dsh-remote-plugin 0.4.8 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # dsh-remote-plugin
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
 DSH Remote 的 DSH bundle 插件：在 DSH 左侧原生边栏注册入口，点击从右侧滑出管理抽屉；插件**内置网关程序并随 DSH 自动启停**（独立 systemd 单元），抽屉直显令牌、主机 IP 与设备监控，配合 [dsh-Remote](https://github.com/Blank-not-black/dsh-Remote) 的 Android App 实现手机远程操控与文件互传（`/fs/list`、`/fs/file`、`/fs/upload`）。
 
 ## 安装
@@ -7,7 +9,7 @@ DSH Remote 的 DSH bundle 插件：在 DSH 左侧原生边栏注册入口，点
 ```sh
 dsh plugin --profile web add dsh-remote-plugin
 # 或 pin 版本
-dsh plugin --profile web add dsh-remote-plugin@0.4.8
+dsh plugin --profile web add dsh-remote-plugin@0.5.0
 ```
 
 重启 DSH Web 后 Ctrl+F5，左侧边栏底部出现 App 图标入口。
@@ -22,13 +24,13 @@ dsh plugin --profile web add "github:Blank-not-black/dsh-Remote#main&path:/packa
 
 - 默认**自动启动**：DSH 启动或抽屉刷新时，插件会拉起内置 `gateway.cjs`（`0.0.0.0:8787`），独立于 DSH 进程。
 - 开关持久化在 `~/.dsh-remote/gateway.enabled`；抽屉内可停止/启动。
-- 令牌在 `~/.dsh-remote/token`（首次自动生成，重复使用不覆盖），抽屉里显示并可复制。
+- 令牌在 `~/.dsh-remote/token`（首次自动生成，重复使用不覆盖），抽屉里显示并可复制；支持**二维码扫码配对**与**一键轮换**。
 - 环境变量 `DSH_REMOTE_AUTOSTART=0` 可关闭自动管理。
-- 文件端点：`/fs/list`（列目录）、`/fs/file`（下载，支持 Range）、`/fs/upload`（上传，默认上限 2GB）；默认根目录 `~`，`DSH_REMOTE_FS_ROOT` 可开多根（`:` 分隔）。
+- 文件端点：`/fs/list`（列目录）、`/fs/file`（下载，支持 Range）、`/fs/upload`（分块续传，支持暂停/取消，落盘前 SHA-256 校验）；默认根目录 `~`，`DSH_REMOTE_FS_ROOT` 可开多根（`:` 分隔）。
 
 ## 手机 App
 
-从 [Releases](https://github.com/Blank-not-black/dsh-Remote/releases/latest) 下载 `dsh-remote.apk`，App「设置」里可添加多个服务器地址（局域网 + Tailscale），点「测速」自动选最快；填抽屉里的令牌即可。聊天记录会本地缓存，断网也能看历史；下载的文件统一放系统「下载/dsh-remote」。
+从 [Releases](https://github.com/Blank-not-black/dsh-Remote/releases/latest) 下载 `dsh-remote.apk`。推荐在抽屉点「二维码」，App「设置 → 扫码连接」直接配对；也可手动添加多个服务器地址（局域网 + Tailscale），点「测速」自动选最快。聊天记录会本地缓存，断网也能看历史；下载的文件统一放系统「下载/dsh-remote」。
 
 ## License
 

package/gateway.cjs

@@ -143,7 +143,22 @@ function loadToken() {
   return token
 }
 
-const TOKEN = loadToken()
+const TOKEN_FROM_ENV = !!process.env.TOKEN
+let TOKEN = loadToken()
+
+/** 一键轮换令牌: 写回 TOKEN_FILE 并立即生效(旧令牌/旧连接全部失效)。 */
+function rotateToken() {
+  if (TOKEN_FROM_ENV) return { error: 'token-from-env', detail: '令牌来自 TOKEN 环境变量, 请修改环境变量后重启' }
+  const next = crypto.randomBytes(24).toString('base64url')
+  try {
+    fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true })
+    fs.writeFileSync(TOKEN_FILE, next + '\n', { mode: 0o600 })
+  } catch (err) {
+    return { error: 'write-failed', detail: err.message }
+  }
+  TOKEN = next
+  return { ok: true, token: next }
+}
 
 function tokenOf(req, url) {
   const auth = req.headers.authorization || ''
@@ -453,6 +468,8 @@ function serveAdminApi(req, res, url) {
           error: latestState.error,
           newer: !!(latestState.version && cmpVersion(latestState.version, VERSION) > 0)
         },
+        token: TOKEN,
+        tokenFromEnv: TOKEN_FROM_ENV,
         tokenMasked: TOKEN.slice(0, 4) + '…' + TOKEN.slice(-4),
         tokenLength: TOKEN.length,
         totalRequests,
@@ -464,6 +481,29 @@ function serveAdminApi(req, res, url) {
     })
     return
   }
