ZStack API Router 升级教程

产品版本

本文档对应的产品版本为 ZStack API Router 1.0.0。

读者对象

本文档介绍 ZStack API Router 的升级准备、升级操作、验证和回滚方法，主要适用于以下读者：

• 部署运维工程师。
• 平台管理员。
• 技术支持工程师。
• 负责生产变更和灰度发布的实施人员。

升级范围

升级窗口

重要限制

升级前请阅读以下注意事项：

• PostgreSQL 数据库迁移（migration）只能前进式追加，不要修改已应用的迁移文件。
• 如果升级仅涉及入口代理、控制台或应用进程，通常可以应用层回滚。
• 如果新版本已经执行数据库迁移，应用层回滚不一定足够，必要时必须恢复数据库备份。
• 如果旧库迁移已写入目标库，回滚前需要明确目标库是否允许清空或恢复。
• 生产环境异常时，优先回滚入口层，其次回滚应用层，最后才恢复数据库。
• 升级过程中如出现持续 5xx、配额异常、用量日志异常或数据面不可用，应暂停升级并进入回滚流程。

适用边界

检查当前版本

记录当前版本、镜像、配置和入口信息：

docker images | grep zstack-router
docker compose ps

如使用 systemd：

systemctl status zstack-router
systemctl cat zstack-router

记录当前环境变量：

printenv | grep '^ZR_' | sort

检查服务状态

curl -fsS http://{ROUTER_HOST}:3080/healthz
curl -fsS http://{ROUTER_HOST}:3080/readyz
curl -fsS http://{ROUTER_HOST}:3080/metrics

检查近期请求状态：

select status, count(*) as requests, max(created_at) as last_seen
from zr_usage_logs
where created_at >= now() - interval '30 minutes'
group by status
order by last_seen desc;

检查变更内容

升级前请确认：

