Suggestion 故障排查手册

本文档汇总 suggestion 常见问题与定位步骤。

1. suggestions 总是空数组

现象

{"query":"shirt","language":"en","resolved_language":"en","suggestions":[],"took_ms":0}

排查步骤

1. 确认索引存在且有数据：

curl -u "$ES_USERNAME:$ES_PASSWORD" \
  "$ES_HOST/search_suggestions_tenant_171/_count?pretty"

1. 直接查 suggestion 索引样本：

curl -u "$ES_USERNAME:$ES_PASSWORD" \
  "$ES_HOST/search_suggestions_tenant_171/_search?pretty" -d '{
    "size": 20,
    "query": {"match_all": {}},
    "_source": ["lang","text","rank_score"]
  }'

1. 确认请求语种是否匹配（language=en 时，索引里应有 lang=en 文档）。

2. 检查服务版本是否为最新（重启后端）：

bash scripts/stop.sh
bash scripts/start_backend.sh

已修复的历史问题

• 重复传 size 导致 ES 查询异常并被吞掉：
  • 症状：日志里出现 Received multiple values for 'size'
  • 结果：接口返回空 hits（看起来像“无数据”）
  • 处理：确保 query body 不再携带 size，仅通过 client 参数传 size

2. 报错：tenant_id is required

现象

{
  "error": "tenant_id is required. Provide it via header 'X-Tenant-ID' or query parameter 'tenant_id'",
  "status_code": 400
}

原因

• 请求缺少 X-Tenant-ID，且 URL 没有 tenant_id。

处理

• API 调用至少满足其一：
  • Header：X-Tenant-ID: 171
  • Query：tenant_id=171

示例：

curl "http://localhost:6002/search/suggestions?q=shirt&size=5&language=en&with_results=false&tenant_id=171"

3. ES 401：missing authentication credentials

现象

{
  "type":"security_exception",
  "reason":"missing authentication credentials ..."
}

原因

• ES 开启了安全认证，curl/脚本未带凭证。

处理

curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"

或使用 API Key：

curl -H "Authorization: ApiKey <base64_key>" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"

4. 构建脚本报 Cannot connect to Elasticsearch

原因

• ES 地址不对，或账号密码未配置，或网络不可达。

检查

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

5. 前端请求未携带租户参数

现象

• Network 中请求 URL 无 tenant_id
• Header 里无 X-Tenant-ID

处理

• 确认前端最新代码已生效（清缓存后强刷）。
• 前端应同时透传：
  • X-Tenant-ID
  • tenant_id query 参数（兜底，避免代理丢 header）

6. 关键 query（如 shirt）没有被索引

检查路径

1. MySQL 里确认日志存在并在回溯窗口内：

SELECT query, language, create_time
FROM shoplazza_search_log
WHERE tenant_id = 171
  AND query = 'shirt'
ORDER BY create_time DESC
LIMIT 20;

1. 构建命令是否使用足够大的 --days（例如 365）。
2. 检查 query 是否被清洗规则过滤（空白/符号/过长等）。

7. Invalid HTTP request received.

原因

• 6002 端口上跑的进程不是当前 FastAPI 服务，或请求协议与服务不匹配。

处理

bash scripts/stop.sh
bash scripts/start_backend.sh
curl "http://localhost:6002/health"

若 /health 正常，再测试 /search/suggestions。