Aztech-Lab/dsh-3301

曾用名 dsh-proxy；项目与包名现统一为 dsh-3301。

把你的 DeepSeek Harness（DSH）端口代理到 http://<本机IP>:3301，并额外施加安全协议，让你内网可以任何时候访问 DSH（包括手机）。

⚠️ 仅适用于 DSH 1.1。 DeepSeek Harness 1.2 加入了本地 token 验证，会破坏这种反向代理方式（代理无法再透传访问界面）。本项目面向 DSH 1.1。若你用的是 1.2+，需要别的访问方式。

✅ 已更新： 这个限制已经解决。本项目同时以 DSH 插件形式提供（身份 dsh-3301），在 当前 DSH 上可用 —— 见下方插件形态。独立代理形态继续保留。

English · 中文

在 DSH Web GUI 前面的带密码反向代理（HTTP + WebSocket）；也可作为 DSH 插件（dsh-3301）运行，插件形态的口令可选（默认不设）。

DSH 保持绑定在 127.0.0.1（仅回环，安全）。本代理绑定 0.0.0.0，让局域网内的手机能通过密码访问它。插件形态默认没有口令：可自行设置，也可留空。

无需额外安装依赖 —— CLI 形态纯 Node 内置模块；插件形态复用 DSH 已自带的包。跨平台（macOS / Linux / Windows × x86 / ARM）—— 已在 Windows 实测；macOS/Linux 由代码中的平台分支保证，尚未在真机验证。

给 agent 看（TL;DR）

DSH 前面的带密码反向代理。DSH 保持回环；本代理绑定 0.0.0.0:3301 并转发 HTTP + WebSocket 给它。认证是签名 cookie（30 天会话）、可选 HTTPS、带速率限制。运行：DSH_PROXY_PASS=<密码> node lib/cli.js。macOS 停止：launchctl bootout gui/$(id -u)/com.dsh.lan-proxy。详见下文。

插件形态（当前 DSH 首选）： node tools/deploy.mjs dsh-3301（或 dsh plugin --profile web add dsh-3301） → 重启 DSH → 手机打开 http://<本机IP>:3301。默认没有口令；设置卡片在 设置 → 插件 → 插件配置 → dsh-3301。详见下文。

插件形态（dsh-3301）

上面的独立代理仍然可用；但在当前 DSH 上，推荐方式是插件，包/插件身份为 dsh-3301 （npm 上的 dsh-proxy 已被另一个无关的"LLM 网关"插件占用）。

• DSH 本体始终只绑定 127.0.0.1，不对局域网暴露。
• 插件在 DSH 进程内开启局域网入口（默认 0.0.0.0:3301）：没有独立进程、没有计划任务，随 DSH 启停。
• 默认没有口令：未设置口令时入口不校验；保存时把口令留空即清除口令。
• 口令只存 salt + scrypt 校验子（$DSH_HOME/dsh-3301/auth.json），磁盘上无明文；改/清除口令仅限本机（loopback）。
• 登录是表单（口令只在登录那一次过网），带按 IP 的失败锁定与签名会话 cookie（默认 30 天）。
• 会话来自官方 ctx.connection.authenticatedUrl()（不再读取你的凭据文件）；客户端兜底用 ctx.webServer.tapIndex() 在压缩前注入，不需要改写 HTML。

⚠️ 在设置口令之前，能连到 3301 端口的人都能直接进入 DSH。 请在把机器暴露出去之前先设口令： 设置 → 插件 → 插件配置 → dsh-3301，或在本机打开 http://127.0.0.1:3301/__gate/setup。

# 当前请用：clone 后部署（我们暂不发布 npm 包，原因见下）
git clone https://github.com/Aztech-Lab/dsh-3301
cd dsh-3301
node tools/deploy.mjs dsh-3301

大家第一反应会敲的 dsh plugin --profile web add dsh-3301 需要 npm 上的包，而我们刻意没有发布 （仓库本身就是安装源，且没有构建步骤）。在上架之前请用上面的 clone + deploy 路径。

部署目标是你的 DSH profile（$DSH_HOME/profiles/<profile>），通常在本仓库之外。 如果写入被拒（EACCES: permission denied），请给该目录写权限，或用拥有 $DSH_HOME 的那个用户执行。

装完重启 DSH，打开 设置 → 插件 → 插件配置 → dsh-3301：

项	说明
启用入口	关闭即释放监听端口
监听地址	0.0.0.0（局域网可达）/ 127.0.0.1（仅本机）
监听端口	默认 3301
用户名	登录表单用户名，默认 dsh
安全验证周期	会话 cookie 有效期，默认 30 天
失败次数上限 / 锁定时长	超过即锁定该 IP
注入客户端兜底	注入 __DSH_TRANSPORT__.ownsHost，让局域网页面的设置平面可用
口令	只写输入框：留空 = 清除；修改须填当前口令

首次设置也可在本机打开 http://127.0.0.1:3301/__gate/setup； http://127.0.0.1:3301/__gate/health 无需认证即可查看入口状态。

卡片观感与 DSH 官方插件卡片一致（沿用官方 dsh-client-ui-settings-plugins（BSD-3-Clause）的样式声明 与主题变量）；实现代码均为本项目自行编写。

