配置

Agent Hub 核心环境变量与认证模式参考。

​

配置

Hub 使用 Viper 加载配置，环境变量优先级最高。本页是完整的环境变量参考，并包含升级与多租户说明。

​

服务器

变量	必填	默认值	说明
SERVER_HOST	否	0.0.0.0	监听地址
SERVER_PORT	否	8081	监听端口
SERVER_CORS_ORIGINS	否	允许全部	逗号分隔的 CORS allowlist；强烈建议显式设置

​

数据库

变量	必填	默认值	说明
DATABASE_URL	✅	—	MySQL DSN
DATABASE_MAX_IDLE	否	10	连接池空闲数
DATABASE_MAX_OPEN	否	100	连接池上限
DATABASE_MAX_LIFETIME	否	3600	连接最大存活时间（秒）

​

认证

Hub 提供两个可互换的认证后端，由 AUTH_MODE 选择：

• builtin（默认）：自包含的用户名密码系统，开源部署开箱即用，无需外部身份提供方。首次访问显示初始化页面，创建固定用户名的 admin 账号；后续用户通过 admin 签发的一次性邀请链接加入。角色为 admin / maintainer / member。
• casdoor：把认证委托给已有的 Casdoor SSO，适用于已运行 Casdoor 的托管与私有化部署。

变量	必填	默认值	说明
AUTH_MODE	否	builtin	认证后端：builtin 或 casdoor
AUTH_JWT_SECRET	否	自动生成	builtin 模式的 JWT 签名密钥；显式设置时必须 ≥ 32 字节（openssl rand -hex 32）。留空时首次启动生成随机密钥并持久化到 MySQL system_settings 表——重启、容器重建与镜像升级都会话不失效。casdoor 模式下忽略。多副本部署必须显式设置共享密钥

​

Casdoor（仅 AUTH_MODE=casdoor）

变量	必填	默认值	说明
CASDOOR_ENDPOINT	✅	—	Casdoor 服务地址
CASDOOR_CLIENT_ID	✅	—	OAuth Client ID
CASDOOR_CLIENT_SECRET	✅	—	OAuth Client Secret
CASDOOR_CERTIFICATE	✅	—	JWT 验签证书
CASDOOR_ORGANIZATION	否	—	可选。仅从旧版本升级且存量数据无法自动归属租户时，作为回填目标的显式覆盖（一次性升级逃生舱，完成迁移后可移除）。正常运行不消费该配置——租户来自登录 token 的组织（owner）
CASDOOR_CALLBACK_URL	否	—	OAuth 回调 URL

角色由 Hub 本地管理；JWT 中的 Casdoor roles claim 被完全忽略。Casdoor 只提供用户身份（认证）。详见下文多租户一节。

​

多租户与角色管理（仅 casdoor 模式）

• 租户 = Casdoor 组织：token 中的组织（owner）即租户 ID，业务数据按租户隔离。组织的创建与配置在 Casdoor 侧完成，Hub 不接管。
• 角色由 Hub 本地管理：角色真实源是本地 user_identities 租户成员表（Role + Status pending/active），Casdoor 仅提供用户身份。JWT 中的 Casdoor roles claim 完全忽略。CASDOOR_ROLE_MAPPING / CASDOOR_DEFAULT_ROLE 环境变量已废弃（检测到仅打 warning，不影响启动）；升级后 Casdoor 侧的 agent-hub-* 角色可手动删除。
• 新用户待审批流程：新用户首次登录成功后自动创建 pending 记录，前端渲染「等待审批」页（可访问 /auth/userinfo 与 logout，其余 API 返回 403 PENDING_APPROVAL）。admin 在用户管理页为其分配角色后自动转为 active。
• admin 锚定 Casdoor 组织管理员：本地 admin 资格与 Casdoor 组织管理员（IsAdmin）双向同步——组织管理员登录/CLI 身份核对时自动成为本地 admin；被取消组织管理员则本地 admin 撤销为待审批。admin 任命/降级采用「Casdoor 先行」双写：先成功修改 Casdoor is_admin，再写本地。
• 用户管理（admin）：列表来自本地成员表（禁用状态实时查 Casdoor）；审批 = 给 pending 用户分配角色（自动转 active）；禁用/重置密码直通 Casdoor；admin 在用户管理页获取本组织的一次性 OAuth 授权登录链接（/api/v1/admin/users/login-url，带本组织 client_id + PKCE）引导新用户走 Casdoor 登录/注册流。邀请制接口仅 builtin 模式可用。
• 升级指引（breaking）：升级到此模型后所有现有用户变为待审批；Casdoor 组织管理员登录后自动成为 admin，再逐个为其他用户分配角色。业务数据方面：升级时存量 agents / providers / AIGC 配置等自动回填——无需任何配置，回填租户从 user_identities 自动推断（恰好一个组织登录过即推断为该组织）；聊天记录按 user_id → user_identities 映射回填到各用户所属租户，映射不到的兜底回填推断租户。仅在存量数据无法自动归属（user_identities 为空或含多个组织）时，启动会报错指引临时配置 CASDOOR_ORGANIZATION 指定回填目标，完成本次一次性迁移后即可移除。
• 已知限制：
  • JWT 无吊销通道：admin 在 Casdoor 侧被降级后，其未过期的 access token 在过期前仍有效；CLI token 最迟 5 分钟内经身份缓存纠正。
  • 用户列表只显示登录过的用户（列表数据源为本地成员表，而非直通 Casdoor）。
