Python版testcontainers是社区独立实现，不依赖JVM或Java代码，通过docker-py直连Docker API，轻量快速但不兼容Java版特性。
为什么 testcontainers 的 Python 版本不是“官方原生”实现
Python 版本的 testcontainers 是社区主导的独立实现，和 Java 版本没有共享代码或运行时。它不调用 Java 的 testcontainers-core，也不依赖 JVM —— 它直接通过 Docker API（经由 docker-py）管理容器生命周期。
这意味着你不能指望它支持 Java 版本里那些深度集成 Spring Boot 或 TestNG 的特性；反过来，它更轻、启动更快，也更容易嵌入到纯 Python 测试流程中。
- 它用的是
docker.from_env()连接本地 Docker daemon，不是 HTTP 代理或远程 socket 转发 - 所有容器启动逻辑都在 Python 层完成，比如镜像拉取、端口绑定、健康检查轮询都自己实现
- 不兼容 Java 版本的
GenericContainer().withClasspathResourceMapping()这类语义 —— Python 没有 classpath 概念
GenericContainer 启动失败但没报错？先看日志和健康检查配置
常见现象是测试卡住几秒后超时，或者容器已退出但 get_container_host_ip() 返回空。根本原因往往是容器启动了但没通过健康检查，而默认健康检查策略又太激进。
- 默认启用
wait_for_container_ready=True，且会尝试对容器暴露的端口做 TCP 连通性探测（非 HTTP） - 如果服务监听在
127.0.0.1而不是0.0.0.0，TCP 探测必然失败 —— 容器内 localhost ≠ 宿主机 localhost - 建议显式关闭自动等待：
container = GenericContainer("redis:7").with_exposed_ports(6379).start()，然后手动用container.get_container_host_ip()+container.get_exposed_port(6379)连接并验证 - 若必须用健康检查，优先选
with_healthcheck()配置 shell 命令（如redis-cli ping），比端口探测更可靠
用 PostgreSQLContainer 时用户名密码不生效？注意环境变量拼写和初始化时机
很多用户发现设置了 POSTGRES_USER 和 POSTGRES_PASSWORD，但连接时仍被拒绝，或者连上了却无法创建数据库 —— 其实是 PostgreSQL 容器只在首次初始化时读取这些变量，后续重启不会覆盖已有数据目录。
立即学习“Python免费学习笔记（深入）”；
- 确保容器是全新启动（无残留 volume），否则旧数据目录里的
pg_hba.conf和postgres用户密码不会更新 - 环境变量名必须全大写且严格匹配：是
POSTGRES_USER，不是user或PGUSER - 如果需要自定义初始化 SQL，用
with_volume_mapping()挂载/docker-entrypoint-initdb.d/目录，脚本后缀必须是.sh或.sql - 连接时别用
localhost—— 在容器网络里要用container.get_container_host_ip()获取宿主机网关地址，或直接用容器名（如启用了自定义 network）
CI 环境下 testcontainers 启动慢甚至失败？Docker 权限和资源限制最常被忽略
本地跑得好，CI 上频繁超时或 PermissionError，基本可以锁定两个点：Docker socket 访问权限不足，或容器被平台强制 kill（OOM / CPU quota 超限）。
- GitHub Actions 默认不挂载
/var/run/docker.sock，必须显式加services块或用docker/setup-qemu-action启动 dockerd - GitLab CI 需确认 runner 配置了
docker:dindservice，且 job 中设置DOCKER_HOST=tcp://docker:2375 - 容器启动时默认不限制内存，但某些 CI 平台（如 CircleCI）对单个 job 内存上限很严，PostgreSQL + Redis 一起跑很容易触发 OOM —— 用
with_env({"POSTGRES_SHARED_BUFFERS": "64MB"})主动降配 - 避免在
setUp中反复创建/销毁容器，复用static container实例，否则每次都会拉镜像+初始化，CI 时间翻倍
真正麻烦的从来不是语法怎么写，而是容器什么时候启动、在哪种网络里可见、有没有被平台静默回收 —— 这些细节不会报错，只会让测试偶尔失败，然后花半天怀疑是不是代码问题。
