dsh-web-remote-access

让 DeepSeek Harness(dsh)Web UI 支持远程访问,并用访问令牌做访问控制
_{不改动 harness 源码,全部通过 bundle 插件实现}

一个开箱即用的 DeepSeek Harness (dsh) 插件:解锁 dsh web 的远程访问能力(--host 0.0.0.0),并让对外暴露的 Web UI 始终处于访问令牌(web token)保护之下——页面、/api RPC、WebSocket 下行全部在门卫之后;回环访问则无需令牌,本地使用零打扰。

开源项目:github.com/studyzy/dsh-web-remote-access · MIT 协议

---

目录

• 特性
• 安装
• 用法
• 工作原理
• 安全说明
• 项目结构
• 开发
• 常见问题
• Fork 来源与兼容性
• 贡献
• 许可证

---

特性

• 🔓 远程访问:--host 0.0.0.0 可用,且始终有令牌保护——对外暴露的服务绝不会无认证运行。
• 🛡️ 全表面门卫:所有请求(页面、/api RPC、WebSocket 下行)都经过 web token 门卫:
  1. 首次打开 http://<host>:<port>/?web_token=<token> → 服务器 302 跳转到干净路径,并下发会话 Cookie(dsh_web_token,HttpOnly, SameSite=Lax,浏览器关闭即失效)。
  2. 之后请求携带 Cookie 正常访问,直到浏览器关闭。
• 🔑 令牌仅对远程绑定启用:--host 0.0.0.0 时,解析顺序 --web_token → 环境变量 $DSH_WEB_TOKEN → 启动时随机生成的令牌;回环绑定不启用门禁(令牌为空)。
• 🖨️ 一键直达:启动时打印可直接打开的 URL(含 ?web_token=),绑定所有网卡时还会打印 LAN 地址。
• ⏱️ 常数时间比较:令牌校验使用 sha256 + timingSafeEqual,不泄漏令牌长度与内容。
• 📱 PWA 兼容:/manifest.webmanifest 豁免令牌,安装检测不受影响。
• 🌐 配置平面远程可达:通过令牌认证的 /api 请求以回环权威呈现给下游信任围栏,使 settings.*、credentials.*、agentPreset.*、host.*、llm.discoverModels 等特权方法可远程访问。
• 🧩 零源码改动:不改动 harness 源码,全部通过 bundle 插件(patch 层)实现;卸载插件即可完全还原默认行为。

安装

需要 dsh 环境。安装为 web profile 的插件:

# 从 GitHub 安装(推荐,免构建)
dsh plugin --profile web add [email protected]:studyzy/dsh-web-remote-access.git

# 或 HTTPS
dsh plugin --profile web add https://github.com/studyzy/dsh-web-remote-access.git

# 从 npm 安装(需已发布)
dsh plugin --profile web add @studyzy/dsh-web-remote-access

# 本地源码安装(开发用)
dsh plugin --profile web add /path/to/dsh-web-remote-access

安装后 profile 层叠顺序变为 dsh-base → dsh-web-app → @studyzy/dsh-web-remote-access。

卸载:

dsh plugin --profile web remove @studyzy/dsh-web-remote-access

即可完全还原默认行为。

用法

dsh --profile web --host 0.0.0.0 --web_token <token>     # 远程,固定令牌
DSH_WEB_TOKEN=<token> dsh --profile web --host 0.0.0.0    # 远程,令牌来自环境变量
dsh --profile web --host 0.0.0.0                          # 远程,随机令牌(打印在 URL 里)
dsh --profile web                                        # 回环,无需令牌

启动后终端会打印类似这样的 URL(可直接打开):

dsh web: http://127.0.0.1:3080/?web_token=<token> (LAN: http://192.168.1.5:3080/?web_token=<token>)

CLI 选项

选项	说明
--host <host>	绑定地址。0.0.0.0 表示所有网卡;默认 127.0.0.1
--port <port>	监听端口;传 0 由操作系统分配空闲端口。默认 3080
--no-open	启动后不在默认浏览器中打开 Web UI(无头服务器常用)
--trusted-host <authority...>	额外信任的权威(host 或 host:port,可重复),用于 /api 浏览器信任围栏
--web_token <token>	访问令牌;仅对 --host 0.0.0.0 绑定启用;缺省时回退到 $DSH_WEB_TOKEN,再回退到启动时随机生成的令牌

