执行 catalogsearch_fulltext 重建时报错，先保留完整异常，不要只截取最后一句。连接超时、索引只读、字段映射冲突和 bulk 请求过大都会表现为“搜索索引失败”，处理方式完全不同。

确认 Magento 实际连接的是哪一个搜索节点

先查看部署配置和后台搜索引擎设置，确认主机、端口、索引前缀、认证与 HTTPS 是否一致。可从服务器测试健康接口：

SEARCH_ENDPOINT='搜索服务地址'
curl -sS \"$SEARCH_ENDPOINT/_cluster/health?pretty\"
curl -sS \"$SEARCH_ENDPOINT/_cat/indices?v\"

连接被拒绝应检查服务监听、DNS、防火墙和 TLS；401/403 则检查凭据和访问策略。不要为了让索引通过而关闭搜索服务认证。

黄色不一定失败，红色和只读必须处理

单节点集群因副本无法分配而显示 yellow，通常仍可读写；red 表示主分片未分配，需要先恢复集群。磁盘达到 flood-stage watermark 时，OpenSearch 会把索引设为只读，Magento 的 bulk 写入随即失败。释放磁盘后还要确认只读标记已经解除，再重新索引。

curl -sS \"$SEARCH_ENDPOINT/_cluster/settings?include_defaults=true&pretty\"
curl -sS \"$SEARCH_ENDPOINT/_cat/allocation?v\"

不要直接删除所有索引来腾空间。先识别过期索引、快照和日志占用，确认索引前缀，避免误删其他应用的数据。

映射冲突通常来自属性数据

异常中出现 mapper_parsing_exception、illegal_argument_exception 或某字段类型冲突时，找出对应商品属性。一个属性原来按数字索引，后来写入文本，或第三方模块向同名字段输出不同类型，都可能造成 bulk 中部分文档失败。核对属性 backend type、input type 与历史数据，再修复异常记录。

若错误是请求体过大或超时，可以调整 Magento 搜索索引批次，但批次越小只会降低单次峰值，不会修复坏数据。先单独运行并记录详细输出：

bin/magento indexer:reset catalogsearch_fulltext
bin/magento indexer:reindex catalogsearch_fulltext -vvv

reset 只重置状态，不会解决服务端根因。修复后检查 indexer 状态、集群文档数量，并在前台分别搜索名称、SKU 和一个可搜索属性。还要再修改一个商品，确认增量索引可以自动更新，避免只验证了一次全量重建。