update-system/server/服务端Docker镜像交付说明.md

服务端 Docker 镜像交付说明

这份说明用于把 SimCAE 自动升级/崩溃上报服务端交付给开发组或部署人员。

1. 要不要给开发组发 Docker 镜像

分两种情况：

• 如果开发组只负责接入客户端 SDK，通常不需要给他们镜像，只需要给一个已经部署好的测试服务地址、token、License 和 SDK 文档。
• 如果开发组需要本地完整联调，建议给他们一个服务端 Docker 部署包。部署包不要只有一个镜像，还要包含 docker-compose.image.yml、.env 示例、keys 目录说明。

2. 服务端包含哪些容器

当前服务端不是单容器，而是三个服务：

• api：FastAPI 服务，提供升级接口、后台页面、Manifest 签名、崩溃上报接口。
• minio：对象存储，用于保存版本文件。
• minio-init：启动时自动创建 MinIO bucket。

所以交付时推荐给 Docker Compose 部署包。

3. 构建服务端镜像

在项目根目录执行，注意 Dockerfile 的构建上下文必须是项目根目录，因为镜像会复制 server 代码和 client/admin.html。

cd C:\Users\admin\Desktop

docker build `
  -t simcae-update-server:0.1.0 `
  -f server\Dockerfile `
  .

验证镜像：

docker images simcae-update-server

4. 导出镜像给别人

如果接收方机器可以访问 Docker Hub，只导出 api 镜像即可：

docker save `
  -o simcae-update-server_0.1.0.tar `
  simcae-update-server:0.1.0

如果接收方机器不能联网，建议把 api、minio、minio-init 使用的三个镜像一起导出：

docker pull minio/minio:RELEASE.2025-04-22T22-12-26Z
docker pull minio/mc:RELEASE.2025-04-16T18-13-26Z

docker save `
  -o simcae-server-all-images_0.1.0.tar `
  simcae-update-server:0.1.0 `
  minio/minio:RELEASE.2025-04-22T22-12-26Z `
  minio/mc:RELEASE.2025-04-16T18-13-26Z

建议交付目录：

SimCAEServerDockerPackage/
  simcae-update-server_0.1.0.tar
  docker-compose.image.yml
  .env.example
  keys/
    manifest_private_key.pem
  README.md

注意：manifest_private_key.pem 是服务端签 Manifest 的私钥。客户端 SDK 中的 manifest_public_key.pem 必须和它匹配。

4.1 推荐：在 Ubuntu 上使用离线打包脚本

如果接收方服务器不能联网，推荐直接使用 Ubuntu/bash 脚本生成完整离线包。脚本会完成：构建 api 镜像、拉取 MinIO 镜像、导出三张镜像、复制 docker-compose.yml、复制 .env.example、复制 keys、生成快速启动说明，并压缩成 tar.gz。

在当前 Ubuntu 机器上执行：

cd /path/to/project/server

bash ./package-offline-server.sh \
  --version 0.1.0 \
  --output-dir ./dist/SimCAEServerDockerPackage

生成结果：

server/dist/SimCAEServerDockerPackage/
  images/
    simcae-server-all-images_0.1.0.tar
  keys/
    manifest_private_key.pem
    manifest_public_key.pem
  docker-compose.yml
  .env.example
  README.md
  QUICK_START.md
  load-images.sh

server/dist/SimCAEServerDockerPackage.tar.gz

把 SimCAEServerDockerPackage.tar.gz 拷贝到离线服务器即可。

如果是在 Windows 机器上打包，也可以使用 package-offline-server.ps1，但 Ubuntu 服务端主流程建议使用 package-offline-server.sh。

5. 离线 Ubuntu 服务器如何运行

接收方服务器需要提前安装好 Docker Engine 和 Docker Compose plugin。离线包拷过去后执行：

tar -xzf SimCAEServerDockerPackage.tar.gz
cd SimCAEServerDockerPackage

bash ./load-images.sh
nano .env

.env.example 里已经填好一组可直接试跑的默认 token 和 MinIO 账号。你通常只需要先改服务器地址：

MINIO_PUBLIC_ENDPOINT=http://服务器IP:9000

正式部署时，建议同时修改这些默认值，避免所有环境共用同一套公开示例密码：

CLIENT_API_TOKEN=客户端 API token，对应客户端 app_config.json 的 client_token
ADMIN_TOKEN=后台管理员 token，网页登录时填这个值
CRASH_REPORT_TOKEN=崩溃上传 token
CRASH_SYMBOL_TOKEN=符号包上传 token
MINIO_ACCESS_KEY=MinIO 用户名
MINIO_SECRET_KEY=MinIO 密码

如果你在网页里点击“更改令牌”，新令牌只会在当前服务进程中立即生效。为了让服务重启后仍然使用新令牌，请同步修改 .env 里的 ADMIN_TOKEN，然后执行 docker compose restart api。

启动：

docker compose up -d

查看状态：

docker compose ps

查看日志：

docker compose logs -f api

访问：

后台/API: http://服务器IP:8000/
MinIO 控制台: http://服务器IP:9001/

如果服务器开启了防火墙，至少放行：

8000  后台/API
9000  客户端下载升级文件
9001  MinIO 控制台，可按需限制访问

6. 客户端 SDK 需要哪些服务端信息

发给客户端开发组的信息通常是：

api_base_url=http://服务器IP:8000
client_token=CLIENT_API_TOKEN 的值
license_key=后台创建的 License
manifest_public_key.pem=与服务端 manifest_private_key.pem 匹配的公钥
crash_report_token=CRASH_REPORT_TOKEN 的值，如果接入崩溃上报

7. 生产部署提醒

• 不要把生产私钥和 token 发到无关人员手里。
• 正式环境需要备份 runtime、minio_data、keys。
• 对外开放端口至少包括 8000 和 9000；9001 是 MinIO 控制台，生产环境可限制访问。
• 修改服务端签名私钥后，必须重新生成客户端 manifest_public_key.pem，并重新打 SDK/客户端包。