1. 这个报错到底在说什么
Exception authenticating MongoCredential这个报错，几乎每个用 Spring Boot 连 MongoDB 的人都会撞上一次。它的字面意思是“认证 MongoCredential 时发生异常”，但真正让人头疼的是——它只告诉你认证失败了，却不告诉你为什么失败。密码错了？用户名不对？认证库选错了？还是连接串格式有问题？全靠自己排查。
我先把结论放在前面：这个报错的本质是MongoDB 服务端拒绝了客户端提交的认证凭据。Spring Boot 通过spring-boot-starter-data-mongodb自动装配MongoClient，底层走的是 MongoDB 官方 Java Driver，认证流程由 Driver 完成。一旦 Driver 提交的MongoCredential与服务端存储的用户信息不匹配，就会抛出这个异常。
它通常长这样：
org.springframework.data.mongodb.UncategorizedMongoDbException: Exception authenticating MongoCredential{mechanism=SCRAM-SHA-1, userName='admin', source='admin', password=<hidden>, mechanismProperties=<hidden>}注意看括号里的信息，这里藏着排查的关键线索：mechanism、userName、source三个字段，基本决定了认证能不能过。很多人只盯着“密码是不是错了”，结果绕了一大圈才发现是source（认证数据库）填错了。
这篇文章适合谁看？只要你在 Spring Boot 项目里用过 MongoDB，不管你是刚接触的新手，还是被这个报错卡了半天的老手，都能从下面找到可复现的排查路径。我会把认证原理、配置写法、排查步骤、常见坑全部拆开讲，尽量让你下次遇到同类问题时能五分钟定位。
2. 先搞懂 MongoDB 的认证机制
2.1 SCRAM 认证是怎么跑起来的
MongoDB 从 3.0 开始默认使用SCRAM（Salted Challenge Response Authentication Mechanism）作为认证机制，具体分SCRAM-SHA-1和SCRAM-SHA-256两个版本。Spring Boot 底层用的 Java Driver 默认会尝试协商，但如果你手动指定了 mechanism，就可能出现版本不匹配。
SCRAM 的认证过程简单说分四步：
- 客户端发送用户名和一个随机数（client nonce）
- 服务端返回盐值（salt）、迭代次数（iteration count）和一个服务端随机数
- 客户端用密码+盐值计算出 proof，发回服务端
- 服务端校验 proof，通过则认证成功
这个流程里，密码本身不会明文传输，但客户端和服务端必须对“用哪个哈希算法、迭代多少次”达成一致。如果服务端用户是用SCRAM-SHA-256创建的，而客户端只支持SCRAM-SHA-1，认证就会失败，报的就是这个异常。
2.2 认证库（authSource）为什么这么关键
MongoDB 的用户是挂在某个数据库下的，这个数据库叫认证库，对应连接串里的authSource参数。很多人以为用户是全局的，其实不是。
举个例子：你在admin库里创建了用户appUser，那这个用户的认证库就是admin。连接时必须告诉 Driver “去 admin 库认证这个用户”，否则 Driver 默认会去你要连的业务库（比如mydb）里找这个用户，找不到自然认证失败。
这就是为什么同一个用户名密码，用命令行能连上，用 Spring Boot 却报Exception authenticating MongoCredential——大概率是authSource没配对。
2.3 Spring Boot 自动装配做了什么
Spring Boot 的MongoAutoConfiguration会读取spring.data.mongodb.uri或分散的host/port/username/password/database配置，然后构建MongoClient。如果你用的是 URI 方式，Driver 会自己解析authSource；如果你用的是分散配置方式，默认 authSource 等于 database，这一点极其容易踩坑。
# 分散配置方式，authSource 默认等于 database spring: data: mongodb: host: 127.0.0.1 port: 27017 username: appUser password: pass123 database: mydb # 如果用户建在 admin 库，这里必须显式指定 authentication-database: admin注意最后那行authentication-database，它就是authSource的 Spring Boot 配置项。少了它，Driver 会去mydb里认证appUser，直接失败。
3. 逐项排查：把报错拆成可验证的小问题
3.1 第一步：确认用户到底建在哪个库
排查任何认证问题，第一步永远是回到数据库本身确认事实。用命令行连上 MongoDB（本地或容器内都行），执行：
// 切换到 admin 库 use admin // 查看所有用户 db.system.users.find({}, {user: 1, db: 1, mechanisms: 1})输出里每个用户都有user、db、mechanisms三个关键字段。db就是认证库，mechanisms是这个用户支持的认证机制。把这两个值记下来，后面配置要用。
提示：如果
db.system.users查不到你预期的用户，说明用户根本没建成功，或者建在了别的库。先解决这个，再谈连接。
3.2 第二步：核对连接串的每个字段
Spring Boot 支持两种配置方式，URI 方式和分散方式。URI 方式更直观，推荐优先用：
spring: data: mongodb: uri: mongodb://appUser:pass123@127.0.0.1:27017/mydb?authSource=admin&authMechanism=SCRAM-SHA-256拆开看这个 URI 的每个部分：
| 部分 | 值 | 说明 |
|---|---|---|
| 协议 | mongodb:// | 标准连接协议 |
| 用户名 | appUser | 必须和数据库里一致 |
| 密码 | pass123 | 特殊字符需 URL 编码 |
| 主机端口 | 127.0.0.1:27017 | 按实际填 |
| 业务库 | mydb | 连接后默认操作的库 |
| authSource | admin | 认证库，必须和用户所在库一致 |
| authMechanism | SCRAM-SHA-256 | 按用户支持的机制填 |
这里有两个高频坑：密码里的特殊字符必须 URL 编码（比如@要写成%40，#要写成%23），authSource 必须和用户的 db 字段一致。我见过太多次密码里带@导致 URI 解析错位，最后报认证失败。
3.3 第三步：验证认证机制是否匹配
如果authSource确认没问题，还是报错，就要看认证机制了。MongoDB 4.0 之后默认用SCRAM-SHA-256，但有些老用户是用SCRAM-SHA-1创建的。Driver 默认会协商，但如果你在 URI 里硬写了authMechanism=SCRAM-SHA-1，而用户只支持 256，就会失败。
验证方法：在 admin 库执行
db.system.users.find({user: "appUser"}, {mechanisms: 1})如果返回mechanisms: ["SCRAM-SHA-256"]，那 URI 里就应该写SCRAM-SHA-256，或者干脆不写authMechanism让 Driver 自动协商。最稳妥的做法是不指定 mechanism，除非你有明确的兼容性需求。
3.4 第四步：排除网络与权限干扰
认证失败有时候不是密码问题，而是根本没连上正确的实例。比如你本地起了两个 MongoDB，一个 27017 一个 27018，配置写错了端口，连到了另一个没有该用户的实例，照样报认证失败。
排查方法：先用命令行确认能连上目标实例
mongosh "mongodb://appUser:pass123@127.0.0.1:27017/mydb?authSource=admin"命令行能连上，说明用户、密码、authSource、mechanism 都没问题，问题就在 Spring Boot 配置的写法上。命令行连不上，说明是数据库侧的问题，跟 Spring Boot 无关。
4. 完整实操：从零复现并修复这个报错
4.1 搭建一个会报错的环境
为了让你能真实复现，我先故意配一个错的，再修对。假设数据库里有个用户appUser，建在admin库，支持SCRAM-SHA-256。
先写一个错误配置：
spring: data: mongodb: host: 127.0.0.1 port: 27017 username: appUser password: pass123 database: mydb # 故意不写 authentication-database启动 Spring Boot，调用任意 Repository 方法，就会看到：
Exception authenticating MongoCredential{mechanism=SCRAM-SHA-1, userName='appUser', source='mydb', ...}注意source='mydb'，这就是问题所在——Driver 去mydb库认证appUser，但用户实际在admin库。
4.2 修复配置并验证
改成正确配置：
spring: data: mongodb: host: 127.0.0.1 port: 27017 username: appUser password: pass123 database: mydb authentication-database: admin或者用 URI 方式：
spring: data: mongodb: uri: mongodb://appUser:pass123@127.0.0.1:27017/mydb?authSource=admin重启应用，再调用 Repository，认证通过。如果还是失败，看异常里的source字段变成了什么，对照数据库里的db字段逐一核对。
4.3 用代码方式手动构建 MongoClient 排查
有时候配置文件被多个 profile 覆盖，你根本不知道最终生效的是哪个。这时候可以写一段临时代码，手动构建MongoClient并打印配置：
@Configuration public class MongoDebugConfig { @Bean public MongoClient debugMongoClient() { ConnectionString cs = new ConnectionString( "mongodb://appUser:pass123@127.0.0.1:27017/mydb?authSource=admin"); System.out.println("AuthSource: " + cs.getCredential().getSource()); System.out.println("Mechanism: " + cs.getCredential().getAuthenticationMechanism()); return MongoClients.create(cs); } }运行后看控制台输出的AuthSource和Mechanism，和你预期的是否一致。这个方法在排查“配置明明改了却不生效”的问题时特别管用。
4.4 密码特殊字符的处理
如果密码里有@、:、/、#这些字符，URI 方式必须编码。比如密码是p@ss:123，要写成：
mongodb://appUser:p%40ss%3A123@127.0.0.1:27017/mydb?authSource=admin编码对照表：
| 字符 | 编码 |
|---|---|
| @ | %40 |
| : | %3A |
| / | %2F |
| # | %23 |
| ? | %3F |
| & | %26 |
懒得手动编码的话，用分散配置方式（username/password分开写）可以避开这个问题，Spring Boot 会自己处理。
5. 常见问题速查与避坑经验
5.1 高频问题速查表
| 现象 | 可能原因 | 解决方向 |
|---|---|---|
| source 指向业务库 | 没配 authSource | 加 authentication-database 或 authSource |
| mechanism 是 SCRAM-SHA-1 但用户是 256 | 硬写了旧机制 | 去掉 authMechanism 让 Driver 协商 |
| 命令行能连，Spring Boot 不能 | 配置被覆盖或写法错 | 打印最终生效的 ConnectionString |
| 密码含特殊字符 | URI 未编码 | 编码或改用分散配置 |
| 换了密码仍报错 | 旧连接池缓存 | 重启应用，清掉连接池 |
| 本地能连，容器内不能 | 网络或实例不同 | 确认容器内能访问目标实例 |
5.2 我踩过的几个坑
坑一：profile 覆盖导致配置失效。项目里有application.yml和application-dev.yml，我在 dev 里改了 authSource，结果启动时用的是默认 profile，配置根本没生效。排查时一定要确认当前激活的 profile，或者直接在启动日志里搜MongoClient相关输出。
坑二：密码里有@但没编码。URI 解析时@是分隔符，密码里的@会让 Driver 把后面的内容当成主机名，连都连不上，报的却是认证失败，误导性极强。后来我养成习惯，密码复杂的一律用分散配置。
坑三：MongoDB 版本升级后机制变了。从 4.0 升到 5.0 后，新建用户默认SCRAM-SHA-256，但老配置里写死了SCRAM-SHA-1，升级后全部认证失败。解决办法是去掉硬编码的 mechanism，让 Driver 自动协商。
坑四：连接池缓存了旧凭据。改完密码后没重启应用，连接池里还是旧凭据，一直报认证失败。这种问题最容易被忽略，改完配置记得重启。
5.3 一个实用的排查顺序
遇到这个报错，我现在的排查顺序固定为：
- 看异常里的
source字段，确认认证库 - 命令行用同样凭据连一次，确认数据库侧没问题
- 检查 Spring Boot 最终生效的配置（打印 ConnectionString）
- 检查密码特殊字符和 URL 编码
- 检查认证机制是否匹配
- 重启应用清连接池
按这个顺序走，基本不会绕弯路。大部分情况下，问题就出在前两步。
6. 关于认证配置的一些延伸思考
6.1 为什么推荐 URI 方式
分散配置方式虽然能避开密码编码问题，但字段多、容易漏配，尤其是authentication-database这个字段，名字长还容易忘。URI 方式把所有信息集中在一行，复制粘贴方便，出问题时一眼能看全。我的建议是：密码简单用 URI，密码复杂用分散配置，或者干脆把密码放到环境变量里，URI 里用占位符。
6.2 生产环境的凭据管理
生产环境绝对不要把密码明文写在application.yml里。常见做法是用环境变量：
spring: data: mongodb: uri: mongodb://${MONGO_USER}:${MONGO_PASS}@${MONGO_HOST}:27017/mydb?authSource=admin然后在部署时注入环境变量。这样配置文件可以进版本库，密码不会泄露。如果团队有配置中心，那就更好了，直接对接配置中心拉取。
6.3 多数据源场景下的注意事项
有些项目要连多个 MongoDB 实例，这时候不能靠 Spring Boot 自动装配，得手动配置多个MongoClient和MongoTemplate。每个数据源的authSource可能不同，一定要分别核对。手动配置时，MongoCredential.createCredential(username, authSource, password)的第二个参数就是认证库，写错了照样报这个异常。
MongoCredential credential = MongoCredential.createCredential( "appUser", "admin", "pass123".toCharArray()); MongoClientSettings settings = MongoClientSettings.builder() .applyToClusterSettings(b -> b.hosts(Arrays.asList( new ServerAddress("127.0.0.1", 27017)))) .credential(credential) .build(); MongoClient client = MongoClients.create(settings);这段代码里createCredential的第二个参数"admin"就是认证库，和 URI 里的authSource等价。多数据源时每个都要单独确认。
6.4 认证失败与权限不足的区别
最后提醒一个容易混淆的点：Exception authenticating MongoCredential是认证失败，意思是“你是谁”没验证通过。而权限不足报的是not authorized on mydb to execute command，意思是“验证通过了，但你没权限干这事”。两者解决方向完全不同，别搞混了。认证失败查凭据和 authSource，权限不足查用户角色（readWrite、dbAdmin等）。
我在实际项目里遇到这个报错的次数，少说也有几十次了，真正因为密码错的其实不多，大部分都是authSource没配对或者密码特殊字符没编码。把这两个点记住，能省下大量排查时间。
