Debezium 故障排查

内容：现象 -> 原因 -> 排查 -> 解决

重点覆盖 PostgreSQL + Kafka + Debezium 的真实故障。

一、定位总图

数据库写入
  ↓
WAL / binlog
  ↓        ←① DB 问题？
Debezium Connector
  ↓        ←② Connector 问题？
Kafka Topic
  ↓        ←③ Kafka 问题？
Consumer
           ←④ 下游慢？

第一原则：

👉 不要一上来就重启 Debezium

二、Debezium 常见故障总览

现象	最可能原因
数据不再同步	Slot / binlog 中断
延迟越来越大	下游慢 / Kafka backlog
PG 磁盘爆满	Slot 堆积 WAL
Connector FAILED	schema / 权限 / DDL
重启后数据重复	at-least-once 正常现象
Snapshot 卡住	大表 / 锁 / IO

三、PostgreSQL 相关故障（最致命）

1️⃣ WAL 无限增长（高危）

现象

PG 磁盘暴涨
pg_wal 目录巨大
DB 变慢甚至只读

原因

Debezium 停止
Replication Slot 没消费
PG 不敢删除 WAL

排查

SELECT
  slot_name,
  active,
  pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS lag
FROM pg_replication_slots;

解决

⚠️ 会丢 CDC 数据，谨慎

SELECT pg_drop_replication_slot('debezium_slot');

👉 正确做法

先恢复 Debezium
再确认 slot 消费

2️⃣ Debezium 启动失败（PG）

现象

Connector FAILED
日志有：
permission denied
logical decoding requires wal_level=logical

排查清单

wal_level = logical
max_replication_slots >= 1
max_wal_senders >= 1

-- 用户权限
ALTER ROLE debezium WITH REPLICATION;

3️⃣ 表 update/delete 不生效

现象

insert 有
update / delete 没事件

原因

表没有 Primary Key

解决

ALTER TABLE xxx ADD PRIMARY KEY (id);

四、Snapshot 相关故障

4️⃣ Snapshot 卡住 / 极慢

现象

op=r 持续很久
Kafka 流量暴涨
DB IO 飙升

排查

表行数是否巨大
是否全表 snapshot
是否业务高峰期

解决

snapshot.mode=when_needed
snapshot.fetch.size=1000

👉 大表

分表
离线导一次
CDC 只跑增量

5️⃣ Snapshot 后数据重复

原因

snapshot + WAL 本身就会重复一次边界数据
Debezium 语义正常

正确处理

下游幂等 upsert
以主键覆盖

五、Kafka / Connect 层故障

6️⃣ Connector 状态 FAILED

排查顺序

GET /connectors
GET /connectors/{name}/status

看：

connector
task
trace

常见原因

Kafka Topic 不存在
Schema 不兼容
transform 配置错误
DDL 解析失败

7️⃣ Kafka Topic Lag 越来越大

原因

Consumer 慢
Kafka 分区太少
磁盘 / 网络瓶颈

排查

kafka-consumer-groups.sh --describe

六、数据问题（最容易误判）

8️⃣ 数据重复（最常见误会）

原因

Debezium 是 at-least-once
重启 / rebalance 都可能重复

正确姿势

主键作为 key
下游 upsert

👉 不是 bug

9️⃣ 数据乱序

原因

多分区
多表

事实

单 key 顺序保证
跨 key / 跨表 ❌

七、DDL / Schema 问题

🔟 表结构变更后 Connector 挂掉

原因

不兼容 DDL
字段类型 Debezium 不支持

解决

include.schema.changes=false

或：

停 Debezium
改表
重启

八、日志排查关键点（必看）

Debezium 日志重点关键词

FAILED
WARN
replication slot
offset
unable to parse
out of memory

Kafka Connect 内部 Topic

Topic	作用
connect-offsets	读到哪
connect-status	状态
connect-configs	配置

九、故障排查 SOP（记住这个）

Connector 状态？
Task 状态？
Slot 是否 active？
WAL 是否堆积？
Kafka lag？
Consumer 是否慢？

十、生产级“保命清单”

✅ 监控 replication slot
✅ 监控 pg_wal 磁盘
✅ Consumer 幂等
✅ Snapshot 避开高峰
✅ Connector 自动重启
✅ Topic 磁盘容量规划

十一、总结

Debezium 出问题，80% 是 Slot / Snapshot / Consumer，不是 Debezium 本身。