yyyq0325-ai/dsh-webgate

WebGate — DeepSeek Harness Web 登录门禁

为 DeepSeek Harness 的 Web GUI 加一道账号密码门：每次打开 DSH Web 都必须先登录；登录令牌有效期 12 小时；令牌过期被登出时，后台正在运行的任务完全不受影响，重新登录后一切还在。

📋 更新日志（新功能与破坏性变更都记录在这里）：CHANGELOG.zh.md

WebGate 登录页预览（中文）

特性

- 🔐 路由级登录门禁 — 通过 webserver/index-inject 向每个 index.html 注入守卫脚本：无令牌或过期立即 location.replace('/login') 跳转到独立登录页，登录后跳回原地址；守卫同步执行并临时隐藏文档，应用内容零闪现
- ⏱ 12 小时会话令牌 — 绝对有效期；前端 30 秒巡检 + 页面重新可见时向服务端复核；过期自动回到登录页
- 🚀 后台任务零打扰 — 门禁只作用于浏览器视图层，Host 端的会话、后台任务、子代理照常运行
- 🎨 DeepSeek 官网风登录页 — 直接对照 deepseek.com 的线上设计：#f9f8f8 浅色底 + 顶部天蓝渐变罩（#9cc1e7 → 透明）+ canvas 云团缓流 + 24px 玻璃卡片 + 官网同款近黑药丸按钮 + 官方字标，另有独立登录页 /auth/page
- 🖥 设置页图形化管理 — 在 DSH 设置的「WebGate 用户」页里增删用户、改密码、勾选成员可见工作区，无需再敲命令（v0.4.0 新增）
- 🛡 内置管理员不可撼动 — admin 恒为管理员：没有角色切换入口，也不渲染删除按钮；Host 侧拒绝删除/降级它，加载用户库时还会把被改坏的角色强制纠回 admin
- 🛠 用户管理命令 — /useradd /passwd /userlist /userdel /grant /revoke（密码不写入会话日志），另有 webgate_user_ 模型工具可让 Agent 代管
- 💾 持久化 — 用户库存放在 $DSH_HOME/.credentials.yaml 的 grant record 中，随 Harness 自身凭据文件一起管理，插件重启自动恢复
- 🌐 三语，跟随 DSH 语言设置 — 中文 / English / Русский；登录卡片底部与设置页都有对应语言，偏好记忆在本地，浏览器语言（zh / en / ru）自动识别；API 错误消息按请求的 Accept-Language 协商
- 👥 账号角色与工作区授权 — 创建用户时定角色（admin / member，默认 member），之后不再变更；成员仅能看到被授权的工作区；命令与工具沿用「管理员密码 sudo」模型，设置页则用当前管理员会话
- 🧩 零依赖 — 纯 JavaScript 实现；动态沙箱里没有 node:crypto，密码哈希使用内置 PBKDF2-HMAC-SHA256（20000 次迭代，已通过标准测试向量验证）

安装

✅ 本包已发布到 npm：@yyyq0325/dsh-webgate。npm 安装是现在的推荐方式（版本化、可锁定、无 Git 依赖）。
⚠️ 裸名 dsh-webgate 是另一个无关包，请勿使用。

方式 A：npm（推荐）

dsh plugin --profile web add @yyyq0325/dsh-webgate

安装命令会依据 package.json 的 dsh.bundle.patch 声明自动挂载本插件，重启 dsh 后生效。升级同样一条命令（或 npm update @yyyq0325/dsh-webgate 后重启）。

方式 B：从 GitHub 安装

dsh plugin --profile web add github:yyyq0325-ai/dsh-webgate

适合在官方 npm 版发布前体验最新分支（默认取仓库默认分支；可用 #分支名 指定）。

方式 C：手动挂载

把 cordis.patch.yml 中的 insert 行复制进 profile 的补丁文件 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: webgate
name: '@yyyq0325/dsh-webgate'

并确保本包已安装到 profile 可解析的位置（如 profile 目录下 npm i @yyyq0325/dsh-webgate）。

方式 C：临时动态插件（免安装）

不修改任何配置，直接在支持动态插件的会话中用 cordis_define 运行 dynamic/webgate.host.js 的内容作为 code.host。该文件由 npm run build:dynamic 从 src/index.js 自动生成。

⚠️ 动态形态只包含 Host 半边，因此设置页（浏览器半边）在该模式下不可用——dynamic/ 产物没有客户端模块。想用图形化界面管理用户，请用方式 A/B/C（安装整包）。

快速开始

首次激活时自动创建初始管理员：

用户名：admin
密码：admin1234

登录后请立即修改密码：

/passwd admin 你的新密码