• 部署要求：Hub 使用的 Casdoor Application 需要所在组织的用户管理权限（读写用户、组织管理员标志）。

数据隔离语义

业务表（agents / cloud_sessions / cloud_messages / provider_summaries / tools / mcp_servers / skills / scenes / aigc_configs）均含 tenant_id 列并按租户隔离：

• tenant_id = Casdoor 组织名：与登录 token 的组织（owner）一致；builtin 模式恒为 default。
• 哨兵约定：业务表 tenant_id 列的默认值为空串 ''（共享哨兵）——写入时由代码显式盖章请求租户，不依赖数据库默认值；空串仅在共享行（内置/种子数据）合法。
• 内置/种子数据全局共享：内置 tools、MCP servers、skills、scenes 及共享 provider 种子行的 tenant_id 为空串（全局共享行）——各租户均可读、不可修改；租户编辑共享 provider 时按 copy-on-write 复制为本租户行后再改动，原共享行不受影响。
• 存量数据回填：从旧版本升级时，启动迁移把存量业务数据回填到归属租户（builtin 模式 → default；casdoor 模式 → 从 user_identities 自动推断的唯一组织，可用 CASDOOR_ORGANIZATION 显式覆盖）。正常运行不依赖任何组织配置，CASDOOR_ORGANIZATION 仅在存量数据无法自动归属（0 或多个组织登录过）时作为一次性升级逃生舱存在。
• 同名资源跨租户共存：原全局唯一约束（如 agents 的 uk_name、provider_summaries 的 uk_key）已改为 (tenant_id, name) / (tenant_id, key) 复合唯一索引——不同租户可各自持有同名 agent / 同 key provider。
• 聊天数据两级隔离：cloud_sessions / cloud_messages 首先按租户隔离，会话列表在租户内再按用户隔离（member 仅见自己的会话，admin/maintainer 可见本租户全部会话）。
• AIGC 配置纯 per-tenant：每个租户各自配置自己的 aigc_configs 行（ContentProducer 主体编码等）；未配置的租户不注入 AIGC 标识，不存在跨租户的共享默认回退。写操作（Save / RotateKey / Delete）只作用于本租户行，且拒绝在租户身份缺失（builtin 之外的空租户上下文）时执行。升级时，旧「全局一份」时代的遗留共享行自动归属回填租户（显式指定或自动推断的唯一租户）；若该租户已保存自有配置，则丢弃遗留共享行、保留租户自有配置。
• knowledge MCP 链（runtime token）：以 runtime token 访问知识库时，租户取自所命中的 agents 行的 TenantID，与操作者无关。
• Kong 对账为全局语义：后台 Kong 路由对账任务扫描全表（agent ID 全局唯一），不受租户隔离过滤影响。

​

角色权限矩阵

