dsh-admin-gateway

DeepSeek Harness (dsh) 管理员验证网关插件。

核心优势

零成本公网暴露：只需一个绑定在 Cloudflare 的域名，无需公网 IP、无需开防火墙端口、无需购买服务器，一条 Cloudflare Tunnel 即可让 dsh web 安全上线公网（HTTPS / DDoS 防护全由 Cloudflare 提供）
开箱即用的安全防线：管理员密码登录 + 会话 Cookie + 防暴力破解限速 + 防 DNS rebinding，未认证流量永远到不了 dsh 本体
即插即用：npm 安装 → 配置密码 → 绑定域名，三步完成，无需改 dsh 一行代码

它解决什么问题

dsh 的 HTTP 服务器（ctx.webServer）没有请求级中间件钩子，host 默认绑定 127.0.0.1，无 TLS / 认证 / origin 策略。本插件自起一个独立的 node:http 网关，先做管理员验证，通过后反向代理到 dsh web 本体，并正确改写 Host / Origin / Referer 头以满足 dsh Connection 信任检查（isTrustedApiRequest）。

配合 Cloudflare Tunnel 使用时，隧道只把流量送到网关端口，未认证请求永远到不了 dsh 本体。

功能特性

管理员密码登录（scrypt 哈希 + timingSafeEqual 时序安全比较）
HttpOnly + SameSite=Strict 会话 Cookie，服务端内存会话，TTL 可配
登录失败按 IP 限速锁定（防暴力破解）
Host 头白名单校验（防 DNS rebinding）
请求体大小上限（防超大报文攻击）
可选 per-IP 请求速率限制
安全响应头（X-Frame-Options / X-Content-Type-Options / Referrer-Policy）
/api 未认证返回 401 JSON；浏览器页面未认证 302 跳转登录页
反向代理时改写 Host / Origin / Referer，满足 dsh 信任检查
WebSocket / SSE 升级代理（dsh web UI 依赖事件流）

安装

npm install dsh-admin-gateway

作为 dsh 插件（bundle）安装到 profile：

# 在插件目录的父目录执行（不要在插件目录内写 ./dsh-admin-gateway）
cd /path/to/parent && dsh plugin --profile web add ./dsh-admin-gateway
# 或通过 npm 安装包名引用
dsh plugin --profile web add dsh-admin-gateway

确认插件已生效：

dsh --profile web --dump-config | grep -A3 'admin-gateway'
# 看到 "# == dsh-admin-gateway" 层 = 成功

配置

插件通过 cordis.patch.yml（或 profile 的配置层）注入，示例：

- insert:
    - id: admin-gateway
      name: dsh-admin-gateway
      config:
        port: 3081
        upstream: 'http://127.0.0.1:3080'
        allowedHosts:
          - dsh.example.com
        sessionTtlMs: 43200000
        maxBodyBytes: 5242880

配置项

字段	默认值	说明
`port`	`3081`	网关监听端口
`host`	`127.0.0.1`	网关监听地址，只应绑定回环（由 cloudflared 从本机连入）
`upstream`	`http://127.0.0.1:3080`	上游 dsh web 地址
`adminPassword`	`''`	管理员密码；优先取环境变量 `DSH_ADMIN_PASSWORD`，其次取此值。两者都为空时插件启动报错
`sessionTtlMs`	`43200000` (12h)	会话有效期（毫秒）
`cookieName`	`dsh_admin_session`	会话 Cookie 名称
`loginMaxAttempts`	`5`	登录失败限速：窗口内允许的最大失败次数
`loginWindowMs`	`600000` (10min)	登录失败限速窗口（毫秒）
`loginLockMs`	`600000` (10min)	锁定时间（毫秒），超过 maxAttempts 后锁定该 IP
`maxBodyBytes`	`5242880` (5MB)	请求体大小上限（字节）
`reqLimitPerMin`	`0`	可选：每 IP 每分钟最大请求数，0 表示不限制
`allowedHosts`	`[]`	Host 白名单（防 DNS rebinding）；留空接受任意 Host
`allowedIps`	`[]`	可选：IP 白名单，留空不限制来源 IP

使用步骤

1. 设置管理员密码（推荐环境变量方式，避免明文进配置）：

