add: anowflake email kafka, refa: redis connectg

2026-02-25 01:16:13 +08:00
parent fdbcde13b2
commit 300058ad01
67 changed files with 3596 additions and 139 deletions
@@ -0,0 +1,266 @@
+# 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`