wangchuanli/workbuddy-portal
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

chore: 项目定名为 workbuddy-portal，容器化并补齐文档体系

浏览代码 
## 项目定名
- 目录 wb_usage_portal → workbuddy-portal
- Python 包 wb_usage → workbuddy_portal（含 session cookie 名）
- 界面品牌统一为 WorkBuddy Portal；项目标识收敛到 config 单一来源

## 容器化
- Dockerfile：多阶段构建，依赖层与源码解耦；非 root(uid 1000)；内置健康检查
- docker-compose.yml：单服务 + 绑定挂载 data/logs + 日志轮转 + TZ
- docker/entrypoint.sh：幂等初始化 → exec serve（LF 行尾，已由 .gitattributes 锁定）
- docker/healthcheck.py：纯标准库探活 /login（slim 镜像无 curl）
- .dockerignore / .env.example；数据目录可用 WB_DATA_DIR 等环境变量覆盖

## 文档
- docs/USER-GUIDE.md    用户使用手册（含 9 张真实界面截图）
- docs/DEPLOYMENT.md    部署运维（Docker / 裸机 / 反代 / 备份 / 推 Gitea 注册表）
- docs/ARCHITECTURE.md  架构与设计说明（含已知坑与红线、验证体系）
- docs/API.md           接口参考（路径 / 参数 / 返回结构 / 错误码）
- docs/FAQ.md           常见问题；docs/CHANGELOG.md 变更日志

## 修复缺陷（8）
1. /records/export 必然 500：生成器在请求上下文销毁后才迭代，改用自建连接
2. 大屏页图表全白：相对路径把 echarts.min.js 解析成 /vendor/... → 404
3. /users 500：路由已注册但模板缺失
4. 明细页日期筛选失效：视图传 f.frm、模板读 f.from
5. 配置页维护按钮全死：调用了不存在的 WBU.bindMaint()
6. 审计只能看最近 40 条：LIMIT 写死
7. 明细页多跑一条无用 SELECT：day_list() 取了没人用
8. 登录页锁定阈值未从配置注入

## 安全加固
- 新增 safe_next()：拒绝 //evil.com 等协议相对 URL 的开放重定向
- 缺 CSRF 的写请求统一 400
- 默认开启云端 HTTPS 证书校验（ssl_verify=1）；Cookie 是账号凭证
- 登录失败计数表加上限与 TTL
- /logout 拆分为 POST(执行) + GET(仅提示)，防 <img src=/logout> 静默退出
- settings 内部簿记键 slot:* 读写两侧过滤，不再从 /api/settings 泄漏

## 内部质量与工具
- 设置项写时校验 + 读时兜底，杜绝「一个手滑的数字让采集整个跑不起来」
- 全局 ValueError → 400：手写 query string 不再暴露 500 页面
- CSV 导出改 csv.writer 流式写入（原手工拼串，字段含逗号会串列）
- bundle 明细加 20000 上限并回传 recordsTotal/recordsTruncated，不静默丢数据
- tools/smoke.py 离线回归 99 项；tools/check_live.py 真实 HTTP 56 项
- tools/shots.py Playwright 逐页截图 + JS 报错收集

