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

New Issue

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

ila commented

2026-08-25 14:51:18 +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 恢复旧二进制和配置，继续只加载环境文件；无数据库变化。 ## 验收标准 - [x] YAML 严格拒绝未知字段、缺失 schema、非法端口和不一致 timeout/lease。 - [x] 未设置环境变量时使用 YAML；环境变量能逐项覆盖。 - [x] Portal 只通过显式 `--config` 启动，Supervisor 正确传递解析后的绝对路径。 - [x] 本机设置 120 秒 Provider timeout、150 秒 lease 和 80/443/8080 端口后正常启动。 - [x] 根模块、配置解析、Supervisor resolver 和现有 SSRF 测试通过。 - [x] Wiki 启动、配置、部署与排错说明更新并同步镜像。 ## 文档影响更新 Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations、Troubleshooting；任务结果归档 Wiki，不自动导出 `docs/task/`。

ila referenced this issue

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

mvp: MVP-2 API 开放与治理 #35

ila referenced this issue

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

epic: chorus 图文生成服务交付 #3

ila referenced this issue

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

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

ila referenced this issue from a commit

2026-08-25 15:12:48 +08:00

feat: 增加 Portal YAML 运行配置 (#56)

ila referenced this issue from a commit

2026-08-25 15:12:48 +08:00

docs: 明确 Portal YAML 配置优先级 (#56)

ila commented

2026-08-25 15:13:19 +08:00

实施与验证结果

实现提交：d7f4688；文档 revision 补充提交：d30365d；均已推送 main。
Portal 新增必填 --config，严格读取 schema version 1 的 YAML；未知字段、多文档、缺失文件、错误扩展、非正数、空/非法端口和 timeout/lease 不一致均失败关闭。
YAML 覆盖 provider timeout/响应上限/端口和 worker lease/轮询；同名环境变量逐项覆盖。生产必填检查不再重复要求这四项只能来自环境变量。
chorus-local-config 解析 portal.settings_file 绝对路径；Supervisor、all 和 dev 三套脚本统一传入配置。
本机未跟踪 portal/config/settings.yml 已使用 120 秒 timeout、150 秒 lease、80/443/8080；环境文件不再覆盖这五项。
Supervisor 制品已重建并只重启 chorus-user；进程命令行含 settings 路径，持续 Running，/login 返回 200。未自动提交真实生成请求。

测试

go test ./...：通过。
go vet ./...：通过。
PowerShell 三个启动脚本语法解析：通过。
python -m unittest discover -s tests -v：43 项通过。
python dev_scripts/harness.py check --strict：通过。
python dev_scripts/harness.py sync --check：通过。

文档与本地文件

Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Troubleshooting、Deployment-and-Operations 已先更新 Wiki、在线回读并同步镜像。真实 settings.yml 与已有本机 local-services.yml、Admin settings 均未提交；仓库只提交无敏感值 example。误重复创建的 #57 已说明原因并关闭，无代码关联。

## 实施与验证结果 - 实现提交：`d7f4688`；文档 revision 补充提交：`d30365d`；均已推送 `main`。 - Portal 新增必填 `--config`，严格读取 schema version 1 的 YAML；未知字段、多文档、缺失文件、错误扩展、非正数、空/非法端口和 timeout/lease 不一致均失败关闭。 - YAML 覆盖 provider timeout/响应上限/端口和 worker lease/轮询；同名环境变量逐项覆盖。生产必填检查不再重复要求这四项只能来自环境变量。 - `chorus-local-config` 解析 `portal.settings_file` 绝对路径；Supervisor、all 和 dev 三套脚本统一传入配置。 - 本机未跟踪 `portal/config/settings.yml` 已使用 120 秒 timeout、150 秒 lease、80/443/8080；环境文件不再覆盖这五项。 - Supervisor 制品已重建并只重启 `chorus-user`；进程命令行含 settings 路径，持续 Running，`/login` 返回 200。未自动提交真实生成请求。 ### 测试 - `go test ./...`：通过。 - `go vet ./...`：通过。 - PowerShell 三个启动脚本语法解析：通过。 - `python -m unittest discover -s tests -v`：43 项通过。 - `python dev_scripts/harness.py check --strict`：通过。 - `python dev_scripts/harness.py sync --check`：通过。 ### 文档与本地文件 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Troubleshooting、Deployment-and-Operations 已先更新 Wiki、在线回读并同步镜像。真实 `settings.yml` 与已有本机 `local-services.yml`、Admin settings 均未提交；仓库只提交无敏感值 example。误重复创建的 #57 已说明原因并关闭，无代码关联。

ila commented

2026-08-25 15:15:53 +08:00