MSI 通过正负 reservation 记录下单、取消、发货和退款对可售量的影响。缺少补偿会让 Source 数量正确但 salable quantity 长期偏高或偏低。不要手工汇总后删除 inventory_reservation。
先固定复现条件
先锁定 SKU、Stock 与异常订单，比较 Source quantity、Stock 索引和 reservation 累计值，并确认订单是否经过导入、取消或部分发货。
php bin/magento inventory:reservation:list-inconsistencies -r
SELECT sku,SUM(quantity) reservation_total FROM inventory_reservation WHERE sku='SKU-1' GROUP BY sku;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku='SKU-1';
SELECT sku,quantity,is_salable FROM inventory_stock_1 WHERE sku='SKU-1';根据结果定位根因
常见根因是旧订单迁移后缺少 initial reservation、扩展直接改订单状态、消息队列未消费，或退款/取消事件被执行两次。先查订单历史和队列日志，不能只看当前数量。
修复时保留回滚路径
把官方不一致命令输出保存并逐单复核，再通过 create-compensations 处理确认的差异。修复触发源，确保业务事件幂等；不要把补偿命令当每日清理任务。
上线后的验收
完成下单、取消、部分发货、全额退款四条链路，每一步记录 salable quantity。下一次索引与消费者运行后差异命令应为空，多个 Source 的物理数量也应正确。
生产环境操作前的检查
针对“Magento 2 inventory reservation 出现库存差异”进行处理时，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；需要 UPDATE、DELETE、补偿命令或目录删除时，必须先确认命中范围并保留可恢复备份。多 Web 节点环境还要比较代码版本、app/etc/env.php 摘要和当前流量节点，避免只修复其中一台。
php bin/magento --version
php bin/magento deploy:mode:show
php bin/magento maintenance:status
php bin/magento indexer:status
php bin/magento cache:status命令应由 Magento 文件所有者在项目根目录执行。生产站不要同时运行多个全量索引或静态部署任务；若涉及数据库结构、库存、支付或订单，先在脱敏的生产数据副本验证，再安排维护窗口。
建立可比较的排查记录
每次实验只改变一个变量，并保存“操作前值、执行命令、开始时间、结束时间、结果、回滚方式”。至少准备一个正常对象和一个异常对象作对照，例如两个 SKU、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。
| 检查点 | 需要记录 | 通过标准 |
|---|---|---|
| 数据层 | 主键、Store/Website、更新时间、关联行数 | 关系完整且无孤儿记录 |
| 应用层 | 异常堆栈、模块、Cron/消费者状态 | 无新异常并可重复执行 |
| 缓存与索引 | 索引模式、版本、源站和公网响应 | 按预期周期自动更新 |
| 业务回归 | 正常路径、失败路径、重复请求 | 结果一致且没有重复副作用 |
修复后的观察窗口
上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。
