ai-saas / saas-search

TROUBLESHOOTING.md 3.48 KB

Suggestion 故障排查手册（Phase 2）

1. /search/suggestions 总是空数组

排查步骤

  1. 检查 alias 是否存在并有数据：
ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"
curl "$ES_HOST/$ALIAS_NAME/_count?pretty"
  1. 直接抽样查看：
curl "$ES_HOST/$ALIAS_NAME/_search?pretty" -H 'Content-Type: application/json' -d '{
  "size": 20,
  "query": {"match_all": {}},
  "_source": ["lang", "text", "rank_score", "query_count_30d"]
}'
  1. 确认请求租户和语言：
curl "http://localhost:6002/search/suggestions?q=shirt&size=10&language=en" \
  -H "X-Tenant-ID: 162"

2. 报错：tenant_id is required

请求缺少 X-Tenant-ID（或 query tenant_id）。

示例：

curl "http://localhost:6002/search/suggestions?q=shirt&size=10&language=en&tenant_id=162"

3. 增量更新没有写入（updated_terms=0）

常见原因

  • watermark 时间窗内没有新日志
  • overlap_minutes 太小
  • min_query_len 过滤过严

处理

./scripts/build_suggestions.sh 162 --mode incremental --overlap-minutes 60

并在 MySQL 中确认窗口内日志存在。

4. alias 未切到新索引

检查

ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"
curl "$ES_HOST/_alias/$ALIAS_NAME?pretty"

处理

重新执行全量发布：

./scripts/build_suggestions.sh 162 --mode full --publish-alias --keep-versions 2

5. ES 401：missing authentication credentials

ES 开启鉴权时，所有 curl 都需要 -u "$ES_USERNAME:$ES_PASSWORD" 或 API Key。

6. 构建脚本报 Cannot connect to Elasticsearch

检查 ES_HOST、账号密码、网络连通性：

echo "$ES_HOST"
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST"

7. 首次增量执行失败：找不到 active index

说明该租户尚未完成全量构建。可直接启用 bootstrap（默认开启）：

./scripts/build_suggestions.sh 162 --mode incremental --bootstrap-if-missing

或先执行一次全量。

8. q=F 这类前缀为空，但商品里明明有 F... 标题

典型原因

  • suggestion 索引里只写入了 query_log，没写入商品 title（例如商品文档缺少 spu_id，但有 id）。
  • 英文标题太长，被噪声过滤（现在会自动提取前导短语，例如 Furby Furblets 2-Pack）。

逐条排查

  1. 看 suggestion alias 是否有 en 文档：
ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/$ALIAS_NAME/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{"size":0,"aggs":{"langs":{"terms":{"field":"lang","size":20}}}}'
  1. 查 en 下是否有 f 前缀：
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/$ALIAS_NAME/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{"size":20,"_source":["text","text_norm","lang"],"query":{"bool":{"filter":[{"term":{"lang":"en"}}],"must":[{"prefix":{"text_norm":"f"}}]}}}'
  1. 对照商品索引确认源数据确实存在 F...：
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/search_products_tenant_162/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{"size":20,"_source":["id","spu_id","title.en"],"query":{"match_phrase_prefix":{"title.en":"f"}}}'
  1. 重建后再测 API：
./scripts/rebuild_suggestions.sh 162
curl "http://localhost:6002/search/suggestions?q=F&size=40&language=en&tenant_id=162"