dsh-remote-plugin 0.6.15 → 0.6.17

package/gateway.cjs

@@ -22,6 +22,8 @@
  *   DSH_REMOTE_FS_ROOT       文件传输额外允许根, 默认 ~, 使用系统路径分隔符配置多根
  *   DSH_REMOTE_FS_MAX_UPLOAD 上传字节上限, 默认 2147483648 (2GB)
  *   DSH_REMOTE_WORKBENCH     工作台绑定文件, 默认 ~/.dsh-remote/workbench.json
+ *   DSH_REMOTE_ADVERTISE_HOSTS 额外写入配对二维码的宿主 IP/主机名, 逗号或空白分隔
+ *   DSH_REMOTE_DSH_CONTROL_MODE DSH 生命周期后端: auto/systemd/windows/disabled
  */
 'use strict'
 
@@ -83,6 +85,9 @@ const WORKBENCH_FILE = process.env.DSH_REMOTE_WORKBENCH || path.join(os.homedir(
 const STARTED_AT = Date.now()
 const DSH_SERVICE = String(process.env.DSH_REMOTE_DSH_SERVICE || 'dsh-web').trim()
 const SYSTEMCTL = String(process.env.DSH_REMOTE_SYSTEMCTL || 'systemctl').trim() || 'systemctl'
+const WINDOWS_SC = String(process.env.DSH_REMOTE_WINDOWS_SC || 'sc.exe').trim() || 'sc.exe'
+const DSH_CONTROL_MODE_RAW = String(process.env.DSH_REMOTE_DSH_CONTROL_MODE || 'auto').trim().toLowerCase()
+const DSH_CONTROL_MODE = ['auto', 'systemd', 'windows', 'disabled'].includes(DSH_CONTROL_MODE_RAW) ? DSH_CONTROL_MODE_RAW : 'auto'
 const DSH_CONTROL_TIMEOUT_MS = durationEnv('DSH_REMOTE_DSH_CONTROL_TIMEOUT_MS', 45000, 2000, 5 * 60 * 1000)
 const DSH_CONTROL_POLL_MS = durationEnv('DSH_REMOTE_DSH_CONTROL_POLL_MS', 500, 50, 5000)
 const HTTP_REQUEST_TIMEOUT_MS = durationEnv('GATEWAY_HTTP_REQUEST_TIMEOUT_MS', 15 * 60 * 1000, 0, 24 * 60 * 60 * 1000)
@@ -103,6 +108,52 @@ function gatewayVersion() {
     return '0.0.0'
   }
 }
+
+function validAdvertisedHost(value) {
+  const host = String(value || '').trim()
+  if (!host || host.length > 253 || host === '0.0.0.0' || host === '127.0.0.1') return ''
+  if (!/^[A-Za-z0-9.-]+$/.test(host) || host.startsWith('.') || host.endsWith('.') || host.includes('..')) return ''
+  if (/^\d+(?:\.\d+){3}$/.test(host) && host.split('.').some(part => Number(part) > 255)) return ''
+  const labels = host.split('.')
+  if (labels.some(label => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'))) return ''
+  return host
+}
+
+function configuredAdvertisedHosts() {
+  return [...new Set(String(process.env.DSH_REMOTE_ADVERTISE_HOSTS || '')
+    .split(/[\s,]+/)
+    .map(validAdvertisedHost)
+    .filter(Boolean))]
+}
+
+function containerRuntimeDetected() {
+  if (fs.existsSync('/.dockerenv')) return true
+  try { return /(?:docker|containerd|kubepods|podman|lxc)/i.test(fs.readFileSync('/proc/1/cgroup', 'utf8')) } catch { return false }
+}
+
+function dshControlSupport() {
+  if (DSH_CONTROL_MODE === 'disabled') {
+    return { supported: false, code: 'EXTERNAL_LIFECYCLE', message: '当前 DSH 由 Docker、面板或其他外部平台管理' }
+  }
+  if (process.platform === 'win32') {
+    if (DSH_CONTROL_MODE === 'systemd') return { supported: false, code: 'CONTROL_MODE_MISMATCH', message: 'Windows 环境不能使用 systemd 控制 DSH' }
+    return { supported: true, manager: 'windows' }
+  }
+  if (DSH_CONTROL_MODE === 'windows') return { supported: false, code: 'CONTROL_MODE_MISMATCH', message: '当前系统不能使用 Windows Service 控制 DSH' }
+  if (DSH_CONTROL_MODE === 'systemd' || (process.env.DSH_REMOTE_SYSTEMCTL && SYSTEMCTL !== 'systemctl')) {
+    return { supported: true, manager: 'systemd' }
+  }
+  if (containerRuntimeDetected()) {
+    return { supported: false, code: 'EXTERNAL_LIFECYCLE', message: '当前网关运行在容器中，DSH 生命周期应由 Docker、面板或其他外部平台管理' }
+  }
+  if (!fs.existsSync('/run/systemd/system')) {
+    return { supported: false, code: 'EXTERNAL_LIFECYCLE', message: '当前环境没有 systemd，DSH 可能由 Docker、面板或其他外部平台管理' }
+  }
+  return { supported: true, manager: 'systemd' }
+}
+
+const ADVERTISED_HOSTS = configuredAdvertisedHosts()
+const DSH_CONTROL_SUPPORT = dshControlSupport()
 const VERSION = gatewayVersion()
 const PROTOCOL_VERSION = 1
 const CAPABILITIES = Object.freeze({
@@ -110,7 +161,7 @@ const CAPABILITIES = Object.freeze({
   eventPolling: 1,
   workspaceFiles: 2,
   imagePromptTransport: 1,
-  dshLifecycle: 2,
+  dshLifecycle: DSH_CONTROL_SUPPORT.supported ? 2 : 0,
   centralAnnouncements: 2,
   feedback: 1,
   deviceKeys: 1,
@@ -140,10 +191,16 @@ const MIME = {
 // 所有 /fs/* 路径 resolve 后都必须位于某个根内, 已存在的路径还会用 realpath
 // 复核一次, 防止 ../ 穿越与符号链接逃逸。
 const FS_DEFAULT_ROOT = path.resolve(os.homedir())
+function fsConfiguredRoot(value) {
+  const raw = String(value || '').trim()
+  if (!raw || raw === '~') return raw === '~' ? FS_DEFAULT_ROOT : ''
+  if (/^~[\\/]/.test(raw)) return path.resolve(FS_DEFAULT_ROOT, raw.slice(2))
+  return path.resolve(raw)
+}
 const FS_ROOTS = (process.env.DSH_REMOTE_FS_ROOT || FS_DEFAULT_ROOT)
   .split(path.delimiter)
+  .map(fsConfiguredRoot)
   .filter(Boolean)
-  .map(r => path.resolve(r.trim() === '~' ? FS_DEFAULT_ROOT : r.trim()))
 const FS_WORKSPACE_CACHE_MS = durationEnv('DSH_REMOTE_FS_WORKSPACE_CACHE_MS', 15_000, 1000, 10 * 60_000)
 const FS_MAX_UPLOAD = Number(process.env.DSH_REMOTE_FS_MAX_UPLOAD) || 2 * 1024 * 1024 * 1024
 const FS_UPLOAD_TTL_MS = durationEnv('DSH_REMOTE_FS_UPLOAD_TTL_MS', 24 * 60 * 60 * 1000, 60_000, 7 * 24 * 60 * 60 * 1000)
@@ -158,7 +215,7 @@ function fsRootReals() {
 }
 function fsInsideReal(real) {
   for (const root of [...fsRootReals(), ...fsWorkspaceRootsCache.reals]) {
-    if (real === root || real.startsWith(root + path.sep)) return true
+    if (fsInsideRoot(real, root)) return true
   }
   return false
 }
@@ -840,13 +897,94 @@ function classifySystemctlFailure(result) {
   return { code: 'COMMAND_FAILED', message: 'systemctl 未能接受 DSH 控制命令', detail }
 }
 
-async function dshServiceStatus() {
-  if (process.platform === 'win32') {
-    return { ok: true, supported: false, running: false, service: DSH_SERVICE, code: 'PLATFORM_UNSUPPORTED', message: 'Windows 暂不支持通过 systemd 远程控制 DSH' }
+const WINDOWS_SERVICE_STATE_NAMES = Object.freeze({
+  1: 'STOPPED',
+  2: 'START_PENDING',
+  3: 'STOP_PENDING',
+  4: 'RUNNING',
+  5: 'CONTINUE_PENDING',
+  6: 'PAUSE_PENDING',
+  7: 'PAUSED',
+})
+
+function parseWindowsServiceQuery(output) {
+  const text = String(output || '')
+  const state = /\bSTATE\s*:\s*(\d+)(?:\s+([^\r\n(]+))?/i.exec(text)
+  if (!state) return null
+  const stateCode = Number(state[1])
+  const stateName = WINDOWS_SERVICE_STATE_NAMES[stateCode] || String(state[2] || 'UNKNOWN').trim().split(/\s+/)[0].toUpperCase()
+  const pid = /\bPID\s*:\s*(\d+)/i.exec(text)
+  const pending = [2, 3, 5, 6].includes(stateCode)
+  return {
+    stateCode,
+    stateName,
+    pending,
+    running: stateCode === 4,
+    mainPid: Number(pid?.[1]) || 0,
+  }
+}
+
+function classifyWindowsServiceFailure(result) {
+  const detail = [result?.stderr, result?.stdout, result?.error].filter(Boolean).join(' · ').slice(0, 1000)
+  const code = String(result?.code ?? '')
+  if (result?.timedOut) return { code: 'COMMAND_TIMEOUT', message: 'Windows 服务控制命令超时', detail }
+  if (code === 'ENOENT') return { code: 'SERVICE_CONTROL_NOT_FOUND', message: '系统中找不到 sc.exe', detail }
+  if (code === '1060' || /1060|does not exist|cannot find the file specified|找不到指定的服务/i.test(detail)) {
+    return { code: 'SERVICE_NOT_FOUND', message: `未找到 Windows 服务 ${DSH_SERVICE}`, detail }
+  }
+  if (code === '1058' || /1058|disabled|禁用/i.test(detail)) return { code: 'SERVICE_DISABLED', message: `Windows 服务 ${DSH_SERVICE} 已被禁用`, detail }
+  if (/access is denied|permission denied|not authorized|需要提升|拒绝访问/i.test(detail)) return { code: 'PERMISSION_DENIED', message: '当前用户无权控制 Windows DSH 服务', detail }
+  if (code === 'SERVICE_STOP_TIMEOUT') return { code, message: `Windows 服务 ${DSH_SERVICE} 停止超时`, detail }
+  return { code: 'COMMAND_FAILED', message: 'Windows 服务控制命令失败', detail }
+}
+
+function classifyDshServiceFailure(result) {
+  return process.platform === 'win32' ? classifyWindowsServiceFailure(result) : classifySystemctlFailure(result)
+}
+
+async function windowsServiceStatus() {
+  const r = await execFileResult(WINDOWS_SC, ['queryex', DSH_SERVICE], 5000)
+  if (!r.ok) {
+    const failure = classifyWindowsServiceFailure(r)
+    if (failure.code === 'SERVICE_NOT_FOUND') {
+      return { ok: true, supported: false, running: false, service: DSH_SERVICE, ...failure }
+    }
+    return { ok: false, supported: false, running: false, service: DSH_SERVICE, ...failure }
   }
+  const parsed = parseWindowsServiceQuery([r.stdout, r.stderr].filter(Boolean).join('\n'))
+  if (!parsed) {
+    return {
+      ok: false, supported: false, running: false, service: DSH_SERVICE,
+      code: 'STATUS_PARSE_FAILED', message: '无法解析 Windows DSH 服务状态', detail: r.stdout || r.stderr || 'sc.exe 没有返回 STATE',
+    }
+  }
+  const activeState = parsed.running ? 'active' : parsed.stateCode === 7 ? 'paused' : parsed.pending ? 'activating' : 'inactive'
+  return {
+    ok: true,
+    supported: true,
+    running: parsed.running,
+    service: DSH_SERVICE,
+    state: activeState,
+    loadState: 'loaded',
+    activeState,
+    subState: parsed.stateName.toLowerCase(),
+    unitFileState: 'windows-service',
+    mainPid: parsed.mainPid,
+    result: '',
+    execMainStatus: 0,
+    serviceStateCode: parsed.stateCode,
+    serviceState: parsed.stateName,
+  }
+}
+
+async function dshServiceStatus() {
   if (!/^[A-Za-z0-9_.@-]+$/.test(DSH_SERVICE)) {
     return { ok: false, supported: false, running: false, service: DSH_SERVICE, code: 'INVALID_SERVICE', message: 'DSH_REMOTE_DSH_SERVICE 服务名配置不合法' }
   }
+  if (!DSH_CONTROL_SUPPORT.supported) {
+    return { ok: true, supported: false, running: false, service: DSH_SERVICE, ...DSH_CONTROL_SUPPORT }
+  }
+  if (process.platform === 'win32') return windowsServiceStatus()
   const r = await execFileResult(SYSTEMCTL, [
     '--user', 'show', DSH_SERVICE,
     '--property=Id,LoadState,ActiveState,SubState,UnitFileState,MainPID,Result,ExecMainStatus',
@@ -884,6 +1022,31 @@ async function dshServiceStatus() {
   }
 }
 
+async function executeDshServiceAction(action, initial) {
+  if (process.platform !== 'win32') {
+    return execFileResult(SYSTEMCTL, ['--user', '--no-block', action, DSH_SERVICE], 5000)
+  }
+  if (action === 'restart' && initial?.running) {
+    const stop = await execFileResult(WINDOWS_SC, ['stop', DSH_SERVICE], 5000)
+    if (!stop.ok) {
+      const current = await windowsServiceStatus()
+      if (!current.supported || current.running || current.serviceStateCode !== 1) return stop
+    }
+    let stopped = false
+    const checks = Math.max(1, Math.ceil(DSH_CONTROL_TIMEOUT_MS / Math.max(50, DSH_CONTROL_POLL_MS)))
+    for (let i = 0; i < checks; i++) {
+      const current = await windowsServiceStatus()
+      if (!current.supported) {
+        return { ok: false, code: current.code || 'SERVICE_STATUS_FAILED', error: current.message, stderr: current.detail }
+      }
+      if (current.serviceStateCode === 1) { stopped = true; break }
+      await delay(DSH_CONTROL_POLL_MS)
+    }
+    if (!stopped) return { ok: false, code: 'SERVICE_STOP_TIMEOUT', error: `Windows 服务 ${DSH_SERVICE} 停止超时` }
+  }
+  return execFileResult(WINDOWS_SC, ['start', DSH_SERVICE], 5000)
+}
+
 function delay(ms) {
   return new Promise(resolvePromise => setTimeout(resolvePromise, ms))
 }
@@ -949,7 +1112,8 @@ function reconnectDshEventCollectors() {
 
 async function runDshControlOperation(operation) {
   try {
-    dshOperationStep(operation, 'checking', `正在检查 systemd 用户服务 ${DSH_SERVICE}`)
+    const manager = process.platform === 'win32' ? 'Windows 服务' : 'systemd 用户服务'
+    dshOperationStep(operation, 'checking', `正在检查 ${manager} ${DSH_SERVICE}`)
     const initial = await dshServiceStatus()
     operation.initialStatus = initial
     operation.observed = initial
@@ -964,11 +1128,11 @@ async function runDshControlOperation(operation) {
       return
     }
 
-    dshOperationStep(operation, 'command', `正在向 systemd 提交 DSH ${operation.action === 'start' ? '启动' : '重启'}命令`)
-    const command = await execFileResult(SYSTEMCTL, ['--user', '--no-block', operation.action, DSH_SERVICE], 5000)
+    dshOperationStep(operation, 'command', `正在向 ${manager} 提交 DSH ${operation.action === 'start' ? '启动' : '重启'}命令`)
+    const command = await executeDshServiceAction(operation.action, initial)
     operation.command = { ok: command.ok, code: command.code, signal: command.signal }
     if (!command.ok) {
-      const failure = classifySystemctlFailure(command)
+      const failure = classifyDshServiceFailure(command)
       failDshOperation(operation, failure.code, failure.message, failure.detail, await dshServiceStatus())
       return
     }
@@ -1921,6 +2085,7 @@ function serveAdminApi(req, res, url) {
         port: PORT,
         protocol: { version: PROTOCOL_VERSION },
         capabilities: CAPABILITIES,
+        dshControl: DSH_CONTROL_SUPPORT,
         upstream: { url: UPSTREAM.origin, reachable },
         latest: {
           version: latestState.version,
@@ -2138,8 +2303,19 @@ function fsAuthorized(req, url, res) {
   return true
 }
 
+function fsInsideRootFor(pathApi, abs, root, caseInsensitive = false) {
+  let candidate = pathApi.resolve(String(abs || ''))
+  let boundary = pathApi.resolve(String(root || ''))
+  if (caseInsensitive) {
+    candidate = candidate.toLowerCase()
+    boundary = boundary.toLowerCase()
+  }
+  const relative = pathApi.relative(boundary, candidate)
+  return relative === '' || (relative !== '..' && !relative.startsWith('..' + pathApi.sep) && !pathApi.isAbsolute(relative))
+}
+
 function fsInsideRoot(abs, root) {
-  return abs === root || abs.startsWith(root + path.sep)
+  return fsInsideRootFor(path, abs, root, process.platform === 'win32')
 }
 
 function fsWorkspacePath(value) {
@@ -2184,7 +2360,7 @@ async function fsResolve(input) {
   const raw = String(input ?? '').trim()
   let abs
   if (!raw || raw === '~') abs = FS_ROOTS[0]
-  else if (raw.startsWith('~/')) abs = path.resolve(FS_DEFAULT_ROOT, raw.slice(2))
+  else if (/^~[\\/]/.test(raw)) abs = path.resolve(FS_DEFAULT_ROOT, raw.slice(2))
   else if (path.isAbsolute(raw)) abs = path.resolve(raw)
   else abs = path.resolve(FS_ROOTS[0], raw) // 相对路径按默认根解析
   if (FS_ROOTS.some(root => fsInsideRoot(abs, root))) return { abs }
@@ -2281,6 +2457,7 @@ async function fsList(req, res, url) {
       if (!info.isFile() && !info.isDirectory()) continue
       entries.push({
         name: d.name,
+        path: full,
         type: info.isDirectory() ? 'dir' : 'file',
         size: info.isDirectory() ? 0 : info.size,
         mtimeMs: Math.round(info.mtimeMs)
@@ -2293,7 +2470,13 @@ async function fsList(req, res, url) {
     if (a.type !== b.type) return a.type === 'dir' ? -1 : 1
     return a.name.localeCompare(b.name, 'zh-CN', { numeric: true })
   })
-  fsJson(res, 200, { path: resolved.abs, entries })
+  fsJson(res, 200, {
+    path: resolved.abs,
+    entries,
+    roots: FS_ROOTS,
+    platform: process.platform,
+    separator: path.sep,
+  })
 }
 
 async function fsFile(req, res, url) {
@@ -3204,6 +3387,7 @@ async function serveHealth(req, res, url) {
     version: VERSION,
     protocol: { version: PROTOCOL_VERSION },
     capabilities: CAPABILITIES,
+    dshControl: DSH_CONTROL_SUPPORT,
     pid: process.pid,
     upstream: UPSTREAM.origin,
     upstreamProbe: DSH_HEALTH_PATH,
@@ -3217,12 +3401,12 @@ async function serveHealth(req, res, url) {
 }
 
 function lanAddresses() {
-  const out = []
+  const out = [...ADVERTISED_HOSTS]
   let groups
   try { groups = Object.values(os.networkInterfaces()) } catch { return out }
   for (const infos of groups) {
     for (const info of infos || []) {
-      if (info.family === 'IPv4' && !info.internal) out.push(info.address)
+      if (info.family === 'IPv4' && !info.internal && !out.includes(info.address)) out.push(info.address)
     }
   }
   return out

package/index.mjs

@@ -70,17 +70,34 @@ try {
 let dshListen = { host: '127.0.0.1', port: 3080 }
 
 function lanIPs() {
-  const out = []
+  const out = [...configuredAdvertisedHosts()]
   let groups
   try { groups = Object.values(networkInterfaces()) } catch { return out }
   for (const list of groups) {
     for (const it of list ?? []) {
-      if (it.family === 'IPv4' && !it.internal) out.push(it.address)
+      if (it.family === 'IPv4' && !it.internal && !out.includes(it.address)) out.push(it.address)
     }
   }
   return out
 }
 
+function validAdvertisedHost(value) {
+  const host = String(value || '').trim()
+  if (!host || host.length > 253 || host === '0.0.0.0' || host === '127.0.0.1') return ''
+  if (!/^[A-Za-z0-9.-]+$/.test(host) || host.startsWith('.') || host.endsWith('.') || host.includes('..')) return ''
+  if (/^\d+(?:\.\d+){3}$/.test(host) && host.split('.').some(part => Number(part) > 255)) return ''
+  const labels = host.split('.')
+  if (labels.some(label => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'))) return ''
+  return host
+}
+
+function configuredAdvertisedHosts() {
+  return [...new Set(String(process.env.DSH_REMOTE_ADVERTISE_HOSTS || '')
+    .split(/[\s,]+/)
+    .map(validAdvertisedHost)
+    .filter(Boolean))]
+}
+
 function targetPath(pathname) {
   let rel
   try {
@@ -152,7 +169,7 @@ function runExit(cmd, args) {
 
 const GATEWAY_ENV_KEYS = [
   'TOKEN', 'TOKEN_FILE', 'DSH_REMOTE_TOKEN', 'DSH_REMOTE_DEVICE_KEYS', 'DSH_REMOTE_FS_ROOT', 'DSH_REMOTE_FS_WORKSPACE_CACHE_MS', 'DSH_REMOTE_FS_MAX_UPLOAD',
-  'DSH_REMOTE_NOTES', 'DSH_REMOTE_WORKBENCH', 'DSH_REMOTE_DSH_SERVICE', 'DSH_REMOTE_SYSTEMCTL',
+  'DSH_REMOTE_NOTES', 'DSH_REMOTE_WORKBENCH', 'DSH_REMOTE_ADVERTISE_HOSTS', 'DSH_REMOTE_DSH_SERVICE', 'DSH_REMOTE_SYSTEMCTL', 'DSH_REMOTE_DSH_CONTROL_MODE',
   'DSH_REMOTE_DSH_CONTROL_TIMEOUT_MS', 'DSH_REMOTE_DSH_CONTROL_POLL_MS', 'DSH_REMOTE_FEEDBACK_URL',
   'UPDATE_CHECK_URL', 'UPDATE_INTERVAL_MS', 'UPDATE_PROXY', 'DSH_HEALTH_PATH',
   'GATEWAY_WS_IDLE_MS', 'GATEWAY_WS_PING_MS', 'GATEWAY_WS_PONG_TIMEOUT_MS',
@@ -552,6 +569,7 @@ async function serveStatic(req, res, ctx) {
         feedback: 0,
         deviceKeys: 0,
       },
+      dshControl: { supported: false, code: 'EXTERNAL_LIFECYCLE', message: '插件内嵌模式不负责管理 DSH 自身进程' },
       deviceKeys: { supported: false, enabled: false, entries: [] },
       upstream: { url: 'DSH 内嵌(同进程, 无需网关)', reachable: true },
       latest: { version, newer: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-plugin",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "DSH Remote 官方 bundle 插件：DSH 左侧原生边栏入口 + 右侧抽屉内嵌管理控制台；内置网关随 DSH 自动启停(systemd 独立单元)，抽屉直显令牌与设备监控；网关提供 /fs/* 文件传输端点(列表/断点下载/上传)，配合 Android App 远程操控会话/审批/提问/goal 与文件互传(多服务器测速切换、聊天记录离线缓存)。",
   "type": "module",
   "main": "./index.mjs",

package/public/admin.html

@@ -108,6 +108,30 @@
     .gateway-port-row input { width: 92px; background: var(--dsr-bg); color: var(--dsr-text); border: 1px solid var(--dsr-line); border-radius: 8px; padding: 6px 8px; font: inherit; font-size: 13px; outline: none; }
     .gateway-port-row .muted { font-size: 12px; }
     .gateway-port-row .mini-btn { margin-left: auto; }
+    .host-ip-card { margin: 0 0 14px; padding: 18px; background: var(--dsr-panel); border: 1px solid var(--dsr-line); border-radius: var(--dsr-radius); }
+    .host-ip-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; }
+    .host-ip-title { font-size: 16px; font-weight: 750; }
+    .host-ip-head .muted { margin-top: 4px; font-size: 12px; }
+    .host-ip-badge { flex: none; padding: 5px 9px; border: 1px solid var(--dsr-accent-line); border-radius: 999px; color: var(--dsr-accent-strong); background: var(--dsr-accent-soft); font-size: 11px; font-weight: 700; }
+    .host-ip-head-actions { display: flex; align-items: center; justify-content: flex-end; gap: 8px; flex-wrap: wrap; }
+    .host-ip-remove { margin-left: 8px; padding: 3px 7px; }
+    .host-ip-desc { margin: 12px 0; color: var(--dsr-muted); font-size: 12px; line-height: 1.55; }
+    .host-ip-table-wrap { overflow: hidden; border: 1px solid var(--dsr-line); border-radius: 13px; }
+    .host-ip-table { width: 100%; border-collapse: collapse; }
+    .host-ip-table th, .host-ip-table td { padding: 10px 12px; border-bottom: 1px solid var(--dsr-divider); text-align: left; font-size: 12px; }
+    .host-ip-table th { color: var(--dsr-muted); background: var(--dsr-bg-2); font-size: 11px; font-weight: 750; }
+    .host-ip-table tr:last-child td { border-bottom: none; }
+    .host-ip-toggle { width: 74px; }
+    .host-ip-value { font-size: 13px !important; }
+    .host-ip-use { color: var(--dsr-muted); }
+    .host-ip-switch { position: relative; display: inline-block; width: 38px; height: 22px; vertical-align: middle; }
+    .host-ip-switch input { position: absolute; width: 1px; height: 1px; opacity: 0; }
+    .host-ip-switch span { position: absolute; inset: 0; border: 1px solid var(--dsr-line); border-radius: 999px; background: var(--dsr-bg-2); cursor: pointer; transition: .18s ease; }
+    .host-ip-switch span::after { content: ''; position: absolute; width: 16px; height: 16px; left: 2px; top: 2px; border-radius: 50%; background: var(--dsr-muted); transition: .18s ease; }
+    .host-ip-switch input:checked + span { border-color: var(--dsr-accent-line); background: var(--dsr-accent-soft); }
+    .host-ip-switch input:checked + span::after { transform: translateX(16px); background: var(--dsr-accent-strong); }
+    .host-ip-switch input:focus-visible + span { outline: 2px solid var(--dsr-accent-strong); outline-offset: 2px; }
+    .host-ip-empty { padding: 18px; color: var(--dsr-muted); text-align: center; font-size: 12px; }
     .conn-badge { white-space: nowrap; }
     #btn-close-drawer { white-space: nowrap; }
     @media (max-width: 720px) {
@@ -220,7 +244,7 @@
     .tb-btn { border-radius: 11px; background: linear-gradient(135deg, var(--dsr-panel-2), var(--dsr-bg-2)); border-color: var(--dsr-line); transition: transform .18s ease, border-color .18s ease, background .18s ease; }
     .tb-btn:hover { transform: translateY(-1px); border-color: var(--dsr-accent-line); background: var(--dsr-accent-soft); }
     .tb-btn svg { width: 17px; height: 17px; }
-    .login-card, .stat-card, .stats-chart, .table-wrap, .gateway-port-row, .pair-box { background: linear-gradient(145deg, var(--dsr-panel), var(--dsr-bg-2)); border-color: var(--dsr-line); border-radius: 18px; box-shadow: 0 12px 30px var(--dsr-shadow); }
+    .login-card, .stat-card, .stats-chart, .table-wrap, .gateway-port-row, .host-ip-card, .pair-box { background: linear-gradient(145deg, var(--dsr-panel), var(--dsr-bg-2)); border-color: var(--dsr-line); border-radius: 18px; box-shadow: 0 12px 30px var(--dsr-shadow); }
     .login-card { padding: 18px; }
     .stat-grid { gap: 12px; }
     .stat-card { padding: 15px 16px; box-shadow: inset 0 1px var(--dsr-divider), 0 10px 26px var(--dsr-shadow); }
@@ -293,6 +317,9 @@
       .token-row { display: flex; flex-direction: column; align-items: stretch; }
       .token-actions { justify-content: stretch; }
       .token-actions .mini-btn { flex: 1 1 auto; }
+      .host-ip-card { padding: 15px; }
+      .host-ip-table-wrap { overflow-x: auto; }
+      .host-ip-table { min-width: 360px; }
       .device-key-toggle { align-items:flex-start; }
       .device-key-toggle-actions { align-items:flex-end; flex-direction:column-reverse; }
       .device-key-grid.head { display:none; }
@@ -434,6 +461,27 @@
         <button id="btn-save-port" class="mini-btn" data-i18n="savePort">保存</button>
       </div>
 
+      <section id="host-ip-card" class="host-ip-card" aria-live="polite">
+        <div class="host-ip-head">
+          <div>
+            <div class="host-ip-title" data-i18n="hostIPs.title">主机 IP 地址</div>
+            <div id="host-ip-summary" class="muted" data-i18n="hostIPs.loading">正在读取主机地址…</div>
+          </div>
+          <div class="host-ip-head-actions">
+            <button id="btn-host-ip-add" class="mini-btn" type="button" data-i18n="hostIPs.add">添加宿主地址</button>
+            <div class="host-ip-badge" data-i18n="hostIPs.badge">手机连接候选</div>
+          </div>
+        </div>
+        <div class="host-ip-desc" data-i18n="hostIPs.desc">关闭虚拟机、容器或其他无效地址后，它们不会再写入配对二维码，也不会作为诊断和防火墙建议地址。</div>
+        <div class="host-ip-table-wrap">
+          <table class="host-ip-table">
+            <thead><tr><th data-i18n="hostIPs.enabledColumn">启用</th><th data-i18n="hostIPs.addressColumn">主机 IP</th><th data-i18n="hostIPs.statusColumn">状态</th></tr></thead>
+            <tbody id="host-ip-rows"></tbody>
+          </table>
+          <div id="host-ip-empty" class="host-ip-empty hidden" data-i18n="hostIPs.empty">暂无可用的非回环地址</div>
+        </div>
+      </section>
+
       <div id="pair-box" class="pair-box hidden">
         <div class="pair-title" data-i18n="pairTitle">手机 App 扫码配对</div>
         <div class="pair-qr" id="pair-qr"></div>
@@ -558,12 +606,13 @@
         'badge.embedded': '内嵌', 'badge.gateway': '网关', 'badge.connected': '已连接',
         'badge.gateway.title': '新标签页打开网关管理面板', 'badge.gatewayDown': '网关未运行',
         'token.pluginNoGateway': '插件模式 · 未接网关, 无需令牌', 'token.unavailable': '未获取到令牌',
-        'toast.tokenInvalid': '令牌无效', 'toast.connFailed': '连接失败',
+        'toast.tokenInvalid': '令牌无效', 'toast.connFailed': '连接失败', 'toast.authLayer': '登录代理拦截了管理 API，请检查 /remote/* 的认证规则',
         'stat.pluginVersion': '插件版本', 'stat.gatewayVersion': '网关版本',
         'stat.updateAvailable': '{version} 可用', 'stat.currentV': '当前 v{version}',
         'stat.download': '去下载', 'stat.embedded': 'DSH 内嵌 · 免网关',
         'stat.updateCheck': '更新检查: {error}', 'stat.latest': '已是最新(来源检查)', 'stat.notChecked': '未检查更新',
         'stat.hostIP': '主机 IP · {hostname}', 'stat.ipSep': '、', 'stat.phoneGateway': ' (手机连 {port} 网关)', 'stat.phoneThis': ' (手机连这个地址)',
+        'hostIPs.title': '主机 IP 地址', 'hostIPs.badge': '手机连接候选', 'hostIPs.loading': '正在读取主机地址…', 'hostIPs.summary': '已启用 {enabled}/{total} 个地址', 'hostIPs.desc': '关闭虚拟机、容器或其他无效地址后，它们不会再写入配对二维码，也不会作为诊断和防火墙建议地址。Docker 中可手动添加宿主地址。', 'hostIPs.enabledColumn': '启用', 'hostIPs.addressColumn': '主机 IP', 'hostIPs.statusColumn': '状态', 'hostIPs.enabled': '已启用 · 会用于配对', 'hostIPs.disabled': '已关闭 · 不用于配对', 'hostIPs.enable': '切换此地址', 'hostIPs.empty': '暂无可用的非回环地址', 'hostIPs.keepOne': '至少保留一个可用地址', 'hostIPs.add': '添加宿主地址', 'hostIPs.addPrompt': '输入手机可访问的宿主 IP 或主机名：', 'hostIPs.invalid': '地址格式无效', 'hostIPs.exists': '该地址已在列表中', 'hostIPs.remove': '删除',
         'stat.reachable': '可达', 'stat.unreachable': '不可达', 'stat.dshUpstream': 'DSH 上游 {url}',
         'stat.devicesOnline': '设备在线 / 累计', 'stat.totalRequests': '总请求数', 'stat.authFailures': '认证失败',
         'stat.uptime': '运行时长 · {host}:{port}',
@@ -667,12 +716,13 @@
         'badge.embedded': 'Embedded', 'badge.gateway': 'Gateway', 'badge.connected': 'Connected',
         'badge.gateway.title': 'Open gateway admin in a new tab', 'badge.gatewayDown': 'Gateway not running',
         'token.pluginNoGateway': 'Plugin mode · no gateway, no token needed', 'token.unavailable': 'Token unavailable',
-        'toast.tokenInvalid': 'Invalid token', 'toast.connFailed': 'Connection failed',
+        'toast.tokenInvalid': 'Invalid token', 'toast.connFailed': 'Connection failed', 'toast.authLayer': 'The login proxy blocked the admin API; check authentication rules for /remote/*',
         'stat.pluginVersion': 'Plugin version', 'stat.gatewayVersion': 'Gateway version',
         'stat.updateAvailable': 'v{version} available', 'stat.currentV': 'Current v{version}',
         'stat.download': 'Download', 'stat.embedded': 'Embedded in DSH · no gateway',
         'stat.updateCheck': 'Update check: {error}', 'stat.latest': 'Up to date (source check)', 'stat.notChecked': 'Not checked',
         'stat.hostIP': 'Host IP · {hostname}', 'stat.ipSep': ', ', 'stat.phoneGateway': ' (phone connects to gateway {port})', 'stat.phoneThis': ' (phone connects to this address)',
+        'hostIPs.title': 'Host IP addresses', 'hostIPs.badge': 'Phone connection candidates', 'hostIPs.loading': 'Reading host addresses…', 'hostIPs.summary': '{enabled}/{total} addresses enabled', 'hostIPs.desc': 'Disabled virtual-machine, container, or other invalid addresses are excluded from pairing QR codes, diagnostics, and firewall suggestions. In Docker, add a host address manually.', 'hostIPs.enabledColumn': 'Enabled', 'hostIPs.addressColumn': 'Host IP', 'hostIPs.statusColumn': 'Status', 'hostIPs.enabled': 'Enabled · used for pairing', 'hostIPs.disabled': 'Disabled · excluded from pairing', 'hostIPs.enable': 'Toggle this address', 'hostIPs.empty': 'No usable non-loopback address', 'hostIPs.keepOne': 'Keep at least one usable address enabled', 'hostIPs.add': 'Add host address', 'hostIPs.addPrompt': 'Enter a host IP or hostname reachable by the phone:', 'hostIPs.invalid': 'Invalid address format', 'hostIPs.exists': 'This address is already listed', 'hostIPs.remove': 'Remove',
         'stat.reachable': 'Reachable', 'stat.unreachable': 'Unreachable', 'stat.dshUpstream': 'DSH upstream {url}',
         'stat.devicesOnline': 'Devices online / total', 'stat.totalRequests': 'Total requests', 'stat.authFailures': 'Auth failures',
         'stat.uptime': 'Uptime · {host}:{port}',