feat: 增加 Portal YAML 运行配置 #57

New Issue

2026-08-25T14:51:53+08:00

ila commented

2026-08-25 14:51:53 +08:00

基本信息

类型：Portal 启动配置改进
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2
阶段：进行中
前置工单：#55 的出站端口配置实现；不要求 #54 的真实 Provider 验证完成

原始需求

来源：用户对话
提出与确认时间：2026-08-25
关键意图：增加 Portal 配置文件保存 Provider 超时、允许端口与 worker 租约等参数，减少直接编辑 PowerShell 环境脚本。

目标

为 Portal 增加严格 YAML 运行配置，保存 provider/worker 非敏感运维参数；保留环境变量覆盖，并让 Supervisor 从 config/local-services.yml 解析、校验和传递配置路径。

非目标

不把 Provider API Key 写入 YAML。
本次不迁移数据库 DSN、Session Key、存储、限流等现有环境参数。
不增加管理页面在线修改；配置变更仍需重启 Portal。
不改变 SSRF、retryable、模型协议或数据库结构。

已确认方案

本机文件 portal/config/settings.yml，明确加入 Git ignore；仓库提交 portal/config/settings.example.yml。
YAML schema_version: 1，只接受 provider.http_timeout_seconds、provider.max_response_bytes、provider.allowed_ports、worker.lease_seconds、worker.poll_milliseconds。
Portal 新增必填 --config 启动参数；YAML 提供上述值，已设置环境变量逐项覆盖 YAML。
沿用现有生产校验：lease 必须比 Provider HTTP timeout 多 5 秒以上；端口仍使用 #55 严格解析/安全 Client。
config/local-services.yml 的 portal 同时引用 settings_file 与现有 environment_file；Supervisor 先加载环境文件，再传入 YAML 路径。

风险与回退

风险：双来源优先级不清会造成误判，因此固定“环境变量 > YAML”，启动日志不输出配置值或秘密。
回退：Supervisor 恢复旧二进制和配置，继续只加载环境文件；无数据库变化。

验收标准

YAML 严格拒绝未知字段、缺失 schema、非法端口和不一致 timeout/lease。
未设置环境变量时使用 YAML；环境变量能逐项覆盖。
Portal 只通过显式 --config 启动，Supervisor 正确传递解析后的绝对路径。
本机设置 120 秒 Provider timeout、150 秒 lease 和 80/443/8080 端口后正常启动。
根模块、配置解析、Supervisor resolver 和现有 SSRF 测试通过。
Wiki 启动、配置、部署与排错说明更新并同步镜像。

文档影响

更新 Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations、Troubleshooting；任务结果归档 Wiki，不自动导出 docs/task/。

## 基本信息 - 类型：Portal 启动配置改进 - 所属 Epic：#3 - 所属 MVP / 版本：#35 / MVP-2 - 阶段：进行中 - 前置工单：#55 的出站端口配置实现；不要求 #54 的真实 Provider 验证完成 ## 原始需求 - 来源：用户对话 - 提出与确认时间：2026-08-25 - 关键意图：增加 Portal 配置文件保存 Provider 超时、允许端口与 worker 租约等参数，减少直接编辑 PowerShell 环境脚本。 ## 目标为 Portal 增加严格 YAML 运行配置，保存 provider/worker 非敏感运维参数；保留环境变量覆盖，并让 Supervisor 从 `config/local-services.yml` 解析、校验和传递配置路径。 ## 非目标 - 不把 Provider API Key 写入 YAML。 - 本次不迁移数据库 DSN、Session Key、存储、限流等现有环境参数。 - 不增加管理页面在线修改；配置变更仍需重启 Portal。 - 不改变 SSRF、retryable、模型协议或数据库结构。 ## 已确认方案 - 本机文件 `portal/config/settings.yml`，明确加入 Git ignore；仓库提交 `portal/config/settings.example.yml`。 - YAML `schema_version: 1`，只接受 `provider.http_timeout_seconds`、`provider.max_response_bytes`、`provider.allowed_ports`、`worker.lease_seconds`、`worker.poll_milliseconds`。 - Portal 新增必填 `--config` 启动参数；YAML 提供上述值，已设置环境变量逐项覆盖 YAML。 - 沿用现有生产校验：lease 必须比 Provider HTTP timeout 多 5 秒以上；端口仍使用 #55 严格解析/安全 Client。 - `config/local-services.yml` 的 portal 同时引用 `settings_file` 与现有 `environment_file`；Supervisor 先加载环境文件，再传入 YAML 路径。 ## 风险与回退 - 风险：双来源优先级不清会造成误判，因此固定“环境变量 > YAML”，启动日志不输出配置值或秘密。 - 回退：Supervisor 恢复旧二进制和配置，继续只加载环境文件；无数据库变化。 ## 验收标准 - [ ] YAML 严格拒绝未知字段、缺失 schema、非法端口和不一致 timeout/lease。 - [ ] 未设置环境变量时使用 YAML；环境变量能逐项覆盖。 - [ ] Portal 只通过显式 `--config` 启动，Supervisor 正确传递解析后的绝对路径。 - [ ] 本机设置 120 秒 Provider timeout、150 秒 lease 和 80/443/8080 端口后正常启动。 - [ ] 根模块、配置解析、Supervisor resolver 和现有 SSRF 测试通过。 - [ ] Wiki 启动、配置、部署与排错说明更新并同步镜像。 ## 文档影响更新 Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations、Troubleshooting；任务结果归档 Wiki，不自动导出 `docs/task/`。

ila commented

2026-08-25 14:53:01 +08:00