作业16：向量运维监控 · 知识更新状态机 · 恢复演练 · 同步失败告警（跟学 + Cursor）

作业目标：读一遍 Milvus（主）或 Elasticsearch kNN（备）官方运维/监控章节，摘 10 个指标；设计「知识更新」状态机（成功/失败/重试/人工）；写恢复演练：删测试集合 → 从备份恢复 → 抽检查询；Cursor 生成知识同步失败告警文案（含 trace / 任务 ID）。

验收标准：

1. 能默写/对照 10 条向量监控指标及告警含义

2. 能画出知识更新状态机并说明 Dify 各阶段对应关系

3. 在隔离环境完成一次向量恢复演练（或书面逐步命令 + 抽检查询脚本结果）

4. 告警模板含 dataset_id、document_id、task_id、trace_id

环境：207 现网向量 Weaviate；Milvus 用 compose milvus profile 在隔离目录演练；ES 见 RAGFlow 附录。

HTML：docs/html_cursor/作业16_向量监控与知识同步_cursor.html

脚本：scripts_cursor/作业16_向量监控与知识同步/

Runbook：作业16_向量恢复演练Runbook_cursor.md

结果：data/homework16/

前置：作业15 备份清单、Worker Runbook

目录

1. 做完长什么样
2. 学习路线
3. Part A · 官方监控 10 指标（Milvus）
4. Part B · ES kNN 备选 10 指标
5. Part C · 知识更新状态机
6. Part D · 恢复演练步骤
7. Part E · Cursor：同步失败告警文案
8. 完整程序
9. 验收清单

做完长什么样

学习路线

A  读 Milvus Monitoring 章节 → 填 10 指标表
B  画知识更新状态机，对照 Dify 文档 indexing 阶段
C  隔离环境：建测试 collection → 备份 → 删除 → 恢复 → spot check
D  跑 hw16_01 生成告警模板；模拟填 task_id / trace_id

Part A · 官方监控 10 指标（Milvus）

来源：Milvus 官方 Monitoring, Alerts & Logs → Monitoring（Prometheus :9091/metrics，Grafana 预置看板）。

命名规则：milvus_<subsystem>_<name>，subsystem 含 proxy / querynode / datacoord / indexnode 等。

官方告警场景（Create an alert）：CPU/内存过高、磁盘不足、Pod 频繁重启；可用 process_resident_memory_bytes 等进程指标配合上表。

本仓库 compose（milvus profile）：19530 gRPC、9091 metrics/health — 隔离演练时 curl http://127.0.0.1:9091/healthz。

Part B · ES kNN 备选 10 指标

若选 Elasticsearch（RAGFlow 等），读 Cluster health、Cluster stats、kNN stats API（/_opendistro/_knn/stats 或 OpenSearch 等价路径）。

Part C · 知识更新状态机

C1. 总览（Dify 知识库 × 向量层）

Dify 文档在 UI/API 侧经历 解析 → 分片 → embedding → 写向量库；Celery dataset 队列由 worker 驱动。向量层（Weaviate/Milvus/ES）只负责最终可检索对象。

stateDiagram-v2
  [*] --> waiting: 上传完成/API入队
  waiting --> parsing: worker领取
  parsing --> cleaning: 解析成功
  parsing --> error: 解析失败
  cleaning --> splitting: 清洗完成
  splitting --> indexing: 分片完成
  indexing --> completed: 向量写入成功\nPG状态+向量库一致
  indexing --> error: embedding/向量写入失败
  error --> retry: 自动重试\n(次数未超限)
  retry --> waiting: 重新入队
  retry --> manual: 超过max_retry\n或不可恢复错误
  manual --> waiting: 运维修复后\nUI/API「重试」
  manual --> completed: 人工修复数据\nre-index成功
  completed --> [*]

C2. 状态说明

C3. 与监控指标的联动

Part D · 恢复演练步骤

详细命令见 作业16_向量恢复演练Runbook_cursor.md。以下以 Milvus 隔离实例 为例（Weaviate/ES 分支在同 Runbook）。

D1. 演练前

1. 隔离目录（同作业15），启用 profile：COMPOSE_PROFILES=...,milvus
2. 创建测试 collection hw16_test 并 insert 少量向量（Attu 或 pymilvus）
3. 按作业15 备份 volumes/milvus/{etcd,minio,milvus} 三目录

D2. 三步演练

① 删测试集合     drop collection hw16_test（或 UI 删除）
② 从备份恢复     停 milvus 栈 → 还原三目录快照 → 启动
③ 抽检查询       hw16_02_恢复演练抽检查询.py --backend milvus --collection hw16_test
                 + Dify 知识库「命中测试」或 Milvus search

D3. 通过标准

• hw16_02 返回 "ok": true 且 num_entities > 0
• milvus_querynode_entity_num（或等价）与演练前数量级一致
• 随机 1 条 hit-testing / search 能返回预期片段

Part E · Cursor：同步失败告警文案

E1. 提示词

为 Dify 知识库索引失败写告警模板：值班群、邮件、工单、P1 升级。
必须包含 dataset_id, document_id, celery task_id, langfuse trace_id, stage, error。
输出 Python 脚本 hw16_01_知识同步失败告警文案.py，写入 data/homework16/。

E2. 运行

python scripts_cursor/作业16_向量监控与知识同步/hw16_01_知识同步失败告警文案.py \
  --dataset-id "YOUR_DS_ID" \
  --document-id "YOUR_DOC_ID" \
  --task-id "celery-uuid-from-worker-log" \
  --trace-id "langfuse-trace-id" \
  --error "weaviate connection refused" \
  --level P2

E3. ID 从哪里取

完整程序

验收清单

• [ ] 写出 Milvus 10 个指标名称与一句含义（或 ES 备选 10 条）
• [ ] 画出知识更新状态机：completed / error / retry / manual 四条出路
• [ ] 说明 indexing 失败时看哪些指标 + 作业15 哪条队列
• [ ] 书面或实操：删 collection → 恢复备份 → hw16_02 spot check 通过
• [ ] 生成告警 MD，且含 task_id + trace_id 占位或真实值
• [ ] 仅在隔离环境做删除/恢复，未动生产 Weaviate

相关文档

• 作业15 备份：作业15_Dify备份清单_cursor.md
• Worker 队列：作业15_值班Runbook_Worker宕机_cursor.md
• Weaviate 中继：Dify_专题六_weaviate中继_cursor
• 知识库变慢：Dify_专题十四_知识库问答变慢卡住失败排查与容量规划_cursor