kczx-user-management 1.0.4 → 1.4.0

package/README.md

@@ -72,6 +72,7 @@ node scripts/ensure-deps.mjs                     # 仅当上述解析不到 sche
    `/user-management/api/setup` 拒绝一切后续调用。
 
 > 登录页样式与 dsh-passwords 一致（光晕背景 + 网格 + 玻璃卡片 + 渐变按钮），跟随宿主主题深浅色，右上角可切换中文 / English。
+> 品牌可配：标题 / 副标题 / 页脚 / LOGO / 主色 / 默认语言都在 `user-management:` 段里，见「配置」一节。
 
 ## 它做什么
 
@@ -99,15 +100,21 @@ node scripts/ensure-deps.mjs                     # 仅当上述解析不到 sche
 
 | 台账 | 内容 |
 |---|---|
-| 登录记录 | 登录 / 失败 / 登出 / 改密 / 初始化（首次建号）/ 建号 / 删号 / 角色变更 / 资料变更 / 权限变更（含紧凑差异串） |
-| 访问记录 | 页面级访问（保留真实客户端 IP） |
-| 操作日志 | 经过网关的每次 API 调用与 WebSocket 连接（方法 / 路径 / 状态 / 来源 IP） |
+| 登录记录 | 登录 / 失败 / 登出 / 改密 / 初始化（首次建号）/ 建号 / 删号 / 角色变更 / 资料变更 / 权限变更（含紧凑差异串）；按页浏览 |
+| 访问记录 | 页面级访问（保留真实客户端 IP）；按页浏览 |
+| 操作日志 | 经过网关的每次 API 调用与 WebSocket 连接（方法 / 路径 / 状态 / 来源 IP）；**对话类请求连内容一起记**：`session.prompt` 的提示词、`session.rename` 的会话标题写进同一行（最多 500 字，点开展开；粘贴的图片只记数量、不存 base64）。列表多一列「对话内容」，并按页浏览（默认每页 50，可选 20/50/100/200） |
 
 另有 IP 封禁（回环与当前 IP 拒绝封禁，防自锁）与 TOTP 两步验证（默认关闭，可选开启）。
 
+**分页**：登录记录 / 访问记录 / 操作日志 / 用户表四张表都是服务端分页——查询参数带 `limit` + `offset`，
+响应回 `{ ..., total }`，前端底部是共用的分页控件（上一页 / 第 X/Y 页 · 共 N 条 / 下一页 / 每页 20·50·100·200，
+默认 50）。筛选同样在服务端执行，所以「共 N 条」永远是**匹配总数**而不是当前页条数。账号表只有在调用方
+传了 `limit` 时才分页，不传仍然整份返回（后端脚本的老用法不受影响）。
+
 ## 配置
 
