概览

phone-tunnel-pool

One-click Cloudflare quick-tunnel pool for the dsh web GUI — access from your phone via QR, self-healing generations, chase service worker.

README / ZH

插件文档

phone-tunnel-pool — 面向 dsh web 图形界面的 Cloudflare 快速隧道池

English | 简体中文

通过一个悬浮组件（带有可扫描二维码），为 http://127.0.0.1:3080 （DeepSeek Harness 的 web 图形界面）启用/禁用自愈式 Cloudflare 快速隧道池。用手机扫一次码，池子就自己保持存活：

分代轮换（12 小时）： 新的一对隧道按时生成；只要旧的代还有流量就一直保持存活。
追猎 Service Worker： 浏览器访问过的每个域名都会注册一个 service worker。失效或已轮换的主机名会重定向到存活的兄弟隧道或最新的主隧道 —— 只要连接不断，同一个打开的标签页就能挺过代际切换。
免弹窗迁移： 代理只向已认证过的页面注入凭据；任何重定向前，看门狗会先认证目标主机名（铸造其登录 cookie），因此迁移落地即是已登录状态 —— 不会出现 "需要认证" 弹窗。
按用量退役： 代际只在空闲（无标签页 / WebSocket / 近期流量）或达到硬性寿命上限时才退役。
带退避的复活： 失效隧道用新主机名替换；遵循快速隧道的配额（Cloudflare 429），采用指数退避 + 2 次探测的死区宽限（等待 DNS 传播）。

额外：守护进程以分离方式运行，在 dsh web 重启后收养既有隧道，因此同一 URL、密码和二维码一直有效，直到你点击"禁用" —— 无需重新扫码（系统重启仍需要重新扫一次；命名隧道连这一步都不需要 —— 见 PLAN.md §7）。

安装 / 卸载

# 安装（来自本公开仓库）
dsh plugin --profile web add github:iimaguest/phone-tunnel-pool
dsh web        # 图形界面右下角出现悬浮 📱 组件

# 卸载（一条命令 —— 同时移除依赖与 dsh.profile.bundles 层）
dsh plugin --profile web remove phone-tunnel-pool
dsh web

安装后：打开组件 → 启用 → 用手机相机扫描二维码。安装/移除会自动对账 dsh.profile.bundles 与已安装状态 —— 切勿手工编辑 ~/.dsh/profiles/web/package.json；一条没有对应依赖的多余 bundle 条目正是导致 profile 启动失败（"cannot resolve profile bundle"）的那种状态。

前置条件（全部列出）

项目	必需?	由谁提供
`dsh web` 运行在默认端口 3080（可用 `DSH_TARGET_PORT` 覆盖）	必需	你自己（插件是通向它的隧道）
PATH 中的 `cloudflared` 可执行文件	必需	你自己 —— `brew install cloudflared`（或 apt/dnf/Chocolatey，或用 `DSH_CLOUDFLARED` 指定已有二进制）
Node.js 运行时	必需	dsh 自带 —— 无需单独安装（守护进程复用 dsh 的 node）
`python3` + `qrcode` 包	可选	你自己 —— `pip install qrcode`；缺少时组件只显示 URL + 登录信息，不显示可扫描二维码
`caffeinate`	可选	macOS 自带；其他平台跳过
PowerShell	可选	Windows 自带 —— 仅用于 Windows 上的进程清理（那里没有 `pkill`）
出站网络	必需	cloudflared → Cloudflare 边缘节点 443/7844（无需入站端口）

组件会在 dsh web 启动时预检这些项，在你点击"启用"之前就以黄色警告行显示（并给出具体修复方式，如 brew install cloudflared）；如果启用时缺少 cloudflared，守护进程也会用可读的错误快速失败；弹窗里的"刷新"会重新检查一切 —— 前置条件满足后，过期的错误信息会自动清除。

特性标志集按 cloudflared --version 版本门控：2024.6+ 启用可选的后量子握手（DSH_PQ=1），2024.8+ 增加 --management-diagnostics=false；较旧的构建（apt/dnf 包）使用缩减的、兼容的标志集。

