dsh-remote-huaweicloud-devbridge
Verifieddsh-remote-huaweicloud-devbridge · v0.1.4 · MIT · Web UI
用华为云 DevBridge 开发隧道把本地 DeepSeek Harness 安全地暴露给远端设备远控;插件内置鉴权网关、隧道生命周期与侧边栏控制台。
Install
dsh plugin add dsh-remote-huaweicloud-devbridge Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
dsh-remote-huaweicloud-devbridge · DSH 插件
把本机的 DSH Web 界面通过华为云 DevBridge 的出站隧道交给远端设备远控: 侧边栏一个席位,点开是隧道状态、网关状态、访问令牌、二维码与日志。
公网侧的门禁由插件自己的鉴权网关承担,不依赖 DevBridge 的账号体系,也不改 DSH 启动参数。
仓库级介绍见 README.md,架构见 docs/architecture.md。本文中的路径一律相对仓库根目录;
npm 包内只带 lib/、web/、scripts/、cordis.patch.yml 与本文件,不含 docs/ 和根目录文档。
包结构
dsh-plugin/
├─ package.json # dsh.bundle(patch) / dsh.client(inject) / exports / files
├─ cordis.patch.yml # 把插件挂进 web profile,给安全默认值
├─ lib/
│ ├─ index.js # 宿主装配:同源控制面、一次性 API token、生命周期
│ ├─ config.js # 配置优先级、路径换算、config.json 写回
│ ├─ gate.js # 鉴权反向代理(HTTP + WebSocket)
│ ├─ tunnel.js # devbridge CLI 适配、host 常驻与重连看护
│ ├─ control.js # /api/* 同源接口
│ ├─ launch-token.js # 找 DSH 启动令牌(进程内服务 / 手工粘贴 / 落盘兜底)
│ ├─ state.js # state.json(0600,临时文件 + rename)
│ ├─ qrcode.js # 纯标准库二维码生成
│ ├─ page.js # 独立控制页(内联面板,不依赖客户端注入)
│ ├─ log.js # 环形内存日志
│ ├─ client.template.js # 浏览器半的包装模板
│ └─ client.js # 构建产物:内联了 web/panel.js,禁止手改
├─ web/panel.js # 面板 UI 的唯一真源
├─ scripts/build-client.mjs # 重建 lib/client.js
├─ scripts/doctor.mjs # 独立体检:Node / 文件 / CLI / 登录态 / 端口 / 权限
├─ scripts/install-cli.sh # 装 devbridge CLI v0.2.x;--check 只下载审阅不执行
└─ tests/ # 离线自测(注入 CLI / 端口,不连真实中继)
运行时零第三方依赖,Node >= 22.5。前端 React 由 DSH 宿主 require("react") 提供。
装
# 发布前:装本地目录
dsh plugin --profile web add ~/dsh-remote-huaweicloud-devbridge/dsh-plugin
dsh web
# 发布到 npm 后:
# dsh plugin --profile web add dsh-remote-huaweicloud-devbridge
cordis.patch.yml 安装时把插件插进 profile 组合,默认值:enabled: true、
autoStart: false、gatePort: 3081、tunnelExpirationHours: 72、protocol: auto、
allowAnonymous: true。首次装完不会自动联网,要在侧边栏点「开启远控」。
npm run doctor # 一键体检(不依赖 DSH 进程),阻塞项会给修复指引
sh scripts/install-cli.sh --check # 要看官方安装脚本内容:只下载并打印前 8 行,不执行
devbridge auth login # 浏览器登录;或用 HW_API_KEY 环境变量配合 --api-key
体检退出码:0 全部就绪、1 有警告、2 有阻塞项;不会打印 HW_API_KEY 的值。
npm 公开包的 postinstall 会用华为云官方命令自动装好 CLI(pnpm 与跳过开关见根 README.md §装)。
首次配置:华为云账号与登录
面板「开通指引」有同样内容的可折叠速查。从零开始:
- 华为云官网 注册并实名认证;DevBridge 是开发者空间的免费开发隧道,无需 ECS / 公网 IP。
- 登录 开发者隧道 DevBridge 开通服务。
- 装 CLI v0.2.x:
sh scripts/install-cli.sh(--check只下载审阅);v0.1.x 旧域名已停用,须升级并重建隧道。 - 登录二选一(v0.2.x 已移除 AK/SK):浏览器授权用
devbridge auth login;无人值守用 API Key 管理页 创建密钥(只显示一次),export HW_API_KEY='粘贴你的密钥'后执行devbridge auth login --api-key "$HW_API_KEY"。 npm run doctor体检;面板显示auth-required即未登录。API Key 与扫码令牌都不要进仓库或日志。
用
| 面板上的动作 | 发生了什么 |
|---|---|
| 开启远控 | 预检 CLI → 建/复用隧道 → 对齐端口(只保留网关端口)→ 起常驻 host → 从 host 输出取公网 URL |
| 扫码 / 复制链接 | 生成 https://<隧道域名>/?t=<令牌> 的二维码与链接 |
| 轮换令牌 | 换掉签名密钥,旧链接与已签发的会话 Cookie 同时失效 |
| 保存并重新兑换 | 粘贴 DSH 启动链接(含 token=),重新发现令牌并兑换 DSH 会话 Cookie |
| 停止 / 重启 / 忘记隧道 | 停 host、按需重建;「忘记」会清掉持久化的隧道 ID |
| 改配置 | 写回 ~/.dsh/devbridge-remote/config.json(600);端口与 CLI 路径需重启 DSH 生效 |
| 粘贴 DSH 启动链接 | DSH 桌面端常把启动令牌只放内存;扫码后若主界面报 authentication required,把 dsh web 打印的完整链接粘进「DSH 会话兑换」保存一次,网关即可在服务端换到 DSH 会话 Cookie |
不依赖客户端注入时,可直接打开独立控制页 http://127.0.0.1:3080/plugins/devbridge-remote/。
隧道归插件专用:每次开启/重启远控会把隧道端口对账到只剩 gatePort,其他端口映射会被自动清理。
配置
优先级(后者覆盖前者):DEFAULTS < config.json(面板写入) < Cordis entry config
< 环境变量(前缀 DEVBRIDGE_REMOTE_*)。常用项:
| 键 | 默认 | 说明 |
|---|---|---|
autoStart |
false |
是否在 DSH 启动后自动开隧道;默认必须人工确认 |
gateHost / gatePort |
127.0.0.1 / 3081 |
鉴权网关监听地址,只绑回环 |
webPort |
0 |
0 表示运行时向 ctx.webServer 探测 DSH 实际端口 |
tunnelExpirationHours |
72 |
隧道有效期,范围 1–720 |
allowAnonymous |
true |
远端免华为云登录;不等于免插件令牌 |
sessionTtlMinutes / maxFails / failWindowMs |
720 / 10 / 600000 |
会话有效期与同 IP 失败限流 |
确切形状在 docs/specs/contracts/02-config.md;本表只是速查,冲突时以契约为准并同 commit 改文档。
同源 API
控制面前缀 /plugins/devbridge-remote,请求需带页面注入的 x-devbridge-api 头;
独立控制页会自动带上。典型接口:GET /api/status、POST /api/start、
POST /api/stop、POST /api/token/rotate、GET /api/qr、POST /api/config、
POST /api/launch-url。
完整路由、方法与返回体在 docs/specs/contracts/01-api.md。
连不上怎么办
面板会给出 blocker 与一句能照着做的指引,常见几类:
| blocker | 处理 |
|---|---|
cli-missing / cli-broken |
sh scripts/install-cli.sh 装 v0.2.x,再 npm run doctor 复核 |
cli-outdated |
v0.1.x 域名已下线:升级 CLI 后重建隧道 |
auth-required |
执行 devbridge auth login,或设置 HW_API_KEY 后登录 |
gate-failed |
gatePort 被占用:lsof -nP -iTCP:3081 -sTCP:LISTEN 查一下,改端口后重启 DSH |
| host 已启动但无 URL | 看面板日志的中继连通性提示;必要时点「忘记隧道」重建 |
扫码后 DSH 主界面报 authentication required |
0.1.3 起网关会自动刷新 DSH 会话 Cookie,通常刷新页面即可;仍失败说明启动令牌过期,把 dsh web 打印的完整链接粘进面板「DSH 会话兑换」保存一次,重新扫码 |
先跑 npm run doctor,它会按上表逐项给出「就绪 / 警告 / 阻塞」;
发布前的剩余待办见 docs/implementation/PROGRESS.md。
安全默认
只绑回环、默认不自动联网、令牌可一键轮换;转发前重写 authority 并剥离外部身份头与
网关自身 Cookie。完整威胁模型与数据处理见 SECURITY.md。
不要把 gateHost 改成 0.0.0.0,也不要把 3080 / 3081 直接反代到公网。
传输与加密现状
不做应用层端到端加密。 中继终止公网 TLS,能看到到达网关的明文 HTTP(聊天正文、 工具输出、审批内容、DSH 启动令牌)。网关的令牌 / 会话 Cookie / 限流是访问控制,不是加密。
原因:纯浏览器下密钥虽可带外(URL fragment 不进 HTTP 请求),但处理密钥的代码本身经
中继下发,中继改写一次脚本即可在正确加密的同时窃取密钥,且无法检测。要防这一点必须
引入带外可信客户端,与「手机只有一个浏览器」冲突。完整评估与被否决的备选见仓库内
docs/decisions/rejected/0001-drop-application-layer-e2ee.md(npm 包不含 docs/),
可见范围与风险面见仓库根 README.md 的同名章节与 SECURITY.md。
License
MIT,见同目录 LICENSE(npm 包内自带)。