maxStalenessSeconds 是限定可读取的从节点落后主节点时间上限的拓扑过滤器，仅在 secondary 或 nearest 读偏好下生效，最小合法值为 90 秒，不控制数据新鲜度而约束节点复制延迟。
什么是 maxStalenessSeconds，它真能控制“读多旧的数据”？
不是。它不控制“我能接受数据延迟多少秒”，而是限定“我允许读取的从节点，其落后主节点的时间上限”。这个值只在 secondary 或 nearest 读偏好（readPreference）下生效，对 primary 完全无效。
常见误解是把它当缓存过期时间用——比如设成 30，以为读到 29 秒前的数据就 OK。实际它约束的是节点自身的复制延迟（optimeDate 差值），不是你发起查询那一刻的数据新鲜度。
- 必须配合
readPreference: 'secondary'或'nearest'才起作用 - 值为
-1表示不限制（默认行为），0表示禁止使用任何有延迟的节点（即等效于primary） - 最小合法正整数值是
90秒——MongoDB 强制要求至少 90 秒，低于该值会报错maxStalenessSeconds must be at least 90
maxStalenessSeconds 在连接字符串和驱动里怎么配？
它不属于全局连接配置，而是每次读操作或每个会话可单独设置的选项。不同驱动写法差异明显，容易漏掉层级。
Node.js 驱动（mongodb@6+）中，它必须放在 readPreference 对象内部，不能平级写：
const collection = db.collection('logs', {
readPreference: {
mode: 'secondary',
maxStalenessSeconds: 180
}
});
Python PyMongo 则要通过 ReadPreference 类构造：
from pymongo import ReadPreference
coll.find({}, read_preference=ReadPreference.SECONDARY, max_staleness=180)
- Java 驱动里叫
maxStaleness（无Seconds后缀），单位是秒，但类型是long - Mongo Shell（v6.0+）中只能通过
db.runCommand在命令级指定，无法设在集合级 - Spring Data MongoDB 需在
@Document或ReactiveMongoTemplate调用时显式传入ReadPreference实例
为什么设了 maxStalenessSeconds 却没生效？
最常见原因是副本集状态不满足条件：没有可用的 secondary 节点，或所有 secondary 的延迟都超过阈值，此时驱动会自动降级到 primary（不报错，也不警告）。
另一个隐蔽坑是时间同步——maxStalenessSeconds 依赖各节点系统时钟一致。如果 secondary 时钟比 primary 快 2 分钟，即使它刚完成同步，计算出的“落后时间”也会是负数，导致被跳过。
- 用
rs.printSecondaryReplicationInfo()查看各节点真实延迟，别只信监控图表 - 检查 NTP 是否在所有 mongod 进程所在机器上稳定运行
- 设为
90并不意味着“总能读 secondary”，只是“允许最多容忍 90 秒延迟”，而多数生产环境 secondary 延迟常在毫秒级，所以实际可能永远不触发该限制
性能与一致性之间的实际权衡点在哪？
设得太大（如 3600）几乎等于放开读任意 secondary，吞吐提升有限，但可能读到一小时前已回滚的脏数据；设得太小（卡在 90）又极易因瞬时网络抖动导致 fallback 到 primary，失去读写分离意义。
真正影响性能的是读请求是否被分散，而不是这个参数本身。它只在“刚好有多个 secondary、且它们延迟不均”时才起筛选作用。
- 如果你的副本集只有 1 个 secondary，这个参数基本无意义
- 跨地域部署时，
maxStalenessSeconds是防止读到跨洲际延迟高达分钟级节点的最后防线 - 它不解决最终一致性问题，只是避免读到明显过时的节点——真正的业务一致性还得靠应用层判断
optime或使用因果一致性会话（causalConsistency: true）
这个参数的微妙之处在于：它看起来是个时间控制，实际是个拓扑过滤器；你以为在调“延迟容忍”，其实是在划“可用节点边界”。设错不会炸，但会让读负载悄悄回到主库，而你可能几个月都发现不了。
