# @qzsy/dsh-bridge 中文文档

规范地址：https://npmcn.com/package/%40qzsy/dsh-bridge/

版本：3\.4\.1
npm 元数据更新时间：2026-11-02T06:38:48.560Z
中文译文更新时间：2026-11-02T06:43:29.578Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40qzsy/dsh-bridge
原文对照：https://npmcn.com/package/%40qzsy/dsh-bridge/?lang=original
项目主页：https://github.com/qzsy/dsh-remote#readme
源码仓库：https://github.com/qzsy/dsh-remote

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：246 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：^22\.19\.0 \|\| \>=24\.0\.0
- 运行依赖：2 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1
- 首次发布：2026-11-01T13:22:47.176Z
- 最新版本发布：2026-11-02T06:38:48.331Z
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

DSH 远程隧道云官方客户端插件：一条命令把本机 DeepSeek Harness 接入云端隧道（设备码绑定、短期令牌、本地门禁代理、HTTP/SSE/WebSocket 反向隧道）。

## 安装

```sh
npm install @qzsy/dsh-bridge
```

也可以使用：`pnpm add @qzsy/dsh-bridge`、`yarn add @qzsy/dsh-bridge`、`bun add @qzsy/dsh-bridge`

## README

# DSH 远程隧道云 · 官方客户端插件

**@qzsy/dsh-bridge** 是 **DSH 远程隧道云**的官方客户端插件：一条命令把本机 DeepSeek Harness 接入云端隧道，在手机、平板或任意设备上安全远程使用。

-   独立实现：包内所有代码均为本仓库自研（MIT，版权见 LICENSE），不依赖、不包含任何第三方 dsh 隧道插件。
-   独立身份：插件 id/name `qzsy-dsh-bridge`、RPC 通道 `/qzsy-dsh-bridge`、设置项与 provide 服务均为本插件命名；数据目录 `~/.dsh/qzsy-dsh-bridge/`，默认本地端口 `3092`（可配置）。
-   轻量：只做 SaaS 隧道 + 本地门禁代理 + 设置面板，不包含 IM 机器人、Cloudflare、自建隧道、多网卡等额外功能。

## 安装

`<name>` 换成你的 DSH profile（如 `web` / `desktop`）：

```bash
dsh plugin --profile <name> add @qzsy/dsh-bridge
```

安装后在 **设置 → 远程访问** 打开面板（插件 id 为 `qzsy-dsh-bridge`，DSH 组件列表会显示本插件而非其它隧道插件）。

## 绑定设备（接入 DSH 远程隧道云）

无感授权流程（推荐，全程不需要输入设备码、也不需要设本地口令）：

1.  面板中确认 **SaaS 网关地址**：官方云为 `wss://dsh.b.nps.qzsyzn.com/_gw/connect`（自建部署填自己的网关地址），点「保存网关」。
2.  点「**立即登录授权**」：插件自动申请设备码并在系统浏览器打开 `https://<控制面>/device/authorize?code=...`。
3.  在浏览器登录 SaaS 账号 → 点「**授权此设备**」→ 回到 DSH 面板。
4.  面板会自动轮询并完成绑定，**绑定后自动开启隧道**，随后出现「**显示二维码**」按钮。 绑定成功后，面板顶部会出现**账号卡片**：头像、昵称/邮箱/用户名、剩余时长、本月已用、 累计已用与授权时间；每 60 秒自动刷新，也可手动「刷新」。
5.  手机扫码（`https://<控制面>/open/<publicId>`）→ 登录 SaaS 账号 → 自动验证隧道归属并签发一次性 ticket，跳转进入本机 DSH。

> 需要手动输入设备码时，可展开面板「高级：手动设备码 / 局域网口令」，用「获取设备码」走旧流程。 绑定信息（`deviceId` / `deviceSecret`）只保存在本机 `~/.dsh/qzsy-dsh-bridge/config.json` （权限 0600）；面板只显示掩码。解绑会清除本机凭证，设备本身需在控制台吊销。

## 公网地址形态

-   **Host（主）**：`https://<publicId>.b.nps.qzsyzn.com/` —— 多租户生产形态，根路径资源天然隔离。
-   **Path（兼容）**：`https://<平台域名>/<prefix>/t/<publicId>/...` —— 单隧道演示/无泛域名环境。

面板会把 Host 路由（存在时）显示为主地址，并同时列出 Path 路由。

## 手机访问

窄屏（≤ 767px）访问 DSH 时，插件会自动把左侧栏改成抽屉，不需要额外配置：

-   内容区占满屏宽，左上角「菜单」按钮打开会话 / 工作区 / 插件入口；
-   支持手势：左缘向右滑打开、抽屉内向左滑关闭，拖动时跟手，松手吸附；
-   模型切换器在手机上改为底部 sheet：全宽、抓手、遮罩，支持下拉/点遮罩关闭；
-   全面屏自动避开安全区：刘海 / 状态栏 / 底部 home indicator 不遮挡内容；
-   点遮罩、点会话行、按 Esc 或转回桌面宽度都会自动收起；
-   桌面端保持 DSH 原生布局，不受影响。

## 本地门禁与安全语义

插件会在本机监听一个代理端口（默认 `3092`），把请求转发给 DSH 本体并注入 DSH 原生 loopback 会话 cookie。来源判定：