• 是否包含数据库迁移。
• 是否变更控制面 API。
• 是否变更 /v1/* 或 /openai/v1/* 数据面行为。
• 是否需要同步控制台。
• 是否需要调整环境变量。
• 是否需要更新 Nginx 或 Ingress 配置。

检查备份条件

升级前必须准备：

备份数据库

pg_dump "$ZR_DATABASE_URL" > zstack-router-$(date +%Y%m%d%H%M%S).sql

Docker Compose 环境可执行：

docker compose exec postgres pg_dump -U zstack_router zstack_router > zstack-router-$(date +%Y%m%d%H%M%S).sql

备份部署目录

tar -czf zstack-router-deploy-$(date +%Y%m%d%H%M%S).tar.gz /opt/zstack-router

备份入口配置

cp /etc/nginx/conf.d/zstack-router.conf /etc/nginx/conf.d/zstack-router.conf.$(date +%Y%m%d%H%M%S).bak
nginx -t

验证备份

适用场景

适用于试用、小规模环境或单实例生产环境。

前提条件

• 已完成数据库和部署目录备份。
• 已获取新版本镜像或二进制。
• 已安排维护窗口。

操作步骤

1. 停止后台任务组件：

   docker compose stop zr-worker

2. 停止主服务：

   docker compose stop zr-server

3. 加载或拉取新镜像：

   docker compose pull

离线环境使用：

docker load -i zstack-router-image.tar

4. 执行数据库迁移：

   docker compose run --rm zr-server zr-migrate

5. 启动主服务：

   docker compose up -d zr-server

6. 启动后台任务组件：

   docker compose up -d zr-worker

验证方式

docker compose ps
curl -fsS http://{ROUTER_HOST}:3080/healthz
curl -fsS http://{ROUTER_HOST}:3080/readyz

发起一次模型调用，并确认 用量日志 中产生记录。

适用场景

适用于多实例生产环境，或通过 Nginx、Ingress、负载均衡控制流量的环境。

前提条件

• 入口层支持摘除和恢复实例。
• 新旧版本可并行运行。
• 已准备监控指标和回滚入口。

操作步骤

1. 将一台实例从入口层摘除。
2. 在该实例上执行升级。
3. 验证 /healthz、/readyz、/metrics 和数据面调用。
4. 将少量流量切入新实例。
5. 观察成功率、延迟、上游错误、用量日志和审计日志。
6. 无异常后逐步扩大流量。
7. 全部实例升级完成后，保留旧版本备份直到观察期结束。

验证方式

注意事项

• 灰度期间建议在入口层增加标识响应头，便于判断流量命中版本。
• 如发生异常，优先将入口流量切回旧版本。
• 如果新版本已执行不兼容的数据库迁移，应停止扩大灰度并评估数据库回滚。

适用场景

仅升级控制台静态资源，不变更数据面和数据库。

操作步骤

1. 上传新控制台资源到独立发布目录（release directory）。
2. 将灰度目录软链指向新目录。
3. 使用测试用户访问灰度控制台。
4. 验证登录、渠道管理、模型管理、令牌管理、日志查询等页面。
5. 验证通过后，将稳定版本软链（stable symlink）切到新目录。

目录示例：

/data/www/zstack-router/releases/ui-20260622-1/
/data/www/zstack-router/releases/ui-20260622-2/
/data/www/zstack-router/ui-stable -> /data/www/zstack-router/releases/ui-20260622-1
/data/www/zstack-router/ui-gray -> /data/www/zstack-router/releases/ui-20260622-2

回滚方式

如果只发生控制台问题，将稳定目录或灰度目录软链切回旧目录即可。不要优先重启数据面服务。

适用场景

当需要从旧版 AI Studio 或历史版本 ZStack API Router 数据库迁移到新版 ZStack API Router 时使用。

操作步骤

1. 准备源库只读账号。
2. 准备目标库并执行新版本数据库迁移。
3. 执行预检查和演练导入。
4. 在迁移窗口执行正式导入。
5. 校验用户、组织、令牌、渠道、模型、路由策略、计费配置、用量日志和审计日志。
6. 切换入口流量。

迁移前应输出预检查结果，至少包含源库连接状态、目标库连接状态、可迁移对象数量、异常对象数量和预计迁移耗时。

注意事项

• 演练导入通过后再执行正式导入。
• 目标库已有数据时，必须明确是否允许覆盖或合并。
• 迁移失败后不要反复执行正式导入，应先分析失败原因和目标库状态。

回滚原则

升级失败时，按以下顺序处理：

1. 入口层回滚。 将流量切回旧版本或稳定路径。
2. 应用层回滚。 恢复旧镜像、旧二进制或旧控制台静态资源目录。
3. 数据库恢复。 仅当数据库迁移或数据写入导致无法通过应用层恢复时执行。

入口层回滚

适用于灰度异常、少量实例异常、数据面 5xx 增多等场景。

nginx -t
systemctl reload nginx

应用层回滚

适用于未执行数据库迁移，或数据库迁移与旧版本兼容的场景。

docker compose stop zr-worker
docker compose stop zr-server
docker load -i zstack-router-old-image.tar
docker compose up -d zr-server
docker compose up -d zr-worker

数据库恢复

适用于数据库迁移后旧版本无法读取数据库，或迁移数据异常且无法修复的场景。

psql "$ZR_DATABASE_URL" < zstack-router-backup.sql

升级后 /readyz 失败

可能原因：

• 数据库连接失败。
• 数据库迁移未执行或执行失败。
• 新版本环境变量缺失。

处理方法：

1. 检查 ZR_DATABASE_URL。
2. 查看 zr-server 日志。
3. 检查数据库迁移执行记录。

升级后模型调用失败

可能原因：

• 路由策略指向不可用渠道。
• 渠道模型未同步。
• 上游地址或凭证变化。

处理方法：

1. 查看用量日志中的错误状态。
2. 检查渠道健康状态。
3. 执行后台任务组件同步模型。

升级后控制台正常但调用失败

处理方法：

1. 确认控制台入口和数据面入口是否指向同一版本。
2. 检查 /v1/* 路径代理。
3. 使用 cURL 直接调用后端地址验证。