前言¶
DeepSeek Harness（DSH）自带的 dsh web 面向「浏览器和监听进程在同一台机器」的场景。一旦通过反向代理、SSH 隧道或局域网地址访问，Host/Origin 校验、页面 loopback 判定、启动 token 与首次登录体验都会和本地打开不一致：RPC 可能全部返回 403，Models 页出现 settings 不可用，后台任务完成也看不到提醒。
社区插件 dsh-remote-access（维护者 0xshawn）在不修改已安装的 dsh 包的前提下，用 Cordis bundle 补丁补齐上述缺口。下面介绍它做什么、如何安装与配置，以及部署时要注意的边界。
这是什么¶
dsh-remote-access 属于 DSH 生态里的客户端类插件（社区目录：skillhub.cn/plugins/0xshawn/dsh-remote-access）。源码托管于 GitHub，许可证 MIT，当前 package 版本为 0.3.0，要求 Node.js ≥ 20，dsh 版本 ≥ 0.2.0-0 且 < 0.3.0-0。
一句话定位：在反向代理、隧道或 LAN 等非 localhost 权威地址（authority）下提供与本地相近的 Web UI 体验——扩展 /api 信任主机、恢复 loopback 页面视图、固定 launch token，并可选登录页与浏览器通知。认证流程未改：浏览器仍需用 launch token 换取与会话绑定的 signed cookie，Host/Origin 围栏仍在每个 /api 请求前执行；插件减轻部署摩擦，不绕过访问控制。
核心功能¶
与 stock dsh web 的对比如下（摘自上游 README）：
| 问题 | 默认 dsh | 本插件 |
|---|---|---|
/api Host/Origin |
仅 loopback、监听 bind 字面量、--trusted-host；经代理的 authority 易 403 |
将 DSH_REMOTE_ACCESS_TRUSTED_HOSTS 中的 authority 追加到同一列表（--trusted-host 仍可用） |
页面视图 connection.isLoopback |
由 location.hostname 推导；代理页被视为非 loopback，dsh 0.2.0 上 settings 留在进程内存，host-document 动作隐藏 |
注入 __DSH_TRANSPORT__ = { ownsHost: true }，与桌面 shell 同源钩子，使已认证页报告 loopback 视图 |
| Launch token | 每进程随机；重启后只能从日志找 ?token= URL |
可固定 DSH_WEB_TOKEN 或插件配置 |
| 首次登录 | 裸 URL 返回 plain 401，必须知道带 token 的 URL | 默认在裸 URL 提供 HTML token 表单（loginPage），提交后走 stock exchange |
| 后台关注 | 标签在后台时，会话结束或待审批/提问不可见 | 可选 Web Notification（notifications，默认开） |
浏览器通知在页面隐藏或未聚焦时触发（需用户授权）；点击通知可回到 dsh 窗口。这是页面级 Web Notifications，不是 Web Push——标签仍需保持打开（可后台）。子 agent 与已移除会话会跳过。
安装与启用¶
插件装入 web profile。官方安装命令如下（公开仓库，无需 build）：
dsh plugin --profile web add git+https://github.com/0xshawn/dsh-remote-access.git
本地目录也可直接 add：
dsh plugin --profile web add /path/to/dsh-remote-access
安装后重启 dsh web——dsh 在启动时加载 bundle。确认插件行已激活：
dsh --profile web --dump-config | grep -A6 'dsh-remote-access'
卸载：
dsh plugin --profile web remove dsh-remote-access
下次重启后恢复 stock 行为。
若部署曾通过 patch 修改 dsh 包（固定 token、强制 loopback），迁移步骤为：停止在安装脚本里打 patch；安装本 bundle 并重启；保留 DSH_WEB_TOKEN 与 --trusted-host 或 DSH_REMOTE_ACCESS_TRUSTED_HOSTS；确认启动日志仍打印 dsh web: ...?token=<同一 token>。
配置¶
环境变量¶
| 变量 | 含义 |
|---|---|
DSH_REMOTE_ACCESS_TRUSTED_HOSTS |
逗号分隔的 bare authority，如 dsh.example.com,dsh.example.com:8443；无端口项匹配任意端口；追加到 --trusted-host |
DSH_WEB_TOKEN |
非空则固定 launch token；空或未设置则仍为每进程随机 token |
适用于 systemd、launchd、Docker 或 shell。若其他 patch 层覆盖了整个 connection.config，需在对应层里重新声明 trustedHosts 及仍需要的键（如 cookieMaxAgeDays），否则环境变量里的 authority 会被丢掉。格式错误的 authority（带 scheme、path、userinfo 或零填充端口）会在启动时按上游校验报错退出，不会静默忽略。
示例启动：
DSH_WEB_TOKEN="$(cat /etc/dsh/web-token)" \
DSH_REMOTE_ACCESS_TRUSTED_HOSTS="dsh.example.com" \
dsh web --host 127.0.0.1 --port 3080 --no-open
插件配置¶
在 $DSH_HOME/profiles/web/cordis.patch.yml 中覆盖 dsh-remote-access 行：
- id: dsh-remote-access
config:
loopback: true # false 则保持 stock 的 per-authority 页面视图
launchToken: '' # 空则回退 DSH_WEB_TOKEN，再回退随机 token；敏感值建议用 DSH_WEB_TOKEN
loginPage: true # false 恢复 stock 的 plain 401
notifications: true # false 关闭浏览器通知客户端
loginPage：仅在请求 authority 已通过 Host/Origin 围栏时提供表单；不可信 authority 仍为 401，避免 DNS rebinding 等场景收 token。token 仍在 query string 中与打印 URL 一致，不引入第二套密码存储。
反向代理：--public-url https://dsh.example.com/ 仍由 dsh 声明浏览器使用的地址；代理需保留浏览器 Host、剥 mount 前缀、正确转发 WebSocket、按 mount 改写 cookie Path 并在 HTTPS 侧加 Secure。完整清单见上游 Publish the Web UI behind a reverse proxy。TLS、网络隔离与谁能访问端口仍由运维负责。
典型用法¶
- 在仅监听
127.0.0.1的机器上跑dsh web，前面挂 Nginx/Caddy 对外暴露https://dsh.example.com。 - 设置
DSH_REMOTE_ACCESS_TRUSTED_HOSTS=dsh.example.com（或与--trusted-host并用），固定DSH_WEB_TOKEN便于自动化与重启后同一登录链接。 - 用户打开裸域名时填写 token（或直接使用带
?token=的 URL），完成 stock cookie 交换后，Models 等页的 settings 与 host-document 行为与本地 loopback 视图一致。 - 长时间跑任务时保持标签打开并允许通知，以便后台收到「Task finished」或「Approval needed」等提醒。
适用场景与注意¶
适合：需要通过 HTTPS 域名、内网 IP 或隧道远程使用 DSH Web UI，且希望避免手工 patch @deepseek-ai/dsh 的安装维护者。
务必知晓：
- 插件以当前 dsh 进程权限运行；安装前请阅读源码与 MIT 许可证，社区目录 skillhub.cn 与 DeepSeek / 幻方无官方从属关系，安装决策由你自行承担。
- dsh 版本需落在 package 声明的 peer 范围内；与 0.3.x dsh 的兼容性以仓库
engines.dsh为准。 - 通知依赖页面常开；关 Tab 后无法收到 Web Notification。
- 需要自有登录页的前端网关可将
loginPage: false，继续由 stock 401 或网关处理。
结尾¶
dsh-remote-access 把「非 localhost authority 下 DSH Web」从改包 patch 收拢为声明式插件：信任主机、loopback 视图、固定 token 与可选登录页/通知，认证模型不变。进一步了解可查阅 GitHub 仓库（含 中文 README）与 SkillHub 目录页。
