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

2026-08-25 15:08:28 +08:00
parent b0ecbabdf0
commit d7f4688bfb
16 changed files with 320 additions and 37 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Project-Profile.-
-wiki_revision: 5392ab80c7789a793ee271c85d2aca875bedc7f2
-synchronized_at: 2026-08-24T07:59:16Z
+wiki_revision: cd93968f7c48ebbe0a594f6198c29726e8ac9c3e
+synchronized_at: 2026-08-25T07:00:30Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -175,13 +175,13 @@ synchronized_at: 2026-08-24T07:59:16Z

 Windows 本地开发可使用 `config/local-services.yml` 与 `scripts/start-all.bat`、`status-all.bat`、`stop-all.bat` 统一管理 Portal、Admin API 和 Admin UI。统一配置只保存 loopback Host、端口和受保护配置文件路径，不保存或复制 DSN、JWT secret、密码、Token 或 Provider Key。

-Portal 的敏感配置仍来自 `portal.environment_file` 指向的受保护 PowerShell 环境文件，统一配置只覆盖 `CHORUS_LISTEN_ADDRESS`；Admin API 的 Host/Port 和敏感值仍以 `admin.settings_file` 指向的 settings.yml 为唯一事实源；Admin UI Host/Port 来自统一配置，API 基址在启动时由 Admin 地址派生。脚本不会运行 migration、AutoMigrate、seed、管理员 bootstrap 或依赖安装。
+Portal 的数据库、Session 等敏感配置仍来自 `portal.environment_file` 指向的受保护 PowerShell 环境文件；Provider/worker 运维参数来自 `portal.settings_file` 指向的严格 YAML，已设置的同名环境变量逐项覆盖 YAML。统一配置覆盖 `CHORUS_LISTEN_ADDRESS` 并传递两个 Portal 配置路径；Admin API 的 Host/Port 和敏感值仍以 `admin.settings_file` 为唯一事实源。脚本不会运行 migration、AutoMigrate、seed、管理员 bootstrap 或依赖安装。

 统一脚本只管理状态文件记录且可执行路径匹配的进程。端口被未受管进程占用时显示 `unmanaged listener` 并拒绝接管；启动中途失败只回滚本次新启动的组件。现有 `scripts/chorus-dev.bat` 继续用于单独管理 Portal 和 mock。
 <!-- supervisor-39 -->
 ## #39 本机 Supervisor 三实例（2026-08-24，验收通过）

-本机 `D:\supervisor` 通过 `scripts/install-supervisor.bat` 安装并托管三个独立实例：`chorus-user`、`chorus-admin-api`、`chorus-admin-ui`。Portal 和 Admin UI 地址来自 `config/local-services.yml`；Admin API 地址与运行配置来自 `admin/config/settings.yml`。安装器只把构建产物和不含凭据的 program 配置写入 Supervisor 目录，Portal 启动时才在进程内读取受保护环境文件。
+本机 `D:\supervisor` 通过 `scripts/install-supervisor.bat` 安装并托管三个独立实例：`chorus-user`、`chorus-admin-api`、`chorus-admin-ui`。Portal 地址、环境文件和 YAML settings 路径来自 `config/local-services.yml`；Admin API 地址与运行配置来自 `admin/config/settings.yml`。安装器只把构建产物和配置路径写入 Supervisor 目录，Portal 启动时才在进程内读取受保护文件。

 三个实例均以前台子进程运行，启用自动重启、独立日志和进程组停止。更新代码或统一配置后重新运行安装器，再执行 Supervisor `reload`。此入口只用于当前 Windows 本地环境，不执行 migration、AutoMigrate、seed 或账号创建。

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Architecture-and-Code-Map.-
-wiki_revision: 84986fd08a4814ac64fd61d7ab5c02a06d815dc8
-synchronized_at: 2026-08-25T03:56:20Z
+wiki_revision: 451c402646bbd8431a12b624cbe42072d40aa1ca
+synchronized_at: 2026-08-25T07:00:45Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -106,7 +106,7 @@ MVP-0 第一张上传图自动作为 `primary`，其余为 `reference`；不提
 - MySQL 8 集成测试分别完成一次 chat 和 images_edits，断言 rendered_prompt、attempt ProviderModel/latency、输出记录、原图和缩略图；全程不访问真实 Provider。
 ### #15 portal 组合根与运行闭环

