dsh-bridge-gateway

English | 简体中文

DeepSeek Harness（DSH）远程访问插件。以 wenbin-wb/dsh-bridge 为根基，额外加入**「公网直连网关」**与 Tailscale 隧道，让手机等外网设备既能不借助隧道 直连、也能用 Tailscale 拿到稳定的 HTTPS 地址。

局域网访问、Cloudflare 隧道、自建隧道、IM 机器人等原有能力保持不变；插件默认完全不启用， 装上后原有行为零改动，需要什么再开什么。

项目血缘：本仓库是 wenbin-wb/dsh-bridge 的增强分支（fork），并持续跟进上游修复。详见 与上游的关系。

与上游的关系

本项目的上游是 wenbin-wb/dsh-bridge， 它提供了本插件的全部基础能力。本仓库在其之上做了一件事、并修了两类问题。

上游是谁

| 项 | 说明 | |---|---| | 仓库 | wenbin-wb/dsh-bridge | | 定位 | DSH 多通道远程访问与安全守护插件 | | 能力 | 局域网扫码直连、Cloudflare / 自建公网隧道、微信 / QQ / 飞书 / Telegram 机器人、全协议访问认证 | | 协议 | MIT | | 关系 | 本仓库的 fork 源头；本项目的局域网访问、隧道、IM 机器人、安全认证均来自上游 |

上游是这类插件的开创性实现：它把「手机上继续用 DSH」这件事用最省事的方式做通了 —— 扫码进局域网、隧道出公网、IM 里直接对话。本插件站在它的肩膀上。

本仓库做了什么

一、新增：公网直连网关（上游没有）

上游解决「外网访问」的方式是隧道（Cloudflare 或自建）。隧道需要第三方转发， 且免费临时域名每次重启都会变。

本插件新增直连网关：电脑直接监听 0.0.0.0:<端口>，自带 HTTPS 自签证书与强制登录门禁， 外网设备不经任何第三方直接连上来。适合「自己有公网 IP / 会做端口映射」的场景， 也适合不想把流量过第三方的情形。

二、新增：Tailscale 隧道（上游没有）

上游的隧道要么过 Cloudflare、要么自建服务器。本插件新增 Tailscale Serve 通道： 复用你已有的 tailnet，把本机 WebUI 发布成 https://<主机名>.<tailnet>.ts.net。

• 地址自动探测：网关只读查询 tailscale status / tailscale serve status， 自动填入 Serve 地址，也支持手动编辑；
• 只读，不改你的 Tailscale 配置：插件绝不代你执行 tailscale serve， 未配置时只给一条可复制的命令让你自己执行；
• TLS 证书由 Tailscale 自动签发，无需自签证书、无需备案域名。

三、修正：与 DSH 原生能力的冲突（上游至今保留）

| 问题 | 上游现状 | 本仓库做法 | |---|---|---| | 目录选择器 | 以 priority:-10 抢注 DSH 原生 directoryFlow 两个 Slot，并用 capture 阶段 click 拦截劫持「添加工作区」按钮 | 改用官方 browse 目录选择器（成对挂载 host 后端 + 浏览器 UI 面），不再抢注 Slot、不再拦截 DOM | | 代理层改写 HTML | 反向代理时截取 HTML 做字符串替换，注入 PWA meta | 改走官方 webserver/index-inject 机制，由宿主统一渲染；代理回归纯透明转发 | | 目录选择服务名 | 用 ctx.workspaces.pickDirectory（官方实为 ctx.uiWorkspace） | 不再依赖该服务；目录选择整体交还原生 |

上游这两处实现在其 CHANGELOG 中作为功能描述，但会导致「添加工作区点了没反应」。 本仓库已修复，并欢迎上游采纳。

四、跟进：持续移植上游修复

上游迭代很快，本仓库持续跟进。已移植的修复见 CHANGELOG，主要包括：

• DSH 0.1.5 适配：agent preset 真实挂载、会话已存在误判、平台配置重启即丢、/rename 持久化；
• DSH 0.1.7 兼容性核查：无需改动（宿主注入的 connection / webServer / sessions / agents / approval / workspaceRegistry / sessionPersistence / loader 服务、settings.section 槽位、 dsh-llm 的 createUserMessage 均仍存在）；
• 隧道保活：WebSocket Ping/Pong 帧层应答、cloudflared 崩溃自愈与禁用 autoupdate；
• 可靠性：Telegram 代理在 Node ≥ 24 下失效、登录 Session 持久化。

由于两边都在演进，功能上可能各有先后。遇到问题时建议对照上游 README 确认某项能力 归属哪一侧。

命名说明

插件名由 dsh-bridge 改为 dsh-bridge-gateway（体现「网关」这一新增能力）。 老用户升级时数据目录、配置、密码、证书、登录态都会自动迁移，无需手工处理：