-走 `~/.dsh/settings.yaml` 的 `user-management:` 段（改完要么热重载、要么重启）：
+走 `~/.dsh/settings.yaml` 的 `user-management:` 段。改完即时生效的字段无需重启；只有监听器字段
+（`listenHost` / `port` / `plaintext` / `sites`）会触发监听器重建，其余一律下一个请求就用新值。
 
 ```yaml
 user-management:
@@ -116,11 +123,90 @@ user-management:
   port: 8088
   plaintext: false        # true 时只允许回环（明文服务观察层用，见 MERGED-DEPLOYMENT.md）
   sites: []               # 空 = 自动枚举本机 IP；配域名 + 证书则按 SNI 选择
-  title: 'DSH 控制台'
   setupKey: ''            # 首次初始化密钥；留空 = 启动时随机生成并写到 setup-key.txt
   historyMaxBytes: 67108864   # 历史改写缓冲上限（字节，默认 64 MiB，最小 1 MiB）
+
+  # ── 登录页品牌（全部即时生效，改完刷新 /login 即可） ──
+  title: 'DSH 控制台'      # 部署名：标签页标题后缀 + 标题兜底
+  brandName: ''           # 卡片主标题；只填它，门面就是你的产品名
+  loginTitle: ''          # 逐行覆盖内置文案（'' = 用内置的「登录」/ Sign in）
+  loginSub: ''
+  setupTitle: ''          # 同上，作用于首次「初始化平台」表单
+  setupSub: ''
+  footerText: ''          # '' = 内置的「dsh 插件 · user-management」
+  showFooter: true
+  logoUrl: ''             # http(s)、data: URI，或本机图片文件；'' = 内置标记
+  logoSize: 48            # 标记方框边长（px，24–96）；图片按 contain 铺满方框
+  auditConversationText: true   # 操作日志记录 session.prompt 文字与会话标题（见下）
+  brandColor: ''          # '#rrggbb'；只重染品牌色 token，danger/ok/warn 不动
+  defaultLang: 'zh'       # 不带 ?lang= 时的门面语言（zh | en）
+  showLangSwitch: true    # 是否显示页内中英切换
+
+  # ── 会话与请求策略（全部即时生效） ──
+  sessionDays: 7          # 会话有效期（天，滑动续期：过半后续一次）
+  maxBodyBytes: 65536     # 本插件 API 的 JSON 请求体上限（字节）
+  otpFailLimit: 5         # 两步验证连续错误几次后锁定
+  otpLockoutSeconds: 60   # 锁定多久
 ```
 