平台。 macOS、Linux 和 Windows（Windows 使用 PowerShell 做进程清理； caffeinate 仅限 macOS，其他平台静默跳过）。守护进程的状态文件与日志位于各操作系统的临时目录（os.tmpdir()）；组件的设置文件（iptunnel-settings.json）位于 ~/.dsh。

截图

截图中的活跃主机名、凭据与二维码均已模糊处理。

工作原理

dsh web GUI  <--  /iptunnel 路由  --  认证代理 (127.0.0.1:3090)
                                              │  Basic + 会话 cookie,
                                              │  Host 改写为 127.0.0.1:3080
                                              │  （GUI 的浏览器信任围栏）
                                              ▼
cloudflared A ─ 到 ─ 认证代理 ───────────────────────────────────┐
cloudflared B ─ 到 ─ 认证代理 ───────────────────────────────────┤ （隧道守护进程
    ... 新代际 ...  ──────────────────────────────────   │   统一管理）

文件：lib/index.js（主机 API：启用/禁用/收养、状态与二维码 SVG 路由）、 lib/daemon.mjs（分离的池大脑：生成、探测、轮换、退役、复活）、 cf-auth-proxy.mjs（公有 /iptunnel/* 服务路径 + Basic 认证 + 看门狗注入 + 凭据交接）、iptunnel-sw.js（追猎 service worker）、 iptunnel-watchdog.js（打开标签页的看门狗）、lib/client.js（组件）、 verify.sh（端到端审计）。PLAN.md = 完整规格 + 边界情况； NOTES.md = 工程历史。

资源占用（默认最小化）

禁用状态 = 零进程（只保留 GUI 里的悬浮小图标）。
启用状态 = 1 个 node 守护进程 + 1 个认证代理 + 每个存活代际 2 个 cloudflared。默认上限：4 代 × 2 = 8 条隧道（繁忙时全部在跑；空闲代 60 分钟后自行退役）。
进一步缩小的旋钮：DSH_MAX_GENS=2（≤4 条隧道）、DSH_IDLE_MS=1200000 （空闲 20 分钟即退役）；DSH_PQ —— 后量子握手默认关闭 （DSH_PQ=1 开启），因为每次连接都有 CPU 开销；不开启时使用经典握手。
手机电量： 看门狗在无变化时退避 30 秒 → 300 秒（5 分钟）。
保持唤醒为可选： caffeinate（macOS）默认关闭；在组件里打开（"Keep machine awake while enabled"）或设置 DSH_CAFFEINATE=1 —— 下次"启用"时生效（并允许屏幕睡眠 —— 仅 -i，不额外耗电亮屏）。不开启时，闲置的 MacBook 可能休眠，池子在唤醒前保持静默。
守护进程日志上限 512 KB（保留最近 128 KB）；探测每 30 秒一次。

安全模型

密码每次"启用"时生成，仅存于内存，在组件中显示并嵌入二维码；不提交、不发布。（守护进程把当前凭据放在操作系统中临时目录下的 0600 状态文件中，使隧道在 dsh web 重启后仍存活；禁用时删除该文件。）
/iptunnel/* 服务路径（health、sw-config、sw.js、entry、watchdog.js、 telemetry、preauth）因故必须公开 —— 浏览器取 service worker 时不带凭据；它们只携带主机名与池存活信息。凭据交接（/iptunnel/preauth）只为出示了有效密码的调用方铸造 cookie，绝不回显任何内容。
window.__ptAuth 只注入代理已认证过的 HTML。
代理监听 127.0.0.1；公网暴露只通过隧道主机名发生 —— 二维码/主机名相当于随身令牌（拿到它的人就能在启用期间打开隧道）：用完请禁用。
快速隧道属于测试级（无 SLA，按 IP 有生成配额）。与该仓库解耦的同模式包适用于任意本地端口；命名隧道是终极形态（一个稳定主机名 → 无需重扫、无弹窗、无配额）。

许可证

Apache-2.0 —— 见 LICENSE。第三方代码： cloudflared（由 Cloudflare 分发）、 Python qrcode 库 —— 仅在运行时使用，未随仓库内置。

phone-tunnel-pool