feat: 优化发布清单和安装结构自动识别

2026-07-15 06:33:33 +00:00
parent 0548692db0
commit 4df439b5ce
28 changed files with 1702 additions and 198 deletions
@@ -200,10 +200,12 @@ MinIO 控制台: http://你的服务器IP:9001/
 | --- | --- | --- | --- |
 | `MINIO_PUBLIC_ENDPOINT` | 必填 | 不能直接用于正式环境 | 改成客户端能访问到的 MinIO 地址，格式是 `http://服务器IP:9000`。客户端会用这个地址下载升级文件。 |
 | `SERVER_PORT` | 必填 | 可以 | 后台/API 端口，默认 `8000`。如果服务器 8000 被占用，可以改成其他端口。 |
-| `PUBLIC_API_BASE_URL` | 可不填 | 可以 | 管理页生成客户端 `app_config.json` 时使用的后端 API 地址。不填时自动使用当前访问后台的地址；如果经过域名、反向代理或端口映射，建议填成客户端实际能访问的地址，例如 `http://服务器IP:8000`。 |
+| `PUBLIC_API_BASE_URL` | 可不填 | 可以 | 管理页生成 qrc 服务端配置 `server_config.json` 时使用的后端 API 地址。不填时自动使用当前访问后台的地址；如果经过域名、反向代理或端口映射，建议填成客户端实际能访问的地址，例如 `http://服务器IP:8000`。 |
 | `RELEASE_MAIN_EXECUTABLE` | 必填 | SimCAE 默认可以 | 发布包里主程序的相对路径。Windows 示例：`bin/SimCAE.exe`；Linux 示例：`bin/SimCAE`。 |
 | `CLIENT_API_TOKEN` | 必填 | 可以 | 客户端访问服务端 API 的令牌。必须和客户端 `config/app_config.json` 里的 `client_token` 完全一致。 |
-| `ADMIN_TOKEN` | 必填 | 可以 | 管理后台登录令牌。网页登录时输入这个值。网页里“更改管理员令牌”成功后，会写回当前目录的 `.env`。 |
+| `ADMIN_USERNAME` / `ADMIN_PASSWORD` | 必填 | 可以 | 管理后台初始用户名和密码。首次启动且数据库里没有管理员用户时，会自动创建这个账号。网页登录时输入这组账号密码。 |
+| `ADMIN_JWT_SECRET` | 必填 | 可以 | 管理后台 JWT 签名密钥。正式部署建议改成随机长字符串，并长期保持不变；改掉后旧登录 token 会失效。 |
+| `ADMIN_TOKEN` | 必填 | 可以 | 管理后台兼容令牌。新后台默认不用它登录；它仍用于旧脚本兼容、JWT_SECRET 未设置时的默认签名密钥，以及 `CRASH_ADMIN_TOKEN` 为空时的崩溃报告管理兜底令牌。 |
 | `LICENSE_KEY_ENCRYPTION_SECRET` | 必填 | 可以 | 后台授权列表显示 License Key 时使用的加密密钥。正式部署建议修改，并且部署后长期保持不变；如果后续改掉它，旧 License 仍可用于客户端校验，但后台无法再显示旧 License Key 原文。 |
 | `MINIO_ACCESS_KEY` | 必填 | 可以 | MinIO 用户名。默认可试跑，正式环境建议改。 |
 | `MINIO_SECRET_KEY` | 必填 | 可以 | MinIO 密码。默认可试跑，正式环境建议改。 |
@@ -263,15 +265,15 @@ MinIO 控制台: http://你的服务器IP:9001/
 3. 如需预置授权，先创建或选择一个 License，页面会自动把可查看的 License 填入“客户端配置生成”
 4. 打开“客户端配置生成”
 5. 点击“生成配套配置”
-6. 点击“复制配置”
-7. 粘贴到客户端 bin/config/app_config.json
+6. 点击“复制配置”，粘贴到客户端 `bin/config/app_config.json`
+7. 点击“复制 qrc 配置”，粘贴到客户端源码 `config/server_config.json`
+8. 重新编译 Launcher / Updater / Bootstrap，让 `api_base_url` 通过 qrc 编进程序
 ```

-客户端 `config/app_config.json` 至少要和服务端保持这两个值一致：
+客户端 `config/app_config.json` 至少要和服务端保持这个值一致：

 ```json
 {
-  "api_base_url": "http://你的服务器IP:8000",
  "client_token": "和服务端 CLIENT_API_TOKEN 一样"
 }
 ```
@@ -288,7 +290,7 @@ CLIENT_API_TOKEN=SimCAEClientToken2026
 "client_token": "SimCAEClientToken2026"
 ```

-`api_base_url` 是后端 API 地址，走 `SERVER_PORT`，不是 MinIO 地址。
+`api_base_url` 是后端 API 地址，走 `SERVER_PORT`，不是 MinIO 地址。它现在位于客户端源码 `config/server_config.json`，并通过 qrc 编译进程序，不再写入客户端 `app_config.json` 或注册表。

 ## 六、发布新版本

@@ -438,4 +440,4 @@ MINIO_PUBLIC_ENDPOINT=http://你的服务器IP:9000

 `keys/manifest_private_key.pem` 是服务端签 Manifest 的私钥，必须保护好。客户端 SDK 里的 `manifest_public_key.pem` 必须和这个私钥配套，否则客户端会 Manifest 验签失败。