- `portal/main.go` 现在实际组装 MySQL queue controller、SSRF 安全 HTTP client、Provider factory/catalog、本地存储和内嵌 worker；同步 handler 仍只写 pending，不持有 Provider 依赖。
+- `portal/main.go` 现在实际组装 MySQL queue controller、SSRF 安全 HTTP client、Provider factory/catalog、本地存储和内嵌 worker；同步 handler 仍只写 pending，不持有 Provider 依赖。Portal 启动必须显式传入 `--config <settings.yml>`；Provider/worker 参数从严格 YAML 读取，同名环境变量优先覆盖。
 - worker 的 claim 必须经过 `queue.Controller`；收到退出信号后先阻止新 claim，HTTP server 停止接收请求，并等待在途 worker 在租约上下文内完成。HTTP 或 worker 任一组件意外结束都会让进程失败关闭。
 - 非生产默认 lease 60 秒、Provider HTTP 超时 45 秒、轮询 250ms、响应上限 32MiB；生产必须显式配置，且 lease 必须比 HTTP 超时多 5 秒以上。
 - `CHORUS_TEST_DISABLE_WORKER=true` 只允许 `CHORUS_ENV=test`，用于浏览器稳定观察状态的测试 fixture；开发和生产环境启用会直接报错。真实 Provider/worker 成功仍通过注入受控 DNS/DialContext 的 MySQL 集成测试验证，生产 SSRF 逻辑没有旁路。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.-
-wiki_revision: 9931fb7acc36ebcbcc122bcbd528887b970efb10
-synchronized_at: 2026-08-25T03:56:31Z
+wiki_revision: 660d4bc4e857a92c6cf6606d2af95d1b5f2f6d04
+synchronized_at: 2026-08-25T07:00:57Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -202,14 +202,14 @@ scripts\chorus-dev.bat restart
 scripts\chorus-dev.bat stop
 ```

-`start` 会校验环境文件、本地 MySQL TCP 连接和监听端口，构建临时可执行文件，在后台启动 portal，并检查 `/login`。重复启动不会创建第二个 portal；`restart` 只重启 portal；`stop` 只停止由脚本记录且可执行文件路径匹配的 portal 和 mock 进程。脚本不会执行迁移、GORM AutoMigrate、seed 或创建测试账号。
+`start` 会校验环境文件、`portal/config/settings.yml`、本地 MySQL TCP 连接和监听端口，构建临时可执行文件，以 `--config` 显式传入 YAML 后在后台启动 portal，并检查 `/login`。重复启动不会创建第二个 portal；`restart` 只重启 portal；`stop` 只停止由脚本记录且可执行文件路径匹配的 portal 和 mock 进程。脚本不会执行迁移、GORM AutoMigrate、seed 或创建测试账号。

 脚本默认读取仓库外的 `D:\OPC\chorus-tools\chorus-test.env.ps1`；也可把其他可信环境文件作为带引号的第二个参数传入，例如 `scripts\chorus-dev.bat start "D:\tools\chorus local.env.ps1"`。日志、PID 状态和临时可执行文件位于 `%LOCALAPPDATA%\Chorus\dev`。

 需要在当前终端观察输出时，仍可运行：

 ```powershell
-go run ./portal
+go run ./portal --config portal/config/settings.yml
 ```

 浏览器验证：
@@ -361,6 +361,7 @@ portal:
  host: 127.0.0.1
  port: 8080
  environment_file: ../../chorus-tools/chorus-test.env.ps1
+  settings_file: ../portal/config/settings.yml
 admin:
  settings_file: ../admin/config/settings.yml
 admin_ui:
@@ -368,7 +369,7 @@ admin_ui:
  port: 9528
 ```

-相对路径以 `local-services.yml` 所在目录为基准。配置严格拒绝未知字段、非 loopback Host、无效/重复端口、缺失文件或错误扩展名。`chorus-local-config` 读取 Admin settings 时只投影 `settings.application.host/port`，不会输出其他配置内容。Admin Host/Port 不在统一配置重复保存，避免两个事实源漂移。
+相对路径以 `local-services.yml` 所在目录为基准。Portal `environment_file` 保存数据库、Session 等敏感环境变量；`settings_file` 保存 Provider/worker 运维参数，环境变量优先覆盖 YAML。配置严格拒绝未知字段、非 loopback Host、无效/重复端口、缺失文件或错误扩展名。`chorus-local-config` 读取 Admin settings 时只投影 `settings.application.host/port`，不会输出其他配置内容。Admin Host/Port 不在统一配置重复保存，避免两个事实源漂移。

 从仓库根目录执行：

