前言¶

如果要在 dsh web 前加登录门禁，常见做法是在反向代理或外层服务上临时挡一下。dsh-auth-gateway 是 xbzbing 维护的 Cordis 网关插件，MIT 许可，面向 DeepSeek Harness（dsh web）提供密码认证、TOTP 双因素认证、真实请求拦截、会话管理与登录审计。

下面介绍它的能力、安装方式、启用 TOTP 的方法，以及卸载和密码重置时的注意点。

这是什么¶

dsh-auth-gateway 是一个网关层插件：它为 dsh web 建立认证门禁，并在网关层拦截未认证的 HTTP 与 WebSocket 请求。它不是单纯给页面加一个登录框，而是把认证、会话、限流和审计放在 dsh web 的请求路径上处理。

维护者为 xbzbing，许可证为 MIT。README 说明本项目已支持 dsh 0.1.1-rc.2；package.json 声明 Node >= 20。

核心能力¶

先做密码门禁，再按需要启用 TOTP。下面列出它覆盖的主要事项：

• 为 dsh web 提供密码认证门禁
• 支持 TOTP 双因素认证与一次性备份代码
• 在网关层拦截未认证的 HTTP 与 WebSocket 请求
• 记录登录成功、失败、登出、改密与暴力破解告警的审计日志
• 提供密码失败锁定、全局登录速率限制与 OTP/备份码独立限流
• 提供基于内存 token 与 HttpOnly Cookie 的会话管理
• 支持反向代理子路径 basePath 与可选认证设置面板

安装与启用¶

安装插件：

dsh plugin --profile web add dsh-auth-gateway

启动 dsh web：

dsh web --port 8080

首次部署后，会生成一次性初始密码，并打印在控制台。先复制初始密码，再打开 dsh web 页面登录。

登录后会进入个人密码设置步骤。个人密码设置是强制步骤，完成前所有功能不可用。经过上面的步骤后，后续访问 dsh web 会先经过登录门禁。

启用 TOTP¶

如果启用 TOTP，登录后访问：

/otp/setup

在该页面启用 TOTP，并保存一次性备份代码。已启用 OTP 后，登录需要密码 + 验证码（或备份代码）。

OTP 密钥以 AES-256-GCM 加密存储。主密钥可以来自环境变量：

DSH_AUTH_GATEWAY_MASTER_KEY

也可以来自自动生成的：

auth-gateway/otp-master.key

会话、限流与审计¶

会话管理使用内存 token 与 HttpOnly Cookie。

防护策略包括：

• 密码失败锁定
• 全局登录速率限制
• OTP/备份码独立限流

审计日志会记录登录成功、登录失败、登出、改密与暴力破解告警。日志持久化到：

$DSH_HOME/auth-gateway/audit.log

按天轮转，保留 90 天，不记录凭据。

子路径部署¶

如果 dsh web 不是部署在根路径，而是放在反向代理子路径下，子路径部署时需要在部署方 profile patch 中配置 basePath。插件本身也提供可选认证设置面板。

密码重置与卸载¶

忘记密码时，可以用 dsh-auth-gateway-reset 重置，重启后控制台会打印新初始密码。

卸载时先清凭据，再移除插件：

~/.dsh/profiles/web/node_modules/.bin/dsh-auth-gateway-uninstall
dsh plugin --profile web remove dsh-auth-gateway

适用场景与注意¶

适合以下场景：

• 需要给 dsh web 加密码登录门禁
• 需要 TOTP 双因素认证与备份代码
• 需要拦截未认证 HTTP 与 WebSocket 请求
• 需要保留登录审计与限流记录

安装前需要注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证
• 许可证为 MIT
• README 说明支持 dsh 0.1.1-rc.2，运行环境需要 Node >= 20
• 存在一项记录在案的安全例外：LAN trust 为域名/反代访问模型设置页做最小介入

相关链接¶

GitHub：

https://github.com/xbzbing/dsh-auth-gateway

插件目录线索（以实际目录为准）：

https://www.skillhub.cn/plugins/xbzbing/dsh-auth-gateway