NATLAN Docs

外观

控制面升级 ​

控制面走 docker 整栈重建。三个后端服务（control-server、auth-server、registry-server）必须一起换——它们经共享的 registry 客户端互相调用，也共用同一套 schema 契约。

部署形态与配置载体见 控制面部署。

步骤 ​

  1. 拉新代码。

  2. 先跑数据库迁移（见 数据库迁移）。

    注意迁移与代码的顺序：

    • 加列类迁移要在新代码上线前跑；
    • 删列类迁移要在新代码不再引用旧列之后再跑。

  3. 重建整栈。

    bash
    cd /opt/dn42-control/deploy/docker
sudo docker compose -p docker-compose up -d --build

  4. 验收（见下）。

只重建单个服务时 ​

整栈 up -d 会连 nginx 一起重建，不会有问题。但只重建 control-server 或 auth-server 时必须 reload nginx：

bash
sudo docker compose -p docker-compose exec nginx nginx -s reload

upstream control_backend 是静态解析——容器名在 nginx 配置加载时解析一次并缓存。单独重建后端会让它指着已失效的旧 IP，对外一律 502。

验收 ​

bash
# 存活探针
curl -s https://api.natlan.io/healthz
curl -s https://api.natlan.io/control/v1/healthz

# OIDC discovery：issuer 必须是 auth 服务自己的域名
curl -s https://auth.natlan.io/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'

# fleet 全员回报
curl -s -H "Authorization: Bearer <admin-token>" \
  https://api.natlan.io/control/v1/admin/health

issuer 若变成别的主机名，说明 auth-server 在从 Host 头推 issuer 而不是读配置——那会让所有已签发的 ID Token 与已注册的 Passkey 失效，须先修配置再继续。

重建后的「全员掉线」是假象 ​

控制面重建期间，全部 agent 的 WebSocket 会同时断开并进入指数退避重连（1s 起，上限 30s）。这段时间里管理面看到的是「全 fleet 离线」。

这不是事故：

  • 数据面完全不受影响——节点按最后一次已应用的配置继续转发。控制面失明不等于网络中断。
  • agent 会自行回连，无须登任何节点。
  • 退避上限 30s，因此最坏情况下最后一台节点在重建完成后约 30 秒内回来。

判断是否真出问题，看重建完成后 1–2 分钟的 GET /control/v1/admin/health：仍有节点 down 才需要排查。只读诊断手段见 故障排查。

回退 ​

docker 镜像回退是最快的路径：git checkout <旧 commit> 后重新 up -d --build。

注意迁移不可逆：删列类迁移回退后旧代码会找不到列。回退前先确认目标 commit 与当前数据库 schema 兼容——必要时先 alembic downgrade，但删列类多数不可逆，实际操作中更常见的是从备份恢复。

配置文件（deploy/docker/*.toml 与 nginx/conf.d/*.conf）跟踪在仓库里，回退代码会连配置一起回退。改配置前先在宿主上留一份备份目录。