@feiyang666/dsh-mobile-remote 1.1.0 → 1.4.1

package/lib/index.js

@@ -24,11 +24,25 @@
 //   不 import 任何 dsh-client / dsh-host 内部包，仅使用 Node 内置模块与
 //   webServer 服务公开的 tapIndex / register 接口。
 
-import { networkInterfaces } from 'node:os'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import {
+  networkInterfaces, homedir, hostname, cpus, totalmem, freemem,
+  platform, release, arch, loadavg, uptime as osUptime,
+} from 'node:os'
+import { join, dirname } from 'node:path'
+import {
+  existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, rmSync,
+} from 'node:fs'
+import { spawn } from 'node:child_process'
 import qrcode from './qrcode.js'
+import {
+  startExternal, stopExternal, externalView,
+  autoRestoreExternal, loadPersistedState, DEFAULT_SERVER_BASE,
+  frpcLogTail,
+} from './external.js'
+import {
+  hasPassword, verifyPassword, setPassword,
+  isEnabled, login, verifyToken, revokeToken, clearSessions,
+} from './password.js'
 
 /** 插件名（loader 诊断用）。 */
 export const name = 'dsh-mobile-remote'
@@ -54,8 +68,19 @@ export function apply(ctx) {
   const remoteEnabled = ctx.webServer.host === '0.0.0.0'
   const port = ctx.webServer.port
 
-  // 活跃设备表：deviceId -> 最近心跳时间戳。
+  // 活跃设备表：deviceId -> 详细设备信息（见 handleHeartbeat）。
   const devices = new Map()
+  // 累计去重设备数 + 累计心跳数（进程生命周期内的统计，供设置页展示更丰富的数据）。
+  const seenEver = new Set()
+  let totalBeats = 0
+  const tracker = {
+    seenEver,
+    recordBeat() { totalBeats += 1 },
+    beats: () => totalBeats,
+  }
+
+  // 外网隧道状态（frpc 子进程 + 配置）。
+  const external = { proc: null, status: 'idle', url: null, domain: null, tunnelPort: null }
 
   ctx.effect(() => {
     const dispose = ctx.webServer.tapIndex((html) => injectIntoIndex(html, remoteEnabled))
@@ -63,25 +88,61 @@ export function apply(ctx) {
   }, 'dsh-mobile-remote: index transform')
 
   ctx.effect(() => {
+    // DSH 应用层状态缓存（版本 / 会话 / 工作区 / 插件 / 模型），后台定时刷新，
+    // status 请求直接读缓存，避免 sessionPersistence.list() 拖慢每 5s 的轮询。
+    const dshCache = { value: null, at: 0 }
+    const refreshDsh = () => { void refreshDshInfo(ctx, dshCache) }
+    refreshDsh()
+    const dshTimer = setInterval(refreshDsh, 60_000)
+
     const disposers = [
-      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/status', handler: handleStatus(ctx, devices) }),
-      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/toggle', handler: handleToggle(ctx) }),
-      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/heartbeat', handler: handleHeartbeat(devices) }),
-      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/qr', handler: handleQr() }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/status', handler: authGate(handleStatus(ctx, devices, external, tracker, dshCache)) }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/toggle', handler: authGate(handleToggle(ctx)) }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/heartbeat', handler: authGate(handleHeartbeat(devices, tracker)) }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/qr', handler: authGate(handleQr()) }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/external/start', handler: authGate(handleExternalStart(ctx, external)) }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/external/stop', handler: authGate(handleExternalStop(ctx, external)) }),
+      // frpc 运行日志读取（供设置页展示外网隧道详细状态）
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/external/log', handler: authGate(handleExternalLog()) }),
+      // —— 远程访问密码门禁相关（auth 系列不套 authGate，需放行）——
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/auth-status', handler: handleAuthStatus() }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/auth', handler: handleAuth() }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/logout', handler: handleLogout() }),
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/set-password', handler: handleSetPassword() }),
+      // —— Service Worker：远程访问首屏缓存加速（仅 HTTPS 外网生效）——
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/sw.js', handler: handleServiceWorker() }),
     ]
     const timer = setInterval(() => {
       const now = Date.now()
-      for (const [id, seen] of devices) {
-        if (now - seen > HEARTBEAT_TTL) devices.delete(id)
+      for (const [id, info] of devices) {
+        if (now - info.lastSeen > HEARTBEAT_TTL) devices.delete(id)
       }
     }, HEARTBEAT_SWEEP)
+    // dsh 重启后自动恢复外网访问：读取持久化的绑定码 / 中转地址重新拉起 frpc，
+    // 免去每次手动输入。设置 DSH_DISABLE_AUTO_RESTORE=1 可关闭该行为。
+    if (process.env.DSH_DISABLE_AUTO_RESTORE !== '1') {
+      const patchFile = patchFilePath(ctx)
+      void autoRestoreExternal(external, patchFile, ctx.webServer.port || 3080)
+    }
     return () => {
       clearInterval(timer)
+      clearInterval(dshTimer)
+      stopFrpc(external)
       for (const dispose of disposers) dispose()
     }
   }, 'dsh-mobile-remote: api routes')
 }
 
