快照模式是什么
Debezium 连接器首次启动时，面对一张已经有数据的表必须先解决「历史数据怎么办」，snapshot.mode 就是这个开关。默认的 initial 会先做一次一致性全量快照、再无缝切到位点做增量；其余模式则是为了避开全量这一步或修复元数据历史。模式选错的后果很直接：要么目标端永远缺历史数据，要么每次都重新拉一遍全量。
基本信息
| 适用平台 | Debezium（Kafka Connect 或嵌入式）MySQL、PostgreSQL 等连接器 |
|---|---|
| 默认值 | initial，全量快照后转增量 |
| 相关参数 | snapshot.mode、snapshot.locking.mode、snapshot.fetch.size |
| 状态存储 | schema 历史主题与位点主题，重启依赖它们 |
| 观测方式 | 连接器状态、快照阶段的日志与任务指标 |
常用模式怎么选
| 模式 | 行为 | 典型场景 |
|---|---|---|
| initial | 全量快照 + 继续增量 | 首次接入新链路 |
| schema_only | 只快照结构，从当前位点继续 | 已有全量基线，只需要增量 |
| initial_only | 只做快照，不进入增量 | 一次性导出 |
| schema_only_recovery | 只快照结构并重置历史记录 | schema 历史主题损坏后恢复 |
| when_needed | 仅在必要时快照 | 需要自动化处理位点异常的链路 |
连接器配置片段
连接器配置片段
{
"name": "mysql-orders-connector",
"config": {
"connector.class": "io.debezium.connector.mysql.MySqlConnector",
"database.hostname": "10.0.0.5",
"database.server.id": "184054",
"database.server.name": "app",
"table.include.list": "app.orders",
"snapshot.mode": "initial",
"snapshot.locking.mode": "minimal"
}
}典型使用场景
- 新接入一张业务表：用 initial 一次拿到全量基线，之后自动接增量
- 已用离线任务补过全量：用 schema_only 避免再拉一遍历史
- 只做一次性导出：用 initial_only 拿到快照后不占用增量资源
- 元数据主题损坏：用 schema_only_recovery 重建结构信息后继续
- 重建链路：先停连接器、清理目标端与位点，再按目标语义选择模式重跑
schema_only 跳过数据快照：目标端没有全量基线时用它，历史数据永远不会进管道。
快照期间的锁行为由 snapshot.locking.mode 控制，较新版本默认使用更轻量的加锁方式；扩容期、大表接入前仍应确认版本与默认值，并在业务低峰执行首次快照。