管理台（/api/v1/admin/*）按角色开放如下（builtin 与 casdoor 模式语义一致）：

权限	admin	maintainer	member
用户管理（用户列表/审批/邀请/重置密码）	✅	—	—
管理写操作（创建/编辑/删除 agent、tool、MCP、skill、scene、provider、知识库）	✅	✅	—
敏感读（AIGC 配置与密钥、agent 运行时文件内容）	✅	✅	—
非敏感 GET（agent/tool/MCP/skill/scene/provider/知识库列表与详情、部署状态 deploy）	✅	✅	✅
聊天历史会话（查看/删除）	✅ 全部会话	✅ 全部会话	✅ 仅自己的会话
普通聊天（公开 /agents 聊天接口）	✅	✅	✅
CLI token 自管理（/cli）	✅	✅	—

要点：

• member 只读边界：member 可读管理台的非敏感数据（列表/详情/知识库/部署状态 deploy，含 runtimeUrl/apiKey），但管理写操作（POST/PUT/PATCH/DELETE，含探活、部署启停）与敏感读（AIGC 配置含密钥、agent 运行时文件内容 files/content）仍返回 403——中间件是权限墙，前端按钮隐藏仅 UX。例外：member 可删除自己的聊天会话。
• 聊天会话按用户隔离：member 仅可查看/删除自己的聊天会话；admin/maintainer 可见并管理全部会话。
• 用户管理仅 admin：审批/角色分配/邀请/重置密码保持 admin 专属（RequireAdmin）。
• 路径未改名：全部保持 /api/v1/admin/*，仅内部按 write（admin/maintainer）/ read（admin/maintainer/member）分组注册。
• CLI token 收口：/api/v1/cli 仅 admin/maintainer 可用（member 403），不属于 /admin 面但同样由角色中间件拦截；member 历史已签发的 token 不主动吊销，自然过期后无法续签。
• member 部署按钮：member 在 Agent 页可见部署按钮，弹窗内仅「聊天」可用，其他操作按钮置灰。

​

运维（Ops API）

运维端点（/api/v1/ops/*，当前用于多组织 OAuth client 登记，见下文 runbook）的鉴权开关：

变量	必填	默认值	说明
OPS_API_KEY	否	—	运维 API 鉴权密钥。空（默认）= 运维端点不挂载，请求 /api/v1/ops/* 等效 404；配置后所有请求需携带请求头 X-Ops-Key: <OPS_API_KEY>，匹配放行，否则拒绝。仅在需要接入新组织时配置
CHAT_PUSH_API_KEY	否	—	/api/v1/chat/push 专用推送密钥。空（默认）= X-Chat-Push-Key 通道禁用，push 仅走 JWT/CLI 鉴权；配置后携带请求头 X-Chat-Push-Key: <CHAT_PUSH_API_KEY> 的请求可走该通道（会话归属由请求 body 的 per-session user_name/org 决定，user_name 必填；org 语义按模式分：builtin 忽略该字段恒落 default；casdoor 显式传则用所传值，缺省解析为 tenant_oauth_clients 的 default 行组织——未登记 default 行时缺省 org 的推送返回 400）。与 CHAT_PUSH_PUBLIC_URL 同时配置时，部署 agent 会把回传配置经 deployer 写入 runtime 的 agents.yaml hub 段（见下）。独立于 OPS_API_KEY，泄漏互不影响。建议使用 ≥32 字节高熵随机值，入 secret manager 管理
CHAT_PUSH_PUBLIC_URL	否	—	Hub 自身对外可达的 base URL（如 https://console.example.com，裸 base 不带路径——runtime 会自拼 /api/v1/chat/push）。与 CHAT_PUSH_API_KEY 同时配置时，新部署的 agent runtime 开启聊天记录回传，Hub 同时下发该 agent 的部署租户作为可信 org（builtin 恒 default，casdoor 为部署时的租户）：runtime 以此为回传会话盖章租户，X-Org 头已被 runtime 移除、无法影响落点。Hub 自身代理的聊天不回传（Hub 自记录，runtime 因无身份头自动跳过）。仅配置其一 = 不下发回传配置（回传关闭，向后兼容）。存量 agent 需重新部署才会带上该配置（含 org）。外部调用者直连 runtime 只需携带 X-User-Name（会话归属用户）

可信 hub.org 的生效要求：Hub ≥ v2.1.5 + agent-deployer ≥ v2.2.0（支持 HubConfig.org）+ agent-runtime ≥ 2.2.0（从配置读 org，已移除 X-Org 头），且存量 agent 重新部署。旧组件会静默忽略 org 字段——若链路中仍有 runtime < 2.2.0 在跑，该 runtime 仍采信 X-Org 且无 org 时回传落点回退 Hub 默认租户解析（多租户 casdoor 下可能错归），请完成升级后重新部署存量 agent。

​

多组织接入 runbook（仅 casdoor 模式）

单组织部署（一个 Casdoor 组织 = 一个租户）无需任何操作：租户 client 表为空时自动回落 env 全局 CASDOOR_CLIENT_ID / CASDOOR_CLIENT_SECRET / CASDOOR_CERTIFICATE，行为与旧版本完全一致。只有当第二个及以后的组织（租户）需要通过各自 Casdoor Application 登录时，才按以下三步操作。

​

第一步：Casdoor 侧建组织与应用

每个组织（如 acme）在 Casdoor 中：

1. 创建组织 acme（组织即租户，业务数据按组织隔离）。
2. 在该组织下创建一个 Casdoor Application，回调（redirect URL）配置为 Hub 全局回调 CASDOOR_CALLBACK_URL（无需 per-org 回调），记录其 Client ID / Client Secret。
3. 无需创建 agent-hub-admin / agent-hub-maintainer / agent-hub-member 角色——Hub 的角色以本地成员表（user_identities）为准，Casdoor 侧角色不被消费（Casdoor 仅提供用户身份，Casdoor 组织管理员自动同步为本地 admin）。旧版本若在 Casdoor 侧创建过这些角色，可手动删除。

​

第二步：通过 Ops API 登记租户 client

先在 Hub 侧配置 OPS_API_KEY 并重启，然后：

curl -X POST https://<hub>/api/v1/ops/tenant-clients \
  -H "X-Ops-Key: <OPS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"org":"acme","clientId":"...","clientSecret":"..."}'

字段说明：org = Casdoor 组织名（即租户 ID）；cert 可选，仅当该组织使用独立于全局 CASDOOR_CERTIFICATE 的验签证书时才需要传（PEM 明文；非空时必须为合法 PEM 证书（-----BEGIN CERTIFICATE----- 开头），否则 400）；isDefault 可选。

org 命名约束：组织名必须匹配 ^[a-z][a-z0-9]{0,62}$（小写字母开头，仅小写字母和数字，不超过 63 字符），不允许连字符、大写、下划线等，不合法返回 400。原因：组织名用于拼接部署键 <org>-<agent> 与 runtime URL 路径段 /<org>/<agent>（见下文「Agent ID、部署键与 runtime URL」），而 agent 名本身允许连字符——若 org 也允许连字符，(org "a", agent "b-c") 与 (org "a-b", agent "c") 会拼出同一个部署键，产生跨租户覆盖/误删的歧义。已登记的存量组织不受影响，无需迁移。

default tenant 语义（不变式：有且唯一）：

• 首行自动成为 default：登记的第一条记录自动 isDefault=true。
• 登录页组织输入框留空（或无 org 参数访问）即走 default 行。
• 切换 default：给新行显式传 "isDefault":true（原子切换，旧 default 自动降级）。
• 降级保护：把当前 default 降级（新增非 default 行时）且表内还有其他行 → 409；删除 default 行且表内还有其他行 → 409（响应含迁移指引：先把 default 切给其他组织再删）。删 default 是最后一行时允许；删除不存在的 org 幂等返回 204。

管理查询：GET /api/v1/ops/tenant-clients（返回 org / clientId / isDefault / hasCert / 时间，不返回 secret）；删除登记：DELETE /api/v1/ops/tenant-clients/<org>（default 行且表内还有其他行 → 409；删除不存在的 org 幂等返回 204）。

​

第三步：分发组织专属登录链接

给该组织成员分发：https://<hub>/login?org=acme

• 登录页「更多」折叠区内会出现组织输入框（仅存在多组织配置时渲染），成员也可手动填组织名。
• 组织用户首次登录自动创建 pending 记录（等待 admin 审批分配角色）；Casdoor 组织管理员登录自动成为该租户 admin。
• 登录后的 refresh token 按 token 内的 owner 自解析对应组织凭证，无需额外配置。

​

解析链与边界行为

• 显式 org 未注册 → 404，绝不回落：?org=xxx 指定了不存在/未登记的组织，登录预检就地报错，不会回退到 default。
• 留空 / 无参数 → default 行 → env 全局：default 行不存在（表空）时回落 env CASDOOR_CLIENT_ID（存量单组织部署零改动）。

​

Agent ID、部署键与 runtime URL

自 deployer v3.1 契约起，agent 的三个标识各自独立：

标识	形态	用途
Agent ID	裸 <name>	runtime agent 图与 chat 语义；Hub 的聊天/详情代理经 /v1/agents/<name> 裸名寻址 runtime（subagent 同为裸名）
Deployment key	<org>-<name>	deployer 容器/数据目录/生命周期寻址（Get/Start/Stop/Delete）；Kong service/route 实体名（带 agent- 前缀，如 agent-acme-general）
Public URL	casdoor：/<org>/<name>；builtin：/<name>	Kong 路由与无 Kong 时的 Hub 代理路径（/runtime 前缀）；builtin 不暴露内部 default 租户名，但 deployment key 仍保持 default-<name>

• 数据库仍存裸名（agents.name 等），租户归属由 tenant_id 列表达，部署键仅在部署/网关层拼接。
• 链路版本要求：agent-deployer ≥ v3.1.0（deploymentKey 必填拆分；Hub 部署前做能力探测，旧版 deployer 会被明确拒绝并返回 503）+ agent-runtime ≥ v2.6.1 + agent-sdk ≥ v3.1.0。
• 升级顺序：deployer v3.1.0 → Hub → 强制重新部署存量 Agent（runtime 图中的 prefixed root ID 需经重部署改回裸 ID；重部署前聊天/详情对旧 agent 返回 404 属预期）。存量 <org>-<name> 容器与数据目录无需迁移。
• builtin Kong 路由自动迁移：升级后首个对账周期（约 300s）把 /default/<name> 路由收敛为 /<name>；无 Kong 时公开 URL 从 /runtime/default/<name> 变为 /runtime/<name>（无重定向，调用方需更新）。

​

OSS（S3 / MinIO）

变量	必填	默认值	说明
OSS_ENDPOINT	否	—	S3 / MinIO Endpoint。留空 = 整体禁用 OSS（服务正常启动，仅文件上传/下载功能降级）
OSS_REGION	否	us-east-1	S3 Region
OSS_BUCKET	启用 OSS 时必填	—	Bucket 名（OSS_ENDPOINT 非空时缺失会启动报错）
OSS_ACCESS_KEY	启用 OSS 时必填	—	S3 Access Key
OSS_SECRET_KEY	启用 OSS 时必填	—	S3 Secret Key
OSS_FORCE_PATH_STYLE	否	false	MinIO 必须设为 true
OSS_CDN_HOST	否	—	Skill 文件下载的域名前缀。设置时：/skills 列表与 /skills/:name/download 返回永久 CDN URL；未设置时：列表 URL 字段为空，下载接口回落为 1 小时有效的 OSS 预签名 URL

​

Provider 加密

变量	必填	默认值	说明
PROVIDER_ENCRYPTION_KEY	⚠️	—	Provider API key 的加密密钥（32 字节 hex）。不设置则明文存储——仅限开发环境

生成加密密钥：

openssl rand -hex 32

详见 Provider 配置。

​

Agent Deployer

变量	必填	默认值	说明
AGENT_DEPLOYER_URL	✅	—	agent-deployer 服务地址，如 http://agent-deployer:8080（不带 /api/v1 后缀——客户端自行拼接 API 路径）
AGENT_DEPLOYER_API_KEY	否	—	agent-deployer 认证 Bearer token
AGENT_DEPLOYER_PUBLIC_HOST	否	从 AGENT_DEPLOYER_URL 解析	浏览器访问 runtime 的 Host
AGENT_RUNTIME_API_KEY	⚠️	—	已废弃 / 仅为兼容保留。Runtime Token 现由 Hub 在部署时生成并加密存储于 agents.runtime_token；该变量当前未被使用，仅作为配置项保留

Agent 图部署协议：Hub 部署 Agent 时向 agent-deployer 下发完整 Agent 图——rootAgentId + agents[]，subagent 为纯 id 引用，每个 Agent 携带自身完整能力（不继承、不回退父级配置），maxSessionQueries 等运行时全局字段仅 root 携带；自 deployer v3.1 起 rootAgentId 为裸 Agent ID，租户限定移至独立的 deploymentKey 字段。链路版本要求：agent-deployer ≥ v3.1.0（Hub 部署前探测并拒绝旧版）+ agent-runtime ≥ v2.6.1 + agent-sdk ≥ v3.1.0；Hub 升级后需重新部署存量 Agent。

​

Multirag（知识库）

变量	必填	默认值	说明
MULTIRAG_BASE_URL	知识库模块必填	—	multirag 服务地址，如 http://multirag:8000；缺失时服务仍启动，知识库 API 返回 503
KNOWLEDGE_MCP_URL	Agent 使用知识库时必填	—	Hub 的完整知识库 MCP 地址，必须包含 /api/v1/knowledge/mcp，并且可从 agent-runtime 容器访问（例如 http://<hub-host>:8081/api/v1/knowledge/mcp；不要误用容器内的 localhost）。启动时会自动写入或回填内置 knowledge MCP；修改后需重启 Hub 并重新部署 Agent
MULTIRAG_API_KEY	知识库模块必填	—	Hub 服务账号访问 multirag 的 Bearer token；不暴露给浏览器
MULTIRAG_TIMEOUT_SECONDS	否	30	Hub 调用 multirag 标准 API 的超时时间
MULTIRAG_UPLOAD_TIMEOUT_SECONDS	否	3600	Hub 向 multirag 流式上传文档的超时时间（秒）

大文件上传从浏览器流式直传 multirag，不会在 Hub 内整体缓冲。生产环境的反向代理或 Kong Route 也必须允许目标文件大小、关闭全请求体缓冲，并把上游超时设置为不小于 MULTIRAG_UPLOAD_TIMEOUT_SECONDS。