dsh-plugin-mobile-gateway 0.7.7 → 0.9.0

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,49 @@ 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 restartCloudflare = async () => {
+        if (cloudflareBusy) return
+        setCloudflareBusy(true)
+        setError(null)
+        try {
+          const data = await request('/mgw/cloudflare/restart', { method: 'POST' })
+          if (data.mode === 'quick') setQr(null)
+          setStatus((current) => ({ ...(current || {}), cloudflare: data }))
+          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 +468,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 +557,38 @@ 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(React.Fragment, null,
+                      React.createElement('button', { style: { ...styles.button, width: '100%', marginTop: 8 }, disabled: cloudflareBusy || !status.gatewayEnabled, onClick: restartCloudflare }, '重启 Tunnel'),
+                      React.createElement('button', { style: { ...styles.button, width: '100%', marginTop: 8 }, disabled: cloudflareBusy, onClick: () => configureCloudflare(false) }, '关闭 Cloudflare Tunnel'),
+                      React.createElement('p', { style: styles.muted }, '重启会短暂断开手机连接；Quick 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 +618,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 +668,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: '一次性设备配对二维码' }),