| 来源 | 判定 | 结果 |
| --- | --- | --- |
| 物理本机回环 | 连接来自 `127.0.0.1` / `::1` 且未带隧道标记 | 免认证，享有本机特权 |
| SaaS 隧道 | 携带 `x-dsh-internal-tunnel` 标记，并带网关注入的 `x-qzsy-gate: ts.uid.hmac` | 验签通过（HMAC-SHA256、±60 秒）即认证；未验签一律 401，不再要求本地口令 |
| 局域网 / 其它直连 | 非回环且无有效隧道标记 | 需本地口令登录或 `?auth=` 令牌换取会话（可选能力） |

-   `/__qzsy_bridge__/loopback-token` 只对物理回环签发；经隧道访问一律 **403**。
-   隧道访客由**网关信任头**认证：hello-ack 为每条连接下发随机 32 字节 `gate.secret`，网关在校验一次性 ticket 且账号为隧道 owner 后附加 `x-qzsy-gate`；插件验签通过即放行，不依赖本地口令。
-   `x-qzsy-gate` 由网关先剥掉客户端伪造值再附加；插件转发 DSH 前也会剥离该头与隧道标记。
-   本地口令是**可选的局域网直连能力**（面板「高级」里可设置），与 SaaS 扫码进入互不影响； `?auth=` 固定令牌同样只用于局域网/直连，请只发给可信设备。

## 配置

配置文件：`~/.dsh/qzsy-dsh-bridge/config.json`

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `port` | `3092` | 本地门禁代理端口 |
| `gatewayUrl` | `wss://dsh.b.nps.qzsyzn.com/_gw/connect` | SaaS 网关地址（也接受 http(s)） |
| `autoStart` | `false` | 随 DSH 启动自动开启隧道 |
| `deviceId` / `deviceSecret` | — | 绑定后写入，勿手工复制到其它设备 |
| `tunnel` / `routesVersion` | — | 云端下发的只读缓存 |
| `access.token` / `access.sessionSecret` | 自动生成 | 本地访问令牌与会话签名密钥 |

也支持 cordis 配置（见 `cordis.example.yml`）：`port`、`targetPort`、`gatewayUrl`。

## 故障排查

| 现象 | 排查 |
| --- | --- |
| 面板显示「未绑定」 | 确认网关地址可访问；重新点「立即登录授权」，确认浏览器里已点「授权此设备」 |
| 授权页提示设备码无效/过期 | 设备码 10 分钟有效，回面板重新点「立即登录授权」 |
| 开启隧道一直「连接中」 | 检查 `wss://.../_gw/connect` 是否可直连（公司代理/防火墙可能拦截 WebSocket） |
| 握手失败 `auth_failed` / `revoked` | 设备已吊销或令牌失效：解绑后重新绑定；被吊销需在控制台重新添加设备 |
| 打开公网地址 401 | 隧道来源只认网关 `x-qzsy-gate` 签名：确认控制台/网关已升级到支持无感授权（hello-ack 下发 gate.secret），并重新扫码获取新 ticket |
| 本机 3092 被占用 | 在 `config.json` 或 cordis 配置里改 `port` |
| 请求 502 | DSH 本体不可达：确认 `dsh web` 在运行，或配置 `targetPort` |
| WebSocket 打不开 | 确认网关与反代放行 WS Upgrade；插件会透传 `ws-open/accept/frame/close` |

## 已知限制（v3.2.0）

-   `getStatus` 为面板引导接口，免 adminToken，只返回脱敏状态（设备 id/secret 均掩码，不含访问令牌与二维码；`openUrl` 由 /open/ 二次校验归属）。
-   adminToken 每次进程启动随机生成，只经物理回环 `/__qzsy_bridge__/loopback-token` 签发；重启 DSH 后需重新领取（面板自动完成）。
-   访问口令登录已内置限流（同一 IP 连续 5 次失败锁定 60 秒）；请使用足够强的口令，并只在内网/可信网络暴露本地端口。
-   修改或清除访问口令会轮换会话签名密钥，所有已登录的远程访客会立即失效。
-   `access.token` 为固定本地令牌（`?auth=` 链接可重复使用），README 已说明泄露处置方式；吊销设备后请解绑并重新绑定以轮换设备密钥。

## 开发与测试

```bash
npm install
node client/build.mjs        # 重建 client/client.js
node --test test/*.test.mjs  # 全量单测
```

测试覆盖：v2 握手、心跳与心跳超时、HTTP/SSE/WebSocket 转发、route-update、drain、 4003 吊销终态、断线重连、门禁三类来源、打包身份（全包无第三方包名残留）。

## 协议与许可

-   控制通道协议 v2 契约见仓库 `docs/architecture/saas-tunnel.md`，共享类型见 `packages/tunnel-protocol`。
-   本包以 MIT 许可发布，版权归本仓库（qzsy）所有，详见 [LICENSE](https://npmcn.com/package/%40qzsy/dsh-bridge/LICENSE)。

## 常见问题

### @qzsy/dsh-bridge 是什么？

DSH 远程隧道云官方客户端插件：一条命令把本机 DeepSeek Harness 接入云端隧道（设备码绑定、短期令牌、本地门禁代理、HTTP/SSE/WebSocket 反向隧道）。

### 如何安装 @qzsy/dsh-bridge？

在项目目录运行 npm install @qzsy/dsh-bridge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @qzsy/dsh-bridge 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/qzsy\_\_dsh-bridge 是否存在。

### @qzsy/dsh-bridge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @qzsy/dsh-bridge 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.19\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @qzsy/dsh-bridge 可以商用吗？

@qzsy/dsh-bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @qzsy/dsh-bridge 还在维护吗？

最新版本 3\.4\.1 发布于 2026/11/02（1 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。