chore: 更新客户端和服务端子模块交付状态

2026-07-16 08:36:59 +00:00
parent 5745b27d66
commit 397a4f1785
6 changed files with 106 additions and 20 deletions
@@ -1,8 +1,13 @@
 **
-!server/Dockerfile
-!server/requirements.txt
-!server/main.py
-!server/db.py
-!server/minio_tool.py
-!server/tables.sql
-!server/admin.html
+!update-server/
+!update-server/Dockerfile
+!update-server/requirements.txt
+!update-server/main.py
+!update-server/db.py
+!update-server/minio_tool.py
+!update-server/tables.sql
+!update-server/app/
+!update-server/app/**
+!update-server/admin-ui/
+!update-server/admin-ui/dist/
+!update-server/admin-ui/dist/**
@@ -1,8 +1,8 @@
-[submodule "server"]
+[submodule "update-server"]
 	path = update-server
 	url = https://git.alimzs.com:6443/nikelaluo/update-server.git
 	branch = master
-[submodule "client"]
+[submodule "update-client"]
 	path = update-client
 	url = https://git.alimzs.com:6443/nikelaluo/update-client.git
 	branch = master
@@ -0,0 +1,71 @@
+# 项目交付状态一页纸
+
+这份只看当前状态，不记录开发历史。更详细的背景和概念看 `项目总览.md`。
+
+## 项目是什么
+
+这是 SimCAE 自动升级、授权、版本发布和崩溃报告服务的一套客户端 SDK + 服务端后台。
+
+```text
+update-client/   Launcher / Updater / Bootstrap、SDK 打包、客户端接入文档
+update-server/   FastAPI 后端、Vue 管理后台、Docker 离线部署包
+```
+
+## 当前可以交付什么
+
+- Windows/Linux 客户端升级运行时：`Launcher`、`Updater`、`Bootstrap`。
+- 客户端 SDK 包：包含运行程序、配置模板、接入文档、最终客户端打包脚本。
+- 服务端 Docker 离线部署包：包含 API 镜像、管理后台、MinIO、compose 文件、配置模板和 Manifest 签名密钥。
+- 管理后台：基于 pure-admin-thin / Vue3 / Element Plus / TypeScript / Vite。
+- 后端：基于 FastAPI，已经按 routes / services / repositories / schemas / core 分层，并支持 JWT / RBAC。
+- 后端自动化测试：pytest，覆盖登录/JWT、License/设备、更新检查、发布和崩溃报告核心流程。
+
+## 已完成的核心功能
+
+- 应用、渠道、版本发布、策略管理。
+- License 授权、设备登记、设备数限制。
+- Manifest 生成、SHA-256 文件校验、私钥签名、公钥验签。
+- 客户端检查更新、下载、安装、健康检查、失败回滚。
+- 升级日志、下载日志、管理员审计日志。
+- 发布清单 `发布清单.txt` / `release_manifest.txt`，支持选择发布哪些文件、排除哪些文件。
+- 发布压缩包支持 zip、tar.gz、tgz、tar.bz2、tbz2、rar。
+- 发布任务后台化：上传完成后，服务端后台继续处理，页面轮询任务状态。
+- 崩溃报告上传、查询、文件下载和符号包上传接口。
+
+## 当前要特别注意
+
+- `keys/manifest_private_key.pem` 必须在真实服务端部署包里，但不能进 Git、不能给客户端、不能公开传播。
+- 客户端 SDK 里的 `manifest_public_key.pem` 必须和服务端私钥配套。
+- `config/server_config.json` 会编进客户端程序；改服务端地址后必须重新编译 Launcher / Updater / Bootstrap。
+- `app_config.json` 首次启动会导入当前用户配置区，非空配置导入后会清空为 `{}`。
+- Manifest 缓存和设备身份等运行态文件默认在当前用户数据目录，不再默认写安装目录。
+- 公网部署前仍建议改默认 token/password、配置 HTTPS、限制 MinIO 控制台暴露范围、收紧 CORS。
+
+## 打包入口
+
+客户端 SDK：
+
+```powershell
+cd update-client
+.\scripts\package-sdk.ps1 -SourceDir .\out\bin\Release -OutputDir .\dist\UpdateClientSDK -ZipFile .\dist\UpdateClientSDK.zip -SdkVersion 0.1.0
+```
+
+服务端 Docker 离线包：
+
+```bash
+cd update-server
+bash ./scripts/package-offline-server.sh --version 0.1.0 --output-dir ./dist/SimCAEServerDockerPackage
+```
+
+服务端自动化测试：
+
+```bash
+cd update-server
+./venv/bin/python3 -m pytest -q
+```
+
+## 还不算完成的事情
+
+- 真实 Linux 版 SimCAE 主程序还没有交付联调。
+- 公网生产级安全加固还未全部自动化，例如登录限流、HTTPS 自动化、默认密钥强制替换。
+- 数据库迁移仍是 `tables.sql` + 手写兼容逻辑，长期维护可考虑 Alembic。
@@ -2,6 +2,8 @@

 本文档用于总览当前项目的目标、已实现能力、主要目录、交付物和后续注意事项。适合在提交代码、交接项目或给他人快速了解项目时阅读。

+如果只想快速判断“现在能交付什么、还要注意什么”，先看根目录的 `项目交付状态一页纸.md`。
+
 ## 一、项目整体是什么

 本项目是一套面向 Windows/Linux 客户端软件的自动升级与版本控制系统，并补充实现了 SimCAE 崩溃报告后端接口。
@@ -69,7 +71,7 @@ MainApp.exe / MainApp        当前仓库内的示例业务程序
 - 升级后健康检查 `--health-file`，业务程序启动成功后写入 `ok`。
 - 升级失败回滚。
 - 升级日志和下载日志上报服务端。
- `update-server/legacy/admin.html` 管理后台布局已优化，升级日志和下载日志默认折叠。
+- Launcher / Updater / Bootstrap 已支持 Windows 和 Linux Qt 跨平台编译。

 ## 三、客户端 SDK 交付状态

@@ -94,20 +96,27 @@ update-client/Docs/02-编译环境和第三方依赖说明.md

 ```text
 UpdateClientSDK/
-  SimCAE自动升级SDK接入说明_v0.1.docx
  sdk_manifest.json
+  Docs/
+    00-先读我-客户端文档入口.txt
+    01-客户端接入打包部署指南.md
+    02-编译环境和第三方依赖说明.md
  bin/
  config/
    app_config.json
    manifest_public_key.pem
+  Common/
+    ConfigHelper.h/.cpp
+    TicketHelper.h/.cpp
  scripts/
+  SimCAE自动升级SDK接入说明_v0.1.docx   可选，本地存在时才会随包复制
 ```

-为了降低接入方理解成本，SDK 根目录只保留一个 Word 说明文档作为入口。
+为了降低接入方理解成本，SDK 包内默认带 `Docs/00-先读我-客户端文档入口.txt`。Word 接入说明是可选增强，`.docx` 不进 Git；fresh clone 没有 Word 时也能打包 SDK。

 Linux 当前已完成 Qt 跨平台编译、Linux SDK 打包脚本、Linux 最终客户端打包脚本、Linux 配置模板和部署说明。真实 Linux 版 SimCAE 主程序还未由业务开发方交付，因此真实业务联调暂未完成。

-Word 文档已经说明：
+客户端接入文档已经说明：

 - 拿到 `UpdateClientSDK.zip` 后怎么操作。
 - 如何复制 SDK 运行时到业务软件 Release 目录。
@@ -127,6 +136,7 @@ Word 文档已经说明：
 - 管理后台前端：使用 GitHub 上的 `pure-admin-thin` / `vue-pure-admin` 生态，技术栈是 `Vue3 + Element Plus + TypeScript + Vite`。
 - 存储组件：元数据使用 SQLite，版本文件和崩溃文件使用 MinIO 对象存储。
 - 当前说明：后端已经完成工程化分层，并已加入用户名/密码登录、Argon2 密码哈希、JWT access/refresh token、RBAC 权限检查和管理员用户管理页面。当前实现是轻量用户体系，后续仍可继续接入 FastAPI Users 等更完整的成熟认证组件。
+- 自动化测试：使用 pytest，测试会创建隔离的临时数据库、临时 Manifest 私钥和临时存储目录，覆盖管理员登录/JWT、License/设备登记、更新检查、发布事务和崩溃报告核心流程。

 当前后端已经从早期单文件形态拆成分层结构，主要入口和目录：

@@ -140,7 +150,6 @@ update-server/db.py
 update-server/tables.sql
 update-server/minio_tool.py
 update-server/admin-ui/            新版管理后台源码
-update-server/legacy/admin.html           旧版管理后台页面，保留兼容
 ```

 服务端文档现在统一放在：
@@ -159,6 +168,7 @@ update-server/Docs/03-后端工程化结构说明.md
 - License 管理。
 - 设备首次登记。
 - 版本发布。
+- 版本发布已支持后台任务模式：浏览器上传完成后，服务端继续在后台校验、入库和上传 MinIO，管理页面轮询任务状态。
 - 版本发布支持两种方式：选择软件发布根目录，或上传压缩好的发布包。管理页面已经拆成“软件根目录/压缩发布包”两个发布方式，避免用户误以为只能选择文件夹。
 - 压缩发布包支持 `zip`、`tar.gz`、`tgz`、`tar.bz2`、`tbz2`、`rar`；服务端会先解压，再按 `RELEASE_MAIN_EXECUTABLE` 校验主程序路径。
 - Manifest 生成和私钥签名。
@@ -335,7 +345,7 @@ SimCAE/

 ## 十、运行目录权限说明

-当前客户端 SDK 把部署配置源放在 `Launcher.exe` 所在目录下的 `config/app_config.json`，启动时同步到当前 Windows 用户注册表；运行时普通配置值优先读写注册表，路径为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。服务端 API 地址 `api_base_url` 是例外：它位于源码 `config/server_config.json`，通过 `config/server_config.qrc` 编译进程序，不再写入 `app_config.json` 或注册表。如果检测到 `app_config.json` 变化，SDK 会删除 `config/client_identity.dat` 和 `config/version_policy.dat`，避免旧授权身份或旧策略继续生效；安装目录不可写时会弹出管理员权限确认框。设备身份、状态、策略、更新事务、备份、暂存文件、下载断点和 Manifest 缓存仍位于 `Launcher.exe` 所在目录下，例如 `config/client_identity.dat`、`config/local_state.json`、`config/version_policy.dat`、`update/` 和 `update_temp/`。当 SDK 放在 `SimCAE/bin` 时，这些运行时文件都在 `SimCAE/bin` 下，不会再在 `SimCAE/` 根目录生成顶层 `update/`。
+当前客户端 SDK 把部署配置源放在 `Launcher.exe` 所在目录下的 `config/app_config.json`，启动时同步到当前用户的 QSettings 配置区；Windows 下对应注册表路径 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`，Linux 下由 Qt QSettings 写入当前用户配置目录。服务端 API 地址 `api_base_url` 是例外：它位于源码 `config/server_config.json`，通过 `config/server_config.qrc` 编译进程序，不再写入 `app_config.json` 或注册表。如果检测到 `app_config.json` 变化，SDK 会删除当前用户数据目录里的 `client_identity.dat`、`version_policy.dat` 和 `local_state.json`，避免旧授权身份、旧策略或旧防回滚状态继续生效。设备身份、状态、策略、更新事务、备份、暂存文件、下载断点和 Manifest 缓存默认位于当前用户数据目录，例如 Windows：`%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\`。当 SDK 放在 `SimCAE/bin` 时，不会再在 `SimCAE/` 根目录生成顶层 `update/`。

 如果把软件放在 `C:\Program Files\SimCAE\bin` 并用普通用户启动，普通配置值已经不需要写回 `app_config.json`；但设备身份、状态、策略、更新缓存等文件仍可能需要写安装目录。当前代码对小型状态文件写入已有管理员权限确认；正式要完整安装到 `Program Files` 并自动升级大文件时，后续仍建议补 Windows 服务，或将更多运行时状态迁移到 `ProgramData` / `AppData`。

@@ -1072,7 +1082,7 @@ SimCAE Crash Report 第一阶段——已实现。
 5. 对 Manifest、策略、设备身份、离线包做 RSA 签名。
 6. 给客户端签发临时下载 URL。
 7. 接收升级结果、下载结果、设备登记和 License 授权。
-8. 提供新版 admin-ui 管理后台，并保留 legacy/admin.html 作为旧版兼容入口。
+8. 提供新版 admin-ui 管理后台；旧版 admin.html 已在开发阶段移除，不再保留兼容入口。
 9. 接收 SimCAE 崩溃报告和符号包。

 服务端主要存储有三类：
@@ -1453,7 +1463,7 @@ Docker 运行时，依赖的是镜像里的 Python、镜像里的依赖、容器
 1. 使用 python:3.12-slim 作为基础镜像。
 2. 安装 update-server/requirements.txt 里的 FastAPI、MinIO、cryptography 等依赖。
 3. 拷贝 main.py、db.py、minio_tool.py、tables.sql。
-4. 拷贝 update-server/legacy/admin.html 到容器内 /app/legacy/admin.html。
+4. 拷贝 admin-ui/dist 管理后台静态文件到容器内 /app/admin-ui/dist。
 5. 使用非 root 用户 updateapp 运行。
 6. 暴露 8000 端口。
 7. 提供 healthcheck。
@@ -1591,7 +1601,7 @@ cd update-client

 第五步：补接入方文档和 Demo。

-1. SDK 根目录只保留一个 Word 接入说明作为入口，打开包后一眼能看到。
+1. SDK 包内提供 Docs/00-先读我-客户端文档入口.txt 作为默认入口；Word 说明仅作为可选增强。
 2. 准备一个最小 MainApp 示例，演示 --ticket-file 和 --health-file。
 3. 准备一份常见错误说明。
 4. 准备一份服务端 Docker 部署说明。