ConnectionTimeoutError 或 socket.timeout 表明 PyMongo 未在规定时间内收到 MongoDB 响应，前者是 TCP 连接失败，后者是连接成功但读响应超时；需分层排查网络、DNS、TLS、副本集配置及连接池等问题。
ConnectionTimeoutError 或 socket.timeout 是什么信号
这不是代码写错了，而是 PyMongo 在规定时间内没等到 MongoDB 的响应。常见于网络不通、服务没起来、防火墙拦截，或者 URI 里漏了关键参数导致连接逻辑卡死。
典型错误信息长这样：ConnectionTimeoutError: timed out 或 socket.timeout: The read operation timed out。注意区分：前者是连不上服务器（TCP 层失败），后者是连上了但读响应超时（应用层卡住）。
- 先用
ping和telnet your-mongo-host 27017（或nc -zv your-mongo-host 27017）确认基础连通性 - 如果本地能连但 Docker/云环境连不上，大概率是容器网络配置或安全组没放行
27017端口 - 云数据库（如 Atlas、阿里云 MongoDB）必须检查白名单——不是本机 IP，而是你运行 Python 的机器出口 IP
URI 中 timeoutMS 和 connectTimeoutMS 到底怎么设
PyMongo 默认的 connectTimeoutMS=20000（20 秒）和 socketTimeoutMS=30000（30 秒）对开发环境够用，但线上高延迟链路或调试阶段容易误判。关键是这两个参数不能只调大，得按用途分开控制。
-
connectTimeoutMS控制“建立 TCP 连接”的最大等待时间，设太小会把慢网误判为宕机；设太大则故障发现滞后。建议生产环境设为5000～10000 -
socketTimeoutMS控制“一次请求读取响应”的超时，影响单次查询，不建议盲目调大，否则慢查询会拖垮整个连接池 - 务必显式传参，别依赖默认值：
mongodb://localhost:27017/?connectTimeoutMS=5000&socketTimeoutMS=10000 - 如果用的是副本集，还要加
serverSelectionTimeoutMS（默认 30 秒），它控制选主节点的总耗时，常被忽略
为什么加了 timeout 参数还是超时
因为 PyMongo 的超时机制分层生效，URI 参数只是其中一环。真正卡住的地方往往在 DNS 解析、SSL 握手、或连接池复用逻辑上。
立即学习“Python免费学习笔记（深入）”；
- DNS 解析慢？加
tlsAllowInvalidCertificates=true（仅测试）或改用 IP 地址直连，避开 DNS 查询 - 用 TLS/SSL 连云服务但证书校验失败？加上
tls=true&tlsAllowInvalidCertificates=true快速验证是否 SSL 导致阻塞（正式环境必须配好 CA） - 连接池满且所有连接都在忙？检查是否忘了
client.close()，或并发数远超maxPoolSize（默认 100）。用client.options.pool_options.max_pool_size查当前值 - 副本集配置了不存在的 host？PyMongo 会逐个尝试，每个都耗尽
connectTimeoutMS，总耗时可能达数分钟
本地能连、部署后连不上：Docker 和 Kubernetes 常见陷阱
容器内 DNS 解析、host 网络模式、服务发现方式，都会让 URI 表面正确实则失效。
- Docker Compose 里用
localhost指向宿主机？错。容器里localhost是自己，应该用服务名（如mongodb）或host.docker.internal（Mac/Win） - K8s 中硬编码
mongo-service:27017却没等 Service 就绪？加 readiness probe 或启动脚本里用nc -z mongo-service 27017等几秒再启 Python - 用了
authSource=admin但用户不在 admin 库？报错可能是超时而非认证失败，因为 PyMongo 先连 admin 再切库，连不上 admin 就一直卡 - 镜像里没装 ca-certificates？TLS 连接会 hang 住，加
RUN apt-get update && apt-get install -y ca-certificates
client = MongoClient(...) 调用里。排查时得一层层剥开，而不是盯着一个 timeoutMS 反复调大。 
