排查路径

• 对照cron_schedule、文件mtime与Web访问日志，确认同一Sitemap是否在上一任务未完成时再次启动。
• 为单个sitemap_id加互斥锁，生成到同目录临时文件，完成XML校验后再原子rename替换正式文件。

落地修复

1. 检查磁盘空间、文件权限和Base URL，失败时保留上一份完整文件而不是先清空正式文件。
2. 多节点部署时只允许一个调度节点生成，产物放共享存储或同步后再对外发布。

SELECT job_code,status,scheduled_at,executed_at,finished_at FROM cron_schedule WHERE job_code LIKE '%sitemap%' ORDER BY schedule_id DESC LIMIT 30;ls -lh --time-style=long-iso pub/sitemap*.xmlxmllint --noout pub/sitemap.xml

完成标准

并发触发时只有一个任务写入，抓取过程中始终得到完整有效XML，索引文件中的子文件均可访问。

排查路径

• 用两个独立cookie jar请求同一URL并分别设置币种，确认错误只发生在HIT而源站MISS正确。
• 以后台导出的当前版本VCL为基线，自定义vcl_hash不能删除Magento vary上下文。

落地修复

1. 检查前置CDN是否再次缓存HTML却忽略Cookie/Vary，Store与币种切换必须正确分区。
2. 部署修正VCL后清受影响Host缓存并预热，不能把整站永久pass作为最终方案。

curl -sSI -c usd.jar -b usd.jar https://shop.example/product.html
curl -sSI -c eur.jar -b eur.jar https://shop.example/product.html
# 比较X-Magento-Cache-Debug、Age、X-Magento-Vary

完成标准

两个cookie jar交替请求十次，价格与币种始终匹配；相同上下文仍能HIT，切币种不读取旧对象。

解决方案

1. 运行maintenance:status确认模式和允许列表已写入正确release。多节点若各自有独立var目录，设置可能只落在执行命令的节点。
2. 在受控临时日志或Web服务器access log记录REMOTE_ADDR与代理传来的X-Forwarded-For。Magento维护判断通常不会无条件信任任意客户端伪造的XFF。
3. 在负载均衡/Nginx层配置可信代理和real_ip_header，让应用获得真实客户端IP；set_real_ip_from只允许实际代理网段，不能信任0.0.0.0/0。
4. 重新设置允许IP并滚动访问所有节点。若CDN在源站前，必要时在CDN边缘建立受认证的维护绕过，不要公开放行整个CDN出口网段。

bin/magento maintenance:status
bin/magento maintenance:allow-ips 203.0.113.25
cat var/.maintenance.ip 2>/dev/null
# Nginx示例需替换为真实代理网段：
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

回归测试

允许IP访问首页和后台返回正常页面，未允许的外部网络仍503；伪造X-Forwarded-For不能绕过，切换每个Web节点结果一致。

测试结束后删除临时IP日志；不要记录完整Cookie、Authorization或后台URL密钥。

解决记录

步骤1：用浏览器Network确认响应服务器与请求大小，先区分CDN、负载均衡、Nginx和PHP哪一层限制。

步骤2：在对应admin location/server设置合理client_max_body_size，不能只改另一个虚拟主机。

步骤3：同步检查PHP upload_max_filesize、post_max_size、max_file_uploads和临时目录空间，post_max_size应覆盖完整multipart请求。

步骤4：重载配置并上传边界大小文件；仍失败时检查WAF策略和代理请求体限制。

命令与数据检查

nginx -T | grep -n client_max_body_sizephp -i | grep -E 'upload_max_filesize|post_max_size|max_file_uploads|upload_tmp_dir'nginx -s reload

上线前验收

允许范围内的JPG/PNG可上传并生成缩略图，超限文件显示友好错误，前台不会接受危险格式。

解决记录

步骤1：分别检查default、page_cache和session配置；逻辑DB是否被托管Redis真正支持也要确认。

步骤2：为每个环境配置唯一id_prefix，更稳妥是独立实例或独立DB；Session必须完全隔离。

步骤3：切换后清本环境Magento缓存并预热，绝不能对共享Redis执行FLUSHALL。

步骤4：用SCAN统计不同前缀键，验证测试cache:flush不会改变生产键数量，并检查锁和队列连接是否也共享。

grep -n 'id_prefix|database|session|page_cache' app/etc/env.php
redis-cli INFO keyspace
redis-cli --scan --pattern 'prod_*' | head
redis-cli --scan --pattern 'stage_*' | head

上线前验收

两个环境交替清缓存、登录和部署互不影响，生产不出现测试配置，Session键完全隔离。

处理步骤

步骤1：查询sitemap表，确认每个Store有独立记录、sitemap_filename和sitemap_path。后台创建时必须选择正确Store View。

步骤2：在对应Store Scope读取web/secure/base_url与web/unsecure/base_url。Cron/CLI运行时若自定义代码未模拟Store，可能总用默认域名。

步骤3：sitemap_path是Magento安装目录下的可写相对目录，Web服务器URL必须能映射到该文件。生成成功但404时检查DocumentRoot、Nginx location和发布容器持久卷。

步骤4：删除错误文件前先保留副本，按Store重新生成。robots.txt或搜索引擎提交的URL也要分别指向正确域名的Sitemap。

命令与数据检查

SELECT sitemap_id,sitemap_filename,sitemap_path,store_id,sitemap_time FROM sitemap ORDER BY store_id;
bin/magento config:show web/secure/base_url --scope=stores --scope-code=zh_cn
find pub -maxdepth 3 -name '*sitemap*.xml' -ls
curl -I https://cn.example/sitemap.xml

上线前验证

随机抽查商品、分类、CMS URL，全部属于该Store域名并返回200；XML位置可公开访问，另一个Store的URL不会混入。

生成时间正确但内容旧时，还要检查Cron节点写入的文件系统是否与Web节点共享。

普通页面正常，保存地址或提交支付时偶发502。应把Nginx错误、PHP-FPM容量和慢请求时间线对齐。

在同一request_id下关联Nginx access/error、PHP-FPM slowlog和Magento日志，判断upstream超时还是进程崩溃。

检查pm.max_children是否耗尽、listen queue与内存，不能只延长fastcgi_read_timeout掩盖容量问题。

修复方法

• 用slowlog定位外部税费、运费或支付调用，为它们设置连接/读取超时和可控失败策略。
• 按单进程峰值内存计算max_children，调整后压测结账而不是只压首页，并监控队列长度。

grep -E 'upstream timed out|connect() failed|reset by peer' /var/log/nginx/error.logps -ylC php-fpm --sort:rssss -lntp | grep php-fpm# 开启request_slowlog_timeout与slowlog后复现

怎样才算解决

持续结账压测无502，FPM队列与RSS在容量内，外部服务超时时用户收到可恢复错误而非网关错误。

手工添加的列在setup:upgrade后消失。Declarative Schema以启用模块声明为目标状态，数据库不是唯一事实来源。

从备份确认列定义和数据，明确哪个业务模块拥有字段，不立即重复ALTER生产。

在自定义模块db_schema.xml声明列、索引和约束；修改他人表也由自己的模块声明新增部分。

修复方法

• 按版本流程生成db_schema_whitelist.json，并在预发布运行setup:db:status查看计划。
• 先部署声明创建列，再按主键从备份回填；必要迁移用幂等Data Patch。

bin/magento setup:db:status
bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module
SHOW CREATE TABLE target_table;
bin/magento setup:upgrade

怎样才算解决

连续两次升级列都保留，全新安装结构一致，回填数量与备份相符，应用正常读写。

列表浏览正常，点击Export CSV就Allowed memory size exhausted。导出会遍历全部筛选结果，自定义列在每行load实体会迅速放大内存。

记录导出筛选条件、总行数和OOM堆栈。先用100、1000、10000行逐级测试，观察内存是否线性增长或突然跳升。

检查Grid Collection是否select了大字段、join造成重复行，Renderer/DataProvider是否在每行调用Repository getById。把所需字段一次join或批量预取。

php -d memory_limit=512M bin/magento vendor:export --page-size=1000 --from-id=1
rg -n 'getCsvFile|getCsv|_prepareCollection|addFieldToFilter|getById' app/code
SELECT COUNT(*) FROM target_table WHERE created_at BETWEEN :from AND :to;

实际修复

• 大数据导出改为固定页大小读取并流式写临时文件/响应，每页clear集合与实体缓存。排序必须稳定（例如entity_id），避免翻页重复漏行。
• 若导出需要分钟级时间，改成队列任务并提供下载链接；限制用户可导出的最大范围和临时文件保留时间。

怎样才算修好

用边界数据量导出，CSV行数与COUNT一致，首尾ID无缺失重复，内存峰值在分页增加后保持稳定；中文和公式开头字段正确转义。

可执行检查

composer show vendor/packagecomposer why cweagans/composer-patchespatch --dry-run -p1 -d vendor/vendor/package < patches/fix.patchrm -rf vendor/vendor/package && composer install --no-interaction

通过标准：干净CI和生产构建都明确显示补丁成功，目标回归用例通过；上游已修复时安全移除补丁。

可执行检查

SELECT patch_name FROM patch_list WHERE patch_name LIKE '%Vendor\Module%';
SHOW COLUMNS FROM vendor_table LIKE 'custom_column';
bin/magento setup:db:status
bin/magento setup:upgrade

通过标准：全新安装、正常升级和问题库修复得到同一Schema，再次setup:upgrade无重复副作用。

可直接执行的检查

bin/magento queue:consumers:list
bin/magento queue:consumers:start vendor.consumer --max-messages=100
# 业务表建议：UNIQUE(event_id, handler_name)，并记录 processing/completed/failed 状态

通过标准：在业务提交后、ack前主动终止Consumer，再启动处理；消息可以重投，但订单/发货/外部调用只产生一次最终副作用。

不要用消息正文哈希替代业务ID，字段顺序变化和合法重复事件会让哈希去重失真。

在db_schema.xml新增外键后setup:upgrade失败，通常是旧表已有孤儿数据或两列类型并不完全一致。

固定复现范围

用LEFT JOIN找出子表中不存在父记录的值，并统计数量；不要先关闭foreign_key_checks强行建约束。

定位真实原因

比较两列数据类型、unsigned、长度与字符集，引用列必须有索引且定义兼容。

执行修复

制定孤儿数据处理规则：补父记录、归档或删除，并先在数据库副本验证影响。

恢复后处理

修正数据和Schema后运行setup:upgrade，再检查SHOW CREATE TABLE和级联删除策略是否符合业务。

SELECT c.parent_id,COUNT(*) FROM child_table c LEFT JOIN parent_table p ON p.entity_id=c.parent_id WHERE p.entity_id IS NULL GROUP BY c.parent_id;SHOW CREATE TABLE child_table;SHOW CREATE TABLE parent_table;bin/magento setup:upgrade

回归测试

升级成功且重复执行无变化，新增非法parent_id被数据库拒绝，删除父记录按预期RESTRICT或CASCADE。

composer install/update被allow-plugins阻止。这是Composer安全机制，删除vendor不能解决。

固定复现范围

从错误取得完整package名，用composer show与why确认来源及是否必要。

定位真实原因

只允许经过审核的具体插件：composer config allow-plugins.vendor/package true，不允许通配所有插件。

执行修复

配置写入项目composer.json并提交，保证CI与生产一致，不只改个人全局配置。

恢复后处理

重新validate和install，检查composer.lock没有意外大范围升级；未知插件保持阻止。

composer show vendor/package --all
composer why vendor/package
composer config allow-plugins.vendor/package true
composer validate
composer install --no-dev --prefer-dist --no-interaction

回归测试

干净环境可非交互构建，只加载批准插件；删除本地vendor重建结果一致。

日志反复出现Could not acquire lock for cron job，任务长期不执行。锁本身是在防止同一Job并发，先确认持锁进程是否真的还活着。

定位与修复记录

1. 固定复现范围

从日志取得job_code和时间，查询cron_schedule最近记录。状态running且executed_at很早，才可能是遗留任务；短任务偶发抢锁通常只是另一个实例正在执行。

2. 确认真实原因

在所有Cron节点检查bin/magento cron:run进程、系统crontab与Supervisor。多台机器都跑default组而又使用不同锁后端，会互相看不见。

3. 执行修复

确认env.php锁提供者和缓存/数据库连接一致。先停止重复调度源，再处理确认已死亡的running记录；不要在活进程存在时改状态。

4. 恢复后处理

对耗时任务加业务级分页和超时监控，让单次在计划间隔内完成。必须并行时拆成不同job code或队列消息，而不是关闭锁。

SELECT schedule_id,job_code,status,scheduled_at,executed_at,finished_at,messages FROM cron_schedule WHERE job_code='vendor_job' ORDER BY schedule_id DESC LIMIT 20;
ps -eo pid,lstart,etime,cmd | grep '[b]in/magento cron:run'
crontab -l
bin/magento cron:run --group default

验收清单

• 连续观察至少三个调度周期，每次只有一个running并能转success；无重复业务记录，下一周期可正常获取锁。
• 若任务涉及订单或库存，清遗留状态前先确认没有仍在执行的数据库事务。

实际处理步骤

1. 查看生成后的requirejs-config与Network Initiator，列出目标模块所有map、paths和mixins来源。
2. 统一由一个模块负责替换；主题和模块不能分别把原模块映射到不同实现，路径名也要保持大小写一致。
3. Mixin返回目标组件且只注册一次，避免在initialize每次bind全局事件却不dispose。
4. 删除目标静态目录并重新deploy，清浏览器与CDN缓存后用无痕窗口复测。

检查命令

rg -n "map:|mixins:|Vendor_Module/js/component" app/code app/designfind pub/static -name requirejs-config.js -printbin/magento setup:static-content:deploy -f

验证结果

目标模块只请求一次、事件只触发一次，两个主题和生产模式下行为一致。

实际处理步骤

1. 确认Store的general/locale/code与请求路径，zh_CN等代码不能混用。
2. 检查部署命令是否只生成部分语言，或--area、--theme、--no-parent排除了主题依赖。
3. 在维护窗口按目标主题和Locales完整重新deploy，不单独复制缺失JS。
4. 多节点比较deployed_version.txt与Locale目录校验和，清CDN旧404并检查静态签名重写。

检查命令

bin/magento config:show general/locale/code --scope=stores --scope-code=zh_cn
find pub/static/frontend -maxdepth 4 -type d -name "zh_*"
bin/magento setup:static-content:deploy -f zh_CN en_US

验证结果

目标Locale的JS、Knockout模板、翻译字典和CSS均200，切换节点不再404。

按顺序解决

1. 从报错节点检查源码中的Thing类是否存在、命名空间和大小写正确，再检查generated/code对应Factory。只有部分节点缺失时直接比较release版本。
2. 确认部署顺序：安装依赖与代码完成后运行setup:di:compile，随后再打包并原子切换release。若compile后才复制app/code，新类不会被生成。
3. generated/code必须和本次源码、composer.lock一起发布；不要多个节点共享一个正在写入的generated目录。Web进程需要读取权限，但不应靠开放777解决。
4. 清PHP OPcache或滚动重启FPM，使旧进程不再引用上一release路径。多节点逐台健康检查后再接流量。

检查命令

test -f app/code/Vendor/Module/Model/Thing.php
test -f generated/code/Vendor/Module/Model/ThingFactory.php
bin/magento setup:di:compile
find generated/code/Vendor/Module/Model -maxdepth 1 -type f -ls
sha256sum composer.lock app/etc/config.php

验证结果

连续请求覆盖所有Web节点，目标类始终存在；重新发布一次也不复发，且部署期间没有节点读取半成品目录。

注意：在Cloud或只读文件系统中更不能依赖运行时生成，构建产物缺失必须回滚release。

排查路径

• 从浏览器控制台记录被阻止的script、frame、connect或img来源，区分支付生产域与测试域。
• 在支付模块csp_whitelist.xml为对应policy添加精确host；内联脚本优先改为外部文件或使用Magento nonce/hash机制。

落地修复

1. 支付iframe、API和风控像素可能属于不同policy，逐项添加且只允许HTTPS官方域名。
2. 部署后清config/FPC并检查响应Content-Security-Policy，确认没有重复代理Header覆盖Magento配置。

rg -n 'csp_whitelist|content-security-policy' app/code app/designcurl -sSI https://shop.example/checkout/ | grep -i content-security-policybin/magento cache:clean config full_page

完成标准

支付组件完整加载并可下单，控制台无相关CSP错误，未授权测试域和任意内联脚本仍被阻止。

排查路径

• 查看保存请求payload，确认字段位于data[general][field]、field或其他实际路径。
• 检查form namespace、dataSource、fieldset和field dataScope，Provider getData结构与JS期待层级一致。

落地修复

1. Controller/Repository从同一路径取值，并写入模型允许字段或Extension Attribute，数据库列必须存在。
2. 布尔字段配置valueMap，空值区分“清除”和“未提交”，避免0被过滤。

rg -n 'dataScope|namespace|provider' view/adminhtml/ui_component app/code
SHOW COLUMNS FROM vendor_entity LIKE 'custom_field';

完成标准

新建、编辑、清空和值为0四种情况保存后重新打开均正确，Repository/API读取一致。

解决方案

1. 完整保存第一条编译错误。找到生成目标类的constructor，并用Reflection或源码确认父类当前版本的参数顺序与类型。
2. 自定义类继承核心类时，升级后父构造函数新增/调整参数最常见。同步子类签名和parent::__construct调用，优先避免复制整个父构造函数。
3. 若错误来自di.xml，检查argument name是否仍与构造函数参数名一致，xsi:type=object指向的类是否实现期望接口；virtualType链中同名参数也会覆盖。
4. 清除旧generated/code与generated/metadata后重新compile。生产构建必须使用与运行环境相同的composer.lock和PHP主次版本。

bin/magento setup:di:compile
rg -n '<argument name="problemArg"|<preference.*ExpectedInterface' app/code vendor
php -r "require 'app/bootstrap.php'; $r=new ReflectionClass('Vendor\Module\Model\Target'); foreach($r->getConstructor()->getParameters() as $p){echo $p,PHP_EOL;}"

回归测试

di:compile无错误，相关页面/CLI实际实例化目标类成功；同时运行静态分析或最小集成测试，确保不是靠可空默认值掩盖缺失依赖。

generated目录应在构建阶段重新生成，不要把旧环境生成物复制进新版本。

解决记录

步骤1：比较所有Web节点pub/static/deployed_version.txt、HTML中的/version数字及文件校验和。

步骤2：使用同一构建产物原子切换到各节点，代码、静态文件和版本号不能分批不一致暴露。

步骤3：清Magento FPC后按Host和static路径清CDN，避免CDN缓存旧HTML或旧404。

步骤4：检查Nginx static签名重写规则和symlink权限，不能用关闭静态签名长期规避。

命令与数据检查

for h in web1 web2; do ssh $h 'cat pub/static/deployed_version.txt'; donecurl -sS https://shop.example/ | grep -o '/static/version[0-9]*/' | headsha256sum pub/static/frontend/Vendor/theme/*/*/js/app.js

上线前验收

连续请求命中不同节点时HTML版本一致，新资源返回200，旧HTML不再引用已删除路径。

解决记录

步骤1：检查请求中的selected、excluded、filters和namespace；全选依赖筛选条件和excluded列表。

步骤2：Controller使用MassAction Filter的getCollection应用UI筛选，不要只遍历request[selected]。

步骤3：primaryFieldName、requestFieldName和indexField必须对应真实主键。

步骤4：大批量改为分页或队列，并记录成功失败ID；执行前显示匹配总数避免误处理全表。

$collection = $this->filter->getCollection($this->collectionFactory->create());
foreach ($collection->getItems() as $item) { /* enqueue/process */ }

上线前验收

当前页选择、跨页全选、排除3条及带筛选全选的处理数量都与界面一致。

处理步骤

步骤1：确认模块已启用且registration.php、module.xml名称一致。执行module:status和setup:upgrade后查看config缓存，不要只看代码目录。

步骤2：routes.xml必须位于etc/frontend，router id通常为standard；route的id用于布局handle，frontName才是URL第一段。检查XML命名空间和模块name。

步骤3：Action类路径应匹配Controller/Action/Index.php，并实现ActionInterface或继承正确Action。Linux文件名大小写不一致在本地macOS可能正常、生产会404。

步骤4：在execute入口写临时脱敏日志。完全没有进入时检查前置路由冲突、URL Rewrite和Web服务器location；进入后返回404则查ResultFactory逻辑。

命令与数据检查

bin/magento module:status Vendor_Module
php -l app/code/Vendor/Module/Controller/Action/Index.php
xmllint --noout app/code/Vendor/Module/etc/frontend/routes.xml
bin/magento cache:clean config full_page

上线前验证

访问标准URL返回预期状态；不存在action仍404；开启/关闭Store Code和两个Store View时路由均稳定，日志只记录一次执行。

不要把敏感参数直接写日志，自定义POST路由还需要正确处理CSRF。

执行cache:clean或部署后全站客户Session丢失。正常缓存清理不应删除Session，通常是Redis数据库或前缀配置重叠。

比较env.php中default cache、page_cache和session的host、port、database及前缀，Session必须独立。

检查部署脚本是否执行redis-cli FLUSHALL/FLUSHDB，或把cache:flush误当成安全的cache:clean。

修复方法

• 迁移Session存储时设置独立数据库/实例并安排窗口；不要在高峰直接切换造成全部现有Session失效。
• 执行一次受控cache:clean，比较Session键数量和测试账号Cookie，确认没有被清除。

grep -n 'session|page_cache|default|database|id_prefix' app/etc/env.phpredis-cli -n 2 DBSIZEbin/magento cache:clean config layout block_html

怎样才算解决

清理任意Magento缓存类型后已登录账号仍在线，Session过期只由自身生命周期控制。

Grid能打开，一筛选ID或状态就报Column is ambiguous。join的多个表都有同名列，而Filter仍使用裸字段。

从异常SQL确认冲突列和表别名，明确UI字段属于主表还是join表。

在Collection用addFilterToMap映射到main_table.entity_id或目标别名，Select列使用唯一alias。

修复方法

• UI column name、filter与DataProvider字段保持一致，自定义addFilter保留condition type。
• 同时测试排序、范围筛选和导出；只修WHERE不修ORDER BY仍会报错。

$collection->addFilterToMap('entity_id', 'main_table.entity_id');
$collection->addFilterToMap('status', 'main_table.status');

怎样才算解决

ID、状态、日期筛选与排序、CSV导出均正常，join不会造成重复行。

同一个CMS identifier在主站正常，切到另一个Store就404。缓存不是第一嫌疑，先验证页面是否真正分配给该Store。

查询cms_page_store，确认page_id关联目标store_id或store_id=0（All Store Views）。页面还必须is_active=1。

检查目标Store是否存在另一个相同identifier页面。多个可匹配页面会导致加载歧义，按语言拆分时每个页面只分配明确Store。

SELECT page_id,identifier,title,is_active FROM cms_page WHERE identifier='shipping-policy';
SELECT cps.page_id,cps.store_id,s.code FROM cms_page_store cps JOIN store s ON s.store_id=cps.store_id WHERE cps.page_id IN (:page_ids);
bin/magento config:show web/url/use_store

实际修复

• 带Store Code的URL要确认web/url/use_store以及Base URL路径。反向代理若剥离或重复添加Store Code，会在CMS路由前得到错误path。
• 修正分配后清full_page和block_html；用Host与Store Cookie都固定的请求验证，避免浏览器残留Cookie把请求送到另一个Store。

怎样才算修好

在每个目标Store用无痕请求页面，状态200、标题与语言正确；未分配的Store应保持404而不是错误回退。

可执行检查

SELECT scope,scope_id,path,value FROM core_config_data WHERE path='vendor/module/setting' ORDER BY scope,scope_id;bin/magento config:show vendor/module/setting --scope=stores --scope-code=zh_cnbin/magento cache:clean config

通过标准：默认、Website和两个Store View分别返回预期值，后台保存与CLI、前台、Cron读取结果一致。

可执行检查

SELECT email,rp_token_created_at FROM customer_entity WHERE email='test@example.com';
SELECT UTC_TIMESTAMP(),NOW();
date -u
bin/magento config:show customer/password/reset_link_expiration_period

通过标准：最新链接在有效期内可使用一次，旧链接和已使用Token失效，所有Web节点与数据库时间一致。

可直接执行的检查

curl -I -L --max-redirs 10 https://shop.example/old-category.html
SELECT url_rewrite_id,request_path,target_path,redirect_type,store_id,entity_id FROM url_rewrite WHERE request_path IN ('old-category.html','new-category.html') OR target_path IN ('old-category.html','new-category.html');

通过标准：旧URL只跳一次到新URL，新URL直接200；带参数、尾斜杠和两个Store域名都不会回跳。

301会被浏览器和CDN长时间缓存，验收应使用curl和新路径，不要只看原浏览器标签。

后台域名切换后账号密码和验证码都正确，却反复回到登录页。先区分2FA验证失败与Admin Session Cookie未保存。

固定复现范围

浏览器检查登录响应的Set-Cookie、Domain、Path、Secure和SameSite，并清除旧域名同名Cookie。

定位真实原因

核对web/secure/base_url、cookie_domain、cookie_path及Offloader Header，反向代理必须把HTTPS状态传给Magento。

执行修复

服务器时间与手机时间保持NTP同步；若只是个别用户，按官方CLI流程重置该用户2FA提供器后重新绑定。

恢复后处理

清config缓存并在无痕窗口测试，不能通过关闭整个2FA模块作为长期解决方案。

bin/magento config:show web/secure/base_urlbin/magento config:show web/cookie/cookie_domaintimedatectl statusbin/magento security:tfa:reset adminuser google

回归测试

新域名连续登录、退出和Session过期均正常，旧域名Cookie不影响，其他管理员2FA保持有效。

中文站Invoice邮件出现英文主站Logo。邮件Logo取决于订单Store环境和Transactional Email配置。

固定复现范围

记录Invoice所属order.store_id、模板ID和异步发送配置，在目标Store Scope检查Logo和模板。

定位真实原因

自定义发送代码以订单Store构造Template Options，并用Environment Emulation包裹渲染，finally停止模拟。

执行修复

队列消息保存store_id，Consumer不能在默认Store渲染；图片URL使用订单Store的secure Base URL。

恢复后处理

清配置/模板缓存后发送两个Store测试邮件，不能在HTML硬编码主域名。

SELECT i.increment_id,o.store_id FROM sales_invoice i JOIN sales_order o ON o.entity_id=i.order_id WHERE i.increment_id='INV-1';
bin/magento config:show design/email/logo --scope=stores --scope-code=zh_cn

回归测试

两个Store的Logo、语言、发件人和链接域名均正确，交叉发送顺序不会串站。

新建中文商品时URL Key为空，保存后出现重复或无法生成Rewrite。直接用随机字符串虽能保存，却会造成URL不稳定。

定位与修复记录

1. 固定复现范围

确认url_key是否勾选Use Default，以及哪个Store范围为空。检查自定义Plugin是否在Product Url Key Generator之后再次过滤非ASCII字符。

2. 确认真实原因

确定稳定策略：使用人工维护的英文短名、拼音slug或SKU派生值。转换结果必须小写、仅允许安全字符、合并连续连字符并去掉首尾连字符。

3. 执行修复

当转换结果仍为空时回退到SKU；保存前按Store检查request_path唯一性，冲突时追加稳定短后缀，不能每次保存生成新随机值。

4. 恢复后处理

对已上线商品批量修复时保留旧URL的301重写。先导出entity_id、store_id、旧url_key和新slug，dry-run检测冲突后再分批执行。

SELECT entity_id,sku FROM catalog_product_entity WHERE entity_id=:entity_id;
SELECT store_id,value FROM catalog_product_entity_varchar WHERE entity_id=:entity_id AND attribute_id=(SELECT attribute_id FROM eav_attribute WHERE attribute_code='url_key' AND entity_type_id=4);
SELECT request_path,target_path,store_id FROM url_rewrite WHERE request_path LIKE 'new-slug%';

验收清单

• 创建纯中文、中文加数字、重复名称三个商品；每个Store生成稳定且唯一URL，二次保存URL不变化，旧地址正确301。
• SKU可能包含内部信息或不适合公开，采用SKU回退前先确认业务与SEO要求。

实际处理步骤

1. 按订单号对照邮件服务日志、cron_schedule和sales_order.email_sent，确认两次发送分别来自哪个入口。
2. 使用Magento标准send_new_order_email流程；自定义Observer不能再直接调用TransportBuilder发送同一模板。
3. 异步发送时只有成功后更新状态，重试前再次检查订单标记；队列消息以order_id和邮件类型做唯一幂等键。
4. 并发Consumer必须原子领取任务，修复后清理重复调度但不删除待发送的其他订单。

检查命令

SELECT increment_id,email_sent,send_email,created_at FROM sales_order WHERE increment_id='000000123';SELECT job_code,status,messages,executed_at FROM cron_schedule WHERE job_code LIKE '%email%' ORDER BY schedule_id DESC LIMIT 50;rg -n 'sendNewOrderEmail|TransportBuilder|sales_order_place_after' app/code

验证结果

普通下单、支付重试、Consumer重启和邮件服务超时场景中，每种邮件只发送一次且失败可恢复。

实际处理步骤

1. 从php://input或请求对象取得原始body并只读取一次；不能对decode后的对象再次encode再验签。
2. 确认代理没有解压重压、转换字符集或把JSON包装成表单，Content-Type和签名头完整透传。
3. 按网关文档组合timestamp与rawBody，用常量时间比较，并检查服务器时钟和允许窗口。
4. 验签后再解析业务字段，按event_id/transaction_id幂等处理。

检查命令

# PHP伪代码：$raw=$request->getContent(); verify($timestamp.'.'.$raw,$header,$secret)
timedatectl status

验证结果

官方测试事件通过；重放同一事件只执行一次，篡改一个字节或过期timestamp均被拒绝。

按顺序解决

1. 确认请求实际Store ID，查询eav_attribute_label中attribute_id+store_id的frontend_label；没有记录时会回退默认属性label。
2. 再查eav_attribute_option_value。store_id=0是默认option label，目标Store应有对应记录；保存空字符串可能被当成没有覆盖。
3. 自定义Configurable JSON或Swatch Resolver必须在目标Store环境下获取label。若Block cache key不含store_id，先访问英文站会把英文JSON缓存给中文站。
4. 补齐标签并修正cache key后清block_html与FPC；GraphQL/PWA还要携带Store Header并清客户端缓存。

检查命令

SELECT attribute_id,store_id,value FROM eav_attribute_label WHERE attribute_id=:attribute_id;
SELECT option_id,store_id,value FROM eav_attribute_option_value WHERE option_id IN (:option_ids) ORDER BY option_id,store_id;
bin/magento cache:clean block_html full_page graphql

验证结果

交叉访问两个Store的同一商品，每个属性名和选项值使用本Store翻译；连续切换访问顺序也不能串语言。

注意：URL中的Store Code和Cookie可能覆盖预期Store，排查时同时看响应中的Store上下文。

排查路径

• 记录RSS随消息数变化，使用固定测试消息复现；同时检查未释放的大Collection、图片资源和静态缓存。
• 逐条处理时清理实体引用，避免把完整对象追加到进程级数组；异常路径也要关闭文件与外部连接。

落地修复

1. 使用--max-messages让Consumer定期优雅退出，由Supervisor/systemd自动拉起，并设置停止超时。
2. 限制重试和死信策略，单条毒消息不能在内存中无限失败重放。

ps -o pid,rss,etime,cmd -C php | grep consumers:startbin/magento queue:consumers:start async.operations.all --max-messages=1000# Supervisor: autorestart=true, stopwaitsecs=60

完成标准

处理相同规模消息时RSS在区间内波动，进程轮换不丢消息、不重复业务写入，毒消息可追踪。

排查路径

• 记录3DS前后quote_id、支付attempt_id以及返回请求是否带Cookie，不记录卡数据。
• 跨站POST时检查SameSite、Secure、HTTPS和Cookie域；Lax策略可能不携带原Session。

落地修复

1. state参数需签名并绑定Quote/attempt，不能只依赖Session；返回后先查询网关状态再恢复订单。
2. 订单已创建时跳成功页；重复返回和刷新必须幂等，不能再次capture。

php bin/magento config:show web/cookie/cookie_domain
php bin/magento config:show web/cookie/cookie_path
# Network检查Set-Cookie的SameSite与Secure

完成标准

成功、失败、取消、超时和重复返回均能定位原Quote/Order，只发生一次支付，伪造state被拒绝。

解决方案

1. 解码product_options，确认options与info_buyRequest都含option_id和选择值。只有additional_options显示文本但buyRequest为空，说明下单时只做了展示，没有保存可重建配置。
2. 自定义加购代码应使用Product Type prepareForCartAdvanced或Cart addProduct并传完整buyRequest，不要直接new Quote Item后写name/price。
3. 自定义选项值已被删除或option_id在新版本变化时，Reorder应给出可理解错误并要求重新选择，不能静默加入无选项商品。
4. 修复后新订单会保存完整buyRequest。历史订单若有足够的additional_options，可建立受控映射恢复；无法确定时不要自动猜值。

SELECT item_id,sku,product_options FROM sales_order_item WHERE order_id=:order_id;
SELECT option_id,product_id,type,is_require FROM catalog_product_option WHERE product_id=:product_id;
SELECT option_type_id,option_id,sku FROM catalog_product_option_type_value WHERE option_id IN (:option_ids);

回归测试

新建包含文本、下拉、日期和文件以外可重用选项的订单，再Reorder；购物车选项、价格附加值和最终订单完全一致。

文件上传选项通常不能安全复用原文件，应明确要求客户重新上传。

解决记录

步骤1：按job_code和status统计数量、最老时间与执行耗时，识别重复调度、长期error或never finished任务。

步骤2：确认cron:run没有被多个系统Cron以过高频率重复启动，并检查同一组锁是否正常。

步骤3：修复异常Job后配置合理的history_success_lifetime、history_failure_lifetime与cleanup_every。

步骤4：分批删除超过保留期的success/error/missed历史记录，控制事务大小并保留pending/running。

命令与数据检查

SELECT job_code,status,COUNT(*) c,MIN(created_at),MAX(created_at) FROM cron_schedule GROUP BY job_code,status ORDER BY c DESC LIMIT 30;DELETE FROM cron_schedule WHERE status IN ('success','error','missed') AND finished_at < UTC_TIMESTAMP()-INTERVAL 30 DAY LIMIT 5000;bin/magento config:show system/cron/default/history_success_lifetime

上线前验收

表行数稳定，Cron查询恢复使用索引，新任务按时运行且清理任务不会阻塞业务写入。

解决记录

步骤1：记录切换前后checkoutProvider与set-billing-address请求，确认只丢UI还是Quote也被改写。

步骤2：检查支付renderer的initialize、selectPaymentMethod和afterRender，不能每次显示都调用useShippingAddress。

步骤3：same-as-shipping订阅只在用户操作时更新，并在组件销毁时解除，避免重复subscription反向写值。

步骤4：保存Billing Address的Promise完成后再提交订单，后端以Quote最后地址为准。

rg -n 'isAddressSameAsShipping|billingAddress|selectPaymentMethod|setBillingAddress' app/code app/design
# Network检查/carts/*/billing-address与/payment-information

上线前验收

三个支付方式来回切换，独立账单地址保持；只有勾选同配送时才同步，Order地址与页面一致。

处理步骤

步骤1：保存应用优惠码前后的quote、quote_address和salesrule验证日志。记录customer_group_id、website_id、国家、地区、邮编、subtotal以及shipping_method。

步骤2：在Sales Rule中逐层检查Website、客户组、有效期、Uses、Coupon Uses以及Conditions。配送国家条件在地址未知时可能暂时通过，填写后才会被正确判定失败。

步骤3：若条件应当通过，检查自定义total collector或地址保存插件是否清空coupon_code、覆盖applied_rule_ids，或者错误地用billing address验证实体购物车。

步骤4：修正规则或插件后重新collect totals。不要只修改discount_amount，折扣必须由规则重新计算并同步到base金额和item分摊。

命令与数据检查

SELECT entity_id,coupon_code,customer_group_id,store_id,subtotal,grand_total,applied_rule_ids FROM quote WHERE entity_id=:quote_id;
SELECT address_type,country_id,region_id,postcode,shipping_method,subtotal,discount_amount FROM quote_address WHERE quote_id=:quote_id;
SELECT rule_id,name,is_active,from_date,to_date,conditions_serialized,actions_serialized FROM salesrule WHERE coupon_type<>1;

上线前验证

测试允许/禁止国家、边界金额、访客/登录客户和切换配送方式；符合条件时优惠码保留，不符合时页面给出明确提示而非静默消失。

多币种规则通常以base金额判断，验证时同时记录subtotal与base_subtotal。

中文Store搜索结果出现英文名称或英文属性标签，直接访问商品页却正常。搜索索引可能在错误Store上下文中构建。

对同一SKU查询默认范围与目标store_id的name、description和参与搜索属性值，确认源数据存在。

检查catalogsearch_fulltext为每个Store建立的索引/alias，Cron运行时不能被自定义代码强制切到默认Store。

修复方法

• 自定义数据Mapper应使用传入的storeId加载属性标签，不能从全局StoreManager读取当前后台Store。
• 修复后仅重建catalogsearch_fulltext并清搜索/FPC缓存，分别用两个Store请求验证。

SELECT store_id,value FROM catalog_product_entity_varchar WHERE entity_id=:entity_id AND attribute_id=:name_attr ORDER BY store_id;bin/magento indexer:reindex catalogsearch_fulltextcurl -sS 'http://opensearch:9200/_cat/aliases?v'

怎样才算解决

相同关键词在中英文Store返回各自名称和标签，切换Store不会读取上一站的搜索文档。

合法英国、加拿大或无邮编地区地址被判格式错误。前端是否阻止请求和后端是否拒绝要分开检查。

在Network确认请求是否发出；未发出查前端validate，请求400读取后端字段错误。

country_id变化时动态更新postcode的required和正则，不能全局套用美国5位数字规则。

修复方法

• 使用国家级规则；不要求邮编的国家允许空值，同时保留长度和安全过滤。
• 第三方地址服务超时不应等同地址非法，可提供受控的“使用原地址”路径并在服务端规范化。

rg -n 'postcode|zip.*validate|validate-postcode' app/code app/design
# 比较country_id切换前后的input class与validation配置

怎样才算解决

美国、英国、加拿大、无邮编国家以及含空格/连字符格式均按国家正确判断，前后端规则一致。

后台显示全部实体商品已发货，订单仍是Processing。不要直接UPDATE state/status为complete，先找出Magento为什么仍判断canInvoice或canShip。

查询每个order_item的qty_ordered、qty_invoiced、qty_shipped、qty_refunded、qty_canceled以及product_type。父子商品要看实际可发货行，不能简单相加。

若canInvoice仍为真，检查支付动作是Authorize还是Authorize and Capture，以及是否缺Invoice。虚拟商品不需要Shipment，但通常需要完成开票。

SELECT item_id,parent_item_id,sku,product_type,qty_ordered,qty_invoiced,qty_shipped,qty_refunded,qty_canceled FROM sales_order_item WHERE order_id=:order_id;
SELECT increment_id,state,status,total_invoiced,total_paid FROM sales_order WHERE entity_id=:order_id;

实际修复

• Shipment数量不足时，检查Bundle/Configurable父子行、自定义创建Shipment代码是否使用错误item_id，或小数数量被取整。
• 修复缺失业务单据后调用Order Repository保存，让状态机自行计算。只有所有可开票/可发货动作结束时才应Complete。

怎样才算修好

覆盖纯实体、纯虚拟、可配置和Bundle订单；完成Invoice/Shipment后自动Complete，仍有未开票或未发货数量的订单继续保持Processing。

可执行检查

bin/magento indexer:status catalogsearch_fulltextbin/magento indexer:show-mode catalogsearch_fulltextcurl -sS 'http://opensearch:9200/_cat/aliases?v'curl -sS 'http://opensearch:9200/_cluster/health?pretty'

通过标准：单品保存后能通过SKU和关键词搜索，两个Store结果符合各自可见性，后续增量更新无需全量重建。

可执行检查

SELECT subtotal,base_subtotal,subtotal_with_discount,base_subtotal_with_discount,shipping_amount,discount_amount FROM quote_address WHERE quote_id=:quote_id;
SELECT rule_id,name,conditions_serialized,actions_serialized,simple_free_shipping FROM salesrule WHERE is_active=1;

通过标准：门槛前后1分钱、优惠券前后、两个国家和两种币种下，页面、Quote与Order运费一致。

可直接执行的检查

SELECT item_id,sku,qty,back_to_stock FROM sales_creditmemo_item WHERE parent_id=:creditmemo_id;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku='SKU-1';
SELECT stock_id,sku,SUM(quantity) FROM inventory_reservation WHERE sku='SKU-1' GROUP BY stock_id,sku;

通过标准：测试未发货取消、已发货全退、部分退且不回库、部分退并回库四种情况，Source quantity与salable quantity都只变化一次。

退款到支付平台成功不代表仓库已收货，业务上需要RMA时应让入库确认驱动回库存。

促销结束时间已过，商品页和购物车仍显示规则价。价格规则依赖时区、Cron应用和价格索引，单纯清浏览器缓存没有作用。

固定复现范围

确认规则Website、客户组、from_date/to_date以及后台配置时区，日期边界按商店时区解释。

定位真实原因

检查catalogrule_apply_all及相关Cron是否成功，cron_schedule不能长期pending或missed。

执行修复

执行规则应用与catalog_product_price重建，再清FPC/Varnish；先在预发布验证影响范围。

恢复后处理

若自定义价格服务缓存最终价，缓存键必须包含日期和客户组，并在规则失效时主动清理。

bin/magento cron:run --group=defaultbin/magento indexer:reindex catalogrule_rule catalogrule_product catalog_product_priceSELECT job_code,status,scheduled_at,executed_at,finished_at FROM cron_schedule WHERE job_code LIKE 'catalogrule%' ORDER BY schedule_id DESC LIMIT 20;

回归测试

在规则开始和结束边界前后测试，列表页、商品页、GraphQL与购物车价格同步切换。

结账显示两条完全相同的配送方式。Magento依赖carrier_code + method_code唯一标识，不是靠标题区分。

固定复现范围

保存shipping-methods接口原始rates，比较carrier_code、method_code、amount，判断重复来自后端还是前端。

定位真实原因

检查自定义Carrier的$_code和Method code，复制模块后必须更换code，同Carrier不同服务也要不同method。

执行修复

检查collectRates插件只调用proceed一次并且不会重复append，前端mixin不要重复push Observable。

恢复后处理

修复后清config/FPC并重新估算运费；已有Quote的冲突shipping_method应清除后重选。

rg -n '$_code|setCarrier(|setMethod(|collectRates' app/code
SELECT carrier,method,price FROM quote_shipping_rate WHERE address_id=:address_id ORDER BY rate_id;

回归测试

不同地址重复估算三次，每个carrier_method只有一条；保存到Quote和Order的配送方式正确。

网关后台显示Capture成功，Magento订单仍Processing/Pending Payment且没有Invoice。第一原则是停止自动重试支付，避免二次扣款。

定位与修复记录

1. 固定复现范围

用订单号、网关transaction_id和金额在两边对账。确认Capture确实settled/authorized-captured，而不是只创建了authorization。

2. 确认真实原因

查sales_payment_transaction与order_payment中的last_trans_id、amount_paid。已有capture交易但无Invoice，说明回调在保存Invoice前中断；完全无交易记录则先安全补录网关事实。

3. 执行修复

通过InvoiceService为可开票数量创建Invoice，设置capture case为NOT_CAPTURE并关联现有transaction_id，注册后在数据库事务中保存Invoice与Order。绝不能调用CAPTURE_ONLINE。

4. 恢复后处理

把补救脚本限制到一个明确订单，执行前输出dry-run信息并备份。随后修复Webhook幂等与事务边界，让重复回调只返回成功。

SELECT entity_id,increment_id,state,status,total_paid,total_invoiced FROM sales_order WHERE increment_id='000000123';
SELECT txn_id,txn_type,parent_txn_id,is_closed,additional_information FROM sales_payment_transaction WHERE order_id=:order_id;
SELECT entity_id,increment_id,state,grand_total FROM sales_invoice WHERE order_id=:order_id;

验收清单

• 补建后total_paid、total_invoiced与网关Capture金额一致，只出现一个capture transaction；退款入口可用且客户只收到一次发票邮件。
• 金额或币种对不上时不要自动补Invoice，先交由财务和支付负责人确认。

实际处理步骤

1. 查询salesrule_coupon_usage、salesrule_customer和相关订单状态，按coupon_id、customer_id核对计数。
2. 正常取消订单应通过Order Management执行；直接更新state/status不会触发优惠券使用次数回滚。
3. 检查支付失败逻辑是否重复调用下单或重复派发sales_order_place_after，确保一次订单只增加一次。
4. 历史数据先列出应回滚的订单并备份，再使用服务层或审计脚本逐单纠正，禁止无条件重置全部计数。

检查命令

SELECT coupon_id,customer_id,times_used FROM salesrule_coupon_usage WHERE coupon_id=:coupon_id;SELECT rule_id,customer_id,times_used FROM salesrule_customer WHERE rule_id=:rule_id AND customer_id=:customer_id;SELECT increment_id,state,status,coupon_code FROM sales_order WHERE coupon_code=:code;

验证结果

成功订单占用一次，取消后按规则释放，支付重试不重复累计，客户与全局使用上限都正确。

实际处理步骤

1. 查询inventory_source和Stock-Source链接，确认enabled状态及是否仍属于当前Stock。
2. 检查该Source是否仍有非零Source Item、未完成发货或自定义SSA缓存；先处理业务库存再解绑。
3. 清config、block与FPC；API仍返回旧Source时检查自定义Provider缓存键是否包含Stock ID。
4. 历史Shipment保留原source_code用于审计，新Shipment候选只过滤当前有效Source。

检查命令

SELECT source_code,name,enabled FROM inventory_source WHERE source_code='old_wh';
SELECT * FROM inventory_source_stock_link WHERE source_code='old_wh';
SELECT COUNT(*),SUM(quantity) FROM inventory_source_item WHERE source_code='old_wh';

验证结果

新Shipment候选不再出现旧仓，新订单由有效仓推荐；历史Shipment仍显示原仓信息。

按顺序解决

1. 从异常表名确定store_id，再查store是否存在，以及sales_sequence_meta中order实体是否有该Store映射。
2. 比较一个正常Store的meta、profile和实际sequence表结构。若只迁了业务表没迁序列表，应从同版本结构恢复，而不是手工创建只有一列但缺少自增设置的表。
3. 若Store是后台新建后出现问题，检查创建Store时setup/observer异常。修复模块后通过Magento的Sequence建表逻辑补齐order、invoice、shipment、creditmemo，不只补当前报错表。
4. 设置起始值前查询该Store现有最大increment_id，确保新序列不会与历史订单重复。操作前备份所有sales_sequence相关表。

检查命令

SELECT store_id,code,website_id FROM store ORDER BY store_id;
SELECT meta_id,entity_type,store_id,sequence_table FROM sales_sequence_meta ORDER BY store_id,entity_type;
SELECT MAX(increment_id) FROM sales_order WHERE store_id=:store_id;
SHOW CREATE TABLE sequence_order_1;

验证结果

在目标Store依次创建订单、Invoice、Shipment和Credit Memo，编号前缀、步长与唯一性正确；另一个Store序列不受影响。

注意：不要复制生产订单号到测试后再反向覆盖生产序列，迁移必须明确每个环境的编号边界。

排查路径

• 对比cart section-data与totals-information接口，记录quote_id和更新时间，确认差异来自显示层还是Totals。
• 自定义加购、改数量、优惠券或地址接口完成后触发正确customer-data section失效，不要直接改DOM金额。

落地修复

1. 在sections.xml声明会影响cart的Action；异步请求必须等待Quote保存和collectTotals完成再刷新section。
2. 清浏览器localStorage仅用于复现，最终修复要保证多标签页和登录合并购物车也能自动更新。

rg -n '<action name=|customer-data|invalidate(.*cart' app/code app/design# 浏览器检查 localStorage: mage-cache-storage 与 mage-cache-storage-section-invalidation

完成标准

加购、改数量、用券、登录和切换地址后，迷你购物车与购物车页、结账页金额同步且无需手工刷新。

排查路径

• 按订单号在metadata中定位原预留与补偿，按stock_id和SKU求和，不能只看最后一条。
• 确认订单经标准Order Management cancel执行；ERP直接改state/status不会触发完整补偿。

落地修复

1. 运行list-inconsistencies，确认订单确已取消且未发货后，再将审核过的输出交给create-compensations。
2. 修复ERP/API取消流程并做幂等；历史订单逐单补偿，避免部分发货单被错误加库存。

SELECT reservation_id,stock_id,sku,quantity,metadata FROM inventory_reservation WHERE metadata LIKE '%000000123%' ORDER BY reservation_id;
bin/magento inventory:reservation:list-inconsistencies -r

完成标准

新订单预留为负，取消后累计归零且salable恢复；重复取消不会再增加补偿。

解决方案

1. 查询问题订单的send_email与email_sent。send_email=0表示业务流程根本没有安排发送；send_email=1且email_sent为空才是待发送。
2. 在cron_schedule中查sales_send_order_email及对应时间窗口。success但邮件未到，需要查SMTP传输和退信；error/missed则先修Cron锁、PHP错误或执行频率。
3. 自定义下单代码应通过Order Email Sender安排发送，不要只创建Order后假设Cron会自动发现。异步模式下也要保留正确Store环境和模板配置。
4. 修复后只对确认未发送的订单重试，发送前再次检查email_sent，防止批量重发造成重复邮件。

SELECT increment_id,store_id,send_email,email_sent,created_at FROM sales_order WHERE increment_id='000000123';
SELECT job_code,status,messages,scheduled_at,executed_at,finished_at FROM cron_schedule WHERE job_code='sales_send_order_email' ORDER BY schedule_id DESC LIMIT 20;
bin/magento cron:run --group default

回归测试

创建访客和登录客户订单各一笔，观察一轮Cron后email_sent变为1；模板语言、发件人、订单链接和重复发送控制均正确。

SMTP返回250只代表服务器接收，不代表最终进收件箱；需要结合退信和邮件服务事件。

解决记录

步骤1：比较订单、order_item与两张invoice_item的qty、tax_amount、discount_tax_compensation_amount。

步骤2：自定义Invoice Total只计算本次可开票行，扣除已开票金额；不要重新按订单小计完整算一次。

步骤3：基础币种先计算并按Magento精度舍入，最后一张Invoice吸收舍入差，确保累计值等于订单。

步骤4：修复后用新测试订单验证；历史已发送发票按财务流程冲销重开，不直接改账务表。

命令与数据检查

SELECT increment_id,tax_amount,base_tax_amount,discount_amount,grand_total FROM sales_invoice WHERE order_id=:order_id ORDER BY entity_id;SELECT item_id,qty_invoiced,tax_invoiced FROM sales_order_item WHERE order_id=:order_id;

上线前验收

按1+1、1+2和最后剩余数量开票，所有Invoice累计税、折扣和总额与Order完全相等。

解决记录

步骤1：确认Source属于当前Website对应Stock，Source Item status启用，不能只看quantity。

步骤2：检查inventory.reservations.updateSalabilityStatus消费者是否持续运行，并查看退出异常。

步骤3：Consumer运行但单个SKU不更新时，比较SKU格式、队列消息和当前版本相关补丁。

步骤4：恢复Consumer后只修改一个测试SKU，观察消息消费和inventory_stock_X变化，再决定是否全量reindex。

bin/magento queue:consumers:list | grep inventory.reservations.updateSalabilityStatus
bin/magento queue:consumers:start inventory.reservations.updateSalabilityStatus --max-messages=100
bin/magento indexer:status inventory

上线前验收

连续修改数量与状态，无需手工全量索引即可在合理延迟内反映到前台，Consumer重启不重复改库存。

处理步骤

步骤1：对重复订单比较customer/guest、quote_id、支付transaction_id、remote_ip和created_at。相同Quote产生两单说明订单提交并发保护失效；不同Quote则先查前端是否重复创建购物车。

步骤2：前端在placeOrder Promise完成前禁用按钮并显示进度，失败时按明确错误恢复；不要在timeout后自动无条件重发。

步骤3：服务端以cart_id加支付attempt_id生成幂等键，在提交前原子占用。相同键再次到达时返回原订单结果，不再次调用网关。数据库要有唯一约束或可靠锁，不能只用进程内变量。

步骤4：支付回调按网关transaction_id幂等处理；创建Invoice、发送邮件和扣库存前检查是否已完成。已有重复单逐单核对支付后取消未付款单。

命令与数据检查

SELECT entity_id,increment_id,quote_id,customer_email,created_at FROM sales_order WHERE quote_id=:quote_id ORDER BY entity_id;
SELECT payment_id,txn_id,txn_type,created_at FROM sales_payment_transaction WHERE order_id IN (:order_ids);

上线前验证

使用浏览器双击、两个并发请求、客户端超时重试和重复Webhook测试，最终只能有一张订单、一次capture和一次库存扣减。

不要通过关闭客户重试来掩盖问题；幂等返回应让客户能拿到已经创建的订单号。

将预发布数据库恢复到生产或新增Store后，创建订单时报increment_id重复。订单号来自按Store维护的sequence表，不只看sales_order最大值。

确认出错订单的store_id以及对应sales_sequence_meta、sales_sequence_profile和sequence_order_N表。

比较sequence表当前AUTO_INCREMENT与该Store已有订单最大序号，先备份并暂停下单后再校正。

修复方法

• 数据库克隆脚本必须连同sequence元数据一起迁移；新增Store应通过标准流程创建对应sequence表。
• 不要直接修改历史订单increment_id绕过唯一键，外部ERP和支付已引用这些号码。

SELECT store_id,MAX(entity_id),MAX(increment_id) FROM sales_order GROUP BY store_id;SELECT * FROM sales_sequence_meta WHERE entity_type='order';SHOW TABLE STATUS LIKE 'sequence_order_%';

怎样才算解决

每个Store连续创建多张订单均唯一，Invoice、Shipment和Credit Memo各自序列也无冲突。

同一客户组在A站有折扣，B站不应有，但B站也显示A站价格。先核对价格作用域和原始高级价格行。

确认Catalog Price Scope是Website还是Global，并记录两个Store所属website_id。

查询website_id=0与具体Website的价格行；不需要的All Websites记录应通过正式接口删除。

修复方法

• 自定义价格插件从当前Store获取Website，不能写死默认站；缓存键需包含客户组和Store维度。
• 修复数据与代码后全量重建价格索引，客户退出重登并清FPC/GraphQL缓存。

bin/magento config:show catalog/price/scope
SELECT website_id,customer_group_id,qty,value FROM catalog_product_entity_tier_price WHERE entity_id=:entity_id;
bin/magento indexer:reindex catalog_product_price

怎样才算解决

同一SKU和客户组在两个Website分别显示各自价格，购物车、订单与API返回一致。

结账页新增门牌号或税号字段后，前端能填写，但shipping-information返回400，或订单地址里为空。必须把显示、传输和持久化三层分别验证。

确认customer_address属性backend_type、is_required和used_in_forms。结账使用的表单代码与后台客户地址不同，属性没有分配到正确form时Repository可能忽略。

在浏览器Network检查字段位于shippingAddress.customAttributes还是extension_attributes，并与后端插件读取路径一致。字段名必须和attribute_code完全相同。

SELECT attribute_id,attribute_code,backend_type,is_required FROM eav_attribute WHERE entity_type_id=(SELECT entity_type_id FROM eav_entity_type WHERE entity_type_code='customer_address');
SELECT * FROM customer_form_attribute WHERE attribute_id=:attribute_id;
bin/magento setup:di:compile

实际修复

• 声明extension_attributes.xml并生成代码；保存前把扩展属性复制到Customer Address/Quote Address，提交订单时再明确复制到Order Address。不要依赖任意数组自动落库。
• 非必填字段要允许null和空字符串；下拉字段提交option value而不是显示label。清generated并重新compile后测试。

怎样才算修好

测试访客新地址、登录客户新地址、已保存地址和账单地址同/不同四种路径，customer_address_entity、quote_address和sales_order_address值一致。

可执行检查

SELECT increment_id,base_grand_total,grand_total,shipping_amount,tax_amount,discount_amount,adjustment_positive,adjustment_negative FROM sales_creditmemo WHERE order_id=:order_id;SELECT txn_id,txn_type,parent_txn_id,is_closed FROM sales_payment_transaction WHERE order_id=:order_id;

通过标准：全额、部分、仅运费及重复回调测试中，Magento累计退款、网关累计退款和订单可退款余额完全一致。

可执行检查

SELECT website_id,all_groups,customer_group_id,qty,value,percentage_value FROM catalog_product_entity_tier_price WHERE entity_id=:entity_id ORDER BY website_id,customer_group_id,qty;
bin/magento indexer:reindex catalog_product_price

通过标准：访客、两个客户组、边界数量和两个Website只出现预期阶梯，购物车与商品页价格一致。

可直接执行的检查

SELECT entity_id,is_active,customer_id,items_count,items_qty,updated_at FROM quote WHERE entity_id IN (:guest_quote,:customer_quote);
SELECT quote_id,sku,qty,product_type FROM quote_item WHERE quote_id IN (:guest_quote,:customer_quote);

通过标准：测试客户原购物车为空和非空两种情况，同SKU与带自定义选项商品都覆盖；登录、退出再登录后只保留一个活动Quote且金额正确。

PWA/GraphQL还要确认客户端在登录后改用customerCart返回的新cart_id。

后台已允许缺货下单，商品页也显示可售，但加入购物车仍提示Requested qty is not available。需要同时检查Stock、Source和阈值配置。

固定复现范围

在当前Website对应Stock下查询is_salable与salable quantity，不能只看默认Source的quantity。

定位真实原因

核对Manage Stock、Backorders、Out-of-Stock Threshold及Use Config Settings；负阈值决定可继续销售的下限。

执行修复

检查可配置商品的实际子SKU配置，父商品设置不会覆盖子商品的库存选项。

恢复后处理

清理不一致Reservation并重建库存索引；自定义数量校验插件必须使用MSI服务而非旧StockItem数量。

bin/magento inventory:reservation:list-inconsistencies -rbin/magento indexer:reindex inventorySELECT sku,quantity,is_salable FROM inventory_stock_1 WHERE sku='SKU-1';

回归测试

数量跨越0和负阈值时行为符合设置，商品页、GraphQL加入购物车与后台订单结果一致。

给父商品或子商品换Attribute Set后，Edit Configurations为空，前台色板消失。Attribute Set变化不是单纯的界面分组调整。

固定复现范围

导出父商品超级属性列表，确认新Attribute Set包含同一attribute_id，而不是同名新属性。

定位真实原因

检查属性为Select、允许用于可配置商品，并确认每个子商品仍保存有效option_id。

执行修复

在副本商品先把缺失属性加入新Set、保存子商品值，再切换父子商品Attribute Set。

恢复后处理

重建EAV、configurable、价格和库存索引；若关联已删除，使用官方Link Management按已验证组合恢复。

SELECT product_id,attribute_id FROM catalog_product_super_attribute WHERE product_id=:parent_id;
SELECT attribute_set_id,attribute_id FROM eav_entity_attribute WHERE attribute_set_id=:new_set;
SELECT parent_id,product_id FROM catalog_product_super_link WHERE parent_id=:parent_id;

回归测试

后台组合数量与迁移前一致，前台每个选项映射唯一子SKU，后续保存不会再次丢组合。

订单明明更靠近华东仓，创建Shipment时Magento却推荐默认仓。先确认使用的是Priority还是Distance算法，二者需要的配置完全不同。

定位与修复记录

1. 固定复现范围

记录订单Website、stock_id、收货地址、SKU和推荐source_code。确认订单所属Website只绑定到预期Stock。

2. 确认真实原因

Priority算法按Stock配置中的Source顺序选择，不按Source名称或后台列表排序。重新拖动优先级并保存；禁用或无货Source会被跳过。

3. 执行修复

Distance Priority算法需要正确的经纬度、国家地区数据和距离提供者。地址缺邮编或Source坐标为空时可能回退。检查下载的geonames数据与API凭证。

4. 恢复后处理

如果ERP创建Shipment时自己传source_code，Magento推荐不会生效；修复ERP映射或在调用Source Deduction前使用正式Source Selection接口。

SELECT stock_id,website_id FROM inventory_stock_sales_channel WHERE website_id=:website_id;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku='SKU-1';
SELECT source_code,name,latitude,longitude,enabled FROM inventory_source;

验收清单

• 用两个仓都有货、首选仓缺货、部分数量不足三种订单测试；推荐、实际扣减和Shipment中的source_code必须一致。
• 不要通过直接改inventory_source_item数量来强迫选仓，这会破坏ERP库存事实。

实际处理步骤

1. 记录最后处理文件并用identify检查像素尺寸、色彩空间和文件是否损坏；小体积图片也可能解码占用数百MB。
2. 隔离超大或损坏原图，重新压缩后再上传；同时确认GD或ImageMagick版本及临时目录空间。
3. 在非高峰以单进程或受控批次执行，避免多个resize与部署任务同时争抢内存。
4. 调整CLI memory_limit后监控峰值RSS，生成完成再清理旧缓存，不能删除catalog/product原图。

检查命令

find pub/media/catalog/product -type f -size +20M -printidentify -format '%w %h %m %f\n' pub/media/catalog/product/x/y/image.jpgphp -d memory_limit=2G bin/magento catalog:images:resize

验证结果

全量命令正常结束，随机抽查各主题尺寸均可访问，日志无坏图且服务器未发生OOM Kill。

实际处理步骤

1. 为图片记录外部ID、内容SHA-256和Magento entry_id；不能只按文件名判断。
2. 上传前读取media_gallery_entries并比较外部ID或内容哈希；已存在则更新label、position和roles。
3. 一次业务上传使用稳定幂等键，结果未知时先GET核对，再决定是否重试，禁止并发重放。
4. 历史重复项先确认各Store图片角色，只删除内容相同且无独立角色的冗余entry，再重建图片缓存。

检查命令

GET /rest/V1/products/SKU/media
POST /rest/V1/products/SKU/media
# 客户端保存 external_image_id -> entry_id 与 sha256(content) 映射

验证结果

模拟服务器已保存但客户端超时，再重试同一图片；最终只有一个entry，图片角色和排序正确。

按顺序解决

1. 保存接口返回的bulk_uuid，并调用Bulk Status接口取得每个operation_key、status、result_message和serialized_data。先按错误类型分组。
2. 401、字段校验、SKU不存在等确定性错误先修数据；队列连接中断、死锁、临时超时才适合自动重试。不要把所有Rejected都当成瞬时故障。
3. 从原始业务数据按operation_key重建只包含失败项的新批次，不要直接执行数据库里的serialized_data。为每条业务操作保留外部幂等键，成功项不得重复创建资源。
4. 确认async.operations.all消费者正在运行；提交新批次后分别记录旧、新bulk_uuid，直到所有操作进入最终状态。

检查命令

bin/magento queue:consumers:list | grep async.operations.all
bin/magento queue:consumers:start async.operations.all --max-messages=500
curl -H 'Authorization: Bearer ***' 'https://shop.example/rest/V1/bulk/BULK_UUID/status'

验证结果

构造一条合法、一条字段错误和一条临时失败数据；修复后只重试后两条中的可重试项，已成功记录的updated_at和关联数据不应再次变化。

注意：生产脚本应设置最大重试次数和死信报告，避免毒消息无限循环。

排查路径

• 按报错的store_id和request_path查询全部记录，区分系统生成、分类路径、商品路径和自定义重定向。
• 检查两个商品或分类是否在同一Store生成相同url_key；同时核对URL后缀、分类路径开关和历史重定向。

落地修复

1. 先修正冲突实体的url_key或Store范围，再只删除可再生成的系统记录；保留is_autogenerated=0的人工重写。
2. 对目标商品/分类重新生成并清FPC，检查旧地址的301链不能循环。

SELECT url_rewrite_id,entity_type,entity_id,request_path,target_path,redirect_type,is_autogenerated FROM url_rewrite WHERE store_id=:store_id AND request_path=:path;SELECT entity_id,store_id,value FROM catalog_product_entity_varchar WHERE attribute_id=:url_key_attr AND value=:url_key;

完成标准

重复路径只保留一条有效目标，商品与分类保存成功，旧URL跳转一次后到正确新地址。

排查路径

• 导出一个已关联两个分类的商品，观察categories列对层级和多个分类的实际表达。
• 固定不同的路径分隔符和多分类分隔符；分类名包含分隔符时先改名或使用版本支持的转义。

落地修复

1. 确认导入所用根分类和目标Store根目录，路径字符串正确但根目录错误也会建到另一棵树。
2. 先用一个SKU试导并核对分类树；清理错误分类前检查商品关联和URL Rewrite。

SELECT c.entity_id,c.path,c.level,v.value name FROM catalog_category_entity c JOIN catalog_category_entity_varchar v ON v.entity_id=c.entity_id WHERE v.attribute_id=(SELECT attribute_id FROM eav_attribute WHERE attribute_code='name' AND entity_type_id=3) ORDER BY c.path;

完成标准

商品进入指定叶子分类且不创建多余根分类，面包屑、URL和分类商品数与导入文件一致。

解决方案

1. 在相同Store View下直接查catalog_product_entity对应backend表，确认目标entity_id、attribute_id、store_id确实有值；没有Store值时应验证是否正确回退到store_id=0。
2. 若使用ProductInterface扩展字段，Resolver不要从$model数组猜数据。用value中的model或Repository按当前Store读取，并处理简单、可配置、虚拟等商品类型。
3. 核对schema.graphqls的返回类型。属性是数组或对象却声明为String时，序列化会失败；Dropdown若需要文本，要通过选项源把option_id转为当前Store标签。
4. 清理config与GraphQL缓存，重新请求一个有值和一个无值商品。若Varnish/FPC参与GraphQL GET缓存，自定义Resolver还要返回正确Identity。

SELECT attribute_id,attribute_code,backend_type FROM eav_attribute WHERE attribute_code='vendor_code';
SELECT entity_id,attribute_id,store_id,value FROM catalog_product_entity_varchar WHERE attribute_id=:attribute_id AND entity_id=:entity_id;
bin/magento cache:clean config graphql full_page

回归测试

使用default与第二语言Store Header查询，同一SKU分别返回对应值；无值商品返回明确的null而不是导致整个products查询报错。

不要在每个商品Resolver里单独load一次实体，列表查询会形成N+1；批量加载或使用已提供的数据。

解决记录

步骤1：从异常堆栈和临时计数日志确认同一SKU、同一请求重复进入哪个Observer或Plugin。

步骤2：Observer中不要再次执行$product->save()；只改当前对象可在合适的before事件设置数据，跨实体写入改用Repository并加边界。

步骤3：确需二次更新时使用请求级guard并比较旧新值，只在值真正变化时执行；guard不能掩盖无限业务循环。

步骤4：检查aroundSave必须且只能调用一次proceed，修复后移除临时日志并重新编译。

命令与数据检查

rg -n 'catalog_product_save_|aroundSave|->save(' app/code# 临时记录sku、事件名与debug_backtrace摘要bin/magento setup:di:compile

上线前验收

单次保存只进入预期次数，CLI导入和后台保存都能完成，索引与扩展字段仍正确更新。

解决记录

步骤1：导出一个已有多选值的商品，以系统格式确认列名、标签和多值分隔符。

步骤2：CSV字段包含逗号时用双引号包裹；选项标签也含逗号时改用明确的多值分隔符并保持导入设置一致。

步骤3：核对目标Store选项标签的大小写、空格和语言，先创建缺失选项，避免导入器无法映射。

步骤4：用Validate Data检查Skipped Rows，先导入一个SKU并重新导出验证，再执行批量。

SELECT a.attribute_code,o.option_id,v.store_id,v.value FROM eav_attribute a JOIN eav_attribute_option o ON o.attribute_id=a.attribute_id JOIN eav_attribute_option_value v ON v.option_id=o.option_id WHERE a.attribute_code='features';

上线前验收

单值、多值、标签含逗号及第二语言Store均能完整保存，重新导出不丢值也不生成重复option。

处理步骤

步骤1：从服务器access log复制实际收到的完整query string，对比客户端发送内容。重点检查第一个参数后是否使用&，方括号是否被HTTP库二次编码。

步骤2：fields只描述返回结构，例如items[sku,name],total_count；searchCriteria仍是独立顶级参数。不要把&searchCriteria拼进fields值，也不要对整条URL一次urlencode。

步骤3：用curl的--get与--data-urlencode分别传参数，确认服务端解析结果。若curl正常、SDK异常，修复SDK的query builder而不是改Magento Repository。

步骤4：自定义接口还要确认方法参数名为searchCriteria且类型是SearchCriteriaInterface；实现层调用getList时必须传入收到的对象。

命令与数据检查

curl --get 'https://shop.example/rest/V1/products'   --data-urlencode 'searchCriteria[filter_groups][0][filters][0][field]=status'   --data-urlencode 'searchCriteria[filter_groups][0][filters][0][value]=1'   --data-urlencode 'searchCriteria[filter_groups][0][filters][0][condition_type]=eq'   --data-urlencode 'fields=items[sku,name,status],total_count'

上线前验证

确认total_count与不带fields时一致，items只保留指定字段；再测试空结果、第二页以及包含空格和加号的过滤值。

记录请求时隐藏Authorization头和客户数据，但保留原始参数顺序与编码形式。

REST创建客户地址时标准字段正常，自定义字段却返回Custom attribute is invalid。先核对属性实体、输入代码和前后台表单配置。

确认属性创建在customer_address实体而不是customer实体，并检查attribute_code拼写与数据类型。

请求体按custom_attributes数组提交attribute_code/value；多选值按接口要求传字符串或数组，不能直接发送后台标签。

修复方法

• 检查属性已加入正确Attribute Set/Group并允许用于相应表单；API写入还需Service Contract可见。
• 清EAV和config缓存后用GET读回地址；若只在某Website失败，核对客户Website与地址归属。

GET /rest/V1/attributeMetadata/customerAddressPOST /rest/V1/customers/123/addressesSELECT attribute_id,attribute_code,backend_type FROM eav_attribute WHERE entity_type_id=(SELECT entity_type_id FROM eav_entity_type WHERE entity_type_code='customer_address');

怎样才算解决

同一地址可通过REST新增、修改和清空该属性，后台打开后值一致，非法选项返回明确错误。

自定义REST接口传入items数组时，反序列化阶段报Class does not exist，业务方法甚至没有执行，根因通常在Service Contract类型声明。

接口DocBlock使用完整的\Vendor\Module\Api\Data\ItemInterface[]，参数名与JSON字段一致。

为Data Interface提供getter/setter，并在di.xml配置preference到实现类。

修复方法

• 不要只声明array后期待Magento推断内部对象，也不要把具体Model作为公共接口类型。
• 清generated和config缓存后重新compile，先用一个最小对象跑通，再增加嵌套数组。

/** @param \Vendor\Module\Api\Data\ItemInterface[] $items */
public function save(array $items);
# di.xml配置ItemInterface到Data实现类
bin/magento setup:di:compile

怎样才算解决

单个和多个对象都能反序列化为Data Interface；缺字段或错误类型返回明确400，Swagger结构正确。

客户CSV在验证阶段提示Invalid website_id，常见原因不是客户数据坏了，而是把Store ID、Store Code或旧环境的Website ID填进了新环境。

先导出一条当前环境的测试客户，确认该版本客户导入使用的网站字段名和格式。不要直接照搬另一套环境的数字ID。

查询store_website与store表建立映射。CSV若使用_website字段，填Website Code；若明确要求website_id，则填当前环境的数字ID。Default Website也不要凭经验假设为1。

SELECT website_id,code,name,is_default FROM store_website ORDER BY website_id;
SELECT store_id,code,website_id,is_active FROM store ORDER BY website_id,store_id;
SELECT email,website_id,COUNT(*) c FROM customer_entity GROUP BY email,website_id HAVING c>1;

实际修复

• 检查Customer Account Sharing Options。按Website共享时，同一email可存在于不同website；全局共享时，导入到第二个website会触发重复邮箱而不是website错误。
• 先用两行CSV验证：一个新客户、一个更新客户。验证通过后再批量导入，并保留Import History与失败行文件。

怎样才算修好

在目标Website前台分别执行登录、忘记密码和下单，后台客户记录的website_id、store_id与邮件域名均正确。

可执行检查

rg -n 'OrderInterface|extension_attributes|OrderRepository' app/code/VendorSHOW COLUMNS FROM sales_order LIKE 'external_reference';bin/magento setup:di:compilebin/magento cache:clean config

通过标准：保存后Repository get、getList、REST与后台页面读取同一值，未设置的历史订单返回约定的空值。

可执行检查

SELECT product_id,attribute_id FROM catalog_product_super_attribute WHERE product_id=:parent_id;
SELECT entity_id,attribute_set_id,sku,type_id FROM catalog_product_entity WHERE sku IN ('PARENT','CHILD-1');

通过标准：父商品variants包含新子SKU，前台每个属性组合唯一，价格和可售状态均来自正确子商品。

可直接执行的检查

SELECT COUNT(*) FROM catalog_category_product WHERE category_id=:category_id;
SELECT request_path,store_id,COUNT(*) c FROM url_rewrite WHERE entity_type='category' AND entity_id=:category_id GROUP BY request_path,store_id HAVING c>1;
rg -n 'catalog_category_save_(before|after)|->save(' app/code
bin/magento indexer:reindex catalog_category_product catalog_product_category catalog_url

通过标准：分别保存名称、描述、URL Key和100个商品关联；每项都在代理超时前完成，前台旧URL按配置跳转，新URL返回200且无重复重写。

若必须修改上万商品关联，优先拆分后台操作或使用受控批处理，不要让一个HTTP请求承担全部工作。

分类第一页和第二页出现同一SKU，或者翻到后面漏商品。常见原因不是pageSize，而是排序字段不唯一或翻页期间索引结果发生变化。

固定复现范围

保存每页返回的SKU、position和排序字段，使用同一Store、客户组、筛选及search参数复现。

定位真实原因

自定义Collection排序时追加entity_id等稳定的唯一次序；只按相同价格或相同position排序会导致数据库任意换序。

执行修复

确认客户端没有把currentPage从0开始，也没有在筛选变化后继续使用旧页码和旧结果。

恢复后处理

大量商品更新期间完成相关分类与价格索引后再做一致性验收，缓存键要包含排序和筛选变量。

query { products(filter:{category_id:{eq:"12"}},pageSize:20,currentPage:2,sort:{position:ASC}) { total_count items { sku } page_info { current_page total_pages } } }

回归测试

固定数据下连续读取全部页，SKU集合无重复无遗漏，总数与分类索引一致；同分值商品顺序保持稳定。

generateCustomerToken成功返回Token，紧接着查询customer却提示未授权。先确认第二个请求真的把同一个Token发送到了Magento，而不是先延长Token寿命。

固定复现范围

核对请求头为Authorization: Bearer TOKEN，Bearer与Token之间只有一个空格，不能包含引号或响应字段名。

定位真实原因

比较生成和使用Token时的域名、环境及Store Header；测试站Token不能在生产站使用。

执行修复

确认反向代理保留Authorization头，customer与customerCart响应不得进入公共缓存。

恢复后处理

确认客户账号启用且Website范围正确，修复后重新生成Token，不继续使用已吊销或错误环境的旧Token。

curl -sS https://shop.example/graphql -H 'Store: default' -H 'Authorization: Bearer ***' -H 'Content-Type: application/json' --data '{"query":"{customer{email firstname}}"}'

回归测试

同一Token可读取customer与customerCart；去掉头、错误Store或吊销Token时明确失败，且客户响应不会串会话。

Bundle详情页能勾选选项，但修改数量后总价不变。先区分后端选项价格是否正确，还是浏览器没有重新计算。

定位与修复记录

1. 固定复现范围

在页面源代码中找到 bundleConfig，确认选项ID、selectionID、基础价格和canApplyMsrp等数据存在。若这里价格已错，先重建 catalog_product_price 并检查子商品价格。

2. 确认真实原因

bundleConfig正确时，在Console观察数量输入框是否触发change。自定义主题若删除 data-selector、改写name或把输入框复制成另一个节点，Magento_Bundle/js/price-bundle就找不到原字段。

3. 执行修复

恢复核心模板中的data-role和name结构；自定义JS应触发标准change事件，不要直接修改页面上的价格文本。确认priceBox只初始化一次，避免两个组件互相覆盖。

4. 恢复后处理

清理目标主题静态目录并按实际语言重新部署，随后清FPC。不要只在developer模式下验证，因为生产合并后的RequireJS路径可能不同。

bin/magento indexer:reindex catalog_product_price
find app/design app/code -path '*Magento_Bundle*' -type f
rg -n 'price-bundle|bundleConfig|data-selector' app/design app/code
bin/magento setup:static-content:deploy -f zh_CN en_US

验收清单

• 依次测试单选、多选、可输入数量和默认数量；页面价、加入购物车后的item price以及订单金额必须一致。
• 固定价Bundle与动态价Bundle走的价格数据不同，排查时先确认商品Price Type。

实际处理步骤

1. 在浏览器Network或GraphQL日志中确认变量类型、字段名与schema完全一致，先排除前端根本没提交。
2. 给输入对象配置对应Input类型，在Resolver中把值写入Data Interface或Extension Attribute，不能只修改临时数组。
3. 检查extension_attributes.xml、接口getter/setter以及Repository保存插件；保存后重新从Repository读取，不直接依赖Model状态。
4. 清GraphQL与config缓存并重新编译，分别测试新增、修改、空值清除和权限不足。

检查命令

rg -n 'type .*Input|extension_attributes|setExtensionAttributes' app/code/Vendorbin/magento setup:di:compilebin/magento cache:clean config graphql

验证结果

Mutation响应与再次查询、REST读取及数据库结果一致，空值和非法值都有明确行为。

实际处理步骤

1. 使用与购物车相同的Store Header查询父SKU，从configurable_options.values读取uid和value_index，不要把attribute_id或option_id自行编码。
2. selected_options必须包含组成真实子SKU所需的全部超级属性；只传颜色、不传尺码时无法解析唯一变体。
3. 属性选项重建、环境迁移或Store切换后清除客户端保存的旧UID，再用本次products查询返回值提交。
4. 自定义选项应使用其自己的selected_options或entered_options UID，不能混入可配置属性UID。

检查命令

query { products(filter:{sku:{eq:"CONF-1"}}){items{... on ConfigurableProduct{configurable_options{attribute_code values{uid label value_index}} variants{product{sku}}}}}}

验证结果

有效组合可加入购物车且SKU对应正确子商品；缺属性、禁用子SKU和其他Store的旧UID必须明确失败。

按顺序解决

1. 先记录问题页面的 Store、Website、父SKU和被禁用的子SKU。确认子商品已启用、分配到同一 Website，并且必选属性值没有为空。
2. 检查 Website 绑定的 stock_id，再核对子SKU所在 Source 是否属于该 Stock、Source Item 的 status 是否为1。数量大于0但 status 为0仍会被判为不可售。
3. 查询 reservation 汇总；若存在取消或失败订单留下的负数，使用官方 list-inconsistencies 输出确认后再创建补偿，不要直接删除 inventory_reservation。
4. 修复来源或 reservation 后，只重建 inventory、configurable 与价格相关索引并清理 block/FPC；随后重新请求产品 JSON 配置，确认该 option 对应的 salableProducts 已恢复。

检查命令

SELECT stock_id,website_id FROM inventory_stock_sales_channel WHERE website_id=:website_id;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku IN ('CHILD-RED-S','CHILD-RED-M');
SELECT stock_id,sku,SUM(quantity) reserved FROM inventory_reservation WHERE sku='CHILD-RED-S' GROUP BY stock_id,sku;
bin/magento inventory:reservation:list-inconsistencies -r
bin/magento indexer:reindex inventory catalog_product_price

验证结果

用同一Store分别测试有货、无货两个子SKU；有货色板可选并能加入购物车，无货项仍保持禁用。再切换另一个Website，确认库存范围没有串站。

注意：如果数据库状态正确但只有某台Web节点异常，检查各节点 generated、静态资源版本和FPC是否一致。

判断：列出未更新的Indexer，确认它们是schedule模式；再查对应changelog是否增长以及indexer_update_all_views最近一次运行结果。

bin/magento indexer:show-mode
bin/magento indexer:status

复核：某个Indexer异常时，Cron可能继续处理其他任务，形成只更新部分的现象。修复后修改一条只影响该Indexer的测试数据，观察version_id推进。

完成标准

原问题可以稳定消失，相关边界场景仍能正常工作，而且不需要依赖手工清缓存或重复执行命令。

点击保存属性没有明确报错，Network里validate请求返回302并最终得到后台登录HTML。表单期待JSON，所以页面看起来像没有反应。

处理记录

检查重定向目标与Admin Cookie的Domain、Path、Secure和SameSite，并对比主表单请求是否使用同一后台路径。反向代理协议识别错误也可能造成域名跳转。

修复后validate应直接返回JSON，不经过登录页。再保存一个文本属性和一个下拉属性，确认两种验证路径都正常。

多节点站点还应在不同Web节点各请求一次，确认代码、缓存与共享文件一致；单台节点恢复不能代表整个站点已经恢复。

1. 序列化器根据getter生成字段。实现类若直接写成员变量，getter却从DataObject的另一个key读取，最终就是空；还要确认工厂创建的是正确实现类。
2. 比较Repository原始行、DTO调用setter后和返回前getter三个位置。先让一个字段跑通，再增加嵌套对象与数组。

检查命令

public function getCode();
public function setCode($code);

• 先在测试环境复现；
• 每次只改一个变量；
• 恢复后再检查日志没有产生新的异常。

避免误判

测试时固定同一个Store、客户状态和输入数据，并记录修改前后的请求与数据库结果，避免把作用域差异当成随机故障。

排查重点

检查Schema filter input、字段到真实attribute_code的映射，以及Filter Processor是否向集合加入正确条件。Dropdown还要分清传选项文本还是option_id。

{ products(filter: { vendor_code: { eq: 'A01' } }) { total_count items { sku name } } }

先在集合SQL中确认条件，再测试eq、in与match。不要返回全部商品后用PHP过滤，这会破坏分页并拖慢查询。

验收时要重新打开后台页面，并从前台或接口读取一次最终数据；只看到保存成功提示，不能证明缓存、索引和展示层已经同步。

判断：查询EAV值表是否仍有对应实体。若记录存在，检查删除事务与外键；若不存在，检查唯一校验插件是否维护自己的索引或缓存。

SELECT e.entity_id, e.sku, v.store_id, v.value FROM catalog_product_entity_varchar v JOIN catalog_product_entity e ON e.entity_id=v.entity_id WHERE v.attribute_id=:attribute_id AND v.value='SERIAL-001';

复核：不要直接关闭unique标记录入重复值。修复数据和删除流程后，完整验证创建、删除、重新使用同一值。

完成标准

原问题可以稳定消失，相关边界场景仍能正常工作，而且不需要依赖手工清缓存或重复执行命令。

管理员只改商品名称，保存时却提示无权修改Design Attributes，因为表单同时提交了页面布局、主题等设计字段。

处理记录

检查请求中的custom_design、page_layout、custom_layout_update与设计日期。用户不应修改时，字段应禁用并避免提交；业务确需修改时才补充最小必要ACL。

第三方表单Modifier也可能把隐藏字段重新加入payload。用管理员和受限角色分别保存同一商品，确认普通字段可改而设计字段仍受控。

多节点站点还应在不同Web节点各请求一次，确认代码、缓存与共享文件一致；单台节点恢复不能代表整个站点已经恢复。

1. 先查看HTML中的window.checkoutConfig是否包含quoteData。服务端已缺失时，检查自定义ConfigProvider或Plugin是否用自己的数组替换原结果，以及旧主题layout是否删除核心block。
2. HTML中有quoteData但JS读取不到，再查脚本执行顺序与CSP。修复后测试空购物车、访客购物车和登录客户。

检查命令

grep -Rni 'getConfig' app/code/*/*/Plugin app/code/*/*/Model

• 先在测试环境复现；
• 每次只改一个变量；
• 恢复后再检查日志没有产生新的异常。

namei -l pub/media/catalog/product/a/b/image.jpg
df -h pub/media

避免误判

测试时固定同一个Store、客户状态和输入数据，并记录修改前后的请求与数据库结果，避免把作用域差异当成随机故障。

排查重点

小组合成功而大组合失败，检查请求体大小、执行时间和重复选项；最小组合也失败，则检查超级属性是否为Dropdown且允许用于可配置商品。

若异常出现在图片角色保存，取消批量应用图片再试。修复后核对子商品数量、关联表与前台选项，不只看父商品是否保存成功。

验收时要重新打开后台页面，并从前台或接口读取一次最终数据；只看到保存成功提示，不能证明缓存、索引和展示层已经同步。

判断：检查自定义Observer是否调用flush或cleanType，以及Block的getIdentities是否返回过宽的全局标签。所有URL同时MISS通常是全量flush，只有商品和分类页MISS多为正常标签失效。

rg -n 'cacheManager->flush|cleanType|getIdentities' app/code

复核：记录保存前后的缓存标签与BAN请求，修正扩展后比较命中率。不要通过禁止商品变更失效缓存来换取命中率。

完成标准

原问题可以稳定消失，相关边界场景仍能正常工作，而且不需要依赖手工清缓存或重复执行命令。

索引器显示Ready且模式为Update by Schedule，商品改价后前台仍不更新。Ready不代表MView增量链路正常推进。

处理记录

检查mview_state.version_id、对应changelog、数据库触发器和indexer_update_all_views任务。changelog有数据但version_id不动，重点看index Cron与锁。

bin/magento indexer:show-mode
bin/magento cron:run --group index
bin/magento indexer:status

恢复后只修改一个测试商品，观察增量记录是否被消费。一次全量reindex成功不能证明定时增量已经修好。

多节点站点还应在不同Web节点各请求一次，确认代码、缓存与共享文件一致；单台节点恢复不能代表整个站点已经恢复。

1. 实现类必须实现同名getter和setter，di.xml的preference也要指向该实现。对象数组还需在DocBlock中声明正确接口类型。
2. 先用只含必填字段的请求跑通，再逐个增加字段。不要在控制器中静默忽略未知字段，否则客户端契约错误会进入业务层。

检查命令

public function getDeliveryNote();
public function setDeliveryNote($value);

• 先在测试环境复现；
• 每次只改一个变量；
• 恢复后再检查日志没有产生新的异常。

curl -sS https://shop.example/rest/all/schema -H 'Authorization: Bearer ***'

避免误判

测试时固定同一个Store、客户状态和输入数据，并记录修改前后的请求与数据库结果，避免把作用域差异当成随机故障。

排查重点

确认属性关联落在商品实际使用的Attribute Set，而不是Default Set；清理EAV和config缓存，再检查backend type与输入值是否匹配。

SELECT attribute_set_id, attribute_group_id, attribute_id FROM eav_entity_attribute WHERE attribute_id=:attribute_id;

不要在每次商品保存时动态加入属性。结构变更应在Patch中完成。用default scope和一个Store View各保存一次，可快速识别作用域问题。

验收时要重新打开后台页面，并从前台或接口读取一次最终数据；只看到保存成功提示，不能证明缓存、索引和展示层已经同步。

判断：从Network查看失败请求是404、403还是返回HTML。若路径落在自定义主题，检查旧版本复制的web/template/shipping.html；再核对RequireJS map和mixin。

find app/design app/code -path '*Magento_Checkout*shipping*.html'
bin/magento setup:static-content:deploy -f zh_CN en_US

复核：生产模式按实际locale重新部署，并确保所有Web节点使用同一release。修复后确认模板返回正确内容，再测试访客和登录客户。

完成标准

原问题可以稳定消失，相关边界场景仍能正常工作，而且不需要依赖手工清缓存或重复执行命令。

配送步骤已选中某个方式，点击下单仍报The shipping method is missing。不能只看页面状态，Magento最终验证的是Quote Shipping Address里的shipping_method。

处理记录

修改邮编、切换账单地址或应用优惠码都会重新收集rates。第三方承运商若在此时超时，旧方式从rates消失，前端却可能仍显示选中。

SELECT country_id, region_id, postcode, shipping_method FROM quote_address WHERE quote_id=:quote_id AND address_type='shipping';

记录carrier code、method code与重算前后的rate列表。修复后依次测试修改地址、切换币种和应用优惠码再下单。

多节点站点还应在不同Web节点各请求一次，确认代码、缓存与共享文件一致；单台节点恢复不能代表整个站点已经恢复。

1. 先在All Store Views记录三个角色，再逐个检查子范围；把目标范围角色改为No Image后保存，最后删除媒体记录并重建图片缓存。
2. 不要直接从pub/media删除文件。数据库引用仍在时，后台会继续认为图片存在，前台还可能产生404。批量操作前先用一个SKU验证。

• 先在测试环境复现；
• 每次只改一个变量；
• 恢复后再检查日志没有产生新的异常。

SELECT entity_id, attribute_id, store_id, COUNT(*) c FROM catalog_product_entity_varchar GROUP BY entity_id, attribute_id, store_id HAVING c > 1;

避免误判

测试时固定同一个Store、客户状态和输入数据，并记录修改前后的请求与数据库结果，避免把作用域差异当成随机故障。

排查重点

若数据库值刚保存就被改回，检查保存事件、Repository Plugin和同步模块；数据库已是新值但页面显示旧值，则清理EAV与配置缓存，并确认各后台节点使用同一缓存。

SELECT attribute_id, attribute_code, is_global FROM catalog_eav_attribute JOIN eav_attribute USING(attribute_id) WHERE attribute_code='vendor_code';

用一个无第三方插件的测试属性复现，再比较系统属性和自定义属性。这样能区分缓存、作用域与扩展代码问题。

验收时要重新打开后台页面，并从前台或接口读取一次最终数据；只看到保存成功提示，不能证明缓存、索引和展示层已经同步。

先看属性作用域与保存范围

切到目标 Store View，取消“使用默认值”后再保存 URL Key。若导入脚本总在 default scope 写入，它会覆盖不到店铺级值；反过来，错误的 store_id 也会产生看似存在却永远不被当前店铺读取的数据。

SELECT store_id, request_path, target_path, redirect_type
FROM url_rewrite
WHERE entity_type='product' AND entity_id=:product_id
ORDER BY store_id, request_path;

最终 URL 还受到商品 URL 后缀、是否包含分类路径、历史重定向和同店铺唯一性限制。不要只查 EAV 属性值。

验收矩阵

• 直接访问两个语言的新 URL 都返回 200；
• 旧 URL 只做一次预期 301；
• 切换语言不会落回默认 Store；
• canonical 指向当前语言的规范地址。

若批量改大量 URL Key，应先用少量 SKU 生成重写并检查冲突，再扩大范围。

SHOW FULL PROCESSLIST;
SELECT trx_id, trx_started, trx_mysql_thread_id, trx_query
FROM information_schema.innodb_trx
ORDER BY trx_started;

Ready 只说明 Magento 记录的索引状态，不代表某次被中断的 CLI、导入脚本或数据库会话已经提交。先定位最老事务对应的应用进程、主机和操作，再决定是否终止；不要看到 lock 就批量 kill 连接。

常见起因包括手工脚本开启事务后异常退出、部署时同时运行全量 reindex，以及监控工具长时间保持未提交查询。处理持锁会话后，单独执行价格索引并观察是否正常完成。

预防措施是给发布流程加互斥锁，避免商品批量更新与全量索引重叠；自定义脚本使用 try/finally 回滚。复测除了保存速度，还要检查价格、分组价和网站范围价格。

先看客户端缓存如何识别 CartItem。若查询返回的对象缺少稳定 ID，或 type policy 使用了错误 keyFields，Apollo 可能把新对象与旧对象当成两条记录。mutation 也可能没有返回页面实际读取的字段，导致缓存无法覆盖。

三种更新方式

• 让 mutation 返回购物车组件需要的完整字段；
• 在 update 函数中按稳定标识更新缓存；
• 对关键操作执行一次精确 refetch，而不是清空全部缓存。

若 mutation 响应本身就是旧数据，再回到 Magento Resolver、Cart ID 和后端缓存排查。修复后连续执行加数量、删商品、应用优惠码，不刷新页面也应与服务端结果一致。

画出同一时间的三种表示

1. 数据库字段：通常为 UTC；
2. 筛选输入：管理员看到的本地日期；
3. SQL 边界：转换后的 UTC 起止时间。

SELECT @@global.time_zone, @@session.time_zone, UTC_TIMESTAMP(), NOW();

自定义 UI Component 列若同时设置 date filter，又在 collection 的 addFieldToFilter 中手工减 8 小时，就会重复转换。结束日期还应覆盖本地当天的完整范围，而不是当天 00:00:00。

SELECT page_id, LENGTH(content), LEFT(content, 300)
FROM cms_page
WHERE page_id=:page_id;

先判断多余字符已经写进数据库，还是仅在后台编辑器显示。若数据库内容每次都变长，搜索自定义 CMS 保存 Plugin、Observer 和导入脚本中的 addslashes、json_encode、手工实体转换。

Page Builder 自己负责其内容格式。扩展如果先把 HTML 变成 JSON 字符串，再交给已经会序列化的层，就会编码两次。修复时从原始备份恢复一份页面，在进入 repository 前后各比较一次内容；不要对线上全部页面执行不加条件的 stripslashes，合法的代码示例也可能被破坏。

验收采用“打开—保存—再打开—再保存”两轮，数据库内容长度与前台渲染应保持稳定。

对比请求链路

• 加载结账页时使用的域名与提交域名是否一致；
• POST 是否带上同一个 Session Cookie；
• 结账 HTML 是否被 CDN 或错误的 Full Page Cache 缓存；
• 登录、切换店铺后页面里的 form_key 是否已刷新。

不要把完整 Cookie 或 token 贴进日志。可以在测试环境只记录 form_key 的哈希前几位和 Session ID 哈希，用来判断两次请求是否属于同一会话。

如果站点为了“恢复下单”直接关闭 Checkout Form Key Validation，风险会被转移而不是消失。应修正缓存排除、Cookie Domain 或前端取值逻辑。最后在访客、登录客户、跨 Store 切换和长时间停留后提交四种场景复测。

SELECT source_code, sku, quantity, status
FROM inventory_source_item
WHERE sku='SKU-001';

通过 SourceItemsSaveInterface 保存时，导入程序要明确设置状态；不要直接写表。还要确认 Source 已分配到当前 Website 使用的 Stock。若 status 和映射都正确，再检查库存索引以及未补偿的 Reservation。

本次修复在导入映射中加入“数量大于零并且 ERP 可销售”才设为 in stock 的业务规则。零库存、冻结库存、恢复库存三组样本都通过后才重新跑全量导入。

readlink -f /var/www/shop/current
ps -ef | grep php-fpm
php -i | grep -E 'opcache.validate_timestamps|realpath_cache_ttl'

使用 current -> releases/20260113 这类软链接发布时，PHP-FPM worker 可能继续持有旧 release 的真实路径或 OPcache 字节码。CLI 每次启动新进程，所以看起来已经更新。

正确动作是按部署方案平滑重载对应 FPM pool，让新 worker 接管；不要粗暴杀光进程造成正在结账的请求中断。若 OPcache 关闭时间戳校验，发布流程必须显式 reset 或 reload。

验证时在不泄露绝对路径的诊断端点记录 release 版本号，连续请求多次，确保负载均衡后的每个节点都返回同一版本。随后移除临时端点。

SVG 是 XML 文档，不只是“另一种图片”。它可能包含脚本、事件属性、外部资源和嵌入内容，因此 Magento 或安全模块拒绝它通常是有意设计。

可接受的处理方式

1. 优先把装饰图转换成 WebP 或 PNG；
2. 确需 SVG 时，只对指定后台字段或目录开放；
3. 在服务端做 SVG 清洗，移除 script、事件属性和外部引用；
4. 同时校验扩展名、MIME 与实际文件内容。

仅在前端 JavaScript 增加 .svg 后缀不会增加安全性，攻击者可以绕开浏览器直接请求上传接口。

放行后用普通图标、带脚本测试样本和伪装成 SVG 的文本各验证一次。安全样本应成功，危险与伪装文件必须被拒绝。

抓响应头而不是复制客户Cookie

curl -skD headers.txt -o /dev/null https://shop.example/customer/account/
awk 'BEGIN{IGNORECASE=1}/^Set-Cookie:/{print length($0),$0}' headers.txt

生产排查只统计名称与长度，不把完整 Cookie 值写进工单。重点找同名 Cookie 被多个 Path 或 Domain 重复设置，以及第三方模块把 JSON、追踪参数塞进响应头。

缓冲区调整只能基于测量

fastcgi_buffer_size 和 fastcgi_buffers 可以临时缓解，但无限加大掩盖了响应持续膨胀。先删除错误 Cookie 写入逻辑，再让受影响浏览器清理旧项。最后测试登录、退出、切换 Store 和加入购物车，确认头大小保持稳定。

SELECT url_rewrite_id, store_id, request_path, target_path, redirect_type
FROM url_rewrite
WHERE request_path IN ('shoes.html','cn/shoes.html')
ORDER BY store_id, url_rewrite_id;

排查时把每次响应的 Location 和 Store Cookie 记录下来。只看最终错误页会漏掉中间切换了哪个 Store View。

不要混淆三类规则

• 系统生成的商品、分类 canonical rewrite；
• 管理员创建的 301/302 重定向；
• Nginx、CDN 或语言切换模块的外层跳转。

同一个 request path 在不同 store_id 下可以有不同目标。清理冲突前先备份目标记录，不要按 request_path 跨店铺一把删除。重建后分别用无 Cookie、中文 Cookie、英文 Cookie 请求，确认每条链路最多发生预期的一次跳转。

第一刀：记录请求开始、数据库提交和响应结束时间。若数据库更新很早完成，后面的耗时多半在保存后的 Observer、Plugin 或同步接口。

grep -RniE 'catalog_product_save_(before|after)|catalog_product_save_commit_after' app/code
bin/magento dev:profiler:enable html

第二刀：在测试环境用相同商品和数据，逐个停用最近增加的模块。不要在生产环境随机关模块，也不要把 max_execution_time 调到十分钟后就宣布修好。

本次根因是 catalog_product_save_after 中同步调用远程 ERP，并且连接超时设为 90 秒。改为提交后写入队列，消费者负责重试；后台保存只记录任务 ID。复测简单、可配置、含大量图片三类商品，同时确认索引状态和 ERP 最终数据一致。

bin/magento queue:consumers:start async.operations.all --max-messages=1000

--max-messages 的目的就是让长驻 PHP 进程定期结束，释放累积内存并加载新代码。它完成 1000 条后以正常状态退出，不等同于崩溃。

若进程每处理一条就退出，才应检查消息异常、内存限制或消费者名称。验收时同时看退出码、处理数量和队列深度，不能只追求进程 PID 永远不变。

<extension_attributes for="MagentoSalesApiDataOrderInterface">
  <attribute code="warehouse_note" type="string" />
</extension_attributes>

如果插件实际给 warehouse_note 塞进数组，序列化阶段就会与声明冲突。返回对象列表时，类型应写成完整接口数组，例如 VendorModuleApiDataItemInterface[]，不能写实现类的随意缩写。

核对三处

1. extension_attributes.xml 的 for 与 type；
2. 插件调用的 setter、getter以及真实返回值；
3. 生成的 Extension 接口是否来自当前配置。

修正 XML 后重新编译并清理旧生成代码，再分别请求单对象与搜索列表接口。若操作具有写入副作用，还要检查客户端是否因 500 自动重试，避免同一业务被执行两次。

SELECT entity_id, increment_id, state, status, updated_at
FROM sales_order WHERE increment_id='000001234';

SELECT entity_id, increment_id, status, updated_at
FROM sales_order_grid WHERE increment_id='000001234';

若站点启用了异步 Grid 更新，保存订单后会由任务把数据同步到 sales_order_grid。先查对应消费者或 Cron 是否运行，再查队列积压；不要用定时 SQL 直接覆盖 grid 表，这会遗漏扩展增加的列。

只有一单异常

确认第三方模块是否绕过 Order Repository 直接更新数据库。直接 SQL 改 sales_order.status 不会触发正常保存链路。

所有新订单都延迟

检查异步配置、消息队列连接和消费者管理。修复后创建一张测试订单，观察详情与列表状态的时间差，并确认筛选、导出结果也已同步。

1. 用响应头判断返回 413 的服务器；
2. 检查入口代理、Nginx 虚拟主机和 location 覆盖；
3. 再核对 PHP-FPM 的上传与 POST 限制；
4. 最后确认 Magento 字段本身允许该扩展名和大小。

nginx -T 2>/dev/null | grep -n client_max_body_size
php-fpm -i | grep -E 'upload_max_filesize|post_max_size'
curl -i -X POST https://shop.example/rest/V1/vendor/upload   -H 'Authorization: Bearer ***' -F 'file=@sample.bin'

post_max_size 应大于实际 multipart 请求体，因为边界和其他字段也占空间。改完 Nginx 配置要 reload，改 FPM 配置要重载对应 pool。不要用无限制大小代替容量设计；API 仍应在业务层校验类型、尺寸并避免把整个文件长期留在内存。

判断依据

• 故障跟着后台用户走，而不是跟着浏览器走；
• Network 中 mui/index/render 请求返回正常结构；
• 页面控制台提示某个列名或筛选组件不存在。

ui_bookmark 会保存用户自己的列顺序、显示状态、过滤条件和视图。模块升级删除了一列，旧 bookmark 仍可能引用它。

SELECT bookmark_id, user_id, namespace, identifier
FROM ui_bookmark
WHERE user_id=:admin_user_id
  AND namespace='sales_order_grid';

先导出目标记录留档，只删除这个用户、这个 namespace 的 bookmark。重新打开列表后，Magento 会按当前 XML 创建默认视图。若所有管理员都坏，问题更可能在 UI Component XML、DataProvider 或集合查询；批量清整张表只会抹掉其他人的个人设置。

最常见的错误是复制了别的 Grid，把 selectProvider 的 namespace 留成旧值；也有人给 selectionsColumn 改名，却没有同步导出按钮。

<exportButton name="export_button">
  <settings>
    <selectProvider>vendor_item_listing.vendor_item_listing.columns.ids</selectProvider>
  </settings>
</exportButton>

清除配置与页面缓存后，用“无筛选、单个筛选、勾选部分记录”三种方式导出。CSV 行数和页面条件一致，才算修复完整。

No callbacks found for cron job vendor_sync

这里不是“Cron 没启动”，而是调度表里仍有旧 job code。Magento 读取当前合并配置时找不到它的 instance 和 method，于是无法执行。

SELECT schedule_id, job_code, status, scheduled_at
FROM cron_schedule
WHERE job_code='vendor_sync'
ORDER BY schedule_id DESC;

先确认新版本代码中确实没有同名 crontab.xml，并检查模块是否只是被临时禁用。若任务属于已永久卸载的扩展，可清理该 job code 尚未执行的历史行；不要直接清空整张表，以免误删正在运行的其他任务。

若同一个报错持续重新生成，说明配置缓存或某个节点仍保留旧代码。只删数据库记录不会解决。

多节点部署要比较各节点的 app/etc/config.php 和 release 目录，再清理配置缓存。下一轮 Cron 运行后应确认该 job 不再生成，其他任务的 success、missed 数量没有异常变化。

先确认 Magento 看到的地址

tail -f /var/log/nginx/access.log
cat var/.maintenance.ip
bin/magento maintenance:status

不要照抄“查询 IP”网站的结果。站点经过 CDN 或负载均衡时，源站可能看到代理地址；双栈网络还会优先使用 IPv6。白名单中的 203.0.113.10 与 ::ffff:203.0.113.10 也不是同一个字符串。

处理顺序

1. 从站点访问日志确认真实客户端地址；
2. 让受信代理正确覆盖真实地址 Header，不能信任任意来源；
3. 用 bin/magento maintenance:allow-ips 地址 写入；
4. 分别用 IPv4、IPv6 和手机网络复测。

如果运维层也配置了维护页，Magento 的白名单不会越过 Nginx 或 CDN 的拦截。此时应先判断 503 由哪一层返回，再改对应规则。

Limit of total fields [1000] has been exceeded

把上限从 1000 改成 5000 可能立刻成功，也可能让集群内存和 mapping 状态继续膨胀。先回答“这些字段为什么进入索引”。

查看实际Mapping规模

curl -s 'http://opensearch:9200/magento_product_*/_mapping' > mapping.json
curl -s 'http://opensearch:9200/_cluster/stats?filter_path=indices.mappings'

按属性代码统计字段，尤其找带随机后缀、Store ID、选项 ID 的动态字段。正常的 Magento 属性增长是可解释的；第三方扩展把 JSON 每个键展开成新字段，会让数量随商品数据无限增长。

属性配置也要做减法

检查大量历史属性是否仍被标记为可搜索、用于分层导航或参与搜索权重。禁用不需要的搜索用途不会删除业务数据，却能减少新索引文档和 mapping 负担。先在测试索引验证查询功能，再调整生产。

什么时候可以提高上限

确认字段都属于真实业务需要、节点有足够 heap、集群状态稳定时，可以适度提高 index 级限制，并记录容量依据。但它应与清理动态 mapping、属性治理一起完成。

Magento 重建索引通常创建新索引再切 alias。修复后确认新索引 mapping 数量下降、alias 已切换、旧索引按保留策略清理。最后测试全文搜索、筛选、多 Store 和增量更新；一次全量 reindex 成功不代表动态字段不会再次增长。

先看 Composer 正在访问哪个域名。Magento Marketplace、私有 Satis、GitHub 和公司 Git 需要的认证方式不同，不能把一对 key 填到所有仓库。

composer config --global --list --auth
composer diagnose
composer install --no-interaction --no-dev --prefer-dist -vvv

日志分享前删除 Authorization、token 和带凭据 URL。

CI里用受控秘密注入

把凭据放在部署平台的 Secret 中，通过 COMPOSER_AUTH 或构建时生成的临时 auth 配置提供；不要提交 auth.json 到 Git，也不要复制开发者的整个 Composer Home。密钥权限只覆盖需要的仓库，并设置轮换。

如果锁文件引用已经下线的私有 dist URL，即使 package 仍在缓存里，干净构建也会失败。用全新容器、空 Composer cache 执行一次 install，才能证明仓库与凭据完整。

最后验证非交互命令不会等待 stdin，失败时能快速返回明确的 401/403；成功构建产物中不包含 auth.json、环境变量转储或 Composer 调试日志中的秘密。

这不是“再创建一次订单”的场景

先用支付交易号确认订单已经存在。成功页通常从 Checkout Session 读取 last quote/order 信息；信息丢了，页面不能展示，不代表应该重新 submit quote。

按回跳时间线查

1. place order 后是否设置 last order ID；
2. 跳到支付域名前 Session Cookie 的 Domain、SameSite、Secure 是否允许返回；
3. return controller 是否提前 clearQuote 或清整个 checkout session；
4. webhook 与浏览器 return 是否竞争修改状态；
5. 自定义成功页 Block 是否从错误 session key 取值。

我会对比正常支付方式与问题支付方式的 Cookie 和重定向链。若只在跨域支付失败，优先查 SameSite/Secure 与 HTTPS 终止；若同域模拟也失败，就读支付模块 return action。

# 日志只记录哈希后的session标识、quote_id、order_id与request_id
place_order  quote=812 order=1042 session=ab12...
return       quote=?   order=?    session=cd34...

两段 session 标识不同，说明回跳没有带回原会话。标识相同但 order 为空，则是应用过早清理。

修复时让 webhook 负责幂等更新支付状态，让 return 只负责用户体验；成功页只读取已创建订单，不执行二次业务。验收覆盖成功、取消、浏览器关闭后仅 webhook 到达、return 与 webhook 乱序四种情况。每个支付交易只能对应一张订单。

数据库显示它的 backend_model 指向多年前扩展中的类。这个类在 beforeSave 中假定输入永远是逗号字符串，但新后台组件提交的是数组，于是把合法值当成非法。

SELECT attribute_id, attribute_code, backend_type,
       backend_model, source_model, frontend_input
FROM eav_attribute
WHERE attribute_code='external_codes';

排查顺序：

1. 保存请求里的原始类型；
2. UI组件是否把空值传成 []、null 或空字符串；
3. backend_type能否容纳转换后的值；
4. backend model是否仍存在且兼容当前PHP；
5. Store View保存时是否错误覆盖默认值。

不要直接在数据库里删除 backend_model 名称。它可能还负责序列化、唯一性或同步副表。应先为旧数据建立测试样本，再修改模型兼容数组/字符串并给出明确异常消息；如果确实不再需要，通过 Data Patch 安全迁移配置与现有值。

修复后测试新商品、已有商品、空值、多个值和 Store View 覆盖。再跑一次批量导入，因为导入调用同一属性后端模型，却不经过后台 UI 的数据整理。

先取证，再改变状态

bin/magento indexer:status
bin/magento indexer:show-mode
SELECT * FROM indexer_state WHERE status='suspended';
SELECT * FROM mview_state ORDER BY updated DESC;

按索引器更新时间向前查看 Cron、system、exception 和数据库日志。磁盘满、临时表空间不足、OpenSearch只读、数据库连接中断，都可能让任务被保护性挂起。

检查锁是否真的跨进程共享

Application Lock 配置错误时，一个索引任务可能认为已有实例运行，或者多节点同时处理同一 changelog。确认所有节点使用一致的锁提供方、前缀和后端；如果使用数据库锁，再检查长事务与连接中断。

恢复顺序

1. 停止制造积压或冲突的任务；
2. 修复磁盘、搜索集群、数据库或锁根因；
3. 记录 changelog 位置；
4. 只 reset 受影响索引器；
5. 低峰执行重建并观察下一个增量周期。

不要一上来 truncate changelog，它是增量索引的事实记录。验收不是 status 变 Ready，而是新增、改价、改库存都能由下一轮 Cron 推进版本，且 24 小时内不再进入 Suspended。

一次失败回调要保留什么

• 请求 ID、到达时间和来源 IP；
• 签名头名称与算法版本；
• 原始 body 的 SHA-256，仅在安全环境短期保留脱敏样本；
• 用于签名的时间戳；
• 代理是否解压、改写或转换编码。

不要在日志中输出密钥、完整银行卡数据或未经脱敏的请求体。

常见错误是先 json_decode()，业务处理后再 json_encode() 去算 HMAC。键顺序、斜杠、空白和 Unicode 转义任何一个变化，摘要都不同。签名必须用框架读取到的原始 body 按支付平台规定拼接。

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $received)) {
    throw new LocalizedException(__('Invalid signature.'));
}

示例中的拼接格式只是结构说明，实际必须严格使用该支付平台当前协议。

验证通过也不能直接处理两次

校验时间戳允许窗口，保存 event ID 并做唯一约束。平台重试同一事件时应返回成功但不重复开票、发货或改状态。密钥轮换期间可同时验证新旧密钥，但必须记录命中哪一把，并在窗口结束后移除旧密钥。

最终用官方测试事件验证：正常签名成功、改一个字节失败、过期时间戳失败、同一 event 重放不产生第二次业务动作。

我先用完全相同的 query 连续请求并记录响应头，再换 SKU、Store 和客户组。结果显示自定义字段被缓存，却没有关联到品牌实体的 cache tag。

Identity必须描述“这段结果依赖谁”

Resolver 返回品牌说明，它不仅依赖产品，还依赖品牌实体。只返回产品 ID 的 Identity，保存品牌时就不会让这份 GraphQL 结果失效。实现 Identity 时使用实体本身定义的缓存标签格式，避免自己拼出一个永远没人清理的字符串。

另一个维度是上下文：字段若按 Store View、客户组或币种变化，缓存键也要区分这些上下文。Identity负责实体变更失效，context负责不同请求之间不串数据，二者不能互相替代。

# 复现时保存两次响应与缓存头
curl -sS -D headers-1.txt -o body-1.json https://shop.example.com/graphql ...
curl -sS -D headers-2.txt -o body-2.json https://shop.example.com/graphql ...

修复后更新品牌实体，只清对应 tag，旧查询应返回 B；另一个无关品牌仍可保持命中。再用两个 Store 与两个客户组交叉测试，防止为了修“旧值”引入跨站或跨客户价格泄漏。

SQLSTATE[42S22]: Column not found: 1054 Unknown column 'supplier_name' in 'where clause'

显示值可能是 DataProvider 后处理出来的，或者 SQL 中只是 select alias。筛选器会把字段放进 WHERE，此时数据库需要知道它属于哪张表。

先看最终SQL

确认 supplier 表是否已 join、真实列名是什么、join 发生在 addFieldToFilter 之前还是之后。若真实字段是 s.name，把筛选映射到它：

$collection->addFilterToMap('supplier_name', 's.name');

映射应放在 collection/data provider 的合适位置，而不是在控制器里解析筛选参数。多个表都有 name 时必须带 alias，避免从 Unknown column 变成 Ambiguous column。

如果一件商品可能关联多个供应商，普通 join 会让 Grid 行重复，筛选和分页数量都不准确。这时要先决定展示规则：主供应商、聚合文本，还是子查询。不能只加 GROUP BY 压掉重复，因为 count SQL 和导出仍可能错。

验证范围

文本包含、精确值、空值筛选各测一次，再测试排序、分页、导出和 Mass Action。Grid 列“能看到”只是第一关，所有基于 collection 的动作都必须使用同一字段语义。

{"country_id":"US","region":"California","region_id":999}

文字看起来正确，但 999 并不是 US 下的 California。承运商和税务规则通常更信任 region_id，因此页面能展示不代表数据有效。

查字典与异常地址

SELECT d.region_id, d.country_id, d.code, n.name
FROM directory_country_region d
LEFT JOIN directory_country_region_name n ON n.region_id=d.region_id
WHERE d.country_id='US' AND (d.code='CA' OR n.name='California');

再筛出 country_id 与 region_id 所属国家不一致的客户地址。先导出清单并按客户确认，不能只根据 region 文本模糊匹配后批量写库；不同国家可能存在同名地区。

入口修复

CSV 导入、ERP 接口和自定义地址组件只能选择一种明确策略：有目录地区的国家传正确 ID；自由文本国家传 region 并让 region_id 为空。国家变化时必须清掉旧 ID，不能只更新文字。

历史数据通过受控脚本使用 Region Factory/Repository 映射并保存，保留变更日志。修复后验证账户编辑、默认配送地址、运费估算、税费和下单生成的 order_address 五处一致。

分清403是谁返回的

响应是 Magento 页面，先查客户、订单、链接购买记录和允许下载次数；响应是 Nginx 默认页，查 Web 服务器 location 命中。保存 access log 中的 URI 与最终内部重写路径：

curl -I -b cookies.txt 'https://shop.example.com/downloadable/customer/products/'
nginx -T | grep -n -A8 -B3 'downloadable|media'

不要把带签名或密钥的完整下载 URL 写进共享工单。

安全的请求链

1. 客户通过 Magento 路由发起下载；
2. 应用校验客户、订单状态、次数与链接有效性；
3. 校验通过后由应用流式输出，或通过内部重定向让 Nginx 发送文件；
4. 媒体真实目录仍禁止外部直接访问。

如果使用 X-Accel-Redirect，内部 location 必须标记 internal，应用生成的内部路径与 alias 要一致。容器部署还要确认 PHP 和 Nginx 看到的是同一挂载点。

文件权限只需让运行用户可读，不要 777。验收时分别使用已付款客户、未购买客户、达到下载次数的客户和直接文件 URL；只有第一种应成功。

Grouped 商品自己不承载可售数量，真正加入购物车的是用户输入数量大于零的子商品。模板改造后若输入框 name 丢了，页面看得到子项，POST 却没有 super_group，后台只会认为没有选择商品。

后端证据

用当前 Website 对应的 Stock 查询每个子 SKU 的 salable quantity，不要只看 Default Source。子商品被禁用、未分配到当前网站或只在另一个 Stock 可售时，父页面可能仍被缓存显示，但提交会失败。

然后用原生主题临时对照一次。如果原生主题可以加入，检查自定义模板是否保留 add-to-cart form、form_key 和数量字段；如果原生也失败，再查关联与库存。

修复后至少测试：只选一个子项、同时选两个、输入零、输入超过可售量，以及一个子项缺货。报错应准确落在失败子项，不能让一个缺货子项阻塞其他可购买子项。

先记录问题订单的 Store ID，因为 Sales PDF Logo 可以按网站或商店视图配置。再到生成 PDF 的那个节点检查真实文件，而不是在 Web 节点看：

bin/magento config:show sales/identity/logo
find pub/media/sales/store/logo -maxdepth 2 -type f -ls

如果发票由队列或 Cron 生成，Consumer 节点没有挂载同一份 pub/media，就会出现后台能看、邮件附件没图。另一个常见问题是文件扩展名为 PNG，实际内容却是 WebP，浏览器能识别，PDF 图片库不能。

我用三步收尾：重新上传一张标准 RGB PNG；确认 Web 与 Consumer 节点文件校验值一致；分别从后台下载和异步邮件生成 PDF。两份文件都出现 Logo，且不同 Store 使用各自配置，才算修复。

先确认重复的是文件、记录还是商店视图

SELECT mg.value_id, mg.value, mg.media_type,
       v.store_id, v.position, v.disabled
FROM catalog_product_entity_media_gallery mg
JOIN catalog_product_entity_media_gallery_value v
  ON v.value_id = mg.value_id
WHERE v.entity_id = :product_id
ORDER BY mg.value, v.store_id;

同一个 value_id 有多条 store 记录属于作用域数据，不一定重复；不同 value_id 指向不同后缀文件，才是反复新增。

同步代码不要每次都addImage

常见代码只判断远程 URL 是否变化，却没有按 Magento 中的规范化媒体路径找现有图片。URL 带时间参数、大小写不同或前导斜杠不同，比较都会失败。

我的修复是先计算稳定的源图片业务键，查询商品已有 Gallery，内容未变时更新 label、position、角色，不重新复制文件；内容改变才替换。同步任务重复执行两次，图库行数必须保持不变。

历史数据清理前先确认 image、small_image、thumbnail 是否引用准备删除的文件，并核对其他商品是否共享同一路径。不要按文件名后缀直接批量删。先在副本库生成保留/删除清单，后台抽查角色图，再通过服务层做清理。

修复后连续跑三次同步，并分别在 All Store Views 和一个子视图查看排序、标签和禁用状态。这样才能确认“去重”没有把商店级配置一起抹掉。

我用同一浏览器连续保存三类证据：HTML 文档请求、customer/section/load 请求、Cookie。结果是 HTML 可以公共缓存，客户姓名和购物车应由 private content 再加载；问题页面的 section/load 也被 CDN 缓存了。

快速判断

curl -sSI https://shop.example.com/
curl -sSI 'https://shop.example.com/customer/section/load/?sections=cart,customer'

• HTML HIT 不一定错；
• 带客户私有数据的 section 响应不应成为跨用户公共缓存；
• X-Magento-Vary Cookie 被代理删除，会让页面上下文失去区分；
• 把所有 Cookie 都加入 cache key 又会把命中率打到很低。

最终修改的是 CDN 对 private-content 路径的缓存规则，并恢复必要 Cookie 的转发。没有通过“登录页面全部 bypass”粗暴规避，因为那会让大量可缓存 HTML 失去价值。

验收用三个无痕会话：游客、客户A、客户B。三者请求同一商品页可以共享公共 HTML，但 customer-data 必须分别返回自己的姓名和购物车；退出登录后本地 section 也要被正确失效。

1. 两条记录是否拥有不同的 schedule_id？
2. 两台机器是否在同一秒启动？
3. 第一次是否仍在运行，第二次就开始了？
4. 外部接口是否因超时重试，而服务端其实已处理成功？

SELECT schedule_id, job_code, status, created_at,
       scheduled_at, executed_at, finished_at, messages
FROM cron_schedule
WHERE job_code='vendor_sync'
ORDER BY schedule_id DESC LIMIT 20;

三种常见根因

系统crontab重复：同一节点被 root 与 Magento 用户各配置一份，或旧发布目录的任务没有移除。

锁不共享：两台节点使用本地文件锁，各自都认为自己拿到了锁。多节点应使用项目支持的共享锁后端，并确认节点连接到同一数据库/Redis。

任务超过调度间隔：上一轮还没结束，下一轮又被标记为可执行。任务需要合理的超时、批次和互斥，而不是单纯把执行频率调低。

业务动作必须自己幂等

即使调度层只有一次，网络超时也可能触发重试。向 ERP 推送订单时应带稳定的业务键，让接收方识别重复；发送优惠券、扣款和库存更新更不能依赖“Cron理论上只跑一次”。

修复后连续观察至少两个完整调度周期。对照主机名、PID、schedule_id 和业务键，确认第二个进程拿不到锁时会安全退出，并且人为重放同一任务不会产生第二份业务结果。

SELECT patch_name FROM patch_list
WHERE patch_name LIKE 'Vendor\Module%';

只要类名已经在 patch_list，修改 apply() 后再运行也不会重放。

不要在生产库直接删除patch_list记录

删除记录会让原补丁从头再来。若它创建属性、移动数据或发送业务事件，不具备幂等性时可能产生重复选项、覆盖人工数据，甚至在中途失败。

正确方式是新建第二个补丁类，把“这次新增的变化”写进去，并通过 getDependencies() 声明它依赖第一个补丁。新环境会按顺序执行两个补丁，旧环境只执行新的一个。

补丁是已经发生过的数据库历史，不是可以随意改写的初始化脚本。

本地确实需要反复调试未发布补丁时，可以重建一次性开发数据库；不要把删除 patch_list 当成上线步骤。新补丁还应先判断目标状态，尽量做到重复运行也安全。

验收很简单：全新数据库安装一次，从旧版本升级一次，两条路径得到相同 schema 与数据；再次执行 setup:upgrade 不应产生额外变化。

前端组件不是事实来源。它只把 Quote Totals 中的一段数据显示出来；订单创建时并不会自动猜测哪个自定义 segment 需要持久化。

先查支付前 Quote 与创建后的 Order：

SELECT entity_id, grand_total, base_grand_total, custom_fee, base_custom_fee
FROM quote WHERE entity_id = :quote_id;

SELECT entity_id, grand_total, base_grand_total, custom_fee, base_custom_fee
FROM sales_order WHERE quote_id = :quote_id;

Quote 正确而 Order 为空，问题在字段声明或转换；Quote 自己就为空，前端可能只是临时拼了显示值。

金额字段必须同时处理基础币种与订单币种，并明确税前、税后及折扣顺序。只加到 grand_total 会造成明细和总额对不上；只保存展示币种会让多币种退款无法还原。

我会这样验收

• 费用适用与不适用的商品各下一单；
• 切换币种后核对 base/display 两组金额；
• 部分开票、部分退款，确认费用是否按设计分摊；
• 重复 collectTotals 不得把费用累加两次。

最后再看支付网关请求。如果 Magento 订单总额与网关捕获金额不同，不能只在后台补一列，而要重新核对费用进入 grand total 的时点。

我不先看资源模型，而是直接保存一次 Network 里的 POST。假设请求实际是：

general[name]=New Name

控制器却读取 $request->getParam('name')，拿到的自然是空值。页面回显来自 DataProvider，提交来自 UI Component；两条链路可以一条正确、一条错误。

四个名字必须形成同一条路径

1. form 的 namespace；
2. fieldset 的 dataScope；
3. field 的 source/dataScope；
4. DataProvider 返回数组的根节点。

如果 DataProvider 返回 [$id => ['general' => ['name' => 'A']]]，XML 与保存逻辑就应按 general.name 对齐。不要为了让页面显示而在 getData() 中复制两份值，这会把读取问题藏起来。

<item name="dataScope" xsi:type="string">general.name</item>

保存时先记录经过白名单后的 payload 键，不要记录敏感值。字段完全没进请求，查组件绑定；请求中有值但控制器读不到，查层级；控制器读到而数据库没变，再看 repository、resource model 和事务。

一个容易忽略的覆盖

prepareMeta()、Modifier Pool 或另一个模块可以在运行时改字段配置。浏览器中的 UI registry 才是最终结果，不能只看自己模块的 XML。修复后分别测试新建和编辑，因为两者的 provider 数据结构经常不同；再提交空值，确认系统按业务规则清空或拒绝，而不是悄悄保留旧值。

Deprecated: Creation of dynamic property VendorModuleModelClient::$token is deprecated

后面的 JSON 本身完全正确，但客户端从第一个字节开始解析，当然会失败。这类问题在 PHP 升级后很常见，根因是旧扩展动态创建属性；display_errors 又被误开，最终把诊断信息送给了 API 调用方。

应急处理

生产环境关闭错误直接展示，把错误留在 PHP-FPM 日志中。修改的是实际 FPM pool 使用的配置，不要只改 CLI 的 php.ini：

php --ini
php -i | grep -E 'display_errors|error_reporting'

CLI 输出只能帮助确认命令行环境。FPM 配置修改后需要平滑重载，并用接口再次确认 Content-Type 与响应首字节。

真正的修复

在报错类中声明属性并给出合适类型，或者升级扩展到支持当前 PHP 的版本。不要长期从 error_reporting 中屏蔽所有 Deprecated，因为同一批日志里可能还藏着下一次 PHP 大版本会直接失败的问题。

我会抽查 REST、GraphQL、后台保存和 Cron 四条入口：它们可能由不同 SAPI 或 pool 执行。验收标准是浏览器响应无杂字、日志能记录兼容性警告、修正后的模块不再产生该警告。

ACCESS_REFUSED - access to vhost '/' refused for user 'magento'

密码并没有写错。问题是运维创建了用户，也允许它登录 RabbitMQ 管理页，却没有给 Magento 实际使用的 vhost 授权。管理界面登录权限与队列读写权限不是一回事。

先把连接目标逐项对齐

查看 app/etc/env.php 中的 host、port、user、virtualhost 和 ssl，不要只验证账号。vhost 名称里的斜杠需要正确转义；集群环境还要确认每个 Web、Cron、Consumer 节点读取的是同一份配置。

rabbitmqctl list_vhosts
rabbitmqctl list_user_permissions magento
rabbitmqctl list_permissions -p /magento

如果 Magento 配置使用 /magento，授权也必须落在这个 vhost：

rabbitmqctl set_permissions -p /magento magento ".*" ".*" ".*"

生产环境应按实际交换机和队列缩小正则范围，上面的全权限更适合作为短暂验证。改完后重新启动一个消费者并观察是否能声明 exchange、写消息和 ack；只做到 TCP 连接成功还不够。

错误文本不同，排查方向也不同

• PLAIN login refused：优先检查凭据或认证方式；
• access to vhost refused：检查 vhost 是否存在及权限；
• NOT_FOUND - no queue：连接已经成功，继续查拓扑声明；
• TLS 握手失败：核对证书、端口与 ssl 配置。

最后我会发送一条测试消息，确认队列数量先增加再减少，并检查消费者日志没有继续重连。这样能证明权限覆盖了完整收发链路，而不是仅让报错暂时消失。

把三个resource ID并排对照

etc/adminhtml/menu.xml：

<add id="Vendor_Module::records"
     title="Records"
     module="Vendor_Module"
     sortOrder="20"
     parent="Magento_Backend::content"
     action="vendor_module/record/index"
     resource="Vendor_Module::records"/>

Controller：

class Index extends MagentoBackendAppAction
{
    public const ADMIN_RESOURCE = 'Vendor_Module::records';
}

etc/acl.xml 中也必须存在完全相同的 ID，并挂在合适的父资源下。大小写、下划线和模块前缀只要有一个字符不同，管理员就会被拒绝。

超级管理员能进，普通角色不能进，就刷新角色资源

修改 ACL 后执行：

php bin/magento cache:clean config

然后在后台重新保存一次角色权限，让新 resource 写入角色规则。不要直接修改 authorization_rule 表，因为层级变化后很容易留下错误授权。

用两个账号验证：超级管理员应能访问，受限角色只有勾选 Records 后才能访问；取消权限后再次请求应返回 Access denied。这样既证明功能可用，也证明 ACL 没被为了省事设置成过宽的父级资源。

先检查requirejs/require.js的请求状态

Network 过滤 require.js，看它是 404、403、HTML 响应还是被 CDN 返回了旧内容。如果响应 Content-Type 是 text/html，经常是静态资源没部署，Nginx 又把 404 fallback 到首页。

确认文件：

pub/static/frontend/Vendor/theme/zh_Hans/requirejs/require.js

并检查页面 source 中 require.js 是否出现在依赖它的 bundle 之前。

暂时关闭合并功能定位，不要直接长期绕过

如果启用了第三方 JS 合并、defer 或 CDN 优化，先在测试环境关闭它，重新部署：

php bin/magento config:set dev/js/merge_files 0
php bin/magento config:set dev/js/enable_js_bundling 0
php bin/magento setup:static-content:deploy -f   --theme Vendor/theme zh_Hans
php bin/magento cache:flush

恢复后再逐项打开优化配置，找出哪个步骤改变了脚本顺序。Cloudflare Rocket Loader 一类功能也要对 Magento 的 RequireJS 页面排除。

最后用无痕窗口打开首页、商品页和 checkout，确认 require 在第一个自定义模块执行前已经存在，并检查所有静态 JS 都返回 200，而不是只看到结账界面出现就结束。

先查看邮件原文里的img src

不要只看邮件客户端渲染。查看原始邮件，找到：

<img src="/media/wysiwyg/mail/logo.png">

这就是问题。模板里用 Magento 指令生成绝对地址：

<img src="https://www.360magento.com/media/wysiwyg/mail/logo.png" alt="Store">

主题静态资源则用：

<img src="{{view url='images/email/logo.png'}}" alt="Store">

检查生成出来的是不是内部域名

如果最终地址是 http://nginx/media/... 或内网主机名，说明 Store View 的 Base URL 或反向代理协议仍有问题。用实际发送邮件所属的 Store View 检查 secure/unsecure Base URL，而不是只看 Default Config。

图片 URL 还必须允许公网匿名访问，不能依赖后台 Cookie，也不要被防盗链规则按 Referer 拦截。发一封测试邮件后，从无登录状态的浏览器直接打开邮件原文中的完整图片 URL；返回 200 且 Content-Type 正确，邮件客户端才有机会正常显示。

先把失败请求里的filters参数留下来

在 mui/index/render 请求中找到 filters[created_at][from] 和 to，再把 collection 生成的 SQL 打到日志：

$this->logger->debug((string) $collection->getSelect());

如果 join 的两张表都有 created_at，给 filter 建立明确映射：

$collection->addFilterToMap('created_at', 'main_table.created_at');

Grid XML 中也让列名对应 collection 可过滤字段，不要显示别名 A，却让 DataProvider 对不存在的别名 B 做 WHERE。

日期列的dataType和timezone要按存储值设置

Magento 数据库里的标准时间通常按 UTC 保存，UI 日期列可配置：

<column name="created_at" class="MagentoUiComponentListingColumnsDate">
    <settings>
        <filter>dateRange</filter>
        <dataType>date</dataType>
        <label translate="true">Created At</label>
    </settings>
</column>

如果字段保存的是商店本地时间或纯日期，就不要照抄带时区转换的配置。测试时用跨午夜的数据，分别筛选单日和跨日范围，检查边界记录是否被错误排除。SQL 不报错只是第一步，日期范围与后台显示的时区一致才算完成。

先确认当前模式和维护状态

php bin/magento deploy:mode:show
php bin/magento maintenance:status

自定义错误皮肤放在：

pub/errors/mytheme/503.phtml
pub/errors/mytheme/css/styles.css

并创建 pub/errors/local.xml：

<?xml version="1.0"?>
<config>
    <skin>mytheme</skin>
</config>

在生产模式下再验证503响应

php bin/magento deploy:mode:set production
php bin/magento maintenance:enable
curl -I https://shop.example.com/

应返回 503，并显示自定义页面。不要只在浏览器看，因为 CDN 可能缓存旧的 500/503 页面。还要测试白名单 IP：

php bin/magento maintenance:allow-ips 203.0.113.10

白名单来源如果经过代理，Magento 看到的客户端 IP 可能不是你的公网 IP，需要同时核对可信代理和转发头。验证完成后执行 maintenance:disable，再确认首页恢复 200。

先在OpenSearch里看alias和index是否同时存在

curl -s 'http://opensearch:9200/_cat/aliases?v'
curl -s 'http://opensearch:9200/_cat/indices?v'

正常情况下，Magento 使用的 alias 应指向一个存在且 health 正常的索引。若 alias 指向的索引刚被外部清理任务删除，应用查询会失败；若多个部署同时重建，也可能出现别名切换竞争。

对照Magento日志里的真实索引名

打开搜索请求对应的 exception.log，记录 index_not_found_exception 或 429 的索引名，再检查配置：

php bin/magento config:show catalog/search/engine
php bin/magento indexer:status catalogsearch_fulltext

确认不同环境没有共用同一个 OpenSearch index prefix。测试、预发布和生产共用前缀时，一个环境重建或清理会误伤另一个环境。

修正前缀或外部生命周期策略后，只让一个发布任务执行完整 reindex：

php bin/magento indexer:reindex catalogsearch_fulltext

随后再次查看 alias，确认它稳定指向新索引，并连续请求多个关键词。不要把“重建一次恢复”当永久修复，必须找到是谁删除索引或抢着切 alias。

对着404地址检查原图和缓存图

假设页面请求：

/media/catalog/product/cache/.../a/b/abc.jpg

先找原图：

find pub/media/catalog/product -path '*a/b/abc.jpg' -ls

原图不存在，就看保存商品时的 exception.log，以及 PHP-FPM 用户是否能写 pub/media/catalog/product。原图存在而 cache 路径没有，则测试：

php bin/magento catalog:images:resize

权限要按运行用户修，不要chmod 777

确认 CLI 用户、PHP-FPM 用户和部署用户的组关系，再设置目录组写权限与 setgid。例如实际用户组为 www-data 时：

chgrp -R www-data pub/media
find pub/media -type d -exec chmod 2775 {} +
find pub/media -type f -exec chmod 664 {} +

命令里的用户组必须按服务器实际情况调整。还要确认 ImageMagick/GD 可用，以及 Nginx 的 /media/ 规则没有把不存在的缓存图直接永久缓存成 404。

最后重新保存同一商品，确认原图已移动、resize 命令无异常、前台缩略图 200。只清浏览器缓存而没检查文件落盘，不算修好。

用最小请求对比直连和域名

curl -i   -H 'Authorization: Bearer YOUR_TOKEN'   https://shop.example.com/rest/V1/store/storeViews

如果直连 PHP-FPM 前的测试正常，而走 Nginx/Apache/CDN 失败，检查 Web Server 是否丢了认证头。PHP-FPM 常见配置是：

fastcgi_param HTTP_AUTHORIZATION $http_authorization;

Apache 环境则确认 rewrite 或 FastCGI 配置没有清掉 Authorization。

头已收到再查Integration权限

后台打开对应 Integration，确认 API Resources 里勾选了实际 endpoint 需要的 ACL；更改资源后重新激活并使用新 Token。自定义 webapi.xml 的 resource 也要指向真实存在的 acl.xml ID：

<resources>
    <resource ref="Vendor_Module::api"/>
</resources>

401 多半是认证失败，403 更像已识别身份但没有权限。结合 var/log/exception.log 与响应码判断，不要把所有问题都归到 ACL。最终分别测试一个公共接口和目标受限接口，确认 Token 被识别且只有授权范围内的资源能访问。

先确认配置状态而不是只看app/code目录

php bin/magento module:status Vendor_Module
grep -n "Vendor_Module" app/etc/config.php

再搜索到底是谁还引用旧类：

rg "Vendor\Module" app/code app/etc vendor/composer

有时另一个自定义模块在 di.xml、构造函数或 preference 中仍依赖被禁用模块，这种情况下重新编译也应该失败，不能靠删生成代码掩盖。

确认没有真实依赖后再重建DI

维护窗口内执行：

php bin/magento maintenance:enable
rm -rf generated/code/* generated/metadata/*
php bin/magento setup:di:compile
php bin/magento cache:clean config
php bin/magento maintenance:disable

多节点环境要在构建阶段生成一次，再把同一 generated 产物发布到所有节点，不能只清当前机器。验证时用 setup:di:compile 的成功退出码作为第一道标准，再请求原报错页面，确认日志没有继续加载旧 Proxy。

先看js-translation.json里有没有这句话

打开当前 locale 的：

pub/static/frontend/Vendor/theme/zh_Hans/js-translation.json

搜索英文原文。没有的话先确认 CSV 编码为 UTF-8、引号正确，并位于主题或模块的 i18n/zh_Hans.csv。

前端 JS 必须这样调用：

define(['mage/translate'], function ($t) {
    'use strict';
    return $t('The requested quantity is not available.');
});

字符串拼接会导致字典匹配失败，动态变量用占位符，不要先拼成完整英文。

删除当前locale的字典后重新部署

rm -f pub/static/frontend/Vendor/theme/zh_Hans/js-translation.json
php bin/magento setup:static-content:deploy -f   --theme Vendor/theme zh_Hans
php bin/magento cache:clean translate full_page

浏览器里还要清 mage-translation-storage 和 mage-translation-file-version，否则 Local Storage 会继续使用旧字典。刷新后在控制台执行 $.mage.__('英文原文') 或通过模块加载 mage/translate 验证返回值，再检查结账实际提示。

在DevTools里反查实际CSS文件

选中元素，看命中的 CSS URL，例如：

/static/version123/frontend/Vendor/theme/zh_Hans/css/styles-l.css

这里已经告诉了当前 area、theme 和 locale。部署时如果只生成了 en_US，中文 Store View 当然还在用旧文件或直接 404。

只清当前主题的生成结果再部署

先确认当前主题继承关系没有写错，然后执行：

rm -rf pub/static/frontend/Vendor/theme/zh_Hans
rm -rf var/view_preprocessed/pub/static/frontend/Vendor/theme
php bin/magento setup:static-content:deploy -f   --area frontend --theme Vendor/theme zh_Hans
php bin/magento cache:clean full_page

不要删除 pub/static/.htaccess。多节点部署时还要确认静态资源是共享存储，或者同一构建产物已经同步到每个节点；否则刷新几次时新旧样式会交替出现。

最后直接打开生成后的 styles-l.css 搜索刚改的规则，再回到页面确认响应命中的是这份文件。如果文件里都没有规则，问题在 LESS 编译或主题继承；文件里有但页面没用，才继续查 CDN、FPC 和选择器优先级。

在登录请求里对比Set-Cookie和下一跳Cookie

Network 里看后台登录 POST 响应有没有 Set-Cookie: admin=...，然后看随后的 dashboard 请求是否带上同一个 Cookie。没带时检查四项：

• Cookie Domain 是否写成了旧域名。
• Cookie Path 是否限制在错误的后台路径。
• 前端实际是 HTTPS，但 Magento 认为当前请求是 HTTP。
• SameSite / Secure 属性是否与浏览器访问方式冲突。

让代理把真实协议传给Magento

Nginx 反代至少要正确传递：

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

如果 TLS 在负载均衡终止，后端 $scheme 可能永远是 http，这时应使用上游提供的协议头，不能盲目硬编码。Magento 的 Secure Base URL 也要与用户实际访问地址一致。

配置修正后清理旧浏览器 Cookie 再测。只清 Magento 缓存往往没用，因为浏览器还在带旧 domain/path 的会话。登录后连续打开三个后台页面并观察 session Cookie 没有变化、请求不再 302 回 login，才表示代理协议和 Cookie 已经对齐。

用报错里的request_path直接查

假设冲突路径是 sale.html：

SELECT url_rewrite_id, entity_type, entity_id, request_path,
       target_path, redirect_type, store_id, is_autogenerated
FROM url_rewrite
WHERE request_path = 'sale.html';

一定要带 store_id 看。不同 Store View 可以有同名路径，但同一个 store 内不能有两条相同 request_path。

再确认这条记录对应的商品或分类是否还存在：

SELECT entity_id, parent_id, path
FROM catalog_category_entity
WHERE entity_id = 42;

先判断是正常占用还是孤儿记录

如果路径已被另一个有效分类使用，就应该改当前分类 URL Key，而不是删 rewrite。只有确认 entity 已不存在、路径是迁移残留时，才考虑先备份该行再清理。

自动生成的分类 URL Rewrite 可以通过重新保存实体或相关索引恢复，但自定义 301 跳转不能随便删。生产库操作前先导出冲突行：

SELECT * FROM url_rewrite
WHERE url_rewrite_id = 1234;

清理后保存分类，再访问新路径和旧路径各一次，确认新地址 200、需要保留的历史地址仍按预期 301，而不是只看后台“保存成功”。

先用最短路径排除目录层级问题

etc/frontend/routes.xml：

<router id="standard">
    <route id="vendor_module" frontName="tools">
        <module name="Vendor_Module"/>
    </route>
</router>

访问 /tools/ping/index 时，类应是：

VendorModuleControllerPingIndex

文件为：

app/code/Vendor/Module/Controller/Ping/Index.php

Linux 文件系统区分大小写。目录写成 controller/ping，本机 macOS 可能没事，上服务器就会 404。

action类要满足当前版本的接口要求

class Index implements MagentoFrameworkAppActionHttpGetActionInterface
{
    public function __construct(
        private MagentoFrameworkControllerResultJsonFactory $jsonFactory
    ) {}

    public function execute()
    {
        return $this->jsonFactory->create()->setData(['ok' => true]);
    }
}

如果这是 POST 接口，则实现 HttpPostActionInterface，并处理 Form Key 或明确实现合适的 CSRF 逻辑。不要为了让请求通过就全局关闭 CSRF。

再运行：

php bin/magento module:status Vendor_Module
php bin/magento cache:clean config

先让最短的 JSON Action 返回，再逐步加依赖和业务逻辑。这样能清楚区分“路由没命中”和“Controller 构造失败后被错误页接管”。

在请求里看selected传来的到底是什么

Network 中打开 Mass Action 请求，正常应包含：

selected[]=12
selected[]=15
excluded=false

如果 selected 是空，先对比 storageConfig、selectionsColumn 和主键字段：

<storageConfig>
    <param name="indexField" xsi:type="string">entity_id</param>
</storageConfig>

<selectionsColumn name="ids">
    <settings>
        <indexField>entity_id</indexField>
    </settings>
</selectionsColumn>

数据源返回的每条 item 也必须包含 entity_id。数据库主键叫 rule_id，XML 却抄成 entity_id，页面仍会显示勾选框，但前端没有稳定的行 ID。

控制器别自己拼where in

批量操作用 MagentoUiComponentMassActionFilter 处理“选择全部”和 excluded：

$collection = $this->filter->getCollection(
    $this->collectionFactory->create()
);

foreach ($collection as $item) {
    $item->setIsActive(false)->save();
}

这样既支持逐条勾选，也支持跨页“全选后排除几条”。修完后分别测试选两条、全选当前页、Select All，再看真正被修改的 ID 是否一致，避免页面不报错但误处理整张表。

先在控制台确认目标模块有没有注册mixin

打开页面后执行：

require.s.contexts._.config.config.mixins

找到目标模块，例如：

Magento_Checkout/js/action/place-order

如果这里没有你的 mixin，问题在 requirejs-config.js 的位置、作用域或模块名，而不是 mixin 函数本身。前台文件应放在：

app/code/Vendor/Module/view/frontend/requirejs-config.js

后台则是 view/adminhtml，全局才用 view/base。

模块名要写AMD名称，不要写磁盘路径

var config = {
    config: {
        mixins: {
            'Magento_Checkout/js/action/place-order': {
                'Vendor_Module/js/action/place-order-mixin': true
            }
        }
    }
};

Mixin 文件返回的函数还要包住原目标：

define([], function () {
    'use strict';
    return function (target) {
        return target.extend({
            // override here
        });
    };
});

如果目标导出的是普通函数而不是 UI Component，就要返回一个包装函数，不能机械地 target.extend()。

生产模式下重新部署对应 area、theme 和 locale 的静态资源，然后清浏览器缓存。最后不仅要看到 mixin 文件 200，还要在 mixins 配置中看到它，并确认目标方法确实走进覆盖逻辑。

先在浏览器里把UI组件日志打开

控制台执行：

require([
    'Magento_Ui/js/lib/logger/console-logger',
    'Magento_Ui/js/lib/logger/levels-pool'
], function (logger) {
    logger.setDisplayLevel(5);
});

刷新页面后，重点看 provider、deps 或 columns 组件未加载的警告。这比只看 var/log 快，因为 XML 能通过服务端解析，不代表前端组件名能对上。

把provider、dataSource和spinner三个名字逐字对齐

一个可工作的结构至少要保证：

<item name="provider" xsi:type="string">
    vendor_module_listing.vendor_module_listing_data_source
</item>
<item name="spinner" xsi:type="string">vendor_module_columns</item>

并且下面真实存在同名的：

<dataSource name="vendor_module_listing_data_source" component="Magento_Ui/js/grid/provider">
    <settings>
        <updateUrl path="mui/index/render"/>
    </settings>
</dataSource>
<columns name="vendor_module_columns">

Grid 不要直接复用编辑表单的 DataProvider。列表需要返回 items 和 totalRecords，Collection 还要正确注册到 CollectionFactory。Network 虽然是 200，但返回结构不对时，provider 仍然无法完成初始化。

修改后清 config、layout 缓存，删除浏览器 Local Storage 中这个 listing 的旧 bookmark 再测试。看到 mui/index/render 返回正确 JSON、Loading 消失并能翻页，才算真正修好。

先确认报错用的是旧masked_id还是新quote_id

在浏览器 Network 里看失败的 GraphQL 或 REST 请求。如果请求里还是登录前的 maskedCartId，再查：

SELECT quote_id, masked_id
FROM quote_id_mask
WHERE masked_id = '请求里的ID';

然后确认对应 quote 是否仍然 active：

SELECT entity_id, customer_id, is_active, updated_at
FROM quote
WHERE entity_id = 12345;

如果登录后生成或激活了另一个 customer quote，旧 masked ID 继续请求自然会找不到有效购物车。

登录完成后必须让checkout重新取customer-data

自定义登录弹窗或单页应用最常漏掉这一段：登录成功只改了页面上的用户状态，却没有失效 cart、customer 等 section，也没有重新初始化 checkout。

define(['Magento_Customer/js/customer-data'], function (customerData) {
    'use strict';
    customerData.invalidate(['customer', 'cart']);
    customerData.reload(['customer', 'cart'], true);
});

如果是 Headless 前端，登录或合并购物车成功后要丢弃旧 cart token，以服务端返回的新 cart ID 为准。不要捕获异常后无限重试原 ID，那只会把同一个无效请求打很多遍。

验证时打开两个标签页复现完整过程：游客加购、打开结账、另一页登录、回到结账。页面应主动重新加载购物车，而不是继续提交旧 masked ID。

先让Magento自己报出可售数量

不要只查 inventory_source_item.quantity。先运行：

php bin/magento inventory:reservation:list-inconsistencies -r

再用 SKU 查可售数量。不同版本可用的 CLI 命令并不完全一致，我一般直接在一个临时 PHP 脚本里调用 GetProductSalableQtyInterface，并明确传入当前 website 对应的 stock ID。这样能避免查错库存范围。

数量有货但salable为0，就逐项对账

我会按这个顺序看：

1. 当前 Website 是否真的分配到了这个 Stock。
2. Stock 下是否包含保存该 SKU 的 Source。
3. Source Item 的状态是不是 In Stock，不是只看 quantity。
4. Out-of-Stock Threshold 是否大于或等于现有数量。
5. inventory_reservation 里是否残留了没有补偿回来的负数。

查 reservation：

SELECT stock_id, sku, SUM(quantity) AS reserved
FROM inventory_reservation
WHERE sku = 'TEST-SKU'
GROUP BY stock_id, sku;

不要直接删表里的 reservation。先用 list-inconsistencies 找异常订单，再生成补偿：

php bin/magento inventory:reservation:list-inconsistencies -r |
php bin/magento inventory:reservation:create-compensations

处理完重新索引 inventory，再用同一 website、同一 SKU 查询 salable quantity。只有接口返回值恢复并且前台实际能加入购物车，才说明不是表面上“改了库存”，而是可售库存链路真的恢复了。

不看页面提示，先在Network里找catalog/product/save

正常保存大致会看到这几步：

catalog/product/validate  200
catalog/product/save      302
catalog/product/edit      200

出问题时则是：

catalog/product/save      301
catalog/product/save      302

第二次 save 已经变成重定向后的请求，没有原来的表单数据，所以 Magento 才说没有数据可保存。这个现象和 PHP 的 post_max_size 超限不一样；超限时通常能看到请求大小异常，而这里最明显的证据就是多出来的 301。

顺着Location头查是谁改了后台地址

点开 301 响应，看 Location 到底多了什么。常见情况是少了 Store Code、HTTP 被强制跳到 HTTPS，或者反向代理传进来的 Host 与后台 Base URL 不一致。

如果启用了 Add Store Code to URLs，还要检查 Web Server / Nginx 配置是否把后台请求重写到了另一个不带 Store Code 的地址。站点放在负载均衡后面时，再确认代理有没有正确传递：

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

不要先改 Product Save 控制器。先把保存请求的最终 URL 调整成一次就能命中的地址，再清配置缓存并重新登录后台。Network 中 catalog/product/save 直接返回 302，商品内容也能重新读出来，这个问题才算处理完。

先去掉Factory后缀，确认源类能被自动加载

例如报错是：

Class Vendor\Catalog\Model\FeedFactory does not exist

Magento 能生成 FeedFactory 的前提是 Vendor\Catalog\Model\Feed 可以被 Composer 找到。依次检查：

test -f app/code/Vendor/Catalog/Model/Feed.php && echo found
php -l app/code/Vendor/Catalog/Model/Feed.php
composer dump-autoload -o
php -r "require 'app/bootstrap.php'; var_dump(class_exists('Vendor\\Catalog\\Model\\Feed'));"

最后一条如果返回 false，问题还没到代码生成阶段。检查文件名大小写、namespace、类名以及模块是否真的存在。Linux 区分大小写，本地 macOS 能跑不代表服务器也能加载。

连续大写缩写最容易让文件名和类名对不上

像 WeatherDataDBDetails 这种命名，看起来没有拼错，但文件、类型声明、构造参数和引用处只要有一处写成 WeatherDataDbDetails，开发机上可能侥幸通过，Linux 编译就会失败。不要靠肉眼来回看，直接搜索所有声明和引用：

rg -n 'WeatherData(DB|Db)Details' app/code

比较稳的做法是按项目约定统一缩写写法，例如把 DB 当作 Db，然后让文件名、类名、use、XML 和构造参数完全一致。修改大小写时，Git 在不区分大小写的文件系统上可能不记录变化，可以通过中间文件名完成 rename。

源类能加载，再查generated目录的属主和残留

Magento 2.2 及以后通常在 generated/code 生成 Factory、Proxy 和 Interceptor。先看运行编译的用户是否有权限：

id
namei -l generated/code
find generated/code -maxdepth 3 ! -user deploy -ls | head

不要直接 chmod -R 777 generated。应该让固定的部署用户拥有目录，并让 Web 用户按部署模型获得需要的读取权限。确认当前没有其他发布或 PHP 进程正在生成代码后，再清理旧产物并重新编译：

find generated/code generated/metadata -mindepth 1 -delete
php bin/magento setup:di:compile

如果报错类属于已经卸载的模块，查配置和缓存残留

第三方模块从 Composer 移除后，app/etc/config.php、其他模块的 di.xml、插件声明或编译缓存可能仍引用旧类。用完整类名搜索代码和配置：

rg -n 'OldVendor\\OldModule|OldClass' app/code app/etc vendor composer.*

确认模块确实已卸载后，修正模块列表和依赖，再按当前环境清配置缓存。Redis 是共享缓存时只删除本项目使用的 cache database 或 key 前缀，不要在一台承载多个站点的 Redis 上随手 FLUSHALL。

最终判断很直接：源类 class_exists() 为 true、生成目录可写、旧模块引用已清干净，setup:di:compile 才有可能稳定通过。Factory 不存在只是结果，真正要修的是它为什么没法被生成。

先从堆栈找到是谁在读这段值

异常最后落在 Json.php 不代表根因在那里。从调用栈向上找第一个具体模块、配置路径或数据模型。例如错误只在编辑客户时出现，就优先查客户扩展属性；只在结账页出现，则查支付、配送或营销模块读取的配置和缓存。

临时调试可以在调用方记录字段主键和原始值长度，但不要把客户数据直接写入日志。拿到疑似值后分别验证：

php -r '$v=$argv[1]; json_decode($v, true); var_dump(json_last_error_msg());' '待检查内容'

PHP 序列化字符串常以 a:、s:、i:、O: 开头，但不能只靠前缀批量判断，更不能对不可信内容使用允许对象实例化的 unserialize()。

确认字段后，先统计再迁移

假设已定位到某扩展表的 options 字段，先查总量、空值和样本：

SELECT COUNT(*) AS total,
       SUM(options IS NULL OR options = '') AS empty_values
FROM vendor_module_item;

SELECT entity_id, LEFT(options, 120)
FROM vendor_module_item
WHERE options IS NOT NULL AND options <> ''
LIMIT 20;

不要因为某个回答说“truncate 这张表”就照做。表中可能同时保存业务状态或订阅关系。最稳妥的是由扩展升级脚本逐行读取旧格式，使用受限的 unserialize($value, ['allowed_classes' => false]) 转成数组，再编码为 JSON，并记录成功、跳过和失败数量。

数据迁移要能停、能重跑、能核对

先备份目标表；按主键分批处理；每批提交；转换前后保留行数和校验信息。遇到无法解析的值不要写成空数组掩盖问题，而是把主键放进失败清单，确认它究竟是截断数据、双重序列化还是扩展版本不匹配。

修完数据再清相关缓存

如果错误值来自 core_config_data，清 config cache；来自模块缓存，则清对应 cache type。不要把“全站 cache:flush”当成数据修复。最终要重复触发原页面或命令，并在日志中确认没有新的反序列化异常。正确结果是数据库里的旧格式被一次性迁移，而不是框架从此默默兼容所有坏值。

后执行的Patch明确返回它依赖的类

use Magento\Framework\Setup\Patch\DataPatchInterface;

class AssignDefaultGroup implements DataPatchInterface
{
    public static function getDependencies(): array
    {
        return [
            CreateDefaultGroup::class,
        ];
    }

    public function apply(): void
    {
        // CreateDefaultGroup 已完成后再写关联数据
    }

    public function getAliases(): array
    {
        return [];
    }
}

如果 Patch C 必须在 A、B 都完成之后执行，就同时返回两个类。依赖可以跨模块，但对方模块也应该在 module.xml 的 sequence 或 Composer 依赖中体现安装关系，避免代码根本未安装。

只给真正的数据依赖排序

两个 Patch 操作互不相关的表，就不必为了“看起来整齐”串成一条长链。依赖越多，循环依赖和后续重构越麻烦。判断标准很简单：前一个 Patch 没有执行，后一个是否必然失败或产生错误数据？只有答案为是，才写进 getDependencies()。

patch_list有记录后，改apply不会重新执行

SELECT patch_name
FROM patch_list
WHERE patch_name LIKE 'Vendor\\Module\\Setup\\Patch\\Data\\%';

Data Patch 成功后会记录类名。你后来修改 apply()，Magento 不会再次执行它。开发环境可以在确认数据可回滚后删除对应记录重测；生产环境不要随便删 patch_list，应该新增一个 Patch 来做后续变更。

如果只是给类改名，需要通过 getAliases() 返回旧类名，避免升级站点把同一份变更再跑一次。

在空库和升级库各跑一遍

空库测试能验证完整依赖排序，已有数据库升级测试能验证历史 patch 记录、类重命名和新增 patch 的组合。执行后除了看命令成功，还要核对业务表和 patch_list。Patch 的目标是可重复部署同一个结果，不是依赖某台服务器恰好按文件名顺序扫描。

Handler只负责文件和最低日志级别

namespace Vendor\Payment\Logger;

use Magento\Framework\Logger\Handler\Base;
use Monolog\Level;

class Handler extends Base
{
    protected $loggerType = Level::Debug;
    protected $fileName = '/var/log/payment.log';
}

不同 Magento/Monolog 版本对 level 常量的类型要求可能不同。如果项目仍使用 Monolog 1/2，就按当前 Magento\Framework\Logger\Handler\Base 的属性定义使用 Logger::DEBUG。不要从网上复制一段代码后跳过编译检查。

用di.xml组装一个只带这个Handler的Logger

<virtualType name="VendorPaymentLogger" type="Magento\Framework\Logger\Monolog">
    <arguments>
        <argument name="name" xsi:type="string">payment</argument>
        <argument name="handlers" xsi:type="array">
            <item name="payment" xsi:type="object">Vendor\Payment\Logger\Handler</item>
        </argument>
    </arguments>
</virtualType>

<type name="Vendor\Payment\Model\GatewayClient">
    <arguments>
        <argument name="logger" xsi:type="object">VendorPaymentLogger</argument>
    </arguments>
</type>

业务类仍然依赖 Psr\Log\LoggerInterface，不用把自定义 Logger 类写死：

public function __construct(private LoggerInterface $logger) {}

$this->logger->info('payment request started', [
    'order_id' => $orderId,
    'request_id' => $requestId,
]);

日志能定位问题，但不能把敏感数据原样落盘

支付日志至少要过滤卡号、CVV、Authorization、Cookie、完整 access token 和客户密码。请求体最好建立白名单，只记录订单号、网关请求号、金额、币种、HTTP 状态和耗时。失败响应也不要整包输出，第三方接口有时会回显用户资料。

用一笔可控测试订单验证四件事

编译并清配置缓存后，检查 var/log/payment.log 是否由正确用户创建、正常请求是否写入、异常是否包含 correlation id、system.log 是否没有重复一份。最后配置 logrotate 或容器日志采集，避免高峰期把磁盘写满。独立日志的价值是快速串起一笔交易，而不是把所有对象 dump 得越多越好。

先确认现在是谁在执行命令

id
ps -eo user,group,cmd | rg 'php-fpm|apache2|httpd'
namei -l pub/static
find pub/static -maxdepth 3 \( ! -user deploy -o ! -group www-data \) -ls | head -50

示例里的 deploy 和 www-data 要换成服务器真实用户。重点是发布用户能创建文件，PHP-FPM 用户能读取；如果运行时也需要生成静态文件，则双方要通过同一组获得写权限。不要混用 root、部署账号和 Web 用户轮流跑 Magento 命令，否则下一次发布还会反复变属主。

777也无效时，检查失效软链和挂载

find -L pub/static -type l -print
findmnt -T pub/static
getfacl -p pub/static | sed -n '1,40p'

旧版本或开发模式可能留下指向已删除源文件的软链。权限检查递归走到这里会失败，即使父目录是 777 也没用。容器环境还要看 pub/static 是否被只读 volume 覆盖，宿主机权限和容器内 uid 是否一致。

确认可以重建后再清静态产物

pub/static 属于生成内容，但 .htaccess 在 Apache 环境中可能仍需要保留。不要无脑删除整个目录。可以先备份并仅清生成内容：

find pub/static -mindepth 1 ! -name '.htaccess' -delete
find var/view_preprocessed -mindepth 1 -delete

如果目录里混入了人工上传文件，先停下来确认发布流程，不能因为它“理论上可生成”就直接清空。

把属主和组一次修到发布模型上

常见做法是代码归部署用户、可写目录归共享组，并设置 setgid 让新文件继承组：

chown -R deploy:www-data pub/static var generated
find pub/static var generated -type d -exec chmod 2775 {} +
find pub/static var generated -type f -exec chmod 0664 {} +

上面只是模型，具体权限要按主朸隔离策略调整。修完后用部署用户依次跑 setup:upgrade 和静态资源部署，再用 PHP-FPM 用户做一次只读访问验证。问题解决的标准不是命令暂时通过，而是下一次发布不会再次产生 root 属主文件。

先看是哪条依赖在构造阶段启动了Session

从异常栈往上找第一个自定义类。如果命令构造函数直接注入了重量级服务，该服务的依赖链可能创建 customer session，而 session 必须知道当前 area。此时问题不只是少一行 setAreaCode，而是对象创建得太早。

容易触发的写法类似：

public function __construct(
    private TaxCalculationInterface $taxCalculation,
    AppState $appState
) {
    $appState->setAreaCode(Area::AREA_ADMINHTML);
    parent::__construct();
}

把area设置移到execute，构造函数只保存依赖

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $this->appState->setAreaCode(Area::AREA_ADMINHTML);
    $this->runImport();
    return Command::SUCCESS;
}

area 要按实际业务选择。读取前台价格、客户组上下文时未必应该用 adminhtml；纯全局处理也不要为了消掉异常随便选一个 area。

这段逻辑可能被别处调用，就用emulateAreaCode包住

return $this->appState->emulateAreaCode(
    Area::AREA_ADMINHTML,
    fn () => $this->runImport()
);

emulation 的好处是执行完成后恢复原状态，适合共享服务或测试。但如果依赖在构造阶段已经启动 session，emulation 仍然来不及，这时要把该依赖改成 Proxy 或 Factory，让真实对象到 execute() 里才创建。

修完要跑的不只是这条命令

先执行目标命令，再跑：

php bin/magento list
php bin/magento cache:status
php bin/magento setup:di:compile

list 很重要，因为它会加载全部命令，最容易暴露“构造函数里抢先设置 area”的问题。真正稳定的修复是控制初始化时机，而不是捕获 Area code is already set 后假装没事。

先从异常栈里拿到theme id或theme path

不要一上来清整张 theme 表。先看 var/log/exception.log、部署命令输出以及错误前后的 theme 信息，再查询：

SELECT theme_id, parent_id, theme_path, theme_title, area, type, code
FROM theme
ORDER BY theme_id;

然后把 theme_path 与 app/design/frontend、app/design/adminhtml 下的实际目录逐一对上。还要检查 registration.php 和 theme.xml 是否在，文件夹存在不等于主题注册完整。

再查哪个scope还指着这个theme_id

SELECT config_id, scope, scope_id, path, value
FROM core_config_data
WHERE path = 'design/theme/theme_id';

如果旧主题 ID 只出现在某个 Store View，首页可能正常，而那个 Store View 一打开就报错。先明确 scope，不能只改 default 级配置。

主题本来就该存在，就把代码和依赖补回来

如果是发布漏文件或 Composer 包没有安装完整，正确处理是恢复主题代码，再运行：

php bin/magento setup:upgrade
php bin/magento cache:clean config layout

同时确认父主题也存在。只把数据库里的 parent_id 改成 NULL，虽然可能暂时不报错，但会破坏继承链，CSS 和模板随后会出现更隐蔽的问题。

确认主题已经下线，才清配置和注册记录

先在后台或配置表把相关 Store View 切到仍然存在的主题，再备份 theme 表，最后删除明确无用的那一条注册记录。不要按 theme_title 模糊删除，也不要清空整表。处理后清配置与 layout 缓存，再执行一次静态资源部署。

验证时除了前台，还要运行 php bin/magento setup:di:compile 或计划中的正式发布命令。因为有些残留只会在编译、静态资源收集阶段触发，浏览几个页面正常并不能证明主题注册已经干净。

先确认主题代码和商店语言

主题名不是目录最后一级，而是注册时的 Vendor/theme。语言也要以商店实际 locale 为准：

php bin/magento config:show general/locale/code
php bin/magento theme:uninstall --help

第二条只是利用命令帮助确认当前版本的主题相关能力，不要真的执行卸载。多 Store View 环境还应从后台配置或数据库确认各 scope 的 locale，不能假设全部是 en_US。

生产模式下把范围写完整

例如只部署 Acme/shop 的中文和英文前台资源：

php bin/magento setup:static-content:deploy \
  --area frontend \
  --theme Acme/shop \
  zh_Hans_CN en_US \
  --jobs 4

如果服务器 CPU 和内存不宽裕，--jobs 不要盲目开大。主题继承的父主题资源会由依赖关系处理，通常不需要再把 Luma 单独列一遍。

开发模式不要拿生产命令反复硬跑

开发模式下静态资源可以按请求生成。此时 CSS 改动看不到，先检查浏览器拿到的文件路径、静态文件签名和预处理缓存，而不是每次都全量 deploy。生产模式才把静态资源部署当作发布步骤，并尽量在维护窗口或新 release 目录里完成。

部署完成后别只看命令返回0

检查目标目录是否真的生成：

find pub/static/frontend/Acme/shop -maxdepth 2 -type d

再用浏览器 Network 查看 CSS URL 对应的 theme 和 locale。若启用了静态内容版本号，还要刷新页面缓存和 CDN，避免 HTML 仍引用旧版本。只部署一个主题能缩短发布时间，但前提是本次改动没有同时影响后台资源、共享语言包或其他主题；涉及模块级 view/frontend 文件时，也要确认所有使用该模块资源的主题是否都需要重新部署。

先把跳转链打印出来

浏览器只显示“重定向次数过多”，信息不够。先在服务器外执行：

curl -I -L --max-redirs 10 https://staging.example.com/

如果 http 和 https 来回切换，优先查代理和 secure 配置；如果 URL 没变但不断返回 302，通常更像 Cookie、Store Code 或后台会话问题。也可以去掉 -L，逐次看 Location 和 Set-Cookie。

数据库是从旧站导入的，先查Cookie域名

SELECT scope, scope_id, path, value
FROM core_config_data
WHERE path IN (
  'web/cookie/cookie_domain',
  'web/unsecure/base_url',
  'web/secure/base_url',
  'web/secure/use_in_frontend',
  'web/secure/use_in_adminhtml',
  'web/secure/offloader_header'
)
ORDER BY path, scope, scope_id;

web/cookie/cookie_domain 如果还写着旧域名，浏览器不会把会话 Cookie 发给新站。这里还要留意 website/store 级配置是否覆盖 default 值。测试环境没有特殊要求时，可以把 Cookie Domain 留空，让 Magento 按当前 Host 生成；需要显式设置时，只填域名，不要带协议、路径或端口。

HTTPS在负载均衡器终止，就核对offloader header

常见架构是用户访问 HTTPS，但 Nginx、Ingress 或 CDN 回源 Magento 时使用 HTTP。Magento 如果不知道外层请求本来是 HTTPS，就会再次跳到 HTTPS，代理又回源 HTTP，于是形成循环。

先确认代理实际传的是哪个头：

proxy_set_header X-Forwarded-Proto $scheme;

Magento 的 web/secure/offloader_header 要与之匹配，通常是 X-Forwarded-Proto。不要因为看到别人配置了 SSL_OFFLOADED 就直接照搬，关键是 Web 服务器交给 PHP 的请求头名称和 Magento 配置必须一致。

修改后只清配置缓存，再删旧Cookie

php bin/magento cache:clean config full_page

用无痕窗口重新访问，避免旧域名 Cookie 干扰判断。如果后台仍循环，再检查 env.php 中的后台前缀、Web 服务器是否额外做了 www 跳转，以及 CDN 是否也配置了一层 HTTP 到 HTTPS 规则。把每一跳的 Location 记录下来，通常两三次就能看出是谁在重复改协议或域名。

先把页面上的入口找全，别只删右侧栏

商品对比不只出现在一个位置。分类列表、搜索结果、商品详情、顶部链接和 compare sidebar 都可能有入口；Wishlist 还会出现在客户中心、商品卡片和详情页。先在当前主题及父主题里查 block 名称：

rg 'catalog\.compare|product\.compare|wishlist' app/design/frontend vendor/magento/module-*/view/frontend/layout

这里不要直接改 vendor。搜索的目的只是确认当前 Magento 版本使用了哪些 block 名，真正的覆盖文件放到自定义主题。

只是隐藏功能时，用layout remove掉对应block

例如在主题的 Magento_Catalog/layout/default.xml 中处理公共区域：

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="catalog.compare.sidebar" remove="true"/>
        <referenceBlock name="catalog.compare.link" remove="true"/>
        <referenceBlock name="wishlist_sidebar" remove="true"/>
    </body>
</page>

商品卡片里的“加入对比”和“加入愿望单”不一定都是独立 block。有的主题在模板或 UI component 中直接输出按钮，所以公共 layout 清完之后还要检查分类页、搜索页和商品详情页。自定义主题如果继承了第三方主题，也要以实际渲染出来的 layout handle 为准，不能照抄一组 block 名就认为结束了。

不要用CSS把按钮盖住

display:none 只能让用户看不见，HTML、初始化脚本以及相关接口仍然存在。后续换主题、做无障碍检查或让搜索引擎抓页面时，很容易再次暴露。能在 layout 阶段移除就不要用 CSS；模板中直接输出的入口，则在自定义主题内覆盖最小模板片段。

清完缓存后按游客和登录用户各走一遍

php bin/magento cache:clean layout block_html full_page

然后至少检查首页、分类页、搜索页、商品详情、客户中心和购物车。浏览器里再搜一次 compare、wishlist，确认没有遗留链接和 JS 报错。这样做保留了模块依赖关系，只收掉用户入口，后面换主题或恢复功能也容易回滚。

先确认这个进程监听的是哪一个consumer

ps -ef | grep '[q]ueue:consumers:start'
bin/magento queue:consumers:list
supervisorctl status

对照 Supervisor 配置里的 consumer 名称、Magento 配置和 RabbitMQ 实际队列绑定。配置改过但旧进程没重启时，它仍可能运行旧 consumer 或旧 release。多套环境共用 RabbitMQ vhost，也可能看错队列。

在RabbitMQ里分开看Ready和Unacked

Ready 高、Unacked 为 0，通常是没有消费者真正订阅；Unacked 持续很高，说明消息已取走但处理没完成或没有 ack。结合 connection、channel、consumer tag 和 hostname，确认是哪台机器占着消息。

如果 Ready 在下降但业务完全没有结果，别只看队列曲线，继续查消息是不是被路由到错误 consumer 或失败队列。交换机、routing key 与 queue binding 任何一个不一致，都会让“有消费者、也有消息”这两个事实彼此无关。

如果只有一条消息长期 unacked，抓 consumer 的 PHP 调用栈或打开针对性日志。外部 API 没超时、数据库锁等待、图片处理卡住，都会让进程看着 alive，实际上停在同一条消息上。

Unacked 数量刚好等于 worker 数乘以 prefetch 时，通常是所有 worker 都卡在处理阶段。此时继续加进程只会拿走更多消息并占用内存，应该先找到单条消息为什么不结束。

消息反复回队列时，先保存失败原因

消费者抛异常后立即 nack/requeue，Ready 数可能几乎不变，但日志会重复同一消息。记录 message ID、topic、重试次数和异常，设置合理的重试与失败队列，避免毒消息无限占满 worker。

重启前先判断会不会重复执行

直接 kill 卡住的 consumer 会让未确认消息重新投递。如果处理过程已经调用外部系统，只是 ack 前卡住，重投可能产生重复订单、重复邮件或重复库存动作。业务处理必须使用稳定键做幂等。

修复后观察 Ready、Unacked 和 ack rate，而不是只看 Supervisor 变绿。再投一条可识别的测试消息，确认正确 consumer 在预期时间处理，并完成一次滚动重启测试。这样才能证明进程管理和消费链路都正常。

最后把 Supervisor 的退出码、启动目录、PHP 路径和最大消息数写清楚。发布后主动滚动重启长期 consumer，确保它们加载的是新 release；否则 Web 已经运行新代码，队列进程还在执行旧类，问题会表现得非常随机。

先把报错补丁和真实列定义对上

从异常栈找到具体 Schema Patch、UpgradeSchema 或 declarative schema 文件，再查看数据库列类型、长度、nullable、默认值和索引。字段同名不等于定义一致。

SHOW CREATE TABLE target_tableG
SELECT patch_name
FROM patch_list
WHERE patch_name LIKE '%Vendor\Module%';

patch_list 没记录，但列已经存在，常见原因是补丁执行到 addColumn 后进程中断，事务没有覆盖 DDL，或者有人手工执行了 SQL。此时盲目删除列可能把已经写入的业务数据一起删掉。

再查有没有第二个模块也在加同名列

grep -R "column_name" app/code vendor/*/*/etc/db_schema.xml -n
grep -R "addColumn.*column_name" app/code vendor -n

如果两个自定义模块声明同一列，应该确定列归属并合并设计，而不是靠模块加载顺序碰运气。Declarative schema 与旧 UpgradeSchema 同时维护同一字段，也容易在迁移阶段重复。

处理方式取决于列里有没有数据

列为空、定义错误且确认没有代码使用时，可以在备份和测试验证后删除，让正式补丁重建。列已有数据且定义与代码一致，更安全的做法通常是让补丁先检测列是否存在，或修复补丁登记状态，但必须确认该补丁除了加列之外没有其他步骤。

不要随便往 patch_list 插一条记录跳过补丁。它可能还创建索引、迁移数据或增加约束，只标记完成会留下半套结构。

在数据库副本上完整跑一次升级

修复后从生产结构副本执行 setup:upgrade，检查 db_schema_whitelist、索引和外键，再跑应用回归。最后把人工处理写进部署记录。目标是让下一套相同旧版本数据库也能自动升级，不是只让当前库绕过这一行。

按时间把四段日志拼起来

我会用 increment_id、支付平台 transaction ID 和 quote/order ID，把“创建支付请求、用户返回页、异步 webhook、Magento 状态更新”放在同一条时间线上。用户关闭返回页不应该影响异步回调，所以不要只查 success URL。

如果网关能看到 webhook 已发送，记录它的 HTTP 状态和响应体。404 是路由不对，401/403 多半是签名或 WAF，500 才进入 Magento 代码异常。返回 200 也不代表业务成功，有些插件捕获异常后仍然响应 200。

Webhook进来了，就查它为什么没认出这张订单

对照 merchant account、store scope、订单号字段、金额、币种和签名使用的原始 body。反向代理修改 body、读取流后没有重置、测试与正式密钥混用，都会导致验签失败。

再看 sales_payment_transaction 和 order payment additional information。支付成功事件如果没有保存外部 transaction ID，后续重复回调无法幂等判断，也无法正确 capture 或开票。

有些网关先发 authorized，再发 captured；两个事件可能乱序到达。处理 captured 时如果代码要求订单仍处于某个固定状态，早到或晚到的事件就会被丢弃。应该按外部交易的状态与唯一 ID 判断是否可以推进，而不是只依赖当前 Magento status 文本。

别把Pending Payment只当成status文本

检查订单内部 state/status、payment action 是 Authorize 还是 Authorize and Capture，以及插件成功分支实际调用了什么。Authorize 只授权时不一定立即生成发票；Capture 成功却仍 pending，才说明状态机或回调处理断了。

SELECT entity_id, increment_id, state, status, updated_at
FROM sales_order
WHERE increment_id = '000000123';

修复后重放同一个Webhook

第一次回放应把订单推进到正确状态并写入交易；第二次回放必须安全返回，不能重复开票、扣库存或发邮件。再测金额不一致、签名错误和回调延迟。旧订单的数据修复要根据支付平台真实交易逐单处理，不能批量把 Pending Payment 全改成 Processing。

先确认是500、502还是200空页面

curl -I https://shop.example.com/admin-path/
tail -f var/log/exception.log var/log/system.log
journalctl -u php-fpm --since "10 minutes ago"

500 重点看 PHP 异常；502 看 PHP-FPM 是否崩溃或超时；200 但 body 为空，检查 fatal error 是否被输出配置吞掉。生产环境不要打开公开报错页面，日志里按请求时间找。

直接diff更新前后的composer.lock

如果目标只是升级一个支付模块，lock 却变了几十个框架包，问题范围已经失控。列出新增、删除和变更版本，再按异常中的类名回到具体包。

composer show --direct
composer why vendor/package
composer why-not vendor/package target-version
composer validate

Class not found 先查包、autoload 和模块状态；方法签名不兼容或参数类型错误，通常是扩展与框架版本不匹配。不要直接改 vendor 里的方法，应该锁回兼容版本、升级扩展或应用正式 patch。

依赖确认没问题，再重建generated和静态资源

旧 interceptor/proxy 引用了更新前构造函数时，重新编译确实能修。但如果 setup:di:compile 自己报错，就继续修 DI 或依赖，不能删除 generated 后绕过编译上线。

多节点还要滚动重载 PHP-FPM/opcache。代码已经切到新 release，旧 worker 仍执行旧字节码时，会出现某些节点正常、某些节点白屏。

恢复后在干净目录用 lock 文件执行 composer install，再完成编译和基础回归。把这次确切的包版本和修复提交到版本控制，保证下一台机器能重复部署，而不是只在出问题的服务器上手工修好。

先保存故障quote里这一行的价格字段

记录 quote item 的 product_type、price、base_price、custom_price、original_custom_price、row_total 和父子 item 关系。普通商品这些值不该无缘无故变成 0；动态价格 bundle 的父行是 0、金额放在子行，则可能是正常数据结构，只是模板显示错了对象。

普通加购正常，自定义入口为0，就搜setCustomPrice

grep -R "setCustomPrice" app/code -n
grep -R "setOriginalCustomPrice" app/code -n
grep -R "setIsSuperMode" app/code -n

快速下单、ERP 下单和自定义 Controller 经常把空字符串、缺失价格转换成 0，再调用 custom price。还有代码为了允许手工价打开 super mode，却没有限制调用场景。先让标准商品页加购和自定义入口各生成一个新 quote，对比差异。

加购时有价格，collectTotals后才归零，就按collector顺序查

在测试环境记录 collectTotals 前后 item 和 address total。折扣、税、积分、礼品卡及自定义 collector 都可能改金额。Around plugin 忘记调用 proceed，或返回了错误对象，也会让后续 collector 读到不完整数据。

同时看 base_currency_code、quote_currency_code 和 conversion rate。汇率服务返回 0 时，base_price 可能仍正确，显示币种金额却归零。

修完一定用新购物车测试

旧 quote 已经保存了 custom_price，清缓存不会自动恢复。删除测试 Session 或创建新客户购物车，再测游客、登录客户、优惠券、目标币种和不同产品类型。最后核对订单金额与支付请求，不能只看购物车页面重新显示了 199 元。

先把锁定时间和访问日志对上

只查询这个管理员的失败次数、锁定到期时间和状态，不要把整张管理员表导出来。然后在 Nginx/Apache 日志里按后台登录路径、用户名相关请求时间和来源 IP 对照。Magento 不一定把用户名明文写入访问日志，可以结合 Session、IP、User-Agent 和请求频率判断。

常见来源包括浏览器密码管理器自动提交旧密码、可用性监控把登录页当表单探测、旧自动化脚本，以及另一位管理员还开着保存旧凭据的窗口。

如果来源 IP 是公司出口，继续按 User-Agent 和请求间隔区分具体客户端。固定每 30 秒一次更像监控，打开页面马上连续数次更像浏览器自动填充或脚本重试。必要时在受控时间短暂增加登录失败审计字段，但不要把密码、验证码或完整 Cookie 写进日志。

确认没有重试后再解锁这个用户

bin/magento admin:user:unlock username
bin/magento admin:user:create --help

优先使用当前版本 CLI 解锁指定用户，不要批量清空所有管理员的 failures。完全无法进入后台时，可以按应急流程创建临时高强度账号，处理完成后立即禁用，并保留审计记录。

一台节点正常、一台节点总锁，就查时间和Session

负载均衡环境里，应用节点与数据库时间不一致会让锁定到期判断异常。检查 NTP、PHP 时间和数据库 UTC 时间。若后台 Session 分散在本地文件，登录请求切节点也可能表现异常，但它通常还会伴随掉线或 Form Key 问题。

解锁后分别测试密码、2FA 和退出重登。再故意输错一次，失败计数应该只增加一次；一次点击增加多次，就继续查代理重试或前端重复提交。把真正的自动重试源停掉，才算解决，不是把锁定阈值改得更大。

还要确认失败发生在哪一步。密码错误会增加登录失败计数，2FA 验证失败属于后续认证流程；如果界面统一显示“锁定”，日志里仍应能分开。把 2FA 问题误当密码爆破处理，解锁多少次都会再次失败。

保存前后盯住同一个文件名

上传完成先在 pub/media/catalog/product/tmp 找到文件，保存后再看它有没有进入正式的 catalog/product 分散目录。tmp 有、正式目录没有，先看文件移动、磁盘和权限；正式文件存在但后台没有记录，再查数据库。

df -h
df -i
find pub/media/catalog/product/tmp -type f -mmin -10
tail -f var/log/system.log var/log/exception.log

inode 用完时磁盘容量可能仍显示有空间。跨挂载点移动、SELinux、安全扫描占用文件，也会让 rename 或 copy 失败。不要直接把 media 改成 777，先确认 PHP-FPM 与部署用户的 owner、group 和 umask。

文件已经进正式目录，就查媒体库三层关系

对照一个正常商品，检查 media gallery 主记录、store view 的 value 记录和商品关联。只写了文件名但没关联 entity，文件会一直躺在磁盘上，后台却看不到。不同 Magento 版本表结构不同，先用当前库的 schema 确认字段再查询。

图库里有图片但前台角色图空白时，再看 image、small_image、thumbnail 是否在当前 store view 被覆盖为 no_selection。这和整张图库记录丢失不是同一个问题。

多节点环境要确认tmp和正式media是不是同一份

上传请求落在 A 节点，保存请求落在 B 节点，而 tmp 目录没有共享，就会随机消失。使用对象存储时还要看上传、复制和读取是否都走同一套 remote storage 配置。靠 sticky session 只能暂时遮住问题，不能替代共享媒体设计。

修复后分别上传小 JPG、大 PNG、同名文件，并从两台后台节点各测一次。后台图库、数据库关系、原图 URL 和缓存图 URL 都正常，才算完整通过。

保存前把scope和配置路径记下来

同一个字段在 Default、Website、Store View 可以有三份值。先确认左上角当前作用域，以及“Use Default”是否勾选。然后从页面字段或 system.xml 找到真实配置路径。

bin/magento config:show section/group/field
SELECT scope, scope_id, path, value
FROM core_config_data
WHERE path = 'section/group/field';

保存后立刻查数据库。新值从来没写进去，就看 backend model 校验、ACL、POST 参数和异常日志；数据库里已经是新值，页面却显示旧值，再查读取作用域、config cache 和应用连的是不是同一个数据库。

读写分离环境要从处理保存请求的节点和处理刷新请求的节点分别确认数据库连接。写入主库后立刻从延迟副本读取，会短暂看到旧值；如果刷新几秒后又恢复新值，就是明显信号。后台配置读取通常不应该在不保证一致性的副本上完成。

数据库里刚改好，几秒后又变回去，就找覆盖源

容器启动脚本、部署任务、配置同步程序都有可能把旧值重新写回。连续查询该 path，并对照部署和 cron 时间。不要一直在后台重复保存，否则只会让覆盖动作更难看清。

自定义 backend model 也可能在 afterSave 中把一个可视字段拆成多个配置值，或者根据另一个开关强制清空。Network 里的 POST 有新值、数据库从未出现新值时，把该字段配置类和保存事件一起搜出来，比继续怀疑浏览器缓存有效。

再检查 app/etc/config.php、env.php 和环境变量。被配置管理锁定的 path 应该从代码或部署变量修改，后台不是它的事实来源。使用 Magento 的配置状态命令确认是否被锁，不要直接删配置文件里的节点。

修完后必须走一次正常发布

我会在正确 scope 保存或更新部署配置，清理 config cache，再从另一台 Web 节点读取一次。随后执行一次完整部署或重启容器，确认值没有被旧变量覆盖。

最终记录这个配置到底由数据库、config.php 还是环境变量维护。下次再改时团队知道去哪里动手，比“这次刷新终于没变回去”更重要。

多网站配置还要拿两个 store view 交叉验证：目标站点读到新值，未修改站点继续继承原值。这样能证明 scope_id 没写错，也不会为了修一个站点把全局配置一起覆盖。

两封邮件先比这三个值

Message-ID 不同、模板生成时间也不同，通常是 Magento 发送流程执行了两次；Message-ID 相同但邮箱收到两次，继续查 SMTP 服务商或下游转发。再对照订单状态历史，看重复邮件是否紧跟两次支付回调或两次状态变更。

数据库里检查订单的 email_sent、创建时间和更新时间，但不要为了测试直接把 email_sent 改回 0，这会主动制造下一封邮件。

在自定义代码里搜第二个OrderSender

grep -R "OrderSender" app/code -n
grep -R "->send(.*order" app/code -n

核心下单流程已经安排发送时，自定义 observer 又监听 checkout success 调一次，是最直接的重复来源。支付插件也可能在 webhook 里再次调用发送。网关重复投递回调是正常现象，回调处理必须按交易号或事件 ID 做幂等，不能假设只会收到一次。

我会在发送入口临时记录 order_id、调用栈的自定义类、消息 ID 和 hostname，不记录客户敏感信息。两封邮件分别由哪个入口产生，很快就能看出来。

如果项目开启异步销售邮件，还要分清“入队两次”和“同一条消息消费两次”。在发送进入队列的位置与真正调用邮件传输的位置分别加一次关联 ID：前面已经出现两条，去查业务事件；前面一条、后面两次，才把注意力放到消费者确认与重投。

只有证据指向队列，才查Cron和Consumer

异步邮件模式下，同一条消息可能因为 consumer 发送成功后未及时确认而被重新投递。两台节点重复运行任务、进程被强杀、连接在 ack 前中断，都需要结合消息 ID 和 worker hostname 判断。

修复后我会故意重放一次支付回调，再在发送过程中重启一个测试 consumer。订单状态可以重复查询，但确认邮件只能生成一次。如果只是把某个 cron 停掉后不再重复，却没有解释第二次调用从哪里来，问题还没有解决。

另外核对邮件模板与发件配置作用域，避免把“订单确认”和自定义的“支付成功通知”做成几乎相同的正文。两封不同业务邮件看起来一样，不属于重复投递，应该从模板和主题上明确区分，而不是删除其中一个发送流程。

先在Console里看checkoutProvider有没有值

打开浏览器开发者工具，找到这个 UI Component 的 dataScope 和 provider。字段如果声明在 shippingAddress.custom_attributes.house_number，就检查 checkoutProvider 的同一路径，不要只看 DOM 的 value。

常见情况是 LayoutProcessor 注入时用了 customAttributes，mixin 读取时却写成 custom_attributes；页面显示组件和校验组件实际绑定了两个对象。还有一种是同名字段被注入两次，用户填了可见的那个，隐藏的副本仍为空。

点下一步，直接看shipping-information请求

Network 里找到保存配送信息的请求，搜索字段代码。请求里没有值，问题还在前端数据转换；请求里有值而接口报必填，再查后端 extension attribute 或地址属性声明。

{
  "shipping_address": {
    "custom_attributes": [
      {"attribute_code": "house_number", "value": "8-2"}
    ]
  }
}

项目有时把字段放在 extension_attributes，有时使用 customer address EAV 的 custom_attributes。两种方式都能做，但前端 payload、extension_attributes.xml、接口和保存插件必须选同一条路径。字段代码差一个下划线也不会自动映射。

值传到了，就查quote_address有没有落库

在测试环境对照请求和 quote_address。接口返回成功但数据库没有值，检查保存插件是否执行、数据库列是否存在、setter 是否写到正确对象。quote 有值而 order_address 没值，则漏了 quote 转 order 的字段复制。

修复后我会测四条路径：游客新地址、登录用户新地址、从地址簿选择旧地址、账单地址与配送地址不同。最后下一个测试订单，后台订单地址必须看到该字段。只让红色必填提示消失不算修好，发货环节真正拿得到值才算。

保留429响应体，它会告诉你拒绝类型

日志不要只截状态码。响应中的 rejected_execution_exception、线程池名称或 circuit breaker 信息能直接指向资源。同步记录当时节点 CPU、JVM heap、磁盘水位、pending tasks 和 thread pool rejected 计数。

curl -s http://opensearch:9200/_cluster/health?pretty
curl -s http://opensearch:9200/_cat/thread_pool/search,write?v
curl -s http://opensearch:9200/_cat/nodes?v&h=name,cpu,heap.percent,ram.percent,disk.avail

命令应在受控网络并使用正确认证。不要把管理端口暴露到公网。

看429发生在reindex还是用户搜索高峰

如果每次全量 reindex 都出现 write/bulk rejected，降低批次并错峰执行，检查是否同时有多个索引任务。若是 search 线程池拒绝，分析慢查询、聚合字段和机器人流量。商品属性大量设置为 searchable/filterable，会显著放大查询与索引成本。

再查看索引数量、主分片和副本分布。小目录拆成大量分片会浪费 heap，大目录只有一个热点分片又会让单节点吃满。不要直接照搬别人的 shard 数，先看当前文档量、分片大小和节点数，再规划新索引并通过 Magento 的重建流程切换 alias。

磁盘接近水位、分片过多或副本不可分配时，简单增加重试只会把更多请求压回集群。先恢复集群健康，再决定扩节点、调 shard、清理旧索引或优化查询。

应用重试必须有边界

对可重试的查询使用短暂指数退避和随机抖动，限制次数；不要立即无限重试。前台还应给出可理解的降级结果，而不是把异常吞掉后展示“没有商品”，否则业务会误判为搜索索引为空。

扩容后也要复测同等负载，观察 rejected 计数是否继续增长、P95 查询延迟和 reindex 用时。真正解决 429，是让峰值请求量、查询成本和集群容量重新匹配，而不是把日志级别改低。

最后把前台搜索和后台索引的容量指标分开设告警：集群健康为 green 也可能持续拒绝高峰查询。至少监控 heap、GC、磁盘水位、search/write rejected、队列长度和慢查询。这样下一次接近极限时能提前扩容或限流，而不是等客户看到空白页才发现。

用curl看每一跳，不要相信浏览器地址栏

curl -IL --max-redirs 10 https://shop.example.com/new-name.html
curl -I https://shop.example.com/old-name.html

记录每个 Location 和状态码。浏览器会缓存永久重定向，测试时用 curl 或无痕窗口更可靠。如果第一跳就来自 CDN，先绕过外层缓存确认 Magento 本身返回什么。

查当前Store View的Rewrite，而不是全库模糊搜索

按 request_path、target_path、entity_id 和 store_id 查询 url_rewrite。新路径如果被一条 custom rewrite 指向旧路径，而旧路径又指回新路径，就会形成循环。也要区分系统生成记录和管理员创建的自定义重定向。

后台保存 URL Key 时“Create Permanent Redirect for Old URL”会保留旧地址跳向新地址，这是正常 SEO 行为；方向应是旧到新。如果方向相反，多半有历史自定义 rewrite、导入脚本或扩展重建了错误记录。

分类路径与Canonical不是同一个问题

开启分类路径后，同一商品可能有多个 request_path。你改的是商品主 URL Key，但分类 URL rewrite 仍在旧路径，或者菜单缓存还输出旧链接。Canonical 标签只告诉搜索引擎首选地址，不会负责浏览器 301。

不要直接 TRUNCATE url_rewrite。先导出相关商品和 store 的记录，删掉确认有冲突的自定义项，再让 Magento 对该实体重新生成。全表重建会影响 CMS、自定义重定向和正在收录的页面。

修复后验证新地址 200、旧地址单跳 301 到新地址、分类页链接已经更新，并检查两个 store view 不互相串域。跳转少一层和方向正确，对用户与 SEO 都比“最终能打开”更重要。

用响应头判断谁在回答

curl -sI https://shop.example.com/page | egrep -i 'age|x-cache|x-magento-cache-debug|x-magento-tags|via'
curl -s https://shop.example.com/page -o /tmp/page.html

连续请求比较 Age、HIT/MISS 和 Magento 缓存调试头。绕过 CDN 直连 Varnish，再绕过 Varnish 直连源站，直到看到新内容。在哪一跳从新变旧，就查那一层，而不是从浏览器一路清到 Redis。

缓存Tag有没有传到Varnish很关键

Magento 更新 Block 时依赖相关 identity/tag 失效页面。如果自定义 Block 没实现正确 identity，或者 Nginx/CDN 删除了 X-Magento-Tags、PURGE/BAN 没到 Varnish，后台清理只能影响 Magento 自身缓存，外层对象仍然存活。

检查该页面缓存对象是否带有 CMS Block 对应标签，以及保存 Block 后 invalidation 请求是否成功。不要把标签头直接暴露给公网，但内部代理链要能使用它。

同名Block和Store View也会制造“缓存没清”的错觉

多商店里可能有相同 identifier 的不同 Block。后台改的是 Default Store View，页面实际读取另一个 store scope；或者 Page Builder 内容嵌入了另一块。直接在页面 HTML 找一段唯一文本，再回后台确认具体 block_id。

浏览器 Service Worker、CDN Edge 和 Varnish 的 TTL 也要分开。用 curl 得到新内容而用户浏览器仍旧，再查浏览器缓存；公网 CDN 旧、源站新，则做精确 URL purge，避免全站清缓存造成无谓回源峰值。

修复后保存同一 Block 两次，每次用唯一标记验证各层在合理时间内更新，并确认其他页面没有被全部驱逐。目标不是“清得越彻底越好”，而是让正确的 Tag 精准失效。

从404 URL反推缺的是哪一组产物

把 URL 拆成 static version、frontend/adminhtml、Vendor/theme、locale 和文件路径。然后到发布产物里按同样层级找文件。不要直接搜索整个 pub/static，因为旧版本目录或 symlink 可能让你找到一份页面根本不会访问的文件。

bin/magento theme:uninstall --help
bin/magento setup:static-content:deploy -f zh_Hans en_US   --area frontend --theme Vendor/theme

上面的部署参数只是示例。先用当前商店 locale 和实际主题代码替换。新增主题必须有正确的 registration.php、theme.xml 以及父主题声明，后台选择的 Design Configuration 作用域也要对应当前 store view。

多节点发布时，命令可能跑在用户看不到的磁盘上

如果每个 Web 节点有独立 pub/static，只在发布机执行成功不够。确认产物被打包并分发到所有节点，静态资源 CDN 的源站也读取同一版本。请求偶发 200/404 通常就是节点内容不一致。

检查静态签名。HTML 引用了新的 version 路径，但 CDN 或 Nginx 仍映射旧 release 时，文件实际存在也会 404。对照页面源代码版本号、部署后的 deployed_version.txt 和当前 symlink。

别用777掩盖生成和读取用户不一致

部署用户需要写入生成目录，Web 用户需要读取。确认 owner、group、umask 与发布流程一致。若 LESS 编译或某个源文件失败，查看完整命令输出，不要只看最后一行。

修复后请求具体 CSS URL 并检查 Content-Type，再刷新一个使用父主题的页面和一个使用新主题的页面。最后清 CDN 的精确路径。能够访问文件只是第一步，样式内容属于正确 release、所有节点一致，才算部署完成。

先证明系统Cron真的每分钟触发

检查运行 Magento 的系统用户 crontab，不要只看 root。确认路径是当前 release，标准输出和错误没有被静默丢弃。部署切换软链接后，旧 crontab 指向过期目录也是常见原因。

crontab -u www-data -l
journalctl -u cron --since "30 minutes ago"
ps -ef | grep '[c]ron:run'

在 crontab 中使用绝对 PHP 路径和 Magento 根目录。交互 Shell 里可用的 PHP 版本、PATH、内存限制和环境变量，cron 用户不一定有。把 php -v 和必要环境写入临时诊断日志，很快能看出差异。

missed表示错过调度窗口，不等于任务代码报错

查看 scheduled_at、executed_at 和 finished_at。某个任务运行太久或锁未释放，会让后续任务来不及在允许窗口内启动。按 job_code 分组统计 pending、running、missed 数量，比只看最新十行更有用。

SELECT job_code, status, COUNT(*)
FROM cron_schedule
WHERE created_at > UTC_TIMESTAMP() - INTERVAL 2 HOUR
GROUP BY job_code, status;

如果总是同一个 job_code 长时间 running，就查它的业务和外部依赖。不要先批量把 running 改成 success，那只会隐藏锁和重复执行风险。

多节点只能让正确的节点负责调度

Web 节点都装了相同 crontab 时，若没有合适锁机制可能重复跑；发布时所有节点又同时停 cron，则会集体漏跑。明确 cron 主机、消费者主机和共享数据库，并记录每次执行的 hostname。

修复后至少观察两个调度周期，确认 schedule 记录按预期提前生成、到点执行、状态 success。手动跑通一次只能证明当前命令可运行，持续没有 missed 才说明自动调度恢复。

从报错的PHP节点确认它实际连到了谁

不要只在 Redis 管理机上看。登录发生错误的 Web、cron 和 consumer 节点，解析配置里的主机名，并连接同一个地址查询 role。

getent hosts redis.internal
redis-cli -h redis.internal -p 6379 ROLE
redis-cli -h redis.internal -p 6379 INFO replication

多节点环境可能只有部分机器缓存了旧 DNS，表现为请求随机报错。也可能 cache、page_cache、session 使用三套不同 Redis 配置，首页正常但登录失败，或者后台正常而 cron 报错。

先按报错上下文判断是哪一个用途：前台随机退出多半是 session 写失败；配置保存或缓存清理时报错多半是 cache；整页缓存刷新失败则看 page_cache。三套连接逐个做最小读写测试，能避免只修首页缓存而客户仍然掉线。

切主机制要和Magento连接方式匹配

如果使用云 Redis 的主节点 endpoint，配置应指向会随故障切换更新的写端点，而不是某台实例 IP。使用 Sentinel 或代理时，要确认 Magento 所用客户端和配置确实支持主节点发现，不能把 Sentinel 地址当普通 Redis 地址直连。

检查 app/etc/env.php 中 cache、page_cache、session 的 server、port、database 和持久连接设置。不要在三处共用同一 database 后靠前缀勉强区分，故障排查会非常混乱。

旧的PHP长连接不会因为DNS更新立刻消失

解析已经指向新主，但 PHP-FPM worker 仍持有到旧副本的 persistent connection 时，需要按发布流程平滑重载 PHP-FPM，并重启长期运行的 consumer。先摘流量再处理，避免直接重启造成结账请求中断。

修复后分别写入 cache、session，并跑一条 cron/consumer 任务。再做一次受控切换，观察应用恢复时间、DNS TTL 和连接重建。真正的解决不是手工改一次 IP，而是让下次故障切换时所有写连接都能自动跟随主节点。

受控切换时我会保留一条已登录客户会话并持续请求，同时监控新登录、购物车写入和后台保存。缓存可以短暂 MISS，但 Session 不能在主从切换时被写到两边形成分叉。如果架构无法保证会话一致性，至少要明确故障窗口和用户影响，而不是仅凭 Redis 监控变绿宣布恢复。

先确认订单属于哪个Stock

Website 会映射到 Stock，Stock 再包含多个 Source。网站如果挂错 Stock，后面的算法再聪明也只能在错误的仓库集合里选。后台逐层核对 Website → Stock → Source，并确认每个 Source 已启用、商品 Source Item 状态为 in stock。

Priority算法不会理解“离客户最近”

默认 Source Priority 按后台配置顺序扣减，它不知道地理距离。Distance Priority 才会结合地址与距离提供方，但还依赖完整的发货地址、国家地区代码、经纬度或距离服务配置。看到“选错仓”先确认当前使用的是哪个算法。

在创建发货页面记录系统给出的 source 和 qty 建议，然后对照各 Source 的可用数量。不要只查 inventory_source_item 的 quantity，reservation 会影响 salable quantity，而算法还可能考虑是否能完整满足发货。

bin/magento inventory:reservation:list-inconsistencies
bin/magento indexer:status inventory

自定义算法要检查输入，而不只是排序代码

如果项目按省份、邮编或仓库成本自定义选择策略，先把订单地址、候选 Source、可用数量和排序分数写入结构化日志。地址字段为空、邮编格式不同或地区名称被翻译，都可能让算法走默认仓。

还要区分“推荐来源”和“实际发货来源”。管理员可以手动改 Source，ERP 也可能忽略 Magento 建议自行分仓。最终库存从哪扣，要看 Shipment 和 Source Deduction 执行记录，而不是只看下单页面。

如果订单已经发货却扣错仓，沿消息队列检查 source deduction message 使用的 source_code 和 sales_channel。异步消费者停掉时，后台可能已经生成 Shipment，但 Source Item 数量尚未更新；这时重复创建补偿脚本反而会二次扣减。先确认消息是否仍在队列、是否失败以及 reservation 是否已释放。

距离算法还要留意地址质量。国家、省份和邮编缺一项时，距离服务可能无法计算并回退到优先级。把算法返回的候选列表、距离和回退原因记下来，才能解释为什么某笔订单去了远仓，而不是凭地图肉眼判断。

修复后用同一 SKU 测试单仓可满足、需要拆仓、最近仓缺货和虚拟商品四种订单。只测试库存充足的一单，很容易把优先级调整误认为距离算法已经正常。

先确认用于配置的属性本身合格

颜色、尺寸等属性必须是合适的 Catalog Input Type，作用域通常为 Global，并启用用于创建可配置商品。父商品和所有子商品要使用包含这些属性的同一个属性集。属性代码、选项 label 和导入值要完全对应，注意前后空格与大小写。

子商品应先存在，再让父商品引用SKU

我通常把流程拆成两次：先导入简单商品，确认 SKU 和属性值；再导入可配置父商品及关联字段。这样失败时能明确是商品创建问题还是关系问题。

sku,product_type,attribute_set_code,color,size
shirt-red-s,simple,Default,Red,S
shirt-blue-m,simple,Default,Blue,M

父行的 configurable_variations 需要按 Magento 当前导出样例的格式列出每个子 SKU 及其属性组合，configurable_variation_labels 则负责前台显示名称。不要凭印象手写分隔符，先从同版本后台创建一个最小商品并导出，拿它作为模板。

导入行为和多网站字段也会影响结果

Add/Update、Replace 的处理方式不同。Replace 可能先删除再重建关系，缺少某一列时结果和 Add/Update 不一样。子商品如果不属于父商品所在 website，或者状态、可见性、库存不合理，后台关系可能存在但前台组合仍不可选。

导入后先在父商品后台看关联，再检查前台初始化 JSON。必要时重建 configurable、product EAV、price 和 stock 相关索引，但只有关系表已经正确写入时重建才有意义。

批量文件上线前，我会用两个属性、两个子商品做十行以内的小样，确认格式后再扩大。最终检查父商品的每个组合、子商品独立 SKU、网站分配和价格库存。比起反复导入几万行，这种最小样本更快找到具体是哪一列把关联吃掉了。

先把最终请求URL完整记录下来

数组参数经过 SDK、网关和 URL 编码后很容易变形。确认服务端实际收到的是 searchCriteria[pageSize] 和 searchCriteria[currentPage]，页码从 1 开始。响应中的 total_count 是匹配总数，不是当前页条数。

?searchCriteria[pageSize]=100
&searchCriteria[currentPage]=2
&searchCriteria[sortOrders][0][field]=entity_id
&searchCriteria[sortOrders][0][direction]=ASC

稳定排序字段必须尽量唯一。只按 updated_at 排序时，同一秒更新的多条记录顺序可能变化；可以把 entity_id 作为第二排序，或者直接采用“上次最大 ID”方式做游标式增量。

同步期间数据在变化，offset分页天然会漂移

第一页拉完后有人新增或删除商品，第二页的 offset 已经对应另一组数据，于是产生重复或漏项。对实时变化大的订单接口尤其明显。可行做法是固定时间窗口，例如只取 updated_at 小于任务开始时间的数据，并保存最后成功同步的时间和 ID。

筛选条件也要正确分组：同一个 filter_group 内通常是 OR，不同组之间是 AND。把“更新时间大于 X”和“小于 Y”放错组，会让数据集远大于预期，表现得像分页失效。

客户端要以主键去重，但不能靠去重掩盖漏数

接收端用 entity_id 或业务唯一键做幂等写入是必要的，不过任务结束仍应核对拉取的唯一 ID 数与预期窗口 total_count。若不一致，保存每页的首尾 ID，便于重跑和定位。

最后用三种场景验证：静态数据全集、同步过程中新增一条、同步过程中更新同一秒的多条。只有在数据变化时也不漏不重，分页方案才适合生产集成。

用同一个Token绕过每一层测试

从浏览器复制请求为 curl，分别请求公网域名、CDN 后的源站地址和本机 upstream。响应在哪一层开始变化，就查那一层的头转发。日志只记录 Authorization 是否存在和长度，不要打印完整 Token。

curl -i https://shop.example.com/graphql   -H 'Content-Type: application/json'   -H 'Authorization: Bearer REDACTED'   --data '{"query":"{customer{firstname}}"}'

Nginx、Apache、负载均衡和 WAF 都可能过滤 Authorization。PHP-FPM 环境还要确认该头以预期变量传入。修配置后在应用入口做一次临时的“是否收到”日志，比重复生成 Token 更快。

如果公网请求丢头而直连 PHP 正常，要沿代理链一段一段加回。Nginx 常见的是 FastCGI 参数没有传递 HTTP_AUTHORIZATION；Apache 可能被 rewrite 或安全模块处理；CDN 则可能没有把该头加入允许转发列表。修改任何一层后都用同一条 curl 复测，避免同时改三处后无法判断真正原因。

确认Token属于客户，而不是集成或后台用户

Magento 的 customer、admin 和 integration token 用途不同。用生成客户 Token 的 mutation 重新生成一枚，在没有 CDN 缓存的环境直接查询 customer。还要带正确 Store 头，多网站共享邮箱时，Token 的网站上下文不一致会产生权限或数据差异。

缓存不能只按GraphQL正文区分

如果游客先请求相同 query，CDN 随后把缓存响应发给登录客户，看起来就像 Token 被忽略。检查 GraphQL POST/GET 的缓存规则、Vary 信息以及 Magento 返回的缓存标识。包含 customer 私有数据的请求不应该命中公共游客缓存。

我会在响应头里记录 cache HIT/MISS，并用两个不同客户的 Token 交叉测试：A 不能看到 B 的数据，登录请求也不能复用游客响应。这比只验证“终于返回 firstname 了”更重要。

对于只查询公开商品的请求，也别简单地把 Authorization 从缓存键删掉。登录客户可能有专属客户组价格、共享目录或可见性。可以先对照 Magento 返回的缓存上下文标识，再配置 Varnish/CDN；自己拼一个只按 query hash 的键，最容易造成跨客户数据污染。

修好后再测试 Token 过期、空 Authorization、错误 Store 头和并发请求。最终结论应明确是代理丢头、Token 类型、网站上下文还是缓存键，而不是把所有 GraphQL 401 都归到“重新登录”。

先把“邮件没数据”和“模板取不到”分开

临时切回当前版本自带的订单模板发送测试。如果默认模板正常，发送流程、订单对象和队列基本没问题；只需迁移自定义模板。若默认模板也缺值，再检查调用 Sender 时传入的 template vars。

在后台加载默认模板，查看页面列出的可用变量。新模板常使用已经整理好的变量，例如 order_data 中的 customer_name，而不是在模板里层层调用订单对象。

不要继续在模板里调用getData和任意方法

旧写法可能类似从 order 对象继续取 payment、address，再调用方法。严格模式下这些访问会被拦截或返回空。正确做法是在发送邮件的 PHP 代码里先把需要的数据整理为标量或安全对象，再作为命名变量传给模板。

$transport = [
    'order' => $order,
    'order_data' => [
        'customer_name' => $order->getCustomerName(),
        'custom_reference' => (string)$order->getData('custom_reference')
    ]
];

示例只说明思路。实际项目应尽量扩展现有 transport，而不是复制整个 Sender。自定义字段还要做合适的 HTML 转义；只有确实是可信 HTML 的内容才使用 raw。

队列会让你一直看到修改前的结果

异步发送开启时，测试邮件可能是队列里旧任务生成的。记录订单号、模板 ID 和入队时间，清楚地区分新订单与旧消息。也要确认配置作用域选中了你刚修改的模板，多商店经常仍引用另一份副本。

我最后会测试游客订单、注册客户、缺少自定义字段和包含特殊字符的客户名。模板不报错只是最低要求，还要保证空值有合理兜底、HTML 没被意外转义，并且不重新开放任意方法调用。这样升级后的模板才是真正兼容，而不是暂时绕过限制。

先看导出请求带了哪些筛选条件

打开 Network，点击导出，保存请求参数。UI Grid 的筛选、选择方式和 namespace 会一起传给导出控制器。页面上看似已经清空筛选，用户 bookmark 里可能仍保存着日期、store 或状态条件。

用 Reset Filters 后再导一次，并换一个从未打开过该 Grid 的管理员账号测试。如果新账号正常，优先清理或重建该用户的 UI bookmark，而不是改订单表。

SELECT bookmark_id, user_id, namespace, identifier
FROM ui_bookmark
WHERE namespace = 'sales_order_grid';

不要直接删除所有人的 bookmark。先备份并只处理故障用户和对应 namespace，否则别的后台列表布局也会被重置。

有自定义列时检查导出用的collection

页面数据有时来自插件改过的 DataProvider，而导出请求走另一条 collection 链路。自定义 join 使用 inner join、重复 alias 或只在普通请求下注入条件，都可能让导出 collection 变成空集。

临时去掉自定义列并不能证明字段本身有问题，要对照生成 SQL。记录普通 Grid 和 export 请求的 where、join、store scope 差异，尤其检查批量选择参数是 selected 还是 excluded。

异步导出还要看消费者和文件权限

部分版本或扩展会把大批量导出交给消息队列。请求立即成功但文件为空或迟迟不生成，就检查对应 consumer、队列记录和 var/export 的写权限。Web 节点与 consumer 节点使用不同共享目录时，也会发生任务写完但下载节点找不到文件。

修复后分别验证：无筛选导出、按日期筛选、只勾选两单、排除一单以及非超级管理员。CSV 行数应该和 Grid 当前条件一致，自定义金额列也要核对一两条原始订单，避免“有数据了”却导出错行。

先确认订单是不是已经被自动开票

进入 Invoices 标签，看是否已有发票。很多网关配置 Capture 时，会在回调成功后自动创建发票；管理员再找按钮属于重复操作。对照每个 order item 的 qty_ordered、qty_invoiced 和 qty_canceled，剩余可开票数量为零时按钮本来就不该出现。

状态标签正常，不代表内部state允许开票

自定义 status 可以挂在错误的 state 下。页面显示“已付款”只是文本，内部如果是 canceled、closed、holded 或 payment review，canInvoice() 仍会返回 false。用订单 ID 对照 sales_order 的 state/status，并检查是否处于 hold 或支付审核。

SELECT entity_id, increment_id, state, status,
       total_qty_ordered, total_invoiced
FROM sales_order
WHERE increment_id = '000000123';

不要直接在数据库里把 state 改成 processing。订单、支付、发票和库存是一组状态机，手改一列可能让按钮出现，却留下金额和交易记录不一致。

Payment Action决定什么时候生成发票

Authorize Only 通常保留后续 Capture；Authorize and Capture 往往由支付模块自动开票。第三方网关若在回调里只改订单状态、没有正确登记 transaction 或 invoice，也会产生“看似支付成功但不能开票”的半状态。

查看 payment additional_information、authorization transaction 和网关回调日志，确认是否还有可捕获金额。退款、部分开票和虚拟商品也要分别计算，不要只看 grand_total。

定位时我会在测试环境记录 canInvoice() 返回前各项条件，而不是用插件强行让按钮显示。修复支付回调或订单状态映射后，新订单应能按预期自动开票或显示按钮；旧订单则需要按真实交易状态做数据修复。最终拿全新订单测试，避免历史脏数据让结论失真。

先在页面源码里找子商品价格

查看可配置商品初始化 JSON，重点看 attributes、optionPrices 和子商品 ID 的对应关系。两种颜色的 optionPrices 本来就相同，问题在服务端价格计算或索引；JSON 里价格不同但页面不变，才是前端事件没有驱动 priceBox。

同时确认子商品的 website、客户组价格、special price 日期和货币。后台看到的基础价格不一定等于当前客户组最终价格。

bin/magento indexer:reindex catalog_product_price
bin/magento cache:clean block_html full_page

只在索引确实缺失时执行，不要把这两条当成固定仪式。重建前后都应该对比初始化 JSON，否则无法证明是索引修好的。

JSON正确时，跟着change事件往下查

在浏览器 Console 观察选择颜色后是否选中了对应 simple product，页面有没有 JavaScript 异常。第三方主题经常复制旧版 configurable.js 或 swatch-renderer.js，升级 Magento 后方法签名变了，错误被其他脚本吞掉，只剩价格不更新。

检查 priceBox 节点的 data-role 是否仍然存在，是否出现两个相同 ID 的价格容器。快速购买、Sticky Header 或自定义图库可能克隆了表单，事件更新的是隐藏区域，用户看到的那一块自然不变。

别把所有差价都写进前端脚本

有人为了赶进度在 onchange 里手工加 20 元，这会绕过客户组价格、税、货币格式和促销规则。正确修复应该让前端使用 Magento 输出的最终价格结构，只修复选项到商品 ID 的解析或 priceBox 更新链路。

最后测试不仅要点颜色，还要覆盖颜色+尺寸组合、缺货组合、登录客户组和含税显示。若只有某个组合不更新，通常是允许组合索引或子商品数据问题；若所有组合都不更新，才集中查主题 JS。这样排查比“索引和静态资源全清一遍”更容易留下可复现的结论。

先证明这件商品真的命中规则

把条件缩到最小，只保留一个可明确验证的 SKU 或属性。确认 Website、Customer Group、生效日期和商品在当前 store view 的属性值。用于规则的属性如果刚改过“Use for Promo Rule Conditions”，也需要让相关索引和缓存认识到新配置。

特殊价格和目录规则同时存在时，前台通常取可用的最低价格。商品本来就有更低的 special price，会让人误以为规则没执行。测试时记录 regular、special、rule 三种价格，不要只盯最终数字。

看价格索引状态和Cron，不要只看命令最后一行

bin/magento indexer:status catalogrule_rule catalogrule_product catalog_product_price
bin/magento indexer:reindex catalogrule_rule catalogrule_product catalog_product_price
bin/magento cron:run --group=index

Update by Schedule 模式依赖 cron 和 changelog。索引显示 Ready 不代表刚修改的规则已被消费，还要看 mview_state 的版本是否推进、cron_schedule 中相关任务是否成功。生产环境不要习惯性把所有索引切成 Update on Save，它可能把后台保存规则变成一个很重的同步操作。

直接对照索引表比反复清缓存更快

用产品 ID、website ID、customer group 和日期查询规则索引，确认是否产生记录以及 rule_price 是多少。没有记录就回到匹配和索引链路；有正确记录但页面错误，才检查价格缓存、全页缓存和第三方价格插件。

多网站项目尤其容易把规则建在默认网站，却在另一个网站测试。Catalog Price Rule 的作用范围不是仅靠 store view 名称判断，数据库里的 website_id 才是关键。

修复后我会用游客和目标客户组各打开一次商品页、分类页和购物车，并等跨过一个日期边界再确认 cron 能自动切换。一次手工 reindex 能让价格出现，不等于线上调度已经恢复。

用一辆最简单的购物车复现

我会先清空购物车，只放一个确认应该参与活动的简单商品，并用无痕窗口登录正确客户组。复杂购物车里混着 bundle、赠品、虚拟商品和免折 SKU，很难看出是哪条条件排除了折扣。

后台逐项核对 Website、Customer Groups、起止日期、Uses per Customer 和 Coupon Uses。日期要按商店时区理解，不要拿服务器 UTC 直接判断。规则过期或次数用尽时通常不会正常应用，但自定义模块可能保留前端成功提示，所以仍要查。

Conditions和Actions不是一回事

Conditions 决定整辆购物车是否进入规则，Actions 下方的条件决定哪些行真正打折。最常见的是上面按分类判断通过，下面又把该分类排除了；或者配置“仅匹配以下条件的商品”，但用的是不可用于促销规则的属性。

检查商品在当前 store view 的真实属性值，不要只看 All Store Views。可配置商品还要确认条件落在父商品还是子商品，购物车里的实际 item 对应哪个 SKU。

优先级和Stop Further Rules会让后面的规则看似失效

临时停掉其他购物车规则，只留这一条测试。如果折扣出现，就按 sort order 逐个恢复，并检查前一条是否开启 Discard subsequent rules。多张优惠同时存在时，也要确认系统是否允许叠加。

代码层我会观察 quote 的 coupon_code、applied_rule_ids 以及各 item 的 discount_amount。coupon_code 有值而 applied_rule_ids 为空，说明规则校验没通过；规则 ID 已应用但金额为零，则继续看 Action 计算和商品行。

bin/magento cache:clean config full_page
bin/magento indexer:status

购物车规则本身不像目录价格规则那样只靠一次 reindex 就能解决。修复后要重新触发 collect totals，最好新建购物车验证，避免旧 quote 保存的金额干扰。最终至少测试游客、目标客户组、临界金额和被排除 SKU 四种情况，确认规则不是只在“刚好那辆购物车”里有效。

先沿着异常栈找到是谁需要这个接口

报错最后一行常常只有接口名，真正有价值的是上面第一个自定义类。查看它的构造函数，确认参数类型是不是你预期的接口。有时 IDE 自动导入了同名但不同命名空间的 Interface，怎么改 di.xml 都不会对。

bin/magento setup:di:compile -vvv
bin/magento module:status Vendor_Module
grep -R "完整接口名" app/code vendor/*/*/etc -n

搜索结果里重点看 preference、type argument 和 virtualType。一个接口可以在全局 etc/di.xml 有实现，但某个 etc/adminhtml/di.xml 或 etc/frontend/di.xml 又改了参数。CLI 编译读取的配置范围和浏览器请求并不完全一样，所以“后台能用”不能证明全局 DI 正确。

再看异常发生在 application code generation 的哪一步。Repositories、Factories、Proxies 和 Interceptors 的错误上下文不同：Factory 生成失败经常是目标类或构造函数不可用；Interceptor 失败则要检查被插件的方法是否允许拦截、插件类本身能否实例化。不要只复制异常最后一句去搜索。

检查提供实现的模块是否真的在依赖链里

如果实现来自另一个模块，调用方的 module.xml 应通过 sequence 表明加载关系，composer.json 也应声明包依赖。只依赖服务器上碰巧安装的模块，换一套环境就会在编译阶段暴露出来。

另外核对具体类是否可实例化：是不是 abstract、构造函数又依赖了同一个接口形成循环、类文件大小写是否和 Linux 文件系统一致。开发机在不区分大小写的文件系统上能跑，并不代表生产机也能自动找到。

用生成后的DI信息验证，不靠清缓存碰运气

修改后删除的应该是可重新生成的编译产物，并按照项目部署流程重新编译；不要把 vendor 和配置文件一起删掉。编译通过后，再用 DI 信息命令确认接口最终解析到哪个类：

bin/magento dev:di:info 'VendorModuleApiSomeInterface'

如果这个命令得到的实现和设计不一致，继续查覆盖顺序。只有确认“谁请求接口、哪个配置提供实现、最终合并结果是什么”，这个问题才算解决。临时把接口改成具体类虽然可能过编译，却会破坏可替换性，也容易在下次升级时再次爆掉。

发布前还要在一套干净目录执行 composer install 后重新编译。开发机残留的 generated 文件可能让错误暂时消失，CI 的全新工作区更能证明依赖声明与 DI 配置完整。若只有生产报错，比较启用模块列表和 composer.lock，而不是把生产生成目录复制回开发机。

第一步看那条保存请求究竟处于什么状态

打开浏览器 Network，重新保存一次，找到 product/save 请求。Pending 说明服务端还没结束；500 要看响应体和 exception.log；302 跳登录页多半是 Session 或 Form Key；200 却返回整页 HTML，则可能被 WAF、登录重定向或 PHP Warning 污染。

我会把请求开始时间记下来，再按同一时间段查日志，避免在几百 MB 的文件里盲搜：

tail -f var/log/system.log var/log/exception.log
journalctl -u php-fpm --since "5 minutes ago"

如果 PHP-FPM 日志显示 worker 超时或内存耗尽，先记录商品 SKU、图片数量和属性集。只有特定商品失败，通常是数据或媒体问题；所有商品都慢，才更像全局插件、数据库或基础设施。

Pending请求要查数据库正在等什么

SHOW FULL PROCESSLIST;
SHOW ENGINE INNODB STATUSG

长时间处于 Waiting for table metadata lock、更新价格索引表或 URL Rewrite 表，说明请求不是“死了”，而是在等锁。此时重启 PHP 只能让请求消失，锁的来源仍然存在。找到持锁事务和对应业务后再决定结束连接，别直接清空进程。

若数据库没有等待，我会在测试环境打开一次 Magento profiler，或者用 PHP-FPM slowlog 抓正在执行的调用栈。保存耗时稳定在同一个 Observer 或 Plugin，才有资格继续读那段代码。耗时飘忽且集中在远程域名，则检查 DNS、HTTP 超时和失败重试。很多“商品保存很慢”其实是在同步图片或通知 ERP，Magento 只是同步等待它返回。

图片较多的商品还要观察临时目录、磁盘 inode 和图片处理进程。上传预览成功并不代表保存时从 tmp 移动、生成角色图和缓存图都能完成。拿一个无图片的简单商品做对照，能快速把 EAV 保存与媒体处理拆开。

临时绕开插件时要一次只缩小一层

商品保存周围经常有 ERP 同步、自动生成 URL、图片压缩和审计插件。用 profiler 或插件日志确认耗时；在测试环境按模块逐个验证，不要在线上一次性禁用几十个模块。尤其检查 afterSave、aroundSave 中是否调用外部 HTTP 接口且没有超时。

还有一种情况是保存已经成功，前端在等待后续 Ajax 或页面跳转。刷新后若数据已落库，就检查返回内容是否混入调试输出，以及后台 JS Console 是否报错。最终修复标准不是“转圈没了”，而是保存请求耗时稳定、响应码正确、同类商品和大图商品都能完成，并且没有生成重复 URL 或半套索引数据。

先只申请一次，然后保留原始链接

连续点击“忘记密码”会生成新的重置 Token，之前邮件里的链接随即失效。测试时只提交一次，等队列发出邮件后复制完整 URL，不要让邮箱安全扫描器截断参数。重点确认链接里是否同时带有客户标识、Token 和正确的网站域名。

可以在测试账号上对照数据库中的时间与 Token 字段，但不要把 Token 发到工单或群里。线上排查只记录是否变化、生成时间和客户 ID 即可。

SELECT entity_id, email, website_id,
       rp_token_created_at,
       CASE WHEN rp_token IS NULL THEN 'empty' ELSE 'set' END AS token_state
FROM customer_entity
WHERE email = 'test@example.com';

提交一次后刷新查询，如果 Token 很快又变化，说明有第二次请求、自动化脚本或客服后台操作覆盖了它。邮件发送延迟也会造成旧邮件晚于新邮件到达，客户点开的其实是已经被替换的那一封。

自定义邮件模板最容易丢参数

升级后沿用很老的模板时，不要凭记忆拼重置地址。先临时切回当前版本自带模板发一封测试邮件。如果默认模板可用，自定义模板不可用，问题就在变量或转义方式，而不是控制器。

还要检查配置作用域。多网站允许相同邮箱属于不同 website，生成 Token 的网站和打开链接的域名必须一致。反向代理把 Host 改错、邮件 Base URL 使用主站域名，也可能把客户带到另一套 website 上校验。

时间要比较数据库、PHP和应用节点

date -u
php -r 'echo gmdate("c"), PHP_EOL;'
mysql -e "SELECT UTC_TIMESTAMP(), NOW();"

Magento 保存的时间、PHP 默认时区和数据库会话时区如果混在一起，日志看着只差几分钟，校验时却可能已经超过配置窗口。先统一 UTC 基准，再检查后台 Password Recovery Link Expiration Period 的网站级配置。

修好后我会做两组验证：同一账号申请两次，确认第一封确实失效、第二封可用；不同 website 上的同邮箱各申请一次，确认链接只在所属站点生效。这样才能证明修的是 Token 流程，而不是碰巧让某一封邮件通过。

先确认不是30秒时间窗的问题

TOTP 验证码依赖服务器与手机时间。如果只有一台手机失败，先让手机开启自动日期和自动时区；如果所有管理员突然一起失败，就检查服务器时间，而不是逐个重置账号。

date -u
timedatectl status
chronyc tracking

我会同时看应用节点的时间。多节点环境里，某一台机器慢一分钟，就可能表现为验证码偶发成功、偶发失败。NTP 修好后再试一次，避免把一个基础设施问题改成账号问题。

换手机并不会自动迁移Magento里的密钥

旧手机没有导出验证器账号，新手机扫描的如果不是当前后台用户对应的二维码，生成的数字当然永远不匹配。还能用另一位超级管理员登录时，直接到用户管理中找到该账号，在 2FA 页面执行 Reset。下次登录会重新出现配置流程。

后台没人能登录时，可以从 Magento 根目录只重置这个用户，不要为了省事关闭整个 2FA 模块：

bin/magento security:tfa:reset admin_username google

具体 provider 名称先根据当前版本和已启用模块确认。重置成功后，用无痕窗口重新登录并扫描新二维码。原窗口可能还保存着旧的登录状态和 2FA Cookie，继续在原页面刷新会制造“命令没生效”的假象。

仍然无效时看账号和请求落在哪台机器

检查执行命令的数据库是否就是线上后台使用的数据库，也要确认负载均衡后所有节点读取同一份加密配置。若迁移环境时更换了加密 key，旧的加密数据可能无法正确读取，这时日志里通常不只出现验证码错误，还会伴随解密异常。

最终验证不要只看能否进首页。我会退出后台、清掉该域名 Cookie，再完成一次完整登录，随后确认用户的 2FA 记录已经重新生成。这样可以排除当前 Session 恰好还有效的情况。核心思路是：先校准时间，再重置单个用户，最后才考虑模块和加密配置，别上来就禁用 2FA。

先还原订单履约状态

记录 order、invoice、shipment、credit memo 的 ID 与时间，商品是否已发货、从哪个 Source 发货、退款数量和是否勾选 Return to Stock。未发货订单的取消与已发货订单的退货，库存事件不同；虚拟商品也不存在物理回库。

部分退款尤其要按 item 检查。订单买 5 件、发 3 件、退 2 件时，系统不能凭总数猜回哪个仓库。后台操作界面可能只显示数量，但 MSI 需要明确 Source 上下文。

MSI 中 Source Quantity 与 Salable Quantity 分开变化

下单 reservation 先影响 salable，发货再扣 Source Quantity 并做补偿。退款回库可能增加具体 Source 的物理数量，同时通过事件影响可销售状态。用服务接口或只读查询按 SKU、stock、source 和订单 reservation 对账，避免只看商品编辑页总数。

php bin/magento inventory:reservation:list-inconsistencies
php bin/magento queue:consumers:list
php bin/magento indexer:status inventory

若回库事件已产生但前台未变化，检查库存消费者与索引；若根本没有事件，回到 Credit Memo 参数、插件和订单状态。

ERP/WMS 集成决定谁是物理库存事实源

部分项目规定 Magento 只申请退货，仓库验收入库后由 WMS 增加数量。此时退款当刻不回库存可能是正确设计。必须和业务确认“退款即回库”还是“验收后回库”，并保证两边不会各加一次。

Webhook 和队列要用 creditmemo_id、order_item_id 等稳定键保证幂等。外部回调重放时，不能重复增加库存。失败消息应可重试且保留状态。

完整验收要覆盖四条路径

未发货取消、已发货全额退货、部分退货、不回库退款分别测试。每条路径对比 Source Quantity、Salable Quantity、reservation 合计、订单状态和 ERP 记录。最后再下一个测试订单，确认恢复的库存确实可售且不会超卖。退款金额正确只是财务闭环，库存还需要自己的闭环。

先保留未经格式化的原始金额

页面通常只显示两位小数，数据库和计算过程中可能保留更多精度。记录 quote 与 order 的 base_subtotal、discount、shipping、tax、grand_total 及对应非 base 字段，同时保存商品 qty、税率和是否含税。用相同数据在表格中逐行重算，找出第一次舍入的位置。

Unit Price、Row Total 与 Total 算法结果本来就可能不同

按单价计算会先对每个单件税额舍入，再乘数量；按行计算先乘数量，再对行税额舍入；按总计计算又在更高层聚合。多商品、多数量时差一分钱并不意外，关键是购物车、订单、发票和外部支付使用同一种事实。

后台 Tax Calculation Method、Catalog Prices 是否含税、Shipping Prices 是否含税、Apply Customer Tax 与折扣先后顺序都要按 Website 作用域核对。不要只截图一个配置项。

折扣分摊与多币种会再增加一次舍入

购物车折扣按比例分到每个 item 时，尾差必须落到明确行。base currency 换算为 order currency 后又会舍入。支付模块如果重新用显示金额计算明细，而不是使用订单已计算字段，就可能得到另一套结果。

外部支付明细必须可回算到订单总额

构建 line items 后，在发送前程序化断言：商品、运费、税、折扣合计等于请求总金额。若支付服务要求每行两位小数，设计明确的尾差分配规则，通常把差额落在最后一条合适项目，而不是悄悄修改订单。

用矩阵而不是单个订单验收

测试单件、多数量、多个税率、优惠券、含税价、运费税、多币种、部分发票和部分退款。每一步比较 quote、order、invoice、credit memo 与支付平台。允许的显示差异要有解释，提交和结算金额必须完全对得上。税额问题真正的终点是全生命周期可对账。

先定义每类页面的唯一地址

商品页是否包含分类路径？同一商品在多个分类下是否统一到无分类路径？分页、排序、筛选参数是否应该 canonical 到自身、第一页或上级分类？先把规则写清楚，再看代码。没有策略时，技术修改只会从一个错误变成另一个错误。

检查 Store View 的 Base URL 与产品分配

分别在每个 Store Scope 读取 secure Base URL，确认域名、路径和尾斜杠。商品必须真正分配到对应 Website，并有该 Store 的启用状态和 URL Key。若德文站只是前端代理英文 Store，Magento 自然生成英文上下文。

查看最终 HTML head 中所有 canonical 和 hreflang。主题、核心功能和第三方 SEO 模块可能同时输出标签，出现两个 canonical 比没有更糟。搜索源码时不仅找 rel=canonical，也要检查 layout block 与 head additional。

hreflang 不是 canonical 的替代品

不同语言页面通常各自 self-canonical，再用 hreflang 相互关联。每个 hreflang 目标应返回 200，并最好形成互相引用；不存在翻译时，不要凭 URL 规则生成一个 404。x-default 是否使用，取决于站点的语言选择策略。

缓存上下文容易造成串域

自定义 canonical block 如果 cache key 不包含 Store ID，首次由英文站缓存后，德文站也可能拿到英文域名。Varnish/CDN host key 配置错误也会造成跨域缓存。用不同 Host 连续交叉请求，检查响应 Age 和标签是否跟随 Store。

验收选商品、分类、CMS、分页和带筛选参数页面，在每个域名检查唯一 canonical、hreflang 互链、状态码和最终跳转。再用站点爬虫生成矩阵，避免只手工检查首页。SEO 标签看似一行 HTML，背后其实是完整的多商店 URL 模型。

先确认这条 Sitemap 属于哪个 Store View

后台每条 sitemap 记录有明确 Store View 和文件路径。多商店环境要逐条核对，不要复用一条记录期待它自动覆盖所有域名。生成 URL 时会读取对应 Store 的 secure/unsecure Base URL，因此作用域配置错误会把整份文件指向错误站点。

用 CLI 或后台生成后，记录生成时间、文件大小和 URL 数量。文件没更新时，检查目录权限、只读 release、共享存储和多节点。后台节点写入本地磁盘，而公网请求落到另一节点，会得到旧文件或 404。

空文件先检查实体是否具备进入条件

商品需要在目标 Website 启用、可见，并符合 sitemap 配置；分类、CMS 页面也受启用状态和 Store View 影响。随机选择一个预期 URL，从实体分配一直查到最终 rewrite，不要先怀疑 XML writer。

若数据库有大量商品但 sitemap 只有少数，比较网站分配、可见性和索引状态。自定义插件可能在集合上添加过滤，导致某个 Store 全部被排除。

域名正确还要检查 URL 是否可访问

从 sitemap 抽样请求 200、301、404，确认不包含后台路径、noindex 页面、搜索结果或带 session 参数的 URL。多级 301 会浪费爬虫抓取预算；跨域跳转说明 Base URL 或 rewrite 有问题。

定时生成与提交也要闭环

手工生成正常、第二天又旧，检查 cron_schedule 中 sitemap 任务、计划频率、时区和错误日志。文件很大时确认拆分策略和压缩产物。robots.txt 或站长平台提交的路径要与真实文件一致。

验收按 Store View 分别统计 URL 数，抽样商品/分类/CMS，验证域名、语言、canonical 和 HTTP 状态。再模拟下一次 cron，确认时间戳和内容更新。Sitemap 的价值是稳定反映可索引页面，不是后台出现一行“成功”。

从组件配置还原模板 ID

UI Component 里的 template 通常写成 Vendor_Module/path/file，对应 web/template/path/file.html。大小写、下划线和连字符必须一致。Linux 上大小写错误会 404，本地系统可能看不出来。

在 Network 找失败请求，检查状态码、最终 URL、Content-Type 和响应体。200 但响应是登录页、404 HTML 或 WAF 页面，Knockout 一样无法当模板解析。

确认当前 area、主题和 locale 的发布产物

只为 en_US 部署静态内容，zh_CN Store View 请求模板就可能缺失。主题覆盖文件如果路径不完整，也会让 fallback 结果不同。检查页面当前 locale 和 theme，而不是只在默认主题目录找。

find pub/static -path '*Vendor_Module*template*' -name '*.html'
find app/design app/code -path '*web/template*' -name '*.html'

旧 HTML 与新静态版本不匹配

发布切换后，FPC/CDN 仍返回旧 requirejs 配置或旧组件 JSON，浏览器便去请求已经清理的版本目录。静态产物应在切换前完成，HTML/FPC 清理与 release 切换顺序要固定。Service Worker 或 PWA 缓存也可能继续保存旧模板 URL。

模板加载成功后仍报错怎么办

HTML 中未闭合标签、错误 Knockout binding、引用不存在变量，可能让错误看起来像加载失败。用最小模板替换做对照，再逐段恢复 binding。不要在模板里执行复杂业务逻辑，把数据准备放进 view model。

修复后在目标 Store View、无痕窗口和生产静态合并模式测试，Network 返回正确 HTML，Console 无 binding 错误，结账步骤能前进。只让开发者自己的浏览器不报错不够，多语言和旧缓存路径必须一起覆盖。

路径必须匹配 AMD 模块名

requirejs-config.js 中的目标键应是模块 ID，不是磁盘绝对路径，也通常不带 .js。先在浏览器中确认目标组件实际通过哪个 ID 加载，主题覆盖或 bundle 可能改变你以为的路径。

var config = {
    config: {
        mixins: {
            'Magento_Checkout/js/view/example': {
                'Vendor_Module/js/example-mixin': true
            }
        }
    }
};

确认合并后的配置，而不是只看源文件

在 Network 找页面实际加载的 requirejs-config，搜索两个模块 ID。源文件正确但合并产物没有，检查文件位置是否为 view/frontend/requirejs-config.js、模块是否启用、area 是否正确，以及静态部署包含当前主题和语言。

多 release 或 CDN 环境还要核对 HTML 中的静态版本与 JS 文件版本。旧 HTML 引用旧配置时，你在服务器看到新文件也没用。

Mixin 自身必须返回正确包装

目标是 UI Component、jQuery widget 或普通对象时，写法不同。Mixin factory 必须返回扩展后的 target；遗漏 return、依赖顺序写错、方法名大小写不一致，都可能静默失败。给模块加载阶段加临时日志，再给目标方法入口加日志，能判断停在哪一层。

如果目标模块在 mixin 配置加载前已经被 require 并实例化，后补配置也不会自动改造现有实例。不要在运行中动态注入，确保配置在首次加载前合并。

用行为测试结束排查

清理最小必要静态缓存后开新会话，确认配置只加载一次、mixin factory 执行、目标方法参数和返回值符合预期。再测试生产合并/压缩开启的模式，因为开发模式正常不代表 bundle 后仍正常。最后移除调试日志，避免在客户浏览器输出订单或地址信息。

先确认 full action name 与实际 layout handle

商品页除了 catalog_product_view，还可能加载商品类型、布局更新、主题和 CMS 相关 handle。自定义控制器的路由名与文件名也经常写错。开启开发环境的 layout 调试或在受控日志中记录 handles，确认你的 XML 确实被加载。

remove 使用的是 layout name，不是 CSS class

浏览器里的 id、class 和模板文件名不能直接当 referenceBlock name。找到定义该 block 的原始 layout XML，确认 name。若目标是 container，应使用 referenceContainer。页面看起来相同的内容也可能由另一个 block、view model 或 JS 组件再次渲染。

<referenceBlock name="product.info.review" remove="true"/>
<referenceContainer name="sidebar.main" remove="true"/>

加载顺序可能把它重新加回来

模块 A 删除 block，模块 B 在后续 handle 又以相同或不同 name 添加。检查模块 sequence、主题继承和所有同名声明。不要只在 app/design 搜索，vendor 模块和后台 CMS Layout Update 也可能参与。

如果 block 由 PHP 在运行时创建，layout XML 的静态 remove 找不到它，需要定位创建点，从扩展机制或配置解决，而不是添加更多 remove。

哪些缓存需要清

Layout 合并主要受 layout/config/FPC 影响，静态内容部署通常与“block 是否存在”无关。开发时清最小必要缓存，避免每次全 flush 让其他问题被掩盖。生产修改应随完整发布流程，不要直接编辑 vendor。

验收不仅看元素消失，还要检查页面没有留下空容器、关联 JS 不报错、结构化数据与移动端布局正常。若删除的是扩展提供的业务入口，还要确认没有影响结账或可访问性。

把失败请求和集群内存放在同一时间线上

记录 Magento request ID、搜索词、筛选项、Store View、结果页码和发生时间。OpenSearch 侧查看 heap、GC、breaker、线程池拒绝和慢日志。只有某个复杂筛选失败，可能是聚合问题；所有查询都失败，可能是集群已长期高压。

curl -sS 'http://search-host:9200/_cluster/health?pretty'
curl -sS 'http://search-host:9200/_nodes/stats/jvm,breaker,indices?pretty'
curl -sS 'http://search-host:9200/_cat/indices?v'

接口可能暴露内部信息，只应在受控网络使用，不要把完整输出公开。

高基数字段和大聚合是常见元凶

分层导航会对可筛选属性做 aggregation。把几乎每个商品都不同的文本属性设为可筛选，bucket 数量会巨大。检查新近启用的 layered navigation 属性、字段类型和 doc_values。业务不需要的筛选应关闭，而不是让集群为它预留更多内存。

深分页、超大的 pageSize、通配符前缀和同时请求大量聚合也会放大内存。前端应设置合理分页上限，避免为了总数一次取回大量文档。

索引与分片布局也影响单节点压力

太多小分片会消耗大量固定开销，太少且过大的分片又让查询集中。检查索引前缀是否残留多套旧环境索引、replica 是否适合节点数、分片是否均匀。不要在故障时直接删除看不懂的索引，先确认 Magento 当前别名和回滚需求。

调 heap 只能在证据支持时进行

容器限制、JVM heap 和宿主机内存必须匹配，不能让 JVM 认为有更多内存而被系统 OOMKill。调整后观察 GC 暂停、查询延迟与缓存命中，而不是只看熔断消失。

最终用真实搜索词、最复杂筛选、空关键词和高并发分别压测。熔断为零、heap 能回落、P95 延迟稳定，并且业务筛选结果没有被错误删减，才是完成。

从 bulk_uuid 找到每一条 operation

先保存提交时间、调用身份、路由和返回 UUID。通过官方状态接口查看总数、成功、失败和未完成数量。若只有少数 operation 失败，先读单条错误；若全部未开始，重点查消息是否发布与对应 consumer。

数据库只读查询可用于辅助，但不同版本表结构可能变化，不要根据网上 SQL 直接改状态。状态表是结果，不是队列本身；把 open 手工改成 complete 不会执行任何业务。

确认负责拆分和执行的 consumer 都在运行

php bin/magento queue:consumers:list
php bin/magento queue:consumers:start async.operations.all --max-messages=1000

实际 consumer 名称以当前版本列表为准。检查进程管理器、cron consumers_runner、RabbitMQ 队列深度和未确认消息。队列不断增长但 consumer 无进程，是运行问题；consumer 存在却吞吐为零，查连接、权限和处理异常。

一条毒消息可能拖住整个观察

输入数据的 SKU、website、属性类型或必填字段错误，会让 operation 失败。错误处理若不断 requeue，同一条消息可能被快速重复。为消息设置可控重试和失败落点，保留错误原因，不能无限热循环。

批量请求也要控制大小。一次塞几万条虽然减少 HTTP 次数，却会放大序列化、队列和失败重跑成本。按可观测批次提交，每批保存 UUID，做到失败批次可单独重跑。

重跑之前先判断操作是否幂等

更新商品属性通常可以按最终值重试；扣库存、创建客户或触发外部同步则可能有副作用。根据 operation 的业务键检查是否已经部分成功，不能看到 bulk 仍 open 就整体再次提交。

验收时故意加入一条错误数据：正常项完成，错误项给出明确失败，bulk 最终状态可解释；consumer 重启后未完成项继续处理，不产生重复副作用。这样异步链路才真正可运维。

先证明慢的是哪个字段

从最小 query 开始，只保留 items 的 id；然后每次加回一个字段，记录响应时间、SQL 数量和 resolver 耗时。不要一上来分析完整 PWA 请求，因为多个字段、fragment 与内联查询会把问题混在一起。

在预发布启用数据库 profiler 或 APM，把 SQL 指纹聚合。若商品数从 10 增到 50，某条 SQL 次数也从 10 墠到 50，基本可以锁定对应 resolver。生产环境采样时要限制日志，不记录客户 token 和完整变量。

普通 Resolver 为什么容易制造 N+1

字段 resolver 会针对父节点逐个调用。如果每次都用 Repository 加载实体，除了 SQL，还会触发插件、扩展属性和事件。Repository 适合清晰的单实体业务边界，不代表适合循环中批量读取。

先收集当前批次所有父实体 ID，再一次查询所需数据，以 ID 建 map 返回。Magento GraphQL 提供 BatchResolver 和 BatchServiceContractResolver 机制，用于把同一字段的多个请求合并。关键不是接口名字，而是保证批量服务只查一次，并能保持输入输出顺序与缺失值语义。

批量之后还要处理重复字段与缓存

同一个请求中不同 fragment 可能访问同一业务数据，可在请求生命周期内做小范围 memoization，但不要用跨客户的静态缓存保存个性化结果。可公开缓存的 query 需要正确 cache identity；含客户、购物车或权限数据的字段不能误放进公共缓存。

防止查询本身无限膨胀

即使没有 N+1，客户端一次请求数百 items、深层嵌套关联，也会消耗大量资源。为分页设置合理上限，评估查询复杂度和超时，并让前端只取当前页面真正使用的字段。返回巨大 payload 后再由浏览器丢掉大半，是另一种浪费。

改造后用 10、50、100 个 item 做曲线：SQL 数量应接近固定或按少量批次增长，响应时间不再线性爆炸，结果与旧 resolver 一致，缓存失效也正确。性能优化不能以漏字段或串客户数据为代价。

先比较失败请求中的两个 Form Key

一个来自当前 session，另一个随表单提交。用浏览器 Network 查看请求中是否真的包含 form_key、字段是否被截断、提交前页面是否已停留很久。服务端日志只记录哈希或是否一致，不要打印完整 session 内容。

如果小表单也随机失败，优先查会话；只有字段很多的产品/配置页失败，才重点看 max_input_vars、post_max_size、Web 服务器请求限制和 WAF。

会话为什么会在后台请求之间变化

检查 Admin Cookie 的 Domain、Path、Secure、SameSite 与 Lifetime。后台通过 HTTPS，代理回源却让 Magento 认为是 HTTP，会生成不一致 Cookie。多节点如果 session 存本地文件，请求切换节点后也会拿不到原 session。

Redis session 场景查看连接错误、淘汰、TTL 与锁超时。后台保存大产品耗时很长，session 锁或连接超时可能在请求完成前就让下一请求使用新会话。

字段截断要用最小复现证明

逐步增加可配置商品选项或系统配置字段，观察 form_key 是否位于被截断部分。PHP 的 max_input_vars 按嵌套输入展开计数，页面看起来只有几百行，实际字段可能数千。修改参数后要确认 CLI 与 PHP-FPM 使用的不是两份 php.ini，并平滑重载正确的 FPM 池。

php --ini
php -i | grep -E 'max_input_vars|post_max_size'
systemctl reload php-fpm

命令行配置只能辅助，最终应通过 Web 请求暴露的受控诊断确认 FPM 值，诊断页面用完立即移除。

代理不应缓存后台页面

若 CDN/Varnish 错误缓存 Admin HTML，页面里的 form_key 属于旧会话，提交必然失败。后台路径应正确 bypass 公共缓存，响应也不应被共享。修复后跨节点连续保存、小表单与大表单都通过，长时间停留后的过期行为有明确提示，才能结束排查。

先确认客户账号共享范围

Magento 可以按 Global 或 Per Website 共享客户账号。Global 模式下，同一个邮箱全站只能有一个客户；Per Website 模式下，同邮箱可以在不同 website_id 存在。先核对当前配置，再查询实际数据：

SELECT entity_id, email, website_id, store_id, created_at
FROM customer_entity
WHERE email = :email
ORDER BY website_id;

不要用 Store View 名称代替 website_id。store_id 决定客户创建时的商店上下文，唯一性核心通常是 email 与 website 范围。CSV 中 Website 字段映射错误，会把所有客户导进默认网站，于是产生“意外重复”。

改变共享范围不是无成本开关

从 Per Website 改成 Global 前，必须先扫描跨网站同邮箱客户，因为合并后会发生身份冲突。两个账号可能有不同密码、地址、客户组、订阅状态和订单历史，不能自动认定它们是同一个人。

反过来，从 Global 改成 Per Website 后，也要决定现有客户属于哪些网站，以及登录、重置密码和 SSO 的预期。配置改变应在迁移方案里明确，而不是为了让一次导入通过临时切换。

导入文件还要处理大小写和空白

邮箱前后空格、不可见字符、大小写规范化和字符编码会导致肉眼看似不同、系统判断冲突。导入前用脚本做规范化并生成重复报告，但保留原始文件以便审计。不要把“去重”写成简单保留最后一行，客户资料可能在其他行更完整。

冲突客户要有业务决策

同一自然人在两个网站有账户，可以选择账号合并、保留网站隔离，或建立明确关联。合并时需要迁移地址、订单可见性、订阅与客户组，并通知用户密码策略。无法自动判断的冲突进入人工清单。

最终用三种账号测试：只在网站 A、只在网站 B、两个网站同邮箱。验证登录、忘记密码、下单和后台查找都符合共享策略。导入“成功”只是技术结果，客户能在正确网站继续使用账号才是业务完成。

从一个失败 SKU 沿路径追踪

记录 CSV 中 base_image、small_image、thumbnail_image 的值，以及导入界面填写的 Images File Directory。现代 Magento 导入通常以 var/import/images 为图片基础目录，CSV 应使用相对路径。开头斜杠、大小写和子目录拼接错误非常常见。

find var/import/images -type f | head
find pub/media/catalog/product -type f -iname '*example*'
ls -ld pub/media pub/media/catalog pub/media/catalog/product

Linux 区分大小写。CSV 写 /A/B/Image.JPG，文件实际是 a/b/image.jpg，开发者在不区分大小写的电脑上看不出问题，服务器会直接找不到。

原图存在，404 可能发生在缓存尺寸

分类页和商品页通常请求 pub/media/catalog/product/cache 下的派生图。清理图片缓存后，首次请求需要 PHP/GD 或 ImageMagick 重新生成。检查 Web 用户对 media 的读写权限、临时目录、图片格式和内存限制。

不要把整个 media 设置为 777。统一部署用户与 Web 用户的组权限，并确认新建文件继承正确组。损坏的 JPEG、超大 TIFF 或不支持的颜色空间也可能让缩放失败，日志里通常能看到具体异常。

多节点与 CDN 会让问题看起来随机

一台节点导入了原图，其他节点没有共享 media，请求经过负载均衡时就时好时坏。确认 media 是共享存储、对象存储，还是由发布任务同步。CDN 若缓存了 404，源站文件补齐后也可能继续返回旧失败，需要按 URL 精确清理。

验收时选主图、附加图和不同尺寸缩略图，各自请求原图与缓存图；连续命中不同节点；再新导入一个从未使用的文件名，确认无需人工 chmod 或清 CDN 就能显示。这样才证明导入链路修好，而不是手工补了一张图。

先用 entity_id、increment_id 和 store_id 对账

SELECT entity_id, increment_id, store_id, created_at, state, status
FROM sales_order
WHERE created_at BETWEEN :from AND :to
ORDER BY entity_id;

不要只按 increment_id 搜索。Magento 的订单显示号通常与 Store 关联，不同 Store 可能使用不同 sequence，因此跨网站看到相同数字不一定违反数据库唯一约束。先确认业务要求是“全站唯一”还是“店铺内唯一”。

为什么会跳号

Sequence 号被取得后，后续事务可能失败或回滚，已经消耗的值不会自动回收。并发请求、支付失败、风控拒绝都可能留下空洞。空洞不等于存在被删除订单，更不能据此补造记录。

检查 sales_sequence_meta、sales_sequence_profile 与对应 sequence_order_* 表，核对当前 Store 使用的表、前缀、后缀与步长。只读查看 AUTO_INCREMENT 可以帮助判断下一号，但不要在营业中直接改小。

真正危险的是自定义生成器绕过原子性

有些模块用“查询当前最大值 + 1”生成订单号。在两个并发请求下，两边都可能读到同一个最大值。正确做法应依赖数据库原子序列或带唯一约束的幂等分配，不能靠 PHP 锁或毫秒时间戳碰运气。

迁移数据时也要注意导入的 increment_id 与本地序列。若导入历史订单后没有把序列推进到安全位置，新订单可能撞号；反过来盲目把 AUTO_INCREMENT 调得很大，只会造成更明显的跳号。

处理原则

如果只是合法空洞，向运营解释原因并用支付/quote 日志证明没有丢单，不需要填号。如果发现同一 Store 真正重复，立即停止相关定制生成器，确认数据库约束与受影响订单，并评估财务、发票和 ERP 引用。修复后用并发压测验证序列唯一，失败事务允许留空洞，但绝不能重复。

先保存数据库给出的死锁现场

SHOW ENGINE INNODB STATUSG

重点看两个事务各自持有和等待的索引、SQL、表与记录范围。应用异常日志只显示“死锁”，不足以判断谁先锁了 inventory、sales_order、sequence 或自定义表。开启更持续的 deadlock 日志时要评估生产开销和日志敏感信息。

把数据库线程时间与 Magento request ID、quote_id、订单增量号、消费者消息 ID 对齐。常见组合是：前台下单事务按 A→B 更新，自定义 observer 或异步回调却按 B→A 更新；两个请求并发时就形成环。

减少事务里不必要的工作

不要在数据库事务中调用外部支付、ERP、邮件或慢 API。远程请求延长持锁时间，一次网络抖动就让锁冲突概率上升。事务里只保留必须原子完成的本地写入，外部副作用在提交后通过事件或队列执行。

批量更新多条记录时使用稳定顺序，例如始终按主键升序。两个事务访问同一组行但顺序相反，是最典型的死锁来源。SQL 还要能命中索引，范围扫描会锁住比预想更多的记录。

重试必须围绕完整业务操作设计

数据库回滚后可以有限次数重试，但要加随机退避，并保证重试入口幂等。支付已授权、订单保存失败时，不能简单重新扣款。使用稳定业务键检查订单是否已存在，区分“数据库事务失败”和“外部动作已经成功”。

不要在捕获异常后只重跑最后一个 UPDATE，因为原事务其他写入已经一起回滚。重试边界应覆盖完整的本地原子操作，同时避免重复发送外部请求。

验证不能只靠压一次接口

构造同一 SKU、同一客户或同一 quote 的并发请求，持续观察 deadlock 数量、订单重复率和响应时间。确认失败事务能给用户明确结果，重试不会创建重复订单，支付与库存最终一致。死锁很难承诺绝对为零，但发生频率、恢复行为和数据结果必须可控。

给内存曲线加上消息坐标

在不记录敏感 payload 的前提下，记录 consumer 名称、消息 ID、topic、处理耗时、payload 字节数、处理前后 memory_get_usage(true) 与峰值。这样能区分：

• 每处理一条都增加少量且不回落：对象或静态缓存跨消息残留；
• 某个 SKU/订单后突然跳高：特定业务数据导致大集合；
• 失败消息快速重回队列：重试风暴不断创建异常和日志；
• 空闲时也增长：连接、监控或框架循环存在问题。

同时查看容器和宿主机指标，不要把 PHP memory_limit 异常与系统 OOM 混为一谈。

长生命周期进程和普通 Web 请求不一样

Web 请求结束后对象整体释放，Consumer 会在同一进程处理很多消息。单例服务、Registry、静态数组、第三方 SDK 客户端缓存，如果没有每条消息重置，就会长期保留引用。批量加载 collection 后也应及时释放大数组，避免把完整实体堆进后续闭包。

用固定的消息样本在预发布循环重放，配合 PHP profiler 或周期性内存快照定位增长点。不要在生产直接打印完整对象图，它可能包含客户信息，也会额外放大日志与内存。

先用有限生命周期止血，但别把它当根治

Magento consumer 支持限制处理消息数，进程管理器可在正常退出后重启。合理的 max_messages 能降低长期碎片和不可控增长，是保护措施；如果每十条消息就需要重启，仍说明代码或数据有问题。

php bin/magento queue:consumers:start consumer.name --max-messages=1000

重试也要有上限和延迟。永久失败的消息应进入明确的失败处理流程，而不是立即 nack/requeue 形成热循环。记录失败次数和最后异常，确保同一消息不会无限消耗资源。

修复后的验证方式

用小消息、正常大订单、故意失败消息三组样本，各跑足够数量。内存可以在启动阶段上升，但随后应进入稳定区间；队列吞吐不下降；失败消息按设计停止重试；进程被重启时没有未确认消息长期悬挂。只有曲线、吞吐和业务结果都稳定，才算解决。

Magento 的规则很直接：可缓存页面中只要有一个 block 不可缓存，整页就不能进入 Full Page Cache。它不是“只有这个小块不缓存”。所以把会员名字、购物车数量或实时库存直接做成不可缓存 block，代价可能是所有商品页都动态渲染。

先证明页面确实没有进入 FPC

curl -sS -D - -o /dev/null https://shop.example.com/product.html
curl -sS -D - -o /dev/null https://shop.example.com/product.html

比较两次请求的 Age、X-Magento-Cache-Debug 或 Varnish 命中标记。确认不是 Cookie、Authorization、查询参数或 CDN 规则主动 bypass 后，再查 layout。

不要只搜索自己模块

最终 layout 来自主题、核心模块和所有扩展合并。搜索所有 cacheable="false"，再按当前 full action name 确认它是否真的落在商品页。某个 default.xml 的设置影响范围可能比开发者想象大。

grep -R 'cacheable="false"' app/code app/design vendor/*/*/view/frontend/layout -n

临时禁用可疑模块或 layout handle 做对照，避免仅凭文件名下结论。开发者工具中的 profiler 和响应头可以帮助确认页面恢复缓存后的变化。

个性化内容应该怎么放

购物车数量、欢迎语、客户专属提示适合 customer-data/private content，由浏览器在公共页面加载后补齐。真正必须实时请求的数据，可以做小型 AJAX/GraphQL 接口，并设置清楚的超时与失败降级。不要为了一个十几字的客户名字牺牲整个 FPC。

如果 block 内容其实对所有用户相同，只是更新频率较高，可以使用正确 cache key、cache lifetime 和 identity tag，而不是直接关闭缓存。实体保存时精准失效，比把页面永久设成 MISS 更可控。

修复后不能只看首页变快

我会连续请求商品页、分类页和 CMS 页，确认第二次命中；再测试登录用户的私有内容没有串号，购物车数量能更新，退出登录后数据被清理。最后比较 PHP-FPM 请求数和 Varnish hit rate。性能恢复与个性化正确必须同时成立。

用同一个 SKU 列出所有可能的价格来源

我会记录 website_id、customer_group_id、currency、商品类型和日期，然后核对基础价、Group Price、Tier Price、Catalog Price Rule、Special Price 时间窗口，以及 B2B 环境中的 Shared Catalog。不要只看商品编辑页顶部价格字段。

可配置商品还要分别看父子商品。列表页展示的最低价来自关联子商品索引，不一定等于父商品保存的数值。Bundle、Grouped 商品又有各自聚合规则。

索引问题要比较维度，不要只看状态

php bin/magento indexer:status catalog_product_price
php bin/magento indexer:reindex catalog_product_price

索引显示 Ready，只代表没有被标记 invalid，不代表某个维度的行一定正确。用只读查询比较目标 entity、website 和 customer_group 的索引记录，并与后台配置来源对照。绝对不要手工 UPDATE 价格索引表，它是派生数据，下一轮索引会覆盖。

若只有计划模式延迟，检查 mview changelog 与 cron；若每次 reindex 都生成错误值，问题在价格来源、作用域或插件。第三方动态定价模块可能通过 plugin 改写 price model，却没有正确声明 cache identity。

价格正确但页面仍旧，要看缓存键是否包含客户身份

登录用户的个性化价格通常通过 private content 或带客户组上下文的缓存处理。自定义 block 如果把会员价放进公共 FPC，却使用固定 cache key，VIP 与访客就可能互相看到缓存价格。GraphQL/PWA 还要检查请求头中的 Store、Currency 与客户 token。

我会用无痕窗口建立四个互不复用的会话：访客、普通会员、VIP、批发组；分别请求商品页、分类页、搜索结果和购物车。再切换币种与 Store View，确认显示价、quote item price 和订单金额一致。只有商品展示和下单两端都正确，会员价才算真正修复。

我会先选一个具体商品，把它在所有 Store View 的 rewrite 完整拉出来：

SELECT url_rewrite_id, entity_type, entity_id, request_path,
       target_path, redirect_type, store_id, is_autogenerated
FROM url_rewrite
WHERE entity_type = 'product'
  AND entity_id = :product_id
ORDER BY store_id, url_rewrite_id;

先区分“当前主路径”和“历史跳转”

redirect_type = 0 通常是当前可访问路径；301/302 是历史或人工重定向。先画出 request_path 到 target_path 的图，确认有没有 A→B→C、A→B→A，或者两个实体争用同一 request_path。不要只按 request_path 去重，因为不同 Store View 可以合法拥有同名路径。

目标是让重要旧地址一步跳到最终 canonical URL，而不是经过多层。对仍有外链、流量或订单邮件引用的旧地址保留 301；从未上线、没有引用的生成错误记录才适合删除。

为什么重新保存商品后问题又回来

检查 Catalog URL 配置、是否在 URL 中包含分类路径、是否为旧 URL 创建永久重定向，以及第三方 SEO 模块的 observer/plugin。批量导入若每次都重写 url_key，也会持续制造历史记录。

分类层级变化会产生更多组合路径。一个商品属于几十个分类时，开启分类路径会显著扩大 rewrite 数量。先确认业务是否真的需要这套路径策略，不能一边批量删、一边让配置继续生成。

清理时给自己留回滚和验证窗口

先备份目标记录，只按明确的 entity_id、store_id 和路径集合修改。生产大表上避免一条 DELETE 扫全表，按主键分批并观察锁。清理后通过标准索引/保存流程重建当前路径，不要手写 target_path 猜内部路由。

验收清单包括：新地址 200；重要旧地址一次 301 到新地址；不存在循环；canonical 指向最终地址；各 Store View 留在自己的域名和语言；站点地图只包含当前 URL。最后从访问日志统计一周仍被请求的旧路径，再决定是否继续保留。SEO 安全的关键不是 rewrite 表有多干净，而是用户和爬虫能稳定到达唯一最终页面。

先保存一次真正失败的请求

在浏览器 Network 中找到 shipping-information 或 estimate-shipping-methods 请求，保存请求体、响应体、quote_id 和时间。地址里的 country_id、region_id、postcode 只要缺一个，某些承运商就会直接返回空集合。前端表单看起来填了省份，不代表传给后端的是有效 region_id。

我会用同一个购物车分别测试：完整地址、另一个邮编、默认配送方式和访客/登录用户。只有某个地址失败，优先看区域规则；所有地址都失败，才继续查全局配置或代码。

后台显示启用，不代表当前 Website 启用

配送配置通常有 Website 或 Store View 作用域。切换作用域后核对 Enabled、Allowed Countries、Specific Error Message、价格和最小订单条件。配置值可能在 Default 是 Yes，但当前 Website 明确覆盖成 No。

用 CLI 读取实际作用域比凭后台截图更可靠：

php bin/magento config:show carriers/flatrate/active
php bin/magento config:show carriers/flatrate/sallowspecific
php bin/magento config:show carriers/flatrate/specificcountry

第三方承运商还要检查 API 凭据、沙箱/生产地址、超时和币种。外部接口失败时，模块如果吞掉异常，只会让前端看到空数组，所以需要在 carrier 的 collectRates() 入口和返回处加临时日志，记录条件但不要记录客户完整地址或密钥。

免费配送、购物车规则和重量条件经常互相影响

查看 quote item 的重量、是否虚拟商品、free_shipping 标记和折扣规则。一个商品重量为 0，可能被承运商判定不可报价；一个购物车规则把部分商品标成免费配送，也可能让自定义模块算出负数或直接跳过。

多源库存环境还要确认当前 Stock 能否为地址提供货源。商品“有货”只代表可销售，未必所有来源都支持该区域或配送组合。若自定义 Source Selection 在报价前介入，检查它是否错误过滤了来源。

前端有旧缓存时，后端其实已经返回了方法

响应 JSON 已包含 rates，但页面仍空，问题就在 JS 状态。比较 Knockout shipping-service、checkout-data 和 customer-data 中的地址标识，确认旧请求没有在较晚时返回并覆盖新结果。切换地址后应触发重新估价，而不是继续使用上一个 postcode 的结果。

我最后会用四组用例验收：访客与登录用户、国内与国外地址、普通商品与含虚拟商品购物车、优惠券前后。每组都要确认后端返回的方法、页面显示价格和订单最终 shipping_amount 一致。只有这样，才不是“某个测试地址碰巧好了”。

先用响应头画出循环

curl -I https://shop.example.com/
curl -IL --max-redirs 10 https://shop.example.com/

记录每次 Location、主机名和协议。如果在 www 与裸域之间来回，查 canonical host；同一 URL 不断 301/302，查协议识别与 Cookie。不要一开始就关闭所有 HTTPS 强制设置。

外层代理要明确传递原始协议

负载均衡或 nginx 通常通过 X-Forwarded-Proto 告诉应用客户端使用 HTTPS。源站与 Magento 必须信任正确的头，而且只能信任受控代理来源，避免客户端伪造。

同时检查 secure/unsecure Base URL、Use Secure URLs 与 offloader header。多层代理每层追加或覆盖头的方式要一致，否则某些节点识别 HTTPS、某些识别 HTTP，会随机循环。

缓存可能继续保存错误重定向

CDN 或 Varnish 缓存 301 后，即使源站修好，外部仍可能循环。先绕过缓存验证源站，再精确清理错误对象。浏览器也会长期记忆 301，测试时用 curl 更可靠。

修复后验证首页、后台、登录、静态资源和支付回跳，确认 Location 始终使用预期域名和 HTTPS。Base URL 与 nginx 不是二选一：代理传递事实，Magento 使用事实，两边必须一致。

先确定被哪个 directive 拦截

支付 SDK 不只有脚本，还会创建 iframe、请求 API、加载字体或图片。分别记录被拦截 URL 和 script-src、frame-src、connect-src、img-src。第一个错误消失后，后续资源仍可能被拦。

在模块中做最小范围白名单

<policy id="frame-src">
    <values>
        <value id="payment-frame" type="host">https://secure.payment.example</value>
    </values>
</policy>

通过 etc/csp_whitelist.xml 为确切资源类型添加可信主机。域名来自支付商官方文档和实际 Network，请勿把整个顶级域或任意 HTTPS 放开。测试与生产域名不同要分开管理。

用 Report-Only 收集遗漏

先在预发布或受控流量观察报告，按页面与来源整理。标签管理器可能动态引入更多域名，需要和业务确认哪些真正必需。

最终测试表单展示、3DS 跳转、失败重试、保存卡与回调。浏览器无 CSP 错误只是基础，支付链路也必须完整。白名单越小，后续供应商改域名时越容易审计。

给同一次结账建立金额时间线

1. 购物车 collectTotals 后的 quote totals；
2. 前端 totals API 返回值；
3. 提交订单前发送给支付模块的金额；
4. sales_order 的金额字段。

用 quote_id 与请求 ID 串起来，比较 subtotal、discount、shipping、tax、grand_total 和 base_* 字段，找出第一次不同。只比较 grand_total 会隐藏汇率或税额舍入问题。

重复 collectTotals 本身不是修复

自定义 total collector 应该幂等。每执行一次就追加费用，通常是没有先重置自身字段，或 sort_order 与税、折扣顺序冲突。记录 collector 类名与执行前后金额，检查同一请求是否多次运行。

前端旧 totals 也可能来自 customer-data 或并发请求覆盖。Network 中看返回顺序：较慢旧请求最后回来，会把新地址对应的金额覆盖到页面，但提交时服务端又按最新 quote 计算。

支付模块使用订单金额作为最终事实

不要从页面接收可修改金额。支付请求应基于服务端订单，并正确处理 base currency 与 order currency。回调金额不一致时明确拒绝或进入人工处理，不能默默标记已支付。

修复后测试优惠券、税、配送方式、多币种和地址切换，对比前端、订单、支付平台三方金额。第一次分叉消除后才算解决。

把登录响应与下一次请求并排看

在 Network 保留日志，检查登录响应的 Set-Cookie，再看跳转请求是否携带对应 Cookie。记录 Domain、Path、Expires、Secure 与 SameSite。只看存储面板容易漏掉被浏览器拒绝的 Cookie。

• Cookie 配成 www 域，实际登录发生在裸域或其他子域；
• Cookie Path 不是站点根路径；
• HTTPS 经代理回源 HTTP，Magento 误判协议；
• 支付或 SSO 回跳需要的 SameSite 行为与设置冲突。

Base URL 与代理头必须一致

检查 secure/unsecure Base URL、强制 HTTPS 和负载均衡传递的协议头。若 Magento 认为请求是 HTTP，可能生成错误跳转或 Cookie 属性。不要通过关闭 Secure Cookie 修生产 HTTPS。

还要排除多节点 session 不共享：登录和跳转落到不同节点，而 session 存在本地文件，表现也像 Cookie 丢失。可用节点标记、Redis 监控辅助确认。

修改后覆盖真实跳转链

测试直接登录、结账中登录、退出再登录、支付回跳与不同子域入口。每条路径都确认 Cookie 被接受并发送。目标不是按钮不报错，而是同一会话在域名和 HTTPS 链路中保持一致。

先检查商品资格

确认商品属于当前 Website，状态启用，可见性包含 Search，目标 Store View 的名称、SKU 或搜索属性有值。配置商品还要确认子商品状态与库存。不要只在 Default Scope 看字段。

新建属性勾选 Use in Search 后需要索引更新；如果期望用字段筛选，还要检查 layered navigation 与搜索权重。

证明文档是否进入搜索引擎

php bin/magento indexer:status catalogsearch_fulltext
php bin/magento indexer:reindex catalogsearch_fulltext
curl -sS 'http://search-host:9200/_cat/indices?v'

核对 Magento 配置的引擎地址、索引前缀和别名。多环境共用集群时，前缀配错会导致你查看另一个环境。生产查询应限制返回量，不要随意对大索引执行通配搜索。

有文档但前台没结果，再看查询上下文

Store ID、Customer Group、库存状态和请求参数会影响最终集合。抓取 GraphQL 或搜索请求，比较关键词分词结果。中文、连字符 SKU 与特殊字符尤其容易受 analyzer 影响。

验收选完整 SKU、商品名普通词和需要分词的中文词。每个词在目标 Store View 返回正确商品，并确认新增、禁用和改名后计划索引能自动更新，才算恢复。

先核对请求的四个基本量

记录实际 HTTP 方法、完整路径、Store Code 和 Content-Type。GET 与 POST 是不同路由，/rest/V1/、/rest/all/V1/ 和带店铺代码的 URL 也不能凭印象互换。注意代理是否重写路径前缀。

检查 webapi.xml，不是 frontend routes.xml

<route url="/V1/example/:id" method="GET">
    <service class="Vendor\Module\Api\ExampleInterface" method="getById"/>
    <resources>
        <resource ref="Vendor_Module::example"/>
    </resources>
</route>

文件路径、大小写或 XSD 错误会让配置无法正确合并。模块启用后清配置缓存并在构建中重新编译，不要在线上只替换一个 XML。

接口签名也会影响服务暴露

参数名要与 URL 占位符、JSON 字段对应，复杂类型使用明确数据接口。方法只存在实现类、接口未声明，或 docblock 类型无法解析，都会在 Web API 层出问题。

先调用一个已知端点证明 REST 入口正常，再调用自定义路由。最后分别测试正确方法、错误方法和无权限身份，确认得到预期的成功、路由错误和授权错误，而不是被代理统一改写。

先在最靠近 Magento 的位置重放请求

curl -i \
  -H 'Authorization: Bearer REDACTED' \
  -H 'Content-Type: application/json' \
  https://shop.example.com/rest/V1/store/storeConfigs

不要把真实 token 写进工单或日志。可以在 nginx/PHP 层只记录头是否存在及长度，绝不记录完整值。公网失败、绕过代理访问源站成功，优先查 CDN、WAF、负载均衡和 FastCGI 参数。

401、403 与路由错误不是一类问题

401 通常是身份没被接受；403 更偏向身份有效但 ACL 不允许；404 或 Request does not match any route 要查 URL 与 webapi 路由。客户端不要把所有非 200 都显示成 token 失效。

还要分清管理员 token、客户 token 与 Integration token。客户 token 无权访问后台资源；Integration 修改 ACL 后也要重新确认授权。服务器时间漂移、token 撤销和用户禁用同样会影响认证。

随机 401 要核对多节点

按响应头或日志定位节点。节点间 env.php、加密密钥、数据库或部署版本不一致，会造成部分请求正常、部分失败。修好后连续跨节点请求，并验证只读与需要 ACL 的两个端点。

先画调用栈，不要只背排序规则

before 与 around 的进入顺序受配置排序影响，after 发生在返回过程。around 调用 $proceed() 前后的代码会包住后续链，所以日志常呈现：

before A
around A enter
before B
original method
after B
around A leave
after A

调试时为每个 plugin 打印类名、阶段和请求 ID，比只记录 plugin called 更容易确认链条。

around 不调用 proceed 会截断后续

第三方模块为了返回缓存结果，可能在条件分支直接 return。此时后面的 plugin 和原方法都不会执行。检查每条 return 路径，并确认参数、返回类型与目标方法兼容。

最终配置来自多个 di.xml 合并

同名 plugin 可以被其他模块禁用或覆盖，area 配置也会改变结果。检查模块加载顺序和生成的 interceptor。目标方法若是 final、static、构造函数或其他不可拦截范围，也不会按预期工作。

只需改参数时用 before，只改结果时用 after，确实需要包围调用再用 around。修复后用集成测试断言最终输入输出，不要把脆弱的完整日志顺序当成唯一业务契约。

用最终 DI 配置验证，不要凭文件名猜

php bin/magento dev:di:info 'Magento\Vendor\Api\SomeInterface'
php bin/magento module:status Vendor_Module

输出仍指向原实现，就检查 etc/di.xml、模块状态、sequence 和配置缓存。若只写在 etc/adminhtml/di.xml 或 etc/graphql/di.xml，全局调用不会读取该 area 配置。

Proxy、Factory 与 virtualType 会让你看错对象

调用方可能注入 Proxy、Factory、virtualType，或直接依赖另一个具体类。沿构造函数类型与 object manager 配置追踪实际实例，不要只在目标类构造函数打断点。已有 interceptor 时，也要看最终生成类和插件链。

generated 必须与当前代码同批生成

编译产物来自旧 release，源码来自新 release，会出现配置看起来对、运行时仍旧的混合状态。构建时清理旧 generated，安装依赖后编译，并随同一产物部署。线上不应边接流量边 compile。

如果只改一个方法行为，还应重新评估 preference 是否必要。Preference 会整体替换实现，冲突范围更大；能用 plugin、事件或组合完成时，升级风险通常更低。最终以 dev:di:info、实际实例类名和目标调用路径一致为准。

先在构建目录验证补丁落到了哪个文件

composer show vendor/package
grep -R "patched marker" vendor/vendor/package -n
composer install -vvv --no-interaction

补丁按旧版本上下文制作时，有的工具会失败退出，也有流水线把失败当成非阻断警告。日志里不能只搜 applied，还要确认没有 skipped、cannot apply 或目标包未安装。

构建成功，运行环境也可能没拿到同一份 vendor

镜像若在 patch 前就复制了 vendor，后续构建目录再正确也没用。进入实际处理请求的容器，核对文件校验值、镜像标签与 release 路径。多节点逐台检查，避免新旧节点同时在负载均衡里。

源码更新后还要考虑 OPcache

如果部署会原地覆盖 PHP 文件，而 OPcache 时间戳验证关闭，PHP-FPM 可能继续执行旧字节码。正确做法通常是原子发布后平滑重载 FPM，不是 flush Magento cache。涉及生成类时，再按构建流程重建 generated 和 DI。

我习惯在补丁中选稳定片段计算校验值，在 CI、镜像和线上容器三个阶段比对。验收既看文件内容，也触发原始错误路径。这样能明确是补丁没打、产物没带、节点没换，还是运行时仍缓存旧字节码。

先看进程正在做什么

ps -eo pid,etime,cmd | grep '[s]etup:upgrade'
SHOW FULL PROCESSLIST;
SELECT * FROM performance_schema.metadata_locks
WHERE LOCK_STATUS = 'PENDING';

若 SQL 等 metadata lock，通常是长事务占用了即将 ALTER 的表。先找到阻塞链与业务来源，评估能否安全结束阻塞事务，不要先杀升级会话。

没有锁，也可能在处理大表

Declarative schema、数据补丁和第三方迁移都可能扫描大表。检查当前 SQL、磁盘 I/O、临时表空间与 binlog。测试库几秒的无索引 UPDATE，在生产几千万行会完全不同。

查看 patch_list 和模块状态，定位尚未完成的 patch 类并阅读实现。补丁应可重复或明确标记完成；超大数据迁移不宜全部塞进发布命令。

中止前先准备恢复路径

确认数据库有可恢复备份，记录 release、维护模式和已完成 patch。若必须终止，先理解事务边界。重跑前解决锁或 SQL 根因。

后续在生产规模副本演练，记录每个 patch 耗时，把大迁移拆成可观察、可续跑任务。命令结束后仍要核对 schema、patch_list、核心页面和消费者。

从一个具体 404 反推文件路径

不要先删整个目录。记录完整 URL、locale、area 和版本号，然后在当前 release 查对应文件：

find pub/static -path '*frontend*' -name 'styles-m.css' -o -name 'requirejs-config.js'
ls -la pub/static pub/static/_cache

文件不存在，查命令是否包含正确语言、主题与 area；文件存在但 nginx 404，查 root、符号链接、容器挂载和权限。

静态签名会让文件存在仍然 404

HTML 若来自旧 FPC/CDN，而静态目录已经切到新 release，就会请求不存在的旧版本。应先完成新静态产物，再原子切换 release，并在合适时点刷新页面缓存。

多节点要确认每个节点都生成，或构建产物通过共享存储分发。只在一台机器手工 deploy，一半流量仍会 404。

生产不要边访问边生成

构建阶段应固定模式、依赖、主题和语言；发布阶段只做原子切换。权限由部署用户与 Web 用户组策略统一，不要用 chmod 777。

用 curl 分别请求 HTML 与引用资源，连续命中不同节点并观察 CDN。所有节点在切换前后都返回同一版本 200，链路才算稳定。

先确认字段落在哪张表

SELECT entity_id, increment_id, external_number
FROM sales_order
WHERE entity_id = :order_id;

SELECT entity_id, increment_id, external_number
FROM sales_order_grid
WHERE entity_id = :order_id;

字段只在 sales_order，XML 把列画出来也拿不到数据。应通过 declarative schema 增加 Grid 字段，并在订单保存或异步刷新时同步。不要为了省代码在列表 collection 对大表做无索引实时 join。

数据有了，列仍不见，再查 UI Component

检查 view/adminhtml/ui_component/sales_order_grid.xml 合并结果，列名是否与数据源键一致。看 Grid AJAX 响应：JSON 已有字段但页面没有，问题在前端列配置；响应没有，继续查数据源。

管理员 bookmark 会保存旧列状态

后台保存用户的列显示、排序和筛选。新列部署后，旧 bookmark 可能继续隐藏它。先在 Columns 菜单确认，再针对当前用户重置视图，不要清掉所有管理员配置。

最后测试新订单与历史订单。历史回填应分批且可重复执行。SQL、Grid AJAX 和页面三处一致，筛选与导出也能工作，才算完成。

先确认订单有没有进入邮件流程

用明确测试订单记录下单时间、网站和邮箱，再只读检查发送标记。重点不是手工把 email_sent 改成 1，而是判断系统有没有尝试发送。

php bin/magento cron:run
php bin/magento cron:run
tail -f var/log/cron.log var/log/exception.log var/log/system.log

计划生成和执行可能需要连续两个周期。还要在 cron_schedule 中按邮件 job_code 查状态与 messages。

SMTP 接受不等于收件成功

应用日志显示服务器接受，只说明上游返回成功。仍需查投递日志、退信、抑制列表和 SPF/DKIM/DMARC。只有某个域收不到，优先查投递层；所有域都没记录，才回到应用传输。

模板问题通常会留异常

不存在变量、内联 CSS 失败或编码异常，会让渲染中止。用真实订单相同 Store View 与模板测试，别拿默认商店证明另一个网站正常。

修复后创建新订单，确认自动入队、cron 准时消费、邮件服务收到且最终邮箱到达。直接改数据库标记或不停点击发送，只会模糊问题位置。

先只读生成清单

php bin/magento inventory:reservation:list-inconsistencies -r
php bin/magento inventory:reservation:list-inconsistencies -c

参数会随版本变化，先看 --help。保存结果后抽取订单核对：是否真实发货、取消、重复下单，或第三方系统直接改状态。

同一订单短时间多次变更时，重点查 webhook 重放和人工批量操作。错误业务状态会让工具生成数学上正确、业务上错误的补偿。

补偿是追加记录，不是修改历史

Reservation 设计为 append-only。正确修复通常是新增相反数量，使订单链合计回到预期，而不是删除旧行。生产前应在同版本副本演练，记录目标 SKU 修复前后 salable quantity，并分批执行，防止消费者瞬间积压。

修完必须复盘来源

常见根因是旧订单缺初始 reservation、外部 OMS 直接写状态、取消事件未触发、消费者停机或插件重复处理。结束条件是历史差异按范围归零，新订单链闭合，消费者无 backlog，前台数量符合业务预期。

先确定网站使用哪个 Stock

MSI 里 Website 关联 Stock，Stock 聚合 Source。一个 Source 有数量，不代表它属于当前销售渠道。先确认网站、SKU、Stock ID 和 Source 分配。

php bin/magento inventory:reservation:list-inconsistencies
php bin/magento indexer:status inventory

不同版本的库存 CLI 可能不同，命令不存在就使用服务契约或只读 SQL 辅助确认，不要在生产猜表更新。

Reservation 是差值，不是库存快照

下单写负 reservation，发货、取消或退款写补偿记录。它是追加日志，正常完成后同一订单链合计应回到零。未完成订单会合法降低 Salable Quantity；异常中断才会留下不一致。

按订单号检查每个负数的业务原因，不能因为看到负数就删除，也不能直接改索引表，下一次重建仍会覆盖。

数量正确后仍缺货，再看阈值与索引

Out-of-Stock Threshold、Backorders、Manage Stock 和商品级覆盖都会改变结果。若库存消费者长期未运行，状态也会延迟更新。

验收覆盖下单、取消、发货：下单后 salable 降低，取消后恢复，发货后 source quantity 扣减且 reservation 抵消。只把页面暂时改成有货，不代表库存链路恢复。

先确认请求经过了谁

curl -sS -D - -o /dev/null https://shop.example.com/product.html
curl -sS -D - -o /dev/null https://shop.example.com/product.html

关注 Age、Varnish 标记、CDN 标记及 Magento cache debug。如果前面还有 CDN，Varnish 已 purge 但 CDN 仍命中，看起来就像 Varnish 没刷新。

确认 purge 到达正确主机

后台配置的缓存主机和线上真实地址经常不一致，尤其在容器和迁移后。刷新时同时看 Magento 日志与 Varnish access log，确认 PURGE/BAN 到达且 ACL 允许来源。

自定义实体若没返回正确 identity tag，系统不知道页面依赖它；使用过大的 tag 又会让一次小改动清掉大量页面。

别忽略 grace 和后端健康

后端 unhealthy 时，Varnish 可能在 grace 内继续提供陈旧内容。这是保可用性设计。应查健康检查 URL、nginx/PHP 响应与 Varnish 日志，而不是反复 cache:flush。

修复后做一次可追踪测试：修改无风险文本，记录保存时间，观察失效请求、Age 归零、下一次 MISS、随后再次 HIT。把链路跑通，比关掉缓存更能说明问题。

先把掉线发生在哪一层分清

浏览器仍携带 session cookie，只能证明会话编号还在；Redis 中对应 key 消失，Magento 一样会创建新会话。复现时记录响应头、Cookie 名和发生时间，然后检查：

redis-cli INFO memory
redis-cli INFO stats
redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET maxmemory-policy
redis-cli --latency

evicted_keys 持续增长是强信号。缓存和 session 不宜混在同一个小实例里，否则缓存膨胀会把登录态一起挤掉。

TTL 与 Magento 配置要对得上

核对 env.php 的 session 配置、后台 Cookie Lifetime 和 Redis 实际 TTL。爬虫、顾客与管理员会话的生命周期可能不同，min_lifetime、max_lifetime 也会参与限制。

若日志有连接超时，查 Redis 连接数、网络抖动和超时，而不是继续提高 Cookie Lifetime。超时调得过长只会让 PHP worker 堵得更久。

锁等待也可能被误判为掉线

同一用户并发 AJAX 时，session locking 会让请求串行。锁等待超阈值后，前端可能把失败当成重新登录。把 PHP 慢请求、Redis 延迟和浏览器 Network 对齐，确认是 key 丢失还是锁等待。

验收要看 evicted_keys 不再增长、内存有余量、TTL 合理，并做同账号多并发测试。四项都稳定，随机掉线才算修好。

先证明它真的死了

php bin/magento indexer:status
ps aux | grep '[b]in/magento indexer'
SHOW FULL PROCESSLIST;

仍能看到 PHP 进程，而且 SQL 扫描行数、临时表或 CPU 在变化，它可能只是慢。先看磁盘空间、临时目录及 metadata lock。进程已经不存在，状态却几小时不变，才属于残留状态。

php bin/magento indexer:reset catalogsearch_fulltext
php bin/magento indexer:reindex catalogsearch_fulltext

只处理对应索引器，不要为了省事全部 reset。

Update by Schedule 还要查 mview

计划模式下变化先写入 changelog。索引状态正常但前台数据旧，常见原因是订阅的 version_id 没推进：

SELECT view_id, mode, status, version_id, updated
FROM mview_state
ORDER BY updated ASC;

比较 version_id 与对应 *_cl 表最大版本。不要随便 TRUNCATE changelog，那可能跳过尚未消费的商品变化。先备份状态，再决定全量重建或从正确版本继续。

恢复后还要回答为什么卡

若总在同一商品或 SQL 停住，查异常数据、缺失索引、锁等待和插件；若只在高峰发生，考虑计划模式并为 cron 留独立资源。安全恢复只是第一步，找到导致 Processing 没正常收尾的进程或 SQL 才算闭环。

先判断是 cron 根本没跑，还是来不及跑

先把最近半小时的状态按时间排出来：

SELECT job_code, status, scheduled_at, executed_at, finished_at, messages
FROM cron_schedule
WHERE scheduled_at > NOW() - INTERVAL 30 MINUTE
ORDER BY schedule_id DESC;

如果只有 pending 和 missed，完全没有新的 running、success，先查操作系统计划任务。Web 站点能打开，不代表 CLI 使用的是同一个 PHP：

crontab -l
which php
php -v
php bin/magento cron:run

手工执行时要使用和系统 cron 相同的用户、工作目录及 PHP 路径。常见现场是 crontab 仍指向已下线的 PHP，或者发布后目录改名，命令从一开始就没进入 Magento。

有 success 但 missed 仍增长，要找堵住队列的任务

Magento 会提前生成计划。任务超过 Schedule Lifetime 仍未执行才变成 missed。此时应比较 executed_at - scheduled_at，再找耗时异常的 job。第三方同步、报表导出和全量商品脚本尤其容易拖死默认 cron 组。

自定义任务应按主键游标或时间窗口拆批，不能每分钟从第一行重新扫全表。需要互斥时，锁必须在异常退出后可释放，否则后续任务会全部跳过。

恢复时别一股脑重跑所有 missed

订单邮件、库存同步可能有外部副作用。补跑前先确认幂等：重复执行会不会发两封邮件、扣两次库存或重复调用 ERP。索引任务可以定向重置；业务任务更适合按 job_code 和业务主键补偿。

连续观察两个调度周期，新任务能准时从 pending 到 running 再到 success，积压持续下降，才算恢复。清表只能处理症状，系统 cron、任务耗时和幂等才是根。

先把同一个配置路径在四个位置对齐

假设路径是 vendor_module/general/enabled，我会依次确认：

1. 后台保存的是 Default、Website 还是 Store View；
2. core_config_data 对应 scope/scope_id 的值；
3. app/etc/config.php 或 app/etc/env.php 是否声明了这个路径；
4. 运行环境是否存在把配置路径转换后的环境变量覆盖。

数据库查询只用于确认：

SELECT scope, scope_id, path, value
FROM core_config_data
WHERE path = 'vendor_module/general/enabled'
ORDER BY scope, scope_id;

不要只看 Default 行。后台在 Store View 保存的值，可能被 Website 继承关系影响；反过来，部署配置锁的是另一个作用域，也会造成“有的店变了，有的没变”。

为什么 app:config:import 会把它改回去

app:config:import 的职责就是把共享配置导入当前环境。某个路径已经被 dump 进 config.php，仓库里的值便是部署声明。你只在生产后台改数据库，却没有更新声明文件，下一次 import 恢复仓库值，反而是命令按设计工作。

env.php 更适合环境特有或敏感配置，环境变量又可以在运行时覆盖配置。要注意：如果最高优先级来自平台环境变量，改数据库、改 config.php 甚至清缓存都不会改变最终读值。

先用 CLI 读最终值，再讨论谁覆盖谁

对非敏感配置，可以在目标作用域读取 Magento 最终解析到的值，并与数据库和文件逐项对照。不要把支付密钥、令牌等敏感值打印进工单或 CI 日志。若同一命令在 Web 容器和 CLI 容器结果不同，还要检查两者挂载的 app/etc、环境变量和发布版本是否一致。

另一个常见误判是只清了应用缓存，却命中了旧容器。配置导入后应确认所有实例使用同一份 release 和环境修订；否则表面像值被改回，实际是请求在新旧节点之间切换。

真正要修的是团队流程

先给配置分三类：

• 所有环境共享：在受版本控制的 shared config 中变更，走代码评审和部署；
• 环境专属或敏感：通过 env.php 管理命令、平台变量或密钥系统维护，不进普通仓库；
• 允许运营实时调整：不要把该路径锁进部署文件，让数据库成为它的事实源，同时保留权限与审计。

最糟糕的是同一路径今天由后台改，明天由部署改，紧急时又由环境变量改，团队却没有记录谁优先。把每个配置归属写进部署文档，比再加一次 cache flush 有用。

不要为了让后台可编辑，直接删整段配置

从 config.php 或 env.php 移除路径，会改变它的管理方式。提交前先确认其他环境是否依赖这条声明，以及下一次 app:config:dump 会不会又把它带回来。比较安全的做法是只调整目标路径，保留版本记录，并在流水线里检查未预期的配置 diff。

一次安全的修复演练

我会先在预发布复制相同作用域：记录当前有效值，运行 import，观察计划变更；再按确定的事实源修改，重新部署，确认后台是否应当只读以及前台实际读值。回滚也应该回滚配置声明版本，而不是临时 UPDATE 数据库。

上线验收时同时检查 CLI 读值、后台作用域和真实业务行为。配置页面显示某个数字不代表代码一定读到它——作用域、锁定文件和环境变量任意一层不同，最终值都可能变。把优先级画清楚后，这类“自己变回去”的问题就不神秘了。

十分钟内先确认是哪一种

从订单找到 quote_id，然后只读查询：

SELECT entity_id, increment_id, quote_id, state, status, created_at
FROM sales_order
WHERE increment_id = :order_number;
SELECT entity_id, is_active, reserved_order_id, items_count,       customer_id, updated_at
FROM quote
WHERE entity_id = :quote_id;

如果 Quote 已经 is_active = 0，重新调用后端 cart API 通常拿不到这辆活动购物车，问题更偏向前端 customer-data、PWA store 或 localStorage 没清。若 Quote 仍为 1，则继续查订单提交链路。

数据库已经正确：清的是前端“身份”，不是服务器缓存

Luma/Hyvä/PWA 的处理方式不同，但共同点是下单成功后要让当前 cart 标识失效，并重新加载购物车区块。只做 cache:clean 解决不了某个浏览器 localStorage 里的旧 cart_id。

我会在成功页打开 Network，确认页面没有继续查询旧 cart；再开一个新标签页，看购物车状态是否从持久化存储恢复。若只有支付网关回跳路径失败，而货到付款正常，通常是回跳页面绕过了标准成功处理。

Quote 真的仍 active：沿“创建订单”边界查

标准提交过程中，Quote 会与订单建立关系并结束活动状态。定制支付模块常见的错误是：

• 先创建订单，捕获后续异常时又把 Quote 设回 active，却没有判断订单已存在；
• 为了失败后恢复购物车，在支付 callback 和用户 return URL 两条路径都执行恢复；
• 插件包住 place order，提交成功后抛异常，补偿逻辑把状态回滚了一半；
• 异步下单时，前端把“已接收”当“失败”，继续沿旧 cart 操作。

把订单号、quote_id、payment transaction ID 和请求 ID 串成时间线，通常能看到是哪一个回调最后修改 Quote。不要只搜用户看到成功页的那次请求，支付平台的服务器 callback 可能更早或更晚到达。

为什么不能直接批量把这些 Quote 改成 0

对“已经有唯一有效订单”的单条 Quote，停用看起来合理，但批量脚本若没有处理并发、重复订单和失败支付，会把仍需恢复的购物车也关掉。先找出每个 active Quote 对应的订单数量和状态；存在两张订单时，重点已不是清购物车，而是支付、库存和取消哪张订单。

修复后我会测试四条路径：普通支付成功、用户关闭回跳页、支付成功但 return 超时、支付失败后重试。每条都要求一辆 Quote 最多对应一个预期订单，成功后旧 cart 不再可写，失败时则能明确创建新 cart 或受控恢复。购物车图标变成 0 只是表面，幂等性才是最后的验收标准。

我现在按两个问题拆：运行中的 Magento 有没有读到这份 schema？客户端拿到的是不是当前 schema？

第一步：确认文件确实属于已启用模块

php bin/magento module:status Vendor_Module
php bin/magento setup:db:status
grep -R "my_new_field" app/code/Vendor/Module/etc vendor/vendor-name/module-name/etc

路径必须是模块的 etc/schema.graphqls，文件名、大小写和部署包都要一致。新模块若没有完成注册、启用或 setup upgrade，schema 内容再正确也不会参与合并。

多节点环境再加一项：在每台实际接流量的节点计算该文件校验值。只发布到一台时，请求会一会儿认识字段、一会儿不认识，表现得很像缓存。

第二步：先只加一个最小字段

复杂 schema 有时是类型扩展位置写错，或者 resolver 配置让加载失败。先缩成一个不会依赖业务数据的字段，确认它能出现在 introspection 中，再逐步加参数、返回类型和 resolver。这样比同时调 schema、DI 和业务 SQL 快得多。

同时查看 var/log/exception.log、system.log 和 PHP 日志。schema 合并错误有时在构建或首次请求就已经记录，前端只显示一句泛化错误。

清哪类缓存才有意义

schema 定义属于服务配置的一部分，开发环境可以先定向清理 Magento 的 config cache，再请求 introspection 验证：

php bin/magento cache:clean config
php bin/magento cache:status

如果项目启用了生产编译，新增 resolver 类、构造参数或 DI 配置后，还要按项目标准重新编译和部署。cache:flush 不会替你生成缺失的 compiled code。

graphql_query_resolver_result 缓存保存的是可缓存 resolver 的结果，不是所有 schema 变更的万能开关。字段连 introspection 都不存在时，先处理模块加载与 config schema，不要把注意力放在业务结果缓存上。

最后排除“其实是客户端旧 schema”

IDE 和前端代码生成工具会缓存 introspection。直接用 curl 向实际 /graphql 端点发一个最小查询；如果服务端已认识字段，而 IDE 仍标红，刷新 schema 或重启代码生成工具即可。还要确认请求域名、Store header 和环境没指到另一套站点。

我的验收顺序是：introspection 能找到字段；最小查询能调用 resolver；带真实参数的查询返回正确数据；关闭开发日志后在所有节点重复请求。这样每一步只验证一个层次，不需要靠“再清一次全部缓存”碰运气。

PRECONDITION_FAILED - inequivalent arg 'x-...' for queue '...'

这不是 RabbitMQ 连不上，而是已经存在一个同名队列，Magento 当前代码想用另一组属性再次声明它。RabbitMQ 会做属性等价检查，durable、exclusive、auto-delete 或 arguments 对不上时，直接关闭 channel，避免客户端悄悄改变现有队列语义。

先把错误原文保留下来

错误一般会同时写出“received”和“current”值，例如代码想要 x-queue-type=quorum，现有队列却是 classic。不要只截取第一行，因为具体哪个参数不同，决定了能否原地调整。

随后查看当前队列，而不是立刻删除：

rabbitmqctl list_queues -p / name durable auto_delete arguments messages_ready messages_unacknowledged consumers

同时检查 Magento 模块中的 etc/queue_topology.xml、queue_consumer.xml，以及 RabbitMQ Policy。参数可能来自应用声明，也可能由 Policy 注入。只改一边，下一次部署仍会冲突。

我遇到最多的三个来源

• 升级模块后，开发者把已有 classic queue 改成 quorum，队列名字却没变；
• 两个 Magento 环境误用了同一个 vhost，测试环境用不同参数声明了生产队列；
• 旧模块已移除，但它创建的队列还在；新模块复用了同名队列。

有消息时，删除队列不是“修复”

如果 messages_ready 或 messages_unacknowledged 不为 0，删除会造成业务消息丢失或状态不一致。先确认消息对应什么业务：库存、异步操作、邮件与第三方同步的补偿方式完全不同。

生产上我更倾向于新建一个名字明确的新队列，让新代码发布到新队列；暂停旧生产者后把旧队列消费完，再下线旧绑定。若必须迁移消息，也要考虑消息是否仍适合新的队列类型、重试和死信设置，不能只把 payload 搬过去。

以 classic 改 quorum 为例，不能只改一个参数

队列类型变化通常意味着可用参数也跟着变。旧 classic queue 上的镜像参数、队列 TTL、优先级或独占设置，不一定能原样搬到 quorum queue。先根据当前 RabbitMQ 版本核对支持矩阵，再在测试 vhost 用与生产相同的 topology 声明一遍。

发布时还要考虑滚动部署：旧节点仍认为队列是 classic，新节点已经声明 quorum，两代代码同时在线就会互相打架。可以先发布兼容的生产者，让消息写到一个稳定 exchange，再切 binding 和 consumer；确认旧版本全部下线后，才移除旧队列。这样迁移边界在 RabbitMQ 拓扑，而不是寄希望于所有应用进程同一毫秒重启。

参数明明一样，为什么还报错

管理界面显示的名称相同，不代表来源相同。例如 x-dead-letter-exchange 可能由客户端 arguments 声明，也可能来自 policy；一个值是字符串，另一个被序列化成不同 AMQP 类型，也会不等价。把错误中的参数名、类型、received/current 原样对照 definitions，比肉眼看两份 XML 更可靠。

什么时候可以删除再重建

只有在确认队列没有待处理和未确认消息、没有旧版本节点仍在发布/消费，并且它可以从 Magento 配置安全重建时，我才会删除。操作前导出 definitions 或至少记录 exchange、binding、arguments，方便回滚和复盘。

修好后不要只看 consumer 进程“还活着”。发布一条可识别的测试消息，确认它只被处理一次，失败时进入预期的重试或死信路径；然后重启消费者，验证同名队列再次声明不会报错。能经得住重启，才说明参数来源已经统一。

php bin/magento maintenance:disable
php bin/magento maintenance:status

命令明确显示 maintenance mode is not active，浏览器却仍是一张维护页。这里最重要的不是再删一次 flag，而是先问：这张页面到底是谁返回的？

用响应特征确定层级

curl -I https://shop.example.com/
curl -sS -D /tmp/headers.txt -o /tmp/body.html https://shop.example.com/
head -40 /tmp/headers.txt

看状态码、Age、Via、CDN 命中标记、Server 以及响应里的自定义 request ID。再从允许的内网路径直连 origin 测一次。如果 origin 已正常而公网仍维护，问题在 CDN、WAF 或负载均衡，不在 Magento。

反过来，如果某些请求正常、某些仍维护，优先怀疑多节点。发布脚本可能只在一台共享代码目录外的节点执行了 disable；另一个节点的 var/.maintenance.flag 还在，负载均衡便会交替返回两种页面。

别把三个“维护开关”当成一个

1. Magento 自己的维护模式：由 CLI 管理，可用 maintenance:status 检查；
2. Web 服务器或部署脚本的静态维护页：Nginx/Apache 可能根据另一个文件或环境变量直接返回；
3. 边缘层维护：CDN、Fastly、负载均衡或托管平台可能有独立开关和缓存。

很多事故就是发布脚本同时打开了第 1 和第 2 个开关，收尾只关闭一个。

如果确实是 Magento 仍在返回 503

确认命令是在正确项目根目录、由正确发布版本执行，并检查 PHP/Web 进程看到的代码路径是否相同。蓝绿发布时，SSH 当前目录可能已经指向新 release，但 Web 流量仍在旧 release。

还要看维护模式是否配置了允许 IP。测试人员的 IP 被放行时，自己看到正常页面，并不能证明公众已经恢复。用外部探测点测试比在办公室浏览器刷新可靠。

缓存能不能让维护页一直存在

正常配置下 503 不应被长期缓存，但自定义 VCL、反向代理规则或错误页缓存可能做错。此时先检查响应头与缓存键，再定向 purge。不要一看到旧页面就把 Magento、Redis、CDN 全部清空；既破坏命中率，也无法知道真正是哪层。

我的恢复标准是：公网与 origin 都返回预期状态，匿名和登录请求正常，至少连续命中所有应用节点，并且负载均衡健康检查恢复。只在一个浏览器里看到首页打开，还不能宣布发布结束。

我会先做一个很朴素的对照：导出 100 条、1 万条和相同数量但更窄日期范围的数据，记录峰值内存。如果内存近似按行数线性增长，代码大概率把结果或 CSV 全攒在数组里；如果加某一列后突然暴涨，就去查这列的 renderer 或插件。

网格里“看不见”的 JOIN 也会付出代价

不少项目给订单网格加了商品 SKU、优惠明细、支付附加信息。页面只显示 20 行时问题不明显，导出会移除分页，把 JOIN 扩展后的所有行送进 PHP。先打印导出 collection 的 SQL，并检查：

• 一张订单是否因为 item、shipment 或 transaction JOIN 变成多行；
• renderer 是否对每一行再次加载完整订单，形成 N+1 查询；
• 扩展字段是否反序列化了很大的 payment additional_information；
• 导出插件是否先 getItems()，再构造一个完整二维数组。

临时拿数据：先缩小范围

如果运营当天就要文件，我会先按创建日期或 increment_id 分成几段，从后台分别导出。这是止血，不是最终方案。切分时要保存过滤条件和导出时间，避免几段之间漏单或重复。

长期方案：稳定游标 + 流式写文件

真正的大批量导出不适合绑在一个浏览器请求里。可以做 CLI 命令或队列任务，每批只取固定数量，以单调递增主键作为游标：

SELECT entity_id, increment_id, created_at, status, grand_total
FROM sales_order
WHERE entity_id > :last_id  AND created_at >= :from  AND created_at < :to
ORDER BY entity_id ASC
LIMIT 1000;

每批读取后立即写入已打开的 CSV 流，释放集合，再保存 last_id。不要用越来越大的 OFFSET；数据量大时它会越翻越慢。时间条件最好用半开区间，例如 [2025-07-01 00:00:00, 2025-07-02 00:00:00)，边界更不容易重复。

如果导出过程中订单还会变化，要先定义一致性：是“任务开始时的快照”，还是“读取到这一刻的最新状态”。普通运营报表通常可以记录任务开始时间，并限制最大 entity_id；财务用途则可能需要从报表库或事务一致的快照生成。

CSV 本身也有几个容易忽略的坑

• 用标准 CSV writer 处理逗号、引号和换行，不要手工字符串拼接；
• 防止以 =、+、-、@ 开头的用户输入被表格软件当公式执行；
• 明确金额导出的是 base currency 还是 order currency；
• 客户邮箱、地址等数据应按权限生成，并设置下载文件的保留期。

验收时我不只看“文件能下载”。还会核对数据库条件下的订单数、CSV 行数、首尾订单、金额合计，并监控峰值内存是否在批次之间回落。这样才能证明导出已经从“碰运气的大请求”变成可控任务。

先分清“缺字形”还是“编码坏了”

用 PDF 阅读器复制那串方框，粘贴到纯文本里：

• 粘贴后能看到正确中文，多半是字体不包含中文字形；
• 粘贴后也是乱码，要继续检查进入 PDF 前的字符串编码和自定义模块处理；
• 只有某些生僻字是方框，说明字体覆盖范围不完整，不是整个流程都坏了。

再做一个最小样本：客户名、地址、商品名分别放常用中文、数字和英文。这样能看出是所有绘制位置都用了错误字体，还是只有商品表格的 renderer 没换。

修复位置在 PDF 绘制代码，不在前台主题

我会做一个小模块扩展发票 PDF 的字体选择，让正文、粗体和必要的标题都使用服务器上可读取、允许嵌入并包含 CJK 字形的字体文件。不要直接改 vendor，升级后一定会丢；也不建议用一个 preference 粗暴复制整个核心 PDF 类，后续版本改分页或金额布局时很难跟。

更稳妥的做法是把“创建字体”集中成一个服务，再在实际调用 drawText 前切换字体。伪代码大致是：

$font = $fontFactory->fromPath(
    $moduleDir . '/view/base/web/fonts/YourCjkFont.ttf');
$page->setFont($font, 9);
$page->drawText($text, $x, $y, 'UTF-8');

具体 API 会随项目使用的 PDF 库和 Magento 版本不同，不能照抄一行就上线。重点是：传入的字体对象必须真的嵌入 PDF，并且每个绘制中文的 renderer 都走到它。

字体选好了，布局还可能坏

CJK 字体通常比内置西文字体大得多，字宽也不同。换字体后我会专门看三件事：

1. 长中文商品名是否越过数量和金额列；
2. 两行地址换页时有没有压住页脚；
3. 粗体标题是否因为没有对应字重，又退回缺字的字体。

如果项目只是为了十几个固定中文标签，盲目嵌入完整大字库会让每张发票膨胀很多。可以选择允许子集嵌入的字体和实现，但要确认所用 PDF 库是否真的做子集化。不要随便从本机复制商业字体到服务器，字体授权也属于上线检查项。

缓存清理不是核心，但部署路径要一致

字体文件随模块发布后，要确认生产节点都包含同一文件、PHP 进程有读取权限，编译后的类确实是新版本。只在一台节点放字体会造成“有时正常、有时方框”的诡异现象。

最后用发票、发货单、贷项通知单各导出一份，因为它们可能共享部分抽象类，却有不同 item renderer。再用至少两种 PDF 阅读器打开并实际复制文字。能显示只是第一关，能搜索、复制，打印时也不丢字，才算这次字体修复完成。

Magento 最终要求唯一的是某个 Store 下的 request_path，而不是后台表单里那一格 URL Key。分类路径、URL 后缀、旧商品的永久重定向，都会参与生成结果。

先按最终路径搜，不要只搜商品属性

假设目标路径是 blue-shirt.html，先查对应 Store：

SELECT url_rewrite_id, entity_type, entity_id, request_path,       target_path, redirect_type, store_id, is_autogenerated
FROM url_rewrite
WHERE store_id = :store_id  AND request_path IN ('blue-shirt', 'blue-shirt.html');

如果商品开启了“Use Categories Path for Product URLs”，还要搜索带分类前缀的路径。反过来也一样：你在后台看到的 key 没有分类，但生成 request_path 时可能已经加了分类层级。

看到冲突记录后，先判断它为什么存在

我一般把结果分成三类：

• 仍指向有效商品或分类：这是正常占用，应改新商品 URL，不能删除别人的入口；
• 301 历史重定向：说明这个地址过去用过。删除会让旧链接失去 SEO 价值，要先确认业务是否允许复用；
• 孤儿或重复生成记录：entity 已不存在，或者一次失败导入留下异常数据。这才是需要进一步修复的对象。

查孤儿时也不要只写一个大 DELETE。先把目标范围导出来，至少保留 url_rewrite_id、路径、Store 和目标实体。多商店尤其容易误删：同一路径在不同 store_id 下可以分别存在，问题只发生在保存商品的那个 Store。

为什么删完又回来

如果记录的 is_autogenerated = 1，它通常由目录 URL 重写逻辑重新生成。你只删结果，不改产生冲突的商品、分类路径或作用域，下一次保存、导入或重建时它还会回来。

另一个隐蔽点是 Store View 回退。默认作用域里是 blue-shirt，某个 Store View 曾单独保存过同样的值，后来界面上又切回“Use Default Value”。排查时应该明确列出每个作用域的实际属性值，而不是只看当前后台页面。

我的处理顺序

1. 确定目标 Store、URL 后缀以及是否带分类路径；
2. 在 url_rewrite 查最终 request_path 的占用者；
3. 打开占用者，确认它是有效入口、历史 301 还是孤儿；
4. 能从后台调整的，优先修改源实体并让 Magento 重建；
5. 只有确认是异常数据时，才在备份后做定向清理，再保存单个实体验证。

我不会直接清空整个 url_rewrite 表。那样确实可能让当前商品拿回漂亮 URL，却同时丢掉全站自定义重写和历史重定向。这个问题的关键不是“怎样去掉 -1”，而是先回答：没有 -1 的那个地址，现在究竟属于谁。

麻烦在于，前端经常把这句正常保护机制展示成“结账失败”。用户看到红色提示又点一次，实际上第一笔订单可能已经创建了。

先回答最重要的问题：订单到底有没有生成

不要立刻创建新购物车重试支付。先用服务端日志中的 masked cart ID 找到 Quote，再查它和订单的关系：

SELECT entity_id, is_active, reserved_order_id, customer_id,       created_at, updated_at
FROM quote
WHERE entity_id = :quote_id;
SELECT entity_id, increment_id, status, state, quote_id,       created_at, grand_total
FROM sales_order
WHERE quote_id = :quote_id;

如果已经有订单，前端应该进入成功页或订单查询流程，而不是继续对原 cart 执行 mutation。尤其是支付接口超时、浏览器提前断开时，客户端没收到成功响应，不代表服务端事务没有完成。

旧 cart_id 通常藏在三个地方

第一处是 localStorage 或 IndexedDB。下单成功后前端只清了内存状态，没有删除持久化的 cart token；用户刷新页面，又把它装回来了。

第二处是登录前后的购物车合并。游客 cart 被合并进客户 cart 后，组件树里仍有请求持有游客 ID。你会看到同一秒内两个 cart_id 交替出现。

第三处是重复提交。按钮虽然变灰，但双击、移动端重触或网络重试已经发出了两个 placeOrder。第一个请求将 Quote 变为 inactive，第二个请求随后得到这句报错。

用时间线判断是哪一种

GraphQL 官方错误里也把 CART_NOT_ACTIVE 与 CART_NOT_FOUND 分开了。前者意味着对象存在但生命周期已结束；后者才更像 ID 错误或无权限。因此，遇到 inactive 就无条件新建购物车，会丢掉“订单其实已经生成”的关键信号。

不要把 is_active 手工改回 1

这条 UPDATE 看起来很诱人，但如果订单已经存在，相当于把已结算的商品重新开放下单。库存、优惠券、礼品卡和支付授权都可能重复。正确处理是：

• 有订单：恢复订单结果展示，不复活 Quote；
• 没有订单且提交明确失败：由受控的业务流程创建新 cart 或恢复结账内容；
• 状态来源不明：先记录修改 Quote 的调用栈或插件，再决定补偿。

最后我会用人为制造超时来验收：让 placeOrder 在服务端完成、客户端超时，然后刷新页面。页面必须能识别已有订单，而不是再次提交。这个场景通过了，才说明问题真的解决。

所以我现在遇到这句话，第一件事不是让用户重填，而是确认最后一次 place order 使用的 cart_id，是否就是保存地址时的 cart_id。PWA、移动端和做过 checkout 定制的站点，登录、合并购物车或刷新 token 后很容易换了 cart，页面却还留着旧地址。

先看请求顺序，不要先猜字段

在浏览器 Network 里按 cart_id 过滤，把一次完整结账串起来。实体商品通常应该看到这样的顺序：

1. setShippingAddressesOnCart 成功，并返回 shipping_addresses；
2. 重新读取可用配送方式；
3. setShippingMethodsOnCart 成功；
4. 设置账单地址、支付方式；
5. placeOrder 使用同一个 cart_id。

如果地址请求在前端显示“成功”，但响应的 shipping_addresses 是空数组，就不要继续看支付模块。先保存该请求的 variables 和响应，再到后端日志里用时间与请求 ID 对齐。常见情况是前端吞掉了 GraphQL 的 errors，只判断 HTTP 200。

数据库只用来确认事实，不要直接补地址

拿到 Quote 的内部 ID 后，可以只读检查地址是否真正落库：

SELECT entity_id, is_active, customer_id, store_id, items_count
FROM quote
WHERE entity_id = :quote_id;
SELECT address_id, address_type, country_id, region_id, region,       postcode, city, shipping_method, collect_shipping_rates
FROM quote_address
WHERE quote_id = :quote_id;

实体商品应该至少有一条 address_type = 'shipping' 的记录。记录存在也不等于可用，还要看国家、region、邮编和配送方式。某些国家要求 region，前端传了文字 region 却没传正确的 region_id，地址能显示，后续校验仍可能失败。

不要为了赶紧恢复下单，直接往 quote_address 插数据。地址保存不仅是几列字段，还会触发运费收集、税费和扩展属性处理；手工补行往往把“缺地址”变成更难追的金额错误。

我会特别检查这四个分支

• 登录后 cart 发生合并：游客 cart_id 已失效，页面组件仍把地址写给旧 cart；
• 自定义地址组件只改了 UI 状态：Knockout/React store 更新了，但没有真正调用保存地址的 mutation；
• 配送方式重算清掉了地址或 method：切换国家、优惠码或门店自提后，异步响应乱序覆盖了新状态；
• 购物车全是虚拟商品：本来就不需要 shipping address，此时若自定义 place-order 校验仍强制要求它，判断位置写错了。

修复后怎样证明不是“碰巧好了”

我会开慢速网络复测一次，再分别测试游客、登录客户、登录时合并购物车，以及返回上一步修改国家。每次都记录 cart_id，并确认保存地址的响应先回来，配送方式才允许选择。订单创建后，再核对订单 shipping address 与用户最后一次提交一致。

如果加一条“为空就再调一次保存地址”的重试便不报错，这通常只是掩盖竞态。真正的修复是让结账状态只认当前 cart，并让地址、运费、支付按可观察的顺序推进。

把订阅当成状态机，而不是一个数字

站点是否开启 double opt-in 会改变正常路径。开启确认时，提交表单后没有立即变成 Subscribed 并不是故障。

从一条测试邮箱追完整链路

使用专门测试邮箱，记录提交时的 Store View、是否登录、subscriber ID 和时间。数据库只做查询：

SELECT subscriber_id, subscriber_email, subscriber_status,
       store_id, customer_id, change_status_at
FROM newsletter_subscriber
WHERE subscriber_email = :email;

然后确认邮件是否由正确 Store 模板发送，链接域名是否属于同一网站，点击后是否仍携带有效的订阅者标识和确认码。多网站环境里，Base URL、Cookie 域和路由重写错误都可能让链接回到首页，却没有真正执行确认。

邮件发出不代表确认链接可用

我见过模板把确认 URL 当普通文本过滤掉参数，也见过 CDN/WAF 缓存确认页或拦截查询字符串。查看服务器访问日志时只记录请求路径、状态码和请求 ID，不要把完整确认码写入日志或工单。

如果点击后状态没有变化，检查请求是否进入 Newsletter confirm controller、订阅者是否属于当前 Store，以及自定义插件有没有在保存后把状态改回。一次请求内先订阅再取消的情况，最终页面仍可能显示“成功”。

第三方邮件平台谁是事实源

集成 Mailchimp、Klaviyo 或自建 CRM 后，要明确 Magento 与外部平台谁负责同意状态。双向同步若没有事件版本或时间戳，很容易发生：

• Magento 刚确认订阅，旧的外部取消事件又把它覆盖；
• Webhook 重试多次，重复发送确认邮件；
• 一个 Store 取消订阅，错误地影响另一个品牌列表；
• 批量导入联系人时绕过了同意来源和确认记录。

同步消息至少要有幂等键、事件时间、列表/Store 映射和来源。遇到冲突时，通常应优先尊重更严格的取消状态，而不是为了列表数量把用户重新订阅。

为什么不建议直接 UPDATE subscriber_status

直接改状态会跳过确认、事件、邮件和第三方同步，也无法证明用户何时、通过什么入口同意。技术上数字变成了 Subscribed，合规和业务链路却仍是断的。修复应让正常服务完成状态迁移；历史数据需要补偿时，也要留下来源、批次和回滚记录。

最后用四条路径验收

分别测试访客首次订阅、登录客户订阅、取消后重新订阅、外部平台回调。每条路径都核对页面提示、Magento 状态、邮件、第三方列表和重复回调结果。再用两个 Store View 各跑一次，确认语言、域名和列表不会串站。只有这些状态转换都能解释，才算真正解决了“状态不更新”。

先确定你们的账号模型

php bin/magento config:show customer/account_share/scope

SELECT website_id, email, COUNT(*) AS cnt
FROM customer_entity
GROUP BY website_id, email
HAVING COUNT(*) > 1;

共享范围为 Global 时，一个邮箱在整个 Magento 实例只能对应一个客户；范围为 Per Website 时，相同邮箱可以分别存在于不同 Website。这里的边界是 Website，不是 Store View。

不要为了让导入通过就临时切换范围。已有客户、登录行为、地址、订单归属和第三方 SSO 都可能依赖当前模型。范围变更应当作为独立迁移项目评估。

“两个网站”可能只是两列写法不一致

客户导入文件需要把记录映射到真实 Website。不同 Magento 版本或导入模式使用的列名可能不同，后台示例文件是最可靠的起点。常见错误包括：

• 填写了 Store View code，却以为是 Website code；
• 一个 code 带了不可见空格或大小写不一致；
• 目标环境的 Website code 与测试环境不同；
• 更新模式下没有提供客户现有 website，系统尝试在默认网站创建；
• CSV 中同一邮箱在同一 Website 本来就重复，只是行距很远。

导入前做一次规范化预检

我会把邮箱转为统一大小写、去掉首尾空格，再按“规范化邮箱 + 目标 website code”统计重复。与此同时，从目标环境导出现有客户的 entity_id、email 和 website_id 做冲突比对。这样能把三种情况分开：

1. CSV 自己重复；
2. CSV 与现有客户冲突；
3. 网站映射失败后全部落到了默认 Website。

预检文件里不要散布真实客户邮箱。可以在受控环境处理，并在报告中使用哈希或遮罩。

看到重复记录时，别直接合并 customer_entity

两个客户可能各自拥有订单、地址、订阅、积分和外部系统 ID。即使邮箱相同，也不能仅凭这一字段判断是同一个人。先让业务确认账号共享策略和客户身份，再决定保留、迁移还是合并。

数据库唯一约束报错只说明当前键不允许插入，并不告诉你哪种业务处理正确。删除唯一索引会让脏数据进入系统，之后登录查询可能返回不确定的客户。

一个安全的重跑方法

先用 5 条小样本覆盖：新邮箱、目标网站已有邮箱、另一个网站同邮箱、未知 website code、带空格邮箱。选择与正式任务相同的 Add/Update 行为，核对导入报告后再扩大批次。正式重跑必须保证可幂等：已经成功的客户应被识别为更新或跳过，不能再创建一份。

最终不仅要看“导入成功多少条”，还要在两个 Website 分别测试登录、忘记密码、客户地址和历史订单可见性。账号范围问题最容易在导入时被绕过去，然后在客户登录时爆出来。

这种问题不能靠“每台机器都跑一遍 static-content:deploy”解决。恰恰相反，各节点独立生成产物和版本号，往往就是不一致的来源。

用响应把请求落点标出来

先让负载均衡或 Web Server 临时返回不含敏感信息的节点标识，例如 X-App-Node 和发布版本 X-Release。连续请求页面，记录：

• HTML 来自哪个节点；
• HTML 中的 static version；
• 失败静态文件回源到哪个节点；
• CDN 是 HIT、MISS 还是回源错误。

如果 HTML 节点和静态文件节点属于不同 release，问题已经很清楚：发布过程没有做到版本一致性。

比较的不只是 deployed_version.txt

cat pub/static/deployed_version.txt
sha256sum pub/static/frontend/Vendor/theme/zh_Hans/js/*.js | sort
sha256sum app/etc/config.php composer.lock
readlink -f pub/static
readlink -f current

每台节点上的 deployed_version.txt、主题关键文件哈希、代码 release 和 pub/static 实际指向都应一致。若使用共享存储，还要确认所有节点看到的是同一挂载点，而不是路径同名的本地目录。

三种发布方式，只有一种适合你的架构

构建一次，分发同一产物

在 CI 构建 Magento 代码和静态内容，生成一个不可变 artifact，再分发到所有节点。版本文件与静态资源天然一致，这是最容易审计的方式。

共享 pub/static

所有节点读取同一份静态目录，但写入必须由单一构建流程完成。滚动发布时要避免旧代码读取到只适用于新代码的静态产物。

各节点本地静态目录

可以使用，但节点必须从同一个构建产物解压，不能各自运行生成命令。还要确保流量只在解压完成后切入。

原子切换比清缓存重要

可靠做法是把新版本部署到独立 release 目录，完成代码、依赖和静态资源校验后，再一次性切换 current 软链接或负载均衡目标。不要在正在服务的 pub/static 上边删边生成。

CDN 清理也应在源站全部可用之后执行。过早 purge 会让全球节点同时回源，恰好击中尚未完成部署的应用节点；过晚则继续提供旧 HTML 或旧静态内容。具体顺序取决于 CDN 缓存的是 HTML 还是只有静态文件。

验证时故意绕过“幸运命中”

对每个应用节点分别请求同一个 HTML 和两个关键 JS/CSS，再通过真实域名请求一遍 CDN。连续至少覆盖一个负载均衡轮次，并检查 404、MIME type、缓存头和文件哈希。只在浏览器里刷新一次，很可能只是幸运地落到了已经完成发布的节点。

MISCONF Redis is configured to save RDB snapshots,
but it is currently not able to persist on disk

网上最常见的“修复”是一条 CONFIG SET stop-writes-on-bgsave-error no。它确实可能让网站马上恢复写入，但这相当于把烟雾报警器拆掉，并没有处理 RDB 为什么失败。

先判断受影响的是缓存，还是会话

Magento 经常把 default cache、page cache 和 session 放在不同 Redis DB，甚至不同实例。缓存暂时不可写会造成性能下降和页面错误；Session 不可写则可能导致登录、购物车和后台会话丢失。先从 app/etc/env.php 确认实际连接，不要看到 Redis 就执行 FLUSHALL。

记录主机、端口、DB、key 前缀和用途即可，不要在工单里暴露密码。

十分钟内应该收集的证据

redis-cli INFO persistence
redis-cli INFO memory
redis-cli CONFIG GET dir
redis-cli CONFIG GET dbfilename
df -h
df -i
free -m
journalctl -u redis --since "30 minutes ago"

INFO persistence 里重点看 rdb_last_bgsave_status、rdb_last_bgsave_time_sec 和 rdb_bgsave_in_progress。磁盘空间充足并不代表能写：inode 用尽、目录所有者错误、只读文件系统、容器挂载变化和安全策略都可能让 Redis 无法创建临时 RDB 文件。

磁盘没满时，为什么 BGSAVE 仍会失败

Redis 通过 fork 创建后台保存进程。数据集很大、内存紧张或 overcommit 策略不合适时，fork 本身可能失败。日志通常会出现 Cannot allocate memory。这时清几百 MB 日志不一定有用，需要评估实例内存、峰值写入、容器限制和持久化策略。

另一个常见现场是运维迁移了 dir，新目录存在但 Redis 用户无权写入。用服务实际运行用户验证目录权限，不能用 root 手工创建一个文件就宣布正常。

恢复顺序

1. 控制应用写入压力，确认是否需要临时切维护模式；
2. 修复磁盘、inode、权限、只读挂载或内存问题；
3. 手工触发一次 BGSAVE 或等待计划保存，并确认状态成功；
4. 验证 Magento Cache、Session、购物车和后台登录；
5. 观察下一轮自动持久化，而不是看到第一条 PONG 就结束。

什么时候可以临时关闭 stop-writes

只有当 Redis 的业务角色、数据可重建性、主从/备份和数据丢失窗口都经过明确评估，并且团队接受风险时，才可能把它作为短时应急措施。对 Session、队列或其他不可轻易重建的数据，贸然继续写尤其危险。即使临时关闭，也必须有恢复原配置的时间点和负责人。

本次故障关闭前，我会检查一次新的 RDB 文件时间与大小、Redis 日志无新错误、Magento 错误率恢复、Session 不再丢失，并确认磁盘告警阈值已经调整。MISCONF 不是 Magento 缓存故障的同义词，它首先是持久化失败。

先确认系统正在判断哪一种币种

一张 Quote 至少涉及基础币种和展示/交易币种，支付模块还可能单独定义清算币种。记录问题 Quote 的以下字段：

SELECT entity_id, store_id, base_currency_code,
       quote_currency_code, global_currency_code,
       base_grand_total, grand_total
FROM quote
WHERE entity_id = :quote_id;

不要只看页面右上角显示的货币。某些网关按 quote_currency_code 判断，另一些旧模块误用了 base currency；也有模块允许前台显示多币种，但下单前强制转换成指定结算币种。

支付方式可用性是一串条件，不只有币种

当币种改变时，订单金额也会改变，进而触发最低/最高金额限制。Store View 变化还可能连带改变账单国家、客户组或配置作用域。为了不把相关条件误判成币种问题，我会做一个小矩阵：

只有币种变化会稳定改变结果，才继续追 supported currencies。

配置页面显示“全部币种”也不一定是真的

第三方网关常把支持列表写在代码、远端 Merchant 配置或 API 响应里，而不是 Magento 后台。还要检查 Default、Website 和 Store View 是否有覆盖值：

php bin/magento config:show payment/your_method/active --scope=stores --scope-code=de_de
php bin/magento config:show payment/your_method/min_order_total --scope=stores --scope-code=de_de
php bin/magento config:show payment/your_method/max_order_total --scope=stores --scope-code=de_de
grep -RniE "canUseForCurrency|isAvailable|supported.*currenc" app/code vendor/YourVendor

如果模块实现了 canUseForCurrency()，直接看它比较的是哪一个币种，以及配置空值代表“全部”还是“一个都不支持”。这类细节比清缓存更有价值。

用接口响应区分后端过滤与前端显示

检查获取支付方式的 REST/GraphQL 请求。响应里本来就没有该方法，问题在后端可用性判断；响应有方法但 UI 不显示，才去看 Knockout 组件、错误的 region、前端条件和 customer-data 缓存。这个分界可以省掉大量无效的浏览器调试。

修复后至少用两种浏览器会话、访客和登录客户各测一次，并完成到网关创建支付单的步骤。支付方式“重新出现”不等于修复完成；如果网关最终拒绝该币种，只是把错误从结账页推迟到了付款页。

先记住这个关系：下单主要影响 Reservation，它改变可售数量；发货主要影响 Source Item，它从实际来源扣减。订单取消、退款或补偿又会追加相反方向的 Reservation。报错发生在发货阶段，并不代表下单时那笔 Reservation 没有成功。

用一张订单还原库存轨迹

因此要同时查订单 SKU 的 Reservation 链和 Shipment 选择的 Source。只看后台商品总库存，会把两个层次混在一起。

Source 为什么会扣不下去

我会按下面几类证据判断，而不是反复点“发货”：

• 来源不匹配：订单属于某个 Stock，但 Shipment 选择了不在该 Stock 销售渠道中的 Source；
• 数量已经变化：下单后仓库同步把 Source quantity 降低，发货时不再允许扣减；
• 重复处理：ERP 已创建 Shipment 或发送过扣减消息，重试又走了一遍；
• SKU 映射错误：外部系统传的是旧 SKU、父 SKU，或大小写/空格不同；
• 自定义插件破坏扩展属性：Shipment source code 没被正确带到扣减请求。

先做只读检查

SELECT reservation_id, stock_id, sku, quantity, metadata
FROM inventory_reservation
WHERE sku = :sku
ORDER BY reservation_id;

SELECT source_code, sku, quantity, status
FROM inventory_source_item
WHERE sku = :sku;

php bin/magento inventory:reservation:list-inconsistencies

metadata 能帮助确认 Reservation 来自哪张订单和哪类事件。不要把查到的负数当作错误；下单 Reservation 本来就是负的。真正要看的是同一订单的事件是否完整、总和是否符合它当前的业务状态。

三种修法，不能混用

仓库实际有货，只是 Source 选错

回到 Source Selection，选择实际履约的来源，再创建 Shipment。若由 ERP 指定来源，修复映射和幂等键，避免下一单继续选错。

库存同步晚到，实际已经无货

不要伪造 quantity。应拆单、换来源、等待补货或取消未能履约的数量，并让取消流程产生正确的补偿 Reservation。

历史 Reservation 不一致

先使用 Magento 提供的不一致检查和补偿命令在测试环境验证输出，明确会影响哪些订单，再按受控变更执行。直接删除 inventory_reservation 行会破坏审计链，后续很难判断某个补偿到底对应哪次业务事件。

最终验收不能只看 Shipment 创建成功。我会同时核对 Source quantity、目标 Stock 的 salable quantity、Reservation 总和、订单已发数量和 ERP 状态，并再做一次相同回调重放，确认幂等逻辑不会二次扣减。

先看失败的是一件，还是整个收藏夹

单个商品失败，优先比较这条 wishlist item 保存的购买参数；所有商品都失败，才去查 Quote、Session、表单校验或自定义插件。可以从后台复现同一客户，也可以在脱敏副本中读取 wishlist item 的 buy_request，但不要随意修改生产数据。

旧购买参数与现在的商品定义对不上

可配置商品依赖 super_attribute；Bundle、Grouped 和带必选 Custom Option 的商品还有各自参数。最常见的真实变化是：

• 管理员删除了原来的颜色或尺寸选项；
• 子商品仍存在，但已禁用、不可见或不属于当前 Website；
• 某个原本非必填的 Custom Option 被改成必填；
• 商品类型或选项 ID 在导入后重建，旧 ID 失去意义。

这时不应该偷偷替客户选择另一个尺寸。更合理的体验是把用户带回商品页，保留仍有效的选择，并明确提示需要重新选择已经失效的选项。

商品“有货”不等于当前请求可加入购物车

在 MSI 环境中，要以当前 Website 对应 Stock 的 salable quantity 为准。检查父商品状态没有意义，还要确认具体子 SKU 在目标 Stock 是否可售。与此同时，最小购买数量、增量数量、客户组限制和缺货预售配置也会影响 Quote 校验。

php bin/magento inventory:reservation:list-inconsistencies
php bin/magento indexer:status inventory

SELECT product_id, website_id
FROM catalog_product_website
WHERE product_id IN (:parent_id, :child_id);

上面的 SQL 只用于确认网站归属。库存问题应通过 Inventory API 或 CLI 判断，不要自己把 source_item 的 quantity 当成可售数量。

一个实用的判断顺序

1. 用目标 Store View 打开商品页，看它是否真的允许购买；
2. 确认失败的是父商品选择还是具体子商品；
3. 对比 wishlist 的 buy request 与商品当前必选参数；
4. 再检查 Website、客户组、最小数量和 MSI 可售性；
5. 最后才审查 addProduct 插件和 Quote 校验扩展。

如果异常信息被前端统一改成“无法加入购物车”，临时记录异常类和商品 ID，不要只记录翻译后的消息。LocalizedException、无效选项和库存异常的处理方向完全不同。

修复后的体验比“按钮不报错”更重要

测试一条当天新收藏的商品、一条选项已删除的旧收藏、一条子商品缺货的收藏，以及跨 Website 登录的收藏。有效商品应直接进入购物车；失效选项应要求重选；不可售商品要给出准确原因。不要为了让批量“全部加入购物车”返回成功而吞掉失败项，否则客户会以为所有商品都已加入，结账时才发现数量不对。

先做一个不会误导你的测试

选一个只在新模板中出现的短语，例如“售后编号”，不要用颜色或页脚年份这种可能被邮件客户端缓存的元素。然后完成三次发送：

1. 直接从后台发送模板预览；
2. 创建一张新订单并立即处理队列；
3. 处理一张修改模板之前就已进入队列的旧订单。

如果预览都是新的，但新订单邮件仍旧，问题在 Store 配置或发送进程；如果只有旧队列任务使用旧内容，要检查队列是否保存了已经渲染好的正文。不要把三种结果混在一起。

Magento 内置销售邮件与自定义队列的行为可能不同

Magento 的销售邮件异步发送主要以订单/发票等实体的发送状态驱动，发送时再根据 Store 配置选择模板。很多第三方模块为了重试方便，会提前渲染主题和 HTML，把整封邮件作为队列消息保存。前者改模板后通常影响尚未发送的邮件，后者不会，因为旧 HTML 已经成为历史快照。

所以第一件事是查清实际发送类。搜索自定义模块是否把 TransportInterface、模板正文或序列化后的消息写入表或消息队列：

grep -RniE "setTemplateIdentifier|TransportBuilder|message_queue|email_body" app/code vendor/YourVendor
php bin/magento config:show sales_email/general/async_sending
php bin/magento config:show sales_email/order/template
php bin/magento config:show sales_email/order/guest_template

最容易看漏的是配置作用域

后台编辑的是一个模板，实际发送配置可能仍指向另一个模板 ID；登录客户与访客订单还可能使用不同配置。更常见的是：你在 Default Config 改了值，但目标 Website 或 Store View 早就保存了覆盖值。

检查时带上作用域参数，并从问题订单读取真实 store_id。不要以当前后台右上角选中的 Store 代替订单所属 Store。

php bin/magento config:show sales_email/order/template --scope=stores --scope-code=cn_zh
php bin/magento config:show sales_email/order/guest_template --scope=stores --scope-code=cn_zh

为什么重启消费者有时真的有效

如果发送由常驻 PHP 进程完成，发布新代码、修改依赖注入或更换模板解析逻辑后，旧进程可能一直使用启动时加载的类和配置对象。此时 Web 请求已经是新版本，消费者仍在旧版本。先确认进程由 Supervisor、systemd 还是容器编排管理，再做有序重启；不要在高峰期直接杀掉所有 worker，让处理中消息处于未知状态。

纯数据库模板文本通常不要求重启 PHP，但模板选择逻辑、插件和自定义变量提供器变更需要。这个区别能避免每次改文案都把队列服务重启一遍。

把一次发送追到具体模板

临时增加脱敏日志，记录订单号、Store ID、客户是否访客、最终模板标识、区域和队列消息 ID。不要记录收件人完整邮箱、邮件正文或重置链接。拿到“最终模板标识”后，问题就从模糊的旧缓存，缩小成了明确的配置选择或内容快照。

修复完成后，我会故意保留一条修改前任务，再创建一条修改后任务，分别观察系统是否符合设计。如果产品要求“所有未发送邮件立刻采用新模板”，而当前队列保存的是 HTML 快照，那就不是清缓存能解决的，需要调整队列的数据模型或提供受控的重建任务。

发票号不是从订单号截出来的

Magento 的订单、发票、发货和退款单各有自己的 sales sequence。创建发票时，系统会根据实体类型和 Store 选择对应 sequence profile，然后生成下一个编号。先查映射，不要先改已经生成的号码：

SELECT meta_id, entity_type, store_id, sequence_table
FROM sales_sequence_meta
WHERE entity_type = 'invoice'
ORDER BY store_id;

SELECT profile_id, meta_id, prefix, suffix, start_value, step
FROM sales_sequence_profile
WHERE is_active = 1
ORDER BY meta_id;

这里要回答两个问题：每个 store_id 是否指向预期的 sequence table；活动 profile 的前缀是否真的属于该店铺。配置本身若已经串了，任何代码都会稳定地产生错误号码；配置正确而问题偶发，才应该继续追运行时上下文。

问题通常发生在“订单店铺”和“当前店铺”分开的时候

前台下单时上下文比较单纯，订单属于哪个 Store，创建后续单据时通常仍沿用它。后台批量操作、Cron 或第三方 ERP 回调就不同：代码可能拿到管理员当前 Store、默认 Store，甚至上一个循环遗留的模拟环境。

重点审查自定义开票代码里有没有这些味道：

• 用 StoreManagerInterface::getStore() 代替 $order->getStoreId()；
• 循环中调用 store emulation，却没有在 finally 中结束；
• 把 Invoice Factory 或 Sequence Manager 做成带状态的长生命周期对象；
• ERP 只传订单号，代码随后按当前网站重新加载订单相关对象。

用一条审计日志抓住偶发串号

不要把整个订单对象写进日志。创建发票之前记录订单实体 ID、订单 increment ID、订单 store_id、当前 Store ID、将要使用的 sequence meta/profile，以及本次任务的批次 ID。出现下一张错号时，就能判断上下文是在什么时候改变的。

$orderStoreId = (int) $order->getStoreId();
$currentStoreId = (int) $storeManager->getStore()->getId();

$logger->info('invoice_sequence_context', [
    'order_id' => (int) $order->getEntityId(),
    'order_increment_id' => $order->getIncrementId(),
    'order_store_id' => $orderStoreId,
    'current_store_id' => $currentStoreId,
    'batch_id' => $batchId,
]);

如果两个 Store ID 不同，并不自动代表有错；后台本来就可能处于 Admin Store。关键是后续 sequence 选择是否明确使用订单所属 Store，而不是依赖隐式的全局当前值。

已经生成的错号不能直接 UPDATE

发票号可能已经进入邮件、支付平台、ERP、会计凭证和客户下载文件。直接改 sales_invoice.increment_id 只会让各系统记录互相矛盾。先确认当地财税规则和外部系统是否允许作废重开；如果必须修复，要把 Magento、ERP、邮件/文档和审计记录作为一次受控变更处理。

同时检查错误序列的当前值，避免“修好了选择逻辑，却在下次生成时撞号”。不要手动把计数器调回一个看似顺眼的数字，除非已经查清所有已占用编号并准备好唯一性校验。

我会怎样复测这个问题

准备两个前缀不同的 Store，各下两张订单。先交替手工开票，再用批量任务按 A1、B1、A2、B2 的顺序处理，最后让消费者或 ERP 回调再跑一轮。每张发票都核对订单 store_id、序列表、前缀和连续性。只有跨 Store 交替执行仍稳定，才说明那个“偶尔串号”的上下文泄漏真正消失了。

这类问题先别碰分页器。count() 和 getSize() 本来就不是一回事：前者统计当前已经加载到内存里的对象数量，后者会基于集合的 Select 另外生成一条计数 SQL。只要扩展代码对原查询做过 JOIN、GROUP BY 或 HAVING，两条数字就可能分开。

先把“列表 SQL”和“计数 SQL”并排打印

不要只看最终数字。临时在可控环境记录下面两条 SQL，通常一眼就能看出分叉发生在哪里：

$collection = $this->productCollectionFactory->create();
// 应用与页面相同的过滤条件

echo (string) $collection->getSelect();
echo "
--- COUNT SQL ---
";
echo (string) $collection->getSelectCountSql();

如果商品表 JOIN 了库存来源、分类关系或自定义一对多表，一个商品可能展开成多行。页面加载时 Magento 最终仍会按实体生成对象，但计数 SQL 可能在算展开后的行数。典型特征是：

• 去掉某个 JOIN 后数字恢复；
• COUNT(*) 明显大于 COUNT(DISTINCT e.entity_id)；
• 同一个商品在原始 SQL 结果中出现多次。

最常见的三个“制造重复行”现场

一对多表只用于过滤，却直接 join

例如一个商品有多个来源库存记录。需求只是“至少一个来源满足条件”，却把完整来源表连接进集合。更合适的写法往往是 EXISTS 子查询，或者先在子查询里聚合为每个 SKU 一行，再 JOIN 回主集合。

分类关系和自定义属性同时连接

商品属于多个分类时，catalog_category_product 会天然扩行。若页面不需要分类 position，尽量使用 Magento 已有的分类过滤能力；确实要手写 JOIN 时，必须确认每个实体最终只保留一行。

GROUP BY 修好了列表，却破坏了 size

有人发现重复后直接加 GROUP BY e.entity_id。列表看起来正常了，但集合生成计数 SQL 时可能保留或改写这个 GROUP，结果变成多个 count 行。此时不是再套一层 COUNT(*) 就万事大吉，而是要决定“业务上到底在数商品、组合还是分组”。

别忽略 getSize() 自己的缓存

getSize() 首次执行后会把结果保存在集合实例中。下面这种调用顺序很容易留下旧数字：

$size = $collection->getSize();
$collection->addFieldToFilter('status', 1);
// 此时再次 getSize() 可能仍返回前一次结果

正确做法不是到处调用内部方法清缓存，而是把所有过滤、JOIN 和作用域条件都组装完成后再读取 size。需要尝试不同条件时，重新创建集合比复用一个已计算过 size 的实例更清楚。

怎样修，取决于你真正要数什么

如果业务对象就是商品，优先从查询结构上消除一对多扩行；仅在确定语义正确时使用 COUNT(DISTINCT e.entity_id)。如果列表展示的是“商品 × 来源”这样的组合，就不应该强行按商品去重，工具栏也要明确显示组合数量。

我会用三组数据验收：一个没有关联记录的商品、一个只有一条关联记录的商品、一个有三条关联记录的商品。然后同时核对第一页、最后一页、空结果页以及应用筛选后的总数。只测第一页很容易把分页边界的漏项藏起来。

因此，遇到 getSize() 不准时，最有效的起点不是缓存和索引，而是把两条 SQL 放在一起看。它们从哪一段开始不同，根因通常就在那里。

固定复现条件

在测试订单中记录浏览器 Console、提交请求、非敏感错误码、页面域名和 reCAPTCHA action。不要记录 Token、客户地址或密钥。比较默认 Checkout 与第三方一步结账。

php bin/magento module:status | grep -i captcha
php bin/magento config:show recaptcha_frontend/type_for/place_order
grep -R --line-number 'place_order|reCaptcha' app/code app/design 2>/dev/null
grep -RniE 'captcha|recaptcha|validation' var/log | tail -n 100
curl -sS -o /dev/null -w '%{http_code} %{time_total}
' https://www.google.com/recaptcha/api/siteverify

根据证据定位

请求没有 Token，查 JS 组件和 CSP；后端返回 hostname/action 不符，查域名与配置；偶发过期说明 Token 生成过早；仅代理后失败，检查源站出网、客户端 IP 与可信代理。第三方结账可能绕过标准 provider。

修复与回滚

使用目标 Magento 版本支持的 reCAPTCHA 类型，在真正提交前获取对应 action 的短期 Token，并按扩展提供的集成点挂载。修复 CSP 与出网，不在日志写 Secret；需要应急降级时应限时、受监控并保留其他风控。

验收

成功下单、失败后重试、页面停留超时、多个支付方式和移动端都测试；无 Token 与伪造 Token 必须被拒绝，正常客户不能产生重复订单。

生产环境操作前的检查

处理“Magento 2 reCAPTCHA 阻止客户提交订单”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

确认字段存在哪张表、何时保存、单订单接口与列表接口是否都缺失。检查生成的 OrderExtension 接口和 Repository get/getList 加载路径。

grep -R --line-number 'extension_attributes.*OrderInterface|attribute code=' app/code/Vendor/Module/etc 2>/dev/null
grep -R --line-number 'OrderRepositoryInterface' app/code/Vendor/Module 2>/dev/null
mysql -e "SHOW COLUMNS FROM sales_order LIKE 'custom_field'"
php bin/magento setup:di:compile
curl -sS -H 'Authorization: Bearer REDACTED' https://shop.example.com/rest/V1/orders/123

根据证据定位

只加数据库列不会进入 API；声明 Extension Attribute 但没有 hydrator/plugin 时值仍为空；get 生效而 getList 为空，通常是批量加载路径未覆盖。保存接口也需要把输入显式写入实体。

修复与回滚

在 extension_attributes.xml 声明合适类型，通过 Repository 插件或 extension join 加载，并使用资源模型保存。字段若含敏感数据，应先确认 ACL 与是否真的需要暴露。

验收

创建、读取、列表、更新订单均验证字段；无权限 Token 不得看到敏感值，批量接口避免 N+1 查询。

生产环境操作前的检查

处理“Magento 2 订单自定义属性没有出现在 REST API”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

保存 query、Store Header、Content-Currency、响应 currency 与金额，不记录客户 Token。分别绕过 CDN 请求源站，并测试公开价格与登录客户价格。

curl -sS -H 'Content-Type: application/json' -H 'Store: default' -H 'Content-Currency: EUR'  --data '{"query":"{storeConfig{base_currency_code default_display_currency_code} products(search:"SKU"){items{sku price_range{minimum_price{final_price{value currency}}}}}}"}'  https://shop.example.com/graphql
php bin/magento config:show currency/options/allow --scope=stores --scope-code=default
SELECT * FROM directory_currency_rate WHERE currency_from='USD' AND currency_to='EUR';

根据证据定位

币种未允许或汇率缺失时 Magento 会回退；Store Header 错误会读取另一站点配置；源站正确而 CDN 错误，检查缓存键是否包含 Store 与 Currency。自定义 Resolver 若直接返回 base price 也会忽略上下文。

修复与回滚

在正确 scope 配置允许币种与可信汇率更新，Resolver 使用 Magento 定价服务而非手工字段。公共 GraphQL 缓存必须按 Store、币种及身份正确隔离；客户专属响应不得共享。

验收

两个 Store、三种币种、访客和客户组交叉请求，currency 与金额一致；交替请求不能串币种，购物车与订单最终币种也要匹配。

生产环境操作前的检查

处理“Magento 2 GraphQL Currency Header 被忽略”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

记录 topic、脱敏消息 ID、redelivered 标志、首次与最后失败时间及异常指纹。区分暂时依赖故障、业务数据永久无效和代码缺陷。

php bin/magento queue:consumers:list
php bin/magento queue:consumers:start target.consumer --max-messages=5 -vvv
rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers
rabbitmqctl list_bindings source_name destination_name routing_key
grep -RniE 'consumer|redeliver|reject|requeue' var/log | tail -n 100

根据证据定位

网络超时适合有限退避重试；实体不存在或 schema 不兼容通常是永久失败；处理已完成但 ACK 前崩溃要求消费者幂等。所有错误都 requeue=true 会制造无限循环。

修复与回滚

为消息建立业务幂等键和明确重试预算，可恢复错误指数退避，永久错误进入死信或人工队列并保留脱敏证据。修复代码后按原消息语义安全重放，不要直接在 RabbitMQ 管理页批量 Purge。

验收

构造成功、暂时失败和永久失败消息；成功只产生一次副作用，暂时失败最终恢复，永久失败不再阻塞主队列且可追踪。

生产环境操作前的检查

处理“Magento 2 队列毒消息反复失败重试”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

检查每个节点的磁盘、分片分布、集群健康和索引设置，确认实际 Magento 别名指向哪个版本化索引。

df -h
curl -s 'http://127.0.0.1:9200/_cluster/health?pretty'
curl -s 'http://127.0.0.1:9200/_cat/allocation?v'
curl -s 'http://127.0.0.1:9200/_cluster/settings?include_defaults=true&pretty'
curl -s 'http://127.0.0.1:9200/_all/_settings?filter_path=**.blocks.read_only_allow_delete&pretty'
php bin/magento indexer:status catalogsearch_fulltext

根据证据定位

单节点磁盘满可能让相关分片全部只读；删除文档不一定立即释放段文件空间。大量旧 Magento 索引、快照失败或日志与数据共享卷都可能占用空间。

修复与回滚

先扩容或安全删除确认不再使用的旧索引/日志，使磁盘低于恢复水位，再精确解除受影响索引的 read_only_allow_delete，并重建搜索索引。不要全局关闭磁盘阈值。

验收

集群恢复 green/yellow 的预期状态，Magento 全量与增量索引成功；观察下一个高峰和合并周期，磁盘水位与旧索引保留策略稳定。

生产环境操作前的检查

处理“Magento 2 OpenSearch 因磁盘水位变成只读”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

记录管理员、角色、菜单资源 ID、控制器类与失败 URL。使用全权限管理员和受限管理员对照，确认是否仅自定义页面失败。

grep -R --line-number 'ADMIN_RESOURCE|<resource id=' app/code/Vendor/Module 2>/dev/null
grep -R --line-number '<add.*resource=' app/code/Vendor/Module/etc/adminhtml/menu.xml
php bin/magento cache:clean config
SELECT role_id,parent_id,role_type,role_name FROM authorization_role ORDER BY role_id;
SELECT role_id,resource_id,permission FROM authorization_rule ORDER BY role_id,resource_id;

根据证据定位

菜单 resource 与控制器 resource 不同会出现看得见却进不去；acl.xml 父节点错误会让勾选项不代表真实资源。只对旧 Session 失败时，重新登录可刷新权限，但这不能修复资源定义错误。

修复与回滚

统一 acl.xml、menu.xml 和 ADMIN_RESOURCE，选择合理父资源并升级模块配置。后台角色应按最小权限重新保存；不要绕过 _isAllowed 或把控制器改为全局允许。

验收

新建最小权限角色，允许页面可访问、未授权页面继续拒绝；保存、导出、批量操作和 AJAX 子路由也要逐一验证。

生产环境操作前的检查

处理“Magento 2 修改管理员角色后仍提示 Access Denied”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

保存登录前 guest quote、客户 active quote、登录后 quote_id 和每个 item 的 SKU、qty、parent_item_id、product_options。对个人数据脱敏，并区分真正重复与选项不同的合法两行。

SELECT entity_id,customer_id,is_active,items_count,items_qty,updated_at FROM quote WHERE entity_id IN (101,202,303);
SELECT item_id,quote_id,parent_item_id,sku,qty,product_type,product_options
FROM quote_item WHERE quote_id IN (101,202,303) ORDER BY quote_id,item_id;
grep -R --line-number 'merge(|mergeCart|assignCustomer' app/code 2>/dev/null

根据证据定位

选项完全相同但数量双倍，查 merge 被调用两次或并发登录；SKU 相同而 super_attribute/custom_options 不同，保留两行可能正确；guest quote 被错误重复激活也会产生多次合并。

修复与回滚

使用标准 Quote 合并流程，并以登录事务或请求标识保证幂等。自定义比较逻辑应包含影响购买结果的全部选项；不要在数据库中按 SKU 粗暴删除行，否则会丢失合法配置。

验收

测试空客户购物车、双方均有相同商品、不同选项、可配置与 Bundle，并发点击登录。最终数量与业务规则一致，优惠、库存和 totals 只计算一次。

生产环境操作前的检查

处理“Magento 2 登录后合并购物车出现重复商品”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

用测试客户记录注册 URL、store_id、website_id、邮件模板 ID 和最终链接主机，不记录真实确认 Token。比较同步与异步发送、默认模板与自定义模板。

SELECT entity_id,email,website_id,store_id,confirmation,created_at FROM customer_entity WHERE email='test@example.com';
SELECT store_id,code,website_id FROM store ORDER BY website_id,store_id;
php bin/magento config:show web/secure/base_url --scope=stores --scope-code=store_code
php bin/magento config:show customer/create_account/email_confirmation_template
grep -R --line-number 'getConfirmationUrl|confirmation_url' app/code app/design 2>/dev/null

根据证据定位

客户实体 Store 错误说明注册上下文已丢失；实体正确但链接主机错误，检查 Base URL 与发送模拟；只有异步错误，检查队列消费者是否恢复 Store；模板直接写域名则不会随 Store 变化。

修复与回滚

让注册服务保存正确 website/store，邮件发送在目标 Store 环境中生成 URL，并使用安全的模板 URL 变量。不要拼接 confirmation key 或在日志暴露 Token；修复后对旧邮件应提供重新发送流程。

验收

在两个 Website、两个语言 Store 分别注册，链接只到对应域名并能一次完成确认；重复点击、过期与重新发送都符合安全策略。

生产环境操作前的检查

处理“Magento 2 客户确认邮件链接跳到错误域名”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

保存完整 SQL、字段名、模块与构建版本，确认所有 Web、Cron、消费者是否同时报错。比较代码中的 db_schema.xml、数据库真实表结构和 setup:db:status。

php bin/magento setup:db:status
php bin/magento module:status Vendor_Module
grep -R --line-number 'missing_column' app/code/*/*/etc/db_schema.xml vendor/*/*/etc/db_schema.xml 2>/dev/null
mysql -e "SHOW CREATE TABLE target_tableG"
grep -RniE 'DDL|schema|setup' var/log | tail -n 100

根据证据定位

代码已切换而 setup:upgrade 未执行是最常见原因；模块被禁用、白名单不一致、DDL 权限不足或锁等待也会跳过结构变更。蓝绿发布若两版代码短时间共享数据库，还要检查变更是否向后兼容。

修复与回滚

恢复正确维护窗口和代码版本，备份相关表后运行受支持的 setup:upgrade 并检查输出。结构变化应由声明式 Schema 或补丁管理；不要只为消除异常临时添加一个类型不明的字段。

验收

setup:db:status 返回一致，SHOW CREATE TABLE 与声明匹配；新旧业务路径、Cron、消费者和回滚版本均经过兼容性验证。

生产环境操作前的检查

处理“Magento 2 发布后提示数据库字段不存在”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

固定复现条件

记录报错 key 前缀、Redis DB、节点、PHP 版本和发布批次，不输出缓存正文。比较正常与异常节点的 env.php 缓存配置摘要、phpredis/igbinary 扩展和构建版本。

php -v
php -m | grep -Ei 'redis|igbinary|msgpack'
grep -nA30 "'cache'" app/etc/env.php
redis-cli INFO keyspace
redis-cli --scan --pattern 'zc:*' | head
sha256sum composer.lock app/etc/config.php

根据证据定位

仅一台节点失败说明运行时或代码不一致；所有节点在同一 key 失败，可能是遗留或损坏值；测试与生产 key 前缀相同则属于环境串用。Session、Cache、FPC 常使用不同 DB，必须先确认连接。

修复与回滚

统一 PHP 扩展和序列化配置，为每个环境设置独立前缀或 Redis DB。确认是可再生 cache 后，只清目标缓存池并观察回填；不要执行无范围 FLUSHALL，也不要直接删除未知 Session key。

验收

连续命中所有节点，页面、后台、Cron 和消费者均无反序列化异常；缓存重新生成后命中率恢复，客户登录状态不受影响。

生产环境操作前的检查

处理“Magento 2 Redis 缓存报 Unable to unserialize value”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

保存当前 app/etc/config.php、composer.json、composer.lock 与 module:status，列出直接和间接依赖。确认目标是临时禁用、永久移除代码，还是连业务数据一起卸载。

php bin/magento module:status
php bin/magento module:disable Vendor_Module --dry-run
grep -R --line-number 'Vendor_Module' app/code vendor/*/*/etc/module.xml 2>/dev/null
composer why vendor/package
composer depends vendor/package
git diff -- app/etc/config.php composer.json composer.lock

根据证据分支定位

Magento 模块 sequence 依赖阻止禁用，需先处理上层模块；Composer 包被其他包 require，必须调整包依赖；代码已删除而 config.php 仍启用，应恢复同版本代码让 CLI 可启动，再按顺序操作。sequence 表示加载顺序，服务接口和 DI 依赖还需代码审计。

修复时保留回滚路径

先在维护分支和生产副本验证：停用依赖模块、禁用目标模块、运行 setup:upgrade/compile、完成测试，最后再由 Composer 移除代码。数据表和配置默认保留以便回滚；只有明确审核过 uninstall 行为后才执行数据删除。

上线验收

干净执行 composer install、setup:upgrade、di:compile 和静态部署，前后台、Cron、消费者均无缺类错误。重新启用回滚路径也要测试，确认历史订单或配置没有因卸载丢失。

生产环境操作前的检查

处理“Magento 2 禁用模块时提示依赖关系错误”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录搜索词、Store、当前商品索引别名、实际索引名和 analyzer 输出。使用 _analyze 比较修改前后 token，不只观察前台结果数量。

curl -s 'http://127.0.0.1:9200/_cat/aliases?v'
curl -s 'http://127.0.0.1:9200/_cat/indices?v'
curl -s -X POST 'http://127.0.0.1:9200/magento2_product_1_v1/_analyze'  -H 'Content-Type: application/json'  -d '{"analyzer":"standard","text":"移动电话"}'
curl -s 'http://127.0.0.1:9200/magento2_product_1_v1/_settings?pretty'
php bin/magento indexer:reindex catalogsearch_fulltext

根据证据分支定位

_analyze 没展开同义词，说明 filter 或 analyzer 未引用；分析正确但文档匹配不变，检查同义词用于 index 还是 search 阶段及字段 mapping；重建后新索引正确、别名仍指旧索引，查索引切换失败。集群每个数据节点还必须能读取一致配置。

修复时保留回滚路径

通过受版本控制的搜索配置部署同义词，在新索引上验证 analyzer 后执行 Magento 搜索索引重建和别名切换。区分需要重新索引的 index-time synonym 与可 reload 的 search-time 方案；不要直接修改生产索引 mapping 期待自动生效。

上线验收

准备应互相召回和不应扩展的词组，检查 token、命中 SKU、排序和多语言 Store。滚动重启或索引版本切换后结果保持一致，旧索引只在回滚窗口后删除。

生产环境操作前的检查

处理“Magento 2 OpenSearch 同义词更新后搜索无变化”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录 agreement ID、是否 Active、Mode、关联 Store View 和结账主题。比较 Luma/默认结账与当前主题，检查页面配置数据和 Console 首条错误。

SELECT agreement_id,name,is_active,is_html,mode,checkbox_text,content_height
FROM checkout_agreement ORDER BY agreement_id;
SELECT agreement_id,store_id FROM checkout_agreement_store ORDER BY agreement_id,store_id;
php bin/magento config:show checkout/options/enable_agreements
grep -R --line-number 'checkout-agreements|agreements' app/design app/code 2>/dev/null
php bin/magento cache:clean config layout block_html full_page

根据证据分支定位

agreement 接口或 checkout config 没数据，查 Store 关联与作用域；数据存在但组件没渲染，查布局、模板和 JS 错误；默认主题正常而一步结账失败，按扩展提供的集成点处理。Mode 为自动时本来就可能不要求用户勾选。

修复时保留回滚路径

在正确 Store View 启用需要的协议并使用标准 agreements 组件或扩展的兼容实现。不要只在前端加一个没有服务端校验的复选框；需要强制同意时，提交订单接口必须验证对应 agreement ID。

上线验收

访客与登录客户、每个支付方式和 Store View 都测试。未勾选时订单提交被明确阻止，勾选后可下单，非目标 Store 不应出现错误协议。

生产环境操作前的检查

处理“Magento 2 结账页不显示条款复选框”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录页面 Origin、字体最终 URL、重定向链、Content-Type、Access-Control-Allow-Origin、Vary 和 CDN HIT/MISS。直接访问文件成功不代表字体上下文允许使用。

curl -skI -H 'Origin: https://shop.example.com' https://cdn.example.com/static/font.woff2
curl -skIL https://cdn.example.com/static/font.woff2
php bin/magento config:show web/secure/base_static_url
find pub/static -iname '*.woff*' -o -iname '*.ttf' | head
file pub/static/frontend/Vendor/theme/en_US/fonts/font.woff2

根据证据分支定位

CDN 无 Allow-Origin 而源站有，修 CDN 响应头策略；两者都无，配置静态资源服务器；返回 text/html 常是 404 或安全页，不是字体；只有首次 MISS 失败而 HIT 持续失败，检查 CDN 是否按 Origin 正确缓存及 Vary。

修复时保留回滚路径

对白名单店铺域名返回准确的 Access-Control-Allow-Origin，公共非凭据静态字体也可按安全策略使用通配符。确保 WOFF2 MIME 正确、URL 不重定向到另一未授权域名，并清除精确 CDN 对象；不要给所有动态接口无条件开放 CORS。

上线验收

在两个允许 Store 域名和一个不允许域名测试，字体、图标和 Network 请求符合策略。桌面与移动浏览器、生产和静态版本切换后都不再出现 CORS 错误。

生产环境操作前的检查

处理“Magento 2 CDN 字体被 CORS 拒绝”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

分别请求源站与 Varnish/CDN，保存状态码、响应头大小、X-Magento-Tags 数量和页面包含的自定义 Block。不要把 Cookie 或认证头写入共享日志。

curl -skD /tmp/headers.txt -o /dev/null https://shop.example.com/category.html
wc -c /tmp/headers.txt
grep -i '^X-Magento-Tags:' /tmp/headers.txt | tr ',' '
' | sort | uniq -c | sort -nr | head
grep -R --line-number 'IdentityInterface|getIdentities' app/code 2>/dev/null
nginx -T 2>/dev/null | grep -nE 'proxy_buffer|fastcgi_buffer|large_client_header'

根据证据分支定位

源站已经 502，查 PHP/Web Server 头限制；源站 200、代理 502，查对应上游 buffer；标签主要来自一个自定义前缀，审计其 getIdentities。核心分类标签随商品数增长与自定义 Block 把集合每个实体都加入标签，修复策略不同。

修复时保留回滚路径

让自定义 Block 返回足以精确失效的聚合标签，避免无边界地追加集合中所有对象。确认应用层修复后再依据最大合理头部调整代理 buffer，并评估并发内存；不要删除所有标签，否则内容更新后可能长期不失效。

上线验收

测试小分类和最大分类，源站、Varnish 与 CDN 都返回 200，Header 大小受控。修改一个相关商品后页面能正确失效，无关商品更新不应清空全部站点缓存。

生产环境操作前的检查

处理“Magento 2 Cache Tags 响应头过大导致 502”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录规则 ID、from_date、to_date、is_active、Website、客户组、Store 时区和一个目标 SKU。比较服务器、PHP、数据库和 Magento 商店时间。

date -u
php -r 'echo date("c"), PHP_EOL;'
mysql -e 'SELECT NOW(),UTC_TIMESTAMP(),@@session.time_zone'
php bin/magento config:show general/locale/timezone
SELECT rule_id,name,from_date,to_date,is_active FROM catalogrule WHERE rule_id=10;
SELECT rule_id,product_id,customer_group_id,from_time,to_time,rule_price
FROM catalogrule_product_price WHERE rule_id=10 LIMIT 20;
php bin/magento indexer:status catalogrule_rule catalogrule_product catalog_product_price

根据证据分支定位

规则表未产生目标商品，检查条件、Website 与客户组；已有规则价格但前台不变，查价格索引和缓存；只在日期边界失败，核对时区转换和 Cron 执行窗口。多规则同时命中时还要检查优先级与停止后续规则。

修复时保留回滚路径

统一 NTP 和 PHP/数据库基础时间，Magento Store 使用正确业务时区；修复 Cron 后重新应用规则并让相关索引正常消费。不要每天用手工 Apply 代替故障的调度链，也不要直接修改 rule_product_price。

上线验收

在测试环境使用临近生效与失效边界的规则，覆盖两个客户组和 Website。规则应自动开始与结束，列表、详情、购物车和订单价格一致，跨午夜无需人工操作。

生产环境操作前的检查

处理“Magento 2 Catalog Price Rule 午夜后没有生效”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

锁定订单和 Shipment，导出 sales_order_item 的 parent_item_id、product_type、qty_ordered、qty_shipped、qty_canceled、qty_refunded，再与 sales_shipment_item 对照。

SELECT item_id,parent_item_id,sku,product_type,qty_ordered,qty_shipped,qty_canceled,qty_refunded
FROM sales_order_item WHERE order_id=123 ORDER BY item_id;
SELECT s.entity_id,s.increment_id,si.order_item_id,si.sku,si.qty
FROM sales_shipment s JOIN sales_shipment_item si ON si.parent_id=s.entity_id
WHERE s.order_id=123 ORDER BY s.entity_id,si.entity_id;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku IN ('SKU-A','SKU-B');

根据证据分支定位

shipment_item 数量正确而 order_item 累计错误，查自定义保存流程；父子行同时累计，检查商品类型处理；后台正确但 ERP 显示错误，查接口映射。MSI 环境还要区分 Reservation 补偿与实际 Source deduction，不要把两个动作都当物理扣减。

修复时保留回滚路径

通过 Shipment Repository 或标准订单服务创建发货，按可发的叶子订单项传数量，并用外部 shipment ID 做幂等。不要直接更新 qty_shipped；修历史订单前先重建每张 Shipment 的事实明细并评估库存和邮件副作用。

上线验收

测试可配置、Bundle、简单商品的部分与全部发货，重复提交同一 ERP 事件只能产生一次 Shipment。剩余可发数量、订单状态、库存 Source 和客户邮件应一致。

生产环境操作前的检查

处理“Magento 2 部分发货数量与订单不一致”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

选择一位异常客户和一位正常免税客户，对比 customer_group_id、tax_class_id、商品 tax_class_id、配送与账单地址、Store 和 Quote totals。不要在日志输出完整客户地址。

SELECT customer_group_id,customer_group_code,tax_class_id FROM customer_group ORDER BY customer_group_id;
SELECT class_id,class_name,class_type FROM tax_class ORDER BY class_type,class_id;
SELECT r.code,r.priority,r.position,r.calculate_subtotal
FROM tax_calculation_rule r ORDER BY r.priority,r.position;
SELECT address_type,country_id,region_id,postcode,tax_amount,base_tax_amount
FROM quote_address WHERE quote_id=12345;
php bin/magento config:show tax/calculation/based_on

根据证据分支定位

客户组指向普通税类，属于映射问题；税类正确但规则仍命中，检查 Tax Rule 组合；地址尚未保存时可能使用 Default Tax Destination；登录后旧 Quote 没重算，则检查客户组变更后的 totals invalidation。含税价格配置会让显示口径与 tax_amount 直觉不同。

修复时保留回滚路径

把免税客户组映射到明确的 Customer Tax Class，并在规则层定义不会命中税率的组合。自定义免税证书逻辑应在受控服务中决定税类或税计算上下文，保留审核记录；不要结账后直接把订单 tax_amount 改为零。

上线验收

测试访客、普通客户、免税客户，两种地址和含税/未税显示。购物车、结账、订单、发票与退款的税额必须一致，客户免税状态变化后已有 Quote 应重新计算。

生产环境操作前的检查

处理“Magento 2 免税客户仍被收取税费”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

保存每页请求变量、返回 SKU 顺序、total_count、索引别名和请求时间。固定分类与筛选条件，连续请求相同页两次，并在无商品更新的窗口复现。

curl -sS -H 'Content-Type: application/json'  --data '{"query":"query($p:Int!){products(search:"",pageSize:20,currentPage:$p,sort:{price:ASC}){total_count items{sku name}}}","variables":{"p":1}}'  https://shop.example.com/graphql
grep -R --line-number 'setOrder|addOrder|sort' app/code/*/*/Model/Resolver 2>/dev/null
php bin/magento indexer:status catalogsearch_fulltext catalog_product_price

根据证据分支定位

相同请求自己就顺序变化，优先查非稳定排序和搜索集群；固定不变但页间重复，检查 offset、pageSize 和自定义结果拼接；只有索引更新时变化，则评估无限滚动期间商品变更的产品体验。自定义 Resolver 若先分页后再过滤，会必然漏项。

修复时保留回滚路径

使用业务排序字段加稳定且唯一的次级键，过滤应在分页之前完成。客户端对短时数据变更可按 SKU 去重，但不能用它掩盖服务端 total_count 和排序错误；导出等强一致任务改用主键游标分批。

上线验收

准备多个相同价格与位置的商品，遍历全部页后 SKU 集合应无重复且数量等于 total_count。索引更新、商品上下架和不同 Store View 下也要有可解释的一致行为。

生产环境操作前的检查

处理“Magento 2 GraphQL 翻页出现重复或漏商品”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录切换前后 store_id、website_id、Session 是否保持、active quote_id、SKU 网站分配和货币。分别测试同 Website 的两个 Store View 与跨 Website 切换。

SELECT store_id,code,website_id,group_id FROM store ORDER BY website_id,store_id;
SELECT entity_id,store_id,is_active,customer_id,items_count,quote_currency_code,updated_at
FROM quote WHERE entity_id IN (12345,12346);
SELECT product_id,website_id FROM catalog_product_website
WHERE product_id IN (SELECT product_id FROM quote_item WHERE quote_id=12345);
php bin/magento config:show checkout/options/enable_agreements

根据证据分支定位

Session ID 改变，查 Cookie Domain、Path 和 Base URL；Session 相同但创建新 Quote，查 website 隔离和切换代码；Quote 保留而商品被移除，查目标网站分配、可售量、价格和必选选项。仅显示空但接口有 items，则属于 customer-data 前端刷新问题。

修复时保留回滚路径

先明确业务是否允许跨 Website 共享购物车。同 Website 切换应复用或安全转换 Quote；跨 Website 若需要迁移，应逐项重新验证商品、库存、价格、税和币种，不能只改 quote.store_id。

上线验收

覆盖访客与登录客户、同 Website、跨 Website、可售与不可售商品、优惠码和不同币种。切换结果应符合明确规则，不能静默丢失商品；被移除项目需给出可理解提示。

生产环境操作前的检查

处理“Magento 2 切换商店后购物车变空”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

用测试订单记录 PDF 原始大小、生成耗时、发送进程 memory_get_peak_usage、附件数量和是否异步。比较无附件、单个小附件与问题附件，不在日志保存文档内容或客户信息。

php -i | grep memory_limit
du -h var/tmp/*.pdf 2>/dev/null | sort -h | tail
grep -R --line-number 'addAttachment|createAttachment|TransportBuilder' app/code 2>/dev/null
grep -RniE 'Allowed memory size|out of memory|email' var/log | tail -n 80
php bin/magento config:show sales_email/general/async_sending

根据证据分支定位

生成 PDF 前就耗尽，查商品图片和模板循环；PDF 已生成、构建 MIME 时耗尽，检查整文件多次复制和 Base64；只在队列失败，检查消息是否携带完整二进制而非可重建引用。重复附件还可能来自 Plugin 多次调用。

修复时保留回滚路径

限制附件数量和尺寸，减少高分辨率图片，避免在多个字符串变量中复制同一二进制。队列消息保存受控文件引用或业务 ID，并在消费时验证权限和生命周期；临时文件应在发送完成后安全清理。调整 memory_limit 只能基于峰值和并发容量评估。

上线验收

测试最小、平均和允许的最大附件，邮件可打开且 PDF 内容完整。并发发送时 Worker 内存应回落，失败重试不得重复生成无限临时文件或重复发送。

生产环境操作前的检查

处理“Magento 2 邮件附件导致内存耗尽”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

保存完整堆栈，找到第一个自定义类调用 State::setAreaCode 的位置。确认错误发生在 Cron 组、队列消费者还是 CLI，并检查一个进程内是否循环处理多个实体或消息。

grep -R --line-number 'setAreaCode' app/code 2>/dev/null
grep -R --line-number 'emulateAreaCode|startEnvironmentEmulation' app/code 2>/dev/null
php bin/magento cron:run --group default -vvv
php bin/magento queue:consumers:start your.consumer --max-messages=2 -vvv

根据证据分支定位

入口 Command 中设置一次而服务不再设置通常可接受；深层 Service、Observer 或 Repository 中设置 Area 会污染所有调用方。只有特定模板或配置读取需要前台上下文时，应使用受控环境模拟并保证 finally 中停止。

修复时保留回滚路径

把 Area 责任放在应用入口，业务服务显式接收所需 Store 或配置，不依赖全局 Area。必须兼容不同入口时先读取当前 Area，不要捕获异常后继续猜测；环境模拟需成对开始和停止，防止影响下一条消息。

上线验收

同一进程连续执行任务两次、处理两个 Store，并覆盖 Cron 与手工 CLI。第二次执行不报错，Store 配置和模板也不能沿用上一任务的上下文。

生产环境操作前的检查

处理“Magento 2 Cron 报 Area code is already set”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录每张 *_cl 表的行数、最小与最大 version_id、对应 mview_state 的 version_id 和索引状态，间隔十分钟再次采样，判断生产与消费速度。

SELECT view_id,mode,status,version_id,updated FROM mview_state ORDER BY view_id;
SELECT COUNT(*) cnt,MIN(version_id),MAX(version_id) FROM catalog_product_price_cl;
SELECT COUNT(*) cnt,MIN(version_id),MAX(version_id) FROM catalogsearch_fulltext_cl;
php bin/magento indexer:show-mode
php bin/magento indexer:status
php bin/magento cron:run --group index -vvv

根据证据分支定位

最大 version_id 增长而 state 不动，查 index Cron 与索引错误；state 前进但旧行不清理，检查清理过程与长事务；表没有新行但业务有变更，核对触发器是否存在。Realtime 与 Schedule 模式混用时要确认真实预期。

修复时保留回滚路径

先修复失败索引器或 Cron，观察 state 恢复推进，再让系统正常清理已消费范围。确需人工归档时，只处理严格小于已确认消费 version_id 的记录，并先备份；不能把 state 强行跳到最大值。

上线验收

修改一个商品价格和分类关系，changelog 增加后应在预期周期被消费，前台索引同步。连续观察高峰期，表行数应在可控区间波动而不是单向增长。

生产环境操作前的检查

处理“Magento 2 MView changelog 表持续增长”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

保存 bulk_uuid、路由、提交条数、创建时间与一个 operation_key。统计 open、complete_recoverable、complete 和 rejected 数量，不记录请求中的客户或认证敏感数据。

SELECT uuid,description,operation_count,start_time FROM magento_bulk ORDER BY start_time DESC LIMIT 10;
SELECT bulk_uuid,status,topic_name,operation_key,error_code,result_message
FROM magento_operation WHERE bulk_uuid='BULK-UUID' ORDER BY id;
php bin/magento queue:consumers:list
php bin/magento queue:consumers:start async.operations.all --max-messages=50 -vvv
php bin/magento queue:consumers:start product_action_attribute.update --max-messages=50 -vvv

根据证据分支定位

没有 magento_operation 行，检查请求路由和提交事务；有 open 且队列深度增长，检查 Consumer；转为 recoverable 或 rejected，则读取脱敏错误信息并修业务数据。DB 队列与 RabbitMQ 环境使用的检查方式不同，先确认 env.php 的实际连接。

修复时保留回滚路径

恢复正确 Consumer 和 Supervisor 配置，并对失败操作按业务幂等性决定重试。不要直接把状态 UPDATE 为 complete，也不要删除 open 行掩盖积压；大批量按可承受条数拆分，并给 API 调用方提供状态与失败明细。

上线验收

提交包含成功、可恢复失败和永久失败的小批次，状态应最终收敛且成功实体已保存。重启 Consumer 后消息不能丢失或重复产生业务副作用，积压曲线应持续下降。

生产环境操作前的检查

处理“Magento 2 异步批量 API 一直停在 open”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

给本次构建记录不可变版本号，在响应头或健康页输出不敏感的 build ID 和节点名。对比 Web PHP 与 CLI PHP 的版本、php.ini 和实际 release 路径。

readlink -f /var/www/current
php -i | grep -E 'opcache.validate_timestamps|opcache.revalidate_freq|opcache.enable_cli'
php-fpm -i 2>/dev/null | grep -E 'opcache.validate_timestamps|opcache.revalidate_freq'
ps -eo pid,lstart,cmd | grep '[p]hp-fpm'
sha256sum app/etc/config.php composer.lock

根据证据分支定位

只有 Web 请求旧而 CLI 新，检查 FPM OPcache 和进程；只有队列消费者旧，说明长进程未重启；刷新随机切换版本，说明负载均衡后节点或 release symlink 不一致。validate_timestamps 关闭时，仅替换文件不会使缓存自动失效。

修复时保留回滚路径

使用原子 release 切换，发布完成后按运维策略平滑 reload PHP-FPM 并重启 Magento 长进程；所有节点部署同一构建。不要从 Web 请求暴露 opcache reset 端点，也不要在高峰粗暴 kill 全部进程。

上线验收

连续请求覆盖所有节点，build ID、堆栈行号和行为必须一致；运行 Cron、消费者与后台任务验证新代码。下一次回滚也应按同样流程切换并刷新进程缓存。

生产环境操作前的检查

处理“Magento 2 发布后 PHP 仍执行旧代码”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

用 curl 保存 Location 链、状态码、Host、协议和 Set-Cookie，分别绕过 CDN 请求源站。确认循环只发生在某个 Store View、登录状态或特定商品分类。

curl -skIL --max-redirs 12 https://shop.example.com/old-path.html
SELECT url_rewrite_id,entity_type,entity_id,request_path,target_path,redirect_type,store_id,is_autogenerated
FROM url_rewrite
WHERE request_path IN ('old-path.html','new-path.html')
   OR target_path IN ('old-path.html','new-path.html')
ORDER BY store_id,url_rewrite_id;
php bin/magento config:show web/url/use_store
php bin/magento config:show catalog/seo/product_url_suffix

根据证据分支定位

数据库两条 301 互相指向，属于重写链冲突；Magento 只返回一次，后续由 Nginx/CDN 改回，则检查尾斜杠、HTTP 到 HTTPS 和 www 规范化；不同 Store Code 互跳时，检查 Base URL、Cookie 与 Store Resolver。

修复时保留回滚路径

保留唯一规范 URL和最多一条从旧地址到规范地址的 301，通过后台实体保存或受控数据补丁修复。修改 Web 规则时一次只统一一个维度，并在 CDN 清除精确 URL；不要把所有 404 广泛重定向到首页。

上线验收

检查旧地址一次 301 后到达 200，新地址直接 200；HTTP、HTTPS、www、非 www、带 Store Code 和无 Store Code 都不能形成第二条反向跳转。同步验证 canonical、Sitemap 和内部链接。

生产环境操作前的检查

处理“Magento 2 URL Rewrite 出现循环重定向”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

先把请求缩减到单个字段单个值，再逐个增加条件。保存解码后的查询参数、返回总数和一条应命中、一条不应命中的实体，避免只看第一页。

curl -G 'https://shop.example.com/rest/V1/products'  --data-urlencode 'searchCriteria[filter_groups][0][filters][0][field]=status'  --data-urlencode 'searchCriteria[filter_groups][0][filters][0][value]=1'  --data-urlencode 'searchCriteria[filter_groups][1][filters][0][field]=sku'  --data-urlencode 'searchCriteria[filter_groups][1][filters][0][value]=ABC%'  --data-urlencode 'searchCriteria[filter_groups][1][filters][0][condition_type]=like'
grep -R --line-number 'FilterProcessor|CollectionProcessor' app/code 2>/dev/null

根据证据分支定位

单条件正确、加入第二组后为空，检查期望是否真的是 AND；两个 filter 放同组后数据变多，说明 OR 生效；服务端日志看到括号或百分号被破坏，检查客户端 URL 编码。自定义接口若完全忽略条件，检查 Repository 是否调用 collection processor。

修复时保留回滚路径

先用标准 SearchCriteriaBuilder 在集成测试中表达目标逻辑，再让 REST 客户端生成等价参数。复杂的嵌套布尔条件不要硬塞进不支持的结构，可设计明确的服务接口；禁止把客户端字段直接拼接成 SQL。

上线验收

用真值表准备四条数据，覆盖仅满足 A、仅满足 B、同时满足和都不满足。校验 total_count、分页、排序以及特殊字符值，API 与 Repository 集成测试结果必须一致。

生产环境操作前的检查

处理“Magento 2 REST SearchCriteria 的 AND 与 OR 条件写反”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

在无痕窗口记录登录请求、customer/section/load 响应、private_content_version Cookie 和 Local Storage 中 mage-cache-storage、mage-cache-storage-section-invalidation。比较完整页面登录与 AJAX 登录两条路径。

grep -R --line-number 'sections.xml' app/code vendor 2>/dev/null
grep -R --line-number 'SectionSourceInterface' app/code 2>/dev/null
php bin/magento cache:clean config full_page
curl -sS -D - 'https://shop.example.com/customer/section/load/?sections=customer,cart' -o /tmp/sections.json

根据证据分支定位

section/load 已返回正确客户而页面仍旧，检查 Knockout 绑定和 JS 错误；响应本身还是访客，检查请求 Cookie、Session 与 SectionSource；登录后根本未请求 section/load，则检查 sections.xml 的 action 配置与自定义 AJAX 登录是否触发 invalidate/reload。

修复时保留回滚路径

为改变客户状态的 action 精确配置需要失效的 section，并在自定义前端流程成功后调用官方 customer-data invalidate/reload。不要把 customer、cart 等私有 section 放进公共 CDN 缓存，也不要靠每次清空所有 Local Storage 掩盖缺失的失效规则。

上线验收

访客、客户 A、客户 B 依次登录和注销，页头、购物车和收藏夹不得串号；测试 FPC HIT、浏览器后退和两个标签页，同一账户状态应在合理时间内同步。

生产环境操作前的检查

处理“Magento 2 登录后 customer-data 仍显示访客信息”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

固定一个 Quote，记录 website、目的国家、region_id、邮编、包裹重量、含税和未税金额。导出同一网站当前配置作为模板，不要凭记忆自行拼表头。

php bin/magento config:show carriers/tablerate/active --scope=websites --scope-code=base
php bin/magento config:show carriers/tablerate/condition_name --scope=websites --scope-code=base
SELECT dest_country_id,dest_region_id,dest_zip,condition_name,condition_value,price,cost
FROM shipping_tablerate ORDER BY pk DESC LIMIT 30;
SELECT country_id,region_id,postcode,weight,subtotal,base_subtotal
FROM quote_address WHERE quote_id=12345 AND address_type='shipping';

根据证据分支定位

表中没有目标 website 的记录，说明导入时作用域错误；有记录但国家或地区不符，检查 ISO 国家代码与 region_id；地址匹配而 condition_value 不匹配，则核对 Package Weight、Order Subtotal 等条件口径和虚拟商品。邮编通配规则应按实际实现测试，不能假设星号支持任意位置。

修复时保留回滚路径

在正确 Website Scope 重新导入由系统导出的模板，只保留一条可验证规则作为小样本。确认命中后再分批加入区间和地区；不要直接复制 shipping_tablerate 行到另一网站，因为 website_id、地区与条件可能不同。

上线验收

测试同城邮编、边界重量、边界金额、不允许国家和虚拟购物车。购物车估算、结账重新计算与最终订单运费必须一致，切换地址后旧 rate 不得残留。

生产环境操作前的检查

处理“Magento 2 Table Rate 导入成功却没有运费”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件和影响范围

记录受影响管理员、Provider 类型、错误时间和所有管理员是否同时失败。用另一个已授权管理员对照，确认问题是账号级还是全站级；日志中不得记录一次性验证码、恢复码或共享密钥。

php bin/magento module:status Magento_TwoFactorAuth
php bin/magento config:show admin/security
date -u
timedatectl status
grep -RniE 'two.?factor|2fa|otp|provider' var/log | tail -n 80

根据证据分支定位

所有管理员同时失败，优先检查发布后模块状态、依赖和系统时间；只有一个用户失败，检查其 Provider 绑定与设备时间。多节点偶发失败时，比较各节点 crypt key、PHP 时区和 Session 存储，但不要把密钥内容输出到日志。

修复时保留回滚路径

先恢复 NTP 与一致的部署配置，再使用 Magento 当前版本支持的管理员恢复流程重置特定用户的 2FA 绑定。若必须短时应急停用模块，应限定维护窗口、限制后台网络入口并在完成后立即恢复和重新注册，不要删除数据库记录来猜测状态。

上线验收

分别使用两个管理员完成登录、注销、重新登录和 Session 过期测试；校验错误验证码被拒绝、正确验证码只能使用一次，多节点切换后也不能绕过二次验证。

生产环境操作前的检查

处理“Magento 2 后台双重验证 Provider 不可用”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近一次发布。所有 SQL 默认先执行 SELECT；任何写操作、目录清理或配置切换都应确认影响范围、保留备份并准备回滚。多节点环境要核对各节点代码版本、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 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费或订单的改动，先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。准备一个正常对象与一个异常对象对照；若旧对象恢复而新对象仍能复现，说明根因尚未消除。

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器和目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。

先固定复现条件

选择一个正常 SKU 和一个异常 SKU，记录编辑 Scope、website_id、客户组、币种与更新时间。直接商品页和分类页都测试，避免只看到 CDN 旧页面。

SELECT entity_id,sku,updated_at FROM catalog_product_entity WHERE sku IN ('GOOD-SKU','MISS-SKU');
SELECT attribute_id,attribute_code,is_global FROM catalog_eav_attribute WHERE attribute_id=(SELECT attribute_id FROM eav_attribute WHERE attribute_code='price' LIMIT 1);
php bin/magento indexer:status catalog_product_price
SELECT * FROM mview_state WHERE view_id='catalog_product_price';

根据结果定位根因

Website Scope 下可能只更新了另一个网站；Update by Schedule 模式依赖 Cron 消费 changelog。客户组价、特殊价日期或目录规则也可能覆盖基础 price。

修复时保留回滚路径

在正确 Scope 重做一条样本，确认 EAV decimal 值后只重建 catalog_product_price，并检查 Cron 根因。不要把每日全量 reindex 当作增量失败的替代方案。

上线后的验收

测试两个网站、访客与客户组、列表页和详情页，并核对购物车最终单价。再次批量更新一个小值，前台应在预期索引周期内自动变化。

生产环境操作前的检查

针对“Magento 2 后台批量更新属性后前台价格未变化”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

保存完整异常堆栈和失败索引器，检查数据库主机而非仅 Web 节点的文件系统、inode、tmpdir 与 MySQL 错误日志。

df -h
df -i
mysql -e "SHOW VARIABLES LIKE 'tmpdir'; SHOW VARIABLES LIKE 'innodb_temp_data_file_path';"
mysql -e "SHOW GLOBAL STATUS LIKE 'Created_tmp%';"
php bin/magento indexer:reindex catalog_product_price -vvv

根据结果定位根因

磁盘利用率满、容器临时盘配额、过多临时文件或异常宽的自定义索引查询是常见根因。MEMORY 表还受 max_heap_table_size 限制，但不要不加区分地调大。

修复时保留回滚路径

先释放已确认可删除的日志/临时文件或扩容正确卷，再处理遗留临时表。优化自定义索引 SQL 与批次大小；变更 MySQL 临时表空间前做好备份和重启计划。

上线后的验收

单独重建失败索引器并确认 Ready，再运行完整索引。观察磁盘峰值、临时表数量与查询时间，下一轮定时增量不得再次耗尽空间。

生产环境操作前的检查

针对“Magento 2 重新索引报 The table is full”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

在浏览器瀑布图中找同一时间开始却依次结束的请求，关联 PHP-FPM slowlog、Nginx request_time 和 Redis 客户端。用测试会话复现，不记录真实 session ID。

grep -n "session" app/etc/env.php
redis-cli INFO clients
redis-cli INFO commandstats
ps -eo pid,etime,%cpu,%mem,cmd | grep '[p]hp-fpm'
grep -R "request_slowlog_timeout" /etc/php* 2>/dev/null

根据结果定位根因

外部支付调用、同步邮件、远程库存查询或自定义 Observer 在 session 打开期间执行，会长时间持锁。锁重试次数与等待时间不当只会放大症状。

修复时保留回滚路径

先缩短持锁请求，把外部工作移到队列并尽早关闭不再需要的 session。谨慎调整 max_concurrency、break_after_frontend 等参数，保留并发一致性与回滚配置。

上线后的验收

模拟结账页面的并发 totals、shipping 与 payment 请求，P95 延迟明显下降且购物车不丢商品。Redis 锁超时日志、PHP slowlog 和错误率连续观察一轮高峰。

生产环境操作前的检查

针对“Magento 2 Redis Session Lock 导致结账变慢”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

在无痕窗口保存完整控制台消息、blocked URI、effective directive 与页面 URL。确认脚本是业务必需、由谁加载、是否还有 iframe、connect 或 image 子资源。

grep -R --line-number "csp_whitelist.xml" app/code vendor 2>/dev/null
find app/code -path '*/etc/csp_whitelist.xml' -print
php bin/magento module:status Magento_Csp
php bin/magento cache:clean config full_page

根据结果定位根因

只放行脚本主域名仍可能被 connect-src、frame-src 或 img-src 阻止；内联脚本需要 nonce/hash，不能靠 unsafe-inline 一次放开。支付域名也可能区分测试与生产。

修复时保留回滚路径

在自定义模块的 csp_whitelist.xml 中按 directive 添加精确 HTTPS host；内联代码优先使用 nonce 兼容接口。先在 report-only 环境收集遗漏，再切 enforcing。

上线后的验收

测试全部支付方式、3DS、地址验证与失败重试，控制台没有新的违反项。恶意内联脚本仍应被拦截，其他 Store View 和 CDN 页面头保持一致。

生产环境操作前的检查

针对“Magento 2 CSP 阻止结账第三方脚本”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

在干净构建目录用锁文件安装一次，保存 Composer 输出，确认失败的是补丁下载、SHA 校验、目标包缺失还是 hunk 上下文不匹配。

composer show magento/framework
composer validate
composer install -vvv 2>&1 | tee /tmp/composer-install.log
grep -n -Ei 'patch|failed|skipped' /tmp/composer-install.log
git diff -- composer.json composer.lock patches

根据结果定位根因

composer.json 与 lock 不同步、补丁只配置在根项目外、目标版本已包含修复、补丁 URL 变化或插件被 allow-plugins 阻止，都会导致状态异常。

修复时保留回滚路径

把补丁文件纳入项目并记录来源、适用版本与校验和；在新包版本上重新生成最小补丁。不要用忽略失败继续发布，也不要重新手改 vendor。

上线后的验收

删除 vendor 后执行干净 install，补丁必须成功应用；运行相关单元/集成测试并检查目标代码。CI 应在补丁跳过或失败时阻断构建。

生产环境操作前的检查

针对“Magento 2 Composer 更新后官方补丁失效”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

记录 SKU、website、stock_id、各 Source 数量、是否可售和缺货阈值。不要只看 Default Source，也不要假设 inventory_stock_1 代表所有网站。

SELECT stock_id,website_id FROM inventory_stock_sales_channel;
SELECT source_code,sku,quantity,status FROM inventory_source_item WHERE sku='SKU-1';
SELECT sku,SUM(quantity) reserved FROM inventory_reservation WHERE sku='SKU-1' GROUP BY sku;
php bin/magento inventory:reservation:list-inconsistencies -r

根据结果定位根因

常见原因包括 ERP 只更新一个 Source、网站绑定错误 Stock、取消订单缺少补偿、阈值为负或 Backorders 配置被 Store 覆盖。索引过期会让数据库源数据正确而前台仍旧。

修复时保留回滚路径

先修 Source 同步和 Stock 绑定，再处理经核实的 reservation 差异并重建 inventory 索引。不要直接把索引 quantity 改成零，它会在下次重建时被覆盖。

上线后的验收

在每个网站测试下单、取消、发货与补货，确认 Source quantity、reservation 和 salable quantity 按预期变化。库存到零时前台行为必须符合 Backorders 配置。

生产环境操作前的检查

针对“Magento 2 多来源库存可售数量变成负数”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

按订单号汇总 webhook 访问日志、payment transaction、invoice 和订单历史，确认重复请求的事件 ID、到达间隔与响应码。日志不能保存完整签名密钥或卡数据。

SELECT transaction_id,parent_txn_id,txn_type,is_closed,created_at FROM sales_payment_transaction WHERE order_id=123;
SELECT entity_id,increment_id,state,grand_total,created_at FROM sales_invoice WHERE order_id=123;
SELECT parent_id,status,comment,created_at FROM sales_order_status_history WHERE parent_id=123;

根据结果定位根因

只检查订单 status 不足以防并发，因为两个请求可能同时读到 processing。缺少唯一事件表、未锁订单行、网关交易 ID 未设唯一约束或异常后返回 500，都会触发重复。

修复时保留回滚路径

先验签，再以 provider+event_id 建唯一记录；事务内锁定订单并检查 payment transaction 与 canInvoice。已处理事件立即返回 2xx，永久错误进入人工队列，可重试错误保留明确状态。

上线后的验收

在测试环境并发发送同一回调五次，只能产生一张发票、一次邮件和一个 capture。乱序、延迟与退款回调也不能破坏最终订单状态。

生产环境操作前的检查

针对“Magento 2 支付回调重复导致订单重复开票”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

保留表头和一条失败 SKU，确认导入行为、Store View、字段原始字节及错误列。用同属性的正常商品从后台导出，比较实际格式。

SELECT a.attribute_id,a.attribute_code,a.frontend_input,a.backend_type,a.is_required
FROM eav_attribute a WHERE a.attribute_code='color';
SELECT o.option_id,v.store_id,v.value FROM eav_attribute_option o
JOIN eav_attribute_option_value v ON v.option_id=o.option_id WHERE o.attribute_id=93;
file -bi import.csv

根据结果定位根因

标签大小写或空格不一致、选项只存在于特定 Store、日期格式与 locale 不符、布尔值使用 Yes/No 之外的文本，都会触发错误。CSV 的 BOM 和不可见字符也要排查。

修复时保留回滚路径

在后台或数据补丁中创建缺失选项，再按导出格式修正 CSV。不要为通过导入而关闭验证；生产先用 Add/Update 小批验证，不使用 Replace 处理未知错误。

上线后的验收

导入十行样本后检查默认与 Store View 属性值、筛选器、搜索索引和前台展示。再次导出应得到稳定值，错误报告中不得出现被静默跳过的行。

生产环境操作前的检查

针对“Magento 2 导入商品提示 Value for Attribute Contains Incorrect Value”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

先锁定 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

选一张可复现订单，记录商品类型、总额、已开票金额、已发货数量和当前 state/status，再比较一张正常完成的同类型订单。

SELECT entity_id,increment_id,state,status,total_qty_ordered,total_invoiced,total_paid,total_refunded
FROM sales_order WHERE increment_id='000000123'\G
SELECT order_id,total_qty,qty FROM sales_shipment WHERE order_id=123;
SELECT order_id,state,grand_total FROM sales_invoice WHERE order_id=123;

根据结果定位根因

实物商品通常要完成发票和发货；虚拟商品不需要发货。部分支付模块要求 capture 成功后才能完成，自定义 Observer/Plugin 也可能把状态强制改回 processing。

修复时保留回滚路径

通过标准 invoice、shipment、credit memo 服务推进订单，不直接写数据库。检查自定义状态是否正确分配给 Complete state，并审计 sales_order_save_after 等扩展。

上线后的验收

分别测试在线 capture、离线付款、虚拟商品、部分发货和部分退款。订单历史、邮件、库存扣减与网关状态必须同步，重复回调不能再次改变已完成订单。

生产环境操作前的检查

针对“Magento 2 订单状态无法从 Processing 改为 Complete”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

确认问题 Store View 的 locale，搜索完全一致的源短语。CSV 左侧必须匹配大小写、空格和占位符，主题翻译可能覆盖模块文件。

php bin/magento config:show general/locale/code
find app/code app/design vendor -path '*/i18n/*.csv' -print | grep zh_CN
grep -R --line-number 'Original phrase' app/code app/design vendor 2>/dev/null
php bin/magento cache:clean translate block_html full_page

根据结果定位根因

PHP 文本只需正确翻译和缓存；JS 文本还依赖静态目录中的 js-translation.json。多节点静态版本不一致也会让部分请求继续返回旧字典。

修复时保留回滚路径

在维护窗口只删除准确主题与语言目录，再执行 static-content:deploy。多节点发布同一构建产物，不让每台机器独立生成版本。

上线后的验收

用无痕窗口测试 HTML、结账文本和表单验证，并检查第二语言未被覆盖。连续命中不同 Web 节点时翻译应保持一致。

生产环境操作前的检查

针对“Magento 2 修改翻译 CSV 后前台不更新”进行处理时，先记录 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、两张订单或访客与登录客户。若修复后仅当前对象恢复，而新建对象仍会复现，说明根因尚未消除。

修复后的观察窗口

上线后不要只刷新一次页面就结束。至少观察一轮 Cron、队列消费和索引周期，并在两台节点、无痕浏览器及目标 Store View 重复验证。对日志、数据库行数、错误率和响应时间设置临时观察项；确认它们稳定后再移除调试日志。调试日志可能包含客户、订单或令牌信息，采集时要脱敏，问题结束后及时关闭。

先固定复现条件

记录分类、搜索词、页码、API 参数和调用方。判断是正常用户深翻页，还是导出、爬虫或扩展一次请求超大 pageSize。

curl -s 'http://127.0.0.1:9200/_cat/indices?v'
curl -s 'http://127.0.0.1:9200/magento2_product_1_v*/_settings?pretty'
grep -R --line-number "setPageSize\|setCurPage" app/code 2>/dev/null