> ## 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 使用 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                                                                                |

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

#### 多租户与角色管理（仅 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`（会话归属用户）                                                                            |

<Warning>可信 `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。</Warning>

### 多组织接入 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` 并重启，然后：

```bash theme={null}
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）。**不设置则明文存储**——仅限开发环境 |

生成加密密钥：

```bash theme={null}
openssl rand -hex 32
```

详见 [Provider 配置](/zh/hub/providers)。

## 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 流式上传文档的超时时间（秒）                                                                                                                                                                      |

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