引言

产品版本

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

读者对象

本文档介绍 ZStack API Router 的环境准备、安装部署和部署后验证方法，主要适用于以下读者：

• 部署运维工程师。
• 平台管理员。
• 技术支持工程师。
• 负责模型网关交付的实施人员。

部署概述

ZStack API Router 可部署为独立 API 网关，也可作为 ZStack AIOS 或 LobsterPool 推理链路的一部分。核心服务为 zr-server，数据库使用 PostgreSQL，启动前需执行数据库迁移，可选启动后台任务组件用于渠道健康探测和模型同步。

部署形态

部署组件

环境准备

支持的操作系统

组件版本要求

硬件规格

网络和端口要求

TLS 和域名要求

生产环境建议准备：

• 对外访问域名，例如 api-router.example.com。
• 有效 TLS 证书。
• 指向 Nginx、Ingress 或负载均衡的 DNS 记录。
• 如使用企业统一入口，确认路径转发规则覆盖 /api/zr/*、/v1/*、/openai/v1/*、/healthz、/readyz 和 /metrics。

权限和目录要求

生产部署前检查

安装前请完成以下检查：

单节点 Docker Compose 部署

适用场景

适用于试用、演示、功能验证和小规模环境。

前提条件

• 已安装 Docker 和 Docker Compose。
• 当前用户具备 Docker 操作权限。
• 本地端口 3080 和 Compose 中配置的 PostgreSQL 端口未被占用。

操作步骤

1. 进入部署目录：

cd zstack-router

2. 检查环境变量模板：

sed -n '1,120p' .env.example

3. 启动服务：

docker compose up --build -d

4. 查看服务状态：

docker compose ps

5. 查看日志：

docker compose logs -f zr-server
docker compose logs -f zr-worker

验证方式

curl -fsS http://127.0.0.1:3080/healthz
curl -fsS http://127.0.0.1:3080/readyz
curl -fsS http://127.0.0.1:3080/api/zr/openapi.json

注意事项

• Compose 默认配置适合验证，不建议直接作为大规模生产配置。
• 生产环境应使用独立 PostgreSQL，并配置备份。
• 如只验证 API，可不启用控制台静态资源。

生产环境部署

适用场景

适用于正式业务环境，通常由独立 PostgreSQL、zr-server、可选 zr-worker 和入口代理组成。

前提条件

• 已准备生产 PostgreSQL。
• 已完成数据库备份策略设计。
• 已准备域名、TLS 证书和入口代理。
• 已创建专用运行用户和部署目录。

准备数据库

create user zstack_router with password 'CHANGE_ME';
create database zstack_router owner zstack_router;

验证连接：

psql 'postgres://zstack_router:CHANGE_ME@{DB_HOST}:5432/zstack_router' -c 'select now();'

配置环境变量

创建环境变量文件，例如 /etc/zstack-router/zstack-router.env：

ZR_DATABASE_URL=postgres://zstack_router:CHANGE_ME@{DB_HOST}:5432/zstack_router
ZR_BIND_ADDR=0.0.0.0:3080
ZR_PROVIDER_MODE=openai
ZR_CLOUD_TOKEN=Bearer {CLOUD_TOKEN}
ZR_DISCOVERY_TOKEN=Bearer {DISCOVERY_TOKEN}
ZR_CONSOLE_DIST_DIR=/usr/share/zstack-router-console
ZR_PROVIDER_FAILURE_DUMP_DIR=/var/lib/zstack-router/provider-failures

设置权限：

chmod 600 /etc/zstack-router/zstack-router.env
chown zstack-router:zstack-router /etc/zstack-router/zstack-router.env

执行数据库迁移

export $(grep -v '^#' /etc/zstack-router/zstack-router.env | xargs)
zr-migrate

启动服务

使用 systemd 或容器平台启动 zr-server。需要渠道同步和健康探测时，同时启动 zr-worker。

配置入口代理

Nginx 应转发以下路径：

流式接口需要关闭响应缓冲，避免 SSE 卡顿。

验证方式

离线环境部署

适用场景

适用于无法访问公网镜像仓库或需要离线交付的环境。

前提条件

• 已获得离线部署包。
• 目标服务器已安装 Docker 和 Docker Compose，或部署包已包含前置依赖。
• 已准备 PostgreSQL 或确认部署包内置数据库配置。

操作步骤

1. 上传离线包到目标服务器。
2. 解压到部署目录。
3. 检查 env.example、docker-compose.yml 和 load-and-run.sh。
4. 按环境修改 .env。
5. 加载镜像并启动：

bash load-and-run.sh

6. 执行健康检查。

注意事项

• 确保部署文件来自同一版本包，不要混用旧版本 docker-compose.yml 和新版本镜像。
• 离线环境也必须配置数据库备份。
• 如需要包含 Docker/Compose 前置依赖，打包时使用对应离线依赖选项。

部署后验证

部署完成后，请按以下清单验证：

常见问题

/readyz 返回异常

可能原因：

• ZR_DATABASE_URL 配置错误。
• PostgreSQL 不可达。
• zr-migrate 未执行或执行失败。

处理方法：

1. 使用 psql 验证数据库连接。
2. 查看 zr-server 日志。
3. 重新执行 zr-migrate。

数据面无法调用上游模型

可能原因：

• 上游地址不可达。
• 凭证错误。
• SSRF 策略阻止该地址。
• 渠道未同步模型。

处理方法：

1. 从网关节点访问上游地址。
2. 检查渠道配置。
3. 运行 zr-worker 同步模型。
4. 查看用量日志和上游失败诊断文件。

流式响应不稳定

可能原因：

• Nginx 或 Ingress 开启了响应缓冲。
• 进程文件句柄不足。
• PostgreSQL 连接池不足。

处理方法：

1. 关闭数据面路径的代理缓冲。
2. 提高 systemd LimitNOFILE 或容器 nofile。
3. 根据并发量调整数据库连接池。

附录：常用运维命令

以下命令用于部署验证和运维排障：

curl -fsS http://127.0.0.1:3080/healthz
curl -fsS http://127.0.0.1:3080/readyz
curl -fsS http://127.0.0.1:3080/metrics

查看近期用量：

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