feat: Portal YAML 支持配置监听地址和端口 #74

New Issue

2026-08-28T23:05:30+08:00

ila commented

2026-08-28 23:05:30 +08:00

基本信息

类型：单元任务
所属 MVP：#35
所属 Epic：#3
状态：待验收
提出时间：2026-08-28
原始需求来源：用户对话
用户确认摘要：打包后的 Portal 需要能够直接在 config/portal/settings.yml 中配置监听地址和端口，并按已确认方案建单实施。

目标

为 Portal YAML 运行配置增加监听地址，使 Windows 运行包无需额外批处理环境变量即可修改端口，同时保持既有环境变量兼容和明确优先级。

非目标

不修改 Admin API 或 Admin UI 端口配置。
不改变数据库、会话、Provider、worker 或安全策略。
不新增公开网络监听默认值；默认仍为 127.0.0.1:8080。
不修改 migration 或业务数据。

已确认方案

在 schema_version 1 中增加可选配置：

server:
  listen_address: 127.0.0.1:8080

优先级固定为：CHORUS_LISTEN_ADDRESS 环境变量 > YAML server.listen_address > 默认 127.0.0.1:8080。
严格 YAML 解析继续拒绝未知字段；监听地址为空、格式错误、端口为 0 或超出范围时启动失败。
更新示例配置、配置单元测试、部署与本地验证 Wiki。
重新构建 Windows dist 运行包，保留旧包并产生新版本目录与 ZIP。

风险与控制

风险：配置错误导致服务无法启动，或误监听公网。
控制：配置加载时校验 host:port；示例继续使用 loopback；环境变量覆盖便于部署系统统一注入。
回退：删除 server 配置段即可恢复默认或环境变量行为；代码回退不涉及数据。

验收标准

YAML 可设置 Portal 监听地址和端口。
环境变量可覆盖 YAML。
未配置时保持默认 127.0.0.1:8080。
非法地址与端口启动前被拒绝。
既有 Provider/worker YAML 配置行为不变。
Go 测试、vet、Portal 构建及 Windows 制品检查通过。
Wiki、核心镜像、提交、推送和工单证据完成。

设计证据

非 UI 配置契约变更，无需界面原型；以上配置层级、优先级、校验和回退方案已由用户于 2026-08-28 明确确认。

文档影响

更新 Local-Development-and-Verification、Deployment-and-Operations；同步核心 docs/ 镜像。

## 基本信息 - 类型：单元任务 - 所属 MVP：#35 - 所属 Epic：#3 - 状态：待验收 - 提出时间：2026-08-28 - 原始需求来源：用户对话 - 用户确认摘要：打包后的 Portal 需要能够直接在 `config/portal/settings.yml` 中配置监听地址和端口，并按已确认方案建单实施。 ## 目标为 Portal YAML 运行配置增加监听地址，使 Windows 运行包无需额外批处理环境变量即可修改端口，同时保持既有环境变量兼容和明确优先级。 ## 非目标 - 不修改 Admin API 或 Admin UI 端口配置。 - 不改变数据库、会话、Provider、worker 或安全策略。 - 不新增公开网络监听默认值；默认仍为 `127.0.0.1:8080`。 - 不修改 migration 或业务数据。 ## 已确认方案 - 在 schema_version 1 中增加可选配置： ```yaml server: listen_address: 127.0.0.1:8080 ``` - 优先级固定为：`CHORUS_LISTEN_ADDRESS` 环境变量 > YAML `server.listen_address` > 默认 `127.0.0.1:8080`。 - 严格 YAML 解析继续拒绝未知字段；监听地址为空、格式错误、端口为 0 或超出范围时启动失败。 - 更新示例配置、配置单元测试、部署与本地验证 Wiki。 - 重新构建 Windows dist 运行包，保留旧包并产生新版本目录与 ZIP。 ## 风险与控制 - 风险：配置错误导致服务无法启动，或误监听公网。 - 控制：配置加载时校验 host:port；示例继续使用 loopback；环境变量覆盖便于部署系统统一注入。 - 回退：删除 `server` 配置段即可恢复默认或环境变量行为；代码回退不涉及数据。 ## 验收标准 - [x] YAML 可设置 Portal 监听地址和端口。 - [x] 环境变量可覆盖 YAML。 - [x] 未配置时保持默认 `127.0.0.1:8080`。 - [x] 非法地址与端口启动前被拒绝。 - [x] 既有 Provider/worker YAML 配置行为不变。 - [x] Go 测试、vet、Portal 构建及 Windows 制品检查通过。 - [x] Wiki、核心镜像、提交、推送和工单证据完成。 ## 设计证据非 UI 配置契约变更，无需界面原型；以上配置层级、优先级、校验和回退方案已由用户于 2026-08-28 明确确认。 ## 文档影响更新 Local-Development-and-Verification、Deployment-and-Operations；同步核心 `docs/` 镜像。

