物联网中的 Node-RED（9·下贰）：AI 协作与多工程拆分方案 · 统一面板升级、风险清单与实施计划

本篇是《AI + Node-RED 协作开发与多工程拆分统一管理方案》拆分后的第 4 篇（共 5 篇）。

• （上）背景、核心概念与总体架构
• （中）第一阶段：Flow 拆分与 AI 协作
• （下壹）第二阶段：多工程拆分
• （下贰）第二阶段：统一面板升级、风险清单与实施计划 ← 本篇
• （终）协作边界、与传统方式对比、FAQ 与检查清单

原文标题：AI + Node-RED 协作开发与多工程拆分统一管理方案

五、第二阶段：多工程拆分与统一面板管理（续）

5.7 统一面板升级（双层）

决策：面板不自己拉起进程，只检测端口存活并提示你手动启动；启动后在该工程内做正向 / 反向同步。等架构跑通稳定后，再考虑让面板 spawn 进程。

第一层：工程管理

• 列出全部工程卡片：名称、端口、状态灯；
• 状态检测：面板后端对每个工程 GET http://127.0.0.1:<port>/flows，返回 200 且是合法 JSON = 运行中（绿）；连接拒绝 = 未启动（灰/红）；
• 每个卡片显示「启动命令」（与现有启动脚本同款，优先用本地 node-red），你复制去命令行起；
• 「进入」按钮跳到第二层；
• 面板自身端口为 <面板端口>（非 Node-RED 实例，只是管理面板；各工程端口才是 Node-RED 端口）。

第二层：工程内同步（复用现有逻辑）

• 沿用现有 sync-panel 的 ⬆热部署 / ⬇反向同步 / 单 tab 卡片 UI，但 API 指向该工程端口；
• 后端按当前选中的工程 key 取 port / dir，调用改造后的 sync_flows.js / _reverse_sync.js。

面板改造（服务端 API 双层版）：

接口	方法	作用
/api/projects	GET	返回注册表全部工程 + 各自存活状态（探活 GET /flows）
/api/p/:key/health	GET	单工程探活
/api/p/:key/tabs	GET	该工程 tab 列表（含本地 YAML 对照）
/api/p/:key/deploy-all	POST	按工程端口全量部署
/api/p/:key/deploy-one	POST	按工程端口单 tab 部署
/api/p/:key/reverse-all	POST	按工程端口全量反向
/api/p/:key/reverse-one	POST	按工程端口单 tab 反向

合并部署逻辑 mergeFlows 继承原版（移除 YAML 已有 id 及其子节点、保留其余），按工程端口作用，单实例内安全。

5.8 风险清单与对策（⚠ 执行必读）

编号	风险	对策
R1	连错端口清空他人实例：sync_flows.js 若 port/key 配错，会向错误实例部署	脚本启动前校验 key 存在；部署前打印「将向 port=X 部署工程 Y，确认？」交互确认；一次性迁移脚本必须 dry-run 预览
R2	config 漏带：部署后节点报 missing config	config 内联随 tab 走，正常不会漏；迁移后逐个实例 GET /flows 检查无 warning 即可
R3	连接数暴涨	已降级：各工程连各自后端、不互通，不存在共享连接竞争；仅需拆分前确认 UI 端口空闲
R4	tab id 跨工程重复：同 id 会串	迁移脚本检查全局 tab id 唯一性，重复则报错停止
R5	反向同步跨工程污染：_reverse_sync.js 全量回写	改造为按工程过滤（见 5.6）
R6	AI 误改 flows.json：铁律	继续有效——AI 只改 projects/<key>/src/tabs/*.yaml，绝不碰 flows.json，部署由你/脚本做
R7	中文路径乱码：命令行删移文件乱码	一律用 Node fs 脚本（path.join + 绝对路径）做文件操作，不用 shell 直接删移
R8	单实例部署时误删全局：原 mergeFlows 移除「非 YAML id」节点	多实例下每个实例节点集本就只含本工程，安全；但 dry-run 必须显示将被移除的 id 清单

5.9 分步实施计划（按步执行，每步可回滚）

每步结束都验证，再进下一步。不一次性全做。

• S1 写注册表：生成 projects/_registry.json（本文 5.4 内容）。→ 回滚：删除文件即可。
• S2 建目录骨架：为每个工程创建 projects/<key>/src/tabs/ + settings.js（含 uiPort + userDir）。→ 回滚：删 projects/ 目录。
• S3 拆分 tab + config：跑 split_to_projects.js，把 tab 与 config 按工程分到各 projects/<key>/src/。先 dry-run 预览清单。→ 回滚：src/tabs/ 原样保留可作对照。
• S4 单工程试点部署：选最简单的一个（仅 1 tab）手动起实例 + 跑 sync_flows.js --project <key>，验证端口能起、tab 正常。→ 回滚：停止该实例即可。
• S5 全工程部署：逐个工程起实例 + 部署，逐个 GET /flows 核对无 warning。
• S6 反向同步验证：在某工程 UI 改一个节点 → Deploy → 跑 _reverse_sync.js --project <key> → 确认只回写该工程 YAML。
• S7 面板双层改造：加工程列表 + 状态探活 + 按工程路由部署/反向。
• S8 文档收尾：更新项目导引文档增补「工程 = 分组」说明；各分项目文档路径核对；本文定稿。