P1: 系统性解决本地多服务端口冲突、404 与无法连接问题

[wochenlong]

背景

端口冲突已经成为本项目的持续痛点。当前项目同时管理多个本地服务端口：

• 28000：Next Trainer / 训练主页面 WebUI
• 6008：lora-scripts-next 原创训练监控页
• 6006：秋叶包原有 TensorBoard 默认端口
• 28001：Dataset Tag Editor 默认端口

这些服务都影响训练体验。只要用户本机某个端口被占用，或者某个服务错误地连接到另一个服务端口，就可能出现页面跳错、404、无法连接、训练监控离线、TensorBoard 抢占训练监控端口等问题。

痛点

最近版本已经多次遇到相关问题：

• 训练监控入口跳到 TensorBoard，而不是训练监控页。
• TensorBoard fallback 时占用了训练监控默认端口。
• 训练监控页错误连接到 6006 的 GUI API，返回 HTTP Error 404: Not Found。
• 主页面、训练监控页、TensorBoard、Dataset Editor 之间的链接和代理逻辑容易被硬编码端口污染。
• 整合包和源码启动路径都可能受到旧环境变量、旧进程、端口占用或启动顺序影响。

这些问题虽然可以逐个热修，但根因是端口管理没有形成统一、可验证、可扩展的架构。

期望目标

希望有能力的团队成员或社区贡献者帮助项目彻底解决端口冲突、端口 404、端口无法连接的问题。建议方向包括但不限于：

• 建立统一的本地服务注册表或端口分配器，集中管理 WebUI、训练监控、TensorBoard、Dataset Editor 等服务。
• 所有子服务支持动态端口，并由主进程统一分配、记录、传递和展示。
• 前端不直接硬编码子服务端口，而通过稳定后端入口或代理访问。
• 训练监控、TensorBoard、Dataset Editor 等入口应能识别实际运行端口，并在端口变更后仍可访问。
• 子服务启动失败、端口被占用、连接到错误服务时，应给出明确诊断，而不是泛化为“无法连接”或误报固定端口。
• 增加自动化验证，覆盖默认端口被占用、TensorBoard 抢占、训练监控 fallback、源码启动和整合包启动等场景。

补充：AutoDL / 云端 / 受限环境

项目也会部署在 AutoDL 云端或其他受限运行环境中，这些环境的端口情况和本地桌面环境不同：

• 平台可能只开放指定端口，或要求从某个固定外部端口映射到内部服务。
• 用户可能无法随意占用 28000、6006、6008、28001 等默认端口。
• 多服务同时运行时，端口映射、反向代理、隧道访问和安全策略都会影响访问方式。

因此，端口治理方案不应只做“自动 fallback”，还应该保证每个内嵌服务端口都有用户可自定义能力。建议至少支持通过命令行参数、环境变量或配置文件显式设置：

• 主 WebUI 端口
• 训练监控页端口
• TensorBoard 端口
• Dataset Editor 端口

并且 UI、文档和启动日志都应展示最终实际使用的端口，方便 AutoDL / 云端用户配置外部访问地址。

建议验收标准

• 当 28000、6006、6008、28001 任一默认端口被占用时，应用仍能自动选择可用端口并正常启动核心训练流程。
• 用户可以显式自定义主 WebUI、训练监控、TensorBoard、Dataset Editor 的端口。
• 主页面训练监控入口始终打开训练监控页，不会打开 TensorBoard。
• TensorBoard 入口始终打开 TensorBoard，不会抢占或伪装成训练监控页。
• 训练监控页能够连接正确的主 WebUI API，不再出现连接 6006 GUI API 这类错误指向。
• 用户无需手动理解多个端口，也能通过主页完成训练、看日志、看 TensorBoard、打开 Dataset Editor。
• 源码启动和整合包启动都通过同一套端口契约验证。

优先级

P1。该问题不是单一 P0 崩溃，但会持续影响用户训练体验和发布稳定性，需要系统性治理。

[wochenlong]

历史复发记录（供后续修复参考）

这类问题不是第一次出现。main 历史里多次出现过 “TensorBoard / 训练监控 / 端口上下文丢失” 的问题，说明这不是某个硬编码的单点缺陷，而是本地多服务端口管理缺少统一契约。

关键记录：

• cfe8d7f：引入训练监控，提到 Train monitor (6008) auto-start 和 TensorBoard disabled by default。这里开始出现训练监控与 TensorBoard 默认端口策略的分歧。
• 05de4fb：又恢复 TensorBoard 默认启动，原因是侧栏 TensorBoard 入口报错。这里开始形成 TensorBoard 和训练监控并存的端口冲突风险。
• c94f83c：修复 GUI fallback port，说明端口回退逻辑之前就被状态或顺序问题影响过。
• 8683b46：训练监控可靠性修复，提交说明里明确写了 avoiding port collisions。这说明端口冲突已经是训练监控的已知风险。
• f783c0b：修复首页硬编码 6008，改成 /train-monitor 按实际 TRAIN_MONITOR_PORT 跳转。这次修复解决了“入口链接写死”的一层问题。
• e446df9：修复嵌入服务默认端口保护，防止 TensorBoard fallback 抢占训练监控默认端口。
• adc4811：修复训练监控连接 GUI API 时继承到错误 MIKAZUKI_PORT 的问题；当错连到 TensorBoard 6006 并返回 404 时，会回退探测主 WebUI API。

近期热修已经做了几层止血：

• 首页训练监控入口从硬编码 http://127.0.0.1:6008 改为 /train-monitor。
• /train-monitor 由主 WebUI 按 TRAIN_MONITOR_PORT 跳转到实际运行端口。
• gui.py 在 fallback 前保护每个已启用服务的默认端口，避免 TensorBoard 抢占训练监控端口。
• 训练监控页连接 GUI API 时会探测候选 API，不再盲信可能污染的 MIKAZUKI_PORT。
• 补充了 .cursor/rules/embedded-service-ports.mdc 和 AGENT_INTERNAL.md 里的内嵌服务端口契约，避免后续 agent 再丢失这段上下文。

但这些仍然是阶段性修补。长期上，还是需要一个统一的本地服务端口架构，将“端口分配、子服务启动、入口跳转、代理访问、状态诊断、用户自定义”统一起来。