环境变量

变量	说明
DSH_WEB_TOKEN	未指定 --web_token 时使用的令牌

工作原理

@studyzy/dsh-web-remote-access 是一个 dsh bundle(patch 层):禁用 web-app 的若干行,挂载本包自己的插件。

行	替换为	作用
web-startup	@studyzy/dsh-web-remote-access/startup	fork @deepseek-ai/dsh-web-app/startup,新增 --web_token、$DSH_WEB_TOKEN、随机令牌兜底;提供同名 webStartup 服务,webToken 仅对 0.0.0.0 绑定非空
webserver	@studyzy/dsh-web-remote-access/webserver	fork @deepseek-ai/dsh-host-webserver,保持 ctx.webServer 契约不变,增加:路由匹配前的令牌门卫(含升级路径)、manifest 豁免、对已认证 /api 请求的回环呈现
web-runtime 打印	@studyzy/dsh-web-remote-access/url	打印带 ?web_token= 的 URL 行
—(新增行)	@studyzy/dsh-web-remote-access/polyfill	向 index.html 注入 crypto.randomUUID polyfill(非安全上下文支持)
—(新增行)	@studyzy/dsh-web-remote-access/loopback	向 index.html 注入脚本,让已认证的远程浏览器以回环视图呈现(见下方"安全说明")

令牌仅对远程绑定生效:绑定 0.0.0.0 时解析为 --web_token → $DSH_WEB_TOKEN → 启动时随机生成,因此对外暴露的服务门卫始终开启,打印的 URL 始终能直接打开;回环绑定令牌为空,打印的 URL 直接可开。绑定所有网卡时,/api 信任围栏推导出的 LAN IP 字面量也就是打印的 LAN URL 所用的地址。

请求流程

浏览器首次访问 http://host:port/?web_token=<token>
  └─> 门卫校验 query token
       ├─ 匹配 → 302 跳转到干净路径 + 下发 dsh_web_token 会话 Cookie
       └─ 不匹配 → 401
浏览器携带 Cookie 访问(页面 / /api / WebSocket 升级)
  └─> 门卫校验 Cookie
       ├─ 匹配 → 放行到路由匹配
       └─ 不匹配 → 401(升级路径同样 401,而非裸 socket 关闭)

安全说明

• 无 TLS、无账号体系。这是纯 HTTP 上的共享密钥门卫,与 harness 面向开发的定位一致;除可信网络外,请用真正的反向代理前置 dsh web 终结 TLS。
• 令牌首次打开时出现在地址栏/历史记录里,重定向后会从地址栏清除。
• 令牌比较为常数时间(sha256 + timingSafeEqual)。
• /manifest.webmanifest(仅 GET/HEAD)不要求令牌:浏览器抓取 PWA manifest 时不带会话 Cookie,而该文件是随 dist 发布的公开静态元数据,拦住它只会 401 安装检测,没有任何安全收益。其余(应用、/api、升级路径)全部保持门卫。
• 页面会注入基于 crypto.getRandomValues 的 crypto.randomUUID polyfill:crypto.randomUUID 仅在安全上下文可用,在 LAN IP 上的纯 HTTP 里是 undefined,会导致客户端 RPC 发号崩溃、WebSocket 就绪握手失败("WebSocket is closed before the connection is established")。polyfill 在回环/HTTPS 下自动空操作。
• 通过令牌认证的 /api 请求会以回环权威(Host/Origin 在 Cookie 校验通过后改写)呈现给下游信任围栏。harness 把特权方法(settings.*、credentials.*、agentPreset.*、host.*、llm.discoverModels)钉在回环上"直到出现真正的认证层"——令牌门卫就是那层认证,因此配置平面可远程访问。门卫仍只放行带 Cookie 的同源客户端,非 /api 路径不受影响。
• 客户端侧的对应面:harness 的 connection.isLoopback 完全由页面 location.hostname 决定,LAN IP 下为 false,设置界面因此落入进程内 "memory" 作用域,模型/插件页报 "settings are unavailable in this browser"。本包在令牌门禁启用时向 index.html 注入脚本,在 @deepseek-ai/dsh-client-connection 提供 connection 服务时将其 isLoopback 置为 true,让已认证的远程浏览器呈现与回环访问一致的设置体验(模型页、插件页、设置文档编辑、交付物"打开文件"等)。这不会扩大信任面:页面只会在令牌门卫放行后才被渲染,且服务端 /api 信任围栏仍独立生效。
• 已知限制:DSH_WEB_URL 与 web-surface 模型提示仍是无令牌的回环 URL;本 bundle 不提供带令牌的模型侧 URL。