| 路径 | 变化 | |---|---| | <DSH_HOME>/dsh-bridge/ | → <DSH_HOME>/dsh-bridge-gateway/（启动时自动迁移） | | ~/.dsh-bridge/ | → ~/.dsh-bridge-cloudflared/（cloudflared 缓存，自动迁移，免重下） | | RPC 通道 /dsh-bridge | → /dsh-bridge-gateway，新旧双通道并存，旧缓存页面仍可用 |

功能

• 公网直连网关（本插件新增）。 电脑直接监听 0.0.0.0:<端口>，自带 HTTPS 自签证书与 强制登录门禁，外网设备直连访问。链路在网关处终结并转发到 DSH loopback，插件页面与 RPC 通道原样可用。
• Tailscale 隧道（本插件新增）。 复用已有 tailnet，把 WebUI 发布为 https://<主机名>.<tailnet>.ts.net：地址自动探测（只读查询，不改你的 Tailscale 配置）、 支持手动编辑、一键生成扫码二维码；TLS 由 Tailscale 自动签发。
• 局域网访问。 同一 Wi-Fi 下用手机扫远程访问面板里的二维码即可进入。
• 公网隧道。 Cloudflare（临时/固定域名）或自建隧道，与直连网关、Tailscale 按需选用。
• 远程工作区。 手机端网页目录树直接浏览并选择工作区对话（走 DSH 官方 browse 选择器）。
• 安全认证。 密码门禁 + 扫码免密 Token + 敏感配置的管理员解锁/锁定 + 防暴力破解限频、 登录态持久化（宿主重启不必重新登录）；永不信任客户端自称的 isLocalhost。
• 访客管理。 实时查看「谁正连着本机」（局域网 / 直连 / 隧道，隧道场景显示真实来源 IP）， 附带 IP 黑名单。查看对所有访客开放，断开连接与拉黑需管理员权限。
• IM 机器人。 微信 / QQ / 飞书 / Telegram 机器人走各自网关链路，无需公网 IP； 可配置会话级工作区 / Agent 预设 / 模型；分平台指南见 docs/。
• 卡片折叠。 访问配置与安全认证两个 Tab 的卡片都可折叠，默认只展开首张， 折叠后仍保留状态标签与一行关键信息。
• 移动端适配。 远程网页 UI 针对手机屏幕深度适配（抽屉化侧边栏、点击热区扩至约 44px、 输入框贴底等）。
• 全界面配置。 以上全部功能都在 DSH Web 远程访问面板里配置，无需手改任何文件。

界面

面板共 5 个 Tab：访问配置 / 访客管理 / IM 机器人 / 安全认证 / 运维监控。

| Tab | 内容 | |---|---| | 访问配置 | 直连网关 · Cloudflare 隧道 · Tailscale 隧道 · 自建隧道 · 局域网访问（默认只展开直连网关） | | 访客管理 | 远程连接监控（来源 IP 可见）· 持久黑名单 | | IM 机器人 | 微信 / QQ / 飞书 / Telegram 平台卡片 | | 安全认证 | 全局总控 · 第一道防线（外部访问门禁）· 第二道防线（后台防篡改） | | 运维监控 | 系统指标 · 网络诊断 · 备份恢复 · 重启 DSH |

要求

• Node ^22.19.0 || >=24.0.0。
• DSH web profile（构建与测试基于 0.1.7-rc.2，同时兼容 0.1.5 线：宿主服务、客户端槽位与 设置接口在两个版本上都存在，无需额外适配）。

安装

# 推荐：直接从 GitHub 安装（不经 npm）
dsh plugin --profile web add github:lament-z/dsh-bridge-gateway

# 备选：从 npm 安装
dsh plugin --profile web add dsh-bridge-gateway

# 从本地 clone / 工作副本安装
dsh plugin --profile web add link:<本目录>

升级到最新版：再次执行上面的 GitHub 安装命令（npm 来源可加 @latest）。然后重启 dsh web。

安装后默认不启用：直连网关关闭，原有局域网/隧道/IM 行为完全不变。

使用方法

公网直连网关（核心功能）

不需要隧道，让电脑直接监听公网端口，外网直连访问。

1. 安装后进入 DSH Web 设置 -> 访问配置 Tab。
2. 在直连网关卡片设置端口（默认 7443），点「保存端口」。
3. 点击「开启直连网关」。
4. 在路由器/云服务器把该端口映射到本机，即可通过 https://<公网IP或域名>:端口 访问。

HTTPS 证书为自签，浏览器首次访问会提示不安全，勾选「始终允许」即可继续。外部访客必须通过 安全认证里配置的登录门禁；门禁策略与局域网设置相互独立。

Tailscale 隧道

适合已经在用 Tailscale、想要一个稳定且受信任的 HTTPS 地址的场景（无需自签证书、 无需自备域名）。

1. 在本机执行一次 tailscale serve --bg 3082（3082 是本插件的反代端口， 改成你的实际端口）。这一步必须由你手动执行 —— 插件只做只读探测， 不会代你修改 Tailscale 配置。
2. 进入设置 -> 访问配置 -> Tailscale 隧道 卡片，点「🔍 自动探测并填入」。
3. 探测到地址后点「保存」，二维码随即生成，手机扫码即可访问 https://<主机名>.<tailnet>.ts.net。

