dsh-remote-agent 0.9.3 → 0.9.5

package/lib/index.js

@@ -138,6 +138,31 @@ async function applyWorkerBranch(ctx, config, log) {
   }
 }
 
+/**
+ * 每个"注册宿主"上当前这一代的清理函数。
+ *
+ * 键选 **`ctx.webServer` 服务实例**，不是 `ctx`：
+ * 撞车的是**宿主的路由表**（`webServer.upgrades` 这张 Map）。同一个 ctx 当然
+ * 共用同一张表，但 DSH 热重载时也可能给每代一个新的子 ctx —— 那时按 ctx 记
+ * 就会漏掉，照样撞车。按服务实例记才对应"真正会冲突的那个东西"。
+ *
+ * 读不到 `ctx.webServer`（副机 profile 的 `inject: []` 一读就抛）时退回 ctx，
+ * 这条兜底只是让字典有键，不影响正确性。
+ *
+ * 用 WeakMap：既不阻止 GC，也不会把多个 profile / 多个 host 实例串在一起。
+ */
+const GENERATIONS = new WeakMap()
+
+/** 取"注册宿主"作为字典键。读服务可能抛（无 inject），所以必须 try。 */
+function generationKey(ctx) {
+  try {
+    const ws = ctx && ctx.webServer
+    return ws !== undefined && ws !== null ? ws : ctx
+  } catch {
+    return ctx
+  }
+}
+
 /**
  * DSH 插件入口。
  * @param {object} ctx Cordis 上下文
@@ -166,6 +191,17 @@ export function apply(ctx, config = {}) {
 
   const { role, invalid, unconfigured } = resolveRoleDetail(config)
   const log = loggerOf(ctx)
+
+  // M3（2026-10-20）：独立配置优先，会**压住** loader（patch/插件 UI）里的同名字段。
+  // 这是设计（它才抗得住 DSH 重写），但必须留痕 —— 否则用户"改了 patch 没生效"
+  // 时完全无从判断。只记字段名，不记值（token 等敏感字段不能进日志）。
+  if (Array.isArray(merged.shadowed) && merged.shadowed.length > 0) {
+    log('info', 'instance.json overrides loader config (patch edits ignored for these keys)', {
+      keys: merged.shadowed,
+      fix: '要让 patch 生效，请删掉 instance.json 里对应的键（或用面板改）',
+    })
+  }
+
   // 配置写错必须有反馈。注意**不再回退 hub** —— 那会静默开一个
   // nodeToken 为空、不校验凭证的直连端点（见 resolveRoleDetail 的说明）。
   // 现在当成"未配置"处理：什么都不注册，面板显示引导让用户重选。
@@ -177,6 +213,64 @@ export function apply(ctx, config = {}) {
   }
   const handles = { role, hub: undefined, worker: undefined, unconfigured: unconfigured === true }
 
+  // ══════════════════════════════════════════════════════════════════════════
+  // 可重入：同一个 ctx 上只允许存在**一代**注册（0.9.5 修 duplicate 激活失败）
+  // ══════════════════════════════════════════════════════════════════════════
+  //
+  // 0.9.4 装上后 DSH 报：
+  //
+  //     webserver: duplicate upgrade route "/api/remote-agent/node"
+  //     1 entry did not activate remote-agent (dsh-remote-agent)
+  //
+  // 根因不是"注册了两次"写错，而是**我们的注册不可回收**：
+  //
+  //   · DSH 的 `webServer.registerUpgrade(path)` 是**按 path 查表**的，
+  //     同路径第二次注册直接抛（这是它的组合级契约，合理）：
+  //       if (this.upgrades.has(route.path)) throw new Error('webserver: duplicate upgrade route ...')
+  //   · 我们的注册全部收集在 `__disposers` 里、由 `applyHub()` 的返回值
+  //     `disposeAll` 交给调用方保管 —— 但 **DSH 不认识这个返回值**，
+  //     热重载/安装后 reload 时它只会重新 `apply`，不会回头调我们的 disposer。
+  //   · 于是第二代在第一代的残留上注册 → 撞车 → 整个 entry 激活失败。
+  //
+  // 为什么以前没暴露：只有"同一个 ctx 上重新 apply"才触发。DSH 在
+  // 插件安装/升级后会热重载，这正是用户装 0.9.4 时踩到的那一步。
+  //
+  // 修法：**不指望宿主帮我们清理**。按 ctx 记住上一代的 dispose，重新
+  // apply 时先自己摘干净再装。这样无论宿主是否调用 disposer，都不会重复注册。
+  const genKey = generationKey(ctx)
+  const prevDispose = GENERATIONS.get(genKey)
+  if (typeof prevDispose === 'function') {
+    try {
+      prevDispose()
+      log('info', 're-apply on the same host: previous generation disposed first')
+    } catch (err) {
+      log('warn', 'previous generation dispose failed (continuing)', {
+        error: String(err?.message ?? err),
+      })
+    }
+  }
+
+  let released = false
+  const dispose = () => {
+    if (released) return
+    released = true
+    // 只摘自己：新一代可能已经顶替了这一格，别把它的注册也拆了
+    if (GENERATIONS.get(genKey) === dispose) GENERATIONS.delete(genKey)
+    // 顺序：hub 的路由/监听 → setup 路由 → worker 拨号。
+    // 每一步独立兜底：一个失败不能让后面的漏摘（否则又变成"摘一半"）。
+    try { handles.hub?.disposeAll?.() } catch (err) {
+      log('warn', 'hub dispose failed', { error: String(err?.message ?? err) })
+    }
+    if (Array.isArray(handles.setup)) {
+      for (const d of handles.setup) {
+        try { if (typeof d === 'function') d() } catch { /* 已摘 */ }
+      }
+    }
+    try { if (typeof handles.worker === 'function') handles.worker() } catch { /* 已摘 */ }
+  }
+  GENERATIONS.set(genKey, dispose)
+  handles.dispose = dispose
+
   // ── 未配置：什么都不注册 ────────────────────────────────────────────────
   //
   // 为什么要有这个分支：首次安装时**插件无法知道这台机器是主机还是副机** ——
