workbuddy-portal/docs/USER-GUIDE.md

WorkBuddy Portal 用户使用手册

面向使用者（不是开发者）。读完这份就能独立完成日常操作： 登录 → 看用量 → 配置采集 → 查明细 → 导数据 → 处理常见异常。

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

目录

• 一、这个系统是做什么的
• 二、登录与账号
• 三、获取并填写 Cookie
• 四、概览页：一眼看清家底
• 五、用量大屏：交互式分析
• 六、数据明细页：查、筛、导
• 七、任务管理页：定时与补采
• 八、配置管理页：参数与维护
• 九、日志管理页：出问题先看这里
• 十、用户管理页（仅管理员）
• 十一、常见任务速查
• 十二、常见问题

---

一、这个系统是做什么的

它把 WorkBuddy 账号的积分用量明细自动采集下来，存成一份永久全量存档，并提供查询与可视化。

为什么不直接看官网？官网只给一段时间窗口的明细，过期就查不到了；导出的 xlsx 还会丢掉 约 22% 的 User Prompt 内容。本系统把数据落到自己的库里，只增不减，随时能翻旧账。

一次典型的日常是：

每天 09:00 / 17:00  系统自动采集（你什么都不用做）
   ↓
你想看看进度  →  打开「概览」看今天用了多少
想深挖         →  打开「用量大屏」按模型/客户端/时段切
要找某条记录   →  「数据明细」搜索 + 展开 Prompt
要拿给别人     →  「数据明细」→ 导出 CSV

---

二、登录与账号

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

项目	说明
默认账号	admin / admin123（只有数据库里一个账号都没有时才会创建）
登录保持	12 小时
失败限制	同一 IP 连续错 5 次，锁定 10 分钟
退出	右上角「退出」（走 POST，防被恶意链接静默触发）

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

权限差别

能力	管理员	普通用户
看概览 / 大屏 / 明细 / 任务 / 配置 / 日志	✅	✅
手动触发采集、补采、改配置	✅	✅
导出 CSV	✅	✅
用户管理（建号 / 改权限 / 删号）	✅	❌（导航里不显示，直接访问返回 403）

给只读同事发普通账号即可，没必要共用管理员。

---

三、获取并填写 Cookie

没有 Cookie，采集一定失败。 这是首次部署唯一的必要手工步骤。

3.1 为什么要 Cookie

采集是直接调账号的用量接口，云端用 Cookie 认人。Cookie 是账号凭证，所以它：

• 存在数据库里，页面上只回显掩码（如 a1b2…f9）；
• 不会被任何接口以明文返回。

3.2 拿 Cookie 的两种办法

办法 A：让程序自己从编辑器设置里读（最省事）

如果你平时用 VSCode / Cursor / Trae 登录过 WorkBuddy，Cookie 已经在本机设置里：

python manage.py import-creds

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

办法 B：手工复制（一定可行）

1. 浏览器打开并登录 WorkBuddy 官网；
2. 按 F12 打开开发者工具 → 切到 Network（网络） 标签；
3. 刷新页面，随便点一个发往 workbuddy.cn 的请求；
4. 在 Request Headers（请求标头） 里找到 Cookie: 一行；
5. 整行值复制下来（很长，通常几千字符，要复制完整）；
6. 到本系统「配置管理 → 凭证 → Cookie」，粘贴，保存。

顺手把 User-Agent 也填成同一个浏览器的 UA，成功率高一些。

3.3 验证 Cookie 是否有效

保存后到「任务管理 → 立即采集一次」，然后看「日志管理」最新一条：

日志里看到	含义	怎么办
新增 N 条 或 无新增（已是最新）	✅ 正常	—
cookie_expired / 401 / 403	Cookie 过期了	重新执行 3.2
TLS / SSLError	证书校验失败	见「十二、常见问题」

---

四、概览页：一眼看清家底

从上到下四块：

1. KPI 卡片（6 个）

卡片	含义
存档总量	库里一共多少条记录（只增不减）
累计积分	全部记录的积分合计
活跃天数	有记录的自然日数量
今日积分	今天（本地时区）已消耗
今日 vs 昨日	今日与昨日整日对比，带涨跌幅
采集健康	最近若干次采集的成功 / 失败情况

2. 今日 vs 昨日整日 注意「昨日」是完整一天，而「今日」还在进行中——上午看数字偏低是正常的， 该跟昨天的同一时段比才有意义（大屏页能做这个对比）。

3. 调度状态 显示调度开关、下次执行时刻、上次采集结果。这里显示「已停用」时采集不会自动跑， 到「任务管理」把调度打开。

4. 模型 TOP + 最近采集 按模型看积分消耗排行；下方是最近几次采集的触发方式（手动 / 调度 / 启动补跑）、 耗时、抓取条数、新增条数、去重条数。

