前言¶
DSH 的插件化思路适合把扩展能力作为独立包接入。对于需要把 WebUI 暴露给团队、反代或局域网访问的场景，一个常见问题是：未登录的浏览器是否还能读取页面资源、调用接口、建立实时连接。
dsh-webui-auth 针对这个点提供一个持久化认证插件：先在设置中创建账号密码，之后访问 WebUI 需要先登录。
这是什么¶
dsh-webui-auth 是 DeepSeek Harness（DSH）的 WebUI 身份认证插件，许可证为 MIT，零依赖。
它做的事情比较集中：在 DSH WebUI 前增加登录门禁。创建账号密码后，未认证的浏览器无法加载 WebUI 的资源、调用接口或建立实时连接。认证在 HTTP/传输层强制执行。
核心能力¶
下面介绍它已具备的能力。
- 四层防护：覆盖 WebUI 资源、插件 bundle、
/apiRPC 接口、WebSocket。 - 不改动 DSH 核心包源码：通过运行时包装
webServer路由实现。 fail-closed：预期路由缺失或包装不完整时拒绝启用认证。- 会话持久化：服务端会话写入
sessions.jsonl，由HttpOnly; SameSite=LaxCookie 携带。 - 凭据存储：密码以
scrypt哈希保存在dsh-webui-auth.json，明文不落盘。 - 登录限流：登录失败按客户端 IP 限流，每分钟最多 5 次。
- 审计日志：安全事件追加写入
audit.jsonl，客户端 IP 以HMAC-SHA256假名化存储。 - 首次初始化：需要每次启动生成的
setup token。 - 安全头：登录页与 API 响应带严格 CSP、
nosniff、DENY、no-referrer、noindex、no-store。 - 外观：登录页与设置页跟随 DSH 自带外观设置。
- 零依赖。
安装与启用¶
先执行安装命令：
npx @deepseek-ai/dsh plugin --profile web add dsh-webui-auth
安装后重启 DSH 即生效。
首次启用时，先打开 WebUI 的「设置 → 身份认证」，或访问：
/dsh-webui-auth/login
然后输入启动日志中打印的 setup token，创建账号密码。
启用后：
1、未登录访问任意路径会跳转登录页。
2、登录后按会话有效期免登录，默认 12 小时。
3、修改、禁用、退出均需当前密码。
4、修改密码会吊销所有其他已登录会话。
如果忘记密码，删除数据目录中的 dsh-webui-auth.json。最多 1 分钟内认证会自动关闭，之后用新的 setup token 重新创建账号。
审计与数据文件¶
审计日志追加写入 audit.jsonl。可以通过 CLI 查看：
node index.js audit --limit 50
数据目录按安装方式区分：
- npm / GitHub / tarball 安装：插件包体位于
node_modules内，数据目录为node_modules上级的.dsh-webui-auth/。 - 本地 link / 源码安装：数据目录为插件源码目录。
- 兜底目录：
$DSH_HOME/dsh-webui-auth/。
从 0.3.x 升级时，运行数据不自动迁移。需要手动拷贝以下文件：
dsh-webui-auth.json
sessions.jsonl
audit-hmac-key
audit.jsonl
使用注意与边界¶
以下边界在安装和部署前最好先确认。
- 插件以当前
dsh进程权限运行，安装前应检查源码与许可证。 - WebSocket 升级仍受核心
isTrustedApiRequest限制。反代或局域网部署时，需要把对外域名加入client-connection.trustedHosts。 - 运行时路由包装在热重载到下一次重扫之间存在不超过 10 秒的未保护窗口。
- 反代与 DSH 不在同一台机器时，代理头不被信任，限流会按代理 IP 聚合。
- 审计日志中的 IP 假名化不能防止拥有文件权限的本地攻击者。
- 威胁模型为浏览器/网络客户端。能直接读写宿主进程内存或文件的本地进程不在防护范围内。
0.1.x的 SHA-256 凭据自0.2.0起不再可校验。需要删除凭据文件后重新创建账号。
适用场景¶
dsh-webui-auth 适合需要给 DSH WebUI 增加登录门禁的受控访问场景：账号密码一次创建后会话可持久化，认证覆盖资源、接口和 WebSocket，审计日志可本地查看，部署上不需要改动 DSH 核心源码。
GitHub 仓库地址：
