docs: 固化 L1 端口冲突退让流程

2026-07-18 04:55:03 +02:00
parent bc82a55323
commit d0ef4d2e4a
3 changed files with 18 additions and 2 deletions
@@ -75,7 +75,15 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web
  - 通过 native auth/access profile 只授权当前调试微服务的 `navId`；
  - 左侧根导航必须存在，但只能显示当前微服务的一个页面入口；
  - 只代理当前微服务 API 路径，禁止为了渲染产品壳层启动其他 HWLAB 后端；
-  - 当前微服务前端、API 和 Worker 使用独立端口与生命周期，不得抢占或停止其他 L1 会话；
+  - 当前微服务前端、API 和 Worker 使用 YAML-first 固定端口与独立生命周期；
+  - YAML 声明的 L1 端口被占用时：
+    - 同一服务的旧 L1 进程只通过项目 CLI 停止或重启；
+    - 其他服务不得停止、复用或接管；
+    - 先用有界监听状态确认一个空闲端口；
+    - 再修改本 L1 服务的 owning YAML 端口并通过 parser/CLI 读取新值；
+    - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 绕过 YAML；
+    - 端口退让后继续启动，并从 YAML 新端口执行 `web-probe native-readiness`；
+  - L1 进程的启动、停止、重启、状态和日志只通过项目 CLI 管理；
  - Vite 必须绑定可访问的 native 端口并保持 HMR，浏览器端 HMR 地址不得写成 `0.0.0.0`。
 - L1 公网调试入口交给用户前必须完成浏览器 readiness 验收：
  - 使用 `bun scripts/cli.ts web-probe native-readiness --node <node> --lane <lane> --profile <profile>` 一次完成验收；