KSP_project/deploy/nas-topology-manual/DEPLOY.md

广寒拓扑 NAS 容器手动部署

此部署包只用于更新 NAS 上现有的 topology-api 容器，不修改公网服务器的 Nginx 路由。

部署前

1. 备份 NAS 上当前拓扑项目目录和 .env。
2. 确认当前容器对外端口仍为 38080，容器内端口为 8080。
3. 将本压缩包解压到一个新目录。
4. 把现有生产 .env 复制到解压后的目录。部署包不包含任何凭据。

构建新镜像

在解压目录执行：

docker build --no-cache -t topology-api:20260721-1145 .

本次数据库布局数据已经写入现有拓扑数据库，正常情况下不需要再次运行 seed 脚本。

替换容器

以下命令假定：

• 当前容器名称为 topology-api-2；
• NAS 对外端口为 38080；
• 生产 .env 已复制到当前解压目录。

先停止并保留旧容器：

docker stop topology-api-2
docker rename topology-api-2 topology-api-2-backup-20260721

再启动新容器：

docker run -d \
  --name topology-api-2 \
  --restart unless-stopped \
  --env-file .env \
  -p 38080:8080 \
  topology-api:20260721-1145

验证

curl -fsS http://127.0.0.1:38080/health
curl -fsS 'http://127.0.0.1:38080/api/v1/bases/guanghan/snapshot?mission=GHC-05'
curl -fsS 'http://127.0.0.1:38080/api/v1/bases/guanghan/snapshot?mission=GHC-06'

预期结果：

• GHC-05：engineering_overview_v1，画布宽度 1900。
• GHC-06：engineering_overview_ghc06_v1，画布宽度 2900。
• GHC-05 的吴刚三号位于居住舱二号北部。
• GHC-06 的吴刚二号位于实验舱东部。

公网验证地址：

http://118.89.192.134:59100/topology/guanghan_topology_demo.html?mission=GHC-06

回滚

如果健康检查或页面验证失败，停止并移除新容器，然后恢复旧容器：

docker stop topology-api-2
docker rm topology-api-2
docker rename topology-api-2-backup-20260721 topology-api-2
docker start topology-api-2

确认新版本稳定运行后，旧容器可以继续保留一段时间。不要在首次验证前删除旧容器或旧镜像。