# CDC 实时同步必读

版本：v1.0.0 | 更新日期：2026-08

# 概述

DataMover 的实时同步基于嵌入式Debezium 1.9.8 引擎，通过监听源库的变更日志（binlog / WAL / Redo Log）实现秒级数据捕获。不同于普通任务的 JDBC 批量读取，CDC 任务对源库有额外的配置要求——必须开启变更日志且格式正确，否则任务无法启动或漏数据。

本文列出六种支持 CDC 的源库所需的最小配置、验证命令和常见陷阱。请在生产环境上线前逐项核对。

关于版本兼容性：DataMover 基于 Debezium 1.9.8，各数据库版本的官方支持列表可查阅 Debezium 1.9 文档 (opens new window)。如果您的数据库版本不在官方验证范围内，一般仍可尝试使用——只要底层日志协议（binlog / WAL / Redo）没有大的结构性变更，通常可以兼容。建议在测试环境先行验证后再上线。

数据库	CDC 机制	Debezium 连接器
MySQL / MariaDB / PolarDB-MySQL / OceanBase-MySQL	binlog	debezium-connector-mysql
PostgreSQL / PolarDB-PG	WAL (logical decoding)	debezium-connector-postgres
Oracle	Redo Log (LogMiner)	debezium-connector-oracle
SQL Server	CDC (change data capture)	debezium-connector-sqlserver
达梦 DM	Archive Log	debezium-connector-dm
人大金仓 Kingbase	WAL (logical decoding)	debezium-connector-kingbase

# MySQL / MariaDB / PolarDB-MySQL / OceanBase-MySQL

# 前置条件

检查项	要求	默认值
binlog 开关	必须开启	MySQL 8.0 默认开启，5.7 可能关闭
binlog 格式	`ROW`	默认 `ROW`（MySQL 8.0）
binlog 行镜像	`FULL`	默认 `FULL`（MySQL 8.0）
server-id	必须设置，集群内唯一	默认 `1`
账号权限	`REPLICATION SLAVE`, `REPLICATION CLIENT`	—

# 配置步骤

1) 检查当前配置

SHOW VARIABLES LIKE 'log_bin';
SHOW VARIABLES LIKE 'binlog_format';
SHOW VARIABLES LIKE 'binlog_row_image';
SHOW VARIABLES LIKE 'server_id';

2) 修改 my.cnf / my.ini（需要重启 MySQL）

[mysqld]
server-id=1                              # 集群内必须唯一
log-bin=mysql-bin                        # 开启 binlog
binlog_format=ROW                        # 必须是 ROW 格式
binlog_row_image=FULL                    # 必须是 FULL，否则 UPDATE 可能丢字段
expire_logs_days=7                       # binlog 保留天数，建议 >= 3
binlog_cache_size=4M
max_binlog_size=512M

3) 创建同步账号并授权

CREATE USER 'datamover_cdc'@'%' IDENTIFIED BY 'your_password';
GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT
    ON *.* TO 'datamover_cdc'@'%';
FLUSH PRIVILEGES;

4) 重启 MySQL

systemctl restart mysql

# 验证

-- 确认 binlog 正常写入
SHOW MASTER STATUS;

-- 确认 binlog 格式
SHOW VARIABLES LIKE 'binlog_format';    -- 应输出 ROW
SHOW VARIABLES LIKE 'binlog_row_image'; -- 应输出 FULL

预期输出示例：

+------------------+----------+--------------+------------------+-------------------+
| File             | Position | Binlog_Do_DB | Binlog_Ignore_DB | Executed_Gtid_Set |
+------------------+----------+--------------+------------------+-------------------+
| mysql-bin.000001 |      154 |              |                  |                   |
+------------------+----------+--------------+------------------+-------------------+

# 常见问题

现象	原因	解决
CDC 任务启动报 "binary logging not enabled"	`log-bin` 未开启	按上述步骤配置并重启
UPDATE 操作目标表缺少字段	`binlog_row_image=MINIMAL`	改为 `FULL` 后重启
snapshot 阶段源库被锁死	共享 MySQL 实例	CDC 策略设置 `snapshot.locking.mode=none`
权限报错	账号缺少复制权限	执行上述 GRANT 语句

