diff --git a/.env.docker.example b/.env.docker.example index 7465c0a..3aebe75 100644 --- a/.env.docker.example +++ b/.env.docker.example @@ -95,7 +95,7 @@ MINIO_SECRET_KEY=SimCAE_MinIO_2026_ChangeMe # MinIO 存储桶名称。通常不用改。 MINIO_BUCKET=updates -# 客户端下载升级文件时访问的 MinIO 地址。必须改成 Windows 客户端能访问到的服务器地址。 +# 客户端下载升级文件时访问的 MinIO 地址。必须改成客户端能访问到的服务器地址。 MINIO_PUBLIC_ENDPOINT=http://服务器IP:9000 # MinIO 预签名下载链接有效期，单位分钟。通常不用改。 diff --git a/Docs/00-先读我-服务端文档入口.txt b/Docs/00-先读我-服务端文档入口.txt new file mode 100644 index 0000000..87e1bd1 --- /dev/null +++ b/Docs/00-先读我-服务端文档入口.txt @@ -0,0 +1,49 @@ +服务端文档入口 +============== + +你第一次打开 update-server/Docs 时，先看这一份。这里告诉你每份文档是干什么的，以及部署、测试、维护分别该看哪一份。 + +文档阅读顺序 +============ + +1. 01-服务端Docker打包部署指南.md + 适合部署和运维。说明 Docker 离线包里有什么、怎么打包、怎么部署、.env 每个字段怎么填、怎么查看日志和备份数据。 + +2. 02-崩溃报告接口联调指南.md + 适合测试人员、客户端崩溃上报接入人员。说明 CRASH_REPORT_TOKEN、CRASH_SYMBOL_TOKEN、CRASH_ADMIN_TOKEN 分别怎么用，并给出可直接复制的 curl 示例。 + +3. 03-后端工程化结构说明.md + 适合后端维护人员。说明当前 FastAPI 后端如何按 routes/services/repositories/schemas 分层，以及后续工程化方向。 + +常用任务入口 +============ + +如果你已经拿到 `SimCAEServerDockerPackage.tar.gz`，直接看： + +```text +01-服务端Docker打包部署指南.md 的“三、使用者：最小部署流程” +``` + +如果你要重新生成 Docker 离线部署包，执行： + +```bash +cd update-server +bash ./scripts/package-offline-server.sh --version 0.1.0 --output-dir ./dist/SimCAEServerDockerPackage +``` + +常用源码入口： + +- main.py：服务启动、数据库初始化、MinIO 初始化、全局客户端鉴权。 +- app/api/routes/：管理后台、客户端更新、崩溃报告等 HTTP 路由。 +- app/services/：业务逻辑。 +- app/repositories/：SQLite 数据库读写。 +- admin-ui/：新版管理后台前端源码。 +- legacy/：旧版单文件管理后台，仅作为兼容 fallback。 +- scripts/package-offline-server.sh：生成服务端 Docker 离线部署包。 + +本地源码启动： + +```bash +cd update-server +./venv/bin/python3 main.py +``` diff --git a/Docs/服务端部署说明.md b/Docs/01-服务端Docker打包部署指南.md similarity index 93% rename from Docs/服务端部署说明.md rename to Docs/01-服务端Docker打包部署指南.md index b182ea1..8bed406 100644 --- a/Docs/服务端部署说明.md +++ b/Docs/01-服务端Docker打包部署指南.md @@ -1,4 +1,4 @@ -# SimCAE 服务端 Docker 部署包说明 +# SimCAE 服务端 Docker 打包和部署指南 本文从“维护者打包”到“使用者部署”完整说明 SimCAE 服务端 Docker 包的交付流程。 @@ -6,6 +6,17 @@ 如果你是维护者，要先按“一、维护者：生成 Docker 离线部署包”打包。如果你已经拿到 `SimCAEServerDockerPackage.tar.gz`，直接从“三、使用者：最小部署流程”开始。 +## 先看这里：你要做哪件事 + +| 你的目标 | 直接看哪一节 | +| --- | --- | +| 从源码重新生成离线部署包 | 一、维护者：生成 Docker 离线部署包 | +| 了解交付包里有哪些文件 | 二、这个包里面有什么 | +| 在服务器上部署并启动 | 三、使用者：最小部署流程 | +| 修改 `.env` 配置 | 四、.env 配置怎么填 | +| 发布 Windows/Linux 客户端版本 | 六、发布新版本 | +| 查看日志、重启、备份、升级 | 七、常用命令 | + ## 一、维护者：生成 Docker 离线部署包 在服务端源码所在机器上执行。通常这台机器是 Ubuntu，并且已经安装 Docker。 @@ -139,7 +150,7 @@ bash ./load-images.sh nano .env ``` -最少只需要把 `MINIO_PUBLIC_ENDPOINT` 改成 Windows 客户端能访问到的服务器地址： +最少只需要把 `MINIO_PUBLIC_ENDPOINT` 改成客户端能访问到的服务器地址： ```text MINIO_PUBLIC_ENDPOINT=http://你的服务器IP:9000 @@ -240,7 +251,7 @@ MinIO 控制台: http://你的服务器IP:9001/ | `CRASH_REQUEST_MAX_MB` | 必填 | 可以 | 崩溃报告完整请求最大大小。 | | `CRASH_SYMBOLS_MAX_MB` | 必填 | 可以 | 符号文件最大大小。 | -崩溃报告上传、查询、下载、符号包上传的 curl 联调步骤见 `Docs/崩溃报告接口联调说明.md`。示例里的 `dev-token` 不是固定值，要按接口用途替换为 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN` 或 `CRASH_ADMIN_TOKEN` / `ADMIN_TOKEN`。 +崩溃报告上传、查询、下载、符号包上传的 curl 联调步骤见 `Docs/02-崩溃报告接口联调指南.md`。示例里的 `dev-token` 不是固定值，要按接口用途替换为 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN` 或 `CRASH_ADMIN_TOKEN` / `ADMIN_TOKEN`。 ## 五、客户端配置要同步哪些值 @@ -421,7 +432,7 @@ CLIENT_API_TOKEN=... MINIO_PUBLIC_ENDPOINT=http://你的服务器IP:9000 ``` -这个地址必须从 Windows 客户端能访问。还要确认服务器防火墙放行了 `9000` 端口。 +这个地址必须从客户端能访问。还要确认服务器防火墙放行了 `9000` 端口。 ## 十、安全提醒 diff --git a/Docs/崩溃报告接口联调说明.md b/Docs/02-崩溃报告接口联调指南.md similarity index 94% rename from Docs/崩溃报告接口联调说明.md rename to Docs/02-崩溃报告接口联调指南.md index 170dd24..3e0cebd 100644 --- a/Docs/崩溃报告接口联调说明.md +++ b/Docs/02-崩溃报告接口联调指南.md @@ -1,7 +1,14 @@ -# SimCAE 崩溃报告接口联调说明 +# SimCAE 崩溃报告接口联调指南 本文说明崩溃报告后端接口怎么测试，以及 curl 示例里的 `dev-token` 应该替换成什么。 +最快结论： + +- 上传崩溃报告时，`dev-token` 替换成 `CRASH_REPORT_TOKEN` 的值。 +- 上传符号包时，`dev-token` 替换成 `CRASH_SYMBOL_TOKEN` 的值。 +- 查询或下载崩溃报告时，优先用 `CRASH_ADMIN_TOKEN`；如果它为空，就用 `ADMIN_TOKEN`。 +- 管理后台“客户端配置生成”区域下方会显示这些联调信息，方便复制。 + ## 一、先搞清楚三个 Token curl 示例里的： diff --git a/Docs/后端模板化改造说明.md b/Docs/03-后端工程化结构说明.md similarity index 96% rename from Docs/后端模板化改造说明.md rename to Docs/03-后端工程化结构说明.md index 36cb265..7b80361 100644 --- a/Docs/后端模板化改造说明.md +++ b/Docs/03-后端工程化结构说明.md @@ -1,4 +1,6 @@ -# 后端成熟模板化改造说明 +# 后端工程化结构说明 + +本文给后端维护人员阅读。它说明服务端为什么从单个 `main.py` 拆成 `routes / services / repositories / schemas`，以及后续继续工程化时应该把代码放在哪里。 ## 目标 diff --git a/Docs/ReadMe.txt b/Docs/ReadMe.txt deleted file mode 100644 index 93d04b6..0000000 --- a/Docs/ReadMe.txt +++ /dev/null @@ -1,41 +0,0 @@ -服务端文档入口 -============== - -本目录用于保存 update-server 服务端子仓库的说明文档。 - -建议阅读顺序： - -1. 服务端部署说明.md - 面向部署和运维，说明 Docker 离线包里有什么、怎么部署、.env 每个字段怎么填、怎么查看日志和备份数据。 - -2. 后端模板化改造说明.md - 面向后端维护，说明当前 FastAPI 后端如何按 routes/services/repositories/schemas 分层，以及后续工程化方向。 - -3. 崩溃报告接口联调说明.md - 面向测试和客户端接入，说明 CRASH_REPORT_TOKEN、CRASH_SYMBOL_TOKEN、CRASH_ADMIN_TOKEN 分别怎么用，并给出可直接复制的 curl 示例。 - -常用源码入口： - -- main.py：服务启动、数据库初始化、MinIO 初始化、全局客户端鉴权。 -- app/api/routes/：管理后台、客户端更新、崩溃报告等 HTTP 路由。 -- app/services/：业务逻辑。 -- app/repositories/：SQLite 数据库读写。 -- admin-ui/：新版管理后台前端源码。 -- legacy/：旧版单文件管理后台，仅作为兼容 fallback。 -- scripts/package-offline-server.sh：生成服务端 Docker 离线部署包。 - -本地源码启动： - -```bash -cd update-server -./venv/bin/python3 main.py -``` - -Docker 离线包打包： - -```bash -cd update-server -bash ./scripts/package-offline-server.sh \ - --version 0.1.0 \ - --output-dir ./dist/SimCAEServerDockerPackage -``` diff --git a/scripts/package-offline-server.sh b/scripts/package-offline-server.sh index 296ba91..a6f7ef9 100755 --- a/scripts/package-offline-server.sh +++ b/scripts/package-offline-server.sh @@ -110,7 +110,7 @@ cp "$PROJECT_ROOT/keys/manifest_private_key.pem" "$KEYS_DIR/manifest_private_key cp "$PROJECT_ROOT/keys/manifest_public_key.pem" "$KEYS_DIR/manifest_public_key.pem" cat > "$PACKAGE_DIR/README.md" <<'EOF_README' -# SimCAE 服务端 Docker 部署包说明 +# SimCAE 服务端 Docker 打包和部署指南 本文从“维护者打包”到“使用者部署”完整说明 SimCAE 服务端 Docker 包的交付流程。 @@ -118,6 +118,17 @@ cat > "$PACKAGE_DIR/README.md" <<'EOF_README' 如果你是维护者，要先按“一、维护者：生成 Docker 离线部署包”打包。如果你已经拿到 `SimCAEServerDockerPackage.tar.gz`，直接从“三、使用者：最小部署流程”开始。 +## 先看这里：你要做哪件事 + +| 你的目标 | 直接看哪一节 | +| --- | --- | +| 从源码重新生成离线部署包 | 一、维护者：生成 Docker 离线部署包 | +| 了解交付包里有哪些文件 | 二、这个包里面有什么 | +| 在服务器上部署并启动 | 三、使用者：最小部署流程 | +| 修改 `.env` 配置 | 四、.env 配置怎么填 | +| 发布 Windows/Linux 客户端版本 | 六、发布新版本 | +| 查看日志、重启、备份、升级 | 七、常用命令 | + ## 一、维护者：生成 Docker 离线部署包 在服务端源码所在机器上执行。通常这台机器是 Ubuntu，并且已经安装 Docker。 @@ -251,7 +262,7 @@ bash ./load-images.sh nano .env ``` -最少只需要把 `MINIO_PUBLIC_ENDPOINT` 改成 Windows 客户端能访问到的服务器地址： +最少只需要把 `MINIO_PUBLIC_ENDPOINT` 改成客户端能访问到的服务器地址： ```text MINIO_PUBLIC_ENDPOINT=http://你的服务器IP:9000 @@ -531,7 +542,7 @@ CLIENT_API_TOKEN=... MINIO_PUBLIC_ENDPOINT=http://你的服务器IP:9000 ``` -这个地址必须从 Windows 客户端能访问。还要确认服务器防火墙放行了 `9000` 端口。 +这个地址必须从客户端能访问。还要确认服务器防火墙放行了 `9000` 端口。 ## 十、安全提醒