前言¶
DSH 的插件生态强调「一切皆插件」；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。dsh-auth-gate 是这个生态里的一个认证插件，目标很具体：给 DSH web 实例增加一道登录门，使页面、API 调用和 WebSocket 连接都需要有效会话。
它适合需要把 dsh web 实例开放给浏览器用户和脚本调用的场景。经过这个插件后，未登录的浏览器访问会看到登录页，脚本请求则需要显式携带令牌或会话凭据。
这是什么¶
dsh-auth-gate 是 DSH web 实例的登录门插件。
仓库地址为 https://github.com/TecFancy/dsh-auth-gate。已抓取资料没有单独的 author / maintainer 字段，因此本文只把地址中的 TecFancy 作为 owner 线索，不把它当成正式维护者声明。
资料中可见的基础信息包括：
- 许可证：MIT。
- 运行环境要求：
Node >=22.19.0。 package.json声明了两个 bin：dsh-auth和dsh-auth-proxy。已核实资料详细列出的是dsh-auth的用户管理命令。
核心能力¶
统一拦截页面、API 和 WebSocket¶
dsh-auth-gate 的核心行为是：页面、API 调用和 WebSocket 连接都需要有效会话。没有有效会话的访问会被挡下，浏览器侧可走登录页，脚本或 curl 请求则需要使用 Authorization: Bearer <token> 跳过登录页。
两种认证模式¶
插件支持两种认证模式：
- 密码认证：使用用户名和口令。
- 共享令牌认证：使用一个共享密钥。
默认挂载配置为 mode: token，共享密钥使用 DSH_AUTH_TOKEN 环境变量保存。
可选 TOTP 两步认证¶
密码模式下支持可选的 TOTP 两步认证，遵循 RFC 6238。totp 可配置为 off、optional 或 required。
启用某个用户的 TOTP 后，登录时需要额外输入验证码。验证码每 30 秒变化，并允许前后窗口容差。
默认安全策略¶
已核实资料中列出的默认安全策略包括：
- 口令以哈希存储。
- 登录尝试会受限速。
- 会话 cookie 使用
secure设置。 - 配置缺失或损坏时会阻止访问，而不是静默放行。
用户管理 CLI¶
插件提供 dsh-auth CLI，用于：
- 添加用户。
- 列出用户。
- 禁用用户。
- 启用或禁用 TOTP。
安装与启用¶
先安装插件到 web profile：
dsh plugin --profile web add dsh-auth-gate
这个命令会把插件安装到对应 profile 中。安装后，CLI 不直接加入 PATH，需要通过 profile 调用。
如果启用密码模式，先创建管理员账户。示例中通过 pnpm --dir 进入 web profile 目录执行 dsh-auth：
printf '%s\n' 'choose-a-strong-password' | pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user add admin --password-stdin
接着在 $DSH_HOME/cordis.patch.yml 中覆盖挂载配置。下面示例只覆盖 mode、totp 和 cookieSecure：
- id: dsh-auth-gate
config:
mode: password
totp: optional
cookieSecure: true
经过上面的步骤后，访问 DSH web 实例时会进入登录门。默认 cookieSecure: true 适合 HTTPS 环境；只有在普通 http 测试时才考虑将其设为 false。
配置项¶
已核实资料列出以下配置项：
| 配置项 | 说明 |
|---|---|
mode |
认证模式。默认挂载配置为 token，也可配置为 password。 |
totp |
密码模式下的 TOTP 策略，可配置为 off、optional 或 required。 |
sessionTtl |
登录会话有效期，单位为秒。默认为 604800。 |
cookieName |
会话 cookie 名称。 |
tokenRef |
令牌模式下引用的环境变量。默认挂载配置使用 DSH_AUTH_TOKEN。 |
cookieSecure |
会话 cookie 的 secure 设置。默认为 true，仅普通 http 测试时才考虑设为 false。 |
usersFile |
密码模式下的用户列表文件位置。资料说明默认为 $DSH_HOME/auth/users.yaml。 |
logoutOrder |
控制 Settings → General 中 Sign out 按钮的槽位顺序，数值越大越靠下。 |
典型用法¶
管理用户¶
资料中列出的用户管理命令包括：
dsh-auth user add admin --password-stdin
dsh-auth user list
dsh-auth user disable admin
dsh-auth user totp enable admin
dsh-auth user totp disable admin
如果插件是通过 dsh plugin --profile web add dsh-auth-gate 安装到 profile 中，可以按 profile 调用，例如：
pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user list
启用 TOTP¶
为某个用户启用 TOTP：
dsh-auth user totp enable admin
命令会输出 TOTP secret 或 otpauth:// URI。将该 secret 或 URI 添加到验证器应用后，用户即可在密码模式下使用验证码登录。
脚本请求¶
脚本或 curl 请求可以携带 Bearer token 跳过登录页：
Authorization: Bearer <token>
适用场景与注意¶
适合以下场景：
- DSH web 实例需要对外提供服务，但页面、API 和 WebSocket 都需要登录校验。
- 浏览器用户走登录页，自动化脚本走 Bearer token。
- 密码模式下需要管理多个用户，并对部分或全部用户启用 TOTP。
注意以下事项：
- 该插件会以当前 DSH 进程权限运行，安装前应检查源码和许可证。本插件许可证为 MIT。
- 共享令牌模式下，
DSH_AUTH_TOKEN是敏感凭据，应避免写入仓库或日志。 cookieSecure默认为true，仅在普通http测试时才考虑关闭。- 配置缺失或损坏时会阻止访问，这是预期行为，不是静默放行。
- TOTP 验证码每 30 秒变化，并允许前后窗口容差。
相关链接¶
GitHub 仓库：https://github.com/TecFancy/dsh-auth-gate
如需在 DSH 社区目录中查找，可在独立目录站点中检索 dsh-auth-gate。
