结论：90%的authenticationfailed错误源于authsource配置错误，它必须等于用户创建所在的数据库名（如admin或myapp），而非目标业务库；未指定时默认为admin，易导致认证失败。

直接说结论：90% 的 OperationFailure: authentication failed 错误，不是密码输错了，而是 authSource 没配对 —— 它必须等于用户实际创建所在的数据库名，而不是你打算操作的业务库。

authSource 填错是最常见的根本原因

很多人凭直觉把 authSource 设成自己要访问的库（比如 myapp），但 MongoDB 认证只看“用户在哪建的”。查证方式很简单：进 mongosh，执行 use admin → db.getUsers()，看每个用户的 db 字段值。

• 用户在 admin 库创建 → authSource="admin"（MongoDB Atlas 强制如此）
• 用户在 myapp 库创建 → authSource="myapp"，哪怕你要连的是 otherdb
• 连接字符串里没写 authSource 参数 → 默认用 admin，容易失败

示例正确写法：
mongodb://user:pass@localhost:27017/myapp?authSource=myapp

SCRAM-SHA-256 认证机制不匹配

新版本 MongoDB 默认启用 SCRAM-SHA-256，但旧版 PyMongo（SCRAM-SHA-1，导致握手失败。错误现象是连接不报错，但首次操作（如 list_collection_names()）才抛出认证失败。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 显式指定机制：authMechanism=SCRAM-SHA-256（注意大小写）
• 完整 URI 示例：mongodb://user:pass@localhost:27017/?authSource=admin&authMechanism=SCRAM-SHA-256
• PyMongo ≥3.12 才原生支持 SHA-256；若用旧版，要么升级，要么服务端降级机制（不推荐）

密码含特殊字符未 URL 编码

密码里有 @、/、:、+ 等字符时，URI 解析会提前截断。例如密码是 pa@ss/w+rd，不编码就会被当成 host 或 port 的一部分。

• 用 Python 标准库编码：from urllib.parse import quote_plus → quote_plus("pa@ss/w+rd") 得到 pa%40ss%2Fw%2Brd
• 拼进 URI：mongodb://user:pa%40ss%2Fw%2Brd@localhost:27017/...
• 别依赖 PyMongo 自动处理 —— 它在某些版本和场景下不可靠

Atlas 用户状态异常或权限未生效

即使所有配置都对，MongoDB Atlas 有时会卡住旧用户的状态（尤其改过密码或角色后）。现象是：控制台显示用户存在、权限已分配，但连接仍报 bad auth : authentication failed。

• 最有效解法：在 Atlas 控制台删掉该用户，重新创建一个同名、同角色、同密码的新用户
• 创建后等待 1–2 分钟再试，避免缓存延迟
• 确认用户角色包含 readWrite 或对应业务库的权限，仅 dbAdmin 不够用

真正棘手的点往往不在代码里，而在用户账户本身的状态一致性 —— 它不报错，也不提示，就静默拒绝。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！