界面语言：登录卡片底部「中文 / EN / Русский」分段控件一键切换并记住偏好；默认跟随浏览器语言（ru → 俄语，en → 英文，其余中文）。/auth/page 独立页与全部 API 提示同样三语（接口按 Accept-Language 协商；设置页跟随 DSH 自身的语言设置）。

在设置页里管理用户与工作区（v0.4.0 · 推荐）

打开左下角 设置 → WebGate 用户，即可完成全部账号管理，不必再敲命令：

- 添加用户：填用户名、密码，选角色（成员 / 管理员，默认成员），保存即创建；
- 可见工作区：展开某个成员行，勾选其可见的工作区；勾选「全部工作区」等价于 。勾选清单来自 Host 的工作区注册表（显示标题 + 完整路径），也可以按完整路径、标题或目录名手动添加；不在清单里的历史匹配项以可移除标签呈现；
- 改密码 / 删除用户：行内操作只剩这两个，删除有二次确认；「至少保留一个用户 / 一个管理员」的保护同样生效；
- 内置管理员 admin 是永久管理员：它那一行没有删除按钮，也没有角色切换入口；想再增加管理员，就在「添加用户」时选管理员角色；
- 即时生效：改密码或调整工作区都会撤销该用户的现有登录会话，需要重新登录。

鉴权方式与命令行不同：设置页用当前登录会话（webgate_token Cookie）判定权限，只有 admin 角色能用，因此页内不需要反复输入管理员口令；斜杠命令与模型工具仍保持「管理员口令 sudo」模型。

Host 侧新增的管理端点（同源，仅管理员会话可用，全部返回 { ok, reason, message, state }）：

| 端点 | 说明 |
|---|---|
| GET/POST /auth/api/admin/state | 用户清单 + 工作区清单 + 当前账号（不含口令哈希） |
| POST /auth/api/admin/user/add | 添加用户（可指定 role） |
| POST /auth/api/admin/user/passwd | 修改密码（撤销该用户会话） |
| POST /auth/api/admin/user/del | 删除用户（内置 admin 返回 protected-admin） |
| POST /auth/api/admin/workspace/grant | 授予工作区（ 为全部） |
| POST /auth/api/admin/workspace/revoke | 撤销工作区（/all 清空） |

角色没有在线变更端点：role 只在创建用户时写入；内置 admin 的角色在每次加载用户库时都会被强制纠回 admin。

命令（所有变更命令都要求在末尾附带任意管理员账号的密码，即“sudo 口令”模式——只有知道管理员密码的人才能改动账号体系）：

| 命令 | 说明 |
|---|---|
| /useradd    | 添加 member 用户（用户名 2-32 位字母数字点下划线短横线；密码 6-128 位） |
| /passwd    | 修改密码，该用户现有会话立即全部失效 |
| /userlist | 列出用户、角色、工作区授权与活跃会话数 |
| /userdel   | 删除用户（内置 admin 拒绝删除；至少保留一个管理员） |
| /grant    | 授予成员一个工作区的可见性； 表示全部 |
| /revoke    | 撤销成员的工作区可见性；/all 清空全部授权 |

角色与工作区权限

- admin：拥有全部工作区与管理能力。内置 admin 账号是永久管理员——不可删除、角色不可变更（Host 拒绝，设置页也不提供入口）；如果你在「添加用户」时选了管理员角色，那个账号同样拥有管理能力，但可以被删除（前提是至少留一个管理员）。
- member：登录后只能看到被 /grant 授予的工作区（按完整路径或标题匹配，大小写不敏感），未被授予的条目会在客户端被过滤隐藏，对其余工作区的操作无从发起。
- 授权变更会立即撤销该成员的现有会话，重新登录后生效新权限。
- 界面裁剪：member 会话自动隐藏左下角设置入口、工作区搜索按钮与列表头操作区（含添加工作区）；同时拒绝 settings.、workspace.create、session.search、host.createDirectory 等 RPC（返回标准错误信封，界面优雅报错）。
- ⚠️ 强度说明：工作区过滤运行在浏览器端（守卫脚本包装 fetch 实现），定位是“防误触”而非对抗有意绕过——详见下方安全边界。服务端级强制需要上游提供中间件/网关鉴权点。

诊断接口：GET /auth/api/health 返回服务可用性与用户库状态。

启用 / 停用 / 卸载（防锁死指南）

建议：先用动态插件模式试用，确认满意后再考虑持久安装。

动态插件模式（不落盘，随时可撤）

在支持动态插件的 DSH 会话中，把 dynamic/webgate.host.js 的内容作为 code.host 交给 cordis_define，再 cordis_run 即可。此模式：

- 不写入任何配置文件，~/.dsh/profiles//cordis.patch.yml 保持原样；
- dsh 进程重启后门禁自动消失，无需任何清理操作；
- 随时让 Agent 执行 cordis_stop  立即停用，页面立刻恢复原样（插件定义保留，一条命令可再次启用）；
- 代价：只有 Host 半边，设置页不可用（客户端模块随整包发布）。

