dsh-vpn

DeepSeek Harness 插件：在你自己的 VPS 上一键部署加密的 VPN 服务，保护你的网络连接安全。在 dsh 里填好 VPS 的 IP、端口、用户名和密码，一键部署 sing-box，然后扫二维码导入手机或电脑上的客户端。

用途：保护你的网络安全

• 加密你的网络流量。 在公共 Wi-Fi（咖啡馆、机场、酒店）等不可信网络上，你设备和服务器之间的全部流量都经过加密，别人无法窃听或篡改。
• 保护隐私。 同一网络上的其他人和网络运营方看不到你访问的内容。
• 服务器由你自己掌控。 服务部署在你自己的 VPS 上，不经过任何第三方 VPN 服务商，数据只在你的设备和你的服务器之间传输。
• 默认安全的配置。 协议之间的密钥各自独立、随机生成；推荐的 IP 证书让客户端正常校验服务器身份，防止中间人攻击。

请在遵守所在地法律法规和服务器提供商服务条款的前提下使用。

特性

• 不依赖本机的 ssh 命令：内置纯 JS 的 SSH 客户端（ssh2），用密码登录。
• 两种用法：在设置页点按钮，或者直接对 agent 说“帮我装个节点”。
• 五种协议可选：VLESS Reality、Hysteria2（默认）、TUIC v5、AnyTLS、Shadowsocks 2022。
• 免域名的正规证书：可选 Let's Encrypt 为服务器 IP 签发的证书，所有客户端都能正常校验证书。

使用

用你启动 dsh 的同一种方式安装。profile 名就是启动 dsh 时 --profile 后面的名字；用 dsh web 启动的话就是 web：

# 用 npx 运行 dsh 的
npx @deepseek-ai/dsh plugin --profile web add dsh-vpn
# 全局安装了 dsh 的
dsh plugin --profile web add dsh-vpn

装好后重启 dsh，点左下角「设置」，左侧菜单里的「VPN 设置」就是本插件的设置页（dsh 0.1.5 和 0.1.7 相同）。

在 VPN 设置里：

1. 填写服务器 IP、SSH 端口、用户名、密码，点「保存」和「测试连接」。
2. 勾选要安装的协议，选择证书类型（推荐「IP 证书」），保存后点「安装 / 更新」。
3. 在「节点二维码」里点「刷新二维码」，用手机或电脑上的客户端扫码导入。
4. 服务器防火墙的端口由插件自动放行，不用手动操作；安装完成后提示框会列出放行了哪些端口。

语言

整个插件的语言跟随 dsh 的界面语言（「设置 → 通用设置 → 语言」），目前支持 dsh 提供的中文和 English：

• 设置页切换语言后立即生效。
• agent 安装、卸载前的审批提示，以及 agent 收到的提示，也使用同一种语言。浏览器端会把 dsh 当前的界面语言告诉插件，插件把它保存下来，dsh 重启后仍然沿用。
• 只有从来没有打开过 dsh 网页界面时（例如纯命令行运行），才临时使用电脑的系统语言。

防火墙

安装时插件会检测 VPS 上启用的防火墙，自动放行所选协议的端口（使用 IP 证书时还有 TCP 80）：

| 防火墙 | 做法 | |---|---| | ufw | ufw allow | | firewalld | 放行端口（永久规则和运行时规则都加） | | iptables（如 Oracle Cloud 镜像自带的 REJECT 规则） | 在 INPUT 链最前面插入放行规则，带 dsh-vpn 标签 | | nftables（原生规则集） | 在各个 input 链插入放行规则，带 dsh-vpn 标签 | | 没有启用防火墙 | 不做任何改动 |

• 规则写在 /etc/dsh-vpn/firewall.sh 里，服务每次启动都会重新应用，所以 iptables/nftables 规则重启后也还在。
• 重新安装时，先关闭上次放行的端口，再放行新的，所以取消勾选的协议端口会被关掉。卸载时会删除插件添加的所有规则。
• 插件只添加和删除自己的规则，从不启用防火墙、修改默认策略或改动 SSH 端口。
• 云服务商的安全组（阿里云、腾讯云、AWS 等）在服务器外部，只能在服务商控制台修改，插件改不了；如果有安全组，仍需在控制台放行同样的端口。

证书

| 类型 | 适合 | 客户端校验 | |---|---|---| | 自签证书（默认） | 不想开放 80 端口 | Hysteria2 锁定证书指纹；TUIC 和 AnyTLS 的链接无法锁定，客户端会跳过校验 | | IP 证书（推荐） | 大多数情况 | 所有协议都正常校验证书，不需要域名 |

IP 证书由 sing-box 1.14 内置的 ACME 向 Let's Encrypt 申请（2026 年起正式提供），通过 80 端口完成 HTTP 验证。证书有效期 6 天，由 sing-box 自动续期。

• 签发失败（常见原因是 80 端口没开）：自动退回自签证书，节点仍可使用，页面会提示原因。
• 80 端口被其他程序占用：直接拒绝，不改动正在运行的节点。
• 「查看状态」会显示证书剩余时间；剩余不到 24 小时仍未续期时会发出警告，因为证书过期后客户端将无法连接。

安全设计

