feat(multi-user): 多用户化 + 凭证加密 + 自助注册与图形验证码

数据隔离 - settings / usage_records 主键改为 (user_id, key) / (user_id, request_id)，索引一律以 user_id 打头；collect_runs / audit_log 增加 user_id - query / collect / scheduler 全链路把 uid 作为 conn 之后的第一个位置参数且无默认值（漏传直接 TypeError，不会退化成「返回全量」） - 配置三级回落个人→实例→DEFAULTS；NO_FALLBACK_KEYS={cookie,user_agent} 不回落凭证保密 - 新增 workbuddy_portal/crypto.py：手写 ChaCha20(RFC8439 §2.3) + HMAC-SHA256 encrypt-then-MAC，零第三方依赖；主密钥 cookie_key 与 SECRET_KEY 分键位存放 - get_secret() 是取明文的唯一通道；get_settings() 把加密键置空； secret_state() 只回 {set,chars,tail,broken}；升级时自动加密历史明文注册与验证码 - 新增 /register 与 workbuddy_portal/captcha.py（手写 PNG + 点阵字模 + 干扰线） - 验证码答案只存服务端表、不进 session，一次性、5 分钟过期、按 purpose 隔离 - allow_register / register_max_per_ip / captcha_policy / captcha_length 四个实例级开关 - 失败限速改为 IP + 用户名双维度；停用账号每请求回查、立即失效页面 - 新增 /profile（个人中心）与注册页；登录页加验证码与自助注册入口 - /config 增加凭证状态、cookie_broken 告警、实例级设置区；/users 增加邮箱/状态与启停修复 - base.html 顶层 {% set me %} 覆盖子模板同名变量，导致个人中心「注册于」渲染为空 - WB_COOKIE_SECURE 未写进 compose 的 environment，在 .env 里设了不生效 - 「修改登录密码」提示写「至少 6 位」，与实际策略（≥8 位 + 两类字符）不符 - 「用户管理」删除说明写「可勾选保留」，与页面实际行为不符 - 注册页与 flash 文案里的 **强调** Markdown 字面量验证与文档 - smoke.py 99 → 165 项断言（多用户隔离 / 凭证保密 / 注册与验证码 / 3 条防回归） - check_live.py 56 → 83 项断言（新增注册 / 验证码 / 安全响应头一节） - demo_data.py 造两个账号；shots.py 自动过验证码、重出 11 张截图 - README / SECURITY / ARCHITECTURE / API / DEPLOYMENT / USER-GUIDE / FAQ / CHANGELOG / CONTRIBUTING 同步
2026-09-15 17:32:35 +08:00
@@ -1,17 +1,18 @@
 # WorkBuddy Portal 用户使用手册

 > 面向**使用者**（不是开发者）。读完这份就能独立完成日常操作：
-> 登录 → 看用量 → 配置采集 → 查明细 → 导数据 → 处理常见异常。
+> 注册 / 登录 → 配好自己的凭证 → 看用量 → 查明细 → 导数据 → 处理常见异常。

 > **关于配图**：本文所有截图都用 `tools/demo_data.py` 生成的**合成示例数据**渲染
