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 需要满足的运行状态

```bash
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，导致消费端无数据。

### 指令

```bash
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 转义复杂度。

### 指令

```bash
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 实际收到消息并执行日志打印。

### 指令（回看最近日志）

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

### 指令（实时追踪）

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

### 预期日志示例

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

说明：

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

---

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

### 目的

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

### 指令

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

### 目的

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

### 指令

```bash
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

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

浏览器：`http://localhost:3000`

### 6.2 在 Explore 中查询

使用 Loki 数据源，输入：

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

若没有结果：

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

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

---

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

```bash
# 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`