Table of Contents

38 统一本地服务启停

背景与目标
最终方案
修改文件
验收结果
测试
遗留问题
相关提交
人工验收

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

38 统一本地服务启停

类型：开发工具 / 启动配置
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2 开发基础设施
状态：已完成
日期：2026-08-24
Gitea 工单：#38
Wiki 页面：Task-38-统一本地服务启停

背景与目标

统一 Windows 本地 Portal、Admin API 和 Admin UI 的 Host/端口入口及启停命令，同时保持 Portal 环境文件和 Admin settings 的敏感配置隔离。

最终方案

config/local-services.yml 只保存 loopback Host、端口和配置文件路径；Portal 默认 8080，Admin API 从 settings.yml 读取 8090，Admin UI 默认 9528。
严格 Go YAML 解析拒绝未知字段、非 loopback Host、无效/重复端口和缺失引用文件，只输出启动所需的脱敏投影。
start-all.bat 按 Portal、Admin API、Admin UI 顺序启动；Admin 编译为受管二进制，Admin UI 直接运行锁定的 Vue CLI，并注入 Admin API 基址。
status-all.bat 区分受管运行、停止和非受管监听；stop-all.bat 只停止 PID 与可执行路径匹配的受管进程。
启动中途失败只回滚本次新启动的组件，不执行 migration、AutoMigrate、seed、bootstrap 或依赖安装。
实施时发现默认 9527 已由无关项目使用，脚本正确拒绝接管并回滚 Admin；为保留现有进程，Chorus 默认端口最小调整为 9528。

修改文件

cmd/chorus-local-config/main.go、internal/localservices/：严格配置解析、脱敏投影和单元测试。
config/local-services.yml：非敏感统一服务配置。
scripts/chorus-all.ps1、scripts/start-all.bat、scripts/status-all.bat、scripts/stop-all.bat：统一进程管理入口。
scripts/chorus-dev.ps1：兼容增加显式 Portal 地址和只停止 Portal 的内部命令。
docs/00-project-profile.md、docs/04-local-development-and-verification.md、docs/10-deployment-and-operations.md：Wiki 生成镜像。

验收结果

验收标准	结果
YAML schema、loopback、端口、路径、未知字段和脱敏输出	通过
三服务按序启动、状态识别和 HTTP 可达	通过
精确停止且不停止非受管监听者	通过
端口冲突拒绝接管并回滚本次新进程	通过
现有 chorus-dev 入口兼容	通过
Wiki、测试、提交和远端证据完整	通过
用户明确验收	通过（2026-08-24）

测试

go build ./...、go vet ./...、go test ./...：通过。
go -C admin build .：通过。
PowerShell AST 解析 chorus-all.ps1、chorus-dev.ps1：通过。
隔离 19527 端口执行 start/status/HTTP/stop：三服务受管，Portal 与 Admin UI 返回 200，停止后原非受管 9527 保持运行。
默认 9527 冲突验证：拒绝接管、Admin 自动回滚、已有 Portal 保持运行。
调整为 9528 后默认 start-all：Portal 8080、Admin API 8090、Admin UI 9528 均为受管运行，三个 HTTP 检查返回 200。
python -m unittest discover -s tests -v：42 项通过。
python dev_scripts/harness.py check --strict、sync --check、git diff --check：通过。
未验证部分：未执行生产部署、反向代理路径改造或真实发布；未运行 migration、seed、账号变更或真实 Provider 请求。

遗留问题

生产单一 Host 仍需独立部署工单验证路径前缀、同源 API 基址、Cookie、CORS、CSP 和 HTTPS；#38 只交付本地统一入口。

人工验收

验收人：用户
验收时间：2026-08-24
结果：#38 验收通过。