如何配置Debezium PostgreSQL连接器实现实时数据捕获？

Debezium PostgreSQL连接器是基于PostgreSQL逻辑复制机制构建的变更数据捕获组件，它能够将数据库的插入、更新、删除操作以事件形式推送到Apache Kafka。要使其稳定工作，必须正确理解连接器在复制槽、解码插件和表过滤等方面的配置逻辑。很多连接失败或数据延迟的问题，本质都是配置项之间关系没理清。

逻辑解码与复制槽的基础配置

PostgreSQL本身从9.4版本开始提供逻辑解码功能，Debezium正是利用这一能力，通过复制槽（replication slot）持续读取预写日志（WAL）。在连接器配置中，database.hostname、database.port、database.user和database.password用于建立物理连接，而slot.name则决定了在数据库中创建的复制槽名称。如果多个连接器使用了相同的槽名，后启动的会直接报错，因为PostgreSQL不允许两个活跃消费者共用一个复制槽。

另一个关键参数是plugin.name，它指定了使用的逻辑解码输出插件。常见取值为pgoutput和decoderbufs。前者是PostgreSQL 10以后内置的插件，无需额外安装；后者需要单独编译部署且依赖Protobuf。选择pgoutput时，还需配合publication.name或开启publication.autocreate，因为pgoutput基于Publication机制工作。下面是一段典型的连接器JSON配置片段：

{
  "name": "pg-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname": "192.168.0.1",
    "database.port": "5432",
    "database.user": "debezium",
    "database.password": "dbz_pass",
    "database.dbname": "shop",
    "database.server.name": "shopdb",
    "slot.name": "shop_slot",
    "plugin.name": "pgoutput",
    "publication.autocreate": true,
    "schema.include.list": "public"
  }
}

当连接器首次启动时，若publication.autocreate为true，它会在PostgreSQL中自动执行创建Publication的语句，将所有指定schema下的表纳入捕获范围。若关闭该选项，则必须提前手动创建Publication并关联表，否则连接器只能读到空事件流。这种自动与手动的差别，在多人协作环境里容易引发权限问题，因为创建Publication需要超级用户或具备相应授权的角色。

表与模式过滤的精细化控制

默认情况下，Debezium会捕获database下所有带主键的表，这在大型系统中会产生大量无关事件。通过schema.include.list和table.include.list可以缩小范围。例如只关心订单与用户表时，可写成table.include.list": "public.orders,public.users"。与之相对的是table.exclude.list，用于剔除特定表。两者同时存在时，排除规则优先于包含规则，这是配置时容易忽略的细节点。

除了静态过滤，Debezium还提供column.exclude.list来屏蔽敏感字段，比如密码列或身份证号。被排除的列不会出现在事件消息里，从源头降低数据泄露风险。要注意的是，若某张表没有任何列被保留，连接器会跳过整张表的变更。以下示例展示如何只同步订单表且隐藏其中的备注字段：

{
  "name": "pg-order-only",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname": "127.0.0.1",
    "database.port": "5432",
    "database.user": "debezium",
    "database.password": "dbz_pass",
    "database.dbname": "shop",
    "database.server.name": "shopdb",
    "slot.name": "order_slot",
    "plugin.name": "pgoutput",
    "table.include.list": "public.orders",
    "column.exclude.list": "public.orders.remark"
  }
}

在过滤配置生效后，Kafka中对应的topic命名规则为serverName.schemaName.tableName。如果database.server.name设置得过于宽泛，比如直接写主机名，会导致topic前缀杂乱。建议在初期规划时就使用业务语义明确的短名称，方便下游消费者订阅。同时，过滤规则修改后需要重启连接器才能生效，运行时动态调整并不被支持。

心跳、偏移与WAL堆积治理

逻辑解码最让人头疼的是WAL文件无法被数据库回收，因为复制槽会认为旧日志仍有未消费事件。Debezium提供heartbeat.interval.ms参数，定期向database.server.name对应的心跳topic写入消息，推动确认位点前进。若消费者长时间离线，WAL会持续膨胀直至磁盘写满。因此生产环境务必监控pg_replication_slots视图中的restart_lsn延迟。

另一个相关参数是slot.drop.on.stop，默认false。当连接器被永久删除时，若未手动在数据库执行SELECT pg_drop_replication_slot('slot_name');，槽会一直残留。对于测试环境可开启该选项自动清理，但生产环境应保持false以防误删导致数据断流。此外，snapshot.mode控制首次启动时的全量快照方式，initial会先扫全表再跟增量，而never则只捕获配置后的新变更，适合已通过其他手段同步历史的场景。

-- 查看当前复制槽状态与延迟
SELECT slot_name,
       active,
       pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS lag_bytes
FROM pg_replication_slots;

偏移量存储方面，Kafka Connect自身用内部topic保存连接器offset，Debezium在此基础上依赖复制槽位点。如果手动重置了Connect的offset但槽未变，会造成事件重复或丢失。因此排障时要把数据库槽状态与Connect消费组位移联合分析。通过合理设置心跳间隔、监控槽延迟以及规范快照模式，才能让PostgreSQL连接器长期稳定运行而不拖累主库性能。

DebeziumPostgreSQLCDC修改时间：2026-08-16 22:24:33