dsh-ui-auth

dsh plugin --profile web add dsh-ui-auth

dsh-ui-auth — DSH Web UI 认证网关插件

面向：首次接触本插件的用户。





🔴 兼容性提示：legacy 版本（DSH 0.1.1-rc.2）的支持已于 v0.7.0 结束

v0.7.0 起本插件只跟随 DSH 的新版本开发（目标版本 0.2.0-rc.2），

legacy 传输线（dotted /api/<a>.<b> + apiProxy）的代码已完全移除：

宿主未提供现代传输能力时插件会 fail-closed（认证网关不建立、面板不可访问并输出明确错误），

不会退回旧传输线，更不会降级成无门放行。

若 DSH 后续架构有大变动，我会提前声明该版本的支持结束时间，不会突然中断。

仍在使用 0.1.1-rc.2 的部署请在此之前按 [DSH 版本兼容性](#dsh-版本兼容性) 一节规划升级。

给 DeepSeek Harness（DSH）的 Web UI 加一道用户名 / 密码登录门：未登录时无法访问任何页面、

API 或 WebSocket 通道；登录后可管理用户、邀请码、两步验证（TOTP）与通行密钥（Passkey），

并按登录用户隔离会话数据。

适用场景：把 DSH 面板暴露到内网或公网时，需要一个前置认证层，并希望不同使用者之间互不可见。

文档导航（按角色）

本 README 只讲怎么装、怎么登录、怎么用。更深的主题按你的角色分流（完整清单见 [docs/INDEX.md](docs/INDEX.md)）：

你的角色 · 去哪读

第一次用，只想跑起来 · 本文往下读即可

负责部署与运行 · [运维手册](docs/OPERATIONS.md)（环境变量、备份、升级、排障）

做安全审计 · [安全模型](docs/SECURITY.md) + [验证证据](docs/SECURITY-VERIFICATION.md)

要升级 DSH / 做集成 · [0.2.0 兼容性](docs/DSH-0.2.0-COMPATIBILITY.md)

想读代码 / 提 PR · [架构](docs/ARCHITECTURE.md) + [贡献指南](CONTRIBUTING.md)

特性一览

• 全接口拦截：在 DSH 路由分发之前包装其 HTTP 服务器，覆盖 /api/、/plugins/、HMR、

SPA fallback 与 WebSocket 升级通道，没有旁路。未登录时页面请求 302 跳登录页、API 返回 401、

WS 升级直接断开；登录后原请求原样透传。

• 登录页与注册页：中文 / English 双语，跟随 DSH 的语言设置自动切换（见[多语言](#多语言i18n)）；

登录成功写入会话 Cookie（HttpOnly、SameSite=Strict、12 小时滑动续期），Cookie 名按实例唯一

（同机多实例不会互相踢下线）；注册需邮箱 + 用户名 + 密码 + 有效邀请码，注册成功自动登录并引导绑定 TOTP。

• 用户管理：所有用户可改自己的昵称/邮箱/密码并管理自己的 TOTP 与通行密钥；管理员可增删用户、

重置密码、切换角色、生成/撤销邀请码、清除某人的通行密钥。任何人都无法查看他人的当前密码。

• 两步验证（TOTP）：RFC 6238，可用 Google / Microsoft Authenticator 扫码绑定，也支持手动输入密钥；

启用后登录需「密码 + 动态码」（账号未绑定 TOTP 时，第二步改用通行密钥）。

• 通行密钥（Passkey / WebAuthn）：用指纹、面容或设备 PIN 代替密码登录，一个账号可绑定多个

（本机密钥 + 手机密钥）。支持不输入用户名的一键登录；手机可用浏览器显示的二维码扫码绑定。

私钥永不离开用户设备，服务器只保存公钥。

• 模型与 API Key 按用户隔离（v0.7.0）：每个用户在【设置】→【模型】里管理只属于自己的 provider/

模型/Key；私有 Key 用口令派生密钥信封加密（服务端在未解锁时无法解密），管理员在任何情况下

都读不到他人的私有配置。管理员可把自己的模型分享给指定用户——对方可选用、可看余额、看不到 Key，

撤销立即失效。未配置即阻断（不回退部署级）。

• 按用户隔离：会话与工作区在创建时记录归属；普通用户的会话/工作区列表只显示自己的，

直连他人会话返回 403，管理员不受限。

直播通道（WebSocket）：0.2.0 客户端把它当作主连接通道且普通用户也需要，因此网关校验会话后

在本插件内做透明代理，按登录归属逐帧过滤（宿主会把全部工作区/会话推给每个连接，Issue #6）。

• 登录防护：密码 PBKDF2-HMAC-SHA256（每用户随机盐、60000 轮、常量时间比较）、

密码策略「≥8 位且至少两种字符类型」、按来源 IP 的失败锁定、认证响应一律 Cache-Control: no-store；

通行密钥使用一次性短时挑战、严格的来源/RP ID 校验与签名计数器回退检测。

• 修改密码（引导式）：需先通过「当前密码」校验才解锁新密码输入；新密码实时给出强度三档

（红/黄/绿 + 荧光），确认框在强度达标后解锁并实时比对。

• 多语言（i18n）：界面文案中/英双语，跟随 DSH 的 locale 服务即时切换（客户端订阅 locale/change，

服务端渲染页按 Accept-Language），详见[多语言](#多语言i18n)。

• 会话与审计：会话可跨重启恢复（磁盘只存 Token 的 SHA-256 哈希）；管理员操作与越权尝试

追加写入 dsh-ui-auth-audit.jsonl（JSONL 审计文件）。

环境要求

项 · 要求

DSH · >=0.2.0-rc.2 <0.3.0（web profile）。v0.7.0 起只支持 0.2.0 线——legacy 的 0.1.1-rc.2 传输线已移除，失去现代传输能力时插件 fail-closed（面板不可访问并打印明确错误），详见[兼容性矩阵](docs/DSH-0.2.0-COMPATIBILITY.md)

Node.js · ^22.19.0 · · >=24.0.0（与 DSH 一致）

运行时依赖 · qrcode（生成 TOTP 二维码）、ws（流式通道）与 @simplewebauthn/server（通行密钥服务端校验），安装时自动获取，无需手动构建

浏览器 · 通行密钥需要 Chrome / Edge / Safari / Firefox 等支持 WebAuthn 的现代浏览器；不支持时其余功能不受影响

通行密钥对访问地址有硬性要求（浏览器规则，插件无法绕过）：

访问地址 · 通行密钥 · 说明

https://你的域名 · ✅ 可用 · 推荐的生产部署方式（反代终止 TLS）

http://localhost:3080 · ✅ 可用 · 本机使用请用 localhost，不是 127.0.0.1

http://127.0.0.1:3080 · ❌ 不可用 · Chrome 拒绝 IP 地址作为通行密钥域（RP ID）；面板会提示改用 http://localhost:3080

http://内网IP:3080 · ❌ 不可用 · 明文 HTTP 不是安全上下文，且 IP 不能作为 RP ID；需域名 + HTTPS

安装

本包是标准的 DSH profile bundle（声明了 dsh.bundle.patch 与 dsh.client），

dsh plugin 会自动把它加入 profile 的 bundle 名单：

# 从 npm 安装
dsh plugin --profile web add dsh-ui-auth

# 或固定到某个 GitHub 发行版本
dsh plugin --profile web add github:0QwQ0/dsh-ui-auth#v0.7.0

# 或从本地目录安装（离线 / 二次开发）
dsh plugin --profile web add <本插件目录的绝对路径>

安装完成后重启一次面板生效（bundle 层在启动时应用）。

首次登录

用户表为空时，插件会自动创建管理员 admin，随机密码同时输出到两处：

1. 面板控制台日志（以 [dsh-ui-auth] 开头）；

2. 面板进程工作目录下的 dsh-ui-auth-bootstrap.txt。

打开面板会跳转到 /auth/login，用 admin 与上述随机密码登录。

登录后请立即在【设置】→【用户管理】中修改密码；任意用户改密成功后，引导文件会自动删除。

使用指南

设置面板 → 用户管理

• 所有用户：修改自己的昵称、邮箱、密码；绑定/移除自己的 TOTP 令牌；添加/重命名/删除自己的

通行密钥；开关两步验证。

• 管理员：新增/删除用户、重置他人密码、切换角色、生成与撤销邀请码（可查看每个码的

已用次数与剩余次数）、移除任意用户的 TOTP、清除任意用户的通行密钥（设备丢失时救援）。

• 保护规则：不能删除或降级最后一个管理员，不能删除自己；改密或删除用户后，其其他会话立即失效。

修改密码（引导式校验）

【用户管理】→ 修改密码：先输入当前密码，离开该输入框时自动校验；通过则边框变绿（2px 向外荧光）

并解锁下面两个输入框，失败则变红且保持锁定。新密码实时评估强度：不满足=红、刚满足=黄、很强=绿；

只有在至少黄色时才解锁「确认新密码」，并实时比对（不匹配红、匹配绿）。注册页采用同一套规则。

注册与邀请码

注册入口在登录页的「注册账号」。新用户需要管理员事先在【用户管理】→【邀请码管理】中生成的有效邀请码；

每个码可设置 1–100 次的注册次数，可随时撤销。邮箱目前只做格式填写、不校验真实性，注册后可在用户管理中修改。

两步验证（TOTP）与通行密钥（Passkey）

两步验证可以用两种因子满足：TOTP 动态码或通行密钥。绑定任一种后即可在

【用户管理】→「两步验证」用开关启用；开关打开后，登录方式如下（通行密钥始终可直接登录，

与两步验证开关无关）：

账号状态 · 可用的登录方式

两步验证关闭 · 用户名 + 密码；通行密钥

两步验证开启，已绑定 TOTP · 用户名 + 密码 + 动态码；通行密钥

两步验证开启，只绑定了通行密钥 · 用户名 + 密码 + 通行密钥；通行密钥（可不填用户名）

0.6.4 起移除了「免密 + 动态码」登录：只有动态码、没有密码的登录请求一律被拒绝。

免密入口统一收敛到通行密钥。

TOTP：在【用户管理】→「两步验证（TOTP）」生成密钥，用验证器 App 扫码（或手动输入密钥 /

otpauth 链接）后输入 6 位动态码完成绑定。动态码错误同样计入失败锁定；移除令牌需要当前动态码，

管理员可移除任意用户的令牌。

通行密钥：在【用户管理】→「通行密钥（Passkey）」中添加，同一个账号可以绑定多个：

• ＋ 本机通行密钥：使用这台电脑的 Windows Hello / Touch ID / 设备 PIN；
• 📱 手机扫码添加：浏览器会显示二维码，用手机相机扫码后在本机完成绑定（手机无需与面板处于同一网络，

也不需要手机能访问面板）；

• 绑定后登录页会出现「🔑 使用通行密钥登录」，点击即可不输入用户名与密码直接登录；

也可以照常输入用户名密码，在第二步提示时用通行密钥完成验证。

安全约定：通行密钥的私钥永不离开设备，服务器只保存公钥与名称等公开信息；添加、重命名、删除

通行密钥都需要先确认当前密码（两步验证开启时还需动态码或一次已有通行密钥的确认）；

为避免账号被锁死，两步验证开启且只剩一个通行密钥时不允许删除它——请先绑定 TOTP 或先关闭两步验证。

设备丢失时

…(truncated)