Skip to content

CDC 组件配置说明(JDK11 / Debezium 2.7 版) ​

适用于 kettle_plugins_jdk11 下的四个 CDC 输入插件,以及 Web 设计器(web-etl-ui-vue3)中对应的四个组件。

插件模块Web 设计器组件名Debezium 连接器版本捕获机制
mysql-cdc-input-kettleMYSQL CDC2.7.4.Finalbinlog
pg-cdc-input-kettlePG CDC2.7.0.Final逻辑复制(pgoutput)
oracle-cdc-input-kettleOracle CDC2.7.0.FinalLogMiner
sqlserver-cdc-input-kettleMSSQL CDC2.7.0.FinalCDC 变更表 + Agent

一、配置总流程 ​

CDC 与普通输入组件最大的区别是:大部分工作在数据库侧,不在页面上。数据库没开好,页面配得再对也是 0 行输出。建议严格按顺序做:

  1. 数据库侧开功能:开日志(binlog / wal_level / ARCHIVELOG / CDC 变更表),逐库逐表启用(SQL Server、Oracle 补充日志)。
  2. 数据库侧建账号授权:CDC 账号权限和普通查询账号不同,必须额外给复制/日志读取类权限。
  3. 建 Kettle 数据库连接:在 Web 设计器的数据源里配好连接,CDC 组件从连接中取 host/port/user/password。
  4. 页面配置组件字段:Server Name、包含表、快照模式、偏移量文件等。
  5. 首次运行看日志:日志里会打印全部 Debezium 参数和前置检查结果,出问题先看这段。

二、通用配置说明(四个组件共有) ​

2.1 组件输出字段 ​

四个组件的默认输出字段完全一致,共 6 个:

字段名Kettle 类型内容说明
operationStringc / u / d / rc=新增,u=更新,d=删除,r=快照阶段读出的存量数据
database_nameString库名来自变更事件的 source.db
table_nameString表名来自变更事件的 source.table,不含 schema
before_dataStringJSON变更前整行数据;c 和 r 事件为 null
after_dataStringJSON变更后整行数据;d 事件为 null
timestampDate事件时间来自 source.ts_ms

下游要拿具体列值,需要接一个 JSON Input 之类的组件解析 after_data / before_data,不能直接当列用。

判断增删改时注意用 operation 的单字母值(c/u/d/r),不是 INSERT/UPDATE/DELETE。

2.2 快照模式(snapshotMode) ​

各连接器合法值不同,这是最容易踩的坑。页面下拉框已按连接器限制为下面这些值,选项旁会显示中文说明:

模式含义MySQLPGOracleSQL Server
initial无偏移量时做一次全量快照(结构+数据),之后只读增量;已有偏移量则直接续读✅ 默认✅ 默认✅ 默认✅ 默认
when_needed仅当无偏移量、或偏移量对应的日志位置已不可用时,重做全量快照✅✅✅✅
no_data只取表结构,不读存量数据,从当前日志位置开始增量(旧版 schema_only 的新名)✅✅✅✅
never不做任何快照,直接从当前日志位置流式读取,要求 schema 历史文件已存在✅⚠️ 废弃别名❌❌
initial_only做完全量快照就停止,不进入增量阶段✅✅✅✅
always每次启动都重做全量快照(会重复产出存量数据,慎用)✅✅✅✅
recovery丢弃并根据当前表结构重建 schema 历史文件(旧版 schema_only_recovery 的新名)✅❌✅✅

几个必须知道的点:

  • schema_only / schema_only_recovery 是 Debezium 2.6 之前的旧名,2.7 已废弃,页面不再提供。旧任务里的这些值,打开配置页时会自动折算为 no_data / recovery,插件运行时也会兜底折算,不会再报 snapshot.mode value is invalid。
  • PG 的 never 在 2.7 引擎里仍能通过校验,但已是 no_data 的废弃别名,页面已移除,选 no_data 即可。
  • MySQL 选 never 时,如果 schema 历史文件不存在,插件会自动降级为 no_data,避免启动失败。
  • 首次跑只想验证链路、不想拉存量数据 → 选 no_data。
  • 要做一次存量+增量的完整同步 → 选 initial。
  • 不要用 always 做常规任务,每次重启都会把全表数据重新灌一遍。

