# 广寒拓扑 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
```

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