unis-oa/docs/performance-optimization.md

983 lines
82 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 性能:这个系统的钱花在哪
写给改代码的人。核心只有一句:**这个系统的慢几乎从来不是某条 SQL 写得慢,而是一个接口
在数据库上排了几次队**。所有优化与所有自检都围着这一句转。
## 一笔账
```
一次请求 ≈ 语句条数 × 一趟往返 + 提交次数 × 一次 fsync + Python 自己那点时间
```
量过的数(开发机 → 库在 192.168.124.202 的 MySQL 8):
| 量 | 远端库 | 同机副本 |
| --- | --- | --- |
| 一条最轻的 `SELECT 1` | p50 8.9ms | 0.35ms |
| 一趟完整流程(发起 + 逐环节审批到办结) | 2858ms | 395ms |
同一段代码、同一份数据,差的七倍全在往返次数上。于是判断一个接口要不要动,
先看它问了几条语句,再看语句写了什么:
```bash
cd backend
python3 scripts/slow_reads.py --account localadmin --password 'xxx' # 耗时 + 语句数 + 最慢几条
python3 scripts/perf_guard.py # 全站每个接口几条语句
python3 scripts/perf_guard.py --dups # 顺便报出「一次请求里串着重复问同一张表」的接口(只报告)
```
## 已经落地的十二层
1. **只读复用**(`app/readcache.py`):同一个 Session 里同一条只读结果问过一次就不再问,
按"这条结果依赖哪几张表"作废——任何 Session 写了其中任何一张,这一条立刻失效。
认不出写了哪张表就全场作废,宁可白重取也不给旧值。`OA_READCACHE=off` 整层退回原样。
认人那五处(`account_of` / `resolve` / `map_accounts` / `account_status` / `org.refs_for`)
现在共用 `personref.rows_for` 那一份人员行,同一个人一次请求只问一趟
(见《认人这一趟》)。
流程引擎里也有两份这样的共用清单:`_completed_rows`(这张单的已办)与
`_task_rows`(这张单的待办),各挡住一次审批里重复问同一批行的那几趟
(见《环节抄送那几趟》《待办名单这一问》)。
2. **并发只读块**(`app/parallel.gather`):互不相干的只读块各开一条连接并发跑,
首页、单据详情、待办列表、设计器目录都在用。铁律是块内只读、块内就地序列化成
`dict`/`list`,绝不把 ORM 对象递到块外。`OA_PARALLEL_BLOCKS=off` 退回串行。
3. **选择器探针**(`app/service/org.py`):一串审批人名字里那些"哪个类别都不是"的,
以前每个白问五趟(身份 / 人员 / 部门 / 角色 / 分组)。现在一条 SELECT 里挂五个
`EXISTS` 一次问完,并且整批名字合并成一条预探。30 个不中成员从 150 条 / 2007ms
降到 2 条 / 57ms。同一把探针后来也管住了设计器那两问("这个名字是哪一类"、
"它同时还是哪一类"),见《设计器里那两问》。`OA_SELECTOR_PROBE=off` 退回逐档试错,
`=verify` 每档都再对照一次。
4. **批量预取**:字典选项一次 `MGET` 读完(`cache.get_many_json` + `DictCache.prefetch`),
**`MGET` 没命中的那几本再合起来问一条 `IN`**(`dicts.payloads_by_codes`)——以前只并了
共享缓存那一半,字典 60 秒 TTL 到期或刚被 `invalidate` 的那一趟还是逐条排队问库
(`/draft/types` 七个字典实测 472ms → 28ms;`/job/{job}` 与 `/work/{id}` 标题里挂的
字典变量同理,各从 10 条回到 7 条)。岗位角色成员一条 `IN` 加一次成员合探
(`org.prefetch_roles_of`,只在当前环节真配了角色时才预取)、人员引用一批一次查完
(`org.refs_for`、`expand_accounts_many`)。
同源还有一条:一次审批里有四条路在问**同一行** `users`——"这个账号是不是个人"
(`personref.account_of`)、"这个人还在不在职"(`org.live_refs`、`org._expand_identity`)、
"这批配置指的是谁"(`personref.map_accounts`)。现在一条 `IN` 把账号与状态一起捞回来
(`personref.account_status`),并**按单个账号**存进只读缓存:37 次审批里 `users`
上的来回从 219 条降到 93 条(一次审批少排约 3.4 次队)。写了 `users` 一律当场作废,
"新建的人当场认得、停用的人当场挡掉"一个字没动——省的只是排队。
5. **表单读合并**:`autofill.form_content()` 一个 Session 里同一张表单只问一次库,
标题模板、自动带出、试算都从这一个键派生。以前 ORM 身份映射是弱引用,取完不持有
就会再问一遍,一趟试跑能读同一条表单 2.7 次。外面又套了一层**进程内快照**
(第十二层),跨请求也只问一次库,改了那张表单才作废。
6. **留痕上一条内存带过**(`engine._previous_log_time`):审批要写一条流转日志,
时间戳得比上一条晚,以前每趟回库问一次上一条。现在在 Session 里记着(按 MySQL
`DATETIME(0)` 的四舍五入对齐过),审批少四条 `oa_work_log` 读。
7. **一张单的已办读一次**(`engine._completed_rows`):「上一环节处理人」、抄送上下文里的
上一批人、办结时那句「最后一条正常办结」,问的都是同一张单的同一批 `oa_task_completed`,
以前一次审批要问五趟。现在整批取回来在 Session 里挑,写过这张表立刻作废重问。
8. **连接收尾只付一次**(`[database] pool_reset`,默认 `none`):借连接在这里只有两条路
——ORM Session(`close()` 自己回滚)与 `with engine.connect()/begin()`(自己 commit/rollback),
两条都自带收尾,可出厂口径下连接池归还时还要再补一刀 `ROLLBACK`。一次单据详情要开
7 条 Session(主线程 1 + 并发块 6),于是每个请求白付 7 趟往返;
`scripts/check_pool_reset.py` 把"归还的连接一定已经自己收尾"钉住(带一次反向自检,
故意脏归还一次,证明这个探针抓得住)。
9. **设计读一次,全站都算**(`app/designcache.py`):流程定义(`oa_process` /
`oa_activity` / `oa_route`)是发布之后就不再动的配置,可审批、单据详情、审批人预览
每次都各排三次队去问同一份东西。现在这条链进 Redis:存的是**原始行的列值**,
取回来照旧交给 `definition.build` 拼,构造口径全站还是只有一处。作废挂在连接层
那条写语句上(与只读缓存同一个把手):写这三张表任何一张,键当场删,并留 30 秒
"刚改过"标记挡住在飞请求回填。`OA_DESIGN_CACHE=off` 整层退回每次现查。
10. **报文在提交之前拼**(`app/api/runtime.py::_commit`):`SessionLocal` 开着
`expire_on_commit`,一提交,刚写过的那几行全被标记过期,接着拼报文就得逐行回库刷
回来。一次没办结的审批末尾正好挂着两条这种刷新(当值那条待办 + 这张单子),发起、
打开待办、抄送、分享、评论、改派、挂起、改道各有一笔同样的白问。现在这些接口统一
走"flush → 拼报文 → 提交",省了多少见下面《报文在提交之前拼》那一节。
11. **启动那一趟只反射一次、只探一次**(`app/db.py::create_schema`、`app/seed.py`):
服务和数据都好了之后,每天开服务要问的两百来条基本都是"有没有活要干",一条都不落地。
现在建表补列把全库结构一次读齐(三条查询)、`create_all` 只收缺的那几张表,出厂
种子那几处历史修复各留一条空探测,两百多条降到三十来条,`_startup()` 从 5 秒上下
到 1.2 秒,省的全是远端库的往返。见《启动那一趟》。
12. **空表的结论留在进程里**(`app/presence.py`):审批、发起、单据详情每趟都要问四遍
"这张表里还有没有值得看的行"——事件订阅、通知渠道、流程代理、还没落地的卡人报文。
本部署这四张表都是 0 行,于是每趟排四次队换回来四句"确实没有"。现在结论(一个布尔,
或一份 JSON 化的快照)留在进程里,没人写过这张表就沿用上次那个。作废挂在**提交**上
而不是写语句上:本进程走 `after_commit`,别的进程走 `app/cache.py` 的失效广播,
而**本 Session 自己写过的表一律照实问库**。`OA_PRESENCE=off` 整层退回原样。同一轮
还顺手把配置快照的周期从 2 秒放宽到 60 秒(订阅上失效广播才放宽,广播一断自动退回
2 秒),省下每个请求一次 `oa_system_setting` 整表读。见《四次"确实没有"》。
引导项也跟着调过:`pool_pre_ping` 默认关(远端库上它值 8~10ms 一个请求,连接被服务端
回收的事由 `pool_recycle=1800` 兜),池子放到 16 + 32,因为并发块会把一个请求占的连接
从 1 条抬到最多 1 + `parallel_workers` 条。
## 现在的水位
流程那一头(`备用金申请流程`,本机库副本,探针开):
| 路径 | 优化前 | 现在 |
| --- | --- | --- |
| `POST /task/{id}/execute` 一次审批 | 101 条语句 | 53 条 |
| `POST /job` 一次发起 | 35 条 | 33 条 |
| 整趟流程(发起 + 审批到办结 + 三次详情) | 149 条 / 483ms | 134 条 / 354ms |
| 同一趟流程在远端库上(真实部署,两次各跑一遍) | 2858ms | 2394ms |
| 一次没办结的审批(用印流程,语句条数中位) | 33 条 | 30 条 |
| 一次审批(用印流程,稳态:命中设计缓存) | 26 条(上一轮) | 22 条 |
| 整套用印冒烟合计(9 单 / 37 次审批 / 174 个请求) | 2462 条(上一轮) | 2217 条 |
| 设计器「重复审批人」体检(15 个手工环节那张画布) | 57 条 / 976ms | 12 条 / 241ms |
| 试跑一个环节时读同一张表单 | 2.7 次 / 趟 | 1.3 次 / 趟(再套一层进程内快照后:同一张表单三趟问一次库) |
| 启动建表补列 `create_schema()`(结构已对的那一趟) | 191 条 / 4378ms | 3 条 / 275ms |
| 启动出厂种子 `seed.run()`(装好之后那一趟) | 37 条 / 530ms | 24 条 / 349ms |
| 启动整趟 `app.main._startup()` | 5.1~7.4s(同一台机器上抖动大) | 1.2s |
| 单据详情 `GET /job/{job}`(已办结,同一进程逐次交替 A/B) | 103.6ms | 87.0ms(趟数一条没少) |
| 部门树 `GET /org/tree` | 4 条语句 | 3 条 |
| 发起一单 `POST /job`(备用金线,稳态) | 27~28 条语句 | 24~25 条 |
| 审批一次 `POST /task/{id}/execute`(同一条线,稳态) | 22~23 条语句 | 18~20 条 |
| 一个环节挂 R 条抄送规则时读 `oa_read` | 2R 趟(每条规则各问两遍) | 合起来 1 趟;一条人都抄不出时 0 趟 |
| 一次审批里 `UPDATE oa_work` | 2 条(第一条被第二条整个盖掉) | 1 条 |
| 备用金线整趟(1 发起 + 6 审批,同一进程稳态) | 158 条 | 153 → **150 条** |
| 一次审批里按 work 读 `oa_task`(单据游标名单 / 抄送去重) | 各问一遍:抄送问到两次的环节 3 趟 | 共用一份:两问之间没写待办就只问 1 趟 |
| 一次审批里把同单历史行的 `latest` 置假那条 `UPDATE` | 这张单的全部已办都要锁一遍、比一遍 | 只锁那条还是真的(结果一字不差) |
| 审批人目录 `GET /process/approvers`(身份 DN 迁移前后) | 7 条(14 个岗位全解析不出人) | 18 → **8 条**(14 个岗位各带 1 人) |
接口这一头:`/draft/types` 远端库 280ms → 242ms(Redis 来回 11 → 7 次);字典没命中的
那一半再并成一条 `IN` 之后,冷缓存那一趟从 12 条 / 416ms 回到 6 条 / 279ms。全站 99 个
只读接口合计 272 条(这一轮并掉部门树负责人那一读、又把审批人目录那五条探测并成一条,279 → 272):扫描前先整圈预热,量的本来就是稳态那一圈。量之前先看一眼有没有哪个门刚写过设计
(`check_seed_repairs` 这类)——"刚改过"那 30 秒里共享缓存不许回填,`/job/{job}` 与 `/work/{id}`
会各多三条 `oa_process` / `oa_activity` / `oa_route`,看着像退步,其实是在等标记过期。被填平的是字典 TTL
一到(或刚 `invalidate`)就要付的那笔——`/job/{job}` 与 `/work/{id}` 从"字典过期那一趟
10 条"回到与稳态一样的 7 条,`/draft/types` 首跑与稳态的差距也从 7 条缩到 1 条。基线
重记过七次:认人从两条并成一条 JOIN、"一人多身份"那张档案副本表整张下线、流程定义整条
链进共享缓存、空表探针上线,再到字典冷路径并条,逐接口的数记在
`backend/scripts/perf_budget.json`。这一轮只读那一圈一条没动(实测还是 272 条),动的是
**写路径**:发起与审批里认同一个人为排队四遍,现在问一遍(见《认人这一趟》);
环节抄送那两问也并成了一问(见《环节抄送那几趟》);留痕与站内信那两次整刷改成只刷该刷的
那几行(见《留痕与站内信那两次"整刷"》)。之后只读那一圈的预算重记过一次(第七次):实测涨到 275、预算跟着 274 → 275,四格变动
逐格查过——`/task/completed` +2 与 `/work/created` +1 是这位登录人名下**终于有了**已完成单据
(列表非空才做批量补全),`/design/data-sources/process-fields` -1 与 `/draft/types` -1 是连测
三次都稳定的新值;`/design/integrations/{code}/samples` 那格存成 3 时其实是噪声(稳定值 2),
手工改回。整圈扫下来这一圈在 275~276 之间晃(《待办名单这一问》那一轮之后实测 276,预算跟着的容错是 2,逐接口 0 处超线,预算没再动),多出来的那一格每次都在
`/design/integrations/*` 或 `/draft/types` 这一族里(单独连着跑三次都是同一个数,进了整圈就
±1——整圈按顺序预热,共享缓存冷不冷看它排在谁后面),这正是每格留 2 条容错的用途。
`/auth/captcha` 那一会在 0 一会 1 同理,是 Hub 配置在共享缓存里冷不冷;同一进程交替对比
过:整刷与只刷传入行的读语句一字不差,与代码无关。
身份 DN 迁移加批量认人这一轮之后实测还是 276、逐接口超线 0。`/process/approvers` 那一格基线仍
写着 7、实测 8,落在容错 2 之内,没为它单独重记整份基线:重记是把噪声族那几格(`/draft/types`、
`/design/integrations/*`、`/auth/captcha`)连同它们这一次的冷热一起烙进去,代价比省下一格红字大。
## 少排一次队也算性能:把"一人多身份"整张表拆掉(2026-10)
`oa_identity` 是 O2OA 留下的"一个人挂多个身份"档案表。认人口径早就换成登录账号了,
它只剩下两处展示用途(人员列表那一列、组织树节点那行 DN),代价却一直在付:同步、
建号、改部门、删人四处要维护它,`/auth/me`、`/org/tree`、`/org/persons` 各为它多排
一次队,`org.refs_for` 那批"这串引用是谁"的批量查询也要多问它一趟,作废规则里还得多
按一张表算。表删掉之后 DN 由 `users` + `oa_unit` 现算(`org.dn_for`,纯字符串),
展示一行没少,四个接口各少一条语句,同步少一整段写入。
**表拆掉了,数据里还压着一批身份 DN**。认人口径换成登录账号之后,引用是**按字符串**存在库里
的:审批岗位成员 `oa_role.list_auth`、日程归属人 `oa_schedule.owner`、网盘归属与共享
`oa_file.owner` / `shared_identities`、环节审批人 `oa_activity.config.taskValues`,往运行态还有
待办归谁 `oa_task.identity`、站内信发给谁 `oa_notification.identity`、流转日志里谁做的
`oa_work_log.from_identity`……那里面存的还是老的 O2OA 身份 DN(`紫光汇智\经营管理中心\张梅\zhangmei`、
`系统管理员\localadmin`)。多身份一删,这**一个人都解析不出**,而且不报错:审批人算出来是空的、
单子卡在第一个环节、归属人显示成一串反斜杠。全站 14 个审批岗位**全部**解析出 0 人就是这个——
冒烟脚本过去每次都要临时把岗位挂到管理员名下才跑得通,根子也在这。`migrate_to_users_table.py`
当年写着"人名、身份 DN 一律不碰":那时 DN 还认得,这句话是对的;删掉多身份之后,它把这批引用
撂在了半路。
`scripts/migrate_identity_refs.py` 补的就是这一步,底线只有一条:**宁可少改,不许改错审批人**。
只动现在解析不出人的那些值,认得出的原样留着;DN 末段是库里现存的账号就换成那个账号,末段不是
账号但倒数第二段恰好只有一个同名在职人也换;剩下的(人已经不在库里、或者有歧义)一律不动,
报出来交给人看——设计器把它报红是对的,悄悄换成一个可能不对的审批人是错的。配置那一档是默认档
(先 dry-run 看清单,`--apply` 才写库,写之前整表备份进 `backups/`),运行态与历史行那一档
(`--runtime`,24 列)单独开关,因为那动的是留痕不是配置。库里实跑:配置 **25 行**(`oa_role` 14
/ `oa_schedule` 5 / `oa_file` 6)、运行态 **862 行**。之后 14/14 个岗位各解析出 1 个真人,备用金
第一环批完,财务经理那张待办落到 `zhangmei` 名下(以前是空的);7 条在途待办全部指向真实账号,
那六张在办单过去是**没人能办**的孤儿。
坑记两处:MySQL 里 **JSON 列永远不等于一个绑定字符串**,`WHERE` 得写 `CAST(col AS CHAR)=:old`,
第一版就是这么静默改到 0 行;带反斜杠的值也别用 `LIKE` 去筛(MySQL 的 `LIKE` 还要再解一层转义,
写错同样是静默 0 条),`DISTINCT` 之后本来没几个值,取回来在 Python 里认这个反斜杠。
留下没动的 155 行仍带 DN,全部属于五个已经不在库里的人(`测试经办人` / `测试部门主管` /
`测试总账会计` / `测试总经理` / `QA测试总经理B`),是测试留下的历史行;换算不出的一律不动,
所以它们还在那儿。常驻门 `scripts/check_identity_refs.py` 因此只钉配置那一档——"还能换算成账号
的 DN 必须为 0";历史行允许有"人已经不在库里",不该把门钉红。
## 设计那三趟:从每次审批都排队,到全站问一次(2026-10)
流程定义在 O2OA 那一套里是"打开一张单就得重读一遍"的东西,于是它出现在每一条热路径上:
一次审批 37 条语句里有三条是 `oa_process` / `oa_activity` / `oa_route`,`GET /job/{job}`
那三块并发块里问的也是同一份,而同一个人连着点五张同流程的单,这五遍之间设计一个字没改。
库里只有几百行的时候这条完全看不出来,它是纯排队,不是慢 SQL。
`app/designcache.py` 把这条链放进 Redis(跨请求),换来的是:
| 路径 | 之前 | 之后 |
| --- | --- | --- |
| `POST /task/{id}/execute` 一次审批 | 37 条 | 34 条(远端库少 ≈ 55ms) |
| `GET /job/{job}` 单据详情 | 12 条 | 8 条 |
| `GET /work/{id}` 单据详情(按主键) | 10 条 | 7 条 |
| 全站 99 个只读接口合计 | 294 条 | 282 条 |
两处刻意的设计:
* **缓存里存原始行,不存拼好的定义**。命中之后照样走 `definition.build`,构造口径全站
只有那一处;缓存自己不可能拼出另一种流程定义。
* **回填要过一道"刚改过"标记**。光"写时删键"是不够的:甲请求按旧设计查完还没存,
乙在这中间发布了新版,甲会把旧设计存回去并一路用到 TTL;发布失败回滚也会把一版
根本没存在过的设计留下。写完 30 秒内不许回填(一个 Lua 脚本把判与写合成一趟),
TTL 默认 600 秒兜"绕过应用直接改库"这条路。
同一轮还把审批路径上问**同一行 `users`** 的四条路并成一条(`personref.account_status`,
理由见上面第四层)。同一套冒烟(九张真单据、37 次审批)量出来:每次审批的语句条数中位数
37 → 32,`users` 上的来回 219 → 93 条。
`python3 scripts/check_design_cache.py` 钉住:命中与现查逐字段一模一样、命中那一趟
一条 SQL 都不许多问、改了环节配置当场生效、**未提交的设计进不了缓存**、别处提交一次
设计写下一个 Session 立刻看得见、写单据不牵连设计缓存、整层关掉读出同一份定义。
报文那一头另有一遍逐字节比对:库里 26 张单(在途 + 归档)在开与关两种口径下
`/job/{job}`、`/work/{id}` 的响应一字不差。
## 报文在提交之前拼:每次审批少刷两行(2026-10)
`SessionLocal` 是 `expire_on_commit`(SQLAlchemy 的默认值):`commit()` 一跑,Session 里
所有对象都被标记过期。偏偏流转那一圈接口的写法是"提交完再拼报文"——`db.commit()` 之后
`serializers.task(t)`、`serializers.work(work)` 读的每一列都不再是内存里那份,于是拼一个
对象就回库多问一条。取到的证就摆在语句序列末尾:
```text
INSERT INTO oa_operation_log ... ← 引擎与操作日志都写完了
SELECT oa_task.id AS oa_task_id ... ← 白问:把刚处理的那条待办刷回来
SELECT oa_work.id AS oa_work_id ... ← 白问:再把这张单子刷回来
```
改成"flush → 拼报文 → 提交"。flush 这一步不能省:本项目的 Session 关着 `autoflush`,
`create_time` 那几列的 Python 侧默认值要靠 flush 才落到对象上。两条前提写在 `models`
的口径里,改表时得一起看:`oa_work` / `oa_task` / `oa_read` / `oa_work_comment` /
`oa_operation_log` 没有一列用 `server_default`(库里也核过:没有自增列,也没有
`ON UPDATE CURRENT_TIMESTAMP`),所以 flush 之后不必再回库取数据库生成的值;序列化只读
列属性、不碰关系,拼报文本身不会再问出 SELECT 来。
能省几条要看这次审批是不是这张单的**最后一步**:办结那一趟 `result.work` 退回归档件的
主键,本来就没得刷;没办结的那一趟才在付这两条。九张真单据、37 次审批那套冒烟(用印
流程,多数环节走完还有下一环)量出来:
| 口径 | 之前 | 之后 |
| --- | --- | --- |
| 一次审批的语句条数(中位 / 均值) | 33 / 35.3 条 | 30 / 33.5 条 |
| 37 次审批合计 | 1306 条 | 1240 条 |
| 整套冒烟合计(发起 + 审批 + 详情 + 预览) | 2565 条 | 2461 条 |
| 一次发起 | 26 条 | 24 条 |
远端库一趟往返 17~21ms,一次审批少排两次队 ≈ 35~40ms。
报文有没有变?`scripts/check_write_payload.py` 是这样钉的:发起 / 打开待办 / 审批三趟
请求,**最后一条写语句之后不许再有任何 SELECT**;再把接口回的那份与"另起快照、从库里
重新查出来再序列化"的那份逐字段对,只放行时间那一秒(`DATETIME` 落库四舍五入到整秒,
而 `serializers.dt` 抹掉微秒)。最后一条是反着来的:故意把序列化打坏,这次操作必须整个
回滚——库里不许留下"报了错、单子却已经在库里走完了"那种两头不靠的半截状态。
同一条判据也铺到了另外几条写路径上(`scripts/check_action_surface.py`,46 项)。批量处理、
挂起/恢复、`POST /read/{id}/handle`、`POST /job/title/preview` 这四条以前**一条断言都没有**
(连 `expense/runner.py` 那十个场景也没走到),评论与抄送只是被那两个场景顺带调一次、
没验过结果。它们正是"改完看不出、上线才发现废了"的那类。断言钉的是行为而不是条数:
批量里混一条坏 id 只许失败那一条(整批回滚与整批报失败都算坏);挂起之后那张待办必须
办不动、`status` 一个字不许动、没有 `monitor:work` 的人碰不到别人的单;"抄送需处理"只能
由本人带意见走 `handle`,不许被"标记已阅"顶掉,也不许被再抄一次降级;评论写完在列表里、
删掉就不在;标题预览带同一份表单数据算出来的那一句,必须等于真正发出去的那一句。
它跑的是进程内的真接口,建单删单都只认自己按时间戳起的那几个标题。
## 启动那一趟:两百多条"有没有活要干"降到三十来条(2026-10)
服务和数据都好了之后,开一次服务其实只想知道一件事:有没有活要干。答案通常是"没有",
可这一趟以前要问两百多条,每条都是一个远端往返(这台机器上 17~35ms),人在终端前
等的那几秒全花在排队上。两处占大头:
| 启动里的这一趟 | 以前 | 现在 |
| --- | --- | --- |
| 建表补列 `create_schema()` | 191 条 / 4378ms | 3 条 / 275ms |
| 出厂种子 `seed.run()` | 37 条 / 530ms | 24 条 / 349ms |
| `_startup()` 整趟 | 5.1~7.4s(同一台机器上抖动大) | 1.2s |
建表补列分三步砍下来。第一步是别问五遍:`create_all` 对每张已存在的表问一遍
"你在不在"(60 条),补列、补索引、补列注释、搬老列、清退役五步又各起一个 Inspector、
各把 60 张表反射一遍(一张表的结构就是一个 `SHOW CREATE TABLE` 来回)——六步共用一份
反射就省掉四遍。第二步是别替已存在的表白问:`create_all` 只收"模型里有、库里还没有"
那几张表,而这份名单本来就在第一条 `SHOW FULL TABLES` 里,顺手还暖了方言那侧
"这张表在不在"的缓存,60 条又没了。第三步是干脆别逐表问:这五步要的只有三样——库里有
哪几张表、每张表有哪几列(补注释那步多看一眼列注释)、有哪几个索引名,三样各能一条按库
过滤的 `information_schema` 查询拿全,于是 60 个来回变成 3 个(`app/db.SchemaSnapshot`,
这一步 191 条 → 3 条)。
哪一步真的改了表结构就把这份结构作废,免得下一步拿着旧结构判断——这条不是洁癖,
下面第二条 bug 就是它。逐表反射也没删干净:`[database] schema_reflection = "per_table"`
就退回一张表一张表地问,留给 `information_schema` 被代理挡得不全的环境;两条路补出来的
结构由体检脚本钉成一模一样。
出厂种子贵在"每趟启动把整张表读回来,发现无事可做":修 JSON 数组列的每张表开一个存档点
先数一遍、对银行卡那两句 UPDATE 每趟真跑一遍(行锁和 binlog 一样不少)、补流程分类与
默认表单的各把流程与表单整叠读回来、内置权限角色一个角色一条 SELECT,还有一处把
`users` 连口令哈希一起搬回来,只为拼一张后面根本用不上的姓名表。现在这些都先问一句
"到底有没有要改的行",探到了才动手。
省的前提是**该修的照旧修**:预探写错的症状不是报错,是脏数据永远留在库里、界面上什么都
看不出来。所以这两步各配一个体检脚本,都在自己的临时库里做,业务库一个字节都不碰:
- `scripts/check_seed_repairs.py`(22 项):造一个空库出厂,再把六类历史数据各打坏一次
——JSON 列塞对象、银行卡缺 `person_id` / 账号对不上人、流程没分类、流程没绑默认表单、
部门负责人与直属上级清空、内置权限角色删干净、门户四块演示内容全删——跑一趟种子逐项
断言修回来了,再跑一趟断言一行都不许动,最后记一笔"装好之后那一趟"的语句条数(预算 30)。
- `scripts/check_schema_bootstrap.py`(20 项):空库一次建得出模型声明的全部表与列;
删掉一张表、一列(上面挂着唯一索引)、一个索引,同一趟 `create_schema` 必须全补回来;
结构已对那一趟只许花十来条语句(预算 12);同一份拆坏,`bulk` 与 `per_table` 两种
读法必须补出一字不差的列与索引。
这两条都不是摆设,写它们的时候当场抓到三个已经落进代码的问题:
- 种子的 JSON 数组列预探用 `row.t` 取表名。`Row.t` 在 SQLAlchemy 2.0 里是"整行当元组"
那个老属性,不是这里起名为 `t` 的那一列,于是每张表都数成 0,**整趟修复静默失效**,
服务照起、日志照笑。改回按位置取值,并由体检脚本把"打坏能修回"钉住。
- `create_all(tables=...)` 收的是 Table 对象,写成表名会炸成 `AttributeError: name`,
症状是**空白库一张表都建不出来**;而 `create_schema` 每步单独兜底,把它压成返回值里
一行不起眼的字符串,非空库启动过就看不出来。
- 共用反射之后,改了表结构不作废缓存就会出错事:把 `clear_cache()` 关掉重放一次拆坏,
`users.hub_user_id` 补回来了、它上面那个唯一索引却在那一趟被跳过,`create_schema`
一声不吭——正是半年后才看得见的那种。所以"同一趟里列和它的唯一索引一起回来"被写成
了断言。
## 加进程这一层:只读翻三倍,写路径基本白加
前面七层省的都是"少问几条、少跑一趟",也就是每个请求的**串行库往返**。还剩一种慢不在
这里:返回体不小的只读接口,钱花在 Python 序列化与 gzip 上,单进程时这一截把 CPU 占满,
库再快也排不上队。这一层由 `OA_WORKERS` 买(默认 1 = 与加它之前一模一样):
| 接口 | 1 进程 | 4 进程 | 涨了多少 |
| --- | --- | --- | --- |
| `GET /org/tree`(62KB 报文) | 72 次/秒,p50 105ms | **196~214 次/秒,p50 ~30ms** | 2.7~3.0 倍:序列化 + gzip 是 CPU 活 |
| `GET /draft/types` | 62 次/秒,p50 79ms | 83 次/秒,p50 58ms | 1.3 倍 |
| `POST /job` 一次发起 | 16.3 / 25.3 单/秒 | 18.0 / 21.3 单/秒 | **不涨**:往返与 `sync_binlog=1` 的 fsync 才是墙 |
写路径那两列是两轮各测一次(`uvicorn --workers` 一轮、`OA_WORKERS` 走 `run.py` 又一轮),
两边互相穿过,所以老实写成"不涨"而不是"+10%":p50 还从 300ms 抬到 350ms,多开进程只是
多几个一起等库的人。只读那一行两轮都是近三倍,稳。
同一批压测零错误零死锁,`Threads_connected` 峰值只有 12。进程数不影响后台任务:
延时唤醒、超时提醒、Hub 同步、写回投递在几台机器上都只有一个进程在跑,靠
`oa_worker_lease` 租约。怎么开、连接账(进程数 ×(16+32)vs `max_connections`)怎么算、
它和 `OA_PARALLEL_WORKERS` 为什么是一起乘的,见 `docs/multi-worker-deployment.md` 第 5.1 节。
一句实话:这一层一行 SQL 都不用动就能把只读吞吐翻三倍,但它救不了流程 —— 一趟审批
剩下的 2394ms 里几乎没有 CPU 的时间,全是远端库的往返。所以它排在"把库挪近"后面。
## 详情页这一轮:把排队拆开,把重复的收尾去掉
量法还是"数真往返",但这一轮把探针伸到 SQL 之外——SQLAlchemy 的语句探针看不见
`COMMIT` / `ROLLBACK`,而那才是这张详情页真正的大头:`GET /job/{job}` 看着是 12 条语句,
实际打库 **26 次**,其中 14 次是 `ROLLBACK`(`Session.close()` 一次、连接池归还再一次,
后者纯属重复);另一头,流程定义那四句(流程 → 环节 → 路由 → 表单)互不依赖却串在
同一条线程上,一个人独占 57ms 的关键路径。
两处都改完之后:
| 接口 | 真往返 | 中位耗时(新旧两套代码交替打 9 组) |
| --- | --- | --- |
| `GET /job/{job}` | 26 → 19 | 209ms → 151ms |
| `GET /work/{id}` | 27 → 19 | 262ms → 161ms |
| `GET /task/{id}` | 31 → 24 | — |
`/work/{id}` 多出来那一次是它自己:按 `work_id` 已经拿到行了,又转手按 `job` 查第二趟。
对照的两个进程同一个库、同一台机器、都关着后台调度,一新一旧交替打,抵消远端库的
延迟漂移。报文是**逐字节**比过的:拿改前的写法另起一个进程,`/job`、`/work/{id}`、
`/task/{id}`、`/admin/work/list`、`/org/tree` 那 8 个报文一字不差。
表单那一句顺带修了一个隐患:原来是"一个表单一趟 `db.get`",环节挂三个表单就是三趟
串行往返;现在一条 `IN` 问完,清单在 SQL 里算(环节上挂的 + 流程的 `latest_form`),
所以它也能和别的块一起并发。两份清单口径必须一致,`scripts/check_job_payload.py`
每个流程都把 SQL 那份与 Python 那份 `form_ids()` 对一遍,还用未提交的合成数据
(环节挂重复表单)钉住顺序与去重;归档单"流程定义后来被删了"那两支也各有一条。
## 四次"确实没有":把空表的结论留在进程里(2026-10)
命中流程设计缓存之后一次审批只剩 26 条语句,其中四条问的是同一类问题——"这张表里还有
没有值得看的行":
| 这一条在问 | 本部署的答案 | 改之前 |
| --- | --- | --- |
| `oa_open_webhook` 里启用的事件订阅 | 0 条 | 每趟都问 |
| `oa_notify_channel` 里启用的通知渠道 | 0 条 | 每趟都问 |
| `oa_agent` 里启用的流程代理 | 0 条 | 每趟都问 |
| `oa_outbound_message` 里还没落地的卡人报文 | 0 条 | 每趟都问 |
`app/readcache.py` 那一层只活在一个 Session 里,于是这四个队每趟流转都得重排一次,
换回来四句"确实没有":远端库上就是四次 17~35ms 的往返,而答案几周都不变一次。
`app/presence.py` 把结论留在进程里——一个布尔(还有没有行),或一份 JSON 化的快照
(眼下只有表单定义在用)。三条规则保证它读不到旧值:
* **作废挂在提交上,不挂在写语句上**。写语句发出去不等于已经提交:挂在写法上,
"甲在事务里启用一个渠道还没提交、乙在这中间探了一次把『没有』存下"就会让这个渠道
在下一趟 TTL 之前一直隐形。本进程走 `after_commit`(回滚只丢掉自己记的账),
别的进程走 `app/cache.py` 的失效广播——广播本来就是提交之后才发的那一条。
* **本 Session 自己写过的表一律不用缓存**,读也不读、存也不存。少了这条,
"同一个请求里先把渠道启用、再给它发一条测试消息"就会拿着改动之前的结论办事。
* **存之前先比对作废代号**:问库那段时间里被作废过就当没算过。再兜一层 TTL
(默认 60 秒,`OA_PRESENCE_TTL`)挡"绕过应用直接改库"。
同一台远端库、`seal_apply.py --run`(9 张真单据、37 次审批)量出来:
| 路径 | 之前 | 之后 |
| --- | --- | --- |
| 一次审批(稳态:命中设计缓存) | 26 条 | 22 条 |
| 37 次审批合计 | 1250 条 | 1099 条 |
| `GET /job/{job}` 64 次合计 | 655 条 | 596 条 |
| `POST /job` 9 次发起合计 | 220 条 | 193 条 |
| 整套冒烟合计(174 个请求) | 2462 条 | 2217 条 |
| 全站 99 个只读接口合计 | 282 条 | 279 条 |
同一次统计里审批的中位是 31 → 26。中位比稳态高出来的那几条不是这一层的功劳,是落在
流程设计缓存"刚发布 30 秒不许回填"窗口里的那些审批——一趟冒烟只有 4 次设计作废,
摊到 37 次审批上就成了中位比最小值高几档。
`python3 scripts/check_presence_guard.py`(34 项)钉的是:三种作废时机各走一遍
(本进程提交 / 本进程回滚 / 别处提交之后那条广播)、认不出写了哪张表时整层作废、
**同一个 Session 写过的表必须当场看得见**、四个调用点各开三趟独立 Session 必须
"比不开这一层问得少、答案一字不差",以及空表那一趟第二条都不许多问。表单快照
单独钉"三趟问一次库、提交完立刻换新"。
配置那一头是同一个思路的另一半:订阅上失效广播之后,`oa_system_setting` 快照的周期
从 2 秒放宽到 60 秒(`app/dbconfig.py::CACHE_SECONDS_WITH_BUS`)——保存配置的那一趟会
广播一条,各进程收到就立刻重读,不必每两秒回库读一整张表;Redis 配了却没连上时
`bus_subscribed()` 为假,自动退回 2 秒的老口径。
## 设计器里那两问:一个名字别问四趟(2026-10)
设计器每预览一个环节,都要给环节上每个审批人来源回两句话:这一行解析不到人时"它其实
是哪一类"(`selector_kind_of`),重名时"它同时还是哪一类"(`selector_kind_conflict`)。
这两问在代码里是**逐条问库**:一个名字把人员、部门、岗位角色、分组各问一趟,两个函数
又各问一遍,而它们只在设计器里说话——不碰流转,所以前面十二层谁也没管过它。
一张 15 个手工环节的画布跑一次「重复审批人」体检,光这两问就是三十多趟纯排队:
| 口径(同一台远端库,样例身份 localadmin) | 之前 | 之后 |
| --- | --- | --- |
| 体检一次(`POST /process/processes/{id}/dedup-audit`,用印那张画布) | 57 条 / 976ms | 12 条 / 241ms |
| 同一个接口走 HTTP(含路由与序列化) | p50 651ms | p50 329ms |
| 库里五张画布各跑一次合计 | 2646ms | 856ms |
| 设计器审批人预览(用印冒烟里的均值) | 6.5 条 / 次 | 5.5 条 / 次 |
省法没有新 machinery,是把第三层那把五档探针用到该用的地方,另加一句复用:
* **探针说这一档不沾,那条只会回空的查询就不发**。探针依旧从不替"存在"下结论:
探不到、`OA_SELECTOR_PROBE=off`、探针问崩了,全都照原样逐档问库。
* **问出来的存在性按「类 + 值」缓存在本 Session**(`org._kind_exists`):同一个名字被
"它是哪一类"和"它和谁重名"各问一遍,就此并成一次;写过 `users` / `oa_unit` /
`oa_role` / `oa_group` 任何一张,答案当场作废。
* **角色那一档干脆不用问**:角色的成员清单本来就按名字缓存着(`role_members` 交回
`None` 就是"没有这个角色"),存在性跟着它要。
* **整批预热**:体检开始前把整张画布的名字一次预探、角色成员一条 `IN` 取齐
(`dedupaudit._warm_org`),免得十五个环节各探各的。只填缓存,判定照旧逐环节走。
`OA_READCACHE=off` 那档把两处预热都跳过:缓存关着,预热带回来的东西留不住,
热一次就是白热一次(实测那一档下新旧两种写法都是 111 条,一字不差)。
有一条是顺手抓出来的反面教材:预热一开始把"发起人上级""部门负责人"这些**根本不进这两问**
的来源也一起探了,于是三五个环节的小流程反而多付一条预探(4 条变 5 条)。判"要不要探"
的依据是这一行的来源类型在不在 `SELECTOR_KINDS` 里,不是它有没有值。
`python3 scripts/check_selector_kinds.py`(42 项)钉的是:新写法与"逐条问库、不缓存
不跳档"的老写法在四类上逐一对齐、两个函数交出的措辞逐字对齐;同一个名字第二次问一条
都不许多发;四类都不是的名字预热之后四档一条都不问;整批预探严格比逐个问库省
(实测 5 个名字 19 → 5 条);`OA_SELECTOR_PROBE=off` 时判定一字不变;这四张表任何一张
被写过(新建一个与已有角色重名的部门)答案必须当场重来;体检预热与否报文一字不差。
临时行跑在事务里,跑完整体回滚。
## 构建那一趟:同一份类型检查别跑两遍(2026-10)
前头都在数接口在库上排了几次队,这一节是另一头:改前端的人每次打包都要付的那几秒。
`pnpm build` 是 `vue-tsc -b && vite build`,而 `vite.config.ts` 里还无条件挂着
`vite-plugin-checker({ vueTsc: true })`——它一边打包一边又起一个 vue-tsc 把整个项目
再查一遍,而且压在关键路径上。同一台机器、同一份代码:
| 口径 | 之前 | 之后 |
| --- | --- | --- |
| `npx vite build` | 10.8s | 6.4s |
| `pnpm build` 整趟 | 21.0s | 15.8s |
checker 现在只在开发模式下挂(它的用处就是把红字铺在页面上),构建那一步的类型闸门
本来就在 `vue-tsc -b` 那一关,单独查还有 `pnpm typecheck`。"产物与它无关"不是推断:
把 checker 装回构建里打一次、摘掉再打一次,`dist/assets` 下 123 个文件逐个 sha256
一字不差。前端 36 个测试文件 349 个用例全过;`vite` 开发服务就绪 193ms,那条本来就不慢。
顺手记一件不省时间但挡路的:`pnpm lint:check` 在 HEAD 上就是红的——设计器右侧属性栏
`NodeInspector.vue` 挂着 10 条 `vue/no-mutating-props`。那是这套设计器的编辑模型(属性栏
直接改父组件传进来的那个 `activity` 对象,画布跟着动),不是笔误。代价是这条门现在给不出
信号:谁改前端都会撞见这 10 条,然后怀疑是不是自己弄坏的。真要修得把组件的编辑口径换成
emit 回父组件,那是改设计器的交互模型,得单独立项,不该混在性能改动里。
## 索引这一层:会长大的表上,等值过滤的那一列有没有索引可用(2026-10)
前面每一层都在省"问几次",这一层管的是另一本账:**每问一次,MySQL 要在表里翻多少行**。
判据只有三条,缺一条就是假警报(第一轮扫出 32 处、真缺口三条;照着同一套判据这一轮又扫出三条,一共补了六条):
1. **只看会长大的表**——运行态、日志、台账这类一直 INSERT 的表。几十行的编目表
(`oa_role` / `oa_unit` / `oa_dict_item`)不在其列:给十行表的某一列建索引,
优化器自己都懒得走。
2. **只看没有打头索引可用的列**——`(a, b)` 那种复合索引只有 `a` 对等值查找有用,
所以 `status` 跟着 `identity` 一起筛的时候不算缺口。
3. **只看没人收窄的那一条**——同一个函数里如果还有别的等值条件落在打头索引列上,
MySQL 就有一条走得通的路,这一列跟着被筛一下不贵(`oa_read.read_type` 永远跟着
`identity` 或 `work` 一起问,就是这一档)。
补上的六条,以及各自的证据(**只有替身表实测过的那几条带数**,其余是执行计划):
| 索引 | 谁在这么问 | 证据 |
| --- | --- | --- |
| `users.display_name` | 认人那条 `account = ? OR display_name = ?`(全站最热的一问) | 5 万行替身表 **35.6ms → 7.8ms**(index_merge 把两边并起来);按姓名 `IN` 46.9 → 8.8ms |
| `oa_read.work` | 每次抄送去重、每次办结搬档都按 work 问 | EXPLAIN 全表扫 → `ref`。本部署 8 行,没计时 |
| `oa_attachment.work` | 每张单办结那句 `UPDATE ... WHERE work = ?` | EXPLAIN 全表扫 → `ref`。同上 |
| `oa_work_completed.(form, finish_time)` | 集成模板预览:某张表单最近 15 张已办结的单 | 2 万行替身表:被查的 form 很稀或很旧时 **65.1ms → 17.7ms**(新建的写回模板一张办结单都没有,是最狠的一种);常见 form 中位 10.7 → 9.9ms,几乎不动,因为本来就在倒着扫 `finish_time`。批量搬档 2000 行 489 → 524ms |
| `oa_outbound_message.(integration, create_time)` | 模板页的"报文历史":某个集成最近 50 条报文 | 2 万行替身表 **59.9ms → 16.7ms**,执行计划从"整表扫 + filesort"变成"索引倒排"(`ORDER BY` 那一列一起放进来,省掉排序) |
| `oa_quota_ledger.work` | 办结 / 作废钩子按单号问"这张单还占着多少额度" | EXPLAIN 全表扫 → `ref`;另一处 `(work = ? OR job = ?)` 从整表扫变成 `index_merge union` |
**`index_merge` 要每一支都有索引可用才凑得齐**,这是 `oa_quota_ledger.work` 与
`users.display_name` 那两条的真正来由:`WHERE a = ? OR b = ?` 里只要有一支没索引,
整条就退化成整表扫——所以"这一列自己有索引了"还不够,得看它跟谁一起出现在 `or_` 里。
**加索引唯一的真实风险是顺序**,不是快慢。逐条查过:单值等值列加二级索引前后,
返回顺序完全一致(并列行按主键破平,与聚簇扫同一口径);唯一顺序可变的点是
`org.selectors_exist` 里 `display_name IN (...)`,其结果喂进 `set()`,不受影响。
两条新加的 `(列, 时间)` 复合索引服务的是 `ORDER BY 时间 DESC LIMIT n` 且**没有第二排序键**
的查询(`template_samples` / `template_messages`):同一秒办结的两张单,先后可能换——
这两处原本就随执行计划变,真要钉死就在查询里补一个 `id` 兜底排序,别指望索引顺序。
常驻门:`python3 scripts/check_index_gaps.py`(`--models` 判新建库会得到什么,
`--all` 把"看着可疑其实没事"的那一档也列出来)。它按**函数**归堆解析 `app/` 下的 AST,
判不出两件事:同一条 `or_` 里两边都缺索引时只会各报一次、不会提示该合建复合索引;
一个函数里两条互不相干的查询会被算成互相收窄(少报的方向)。**没索引又不建,必须
在脚本里的 `EXEMPT` 写下一条理由**(写清哪一处调用、为什么不建、什么条件回来补),
索引补上之后那条理由会被判过期、催着删。现在记着 12 条,举两个代表:
`oa_task.person`(只在删人前数一次待办,`oa_task` 是有界的在途表、又是写热点)、
`oa_file.owner_person`(`or_` 第三支是 `json_contains`,这一列补了索引也凑不齐 index_merge)。
## 详情页与部门树:能并的别再串着等(2026-10)
到这一轮,接口里的「排队」只剩两种形状:**同一件事问了两遍**,以及**互不相干的两件事串在了一条线上**。这一轮各中一个。
量法也换了一次。把服务开在探针自己的进程里,包 pymysql 的 `Connection._execute_command`
(SELECT 与驱动层的 `ROLLBACK` 都走它)与 redis-py 的 `execute_command`,一次请求付给
MySQL / Redis 的每一趟就都数得出来。A/B 不再「先跑一版再跑另一版」——远端库的抖动比要量的
差距还大(同一个配置连量三次:110.5 / 103.1 / 106.4ms)。改成一个进程里同时装着两版实现
(改造前那份 `runtime.py` 以另一个模块名装进来、挂到另一条路径上),**逐次交替打**:同一进程、
同一连接池、同一段库况,抖动自己抵掉。
**部门树的负责人不必再回库问一次**(`GET /org/tree`)。拼人员节点时刚把 `users` 整张读过
一次,紧接着给部门节点补负责人姓名,又按 `users.id` 读了第二次(本部署 7 个人 / 10.5ms)。
现在负责人先到这批已经在内存里的行里找,只对找不到的发一次 `IN`。找不到的恰好是三种真会
发生的库状态:负责人已停用(树上不显示他,部门节点还得写他的名字)、负责人是内置系统账号
(同理)、负责人在本次数据范围之外(部门负责人只看自己那一支,撞上别支的人当负责人)——
这三种一律照旧回库问,一个名字都不能少。语句 `4 → 3` 条,报文逐字节相同。
**详情页那趟 Redis 读挪进了并发块**(`GET /job/{job}` / `GET /work/{id}`)。流程定义命中
共享缓存就不必再摊三块出去问,这件事是对的;错的是这一读**串在并发块前面**:时间线里第
30ms 到第 54ms 那一段全是它一个人在等(本部署 Redis 也在另一台机器上,一趟 9~20ms)。它与
`logs` / `task_completed` / `attachments` / `writeback` / `tasks` 互不相干,于是也当成一块
塞进同一次 `gather`。同一进程交替 30 对(已办结的一张单):
| | 中位 | p25 | MySQL 趟 | Redis 趟 | 报文 |
| --- | --- | --- | --- | --- | --- |
| 改造前 | 103.6ms | 96.5ms | 12 | 1 | 17772 字节 |
| 改造后 | 87.0ms | 83.0ms | 12 | 1 | 与改造前逐字节相同 |
30 次里 26 次新版不慢于旧版。**趟数一条没少**,动的只是「谁等谁」。
**审批人目录那五条探测并成一条**(`GET /process/approvers`)。设计器选审批人那一页要把每个
岗位角色 / 分组的成员都解析出来,"这一条配置认不认得出一个人 / 部门 / 岗位角色 / 分组"以前是
四类各问一条批量 `IN`("人"还拆成账号与姓名两条)——五条串在一条线上。这一层早就有一条把
五档 `EXISTS` 并排在一条 `SELECT` 里的探针在替审批人解析问同一件事(见《设计器里那两问》),
于是目录也走它:一条语句问完整批,答案还顺手存进本 Session,后面逐个展开成员时逐档解析
直接跳档。语句 `11 → 7` 条,报文逐字节相同。
判定口径按原样**只认四档**:探针的 `identity` 那一档问的是"这个账号 / 主键在不在 `users`
里",而且不看在职与否,与"认不认得出一个能审批的人"问的不是同一件事,所以那一档一律不算数。
三种情况退回原来那四条批量 `IN`:探针被 `OA_SELECTOR_PROBE=off` 关掉、那条语句问崩了、
以及**一批值多过一条探针的容量**(25 个)—— 值一多,带 `IN` 的批量查询才是对的工具,
不该把几百个 `EXISTS` 串成一条重语句去换一样多的往返。
跟着一起定下来的三条口径:
* 表单清单从「环节块顺手一起问」里拆出来单独成一块:`_process_form_rows` 只认
`process_id`,与环节行本来就不相干。命中与否都要问,所以它先摊出去、不等缓存的答复;
没命中那一支的语句条数因此一字未变——两条各占一个并发位,不再挤在同一块里串着跑。
* **这一层整个不参与时不许倒退**:没配 Redis 或 `OA_DESIGN_CACHE=off` 时那一读必然回空,
再让它占一个并发位、把那三块拖到第二轮去,就是自己给自己加一轮排队。于是先问一句
`definition.design_cache_enabled()`:这一层不参与的部署照旧一趟 `gather` 摊开跑完
(同一进程交替 A/B、缓存关掉那一支:103.0ms → 94.3ms,两边都是 17 趟 MySQL)。
* 退路原样在:`OA_PARALLEL_BLOCKS=off` 之后所有块就地串行,`OA_DESIGN_CACHE=off` 之后
缓存那一读连占位都不占。
顺手钉住的两个地板值,免得下一轮再来撞墙:`GET /auth/me` 三个往返 / 43ms,两趟之间
12~15ms——远端库加远端 Redis 就是这么多,Python 侧只占响应尾部那 8~20ms;列表页在这个
口径下一条都不逐行问库(`org/persons` 取 50 行只用 4 条语句)。常驻门:
`python3 scripts/check_org_tree_managers.py`(18 项:常态确实少问一条、三种负责人的名字
照样写得出、临时改动全程在未提交事务里跑完回滚;把实现改成「只认内存、绝不回库」,
门当场报 7 条错)。
两条门的判据都不是"少问几条"就算了:部门树那条门会把那次 `IN` 的参数抠出来看**到底问了谁**
(复用得到的人不许再出现在 `IN` 里),审批人目录那条门挑的值里特意放了停用账号与 `users.id`
那种数字——把"只认四档"改成五档,它当场报这两条错(`check_selector_kinds.py` 现在 46 项)。
## 认人这一趟:一次审批里 `users` 从问四遍到问一遍(2026-10)
`perf_guard` 数的是 99 个只读 GET,**写路径一直是盲区**:审批人点一下"同意"要排几趟队,
以前只有《报文在提交之前拼》碰过一次。这轮把服务开在探针自己的进程里,把备用金那条线跑了一轮
**稳态**——先写一次设计、等 30 秒"刚改过"标记过期,让流程定义那三趟真命中共享缓存。第一版
探针没等这一段,量出来每次审批都多三趟 `oa_process` / `oa_activity` / `oa_route`,那是冒烟
脚本自己刚发布过设计,不是线上的样子:量写路径之前,先确认要量的那一层是不是刚被自己写过。
量出来的形状很难看:一次审批 22~23 条语句,其中 **4~5 条在问 `users`,问的还是同一个人**。
原因不在 SQL,在缓存的键——`account_of`、`resolve`、`map_accounts`、`account_status`、
`org.refs_for` 各有一份本 Session 缓存,各问各的一次 `users`:读的是同一行,却互不认账。
于是问库收到一处:`personref.rows_for`(账号一趟 `IN`,剩下读得出主键的再一趟 `IN`,部门
跟着 JOIN 出来,认不出也记一笔"不是人")。五个调用点全部从它取,`org.refs_for` 摊平的那
六个字符串照旧自己存一份。登录认人那一趟(`deps.current_user`)是全站第一个问 `users` 的,
问完把行 `note_row` 报进这一层,之后谁问同一个账号都是零往返。
**中间踩到一个真坑**:Session 的身份映射是**弱引用**。第一版改完,`account_of` 之后的
`resolve` 照旧要问一趟——`account_of` 只把字符串交给调用方,那行 ORM 对象没人引用,当场
被回收,`rows_for` 拿着缓存里的主键去 `db.get` 只能重问。现在这一层在本 Session 里把行
拿住(`db.info`,上限 512 人:一个请求碰到的就是发起人、几个审批人、几个抄送人,同步那种
批量认人不跟着拿)。这一条不钉住,下一轮一定有人把它当成"缓存没生效"再改一遍。
一次发起 + 六次审批(同一条线、同一段库况,各跑两轮):
| | 发起一单 | 一次审批 | 归档那一次 | 全程合计 |
| --- | --- | --- | --- | --- |
| 改造前 | 27~28 条 | 22~23 条 | 43 条 | 179~180 条 |
| 改造后 | 24~25 条 | 18~20 条 | 41 条 | 160~161 条 |
按这轮量出来的平均每条 18~20ms 折,一张单从头到尾少等 19 条 ≈ 350ms。墙上时间自己抖得比
这个还狠(同配置两轮差 400ms),所以这轮报的是**语句条数**,墙上值只当参考。
剩下的那两趟 `users` 是这一层的地板:登录那一趟主键,与选择器探针那条五档 `EXISTS`
(一次问完五档,本来就是并条之后的形状)。只读那一圈一条没动(99 个接口 272 条),因为
列表与详情页只认"当前登录的这个人",而那个人早就在第一趟里。
常驻门:`check_readcache.py`(76 → 84 项)。新增那八项钉的不是"少问几条",是这层容易被
改坏的地方:五个调用点**合起来**只问一趟、认不出的那一串换个调用点问也不去库里绕、登录
报进来之后后面各处零往返、写 `users` 当场作废,以及 `account_status` 只按账号问(值写成
`users.id` 不回状态,但 `account_of` 照认——历史列那口径一个字没动)。这一层不加新开关:
它就是一个 `readcache` 调用点,`OA_READCACHE=off` 之后退回各问各的,答案不变,只是又开始排队。
## 环节抄送那几趟:几条规则合起来读一趟 `oa_read`(2026-10)
一个环节可以挂好几条自动抄送规则(到达时抄、办完时抄、按条件抄)。旧写法里每条能抄出人的规则
各排两次队:`apply_activity_cc` 问一遍"这个环节已经抄过谁",`create_reads` 再问一遍"这个人手上
是不是已经有一条待阅",而这两问读的是**同一批 `oa_read` 行**——R 条规则就是 2R 趟。抄送密的那个
流程一次办结能摊好几条规则,远端库一趟 8~20ms,纯排在这两件本可以一次问完的事上。
现在一次读回来共用(`create_reads` 多了 `held` 这个可选参数,只在 `kind="cc"` 生效),并且
**真要抄人才问**:`targets` 空掉就 `continue`。第一版是无条件问,结果一个没挂抄送的环节反而多付
一条——懒问这一步不能省,省了就是拿"抄送少的常态"去换"抄送多的例外"。
两个口径得说清楚,不然"少问一趟"就是拿正确性换的:
- `already`(本环节已经抄过谁)按**刚把这一批行读回来那一刻**的 `(identity, activity)` 算。
autoflush 是关着的,这一趟到下一趟之间没人往库里塞东西,所以"读一次"与"每条规则现问一遍库"
逐字相同——即便中途 `create_reads` 把某条老待阅挪到了本环节,判定也不变。
- 跨规则不重复插靠的是 `busy`(这一轮已经排进抄送名单的人),**不是** `already`。`already`
现在是个快照,光读代码很容易以为它兜得住第二遍,所以这一条必须单独钉住。
常驻门:`check_cc_reads.py`(30 项,全程跑在存档点里,用完整体回滚)。它把改动前那段抄过来做
对照,在同一份库里状态下逐字段比对落下来的待阅(含两条规则各自的 `requiresAction` 不许被抹平、
预置抄送件上 `already` 只认本环节),再钉那条能证的等式:**R 条抄得出人的规则,改动前读
`oa_read` 2R 趟,现在 1 趟;一条人都抄不出时 0 趟**。
这一节刻意**不**报"本趟总语句条数"。同一格跑两遍,总数会被认人那层 Session 级 memo 的冷热带走
一条(逐条对语句时抓到过一次多出来的 `SELECT users`);而 `oa_read` 那一读不进任何 memo,
数出来的就是代码写死的形状。量这种"两条并成一条"的小改动,只数被并掉的那张表。
## 留痕与站内信那两次"整刷":一次审批少一条被盖掉的 `UPDATE`(2026-10)
一次审批里 `UPDATE oa_work` 有两条。第一条只写 `tokens` / `manual_identity_list` / `update_time`
三列,紧接着第二条写八列——**第一条写的那三列被第二条原样盖掉**,纯属白排一次队。逐条对语句
(连"这条从哪一层发出来"一起打)才知道来历:`_log` 与 `notify` 收尾用的是 `db.flush()`(整刷),
而热路径上调用处常常先改了单据、再落留痕、再发站内信,这张脏单据就被顺带刷了出去。改成只刷该刷的
那几行(`db.flush([row])` / `db.flush(rows)`)之后一次审批只剩一条 `UPDATE oa_work`;备用金线整趟
(1 发起 + 6 审批)158 → 153 条,按 18ms/条折回去少等约 90ms。
这种改动真正危险的不是"少一条语句",而是**以前有几处代码靠着这次整刷顺带把别的行刷进库**。
第一分钟就撞上一个:`_sync_work_cursor` 靠 `SELECT oa_task` 算"本环节处理人名单",刚 `db.add`
的待办之所以查得到,全因为 `notify` 那次整刷顺手把它们写了出去(autoflush 是关着的)。改成只刷
站内信之后这份名单算成了空的——`manual_identity_list` 从 `['某账号']` 变成 `[]`,"干预订单"
那一屏的本环节处理人就此消失。现在 `_arrive_manual` 在 `_sync_work_cursor` 之前自己
`db.flush(created)`:谁依赖什么,写在明面上,不再靠隔壁那次 flush 恰好路过。
于是这条改动的常驻门不数语句,而是**把同一张单从头到尾办两遍**:一遍把 `Session.flush` 换回
"传进来什么都不管"的整刷(=改动前),一遍照现在的代码跑,每一步把这张单在 `oa_work` /
`oa_work_completed` / `oa_task` / `oa_task_completed` / `oa_work_log` / `oa_work_comment` /
`oa_read` / `oa_read_completed` / `oa_notification` / `oa_attachment` 里留下的**每一行每一列**
对齐(随机主键、单号、时刻与按时刻算出来的 `duration` 先归一化)。上面那个空名单就是它抓出来的。
跑之前照例把审批去重临时关掉、把各审批岗位挂到管理员名下(与冒烟脚本同一手法,跑完原样还原),
否则同一个人连着几环会被自动跳过,一趟只有一步真办理,比不出东西。
覆盖范围说清楚:逐字段等价目前覆盖**备用金线整趟**(五步真办理 + 归档 + 一条抄送);用印九条线、
批量 / 挂起 / 待阅 / 评论那几个面,由各自的门加两条冒烟的逐条行数守着。**以后要动别处的 flush
范围,先给 `check_flush_defer.py` 加一条对应的 walk**,别只信冒烟的行数——行数看不出"某一列没写进去"。
加锁那一层没动:这条 `UPDATE` 只是推迟到同一事务里更晚的位置,事务边界与语句集合都不变;这条路径上
`oa_work` 本来也没有 `SELECT ... FOR UPDATE`(只有单号计数器 `oa_serial_number` 有),死锁仍由
`_retry_on_deadlock` 兜。
## 待办名单这一问:单据游标与抄送去重共用一份(2026-10)
一次审批里按 `work` 读 `oa_task` 有三处:`_sync_work_cursor` 要写"本环节有哪些人"那两列
(`manual_identity_list` / `manual_identity_text`),`_busy_identities` 要挑"这些人里谁手上还有活"
来挡重复抄送。问的是**同一批行**,只是筛法不同——后者只要 `status=pending` 且环节对得上的那几行。
抄送还在"到达"和"办完"各走一次,所以一个挂得出抄送的环节一次审批能问三趟。
现在两问共用 `engine._task_rows` 那一份(`(账号, 姓名, 状态, 环节)` 四列,不是 ORM 对象——
两张名单都只读不写,没必要把整批待办挂进身份映射),依赖表只写 `oa_task`:谁写了待办,
那份就当场作废。写这一层的钩子在连接层(`app/db.py` 那个 `before_cursor_execute`),
ORM 刷的、bulk 的、裸 SQL 的统统算数,所以"刚 INSERT 的新待办算不算数"这件事不用操心。
**省下来的比想象的少,这是实话**。同一进程里交替跑(把这一格的缓存命中强制关掉就是改动前的形状,
整趟走两遍取平均):备用金线整趟按 `work` 读 `oa_task` **21 → 19 趟**,整趟语句 **153 → 150 条**。
逐条打点看清楚了两问之间到底发生了什么:
- 抄送那两问(到达 + 办完)之间不写待办 → 第二问命中,稳省一趟。
- 游标名单与紧跟其后的抄送去重之间常常插着 `INSERT oa_task` / `DELETE oa_task`
(会签收票把兄弟待办删掉、加签再添人、办结删本人)→ 那份**当场作废**,两问各问一遍。
这是对的:中间真的改过待办,答案本来就该变。想让它"命中"只能改成不作废,那是拿正确性换排队。
所以这一格省的是"每个真挂得出抄送的环节一趟",不是"每一步一趟"。备用金线六个环节里只有
一个真挂得出抄送规则,其余环节的抄送去重根本问不到(没有匹配的规则就提前 return 了)。
顺带把 `INSERT oa_task_completed` 之后那条重置 `latest` 的 `UPDATE` 加了 `AND latest IS true`。
语句一条没少,改的是范围:原来为了把"整张单最后一条已办"这个标记挪到新行上,要把这张单的
**全部**历史行锁住比一遍,其中只有一行真的会变;现在锁的就那一行。结果集完全相同——
已经是假的行本来就该是假的。库里 26 张已归档单逐张数过:每张单 `latest` 为真的恰好一行。
常驻门:`check_readcache.py` 加了一节(84 → 90 项)。它钉三件事:缓存给的那份与现查一字不差;
"名单 + 两遍抄送去重"合起来只问一次库;**新增 / 删掉一条待办之后,抄送去重与本环节名单当场
跟着变**(这一条是本格真正的危险——抄送去重读旧名单会凭空挡掉一条合法抄送,或者漏挡一条重复的)。
外加拿库里每一张单把改前那两句 SQL 逐张对一遍(本环节 / 全环节两种问法)。
行为面另有一条要记的:这条 `UPDATE` 的锁定范围收窄,顺带意味着**已经是假的行不再被重写一次**,
所以那一行的 `update_time` 不会再被这次重置挪动(`update_time` 没有 `ON UPDATE CURRENT_TIMESTAMP`,
ORM 那条 Core `update()` 也不带 Python 侧默认值,改之前改之后都不会动它——只是范围收窄之后
连"同一值重写"都不发生了)。
## 审批人目录那一圈:批量认人与逐条认人必须同口径(2026-10)
`GET /process/approvers` 是设计器打开时拉的那份"谁能审什么":14 个岗位角色、2 个分组、15 个
部门,每条都要知道底下有没有人、是谁。身份 DN 还在的时候它只要 7 条语句——14 个角色一个人都
解析不出,往后那几档根本没跑。DN 迁移之后它**跳到 18 条**:`org.expand_accounts_many` 把一批值
交给并发块,每个 worker 自己开一个 Session,于是"认出这是个账号"这一件小事在 `users` 上排了
十几趟队。这不是迁移带来的退步,是这一格从来没被真数据喂到过。
`app/service/org.py::account_expands` 把第一档(值本身就是登录账号)并成一次 `IN`,走认人那层
共用的 `personref.rows_for`;剩下的姓名 / 部门 / 角色 / 分组照旧进并发块逐条。批量这一档的口径
逐字照阶梯第一档 `_expand_identity`:**认得出账号且在编制内**才算吃掉,认不出、停用的、姓名撞车的
一律原样留给逐条那一圈判,判定分支一条没删——批量只能省排队,不能顺手改答案,这是这类批量预取
唯一真正危险的地方。该端点 **18 → 8 条**。
等价性是钉住的,不是推论:`check_person_ref.py` 加了一节"批量认人与逐条同口径",同一个值单条问
一遍、批量问一遍,两份结果逐字比,再挂上语句计数器确认批量真的只问一条;11 段全绿。真库上另外
拿 25 个混合值(真人账号 / 停用账号 / 库里没有的账号 / 姓名 / 部门 DN)对了一遍:**25/25 一字不差**,
批量那一档当场吃掉 12 个。
## 一个人挂几处岗位:反查这一问不许按人排队(2026-10)
`oa_identity` 下线之后,"一个人几个身份"就剩一个意思:**同一个人被挂进几处岗位角色 / 分组**。
正向那一问(这个岗位有谁)一直是有的,反向那一问没有——想看看某人到底挂了几处,只能一个岗位
一个岗位点开翻。补上 `org.memberships_for` 与 `GET /org/persons/roles` 之后,人员管理页多一列
「岗位角色」,一眼看见 `huangxueqiu` 挂着总经理与财务总监、`ouyangjun` 挂着三处。
这一列是给**列表页**用的,所以它真正的风险不是准不准,是排队:按人发问就是每页 20 趟。
实现只有三条语句,其中两条是 `oa_role` 与 `oa_group` 各一整张(几十行,本来就要全读),第三条是
成员值批量认人那一次 `IN`;问 1 个人与问 20 个人问一样多次库,这条判据钉在门里(问 1 与问 20
各 3 条)。空清单直接不问库。
口径与正向逐字对齐,两处都不许漂:成员值就是本人账号的算**直挂名**(一条库都不必问);绕经部门 /
别的岗位名 / 分组名进来的,交给同一份批量阶梯,**认得出的才算他的岗位**,认不出的字符串不算人——
多算一个人的后果是界面上多一个"看起来该他批、真派待办却永远轮不到他"的人。绕进来那条还带
`via`,鼠标移上去看得见是经哪个岗位进来的。
顺手清掉两处 DN 时代留下的坑,它们正好都挡在"把一个人加进第二个岗位"那条路上:
* 岗位角色的编辑框按「字符串里有没有反斜杠」决定成员进选人控件还是进"按名称补充"文本框。
DN 一迁成账号,**所有成员都掉进那个逗号文本框**,选人控件打开永远是空的。现在成员整套
交给选人控件,那一格只留给真要按名字补的选择器。
* 分组的编辑框只把 `list_identity` 装进控件,保存时固定写 `list_person: []`——**任何人点开
编辑再保存,另一列成员就被清空**。后端读的是这两列的并集,所以这个洞不报错,只是丢人。
现在两列并成一个名单编辑,保存统一落回 `list_identity`,值一个不少。
`python3 scripts/check_memberships.py`(12 项)钉四件事:现网每个岗位正向解析出的人反查都算他
这一处;反查列出来的人正向也认;问 1 个人与问一整页问一样多次库;一个人挂两处岗位给出两处、
绕一层那条标出来路、两列各挂一次只算一处、成员认不出人时不算成任何人的岗位。临时岗位与分组
带 `(校验-` 前缀,开工前扫残留、收工按前缀删,另开一条连接复核库里为零。
## 已办折叠多问的那一条:数单比数行贵一格(2026-10)
「我的已办」以前把 `oa_task_completed` 的流水行原样摆出来:同一条流程退回重办过一次就摆两条,
看着像系统发重了单子。改成按单折叠(`app/service/completed.py`)之后,一次列表请求从
「数行 + 取行」两条变成「数 `DISTINCT work` + 分组取每张单的最近时间 + 按这批 work 回捞代表行」
三条。多出来的那一格是分组那一趟:`idx_oa_task_completed_identity` 只到 `(identity, completed_time)`,
按 `work` 分组要回表再落一次临时表。
预算跟着动了两格:`/task/completed` 5 → 6,`/portal/home` 16 → 17(首页那块「已办」面板同样折叠)。
`/statistics/workbench` 一格没多——数单和数行是同一条 `UNION ALL` 里换了下场的写法。
没拿它去换别的:这一屏本来就要排五六条队,多一条分组在同量级上。口径散没散有
`scripts/check_completed_dedup.py` 盯着(列表、导出、首页角标、工作台计数四处一起对账)。
## 动哪一层要跑哪一条
| 改动落在 | 跑这条 |
| --- | --- |
| 任何接口 | `python3 scripts/perf_guard.py`(`--dups` 顺带报出串着重复问同一张表的接口) |
| `app/readcache.py` 的调用点或作废规则(含引擎里 `_completed_rows` / `_task_rows` 这两份共用清单) | `python3 scripts/check_readcache.py` + `perf_guard.py --ab` |
| `app/cache.py`(Redis 那层)的批量读 / 失效 | `python3 scripts/check_shared_cache.py` |
| 流程定义缓存 `app/designcache.py` / `definition.load` | `python3 scripts/check_design_cache.py` |
| 空表探针 / 表单快照 `app/presence.py` 与它的四个调用点 | `python3 scripts/check_presence_guard.py` + `perf_guard.py --strict` |
| 认人口径 `app/service/personref.py`(含共用的 `rows_for`) | `python3 scripts/check_person_ref.py` + `python3 scripts/check_readcache.py` |
| 配置里的引用列(岗位角色成员 / 日程与网盘归属 / 环节审批人)与批量认人 `org.account_expands` | `python3 scripts/check_identity_refs.py` + `python3 scripts/check_person_ref.py` |
| 岗位归属反查 `org.memberships_for` / `GET /org/persons/roles` | `python3 scripts/check_memberships.py` |
| 审批人解析 / 环节路由 / 试算 | `python3 scripts/check_simulate_paths.py` |
| 设计器那两问 `selector_kind_of` / `selector_kind_conflict` / 去重体检预热 | `python3 scripts/check_selector_kinds.py` |
| 流转日志留痕 | `python3 scripts/check_log_timeline.py` |
| 已办按单折叠 `app/service/completed.py`(列表 / 导出 / 首页角标 / 工作台计数) | `python3 scripts/check_completed_dedup.py` |
| 写路径(引擎、办结迁移、抄送) | `python3 -m advance_cash --run`(自己建单、自己删单) |
| 批量处理 / 挂起恢复 / 待阅处理 / 评论 / 标题预览 `app/api/runtime.py` | `python3 scripts/check_action_surface.py` |
| 环节抄送建待阅 `engine.apply_activity_cc` / `create_reads` 的 `held` | `python3 scripts/check_cc_reads.py` |
| 引擎里 `db.flush` 的作用范围 `_log` / `notify` / `_arrive_manual` | `python3 scripts/check_flush_defer.py` |
| 跨进程租约 `app/service/leader.py` / 准备开 `OA_WORKERS` | `python3 scripts/check_leader_lease.py` |
| 写回什么时候真的发出去 `service/outbox.py`(`wake` / `_mark_wake` / `run_due` / `refresh_pending`)与 `main.py` 调度线程的睡眠 | `python3 scripts/check_outbox_wake.py` |
| Hub 传输层与熔断 `app/service/hub.py` | `python3 scripts/check_hub_breaker.py` |
| 单据详情的拼装 `runtime._job_response` / `definition.build` | `python3 scripts/check_job_payload.py` |
| 详情页什么时候问设计缓存 `definition.design_cache_enabled` | 上一条 + `python3 scripts/check_design_cache.py` |
| 部门树 / 部门列表补负责人姓名 `api/org.py::_managers_by_id` | `python3 scripts/check_org_tree_managers.py` |
| 审批人目录的存在性探测 `org.approver_directory` / `org.selectors_exist` | `python3 scripts/check_selector_kinds.py` + `perf_guard.py --ab` |
| 连接池归还口径 `[database] pool_reset` | `python3 scripts/check_pool_reset.py` |
| 出厂种子里那些"先探一眼再动手"的预探 | `python3 scripts/check_seed_repairs.py`(自建临时库,跑完自己删) |
| 动过索引 / `models.py` 的 `__table_args__` / 新写了等值过滤 | `python3 scripts/check_index_gaps.py` + `python3 scripts/check_schema_snapshot.py` |
| 启动建表补列 `app/db.py::create_schema` | `python3 scripts/check_schema_bootstrap.py`(同上) |
`--ab` 那条是逐字节比:同一接口在关缓存与开缓存下必须给出一模一样的报文。比法是"关缓存
打一头一尾、开缓存夹在中间",头尾那两个数一样就说明这一整个时间窗里库里没动过,中间
与它们的差异只能来自缓存。带秒级时间戳的接口(`/hub/schedule`)与打开就记浏览量的接口
会被单独报成"本身会变",那是接口自己的行为,不是缓存的问题
(`/auth/captcha` 也算一个:它有 Hub 熔断,冷却里与刚超时那两次的提示语不同)。
扫描本身只走只读接口,但个别接口按它自己的业务会顺手记一笔(打开文档加一次浏览量、
打开详情记一条已读),跑一轮约等于有人把界面上每个页面都点开过一次。逐接口的数有一格
左右的正常抖动(Redis 那层共享缓存恰好过期时会长几条),所以超线判定留了 `--tolerance`,
默认 2 条;基线在本机副本上记的,拿去对远端库同样只差一格,不用两个库各记一份。
语句条数超线时先分清两种情况:新功能确实要多问几条,就
`python3 scripts/perf_guard.py --save-budget` 重记基线;不是新功能,就是在哪个循环里
逐行问库了,`slow_reads.py` 会指出是哪几条。
## 开关一览(出事能退)
| 环境变量 | 配置项 | 默认 | 关掉退回到 |
| --- | --- | --- | --- |
| `OA_READCACHE=off` | — | 开 | 每次现查库 |
| `OA_PARALLEL_BLOCKS=off` | `[runtime] parallel_blocks` | 开 | 只读块按原顺序串着跑 |
| `OA_PARALLEL_WORKERS=n` | `[runtime] parallel_workers` | 6 | 一个请求最多占几条连接 |
| `OA_SELECTOR_PROBE=off` | — | 开 | 五档逐个试错 |
| `OA_REDIS_DICT_CACHE=0` | `[redis] dict_cache_seconds` | 60 | 字典每次现查库 |
| `OA_DESIGN_CACHE=off` | — | 开 | 流程定义每次现查库(那三趟回来) |
| `OA_DESIGN_CACHE_TTL=秒` | — | 600 | 设计缓存的 TTL,只兜"绕过应用直接改库" |
| `OA_PRESENCE=off` | — | 开 | 空表探针与表单快照每次现查库(那四条空查询回来) |
| `OA_PRESENCE_TTL=秒` | — | 60 | 上面那层结论的兜底 TTL,只兜"绕过应用直接改库";填 0 等于关掉这一层 |
| `OA_CONFIG_CACHE_SECONDS=秒` | — | 广播订阅上 60,否则 2 | 运行配置快照的重读周期;填小就退回"每两秒回库读一遍" |
| `OA_DB_POOL_PRE_PING=1` | `[database] pool_pre_ping` | 关 | 每次取连接先 ping 一次 |
| `OA_WORKERS=n` | `[server] workers` | 1 | 一个 HTTP 进程(后台任务本来就只有一个,与它无关) |
| `OA_DB_SCHEMA_REFLECTION=per_table` | `[database] schema_reflection` | `bulk` | 启动时一张表一次 `SHOW CREATE TABLE` 读结构(慢 1.5 秒,补出来的结构由体检钉成一样) |
| `OA_DB_POOL_RESET=rollback` | `[database] pool_reset` | `none` | 连接归还时再补一刀 `ROLLBACK`(出厂口径,每个请求每条 Session 多付一趟) |
`OA_REDIS_DICT_CACHE` 有个反直觉的地方:**库在近处时共享缓存反而是负担**。库在另一台
机器上时字典值读回来一次就值 9ms,共享缓存开 60 秒划算;库就在同一台机器上时一趟
0.35ms,比问 Redis(远端,9ms)还快,填 0 直接查库更快。口径写在
`app/service/dicts.py` 的 `shared_cache_seconds()` 那一段。
## 一个不回话的第三方,能把整个系统拖住多久
这一类不在"几条语句"里,它藏在线程池:同步接口共用 starlette 的 anyio 线程池(默认 40 条),
`urlopen(timeout=10)` 会把一条线程占满整个超时。开发机上 Hub 那台站连得上 TCP 却不回话,
于是登录页每开一次就空等 10 秒;44 个人同时打开就把池子占满,`GET /org/tree` 这种与 Hub
毫无关系的接口跟着卡了 10 秒,验证码自己的 p95 涨到 20 秒(排在别人后面等第二轮)。
修法是两道闸(`app/service/hub.py`,都是运行配置):冷却窗口 `hub_breaker_seconds`(默认 5 秒,
每 2 秒放一个探测)与在飞上限 `hub_max_inflight`(默认 8 条,超出的排 0.2 秒队)。
同一场 44 并发重测:验证码 p50 10.0s → **0.23s**,`/org/tree` 最大 10.0s → **269ms**。
只认"不回话"(明确拒绝证明它活着),错误类型没换,`hybrid` 回退本地口令那些行为一字不变,
填 0 整层关掉。完整口径见 `docs/hub-integration.md` 第 14 节,行为由
`python3 scripts/check_hub_breaker.py` 钉住(本地造假 Hub,不连库)。
教训值得记一句:**任何外部调用都可能变成"整个系统的延迟"**,判据是它占的是不是公共线程池、
超时是不是配到十几秒。后面接新外部系统时(网盘、企业微信、大模型)这两条要先问一遍。
## 还没做的,以及为什么没做
- **库与 Redis 的物理位置**。这是剩下的最大一笔(同一趟流程远端 2858ms / 本机 395ms),
但它动的是部署而不是代码:要么把开发库挪到近处,要么把 API 挪到库那边。等拍板。
- **权限那一查**。已经并掉了:`users` + `oa_unit` + `oa_auth_role` 现在是**一条 JOIN**
取完(认人是每个请求的第一件事,人员与角色分两趟问就是请求开头白排一次队)。
权限照旧每次现查,"改角色立刻生效"的口径一个字没动——省下来的只是排队,不是缓存。
再往下省就得给权限加 TTL 缓存,那是改安全语义,不是改性能,得单独拍。
- **审批里那七条 `users` 读**:这轮并完了(见《认人这一趟》)。整行人员档案与批量引用现在
共用 `personref.rows_for` 那一份,一次审批只剩两趟:登录态那一趟主键,与选人探针那条
五档 `EXISTS`。探针那一趟再要省,就得把"这个值是哪一类"跨请求缓存,那需要给它配一套
"写了 `users` / `oa_role` / `oa_group` / `oa_unit` 就广播作废"的键——与 `designcache`
同量级的一件事,换回来一趟往返,先不做。
- **一次请求里共用一份设计载荷**。试过,量下来省不到,已经回退。数过 `definition.load` 在每个
真实路径上每请求被调几次:发起 1 次、审批 1 次、`GET /job/{job}` 0 次、`GET /task/{task}`
1 次(路由守卫那一问)+ 1 次走 `cached_design` 的旁路命中、待办列表 0 次——一次请求最多把
同一个流程读**一遍**;列表里真会摊开多个流程的那处 `api/runtime.py` 早有自己的 `definitions`
去重。再加一层 Session 级 memo 只能挡住"根本没发生过的第二次",却要多养一条隐患:命中不了
这件事不许进缓存(把"空"也记住就等于把这层废掉,写的时候漏了一次,`check_design_cache` 当场
抓到)。这条结论记在 `definition.load` 的 docstring 里,别再往上加。
- **写路径剩下的那些"一趟一件事"**。这轮顺手把一次审批整个拆开看了(备用金线,稳态 18~20 条):
`oa_task` 问五次(取待办、执行前后各复核一次、同步单据游标、数会签在办的人),
`INSERT oa_task_completed` 之后紧跟一条把同单其他历史行 `latest` 置假的 `UPDATE`。
问 `oa_task` 那五次**后来纠正了**:取待办 / 执行前后复核那三次确实是三个不同的问题(状态与
环节各不相同),但"本环节名单"与"谁手上还有活"是同一批行的两种筛法,已经并成一份
(见《待办名单这一问》)。`task_completed` 那一对可以并进 INSERT
(得先确认 `latest` 的基线口径),还在引擎的写路径上,省一条 ≈ 18ms,出事却是"单子卡住"
那一档,等有更值的活顺手做。那条置 `latest` 的 `UPDATE` 本身留着(它与 INSERT 是不同行集,
除非把 `latest` 改成读时派生——那会改掉它"整张单最后一条已办"的语义,退回 / 加签同秒
并列时会算错,明确不做),但锁定范围已经收窄到那一行。
`_task_rows` 剩下的落空也都是正当的:两问之间真有 `INSERT`/`DELETE oa_task`(会签收票、
加签、办结),那份必须作废,不作废就是读旧值。`oa_work` 被 UPDATE 两次那一对已经做掉了(见《留痕与站内信
那两次"整刷"》),顺带把"靠隔壁 flush 路过"这条隐患也清了。
- **详情页那六七次"只是把只读事务收个尾"的往返**。数的是 MySQL 服务端的 `Questions`
计数器(同一台远端库、`OA_SCHEDULER=off`、12 次一组,空白对照组 0 条,说明计数器干净):
| 接口 | 语句 | 真实往返 | 中位耗时 |
| --- | --- | --- | --- |
| `GET /job/{job}` | 7.2 条 | 15.2 次 | 130ms |
| `GET /work/{id}` | 7.0 条 | 16.4 次 | 125ms |
| `GET /task/{id}` | 9.0 条 | 20.1 次 | 180ms |
| `GET /org/tree` | 3.0 条(后来并掉了负责人那一读,见《详情页与部门树》) | 5.8 次 | 126ms |
(这张表数的是 MySQL 服务端的 `Questions`;《详情页与部门树》那节数的是「同一进程交替 A/B、含驱动层收尾往返」,两处的趟数不要横着比。)
| `GET /auth/me` | 2.0 条 | 3.5 次 | 70ms |
差额正好等于这个请求开了几条 Session:一条 Session 借出去,收尾要付一次"结束事务"的
往返,而 `pool_reset` 那一层已经把重复的一刀砍掉了,剩下的是一条都不少。反向验过一次:
把出厂那版"归还时再补一刀 `ROLLBACK`"打开,`/job/{job}` 从 15.2 涨到 21.0、
`/work/{id}` 从 16.4 涨到 25.2,涨的正是 Session 那么多条——这笔账是实的。
能省掉它的只有让只读 Session 跑在 `AUTOCOMMIT` 上(MySQL 那边就没有事务可结束了),
但那会把"同一个 Session 里几条 SELECT 看同一份快照"换成"每条各看一份":详情页主
Session 要读单据、待办、流转日志、表单,中间恰好有人审批,就会拼出一张新旧混着的页面。
这条动的是读一致性口径,不是排队,得单独立项拍板——并发块里那些一次只问一条语句的块
是安全的,主 Session 不安全,所以要逐点决定,不能一把梭。
- **「同步定时任务」那一页的串行读**(`GET /hub/schedule`)。`perf_guard.py --dups` 把它排在第一位:
6 条语句里 4 条在问 `oa_hub_sync_run`,三条还是串着的——上次跑成什么样、最近 30 天跑过哪些、
本周期跑过几次,各问一趟。真并起来最多省一趟("最近一次"那一问不受任何时间窗约束,没法与
另外两问共用一条查询),要并得更狠就得把"本周期从几点算起"这个窗口穿进调度线程与界面共用
的 `full_state`——那是两处必须走同一段代码的地方,为一个管理页的一趟往返动它不值。
- **操作日志 / 同步留痕的保留期**。`oa_operation_log`、`oa_hub_sync_run` 只长不删,
现在几百行看不出问题,等它涨到影响列表页再定保留期。