Jiachi5533/dsh-remote-gateway

解决什么问题

DSH 会把高权限浏览器能力限制在回环地址。普通反代可能只能让页面显示出来，设置、插件模块、WebSocket 或宿主机目录选择仍会失败。本插件提供一个范围很窄的兼容网关，同时不把 DSH 内部 Web 服务直接暴露到局域网或公网。

功能

• 透明转发 HTTP、SSE 和 WebSocket；
• 只接受显式列出的来源 IP；
• 保持 DSH 内部 Web 服务监听在 127.0.0.1；
• 将上游 Host 和 Origin 对齐到内部回环地址；
• 请求进入 DSH 前移除边缘认证和转发客户端身份相关请求头；
• 只修改 dsh-client-connection 的精确能力探针，其余插件 bundle 逐字节透传；
• 将宿主机原生目录对话框替换为 DSH 应用内文件浏览器，远程选择 DSH 主机上的工作区；
• 跟随 DSH 插件生命周期启停，现有 systemd、launchd 或其他 DSH 守护方式会同时守护网关。

架构

反向代理才是公网安全边界，必须提供 TLS 和登录认证。网关的来源白名单只是纵深防御，不是用户认证。

安装

要求：

• DSH web profile；
• Node.js 22.19 或更高版本；
• 支持 WebSocket 转发和登录认证的反向代理。

从 GitHub 安装：

dsh plugin --profile web add github:Jiachi5533/dsh-remote-gateway

然后编辑 ~/.dsh/profiles/web/cordis.patch.yml 中生成的 remote-gateway 配置：

- id: remote-gateway
  name: '@jiachi/dsh-remote-gateway'
  config:
    host: 0.0.0.0
    port: 3080
    allowedSources:
      - 192.0.2.10 # 反向代理的准确局域网 IP
      - 127.0.0.1  # 可选：本机健康检查

首次安装后重启 DSH Web 进程。将反向代理的 HTTP 和 WebSocket 上游设置为 http://DSH主机局域网IP:3080，并在反向代理上启用 HTTPS 与登录认证。

不要把 3080 端口直接暴露到公网，也不要在 allowedSources 里配置大范围网段；当前实现只接受准确 IP 地址。

配置

配置项	默认值	说明
host	0.0.0.0	网关监听地址。
port	3080	网关监听端口；0 仅用于测试。
allowedSources	['127.0.0.1']	允许连接的准确 IPv4 或 IPv6 地址。

IPv4 映射地址会统一格式，IPv6 回环地址 ::1 会按 127.0.0.1 处理。上游地址由 DSH 自身提供，不能通过插件配置改到其他服务。如果内部 DSH Web 服务没有绑定 127.0.0.1，插件会拒绝启动。

白名单内的监控服务可请求 GET /_dsh-remote-gateway/health。它不访问 DSH 上游，直接返回 200 ok，因此检查的是网关进程与来源策略，而不是 DSH 就绪状态。

安全模型

• TLS 和用户认证在反向代理结束；
• 网关只应放行反向代理的局域网地址；
• 内部 DSH Web 服务保持回环监听；
• 转发上游前移除 Authorization、Proxy-Authorization、Forwarded、X-Forwarded-* 和 X-Real-IP；
• 来源 IP 白名单无法防御已经被攻陷的反向代理，也无法区分共享同一来源地址的设备；
• DSH 插件拥有 DSH 进程自身的权限，安装第三方插件前仍需审阅代码。

安全问题报告和部署建议见 SECURITY.md。

兼容性

组件	状态
DSH 0.1.1-rc.2	已于 2026-08-28 验证
HTTP 和 SSE	已验证
WebSocket Upgrade	已验证
设置 API	已验证
应用内宿主机目录浏览	已验证
已有及后续标准 Host/Client bundle	除连接模块精确路径外均原样透传

连接模块补丁采用“失败即停止”策略。如果 DSH 更新改变目标探针，该模块会返回带明确日志的 502，而不是静默加载一个功能残缺的远程页面。

大多数遵循同源相对路径的插件会直接工作，因为客户端资源和请求会透明转发。如果某插件硬编码 localhost、调用宿主机原生窗口，或自行拒绝非回环浏览器地址，仍可能需要针对该插件单独适配。

更新和卸载

可在 dsh-market 更新，或通过命令行重新添加 GitHub 源，然后重启 DSH：

dsh plugin --profile web add github:Jiachi5533/dsh-remote-gateway

卸载：

dsh plugin --profile web remove @jiachi/dsh-remote-gateway

卸载后，从 profile patch 中删除本插件添加且仍残留的 remote-gateway、directory-picker-browse 和 ui-directory-picker-browse 配置行，再重启 DSH。

常见问题

• 403 forbidden：TCP 来源地址不在 allowedSources；应添加反向代理的局域网 IP，不是远程浏览器的公网 IP。
• 502 ... compatibility probe matched 0 times：当前 DSH 连接模块已经变化；请固定到已验证版本，或提交包含双方版本号的 issue。
• 页面能打开但 WebSocket 失败：在反向代理中启用 WebSocket Upgrade 转发。
• 仍出现原生文件夹对话框：确认两个 browse picker 配置已启用，原生 directory-picker 已禁用。
• 新安装的 UI 插件没有显示：安装后重启 DSH，再强制刷新浏览器。

开发

npm test

测试覆盖来源过滤、IPv4 映射地址、信任请求头改写、连接模块失败保护，以及无关插件 bundle 的逐字节透传。

许可证

MIT