``sh # 写入 600 权限的 env 文件，例如 /etc/dsh/admin-gateway.env echo 'DSH_ADMIN_PASSWORD=你的强密码' > /etc/dsh/admin-gateway.env chmod 600 /etc/dsh/admin-gateway.env ``

2. 配置 dsh 启动（systemd 用户服务示例）：

``ini # ~/.config/systemd/user/dsh.service [Service] Type=simple EnvironmentFile=/etc/dsh/admin-gateway.env Environment=PATH=/path/to/npm-global/bin:/usr/local/bin:/usr/bin:/bin ExecStart=/path/to/dsh web Restart=always RestartSec=3 ``

``sh loginctl enable-linger $USER # 关键！否则用户服务不随开机启动 systemctl --user daemon-reload && systemctl --user enable --now dsh.service ``

3. Cloudflare Tunnel 只指向网关端口（示例端口 3081），dsh 本体 3080 保持仅本机可访问。完整配置见下文「通过 Cloudflare Tunnel 暴露到公网」。

4. 访问：浏览器打开外网域名 → 未认证跳转登录页 → 输入管理员密码 → 获得 HttpOnly 会话 Cookie → 正常使用 dsh web UI 与 API。

5. 改密码：编辑 env 文件后重启 dsh 服务（systemctl --user restart dsh.service），旧会话 Cookie 到期前仍有效。

通过 Cloudflare Tunnel 暴露到公网

推荐用 Cloudflare Tunnel（cloudflared）把网关端口暴露到公网：不需要公网 IP、不用开防火墙端口，自带 HTTPS 和 DDoS 防护。关键原则：隧道只指向网关端口（如 3081），dsh 本体（3080）保持仅本机监听。

公网用户 → https://dsh.example.com → Cloudflare 边缘 → cloudflared 隧道 → 网关 127.0.0.1:3081 (鉴权) → dsh web 127.0.0.1:3080

1. 安装 cloudflared

# Ubuntu/Debian（apt 仓库）
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared focal main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install -y cloudflared

2. 登录并授权域名

cloudflared tunnel login

会打印一个授权 URL，在任意浏览器打开（服务器无 GUI 时复制到本机浏览器打开），登录 Cloudflare 并选择要绑定的域名，授权完成后 ~/.cloudflared/cert.pem 生成即成功。cloudflared tunnel list 报 Cannot determine default origin certificate path 说明登录没完成，重新执行。

3. 创建隧道

cloudflared tunnel create dsh-tunnel
# 输出：Tunnel credentials written to /home/<user>/.cloudflared/<UUID>.json

4. 编写 config.yml（指向网关端口！）

# /etc/cloudflared/config.yml
tunnel: <UUID>                          # 上一步输出的 UUID
credentials-file: /etc/cloudflared/<UUID>.json
ingress:
  - hostname: dsh.example.com           # 你的外网域名
    service: http://localhost:3081      # ⚠️ 指向网关端口，不是 3080！
  - service: http_status:404            # catch-all 兜底规则，必须最后一行

注意：写文件不要用 heredoc 管道过 sudo（sudo 会吞掉 stdin 当密码导致文件没写成）。先写到 /tmp 再复制：echo '<密码>' | sudo -S cp /tmp/config /etc/cloudflared/config.yml。

5. 绑定 DNS

cloudflared tunnel route dns dsh-tunnel dsh.example.com
# 创建 CNAME：dsh.example.com → <UUID>.cfargotunnel.com

若报 code: 1003 An A, AAAA, or CNAME record with that host already exists，说明该域名已有 DNS 记录，需要先在 Cloudflare 控制台删除旧记录或用 API 更新。

6. 安装为 systemd 服务（开机自启）

sudo cloudflared service install
sudo systemctl enable --now cloudflared

若提示 service is already installed at cloudflared-update.service（旧版本残留），先 cloudflared service uninstall 并删除 /etc/systemd/system/cloudflared*.service 再重装。建议确认 unit 里是 --config /etc/cloudflared/config.yml 的 config 模式（token 模式会忽略你的 config.yml）。

7. 验证

cloudflared tunnel info dsh-tunnel      # 看到 ≥1 条 active edge connection 即正常
sudo systemctl status cloudflared       # active (running)
sudo journalctl -u cloudflared -n 50    # 出现 INF Registered tunnel connection ... protocol=quic 即成功

