Testcontainers 默认 MongoDBContainer 启动单节点独立模式，不支持事务所需的副本集，导致 PyMongo 4.0+ 调用 start_session() 或写关注时抛出“Transaction numbers are only allowed on a replica set”错误；须改用 GenericContainer 手动配置 --replSet、等待就绪后执行 rs.initiate()，并在 URI 中显式指定 replicaSet 参数方可启用事务。
能直接用，但必须绕开 MongoDBContainer 的默认单节点限制——它不支持副本集，而 Python 的 pymongo 在启用事务或某些写关注（write concern）时会报错，比如 Transaction numbers are only allowed on a replica set。
为什么默认的 MongoDBContainer 在 Python 测试里大概率失败
Testcontainers 官方提供的 MongoDBContainer 启动的是独立模式（standalone），不是副本集（replica set）。但 pymongo 从 4.0+ 开始，只要代码里用了 with client.start_session() as session: 或显式调用 start_transaction()，底层就会要求连接副本集。否则抛出类似这样的错误：
OperationFailure: Transaction numbers are only allowed on a replica set
这不是你代码写错了，是 MongoDB 实例本身没按事务要求启动。
- 即使你没写事务逻辑，某些 ORM（如
motor配合 FastAPI +asyncio）或测试中启用了w: "majority"写关注，也会触发该检查 -
MongoDBContainer不暴露初始化副本集的钩子，也没提供--replSet参数配置入口 - 别指望靠
container.exec("mongosh --eval 'rs.initiate()'")补救——容器启动太快，MongoDB 还没 ready 就执行，大概率失败
改用 GenericContainer 手动启动带副本集的 MongoDB
绕过官方封装，用 GenericContainer 控制启动参数和初始化时机。关键点有三个：指定 --replSet、等待 MongoDB ready、再执行 rs.initiate()。
- 镜像选
mongo:6.0.2或更高（6.0+对副本集初始化更稳定） - 启动命令加
--replSet rs0 --bind_ip_all，避免绑定 localhost 导致容器内无法自连 - 用
wait_for_logs等到waiting for connections on port 27017再执行初始化，比固定 sleep 更可靠 - 初始化脚本用
mongosh（不是旧版mongo），命令是rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })
示例片段（Python + pytest）：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
from testcontainers.core.container import DockerContainer
from testcontainers.core.waiting_utils import wait_for_logs
<p>mongo = DockerContainer("mongo:6.0.2")
mongo.with_command("--replSet rs0 --bind_ip_all")
mongo.with_exposed_ports(27017)
mongo.start()</p><h1>等待 MongoDB 就绪</h1><p>wait_for_logs(mongo, "waiting for connections on port 27017")</p><h1>初始化副本集</h1><p>mongo.exec(["mongosh", "--eval", "rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'localhost:27017' }] })"])</p><h1>获取宿主机映射端口（注意：不是 27017！）</h1><p>host = mongo.get_container_host_ip()
port = mongo.get_exposed_port(27017)
mongo_uri = f"mongodb://{host}:{port}/?replicaSet=rs0"</p>
Pytest fixture 中复用容器并避免端口冲突
多个测试文件共用一个 MongoDB 容器时，不能每个 pytest 模块都新建容器——Docker 端口会冲突，且启动慢。要用 session 级 fixture，并手动管理生命周期。
- 用
@pytest.fixture(scope="session")创建容器，确保整个测试 session 只启一次 - 不要在 fixture 里调
mongo.stop()—— pytest session 结束后容器自动销毁；提前 stop 可能被其他测试误用 - URI 中必须带
?replicaSet=rs0，否则pymongo不会走副本集协议，事务仍不可用 - 如果测试涉及多线程/协程（如
asyncio+motor），确保每个测试用独立 database/collection，避免数据污染
最易忽略的一点：副本集初始化成功后，rs.status() 返回的 members[].stateStr 必须是 PRIMARY，而不是 STARTUP 或 RECOVERING。如果看到后者，说明初始化没生效，得检查 mongosh 命令是否执行成功、端口是否映射正确、URI 是否带 replicaSet 参数——漏掉任意一个，Python 里的事务都会静默降级或直接报错。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
