# 性能:这个系统的钱花在哪 写给改代码的人。核心只有一句:**这个系统的慢几乎从来不是某条 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` | | 待阅处理带附件 / 归档件补批注 `engine.mark_read` 的 `attachments`、`claim_attachments` 认归档单、`_job_response` 的 `can_comment` | `python3 scripts/check_cc_action_files.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` 只长不删, 现在几百行看不出问题,等它涨到影响列表页再定保留期。