项目结构

src/
  index.ts        # 包入口,导出启动服务的类型与常量
  startup.ts      # fork @deepseek-ai/dsh-web-app/startup:解析 --host/--port/--trusted-host/--web_token
  webserver.ts    # fork @deepseek-ai/dsh-host-webserver:令牌门卫 + /api 回环呈现
  url.ts          # 打印带 ?web_token= 的 URL 行(本地 + LAN)
  polyfill.ts     # 向 index.html 注入 crypto.randomUUID polyfill
  loopback.ts     # 向 index.html 注入脚本,远程浏览器呈现回环视图(isLoopback)
tests/            # vitest:fork 契约 + 门卫行为
cordis.patch.yml  # dsh bundle patch 层

开发

pnpm install
pnpm test       # vitest:fork 契约 + 门卫行为
pnpm test:e2e   # 浏览器 e2e:在真实 dsh CLI(隔离 $DSH_HOME)上验证令牌门卫与 WebUI 启动;经由局域网 IP 访问以覆盖 polyfill(需全局 dsh;CI 每天对最新 dsh 跑)
pnpm test:e2e:local   # 浏览器 e2e:复用本地 ~/.dsh 的 web profile,把当前源码链接进去,同样经由局域网 IP 验证(仅本机,不入 CI)
pnpm build      # tsc -> lib/(ESM)

详见 CONTRIBUTING.md。

常见问题 (FAQ)

1. 忘记令牌怎么办?

• 启动日志里打印的 URL 自带 ?web_token=,直接点开即可。
• 固定令牌:用 --web_token <token> 或环境变量 DSH_WEB_TOKEN 指定。

2. 浏览器打开提示 401?

• 检查是否首次访问:http://<host>:<port>/?web_token=<token>(带 query),成功后跳转到干净路径。
• 检查 Cookie 是否被浏览器拦截/清理:会话 Cookie 在浏览器关闭后失效,需重新用带 ?web_token= 的 URL 打开。

3. 如何更换/吊销令牌?

• 重启服务并更换 --web_token(或环境变量)即可;旧令牌与所有已授权会话一并失效。

4. 可以不用令牌吗?

• 回环访问(dsh --profile web,默认绑定)无需令牌,本地使用零打扰。
• 远程访问(--host 0.0.0.0)不可以不用令牌:这是设计使然——对外暴露的服务绝不无认证运行,未显式指定时也会生成随机令牌(打印在 URL 里)。

5. 和反代(如 Nginx/Caddy)怎么配合?

• 回环绑定(--host 127.0.0.1)不再自带令牌门卫:若经反代暴露,请由反代自行处理认证(如 Basic Auth / OAuth)。
• 若希望保留本插件的令牌门卫,反代应把请求转发到绑定 --host 0.0.0.0 的实例,并把带 ?web_token= 的授权 URL 交给终端用户。详见 SECURITY.md。

6. 为什么 WebSocket 一直连不上?

• 最常见原因:纯 HTTP 的 LAN 访问缺少 crypto.randomUUID。本插件已注入 polyfill,请确认用的是本插件的 web profile;若仍失败,检查浏览器控制台错误与令牌 Cookie。

Fork 来源与兼容性

src/webserver.ts 与 src/startup.ts 分别 fork 自 @deepseek-ai/dsh-host-webserver 与 @deepseek-ai/dsh-web-app/startup(基于 0.1.0-rc.7,cordis 4.0.1,schemastery 3.18.1)。需跟随上游演进;harness 自身测试不覆盖它们——由本包的 tests/ 覆盖。

贡献

欢迎提交 issue 与 PR!请先阅读 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md。安全漏洞请通过 SECURITY.md 的私有渠道报告。

许可证

MIT © studyzy