dsh-plugin-mobile-gateway 0.3.0 → 0.4.0

package/README.md

@@ -24,7 +24,7 @@ dsh plugin --profile web add dsh-plugin-mobile-gateway
 如果希望固定版本，可以在包名后指定版本号：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@0.3.0
+dsh plugin --profile web add dsh-plugin-mobile-gateway@0.4.0
 ```
 
 也可以不经过 npm，直接安装 GitHub 版本：
@@ -45,7 +45,46 @@ dsh --profile web --dump-config | grep -A3 mobile-gateway
 
 启动 WebUI 后，左侧边栏底部应出现“移动设备”入口。
 
-### 3. 配置手机可访问的 WebSocket 地址
+### 3. 一条命令配置公网 IP（推荐，无需域名）
+
+如果 Harness 部署在带固定公网 IPv4 的腾讯云 Ubuntu/Debian 服务器上，先在腾讯云安全组中放行入站 TCP `80` 和 `443`，然后在服务器执行：
+
+```bash
+sudo npx --yes dsh-plugin-mobile-gateway setup
+```
+
+安装器会自动从腾讯云实例元数据读取公网 IPv4，并完成：
+
+- 安装 Nginx 和独立 Python 虚拟环境中的 Certbot
+- 为公网 IP 申请受系统信任的短期 TLS 证书
+- 只把 `wss://公网IP/ws/mobile` 代理到 `127.0.0.1:3080`
+- 对普通 HTTP、WebUI、`/mgw/*` 管理接口和其他路径返回 `404`
+- 创建每天两次运行的 systemd 证书续期任务
+- 把公网地址写入 `/etc/dsh-mobile-gateway/public-url`，插件启动时自动读取
+
+因此 DSH 仍然只需监听 `127.0.0.1:3080`，不需要把 3080 端口暴露到公网，也不需要 Tunnel、域名或手写 Nginx 配置。
+
+邮箱是可选项；希望接收 Let's Encrypt 账户通知时可追加 `--email you@example.com`。如果无法从腾讯云元数据识别公网地址，或 DSH 使用了其他本地端口：
+
+```bash
+sudo npx --yes dsh-plugin-mobile-gateway setup \
+  --ip 203.0.113.10 \
+  --port 3080 \
+  --email you@example.com
+```
+
+执行完成后重启 `dsh web`，打开 WebUI 的“移动设备”面板。公网 WebSocket 地址会自动显示为 `wss://公网IP/ws/mobile`；开启移动网关并生成二维码即可。
+
+查看状态或移除安装器生成的公网入口：
+
+```bash
+sudo npx --yes dsh-plugin-mobile-gateway status
+sudo npx --yes dsh-plugin-mobile-gateway remove
+```
+
+`remove` 只删除本插件生成的 Nginx 配置、地址文件和续期任务，不卸载软件，也不删除已有证书。IP 证书有效期约 6 天，必须保持 80 端口可达以便自动续期。相关能力来自 [Let's Encrypt 的短期 IP 地址证书](https://letsencrypt.org/2026/03/11/shorter-certs-certbot/)；公网 IP 自动识别使用[腾讯云实例元数据](https://cloud.tencent.com/document/product/213/17940)。
+
+#### 已有域名或反向代理
 
 打开“移动设备”面板：
 
@@ -130,9 +169,9 @@ dsh plugin --profile web remove dsh-plugin-mobile-gateway
 
 卸载插件不会自动删除 `~/.dsh/mobile-gateway-devices.json`。
 
-## 公网部署
+## 手动公网部署
 
-DSH HTTP Server 本身不负责 TLS。公网入口应由 Nginx、Caddy 或其他反向代理提供 HTTPS/WSS，并且只公开 WebSocket 路由，不要公开 `/mgw` 管理接口或整个未鉴权 WebUI。
+不使用一键安装器时，公网入口应由 Nginx、Caddy 或其他反向代理提供 HTTPS/WSS，并且只公开 WebSocket 路由，不要公开 `/mgw` 管理接口或整个未鉴权 WebUI。
 
 Nginx 核心配置示例：
 
@@ -158,6 +197,7 @@ TLS 证书、域名、防火墙、访问日志保护和代理层速率限制由
     requireAuth: true
     adminLoopbackOnly: true
     publicUrl: wss://gateway.example.com/ws/mobile
+    publicUrlFile: /etc/dsh-mobile-gateway/public-url
     pairingTtlMs: 300000
     allowQueryToken: false
 ```
@@ -172,6 +212,9 @@ TLS 证书、域名、防火墙、访问日志保护和代理层速率限制由
 | iOS 连接提示 `503` | 移动网关尚未开启，回到 WebUI 开启“允许移动设备连接” |
 | iOS 连接提示 `401` | 配对码过期、长期凭证无效或设备已被吊销；删除客户端旧凭证后重新配对 |
 | 真机无法连接 `127.0.0.1` | `127.0.0.1` 在手机上不是电脑；配置手机可访问的 `wss://` 地址 |
+| 一键配置无法识别公网 IP | 确认命令运行在腾讯云 CVM 内，或通过 `--ip <公网 IPv4>` 显式指定 |
+| Certbot 申请或续期失败 | 确认腾讯云安全组和服务器防火墙都允许入站 TCP 80/443，并确认公网 IP 没有变化 |
+| 想检查自动续期 | 执行 `sudo systemctl status dsh-mobile-gateway-cert-renew.timer` 和 `sudo npx --yes dsh-plugin-mobile-gateway status` |
 | 二维码无法再次使用 | 配对码设计为一次性且 5 分钟过期，重新生成即可 |
 | 修改配置后没有生效 | 插件与 profile composition 在启动时加载，需要重启 WebUI 进程 |
 | 需要排查服务端原因 | 查看 `/tmp/mobile-gateway.log`，其中包含连接、鉴权、查询与错误记录 |
@@ -201,6 +244,9 @@ NODE_PATH=/path/to/dsh/node_modules node test/auth.test.mjs
 
 # mock Harness + 真实 WebSocket 客户端的完整协议链路
 NODE_PATH=/path/to/dsh/node_modules node test/gateway.test.mjs
+
+# 公网 IP 安装器的参数、Nginx 隔离与续期配置
+node test/setup-ip.test.mjs
 ```
 
 版本历史与全部 WebSocket 消息类型见 [`PROTOCOL.md`](PROTOCOL.md)。

package/bin/setup-ip.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import http from 'node:http'
+import net from 'node:net'
+import path from 'node:path'
+import process from 'node:process'
+import readline from 'node:readline/promises'
+import { execFileSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+
+const MARKER = '# Managed by dsh-plugin-mobile-gateway'
+const CONFIG_DIR = '/etc/dsh-mobile-gateway'
+const PUBLIC_URL_FILE = path.join(CONFIG_DIR, 'public-url')
+const WEBROOT = '/var/lib/dsh-mobile-gateway/acme'
+const NGINX_CONFIG = '/etc/nginx/conf.d/dsh-mobile-gateway.conf'
+const CERTBOT_HOME = '/opt/dsh-mobile-gateway/certbot'
+const CERTBOT = path.join(CERTBOT_HOME, 'bin/certbot')
+const RENEW_SERVICE = '/etc/systemd/system/dsh-mobile-gateway-cert-renew.service'
+const RENEW_TIMER = '/etc/systemd/system/dsh-mobile-gateway-cert-renew.timer'
+
+function printHelp() {
+  console.log(`Usage:
+  dsh-plugin-mobile-gateway setup [--ip <public IPv4>] [--port 3080] [--email <address>] [--yes]
+  dsh-plugin-mobile-gateway status
+  dsh-plugin-mobile-gateway remove [--yes]
+
+The setup command supports Ubuntu/Debian servers. It keeps DSH on 127.0.0.1,
+publishes only /ws/mobile through Nginx on 443, obtains a short-lived trusted
+Let's Encrypt IP certificate, and installs automatic renewal.`)
+}
+
+function parseArgs(argv) {
+  const command = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'setup'
+  const values = { command, port: 3080, yes: false, ip: '', email: '' }
+  const args = command === argv[0] ? argv.slice(1) : argv
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--yes' || arg === '-y') values.yes = true
+    else if (arg === '--ip') values.ip = args[++index] || ''
+    else if (arg === '--port') values.port = Number(args[++index])
+    else if (arg === '--email') values.email = args[++index] || ''
+    else if (arg === '--help' || arg === '-h') values.command = 'help'
+    else throw new Error(`unknown argument: ${arg}`)
+  }
+  return values
+}
+
+function run(command, args, options = {}) {
+  console.log(`\n> ${command} ${args.join(' ')}`)
+  return execFileSync(command, args, { stdio: 'inherit', ...options })
+}
+
+function commandExists(command) {
+  try {
+    execFileSync('sh', ['-c', `command -v "$1" >/dev/null 2>&1`, 'sh', command], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function writeManagedFile(file, content, mode = 0o644) {
+  if (fs.existsSync(file)) {
+    const existing = fs.readFileSync(file, 'utf8')
+    if (!existing.startsWith(MARKER)) {
+      throw new Error(`refusing to overwrite unmanaged file: ${file}`)
+    }
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o755 })
+  const temporary = `${file}.tmp-${process.pid}`
+  fs.writeFileSync(temporary, content, { mode })
+  fs.renameSync(temporary, file)
+  fs.chmodSync(file, mode)
+}
+
+function metadataPublicIp() {
+  return new Promise((resolve) => {
+    const request = http.get({
+      host: 'metadata.tencentyun.com',
+      path: '/latest/meta-data/public-ipv4',
+      timeout: 2_500,
+      headers: { 'User-Agent': 'dsh-mobile-gateway-setup' },
+    }, (response) => {
+      let body = ''
+      response.setEncoding('utf8')
+      response.on('data', (chunk) => { body += chunk })
+      response.on('end', () => resolve(response.statusCode === 200 ? body.trim() : ''))
+    })
+    request.on('timeout', () => request.destroy())
+    request.on('error', () => resolve(''))
+  })
+}
+
+function assertPublicIpv4(value) {
+  if (net.isIP(value) !== 4) throw new Error(`invalid public IPv4 address: ${value || '(empty)'}`)
+  const octets = value.split('.').map(Number)
+  const privateAddress = octets[0] === 10
+    || octets[0] === 127
+    || (octets[0] === 169 && octets[1] === 254)
+    || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31)
+    || (octets[0] === 192 && octets[1] === 168)
+    || octets[0] === 0
+    || octets[0] >= 224
+  if (privateAddress) throw new Error(`${value} is not a public IPv4 address`)
+}
+
+function certName(ip) {
+  return `dsh-mobile-gateway-${ip.replaceAll('.', '-')}`
+}
+
+function nginxHttpConfig(ip) {
+  return `${MARKER}
+server {
+    listen 80;
+    server_name ${ip};
+
+    location ^~ /.well-known/acme-challenge/ {
+        root ${WEBROOT};
+        default_type text/plain;
+    }
+
+    location / { return 404; }
+}
+`
+}
+
+function nginxTlsConfig(ip, backendPort) {
+  const liveDirectory = `/etc/letsencrypt/live/${certName(ip)}`
+  return `${nginxHttpConfig(ip)}
+server {
+    listen 443 ssl;
+    server_name ${ip};
+    server_tokens off;
+    access_log off;
+
+    ssl_certificate ${liveDirectory}/fullchain.pem;
+    ssl_certificate_key ${liveDirectory}/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    location = /ws/mobile {
+        if ($args != "") { return 404; }
+        proxy_pass http://127.0.0.1:${backendPort};
+        proxy_http_version 1.1;
+        proxy_set_header Host 127.0.0.1:${backendPort};
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_buffering off;
+    }
+
+    location / { return 404; }
+}
+`
+}
+
+function renewalService() {
+  return `${MARKER}
+[Unit]
+Description=Renew the DSH mobile gateway IP certificate
+After=network-online.target nginx.service
+
+[Service]
+Type=oneshot
+ExecStart=${CERTBOT} renew --quiet --deploy-hook /bin/systemctl reload nginx
+`
+}
+
+function renewalTimer() {
+  return `${MARKER}
+[Unit]
+Description=Twice-daily renewal check for the DSH mobile gateway IP certificate
+
+[Timer]
+OnCalendar=*-*-* 00,12:00:00
+RandomizedDelaySec=20m
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`
+}
+
+async function confirm(message, assumeYes) {
+  if (assumeYes) return true
+  if (!process.stdin.isTTY) throw new Error('interactive confirmation is unavailable; rerun with --yes')
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await terminal.question(`${message} [y/N] `)
+  terminal.close()
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+function assertRoot() {
+  if (typeof process.getuid === 'function' && process.getuid() !== 0) {
+    throw new Error('setup/remove must run as root; prepend sudo to the command')
+  }
+}
+
+async function setup(options) {
+  assertRoot()
+  if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) throw new Error(`invalid backend port: ${options.port}`)
+  if (options.email && !/^\S+@\S+\.\S+$/.test(options.email)) throw new Error(`invalid email address: ${options.email}`)
+  if (!commandExists('apt-get') || !commandExists('systemctl')) {
+    throw new Error('automatic setup currently supports systemd-based Ubuntu/Debian servers only')
+  }
+
+  const ip = options.ip || await metadataPublicIp()
+  if (!ip) throw new Error('unable to detect a Tencent Cloud public IP; rerun with --ip <public IPv4>')
+  assertPublicIpv4(ip)
+
+  console.log(`
+Public IPv4: ${ip}
+DSH backend: http://127.0.0.1:${options.port}
+Public endpoint: wss://${ip}/ws/mobile
+
+Before continuing, open inbound TCP ports 80 and 443 in the Tencent Cloud
+security group. Only /ws/mobile will be proxied; the WebUI and /mgw remain private.`)
+  if (!await confirm('Install Nginx/Certbot and configure this public endpoint?', options.yes)) {
+    console.log('Cancelled.')
+    return
+  }
+
+  run('apt-get', ['update'])
+  run('apt-get', ['install', '-y', 'nginx', 'python3', 'python3-venv'])
+  if (!fs.existsSync(CERTBOT)) {
+    run('python3', ['-m', 'venv', CERTBOT_HOME])
+    run(path.join(CERTBOT_HOME, 'bin/pip'), ['install', '--upgrade', 'pip'])
+  }
+  run(path.join(CERTBOT_HOME, 'bin/pip'), ['install', '--upgrade', 'certbot>=5.4,<6'])
+
+  fs.mkdirSync(path.join(WEBROOT, '.well-known/acme-challenge'), { recursive: true, mode: 0o755 })
+  writeManagedFile(NGINX_CONFIG, nginxHttpConfig(ip))
+  run('nginx', ['-t'])
+  run('systemctl', ['enable', '--now', 'nginx'])
+  run('systemctl', ['reload', 'nginx'])
+
+  const certificateArgs = [
+    'certonly', '--non-interactive', '--agree-tos',
+    '--preferred-profile', 'shortlived',
+    '--webroot', '--webroot-path', WEBROOT,
+    '--ip-address', ip,
+    '--cert-name', certName(ip),
+    '--keep-until-expiring',
+  ]
+  if (options.email) certificateArgs.push('--email', options.email)
+  else certificateArgs.push('--register-unsafely-without-email')
+  run(CERTBOT, certificateArgs)
+
+  writeManagedFile(NGINX_CONFIG, nginxTlsConfig(ip, options.port))
+  writeManagedFile(PUBLIC_URL_FILE, `${MARKER}\nwss://${ip}/ws/mobile\n`)
+  writeManagedFile(RENEW_SERVICE, renewalService())
+  writeManagedFile(RENEW_TIMER, renewalTimer())
+  run('nginx', ['-t'])
+  run('systemctl', ['reload', 'nginx'])
+  run('systemctl', ['daemon-reload'])
+  run('systemctl', ['enable', '--now', path.basename(RENEW_TIMER)])
+
+  console.log(`
+Setup completed.
+
+1. Restart dsh web so the plugin reads ${PUBLIC_URL_FILE}.
+2. Open “移动设备”, enable the gateway, and generate a pairing QR code.
+3. The iOS client should connect to wss://${ip}/ws/mobile.
+
+Check later with:
+  sudo npx dsh-plugin-mobile-gateway status`)
+}
+
+function status() {
+  const endpoint = fs.existsSync(PUBLIC_URL_FILE)
+    ? fs.readFileSync(PUBLIC_URL_FILE, 'utf8').split(/\r?\n/).find((line) => line.startsWith('wss://'))
+    : ''
+  console.log(`Public endpoint: ${endpoint || 'not configured'}`)
+  console.log(`Nginx config: ${fs.existsSync(NGINX_CONFIG) ? NGINX_CONFIG : 'not installed'}`)
+  console.log(`Renewal timer: ${fs.existsSync(RENEW_TIMER) ? RENEW_TIMER : 'not installed'}`)
+  if (commandExists('systemctl') && fs.existsSync(RENEW_TIMER)) {
+    try { run('systemctl', ['--no-pager', 'status', path.basename(RENEW_TIMER)]) } catch {}
+  }
+}
+
+async function remove(options) {
+  assertRoot()
+  if (!await confirm('Remove the managed Nginx endpoint and renewal timer? Certificates and installed packages will be kept.', options.yes)) {
+    console.log('Cancelled.')
+    return
+  }
+  if (commandExists('systemctl')) {
+    try { run('systemctl', ['disable', '--now', path.basename(RENEW_TIMER)]) } catch {}
+  }
+  for (const file of [NGINX_CONFIG, PUBLIC_URL_FILE, RENEW_SERVICE, RENEW_TIMER]) {
+    if (!fs.existsSync(file)) continue
+    const content = fs.readFileSync(file, 'utf8')
+    if (!content.startsWith(MARKER)) throw new Error(`refusing to remove unmanaged file: ${file}`)
+    fs.rmSync(file)
+    console.log(`Removed ${file}`)
+  }
+  if (commandExists('systemctl')) run('systemctl', ['daemon-reload'])
+  if (commandExists('nginx')) {
+    run('nginx', ['-t'])
+    run('systemctl', ['reload', 'nginx'])
+  }
+  console.log('Public IP endpoint removed. Existing certificates and packages were left intact.')
+}
+
+export {
+  assertPublicIpv4,
+  certName,
+  nginxHttpConfig,
+  nginxTlsConfig,
+  parseArgs,
+  renewalService,
+  renewalTimer,
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    const options = parseArgs(process.argv.slice(2))
+    if (options.command === 'help') printHelp()
+    else if (options.command === 'setup') await setup(options)
+    else if (options.command === 'status') status()
+    else if (options.command === 'remove') await remove(options)
+    else throw new Error(`unknown command: ${options.command}`)
+  } catch (error) {
+    console.error(`\nError: ${error && error.message ? error.message : String(error)}`)
+    process.exitCode = 1
+  }
+}

