feat(topology): add GHC06 layout and deploy docs

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-11 15:02:47 +08:00
parent cf1d26dba9
commit 26d2fcd0b1
9 changed files with 710 additions and 50 deletions
@@ -0,0 +1,80 @@
+# 广寒拓扑 NAS 容器手动部署
+
+此部署包只用于更新 NAS 上现有的 `topology-api` 容器，不修改公网服务器的 Nginx 路由。
+
+## 部署前
+
+1. 备份 NAS 上当前拓扑项目目录和 `.env`。
+2. 确认当前容器对外端口仍为 `38080`，容器内端口为 `8080`。
+3. 将本压缩包解压到一个新目录。
+4. 把现有生产 `.env` 复制到解压后的目录。部署包不包含任何凭据。
+
+## 构建新镜像
+
+在解压目录执行：
+
+```bash
+docker build --no-cache -t topology-api:20260721-1145 .
+```
+
+本次数据库布局数据已经写入现有拓扑数据库，正常情况下不需要再次运行 seed 脚本。
+
+## 替换容器
+
+以下命令假定：
+
+- 当前容器名称为 `topology-api-2`；
+- NAS 对外端口为 `38080`；
+- 生产 `.env` 已复制到当前解压目录。
+
+先停止并保留旧容器：
+
+```bash
+docker stop topology-api-2
+docker rename topology-api-2 topology-api-2-backup-20260721
+```
+
+再启动新容器：
+
+```bash
+docker run -d \
+  --name topology-api-2 \
+  --restart unless-stopped \
+  --env-file .env \
+  -p 38080:8080 \
+  topology-api:20260721-1145
+```
+
+## 验证
+
+```bash
+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 的吴刚二号位于实验舱东部。
+
+公网验证地址：
+
+```text
+http://118.89.192.134:59100/topology/guanghan_topology_demo.html?mission=GHC-06
+```
+
+## 回滚
+
+如果健康检查或页面验证失败，停止并移除新容器，然后恢复旧容器：
+
+```bash
+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
+```
+
+确认新版本稳定运行后，旧容器可以继续保留一段时间。不要在首次验证前删除旧容器或旧镜像。