# Suggestion 故障排查手册（Phase 2）

  ## 1. `/search/suggestions` 总是空数组

  
  ### 排查步骤
  

  1. 检查 alias 是否存在并有数据：

  
  ```bash

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

  ```
  

  2. 直接抽样查看：

  
  ```bash

  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"]
  }'

  ```
  

  3. 确认请求租户和语言：

  
  ```bash

  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`）。

  
  示例：
  
  ```bash

  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` 过滤过严

  
  ### 处理
  
  ```bash

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

  ```
  

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

  ## 4. alias 未切到新索引

  
  ### 检查
  
  ```bash

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

  ```
  

  ### 处理
  

  重新执行全量发布：

  ```bash
  ./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`、账号密码、网络连通性：

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

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

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

  
  ```bash

  ./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` 文档：
  
  ```bash
  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}}}}'
  ```
  
  2. 查 `en` 下是否有 `f` 前缀：
  
  ```bash
  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"}}]}}}'
  ```
  
  3. 对照商品索引确认源数据确实存在 `F...`：
  
  ```bash
  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"}}}'
  ```
  
  4. 重建后再测 API：
  
  ```bash
  ./scripts/rebuild_suggestions.sh 162 F en
  curl "http://localhost:6002/search/suggestions?q=F&size=40&language=en&tenant_id=162"
  ```