并行跑测试这件事,总让人觉得早已搞定,直到某一天它突然不灵了。
有很长一段时间,我们的后端测试环境看上去都很健康:有 pytest-xdist,有模块化的 fixture、Factory Boy 和结构清晰的 conftest.py,平台库与租户库彼此分离,还有一个会自动加载测试环境的 ~/run_tests 入口。一名工程师单独跑一小部分测试,又快又稳;开几个 worker 并行,也是家常便饭。
后来,我们的工作方式变了。
我们开始在更多场合同时跑更多测试:多个 tmux 窗格、后台校验任务、依赖大量 fixture 的长套件,最后是多个 AI 智能体在几秒之内先后向同一台数据库主机发起测试。一个一直侥幸没出事的结构性问题就此暴露出来:即便用上了 xdist,两次相互独立的 pytest 调用仍可能撞上同一批 PostgreSQL schema,结果是 LockNotAvailable、语句超时,更糟的是数据悄无声息地写进共享的 public。
解决办法不是“再把超时调大一点”,而是把测试环境当作共享基础设施来对待:每次调用独立的命名空间、fail-closed(拿不准就不动)的清理策略、确定性的连接标记,外加几个不起眼却比主线改动更关键的 bug 修复。
本文讲三件事:哪里出了问题,为什么光靠 xdist 解决不了,以及我们最终用上的具体机制。
为什么光有 xdist 不够
pytest-xdist 提供的是单次调用内部的 worker 并行。这和让多次独立调用在同一台数据库主机上安全共存,是两码事。
我们最初的隔离方式是每个 worker 一个 schema:
test_gw0
test_gw1
test_gw2
这种方式一直相安无事,直到两次完全独立的 ~/run_tests 调用同时拉起了 gw0。这时两次运行都会去删除、重建、迁移并填充同一个物理 schema,结果就是结构性的锁争用。在看出规律之前,它很像是测试偶发不稳定。
多租户 SaaS 的测试环境通常至少涉及两个数据库:
- 一个平台数据库,存放用户、组织、角色和全局控制面状态
- 一个或多个租户数据库,存放每个客户实际使用的运营数据
测试一旦加入多租户隔离用例或额外的租户库,“按 worker 名称隔离”就变成了“只有别的调用不来添乱时才算隔离”。对人数不多的人类团队来说,这只是偶尔一次的不稳定;而对一群并发发起测试、还会相互继承 shell 状态的 AI 智能体来说,这就是常态。
教训来得不轻,道理却很简单:xdist 提供的是单次调用内部的 worker 并行,并不会自动让多次独立调用在同一台数据库主机上安全共存。
我们做了哪些改动
现在,每次 pytest 调用都会分配一个命名空间令牌,每个 worker 用 namespace + worker_id 拼出自己的 schema:
test_{namespace}_{worker_id}
~/run_tests 生成的命名空间令牌长这样:
p18234t1745178234r3af93d71
格式是 p<PID>t<EPOCH>r<HEX>,后缀含 32 位熵,取自 /dev/urandom。于是,两次并发调用的 schema 是这样的:
test_p18234t1745178234r3af93d71_gw0
test_p18234t1745178234r3af93d71_gw1
test_p20491t1745178241r9c12d4fe_gw0
test_p20491t1745178241r9c12d4fe_gw1
跨调用冲突从结构上就不可能再发生。真正值得一讲的,是系统里那些必须学会遵守这条规则的部分,以及途中踩到的两个隐蔽 bug。
运行器负责生成并校验命名空间
默认情况下,~/run_tests 每次调用都会生成新令牌,即便调用它的 shell 里还留着上次运行导出的 HONEY_TEST_SCHEMA_NAMESPACE。这一步专防残留的旧导出值,很有必要:否则,某次调试会话遗留的变量,可能让下一次“正常”运行悄无声息地又撞回同一个命名空间。
可以使用限定范围的调试覆盖值(HONEY_TEST_SCHEMA_NAMESPACE_FORCE=mydebug),但限制很严:只能是小写字母和数字,不能有下划线或连字符,最长 32 个字符。运行器在 shell 层就会完成校验,而且是在这个值进入任何报告文件路径或环境变量导出之前。
conftest.py 兜住直接调用 pytest 的情况
pytest 并不只经由 bin/run_tests 调用。为了让这套设计在直接调用 pytest 时同样成立,tests/conftest.py 会:
- 保留运行器已经导出的命名空间
- 如果没有,就生成一个
- 借助
pytest_configure_node钩子(node.workerinput["schema_namespace"]),把控制进程的命名空间传给每个 xdist worker 子进程
少了这一步传递,每个 xdist worker 都会各自生成命名空间,单次调用内部又会回到 worker 之间相互冲突的老路。
隐蔽 bug 之一:search_path 悄悄回落
这是影响最大的一个 bug,而且任何测试都抓不到它。
在 PostgreSQL 中,即使 foo 不存在,SET LOCAL search_path TO foo, public 也不会报错,而是悄悄回落到 public。所以,如果引擎初始化已经改用带命名空间的 schema,而某个 session 作用域的 seeder 还在拼旧名字:
# 引擎现在使用 test_<namespace>_gw0(正确)
# seeder 仍沿用旧写法:
worker_id = os.getenv("PYTEST_XDIST_WORKER", "gw0")
schema = f"test_{worker_id}" # "test_gw0":这个 schema 已经不存在了
seed_sess.execute(text(f"SET LOCAL search_path TO {schema}, public"))
seed_sess.add(OperationType(...)) # 数据最终落进 `public`
seed_sess.commit() # 跨调用污染,而且没有任何报错
填充的数据行落进了共享的 public,并发调用开始互相看到对方的数据。最初的 LockNotAvailable 症状消失了,同一个问题却换了一种隐蔽得多的形式,在暗处继续发作。
现在,凡是涉及 search_path 的 fixture、辅助函数和 seeder,一律调用同一个共享的 worker_schema() 辅助函数来拼 schema 名,引擎和 seeder 用的 schema 再也不可能出现分歧。我们把这一点作为结构性不变量写进了设计文档。
隐蔽 bug 之二:一个正则表达式让 DDL 并行度悄悄减半
schema 初始化用一个 2 槽位的 DDL 信号量,限制同一时刻打到 Postgres 上的并发 CREATE TABLE 数量。槽位按 worker 编号分配:
# 原来的写法
slot_match = re.search(r"(\d+)", schema)
slot = int(slot_match.group(1)) % 2 if slot_match else 0
schema 名为 test_gw0 或 test_gw1 时,这段代码没有问题。加上命名空间后,schema 变成了 test_p12345t1745178234r3af93d71_gw0,re.search(r"(\d+)", ...) 匹配到的是第一段数字,也就是 PID。同一次调用的所有 worker 都得到 12345 % 2 = 1,双通道信号量退化成单通道,既不报错,也没有任何告警日志。
修复方法:锚定 worker 后缀。
def ddl_slot(schema: str, slot_count: int = 2) -> int:
m = re.search(r"_gw(\d+)(?:_|$)", schema)
return int(m.group(1)) % slot_count if m else 0
2 个槽位这个数字本身来自实测。我们有 220 多张租户表,每次 metadata.create_all() 大约要获取 4,000 个系统目录锁。在默认的 max_locks_per_transaction = 64 下,PostgreSQL 的共享锁表约有 19,200 个槽位。两个并发 DDL 事务的峰值接近 8,000 个锁,余量充足;四个并发时峰值超过 16,000,在 -n 22 下出现了 out of shared memory 错误。
活跃命名空间检测:取所有测试库的并集
过期 schema 的清理属于尽力而为,在 pytest 启动前运行。它要删掉崩溃运行遗留的 schema,但绝不能误删仍有活跃调用在用的 schema。
第一直觉是在即将清理的库里查 pg_stat_activity,但这是错的。一个活跃调用此刻可能只在四个已配置测试库中的一个里持有连接。如果逐库检查,就可能把这个活跃命名空间在另外三个库里的 schema 删掉,在更窄的时间窗口里重现最初的竞态。
因此,清理程序在清理任何一个库之前,会先从所有能连上的库中收集活跃集合:
active_namespaces, errors = collect_active_namespaces(all_urls)
active_detection_complete = not errors
for url in all_urls:
sweep_one(
url,
active_namespaces=active_namespaces,
active_detection_complete=active_detection_complete,
)
收集期间只要有一个库连不上(身份验证失败、网络超时、主机黑洞),active_detection_complete 就会变为 False,本次清理一个 schema 也不删。待清理的候选项会带上 reason: active_detection_incomplete 记录下来,这个 fail-closed 决策在 JSON 输出中一目了然。我们还给建立连接设了 5 秒的 connect_timeout,免得某台黑洞主机在这段安全逻辑运行之前,就把 pytest 启动前的清理卡死。
一个事务只删一个 schema
第一版清理程序在一个事务里删除所有过期 schema。积压不多时还行,可遇到一次真实积压(56 个过期 schema,每个含 220 多张租户表),DROP SCHEMA ... CASCADE 累积的系统目录锁直接撑爆了 PostgreSQL 的共享锁表:
psycopg2.errors.OutOfMemory: out of shared memory
更糟的是,这次失败让整个事务中止,剩下的积压原封不动,留给下一次清理以更高的代价再撞一次。
修复方法:先在一个只读的 engine.connect() 块里完成发现,再让每次删除各自在一个短小的 engine.begin() 事务中执行,并设置 SET LOCAL lock_timeout = '5s' 和 SET LOCAL statement_timeout = '30s'。删除失败的 schema 记入该库的 failed 列表,不会中止这个库其余的清理。按新方案,这一轮干净利落地清掉了 56 个 schema 的积压:删除 56 个,失败 0 个,没有出现 OOM。
给连接打上标签,锁问题才能追溯
每个测试连接都带有标签:
application_name = pytest_{worker_id}_{namespace}[_{suffix}]
示例:
pytest_gw0_p18234t1745178234r3af93d71
pytest_gw0_p18234t1745178234r3af93d71_concurrency
临时命名空间之所以禁用下划线,是出于结构上的需要。pytest_gw0_my_debug_concurrency 既可以解析为 (my_debug, concurrency),也可以解析为 (my_debug_concurrency, no suffix),清理程序的活跃命名空间检测器无从判断。临时令牌禁用下划线,后缀边界就不会有歧义。
bin/diagnose_test_locks.py 会在所有已配置的测试库上查询 pg_blocking_pids(),把阻塞双方都打印出来:
SELECT
blocked.pid AS blocked_pid,
blocked.application_name AS blocked_app,
blocked.wait_event,
blocked.query AS blocked_query,
blocker.pid AS blocker_pid,
blocker.application_name AS blocker_app,
blocker.query AS blocker_query
FROM pg_stat_activity blocked
JOIN LATERAL unnest(pg_blocking_pids(blocked.pid)) AS blockers(pid) ON true
JOIN pg_stat_activity blocker ON blocker.pid = blockers.pid;
每个连接都在 application_name 里带着自己的 worker 和命名空间,因此一次 LockNotAvailable 现在可以直接追溯到具体的某次调用,不必再从堆栈跟踪里去推测。
测试报告也按命名空间区分
这是个小细节,却很关键。~/run_tests 把 JSON 报告写到 /tmp/pytest_reports/<timestamp>_<namespace>.json,把收集到的 nodeid 临时文件写到 .collected_nodeids_<namespace>.txt。以前,同一秒启动的两次并发调用会互相覆盖对方留下的证据。读取端(~/test_report)按 *.json 通配匹配,所以给文件名加上命名空间,不会影响任何下游环节。
新旧设计对比
| 关注点 | 早期做法 | 现行做法 |
|---|---|---|
| Worker schema 命名 | test_gw0 | test_{namespace}_{worker} |
| 跨调用安全 | 尽力而为 | 结构性隔离 |
| 报告文件 | 共用时间戳路径 | 带命名空间的路径 |
| 活跃测试检测 | 逐库查看,可能只看到局部 | 取所有已配置库的并集 |
| 清理策略 | 情况不明时也可能误删 | 检测不完整时 fail-closed |
| Schema 删除方式 | 一个事务里删多个 | 一个事务只删一个 schema |
| DDL 槽位推导 | 取 schema 名中的第一段数字 | 锚定 _gwN 后缀 |
search_path 拼接 | 各调用点手工拼接 | 统一的 worker_schema() 辅助函数 |
| 锁问题排查 | 从失败现象推测 | pg_blocking_pids() 加 application_name 标签 |
我们有意没做的事
下面是我们考虑过、最终放弃的几种方案,供面临同样抉择的人参考:
- 每次调用一个独立数据库(
CREATE DATABASE … DROP DATABASE):需要CREATEDB权限,每次调用都要重跑 Alembic,每次启动还要多花 4 到 8 秒 × N 个数据库。太重了。 - 到处调大
lock_timeout:不过是又贴了一块创可贴。故障表现从 15 秒报错变成 120 秒等待,竞态依旧没有解决。 - 用 Postgres advisory lock 替代文件系统的 fcntl 锁:它取代不了命名空间隔离。将来如果出现多主机的 CI runner,这是合理的后续改进;在本地 WSL 工作流里不值得做。
- 靠纪律让调用排队:很脆弱。而且问题刚出现时,这条规矩在实践中就已经屡被打破。
为什么这对 AI 辅助开发团队更重要
人类团队只是偶尔碰上这类冲突,智能体集群则三天两头就会碰上:
- 多个智能体可能在几秒之内相继启动测试
- 它们跑的测试目标往往相近
- 它们可能继承了大家早已忘掉的 shell 状态
- 它们更容易把过期清理和报告收集推到极限
原本看似偶发的边缘情况,成了日常运行中的常态。测试环境必须像共享基础设施一样运作:命名空间、清理规则、诊断工具和安全默认值,都要在无人居中协调的情况下依然成立。
结语
支撑这项工作的思路,在产品里同样一以贯之:显式隔离状态;一旦失去确定性,就 fail-closed;给每项工作打上标签,事后可以追溯;宁要结构性保证,也不靠调大超时来打补丁。EquatorOps 平台和引擎架构背后,正是这样的取向。
如果您正在构建真正面对并发的运营软件,要记住的不是“用命名空间”,而是:一旦相互独立的运行可能在共享状态上发生冲突,worker 级并行就不够了;而一旦 AI 智能体进入工程闭环,这类冲突就不再罕见。
如果想聊聊这套架构背后面向开发者的能力,请访问 /developers。