【讨论】端口与路径路由治理：背景、方案、待决事项与 P0 待办

[wochenlong]

补充说明（2026-05-26）

1. 文档来源：docs/design/ports/ 下三份设计文档（接口规范、迁移计划、优先级路线图）由团队成员 @MikumikuDAIFans（Displace_Asher）整理提出，作为技术方案草案供讨论，尚未经团队评审定为最终共识。
2. 讨论定位：本 Discussion 用于对齐端口/路径治理的方向与 P0 范围；采纳、修改或搁置均以团队在此处的结论为准，不代表已承诺按文档全文实施。
3. 项目背景：端口问题只是 lora-scripts-next 当前多项工作之一（训练稳定性、整合包、Anima、数据集/打标、前端体验等并行）。端口 P0 力求改动小、收益大，避免占用整条发版线；其它事项仍按各自 Issue / 里程碑推进，互不阻塞但需维护者协调优先级。

---

问题

lora-scripts-next 同时运行多个本地服务（主 WebUI、TensorBoard、训练监控、Dataset Tag Editor 等），在端口被占用、环境变量残留或前端硬编码子服务端口时，会出现：

• 训练监控入口打开成 TensorBoard，或反之；
• 训练监控误连 6006 的 API，页面报「无法连接 GUI API」但训练数据仍在同步；
• 用户需要记住 28000 / 6006 / 6008 / 28001 等多个端口；
• AutoDL / 云端只映射一个端口时，静默 fallback 导致平台映射失效。

该问题在多个版本迭代中反复出现，需要团队对齐目标架构与 P0 落地顺序，避免各自修补丁再次回归。

---

背景

• 项目从秋叶 lora-scripts 分叉，保留 TensorBoard、Gradio 打标等子服务，并新增 训练监控（默认 6008）。
• 主 WebUI 默认 28000；子服务端口可通过 gui.py 参数与环境变量配置，占用时会 fallback。
• 相关用户反馈与修复记录分散在 Issue / PR / 内部交接中；维护者与 Agent 曾反复因缺少统一契约而改回硬编码端口。
• 团队成员已提交三份设计文档（见下文「现有方案」），建议作为讨论依据，不代表 main 已全部实现。

---

现有方案

A. 仓库内已落地（main，热修 / 部分 P0）

项	说明
默认端口保护	gui.py 为已启用服务预留各自默认端口，减少 TensorBoard 抢占 6008 等
路径入口	主页 / 引导使用 /train-monitor，后端 GET /train-monitor 重定向到实际监控端口
监控 API	train_monitor/server.py 探测 GUI API；失败记 gui_warning，不阻断其它训练数据展示
Cursor 规则	.cursor/rules/embedded-service-ports.mdc 禁止前端硬编码 127.0.0.1:6008 等
设计文档目录	docs/design/ports/（不进 README 用户传送门）

当前用户可见路径（与目标规范尚未完全一致）：/train-monitor、/tensorboard.html、/proxy/tensorboard/ 等。

B. 团队设计文档（目标架构，待分期实现）

文档	内容
port-interface-standard.md	长期规范：单公共入口 + 路径路由（/monitor/、/tensorboard/、/tagger/）、服务注册表、健康检查
port-routing-migration-plan.md	施工计划：改哪些文件、分阶段、PRT 验收矩阵
port-routing-priority-roadmap.md	P0 / P1 / P2 优先级

方向摘要：用户只记一个 public_base_url（默认 http://127.0.0.1:28000），子服务通过路径访问；运行时 .runtime/services.json 为唯一事实来源。

---

需要确定的事项

请维护者 / 贡献者在回复中表态（可用 👍 / 评论编号）：

1. 是否认同「单公共入口 + 路径路由」为终态？ 是否接受过渡期保留 /train-monitor、/proxy/tensorboard/ 等旧路径？
2. P0 是否接受「最小注册表」：先用现有端口（6006/6008/28001）写入 services.json，不强制 P0 内切换到 281xx 内部端口池？
3. 路径命名：P0 是否新增 /monitor/ 作为 /train-monitor 的别名（302），还是 P0 仍只用 /train-monitor？
4. AutoDL 严格模式：用户显式 --port / --gateway-port 且端口被占用时，是否必须失败（禁止静默 fallback）？
5. Tag Editor / Gradio WebSocket：是否同意放入 P0 后半或 P1（技术风险高于端口隔离本身）？
6. TensorBoard /tensorboard/ 反代：是否同意 P1，P0 仅保证 /tensorboard.html 与 proxy 可用？
7. 发布门禁：是否在 P1 引入 rg 扫描用户入口中的 127.0.0.1:6006|6008|28001？
8. 负责人：P0 各子项是否有人认领（可跟帖「认领 P0-x」）？

