@painclown/dsh-proxy-bridge
轻量级 DSH 反向代理桥，专为 nginx 等 TLS 终结反代后面的 WebSocket 转发设计。
理念参考 @riceawa/dsh-lan-gateway，感谢 riceawa 的启发。
解决什么问题
DSH Web GUI 的 WebSocket 连接在通过 nginx → 网关 → DSH 链路时会因 Origin/Host 不匹配返回 403。本插件跳过 same-site 检查，信任上游终结器（nginx）做访问控制，直接转发 HTTP + WebSocket 到 DSH。
架构
浏览器 ──HTTPS──> nginx (TLS 终结) ──HTTP──> Bridge (0.0.0.0:3083) ──HTTP──> DSH (127.0.0.1:3080)
│
├── 密码门 (可选)
├── DSH Cookie 自动注入
├── WebSocket 透传 (raw TCP splice)
└── 速率限制 / 会话撤销
- HTTP: 转发时重写 Host/Origin 到
127.0.0.1:3080
- WebSocket: socket 直接 splice 到上游，无 same-site 检查
- 密码门: 可选的第二层认证（在 nginx 之上）
- DSH Cookie 注入: 自动为请求注入 DSH 认证 Cookie，无需手动处理 DSH 登录
安装
# 通过 DSH 插件命令安装
dsh plugin --profile web add @painclown/dsh-proxy-bridge
# 或手动安装
cd ~/.dsh/profiles/web
npm install @painclown/dsh-proxy-bridge
快速开始
# 1. 启用桥（默认 3083 → 3080）
proxy_bridge enable
# 2. 设置密码
proxy_bridge config password=dsh2026
# 3. 配置 DSH Secret（从 ~/.dsh/.credentials.yaml 读取）
proxy_bridge config dshSecret=<your-secret>
# 4. 检查状态
proxy_bridge status
命令
| 命令 | 说明 |
|---|
proxy_bridge status | 查看桥状态 |
proxy_bridge enable | 启动桥 |
proxy_bridge disable | 停止桥 |
proxy_bridge restart | 重启桥 |
proxy_bridge config | 更新配置 |
配置示例
# 设置密码（至少 8 位）
proxy_bridge config password=dsh2026
# 配置 DSH Secret（自动注入 DSH 认证 Cookie）
proxy_bridge config dshSecret=vGIxivMEJblP1teRqVymk6sefy7wHMzxds9T0Unv6rE
# 启用自签名 TLS
proxy_bridge config tlsEnabled=true tlsHosts=["dsh.poxx.top","192.168.123.254"]
# 允许 LAN 免登录
proxy_bridge config lanPasswordless=true lanCidrs=["192.168.123.0/24"]
# 清除密码
proxy_bridge config password=
配置字段
| 字段 | 类型 | 默认值 | 说明 |
|---|
enabled | boolean | false | 是否启动监听 |
port | number | 3083 | 监听端口 (0.0.0.0) |
dshPort | number | 3080 | DSH 上游端口 |
password | string | '' | 密码门（空 = 无密码） |
cookieName | string | dsh_bridge_auth | 会话 Cookie 名 |
cookieMaxAgeDays | number | 30 | Cookie 有效期（天） |
dshSecret | string | '' | DSH browser-session secret |
secureCookies | boolean | false | Cookie 加 Secure 标志 |
tlsEnabled | boolean | false | 启用自签名 TLS (HTTPS) |
tlsDays | number | 365 | 自签名证书有效期（天） |
tlsHosts | string[] | [] | 证书 SAN 主机列表 |
lanCidrs | string[] | [] | 信任的 LAN CIDR |
lanPasswordless | boolean | false | LAN/loopback 源免登录 |
安全特性
密码门
- 设置密码后，所有请求必须携带有效会话 Cookie
- 登录页：
/__bridge_login（GET 显示表单，POST 验证密码）
- 登出：
/__bridge_logout（POST 撤销当前会话）
- 速率限制：每 IP 每 60 秒最多 5 次登录尝试
- 密码使用 scrypt 哈希存储，明文不保存
会话管理
- 每个会话有唯一 ID（16 字节随机数）
- 会话 Cookie 使用 HMAC-SHA256 签名
- 登出只撤销当前会话，不影响其他
- 修改密码递增 epoch，撤销所有会话
- 状态持久化到
~/.dsh/proxy-bridge/state.json（0600 权限）
DSH Cookie 注入
当客户端请求不携带 dsh-auth-* Cookie 时，Bridge 使用配置的 secret 自动生成并注入，使 DSH 认证透明化。
文件结构
~/.dsh/proxy-bridge/
├── state.json # 持久化状态（Cookie secret、密码哈希、会话 epoch、已撤销会话）
└── tls/
├── selfsigned.crt # 自签名证书（tlsEnabled=true 时生成）
└── selfsigned.key # 私钥
nginx 配置示例
server {
listen 11007 ssl;
server_name dsh.poxx.top;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:3083;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
}
}
开发
# 构建
npx tsdown
# 部署到 DSH profile
rm -rf ~/.dsh/profiles/web/node_modules/@riceawa/dsh-proxy-bridge/lib/
cp -r lib/ ~/.dsh/profiles/web/node_modules/@riceawa/dsh-proxy-bridge/lib/
源码结构
src/
├── index.ts # 插件入口，工具注册，生命周期管理
├── proxy.ts # 核心代理逻辑（HTTP 转发 + WS 透传 + 认证）
├── auth.ts # 源分类、会话签名、速率限制
├── state.ts # 持久化状态（scrypt 密码、Cookie secret、会话管理）
├── tls.ts # 自签名证书生成和加载
├── login.ts # 登录页渲染、登出路径、速率限制处理
├── config-fields.ts # 配置 schema
└── client/
├── index.ts # 客户端入口
└── bridge-card.tsx # React 配置卡片
与 dsh-lan-gateway 的区别
| 特性 | dsh-lan-gateway | dsh-proxy-bridge |
|---|
| Same-site 检查 | 严格（Origin/Host 必须匹配） | 跳过（信任 nginx） |
| 适用场景 | 直接暴露到 LAN | 放在 nginx 后面 |
| WS 403 问题 | 需要配置 Origin 白名单 | 自动解决 |
| DSH Cookie 注入 | 无 | 有 |
| 复杂度 | 较高（request policy、upstream session） | 较低 |
License
MIT