npm 安装版的停用与卸载

dsh plugin --profile web remove @yyyq0325/dsh-webgate

手动 patch 行的停用与卸载

编辑 ~/.dsh/profiles/web/cordis.patch.yml，将插件行加上 disabled: true（保留配置停用）或整行删除（彻底卸载），重启 dsh 生效：

- insert:
- id: webgate
name: '@yyyq0325/dsh-webgate'
disabled: true   # 停用；或删除整个条目卸载

忘记密码怎么办

1. 打开 $DSH_HOME/.credentials.yaml（默认 ~/.dsh/.credentials.yaml）；
2. 删除 records: 段下 webgate/users: 的整段记录（其他内容一律不动）；
3. ⚠️ 如果删除后 records: 下面已经没有任何条目，必须把 records: 这一行也一并删除（或改写成 records: {}）。留一个空值的 records: 键会让 YAML 把它解析成 null，插件写入用户记录时会报 Expected YAML collection at records；
4. 重启 dsh —— 插件启动时发现没有用户，会重新引导初始账号 admin / admin1234。

该文件里同时保存着 API Key 等其他凭据，只删 webgate/users 那一段即可，其余行请保持原样。

兜底原则

本插件只注册自己的路由/监听/命令，除上述一条凭据记录外不修改任何 Harness 数据。无论出现何种异常，按上面任一方式停用插件并重启 dsh，即可完全恢复到安装前状态。

排查：装卸插件后全站 400/404

症状：安装或卸载任意插件后 Web 全挂——/ 与 /index.html 返回空 body 的 400，其余路径 404；卸载插件、重启 dsh 均无效。

原因：部分第三方插件把 peerDependencies 钉在旧版 @deepseek-ai/ 上。在 profile 目录里执行安装时，这些旧版包会被物化到 ~/.dsh/profiles/web/node_modules/@deepseek-ai/，而 cordis Loader 以 profile 目录为锚解析路由插件，旧版 @deepseek-ai/dsh-host-webserver 就会遮蔽 Harness 自带的新版；两个版本的 API 不匹配（新版 frontend-static 每次渲染 index 都要调用旧版上不存在的 renderIndex），于是所有页面都抛异常。

修复：

1. 完全退出 dsh；
2. 把旧版影子目录改名移走（确认恢复后可删除备份）：

Rename-Item ~/.dsh/profiles/web/node_modules/@deepseek-ai _stale-deepseekai-backup

3. 重启 dsh。这些包会经由 $DSH_HOME/profiles/node_modules 的软链接回退解析到 Harness 自带版本；
4. 页面恢复正常后删除 _stale-deepseekai-backup。

预防：往 profile 安装插件一律走 dsh plugin --profile web add （底层 pnpm，遵守 autoInstallPeers: false）；不要在 profile 目录手动跑 npm 安装——npm 会自动安装 peer 依赖，容易再次引入版本漂移。

工作原理

浏览器 ── GET / ──▶ webServer(fallback=静态 dist)
│ renderIndex()
│ ├─ 结构化注入表（webserver/index-inject 事件）
│ │   └─ WebGate：守卫脚本
▼
无令牌/过期 → location.replace('/login') ──▶ 独立登录页（双语）
│ POST /auth/api/login
▼ 校验 PBKDF2 哈希，签发 12h 令牌
登录成功 ◀── Cookie + localStorage 写入 token/exp ─┘ → 跳回 next（默认 /）
已认证 → 正常使用（30s 巡检 + visibilitychange 服务端复核 + 会话角标）

- 密码存储：PBKDF2-HMAC-SHA256(20000 iter, 16B random salt)，常数时间比较；命令参数带密码时不写入会话日志（recordInput: false）
- 用户库：一条 credentials grant record（key webgate/users），payload 为 JSON 字符串——字符串是原始值，可安全跨越动态插件沙箱与宿主之间的 realm 边界
- 设置页：整包的客户端半边（exports["./client"]，dsh.client.platform = web）向 Web 设置面板的 settings.section 槽注册一级页面，通过同源 fetch 调 /auth/api/admin/ 读写；页面用 ctx.locale 三语（内置 zh/en 走整表注册，ru 由 i18n 插件补进语言表、以单语言形式登记），样式只用主题变量 + 官网配色常量
- 生命周期：所有路由、监听、命令、工具注册均挂在插件 Fiber 上，停止/更新插件自动清理；客户端模块随插件行一起装载与卸载

安全边界（请务必阅读）

这是一个面向本地个人工具的入口门禁，不是企业级安全方案。当前为「守卫跳转」模式：守卫脚本运行在浏览器里，理论上可以被 DevTools 禁用或删除——绕过后页面外壳与 /api 数据通道仍然可达。原因与边界：

