配置系统
Yuxi 的配置分成两类：启动进程时读取的环境变量，以及运行中由管理员在页面维护的系统配置。区分这两类，可以判断修改后需要保存、清缓存还是重启服务。
配置来源和优先级
对支持运行时修改的字段，生效顺序是：
代码默认值 < 环境变量 < PostgreSQL 中保存的系统配置数据库中保存的非空值优先于环境变量；布尔值和列表即使是 false 或空列表，也会被视为管理员明确保存的值。没有数据库值时，系统才读取对应环境变量或代码默认值。
启动期环境变量由 Docker Compose 注入 API、worker、provisioner 和依赖服务。它们决定服务地址、密钥、存储位置和沙盒承载方式。修改环境变量后需要重新创建读取它的容器；只执行 docker compose restart 不会更新容器环境：
docker compose up -d --force-recreate api worker如果改的是 provisioner 变量，把服务名换成 sandbox-provisioner；生产环境还要带上 --env-file .env.prod -f docker-compose.prod.yml。
管理员系统配置
管理员在“设置 → 基本设置”中修改系统配置。当前配置项由 options.py 定义，包含：
- 默认对话模型、快速响应模型、嵌入模型和重排模型；
- 默认 OCR 解析引擎。
系统配置保存到 PostgreSQL 的 config_options 表。API 和 worker 通过 Redis 保存短期缓存；保存成功后缓存会失效，下一次读取从数据库取得新值。Redis 不可用时，读取路径回源 PostgreSQL，不把缓存当作最终事实。
运行中的已初始化组件不保证热更新。例如模型供应商使用的 API Key 环境变量、OCR 服务地址、沙盒连接和数据库地址变化后，应重新创建实际读取这些变量的 API、worker 或 provisioner。
模型和 OCR
- 模型供应商、聊天模型、嵌入模型和重排模型的配置见模型配置。
- OCR 引擎和各服务凭证的配置见文档处理与 OCR。
- 沙盒应用层与 provisioner 的配置见沙盒配置与运维。
- 编码执行（opencode/codex）的加密密钥、供应商引用与沙盒策略见编码执行配置指南与编码执行配置参考。
委派与 Multica 桥接
元垒通过统一委派接口把任务交给外部执行器，Multica 是其中一个渠道。MVP 的 Multica 凭据只走实例级全局环境变量，由 API 与 worker 读取，scripts/init.sh 不生成这四个键；接入 Multica 实例时必须手工提供。YUANLEI_MULTICA_BASE_URL、YUANLEI_MULTICA_TOKEN 或 YUANLEI_MULTICA_WORKSPACE_ID 任一为空时整条 Multica 渠道 fail-closed：MulticaExecutor 不注册，向 multica 发起委派得到结构化 executor_unavailable，Multica 渠道同步与游标入口返回结构化 channel_unavailable（均为 HTTP 503），元垒其余能力独立可用。
| 变量 | 必填 | 说明 |
|---|---|---|
YUANLEI_MULTICA_BASE_URL | 是 | Multica 实例地址；端点与认证头收敛在 HttpMulticaClient |
YUANLEI_MULTICA_TOKEN | 是 | 渠道令牌；只经环境注入，明文不写入 DB、API 响应、日志或事件 |
YUANLEI_MULTICA_WORKSPACE_ID | 是 | issues 端点的 workspace 作用域；缺失即 400，故与凭据一起 fail-closed |
YUANLEI_MULTICA_PROJECT_ID | 否 | 出向创建与入向拉取的项目范围；为空时用渠道默认 |
凭据是启动期读取，修改后重建读取它的容器：
docker compose up -d --force-recreate api worker出向委派（POST /api/projects/{project_id}/delegations）先按稳定 operation_id 与描述标记核对再创建，同一操作不产生第二个远端工作项；入向同步（POST /api/projects/{project_id}/channels/multica/sync）在项目内拉取并只产生 proposed 治理行。入向请求固定 sort=updated_at&direction=desc（服务端忽略 updated_after），游标是稳定组合键 (updated_at, id)；同一 updated_at 的边界秒内项目每轮重扫并靠外部标识去重，避免因服务端并列次序丢失项。两个入口都要求登录用户且 Project 可见。
当前粒度是实例级全局：同一实例内所有 Project 共用一组 Multica 凭据。升级到按 Project 的凭据（依据 channel_delegations.project_id 与 channel_sync_cursors(channel, project_id)，非按用户）属于后续决策。完整语义、失败与取舍见外部执行器委派与 Multica 桥接。
Agent 并发容量
Compose 默认按单 worker、100 个同时运行的 AgentRun 配置。执行槽、API/worker Redis 和 PostgreSQL 池、LangGraph checkpoint 池、PostgreSQL 服务端上限、Sandbox 地址池与清理并发必须联动核算，不能只扩大其中一个值。
推荐值、1/10/20/50/100 并发的延迟和资源实测、取消 key 轮询的负载模型及完整验证命令见 Agent 并发容量。所有可覆盖变量仍集中列在仓库根 .env.template，不另外维护重复配置清单。
修改后的确认方式
修改系统配置后，重新打开配置页面确认保存值，并用一次真实请求确认行为。只看到 HTTP 200 或提示“保存成功”不能证明模型、OCR 或检索链路已经可用。
- 模型：在供应商页面执行连接测试，再发起一次真实对话。
- OCR：在 OCR 配置中查看健康状态，再解析一份测试文件。
- 知识库：回到知识库页面检查文件状态和检索结果。
- 沙盒：检查 provisioner
/health，再执行一次文件读写或命令操作。
历史配置
旧版 base.toml 和 SAVE_DIR 不属于当前运行时配置来源。受支持的历史数据由一次性 storage migrator 处理；日常部署不要手动把旧文件复制回运行目录。升级步骤见生产部署指南。