juwan-backend/docs/email-kafka-consumer-test-guide.md

Email Consumer Kafka 投递与日志验证实验手册

1. 实验目标

验证 email-task consumer 是否能正常消费 Kafka 消息，并在日志中打印消费内容。

本实验同时给出两种验证方式：

1. kubectl logs 直接查看 Pod 日志
2. Grafana + Loki 查看聚合日志

---

2. 实验前提

2.1 需要满足的运行状态

kubectl -n juwan get pods -l app=email-task
kubectl -n kafka get pods
kubectl -n monitoring get pods

预期：

• email-task 至少 1 个 Pod 为 Running
• Kafka 集群有可用 broker（如 my-cluster-kafka-pool-0）
• loki/promtail/grafana 为 Running（若需要 Loki 验证）

2.2 本次实验使用的关键配置

来自 app/email/mq/etc/email.yaml：

• Broker: my-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092
• Topic: email-task
• Group: email-consumer-group

---

3. 实验步骤（详细）

步骤 1：确认 Topic 存在

目的

避免消息投递到不存在的 Topic，导致消费端无数据。

指令

kubectl -n kafka exec my-cluster-kafka-pool-0 -- \
  /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server my-cluster-kafka-bootstrap:9092 \
  --list

预期结果

输出中包含：

• email-task

---

步骤 2：投递一条最小测试消息（纯文本）

目的

先验证链路通路（producer -> kafka -> consumer）是否正常，不引入 JSON 转义复杂度。

指令

kubectl -n kafka exec my-cluster-kafka-pool-0 -- /bin/bash -lc \
"printf 'test-email-message\\n' | \
/opt/kafka/bin/kafka-console-producer.sh \
--bootstrap-server my-cluster-kafka-bootstrap:9092 \
--topic email-task"

预期结果

命令正常返回（通常无额外输出）。

---

步骤 3：查看 consumer 日志（kubectl 直查）

目的

确认 consumer 实际收到消息并执行日志打印。

指令（回看最近日志）

kubectl -n juwan logs -l app=email-task --tail=120

指令（实时追踪）

kubectl -n juwan logs -l app=email-task -f --since=10m

预期日志示例

Consume get message key: , value: test-email-message

说明：

• key 为空是正常的（本次 producer 未设置 key）
• value 为投递内容，说明消费链路正常

---

步骤 4：投递业务消息（验证码 JSON）

目的

模拟真实业务 payload，验证 consumer 对业务消息格式的处理。

指令

kubectl -n kafka exec my-cluster-kafka-pool-0 -- /bin/bash -lc "cat <<'EOF' | \
/opt/kafka/bin/kafka-console-producer.sh \
--bootstrap-server my-cluster-kafka-bootstrap:9092 \
--topic email-task
{\"type\":\"verification_code\",\"email\":\"test@example.com\",\"code\":\"123456\",\"scene\":\"login\",\"expired_minutes\":5}
EOF"

预期结果

• producer 正常返回
• email-task 日志可看到包含 JSON 的消费日志

---

步骤 5：投递业务消息（活动通知 JSON）

目的

验证另一类业务消息（活动通知）通路。

指令

kubectl -n kafka exec my-cluster-kafka-pool-0 -- /bin/bash -lc "cat <<'EOF' | \
/opt/kafka/bin/kafka-console-producer.sh \
--bootstrap-server my-cluster-kafka-bootstrap:9092 \
--topic email-task
{\"type\":\"activity_notice\",\"email\":\"test@example.com\",\"title\":\"春季活动\",\"content\":\"满100减20\",\"activity_id\":\"A20260225\"}
EOF"

预期结果

• producer 正常返回
• consumer 日志出现活动消息内容

---

步骤 6：使用 Loki/Grafana 验证（可选）

目的

确认日志采集链路（Promtail -> Loki -> Grafana）正常，便于后续线上排查。

6.1 打开 Grafana

kubectl port-forward -n monitoring svc/grafana 3000:3000

浏览器：http://localhost:3000

6.2 在 Explore 中查询

使用 Loki 数据源，输入：

{job="kubernetes-pods", namespace="juwan", app="email-task"} |= "Consume get message"

若没有结果：

1. 把时间范围调大到 Last 6 hours/Last 24 hours
2. 放宽查询条件：

{job="kubernetes-pods", namespace="juwan", pod=~"email-task-.*"}

---

4. 一键复现实验命令（顺序执行）

# 1) 查看 topic
kubectl -n kafka exec my-cluster-kafka-pool-0 -- /opt/kafka/bin/kafka-topics.sh --bootstrap-server my-cluster-kafka-bootstrap:9092 --list

# 2) 发测试消息
kubectl -n kafka exec my-cluster-kafka-pool-0 -- /bin/bash -lc "printf 'test-email-message\\n' | /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server my-cluster-kafka-bootstrap:9092 --topic email-task"

# 3) 看 consumer 日志
kubectl -n juwan logs -l app=email-task --tail=120

---

5. 常见问题与处理

问题 1：发消息命令报引号/EOF错误

现象：unexpected EOF while looking for matching。

原因：Shell 引号转义不正确。

处理：

• 先用纯文本消息验证链路
• JSON 使用 here-doc（cat <<'EOF'）方式，避免转义混乱

问题 2：发了消息但 consumer 无日志

排查顺序：

1. email-task 是否 Running
2. Topic 是否正确（email-task）
3. consumer group 是否一致（email-consumer-group）
4. 查看 Pod 实时日志（-f）
5. 若只看 Loki，请放大时间窗口并放宽标签条件

问题 3：Loki 查不到但 kubectl logs 能看到

说明业务正常，问题在日志采集查询链路：

• 检查 Promtail target 是否 ready
• 检查 Loki 查询标签/时间范围
• 参考 docs/loki-log-troubleshooting.md

---

6. 实验结论判定标准

满足以下任一即可判定消费链路可用：

1. kubectl logs 出现：Consume get message ...
2. Grafana Loki 查询出现对应消费日志

若两者都出现，说明：

• Kafka 投递正常
• Consumer 消费正常
• 日志采集与检索链路正常

---

7. 关联文档

• Loki 使用：docs/loki-usage-guide.md
• Loki 排错：docs/loki-log-troubleshooting.md
• Email 部署排错：docs/email-task-deployment-troubleshooting.md