FCV升级卡住的根源是config server未先升级或存在未完成元数据变更，必须按config server→shard primary→mongos顺序操作，并确保sh.status()无chunk迁移、rs.status()无异常状态，否则setFCV会静默失败。
FCV 升级卡在 featureCompatibilityVersion 未更新
常见现象是执行 db.adminCommand({ setFeatureCompatibilityVersion: "7.0" }) 后，db.adminCommand({ getCmdLineOpts: 1 }) 或 db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 }) 仍返回旧版本，且分片集群中部分 mongos 或 config server 节点未同步生效。
根本原因通常是 config server 的 FCV 没有先升级，或分片集群中存在未完成的元数据变更（如未完成的 chunk 迁移、未提交的 collection 创建事务）。FCV 升级要求所有 config server 和所有 shards 的 primary 节点都处于一致状态。
- 必须按顺序操作：先升级所有 config server 的 FCV，再升级每个 shard 的 primary，最后升级
mongos进程（虽然 mongos 不存 FCV，但需重启以加载新协议） - 检查
sh.status()是否显示 “There are no ongoing chunk migrations”，否则 FCV 命令会静默失败 - 确认所有 shard 的
rs.status()中没有STARTUP、RECOVERING或ROLLBACK状态节点
升级后出现 CommandNotSupported 或 InvalidOptions 错误
典型报错如："The 'create' command does not support the 'timeseries' option in FCV 6.0"，说明应用代码或驱动仍在使用新版本功能，但 FCV 未真正生效，或部分节点 FCV 不一致。
MongoDB 在 FCV 升级后才启用新语法和行为（比如 $search 在 FCV 7.0+ 才默认可用），如果某 shard 的 FCV 仍是 6.0，而应用发了 7.0 特有的命令，就会被该 shard 拒绝。
- 逐个连接每个 shard 的 primary，运行
db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })验证值是否统一 - 检查
mongos日志是否有 “FCV mismatch detected across shards” 提示 - 若发现某个 shard 滞后，不要直接重试 setFCV，先查该 shard 的 oplog 是否卡住：
db.getSiblingDB("local").oplog.rs.find().sort({$natural: -1}).limit(1)，确认 last applied optime 是否持续推进
降级 FCV 时提示 Cannot downgrade FCV when new features are in use
这是硬性限制：一旦创建了 time-series collection、启用了 $$SEARCH_META 聚合阶段、或使用了 FCV 7.0+ 引入的索引类型（如 text 索引带 language_override），就无法回退 FCV。
不是配置问题，而是数据层已写入不兼容结构。MongoDB 不会自动清理这些“新特征痕迹”。
- 用
db.listCollections().toArray()扫描所有集合，过滤type: "timeseries"字段 - 检查索引：
db.runCommand({ listIndexes: "coll" }).cursor.firstBatch.forEach(i => printjson(i.key))，识别含"$**"或"language_override"的索引 - 唯一安全降级路径：导出数据 → 重建集群（FCV 设为目标值）→ 导入，且导入前确保 dump 中不含 time-series 元数据字段（如
timeField、metaField）
Atlas 上分片集群 FCV 升级失败且控制台无明确错误
Atlas UI 只显示 “Upgrade failed”，但日志里可能只有模糊提示如 “One or more nodes failed readiness check”。这是因为 Atlas 在后台执行 FCV 升级前会做一致性预检，任何节点报告 health: 0 或 state: 8 (DOWN) 就中断流程。
真实瓶颈往往不在 MongoDB 层，而在基础设施：比如某个 shard 所在的云盘 IOPS 达到上限，导致心跳超时；或 config server 所在 VM 内存不足，触发 OOM killer 杀掉 mongod 进程。
- 进入 Atlas 项目 → Monitoring → 选择对应集群 → 切换到 “Hosts” 标签页，查看所有节点的
CPU Utilization、Memory Used、Disk Queue Length曲线，重点排查峰值时段 - 在 “Logs” 标签页筛选关键词：
Failed to upgrade FCV、readiness check failed、not primary and cannot step up - 临时方案：将集群缩容到最小规格（如 M10），排除资源争抢干扰；升级 FCV 成功后再调回原规格
FCV 是分片集群升级中最容易被当作“配置开关”轻率操作的部分——它实际是全集群数据格式与协议的契约锚点。哪怕只有一个 config server 节点没完成升级，整个集群的新功能都会被锁死，且错误表现分散在不同组件日志里。动手前务必确认所有节点的健康状态和 oplog 连续性，而不是只盯着 admin 命令是否返回 OK。