@@ -241,6 +335,12 @@ export function apply(ctx, config = {}) {
     // 动态 import 是异步的；不 await —— apply 本身是同步契约。
     // 失败已在 applyWorkerBranch 内部记日志，不让 host 因副机缺件而起不来。
     void applyWorkerBranch(ctx, config, log).then((h) => {
+      // 竞态：这一代已经被 dispose（热重载/卸载）了，把刚挂上的 worker 立刻摘掉。
+      // 否则它会留在后台继续拨号 —— 一份回收不掉的僵尸连接。
+      if (released) {
+        try { if (typeof h === 'function') h() } catch { /* 已摘 */ }
+        return
+      }
       handles.worker = h
     })
   }
@@ -326,6 +426,22 @@ export const Config = z.object({
     uiPullRoot: z.string()
       .default('')
       .description('Web 面板拉取产物时唯一允许落地的目录（绝对路径）。留空则面板拉取按钮禁用。'),
+
+    // ── 独立监听（2026-10-18 引入，2026-10-20 补进 schema）───────────────
+    //
+    // ⚠ 这两个字段 0.9.3 就已在用，但**没有在这里声明** —— 靠 schemastery 的
+    // passthrough 才勉强能读到。后果：插件配置页里根本没有这两项（无表单）、
+    // 没有类型校验（`listenPort: "19387"` 会静默回弹默认值）、也无法在 UI 上改。
+    // 现在正式声明：能配、能校验、能在面板/插件页里看到。
+    listenHost: z.string()
+      .default('')
+      .description('独立监听绑定的具体本机 IP（留空=自动选：Tailscale > 私网 > 回环）。'
+        + '不能填 0.0.0.0 —— 通配地址会把服务暴露到所有网卡，且新版 DSH 同规则拒绝。'),
+    // 取值范围由 normalizeConfig 归一（0 <= port < 65536），这里只声明类型与默认值。
+    listenPort: z.number()
+      .default(19387)
+      .description('独立监听端口（副机从这里拨入）。0 = 关闭独立监听，只走 DSH 自己的 Web 服务通道。'),
+
     uiEnabled: z.boolean()
       .default(true)
       .description('是否注册 Web 面板的控制路由。'),

package/lib/instance-config.js

@@ -55,6 +55,11 @@ export const INSTANCE_FILE_NAME = 'instance.json'
  * 为什么不直接存整个 config：config 里可能有 DSH 注入的东西（未知字段会
  * 被 schemastery passthrough 保留），把它们写回磁盘等于把 loader 的中间态
  * 固化下来。只存我们**真正需要跨重启保留**的。
+ *
+ * ⚠ 2026-10-20 补齐（v0.9.3 审查 H2/M2）：此前少了 `listenHost` /
+ * `listenPort` / `relay` —— 于是架构承诺"配置不会再被 DSH 冲掉"，
+ * 而 0.9.3 新增的两个关键字段恰好不在保护范围内，`relay`（跨 NAT 必需）
+ * 更是从来没有落过盘。用户配了它们，一次重启就静默回默认。
  */
 const PERSISTED_KEYS = Object.freeze([
   'role',
@@ -67,8 +72,18 @@ const PERSISTED_KEYS = Object.freeze([
   'uiPullRoot',
   'agentMode',
   'pair',
+  // 0.9.3 独立监听的绑定意图（自动选地址会挑 Tailscale，用户可能想钉死局域网）
+  'listenHost',
+  'listenPort',
+  // hub 侧中继凭证（跨 NAT 场景的唯一通路）
+  'relay',
 ])
 
+/** 值是对象的白名单字段（当前只有 relay：{ url, token }）。 */
+const OBJECT_KEYS = Object.freeze({
+  relay: ['url', 'token'],
+})
+
 /**
  * 解析 stateDir（与 lib/node/index.js 的 resolveStateDir 同口径）。
  * @param {object} [config]
@@ -96,6 +111,55 @@ export function instanceFilePath(config) {
   return path.join(resolveStateDir(config), INSTANCE_FILE_NAME)
 }
 
+/**
+ * 字段级清洗（读与写共用，保证两侧对称）。
+ *
+ * 2026-10-20 扩展：支持 number（listenPort）与白名单对象（relay）。
+ * 早先只接受 string，于是 `listenPort: 19388` 这种合法配置会被静默丢弃。
+ *
+ * @param {Map<string, unknown>} src
+ * @returns {object|null} 清洗后的对象；没有任何有效字段时返回 null
+ */
+function sanitizeFields(src) {
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!src.has(k)) continue
+    const v = src.get(k)
+    if (v === null || v === undefined) continue
+
+    // roots：数组，去空去重前的简单清洗（真正的规范化在 normalizeRoots）
+    if (k === 'roots') {
+      if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
+        if (arr.length > 0) out.roots = arr
+      }
+      continue
+    }
+
+    // relay：{ url, token } —— 只取白名单子键，且至少有一个非空
+    if (OBJECT_KEYS[k]) {
+      if (!v || typeof v !== 'object' || Array.isArray(v)) continue
+      const sub = {}
+      for (const sk of OBJECT_KEYS[k]) {
+        const sv = v[sk]
+        if (typeof sv === 'string' && sv.trim() !== '') sub[sk] = sv.trim()
+      }
+      if (Object.keys(sub).length > 0) out[k] = sub
+      continue
+    }
+
+    // listenPort：数字（0 合法 —— 表示显式关闭独立监听）
+    if (k === 'listenPort') {
+      const n = typeof v === 'number' ? v : (typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v.trim()) : NaN)
+      if (Number.isInteger(n) && n >= 0 && n < 65536) out.listenPort = n
+      continue
+    }
+
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
 /**
  * 读独立配置。
  *
@@ -119,50 +183,22 @@ export function readInstanceConfig(config) {
     return null
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
-  // 字段级清洗（只取白名单，且去掉明显非法值）
-  const out = {}
-  for (const k of PERSISTED_KEYS) {
-    if (!(k in parsed)) continue
-    const v = parsed[k]
-    if (v === null || v === undefined) continue
-    // roots 是数组，单独清洗
-    if (k === 'roots') {
-      if (Array.isArray(v)) {
-        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
-        if (arr.length > 0) out.roots = arr
-      }
-      continue
-    }
-    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
-  }
-  return Object.keys(out).length > 0 ? out : null
+  return sanitizeFields(new Map(Object.entries(parsed)))
 }
 
 /**
  * 写独立配置（原子写 + 0600）。
  *
  * @param {object} values 要写的字段（按白名单过滤）
- * @param {object} [config] 用于解析 stateDir
+ * @param {object} [config] 用于解析 stateDir —— **必须传**，否则写默认目录、
+ *   而读的一方按 `config.stateDir` 找，两边对不上（v0.9.3 审查 M1 的成因）
  * @returns {{ok:boolean, file:string, error?:string}}
  */
 export function writeInstanceConfig(values, config) {
   const dir = resolveStateDir(config)
   const file = path.join(dir, INSTANCE_FILE_NAME)
   const src = values && typeof values === 'object' ? values : {}
-  const out = {}
-  for (const k of PERSISTED_KEYS) {
-    if (!(k in src)) continue
-    const v = src[k]
-    if (v === null || v === undefined) continue
-    if (k === 'roots') {
-      if (Array.isArray(v)) {
-        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
-        if (arr.length > 0) out.roots = arr
-      }
-      continue
-    }
-    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
-  }
+  const out = sanitizeFields(new Map(Object.entries(src))) ?? {}
 
   const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`
   try {
@@ -193,15 +229,33 @@ export function writeInstanceConfig(values, config) {
  *
  * 例外：如果独立配置里**没有**某个字段，就用 loader config 的值。
  *
+ * ⚠ 这个优先级有一个副作用（v0.9.3 审查 M3）：用户手改 `cordis.patch.yml`
+ * 或 DSH 插件 UI 之后，**同名字段永远不生效**，而且没有任何提示 ——
+ * 与项目反复强调的"面板说 A、插件实际做 B 是最难排查的撕裂"同型。
+ * 所以这里把"被覆盖了哪些字段"回报给调用方，由它记日志/在面板展示。
+ *
  * @param {object} loaderConfig
  * @param {object} [opts]
- * @param {boolean} [opts.overlay] 读到的独立配置（避免重复读盘）
- * @returns {{config:object, source:object|null}}
+ * @param {object} [opts.overlay] 读到的独立配置（避免重复读盘）
+ * @returns {{config:object, source:object|null, shadowed:string[]}}
+ *   `shadowed` = 独立配置压住 loader 值的字段名（值本身不回报，避免日志泄密）
  */
 export function mergeInstanceConfig(loaderConfig, { overlay } = {}) {
   const base = loaderConfig && typeof loaderConfig === 'object' ? loaderConfig : {}
   let saved = overlay
   if (saved === undefined) saved = readInstanceConfig(base)
-  if (!saved) return { config: base, source: null }
-  return { config: { ...base, ...saved }, source: saved }
+  if (!saved) return { config: base, source: null, shadowed: [] }
+
+  const shadowed = []
+  for (const k of Object.keys(saved)) {
+    if (!(k in base)) continue // loader 没有 → 不算"覆盖"，是补全
+    const a = base[k]
+    const b = saved[k]
+    // 只在**值真的不同**时记 —— 否则每次启动都刷一堆无意义的"覆盖"
+    const differ = (typeof a === 'object' || typeof b === 'object')
+      ? JSON.stringify(a) !== JSON.stringify(b)
+      : a !== b
+    if (differ) shadowed.push(k)
+  }
+  return { config: { ...base, ...saved }, source: saved, shadowed }
 }

package/lib/listen-server.js

@@ -80,6 +80,30 @@ function isPrivateIp(ip) {
   )
 }
 
+/**
+ * 判定一个主机名/字面量地址是不是回环。
+ *
+ * ⚠ 这是**唯一的**回环判据（2026-10-20 收口）。此前 `lib/env-check.js` 的
+ * `isLoopbackOrigin`、`lib/hub/index.js` 的内联判断、`lib/client.js` 的前端
+ * 判断各写一份 —— 三份判据迟早分叉（C2 就是"两套地址分类"分叉的直接后果）。
+ * 新增调用方一律用这个，别再内联。
+ *
+ * @param {string} host 形如 `127.0.0.1` / `localhost` / `::1` / `[::1]`
+ * @returns {boolean}
+ */
+export function isLoopbackHost(host) {
+  if (typeof host !== 'string') return false
+  const h = host.trim().toLowerCase()
+  return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]'
+}
+
+/** 一个地址的"可信程度"（0 最高）：Tailscale > RFC1918 > 其它。 */
+function scoreOf(address) {
+  if (isTailscaleIp(address)) return 0
+  if (isPrivateIp(address)) return 1
+  return 2
+}
+
 /**
  * 列出本机所有非内网回环的 IPv4（按优先级排序）。
  *
@@ -102,11 +126,15 @@ export function listCandidateAddresses() {
       const address = typeof info.address === 'string' ? info.address : ''
       if (address === '' || address.startsWith('169.254.')) continue // APIPA
       // 优先级：Tailscale(0) > 私网(1) > 其它(2)
-      const score = isTailscaleIp(address) ? 0 : isPrivateIp(address) ? 1 : 2
-      out.push({ address, family, iface, score })
+      out.push({ address, family, iface, score: scoreOf(address) })
     }
   }
-  out.sort((a, b) => a.score - b.score)
+  // 稳定排序（L6，2026-10-20）：同 score 时不能依赖 `os.networkInterfaces()`
+  // 的返回顺序 —— 那是平台相关的，同一台机器两次启动可能不同 → 绑定地址漂移。
+  // 用「接口名 → 地址」做次级键，保证同一台机器每次选出同一个地址。
+  out.sort((a, b) => (a.score - b.score)
+    || String(a.iface).localeCompare(String(b.iface))
+    || String(a.address).localeCompare(String(b.address)))
   return out
 }
 
@@ -159,7 +187,8 @@ export function resolveListenHost({ listenHost, candidates } = {}) {
  * @param {string} o.path WS 升级路径（必须精确匹配）
  * @param {(conn:import('./ws.js').WSConnection, req:import('node:http').IncomingMessage)=>void} o.onUpgrade
  * @param {string} [o.healthPath] 健康检查路径
- * @param {object} [o.healthBody] 健康检查返回体
+ * @param {object|((req:import('node:http').IncomingMessage)=>object)} [o.healthBody]
+ *   健康检查返回体；传函数可按调用者身份分级（匿名只回 `{ ok: true }`）
  * @param {(level:string,msg:string,extra?:object)=>void} [o.log]
  * @returns {Promise<{server:import('node:http').Server, host:string, port:number, close:()=>Promise<void>}>}
  */
@@ -180,8 +209,22 @@ export function startListenServer({
       try {
         const url = new URL(req.url || '/', 'http://localhost')
         if (req.method === 'GET' && url.pathname === healthPath) {
+          // healthBody 可以是对象，也可以是 `(req) => object`。
+          // 后者用于**按调用者身份分级**：匿名只回 `{ ok: true }`，
+          // 带正确口令才给插件名/角色/计数（v0.9.3 审查 L4 —— 这个端点
+          // 本来是无鉴权的，回 "plugin: dsh-remote-agent, role: hub"
+          // 等于给扫描器送指纹）。
+          let payload = healthBody
+          if (typeof healthBody === 'function') {
+            try {
+              payload = healthBody(req)
+            } catch (err) {
+              log('warn', 'health body threw', { error: String(err?.message ?? err) })
+              payload = { ok: false }
+            }
+          }
           res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-          res.end(JSON.stringify(healthBody))
+          res.end(JSON.stringify(payload === undefined ? { ok: true } : payload))
           return
         }
       } catch {
@@ -225,13 +268,29 @@ export function startListenServer({
       }
     })
 
+    // listen 失败要 reject（调用方会 log 并降级）；listen **之后**的错误则
+    // 只能用日志 —— 那个 Promise 早已 resolve，再 reject 是空操作。
+    // 2026-10-20 修（L1）：原实现无条件 reject，导致运行期 socket 错误全被吞掉。
+    let settled = false
+
     server.on('error', (err) => {
       // listen 失败（端口占用 / 地址不可用）要**明确报出来** ——
       // 静默失败会让"副机连不上"变成又一个无头案。
-      reject(err)
+      if (!settled) {
+        settled = true
+        reject(err)
+        return
+      }
+      log('error', 'listen server error (runtime)', {
+        host,
+        port,
+        error: String(err?.message ?? err),
+        code: String(err?.code ?? ''),
+      })
     })
 
     server.listen(port, host, () => {
+      settled = true
       const addr = server.address()
       const actualPort = addr && typeof addr === 'object' ? addr.port : port
       log('info', 'node endpoint listening', { host, port: actualPort, path: upgradePath })

package/lib/setup-routes.js

@@ -31,7 +31,14 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import { ERROR_CODE, RemoteAgentError } from './protocol.js'
-import { writePatchBlock } from './setup.js'
+import {
+  FORM_OWNED_KEYS,
+  extractPreservedConfig,
+  newNodeToken,
+  readManagedBlockBody,
+  upsertTokenInBlock,
+  writePatchBlock,
+} from './setup.js'
 // 角色解析必须**只有一份实现** —— 面板说"未配置"而插件实际在跑 hub，
 // 是最难排查的撕裂（v0.7.0 踩过）。所以这里直接复用 lib/index.js 的解析器。
 import { resolveRoleDetail } from './index.js'
@@ -39,6 +46,16 @@ import { resolveRoleDetail } from './index.js'
 // 所以每次写配置时也在 <stateDir>/instance.json 存一份（插件加载时合并回来）。
 import { writeInstanceConfig, readInstanceConfig } from './instance-config.js'
 
+/**
+ * 面板表单**管辖**的顶层 config 键由 `lib/setup.js` 的 `FORM_OWNED_KEYS` 定义
+ * （CLI 向导与测试共用同一份，避免两处各写一份再分叉 —— 本版审查的 C2/L2
+ * 就是这么来的）。所以这里直接用那份常量，不再本地复制。
+ *
+ * 其余的一切（nodeToken / uiPullRoot / relay / listenHost / listenPort /
+ * agentMode…）在重写托管块时必须**原样保留** —— 否则用户在面板点一次保存，
+ * 凭证与设置就被静默抹掉（已实证）。
+ */
+
 /** 引导路由的前缀。与 hub 的 `/api/remote-agent/ui` 分开 —— 未配置时后者不存在。 */
 export const SETUP_API_PREFIX = '/api/remote-agent/setup'
 
@@ -249,6 +266,10 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
         hubUrl: typeof config.hubUrl === 'string' ? config.hubUrl : '',
         relayUrl: typeof config.relayUrl === 'string' ? config.relayUrl : '',
         roots: Array.isArray(config.roots) ? config.roots : [],
+        // H3（2026-10-20）：面板必须知道"有没有口令"。此前完全不回显 → 用户
+        // 走面板配完 hub 永远是空口令，而独立监听因此只能绑回环、副机连不上。
+        // ⚠ 只回布尔，绝不回 token 本身（与 /config 的披露边界一致）。
+        tokenSet: typeof config.nodeToken === 'string' && config.nodeToken.trim() !== '',
       },
       // 写入目标（让用户知道改的是哪个文件）
       patchFile: currentPatchFile(),
@@ -349,7 +370,28 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
 
     const blockYaml = `${lines.join('\n')}\n`
     const file = currentPatchFile()
-    const result = writePatchBlock({ file, blockYaml, force: body.force === true })
+
+    // ── 保留本次表单不管辖的字段（H2，2026-10-20）────────────────────
+    //
+    // 托管块是**整体替换**的：新块进来，旧块整段消失。而本表单只提交
+    // role/nodeId/transportMode/hubUrl/relayUrl/roots —— 于是用户在面板点一次
+    // 「保存」，托管块里的 nodeToken / uiPullRoot / relay / listenHost /
+    // listenPort 全部被静默删掉（已实证）。
+    //
+    // 这里把旧块里"不归表单管"的行原样搬到新块末尾（文本级搬运，保留用户的
+    // 格式与顺序；不解析 YAML，避免零依赖被打破）。
+    let preservedLines = []
+    try {
+      const existing = readManagedBlockBody(fs.readFileSync(file, 'utf8'))
+      preservedLines = extractPreservedConfig(existing, FORM_OWNED_KEYS)
+    } catch {
+      // 首次写入（文件不存在）—— 没有可保留的
+    }
+    const blockWithPreserved = preservedLines.length > 0
+      ? `${blockYaml.replace(/\s+$/, '')}\n${preservedLines.join('\n')}\n`
+      : blockYaml
+
+    const result = writePatchBlock({ file, blockYaml: blockWithPreserved, force: body.force === true })
     if (result.ok !== true) {
       // 冲突（有手写条目）是可预期的用户可修复状态，单独给个 code 让面板
       // 能显示"替换手写配置"按钮，而不是把整段错误文案丢给用户。
@@ -371,15 +413,24 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     // `<stateDir>/instance.json`。插件 `apply()` 时会把它合并回来
     // （独立配置优先）。这样 DSH 怎么重写 patch 文件都不影响角色配置。
     //
-    // 失败不阻塞：独立配置写不进去时，patch 文件那层仍然生效（只是不抗冲掉）。
+    // ⚠ 2026-10-20 修两处：
+    //   · **必须传 config**（第二个参数）。此前漏了 → 写默认目录、读自定义
+    //     stateDir → 配了 stateDir 的机器持久化完全失效（M1，已复现）。
+    //   · 先铺上已有值再覆盖表单字段，否则每次保存都会把 nodeToken / relay /
+    //     listenHost 这类"表单不管辖"的字段从 instance.json 里抹掉（H2 的另一半）。
+    const prev = readInstanceConfig(config) ?? {}
+    const nextPersist = { ...prev }
+    // 表单管辖的键以本次提交为准（这样"清空"也能真正生效）
+    for (const k of FORM_OWNED_KEYS) delete nextPersist[k]
     const persisted = writeInstanceConfig({
+      ...nextPersist,
       role,
       nodeId: str(body.nodeId),
       transportMode: str(body.transportMode) || undefined,
       hubUrl: str(body.hubUrl) || undefined,
       relayUrl: str(body.relayUrl) || undefined,
       roots,
-    })
+    }, config)
     if (persisted.ok !== true) {
       applyWarnings.push(`独立配置写入失败（${persisted.error}）—— 角色配置仍写进了 patch 文件，`
         + '但下次 DSH 重写该文件时可能丢失，建议重启后到面板确认一次。')
@@ -403,5 +454,90 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     })
   })
 
+  // ── 生成 / 轮换入网口令（nodeToken）──────────────────────────────
+  //
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 为什么必须有这条（v0.9.3 审查 H3，2026-10-20）
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // CLI 向导（`dsh-remote-setup --role hub`）会生成 `nt_` 开头的口令，
+  // **面板这条路却完全没有** —— YAML 里不写 nodeToken、instance.json 里也不写。
+  //
+  // 后果链（实测）：
+  //   面板配 hub → nodeToken 空 → 独立监听按安全策略只能绑回环
+  //   → 副机连不上 → 体检报"需要口令" → 而面板没有任何生成入口
+  //   → 用户只能去手改 patch → 被 DSH 重写冲掉 → 死循环
+  //
+  // 安全边界：
+  //   · 只对**回环请求**生成并回显明文（与 pair-info 的 token 披露边界一致）
+  //   · 明文只回这一次，之后任何接口都不再吐 token（`/state` 只给 tokenSet）
+  //   · 走的是同一套 patch 写盘（备份 / 校验 / 回滚）
+  route(`${SETUP_API_PREFIX}/rotate-token`, async (req, res) => {
+    if (req.method !== 'POST') return writeJson(res, 405, { error: 'method' })
+
+    const ra = String(req.socket?.remoteAddress ?? '')
+    const loopback = ra === '127.0.0.1' || ra === '::1' || ra === '::ffff:127.0.0.1'
+    if (!loopback) {
+      return writeJson(res, 403, {
+        error: 'loopback-only',
+        message: '生成口令只能在主机本机打开的面板里操作（避免局域网内其他人拿到凭证）',
+      })
+    }
+
+    const token = newNodeToken()
+    const file = currentPatchFile()
+
+    // 只改 nodeToken 这一行，其余字段（roots / uiPullRoot / relay / listen*）原样不动
+    let blockBody = ''
+    try {
+      blockBody = readManagedBlockBody(fs.readFileSync(file, 'utf8'))
+    } catch {
+      // 还没有 patch 文件：生成一个最小的托管块，role 取当前生效角色
+    }
+    if (blockBody.trim() === '') {
+      const detail = resolveRoleDetail(config)
+      const r = detail.role === 'worker' ? 'worker' : 'hub'
+      const inject = r === 'worker'
+        ? "['tools', 'agentLoop', 'sessions']"
+        : "['webServer', 'tools', 'systemPrompt']"
+      blockBody = `- id: remote-agent\n  name: dsh-remote-agent\n  inject: ${inject}\n  config:\n    role: ${r}\n`
+    }
+
+    const result = writePatchBlock({
+      file,
+      blockYaml: upsertTokenInBlock(blockBody, token),
+      force: false,
+    })
+    if (result.ok !== true) {
+      const conflict = /手写的 remote-agent 条目/.test(String(result.error ?? ''))
+      return writeJson(res, conflict ? 409 : 400, {
+        error: conflict ? 'handwritten-conflict' : 'write-failed',
+        message: result.error,
+        file: result.file,
+      })
+    }
+
+    // instance.json 也存一份（这一层 DSH 冲不掉）—— 同样保留已有字段
+    const prev = readInstanceConfig(config) ?? {}
+    const persisted = writeInstanceConfig({ ...prev, nodeToken: token }, config)
+
+    log('info', 'node token rotated', {
+      file: result.file,
+      instance: persisted.ok === true ? persisted.file : null,
+      instanceError: persisted.ok === true ? undefined : persisted.error,
+    })
+
+    writeJson(res, 200, {
+      ok: true,
+      // 明文只此一次：面板要提示用户"复制保存"，之后不再回显
+      token,
+      file: result.file,
+      backup: result.backup,
+      instanceFile: persisted.ok === true ? persisted.file : null,
+      note: '口令已写入。**重启 DSH 后生效**；副机需要用新口令重新配对。'
+        + '这串口令只显示这一次，请立即复制保存。',
+    })
+  })
+
   return disposers
 }