dsh-plugin-mobile-gateway 0.7.7 → 0.8.1

package/lib/client.js

@@ -49,6 +49,7 @@ window.__ModuleLoader__.load({
       input: { width: '100%', boxSizing: 'border-box', border: `1px solid ${colors.border}`, borderRadius: 8, padding: '8px 10px', marginBottom: 10, background: 'transparent', color: 'inherit', outline: 'none' },
       pairingText: { width: '100%', minHeight: 86, boxSizing: 'border-box', resize: 'vertical', border: `1px solid ${colors.border}`, borderRadius: 8, padding: '9px 10px', margin: '10px 0', background: 'transparent', color: 'inherit', outline: 'none', fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 11, lineHeight: 1.45, overflowWrap: 'anywhere' },
       button: { cursor: 'pointer', border: `1px solid ${colors.border}`, background: 'transparent', borderRadius: 8, padding: '7px 11px', color: 'inherit', font: 'inherit' },
+      headerButton: { width: 34, height: 34, boxSizing: 'border-box', padding: 0, display: 'inline-flex', alignItems: 'center', justifyContent: 'center', flexShrink: 0 },
       primary: { background: colors.accent, color: '#fff', borderColor: colors.accent, width: '100%' },
       muted: { color: colors.muted, fontSize: 12, lineHeight: 1.55 },
       row: { display: 'grid', gridTemplateColumns: 'minmax(0, 1fr) auto', columnGap: 12, alignItems: 'center', padding: '12px 0', borderBottom: `1px solid ${colors.border}` },
@@ -56,6 +57,10 @@ window.__ModuleLoader__.load({
       dot: { width: 7, height: 7, borderRadius: 99, display: 'inline-block' },
       error: { color: '#ff8092', background: 'rgba(220,76,100,.12)', borderRadius: 8, padding: 10, marginBottom: 12 },
       qr: { display: 'block', width: 220, height: 220, margin: '12px auto', background: '#fff', borderRadius: 10, padding: 8 },
+      helpButton: { width: 20, height: 20, boxSizing: 'border-box', padding: 0, borderRadius: '50%', border: `1px solid ${colors.muted}`, background: 'transparent', color: colors.muted, cursor: 'help', display: 'inline-flex', alignItems: 'center', justifyContent: 'center', flexShrink: 0, fontSize: 12, fontWeight: 600, lineHeight: 1 },
+      helpBubble: { position: 'absolute', top: '100%', left: 0, zIndex: 20, width: 'min(300px, calc(100vw - 88px))', maxHeight: 'min(440px, calc(100vh - 160px))', overflowY: 'auto', boxSizing: 'border-box', padding: 12, borderRadius: 10, border: '1px solid rgba(255,255,255,.18)', background: '#20242c', color: '#f4f4f5', boxShadow: '0 12px 28px rgba(0,0,0,.35)', fontSize: 12, lineHeight: 1.5 },
+      toolsMenu: { position: 'absolute', top: 'calc(100% + 6px)', right: 0, zIndex: 30, width: 250, maxWidth: 'calc(100vw - 48px)', border: `1px solid ${colors.border}`, borderRadius: 10, padding: 5, background: '#20242c', boxShadow: '0 12px 28px rgba(0,0,0,.35)' },
+      toolsItem: { display: 'block', width: '100%', padding: '9px 10px', textAlign: 'left', border: 0, borderRadius: 7, background: 'transparent', color: colors.text, font: 'inherit', cursor: 'pointer' },
       switch: { position: 'relative', display: 'inline-flex', width: 42, height: 24, flexShrink: 0 },
       switchInput: { position: 'absolute', opacity: 0, width: 1, height: 1 },
       switchTrack: { position: 'absolute', inset: 0, borderRadius: 99, transition: 'background .18s ease', cursor: 'pointer' },
@@ -75,6 +80,42 @@ window.__ModuleLoader__.load({
       return `${scheme}//${window.location.host}${wsPath || '/ws/mobile'}`
     }
 
+    function lanPairingUrl(status) {
+      const urls = status?.lan?.listening && Array.isArray(status.lan.urls) ? status.lan.urls : []
+      return urls.find((url) => !/^ws:\/\/169\.254\./.test(url)) || urls[0] || ''
+    }
+
+    function pairingUrlFor(route, status) {
+      const lanUrl = lanPairingUrl(status)
+      const tunnelUrl = status.cloudflare?.enabled ? status.cloudflare.publicUrl || '' : ''
+      if (route === 'lan') return lanUrl
+      if (route === 'cloudflare') return tunnelUrl
+      if (status.cloudflare?.enabled && status.cloudflare.mode === 'quick') return tunnelUrl
+      return tunnelUrl || status.publicUrl || lanUrl || inferredUrl(status.wsPath)
+    }
+
+    function connectionAdvice(status, publicSetup) {
+      if (!status) return { detected: '正在读取网关环境…', local: '', remote: '' }
+      const system = status.platform === 'darwin' ? 'macOS 电脑' : status.platform === 'win32' ? 'Windows 电脑' : status.platform === 'linux' ? 'Linux 服务器' : '当前设备'
+      const lanReady = !!lanPairingUrl(status)
+      const tunnel = status.cloudflare
+      const tunnelReady = !!(tunnel?.enabled && tunnel.state === 'online' && tunnel.publicUrl)
+      const serverReady = status.platform === 'linux' && !!(
+        (publicSetup?.configured && publicSetup.publicUrl) || /^wss:\/\//.test(status.publicUrl || ''))
+      const detected = `当前检测：${system}；局域网入口${lanReady ? '已就绪' : '未就绪'}；${serverReady ? '公网服务器入口已配置' : tunnelReady ? `${tunnel.mode === 'quick' ? 'Quick' : '命名'} Tunnel 已连接` : tunnel?.enabled ? 'Cloudflare Tunnel 连接中' : '外网入口未连接'}。`
+      const local = lanReady
+        ? '手机与 DSH 处于可互访的同一局域网时，建议选“局域网直连”。'
+        : '如果手机和 DSH 在同一局域网，先确认局域网入口已开启并监听成功。'
+      let remote
+      if (serverReady) remote = '手机在外网时，建议使用已配置的公网服务器地址（“自动选择”）。'
+      else if (tunnelReady && tunnel.mode === 'named') remote = '手机在外网时，建议选“Cloudflare 外网”；当前命名 Tunnel 有固定域名。'
+      else if (tunnelReady) remote = '手机在外网临时使用时，建议选“Cloudflare 外网”；Quick 地址变化后需要重新确认。'
+      else if (status.platform === 'darwin' || status.platform === 'win32') remote = '手机在外网时，无自有域名可开启 Quick Tunnel；有域名且需要固定地址可配置命名 Tunnel。'
+      else if (status.platform === 'linux') remote = '手机在外网时，若使用受支持的 Ubuntu/Debian 服务器且有固定公网 IPv4，可先配置“公网接入”，再选“自动选择”。'
+      else remote = '手机在外网时，需要一个可访问的 wss:// 地址；可在“手动输入地址”中填写。'
+      return { detected, local, remote }
+    }
+
     function DeviceRow({ device, onRevoke, revoking }) {
       const triggerRevoke = (event) => {
         event.preventDefault()
@@ -116,9 +157,19 @@ window.__ModuleLoader__.load({
       const [devices, setDevices] = React.useState(null)
       const [status, setStatus] = React.useState(null)
       const [publicUrl, setPublicUrl] = React.useState('')
+      const [pairingRoute, setPairingRoute] = React.useState('auto')
+      const [connectionHelpOpen, setConnectionHelpOpen] = React.useState(false)
+      const [toolsOpen, setToolsOpen] = React.useState(false)
+      const [toolBusy, setToolBusy] = React.useState(false)
+      const [toolNotice, setToolNotice] = React.useState('')
+      const stoppedRef = React.useRef(false)
       const [publicIp, setPublicIp] = React.useState('')
       const [publicSetup, setPublicSetup] = React.useState(null)
       const [publicSetupBusy, setPublicSetupBusy] = React.useState(false)
+      const [cloudflareHost, setCloudflareHost] = React.useState('')
+      const [cloudflareToken, setCloudflareToken] = React.useState('')
+      const [cloudflareMode, setCloudflareMode] = React.useState('quick')
+      const [cloudflareBusy, setCloudflareBusy] = React.useState(false)
       const [deviceName, setDeviceName] = React.useState('iPhone')
       const [qr, setQr] = React.useState(null)
       const [error, setError] = React.useState(null)
@@ -131,6 +182,8 @@ window.__ModuleLoader__.load({
       const [revokingIds, setRevokingIds] = React.useState(() => new Set())
       const revokingIdsRef = React.useRef(new Set())
       const automaticUrlRef = React.useRef('')
+      const pairingRouteRef = React.useRef('auto')
+      const cloudflareModeLoadedRef = React.useRef(false)
 
       const refresh = React.useCallback(async () => {
         try {
@@ -146,15 +199,23 @@ window.__ModuleLoader__.load({
             setDevices((current) => JSON.stringify(current) === JSON.stringify(nextDevices) ? current : nextDevices)
           }
           setStatus((current) => JSON.stringify(current) === JSON.stringify(statusData) ? current : statusData)
-          const lanUrl = statusData.lan && Array.isArray(statusData.lan.urls) ? statusData.lan.urls[0] : ''
-          const preferredUrl = statusData.publicUrl || lanUrl || inferredUrl(statusData.wsPath)
-          setPublicUrl((current) => {
-            if (!current || current === automaticUrlRef.current) {
-              automaticUrlRef.current = preferredUrl
-              return preferredUrl
-            }
-            return current
-          })
+          if (statusData.cloudflare && statusData.cloudflare.hostname) {
+            setCloudflareHost((current) => current || statusData.cloudflare.hostname)
+          }
+          if (statusData.cloudflare && !cloudflareModeLoadedRef.current) {
+            cloudflareModeLoadedRef.current = true
+            setCloudflareMode(statusData.cloudflare.mode || 'quick')
+          }
+          if (pairingRouteRef.current === 'cloudflare' && !statusData.cloudflare?.enabled) {
+            pairingRouteRef.current = 'auto'
+            setPairingRoute('auto')
+          }
+          if (pairingRouteRef.current !== 'custom') {
+            const preferredUrl = pairingUrlFor(pairingRouteRef.current, statusData)
+            if (automaticUrlRef.current && preferredUrl !== automaticUrlRef.current) setQr(null)
+            automaticUrlRef.current = preferredUrl
+            setPublicUrl(preferredUrl)
+          }
           return true
         } catch (cause) {
           setError(cause.message)
@@ -175,6 +236,43 @@ window.__ModuleLoader__.load({
         }
       }
 
+      const runTool = async (tool) => {
+        if (toolBusy) return
+        setToolsOpen(false)
+        setToolBusy(true)
+        setToolNotice('')
+        setError(null)
+        try {
+          const oldPid = status?.webPid
+          await request(`/mgw/tools/${tool}`, { method: 'POST' })
+          if (tool === 'stop-web') {
+            stoppedRef.current = true
+            setToolNotice('DSH Web 已收到停止指令。需要时可在 Terminal 运行 dsh web 重新启动。')
+            return
+          }
+          if (tool === 'restart-web') {
+            setToolNotice('正在重启 DSH Web，当前连接会短暂中断…')
+            const deadline = Date.now() + 60_000
+            while (Date.now() < deadline) {
+              await new Promise((resolve) => window.setTimeout(resolve, 700))
+              try {
+                const next = await request('/mgw/status')
+                if (next.webPid && next.webPid !== oldPid) {
+                  window.location.reload()
+                  return
+                }
+              } catch { /* old process is shutting down */ }
+            }
+            throw new Error('DSH Web 重启超时，请检查 /tmp/mobile-gateway.log')
+          }
+        } catch (cause) {
+          setError(cause.message)
+          setToolNotice('')
+        } finally {
+          setToolBusy(false)
+        }
+      }
+
       React.useEffect(() => {
         let active = true
         refresh()
@@ -186,10 +284,25 @@ window.__ModuleLoader__.load({
             if (match) setPublicIp(match[1])
           }
         }).catch((cause) => active && setPublicSetup({ installed: false, configured: false, error: cause.message }))
-        const timer = window.setInterval(refresh, 3000)
+        const timer = window.setInterval(() => { if (!stoppedRef.current) refresh() }, 3000)
         return () => { active = false; window.clearInterval(timer) }
       }, [refresh])
 
+      const choosePairingRoute = (route) => {
+        pairingRouteRef.current = route
+        setPairingRoute(route)
+        setQr(null)
+        if (route === 'custom') {
+          automaticUrlRef.current = ''
+          return
+        }
+        if (status) {
+          const nextUrl = pairingUrlFor(route, status)
+          automaticUrlRef.current = nextUrl
+          setPublicUrl(nextUrl)
+        }
+      }
+
       const configurePublicAccess = async () => {
         if (publicSetupBusy) return
         setPublicSetupBusy(true)
@@ -201,7 +314,7 @@ window.__ModuleLoader__.load({
             body: JSON.stringify({ publicIp }),
           })
           setPublicSetup(data)
-          if (data.publicUrl) {
+          if (data.publicUrl && pairingRouteRef.current === 'auto') {
             automaticUrlRef.current = data.publicUrl
             setPublicUrl(data.publicUrl)
           }
@@ -212,6 +325,33 @@ window.__ModuleLoader__.load({
         }
       }
 
+      const configureCloudflare = async (enabled) => {
+        if (cloudflareBusy) return
+        setCloudflareBusy(true)
+        setError(null)
+        try {
+          const data = await request('/mgw/cloudflare', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ enabled, ...(enabled ? {
+              mode: cloudflareMode,
+              ...(cloudflareMode === 'named' ? { hostname: cloudflareHost, token: cloudflareToken } : {}),
+            } : {}) }),
+          })
+          setCloudflareToken('')
+          setStatus((current) => ({ ...(current || {}), cloudflare: data, gatewayEnabled: data.gatewayEnabled, gatewayMode: data.gatewayMode, publicUrl: data.publicUrl || null }))
+          if (!enabled && pairingRouteRef.current === 'cloudflare') {
+            pairingRouteRef.current = 'auto'
+            setPairingRoute('auto')
+          }
+          await refresh()
+        } catch (cause) {
+          setError(cause.message)
+        } finally {
+          setCloudflareBusy(false)
+        }
+      }
+
       const createPairing = async (endpoint) => request('/mgw/pair', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -312,13 +452,41 @@ window.__ModuleLoader__.load({
         }
       }
 
+      const advice = connectionAdvice(status, publicSetup)
+      const helpLine = (name, description) => React.createElement('div', { style: { marginTop: 7 } },
+        React.createElement('strong', null, name), '：', description)
+
       return React.createElement('div', { style: styles.backdrop, onMouseDown: () => setOpen(false) },
-        React.createElement('aside', { style: styles.panel, onMouseDown: (event) => event.stopPropagation(), role: 'dialog', 'aria-modal': true, 'aria-label': '移动设备管理' },
+        React.createElement('aside', { style: styles.panel, onMouseDown: (event) => { event.stopPropagation(); setToolsOpen(false) }, role: 'dialog', 'aria-modal': true, 'aria-label': '移动设备管理' },
           React.createElement('div', { style: styles.header },
             React.createElement('div', null,
               React.createElement('h2', { style: styles.title }, '移动设备'),
               React.createElement('div', { style: styles.muted }, status && status.gatewayEnabled ? '移动网关已开启 · 设备鉴权生效中' : '移动网关已关闭 · 普通 WebUI 模式')),
-            React.createElement('button', { style: styles.button, onClick: () => setOpen(false), 'aria-label': '关闭' }, '✕')),
+            React.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: 6 } },
+              React.createElement('div', { style: { position: 'relative' }, onMouseDown: (event) => event.stopPropagation() },
+                React.createElement('button', {
+                  type: 'button', style: { ...styles.button, ...styles.headerButton, borderRadius: '50%' }, title: '工具', 'aria-label': '工具',
+                  'aria-haspopup': 'menu', 'aria-expanded': toolsOpen,
+                  onClick: () => setToolsOpen((value) => !value),
+                }, React.createElement('svg', { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.8, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': true },
+                  React.createElement('path', { d: 'M10.3 2.8h3.4l.5 2.2a7.6 7.6 0 0 1 1.7.7l1.9-1.2 2.4 2.4L19 8.8c.3.5.5 1.1.7 1.7l2.2.5v3.4l-2.2.5a7.6 7.6 0 0 1-.7 1.7l1.2 1.9-2.4 2.4-1.9-1.2a7.6 7.6 0 0 1-1.7.7l-.5 2.2h-3.4l-.5-2.2a7.6 7.6 0 0 1-1.7-.7l-1.9 1.2-2.4-2.4L5 16.6a7.6 7.6 0 0 1-.7-1.7l-2.2-.5V11l2.2-.5A7.6 7.6 0 0 1 5 8.8L3.8 6.9l2.4-2.4 1.9 1.2a7.6 7.6 0 0 1 1.7-.7l.5-2.2Z' }),
+                  React.createElement('circle', { cx: 12, cy: 12.7, r: 3.1 }))),
+                toolsOpen ? React.createElement('div', { style: styles.toolsMenu, role: 'menu', 'aria-label': '网关工具' },
+                  React.createElement('button', {
+                    type: 'button', role: 'menuitem', disabled: toolBusy || stoppedRef.current || !status?.tools?.restartWeb,
+                    style: { ...styles.toolsItem, opacity: status?.tools?.restartWeb ? 1 : .5 },
+                    onClick: () => runTool('restart-web'),
+                  }, '重启当前网关',
+                  React.createElement('span', { style: { ...styles.muted, display: 'block', marginTop: 2 } }, '结束当前进程并重新启动 DSH Web')),
+                  React.createElement('button', {
+                    type: 'button', role: 'menuitem', disabled: toolBusy || stoppedRef.current || !status?.tools?.stopWeb,
+                    style: { ...styles.toolsItem, color: colors.danger, opacity: status?.tools?.stopWeb ? 1 : .5 },
+                    onClick: () => runTool('stop-web'),
+                  }, '停止 DSH Web',
+                  React.createElement('span', { style: { ...styles.muted, display: 'block', marginTop: 2 } }, '结束后台进程，所有连接将断开')))
+                  : null),
+              React.createElement('button', { style: { ...styles.button, ...styles.headerButton }, onClick: () => setOpen(false), 'aria-label': '关闭' }, '✕'))),
+          toolNotice ? React.createElement('div', { style: { ...styles.muted, marginBottom: 10 } }, toolNotice) : null,
           error ? React.createElement('div', { style: styles.error }, error) : null,
           React.createElement('section', { style: styles.card },
             React.createElement('div', { style: { display: 'flex', justifyContent: 'space-between', gap: 14, alignItems: 'center' } },
@@ -373,7 +541,35 @@ window.__ModuleLoader__.load({
             status && !status.requireAuth
               ? React.createElement('p', { style: { ...styles.error, margin: '12px 0 0' } }, 'Debug 模式：本机 DSH 入口将跳过设备凭证校验；独立局域网入口仍强制鉴权。')
               : null),
-          React.createElement('section', { style: styles.card },
+          status && status.cloudflare && status.cloudflare.supported
+            ? React.createElement('section', { style: styles.card },
+                React.createElement('strong', null, 'Cloudflare Tunnel · PC 外网接入'),
+                React.createElement('p', { style: styles.muted }, '首次开启时自动下载并校验 cloudflared；公网入口只接受已鉴权的移动 WebSocket。'),
+                React.createElement('label', { style: styles.label }, '接入方式'),
+                React.createElement('select', { style: styles.input, value: cloudflareMode, onChange: (event) => setCloudflareMode(event.target.value), disabled: cloudflareBusy },
+                  React.createElement('option', { value: 'quick' }, 'Quick Tunnel · 无需域名'),
+                  React.createElement('option', { value: 'named' }, '命名 Tunnel · 固定域名')),
+                cloudflareMode === 'quick'
+                  ? React.createElement('p', { style: styles.muted }, 'Cloudflare 会分配随机地址；DSH 重启或隧道重连后地址可能改变，手机需重新扫码确认新地址。适合临时使用。')
+                  : React.createElement(React.Fragment, null,
+                      React.createElement('p', { style: styles.muted }, '先在 Cloudflare 创建命名 Tunnel，把公开域名的 Service URL 设为 ', React.createElement('code', null, `http://127.0.0.1:${status.cloudflare.port}`), '。'),
+                      React.createElement('label', { style: styles.label }, '公开域名'),
+                      React.createElement('input', { style: styles.input, value: cloudflareHost, onChange: (event) => setCloudflareHost(event.target.value.trim()), placeholder: 'gateway.example.com', spellCheck: false }),
+                      React.createElement('label', { style: styles.label }, 'Tunnel Token'),
+                      React.createElement('input', { style: styles.input, type: 'password', value: cloudflareToken, onChange: (event) => setCloudflareToken(event.target.value.trim()), placeholder: status.cloudflare.configured ? '已保存；留空则保持原 Token' : '粘贴 eyJ… Token', autoComplete: 'off', spellCheck: false })),
+                React.createElement('button', {
+                  style: { ...styles.button, ...styles.primary, opacity: cloudflareBusy || (cloudflareMode === 'named' && (!cloudflareHost || (!cloudflareToken && !status.cloudflare.configured))) ? .65 : 1 },
+                  disabled: cloudflareBusy || (cloudflareMode === 'named' && (!cloudflareHost || (!cloudflareToken && !status.cloudflare.configured))),
+                  onClick: () => configureCloudflare(true),
+                }, cloudflareBusy ? '正在处理…' : status.cloudflare.enabled && cloudflareMode === status.cloudflare.mode ? '更新 Tunnel 配置' : cloudflareMode === 'quick' ? '一键开启 Quick Tunnel' : '开启命名 Tunnel'),
+                status.cloudflare.enabled
+                  ? React.createElement('button', { style: { ...styles.button, width: '100%', marginTop: 8 }, disabled: cloudflareBusy, onClick: () => configureCloudflare(false) }, '关闭 Cloudflare Tunnel')
+                  : null,
+                React.createElement('div', { style: { ...styles.muted, marginTop: 9, overflowWrap: 'anywhere', color: status.cloudflare.error ? colors.danger : colors.muted } },
+                  status.cloudflare.error || ({ disabled: '未开启', starting: '正在启动本机入口…', preparing: '正在准备 cloudflared（首次需下载）…', connecting: '正在连接 Cloudflare…', online: '已连接 Cloudflare', 'waiting-for-gateway': '等待移动网关开启' }[status.cloudflare.state] || status.cloudflare.state),
+                  status.cloudflare.publicUrl ? ` · ${status.cloudflare.publicUrl}` : ''))
+              : null,
+          status && status.platform === 'linux' ? React.createElement('section', { style: styles.card },
             React.createElement('strong', null, '公网接入'),
             publicSetup === null
               ? React.createElement('p', { style: styles.muted }, '正在检查系统组件…')
@@ -403,10 +599,46 @@ window.__ModuleLoader__.load({
                       : null)
                 : React.createElement(React.Fragment, null,
                     React.createElement('p', { style: { ...styles.muted, marginBottom: 8 } }, '尚未安装系统 Helper。请在服务器执行一次初始化：'),
-                    React.createElement('code', { style: { display: 'block', fontSize: 10, lineHeight: 1.5, overflowWrap: 'anywhere', userSelect: 'all' } }, 'npx --yes dsh-plugin-mobile-gateway@latest init'))),
+                    React.createElement('code', { style: { display: 'block', fontSize: 10, lineHeight: 1.5, overflowWrap: 'anywhere', userSelect: 'all' } }, 'npx --yes dsh-plugin-mobile-gateway@latest init'))) : null,
           React.createElement('section', { style: styles.card },
+            React.createElement('div', { style: { position: 'relative', display: 'flex', alignItems: 'center', gap: 6, marginBottom: 6 }, onMouseLeave: () => setConnectionHelpOpen(false) },
+              React.createElement('span', { style: { ...styles.label, marginBottom: 0 } }, '配对连接方式'),
+              React.createElement('button', {
+                type: 'button',
+                style: styles.helpButton,
+                'aria-label': '连接方式说明与场景建议',
+                'aria-expanded': connectionHelpOpen,
+                'aria-describedby': connectionHelpOpen ? 'mgw-route-help' : undefined,
+                onMouseEnter: () => setConnectionHelpOpen(true),
+                onFocus: () => setConnectionHelpOpen(true),
+                onBlur: () => setConnectionHelpOpen(false),
+                onClick: () => setConnectionHelpOpen(true),
+                onKeyDown: (event) => { if (event.key === 'Escape') setConnectionHelpOpen(false) },
+              }, '?'),
+              connectionHelpOpen ? React.createElement('div', { id: 'mgw-route-help', role: 'tooltip', style: styles.helpBubble },
+                React.createElement('strong', null, '怎么选连接方式'),
+                helpLine('局域网直连', '手机与 DSH 在同一个可互访的局域网，使用 ws:// 私有地址；离开该网络就无法直连。'),
+                helpLine('Cloudflare Channel（命名 Tunnel）', 'PC 主动连接 Cloudflare，外网用固定域名的 wss://；需要 Cloudflare 账户和域名。'),
+                helpLine('Quick Channel（Quick Tunnel）', '无需账户或域名，Cloudflare 分配临时 wss:// 地址；隧道重建后地址可能变化。'),
+                helpLine('公网服务器连接', 'DSH 运行在有固定公网 IPv4 的 Linux 服务器上，配置公网入口后用 wss:// 公网 IP 连接。'),
+                React.createElement('div', { style: { borderTop: '1px solid rgba(255,255,255,.18)', marginTop: 10, paddingTop: 8 } },
+                  React.createElement('strong', null, '结合当前环境'),
+                  React.createElement('div', { style: { color: '#c6cbd4', marginTop: 4 } }, advice.detected),
+                  React.createElement('div', { style: { marginTop: 6 } }, advice.local),
+                  React.createElement('div', { style: { marginTop: 6 } }, advice.remote),
+                  React.createElement('div', { style: { color: '#aeb6c3', marginTop: 6 } }, '面板无法判断手机当前网络；请按手机所在位置选择，提示不会替你修改选择。')))
+                : null),
+            React.createElement('select', { style: styles.input, value: pairingRoute, onChange: (event) => choosePairingRoute(event.target.value), disabled: !status, 'aria-label': '配对连接方式' },
+              React.createElement('option', { value: 'auto' }, '自动选择 · 优先外网'),
+              lanPairingUrl(status) || pairingRoute === 'lan'
+                ? React.createElement('option', { value: 'lan', disabled: !lanPairingUrl(status) }, lanPairingUrl(status)
+                  ? '局域网直连 · ' + lanPairingUrl(status).replace(/^wss?:\/\//, '').split('/')[0]
+                  : '局域网直连 · 当前不可用')
+                : null,
+              status?.cloudflare?.enabled ? React.createElement('option', { value: 'cloudflare' }, 'Cloudflare 外网') : null,
+              React.createElement('option', { value: 'custom' }, '手动输入地址')),
             React.createElement('label', { style: styles.label }, 'WebSocket 地址'),
-            React.createElement('input', { style: styles.input, value: publicUrl, onChange: (event) => { automaticUrlRef.current = ''; setPublicUrl(event.target.value) }, placeholder: 'ws://192.168.1.10:3081/ws/mobile', spellCheck: false }),
+            React.createElement('input', { style: styles.input, value: publicUrl, onChange: (event) => { choosePairingRoute('custom'); setPublicUrl(event.target.value) }, placeholder: 'ws://192.168.1.10:3081/ws/mobile', spellCheck: false }),
             status && status.lan && status.lan.enabled
               ? React.createElement('div', { style: { ...styles.muted, margin: '-7px 0 10px', color: status.lan.error ? colors.danger : colors.muted } },
                   status.lan.error
@@ -417,8 +649,12 @@ window.__ModuleLoader__.load({
               : null,
             React.createElement('label', { style: styles.label }, '设备名称'),
             React.createElement('input', { style: styles.input, value: deviceName, onChange: (event) => setDeviceName(event.target.value), maxLength: 80, placeholder: 'iPhone' }),
-            React.createElement('button', { style: { ...styles.button, ...styles.primary, opacity: busy || !(status && status.gatewayEnabled) ? .65 : 1 }, disabled: busy || !(status && status.gatewayEnabled), onClick: pair }, busy ? '正在生成…' : status && status.gatewayEnabled ? '生成配对二维码' : '请先开启移动网关'),
-            React.createElement('p', { style: { ...styles.muted, margin: '10px 0 0' } }, '同一局域网可直接使用私有地址的 ws://；公网地址仍必须使用 wss://。配对码只能使用一次，并在 5 分钟内过期。')),
+            React.createElement('button', {
+              style: { ...styles.button, ...styles.primary, opacity: busy || !(status && status.gatewayEnabled) || !publicUrl.trim() ? .65 : 1 },
+              disabled: busy || !(status && status.gatewayEnabled) || !publicUrl.trim(),
+              onClick: pair,
+            }, busy ? '正在生成…' : !(status && status.gatewayEnabled) ? '请先开启移动网关' : !publicUrl.trim() ? '等待连接地址' : '生成配对二维码'),
+            React.createElement('p', { style: { ...styles.muted, margin: '10px 0 0' } }, '同一局域网选择“局域网直连”，无需关闭 Cloudflare Tunnel。局域网使用私有地址的 ws://；公网地址必须使用 wss://。配对码只能使用一次，并在 5 分钟内过期。')),
           qr ? React.createElement('section', { style: { ...styles.card, textAlign: 'center' } },
             React.createElement('strong', null, '使用 iOS 客户端扫码'),
             React.createElement('img', { style: styles.qr, src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(qr.svg)}`, alt: '一次性设备配对二维码' }),

package/lib/cloudflare-tunnel.mjs

@@ -0,0 +1,268 @@
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { ensureCloudflared } from './cloudflared-binary.mjs'
+
+function hostnameOf(value) {
+  if (typeof value !== 'string') throw new TypeError('Cloudflare hostname is required')
+  const hostname = value.trim().toLowerCase()
+  if (hostname.length > 253 || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(hostname) ||
+      !hostname.includes('.') || hostname.includes('..') ||
+      hostname.split('.').some((label) => label.length > 63 || label.startsWith('-') || label.endsWith('-'))) {
+    throw new TypeError('Cloudflare hostname must be a domain name, for example gateway.example.com')
+  }
+  return hostname
+}
+
+function tokenOf(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 8192 || /\s/.test(value)) {
+    throw new TypeError('Cloudflare Tunnel Token must be a nonempty token without whitespace')
+  }
+  return value
+}
+
+function readState(file) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (value?.version !== 1 || typeof value.enabled !== 'boolean' ||
+        typeof value.hostname !== 'string' || typeof value.token !== 'string') {
+      throw new TypeError('invalid Cloudflare Tunnel settings')
+    }
+    if (value.hostname) hostnameOf(value.hostname)
+    if (value.token) tokenOf(value.token)
+    value.mode ??= 'named'
+    if (!['named', 'quick'].includes(value.mode)) throw new TypeError('invalid Cloudflare Tunnel mode')
+    if (value.enabled && value.mode === 'named' && (!value.hostname || !value.token)) {
+      throw new TypeError('enabled named tunnel has no hostname or token')
+    }
+    fs.chmodSync(file, 0o600)
+    return value
+  } catch (error) {
+    if (error.code === 'ENOENT') return { version: 1, enabled: false, mode: 'quick', hostname: '', token: '' }
+    throw new Error(`failed to load Cloudflare Tunnel settings ${file}: ${error.message}`, { cause: error })
+  }
+}
+
+function writeState(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' })
+    fs.renameSync(temporary, file)
+    fs.chmodSync(file, 0o600)
+  } finally {
+    fs.rmSync(temporary, { force: true })
+  }
+}
+
+// A separate loopback listener exposes only the mobile WebSocket. In particular,
+// Cloudflare can never reach the DSH WebUI or the /mgw management API through it.
+export function createCloudflareTunnel({ file, port = 3082, wsPath, executable = 'cloudflared',
+  supported = true, isGatewayEnabled, onUpgrade, log = () => {}, spawnProcess = spawn,
+  prepareExecutable = ensureCloudflared }) {
+  let settings = supported ? readState(file) : { version: 1, enabled: false, mode: 'quick', hostname: '', token: '' }
+  let server = null
+  let child = null
+  let preparing = null
+  let retryTimer = null
+  let disposed = false
+  let phase = 'disabled'
+  let error = null
+  let quickUrl = null
+  let queue = Promise.resolve()
+  const sockets = new Set()
+
+  const shouldRun = () => supported && !disposed && settings.enabled && isGatewayEnabled()
+  const publicUrl = () => settings.mode === 'quick'
+    ? quickUrl
+    : settings.hostname ? `wss://${settings.hostname}${wsPath}` : null
+  const snapshot = () => ({
+    supported,
+    enabled: settings.enabled,
+    mode: settings.mode,
+    configured: !!(settings.hostname && settings.token),
+    hostname: settings.hostname || null,
+    publicUrl: settings.enabled ? publicUrl() : null,
+    port,
+    state: !settings.enabled ? 'disabled' : !isGatewayEnabled() ? 'waiting-for-gateway' : phase,
+    error,
+  })
+
+  const stop = async () => {
+    if (retryTimer) clearTimeout(retryTimer)
+    retryTimer = null
+    const previous = child
+    child = null
+    if (previous && !previous.killed) previous.kill()
+    quickUrl = null
+    for (const socket of sockets) socket.destroy()
+    sockets.clear()
+    const listener = server
+    server = null
+    phase = 'disabled'
+    error = null
+    if (listener) await new Promise((resolve) => listener.close(resolve))
+  }
+
+  const startChild = () => {
+    if (!shouldRun() || !server || child || preparing) return
+    phase = 'preparing'
+    error = null
+    preparing = prepareExecutable({ cacheDir: path.join(path.dirname(file), 'cloudflared-bin'), executable })
+      .then((binary) => {
+        preparing = null
+        if (!shouldRun() || !server || child) return
+        phase = 'connecting'
+        const quick = settings.mode === 'quick'
+        const args = quick
+          ? ['tunnel', '--no-autoupdate', '--loglevel', 'info', '--url', `http://127.0.0.1:${port}`]
+          : ['tunnel', '--no-autoupdate', '--loglevel', 'info', 'run']
+        const childEnv = { ...process.env }
+        delete childEnv.TUNNEL_TOKEN
+        if (!quick) childEnv.TUNNEL_TOKEN = settings.token
+        const running = spawnProcess(binary, args, {
+          env: childEnv,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          windowsHide: true,
+        })
+        child = running
+        let diagnostics = ''
+        let outputTail = ''
+        let registered = false
+        const onOutput = (chunk) => {
+          if (child !== running) return
+          const lines = chunk.toString().slice(0, 4096)
+          outputTail = (outputTail + lines).slice(-4096)
+          if (quick) {
+            const match = /https:\/\/([a-z0-9-]+)\.trycloudflare\.com\b/i.exec(outputTail)
+            if (match) quickUrl = `wss://${match[1].toLowerCase()}.trycloudflare.com${wsPath}`
+          }
+          if (/Registered tunnel connection/i.test(outputTail)) {
+            registered = true
+            outputTail = ''
+          } else if (/ERR|error/i.test(lines)) {
+            diagnostics = (settings.token ? outputTail.replaceAll(settings.token, '[redacted]') : outputTail)
+              .replace(/eyJ[A-Za-z0-9._=-]+/g, '[redacted]').trim().slice(-500)
+          }
+          if (registered && (!quick || quickUrl)) {
+            phase = 'online'
+            error = null
+          }
+        }
+        running.stderr?.on('data', onOutput)
+        running.stdout?.on('data', onOutput)
+        const exited = (reason) => {
+          if (child !== running) return
+          child = null
+          quickUrl = null
+          phase = 'error'
+          error = reason || diagnostics || 'cloudflared exited unexpectedly'
+          log(`Cloudflare Tunnel stopped: ${error}`)
+          if (shouldRun()) retryTimer = setTimeout(() => { retryTimer = null; startChild() }, 10_000)
+        }
+        running.once('error', (cause) => exited(cause.code === 'ENOENT'
+          ? 'cloudflared is not installed or is not on PATH'
+          : `cloudflared failed: ${cause.message}`))
+        running.once('exit', (code, signal) => exited(diagnostics || `cloudflared exited (${signal || code})`))
+      })
+      .catch((cause) => {
+        preparing = null
+        if (!shouldRun()) return
+        phase = 'error'
+        error = `Cloudflare binary preparation failed: ${cause.message}`
+        log(error)
+        retryTimer = setTimeout(() => { retryTimer = null; startChild() }, 30_000)
+      })
+  }
+
+  const start = async () => {
+    if (server || !shouldRun()) return
+    phase = 'starting'
+    error = null
+    const listener = http.createServer((_req, res) => {
+      res.writeHead(404, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' })
+      res.end('Not found')
+    })
+    listener.on('connection', (socket) => {
+      sockets.add(socket)
+      socket.on('close', () => sockets.delete(socket))
+    })
+    listener.on('upgrade', (req, socket, head) => {
+      let pathname
+      try { pathname = new URL(req.url || '/', 'http://localhost').pathname } catch { pathname = '' }
+      if (pathname !== wsPath) {
+        socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n')
+        return
+      }
+      onUpgrade(req, socket, head, { lan: true, port })
+    })
+    try {
+      await new Promise((resolve, reject) => {
+        listener.once('error', reject)
+        listener.listen(port, '127.0.0.1', () => {
+          listener.off('error', reject)
+          resolve()
+        })
+      })
+      if (!shouldRun()) {
+        listener.close()
+        return
+      }
+      server = listener
+      listener.on('error', (cause) => {
+        const message = `Cloudflare origin listener failed: ${cause.message}`
+        void stop().then(() => {
+          if (!shouldRun()) return
+          phase = 'error'
+          error = message
+          log(message)
+          retryTimer = setTimeout(() => { retryTimer = null; void reconcile() }, 10_000)
+        })
+      })
+      startChild()
+    } catch (cause) {
+      try { listener.close() } catch { /* The listener never opened. */ }
+      if (shouldRun()) {
+        phase = 'error'
+        error = `Cloudflare origin listener failed: ${cause.message}`
+        log(error)
+        retryTimer = setTimeout(() => { retryTimer = null; void reconcile() }, 10_000)
+      }
+    }
+  }
+
+  const reconcile = () => {
+    queue = queue.catch(() => {}).then(async () => {
+      if (shouldRun()) await start()
+      else await stop()
+    })
+    return queue
+  }
+
+  const configure = async ({ enabled, mode, hostname, token }) => {
+    if (!supported) throw new TypeError('Cloudflare Tunnel is available on PC only')
+    if (typeof enabled !== 'boolean') throw new TypeError('enabled must be a boolean')
+    const next = {
+      version: 1,
+      enabled,
+      mode: mode === undefined ? settings.mode : mode,
+      hostname: hostname === undefined ? settings.hostname : hostnameOf(hostname),
+      token: token === undefined || token === '' ? settings.token : tokenOf(token),
+    }
+    if (!['named', 'quick'].includes(next.mode)) throw new TypeError('mode must be named or quick')
+    if (enabled && next.mode === 'named' && (!next.hostname || !next.token)) {
+      throw new TypeError('hostname and Tunnel Token are required')
+    }
+    const changed = next.mode !== settings.mode || next.hostname !== settings.hostname || next.token !== settings.token
+    writeState(file, next)
+    settings = next
+    if (changed) await stop()
+    await reconcile()
+    return snapshot()
+  }
+
+  const dispose = () => { disposed = true; void stop() }
+  return { snapshot, configure, reconcile, dispose }
+}