-> ——模型名统一是 `demo-*`，客户端为 `vscode`/`webconsole`/`sdk`，Prompt 是通用示例文本。
+> ——模型名统一是 `demo-*`，客户端为 `vscode`/`webconsole`/`sdk`，Prompt 是通用示例文本，
+> Cookie 是**假串**（`wb_demo_session=…`），账号是 `admin` 与 `demo` 两个。
 > 所以你可以照着重现出几乎一样的界面，也不必担心文档里夹带真实账号信息。
 > 想自己搭一份这样的环境：`python tools/demo_data.py` 然后按输出的提示起服务即可。

 **目录**

 - [一、这个系统是做什么的](#一这个系统是做什么的)
- [二、登录与账号](#二登录与账号)
+- [二、登录、注册与账号](#二登录注册与账号)
 - [三、获取并填写 Cookie](#三获取并填写-cookie)
 - [四、概览页：一眼看清家底](#四概览页一眼看清家底)
 - [五、用量大屏：交互式分析](#五用量大屏交互式分析)
@@ -35,7 +36,7 @@
 一次典型的日常是：

 ```
-每天 09:00 / 17:00  系统自动采集（你什么都不用做）
+每个账号按自己配的时刻自动采集（默认 09:00 / 17:00，你什么都不用做）
   ↓
 你想看看进度  →  打开「概览」看今天用了多少
 想深挖         →  打开「用量大屏」按模型/客户端/时段切
@@ -45,7 +46,9 @@

 ---

-## 二、登录与账号
+## 二、登录、注册与账号
+
+### 2.1 登录

 打开 `http://<部署机器IP>:8848`，会看到登录页。

@@ -55,34 +58,111 @@
 |---|---|
 | 默认账号 | `admin` / `admin123`（**只有数据库里一个账号都没有时**才会创建） |
 | 登录保持 | 12 小时 |
-| 失败限制 | 同一 IP 连续错 5 次，锁定 10 分钟 |
+| 验证码 | 默认**始终要求**，4 位，不区分大小写，5 分钟内有效、只能用一次 |
+| 失败限制 | 同一 IP、或同一用户名连续错 5 次，锁定 10 分钟 |
 | 退出 | 右上角「退出」（走 POST，防被恶意链接静默触发） |

-> ⚠️ **首次部署请立刻改密码**：系统是给局域网访问的，默认密码等于没锁门。
-> 改法：「配置管理 → 修改密码」，或命令行 `python manage.py passwd admin 新密码`。
+**关于验证码**：

-### 权限差别
+- 图上只有数字与大写字母，并且**去掉了容易看错的 `0 O 1 I L`**；
+- 看不清就**点图片换一张**，不消耗任何额度；
+- 一张验证码**用完即废**：输错要换新的，登录用过之后也不能再拿去注册；
+- 答案只存在服务器数据库里，浏览器拿到的只是一个随机编号——**在网页源码里搜不到答案**；
+- 被锁定期间，即使验证码填对也会被拒，等 10 分钟或换一个来源。
+
+> ⚠️ **首次部署请立刻改密码**：系统是给局域网访问的，默认密码等于没锁门。
+> 改法：「个人中心 → 修改登录密码」，或命令行 `python manage.py passwd admin 新密码`。
+
+### 2.2 自助注册
+
+登录页底部有「**自助注册**」入口（地址是 `/register`）。管理员也可以把这个入口关掉。
+
+![注册页](images/09-register.png)
+
+| 字段 | 要求 |
+|---|---|
+| 用户名 | 3~32 位，字母或数字开头，可含 `_` `.` `-`；**这是登录名，注册后不可改** |
+| 显示名 | 选填，留空则与用户名相同 |
+| 邮箱 | 选填，便于日后找回 |
+| 密码 | 至少 8 位，且含大写字母 / 小写字母 / 数字 / 符号中的**至少两类** |
+| 验证码 | 与登录页同款：5 分钟有效、一次性 |
+
+批量注册被三道闸门挡着：
+
+1. **图形验证码** —— 每次提交都要重新过一遍；
+2. **来源限额** —— 同一个 IP 每天最多注册 3 个账号（管理员可调）；
+3. **总开关** —— 管理员可以随时关闭注册入口。
+
+> 注册成功后**不会**自动帮你配好采集。你要粘贴的是**你自己账号**的 Cookie，
+> 见 [第三章](#三获取并填写-cookie)。在那之前，概览页只会提示「未配置凭证」。
+
+### 2.3 个人中心
+
+点右上角**你自己的名字**，进入个人中心（`/profile`）。
+
+![个人中心](images/10-profile.png)
+
+| 区块 | 能做什么 |
+|---|---|
+| 四张卡片 | 我的记录数 / 我的积分 / 采集次数 / 我的 Cookie 状态 |
+| 修改资料 | 改显示名、邮箱（用户名只读） |
+| 修改登录密码 | 需要原密码；改完当前会话仍然有效 |
+| 我的采集凭证 | 是否已配置、多少字符、结尾 4 位、最后更新时间、当前调度时刻 |
+
+> 卡片上的「我的积分」只统计**归属你本人的数据**，别人账号的记录不会算进来。
+
+### 2.4 你的数据边界
+
+这是多用户版最要紧的一条：**每个账号只看得到、也只影响自己的数据。**
+
+| 是「你的」 | 是「共用的」 |
+|---|---|
+| Cookie 与 User-Agent | 接口基址 / 接口路径 |
+| 采集参数（分页、超时、截断…） | 是否开放自助注册、注册限额 |
+| 调度开关与每日时刻 | 验证码策略与位数 |
+| 用量记录、采集历史、导出的 CSV | 数据库文件本身 |
+
+两点值得记牢：
+
+- **管理员也看不到你的 Cookie 和用量明细。** 用户管理页只显示每个账号的记录条数与积分合计，
+  点不进去看内容；Cookie 在页面上永远只回显「长度 + 结尾 4 位」。
+- **采集只使用本人的凭证。** 系统不会拿别人的 Cookie 去替你采集（那会串号），
+  所以每个账号都必须各自配一次 Cookie。
+
+### 2.5 权限差别

 | 能力 | 管理员 | 普通用户 |
 |---|---|---|
-| 看概览 / 大屏 / 明细 / 任务 / 配置 / 日志 | ✅ | ✅ |
-| 手动触发采集、补采、改配置 | ✅ | ✅ |
-| 导出 CSV | ✅ | ✅ |
-| **用户管理**（建号 / 改权限 / 删号） | ✅ | ❌（导航里不显示，直接访问返回 403） |
+| 概览 / 大屏 / 明细 / 任务 / 配置 / 日志 / 个人中心 | ✅ | ✅ |
+| 改**自己**的采集参数、调度时刻、Cookie | ✅ | ✅ |
+| 手动采集、按区间补采 | ✅（只动自己的数据） | ✅（只动自己的数据） |
+| 导出 CSV | ✅（只有自己的） | ✅（只有自己的） |
+| 整理数据库（VACUUM，整库操作） | ✅ | ❌ |
+| 改**实例级**设置（接口地址、开放注册、验证码策略、注册限额） | ✅ | ❌（输入框置灰） |
+| 应用日志尾部 | ✅ | ❌（接口 403，页面上该区块为空） |
+| **用户管理**（建号 / 停用 / 删号 / 改权限） | ✅ | ❌（导航里不显示，直接访问返回 403） |

-> 给只读同事发普通账号即可，没必要共用管理员。
+> 给同事发普通账号即可，没必要共用管理员——管理员是能停用别人账号的角色。

 ---

 ## 三、获取并填写 Cookie

-**没有 Cookie，采集一定失败。** 这是首次部署唯一的必要手工步骤。
+**没有 Cookie，采集一定失败。** 这是每个账号**各自**要做一次的手工步骤。

-### 3.1 为什么要 Cookie
+### 3.1 为什么要 Cookie，以及它怎么被保管

-采集是直接调账号的用量接口，云端用 Cookie 认人。Cookie 是账号凭证，所以它：
- 存在数据库里，页面上**只回显掩码**（如 `a1b2…f9`）；
- 不会被任何接口以明文返回。
+采集是直接调账号的用量接口，云端靠 Cookie 认人。Cookie 等于账号凭证，所以系统对它：
+
+- **加密后入库**：落库前用 ChaCha20 + HMAC-SHA256 加密（密钥在 `data/instance.json`），
+  数据库文件被拷走也读不出明文；
+- **永不回传明文**：页面与接口只回显「多少字符、结尾 4 位」，形如 `1238 字符，结尾 …c0ffe`；
+- **只属于你**：存在你的账号名下，别人（包括管理员）看不到、也拿不到；
+- **和 User-Agent 绑在一起**：两者必须取自**同一次浏览器请求**，否则云端会认为是另一个客户端。
+
+> 「配置管理 → 我的云端凭证」里如果出现 **无法解密** 的红字提示，说明实例主密钥被换过
+> （`data/instance.json` 被删或被替换），重新粘贴一次即可。详见
+> [十二、常见问题](#cookie-显示无法解密)。

 ### 3.2 拿 Cookie 的两种办法

@@ -91,12 +171,17 @@
 如果你平时用 VSCode / Cursor / Trae 登录过 WorkBuddy，Cookie 已经在本机设置里：

 ```bash
-python manage.py import-creds
+python manage.py import-creds              # 不指定 -u 时给「管理员」账号导入
+python manage.py import-creds -u alice     # 想导给谁就写谁的用户名
 ```

 它会去读编辑器 `settings.json` 里的 `codebuddyUsage.*` 字段，写进数据库。
 Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器）。

+> ⚠️ 导入的是**运行这条命令的那台机器上、那个编辑器账号**的 Cookie。
+> 如果 A 同事的机器上跑这条命令去给 B 同事的账号导入，采到的就是 A 的数据——
+> 所以更稳的做法是让每个人自己登录网页、粘贴自己的 Cookie。
+
 **办法 B：手工复制（一定可行）**

 1. 浏览器打开并登录 WorkBuddy 官网；
@@ -116,6 +201,8 @@ Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器
 |---|---|---|
 | `新增 N 条` 或 `无新增（已是最新）` | ✅ 正常 | — |
 | `cookie_expired` / `401` / `403` | Cookie 过期了 | 重新执行 3.2 |
+| `no_cookie`（采集被跳过） | 这个账号**还没配** Cookie | 按 3.2 填一份 |
+| `cookie_broken` | 密文解不开（实例主密钥被换过） | 重新粘贴一次，见 [十二](#cookie-显示无法解密) |
 | `TLS` / `SSLError` | 证书校验失败 | 见「十二、常见问题」 |

 ---
@@ -228,6 +315,10 @@ Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器
 > 调度线程在 Web 进程内，所以「关掉 Web」等于「关掉调度」。
 > 如果偶尔忘了开机，靠「启动补跑」把错过的时刻补回来。

+> **调度是按账号配置的**：你在这里改开关与时刻，只影响**你自己**的采集。
+> 到达时刻时，系统会逐个账号跑——没配 Cookie 的账号会被跳过并在日志里记一条
+> `no_cookie`，不会影响别人。别人也可以在别的时间点采，互不干扰。
+
 ### 7.2 手动采集

 - **立即采集一次**：按断点续采，最常用的按钮。
@@ -249,19 +340,23 @@ Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器

 ![配置管理页](images/04-config.png)

-### 8.1 凭证
+### 8.1 我的云端凭证

 | 字段 | 说明 |
 |---|---|
-| Cookie | 采集用的账号凭证。**只回显掩码**；留空保存 = 不修改（不会被清空） |
-| User-Agent | 与拿 Cookie 的浏览器保持一致更稳 |
+| Cookie | **你本人账号**的凭证，密文入库。留空保存 = 不修改；填一个 `-` = 清空已保存的 Cookie |
+| User-Agent | 与拿 Cookie 的浏览器保持一致更稳（**两者必须取自同一次请求**） |
+
+保存后页面上只显示 `当前 Cookie：1238 字符，结尾 …c0ffe（2026-09-15 10:22 更新）`——
+页面上、接口里都拿不到明文。若显示「**无法解密**」的红字横幅，说明实例主密钥被换过，
+重新粘贴一次即可。

 ### 8.2 采集参数

 | 参数 | 默认 | 范围 | 说明 |
 |---|---|---|---|
-| `api_base` | `https://www.workbuddy.cn` | — | 接口基址（镜像 / 代理时改） |
-| `api_path` | `/billing/meter/get-user-request-usage` | — | 接口路径 |
+| `api_base` | `https://www.workbuddy.cn` | — | 接口基址（镜像 / 代理时改）。**实例级，普通账号只读** |
+| `api_path` | `/billing/meter/get-user-request-usage` | — | 接口路径。**实例级，普通账号只读** |
 | `page_size` | 200 | 20 ~ 1000 | 单页条数。调大能减少请求次数，但单次更慢 |
 | `rewind_minutes` | 2 | 0 ~ 120 | 断点回退分钟数。避免云端写入延迟导致漏数据 |
 | `drift_tolerance_minutes` | 5 | 0 ~ 720 | 云端时间比本地早超过该值才告警 |
@@ -273,19 +368,40 @@ Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器
 > **写错的值会被当场拒绝**并提示原因，不会污染配置（历史版本会因为一个手滑的数字
 > 让采集整个跑不起来）。范围外的数、非数字都会在保存时被拦下。

+> 上表里除 `api_base` / `api_path` 外，**其余都是「你自己的」配置**——改它只影响你这个账号的
+> 采集行为，不影响别人。`schedule_times` 这类调度项同理：每个人可以定自己的采集时刻。
+
 ### 8.3 维护动作

-| 按钮 | 作用 | 何时用 |
-|---|---|---|
-| 补全 Prompt | 把缺失的 `Prompt` 从云端回补 | 从官网 xlsx 导入过数据后（xlsx 丢约 22%） |
-| 导出全量 CSV | 全量导出到 `data/exports/` | 归档 / 交接 |
-| 整理数据库 | `wal_checkpoint` + `VACUUM` | 删过数据后回收空间，或 WAL 文件偏大时 |
+| 按钮 | 作用 | 何时用 | 谁能用 |
+|---|---|---|---|
+| 补全 Prompt | 把缺失的 `Prompt` 从云端回补 | 从官网 xlsx 导入过数据后（xlsx 丢约 22%） | 所有人（只补自己的） |
+| 导出我的 CSV | 导出**你自己的**全量数据到 `data/exports/` | 归档 / 交接 | 所有人 |
+| 整理数据库 | `wal_checkpoint` + `VACUUM`（**整库操作**） | 删过数据后回收空间，或 WAL 文件偏大时 | **仅管理员** |

 这些动作**耗时且会占用写权限**，所以有二次确认。执行期间不要重复点击。

 ### 8.4 修改密码

 填「当前密码 / 新密码 / 确认新密码」。改完当前会话仍然有效，其他会话需要重新登录。
+（同样的表单在「个人中心」也有一份。）
+
+### 8.5 实例级设置（仅管理员可见）
+
+页面最下方这一块，**只有管理员看得到**，改动对**所有账号**生效：
+
+| 设置 | 默认 | 说明 |
+|---|---|---|
+| 开放自助注册 | 允许 | 关掉后登录页不再显示「自助注册」，只能由管理员建号 |
+| 同 IP 每日注册上限 | 3 | 防止一个来源批量刷号；范围 1 ~ 50 |
+| 验证码策略 | 始终要求 | `始终要求` / `仅连续失败 2 次后要求` / `关闭` |
+| 验证码位数 | 4 | 4 ~ 6 位。位数越多越难被自动识别，也越考验眼力 |
+
+> **验证码策略怎么选**：默认的「始终要求」最安全；「仅连续失败后要求」对天天登录的人更友好，
+> 但会给机器人留出 2 次免验证码的尝试机会。**「关闭」只有在前面已经有可信网关时才考虑。**
+>
+> 验证码的答案只存在服务端 `captchas` 表里，5 分钟过期、用一次就删——
+> 所以它不会随会话 Cookie 泄漏出去。

 ---

@@ -302,11 +418,14 @@ Docker 部署时对应 `WB_IMPORT_CREDS=1`（需要把设置文件挂进容器
 Web 进程自身的日志（启动、异常栈、调度动作）。默认展示尾部若干行。

 **3. 操作审计**
-谁在什么时候做了什么：登录、登录失败、改配置、触发采集、导出、建号删号……
+谁在什么时候做了什么：登录、登录失败、改配置、触发采集、导出、建号删号、注册……
 可按**动作**筛选，支持翻页。

 > 排错顺序建议：操作审计（有没有人动过） → 采集历史（采集本身成不成功） → 应用日志（程序有没有异常）。

+> **多用户下你看到的范围**：「采集运行历史」与「操作审计」只有你**自己的**记录；
+> 「应用日志尾部」是整机日志，**仅管理员可见**（普通账号看到的是空区块，接口返回 403）。
+
 ---

 ## 十、用户管理页（仅管理员）
@@ -315,17 +434,25 @@ Web 进程自身的日志（启动、异常栈、调度动作）。默认展示

 | 操作 | 说明 |
 |---|---|
-| 新建账号 | 填用户名 / 显示名 / 密码，可勾选管理员 |
-| 改显示名 | 行内直接改，保存即生效 |
-| 改权限 | 管理员 ↔ 普通用户 |
+| 新建账号 | 填用户名 / 显示名 / 邮箱 / 密码 / 权限（**默认普通账号**） |
+| 改显示名 | 行内直接改，点该行「保存」生效 |
+| 改权限 | 管理员 ↔ 普通 |
+| 改状态 | 启用 ↔ 停用（**停用立即生效**，不必等会话过期） |
 | 改密码 | 给忘了密码的同事重置 |
-| 删除 | 删除账号 |
+| 删除 | **不可逆**，会连同该账号的用量数据与 Cookie 一起删除 |

-内置三条护栏（前端和后端都拦）：
+列表还给出每个账号的**记录条数 / 积分合计 / 最后登录时间与 IP**——但**看不到内容**：
+管理员能看到的只是「有多少」，看不到「是什么」，也看不到任何人的 Cookie。
+
+内置四条护栏（前端置灰 + 后端再拦一次）：

 1. **不能取消自己的管理员身份**（防止把自己锁在门外）；
-2. **不能删除自己**；
-3. **至少要保留一个账号**（防止系统变成没人能登录）。
+2. **不能停用自己**；
+3. **不能删除自己**；
+4. **不能删掉最后一个启用的管理员**（防止系统变成没人能管）。
+
+页面底部是「**账号操作审计**」：最近 20 条账号相关动作，含**注册**与**登录失败**记录——
+想知道有没有人在撞你的密码，看这里。

 ---

@@ -333,24 +460,74 @@ Web 进程自身的日志（启动、异常栈、调度动作）。默认展示

 | 我想… | 怎么做 |
 |---|---|
-| 立刻采集一次 | 任务管理 → 立即采集一次 |
+| 自己注册一个账号 | 登录页 → **自助注册**（需管理员开放注册） |
+| 立刻采集一次 | 任务管理 → 立即采集一次（只采我自己的） |
 | 回补某几天的数据 | 任务管理 → 按区间补采，填起止日期 |
-| 换 Cookie | 配置管理 → 凭证 → 粘贴新 Cookie → 保存 → 回补最近几天 |
+| 换我自己的 Cookie | 配置管理 → 我的云端凭证 → 粘贴新 Cookie → 保存 → 回补最近几天 |
+| 改我的显示名 / 邮箱 / 密码 | 右上角**点自己的名字** → 个人中心 |
+| 看不清验证码 | **点验证码图片**换一张 |
 | 导出某段时间的数据给别人 | 数据明细 → 选日期 → 导出 CSV |
-| 导出全量存档 | 配置管理 → 维护动作 → 导出全量 CSV |
+| 导出我的全量存档 | 配置管理 → 维护动作 → 导出我的 CSV |
 | 找出最贵的请求 | 用量大屏 → 单笔 TOP |
 | 看某条请求的完整 Prompt | 数据明细 → 该行「展开」 |
-| 给同事开只读账号 | 用户管理 → 新建账号，**不勾**管理员 |
-| 同事忘记密码 | 用户管理 → 该行「改密码」 |
-| 把数据备份走 | 让运维按 [部署指南 6.2](DEPLOYMENT.md#62-备份) 备份命名卷，或在「配置管理」导出全量 CSV |
+| 给同事开账号 | 用户管理 → 新建账号，权限选**普通**（或让同事自助注册） |
+| 同事忘记密码 | 用户管理 → 该行「改密」 |
+| 临时封掉某个账号 | 用户管理 → 该行「停用」（数据与 Cookie 保留） |
+| 拒绝别人自助注册 | 配置管理 → 实例级设置 → 开放自助注册 → 关闭 |
+| 把数据备份走 | 让运维按 [部署指南 6.2](DEPLOYMENT.md#62-备份) 备份命名卷，或在「配置管理」导出 CSV |
 | 关掉自动采集 | 任务管理 → 关「启用调度」 |
 | 改采集时刻 | 任务管理 → 每日时刻，如 `08:30,12:30,18:00` → 保存 |
-| 系统变慢了 | 配置管理 → 整理数据库；再不行看「十二」 |
+| 系统变慢了 | 让**管理员**做「配置管理 → 整理数据库」；再不行看「十二」 |

 ---

 ## 十二、常见问题

+### 验证码看不清
+
+点验证码图片**换一张**，不限次数、不消耗额度。图上刻意去掉了 `0 O 1 I L` 这几个易混字符，
+只剩数字与不含它们的字母。也可以让管理员把「验证码位数」调成 4 位。
+
+### 验证码明明填对了，还是提示错误
+
+三种可能，按顺序排查：
+
+1. **这张图已经用过了** —— 验证码是**一次性**的，输错一次、或登录成功之后，它立刻作废，
+   必须点图片重新取一张；
+2. **超过了 5 分钟** —— 有效期只有 5 分钟，慢慢来的话会过期，换一张即可；
+3. **跨了页面** —— 登录页取到的图不能拿去注册页用（两边的验证码是分开的）。
+
+> 另外：如果这个来源已被锁定（连续失败 5 次），即使验证码正确也会被拒；等 10 分钟再试。
+
+### 登录页看不到「自助注册」
+
+说明管理员把注册关掉了。两条路：请管理员在「配置管理 → 实例级设置」里打开，
+或直接请管理员在「用户管理」里给你建一个账号。
+
+### 注册被拒，说来源已达上限
+
+同一个 IP 每天默认最多注册 3 个账号。换个网络，或请管理员把
+「同 IP 每日注册上限」调大（范围 1 ~ 50）。
+
+### 「Cookie 显示无法解密」
+
+「配置管理 → 我的云端凭证」出现红字横幅，或卡片上写着 **无法解密**：这是说数据库里
+存的 Cookie 密文，用当前的实例主密钥解不开了。常见原因是 `data/instance.json`
+（里面存着 `cookie_key`）被删除、被替换，或者从别的机器拷了一份数据库过来。
+
+**影响**：这个账号的采集会失败，日志里是 `cookie_broken`。
+
+**怎么办**：重新粘贴一次这个账号的 Cookie 即可，历史数据不受影响。
+**怎么避免**：`data/instance.json` 里存着会话签名密钥和加密主密钥——备份数据库时
+**把它一起备份**，并且不要在容器之间混用。
+
+### 我能不能看别人的用量
+
+不能，管理员也不能。「用户管理」页只显示每个账号的记录条数与积分合计，看不到内容。
+这是设计如此：Cookie 是账号级凭证，让它跨账号可见等于把别人的账号交出去。
+
+如果确实需要合并统计，正确做法是让每个人各自导出 CSV，再在外部合并。
+
 ### 采集报 `cookie_expired` / `unauthorized`

 Cookie 过期。重新按 [3.2](#32-拿-cookie-的两种办法) 拿一份新 Cookie 填进去。
@@ -391,13 +568,27 @@ Docker 部署请确认 `TZ=Asia/Shanghai`；裸机部署确认系统时区。
 在的。调度在**服务端进程**里，和浏览器无关。要停就去「任务管理」关调度开关，
 或停掉服务。

-### 忘记管理员密码
+### 忘记密码

-在部署机器上执行：
+**你自己的密码忘了**：网页上没法自助重置（没有邮件通道），找管理员在
+「用户管理 → 该行『改密』」给你设一个新的。
+
+**管理员密码忘了**（或者被自己停用了），到部署机器上执行：

 ```bash
-python manage.py passwd admin 新密码      # 裸机
+python manage.py passwd admin 新密码                    # 裸机
 docker compose exec portal python manage.py passwd admin 新密码   # Docker
+
+# 顺便把被停用的账号恢复启用
+python manage.py passwd admin 新密码 --activate
+# 需要新建一个管理员
+python manage.py passwd alice 密码 --role admin
+```
+
+想看现在都有哪些账号、各自什么角色与状态，用：
+
+```bash
+python manage.py users
 ```

 ### 数据会丢吗
@@ -417,4 +608,4 @@ docker compose exec portal python manage.py passwd admin 新密码   # Docker
 ---

 更多技术细节见 [架构与设计说明](ARCHITECTURE.md)、[部署与运维指南](DEPLOYMENT.md)、
-[接口参考](API.md)。
+[接口参考](API.md)、[安全说明](../SECURITY.md)。