-默认 token 和默认 MinIO 密码可以直接试跑。正式部署建议改掉，避免多个环境共用同一套公开示例值。
+默认用户名、默认密码、默认 token 和默认 MinIO 密码可以直接试跑。正式部署建议改掉，避免多个环境共用同一套公开示例值。
@@ -24,7 +24,7 @@

 - 目前不是把某个 GitHub 后端模板整套照搬进项目，而是采用 FastAPI 作为成熟后端框架，并按成熟 FastAPI 后台项目的常见结构做工程化拆分。
 - 管理后台前端已经基于 pure-admin-thin 这类成熟后台模板改造。
- 管理员鉴权当前仍是项目自有令牌机制，尚未整套接入 FastAPI Users/JWT/RBAC。后续生产化安全加固时，可以继续引入成熟认证权限组件。
+- 管理员鉴权已经从单一 `ADMIN_TOKEN` 升级为用户名/密码登录、Argon2 密码哈希、JWT access/refresh token、RBAC 权限检查和管理员用户管理页面。`ADMIN_TOKEN` 仍作为旧脚本兼容令牌和崩溃报告管理兜底令牌保留。

 ## 当前已落地

@@ -35,6 +35,7 @@ app/
  api/
    router.py
    routes/
+      admin_auth.py
      admin_license.py
      admin_policy.py
      admin_version.py
@@ -53,6 +54,7 @@ app/
    audit.py
  db/
  repositories/
+    admin_user_repository.py
    app_channel_repository.py
    crash_report_repository.py
    device_repository.py
@@ -63,6 +65,7 @@ app/
    client_update_repository.py
    publish_repository.py
  schemas/
+    admin_auth.py
    license.py
    policy.py
    version.py
@@ -84,7 +87,7 @@ app/
 当前已经从 `main.py` 抽出的通用能力：

 - `app/core/config.py`：统一读取 `.env`、路径配置和基础 settings。
- `app/core/security.py`：后台令牌校验、令牌摘要、`.env` 写入工具。
+- `app/core/security.py`：管理员 JWT、Argon2 密码哈希、RBAC 权限检查、兼容令牌、令牌摘要、`.env` 写入工具。
 - `app/core/audit.py`：管理后台写操作审计中间件。
 - `app/api/routes/frontend.py`：管理后台静态页面、favicon、platform-config、health 路由。
 - `app/api/routes/admin_license.py`：License 创建、列表、禁用/启用、软删除接口。
@@ -94,7 +97,8 @@ app/
 - `app/api/routes/admin_logs.py`：升级日志、下载日志、管理员审计日志的列表、删除和清空接口。
 - `app/api/routes/admin_crash_report.py`：崩溃报告管理列表和附件下载接口。
 - `app/api/routes/admin_device.py`：设备列表和设备禁用/恢复接口。
- `app/api/routes/admin_config.py`：管理员令牌校验/变更、运行时配置、客户端配置生成接口。
+- `app/api/routes/admin_auth.py`：用户名密码登录、JWT 刷新、登录检查、修改密码、管理员用户列表、创建、角色编辑、禁用/启用和重置密码接口。
+- `app/api/routes/admin_config.py`：运行时配置、客户端配置生成接口，以及旧兼容令牌变更接口。
 - `app/api/routes/admin_publish.py`：管理端发布新版本接口，包含发布锁和管理员鉴权。
 - `app/api/routes/client_update.py`：客户端设备登记、更新检测、下载链接、Manifest、下载日志和升级结果上报接口。
 - `app/api/routes/crash_api.py`：崩溃报告健康检查、报告上传/下载和符号包上传接口。
@@ -116,14 +120,14 @@ app/

 后续不建议一次性重写全部后端，而是按下面顺序迁移：

-1. 接入成熟用户认证模块，例如 FastAPI Users。
-2. 将 `ADMIN_TOKEN` 替换成管理员用户名/密码登录、JWT、refresh token。
-3. 增加用户、角色、权限、菜单权限、API 权限表。
-4. 管理后台常用业务接口、客户端更新接口、版本发布接口、崩溃报告接口已经按领域拆到 `app/api/routes/`，并将 SQL 下沉到 `app/repositories/`。
-5. 继续将请求/响应 `dict` 改成 `app/schemas/` 下的 Pydantic 模型。
-6. 继续补齐请求/响应模型、权限模型、异常模型，让接口契约更清晰。
-7. 继续细化 repository，后续可把 SQLite SQL 逐步迁到 ORM 或统一查询层。
-8. 引入 ORM 和迁移工具，例如 SQLModel/SQLAlchemy + Alembic。
+1. 继续接入更完整的成熟用户认证模块，例如 FastAPI Users，替换当前轻量用户表。
+2. 将现有权限点继续细化，例如 `version:publish`、`license:create`、`audit:read`。
+3. 管理后台常用业务接口、客户端更新接口、版本发布接口、崩溃报告接口已经按领域拆到 `app/api/routes/`，并将 SQL 下沉到 `app/repositories/`。
+4. 继续将请求/响应 `dict` 改成 `app/schemas/` 下的 Pydantic 模型。
+5. 继续补齐请求/响应模型、权限模型、异常模型，让接口契约更清晰。
+6. 继续细化 repository，后续可把 SQLite SQL 逐步迁到 ORM 或统一查询层。
+7. 引入 ORM 和迁移工具，例如 SQLModel/SQLAlchemy + Alembic。
+8. 增加登录失败审计、登录限流、会话管理和更细粒度 Token 轮换。
 9. 保持客户端接口 `/api/v1/...` 尽量兼容，避免客户端 SDK 重编。

 ## 为什么不是直接删除 main.py