+/** 后台刷新 DSH 应用层状态缓存（失败时保留旧值或置 null）。 */
+async function refreshDshInfo(ctx, cache) {
+  try {
+    cache.value = await collectDshInfo(ctx)
+    cache.at = Date.now()
+  } catch {
+    cache.value = null
+  }
+}
+
 /* ------------------------------------------------------------------ */
 /* 远程控制 API                                                         */
 /* ------------------------------------------------------------------ */
@@ -117,6 +178,421 @@ function getLanAddresses() {
   return out
 }
 
+/** 所有 IPv4 网卡详情（含网卡名 / 掩码 / MAC / CIDR / 是否回环），供设置页展示。 */
+function getLanInterfaces() {
+  const out = []
+  for (const [name, entries] of Object.entries(networkInterfaces() ?? {})) {
+    for (const iface of entries ?? []) {
+      if (iface.family !== 'IPv4') continue
+      out.push({
+        name,
+        address: iface.address,
+        netmask: iface.netmask || null,
+        mac: iface.mac || '',
+        cidr: iface.cidr || null,
+        internal: iface.internal === true,
+      })
+    }
+  }
+  return out
+}
+
+/** 当前进程运行时信息（诊断用，设置页展示）。 */
+function runtimeInfo() {
+  const mem = process.memoryUsage()
+  const cpu = cpus()
+  const load = loadavg()
+  const total = totalmem()
+  return {
+    pid: process.pid,
+    hostname: hostname(),
+    platform: platform(),
+    release: release(),
+    arch: arch(),
+    cpus: cpu.length,
+    cpuModel: (cpu[0] && cpu[0].model) ? cpu[0].model : null,
+    cpuSpeed: (cpu[0] && cpu[0].speed) ? cpu[0].speed : null,
+    loadavg: Array.isArray(load) ? load.map((n) => Number(n.toFixed(2))) : null,
+    sysUptime: Math.floor(osUptime()),
+    totalmem: total,
+    freemem: freemem(),
+    memPct: total > 0 ? Math.round((1 - freemem() / total) * 100) : null,
+    nodeVersion: process.version,
+    uptime: Math.floor(process.uptime()),
+    rss: mem.rss,
+    heapUsed: mem.heapUsed,
+    heapTotal: mem.heapTotal,
+    profile: process.env.DSH_PROFILE || 'web',
+    dshHome: process.env.DSH_HOME || join(homedir(), '.dsh'),
+  }
+}
+
+/** 给异步操作加超时保护，超时返回 fallback（默认 null），避免拖慢 status 响应。 */
+function withTimeout(promise, ms, fallback = null) {
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((resolve) => setTimeout(() => resolve(fallback), ms)),
+  ])
+}
+
+/** 多位置探测 dsh 版本号（profile 本地 / 桌面版 / 全局安装）。找不到返回 null。 */
+function detectDshVersion() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profile = process.env.DSH_PROFILE || 'web'
+  const candidates = [
+    join(home, 'profiles', profile, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'),
+  ]
+  if (process.env.APPDATA) {
+    candidates.push(
+      join(process.env.APPDATA, 'dsh-desktop', 'dsh-local', 'node_modules', '@deepseek-ai', 'dsh', 'package.json'),
+    )
+  }
+  candidates.push(join(dirname(process.execPath), '..', '..', 'node_modules', '@deepseek-ai', 'dsh', 'package.json'))
+  for (const f of candidates) {
+    try {
+      if (!existsSync(f)) continue
+      const pkg = JSON.parse(readFileSync(f, 'utf8'))
+      if (pkg && typeof pkg.version === 'string') return pkg.version
+    } catch { /* ignore */ }
+  }
+  return null
+}
+
+/**
+ * 采集 DSH 应用层状态（尽力而为，任一失败/不可用都降级为 null）：
+ * 版本号 / 会话总数 / 工作区列表 / 已安装插件 / LLM 提供方。
+ * 通过 ctx.get() 可选获取服务，不注入必选依赖，避免插件在精简启动下起不来。
+ */
+async function collectDshInfo(ctx) {
+  const out = { version: null, sessions: null, workspaces: null, plugins: null, llm: null }
+  try { out.version = detectDshVersion() } catch { /* ignore */ }
+  try {
+    const sp = ctx.get('sessionPersistence')
+    if (sp && typeof sp.list === 'function') {
+      const headers = await withTimeout(sp.list(), 2000)
+      if (Array.isArray(headers)) out.sessions = headers.length
+    }
+  } catch { /* ignore */ }
+  try {
+    const wr = ctx.get('workspaceRegistry')
+    if (wr && typeof wr.list === 'function') {
+      const list = wr.list()
+      if (Array.isArray(list)) {
+        out.workspaces = list.map((w) => ({
+          path: w.path,
+          title: w.title || '',
+          sessionCount: Array.isArray(w.sessionIds) ? w.sessionIds.length : 0,
+          updatedAt: w.updatedAt || null,
+        }))
+      }
+    }
+  } catch { /* ignore */ }
+  try {
+    const pi = ctx.get('pluginInventory')
+    if (pi && typeof pi.list === 'function') {
+      const snap = pi.list()
+      if (snap && Array.isArray(snap.entries)) {
+        out.plugins = snap.entries.map((e) => ({
+          name: e.moduleName || e.entryId,
+          enabled: e.enabled === true,
+          phase: e.fiberPhase || null,
+        }))
+      }
+    }
+  } catch { /* ignore */ }
+  try {
+    const llm = ctx.get('llm')
+    if (llm && typeof llm.listProviders === 'function') {
+      const ps = llm.listProviders()
+      if (Array.isArray(ps)) {
+        out.llm = ps.map((p) => ({ id: p.id, name: p.name || p.id }))
+      }
+    }
+  } catch { /* ignore */ }
+  return out
+}
+
+/** 从 User-Agent 推断设备名称。 */
+function deviceNameFromUA(ua) {
+  const s = String(ua || '')
+  if (s.includes('iPhone')) return 'iPhone'
+  if (s.includes('iPad')) return 'iPad'
+  if (s.includes('Android')) return 'Android 设备'
+  if (s.includes('Windows')) return 'Windows 电脑'
+  if (s.includes('Macintosh') || s.includes('Mac OS')) return 'Mac 电脑'
+  if (s.includes('CrOS')) return 'Chromebook'
+  if (s.includes('Linux')) return 'Linux 设备'
+  if (!s) return '未知设备'
+  return '浏览器'
+}
+
+/** 从 User-Agent 推断操作系统（用于设备详情展示）。 */
+function osFromUA(ua) {
+  const s = String(ua || '')
+  if (/iPhone|iPad|iPod/i.test(s)) return 'iOS'
+  if (/Android/i.test(s)) return 'Android'
+  if (/Windows NT 10/i.test(s)) return 'Windows 10/11'
+  if (/Windows NT/i.test(s)) return 'Windows'
+  if (/Mac OS X/i.test(s)) return 'macOS'
+  if (/CrOS/i.test(s)) return 'ChromeOS'
+  if (/Linux/i.test(s)) return 'Linux'
+  if (!s) return '未知系统'
+  return '其他系统'
+}
+
+/** 从 User-Agent 推断浏览器内核 / 名称（用于设备详情展示）。 */
+function browserFromUA(ua) {
+  const s = String(ua || '')
+  if (/Edg\//i.test(s)) return 'Edge'
+  if (/OPR\/|Opera/i.test(s)) return 'Opera'
+  if (/Firefox\//i.test(s)) return 'Firefox'
+  if (/Chrome\//i.test(s)) return 'Chrome'
+  if (/Safari\//i.test(s)) return 'Safari'
+  if (!s) return '未知浏览器'
+  return '其他浏览器'
+}
+
+/** 从请求中提取客户端 IP：优先代理转发头（frpc/nginx 会加），回退 socket 地址。 */
+function clientIpFromReq(req) {
+  const fwd = req.headers['x-forwarded-for']
+  if (fwd) {
+    const first = String(fwd).split(',')[0].trim()
+    if (first) return first
+  }
+  if (req.headers['x-real-ip']) return String(req.headers['x-real-ip']).trim()
+  return (req.socket && req.socket.remoteAddress) || null
+}
+
+/* ------------------------------------------------------------------ */
+/* 远程访问密码门禁（host 侧）                                           */
+/* ------------------------------------------------------------------ */
+
+/** 会话 cookie 名。 */
+const AUTH_COOKIE = '__dsh_remote_auth'
+
+/**
+ * 判断当前请求是否为“远程访问”（外网隧道 / 经 HTTPS 反代进入）。
+ * 依据：外网隧道由 Nginx 反代并设置 X-Forwarded-Proto: https，或 socket 本身
+ * 已加密（TLS）。本机 127.0.0.1 与局域网直连（http）不带该头 → 视为内网，
+ * 不强制密码。这样管理员在本机/内网总能正常使用与修复。
+ * @param {import('node:http').IncomingMessage} req
+ */
+function isRemoteRequest(req) {
+  const proto = String(req.headers['x-forwarded-proto'] || '').toLowerCase()
+  if (proto === 'https') return true
+  if (req.socket && req.socket.encrypted) return true
+  return false
+}
+
+/** 从请求 Cookie 头解析某个 cookie 的值（未找到返回 null）。 */
+function parseCookie(req, name) {
+  const raw = String(req.headers.cookie || '')
+  for (const pair of raw.split(';')) {
+    const idx = pair.indexOf('=')
+    if (idx < 0) continue
+    const k = pair.slice(0, idx).trim()
+    if (k === name) return pair.slice(idx + 1).trim()
+  }
+  return null
+}
+
+/** 是否满足远程访问鉴权：远程且已设密码时要求有效 token。 */
+function authorized(req) {
+  if (!isRemoteRequest(req)) return true
+  if (!isEnabled()) return true
+  return verifyToken(parseCookie(req, AUTH_COOKIE))
+}
+
+/** 远程访问鉴权中间件（注册给需要保护的 path 使用）。 */
+function authGate(handler) {
+  return (req, res) => {
+    if (!authorized(req)) {
+      res.writeHead(401, { 'Content-Type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, code: 'AUTH_REQUIRED', message: '请先输入远程访问密码' }))
+      return
+    }
+    return handler(req, res)
+  }
+}
+
+/** GET /__dsh_remote/auth-status：返回远程访问密码的启用状态与本次请求是否需鉴权。 */
+function handleAuthStatus() {
+  return async (req, res) => {
+    json(res, 200, {
+      ok: true,
+      enabled: isEnabled(),
+      // 仅当是远程访问且已设密码时才需要输入
+      required: isRemoteRequest(req) && isEnabled(),
+      authenticated: authorized(req),
+      remote: isRemoteRequest(req),
+    })
+  }
+}
+
+/** POST /__dsh_remote/auth { password }：校验远程访问密码并签发会话 token（写入 cookie）。 */
+function handleAuth() {
+  return async (req, res) => {
+    // 仅远程访问才允许（本机内网无需走这步，但仍可被调用）
+    const body = await readBody(req)
+    const password = typeof body.password === 'string' ? body.password : ''
+    const ip = clientIpFromReq(req)
+    const result = login(password, ip)
+    if (!result.ok) {
+      json(res, 401, { ok: false, code: 'BAD_PASSWORD', message: result.error || '密码错误' })
+      return
+    }
+    const cookie = `${AUTH_COOKIE}=${result.token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400` + (isRemoteRequest(req) ? '; Secure' : '')
+    res.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Set-Cookie': cookie,
+    })
+    res.end(JSON.stringify({ ok: true, authenticated: true }))
+  }
+}
+
+/** POST /__dsh_remote/logout：撤销当前会话。 */
+function handleLogout() {
+  return async (req, res) => {
+    revokeToken(parseCookie(req, AUTH_COOKIE))
+    res.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Set-Cookie': `${AUTH_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`,
+    })
+    res.end(JSON.stringify({ ok: true }))
+  }
+}
+
+/**
+ * POST /__dsh_remote/set-password { password }（仅本机/内网来源可用）：
+ * 设置或修改远程访问密码。远程来源被拒绝，防止外部任意篡改。空密码=清除。
+ */
+function handleSetPassword() {
+  return async (req, res) => {
+    if (isRemoteRequest(req)) {
+      json(res, 403, { ok: false, code: 'LOCAL_ONLY', message: '仅限在本机设置远程访问密码' })
+      return
+    }
+    const body = await readBody(req)
+    const password = typeof body.password === 'string' ? body.password : ''
+    // 密码强度检查
+    if (password && password.length < 4) {
+      json(res, 400, { ok: false, code: 'WEAK_PASSWORD', message: '密码至少 4 位' })
+      return
+    }
+    if (password && password.length > 128) {
+      json(res, 400, { ok: false, code: 'BAD_PASSWORD', message: '密码过长（最多 128 位）' })
+      return
+    }
+    const result = setPassword(password)
+    json(res, 200, Object.assign({ ok: true }, result))
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Service Worker：远程访问首屏加速                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 处理 GET /__dsh_remote/sw.js —— 返回 Service Worker 脚本。
+ *
+ * 背景：dsh 的静态服务（frontend-static）响应头只有 content-type，没有
+ * Cache-Control / gzip。远程（外网 HTTPS）访问时，浏览器每次都要全量重新
+ * 下载 ~1.25MB 的前端资源，经 frp 隧道每个文件要 1~2 秒，导致首屏
+ * "Loading plugins…" 转圈很久。
+ *
+ * 方案：注册一个 Service Worker（SW 只在 HTTPS 下生效，正好覆盖外网访问；
+ * 内网 http 不启用，但内网直连本来就快）。SW 对 `/assets/*.js|css`（文件名
+ * 带内容哈希，内容不可变）做 cache-first 缓存——首次访问后，后续访问直接
+ * 命中浏览器缓存秒开；DSH 更新后资源文件名哈希变化，浏览器自动加载新文件，
+ * 不会出现旧版本。
+ *
+ * 响应头必须带 `Service-Worker-Allowed: /`，否则浏览器不允许把 SW 的 scope
+ * 扩展到根路径（SW 脚本位于 /__dsh_remote/ 下，默认 scope 只覆盖该子路径）。
+ */
+function handleServiceWorker() {
+  return async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    res.writeHead(200, {
+      'Content-Type': 'application/javascript; charset=utf-8',
+      'Service-Worker-Allowed': '/',
+      // SW 本身不缓存或短缓存：保证 DSH 更新后 SW 能及时拿到新版本
+      'Cache-Control': 'no-cache',
+    })
+    res.end(SERVICE_WORKER_JS)
+  }
+}
+
+/** Service Worker 脚本体（cache-first 缓存 /assets/ 下的 js/css）。 */
+const SERVICE_WORKER_JS = `
+'use strict';
+/* dsh-mobile-remote 远程访问加速 SW：缓存 /assets/ 下带内容哈希的静态资源。
+ * 文件名带哈希（如 index-C-1AiF3k.js）→ 内容不变则文件名不变 → 可安全
+ * cache-first；DSH 更新后文件名哈希变化 → 自动回源加载新文件。 */
+var CACHE_NAME = 'dsh-remote-static-v1';
+var CACHE_PATTERN = /^\\/assets\\/.*\\.(js|css)$/;
+
+self.addEventListener('install', function (event) {
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', function (event) {
+  event.waitUntil(
+    caches.keys().then(function (keys) {
+      return Promise.all(keys.map(function (k) {
+        if (k !== CACHE_NAME) return caches.delete(k);
+      }));
+    }).then(function () { return self.clients.claim(); })
+  );
+});
+
+self.addEventListener('fetch', function (event) {
+  var url;
+  try { url = new URL(event.request.url); } catch (e) { return; }
+  if (url.origin !== self.location.origin) return;
+  if (!CACHE_PATTERN.test(url.pathname)) return;
+  event.respondWith(
+    caches.open(CACHE_NAME).then(function (cache) {
+      return cache.match(event.request).then(function (hit) {
+        if (hit) return hit;
+        return fetch(event.request).then(function (resp) {
+          if (resp && resp.ok) cache.put(event.request, resp.clone());
+          return resp;
+        });
+      });
+    }).catch(function () {
+      return fetch(event.request);
+    })
+  );
+});
+`
+
+/**
+ * 从中转服务器查询本成员隧道状态与统计；失败时返回 null（不影响整体 status）。
+ * 优先调用 /api/tunnel/stats（含 frps 实时流量/连接数等），接口不可用则回退到
+ * /api/tunnel/status（旧版后端）。任一失败返回 null。
+ */
+async function queryServerStatus(base, bindCode) {
+  if (!bindCode) return null
+  const server = String(base || DEFAULT_SERVER_BASE).replace(/\/$/, '')
+  const call = (path) => fetch(`${server}${path}`, {
+    headers: { Accept: 'application/json' },
+    // 避免无限期挂起，5 秒超时
+    signal: AbortSignal.timeout(5000),
+  }).then(async (res) => {
+    if (!res.ok) return null
+    const body = await res.json()
+    return body && body.success ? body.data : null
+  }).catch(() => null)
+  const q = `?bindCode=${encodeURIComponent(bindCode)}`
+  const stats = await call(`/api/tunnel/stats${q}`)
+  if (stats) return stats
+  return call(`/api/tunnel/status${q}`)
+}
+
 /** 当前 profile 的 cordis.patch.yml 绝对路径。 */
 function patchFilePath(ctx) {
   // DSH_HOME 环境变量优先，否则 ~/.dsh；profile 名为 DSH_PROFILE 或默认 web。
@@ -182,19 +658,97 @@ function setPatchEnabled(ctx, enabled) {
 }
 
 /** GET /__dsh_remote/status */
-function handleStatus(ctx, devices) {
+function handleStatus(ctx, devices, external, tracker, dshCache) {
   return async (req, res) => {
     const lan = getLanAddresses()
     const remoteEnabled = ctx.webServer.host === '0.0.0.0'
+    // 外网 frpc 是否仍在运行
+    const extRunning = !!external.proc && external.proc.exitCode === null
+    // 已持久化的绑定信息（重启后自动恢复用，前端据此回填表单）
+    const persisted = loadPersistedState()
+    // 活跃设备详情列表（按最近活跃倒序）
+    const deviceList = []
+    for (const [id, info] of devices) {
+      deviceList.push({
+        id,
+        ip: info.ip || null,
+        name: info.name || '未知设备',
+        os: info.os || '未知系统',
+        browser: info.browser || '未知浏览器',
+        ua: info.ua || '',
+        platform: info.platform || '',
+        lang: info.lang || '',
+        online: info.online === true,
+        touch: info.touch === true,
+        dpr: info.dpr || null,
+        screen: info.screen || '',
+        viewport: info.viewport || '',
+        connection: info.connection || null,
+        path: info.path || '',
+        title: info.title || '',
+        mobile: info.mobile === true,
+        beatCount: info.beatCount || 1,
+        battery: info.battery || null,
+        deviceMemory: info.deviceMemory || null,
+        hardwareConcurrency: info.hardwareConcurrency || null,
+        firstSeen: info.firstSeen,
+        lastSeen: info.lastSeen,
+      })
+    }
+    deviceList.sort((a, b) => b.lastSeen - a.lastSeen)
+    // 外网隧道在线时，向中转服务器查询成员真实状态（成员名 / frps 在线 / 最后心跳）
+    let server = null
+    if (extRunning && persisted) {
+      server = await queryServerStatus(persisted.serverBase || undefined, persisted.bindCode)
+    }
     json(res, 200, {
       host: ctx.webServer.host,
       port: ctx.webServer.port,
       lanAddresses: lan,
+      lanInterfaces: getLanInterfaces(),
       remoteEnabled,
       patchEnabled: isPatchEnabled(ctx),
       deviceCount: devices.size,
+      devices: deviceList,
       patchFile: patchFilePath(ctx),
       url: lan.length ? `http://${lan[0]}:${ctx.webServer.port}` : null,
+      // 本机运行时信息（诊断用，设置页展示更详细的数据）
+      runtime: runtimeInfo(),
+      uptime: Math.floor(process.uptime()),
+      nodeVersion: process.version,
+      totalDevicesEver: tracker.seenEver.size,
+      totalHeartbeats: tracker.beats(),
+      // DSH 应用层状态（版本 / 会话 / 工作区 / 插件 / 模型；后台缓存，可能为 null）
+      dsh: dshCache ? dshCache.value : null,
+      // 外网隧道字段（status 直接透传 externalView 的真实状态：
+      // online=隧道已建立 / connecting / error=鉴权失败等 / stopped / idle）
+      external: {
+        enabled: extRunning,
+        running: extRunning,
+        status: external.status || 'idle',
+        url: extRunning ? external.url : null,
+        domain: external.domain,
+        tunnelPort: external.tunnelPort,
+        frpcVersion: external.frpcVersion || null,
+        pid: extRunning && external.proc ? external.proc.pid : null,
+        startedAt: external.startedAt || null,
+        bindCodeShort: persisted && persisted.bindCode
+          ? String(persisted.bindCode).slice(0, 4) + '****'
+          : '',
+        error: external.error || null,
+        defaultServerBase: DEFAULT_SERVER_BASE,
+        persisted: persisted
+          ? { bindCode: persisted.bindCode || '', serverBase: persisted.serverBase || '' }
+          : null,
+        // 中转服务器返回的成员状态（外网在线时才有）
+        server,
+      },
+      // 远程访问密码门禁状态（供设置面板展示）
+      auth: {
+        enabled: isEnabled(),
+        requiredHere: isRemoteRequest(req) && isEnabled(),
+        authenticated: authorized(req),
+      },
       cliHint: remoteEnabled
         ? null
         : 'remote control is off; toggle it in settings or start dsh with --patch',
@@ -223,12 +777,43 @@ function handleToggle(ctx) {
   }
 }
 
-/** POST /__dsh_remote/heartbeat { id?: string, ua?: string } */
-function handleHeartbeat(devices) {
+/** POST /__dsh_remote/heartbeat（移动端上报的详细设备元数据，见下方 MOBILE_JS）。 */
+function handleHeartbeat(devices, tracker) {
   return async (req, res) => {
     const body = await readBody(req)
     const id = typeof body.id === 'string' && body.id ? body.id : 'anonymous'
-    devices.set(id, Date.now())
+    const now = Date.now()
+    const prev = devices.get(id)
+    tracker.seenEver.add(id)
+    tracker.recordBeat()
+    const conn = (body.connection && typeof body.connection === 'object') ? body.connection : null
+    const battery = (body.battery && typeof body.battery === 'object')
+      ? { level: Number(body.battery.level) || null, charging: body.battery.charging === true }
+      : null
+    devices.set(id, {
+      ip: clientIpFromReq(req),
+      ua: String(body.ua || ''),
+      name: deviceNameFromUA(body.ua),
+      os: osFromUA(body.ua),
+      browser: browserFromUA(body.ua),
+      platform: String(body.platform || ''),
+      lang: String(body.lang || ''),
+      online: body.online === true,
+      touch: body.touch === true,
+      dpr: Number(body.dpr) || null,
+      screen: String(body.screen || ''),
+      viewport: String(body.viewport || ''),
+      connection: conn,
+      battery,
+      deviceMemory: Number(body.deviceMemory) || null,
+      hardwareConcurrency: Number(body.hardwareConcurrency) || null,
+      path: String(body.path || ''),
+      title: String(body.title || ''),
+      mobile: body.mobile === true,
+      beatCount: prev ? prev.beatCount + 1 : 1,
+      firstSeen: prev ? prev.firstSeen : now,
+      lastSeen: now,
+    })
     json(res, 200, { ok: true, deviceCount: devices.size })
   }
 }
@@ -263,14 +848,56 @@ function handleQr() {
  * 把移动端 CSS/JS 注入到 index.html。优先注入到 </head> 之前，
  * 找不到则退化为追加到文档末尾。
  */
+/* ------------------------------------------------------------------ */
+/* 外网隧道管理（中转服务 + frpc）—— 见 lib/external.js                  */
+/* ------------------------------------------------------------------ */
+
+/** POST /__dsh_remote/external/start { bindCode?, serverBase?, localPort? } */
+function handleExternalStart(ctx, external) {
+  return async (req, res) => {
+    let body = {}
+    try { body = await readBody(req) } catch { /* ignore */ }
+    try {
+      const patchFile = patchFilePath(ctx)
+      const result = await startExternal(external, body, patchFile, ctx.webServer.port || 3080)
+      json(res, 200, Object.assign({ ok: true }, result))
+    } catch (error) {
+      external.error = String(error?.message || error)
+      json(res, 500, { ok: false, error: external.error })
+    }
+  }
+}
+
+/** POST /__dsh_remote/external/stop */
+function handleExternalStop(ctx, external) {
+  return async (req, res) => {
+    stopExternal(external)
+    json(res, 200, { ok: true, enabled: false })
+  }
+}
+
+/** GET /__dsh_remote/external/log：返回 frpc 运行日志尾部，供设置页排查外网隧道问题。 */
+function handleExternalLog() {
+  return async (req, res) => {
+    json(res, 200, { ok: true, log: frpcLogTail() })
+  }
+}
+
+/** 停止 frpc（apply 清理时调用）。keepState 保留持久化，重启后自动恢复。 */
+function stopFrpc(external) {
+  stopExternal(external, { keepState: true })
+}
 function injectIntoIndex(html, remoteEnabled) {
   const bootConfig =
     '<script id="dsh-mobile-remote-config">window.__DSH_MOBILE_REMOTE__ = ' +
     JSON.stringify({ lanEnabled: remoteEnabled, mobileMaxWidth: MOBILE_MAX_WIDTH }) +
     ';</script>'
+  const gateStyle = `<style id="dsh-mobile-remote-gate-css">${GATE_CSS}</style>`
+  const gateScript = `<script id="dsh-mobile-remote-gate-js">${GATE_JS}</script>`
   const style = `<style id="dsh-mobile-remote-css">${MOBILE_CSS}</style>`
   const script = `<script id="dsh-mobile-remote-js">${MOBILE_JS}</script>`
-  const injection = bootConfig + style + script
+  // 门禁脚本注入在 head 最前，确保在 DSH 界面渲染前就绪
+  const injection = bootConfig + gateStyle + gateScript + style + script
 
   if (html.includes('</head>')) {
     return html.replace('</head>', `${injection}\n</head>`)
@@ -279,11 +906,132 @@ function injectIntoIndex(html, remoteEnabled) {
 }
 
 /* ------------------------------------------------------------------ */
-/* 移动端响应式 CSS                                                     */
-/* 作用：仅修补 composer 输入栏在窄屏下的挤压/粘连，并做 iOS 触屏优化。   */
-/* 不动 sidebar / details / frame / 任何 React 渲染结构。                 */
+/* 远程访问密码门禁：样式 + 前端脚本                                      */
+/* 作用：当本次访问是“远程”（外网隧道 / HTTPS 反代）且管理员已设置密码时，  */
+/* 在 DSH 界面加载前弹出全屏密码验证遮罩。输对密码后种会话 cookie 并重载。  */
+/* 不输密码无法操作 DSH（遮罩拦截所有交互）。                              */
 /* ------------------------------------------------------------------ */
 
+const GATE_CSS = `
+#dsh-remote-gate {
+  position: fixed; inset: 0; z-index: 2147483647;
+  display: flex; align-items: center; justify-content: center;
+  background: rgba(15, 17, 26, 0.92);
+  backdrop-filter: blur(6px);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  color: #e8e8ea;
+}
+#dsh-remote-gate .gate-card {
+  width: min(360px, 88vw); box-sizing: border-box;
+  background: #1d2030; border: 1px solid rgba(255,255,255,.12);
+  border-radius: 14px; padding: 24px 22px;
+  box-shadow: 0 18px 50px rgba(0,0,0,.45);
+}
+#dsh-remote-gate .gate-title {
+  font-size: 17px; font-weight: 700; margin: 0 0 6px;
+}
+#dsh-remote-gate .gate-sub {
+  font-size: 13px; color: #9aa0b5; margin: 0 0 16px; line-height: 1.5;
+}
+#dsh-remote-gate .gate-input {
+  width: 100%; box-sizing: border-box;
+  padding: 10px 12px; font-size: 14px; color: #e8e8ea;
+  background: #14171f; border: 1px solid rgba(255,255,255,.18);
+  border-radius: 9px; outline: none;
+}
+#dsh-remote-gate .gate-input:focus { border-color: #4c8dff; }
+#dsh-remote-gate .gate-btn {
+  width: 100%; margin-top: 12px; padding: 10px 12px;
+  font-size: 14px; font-weight: 600; color: #fff;
+  background: #2a7de1; border: none; border-radius: 9px; cursor: pointer;
+}
+#dsh-remote-gate .gate-btn:hover { background: #3a8df0; }
+#dsh-remote-gate .gate-btn:disabled { opacity: .6; cursor: default; }
+#dsh-remote-gate .gate-err {
+  font-size: 12px; color: #ff6b6b; margin-top: 10px; min-height: 16px;
+}
+#dsh-remote-gate .gate-loading { opacity: .6; }
+`
+
+const GATE_JS = `
+(function () {
+  'use strict';
+  function canCover() {
+    try { return document.getElementById('dsh-remote-gate') === null; } catch (e) { return true; }
+  }
+  function createGate() {
+    if (!canCover()) return;
+    var g = document.createElement('div');
+    g.id = 'dsh-remote-gate';
+    g.innerHTML =
+      '<div class="gate-card">' +
+        '<p class="gate-title">远程访问已锁定</p>' +
+        '<p class="gate-sub">请输入管理员设置的远程访问密码以继续使用。</p>' +
+        '<input class="gate-input" type="password" autocomplete="current-password" placeholder="远程访问密码" />' +
+        '<button class="gate-btn" type="button">进入</button>' +
+        '<p class="gate-err"></p>' +
+      '</div>';
+    document.documentElement.appendChild(g);
+    return g;
+  }
+  function hideGate(g) { try { g.parentNode && g.parentNode.removeChild(g); } catch (e) {} }
+  function submit(g, input, btn) {
+    var pwd = input.value;
+    if (!pwd) { g.querySelector('.gate-err').textContent = '请输入密码'; return; }
+    btn.disabled = true; btn.classList.add('gate-loading');
+    fetch('/__dsh_remote/auth', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ password: pwd }),
+    }).then(function (r) {
+      if (!r.ok) throw new Error('密码错误');
+      return r.json();
+    }).then(function () {
+      window.location.reload();
+    }).catch(function (e) {
+      btn.disabled = false; btn.classList.remove('gate-loading');
+      g.querySelector('.gate-err').textContent = String(e && e.message || e);
+      input.select();
+    });
+  }
+  function init() {
+    if (!canCover()) return;
+    fetch('/__dsh_remote/auth-status', { headers: { 'Accept': 'application/json' } })
+      .then(function (r) { return r.json(); })
+      .then(function (st) {
+        if (!st || !st.required || st.authenticated) return;
+        var g = createGate();
+        if (!g) return;
+        var input = g.querySelector('.gate-input');
+        var btn = g.querySelector('.gate-btn');
+        var doSubmit = function () { submit(g, input, btn); };
+        btn.addEventListener('click', doSubmit);
+        input.addEventListener('keydown', function (e) { if (e.key === 'Enter') doSubmit(); });
+        input.focus();
+      })
+      .catch(function () { /* auth-status 不可达（本机直连等）时不遮罩 */ });
+  }
+
+  /* 远程访问首屏加速：注册 Service Worker，缓存 /assets/ 下带哈希的静态资源。
+   * 仅 HTTPS（外网隧道）下浏览器才允许注册 SW；内网 http 自动跳过。 */
+  function registerSw() {
+    try {
+      if (!('serviceWorker' in navigator)) return;
+      if (location.protocol !== 'https:') return;
+      navigator.serviceWorker.register('/__dsh_remote/sw.js', { scope: '/' })
+        .catch(function () { /* 注册失败不阻塞页面 */ });
+    } catch (e) { /* ignore */ }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { init(); registerSw(); });
+  } else {
+    init();
+    registerSw();
+  }
+})();
+`
+
 const MOBILE_CSS = `
 /* === dsh-mobile-remote 移动端输入栏补丁 ===
  * 作用范围：仅在移动设备（<1024px）下生效。DSH 原生已经在 <1024px 时把侧边栏
@@ -370,11 +1118,8 @@ const MOBILE_JS = `
     return mobileUA || (touch && narrow);
   }
 
-  if (!isMobile()) return;
-
-  document.documentElement.setAttribute('data-dsh-mobile', '');
-
-  // 设备心跳：稳定标识 + 30s 间隔上报，host 统计在线设备数。
+  // 设备心跳：稳定标识 + 30s 间隔上报，host 统计并展示"已连接设备"。
+  // 所有访问本 DSH 的浏览器（PC + 手机）都上报，仅移动端才打 data-dsh-mobile 标记。
   try {
     var KEY = '__dsh_mobile_remote_device';
     var id = localStorage.getItem(KEY);
@@ -382,12 +1127,57 @@ const MOBILE_JS = `
       id = 'dev-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10);
       localStorage.setItem(KEY, id);
     }
+    // 采集当前设备元数据，随心跳上报，host 在设置页展示详细设备信息。
+    // 电池信息为异步获取，首次拿到后缓存在变量中，后续心跳一并上报。
+    var batteryLevel = null;
+    var batteryCharging = null;
+    try {
+      if (navigator.getBattery) {
+        navigator.getBattery().then(function (b) {
+          batteryLevel = Math.round((b && b.level) * 100);
+          batteryCharging = !!(b && b.charging);
+        }).catch(function () {});
+      }
+    } catch (e) {}
+    function deviceMeta() {
+      var scr = window.screen || {};
+      var scrStr = (scr.width && scr.height)
+        ? (scr.width + '\u00d7' + scr.height + (scr.colorDepth ? ' @ ' + scr.colorDepth + 'bit' : ''))
+        : '';
+      var conn = navigator.connection || null;
+      var langs = navigator.languages || [];
+      var title = '';
+      try { title = document.title || ''; } catch (e) {}
+      return {
+        id: id,
+        ua: navigator.userAgent,
+        platform: navigator.platform || '',
+        lang: navigator.language || (langs.length ? langs[0] : '') || '',
+        online: navigator.onLine === true,
+        touch: ('ontouchstart' in window) || (navigator.maxTouchPoints > 0),
+        dpr: window.devicePixelRatio || 1,
+        screen: scrStr,
+        viewport: window.innerWidth + '\u00d7' + window.innerHeight,
+        deviceMemory: navigator.deviceMemory || null,
+        hardwareConcurrency: navigator.hardwareConcurrency || null,
+        battery: (batteryLevel === null) ? null : { level: batteryLevel, charging: batteryCharging },
+        connection: conn ? {
+          effectiveType: conn.effectiveType || null,
+          downlink: (typeof conn.downlink === 'number') ? conn.downlink : null,
+          rtt: (typeof conn.rtt === 'number') ? conn.rtt : null,
+          saveData: conn.saveData === true,
+        } : null,
+        path: (location.pathname || '/') + (location.search || ''),
+        title: title,
+        mobile: isMobile(),
+      };
+    }
     function beat() {
       try {
         fetch('/__dsh_remote/heartbeat', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ id: id, ua: navigator.userAgent }),
+          body: JSON.stringify(deviceMeta()),
           keepalive: true,
         }).catch(function () {});
       } catch (e) {}
@@ -396,6 +1186,10 @@ const MOBILE_JS = `
     setInterval(beat, 30000);
   } catch (e) {}
 
+  if (!isMobile()) return;
+
+  document.documentElement.setAttribute('data-dsh-mobile', '');
+
   // 调试钩子：在控制台暴露状态，便于移动端远程排查。
   window.__DSH_MOBILE_REMOTE_READY__ = {
     mobile: true,