---

建议确认的优先度（共识草案）

层级	范围	说明
P0	行为正确、少踩坑	端口不串台、链接路径化、监控连对 API、启动日志/清单、AutoDL 严格端口
P1	工程化	完整注册表、健康检查、/tensorboard/ /tagger/ 反代、WS/SSE 测试、文档与 rg 门禁
P2	扩展	插件注册、API 版本、多实例、公网权限、观测与诊断平台

---

P0 待办事项（建议执行顺序：改动小 → 收益大在前）

状态列供跟帖更新：[ ] 未开始，[x] 已完成，[~] 进行中。

ID	状态	事项	说明
P0-1	[x]	各服务默认端口互不抢占	gui.py protected_default_ports；建议补回归单测
P0-2	[x]	主页/引导监控链路径化	/train-monitor，patch 脚本；发布前 rg 扫 :6008
P0-3	[x]	训练监控连主 WebUI API	探测 + gui_warning；可再接注册表
P0-4	[ ]	启动日志打印「访问地址清单」	主站、监控、TB、打标最终 URL
P0-5	[ ]	浏览器自动打开路径入口	打开主站 + /train-monitor，非 :6008
P0-6	[ ]	最小 .runtime/services.json	启动时写入；.runtime/ gitignore
P0-7	[ ]	监控从注册表读 api 地址	替代仅 env 推断
P0-8	[ ]	公共入口 28000 fallback 28001–28020	仅未显式指定端口时
P0-9	[ ]	AutoDL 显式端口占用则失败	避免映射错位
P0-10	[ ]	Tag Editor / proxy 去除硬编码 28001	env 或注册表
P0-11	[ ]	/monitor/ 与 /train-monitor 并存	302 别名，不删旧路径
P0-12	[ ]	/tensorboard/、/tagger/ 全路径反代	建议 P0 后半或 P1
P0-13	[ ]	内部端口迁 281xx 池	建议 P1，非 P0 阻塞项
P0-14	[ ]	PRT-007/008 等验收	先单测 + 手工 checklist

P0 验收（最小集）

• PRT-007：TensorBoard 占用监控候选端口时，/train-monitor（或 /monitor/）不得打开 TB。
• PRT-008：训练监控请求主 WebUI /api，不得访问 6006/api。

---

相关链接

• 设计文档索引：docs/design/ports/README.md
• 用户文档（当前行为）：docs/train-monitor.md、docs/cli-args.md
• 端口痛点 Issue（若已创建请跟帖编号）

---

欢迎在下方随意跟帖：若对「需要确定的事项」有想法、对 P0 表有不同排序或想一起做其中某几项，直接写出来即可；不必按固定格式回复。讨论沉淀后，维护者会把已达成的一致意见整理进 docs/design/ports/README.md（例如「P0 执行顺序」），草案文档也会随结论更新。

[wochenlong]

@MikumikuDAIFans 你好，感谢整理 docs/design/ports/ 下三份端口/路径草案，我们已放进仓库的 docs/design/ports/ 并开了本讨论串（文首补充说明了：目前是方案草案，还不是团队定稿）。

想请你和其他关心这块的同学一起看看：

• 方向是否贴合你当初的设想？有没有需要改或暂缓写的部分？
• 若愿意，可以在上文「需要确定的事项」或 P0 表里随手留言——开放式讨论即可，没有固定回复模板，也不必「认领」任务；只是方便大家对齐接下来先做什么。

端口只是项目里并行的一件事，其它线（训练、整合包、Anima 等）也会继续推进；这里主要是避免再反复踩端口/TB/监控错连的坑。谢谢 🙏

[MikumikuDAIFans]

待确定事项表态

1到6我全部认同，第7项仅作为再P0全部完成之前的临时策略（发布门禁）

执行计划分段

简而言之：注册表先行，唯一外部入口稳定，再逐步内化子服务端口

P0-6 和 P0-7时注册表和端口内化的基石，在P0-7完成之前我们依然使用的是外部端口通信.
P0-7 完成前：训练监控主要靠 env / 探测 / 默认端口推断。
P0-7 完成后：训练监控优先靠注册表通信。
此时基本时间端口可查找可定位

P0-8 和 P0-9完整之后，确保唯一外部端口稳定，然后才开始推进端口内化

P0-10到P0-13都是逐步内化端口的任务，我个人认为延后至P1更好，在我们确保注册表和AutoDL 显式端口占用被失败机制这两项成功之后再去逐个击破注册表里的的端口