---

五、用量大屏：交互式分析

左侧导航点「用量大屏」，或直接访问 /dashboard。

大屏是独立的交互页，顶部可切时间区间（今日 / 近 7 天 / 近 30 天 / 自定义）， 所有图表联动重绘。主要图表：

图	看什么
日历热力图	哪几天用得猛（颜色越深越多）。注意：格子颜色是「该日合计」，不是单条
趋势折线	按天的积分走势，判断是否在加速
维度分布	按模型或客户端拆分的占比
时段分布	24 小时里集中在哪些时段（配合判断是否有脚本在跑）
单笔 TOP	最贵的单次请求，含 Prompt 摘要——最值得优化成本的地方

页面左上角有「← 返回后台」等入口，随时能回管理后台。 大屏的数据是按当前筛选窗口实时取的，不是预生成的静态图——切区间会重新请求。

怎么用它省钱：先看「单笔 TOP」抓出最贵的请求类型，再看「时段分布」判断是不是 某个自动化任务在固定时间跑，最后用「数据明细」把那一批记录导出来逐条分析。

---

六、数据明细页：查、筛、导

6.1 筛选条件

条件	说明
快捷区间	「今日 / 近 7 天 / 近 30 天 / 全部」一键填日期
日期	起 / 止，留空表示不限
模型	下拉，来自库里实际出现过的模型
客户端	下拉，来源客户端标识
关键词	在 Prompt 正文里模糊匹配
每页条数	20 ~ 500
排序	时间倒序 / 正序、积分从高到低等

日期写错格式（如 abc、2026-13-99）不会白屏，系统会忽略非法值并提示。

6.2 看单条的完整 Prompt

列表默认不显示 Prompt 全文（它占数据体积约 80%）。点行首的「展开」看该条的完整 Prompt。 想批量看就导出 CSV。

6.3 导出 CSV

点「导出 CSV」，会把当前筛选条件下的全部记录（不是当前页）流式导出， 文件名形如 usage_2026-09-01_2026-09-14.csv。

• 编码为 UTF-8 带 BOM，Excel 双击直接打开不乱码；
• 列与官网导出的 xlsx 完全同构：requestId, credits, prompt, model, client, requestTime；
• 数据量大时也是边查边吐，不会把服务器内存吃满。

---

七、任务管理页：定时与补采

7.1 调度设置

项	说明
启用调度	总开关。关掉后只有手动采集会跑
每日时刻	逗号分隔的本地时刻，如 09:00,17:00。保存即生效，不用重启
启动补跑	打开后，程序启动时会把今天已错过、且还在宽限期内的时刻补采一次
补跑宽限期	超过多少小时就不补了（默认 12 小时）

调度线程在 Web 进程内，所以「关掉 Web」等于「关掉调度」。 如果偶尔忘了开机，靠「启动补跑」把错过的时刻补回来。

7.2 手动采集

• 立即采集一次：按断点续采，最常用的按钮。
• 按区间补采：填 起 / 止，把这几天重新扫一遍。 用途：换了 Cookie 之后回补漏掉的日期；或怀疑某天数据不全时重扫。 重扫不会产生重复——主键去重，已存在的记录按「更早的本地时间」保留。

同一时刻只能有一个采集在跑。重复点击会返回「忙碌」提示，这是设计如此 （SQLite 是单写者，并发只会互相拖慢）。等它跑完再点。

7.3 运行历史

每次采集都留一条记录：触发方式、状态、耗时、抓取/新增/去重条数、退出码。 点「详情」看这一次的逐行日志原文，包括 [warn] 和 [error]。

---

八、配置管理页：参数与维护

8.1 凭证

字段	说明
Cookie	采集用的账号凭证。只回显掩码；留空保存 = 不修改（不会被清空）
User-Agent	与拿 Cookie 的浏览器保持一致更稳

8.2 采集参数

参数	默认	范围	说明
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	云端时间比本地早超过该值才告警
max_prompt	2048	0 ~ 20000	Prompt 入库截断长度，0 = 不截断
verify_days	0	0 ~ 90	每次采集后做整日完整性校验的天数，0 = 关
timeout	30	5 ~ 300	单次 HTTP 超时（秒）
ssl_verify	1（开）	—	校验云端 HTTPS 证书。只在自签/企业代理场景才关

写错的值会被当场拒绝并提示原因，不会污染配置（历史版本会因为一个手滑的数字 让采集整个跑不起来）。范围外的数、非数字都会在保存时被拦下。

8.3 维护动作

按钮	作用	何时用
补全 Prompt	把缺失的 Prompt 从云端回补	从官网 xlsx 导入过数据后（xlsx 丢约 22%）
导出全量 CSV	全量导出到 data/exports/	归档 / 交接
整理数据库	wal_checkpoint + VACUUM	删过数据后回收空间，或 WAL 文件偏大时

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

