diff --git a/.dockerignore b/.dockerignore index 8af2599..2ee6fdd 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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/** diff --git a/.gitmodules b/.gitmodules index b8808bd..6796381 100644 --- a/.gitmodules +++ b/.gitmodules @@ -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 diff --git a/update-client b/update-client index fb6b080..fcd67e0 160000 --- a/update-client +++ b/update-client @@ -1 +1 @@ -Subproject commit fb6b080ad45cde5b97459413f17bcd84d251aed8 +Subproject commit fcd67e08aa1f7c51614f6ecdabf67901ed71e64b diff --git a/update-server b/update-server index 0b71e8d..5d7aa56 160000 --- a/update-server +++ b/update-server @@ -1 +1 @@ -Subproject commit 0b71e8d0244f922956eb144fa5495e319d301298 +Subproject commit 5d7aa560e5661c3008ea20cca04ff36cc790762e diff --git a/项目交付状态一页纸.md b/项目交付状态一页纸.md new file mode 100644 index 0000000..1d0acf6 --- /dev/null +++ b/项目交付状态一页纸.md @@ -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。 diff --git a/项目总览.md b/项目总览.md index 936f151..56309fb 100644 --- a/项目总览.md +++ b/项目总览.md @@ -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 部署说明。