2.3 偏移量文件与历史文件 ​

字段作用删除后果
偏移量存储文件记录已读到的日志位置(binlog 位点 / WAL LSN / SCN / LSN)下次启动按快照模式从头开始
历史文件记录表结构变更历史(schema history)可能报找不到 schema 历史,需配合 recovery 模式重建

存放位置规则(四个插件一致):

  • 只填文件名,如 pg-cdc-offset.dat → 实际落到运行目录下的 cdc-dat\pg-cdc-offset.dat,目录自动创建。
  • 填了带 / 或 \ 的路径,如 cdc-dat/pg-kettle/pg-cdc-offset.dat → 原样使用,父目录自动创建。

推荐第二种写法:按任务(Server Name)分子目录,例如 cdc-dat/pg-kettle/pg-cdc-offset.dat。当前服务端 data-center\cdc-dat\ 下就是这种结构。

两个任务绝对不能共用同一个偏移量文件或历史文件,否则位点互相覆盖,表现为丢数据或重复消费。运行中还会生成 .dat.lock 锁文件,共用会直接抢锁失败。

重置采集位置的办法:停任务 → 删掉该任务的 .dat、.dat.lock 文件 → 按需选快照模式 → 重启。

2.4 Server Name ​

Debezium 的逻辑服务器名(database.server.name),是这个采集任务的身份标识。

  • 同一个库上的多个 CDC 任务必须用不同的 Server Name。
  • 改了 Server Name 等于换了一个新任务,历史偏移量失效,会按快照模式从头采集。任务上线后不要随便改。
  • 默认值:mysql-kettle / pg-kettle / oracle-server-kettle / sqlserver-kettle。

2.5 包含表(tableIncludeList) ​

格式因库而异,格式错了不会报错,只会一直 0 行输出,这是最难排查的问题:

组件格式正确示例常见错误
MYSQL CDC库名.表名test.users,test.orders只写 users
PG CDCschema.表名public.users,public.T_MATERIAL只写 users;漏掉 public.
Oracle CDC用户名.表名(大写)SCOTT.EMP,SCOTT.DEPT写成小写
MSSQL CDCschema.表名dbo.users,guest.t_table把库名当 schema 填
  • 多个表用英文逗号分隔,不要加空格。
  • 大小写必须与数据库中实际存储的一致(Oracle 默认全大写,PG 默认全小写,建表时加了引号的大写表名要照原样写)。
  • 留空的行为:MySQL/SQL Server 会监听库内所有表;不建议留空,会白采大量无关表。

2.6 包含Schema变更(includeSchemaChanges) ​

勾选后,DDL(建表、加字段等)也会作为事件输出到下游。只做数据同步时不要勾,勾了下游会收到无法解析的 schema 事件行。PG 组件没有这个开关。


三、MySQL CDC ​

3.1 数据库侧操作 ​

① 确认 binlog 参数(MySQL 8.0+ 默认已开 binlog):

sql
SHOW VARIABLES WHERE Variable_name IN (
  'log_bin', 'binlog_format', 'binlog_row_image', 'server_id'
);
参数必需值不满足的后果
log_binON完全无法采集
binlog_formatROWSTATEMENT/MIXED 解析不出行级前后镜像
binlog_row_imageFULLbefore_data 只有主键列
server_id非 0开 binlog 的前提

不满足时改 my.cnf / my.ini 的 [mysqld] 段后重启 MySQL:

ini
[mysqld]
server-id = 223344
log_bin = mysql-bin
binlog_format = ROW
binlog_row_image = FULL
# binlog 保留时长,建议 >= 7 天,避免任务停机期间位点失效
binlog_expire_logs_seconds = 604800

binlog_format、binlog_row_image 虽可 SET GLOBAL 动态改,但只影响新建连接,生产环境请改配置文件后重启。

② binlog 保留时间:必须大于任务可能的最长停机时间。位点过期后重启会报位点不可用,此时只能用 when_needed 重做快照。

3.2 账号权限 ​

sql
CREATE USER 'dbzuser'@'%' IDENTIFIED BY 'dbzuser';