+  if (sub === '/token/rotate' && req.method === 'POST') {
+    if (!authorized(req, url)) {
+      authFailures++
+      touchDevice(req, { failedAuth: true })
+      res.writeHead(401, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ error: 'unauthorized' }))
+      return
+    }
+    const r = rotateToken()
+    if (!r.ok) {
+      res.writeHead(409, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ error: r.error, detail: r.detail }))
+      return
+    }
+    // 旧令牌立即失效: 断开已连接的 App/浏览器, 让它们重新扫码/输入
+    for (const d of devices.values()) {
+      if (d.kind !== 'admin') kickDevice(d.ip)
+    }
+    touchDevice(req)
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+    res.end(JSON.stringify({ ok: true, token: r.token, tokenMasked: r.token.slice(0, 4) + '…' + r.token.slice(-4) }))
+    return
+  }
   if (sub === '/shutdown' && req.method === 'POST') {
     if (!authorized(req, url)) {
       authFailures++
@@ -708,6 +748,27 @@ function fsValidName(name) {
   return true
 }
 
+/** 流式计算文件 SHA-256(十六进制)。2GB 也就一次顺序读, 落盘前校验足够快。 */
+function sha256FileHex(file, cb) {
+  const hash = crypto.createHash('sha256')
+  let stream
+  try {
+    stream = fs.createReadStream(file)
+  } catch (err) {
+    cb(err)
+    return
+  }
+  stream.on('error', (err) => cb(err))
+  stream.on('data', (chunk) => hash.update(chunk))
+  stream.on('end', () => cb(null, hash.digest('hex')))
+}
+
+/* 进行中的续传写流: 取消时先 destroy 再删分片, 避免“先删后写”竞态 */
+const activeUploads = new Map()
+function fsActiveKey(dirReal, name, session) {
+  return dirReal + '\n' + name + '\n' + (session || '')
+}
+
 /** 打开上传目标: 同名冲突/符号链接/临时文件都在这层判定。 */
 function fsOpenUploadTarget(res, url, dirLex, dirReal, name) {
   if (!fsValidName(name)) {
@@ -873,6 +934,231 @@ function fsUploadMultipart(req, res, url, dirLex, dirReal, boundary) {
   })
 }
 
+/* ---------- /fs/upload 断点续传 ----------
+ * 分块模式: POST /fs/upload?path=..&name=..&session=<uuid>&offset=N[&finish=1][&overwrite=1]
+ *   - 每一块是 raw body, 服务端写到 .<name>.dsh-remote-part-<session> 的 offset 处
+ *   - offset=0 重开; offset<已有大小 = 回卷重写; offset>已有大小 = 409 offset-mismatch
+ *   - finish=1 时原子 rename 到目标名; 否则返回 {partial:true,size,offset}
+ * 查询进度: GET /fs/upload-probe?path=..&name=..&session=<uuid>
+ */
+function fsPartPath(dirReal, name, session) {
+  const s = String(session || 'default').replace(/[^A-Za-z0-9._-]/g, '').slice(0, 64) || 'default'
+  return path.join(dirReal, `.${name}.dsh-remote-part-${s}`)
+}
+
+function fsTargetState(target) {
+  try {
+    const st = fs.lstatSync(target)
+    if (st.isSymbolicLink()) return { status: 403, error: 'symlink-forbidden', detail: '拒绝覆盖符号链接' }
+    return { exists: true }
+  } catch (err) {
+    if (err.code === 'ENOENT') return { exists: false }
+    return { status: 403, error: 'permission-denied', detail: err.message }
+  }
+}
+
+function fsUploadProbe(req, res, url) {
+  if (req.method !== 'GET') {
+    res.writeHead(405, { allow: 'GET' })
+    res.end()
+    return
+  }
+  if (!fsAuthorized(req, url, res)) return
+  touchDevice(req)
+  const resolved = fsResolve(url.searchParams.get('path') ?? '')
+  if (resolved.error) return fsJson(res, resolved.error === 'forbidden' ? 403 : 404, { error: resolved.error })
+  const checked = fsRealChecked(resolved.abs)
+  if (checked.error) return fsJson(res, checked.error === 'forbidden' ? 403 : 404, { error: checked.error })
+  const name = url.searchParams.get('name') || ''
+  if (!fsValidName(name)) return fsJson(res, 400, { error: 'bad-name' })
+  const part = fsPartPath(checked.abs, name, url.searchParams.get('session') || 'default')
+  let partialSize = 0, partExists = false
+  try {
+    const st = fs.statSync(part)
+    if (st.isFile()) { partialSize = st.size; partExists = true }
+  } catch {}
+  const target = fsTargetState(path.join(checked.abs, name))
+  let targetSize = 0
+  if (target.exists) {
+    try { targetSize = fs.statSync(path.join(checked.abs, name)).size } catch {}
+  }
+  fsJson(res, 200, {
+    ok: true,
+    name,
+    partialSize,
+    partExists,
+    targetExists: !!target.exists,
+    targetSize
+  })
+}
+
+function fsUploadResumable(req, res, url, dirLex, dirReal) {
+  const name = url.searchParams.get('name') || ''
+  if (!fsValidName(name)) return fsJson(res, 400, { error: 'bad-name', detail: '文件名不能为空且不能包含路径分隔符' })
+  const session = url.searchParams.get('session') || ''
+  if (!session) return fsJson(res, 400, { error: 'missing-session', detail: '断点续传需要 session 参数' })
+  const offsetRaw = url.searchParams.get('offset')
+  const offset = Number(offsetRaw)
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    return fsJson(res, 400, { error: 'bad-offset', detail: 'offset 必须是非负整数' })
+  }
+  const finish = url.searchParams.get('finish') === '1' || url.searchParams.get('complete') === '1'
+  const overwrite = url.searchParams.get('overwrite') === '1' || url.searchParams.get('overwrite') === 'true'
+  const sha256Expected = (url.searchParams.get('sha256') || '').trim().toLowerCase()
+  if (sha256Expected && !/^[0-9a-f]{64}$/.test(sha256Expected)) {
+    return fsJson(res, 400, { error: 'bad-sha256', detail: 'sha256 必须是 64 位十六进制' })
+  }
+  const part = fsPartPath(dirReal, name, session)
+  const target = path.join(dirReal, name)
+
+  // 已有分片尺寸对齐: 回卷重写允许, 越界/缺洞拒绝
+  let existing = 0
+  try {
+    const st = fs.statSync(part)
+    if (!st.isFile()) return fsJson(res, 409, { error: 'part-conflict', detail: '分片路径被占用' })
+    existing = st.size
+  } catch (err) {
+    if (err.code !== 'ENOENT') return fsJson(res, 403, { error: 'permission-denied', detail: err.message })
+  }
+  if (offset === 0) {
+    try { if (existing > 0) fs.truncateSync(part, 0) } catch (err) {
+      return fsJson(res, 403, { error: 'permission-denied', detail: err.message })
+    }
+  } else {
+    if (offset > existing) return fsJson(res, 409, { error: 'offset-mismatch', partialSize: existing, detail: 'offset 超过已有分片大小, 请先 probe' })
+    if (offset < existing) {
+      try { fs.truncateSync(part, offset) } catch (err) {
+        return fsJson(res, 403, { error: 'permission-denied', detail: err.message })
+      }
+    }
+  }
+
+  if (finish) {
+    const st = fsTargetState(target)
+    if (st.status) return fsJson(res, st.status, { error: st.error, detail: st.detail })
+    if (st.exists && !overwrite) {
+      return fsJson(res, 409, { error: 'conflict', detail: '文件已存在, overwrite=1 可覆盖' })
+    }
+  }
+
+  let stream
+  try {
+    stream = fs.createWriteStream(part, { flags: offset === 0 ? 'w' : 'r+', start: offset, mode: 0o600 })
+  } catch (err) {
+    return fsJson(res, 403, { error: 'permission-denied', detail: err.message })
+  }
+  const activeKey = fsActiveKey(dirReal, name, session)
+  activeUploads.set(activeKey, stream)
+
+  let bytes = 0
+  let finished = false
+  const abort = (status, msg, extra = {}) => {
+    if (finished) return
+    finished = true
+    activeUploads.delete(activeKey)
+    try { stream.destroy() } catch {}
+    // 网络中断时保留分片, 客户端 probe 后续传; 只有超限/写失败才删
+    if (status === 413 || status === 500) { try { fs.unlinkSync(part) } catch {} }
+    if (!res.headersSent) fsJson(res, status, { error: msg, ...extra })
+    else try { res.destroy() } catch {}
+  }
+
+  stream.on('error', (err) => {
+    abort(500, err.code === 'ENOENT' ? 'part-missing' : 'write-failed', { detail: err.message })
+  })
+  req.on('aborted', () => abort(400, 'client-aborted', { partialSize: offset + bytes }))
+  req.on('error', () => abort(400, 'client-aborted', { partialSize: offset + bytes }))
+  req.on('data', (chunk) => {
+    if (finished) return
+    bytes += chunk.length
+    if (offset + bytes > FS_MAX_UPLOAD) {
+      abort(413, 'too-large', { limit: FS_MAX_UPLOAD })
+      return
+    }
+    stream.write(chunk)
+  })
+  req.on('end', () => {
+    if (finished) return
+    finished = true
+    stream.end(() => {
+      activeUploads.delete(activeKey)
+      const total = offset + bytes
+      try {
+        const st = fs.statSync(part)
+        if (!st.isFile() || st.size !== total) throw new Error('part-size-mismatch')
+        if (!finish) {
+          fsJson(res, 200, { ok: true, partial: true, name, size: total, offset: total, session })
+          return
+        }
+        const commit = (actualSha256) => {
+          try {
+            const ts = fsTargetState(target)
+            if (ts.status) return fsJson(res, ts.status, { error: ts.error, detail: ts.detail })
+            if (ts.exists && !overwrite) return fsJson(res, 409, { error: 'conflict', detail: '文件已存在, overwrite=1 可覆盖' })
+            if (ts.exists) fs.rmSync(target, { force: true })
+            fs.renameSync(part, target)
+            fsJson(res, 201, { ok: true, name, path: path.join(dirLex, name), size: total, resumed: offset > 0, session, ...(actualSha256 ? { sha256: actualSha256 } : {}) })
+          } catch (err) {
+            if (!res.headersSent) fsJson(res, 403, { error: 'write-failed', detail: err.message })
+            else try { res.destroy() } catch {}
+          }
+        }
+        if (sha256Expected) {
+          // 落盘前校验: 不匹配保留分片并返回 422, 客户端可重传或取消
+          sha256FileHex(part, (err, actual) => {
+            if (err) return fsJson(res, 403, { error: 'checksum-failed', detail: err.message })
+            if (actual !== sha256Expected) {
+              return fsJson(res, 422, { error: 'checksum-mismatch', expected: sha256Expected, actual, partialSize: total, session })
+            }
+            commit(actual)
+          })
+        } else {
+          commit(null)
+        }
+      } catch (err) {
+        if (!res.headersSent) fsJson(res, 403, { error: 'write-failed', detail: err.message })
+        else try { res.destroy() } catch {}
+      }
+    })
+  })
+}
+
+/* POST /fs/upload-control?path&name&session&action=cancel
+ * 取消续传: 停止在途写流并删除分片(暂停由客户端 abort 完成, 分片保留)。 */
+function fsUploadControl(req, res, url) {
+  if (req.method !== 'POST') {
+    res.writeHead(405, { allow: 'POST' })
+    res.end()
+    return
+  }
+  if (!fsAuthorized(req, url, res)) return
+  touchDevice(req)
+  const resolved = fsResolve(url.searchParams.get('path') ?? '')
+  if (resolved.error) return fsJson(res, resolved.error === 'forbidden' ? 403 : 404, { error: resolved.error })
+  const checked = fsRealChecked(resolved.abs)
+  if (checked.error) return fsJson(res, checked.error === 'forbidden' ? 403 : 404, { error: checked.error })
+  const name = url.searchParams.get('name') || ''
+  if (!fsValidName(name)) return fsJson(res, 400, { error: 'bad-name' })
+  const session = url.searchParams.get('session') || 'default'
+  const action = url.searchParams.get('action') || ''
+  if (action !== 'cancel' && action !== 'abort') return fsJson(res, 400, { error: 'bad-action', detail: 'action 只支持 cancel' })
+
+  const part = fsPartPath(checked.abs, name, session)
+  const active = activeUploads.get(fsActiveKey(checked.abs, name, session))
+  if (active) {
+    try { active.destroy() } catch {}
+    activeUploads.delete(fsActiveKey(checked.abs, name, session))
+  }
+  // 等写流关闭后再删, 防止 write 把分片重新创建出来
+  setTimeout(() => {
+    let removed = false
+    try { fs.unlinkSync(part); removed = true } catch (err) {
+      if (err.code !== 'ENOENT') return fsJson(res, 403, { error: 'permission-denied', detail: err.message })
+    }
+    fsJson(res, 200, { ok: true, cancelled: true, removed, session })
+  }, 80)
+}
+
 function serveFs(req, res, url) {
   const sub = url.pathname.slice('/fs'.length)
 
@@ -886,6 +1172,8 @@ function serveFs(req, res, url) {
 
   if (sub === '/list') return fsList(req, res, url)
   if (sub === '/file') return fsFile(req, res, url)
+  if (sub === '/upload-probe') return fsUploadProbe(req, res, url)
+  if (sub === '/upload-control') return fsUploadControl(req, res, url)
 
   if (sub === '/upload') {
     if (req.method !== 'POST') {
@@ -909,6 +1197,10 @@ function serveFs(req, res, url) {
     if (Number.isFinite(contentLength) && contentLength > FS_MAX_UPLOAD) {
       return fsJson(res, 413, { error: 'too-large', limit: FS_MAX_UPLOAD })
     }
+    // 带 session/offset 进入分块续传模式; 不带则保持 raw/multipart 一次性上传
+    if (url.searchParams.has('session') || url.searchParams.has('offset')) {
+      return fsUploadResumable(req, res, url, resolved.abs, checked.abs)
+    }
     const contentType = String(req.headers['content-type'] || '')
     if (contentType.startsWith('multipart/form-data')) {
       const m = /boundary=(?:"([^"]+)"|([^;]+))/i.exec(contentType)

package/index.mjs

@@ -317,14 +317,16 @@ async function serveStatic(req, res) {
     })
     return
   }
-  if (pathname === `${MOUNT}/admin/api/note` || pathname === `${MOUNT}/admin/api/kick`) {
+  if (pathname === `${MOUNT}/admin/api/note` || pathname === `${MOUNT}/admin/api/kick` || pathname === `${MOUNT}/admin/api/token/rotate`) {
     if (req.method !== 'POST') {
       res.writeHead(405, { allow: 'POST' })
       res.end()
       return
     }
     const body = await readBody(req, 4096)
-    const sub = pathname.endsWith('/note') ? '/note' : '/kick'
+    const sub = pathname.endsWith('/note') ? '/note'
+      : pathname.endsWith('/kick') ? '/kick'
+      : '/token/rotate'
     const proxied = await proxyGateway(`/admin/api${sub}`, 'POST', body)
     if (proxied !== null) {
       sendJson(res, proxied.status, proxied.json)

package/package.json

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

package/public/admin.html

@@ -32,6 +32,11 @@
     .ua { max-width: 260px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); }
     .token-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 10px 0 14px; }
     .token-row code { flex: 1; background: var(--bg); border: 1px solid var(--line); border-radius: 8px; padding: 8px 10px; font-size: 12px; word-break: break-all; }
+    .pair-box { background: var(--panel); border: 1px solid var(--line); border-radius: var(--radius); padding: 14px; margin-bottom: 14px; text-align: center; }
+    .pair-box .pair-title { font-weight: 600; margin-bottom: 8px; }
+    .pair-qr { display: inline-block; background: #fff; border-radius: 8px; padding: 6px; }
+    .pair-qr svg { display: block; }
+    .pair-box .muted { margin-top: 8px; font-size: 12px; }
     .empty { text-align: center; color: var(--muted); padding: 30px 0; }
     .empty-actions { display: flex; gap: 8px; justify-content: center; flex-wrap: wrap; margin-top: 12px; }
     a.mini-btn { text-decoration: none; display: inline-flex; align-items: center; }
@@ -66,10 +71,18 @@
       <div class="token-row">
         <code id="token-full">—</code>
         <button id="btn-gateway" class="mini-btn hidden">启动网关</button>
+        <button id="btn-qr" class="mini-btn hidden">二维码</button>
+        <button id="btn-rotate" class="mini-btn hidden">轮换令牌</button>
         <button id="btn-copy" class="mini-btn">复制令牌</button>
         <button id="btn-logout" class="mini-btn">退出</button>
       </div>
 
+      <div id="pair-box" class="pair-box hidden">
+        <div class="pair-title">手机 App 扫码配对</div>
+        <div class="pair-qr" id="pair-qr"></div>
+        <div class="muted" id="pair-hint">用 App 内「设置 → 扫码连接」，或系统相机扫一扫自动打开 App</div>
+      </div>
+
       <div class="stat-grid" id="stats"></div>
 
       <div class="section-head"><span>已连接设备</span><span id="device-summary" class="muted"></span></div>
@@ -84,6 +97,7 @@
   </div>
 
   <div id="toast" class="toast hidden"></div>
+  <script src="../qrcode.min.js"></script>
   <script src="../admin.js"></script>
 </body>
 </html>

package/public/admin.js

@@ -19,6 +19,8 @@ let timer = null
 let gatewayRunning = false
 let gatewayBusy = false
 let shownToken = token
+let lastState = null
+let qrShown = false
 
 function toast(text, kind = '') {
   const el = $('toast')
@@ -62,15 +64,20 @@ async function loadState() {
 }
 
 function render(st) {
+  lastState = st
   const isPlugin = st.mode === 'plugin'
   const isGateway = st.mode === 'gateway'
-  shownToken = st.token || (isGateway ? '' : token)
+  shownToken = st.token || token
   $('conn-badge').textContent = isPlugin ? '内嵌' : isGateway ? '网关' : '已连接'
   $('conn-badge').className = 'conn-badge on'
   $('token-full').textContent = shownToken || (isPlugin ? '插件模式 · 未接网关, 无需令牌' : '未获取到令牌')
   // 主机端插件模式: 显示真实令牌(复制可用), 只隐藏退出按钮; 令牌门禁本身不存在
   $('btn-copy').classList.toggle('hidden', !shownToken)
   $('btn-logout').classList.toggle('hidden', pluginMode)
+  // 二维码与轮换只在网关模式下可用(二维码里有完整令牌, 不能在没有网关时生成)
+  $('btn-qr').classList.toggle('hidden', isGateway !== true || !shownToken)
+  $('btn-rotate').classList.toggle('hidden', isGateway !== true || !shownToken || !!st.tokenFromEnv)
+  renderQr(st)
   // 网关开关: 仅插件内嵌页提供, 网关运行/停止两种状态
   gatewayRunning = isGateway
   $('btn-gateway').classList.toggle('hidden', !pluginMode)
@@ -141,6 +148,37 @@ function render(st) {
     btn.addEventListener('click', () => setNote(btn.dataset.noteIp, btn.dataset.note)))
 }
 
+function pairTarget(st) {
+  const ip = (st.lanIPs || []).find(x => x && x !== '127.0.0.1' && x !== '0.0.0.0') || (st.lanIPs || [])[0]
+  const host = ip || (st.host && st.host !== '0.0.0.0' ? st.host : location.hostname)
+  const port = st.port || 8787
+  const base = `http://${host}:${port}`
+  return {
+    url: `dshremote://pair?token=${encodeURIComponent(shownToken)}&server=${encodeURIComponent(base)}`,
+    base
+  }
+}
+
+function renderQr(st) {
+  const box = $('pair-box')
+  if (!qrShown || !shownToken || st.mode !== 'gateway') {
+    box.classList.add('hidden')
+    return
+  }
+  try {
+    const t = pairTarget(st)
+    const qr = window.qrcode(0, 'M')
+    qr.addData(t.url)
+    qr.make()
+    $('pair-qr').innerHTML = qr.createSvgTag({ cellSize: 4, margin: 2, scalable: true })
+    $('pair-hint').textContent = `${t.base} · App「设置 → 扫码连接」，或系统相机扫一扫自动打开 App`
+    box.classList.remove('hidden')
+  } catch (e) {
+    $('pair-qr').textContent = '二维码生成失败'
+    box.classList.remove('hidden')
+  }
+}
+
 async function setNote(ip, current) {
   const name = prompt('给 ' + ip + ' 设置备注（留空清除）：', current || '')
   if (name === null) return
@@ -215,6 +253,32 @@ $('btn-copy').addEventListener('click', async () => {
   }
 })
 
+$('btn-qr').addEventListener('click', () => {
+  qrShown = !qrShown
+  renderQr(lastState || { mode: '', token: shownToken })
+})
+
+$('btn-rotate').addEventListener('click', async () => {
+  if (!confirm('轮换后旧令牌立即失效，手机与浏览器都需要重新扫码/输入。继续？')) return
+  try {
+    const res = await fetch(`${API}/token/rotate`, {
+      method: 'POST',
+      headers: { authorization: 'Bearer ' + (token || shownToken), 'x-dsh-remote-client': 'admin' }
+    })
+    const out = await res.json().catch(() => ({}))
+    if (out.ok && out.token) {
+      token = out.token
+      store.set('dshAdminToken', out.token)
+      toast('令牌已轮换，请重新给设备配对', 'ok')
+      setTimeout(loadState, 300)
+    } else {
+      toast(out.detail || out.error || '轮换失败', 'err')
+    }
+  } catch (e) {
+    toast('轮换失败：' + (e.message || e), 'err')
+  }
+})
+
 $('btn-gateway').addEventListener('click', async () => {
   if (gatewayBusy) return
   gatewayBusy = true