RUNBOOK.md 2.7 KB
Edit Raw Blame History


Suggestion 运行手册（Phase 2）
本文档面向研发/测试/运维，提供 Suggestion 功能在 Phase 2 的标准操作流程。
1. 适用范围

Suggestion 全量构建（版本化索引 + alias 原子发布）
Suggestion 增量更新（watermark）
Suggestion 查询接口：GET /search/suggestions

2. 前置依赖
确保以下服务和配置可用：


Elasticsearch（开启鉴权时需提供账号密码）
MySQL（可访问 shoplazza_search_log）
API 服务（默认 6002）


建议环境变量：
ES_HOST=http://localhost:9200
ES_USERNAME=...
ES_PASSWORD=...
DB_HOST=...
DB_PORT=3306
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...

3. 全量构建（推荐发布流程）
3.1 执行
./scripts/build_suggestions.sh 162 \
  --mode full \
  --days 365 \
  --publish-alias \
  --keep-versions 2

3.2 预期输出
输出包含关键字段：


mode=full
index_name=..._vYYYYMMDDHHMMSS
alias_published=true
alias_publish.current_index 指向新索引
bulk_result.failed=0

4. 增量更新（watermark）
4.1 执行
./scripts/build_suggestions.sh 162 \
  --mode incremental \
  --overlap-minutes 30

4.2 预期输出
输出包含关键字段：


mode=incremental
target_index（当前 alias 对应索引）
query_window.since/until
updated_terms
bulk_result.failed=0

5. ES 验证步骤

若 ES 开启鉴权，请附带 -u "$ES_USERNAME:$ES_PASSWORD"。

ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"

curl "$ES_HOST/$ALIAS_NAME/_count?pretty"

curl "$ES_HOST/$ALIAS_NAME/_search?pretty" -H 'Content-Type: application/json' -d '{
  "size": 10,
  "query": {"match_all": {}},
  "_source": ["lang", "text", "rank_score", "sources", "query_count_30d"]
}'


重点检查：


alias 是否可查（说明发布成功）
文档数 > 0
关键字段存在：lang/text/rank_score/completion/sat

6. API 回归步骤
curl "http://localhost:6002/search/suggestions?q=shirt&size=10&language=en" \
  -H "X-Tenant-ID: 162"

curl "http://localhost:6002/search/suggestions?q=玩具&size=10&language=zh" \
  -H "X-Tenant-ID: 162"


通过标准：


接口返回 200
suggestions 非空（针对已知存在 query）
took_ms 合理

7. 一键验证脚本
./scripts/rebuild_suggestions.sh 162


该脚本执行：


全量重建并发布 alias
增量更新
ES _count 与样例 _search
API /search/suggestions 冒烟请求

8. 发布检查清单

[ ] 全量构建 bulk_result.failed=0
[ ] alias 指向新版本索引
[ ] 增量更新成功（mode=incremental）
[ ] API 冒烟通过
[ ] 文档与脚本已同步