tako 文档 GitHub

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。

失败方向只有一边重要:放多了(超发)。少放(误拒)只是慢一点。

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 翻终态自动释放。

候选 B:DB 互斥 + 计数(数与放行同一笔事务)—— 定案

在同一笔 AcquireRun 事务里:先拿一把所有副本共享的 DB 锁(锁住这个租户),再数活 run, 再插 runs 行。锁在事务提交/回滚时自动释放。

候选 C:SERIALIZABLE + 40001 重试

把抢闸事务提到 SERIALIZABLE,靠 SSI 检出读-判-写冲突,一个事务提交失败后重试。

为什么定 B

  1. 保证等价:A 与 B 在「同上限、同副本数」下的对外行为一致(都不超发),B 的代价面小得多。
  2. B 没有误拒面:A 的僵尸槽位要额外一套清扫才能不误拒;B 沿用原计数口径。
  3. 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. 明确不做(本篇)

8. 演进记录