独立 CLI（node lib/cli.js，环境变量 DSH_PROXY_*）未改动，仍支持在 DSH 之外单独跑代理。

为什么

本节描述独立 CLI 形态；上面的插件形态在认证上不同（表单登录 + scrypt），也不需要自带的 TLS。

• DSH 保持回环 —— 从不直接暴露。
• Cookie 会话认证 —— 避免 Basic-Auth 反复弹窗（会破坏 WebSocket/SSE 应用）。首次请求通过 Basic Auth，之后签发签名会话 cookie；后续请求（含 WebSocket 升级）凭 cookie 通过。会话 cookie 持久 30 天（Max-Age），浏览器重启不用重新认证。代理把它的 cookie 追加到 DSH 自己的 Set-Cookie（如语言偏好）后面，而不是覆盖，所以 DSH 设置能持久。
• HTTPS（可选） —— 自签证书加密密码/会话传输。
• 速率限制 —— 登录失败过多会锁定 IP。
• 无需额外安装依赖 —— CLI 纯 Node 内置模块；插件复用 DSH 自带包。
• 3301!

运行（独立 CLI）

以 DSH 插件方式运行见上文。

DSH_PROXY_PASS=你的密码 node lib/cli.js
# 或安装 bin 后
DSH_PROXY_PASS=你的密码 dsh-3301

然后从局域网任意设备打开 http://<本机IP>:3301。

环境变量（仅独立 CLI 形态；插件形态在设置卡片里配置）

变量	默认	含义
DSH_PROXY_PORT	3301	监听端口
DSH_PROXY_HOST	0.0.0.0	监听地址
DSH_PROXY_USER	dsh	Basic Auth 用户名
DSH_PROXY_PASS	(必填)	Basic Auth 密码
DSH_UPSTREAM	127.0.0.1:3080	上游 DSH 地址
DSH_PROXY_SECRET_FILE	os.tmpdir()/dsh-3301-secret	会话签名密钥文件
DSH_PROXY_CERT	/tmp/dsh-3301-cert.pem	HTTPS 证书（存在则启用 TLS）
DSH_PROXY_KEY	/tmp/dsh-3301-key.pem	HTTPS 私钥

HTTPS（推荐，仅独立 CLI 形态）

插件形态的 3301 入口是明文 HTTP —— 网络不可信时请在前面加 TLS 或隧道。

生成一次自签证书，代理即走 HTTPS：

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /tmp/dsh-3301-key.pem -out /tmp/dsh-3301-cert.pem \
  -days 365 -subj "/CN=dsh-3301"

浏览器会提示一次自签证书警告 —— 接受一次即可。之后密码和会话在网络上加密传输。

macOS launchd（开机自启，仅独立 CLI 形态）

插件随 DSH 启停，无需 launchd。

见 com.dsh.lan-proxy.plist（模板）。加载：

launchctl bootstrap gui/$(id -u) /path/to/com.dsh.lan-proxy.plist

手动停止 / 启动

# 停止（关掉代理）
launchctl bootout gui/$(id -u)/com.dsh.lan-proxy

# 重新启动
launchctl bootstrap gui/$(id -u) /path/to/Library/LaunchAgents/com.dsh.lan-proxy.plist

# 查看状态
launchctl list | grep dsh.lan-proxy

安全说明与风险

已加固：

• DSH 保持回环（从不直接暴露）。
• 认证是 HMAC-SHA256 签名 cookie + 常量时间比较 + HttpOnly —— 防篡改、抗时序攻击。
• 速率限制（5 次失败 → 锁 5 分钟）默认开启。
• HTTPS（启用时）加密密码和会话传输。

已知风险 / 需注意：

• 弱 / 明文密码 —— 默认示例用短数字密码，且明文存在 launchd plist 里。能读 plist（或进程环境）的人能看到密码。请用强随机密码，并尽量别明文存配置。
• 自签证书 —— 浏览器提示一次警告。加密是真实的（RSA 2048），但证书不是受信任 CA 签发，首次连接若用户盲目接受而不核对指纹，理论上可能被中间人攻击。
• 局域网暴露 —— 代理绑定 0.0.0.0，局域网内任何人都能尝试访问，密码是唯一门禁。在不可信网络上这不够。
• 无 IP 白名单 —— 仅密码访问。如需更严控制，放到 VPN（如 Tailscale）后面或加 IP 白名单。

推荐部署：

1. 用强密码（≥12 位，混合字符）。
2. 启用 HTTPS（可信局域网用自签即可）。
3. 局域网不可信时放到 VPN（Tailscale/WireGuard）后面。
4. 密码别明文存配置（用 0600 权限的密钥文件，或从安全来源读环境变量）。

参与贡献

欢迎贡献！有帮助的方向：

• IP 白名单 / 每用户访问控制。
• OAuth2 / SSO 登录（用已有账号替代密码）。
• 用 mkcert 或 Let's Encrypt 做正式 TLS。
• 暴力破解加固（指数退避、持久锁定状态）。
• 测试 和 CI。
• 更好的文档 / 翻译。

开 issue 或 PR —— 见 GitHub 仓库。

鸣谢

本项目由 Aztech Labs 使用 DeepSeek Harness（Deepseek-V4.1-Flash）完成。

许可证

MIT