QXJ 项目文档

简体中文

English
日本語

简体中文

English
日本語

主题

快速开始 ​

本指南帮助你从零搭建 QXJ 本地开发环境。工作区由 Google repo（多仓库管理工具）统一管理，共 10+ 个仓库。

前置要求 ​

软件版本说明
Node.js≥ 20.19前端工程
pnpm≥ 8.8前端包管理器（前端工程必须 pnpm）
Python3.8+（建议 3.11）后端工程
Git / repo2.x / repo 最新版本控制与多仓库管理
Redis5+本地联调必需（会话密钥 / 验证码 / Token 黑名单）

鸿蒙开发额外需要 DevEco Studio（配套 API 6.1.1(24)）。

环境检查清单 ​

  • Node.js ≥ 20.19（node -v）
  • pnpm ≥ 8.8（pnpm -v）
  • Python 3.8+（python --version）
  • Redis 运行中（redis-cli ping 返回 PONG）
  • Git 已配置用户名 / 邮箱
  • DevEco Studio（鸿蒙开发可选）

1. 获取工作区 ​

bash
mkdir qxj-project && cd qxj-project

# 首次初始化（内网 Gitea 上的 repo 工具 v2.67 + manifest）
repo init \
  --repo-url=http://192.168.168.51:3000/qxj-project/git-repo.git \
  --repo-rev=v2.67 \
  -u http://192.168.168.51:3000/qxj-project/manifest.git

# 同步全部仓库
repo sync -c -j8

repo 管理的仓库其 .git 是指向 .repo/ 的符号链接。在 Windows 上请通过 WSL 执行 git 命令（PowerShell 下会报 fatal: error reading '.git'）。 按角色只拉部分仓库、单仓库同步等更多用法见 首页 · 获取 QXJ 项目工作区。

2. 认证后端（qxj-backend-admin，端口 4607） ​

bash
cd qxj-backend-admin

python -m venv venv
# Linux / WSL
source venv/bin/activate
# Windows PowerShell：venv\Scripts\activate

pip install -r requirements.txt

# 按需修改 SECRET_KEY / REDIS_URL 等
cp .env.example .env

.env 关键项（完整清单以 .env.example 为准）：

ini
DEBUG=True
# DB_ENGINE 不设即为 SQLite；DB_ENGINE=mysql 切 MySQL
REDIS_URL=redis://127.0.0.1:6379/0
# 私钥加密主密钥（64 位 hex）；生产必须显式提供，开发不设则由 SECRET_KEY 派生
QXJ_KEY_ENC_KEY=<64 位 hex>
# 开发模板默认允许网页 JSON 登录；生产为 false
ALLOW_JSON_LOGIN=true

初始化数据库与密钥 ​

初始化分两个工具，用途不同，首次开发建议都执行：

bash
# ① 服务器 SM2 密钥对（migrate + ServerKey，握手与令牌签发依赖）
python -m tools.setup init
#   --fixed            使用开发用写死密钥对（仅 DEBUG 环境）
#   --overwrite        销毁旧密钥重建（密钥轮换）

# ② 演示数据（自动兜底 migrate）：角色 / 超管 / 测试用户 / 设备类型与示例设备 /
#    地理围栏 / 时间规则及关联
python -m tools.init.run_all

初始化完成后的数据：

数据内容
超管账号admin、nsp（密码 Nsp123456!，也可用环境变量 QXJ_INIT_ADMIN_PASSWORD 指定）
测试用户lzf（二室老师）、zyy / ysh（二室学生）、lwh（一般学生）
角色5 个：管理员 / 一般老师 / 一般学生 / 二室老师 / 二室学生
地理围栏4 个（天安门 / 信工所大 / 小范围 / 宿舍，GCJ-02 坐标）
时间规则10 条（含默认禁用的周六轮换规则）
设备设备类型 + 示例设备（可替换为实际清单）

启动（HTTPS） ​

调试推荐 HTTPS（摄像头、定位等能力只在安全上下文开放）：

bash
# 首次先生成自签名证书（默认自动探测本机 IP 写入 SAN）
python -m tools.setup gen-cert