1. DSH 的 /api 数据通道由 @deepseek-ai/dsh-client-connection 以命名前缀路由注册在 webServer 上：路由一经注册不可覆盖、最长前缀优先使其他路由无法遮蔽它，而 webServer 本身没有请求中间件缝隙。因此动态插件无法在服务端对 /api 强制鉴权，这是当前 Harness 扩展点的硬限制，不是本插件的选择。
2. 默认只监听 127.0.0.1；若要暴露到局域网或公网，请自行在前面加反向代理等手段做真正的服务端鉴权。
3. 初始管理员密码是公开的默认值，部署后第一件事就是改密码。
4. 登录令牌保存在浏览器 localStorage 与内存中；同时下发 webgate_token Cookie（SameSite=Lax），为将来的网关级校验预留了通道。
5. 管理 API（/auth/api/admin/）以「当前登录会话是 admin」为鉴权：设置页因此不必反复输入管理员口令。这意味着一个 admin 的登录令牌 = 账号体系的完全控制权（本来也等价于该 admin 的 GUI 权限）。令牌只存在浏览器内存/localStorage 与本机 Cookie 中，默认仅监听 127.0.0.1；若对外暴露，请务必加反代鉴权并启用 HTTPS（Cookie 未设 Secure）。
5. 关于 Harness 0.1.5-alpha 的成员工作区过滤，请务必了解它的边界：
- alpha5 把工作区列表改成了 WebSocket 订阅流（/api/remote.mux）。守卫相应地包装了 WebSocket 并在浏览器端改写帧数据，使 member 的界面上只出现被授权的工作区；
- 但未授权工作区的完整数据仍然会到达浏览器——过滤发生在 UI 层，懂 DevTools 的用户可以直读原始 WebSocket 帧看到全部内容。这与旧版 fetch 过滤是同一性质，定位始终是「防误触」而非对抗有意绕过；
- 对 workspace 流的识别基于 open 帧 endpoint 含 workspace 的启发式匹配；未来上游若新增其他含该字样的流式端点也会被同样过滤；
- 真正的 per-user 服务端过滤需要 Harness 上游提供网关鉴权点或请求中间件（本仓库 docs/upstream-webserver-request-waterfall.md 已草拟提案），欢迎有能力的朋友一起推动或提 PR。

🤝 欢迎 PR：上面第 1 条的服务端鉴权缺口，靠浏览器守卫是补不上的——它需要 Harness 上游提供请求中间件 / 网关鉴权点，或者社区一起设计更优的进程内方案。如果你有思路（无论是对本插件的改进，还是对上游的建议），欢迎提 Issue / PR！

开发与测试

npm test                 # 密码学自检 + 宿主逻辑检查（双形态）+ 设置页半边渲染 + 浏览器沙箱冒烟
npm run build:dynamic    # 从 src/index.js 生成 dynamic/webgate.host.js
npm run preview:login    # 生成登录页静态预览（.preview/.html），改样式不必重启 DSH
npm run verify:live      # 对运行中的 DSH (127.0.0.1:3080) 做端到端验证（含管理 API 全链路；改过管理员密码用 pwsh -File scripts/verify-webgate.ps1 -AdminPassword '你的密码'）

无任何 npm 依赖，测试开箱即跑（需要 Node ≥ 22 与 PowerShell 7 仅用于 verify:live）。

源码结构：

src/index.js              # Host 半边：ESM 插件模块（name/inject/apply）+ 登录页视觉
src/client.js             # Client 半边：设置页「WebGate 用户」面板（settings.section）
dynamic/webgate.host.js   # 自动生成的动态插件形态（仅 Host，勿手改）
scripts/                  # 测试、构建与预览脚本
cordis.patch.yml          # 组合插入行

登录页配色与层级对照 deepseek.com 的线上设计令牌：底 #f9f8f8、顶部渐变罩 #9cc1e7 → rgba(250,250,250,0)、玻璃卡片 hsla(0,0%,100%,.62) + blur(12px) + 24px 圆角、主按钮 #1a1615 药丸、强调色 #4d6bfe，字标取自官网 header 的官方 SVG。npm run preview:login 会产出中文 / 英文 / 俄文三份预览页，可在不重启 DSH 的情况下逐像素比对（截图参数示例见脚本输出）。

三语的两条登记路径：内置语言（zh / en）用 ctx.locale.register(ns, { zh, en }) 整表登记；俄语 ru 由 @linxin666/dsh-i18n 通过 addLanguage 补进语言表，因此用 ctx.locale.register(ns, 'ru', dict) 单语言登记；两处都包了 try/catch，缺任何一方都只是少一份词典而不会报错。登录页是独立页面（没有 DSH 的 locale 服务），因此自带一份等价的文案表并按 navigator.language 识别。

License

MIT