AI Gateway 私有化部署

使用 Docker Compose 在企业内网部署 AI Gateway，完成镜像准备、环境配置、首次登录、模型接入、升级和恢复。

本手册面向客户运维和平台管理员。部署包中的 ai-gateway/onprem/ 是配置真值，其中 .env.example 定义可配置项，docker-compose.yml 定义服务拓扑和启动顺序。不要从旧文档复制 Compose 片段覆盖交付包。

部署范围

服务	作用	对外端口
`ai-gateway-app`	AI Gateway 数据面与管理后台	`3000`
`migrate`	一次性执行数据库迁移	无
`postgres`	用户、组织、API Key、供应商和配置数据	无
`redis`	限流、缓存和配置广播	无
`greptimedb`	用量、指标与调用日志时序数据	无
`vector`	用量回灌和指标采集	无
`grafana`	运行和用量看板	`3030`

Compose 会按以下顺序启动：postgres healthy → migrate 成功退出 → ai-gateway-app healthy → vector；Grafana 等待 GreptimeDB 健康后启动。

部署前检查

服务器需要安装 Docker Engine 与 Docker Compose v2：

docker --version
docker compose version

确认服务器能访问 public 镜像仓库，或已经准备好企业内网 registry。生产环境建议使用企业域名和 HTTPS 反向代理；数据库、Redis、GreptimeDB、Vector 与 /api/local/usage-batch 都应保持在内网。

Public 镜像与架构

当前发布的网关镜像是：

uhub.service.ucloud.cn/tensorfusion-public/ai-gateway-onprem:0.3.214

默认镜像都提供 linux/amd64 和 linux/arm64 manifest：

组件	默认 public 镜像
AI Gateway	`uhub.service.ucloud.cn/tensorfusion-public/ai-gateway-onprem:0.3.214`
PostgreSQL	`uhub.service.ucloud.cn/tensorfusion-public/pgvector:pg16`
Redis	`uhub.service.ucloud.cn/tensorfusion-public/redis:7-alpine`
GreptimeDB	`uhub.service.ucloud.cn/tensorfusion-public/greptimedb:v1.0.1`
Vector	`uhub.service.ucloud.cn/tensorfusion-public/vector:0.40.0-alpine`
Grafana	`uhub.service.ucloud.cn/tensorfusion-public/grafana:11.3.0`

离线或仅内网 registry 环境必须完整 mirror 上表六类镜像，然后在 .env 中设置 ONPREM_IMAGE 与对应的 *_IMAGE。不要只 mirror 网关镜像。

docker buildx imagetools inspect \
  uhub.service.ucloud.cn/tensorfusion-public/ai-gateway-onprem:0.3.214

输出应同时包含 linux/amd64 和 linux/arm64。内网镜像也应使用同样方式复核。

准备部署包

在交付包或 mono 仓的私有化目录中执行：

cd ai-gateway/onprem
cp .env.example .env

.env 含密钥和口令，不应提交到 Git。生产环境建议通过企业密钥管理系统或受控部署变量注入。

配置 `.env`

以下项目必须设置：

配置	要求
`ONPREM_IMAGE`	使用发布镜像，或替换为企业内网镜像地址。
`BETTER_AUTH_URL`	用户实际访问的完整地址，例如 `https://gateway.example.com`。
`CLIENT_ORIGIN`	与浏览器访问地址完全一致；多入口用英文逗号分隔。
`BETTER_AUTH_SECRET`	使用 `openssl rand -base64 48` 生成。
`POSTGRES_PASSWORD`	使用 `openssl rand -hex 32` 生成，必须 URL-safe。
`ONPREM_ADMIN_EMAIL` / `ONPREM_ADMIN_PASSWORD`	空库首次启动时创建的首个超级管理员。
`AI_GATEWAY_LOCAL_USAGE_INGEST_TOKEN`	使用 `openssl rand -hex 24` 生成，供 Vector 回灌用量。
`GRAFANA_ADMIN_PASSWORD`	Grafana 管理员密码。

示例：

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

POSTGRES_PASSWORD 会拼入数据库连接串，不要使用 @、:、/、%、#、?、& 等 URL 保留字符。

Origin 与反向代理

BETTER_AUTH_URL 和 CLIENT_ORIGIN 必须包含协议、域名或 IP 与端口，且与浏览器地址一致。例如通过 HTTPS 域名访问时，两项都填写 https://gateway.example.com。配置不一致会导致登录请求出现 Invalid origin。

ONPREM_TRUST_ANY_ORIGIN 默认应保持 false。只有临时内网排障时才设置为 true，排障完成后立即恢复为 false。

初始模型供应商

可以在 .env 中填写 DASHSCOPE_API_KEY 或 DEEPSEEK_API_KEY，首次启动时会 seed 对应供应商。其他 OpenAI、Anthropic 兼容供应商或自托管推理服务，在后台完成配置后再向业务开放。

