Appearance
CDC 组件配置说明(JDK11 / Debezium 2.7 版)
适用于 kettle_plugins_jdk11 下的四个 CDC 输入插件,以及 Web 设计器(web-etl-ui-vue3)中对应的四个组件。
| 插件模块 | Web 设计器组件名 | Debezium 连接器版本 | 捕获机制 |
|---|---|---|---|
mysql-cdc-input-kettle | MYSQL CDC | 2.7.4.Final | binlog |
pg-cdc-input-kettle | PG CDC | 2.7.0.Final | 逻辑复制(pgoutput) |
oracle-cdc-input-kettle | Oracle CDC | 2.7.0.Final | LogMiner |
sqlserver-cdc-input-kettle | MSSQL CDC | 2.7.0.Final | CDC 变更表 + Agent |
一、配置总流程
CDC 与普通输入组件最大的区别是:大部分工作在数据库侧,不在页面上。数据库没开好,页面配得再对也是 0 行输出。建议严格按顺序做:
- 数据库侧开功能:开日志(binlog / wal_level / ARCHIVELOG / CDC 变更表),逐库逐表启用(SQL Server、Oracle 补充日志)。
- 数据库侧建账号授权:CDC 账号权限和普通查询账号不同,必须额外给复制/日志读取类权限。
- 建 Kettle 数据库连接:在 Web 设计器的数据源里配好连接,CDC 组件从连接中取 host/port/user/password。
- 页面配置组件字段:Server Name、包含表、快照模式、偏移量文件等。
- 首次运行看日志:日志里会打印全部 Debezium 参数和前置检查结果,出问题先看这段。
二、通用配置说明(四个组件共有)
2.1 组件输出字段
四个组件的默认输出字段完全一致,共 6 个:
| 字段名 | Kettle 类型 | 内容 | 说明 |
|---|---|---|---|
operation | String | c / u / d / r | c=新增,u=更新,d=删除,r=快照阶段读出的存量数据 |
database_name | String | 库名 | 来自变更事件的 source.db |
table_name | String | 表名 | 来自变更事件的 source.table,不含 schema |
before_data | String | JSON | 变更前整行数据;c 和 r 事件为 null |
after_data | String | JSON | 变更后整行数据;d 事件为 null |
timestamp | Date | 事件时间 | 来自 source.ts_ms |
下游要拿具体列值,需要接一个 JSON Input 之类的组件解析 after_data / before_data,不能直接当列用。
判断增删改时注意用
operation的单字母值(c/u/d/r),不是INSERT/UPDATE/DELETE。
2.2 快照模式(snapshotMode)
各连接器合法值不同,这是最容易踩的坑。页面下拉框已按连接器限制为下面这些值,选项旁会显示中文说明:
| 模式 | 含义 | MySQL | PG | Oracle | SQL 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 CDC | schema.表名 | public.users,public.T_MATERIAL | 只写 users;漏掉 public. |
| Oracle CDC | 用户名.表名(大写) | SCOTT.EMP,SCOTT.DEPT | 写成小写 |
| MSSQL CDC | schema.表名 | 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_bin | ON | 完全无法采集 |
binlog_format | ROW | STATEMENT/MIXED 解析不出行级前后镜像 |
binlog_row_image | FULL | before_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-kettle | database.server.name |
| 快照模式 | ✅ | 见 2.2 节 | snapshot.mode |
| 包含Schema变更 | 只同步数据时不勾 | include.schema.changes | |
| 偏移量存储文件 | ✅ | 如 cdc-dat/mysql-kettle/mysql-cdc-offset.dat | offset.storage.file.filename |
| 历史文件 | ✅ | 如 cdc-dat/mysql-kettle/mysql-cdc-history.dat | schema.history.internal.file.filename |
| 包含数据库 | 库名,多个用逗号,如 test,order_db;留空监听所有库 | database.include.list | |
| 包含表 | 库名.表名,如 test.users | table.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 检查清单
| # | 检查项 | 期望 |
|---|---|---|
| 1 | SHOW VARIABLES LIKE 'log_bin'; | ON |
| 2 | SHOW VARIABLES LIKE 'binlog_format'; | ROW |
| 3 | SHOW VARIABLES LIKE 'binlog_row_image'; | FULL |
| 4 | SHOW 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_slot | slot.name |
| Server Name | ✅ | 任务逻辑名,如 pg-kettle | database.server.name |
| Publication | ✅ | 如 dbz_publication | publication.name |
| 快照模式 | ✅ | 见 2.2 节(PG 无 recovery) | snapshot.mode |
| 自动创建Replication Slot | 不勾则必须先手动建槽 | slot.auto.create | |
| 停止时删除Slot | 生产环境不要勾 | slot.drop.on.stop | |
| 偏移量存储文件 | ✅ | 如 cdc-dat/pg-kettle/pg-cdc-offset.dat | offset.storage.file.filename |
| 历史文件 | ✅ | 如 cdc-dat/pg-kettle/pg-cdc-history.dat | schema.history.internal.file.filename |
| 包含表 | schema.表名,如 public.users | table.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 检查清单
| # | 检查项 | 期望 |
|---|---|---|
| 1 | SHOW wal_level; | logical |
| 2 | SELECT slot_name, plugin FROM pg_replication_slots; | 槽存在且 plugin=pgoutput |
| 3 | SELECT pubname FROM pg_publication; | publication 存在 |
| 4 | SELECT 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/ORCL | database.url |
| Server Name | ✅ | 任务逻辑名,如 oracle-server-kettle | database.server.name |
| 快照模式 | ✅ | 见 2.2 节 | snapshot.mode |
| 包含Schema变更 | 只同步数据时不勾 | include.schema.changes | |
| 偏移量存储文件 | ✅ | 如 cdc-dat/oracle-server-kettle/oracle-cdc-offset.dat | offset.storage.file.filename |
| 历史文件 | ✅ | 如 cdc-dat/oracle-server-kettle/oracle-cdc-history.dat | schema.history.internal.file.filename |
| 包含数据库 | 填 PDB 名称,如 ORCLPDB1;非 CDB 实例留空 | database.pdb.name | |
| 包含表 | 用户名.表名,大写,如 SCOTT.EMP | table.include.list |
Oracle 的两个专属陷阱:
- 数据源 URL 必须连 CDB 根服务(如
/ORCL),连了 PDB(如/ORCLPDB1)会报ORA-65040: 不允许从插接式数据库内部执行该操作。确认 CDB 服务名:SELECT NAME FROM V$DATABASE;或lsnrctl status。 - 「包含数据库」这个字段填的不是普通库名,而是 PDB 名称(映射到
database.pdb.name)。传统非 CDB 实例必须留空,填了反而连不上。
5.4 检查清单
| # | 检查项 | 期望 |
|---|---|---|
| 1 | SELECT LOG_MODE FROM V$DATABASE; | ARCHIVELOG |
| 2 | SELECT SUPPLEMENTAL_LOG_DATA_MIN FROM V$DATABASE; | YES |
| 3 | 账号存在且是 Common User | C## 前缀或 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 会清理)。任务停机超过保留期,未消费的变更就永久丢失了。需要延长:
sqlEXEC sys.sp_cdc_change_job @job_type = N'cleanup', @retention = 10080; -- 分钟,此处 7 天
6.2 账号权限
| 操作 | 所需权限 |
|---|---|
执行 sp_cdc_enable_db | sysadmin 服务器角色(一次性操作,可由 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-kettle | database.server.name |
| 快照模式 | ✅ | 见 2.2 节 | snapshot.mode |
| 包含Schema变更 | 只同步数据时不勾 | include.schema.changes | |
| 偏移量存储文件 | ✅ | 如 cdc-dat/sqlserver-kettle/sqlserver-cdc-offset.dat | offset.storage.file.filename |
| 历史文件 | ✅ | 如 cdc-dat/sqlserver-kettle/sqlserver-cdc-history.dat | schema.history.internal.file.filename |
| 包含数据库 | 库名(如 test),留空则自动用连接里的库 | database.include.list | |
| 包含表 | schema.表名,如 dbo.users | table.include.list |
最高频的错误:把 schema 名(dbo、guest)填到「包含数据库」里。 该字段填库名,schema 名只出现在「包含表」中。填错的表现是引擎正常启动但一条数据都没有。
插件已自动设置
database.encrypt=false、database.trustServerCertificate=true、snapshot.isolation.mode=read_committed(快照期间不阻塞业务写入),无需在页面处理证书问题。
6.4 检查清单
| # | 检查项 | 期望 |
|---|---|---|
| 1 | EXEC xp_servicecontrol 'QueryState','SQLServerAgent'; | Running |
| 2 | SELECT is_cdc_enabled FROM sys.databases WHERE name='test'; | 1 |
| 3 | SELECT is_tracked_by_cdc FROM sys.tables WHERE name='users'; | 1 |
| 4 | SELECT 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 |
| PostgreSQL | ALTER SYSTEM SET wal_level 并重启;建 slot;建 publication(FOR ALL TABLES 需超级用户) | 角色 REPLICATION 属性 + schema USAGE + 表 SELECT |
| Oracle | ALTER DATABASE ARCHIVELOG(需停库);加补充日志;建 Common User | LOGMINING, SELECT ANY TABLE, SELECT ANY TRANSACTION, EXECUTE ON DBMS_LOGMNR, 各 V_$ 视图 SELECT(见 5.2) |
| SQL Server | sp_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 后重启 |
| 5 | SQL Server:库/表级 CDC 未启用,或 Agent 未运行 | 见 6.4 清单 |
| 6 | SQL Server:「包含数据库」填了 schema 名 | 改成库名 |
| 7 | Oracle:「包含数据库」填了普通库名而非 PDB 名 | 非 CDB 实例留空 |
8.2 各库典型报错
| 报错 / 现象 | 原因 | 处理 |
|---|---|---|
The 'snapshot.mode' value is invalid | 旧任务里存的是 schema_only 等废弃值 | 打开配置页会自动折算,重新保存即可;插件运行时也已兜底 |
找不到Replication Slot: xxx | PG 槽未创建且未勾自动创建 | SELECT pg_create_logical_replication_slot('xxx','pgoutput'); |
logical decoding requires wal_level >= logical | PG wal_level 不对 | ALTER SYSTEM SET wal_level='logical'; 后重启 |
permission denied to create replication slot | PG 账号无复制权限 | 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 connected | MySQL Server ID 冲突 | 每个任务给唯一 Server ID |
binlog 位点不可用 / Client requested master to start from position > file size | MySQL 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 privileges | LogMiner 权限不足 | 补齐 5.2 的授权 |
CDC is not enabled on database | SQL Server 库级未启用 | EXEC sys.sp_cdc_enable_db; |
The specified table is not enabled for CDC | SQL Server 表级未启用 | EXEC sys.sp_cdc_enable_table ... |
8.3 看日志的正确姿势
插件在初始化时会把全部 Debezium 参数打到 Kettle 日志(snapshot.mode、table.include.list、偏移量文件实际路径、slot/publication 检查结果等)。出问题时先在日志里搜这几个键,确认引擎实际收到的值与页面填的一致——很多问题就是文件路径落到了预期之外的目录,或者包含表被填成了空。
日志级别建议调到「详细」(Detailed)后再复现一次。