feat: 统一管理本地 Portal、Admin API 与 Admin UI 启停 #38

New Issue

2026-08-24T08:57:07+08:00

ila commented

2026-08-24 08:57:07 +08:00

基本信息

类型：开发工具 / 启动配置
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2 开发基础设施
阶段：已完成
提出时间：2026-08-24

原始需求

来源：用户在当前对话确认方案。
脱敏摘要：希望整体管理本地 Host 和端口，并按确认方案提供统一启动、停止和状态脚本；服务安全配置仍各自隔离。

目标

提供不含凭据的 config/local-services.yml 和 Windows 统一启动入口，一次管理 Portal、Admin API、Admin UI；保留 Portal 环境文件与 Admin settings.yml 各自作为敏感配置来源。

已确认方案

config/local-services.yml 只保存 Portal 地址/环境文件路径、Admin settings 路径和 Admin UI 地址，不保存 DSN、JWT、密码、Token 或 Provider Key。
Admin API 的 Host/Port 继续由被引用的 admin/config/settings.yml 决定，避免重复事实源；统一脚本读取并校验后展示脱敏地址。
Portal 的 Host/Port 由统一配置注入 CHORUS_LISTEN_ADDRESS，其他敏感值继续从受保护的环境文件加载。
Admin UI 由统一配置指定开发 Host/Port，并把 API 基址注入为 Admin API 地址；生产静态部署仍由反向代理管理。
增加 start-all.bat、stop-all.bat、status-all.bat 及 PowerShell 实现；只管理自己记录且可执行路径匹配的进程，不执行 migration、AutoMigrate、seed 或账号创建。
使用项目已锁定的 Go YAML 库严格解析配置，不手写 YAML 字符串解析。

非目标

不修改业务接口、数据库、认证、账号、Nginx 生产配置或现有 admin/config/settings.yml；不自动安装依赖，不自动迁移或创建管理员；不把凭据集中到统一配置。

风险与回退

错误端口或 PID 管理可能启动错误进程或误停其他服务。脚本只接受 loopback Host、显式端口、仓库内受控路径，并通过 PID 与可执行路径匹配后管理；回退为删除新增统一入口并继续使用现有分开启动命令。

验收标准

YAML 严格校验 schema、loopback 地址、端口、相对路径和未知字段，输出不包含敏感配置。
start-all 按 Portal → Admin API → Admin UI 启动，失败时给出可定位日志且不执行迁移/seed。
status-all 区分受管运行、停止和端口被非受管进程占用。
stop-all 只停止状态文件记录且路径匹配的进程；不停止未受管监听者。
现有 scripts/chorus-dev.bat 继续兼容。
Go/PowerShell 测试、Harness 严格检查和文档镜像一致性通过。

文档影响

更新 Wiki Project-Profile、Local-Development-and-Verification 与 Deployment-and-Operations，再同步 docs/ 镜像；任务归档仅写 Wiki，不自动导出。无 UI 原型要求，替代证据为本工单技术方案和命令验证。

实施发现与最小调整（2026-08-24）

默认 9527 已被无关项目的非受管开发服务占用。统一脚本按设计拒绝接管并回滚本次新启动的 Admin；为保留用户现有进程，将 Chorus 默认 Admin UI 端口调整为 9528。该变化不改变已确认的可配置端口方案，也不触碰无关进程。

实现、测试与归档证据

提交：0ca3447、dac9bee，均已推送 origin/main。
真实默认状态：Portal 127.0.0.1:8080、Admin API 127.0.0.1:8090、Admin UI 127.0.0.1:9528 均受管运行，HTTP 检查为 200。
根模块 build/vet/test、Admin build、PowerShell AST、三服务启停/回滚、42 项 Harness 测试和 Wiki 一致性均通过。
任务归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-38-%E7%BB%9F%E4%B8%80%E6%9C%AC%E5%9C%B0%E6%9C%8D%E5%8A%A1%E5%90%AF%E5%81%9C.-
在线回读 revision：ee76ca67562fedaf8bf0e713ee0b2e8aa0e83e6f。
未验证：生产反向代理与真实发布；未执行 migration、seed、账号变更或 Provider 请求。
阶段：已完成；用户明确验收前不关闭。

用户验收

用户验收通过（2026-08-24）。
Wiki 归档：Task-38-统一本地服务启停，revision $(System.Collections.Hashtable[38].revision)。
核心 Project Profile revision：8d5cdac0cee22efe667718393466c59255c6dd17。
验收镜像提交：c8f86c5，已推送至 origin/main。

