43 · 租户并发闸入 DB
性质:方案 + 落地记录(已落地,2026-10-23)。 一句话:同一租户内同时最多跑几场 run(
tenants.max_concurrent_runs,默认 8)这道闸, 原来在 API 层「数一遍 → 比上限 → 放行」,并发下会超发;现在数与放行在同一笔 PG 事务里, 中间持一把所有副本共享的 DB 锁。 代码落点:yk-tako-eino/internal/runengine/{store.go,scope.go,server.go,product_api.go}。 验收落点:yk-tako-eino/internal/runengine/store_test.go(TestTenantGateConcurrent)、scripts/acceptance/tenant_gate.sh。 归属:doc/42 §4.3 第 1 条(「租户并发闸改成 DB 约束」)——2026-10-22 拍板「不同批做」,本篇就是那一批。
0. 背景与动机(什么场景,谁想要什么)
一个租户(= 一组员工,共用模型供应商账号与机器资源)在 tenants.max_concurrent_runs(默认 8) 上有一道闸:同一租户内同时最多跑几场 run。
- 谁要它:平台。它护的是共享资源——模型供应商的 API 配额与账单、同一批机器的 CPU/内存。 一个成员手滑起了 20 场长跑,账单与机器由全租户承担。
- 谁会撞它:正常工作的租户成员。一个成员占满 8 场,其他人全被挡——这属于 doc/42 §4.3 第 2 条「并发额度该分到成员」,不同批做。
失败方向只有一边重要:放多了(超发)。少放(误拒)只是慢一点。
1. 病灶(不修的具体失败故事)
租户 A 现在有 7 场在跑(上限 8,还差 1 场)。张三和李四在同一秒各点一次发送:
| 时刻 | 张三 | 李四 |
|---|---|---|
| t0 | 数活 run = 7 | 数活 run = 7(张三那笔还没提交,数不到) |
| t0 | 7 < 8 → 放行 | 7 < 8 → 也放行 |
| t1 | 插 run 行 → 活 run 变 8 | 插 run 行 → 活 run 变 9 |
结果:9 场在跑,超了上限。多副本下 3 个副本各放行一次 → 10 场、11 场,理论上没有上限。
为什么这不是小毛病:闸形同虚设——限 8 实际能跑 9+,而超发那部分的账单照样记在租户头上。 更糟的是它没有症状:页面上看不出异常,只是账单的曲线比预期陡。
活体实测(2026-10-23,修前):隔离引擎上把租户上限调成 2,并发打 4 次 POST /api/runs → 4 个 202,4 场同时在跑(上限 2)。不是"负载大了才超",是四发就超。
2. 修前的代码事实
| 位置 | 事实 |
|---|---|
product_api.go overQuota |
数一遍(CountLiveRuns)→ 比上限 → 放行。数与放行是两次独立的事,中间没有任何锁。 |
scope.go CountLiveRuns |
SELECT COUNT(*) FROM runs r JOIN sessions s ... WHERE s.tenant_id=$1 AND r.status='running' AND r.lease_until > now()。纯读,无锁。 |
server.go postRuns |
overQuota 在抢闸之前调用(早退 429)。 |
store.go AcquireRun |
真正插 runs 行的地方(另开一笔 PG 事务)。闸本体 = 会话级部分唯一索引 one_live_run_per_session 冲突 → 409。会话闸在 DB 里是对的;错的是它只管「一场会话」,不管「一个租户」。 |
scope.go trySubagentSlot |
同族的另一道闸:用 Redis INCR(原子)而不是进程内信号量——已经是对的形态。 |
根因一句话:闸在应用层读-判-写,不在数据库里——AGENTS.md「闸放数据库不放进程」那条纪律的最后一个漏网之鱼。
3. 形态选择(三个候选,取舍)
候选 A:槽位唯一索引(字面意义的「插入时占槽」)
runs 加 tenant_id + slot_no 两列,加部分唯一索引 UNIQUE (tenant_id, slot_no) WHERE status='running';抢闸时从 0..max-1 挨个试插, 冲突就换下一个;全冲突 = 满。槽位随 status 翻终态自动释放。
- 好处:「冲突本身就说明满了」字面成立;DB 挡住任何写者;与既有
one_live_run_per_session同族同形。 - 代价:① 要 DDL + 存量行回填(开发库有 running 行,直接建索引会撞);② 僵尸行问题——
status='running'但租约已过的行(进程死了没扫)会占着槽位,而计数口径不数它 → 要额外加 「全租户僵尸清扫」,否则一个崩掉的 run 永久吃掉一格容量;③ 上限 N 仍由应用选槽号时保证。
候选 B:DB 互斥 + 计数(数与放行同一笔事务)—— 定案
在同一笔 AcquireRun 事务里:先拿一把所有副本共享的 DB 锁(锁住这个租户),再数活 run, 再插 runs 行。锁在事务提交/回滚时自动释放。
- 好处:同上限、同副本数下不可能超发;无 DDL、无存量迁移、无计数器漂移;计数口径与修前 逐字相同(僵尸行照旧不算活 → 不误拒);闸的仲裁在 DB,不在进程。
- 代价:锁的取法要挑(见 §4.1);「满」的证据是计数不是索引冲突。
候选 C:SERIALIZABLE + 40001 重试
把抢闸事务提到 SERIALIZABLE,靠 SSI 检出读-判-写冲突,一个事务提交失败后重试。
- 好处:无需任何锁语句;DB 直接判「你俩打架了」。
- 代价:重试会重跑整笔事务,包括最后那步 Redis 写(
runliveStart是 INCR/SET 家族, 重跑可能多记一次);PG 的 SERIALIZABLE 在高并发下失败率不低,闸成了抖动源。
为什么定 B
- 保证等价:A 与 B 在「同上限、同副本数」下的对外行为一致(都不超发),B 的代价面小得多。
- B 没有误拒面:A 的僵尸槽位要额外一套清扫才能不误拒;B 沿用原计数口径。
- B 不动契约字节:满租户的响应还是
429 + 113001 + "这个工作区的额度用完了",前端一行不用改。
选 B 不等于放弃「插入时占槽」:B 仍然是「在 DB 的锁下把数与放行做成一步」, 仲裁者是 DB 的锁(flock 那一族),不是应用层的读-判-写。
4. 落地形态
4.1 互斥锁取哪把
| 取法 | 写法 | 优点 | 缺点 |
|---|---|---|---|
| 顾问锁(定案) | SELECT pg_advisory_xact_lock(hashtextextended($1, 0)) |
事务级、随提交/回滚自动释放(进程死了不留残留);不依赖任何表行存在;不挡租户改名字/归档 | 要知道它是 PG 能力;调试要在 pg_locks 里看 advisory lock |
| 租户行锁 | SELECT max_concurrent_runs FROM tenants WHERE id=$1 FOR UPDATE |
看得见、与上限同一行 | 要求 tenants 行存在(单测里的 t_test 就没有);会挡 RenameTenant/ArchiveTenant |
定案用顾问锁:闸的可靠性不能挂在「某张表某行一定在」上。 哈希撞了只是两个租户互相多等一下,方向是安全的(绝不会放多)。
4.2 三条语句,顺序不能换
① SELECT pg_advisory_xact_lock(hashtextextended($1,0)) -- 拿互斥
② SELECT COUNT(*) FROM runs r JOIN sessions s ... -- 数活 run
③ INSERT INTO runs (...) -- 放行
为什么 ② 不能和 ① 并成一条语句:PG 的 READ COMMITTED 下,一条语句只拿一次快照。 若 ①② 合成一条,快照在等锁之前就定了——等 A 提交后我们再数,仍然看不见 A 那行 → 少数 → 照超发。分两条,② 在 ① 拿到锁之后才开始,取到新快照,看得见已提交的那行。
锁序:会话行锁(store.go AcquireRun 开头)→ 租户闸锁 → 插 runs。 租户闸锁只在这一个地方取,没有反向取法,不构成死锁环。
计数口径:与读侧 CountLiveRuns 逐字相同(status='running' AND lease_until > now())—— 两处共用一个 countLiveRuns(db, tenantID) 函数,免得读侧说 7、闸里说 8。
上限口径:与 TenantQuota 相同(tenants.max_concurrent_runs,缺行或 ≤0 → 8)。
4.3 错误映射(字节不变)
| 情形 | HTTP | code | message |
|---|---|---|---|
| 租户并发已满(新增的 DB 闸) | 429 | 113001 | 这个工作区的额度用完了 |
| 日 token 配额用完(原有) | 429 | 113001 | 这个工作区的额度用完了 |
| 同一会话已有活 run | 409 | 112101 | 这场会话正在跑,等它跑完再发 |
前两行仍共用同一个码与同一句文案——把两者分开是 doc/42 §4.3 第 2 条(并发额度分成员 + 拆码)的事, 不同批做,本篇不动。
4.4 overQuota 里那段怎么处置
保留,但降级为「快速失败提示」:它在抢闸前跑,能在 media 落盘、MCP 连接之前就把满租户挡掉。 它只能拒、不能放(数到 ≥ 上限就 429),所以它不构成超发路径;闸在 AcquireRun 里。 代码注释写明了这一句,否则下一个读代码的人会以为闸还在那里。
5. 数据与迁移
无 DDL、无存量迁移:tenants.max_concurrent_runs 已在用;runs 表不动; 计数口径不动(只是被搬到事务内、加了锁)。
6. 验收
| 层 | 落点 | 断什么 |
|---|---|---|
| 存储层回归(PG 真跑) | store_test.go TestTenantGateConcurrent |
8 个 goroutine 同抢一个上限 2 的租户 → 恰好 2 放行、6 个 errTenantFull、库里活 run 恰好 2、被拒的请求零痕迹。把闸摘掉这条立刻红(放行 8)——已实测。 |
| 活体(HTTP 字节) | scripts/acceptance/tenant_gate.sh |
上限 2 的租户并发打 4 次 POST /api/runs → 恰好 2 个 202、2 个 429,429 的响应体逐字 {"code":113001,"message":"这个工作区的额度用完了","data":null};库里 run 行数与会话行数都 = 上限。 |
| 快闸 | contract_test.go |
本篇不改契约字节,快闸无新增项(业务码值本来就在码表里)。 |
改前 vs 改后的活体对照(同一发并发四打,上限 2):
| 修前 | 修后 | |
|---|---|---|
| 响应 | 4 × 202 |
2 × 202 + 2 × 429 |
| 库里 run 行 | 4 | 2 |
| 当时活着的 run | 4(上限 2) | 2 |
7. 明确不做(本篇)
- 并发额度分成员 / 拆
codeQuota(doc/42 §4.3 第 2 条):不同批。 - 日 token 配额闸的原子化:
overQuota里那个used >= daily也是读-判-写,但它的语义是 「今天花超了」而不是「同时跑几场」,额度按实际 token 结算,闸的口径另有设计讨论;本篇不动, 只在 §4.3 表里记下它今天与并发满共用同一个码。 - 闸的可见性:不加「当前活 run 数 / 上限」的查询接口(
GET /api/tenant/usage已有)。
8. 演进记录
- 2026-10-23 立项并落地:用户指出
product_api.go:26-57的并发闸是「读-判-写」竞态 (数一遍与放行是两次独立的事,中间没有锁),要求改成 DB 闸。事实核对基于当日实读代码:product_api.go(租户闸与配额文案)、scope.go(CountLiveRuns口径、子代理槽已用 Redis INCR)、server.go(提示在抢闸前、真正插行在AcquireRun)、store.go(抢闸段;INSERT INTO runs唯一入口;one_live_run_per_session)、pgstore.go(Run模型与部分唯一索引)、identity_store.go(Tenant模型、注册即建租户行)。形态候选见 §3,用户 2026-10-23 拍候选 B(DB 互斥 + 计数), 锁取法选顾问锁。同日落地:lockTenantGate+ 错误映射 +overQuota降级为提示; 活体实测修前 4×202、修后 2×202+2×429;存储层回归用例入库(摘掉闸即红);活体验收脚本入库。 文档同批更新 doc/README.md §1、doc/16 §2c 与 §6、doc/42 §4.3、19v6-03。