外网测试（浏览器 UA，否则可能被 Cloudflare Bot 防护拦 403）：

curl -A 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/126.0' -I https://dsh.example.com/
# 返回 302 跳转登录页 = 隧道 + 网关都正常

Cloudflare Tunnel 常见坑

症状	原因	修复
`curl` 返回 403 Attention Required	Cloudflare Bot 防护拦截 curl 默认 UA	加浏览器 UA 头重试
隧道起了但外网访问旧站点	本地 DNS 缓存了旧解析（CDN 泛解析影子）	`sudo resolvectl flush-caches`，用 `dig @1.1.1.1 dsh.example.com` 验证返回 CF 边缘 IP（104.21.x / 172.67.x）
服务重启后隧道不回来	原 unit 是 `Restart=on-failure`，干净退出不重启	`sudo sed -i 's/Restart=on-failure/Restart=always/' /etc/systemd/system/cloudflared.service` 后 `daemon-reload`
`route dns` 报 code 1003	域名已有 DNS 记录，route 只创建不覆盖	Cloudflare 控制台删除旧记录后重试，或用 API 更新 CNAME
隧道指到 3080 后 API 403	请求绕过了网关直连 dsh，触发信任检查	确保 ingress 指向网关端口 3081

测试

项目自带无依赖 smoke test（mock ctx 加载插件 + 真实 HTTP 断言）：

node smoke-test.mjs

覆盖：未认证页面 302、未认证 /api 401 JSON、错误密码 401、正确密码 302+Set-Cookie（HttpOnly/SameSite=Strict）、伪造 Cookie 拒绝、恶意 Host 403（DNS rebinding）、登录限速 429、安全头、WebSocket upgrade 101（未认证 401）、SSE 长连接透传。

注意事项 / 已知坑

dsh 信任检查：dsh 对 /api 请求有 isTrustedApiRequest() 检查——Host 必须为 loopback；带 Origin 头时 origin.host 必须 === host.host，否则 403 "forbidden"。本插件已自动改写 Host/Origin/Referer（普通请求 + WebSocket upgrade 都处理），无需额外配置；若自行实现反代请务必同步改写这三个头。
WebSocket 事件流：dsh web UI 依赖 /api/events.mux 与 /api/events.host。这两个路径 GET 返回 426 upgrade required 是正常现象（信任检查已通过，要求升级 WebSocket）；返回 403 才是信任检查失败。
RPC 调用格式：POST /api/<namespace>/<method>，body 需带完整 client-request 结构（{"type":"client-request","rpcId":"...","method":"<namespace>/<method>","payload":{}}），method 字段必须与 endpoint 用斜杠形式一致。
密码来源优先级：DSH_ADMIN_PASSWORD 环境变量 > config.adminPassword；两者都未设置时插件启动直接抛错。
会话存储：会话表在内存中，重启 dsh 后所有会话失效（需重新登录）。
多实例：网关无共享状态，多个 dsh 实例各自起网关时注意端口冲突。
上游地址：upstream 只能指向本机或可信内网地址（网关本身不校验上游，配错会代理到意外目标）。

License

MIT

dsh-admin-gateway

Install

Check the source files

dsh-admin-gateway

核心优势

它解决什么问题

功能特性

安装

配置

配置项

使用步骤

通过 Cloudflare Tunnel 暴露到公网

1. 安装 cloudflared

2. 登录并授权域名

3. 创建隧道

4. 编写 config.yml（指向网关端口！）

5. 绑定 DNS

6. 安装为 systemd 服务（开机自启）

7. 验证

Cloudflare Tunnel 常见坑

测试

注意事项 / 已知坑

License

Source facts

Install

Check the source files

dsh-admin-gateway

核心优势

它解决什么问题

功能特性

安装

配置

配置项

使用步骤

通过 Cloudflare Tunnel 暴露到公网

1. 安装 cloudflared

2. 登录并授权域名

3. 创建隧道

4. 编写 config.yml（指向网关端口！）

5. 绑定 DNS

6. 安装为 systemd 服务（开机自启）

7. 验证

Cloudflare Tunnel 常见坑

测试

注意事项 / 已知坑

License

More related plugins

dsh-hooks-claude-code

dsh-hooks-codex

WeKnora#dsh-weknora