也可以跳过探测，点「✎ 手动编辑」直接填地址。探测失败时卡片会给出可复制的 serve 命令， 以及当前 Tailscale 的登录状态（未安装 / 离线 / 未配置 Serve）。

撤销发布：在终端执行 tailscale serve --bg off。

访客管理

访客管理 Tab 列出当前连到本机的来源 IP（局域网 / 直连网关 / 隧道三条通道聚合， 隧道场景显示访客真实 IP），并可维护 IP 黑名单。

• 查看对所有访客开放 —— 「谁正连着本机」是只读事实，不是管理凭据。
• 断开连接 / 拉黑 / 解除拉黑需要管理员权限，非管理员看不到这些按钮。
• 黑名单中的 IP 在任何页面/连接进入前即被拒绝（优先级最高，隧道真实来源同样生效）。 插件不会自动拉黑：运营商 CGNAT 下大量用户共享出口 IP，自动拉黑容易误伤。

局域网访问

在 DSH Web 打开远程访问面板，用同一 Wi-Fi 下的手机扫二维码。

局域网可达性也交给 DSH 原生 --host / trustedHosts 处理；插件自带的局域网反代 默认关闭，需要时可在面板手动开启。

公网隧道

同一面板里选择 Cloudflare（临时/固定域名）或自建隧道。自建隧道协议见 docs/custom-tunnel.md。

隧道具备自愈能力：cloudflared 意外退出会按指数退避自动重连，且已禁用其 24h 自动更新 自我替换；自建隧道在帧层自动应答 DSH 的 WebSocket 心跳，避免长连接被掐断。

工作区选择

点「添加工作区」会打开 DSH 官方目录浏览器（Miller 双列布局、面包屑、可编辑路径、 新建文件夹、显示隐藏文件），本机与远程行为一致，手机端同样可用。

安全配置

设置 -> 安全认证：开启防护、设置密码、管理免密 Token、解锁/锁定管理面。未认证访客在 任何页面内容返回之前就会被拒绝。

登录态会持久化到 <DSH_HOME>/dsh-bridge-gateway/sessions.json（权限 600）， 宿主重启后已登录设备无需重新输入密码；改密码 / 切换模式 / 重新生成 Token 仍会吊销全部旧会话。

IM 机器人

微信 / QQ / 飞书 / Telegram 使用指南： docs/wechat-usage.md、docs/qq-usage.md、 docs/feishu-usage.md、docs/telegram-usage.md。

每个平台卡片里都有 「⚙️ 高级设置」，可配置该平台远程会话的工作区目录、 Agent 预设、模型提供方 / 模型（留空表示使用 DSH 默认值）。这些配置随宿主重启保留。

从 dsh-bridge 升级

老用户升级后无需任何手工操作：数据目录、配置、访问密码、自签证书、登录态都会自动迁移。 迁移是幂等的 —— 新目录已存在时不会覆盖，旧目录也不会被删除（可自行清理）。 若迁移遇到问题，插件照常启动，旧数据留在原处，日志中会有说明。

v0.2.0 起移除了 dsh-mobile 协议舱（/ws/mobile 设备配对）与配套的 Linux 一键 部署 CLI（init / setup / status / remove）。公网访问请改用 Tailscale Serve 或 Cloudflare 隧道。手机浏览器的网页版移动端适配不受影响，仍然保留。

安全说明

• 直连网关始终强制 public_only 式门禁：外部访客与局域网访问共用同一 AuthManager 认证， 仅限 loopback 的资源绝不经网关暴露。
• RPC 通道经由宿主 web server 注册并通过请求拒绝（requestRejection）鉴权， 伪造或未认证的通道调用在入口即被丢弃。
• 自签证书只加密传输、不提供身份：拿到密码的人就能登录——请设置强密码并开启管理员锁定。
• 登录会话文件权限为 600；文件缺失或损坏时安全降级为空（等价于重新登录一次）。
• Tailscale 探测只读：仅查询状态，绝不代用户执行 tailscale serve 修改其配置。
• 访客管理中的写操作（断开 / 拉黑）由服务端 checkAdminAuth 把关， 不依赖客户端自称的身份。

开发

git clone https://github.com/lament-z/dsh-bridge-gateway
cd dsh-bridge-gateway
npm install
npm run build:client
npm test
dsh plugin --profile web add .

测试会通过 test/isolate-home.mjs 把 DSH_HOME 指向一次性临时目录，不会污染你本机的 真实环境。

本项目 fork 自 wenbin-wb/dsh-bridge。 向上游反馈通用问题、向本仓库反馈直连网关相关问题。

发布说明

打 v* 标签推送到 GitHub 即自动 npm publish（GitHub Actions，需仓库配置 NPM_TOKEN secret）。

开源协议

MIT