package/cordis.patch.yml

@@ -13,6 +13,8 @@
         requireAuth: true
         adminLoopbackOnly: true
         pairingTtlMs: 300000
+        # Written automatically by `sudo npx dsh-plugin-mobile-gateway setup`.
+        publicUrlFile: /etc/dsh-mobile-gateway/public-url
 
 # The gateway's `search` query channel needs the full-text session index,
 # which dsh-web-app deliberately ships as `openAt: never` (search disabled).

package/lib/client.js

@@ -168,16 +168,18 @@ window.__ModuleLoader__.load({
         return () => { active = false; window.clearInterval(timer) }
       }, [refresh])
 
+      const createPairing = async (endpoint) => request('/mgw/pair', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: deviceName, publicUrl: endpoint }),
+      })
+
       const pair = async () => {
         setBusy(true)
         setError(null)
         setPairingTokenCopied(false)
         try {
-          const data = await request('/mgw/pair', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ name: deviceName, publicUrl }),
-          })
+          const data = await createPairing(publicUrl)
           setQr(data)
         } catch (cause) {
           setError(cause.message)

package/lib/index.mjs

@@ -87,6 +87,7 @@ const Config = Schema.object({
   deviceFile: Schema.string().default(''),
   pairingTtlMs: Schema.natural().min(30_000).max(15 * 60 * 1000).default(DEFAULT_PAIRING_TTL_MS),
   allowQueryToken: Schema.boolean().default(false),
+  publicUrlFile: Schema.string().default('/etc/dsh-mobile-gateway/public-url'),
 })
 
 function log(line) {
@@ -773,6 +774,7 @@ const plugin = {
       deviceFile: '',
       pairingTtlMs: DEFAULT_PAIRING_TTL_MS,
       allowQueryToken: false,
+      publicUrlFile: '/etc/dsh-mobile-gateway/public-url',
       ...(config || {}),
     }
     const wsPath = options.path
@@ -800,6 +802,19 @@ const plugin = {
     let connectedSinceEnabled = false
     let lastAuthRejectLogAt = 0
     let suppressedAuthRejects = 0
+    const configuredPublicUrl = () => {
+      if (typeof options.publicUrl === 'string' && options.publicUrl.trim()) return options.publicUrl.trim()
+      if (typeof options.publicUrlFile !== 'string' || !options.publicUrlFile.trim()) return ''
+      try {
+        return fs.readFileSync(options.publicUrlFile, 'utf8')
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .find((line) => line && !line.startsWith('#')) || ''
+      } catch (error) {
+        if (!error || error.code !== 'ENOENT') log(`unable to read publicUrlFile: ${error && error.message ? error.message : String(error)}`)
+        return ''
+      }
+    }
 
     const setGatewayEnabled = (enabled, reason) => {
       if (waitTimer) clearTimeout(waitTimer)
@@ -864,7 +879,7 @@ const plugin = {
               waitExpiresAt,
               connectedClients: clients.size,
               wsPath,
-              publicUrl: options.publicUrl || null,
+              publicUrl: configuredPublicUrl() || null,
               pairingTtlMs: options.pairingTtlMs,
               queryTokenAllowed: !!options.allowQueryToken,
             })
@@ -898,7 +913,7 @@ const plugin = {
             }
             const body = await readBody(req)
             const name = typeof body.name === 'string' ? body.name : undefined
-            const publicUrl = normalizePublicUrl(body.publicUrl || options.publicUrl, req, wsPath)
+            const publicUrl = normalizePublicUrl(body.publicUrl || configuredPublicUrl(), req, wsPath)
             const pairing = registry.createPairing(name)
             const payload = {
               version: 2,

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Persistent WebSocket gateway for dsh: exposes /ws/mobile on the web server and forwards agent session output to connected mobile clients",
   "main": "lib/index.mjs",
   "files": [
+    "bin",
     "lib",
     "docs",
     "cordis.patch.yml",
@@ -22,6 +23,10 @@
     "ws": "^8.18.0",
     "qrcode": "^1.5.4"
   },
+  "bin": "bin/setup-ip.mjs",
+  "scripts": {
+    "test": "node test/setup-ip.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs"
+  },
   "exports": {
     ".": "./lib/index.mjs",
     "./client": "./lib/client.js",