ila referenced this issue

2026-08-28 23:05:36 +08:00

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

ila referenced this issue

2026-08-28 23:05:36 +08:00

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

ila referenced this issue from a commit

2026-08-28 23:16:14 +08:00

feat: 支持 Portal YAML 配置监听地址 (#74)

ila commented

2026-08-28 23:18:32 +08:00

实施完成，待人工验收

最终差异

Portal YAML schema_version 1 新增可选 server.listen_address。
优先级为 CHORUS_LISTEN_ADDRESS > YAML > 默认 127.0.0.1:8080。
最终监听地址在启动前校验 host:port，拒绝空 host、非数字端口、端口 0 和超过 65535；严格 YAML 继续拒绝未知字段。
示例配置和 Windows 运行包已包含该字段；统一 Supervisor 启动仍由 local-services.yml 显式覆盖，避免本机三实例配置漂移。
未修改数据库、migration、Admin 端口或安全边界。

验证

go test ./internal/config/...：通过。
go test ./...：通过。
go vet ./...：通过。
Harness 45 项测试与 check --strict：通过。
Wiki sync --check：16 个核心镜像一致。
Portal 前端构建：通过。
Admin UI 生产构建：通过，仅既有 Sass、codemirror 和包体积 warning。
Windows ZIP：68 个条目完整性检查通过，包含四个 EXE、Admin UI、migration 11 及带 server.listen_address 的 Portal 示例配置。

文档与提交

Local-Development-and-Verification revision：50810cebc9b77723c4cbcb467786f12915a09b57
Deployment-and-Operations revision：fe7f8d0ca98f6c2fbf137316afe833b7f2c1f629
提交：f354d53 feat: 支持 Portal YAML 配置监听地址 (#74)，已推送至 origin/main。

Windows 制品

目录：dist/chorus-windows-amd64-f354d53ba6f6
ZIP：dist/chorus-windows-amd64-f354d53ba6f6.zip
大小：65,252,356 字节
SHA-256：37145484f0670811c116cb26e12316e2ecd6069b62b32d836838c65b8d519ecc

工单保持开启，状态为“待验收”。

## 实施完成，待人工验收 ### 最终差异 - Portal YAML schema_version 1 新增可选 `server.listen_address`。 - 优先级为 `CHORUS_LISTEN_ADDRESS` > YAML > 默认 `127.0.0.1:8080`。 - 最终监听地址在启动前校验 `host:port`，拒绝空 host、非数字端口、端口 0 和超过 65535；严格 YAML 继续拒绝未知字段。 - 示例配置和 Windows 运行包已包含该字段；统一 Supervisor 启动仍由 `local-services.yml` 显式覆盖，避免本机三实例配置漂移。 - 未修改数据库、migration、Admin 端口或安全边界。 ### 验证 - `go test ./internal/config/...`：通过。 - `go test ./...`：通过。 - `go vet ./...`：通过。 - Harness 45 项测试与 `check --strict`：通过。 - Wiki `sync --check`：16 个核心镜像一致。 - Portal 前端构建：通过。 - Admin UI 生产构建：通过，仅既有 Sass、codemirror 和包体积 warning。 - Windows ZIP：68 个条目完整性检查通过，包含四个 EXE、Admin UI、migration 11 及带 `server.listen_address` 的 Portal 示例配置。 ### 文档与提交 - Local-Development-and-Verification revision：`50810cebc9b77723c4cbcb467786f12915a09b57` - Deployment-and-Operations revision：`fe7f8d0ca98f6c2fbf137316afe833b7f2c1f629` - 提交：`f354d53 feat: 支持 Portal YAML 配置监听地址 (#74)`，已推送至 `origin/main`。 ### Windows 制品 - 目录：`dist/chorus-windows-amd64-f354d53ba6f6` - ZIP：`dist/chorus-windows-amd64-f354d53ba6f6.zip` - 大小：65,252,356 字节 - SHA-256：`37145484f0670811c116cb26e12316e2ecd6069b62b32d836838c65b8d519ecc` 工单保持开启，状态为“待验收”。

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: OPC/chorus#74