## 验证
- compileall 通过；smoke 99/99；对容器实例 check_live 56/56；截图 0 JS 报错
- 容器内采集实测成功（trigger=startup 补跑：新增 11 条）
这个提交包含在：
wangchuanli
2026-09-14 14:55:50 +08:00
当前提交 86631ae7ab
共修改 58 个文件，包含 9409 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
docs/USER-GUIDE.md
+413
查看文件
@@ -0,0 +1,413 @@
# WorkBuddy Portal 用户使用手册
> 面向**使用者**（不是开发者）。读完这份就能独立完成日常操作：
> 登录 → 看用量 → 配置采集 → 查明细 → 导数据 → 处理常见异常。
**目录**
- [一、这个系统是做什么的](#一这个系统是做什么的)
- [二、登录与账号](#二登录与账号)
- [三、获取并填写 Cookie](#三获取并填写-cookie)
- [四、概览页：一眼看清家底](#四概览页一眼看清家底)
- [五、用量大屏：交互式分析](#五用量大屏交互式分析)
- [六、数据明细页：查、筛、导](#六数据明细页查筛导)
- [七、任务管理页：定时与补采](#七任务管理页定时与补采)
- [八、配置管理页：参数与维护](#八配置管理页参数与维护)
- [九、日志管理页：出问题先看这里](#九日志管理页出问题先看这里)
- [十、用户管理页（仅管理员）](#十用户管理页仅管理员)
- [十一、常见任务速查](#十一常见任务速查)
- [十二、常见问题](#十二常见问题)
---
## 一、这个系统是做什么的
它把 WorkBuddy 账号的**积分用量明细**自动采集下来，存成一份**永久全量存档**，并提供查询与可视化。
为什么不直接看官网？官网只给一段时间窗口的明细，过期就查不到了；导出的 xlsx 还会丢掉
约 22% 的 `User Prompt` 内容。本系统把数据落到自己的库里，**只增不减**，随时能翻旧账。
一次典型的日常是：
```
每天 09:00 / 17:00 系统自动采集（你什么都不用做）
↓
你想看看进度 → 打开「概览」看今天用了多少
想深挖 → 打开「用量大屏」按模型/客户端/时段切
要找某条记录 → 「数据明细」搜索 + 展开 Prompt
要拿给别人 → 「数据明细」→ 导出 CSV
```
---
## 二、登录与账号
打开 `http://<部署机器IP>:8848`，会看到登录页。
![登录页](images/00-login.png)
| 项目 | 说明 |
|---|---|
| 默认账号 | `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 已经在本机设置里：
```bash
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` | 证书校验失败 | 见「十二、常见问题」 |
---
## 四、概览页：一眼看清家底
![概览页](images/01-overview.png)
从上到下四块：
**1. KPI 卡片（6 个）**
| 卡片 | 含义 |
|---|---|
| 存档总量 | 库里一共多少条记录（只增不减） |
| 累计积分 | 全部记录的积分合计 |
| 活跃天数 | 有记录的自然日数量 |
| 今日积分 | 今天（本地时区）已消耗 |
| 今日 vs 昨日 | 今日与**昨日整日**对比，带涨跌幅 |
| 采集健康 | 最近若干次采集的成功 / 失败情况 |
**2. 今日 vs 昨日整日**
注意「昨日」是**完整一天**，而「今日」还在进行中——上午看数字偏低是正常的，
该跟昨天的**同一时段**比才有意义（大屏页能做这个对比）。
**3. 调度状态**
显示调度开关、下次执行时刻、上次采集结果。这里显示「已停用」时采集不会自动跑，
到「任务管理」把调度打开。
**4. 模型 TOP + 最近采集**
按模型看积分消耗排行；下方是最近几次采集的触发方式（手动 / 调度 / 启动补跑）、
耗时、抓取条数、新增条数、去重条数。
---
## 五、用量大屏：交互式分析
左侧导航点「**用量大屏**」，或直接访问 `/dashboard`。
![大屏首页](images/07-dashboard.png)
大屏是独立的交互页，顶部可切**时间区间**（今日 / 近 7 天 / 近 30 天 / 自定义），
所有图表联动重绘。主要图表：
| 图 | 看什么 |
|---|---|
| 日历热力图 | 哪几天用得猛（颜色越深越多）。**注意：格子颜色是「该日合计」**，不是单条 |
| 趋势折线 | 按天的积分走势，判断是否在加速 |
| 维度分布 | 按**模型**或**客户端**拆分的占比 |
| 时段分布 | 24 小时里集中在哪些时段（配合判断是否有脚本在跑） |
| 单笔 TOP | 最贵的单次请求，含 Prompt 摘要——最值得优化成本的地方 |
![大屏交互](images/08-dashboard-interact.png)
> 页面左上角有「← 返回后台」等入口，随时能回管理后台。
> 大屏的数据是**按当前筛选窗口实时取**的，不是预生成的静态图——切区间会重新请求。
**怎么用它省钱**：先看「单笔 TOP」抓出最贵的请求类型，再看「时段分布」判断是不是
某个自动化任务在固定时间跑，最后用「数据明细」把那一批记录导出来逐条分析。
---
## 六、数据明细页：查、筛、导
![数据明细页](images/02-records.png)
### 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`；
- 数据量大时也是边查边吐，不会把服务器内存吃满。
---
## 七、任务管理页：定时与补采
![任务管理页](images/03-tasks.png)
### 7.1 调度设置
| 项 | 说明 |
|---|---|
| 启用调度 | 总开关。关掉后只有手动采集会跑 |
| 每日时刻 | 逗号分隔的本地时刻，如 `09:00,17:00`。**保存即生效，不用重启** |
| 启动补跑 | 打开后，程序启动时会把今天已错过、且还在宽限期内的时刻补采一次 |
| 补跑宽限期 | 超过多少小时就不补了（默认 12 小时） |
> 调度线程在 Web 进程内，所以「关掉 Web」等于「关掉调度」。
> 如果偶尔忘了开机，靠「启动补跑」把错过的时刻补回来。
### 7.2 手动采集
- **立即采集一次**：按断点续采，最常用的按钮。
- **按区间补采**：填 `起` / `止`，把这几天重新扫一遍。
用途：换了 Cookie 之后回补漏掉的日期；或怀疑某天数据不全时重扫。
重扫**不会产生重复**——主键去重，已存在的记录按「更早的本地时间」保留。
> **同一时刻只能有一个采集在跑**。重复点击会返回「忙碌」提示，这是设计如此
> （SQLite 是单写者，并发只会互相拖慢）。等它跑完再点。
### 7.3 运行历史
每次采集都留一条记录：触发方式、状态、耗时、抓取/新增/去重条数、退出码。
点「详情」看这一次的**逐行日志原文**，包括 `[warn]` 和 `[error]`。
---
## 八、配置管理页：参数与维护
![配置管理页](images/04-config.png)
### 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 修改密码
填「当前密码 / 新密码 / 确认新密码」。改完当前会话仍然有效，其他会话需要重新登录。
---
## 九、日志管理页：出问题先看这里
![日志管理页](images/05-logs.png)
三个区块：
**1. 采集运行历史**（可翻页 + 按状态筛 `ok` / `warn` / `error` / `running`）
每行可展开看**逐行日志原文**——排错时最有用的一块。
**2. 应用日志尾部**
Web 进程自身的日志（启动、异常栈、调度动作）。默认展示尾部若干行。
**3. 操作审计**
谁在什么时候做了什么：登录、登录失败、改配置、触发采集、导出、建号删号……
可按**动作**筛选，支持翻页。
> 排错顺序建议：操作审计（有没有人动过） → 采集历史（采集本身成不成功） → 应用日志（程序有没有异常）。
---
## 十、用户管理页（仅管理员）
![用户管理页](images/06-users.png)
| 操作 | 说明 |
|---|---|
| 新建账号 | 填用户名 / 显示名 / 密码，可勾选管理员 |
| 改显示名 | 行内直接改，保存即生效 |
| 改权限 | 管理员 ↔ 普通用户 |
| 改密码 | 给忘了密码的同事重置 |
| 删除 | 删除账号 |
内置三条护栏（前端和后端都拦）：
1. **不能取消自己的管理员身份**（防止把自己锁在门外）；
2. **不能删除自己**；
3. **至少要保留一个账号**（防止系统变成没人能登录）。
---
## 十一、常见任务速查
| 我想… | 怎么做 |
|---|---|
| 立刻采集一次 | 任务管理 → 立即采集一次 |
| 回补某几天的数据 | 任务管理 → 按区间补采，填起止日期 |
| 换 Cookie | 配置管理 → 凭证 → 粘贴新 Cookie → 保存 → 回补最近几天 |
| 导出某段时间的数据给别人 | 数据明细 → 选日期 → 导出 CSV |
| 导出全量存档 | 配置管理 → 维护动作 → 导出全量 CSV |
| 找出最贵的请求 | 用量大屏 → 单笔 TOP |
| 看某条请求的完整 Prompt | 数据明细 → 该行「展开」 |
| 给同事开只读账号 | 用户管理 → 新建账号，**不勾**管理员 |
| 同事忘记密码 | 用户管理 → 该行「改密码」 |
| 把数据备份走 | 拷 `data/usage.sqlite`（连同 `-wal`/`-shm`），或导出全量 CSV |
| 关掉自动采集 | 任务管理 → 关「启用调度」 |
| 改采集时刻 | 任务管理 → 每日时刻，如 `08:30,12:30,18:00` → 保存 |
| 系统变慢了 | 配置管理 → 整理数据库；再不行看「十二」 |
---
## 十二、常见问题
### 采集报 `cookie_expired` / `unauthorized`
Cookie 过期。重新按 [3.2](#32-拿-cookie-的两种办法) 拿一份新 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. 到「日志管理 → 应用日志」看有没有异常栈。
### 关掉浏览器后调度还在跑吗
在的。调度在**服务端进程**里，和浏览器无关。要停就去「任务管理」关调度开关，
或停掉服务。
### 忘记管理员密码
在部署机器上执行：
```bash
python manage.py passwd admin 新密码 # 裸机
docker compose exec portal python manage.py passwd admin 新密码 # Docker
```
### 数据会丢吗
正本是宿主机上的 `data/usage.sqlite`。`docker compose down` **不会删数据**；
只有显式 `docker compose down -v` 或手动删目录才会。
定期拷走这个文件（连同 `-wal` / `-shm`）就是完整备份。
### 能不能同时开多个采集进程
不能，也没必要。SQLite 单写者 + 文件锁的设计就是为了避免并发写。
真要跑多副本，除第一份外都要设 `WB_DISABLE_SCHEDULER=1`，
且只有一份能安全写——所以**不要**横向扩展这个服务。
---
更多技术细节见 [架构与设计说明](ARCHITECTURE.md)、[部署与运维指南](DEPLOYMENT.md)、
[接口参考](API.md)。