# HTTPS 启动开发服务器（保留热重载）
python manage.py runserver_plus 0.0.0.0:4607 \
  --cert-file certs/server.crt --key-file certs/server.key

纯 HTTP 方式 python manage.py runserver 0.0.0.0:4607 仍然可用，两种方式按需选一。 证书与自签 HTTPS 的完整说明（WSL 网络、SAN、端口转发）见后端仓库文档目录 qxj-backend-admin/docs 中的《开发环境HTTPS自签证书.md》。

📖 相关阅读：后端架构 · 仓库详解 · backend-admin · 部署文档

3. 管理前端（qxj-frontend-admin，端口 5173） ​

bash
cd qxj-frontend-admin
pnpm install
pnpm dev

.env.development 已预置：

  • VITE_API_PROXY_URL=http://127.0.0.1:4607 —— /api/v3 经 Vite 代理转发真实后端
  • VITE_USE_JSBRIDGE=false —— 开发模板默认关闭 JSBridge

在普通浏览器里登录调试：把 .env.development 的 VITE_ALLOW_JSON_LOGIN 改为 true（后端开发配置 ALLOW_JSON_LOGIN 默认已为 true）：

ini
VITE_USE_JSBRIDGE = false
VITE_ALLOW_JSON_LOGIN = true

在 Pad 中使用：走 JSBridge 模式，令牌由原生应用持有，设 VITE_USE_JSBRIDGE=true。

构建进后端同源目录（生产可由 Django/whitenoise 直接托管）：

bash
pnpm build:backend   # 输出 ../qxj-backend-admin/frontend_dist

📖 相关阅读：前端架构 · 仓库详解 · frontend-admin · NSP-SM Token 说明

4. 鸿蒙应用（qxj_harmony_next_pad_nsp_browser） ​

  1. 用 DevEco Studio 打开工程（target 6.1.1(24) / compatible 5.0.5(17)）；
  2. 在工程结构中配置签名（调试签名材料由 hpack 统一管理）；
  3. 选择 products/tablet 或 products/phone 的 target 运行。

命令行打包使用独立工具 hpack（pip install harmony-hpack， 首次需在工程根目录执行 hpack init 生成配置）：

bash
# Debug 包
hpack pd "调试包说明"
# Release 包（忽略配置中的 Debug 开关）
hpack pr "发版包说明"
# 仅编译不重签名
hvigorw assembleHap

两个版本：main 分支 4.1.54（单页稳定版），dev 分支 5.2.89（多标签 v2）。

📖 相关阅读：鸿蒙应用架构 · 仓库详解 · harmony-browser · SM2 密钥协商

5. 验证 ​

bash
# 后端可达（HTTPS，自签证书加 -k）
curl -k https://127.0.0.1:4607/api/v3/
# 浏览器打开 https://127.0.0.1:5173 看到前端登录页

常见问题 ​

后端起不来 / gunicorn 报「密钥协商失败」 ​

多为 QXJ_KEY_ENC_KEY 与建库时不一致（runserver、gunicorn 走不同 settings 时 派生值不同）。对齐密钥值后重启进程。

握手后业务端验 token 返回 -3 ​

外层 SM2 验签失败——业务后端配置的服务器公钥与签发私钥不匹配（服务没重启 / .env 没传对 / 被环境变量覆盖）。与 Redis 无关。

浏览器登录提示 JSON 登录被禁用 ​

前端 VITE_ALLOW_JSON_LOGIN 与后端 ALLOW_JSON_LOGIN 需同时为 true； 生产环境两者默认均关闭，Pad 场景请改走 JSBridge。

前端 403 / CORS ​

检查后端 CORS_ALLOWED_ORIGINS 与 CSRF_TRUSTED_ORIGINS 是否包含前端地址； Nginx 终结 TLS 时注意 scheme 与 TRUSTED_PROXY_COUNT。

Pad 访问 HTTPS 报证书地址不匹配 ​

访问用的 IP 不在证书 SAN 中。重新执行 python -m tools.setup gen-cert <Pad访问所用IP> 后重启服务。

下一步 ​

最近更新