## 基本信息 - 类型：开发工具 / 启动配置 - 所属 Epic：#3 - 所属 MVP / 版本：#35 / MVP-2 开发基础设施 - 阶段：已完成 - 提出时间：2026-08-24 ## 原始需求 - 来源：用户在当前对话确认方案。 - 脱敏摘要：希望整体管理本地 Host 和端口，并按确认方案提供统一启动、停止和状态脚本；服务安全配置仍各自隔离。 ## 目标提供不含凭据的 `config/local-services.yml` 和 Windows 统一启动入口，一次管理 Portal、Admin API、Admin UI；保留 Portal 环境文件与 Admin `settings.yml` 各自作为敏感配置来源。 ## 已确认方案 - `config/local-services.yml` 只保存 Portal 地址/环境文件路径、Admin settings 路径和 Admin UI 地址，不保存 DSN、JWT、密码、Token 或 Provider Key。 - Admin API 的 Host/Port 继续由被引用的 `admin/config/settings.yml` 决定，避免重复事实源；统一脚本读取并校验后展示脱敏地址。 - Portal 的 Host/Port 由统一配置注入 `CHORUS_LISTEN_ADDRESS`，其他敏感值继续从受保护的环境文件加载。 - Admin UI 由统一配置指定开发 Host/Port，并把 API 基址注入为 Admin API 地址；生产静态部署仍由反向代理管理。 - 增加 `start-all.bat`、`stop-all.bat`、`status-all.bat` 及 PowerShell 实现；只管理自己记录且可执行路径匹配的进程，不执行 migration、AutoMigrate、seed 或账号创建。 - 使用项目已锁定的 Go YAML 库严格解析配置，不手写 YAML 字符串解析。 ## 非目标不修改业务接口、数据库、认证、账号、Nginx 生产配置或现有 `admin/config/settings.yml`；不自动安装依赖，不自动迁移或创建管理员；不把凭据集中到统一配置。 ## 风险与回退错误端口或 PID 管理可能启动错误进程或误停其他服务。脚本只接受 loopback Host、显式端口、仓库内受控路径，并通过 PID 与可执行路径匹配后管理；回退为删除新增统一入口并继续使用现有分开启动命令。 ## 验收标准 - [x] YAML 严格校验 schema、loopback 地址、端口、相对路径和未知字段，输出不包含敏感配置。 - [x] `start-all` 按 Portal → Admin API → Admin UI 启动，失败时给出可定位日志且不执行迁移/seed。 - [x] `status-all` 区分受管运行、停止和端口被非受管进程占用。 - [x] `stop-all` 只停止状态文件记录且路径匹配的进程；不停止未受管监听者。 - [x] 现有 `scripts/chorus-dev.bat` 继续兼容。 - [x] Go/PowerShell 测试、Harness 严格检查和文档镜像一致性通过。 ## 文档影响更新 Wiki `Project-Profile`、`Local-Development-and-Verification` 与 `Deployment-and-Operations`，再同步 `docs/` 镜像；任务归档仅写 Wiki，不自动导出。无 UI 原型要求，替代证据为本工单技术方案和命令验证。  ## 实施发现与最小调整（2026-08-24）默认 9527 已被无关项目的非受管开发服务占用。统一脚本按设计拒绝接管并回滚本次新启动的 Admin；为保留用户现有进程，将 Chorus 默认 Admin UI 端口调整为 9528。该变化不改变已确认的可配置端口方案，也不触碰无关进程。  ## 实现、测试与归档证据 - 提交：`0ca3447`、`dac9bee`，均已推送 `origin/main`。 - 真实默认状态：Portal `127.0.0.1:8080`、Admin API `127.0.0.1:8090`、Admin UI `127.0.0.1:9528` 均受管运行，HTTP 检查为 200。 - 根模块 build/vet/test、Admin build、PowerShell AST、三服务启停/回滚、42 项 Harness 测试和 Wiki 一致性均通过。 - 任务归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-38-%E7%BB%9F%E4%B8%80%E6%9C%AC%E5%9C%B0%E6%9C%8D%E5%8A%A1%E5%90%AF%E5%81%9C.- - 在线回读 revision：`ee76ca67562fedaf8bf0e713ee0b2e8aa0e83e6f`。 - 未验证：生产反向代理与真实发布；未执行 migration、seed、账号变更或 Provider 请求。 - 阶段：已完成；用户明确验收前不关闭。 ## 用户验收 - 用户验收通过（2026-08-24）。 - Wiki 归档：Task-38-统一本地服务启停，revision $(System.Collections.Hashtable[38].revision)。 - 核心 Project Profile revision：8d5cdac0cee22efe667718393466c59255c6dd17。 - 验收镜像提交：c8f86c5，已推送至 origin/main。

ila referenced this issue

2026-08-24 08:57:10 +08:00

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

ila referenced this issue

2026-08-24 08:57:12 +08:00

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

ila referenced this issue from a commit

2026-08-24 09:20:50 +08:00

feat: 统一管理本地服务启停 (#38)

ila referenced this issue from a commit

2026-08-24 09:28:11 +08:00

fix: 避免统一本地端口冲突 (#38)