8.4 修改密码

填「当前密码 / 新密码 / 确认新密码」。改完当前会话仍然有效，其他会话需要重新登录。

---

九、日志管理页：出问题先看这里

三个区块：

1. 采集运行历史（可翻页 + 按状态筛 ok / warn / error / running） 每行可展开看逐行日志原文——排错时最有用的一块。

2. 应用日志尾部 Web 进程自身的日志（启动、异常栈、调度动作）。默认展示尾部若干行。

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

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

---

十、用户管理页（仅管理员）

操作	说明
新建账号	填用户名 / 显示名 / 密码，可勾选管理员
改显示名	行内直接改，保存即生效
改权限	管理员 ↔ 普通用户
改密码	给忘了密码的同事重置
删除	删除账号

内置三条护栏（前端和后端都拦）：

1. 不能取消自己的管理员身份（防止把自己锁在门外）；
2. 不能删除自己；
3. 至少要保留一个账号（防止系统变成没人能登录）。

---

十一、常见任务速查

我想…	怎么做
立刻采集一次	任务管理 → 立即采集一次
回补某几天的数据	任务管理 → 按区间补采，填起止日期
换 Cookie	配置管理 → 凭证 → 粘贴新 Cookie → 保存 → 回补最近几天
导出某段时间的数据给别人	数据明细 → 选日期 → 导出 CSV
导出全量存档	配置管理 → 维护动作 → 导出全量 CSV
找出最贵的请求	用量大屏 → 单笔 TOP
看某条请求的完整 Prompt	数据明细 → 该行「展开」
给同事开只读账号	用户管理 → 新建账号，不勾管理员
同事忘记密码	用户管理 → 该行「改密码」
把数据备份走	让运维按 部署指南 6.2 备份命名卷，或在「配置管理」导出全量 CSV
关掉自动采集	任务管理 → 关「启用调度」
改采集时刻	任务管理 → 每日时刻，如 08:30,12:30,18:00 → 保存
系统变慢了	配置管理 → 整理数据库；再不行看「十二」

---

十二、常见问题

采集报 cookie_expired / unauthorized

Cookie 过期。重新按 3.2 拿一份新 Cookie 填进去。 Cookie 有效期通常是浏览器会话级别，关掉浏览器可能就失效了——建议用 「办法 B」从已登录的浏览器里复制时，勾选「保持登录」。

采集成功但「新增 0 条」

大概率是正常的：断点续采意味着没有新请求时确实没有新增。 看「日志管理」里那一次的 抓取 条数：

• 抓取 > 0，新增 = 0 → 云端返回的都是库里已存在的，正常；
• 抓取 = 0 → 该时段云端确实没有记录。

日期看起来差一天

所有日期都按部署机器的本地时区（容器里由 TZ 决定，默认 Asia/Shanghai）计算。 如果服务器时区不是东八区，跨日的数据会落到相邻日期上。 Docker 部署请确认 TZ=Asia/Shanghai；裸机部署确认系统时区。

导出的 CSV 在 Excel 里中文乱码

不会——导出已经带 UTF-8 BOM。如果乱码，先确认你打开的是本系统导出的文件， 而不是手工用记事本另存过的版本。

提示「采集正在进行中」

同一时刻只允许一个采集（SQLite 单写者）。等当前这次跑完再操作， 在「任务管理 → 运行历史」里能看到它是否还在 running。

页面能打开但图表空白

1. 强制刷新（Ctrl+F5）清掉旧缓存；
2. 检查浏览器控制台有没有资源 404；
3. 到「日志管理 → 应用日志」看有没有异常栈。

关掉浏览器后调度还在跑吗

在的。调度在服务端进程里，和浏览器无关。要停就去「任务管理」关调度开关， 或停掉服务。

忘记管理员密码

在部署机器上执行：

python manage.py passwd admin 新密码      # 裸机
docker compose exec portal python manage.py passwd admin 新密码   # Docker

数据会丢吗

正本是 Docker 命名卷 workbuddy-portal_wb_data 里的 usage.sqlite（对应容器内 /app/data）。 docker compose down 不会删数据；只有显式 docker compose down -v 或手动 docker volume rm 才会。备份方法见 部署指南 6.2——对使用者的日常来说，更简单的做法是 「配置管理 → 维护动作 → 导出全量 CSV」留一份快照。

能不能同时开多个采集进程

不能，也没必要。SQLite 单写者 + 文件锁的设计就是为了避免并发写。 真要跑多副本，除第一份外都要设 WB_DISABLE_SCHEDULER=1， 且只有一份能安全写——所以不要横向扩展这个服务。

---

更多技术细节见 架构与设计说明、部署与运维指南、 接口参考。