# PostgreSQL / PolarDB-PG / Citus / Greenplum

# 前置条件

检查项	要求	默认值
wal_level	`logical`	默认 `replica`，必须改
max_replication_slots	>= 1	默认 10
max_wal_senders	>= 1	默认 10
账号权限	`REPLICATION` + 表 `SELECT`	—
pg_hba.conf	允许同步账号的连接	—

# 配置步骤

1) 检查当前配置

SHOW wal_level;
SHOW max_replication_slots;
SHOW max_wal_senders;

-- 或
SELECT name, setting FROM pg_settings
WHERE name IN ('wal_level', 'max_replication_slots', 'max_wal_senders');

2) 修改 postgresql.conf（需要重启 PostgreSQL）

wal_level = logical                       # 必须为 logical
max_replication_slots = 4                 # 建议 >= 2（每个 CDC 任务占用 1 个槽）
max_wal_senders = 4                       # 建议 >= max_replication_slots
wal_sender_timeout = 60s                  # 发送超时

3) 修改 pg_hba.conf（reload 即可）

# 添加以下行，允许同步账号连接
host    replication     datamover_cdc    0.0.0.0/0     md5
host    all             datamover_cdc    0.0.0.0/0     md5

pg_ctl reload
# 或
SELECT pg_reload_conf();

4) 创建同步账号并授权

CREATE USER datamover_cdc WITH PASSWORD 'your_password' REPLICATION;
GRANT CONNECT ON DATABASE source_db TO datamover_cdc;
GRANT USAGE ON SCHEMA public TO datamover_cdc;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO datamover_cdc;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO datamover_cdc;

5) 重启 PostgreSQL

systemctl restart postgresql-12

# 验证

-- 确认 wal_level 已生效
SHOW wal_level;                            -- 应输出 logical

-- 确认存在可用的 replication slot
SELECT * FROM pg_replication_slots;

-- 测试发布（可选的额外验证）
-- CREATE PUBLICATION dm_test FOR TABLE your_table;
-- SELECT * FROM pg_publication;

# 常见问题

现象	原因	解决
CDC 任务启动报 "wal_level is not logical"	`wal_level=replica`（默认）	改为 `logical` 后重启 PG
"replication slot is active"	上一个任务未正常释放 slot	在源库删除残留 slot：`SELECT pg_drop_replication_slot('slot_name');`
pg_hba.conf 拒绝连接	未添加 replication 条目	按步骤 3 添加
新建表无 SELECT 权限	未设置默认权限	执行 `ALTER DEFAULT PRIVILEGES`

# Oracle

# 前置条件

检查项	要求	默认值
归档日志	必须开启（ARCHIVELOG 模式）	默认 NOARCHIVELOG
补充日志（Supplemental Logging）	数据库级 + 表级均需开启	默认关闭
LogMiner	使用 LogMiner 或 XStream API（推荐 LogMiner）	—
账号权限	`CREATE SESSION`, `SELECT ANY TRANSACTION`, `SELECT ON V$DATABASE`, `FLASHBACK ANY TABLE`, 待同步表的 `SELECT`	—

# 配置步骤

1) 检查归档模式

SELECT log_mode FROM v$database;
-- 应输出 ARCHIVELOG

2) 开启归档（需以 SYSDBA 在 MOUNT 状态操作）

-- 以 SYSDBA 连接
SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;

-- 验证
ARCHIVE LOG LIST;
SELECT log_mode FROM v$database;

3) 开启补充日志

-- 步骤 a：数据库级最小补充日志（必须）
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

-- 步骤 b：数据库级 ALL COLUMNS 补充日志（默认方案，推荐）
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

-- 如果希望仅对部分表开启，可改用按表开启（替代上面的数据库级 ALL COLUMNS）：
-- ALTER TABLE schema_name.table_name ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

-- 验证
SELECT supplemental_log_data_min, supplemental_log_data_all FROM v$database;

4) 创建同步账号并授权

CREATE USER datamover_cdc IDENTIFIED BY your_password;
GRANT CONNECT TO datamover_cdc;
GRANT CREATE SESSION TO datamover_cdc;
GRANT SELECT ANY TRANSACTION TO datamover_cdc;
GRANT SELECT ON V$DATABASE TO datamover_cdc;
GRANT FLASHBACK ANY TABLE TO datamover_cdc;
GRANT SELECT ON schema_name.table_name TO datamover_cdc;