+> 登录页的品牌只吃 `brandName` / `loginTitle` 这类字段，**改名不会影响账号与台账**；`brandColor` 只重染
+> 品牌色那几个 token（按钮、LOGO 底、聚焦环及其阴影），状态色保持不变——颜色承载语义，不该被顺手改掉。
+>
+> **LOGO 支持本机图片**（1.1.2 起）：`logoUrl` 填绝对路径（`E:/brand/logo.png`）或 `$DSH_HOME/user-management/`
+> 下的文件名（把图片放到 users.json 旁边，然后填 `logo.png`）。裸路径本身不是 URL，浏览器会拿它当相对路径去
+> 请求网关，所以本机图片由插件用 `/user-management/branding/logo` 这条**公开**路由回吐给登录页（和 /login 一样
+> 必须免登录，否则图片是 401）；该路由只吐这一个配置文件，且限定图片扩展名、非空、≤ 512 KiB，其余一律 404，
+> 路径下的其它子路径在本机就直接 404，不会被匿名转发到 dsh 上游。改图不用重启——路由每次现读文件。
+>
+> 图片**铺满方框**：`logoSize` 控制方框边长（默认 48px，24–96），图片用 `object-fit: contain` 填进去——方图正好
+> 铺满，长图/竖图留白而不裁切。这是品牌字段里唯一会改布局的一个，调大小在设置页里改完刷新即可，不用重启。
+> 未接线的占位字段仍有 `loginFailLimit` / `lockoutSeconds`（登录失败不自动锁定，用 IP 封禁代替），
+> 保留只是为了老的 `settings.yaml` 继续可解析。
+
+### 操作日志的分页（1.3.0 起）
+
+台账上限 5000 行、每行还带对话文字，一次全拉进浏览器既慢又没必要。现在「操作日志」是**服务端分页**：
+`GET /user-management/api/audit?limit=50&offset=100` 返回 `{ entries, total, limit, offset }`——除了这一页，
+还给出**匹配总数**，前端才说得出「第 3/40 页 · 共 1987 条」。表格下方有上一页 / 下一页和每页条数（20/50/100/200）。
+
+两个容易做错的点，都按服务端口径处理：
+
+- **筛选也走服务端**，和分页窗口是同一组参数：`username` / `method` / `path` / `statusClass`。若在前端过滤已取回的
+  那一页，翻页翻的就是"某个结果的子集"，而且"共 N 条"只能是这一页的数字——那是错的。筛选条件改动会**回到第 1 页**
+  （换条件后停在旧页码没有意义），输入框有 250ms 去抖，不会每敲一个字发一次请求。
+- **删掉最后一条**时若当前页只剩那一行，会退回上一页，而不是停在"第 N 页（空的）"。
+
+### 操作日志里的对话内容（1.2.0 起）
+
+「用户管理 → 操作日志」每一行是经过网关的一次 API 调用。以前只看得到 `POST /api/session.prompt`——可这一行不论用户说了什么都长一个样，
+日志于是回答不了「这个账号到底做了什么」。现在网关把人打的那句话从请求体里取出来，随行写进台账：
+
+- `session.prompt` → `content[]` 里所有 `type: 'text'` 片段按行拼接；`type: 'image'` 只记**数量**（截图是 base64，不是台账该存的东西）。
+- `session.rename` → 会话标题。
+- 其它 RPC 完全不碰请求体，仍按原来的方式流式转发。
+- 存储侧每行最多 500 字（`MAX_AUDIT_TEXT`，超长截断）；前端那一列默认单行省略、点一下就地展开全文，图片数量显示为徽标。
+- **只观察、不拦截**：抓取只是顺路把请求体缓一下再原样重放给上游，字节不变；超过 2 MiB 的请求体（例如带大图的提示词）原样透传、不记录文字。
+- 隐私开关：`user-management.auditConversationText: false`（设置页「会话与请求策略」里也有这一项）关掉即完全不抓。台账是
+  `$DSH_HOME/user-management/audit.jsonl` 明文文件，提示词可能含口令 / 密钥时请关闭。
+
+### 在设置页里改（1.1.0 起）
+
+上面这些字段也可以在 **设置 → 通用设置** 里改，就在「语言」「外观」那几行下面：「登录页与策略配置」一行，
+默认收起着（通用列里都是紧凑的单行偏好，十六个字段全展开会把这一页压垮），行内摘要写着登录页当前显示
+什么、有几项被改过，点「展开」出现完整表单。本插件在浏览器侧把这个设置命名空间绑成
+`settingsScope.bind({ namespace: 'user-management' })`，并注册进 `settings.general.item` 槽——宿主注册
+命名空间、浏览器注册控件，两边经由同一份 settings 文档同步。
+
+表单行为：改过没存的字段标「未保存」；写入过 `settings.yaml` 的字段标「已自定义」并带「恢复默认」
+（`unset`，清掉覆盖回到内置值，也让 `settings.yaml` 保持干净）；文本框留空等于清除覆盖；数字字段按 schema
+的下限校验（比如请求体上限 ≥ 1024）；保存按字段顺序逐个写入，**任何一个值非法就整体不落盘**并提示是哪一项。
+远程浏览器访问时设置是只读的（settings RPC 只走回环），这一行会直接说明并让你改服务器上的 `settings.yaml`；
+装了旧版插件时它也会明说「这些新字段保存了也不会生效」。
+
+**刻意没放进设置页的字段**：`listenHost` / `port` / `plaintext` / `sites` / `enabled` 会重启监听器——那正是承载
+这个设置页的东西，从 UI 里翻可能把自己关在门外；`trustedSecret` / `setupKey` 是密钥，不该经浏览器表单往返。
+这些继续只在 `settings.yaml` 里配。
+
 ## 数据文件
 
 都在 `$DSH_HOME/user-management/`（默认 `~/.dsh/user-management/`，0600，原子写）：
@@ -151,7 +237,7 @@ node scripts/import-from-dsh-passwords.mjs --from E:\path\to\dsh-passwords --ove
 ## 测试
 
 ```bash
-npm test          # 93 项：策略纯函数、store、API 层、以及真实网关的端到端用例
+npm test          # 138 项：策略纯函数、store、API 层、客户端契约、以及真实网关的端到端用例
 npm run check     # 全量语法检查
 ```