GRANT SELECT, RELOAD, SHOW DATABASES,
      REPLICATION SLAVE, REPLICATION CLIENT
  ON *.* TO 'dbzuser'@'%';

FLUSH PRIVILEGES;
SHOW GRANTS FOR 'dbzuser'@'%';
权限用途是否必需
REPLICATION SLAVE以从库身份读 binlog 流必需,缺失则收不到任何事件
REPLICATION CLIENT查 SHOW MASTER STATUS 取当前位点必需
SELECT快照读表数据、读表结构必需(no_data 模式也要读结构)
RELOAD快照时 FLUSH TABLES必需
SHOW DATABASES枚举库列表必需
LOCK TABLES快照加表锁不需要,插件已设 snapshot.locking.mode=none

插件已默认设置 database.allowPublicKeyRetrieval=true、database.useSSL=false,一般不会遇到 8.0 密码插件报错。仍失败时可改认证方式: ALTER USER 'dbzuser'@'%' IDENTIFIED WITH mysql_native_password BY 'dbzuser';

3.3 前端配置 ​

字段必填填什么Debezium 属性
数据库连接✅选已建好的 MySQL 数据源database.hostname/port/user/password
Server ID⚠️复制拓扑内唯一的数字,如 5400。页面不强制校验,但引擎必需,留空会启动失败database.server.id
Server Name✅任务逻辑名,如 mysql-kettledatabase.server.name
快照模式✅见 2.2 节snapshot.mode
包含Schema变更只同步数据时不勾include.schema.changes
偏移量存储文件✅如 cdc-dat/mysql-kettle/mysql-cdc-offset.datoffset.storage.file.filename
历史文件✅如 cdc-dat/mysql-kettle/mysql-cdc-history.datschema.history.internal.file.filename
包含数据库库名,多个用逗号,如 test,order_db;留空监听所有库database.include.list
包含表库名.表名,如 test.userstable.include.list

Server ID 是 MySQL 独有的高风险字段:Debezium 是以「MySQL 从库」身份连上去的,这个 ID 不能与 MySQL 自身 server_id、真实从库、其他 CDC 任务重复。

sql
-- 查看已连接的从库(含其他 Debezium 实例)
SHOW REPLICAS;      -- MySQL 8.0.22+
SHOW SLAVE HOSTS;   -- 8.0.22 之前

冲突的表现是两个任务互相踢下线、反复重连(A slave with the same server_uuid/server_id ... has connected)。建议每个任务分配独立值,如 5401、5402。

3.4 检查清单 ​

#检查项期望
1SHOW VARIABLES LIKE 'log_bin';ON
2SHOW VARIABLES LIKE 'binlog_format';ROW
3SHOW VARIABLES LIKE 'binlog_row_image';FULL
4SHOW GRANTS FOR 'dbzuser'@'%';含 REPLICATION SLAVE
5页面 Server ID全局唯一、非 1
6页面「包含表」格式库名.表名

四、PostgreSQL CDC ​

4.1 数据库侧操作 ​

① 开逻辑解码(需重启 PG):

sql
SHOW wal_level;                          -- 默认通常是 replica
ALTER SYSTEM SET wal_level = 'logical';  -- 改完必须重启 PG

重启后验证 SHOW wal_level; 返回 logical。

② 确认复制槽额度:

sql
SHOW max_replication_slots;  -- 建议 >= 4
SHOW max_wal_senders;        -- 建议 >= 4

③ 手动创建 Replication Slot(页面「自动创建Replication Slot」不勾时必须做):

sql
SELECT pg_create_logical_replication_slot('debezium_slot', 'pgoutput');

-- 验证:plugin 必须是 pgoutput,slot_type 必须是 logical
SELECT slot_name, plugin, slot_type, active FROM pg_replication_slots;

插件启动时会用 JDBC 主动检查这个槽,槽不存在会直接初始化失败并终止(日志:错误:找不到Replication Slot: xxx),不会带着错误继续跑。

④ Publication:插件会检查,不存在时自动执行 CREATE PUBLICATION <名称> FOR ALL TABLES。

