dsh-remote-agent 0.9.3 → 0.9.4

package/lib/hub/index.js

@@ -18,7 +18,12 @@ import { ERROR_CODE, PROTOCOL_VERSION } from '../protocol.js'
 import { acceptUpgrade } from '../ws.js'
 // 独立监听端口（2026-10-18）：副机拨入不再依赖 DSH 的 webserver 配置
 // （DSH 每次启动重写 profile patch，会把 webserver 段冲掉）。
-import { DEFAULT_LISTEN_PORT, resolveListenHost, startListenServer } from '../listen-server.js'
+import {
+  DEFAULT_LISTEN_PORT,
+  isLoopbackHost,
+  resolveListenHost,
+  startListenServer,
+} from '../listen-server.js'
 import { NodeRegistry } from './node-registry.js'
 import { RelayLink } from './relay-link.js'
 import { createPluginLogger } from './hub-util.js'
@@ -303,47 +308,106 @@ export function applyHub(ctx, config = {}) {
   //
   // ⚠ 自检本身**绝不能**让 hub 起不来：`getOrigin()` 在 listen 之前会抛，
   // 服务缺失时也不存在。整段包 try/catch，拿不到就记 `unknown`。
-  let reachability = { bound: null, origin: null, loopback: null, hint: '' }
-  try {
-    const ws = ctx.webServer
-    const origin = typeof ws?.getOrigin === 'function' ? ws.getOrigin() : null
-    if (typeof origin === 'string' && origin !== '') {
-      let hostname = null
-      try {
-        hostname = new URL(origin).hostname
-      } catch {
-        /* 非 URL 形态：保持 null */
+  //
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 2026-10-20 重写：旧结论只反映 webServer，会**假红**（0.9.3 起独立监听才是主通道）
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // 0.9.3 把节点端点搬到独立监听（默认 19387）后，这段自检没跟着改，结果是：
+  // 副机明明能连（19387 在听），面板却因为 DSH 的 webserver 绑 127.0.0.1 而
+  // 报「副机用任何地址都连不上」，并把用户引向一个已被证伪的修法（改 webserver）。
+  //
+  // 现在拆成两层：
+  //   · `webServerReach` —— 旧通道的结论（保留给"独立监听没起来"的降级场景）
+  //   · `currentReachability()` —— **对外唯一入口**：独立监听优先，实时读取
+  //
+  // 为什么是函数而不是快照：独立监听是异步启动的（Promise），注册 ui-routes 时
+  // 往往还没结果。传快照会让面板永远显示启动瞬间的状态。
+  const listenRuntime = {
+    ok: null, // null=未出结果 / true=在听 / false=失败
+    disabled: '', // 非空 = 显式关闭的原因（listenPort:0 / 测试环境 / token 空）
+    host: '',
+    port: 0,
+    source: '',
+    error: '',
+  }
+
+  /** 旧通道（DSH webserver）的可达性结论。 */
+  function computeWebServerReachability() {
+    try {
+      const ws = ctx.webServer
+      const origin = typeof ws?.getOrigin === 'function' ? ws.getOrigin() : null
+      if (typeof origin === 'string' && origin !== '') {
+        let hostname = null
+        try {
+          hostname = new URL(origin).hostname
+        } catch {
+          /* 非 URL 形态：保持 null */
+        }
+        const h = typeof hostname === 'string' ? hostname.toLowerCase() : ''
+        const loopback = isLoopbackHost(h)
+        return {
+          bound: hostname,
+          origin,
+          loopback,
+          hint: loopback
+            ? 'DSH 的 Web 服务绑在 loopback。如果下面「独立监听」正常，这不影响副机接入 —— '
+              + '本插件已不再依赖它（2026-10-18 架构变更）。'
+            : '',
+          via: 'webserver',
+        }
       }
-      const h = typeof hostname === 'string' ? hostname.toLowerCase() : ''
-      // IPv6 在 URL.hostname 里带方括号
-      const loopback = h === '127.0.0.1' || h === 'localhost' || h === '[::1]' || h === '::1'
-      reachability = {
-        bound: hostname,
-        origin,
+      return { bound: null, origin: null, loopback: null, hint: 'webServer.getOrigin() 不可用', via: 'webserver' }
+    } catch (err) {
+      // getOrigin() 在 listen 完成前会抛（文档明说）；服务缺失也会抛。
+      log('info', 'reachability self-check unavailable', { error: String(err?.message ?? err) })
+      return {
+        bound: null,
+        origin: null,
+        loopback: null,
+        hint: `webServer 可达性自检失败：${String(err?.message ?? err)}`,
+        via: 'webserver',
+      }
+    }
+  }
+
+  const webServerReach = computeWebServerReachability()
+
+  /**
+   * 对外统一的可达性结论：**独立监听优先**。
+   * @returns {{bound:string|null, origin:string|null, loopback:boolean|null, hint:string, via:string, port?:number}}
+   */
+  function currentReachability() {
+    if (listenRuntime.ok === true && listenRuntime.host !== '') {
+      const loopback = isLoopbackHost(listenRuntime.host)
+      return {
+        bound: listenRuntime.host,
+        origin: `${listenRuntime.host}:${listenRuntime.port}`,
         loopback,
         hint: loopback
-          // ⚠ 不能建议 0.0.0.0（2026-10-18 事故）：新版 dsh-host-webserver 在
-          // schema 校验阶段就拒绝通配地址 → webserver 无法激活 → webServer
-          // 服务缺失 → DSH 启动崩溃。必须绑一个**具体的本机接口地址**。
-          ? 'webServer 绑在 loopback，副机无法接入。在 profile 的 cordis.patch.yml 里把 webserver 的 host 改成一个具体的本机 IP（推荐 Tailscale IP：tailscale ip -4），然后重启 DSH。不能用 0.0.0.0 —— 新版 DSH 会拒绝并启动失败。'
+          ? '独立监听绑在 loopback —— 副机无法接入。原因通常是 nodeToken 为空（安全策略：'
+            + '无口令的端点不暴露到网络）。到面板「副机接入」生成口令后重启 DSH 即可。'
           : '',
+        via: 'listen-server',
+        port: listenRuntime.port,
+        source: listenRuntime.source,
       }
-      if (loopback) {
-        log('warn', 'hub 绑在 loopback：副机将无法接入', {
-          origin,
-          bound: hostname,
-          fix: "把 webserver 的 host 改成具体的本机 IP（如 Tailscale IP），不能用 0.0.0.0",
-        })
-      } else {
-        log('info', 'hub reachable from other hosts', { origin, bound: hostname })
-      }
-    } else {
-      reachability = { bound: null, origin: null, loopback: null, hint: 'webServer.getOrigin() 不可用，无法判断可达性' }
     }
-  } catch (err) {
-    // getOrigin() 在 listen 完成前会抛（文档明说）；服务缺失也会抛。
-    reachability = { bound: null, origin: null, loopback: null, hint: `可达性自检失败：${String(err?.message ?? err)}` }
-    log('info', 'reachability self-check unavailable', { error: String(err?.message ?? err) })
+    // 独立监听没起来（失败/关闭）→ 退回旧通道结论，并把原因带上
+    const reason = listenRuntime.error !== ''
+      ? `独立监听启动失败：${listenRuntime.error}`
+      : (listenRuntime.disabled !== '' ? `独立监听已关闭：${listenRuntime.disabled}` : '')
+    return {
+      ...webServerReach,
+      hint: [reason, webServerReach.hint].filter((s) => s !== '').join(' '),
+    }
+  }
+
+  // 启动期的一条日志（面板读实时值，日志只在启动时说一次）
+  if (webServerReach.loopback === true) {
+    log('info', 'DSH webserver 只绑 loopback（不影响独立监听通道）', {
+      origin: webServerReach.origin,
+    })
   }
 
   const registry = new NodeRegistry({ log, limits: cfg.limits, identity: hubIdentity, audit })
@@ -428,6 +492,41 @@ export function applyHub(ctx, config = {}) {
   // ⚠ 这是**新增的主通道**，不是替换：下面 webServer 的 registerUpgrade 仍然
   // 保留 —— 老配置（webserver 恰好绑对了）的机器继续用那条路径，两条通道
   // 并存不冲突（不同端口/不同 socket）。
+
+  // ── 健康检查响应：按调用者身份分级（v0.9.3 审查 L4）──────────────────
+  //
+  // 该端点**无鉴权**，而原实现直接把 `plugin: dsh-remote-agent / role: hub /
+  // protocol` 回给任何人 —— 那是给扫描器送指纹：认出"这台机器装了会执行
+  // 远程命令的插件"正是值得挑的目标。
+  //
+  //   · 匿名（或口令不对） → 只回 `{ ok: true }`
+  //   · 带正确 `x-dsh-token` → 完整信息（healthDetail=false 时不含计数）
+  //
+  // ⚠ 必须定义在**两个使用点之前**：独立监听块在本函数体内同步执行，
+  // 用 `const` 声明的函数在后面会踩 TDZ（`ReferenceError: Cannot access
+  // 'healthPayload' before initialization`）—— 与 0.9.x 那次 H1 同族。
+  // 两条通道（webServer / 独立监听）共用这一份，避免"改一条漏一条"。
+  const healthPayload = (req, via = '') => {
+    const authed = cfg.nodeToken !== '' && safeEqual(req.headers['x-dsh-token'], cfg.nodeToken)
+    if (!authed) return { ok: true }
+    const base = {
+      ok: true,
+      plugin: 'dsh-remote-agent',
+      role: 'hub',
+      protocol: PROTOCOL_VERSION,
+    }
+    if (via !== '') base.via = via
+    if (!cfg.healthDetail) return base
+    const nodes = registry.list()
+    return {
+      ...base,
+      nodes: nodes.length,
+      online: nodes.filter((n) => n.online).length,
+      tasks: registry.listTasks().length,
+      activePulls: pulls.activeCount,
+    }
+  }
+
   let listenHandle
   __reg(() => {
     const listenHost = typeof cfg.listenHost === 'string' ? cfg.listenHost : ''
@@ -450,15 +549,52 @@ export function applyHub(ctx, config = {}) {
     // 显式传非默认 listenPort 时以显式为准（有测试专门验证监听行为时要用）。
     const isUnderTest = typeof process.env.NODE_TEST_CONTEXT === 'string'
       && process.env.NODE_TEST_CONTEXT !== ''
-    const explicitPort = Number.isFinite(cfg.listenPort) && cfg.listenPort !== DEFAULT_LISTEN_PORT
+    // L3（2026-10-20）：原来用"值 != 默认端口"推断"是否显式配置"，
+    // 于是用户显式写 19387 与"没写"无法区分（测试里想显式测 19387 会被跳过）。
+    // 改成看**原始 config 有没有这个键**。
+    const explicitPort = config !== null && typeof config === 'object'
+      && Object.prototype.hasOwnProperty.call(config, 'listenPort')
+      && Number.isFinite(config.listenPort)
+      && config.listenPort !== DEFAULT_LISTEN_PORT
     if (port === 0 || (isUnderTest && !explicitPort)) {
+      listenRuntime.disabled = port === 0 ? 'listenPort: 0' : 'test environment'
       log('info', 'independent listener disabled', {
         reason: port === 0 ? 'listenPort: 0' : 'test environment (pass explicit listenPort to enable)',
       })
       return once(() => {})
     }
 
-    const picked = resolveListenHost({ listenHost })
+    // ── 安全：无口令的端点不暴露到网络（H1，2026-10-20）───────────────
+    //
+    // 0.9.3 把端点从 DSH 的 webserver（默认绑 127.0.0.1）搬到了独立监听，
+    // 而独立监听**主动挑最可达的地址**（Tailscale 优先）。于是"nodeToken 为空"
+    // 从"只有本机能连"变成"整个 tailnet 无口令可连" —— 任何人都能
+    // `attachDirect` 注册成节点、收到派发的任务内容。
+    //
+    // 规则：
+    //   · listenHost 没显式配（自动选）+ token 空 → **强制回环**
+    //     （用户没有表达"要对外"的意图，默认必须安全）
+    //   · listenHost 显式配成非回环 + token 空 → 尊重用户，但明确警告
+    const tokenBlank = cfg.nodeToken === ''
+    const explicitNonLoopback = listenHost !== '' && !isLoopbackHost(listenHost)
+    const forceLoopback = tokenBlank && !explicitNonLoopback
+
+    const picked = forceLoopback
+      ? { host: '127.0.0.1', source: 'loopback-no-token', candidates: [] }
+      : resolveListenHost({ listenHost })
+
+    if (forceLoopback) {
+      log('warn', '独立监听退回 loopback：nodeToken 为空，端点不暴露到网络', {
+        hint: '副机要接入，请先在面板「副机接入」生成口令（nodeToken），再重启 DSH。'
+          + '（0.9.3 之前端点跟 DSH webserver 一起绑 loopback，不存在这个暴露面。）',
+      })
+    } else if (tokenBlank && explicitNonLoopback) {
+      log('warn', 'nodeToken 为空但 listenHost 显式指向非回环地址 —— 端点无口令可连', {
+        host: picked.host,
+        hint: '仅限完全可信网络。建议尽快设置 nodeToken。',
+      })
+    }
+
     let disposed = false
 
     startListenServer({
@@ -466,13 +602,8 @@ export function applyHub(ctx, config = {}) {
       port,
       path: cfg.nodePath,
       healthPath: cfg.healthPath,
-      healthBody: {
-        ok: true,
-        plugin: 'dsh-remote-agent',
-        role: 'hub',
-        protocol: PROTOCOL_VERSION,
-        via: 'listen-server',
-      },
+      // 函数形态：按调用者身份分级（匿名只见 `{ ok: true }`）
+      healthBody: (req) => healthPayload(req, 'listen-server'),
       onUpgrade: (conn, req) => {
         // 与 webServer 那条路完全相同的鉴权与交接逻辑（一处不能少：
         // token 校验是这条通道唯一的口令，跳过就是一个无鉴权入口）。
@@ -499,6 +630,12 @@ export function applyHub(ctx, config = {}) {
           return
         }
         listenHandle = h
+        // 运行时状态：面板的配对码与体检都读它（C1/M4）
+        listenRuntime.ok = true
+        listenRuntime.host = h.host
+        listenRuntime.port = h.port
+        listenRuntime.source = picked.source
+        listenRuntime.error = ''
         log('info', 'node endpoint ready (independent listener)', {
           host: h.host,
           port: h.port,
@@ -510,6 +647,11 @@ export function applyHub(ctx, config = {}) {
         // ⚠ 监听失败不能静默：那会让"副机连不上"变成又一个无头案。
         // 但要**降级而非抛出** —— 本插件不该把整个 DSH 拖垮
         // （webServer 那条通道可能仍然可用）。
+        listenRuntime.ok = false
+        listenRuntime.host = picked.host
+        listenRuntime.port = port
+        listenRuntime.source = picked.source
+        listenRuntime.error = String(err?.message ?? err)
         log('error', 'independent listener failed; falling back to webServer-only', {
           host: picked.host,
           port,
@@ -561,36 +703,16 @@ export function applyHub(ctx, config = {}) {
 
   // ── 健康检查（只读，不含凭证） ─────────────────────────────────
   //
-  // F1-1：该路由无鉴权，暴露的计数可被用来探测"本机在跑多少远程任务"。
-  // 凭证扫描已确认 14 项全 false（无 token/apiKey/绝对路径/hostname/nodeId），
-  // 所以这不是泄漏，只是可被动的存在性探测。
-  // 处置：加 `healthDetail` 配置（默认 true，便于运维自检）；设为 false 时
-  // 只返回 { ok, plugin, role, protocol }，不暴露任何计数。
+  // 响应体由上面定义的 `healthPayload()` 产出（匿名只回 `{ ok: true }`，
+  // 带正确 `x-dsh-token` 才给插件名/角色/计数）。这里只负责注册路由。
   __reg(() => {
     const dispose = ctx.webServer.register({
       kind: 'exact',
       path: cfg.healthPath,
       handler: (req, res) => {
         try {
-          const base = {
-            ok: true,
-            plugin: 'dsh-remote-agent',
-            role: 'hub',
-            protocol: PROTOCOL_VERSION,
-          }
-          let body = base
-          if (cfg.healthDetail) {
-            const nodes = registry.list()
-            body = {
-              ...base,
-              nodes: nodes.length,
-              online: nodes.filter((n) => n.online).length,
-              tasks: registry.listTasks().length,
-              activePulls: pulls.activeCount,
-            }
-          }
           res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
-          res.end(JSON.stringify(body))
+          res.end(JSON.stringify(healthPayload(req)))
         } catch (err) {
           log('warn', 'healthz failed', { error: String(err?.message ?? err) })
           try {
@@ -623,9 +745,16 @@ export function applyHub(ctx, config = {}) {
           // 本行生效配置的只读快照，供面板「主机设置」区展示。
           // 传**原始** config（而非归一化后的 cfg），因为面板要如实反映用户写了什么。
           config,
-          // 可达性自检结论（2026-10-17）：绑 loopback 时副机永远连不上，
-          // 面板要渲染成红色横幅 —— 这个失败在主机侧是完全静默的。
-          reachability,
+          // 可达性：**必须传 getter**（2026-10-20）。
+          // 独立监听是异步启动的，注册路由时它往往还没结果 —— 传快照会让面板
+          // 永远显示启动瞬间的旧结论（0.9.3 的假红就是这么来的）。
+          // 静态的 `reachability` 保留给老调用方/测试，getter 优先。
+          reachability: currentReachability(),
+          getReachability: currentReachability,
+          // 独立监听的实时状态（ok/host/port/source/error/disabled）。
+          // 配对码的端口必须来自这里 —— 浏览器地址栏的端口是 DSH webserver 的，
+          // 与节点端点无关（C1）。
+          listenRuntime,
         }).map(once)
       } catch (err) {
         log('error', 'ui route registration threw', { error: String(err?.message ?? err) })

package/lib/hub/ui-routes.js

@@ -312,11 +312,31 @@ export function registerUiRoutes({
   // 可达性自检结论（2026-10-17）：{ bound, origin, loopback, hint }
   // 绑 loopback 时副机永远连不上，而这个失败在主机侧完全静默 ——
   // 面板必须渲染成红色横幅，否则用户只能去猜"地址填错了？token 错了？"
+  //
+  // ⚠ 2026-10-20：必须用 **getter**，不能用快照。
+  // 独立监听是异步启动的，注册路由的这一刻它通常还没有结果；传快照会让面板
+  // 永远显示启动瞬间的旧结论（0.9.3 的"假红"就是这么产生的）。
   reachability = null,
+  getReachability = null,
+  // 独立监听的实时状态：{ ok, disabled, host, port, source, error }
+  listenRuntime = null,
 }) {
   const disposers = []
   const guard = makeGuard(ctx, log)
 
+  /** 取当前可达性结论：getter 优先，静态快照兜底（兼容老调用方/测试）。 */
+  const reachOf = () => {
+    if (typeof getReachability === 'function') {
+      try {
+        const r = getReachability()
+        if (r) return r
+      } catch {
+        /* 取失败退回快照 */
+      }
+    }
+    return reachability
+  }
+
   // 注册计数：`applyHub` 结束时会打一行日志汇总。
   // 为什么用 log 而不是写文件：上一轮排查用的文件诊断在清理时被删了，
   // 而**路由注册失败是静默致命的**（面板只看到 404，启动日志里什么都没有）。
@@ -440,12 +460,29 @@ export function registerUiRoutes({
         dispatch: true,
         // 可达性自检（2026-10-17）：`loopback === true` 时副机永远连不上，
         // 面板渲染红色横幅。逐字段投影，不 spread。
-        reachability: reachability
+        // 2026-10-20：结论来自 `reachOf()`（独立监听优先），并带上 via/port，
+        // 让面板能说清"是哪条通道在听"。
+        reachability: (() => {
+          const r = reachOf()
+          if (!r) return null
+          return {
+            bound: typeof r.bound === 'string' ? r.bound : null,
+            origin: typeof r.origin === 'string' ? r.origin : null,
+            loopback: r.loopback === true,
+            hint: typeof r.hint === 'string' ? r.hint : '',
+            via: typeof r.via === 'string' ? r.via : 'webserver',
+            port: Number.isFinite(r.port) ? r.port : null,
+          }
+        })(),
+        // 独立监听的原始状态：面板要区分"在听 / 失败 / 关闭"三种情形
+        listener: listenRuntime
           ? {
-            bound: typeof reachability.bound === 'string' ? reachability.bound : null,
-            origin: typeof reachability.origin === 'string' ? reachability.origin : null,
-            loopback: reachability.loopback === true,
-            hint: typeof reachability.hint === 'string' ? reachability.hint : '',
+            ok: listenRuntime.ok,
+            disabled: typeof listenRuntime.disabled === 'string' ? listenRuntime.disabled : '',
+            host: typeof listenRuntime.host === 'string' ? listenRuntime.host : '',
+            port: Number.isFinite(listenRuntime.port) ? listenRuntime.port : null,
+            source: typeof listenRuntime.source === 'string' ? listenRuntime.source : '',
+            error: typeof listenRuntime.error === 'string' ? listenRuntime.error : '',
           }
           : null,
       },
@@ -695,7 +732,19 @@ export function registerUiRoutes({
         // 用 resolveRole 更稳妥（覆盖 both 与显式 hub 两种）。
         role: resolveRole(config) || 'hub',
         config,
-        reachability,
+        // 实时取（独立监听优先），不能再用注册时的快照
+        reachability: reachOf(),
+        // 独立监听的原始状态：体检要能单独报"主通道起没起来"（M4）
+        listener: listenRuntime
+          ? {
+            ok: listenRuntime.ok,
+            disabled: typeof listenRuntime.disabled === 'string' ? listenRuntime.disabled : '',
+            host: typeof listenRuntime.host === 'string' ? listenRuntime.host : '',
+            port: Number.isFinite(listenRuntime.port) ? listenRuntime.port : null,
+            source: typeof listenRuntime.source === 'string' ? listenRuntime.source : '',
+            error: typeof listenRuntime.error === 'string' ? listenRuntime.error : '',
+          }
+          : null,
         nodesOnline: nodes.filter((n) => n.online).length,
       })
     } catch (err) {
@@ -802,48 +851,100 @@ export function registerUiRoutes({
 
   // ── 副机接入：生成配对码（面板 GUI 化的落点）──────────────────
   //
-  // 端口不查内部状态：面板本身就由 hub 的 webserver 服务，浏览器侧把
-  // window.location.port 传回来即是节点拨入端口（节点端点与面板同端口）。
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 2026-10-20 修（C1）：端口**必须**取独立监听的实时状态
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // 原实现：面板传 `window.location.port` 回来，注释写着"节点端点与面板同端口"。
+  // 那个前提在 0.9.3 已被推翻 —— 节点端点搬到了独立监听（默认 19387），
+  // 而 DSH webserver 的端口是**每次启动随机**的（实测见过 56594、58626）。
+  //
+  // 后果：面板生成的每一个配对码都指向"DSH 面板端口 + 节点路径"——
+  // 那个端口既没有节点端点、又绑在 127.0.0.1 → 副机 100% 连不上。
+  // 用户看到的是"配对码贴了没反应"，而两端都没有报错。
+  //
+  // 现在：端口从 `listenRuntime` 取（真实监听成功后的端口）。浏览器传来的
+  // `port` 参数**不再采信**，只作为"独立监听没起来"时的兜底参考。
   //
   // ⚠ token 披露边界（与 /config 的"只回 set 布尔"同一精神）：
   // 含 token 的完整配对码**只对本机回环请求**生成 —— 面板可能被 lanBind
   // 暴露到局域网，局域网内的另一台机器能打开面板 ≠ 应该拿到主机凭证。
-  // 非回环请求得到不含 token 的码（对可信内网直连仍然够用）+ 一条提示。
   route(`${UI_API_PREFIX}/pair-info`, (req, res) => {
     if (req.method !== 'GET') return writeJson(res, 405, { error: 'method' })
     const url = new URL(req.url, 'http://localhost')
-    const portRaw = url.searchParams.get('port') ?? ''
-    const port = /^\d+$/.test(portRaw) && +portRaw > 0 && +portRaw < 65536 ? +portRaw : 19387
     const ra = String(req.socket?.remoteAddress ?? '')
     const loopback = ra === '127.0.0.1' || ra === '::1' || ra === '::ffff:127.0.0.1'
     const tokenSet = typeof config.nodeToken === 'string' && config.nodeToken !== ''
     const token = loopback && tokenSet ? config.nodeToken : ''
-    const codes = detectLanIps()
+
+    // 真实端口：独立监听优先；没起来则退回浏览器端口（老部署），再兜底 19387
+    const portRaw = url.searchParams.get('port') ?? ''
+    const browserPort = /^\d+$/.test(portRaw) && +portRaw > 0 && +portRaw < 65536 ? +portRaw : null
+    const listenOk = listenRuntime && listenRuntime.ok === true
+    const port = listenOk && Number.isFinite(listenRuntime.port) && listenRuntime.port > 0
+      ? listenRuntime.port
+      : (browserPort ?? 19387)
+    const portSource = listenOk && Number.isFinite(listenRuntime.port) ? 'listen-server' : 'fallback'
+
+    // 独立监听在听时，**只有它绑的那个地址**是可用的（新架构只绑一个具体 IP）。
+    // 其余候选地址照旧列出来（老配置可能走 webServer 通道），但明确标 usable，
+    // 免得用户复制了一条连不上的码还以为是自己的问题（C2）。
+    const boundHost = listenOk && typeof listenRuntime.host === 'string' ? listenRuntime.host : ''
+    const candidates = detectLanIps()
+    const codes = candidates
       .map((ip) => {
         const hubUrl = buildHubUrl(ip.address, port)
         const pairCode = encodePairCode({ hubUrl, token })
+        const usable = boundHost === '' ? portSource === 'fallback' : ip.address === boundHost
         return {
           address: ip.address,
           name: ip.name,
           private: ip.private === true,
           hubUrl,
           pairCode,
+          usable,
           includesToken: token !== '' && pairCode !== '',
         }
       })
       .filter((c) => c.pairCode !== '')
+      // 可用的排最前（面板默认展示第一条，用户多半直接复制）
+      .sort((a, b) => Number(b.usable) - Number(a.usable))
+
+    // 独立监听没在听时，给出**可执行**的原因，而不是让用户对着空列表猜
+    const listenerState = !listenRuntime
+      ? 'unknown'
+      : (listenRuntime.ok === true ? 'listening' : (listenRuntime.disabled !== '' ? 'disabled' : 'failed'))
+    const listenerError = listenRuntime && typeof listenRuntime.error === 'string' ? listenRuntime.error : ''
+    const listenerHint = listenerState === 'listening'
+      ? ''
+      : listenRuntime && listenRuntime.disabled !== ''
+        ? `独立监听已关闭（${listenRuntime.disabled}）—— 副机只能走 DSH webserver 通道`
+        : (listenerError !== ''
+          ? `独立监听启动失败：${listenerError}（改 listenPort / listenHost 后重启）`
+          : '独立监听尚未就绪（刚启动？稍后刷新）')
+
     writeJson(res, 200, {
       ok: true,
       port,
+      portSource,
       tokenSet,
       scope: token !== '' ? 'full' : 'tokenless',
       codes,
+      // 面板据此决定是否禁用"生成/复制"并显示原因
+      listener: {
+        state: listenerState,
+        host: boundHost,
+        port: listenOk ? listenRuntime.port : null,
+        source: listenRuntime && typeof listenRuntime.source === 'string' ? listenRuntime.source : '',
+        error: listenerError,
+        hint: listenerHint,
+      },
       firewallHint: `netsh advfirewall firewall add rule name="dsh-remote-agent" dir=in action=allow protocol=TCP localport=${port}`,
       note: token !== ''
         ? ''
         : (tokenSet
           ? '当前不是从主机本机打开的面板 —— 配对码不含 token；完整版请在主机本机打开面板生成，或用 dsh-remote-setup 向导'
-          : '主机未设置 nodeToken —— 配对码不含 token，仅限完全可信内网；公网部署前必须先设置'),
+          : '主机未设置 nodeToken —— 无口令的端点不会暴露到网络（安全策略），副机连不上。请先生成口令。'),
     })
   })
 

package/lib/index.js

@@ -166,6 +166,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 的说明）。
   // 现在当成"未配置"处理：什么都不注册，面板显示引导让用户重选。
@@ -326,6 +337,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 面板的控制路由。'),