@@ -398,7 +399,7 @@ D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf status

 | Supervisor 实例 | 组件 | 地址来源 |
 |---|---|---|
-| `chorus-user` | Portal 与内嵌 worker | `config/local-services.yml` 的 `portal` |
+| `chorus-user` | Portal 与内嵌 worker | `config/local-services.yml` 的 `portal` 地址、环境文件和 settings 文件 |
 | `chorus-admin-api` | Admin API | `admin/config/settings.yml` 的 `settings.application` |
 | `chorus-admin-ui` | Vue 开发服务 | `config/local-services.yml` 的 `admin_ui`；API 基址由 Admin 地址派生 |

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Troubleshooting
-wiki_revision: 47ed912393c434b5547bff7ee4a3c488af03b749
-synchronized_at: 2026-08-25T03:56:42Z
+wiki_revision: 77dbfc1946d599f06a69afc204297dbe198a0cff
+synchronized_at: 2026-08-25T07:01:14Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -69,6 +69,8 @@ LIMIT 10;
 5. 环境代理是否绕开安全 Dial；
 6. 上游返回的结果 URL 是否复用相同客户端。

+若 attempt latency 精确接近 Provider HTTP timeout，先检查 `portal/config/settings.yml` 的 `provider.http_timeout_seconds`；同时保证 `worker.lease_seconds` 比它大 5 秒以上。修改后必须重启 Portal，页面中的 ProviderModel timeout 不能突破更短的全局 HTTP timeout。
+
 拦截私网是正确行为，不能为联调关闭。需要访问内部 mock 时把 mock 与测试进程放在专用测试网络，并使用测试专用注入点，不在生产配置放行私网。

 ### 6. 文件和权限
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Deployment-and-Operations.-
-wiki_revision: 62fb1a6eb027824fce0d4147e6afba7c06e68fcf
-synchronized_at: 2026-08-25T03:57:04Z
+wiki_revision: f75c6883edc8dc431fc04cac1dee22aa2515e0d5
+synchronized_at: 2026-08-25T07:01:43Z
 <!-- gitea-wiki-mirror:end -->

 # 部署与运维
@@ -119,7 +119,7 @@ MVP-0 的终端用户会话保存在单个 portal 进程内存中，Cookie 只
 上传先在应用层校验，再在 generation 事务回调中保存带 owner/generation metadata 的文件。事务失败只清理本请求保存的 key；存储根目录不能作为 nginx/static 目录暴露。
 ## MVP-0 worker 已实现配置与退出行为

-portal 单二进制会同时启动 HTTP server 和内嵌 worker。生产除现有 portal 限制外，还必须显式提供：
+portal 单二进制会同时启动 HTTP server 和内嵌 worker。启动必须显式传入 `--config <settings.yml>`。下列 Provider/worker 参数以 YAML 为基础值，同名环境变量可逐项覆盖：

 | 变量 | 约束 |
 |---|---|
@@ -197,7 +197,7 @@ Provider API Key 由授权管理员通过管理端写入 `provider_credentials.a
 <!-- supervisor-39 -->
 ## Windows 本机 Supervisor 运行

-`D:\supervisor` 是当前 Windows 本地常驻运行方式，不替代生产反向代理或正式服务管理器。通过 `scripts/install-supervisor.bat` 生成三个独立实例：Portal、Admin API 和 Admin UI。Supervisor program 配置只保存进程路径、配置路径、Host/Port 与日志策略；Portal 凭据继续从 `portal.environment_file` 指向的受保护 PowerShell 文件读取，Admin 敏感值继续只存在于 `admin/config/settings.yml`。
+`D:\supervisor` 是当前 Windows 本地常驻运行方式，不替代生产反向代理或正式服务管理器。通过 `scripts/install-supervisor.bat` 生成三个独立实例：Portal、Admin API 和 Admin UI。Supervisor program 配置只保存进程路径、配置路径、Host/Port 与日志策略；Portal 数据库/Session 配置从 `portal.environment_file` 读取，Provider/worker 参数从 `portal.settings_file` 读取，Admin 敏感值继续只存在于 `admin/config/settings.yml`。

 安装或更新：