sql
-- 手动创建(推荐,见下方权限说明)
CREATE PUBLICATION dbz_publication FOR ALL TABLES;

-- 或只发布指定表
CREATE PUBLICATION dbz_publication FOR TABLE public.users, public.orders;

SELECT pubname, puballtables FROM pg_publication;

4.2 账号权限 ​

sql
-- 复制权限(读 WAL 必需)
ALTER ROLE dbzuser REPLICATION;

-- 表读取权限(快照阶段需要)
GRANT USAGE ON SCHEMA public TO dbzuser;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dbzuser;

-- 验证
SELECT rolname, rolreplication, rolsuper FROM pg_roles WHERE rolname = 'dbzuser';
操作所需权限
读 WAL 流角色的 REPLICATION 属性(或超级用户)
创建 replication slot同上
快照读数据对表的 SELECT + schema 的 USAGE
CREATE PUBLICATION ... FOR ALL TABLES必须是超级用户
CREATE PUBLICATION ... FOR TABLE ...是这些表的 owner 即可

重要:插件自动创建 publication 用的是 FOR ALL TABLES,PostgreSQL 要求该操作必须由超级用户执行。如果 CDC 账号不是超级用户(生产环境通常不是),请提前手动建好 publication,插件检查到已存在就不会尝试创建。

逻辑复制连接匹配 pg_hba.conf 里的普通数据库条目,不需要额外添加 replication 关键字的行;只要该账号能正常连这个库,加上 REPLICATION 属性即可。

4.3 前端配置 ​

字段必填填什么Debezium 属性
数据库连接✅选已建好的 PG 数据源database.hostname/port/user/password
Slot Name✅小写字母、数字、下划线,如 debezium_slotslot.name
Server Name✅任务逻辑名,如 pg-kettledatabase.server.name
Publication✅如 dbz_publicationpublication.name
快照模式✅见 2.2 节(PG 无 recovery)snapshot.mode
自动创建Replication Slot不勾则必须先手动建槽slot.auto.create
停止时删除Slot生产环境不要勾slot.drop.on.stop
偏移量存储文件✅如 cdc-dat/pg-kettle/pg-cdc-offset.datoffset.storage.file.filename
历史文件✅如 cdc-dat/pg-kettle/pg-cdc-history.datschema.history.internal.file.filename
包含表schema.表名,如 public.userstable.include.list

两个复选框的取舍:

  • 停止时删除Slot:勾选后任务一停槽就被删,停机期间的所有变更全部丢失,下次启动等于重新开始。生产环境不要勾。
  • 但不勾也有代价:槽会一直持有 WAL,任务长期不跑会让 WAL 无限堆积,最终撑满磁盘。长期停用的任务请手动删槽:
