feat(config): 配置管道治本——单一 schema + 暴露面收敛 + 一键重启 + 三元组 + 根因错误 + 保存即生效（A–G，含 #80）

[Windsander]

S1 概要

配置管道「治本 + 保存即生效」一轮（A–G，17 文件 +1260/−234，零 core：git diff origin/main..HEAD -- src 为空）。

#80 处理：本轮分支已 merge origin/feat/console-pending-restart（保留其全部提交与断言，未重写历史）。#80 的 8 条 pendingRestart 断言原样保留、只增不弱化；本 PR 合并后可直接关闭 #80（改合本 PR 即覆盖其内容）。

A 单一真源（治本）

packages/mcp/src/config-schema.mjs（纯数据）每字段 {path, kind, spec, default, requiresRestart, exposure, ui, read, effective, reason}，驱动：① POST /admin/api/config 写校验 ② pendingRestart 判定（= #80 的 24 项，逐项对应）③ 三元组「实际值/未生效原因」④ 控制台编辑器元数据（/admin/api/settings.configSchema，控制台不再重复声明字段）⑤ verify:config 矩阵。
防漂移断言（E1）：schema.EDITABLE_PATHS == IA 渲染面 且 schema.STATUS_ONLY_PATHS == IA 只读面（多/少即红）。

B 暴露面收敛（用户拍板：自动的不保留在 GUI）

path	exposure	requiresRestart	写入
network.enabled	editable	是	可写
network.libp2p.listen	editable	是	可写
sync.namespaces	editable	是	可写
joinService.enabled	editable	是	可写
mcp.http.port	editable	是	可写
mcp.http.auth	editable	是	可写
sync.antiEntropy.enabled	editable	是	可写
sync.antiEntropy.intervalMs	editable	是	可写
sync.antiEntropy.jitterRatio	editable	是	可写
sync.snapshotThreshold	editable	是	可写
sync.peerWhitelist	editable	是	可写
sync.policyIssuers	editable	是	可写
semantic.enabled	editable	是	可写
semantic.minScore	editable	是	可写
joinService.bind	editable	是	可写
joinService.port	editable	是	可写
mcp.http.host	editable	是	可写
mcp.http.tls	editable	是	可写
mcp.http.tlsKey	editable	是	可写
mcp.http.tlsCert	editable	是	可写

path	exposure	requiresRestart	写入
network.libp2p.relayServers	status-only	是	可写
sync.autoSync	status-only	是	可写
sync.pushOnWrite	status-only	是	可写
status.lan.discovery	status-only	否	可写
status.relay.role	status-only	否	可写
status.relay.bridge	status-only	否	可写
status.nat.holepunch	status-only	否	可写
status.net.broadcast	status-only	否	可写
status.join.endpoint	status-only	否	可写
status.tls	status-only	否	可写
status.invite.grantTtl	status-only	否	可写

path	exposure	requiresRestart	写入
network.libp2p.relayUnlimited	internal	是	可写
network.libp2p.relayServer	internal	是	可写
network.libp2p.relayPolicy	internal	是	受保护
network.lan.enabled	internal	是	可写
network.lan.autoDial	internal	是	可写
network.lan.defaultFactory	internal	是	可写
network.relayService	internal	是	可写
network.broadcast.mode	internal	是	可写
network.broadcast.ttlMs	internal	是	可写
network.nat.autonat	internal	是	可写
network.nat.dcutr	internal	是	可写
network.endpointStore	internal	是	受保护
network.autoConnect	internal	是	可写
network.peers	internal	是	受保护
sync.pushOnWriteThrottleMs	internal	是	可写
sync.peerNamespacePolicy	internal	是	受保护
sync.syncTimeout	internal	是	可写
sync.syncStatePath	internal	是	受保护
semantic.model	internal	是	受保护
semantic.cacheDir	internal	是	受保护
storagePath	internal	是	受保护
storageAdapter	internal	是	受保护
deviceId	internal	是	受保护
deviceName	internal	是	受保护
identity.mode	internal	是	受保护
encryption.level	internal	是	受保护
encryption.passphraseEnv	internal	是	受保护
mcp.http.tokensFile	internal	是	受保护

• network.libp2p.relayServers：editable → status-only（只读「自动 relay 池」= config seeds ∪ 令牌 hints ∪ 地址簿学习）
• network.libp2p.relayUnlimited：editable → internal（GUI 不渲染；保留历史可写能力 writable:true）
• C5–C7 新项（lan.*/relayService/broadcast.*/nat.*/endpointStore…）→ internal（只入 RUNBOOK §13）
• 敏感 internal（storagePath/deviceId/encryption/tokensFile…）显式 writable:false（H4「敏感字段不可写」不回归）
• 高级面 16 → 14；可编辑 = 常用 6 + 高级 14 = 20

C 一键重启（修正 F-UI-1：mebular service restart 之前不存在）

• packages/service 增 restartPlanFor/restartService：launchd kickstart -k gui/<uid>/<label> · systemd systemctl --user restart mebular-<kind>.service · win32 schtasks /End+/Run；未注册只给手动指引（绝不盲发）；命令可注入
• mebular service restart 接上；设置卡 footer 文案与实际命令一致
• GUI POST /admin/api/restart（memory.admin + CSRF + {confirm:true}）：先返回 202 再分离式触发；前台运行 → 409 + 手动指引（命令 + .bak 路径）；MEBULAR_RESTART_DRY_RUN=1 可注入
• 待重启横幅接「一键重启」按钮