私有化镜像不包含我方上游密钥，也不读取 SaaS 运营变量。

启动与验收

docker compose pull
docker compose up -d
docker compose ps
curl -fsS http://localhost:3000/api/health
curl -fsS http://localhost:3030/api/health

预期状态为：PostgreSQL、Redis、GreptimeDB、AI Gateway、Vector 与 Grafana 为 healthy，migrate 为 exited 0。

如果 ai-gateway-app 未启动，先查看迁移和应用日志：

docker compose logs --tail=200 migrate
docker compose logs --tail=200 ai-gateway-app

首次登录与业务接入

打开 BETTER_AUTH_URL，使用 .env 中的 ONPREM_ADMIN_EMAIL 和 ONPREM_ADMIN_PASSWORD 登录。首个超级管理员只会在数据库为空时创建；后续修改 .env 不会重置已有账号密码。

登录后完成以下操作：

在供应商配置中补充或检查可用模型。
在 API Key 管理中为每个业务系统创建独立的 gk_ Key。
在安全设置中按组织维护审核与脱敏规则。

业务系统使用网关地址、后台启用的模型 ID 和独立的 gk_ Key 调用：

curl "https://gateway.example.com/v1/chat/completions" \
  -H "Authorization: Bearer gk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'

模型 ID 以后台已启用的模型为准。业务代码应将 Base URL、模型 ID 和 Key 名称配置化，避免写死。

默认安全行为

私有化实例将 PII 脱敏与输入、输出审核分开处理：

场景	默认行为
输入命中内置审核关键词	返回关键词对应的固定回复，不再请求上游模型。
输入含中国大陆手机号或 `sk-*`	仅将命中的片段替换为 `***`，其余文本保持不变。
输出审核	独立使用输出审核配置，不会混入输入 mock 规则。

管理员可以在安全设置中查看、增删输入审核关键词。清空某项规则后，该规则不再被默认值重新覆盖。

监控与安全基线

Grafana 地址为 http://<host>:3030，使用 admin 与 .env 中的 GRAFANA_ADMIN_PASSWORD 登录。默认看板包含网关健康状态、用量采集和基础指标。

业务系统按应用使用不同 gk_ Key，方便限流、审计和单独撤销。
网关通过企业 HTTPS 反向代理对外提供服务；不要直接暴露数据库和内部采集端口。
反向代理必须拒绝外部访问 /api/local/usage-batch，该接口仅供本地 Vector 使用。
将 BETTER_AUTH_SECRET、数据库密码、管理员密码、Grafana 密码、回灌 token 和供应商 Key 放入企业密钥管理系统。

升级、回滚与备份

升级前先完成 PostgreSQL 逻辑备份：

docker compose exec -T postgres sh -lc \
  'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' \
  | gzip > ai-gateway-before-upgrade-$(date +%F-%H%M).sql.gz

更新 .env 中的 ONPREM_IMAGE 为已验证的新版本，再执行：

docker compose pull ai-gateway-app migrate
docker compose up -d
docker compose ps

migrate 成功后才会启动新版本应用。回滚镜像不等于回滚数据库 schema；遇到不兼容升级时，应先在隔离环境验证恢复，再按备份恢复流程处理。

日常备份可使用相同的逻辑备份命令。恢复前停止应用和 Vector，再导入备份：

docker compose stop ai-gateway-app vector
gzip -dc ai-gateway-backup-YYYY-MM-DD.sql.gz \
  | docker compose exec -T postgres sh -lc 'psql -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose up -d

生产环境还应按合规要求备份 greptime-data、image-data 与 grafana-data。不要依赖固定 Docker volume 名称删除数据卷；不同项目名和部署环境会产生不同卷名。

常见问题

现象	排查方式
登录提示 `Invalid origin`	检查浏览器实际地址是否与 `BETTER_AUTH_URL`、`CLIENT_ORIGIN` 完全一致。
管理员密码不正确	确认数据库是否已初始化；已有账号不会因修改 `.env` 被重置。
`migrate` 失败	运行 `docker compose logs --tail=200 migrate`，检查数据库连接与密码 URL-safe 要求。
无法拉取镜像	检查企业网络或内网 registry 是否包含网关和全部五个基础设施镜像。
Grafana 没有新数据	检查 `vector` 日志，并确认 `AI_GATEWAY_LOCAL_USAGE_INGEST_TOKEN` 在 app 和 Vector 中一致。

上线检查清单

docker compose ps 显示应用与依赖服务健康，migrate 为 exited 0。
管理员可以登录并创建独立的 gk_ Key。
业务系统可以完成一次真实的 /v1/chat/completions 调用。
ONPREM_TRUST_ANY_ORIGIN=false，且浏览器 Origin 配置正确。
/api/local/usage-batch 未暴露到公网。
PostgreSQL 备份已完成，并完成至少一次恢复演练。