sql
-- 查看槽的 WAL 堆积量
SELECT slot_name, active, pg_size_pretty(
  pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
FROM pg_replication_slots;

-- 确认不再需要后删除
SELECT pg_drop_replication_slot('debezium_slot');

4.4 检查清单 ​

#检查项期望
1SHOW wal_level;logical
2SELECT slot_name, plugin FROM pg_replication_slots;槽存在且 plugin=pgoutput
3SELECT pubname FROM pg_publication;publication 存在
4SELECT rolreplication FROM pg_roles WHERE rolname='dbzuser';t
5页面「包含表」格式schema.表名(如 public.T_MATERIAL)
6页面槽名与库中一致完全一致

五、Oracle CDC ​

Oracle 用 LogMiner 读 redo/归档日志。CDB/PDB 架构下 LogMiner 只能在 CDB$ROOT 中运行,这决定了连接必须连 CDB 根,是 Oracle CDC 最核心的一条。

5.1 数据库侧操作 ​

① 确认架构:

sql
-- 以 SYSDBA 连接
SHOW CON_NAME;                                  -- 显示 CDB$ROOT 说明是 CDB/PDB 架构
SELECT PDB_ID, PDB_NAME, STATUS FROM DBA_PDBS;  -- 查看所有 PDB

② 开归档日志模式(LogMiner 硬性要求,需停库):

sql
SELECT LOG_MODE FROM V$DATABASE;   -- NOARCHIVELOG 则需开启

SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;

SELECT LOG_MODE FROM V$DATABASE;   -- 应为 ARCHIVELOG

③ 开补充日志(不开则 before_data/after_data 为 null):

sql
-- 在 CDB$ROOT 中执行
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

SELECT SUPPLEMENTAL_LOG_DATA_MIN, SUPPLEMENTAL_LOG_DATA_ALL FROM V$DATABASE;
-- 应为 YES  YES

只想精细控制到表级别(推荐生产环境用法):

sql
ALTER SESSION SET CONTAINER = ORCLPDB;
ALTER TABLE SCOTT.EMP ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

④ 归档日志空间:CDC 会持续读归档日志,务必确认 db_recovery_file_dest_size 足够且有归档清理策略,否则归档区写满会导致整个数据库挂起。

5.2 账号权限 ​

CDB/PDB 架构下必须用 Common User(跨容器用户)。

测试环境(图省事):

sql
-- 在 CDB$ROOT 中执行
CREATE USER C##DBZUSER IDENTIFIED BY "dbzuser" CONTAINER=ALL;
GRANT DBA TO C##DBZUSER CONTAINER=ALL;

生产环境最小权限(替代 DBA):

sql
GRANT CREATE SESSION TO C##DBZUSER CONTAINER=ALL;
GRANT SET CONTAINER TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$DATABASE TO C##DBZUSER CONTAINER=ALL;
GRANT FLASHBACK ANY TABLE TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ANY TABLE TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT_CATALOG_ROLE TO C##DBZUSER CONTAINER=ALL;
GRANT EXECUTE_CATALOG_ROLE TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ANY TRANSACTION TO C##DBZUSER CONTAINER=ALL;
GRANT LOGMINING TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$LOG TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$LOG_HISTORY TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_LOGS TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_CONTENTS TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$LOGFILE TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVED_LOG TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO C##DBZUSER CONTAINER=ALL;
GRANT SELECT ON V_$TRANSACTION TO C##DBZUSER CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR TO C##DBZUSER CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR_D TO C##DBZUSER CONTAINER=ALL;

报 ORA-65096: invalid common user or role name 是因为没用 C## 前缀。测试环境可绕过: ALTER SESSION SET "_ORACLE_SCRIPT"=TRUE; 之后再建不带前缀的用户。

5.3 前端配置 ​

字段必填填什么Debezium 属性
数据库连接✅数据源的 JDBC URL 必须连 CDB 根,如 jdbc:oracle:thin:@//1.2.3.4:1521/ORCLdatabase.url
Server Name✅任务逻辑名,如 oracle-server-kettledatabase.server.name
快照模式✅见 2.2 节snapshot.mode
包含Schema变更只同步数据时不勾include.schema.changes
偏移量存储文件✅如 cdc-dat/oracle-server-kettle/oracle-cdc-offset.datoffset.storage.file.filename
历史文件✅如 cdc-dat/oracle-server-kettle/oracle-cdc-history.datschema.history.internal.file.filename
包含数据库填 PDB 名称,如 ORCLPDB1;非 CDB 实例留空database.pdb.name
包含表用户名.表名,大写,如 SCOTT.EMPtable.include.list

Oracle 的两个专属陷阱:

  1. 数据源 URL 必须连 CDB 根服务(如 /ORCL),连了 PDB(如 /ORCLPDB1)会报 ORA-65040: 不允许从插接式数据库内部执行该操作。确认 CDB 服务名:SELECT NAME FROM V$DATABASE; 或 lsnrctl status。
  2. 「包含数据库」这个字段填的不是普通库名,而是 PDB 名称(映射到 database.pdb.name)。传统非 CDB 实例必须留空,填了反而连不上。

5.4 检查清单 ​

#检查项期望
1SELECT LOG_MODE FROM V$DATABASE;ARCHIVELOG
2SELECT SUPPLEMENTAL_LOG_DATA_MIN FROM V$DATABASE;YES
3账号存在且是 Common UserC## 前缀或 CONTAINER=ALL
4数据源 URL 服务名CDB 根(如 /ORCL),不是 PDB
5页面「包含数据库」PDB 名(如 ORCLPDB1),非 CDB 实例留空
6页面「包含表」SCHEMA.表名,大写

六、SQL Server CDC ​

SQL Server 是四种库里准备工作最繁琐的:需要 Agent 服务 + 逐库启用 + 逐表启用,三者缺一都收不到数据。

6.1 数据库侧操作 ​

① 确认 SQL Server Agent 正在运行(CDC 靠 Agent Job 抓变更,Agent 不跑则完全不工作):

sql
EXEC xp_servicecontrol 'QueryState', 'SQLServerAgent';   -- 期望 Running
EXEC xp_servicecontrol 'Start', 'SQLServerAgent';        -- 未运行时启动

Docker 环境的 SQL Server 容器默认不启动 Agent,需要设置环境变量 MSSQL_AGENT_ENABLED=True。

② 库级启用 CDC:

sql
USE test;
GO
SELECT name, is_cdc_enabled FROM sys.databases WHERE name = 'test';
EXEC sys.sp_cdc_enable_db;      -- is_cdc_enabled = 0 时执行
GO

③ 表级启用 CDC(每张表都要单独执行):

sql
USE test;
GO
SELECT name, is_tracked_by_cdc FROM sys.tables WHERE name = 'users';

EXEC sys.sp_cdc_enable_table
    @source_schema = N'dbo',      -- schema 名,不是库名
    @source_name   = N'users',    -- 表名
    @role_name     = NULL,        -- NULL = 不限制访问角色
    @supports_net_changes = 1;
GO

④ 确认 Agent Job 已创建并启用:

sql
SELECT name, enabled FROM msdb.dbo.sysjobs WHERE name LIKE 'cdc%';
-- 应有 cdc.test_capture 和 cdc.test_cleanup,且 enabled = 1

-- enabled = 0 时启用
EXEC msdb.dbo.sp_update_job @job_name = N'cdc.test_capture', @enabled = 1;

变更数据保留期默认只有 3 天(cleanup job 会清理)。任务停机超过保留期,未消费的变更就永久丢失了。需要延长:

sql
EXEC sys.sp_cdc_change_job @job_type = N'cleanup', @retention = 10080;  -- 分钟,此处 7 天

6.2 账号权限 ​

操作所需权限
执行 sp_cdc_enable_dbsysadmin 服务器角色(一次性操作,可由 DBA 执行)
执行 sp_cdc_enable_table库的 db_owner
CDC 账号日常运行源表 SELECT + cdc schema 下表的 SELECT
sql
-- 简单做法:给 db_owner
USE test;
CREATE USER dbzuser FOR LOGIN dbzuser;
ALTER ROLE db_owner ADD MEMBER dbzuser;

-- 最小权限做法
GRANT SELECT ON SCHEMA::dbo TO dbzuser;
GRANT SELECT ON SCHEMA::cdc TO dbzuser;

如果启用表级 CDC 时指定了 @role_name(不是 NULL),那么 CDC 账号还必须加入这个 gating role,否则查不到变更表数据。

6.3 前端配置 ​

字段必填填什么Debezium 属性
数据库连接✅选已建好的 SQL Server 数据源database.url 或 database.hostname/port
Server Name✅任务逻辑名,如 sqlserver-kettledatabase.server.name
快照模式✅见 2.2 节snapshot.mode
包含Schema变更只同步数据时不勾include.schema.changes
偏移量存储文件✅如 cdc-dat/sqlserver-kettle/sqlserver-cdc-offset.datoffset.storage.file.filename
历史文件✅如 cdc-dat/sqlserver-kettle/sqlserver-cdc-history.datschema.history.internal.file.filename
包含数据库库名(如 test),留空则自动用连接里的库database.include.list
包含表schema.表名,如 dbo.userstable.include.list

最高频的错误:把 schema 名(dbo、guest)填到「包含数据库」里。 该字段填库名,schema 名只出现在「包含表」中。填错的表现是引擎正常启动但一条数据都没有。

插件已自动设置 database.encrypt=false、database.trustServerCertificate=true、snapshot.isolation.mode=read_committed(快照期间不阻塞业务写入),无需在页面处理证书问题。

6.4 检查清单 ​

#检查项期望
1EXEC xp_servicecontrol 'QueryState','SQLServerAgent';Running
2SELECT is_cdc_enabled FROM sys.databases WHERE name='test';1
3SELECT is_tracked_by_cdc FROM sys.tables WHERE name='users';1
4SELECT enabled FROM msdb.dbo.sysjobs WHERE name='cdc.test_capture';1
5页面「包含数据库」库名,不是 schema 名
6页面「包含表」schema.表名(如 dbo.users)

七、权限速查汇总 ​

数据库一次性 DDL 操作(需高权限,通常由 DBA 做)CDC 账号日常运行权限
MySQL改 my.cnf 并重启(OS 权限)SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT
PostgreSQLALTER SYSTEM SET wal_level 并重启;建 slot;建 publication(FOR ALL TABLES 需超级用户)角色 REPLICATION 属性 + schema USAGE + 表 SELECT
OracleALTER DATABASE ARCHIVELOG(需停库);加补充日志;建 Common UserLOGMINING, SELECT ANY TABLE, SELECT ANY TRANSACTION, EXECUTE ON DBMS_LOGMNR, 各 V_$ 视图 SELECT(见 5.2)
SQL Serversp_cdc_enable_db(需 sysadmin);sp_cdc_enable_table(需 db_owner);启动 Agent源表 + cdc schema 的 SELECT(简化可给 db_owner)

八、排错指引 ​

8.1 任务能启动,但一直 0 行输出 ​

这是最常见的现象,按顺序排查:

序号排查点怎么确认
1「包含表」格式错(漏 schema/库名前缀、大小写不符)对照 2.5 节的格式表
2源表真的没有变更手工 INSERT 一条数据试试
3快照模式选了 no_data/never,而你期望看到存量数据改 initial 并删除偏移量文件
4偏移量文件里已有位点,快照被跳过删掉 .dat 和 .dat.lock 后重启
5SQL Server:库/表级 CDC 未启用,或 Agent 未运行见 6.4 清单
6SQL Server:「包含数据库」填了 schema 名改成库名
7Oracle:「包含数据库」填了普通库名而非 PDB 名非 CDB 实例留空

8.2 各库典型报错 ​

报错 / 现象原因处理
The 'snapshot.mode' value is invalid旧任务里存的是 schema_only 等废弃值打开配置页会自动折算,重新保存即可;插件运行时也已兜底
找不到Replication Slot: xxxPG 槽未创建且未勾自动创建SELECT pg_create_logical_replication_slot('xxx','pgoutput');
logical decoding requires wal_level >= logicalPG wal_level 不对ALTER SYSTEM SET wal_level='logical'; 后重启
permission denied to create replication slotPG 账号无复制权限ALTER ROLE xxx REPLICATION;
must be superuser to create FOR ALL TABLES publication账号非超级用户手动建 publication(见 4.1)
A slave with the same server_uuid/server_id has connectedMySQL Server ID 冲突每个任务给唯一 Server ID
binlog 位点不可用 / Client requested master to start from position > file sizeMySQL binlog 已被清理改 when_needed 重做快照;调大 binlog_expire_logs_seconds
ORA-65040: 不允许从插接式数据库内部执行该操作Oracle 连了 PDB数据源 URL 改连 CDB 根,PDB 名填「包含数据库」
The Oracle server is not configured to use a archive log LOG_MODE未开归档见 5.1 ②
Oracle before_data/after_data 为 null表级补充日志未开ALTER TABLE x.y ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
ORA-01031: insufficient privilegesLogMiner 权限不足补齐 5.2 的授权
CDC is not enabled on databaseSQL Server 库级未启用EXEC sys.sp_cdc_enable_db;
The specified table is not enabled for CDCSQL Server 表级未启用EXEC sys.sp_cdc_enable_table ...

8.3 看日志的正确姿势 ​

插件在初始化时会把全部 Debezium 参数打到 Kettle 日志(snapshot.mode、table.include.list、偏移量文件实际路径、slot/publication 检查结果等)。出问题时先在日志里搜这几个键,确认引擎实际收到的值与页面填的一致——很多问题就是文件路径落到了预期之外的目录,或者包含表被填成了空。

日志级别建议调到「详细」(Detailed)后再复现一次。