D 三元组（补 #80 的双值）

已配置 X / 实际 Y / **未生效原因**（服务端计算，前端只渲染）：待重启 · 环境变量优先 · join 端口被占 · LAN/回环不可达 · 桥未提供 · 缺证书 · 缺可选依赖 · 热生效 · 已生效。覆盖 editable 20 + status-only 11。

E 启动失败根因化

createJoinServer 抛错 → 启动错误即「joinService.port <p> 被占（bind=…）：改端口（如 0）或释放占用」+ 落 join.error.json`（不再笼统「serve 起不来」）。

F/G verify:config（45 断言全绿）+ 保存即生效

• 保存路径：含 requiresRestart 项 → {restarting:true} 自动重启（防抖 800ms 合并多次保存）；全即时项（MEBULAR_CONFIG_HOT_PATHS）→ {effectiveImmediately:true} 就地生效
• 生效校验：新实例装配完成写 serve-ready.json + 用自身运行时逐字段比对 → 绿「已生效（字段清单）」/红「未按预期生效：<字段>（已配置 X / 实际 Y）」
• 回滚兜底：分离监督进程（apply-supervisor.mjs）等新实例健康（serve-ready 新 pid + 端口连通；MEBULAR_APPLY_TIMEOUT_MS 可调），不健康 → 还原 config.json.bak + 再重启 → status:'rolled-back'（含根因）；pending.rollingBack 标记防回滚实例误写「已生效」；前台 nohup → 手动命令 + .bak 路径
• 自锁防护（G4）：改动命中 mcp.http.auth/host/tls → 未带 {confirm:true} 返回 409 needsConfirmation（不写盘、不重启）
• UI：按钮区分「保存并重启 / 保存」；保存中「正在重启…重连中…」；恢复后绿「已生效」/红「已回滚」；诊断页「最近一次应用结果」

红→绿实证（≥4 A + ≥3 G，各自必红）

#	拆掉什么	变红的断言（原文）
A1	删三元组原因	✗ S4 实际生效：intervalMs=保存值 且原因=已生效（actual=123456）、✗ S6 热路径不进待重启横幅（原因=已声明为热生效）（reason=null）
A2	删 service restart	✕ runServiceCli restart：已注册→0 且输出命令；usage 含 restart
A3	删防漂移断言 + 渲染漂移	✗ B 暴露面收敛：relayServers 退出编辑面…（advanced=15 残留=network.libp2p.relayUnlimited）、✗ IA 不丢项…（editorPaths=21…）
A4	schema 与渲染漂移	✗ schema↔IA 防漂移：editable 集合逐项一致（各 20）（schema=20 ia=21 差异=network.libp2p.relayUnlimited）
G1	拆掉自动重启	✗ S4 保存需重启项 → 200 + restarting:true + restart.mode=service（status=200 mode=foreground）、✗ S4 lastApply=applied 且逐字段生效校验全通过（verify=[]）
G2	拆掉回滚	✗ S7 已回滚：config.json 恢复为备份（joinService.enabled=false）（enabled=true）、✗ S7 回滚后旧配置实例恢复健康（serve-ready = 新 pid）（pid=undefined）
G3	拆掉生效校验	✗ S4 lastApply=applied 且逐字段生效校验全通过（verify=[…:null,…]）

我的复验命令

npm run build && npm run lint          # 0 / 0
npm test                               # 849 passed（119 suites；+4 restart 单测）
npm run verify:config                  # 45/45
npm run verify:console                 # E1 含 #80 8 条 + G 收尾断言
npm run verify:connect / lan / invite / nat
npm run verify:daemon / daemon:cluster
npm run verify:fleet:all               # 163/163
npm run check:docs / surface-parity / cleanliness / deps

手动复验「造启动失败再回滚」：

T=$(mktemp -d) && mkdir -p $T/home && node -e "require('net').createServer().listen(4002,'127.0.0.1')" &
# 另开：把 config.json 的 joinService 设 {enabled:true, bind:'127.0.0.1', port:4002}，
# 以服务方式启动（MEBULAR_SERVICE_KIND + MEBULAR_RESTART_CMD 注入），在设置页「保存并重启」
# → 新实例报 joinService.port 4002 被占 → 监督进程自动回滚 → 红色横幅「新配置未生效（原因：…被占）：已回滚」
# → 诊断页「最近一次应用结果」可查时间/字段/原因/备份路径

断言只增不弱化

• feat(console): 设置页「待重启」提示——暴露“配置已保存但未重启” #80 的 8 条 pendingRestart 断言原样保留（可写入/含刚改的键/file+running/重启元信息/全新实例为空/保存→200/含 joinService.enabled/重启后清空）
• A 轮 E1 断言全部保留，仅 F-C4 文案断言随「单一真源迁移」改查 schema 源（语义等价：文案确实在 schema 里）
• 新增：E1 的 G 收尾块（前台契约/自锁/三元组/暴露面/控制台接线）+ verify:config 45 条 + verify-console-ui 2 条 + jest 4 条

依赖/平台说明

• 零新增依赖（未改 THIRD-PARTY.md / check:deps 通过）
• 平台重启命令三平台齐备（launchd/systemd/schtasks），均可注入测试；Windows 计划任务无 restart → End+Run 退化（已单测）
• 监督进程（apply-supervisor）分离启动（detached+unref），Linux systemd 单元内重启场景若 cgroup 级联杀死监督进程 → 回滚不触发但 .bak 仍在（诊断页给出手动回滚命令）——已记 RUNBOOK §13