生产部署至少包含 Hub 服务、MySQL、对象存储和认证配置。需要执行 Agent 时，还要连接 Agent Deployer 与 Agent Runtime。
官方镜像为 zeroneai/agent-hub，采用多阶段构建：前端（vite）→ 后端（Go）→ 精简运行层，最终镜像仅包含 server 二进制、ca-certificates 与 tzdata。
- 暴露端口：
8081
- 健康检查：
GET /health
本地快速启动见 快速开始；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 只会是代理地址：
- 逗号分隔的 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。需要时按 配置 中的 runbook 登记各组织 Casdoor client。
- 升级演练：存量 Agent 需逐个重新部署以落位租户限定部署键（三步迁移见 配置 的「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。
只配置 CHAT_PUSH_API_KEY 或 CHAT_PUSH_PUBLIC_URL 其中一项不会启用聊天回传。两项必须同时设置，存量 Agent 需要重新部署。