# 验证

-- 确认归档开启
SELECT log_mode FROM v$database;                    -- ARCHIVELOG

-- 确认补充日志
SELECT supplemental_log_data_min FROM v$database;   -- YES/IMPLICIT

-- 确认表级补充日志
SELECT owner, table_name, log_group_type
FROM dba_log_groups WHERE owner = 'SCHEMA_NAME';

# 常见问题

现象	原因	解决
CDC 任务启动报 "not in ARCHIVELOG mode"	数据库为 NOARCHIVELOG	按步骤 2 开启归档（需停机）
锁表 / 阻塞	恢复表需拿锁	减少待同步表数量避免恢复风暴
补充日志未开启	`ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS` 未执行，或待同步的表被遗漏	确认数据库级 ALL COLUMNS 已开启；如用按表模式，每个待同步表执行 `ALTER TABLE ... ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS`
权限不足	缺少 `SELECT ANY TRANSACTION` 或 `FLASHBACK ANY TABLE`	补充授权

# SQL Server

# 前置条件

检查项	要求	默认值
CDC 功能	数据库级 + 表级均需启用	默认关闭
SQL Server Agent	必须运行	需手动启动
账号权限	`db_owner` 或 `sysadmin`（仅 CDC 启用阶段），之后可用专用账号	—

# 配置步骤

1) 检查 CDC 状态

-- 数据库级
SELECT name, is_cdc_enabled FROM sys.databases WHERE name = 'your_db';

-- 表级
SELECT name, is_tracked_by_cdc FROM sys.tables WHERE is_tracked_by_cdc = 1;

2) 启用数据库级 CDC

-- 需要 sysadmin 权限
USE your_db;
EXEC sys.sp_cdc_enable_db;
-- 验证
SELECT is_cdc_enabled FROM sys.databases WHERE name = 'your_db';  -- 应输出 1

3) 启用表级 CDC（每个待同步表都要执行）

EXEC sys.sp_cdc_enable_table
    @source_schema = N'dbo',
    @source_name   = N'your_table',
    @role_name     = NULL;    -- 不限制角色访问

-- 验证表的 CDC 配置
EXEC sys.sp_cdc_help_change_data_capture
    @source_schema = N'dbo',
    @source_name   = N'your_table';

4) 确保 SQL Server Agent 运行

-- 查看 Agent 状态
EXEC xp_servicecontrol 'querystate', 'SQLServerAGENT';

-- 如果未运行，在 SSMS 中右键 SQL Server Agent → 启动，或用命令：
-- EXEC xp_servicecontrol 'start', 'SQLServerAGENT';

# 验证

-- 确认数据库 CDC 已启用
SELECT name, is_cdc_enabled FROM sys.databases WHERE name = 'your_db';

-- 确认目标表 CDC 已启用
SELECT name, is_tracked_by_cdc FROM sys.tables WHERE is_tracked_by_cdc = 1;

-- 确认 CDC 捕获作业运行正常
SELECT * FROM msdb.dbo.sysjobs WHERE name LIKE 'cdc.%';

# 常见问题

现象	原因	解决
"CDC is not enabled"	数据库或表未启用 CDC	按步骤 2、3 启用
"SQLServerAgent is not running"	Agent 未启动	启动 SQL Server Agent 服务
CDC 任务启动后无数据捕获	表级 CDC 遗漏	每个待同步表都需要 `sp_cdc_enable_table`
磁盘空间不足	CDC 清理作业未配置	检查 `sys.sp_cdc_cleanup_change_table` 保留策略

# 达梦 DM

# 前置条件

检查项	要求	默认值
归档模式	必须开启	默认关闭
补充日志	需要开启（`RLOG_APPEND_LOGIC`）	默认关闭
账号权限	DBA 或具有 `SELECT ON V$DATABASE`、待同步表的 `SELECT`	—

# 配置步骤

1) 检查归档模式

SELECT ARCH_MODE FROM V$DATABASE;
-- Y = 已开启归档

