> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 部署

> 了解 Agent Hub 的生产部署组件和上线检查。

# 部署

生产部署至少包含 Hub 服务、MySQL、对象存储和认证配置。需要执行 Agent 时，还要连接 Agent Deployer 与 Agent Runtime。

## 镜像

官方镜像为 `zeroneai/agent-hub`，采用多阶段构建：前端（vite）→ 后端（Go）→ 精简运行层，最终镜像仅包含 `server` 二进制、`ca-certificates` 与 `tzdata`。

* 暴露端口：`8081`
* 健康检查：`GET /health`

本地快速启动见 [快速开始](/zh/hub/quickstart)；`quickstart/docker-compose.yml` 默认拉取 `zeroneai/agent-hub` 镜像（builtin 认证模式），`docker-compose.build.yml` 为本地源码构建覆盖文件，用 `-f` 叠加使用。

## Trusted Proxies 与审计来源 IP

审计日志（`audit_logs.remote_ip`）记录每条写操作的来源 IP。Hub 默认**不信任任何代理**（直连语义）：取 TCP 对端地址、忽略 `X-Forwarded-For`——这是安全默认值，但部署在反向代理之后时来源 IP 会失真。

Hub 部署在反向代理（Nginx / Kong 等）之后时，必须把代理网段配进 `SERVER_TRUSTED_PROXIES`，否则审计记录的 IP 只会是代理地址：

```bash theme={null}
SERVER_TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12"
```

* 逗号分隔的 CIDR 列表（每项去空白，空项丢弃）。
* 未设置 / 空值 / 纯空白 = 不信任任何代理（不是错误）。
* 非法 CIDR 启动直接失败（fail-fast）：错误配置后的信任状态不可保证，宁可拒绝启动。
* 只把真正直连 Hub 的代理网段加入列表——`X-Forwarded-For` 可伪造，信任过宽 = 审计 IP 可被伪造。

## 上线检查

* 为数据库与对象存储启用持久化和备份（`cloud_sessions` / `cloud_messages` 是用户数据，定期备份）。
* 把 `PROVIDER_ENCRYPTION_KEY` 设为高熵随机值（不要提交到仓库）。
* 显式设置 `SERVER_CORS_ORIGINS`（不要用默认的 AllowAll）。
* 部署在反向代理之后时，把 `SERVER_TRUSTED_PROXIES` 设为代理网段 CIDR，否则审计日志 `remote_ip` 记录的是代理地址。
* 多副本部署设置相同的 `AUTH_JWT_SECRET`。
* 使用 HTTPS，并将 Provider、Casdoor 和运维密钥放入 secret manager。
* 已有 Casdoor 的存量部署升级时**必须显式设置 `AUTH_MODE=casdoor`**——默认的 `builtin` 会导致 SSO 失效，看起来像账号丢失（breaking change）。
* 限制 Ops API 的网络入口；不需要接入多组织登录时不要设置 `OPS_API_KEY`。需要时按 [配置](/zh/hub/configuration) 中的 runbook 登记各组织 Casdoor client。
* 升级演练：存量 Agent 需逐个重新部署以落位租户限定部署键（三步迁移见 [配置](/zh/hub/configuration) 的「Agent ID、部署键与 runtime URL」）；仅当存量数据无法自动归属租户时，临时设置 `CASDOOR_ORGANIZATION` 作为一次性回填逃生舱（完成后移除）。
* 审批初始 admin：builtin 模式首访创建；casdoor 模式下 Casdoor 组织管理员登录自动成为 admin（无需在 Casdoor 创建任何 Hub 角色），其余用户登录后待审批分配角色。
* OSS 整体可选（`OSS_ENDPOINT` 留空即禁用）；启用时将 Bucket 设为公共读或配置 `OSS_CDN_HOST` CDN 加速 Skill 下载。
* 为 Runtime 回调配置可公开访问的 Hub base URL。

<Warning>只配置 `CHAT_PUSH_API_KEY` 或 `CHAT_PUSH_PUBLIC_URL` 其中一项不会启用聊天回传。两项必须同时设置，存量 Agent 需要重新部署。</Warning>

环境变量详见 [配置](/zh/hub/configuration)，安全边界详见 [安全](/zh/hub/security)。