| 方面 | 做法 | |---|---| | 密码存储 | 存在 dsh 凭据库（$DSH_HOME/.credentials.yaml，权限 0600），不写进配置文件；浏览器只能写入，读不回来 | | 接口鉴权 | 设置页的接口挂在 dsh 自己的 /api 下，复用 dsh 的登录 cookie 和防跨站、防 DNS rebinding 检查 | | 主机指纹 | 首次连接时记录 SSH 主机指纹，之后指纹变化就拒绝连接，防止中间人截获密码 | | sudo | 非 root 用户用 sudo -S：密码只经 stdin 传入，不会出现在命令行，也不会传给脚本 | | agent 操作 | agent 安装或卸载前会弹出审批，写明目标服务器、协议，以及是否重新生成密钥 | | 证书 | 推荐用 IP 证书，所有协议都正常校验；自签模式下 Hysteria2 锁定指纹，TUIC 和 AnyTLS 会标注“需跳过证书校验” |

组成

| 路径 | 作用 | |---|---| | scripts/vpn.sh | 在服务器上运行的安装脚本，也可以单独使用：ssh vps 'sudo bash -s -- install --protocols reality,hy2' < scripts/vpn.sh | | src/ssh.ts / src/remote.ts | SSH 连接、主机指纹锁定、上传并执行脚本 | | src/core.ts | 统一的操作入口（设置页和 agent 共用），同一时间只执行一个操作 | | src/settings.ts / src/credential-store.ts | 服务器设置的校验和存储 | | src/api.ts | 设置页调用的 /api/dsh-vpn/* 接口 | | src/index.ts | agent 工具 vpn_install / vpn_status / vpn_links / vpn_uninstall，以及执行前的审批 | | src/client/ | 浏览器端：设置弹窗里的「VPN 设置」一栏、二维码 | | src/skill.ts + assets/vpn-ops.md | vpn-ops 技能：操作流程和排障 |

远端落盘位置

• /usr/local/bin/sing-box
• /etc/dsh-vpn/：state.env（密钥、端口、已选协议、证书类型）、config.json、cert/（自签证书）、acme/（IP 证书，由 sing-box 维护）
• /etc/systemd/system/dsh-vpn.service
• /etc/sysctl.d/99-dsh-vpn.conf：开启 BBR

开发与测试

pnpm install
pnpm test            # 单元测试（进程内的假 SSH 服务器，不联网）
pnpm build           # lib/：宿主端 tsc 转译 + 浏览器端 esbuild 打包
DSH_SRC=/path/to/deepseek-harness pnpm typecheck   # 对照 dsh 源码做宿主端和浏览器端的类型检查

build 用 esbuild 把 ssh2 打包进 lib/，所以发布到 npm 的包没有任何运行时依赖，也就没有安装脚本。这是必须的：dsh 自带的 pnpm 11 在依赖的安装脚本被跳过时会让 dsh plugin add 直接失败。被打包的第三方库的许可证见 THIRD_PARTY_NOTICES.md。

npm 上的 @deepseek-ai/* 包版本过旧，所以 build 不做类型检查，类型检查对照 dsh 源码单独进行。

端到端测试会在目标机器上安装再卸载，并用 sing-box 客户端实测每种协议的连通性。本地可以用 Lima 虚拟机：

limactl start --name=vps --vm-type=vz --network=vzNAT --set '.mounts=[]' template:ubuntu-24.04
# 在虚拟机里开启 sshd 的密码登录并设置密码，然后：
DSH_VPN_E2E_HOST=<测试虚拟机 IP> DSH_VPN_E2E_USER=root DSH_VPN_E2E_PASSWORD=… pnpm test:e2e

防火墙测试会依次启用 ufw、firewalld、iptables、nftables，只能在测试虚拟机上运行：

DSH_VPN_E2E_FIREWALL=1 DSH_VPN_E2E_HOST=… DSH_VPN_E2E_USER=root DSH_VPN_E2E_PASSWORD=… pnpm test:e2e

IP 证书的测试需要一个本地 ACME 服务器，用 Let's Encrypt 官方的 Pebble 模拟。只能在测试虚拟机上运行，因为它会把 Pebble 的根证书加入系统信任：

ssh 测试机 'sudo bash -s' < tests/e2e/pebble-setup.sh
DSH_VPN_E2E_ACME=https://localhost:14000/dir DSH_VPN_E2E_HOST=… pnpm test:e2e

在插件配置里设置 acmeProvider，就可以让插件改用 Pebble 或其他 ACME 服务器。

发布

推送与 package.json 版本号一致的标签，GitHub Actions 会先跑测试，再发布到 npm。需要在仓库 Secrets 里配置 NPM_TOKEN。仓库是私有的，npm 不支持为私有仓库生成来源证明（provenance），所以发布时不带来源证明：

git tag v0.1.0 && git push origin v0.1.0

TODO

• [ ] SSH 私钥登录
• [ ] 导出客户端配置文件（sing-box / mihomo）和订阅链接
• [ ] 可自定义 Reality 的 SNI、协议端口
• [ ] 证书使用自己的域名（DNS 验证：Cloudflare / 阿里云）
• [ ] IPv6 的 IP 证书（目前只在 IPv4 上验证过）
• [ ] 支持 OpenRC（Alpine）
• [ ] 支持 GitHub 下载镜像
• [ ] 在真实 VPS 上跑端到端测试（Debian 12 / Ubuntu 24.04 / Rocky 9）