2) 开启归档（需重启数据库到 MOUNT 状态）

-- 以 SYSDBA 连接
ALTER DATABASE MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE ADD ARCHIVELOG 'DEST=/dm8/arch, TYPE=LOCAL, FILE_SIZE=128, SPACE_LIMIT=10240';
ALTER DATABASE OPEN;

3) 开启补充日志

-- 开启数据库级补充日志
ALTER SYSTEM SET 'RLOG_APPEND_LOGIC'=1;

-- 验证
SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME = 'RLOG_APPEND_LOGIC';  -- 应为 1

# 验证

-- 确认归档已开启
SELECT ARCH_MODE FROM V$DATABASE;     -- Y

-- 确认补充日志
SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME = 'RLOG_APPEND_LOGIC';  -- 1

# 常见问题

现象	原因	解决
"归档未开启" 报错	达梦默认非归档模式	按步骤 2 开启归档
数据变更未捕获	未开启 `RLOG_APPEND_LOGIC`	按步骤 3 开启
磁盘满	归档日志未清理	配置归档日志保留策略

# 人大金仓 Kingbase

# 前置条件

Kingbase 基于 PostgreSQL，CDC 配置与 PostgreSQL 基本相同。

检查项	要求	默认值
wal_level	`logical`	可能为 `replica`，需确认
max_replication_slots	>= 1	需确认
max_wal_senders	>= 1	需确认
账号权限	`REPLICATION` + 表 `SELECT`	—

# 配置步骤

1) 检查当前配置

SHOW wal_level;
SHOW max_replication_slots;
SHOW max_wal_senders;

2) 修改 kingbase.conf（需要重启）

wal_level = logical
max_replication_slots = 4
max_wal_senders = 4

3) 修改 sys_hba.conf（reload 即可）

# 添加 replication 连接权限
host    replication     datamover_cdc    0.0.0.0/0     md5
host    all             datamover_cdc    0.0.0.0/0     md5

4) 创建同步账号并授权

CREATE USER datamover_cdc WITH PASSWORD 'your_password' REPLICATION;
GRANT CONNECT ON DATABASE source_db TO datamover_cdc;
GRANT USAGE ON SCHEMA public TO datamover_cdc;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO datamover_cdc;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO datamover_cdc;

5) 重启 Kingbase

# 验证

SHOW wal_level;                              -- 应输出 logical
SELECT * FROM sys_replication_slots;         -- 对应 PostgreSQL 的 pg_replication_slots

# 常见问题

现象	原因	解决
"wal_level is not logical"	默认值不是 logical	修改 kingbase.conf 后重启
连接被拒绝	sys_hba.conf 未配置	按步骤 3 添加
replication slot 残留	任务异常退出	手动清理：`SELECT sys_drop_replication_slot('slot_name');`

# 附录：快速检查清单

上线前逐项确认：

数据库	检查项	命令
MySQL	binlog 是否开启 + 格式	`SHOW VARIABLES LIKE 'log_bin'; SHOW VARIABLES LIKE 'binlog_format';`
MySQL	binlog 行镜像	`SHOW VARIABLES LIKE 'binlog_row_image';`
MySQL	账号权限	`SHOW GRANTS FOR 'datamover_cdc'@'%';`
PostgreSQL	wal_level	`SHOW wal_level;`
PostgreSQL	replication slot	`SELECT * FROM pg_replication_slots;`
Oracle	归档模式	`SELECT log_mode FROM v$database;`
Oracle	补充日志	`SELECT supplemental_log_data_min FROM v$database;`
SQL Server	数据库 CDC	`SELECT is_cdc_enabled FROM sys.databases WHERE name='...';`
SQL Server	表级 CDC	`SELECT name, is_tracked_by_cdc FROM sys.tables;`
SQL Server	Agent 状态	`EXEC xp_servicecontrol 'querystate','SQLServerAGENT';`
达梦	归档	`SELECT ARCH_MODE FROM V$DATABASE;`
达梦	补充日志	`SELECT VALUE FROM V$PARAMETER WHERE NAME='RLOG_APPEND_LOGIC';`
Kingbase	wal_level	`SHOW wal_level;`

← 任务管理函数表达式指南 →