dsh-remote-gateway

Readme

# dsh-remote-gateway

**中文** | [English](docs/README_EN.md)

提供安全的反向代理，使DeepSeek Harness可以远程访问，随时随地和AI对话。

DSH 本身**始终只监听**`127.0.0.1`，由网关安全转发向局域网开放。

## 工作方式

```text
浏览器
  → dsh-remote-gateway（白名单 + 密码认证）
  → http://127.0.0.1:<DSH Web 端口>
```

## 要求

- DSH `0.1.1-rc.2` 或更新的兼容版本
- Node.js `^22.23.2 || ^24.19.0`（须使用仍受支持分支的最新安全补丁版本）
- pnpm

## 安装

Github安装：
```sh
dsh plugin --profile web add github:RyensX/dsh-remote-gateway
```

源码安装：

```sh
pnpm install
pnpm build
dsh plugin --profile web add .
```

卸载：

```sh
dsh plugin --profile web remove dsh-remote-gateway
```

## 网关配置

设置页提供：

- 远程网关开关，默认关闭，关闭和重新开启均实时生效；
- 当前实际访问地址、网卡名称和对应二维码；
- 监听地址，默认 `127.0.0.1`；需要局域网访问时再显式改为 `0.0.0.0` 或指定的网卡地址；
- 端口；
- IP 白名单；
- 额外允许的 DNS 名称或 NAT 访问 IP（精确 Host 白名单）；
- 认证滑动过期时间，默认 180 分钟；
- 密码修改；
- 可选 HTTPS 证书和私钥。

所有设置都在点击“保存”后实时生效，无需重启 DSH。

会话按令牌独立滑动过期，最长绝对生命周期为 7 天；服务端推送和心跳不会续期。

首次需要本地访问设置密码才可正常使用。

通过已认证网关地址打开 DSH 时，插件会在 DSH 客户端连接服务发布前安装兼容层，使原生模型、插件和其他设置页继续使用宿主机 Settings 服务，而不是退化为浏览器内存设置。

## 远程访问

为了兼容各种远程访问方案和数据安全方面考虑，插件本身不直接提供远程访问服务，请搭配使用Tailscale、ZeroTier、Cloudflare Tunnel、企业自建 VPN 等。

配置好上述软件后直接打开设置里的网关配置就能看到访问地址。

> 也可以使用公网，但不建议直接暴露到公网，还是推荐上述工具，更加安全可控

### 远程添加工作区与打开配置文件

从网关地址添加工作区时，插件会在当前浏览器内打开宿主机文件夹选择器，不会在运行 DSH 的电脑上弹出一个远程用户无法操作的系统窗口。

设置页右上角的“打开配置文件”时会打开插件提供的页内 YAML/JSON 编辑器：本机仍调用 DSH 原有的系统文本编辑器。

上述操作均受认证保护。

### IP 白名单

只有特定设备使用时建议设置，更安全

白名单一行一项，支持精确 IPv4、IPv6 和 CIDR，例如：

```text
192.168.1.20
192.168.1.0/24
fd00::/8
```

留空表示不限制来源 IP。白名单只是额外准入条件，命中白名单后仍然必须输入密码。来源 IP 只读取 TCP socket，不信任代理请求头。

### 访问域名

网关始终接受本机网卡 IP 和 `localhost`。如需使用证书中的局域网域名、自定义 DNS 名称，或容器/NAT 后的外部访问 IP，必须在“额外允许的 Host”中逐行显式配置，例如 `dsh.home.example`。不在名单内的 Host 会返回 `421`，以阻止 DNS 重绑定；这里只填写精确域名或 IP，不填写协议和端口。

### HTTPS

HTTPS 使用宿主机上的 PEM 文件：

```yaml
dsh-remote-gateway:
  tls:
    enabled: true
    certPath: /absolute/path/to/cert.pem
    keyPath: /absolute/path/to/key.pem
```

证书和私钥路径必须是绝对路径，并且必须指向不超过 1 MiB 的普通文件；设备、管道和目录会被拒绝。保存证书配置后网关会立即加载证书并切换监听器。证书读取或解析失败时不会降级到 HTTP，原监听器会继续提供服务并在本机设置页显示错误。仅覆盖同一路径下的证书文件不会触发自动加载，此类文件内容变更仍需重启 DSH。

HTTP 模式仅适合临时使用的可信局域网。认证页和设置页会显示明文传输警告；密码、会话 Cookie 和 DSH 内容都可能被同一网络中的监听者看到。长期使用或监听非回环地址时应配置 HTTPS，并同时设置 IP 白名单和主机防火墙规则。

## 开发检查

```sh
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm pack --dry-run
```