跳到主要内容

数据集成同步异常解决手册

一、数据源连接问题​

1. MySQL相关问题​

1.1 连接认证异常​

错误信息：Read split MySqlBinlogSplit{splitId='binlog-split', ...} error due to Unable to connect to the MySQL database at 124.71.177.180:3306 with user 'root': unexpected sequence #1.

问题原因：

  1. 客户端数据库连接数不足
  2. 网络抖动导致连接不稳定
  3. 数据库负载过高

解决方案：

  1. 清理数据库中的空闲连接
  2. 扩充数据库的最大连接数限制
  3. 检查网络连接的稳定性，确保无丢包和高延迟
1.2 版本兼容问题​

错误信息： Synchronizing error: Public Key Retrieval is not allowed

问题原因：

  1. Flink CDC与MySQL 8.0的认证方式不兼容
  2. sha256_password认证方式需要通过TLS或RSA公钥加密保护密码

解决方案：

  1. 更改MySQL用户的认证方式： ALTER USER 'username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password'; FLUSH PRIVILEGES;

  2. 在my.ini文件中添加配置： [mysqld] default_authentication_plugin=mysql_native_password

1.3 主键索引问题​

错误信息： Specified key was too long; max key length is 767 bytes

问题原因：

  1. MySQL 5.6中InnoDB存储引擎对索引长度限制为767字节
  2. utf8mb4字符集下varchar(255)会超出限制：
    • utf8mb4每个字符占4字节
    • varchar(255) * 4 = 1020字节 > 767字节限制

解决方案：

  1. 减少varchar字段长度：
    • 将主键字段长度从255修改为191或更小
    • 191 * 4 = 764字节 < 767字节限制
  2. 或更改字符集： ALTER TABLE table_name CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;
1.4 数据同步配置问题​

错误信息： 开启同步任务后数据不同步

问题原因：

  1. binlog未开启
  2. binlog格式配置不正确
  3. binlog保留时间不足

解决方案：

  1. 检查并开启binlog： SHOW VARIABLES LIKE 'log_bin';

  2. 设置正确的binlog格式： SET GLOBAL binlog_format = 'ROW';

  3. 调整binlog保留时间： SET GLOBAL expire_logs_days = 7;

1.5 主从复制错误​

错误信息： A slave with the same server_uuid/server_id as this slave has connected to the master

问题原因：

  1. 多个从库使用相同的server_uuid或server_id
  2. 主从同步配置冲突
  3. 复制连接未正常关闭

解决方案：

  1. 确保从库配置唯一性：

    • 检查并修改server_id
    • 验证server_uuid唯一性

  2. 重置复制状态： STOP SLAVE; RESET SLAVE; START SLAVE;

1.6 CDC数据解析错误​

错误信息： Failed to deserialize data of EventHeaderV4

问题原因：

  1. CDC数据格式不兼容
  2. 数据解析过程中断
  3. 事务日志不完整

解决方案：

  1. 检查数据库配置： SET GLOBAL slave_net_timeout = 120; SET GLOBAL thread_pool_idle_timeout = 120;

  2. 确保事务日志完整性：

    • 检查binlog是否完整
    • 验证CDC追踪状态
1.7 时区配置不匹配​

错误信息： ValidationException: The MySQL server has a timezone offset (0 seconds ahead of UTC) which does not match the configured timezone GMT+08:00.

问题原因：

  1. 数据库服务器时区设置与应用配置不一致
  2. 时区转换错误
  3. 默认时区配置问题

解决方案：

  1. 检查MySQL时区设置： SHOW VARIABLES LIKE '%time_zone%';

  2. 修改数据库时区： SET GLOBAL time_zone = '+8:00'; SET time_zone = '+8:00';

1.8 字符集编码问题​

错误信息： java.sql.SQLException: Incorrect string value: '\xF0\x9F\x98\x81' for column

问题原因：

  1. 数据库字符集不支持特殊字符
  2. 连接字符集配置不正确
  3. 表字段字符集与连接字符集不匹配

解决方案：

  1. 修改数据库字符集： ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

  2. 修改表字符集： ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

1.9 内存使用过高​

错误信息： The table 'xxx' is full

问题原因：

  1. temp_table_size 和 max_heap_table_size 设置过小
  2. 同步过程中产生大量临时表
  3. 系统内存不足

解决方案：

  1. 增加临时表空间： SET GLOBAL tmp_table_size = 67108864; SET GLOBAL max_heap_table_size = 67108864;

  2. 优化查询避免使用临时表

1.10 SSL连接握手异常​

错误信息： HikariPool$PoolInitializationException: Failed to initialize pool: Communications link failure；javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake；java.io.EOFException: SSL peer shut down incorrectly

问题原因：

  1. 客户端默认尝试以SSL方式连接MySQL，但与服务端SSL握手失败（常见于MySQL 5.7配合较新JDK，导致老版本TLS协议被禁用而协商失败）
  2. “测试连接”读取的是“其他连接串参数”，而Flink CDC任务运行时连接器自行拼接连接URL，不读取该参数，因此会出现“测试连接通过但任务启动后仍报SSL错误”的现象
  3. Flink CDC任务存在两条连接（快照阶段的JDBC连接池、增量阶段的Debezium binlog连接），需分别关闭SSL，否则快照阶段过了，增量阶段仍会报同样的错

解决方案：

  1. 确认服务端是否强制SSL（值为OFF时，关闭客户端SSL不会被服务端拒绝）： SHOW VARIABLES LIKE 'require_secure_transport';

  2. 在“其他连接串参数”中追加，供测试连接使用（MySQL 5.x驱动用useSSL，8.x驱动用sslMode）： useSSL=false 或 sslMode=DISABLED

  3. 在“其他连接器选项”中追加，供任务运行时使用。注意此处需用Flink CDC选项格式，不能直接写useSSL： jdbc.properties.useSSL=false&debezium.database.ssl.mode=disabled 其中 jdbc.properties.useSSL 作用于快照阶段的JDBC连接池（即报HikariPool的那条连接），debezium.database.ssl.mode 作用于增量阶段的binlog连接

  4. 保存配置后，将任务停止并重新发布（必须重新发布，resume不会重新加载数据源配置），重启后SSL报错即消失

1.11 连接数打满Too many connections​

错误信息： com.mysql.cj.jdbc.exceptions.SQLNonTransientConnectionException: Too many connections

问题原因：

  1. MySQL max_connections 上限较低，被业务连接 + 同步任务连接共同打满
  2. CDC 快照阶段并行度高，JDBC 连接池占用较多连接
  3. 存在大量空闲未释放连接
  4. 同一实例上运行多个同步任务，连接叠加

解决方案：

  1. 查看当前连接与上限： SHOW VARIABLES LIKE 'max_connections'; SHOW STATUS LIKE 'Threads_connected';
  2. 适当上调上限（需 DBA 评估内存）： SET GLOBAL max_connections = 500;
  3. 降低 CDC 快照并行度，或为同步任务设置合理的连接池上限
  4. 清理空闲连接，缩短 wait_timeout 回收僵尸连接
  5. 为同步任务创建独立账号并限制其最大连接数，避免影响业务
1.12 锁等待超时Lock wait timeout​

错误信息： Lock wait timeout exceeded; try restarting transaction

问题原因：

  1. 快照阶段需要的元数据锁/表锁被其它长事务阻塞
  2. 源库存在长时间未提交事务持有锁
  3. 目标库写入与其它业务争抢行锁（写入侧也可能报此错）
  4. 大事务导致锁持有时间过长

解决方案：

  1. 定位阻塞源头： SELECT * FROM information_schema.INNODB_TRX; SELECT * FROM performance_schema.data_lock_waits; -- 8.0
  2. 提交或终止持锁的长事务
  3. 适当增大锁等待超时（治标）： SET GLOBAL innodb_lock_wait_timeout = 120;
  4. CDC 建议使用支持无锁/弱锁快照的增量快照算法，避免长时间持表锁
  5. 避免在同步高峰期对相关表执行大事务或 DDL
1.13 数据包过大max_allowed_packet​

错误信息： Packet for query is too large (xxx > yyy). You can change this value on the server by setting the 'max_allowed_packet' variable.

问题原因：

  1. 单行数据过大（大文本、BLOB），超过 max_allowed_packet
  2. 批量写入时单批 SQL 过大超过限制
  3. 源库或目标库 max_allowed_packet 配置过小

解决方案：

  1. 查看并调大（源库/目标库按需，两端都可能涉及）： SHOW VARIABLES LIKE 'max_allowed_packet'; SET GLOBAL max_allowed_packet = 67108864; -- 64MB
  2. 减小批量写入的 batch size，避免单批过大
  3. 评估超大字段是否必须同步，可裁剪或单独处理
  4. 修改 GLOBAL 后需重新建立连接（重发任务）才生效
1.14 binlog格式非ROW导致解析异常​

错误信息： 任务能连接但增量数据解析不全/报错，或日志提示 binlog 格式不为 ROW。

问题原因：

  1. binlog_format 设置为 STATEMENT 或 MIXED，CDC 无法可靠解析行级变更
  2. binlog_row_image 非 FULL，导致 UPDATE 前镜像/部分列缺失
  3. 仅改了会话级未改全局，或未重启使配置生效

解决方案：

  1. 检查并设置为 ROW 全镜像： SHOW VARIABLES LIKE 'binlog_format'; SHOW VARIABLES LIKE 'binlog_row_image'; SET GLOBAL binlog_format = 'ROW'; SET GLOBAL binlog_row_image = 'FULL';
  2. GLOBAL 修改仅对新连接生效，已有连接需重连；建议同时写入 my.cnf 持久化并择机重启
  3. 修改前已产生的 STATEMENT 格式 binlog 无法补救，需重新做全量同步
1.15 只读实例/从库无法读取binlog​

错误信息： 连接只读副本（如云 RDS 只读实例）做 CDC 时无增量，或报无 binlog/权限不足。

问题原因：

  1. 连接的是只读实例，其 binlog 未开启或不对外提供订阅
  2. 云厂商只读实例默认不保留可订阅的 binlog
  3. 账号缺少 REPLICATION SLAVE / REPLICATION CLIENT 权限

解决方案：

  1. CDC 增量订阅应连接主实例（或专门用于订阅的实例），而非只读副本
  2. 确认实例已开启 binlog 且保留时间足够（见 1.4、2.3 位点相关）
  3. 授予订阅权限： GRANT REPLICATION SLAVE, REPLICATION CLIENT ON . TO 'sync_user'@'%';
  4. 云环境需在控制台确认实例支持 binlog 订阅并已开启
1.16 数值类型映射溢出(MEDIUMINT被映射为SMALLINT)​

错误信息： Value out of range. Value:"40000" Radix:10（堆栈含 java.lang.Short.parseShort）

问题原因：

  1. 源端为 MySQL MEDIUMINT / MEDIUMINT UNSIGNED，在 Flink/JDBC DDL 或中间算子中被映射/CAST 成 SMALLINT，位宽不足（SMALLINT 最大 32767）
  2. 目标表列型过小，写入或反序列化时溢出

解决方案：

  1. 统一将该列在源表 DDL / 目标表 DDL 中声明为 INT（UNSIGNED 情况建议用 INT 或 BIGINT）
  2. 若目标库已建为 SMALLINT，执行： ALTER TABLE table_name MODIFY COLUMN column_name INT;
  3. 核对全链路（源表声明 → 中间映射 → 目标表）类型一致，避免被自动收窄
1.17 不支持的字段元数据类型field type 230​

错误信息： Unsupported table metadata field type 230；任务之前正常，后续频繁异常停止，TaskManager 日志中 Error during binlog processing，Last offset stored = {... file=mysql-bin.xxxxx, pos=xxxx ...}。

问题原因：

  1. 源端为 MySQL 8.0.x，binlog 是实例级的，CDC 会读取整个实例的 binlog
  2. 当前同步表本身结构正常，但同实例下其它库/表使用了 CDC 不支持的 MySQL 8.0 新特性，污染了 binlog 解析，典型如：
    • JSON 多值索引（multi-valued index），例如对 json_extract 结果建 cast(... as char(255) array) 的 KEY
    • 虚拟/存储生成列（GENERATED ALWAYS AS ... STORED）引用 JSON 函数
  3. 这些特性产生的 binlog 元数据字段类型（如 230）当前连接器无法解析，导致整条 binlog 流处理中断

排查方法：

  1. 根据报错中的 file 与 pos 定位对应的 mysql-bin.xxxxx 文件，下载后用 binlog 解析工具分析出问题事件归属的表
  2. 重点排查同实例下使用了 JSON 多值索引、JSON 生成列的表（不一定是当前同步表）

解决方案：

  1. 去掉触发问题的不支持索引/隐藏（生成）字段，或将相关表迁出该实例
  2. 改用支持该特性的采集方案（如 hdp 链路支持）
  3. 上线 MySQL 8.0 新特性前，评估其对实例级 binlog 采集的兼容性影响
1.18 零值日期Zero date value prohibited​

错误信息： Zero date value prohibited; nested exception is java.sql.SQLException: Zero date value prohibited（mysql 作为源预览源表数据时报错）

问题原因：

  1. 源表存在 '0000-00-00' / '0000-00-00 00:00:00' 等零值日期
  2. 较新 JDBC 驱动默认禁止读取零值日期，直接抛异常

解决方案：

  1. 在数据源"其他连接串参数"中填写（供测试连接/预览使用）： zeroDateTimeBehavior=convertToNull
  2. 在"其他连接器选项"中填写（供任务运行时使用，需 Flink CDC 选项格式）： jdbc.properties.zeroDateTimeBehavior=convertToNull
  3. 保存后停止并重新发布任务使配置生效（resume 不会重新加载数据源配置）
1.19 连接池超时与单账号同步任务数上限​

错误信息： java.sql.SQLTransientConnectionException: HikariPool-x - Connection is not available, request timed out after 10000ms

问题原因：

  1. MySQL 连接数接近上限，连接池拿不到可用连接（同一账号其它任务正常，但新建任务连接失败是典型特征）
  2. 实测同一个 MySQL 账号创建的同步任务数存在上限（本地 MySQL 与阿里云 RDS 实测约为 20 个/账号），超过后新任务连接报此错。该限制源自 MySQL 自身机制，并非数据集成限制，且暂未找到可解除该限制的官方参数说明

排查方法：

  1. 登录 MySQL 查看连接与上限： SHOW PROCESSLIST; SHOW VARIABLES LIKE 'max_connections';
  2. 若连接数接近上限，瓶颈在 MySQL 连接数（见 1.11）
  3. 若 max_connections 充足但仍报错，多为单账号同步任务数已达上限（旧任务正常、新任务全部连接失败）

解决方案：

  1. 连接数不足：适当调大 max_connections（如 150 → 500）
  2. 单账号任务数达上限：另建新的 MySQL 账号，用新账号创建后续同步任务
  3. 规划账号分配：按业务/任务批次拆分多个采集账号，单账号承载的任务数控制在上限以内

2. Oracle相关问题​

2.1 监听连接异常​

错误信息： ORA-12516, TNS:listener could not find available handler with matching protocol stack

问题原因：

  1. 数据库连接池中的并发连接数超过了监听程序的处理能力
  2. 服务器资源不足（CPU、内存、磁盘空间等）
  3. 网络连接不稳定

解决方案：

  1. 检查并调整数据库连接池配置，增加最大并发连接数
  2. 确保服务器资源充足：
    • 检查CPU使用率
    • 增加内存分配
    • 确保磁盘空间充足
  3. 检查网络连接的稳定性，确保无丢包和高延迟
2.2 CDC字段解析错误​

错误信息： DataException: file is not a valid field name

问题原因：

  1. Oracle CDC 3.0及以下版本在处理某些特殊字段时存在bug
  2. 字段命名不规范导致解析失败

解决方案：

  1. 检查表结构，避免使用Oracle保留关键字作为字段名
  2. 参考Issue：https://github.com/apache/flink-cdc/pull/2315
2.3 表主键识别问题​

错误信息： Oracle数据库表存在主键，但系统提示找不到主键

问题原因：

  1. 数据库账户缺少读取schema的权限
  2. 主键定义不规范

解决方案：

  1. 授予用户以下权限： GRANT SELECT ON ALL_CONSTRAINTS TO username; GRANT SELECT ON ALL_CONS_COLUMNS TO username; GRANT SELECT ON ALL_TAB_COLUMNS TO username;

  2. 检查主键定义： SELECT constraint_name, constraint_type, table_name FROM user_constraints WHERE table_name = 'YOUR_TABLE';

2.4 表空间不足​

错误信息： ORA-01653: unable to extend table xxx by xxx in tablespace xxx

问题原因：

  1. 表空间空间不足
  2. 数据文件无法自动扩展
  3. 磁盘空间不足

解决方案：

  1. 检查表空间使用情况： SELECT tablespace_name, bytes/1024/1024 MB, maxbytes/1024/1024 MAX_MB, user_bytes/1024/1024 USED_MB FROM dba_data_files;

  2. 增加数据文件： ALTER TABLESPACE tablespace_name ADD DATAFILE 'path/filename.dbf' SIZE 100M AUTOEXTEND ON NEXT 10M;

2.5 归档日志空间不足​

错误信息： ORA-00257: archiver error. Connect internal only, until freed

问题原因：

  1. 归档目的地空间不足
  2. 归档日志未及时清理
  3. 归档产生速度过快

解决方案：

  1. 检查归档日志使用情况： SELECT * FROM v$flash_recovery_area_usage;

  2. 清理归档日志： RMAN> DELETE ARCHIVELOG ALL COMPLETED BEFORE 'SYSDATE-3';

2.6 Oracle监听器服务名识别错误​

错误信息： ORA-12514, TNS:listener does not currently know of service requested in connect descriptor

问题原因：

  1. 连接字符串中的服务名(SERVICE_NAME)或SID不正确
  2. Oracle数据库实例未运行*
  3. Oracle监听器未正常启动或配置有误*
  4. 监听器尚未注册请求的服务*
  5. TNS配置不正确*
2.7 监听器拒绝连接​

错误信息： Listener refused the connection with the following error: ORA-12514, TNS:listener does not currently know of service requested in connect descriptor (CONNECTION_ID=Fy668w9sSS+ZXlTWboSNzA==)

问题原因：

  1. 监听器未正确配置请求的服务名。
  2. 数据库实例未注册到监听器。
  3. 连接描述符中的服务名拼写错误或不存在。
  4. 监听器未启动或配置错误。

解决方案：

  1. 检查监听器配置： 确保 listener.ora 文件中的服务名配置正确，并且与数据库实例的服务名一致。

  2. 检查数据库实例注册： 确认数据库实例已成功注册到监听器。可以通过以下命令检查：

    SELECT INSTANCE_NAME, STATUS FROM V$INSTANCE;

  3. 如果实例未注册，尝试手动注册：

    ALTER SYSTEM REGISTER;

  4. 检查连接描述符： 确保连接字符串中的服务名正确无误，并且与数据库实例的服务名一致。

2.8 Oracle增量数据不同步问题​

错误信息：Flink Oracle CDC增量数据同步不完整、漏数据或完全无法捕获数据变更。

问题原因：

  1. 数据库级别未启用最小补充日志。
  2. 表级别未配置适当的补充日志。
  3. 启用了补充日志，但配置类型不正确（如只配置了主键日志，但需要全列日志）。
  4. 对象所有者(Schema)与补充日志配置的所有者不匹配。
  5. CDC用户没有足够的权限查看日志内容。
  6. 归档日志被过早清理，导致CDC无法读取变更记录。
  7. 查询是否未提交事物，部分数据库客户端工具不会自动提交事物。

解决方案：

  1. 检查数据库级别补充日志配置：

    SELECT SUPPLEMENTAL_LOG_DATA_MIN as "最小补充日志",
    SUPPLEMENTAL_LOG_DATA_PK as "主键补充日志",
    SUPPLEMENTAL_LOG_DATA_ALL as "全列补充日志" FROM V$DATABASE; 确保至少启用了最小补充日志（SUPPLEMENTAL_LOG_DATA_MIN = 'YES'）。如果未启用，执行： ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

  2. 检查表级别补充日志配置：

    -- 检查特定表的补充日志配置 SELECT LOG_GROUP_NAME as "日志组名称", LOG_GROUP_TYPE as "日志组类型" FROM DBA_LOG_GROUPS WHERE OWNER = '表所有者' AND TABLE_NAME = '表名'; 根据CDC同步需求，为表添加适当的补充日志： -- 为表添加主键补充日志 ALTER TABLE 表所有者.表名 ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

    -- 如果表没有主键，但有唯一键 ALTER TABLE 表所有者.表名 ADD SUPPLEMENTAL LOG DATA (UNIQUE) COLUMNS;

    -- 如果需要捕获所有列的变更 ALTER TABLE 表所有者.表名 ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

  3. 检查并修正对象所有者不匹配问题：

    -- 检查实际表所有者和表名的大小写 SELECT OWNER, TABLE_NAME FROM ALL_TABLES WHERE UPPER(TABLE_NAME) = UPPER('表名');

  4. 验证CDC用户权限：确保CDC用户有足够的权限读取补充日志：

    -- 检查用户权限 SELECT * FROM SESSION_PRIVS;

    -- 授予访问日志和数据字典的权限 GRANT SELECT ON SYS.V_$DATABASE TO cdc用户; GRANT SELECT ON SYS.V_$ARCHIVED_LOG TO cdc用户; GRANT SELECT ON SYS.V_$LOGMNR_CONTENTS TO cdc用户; GRANT SELECT_CATALOG_ROLE TO cdc用户;

注意事项：

  1. 启用全列补充日志会显著增加重做日志的大小，可能影响数据库性能。在高事务量环境中，应谨慎权衡并选择最小必要的补充日志级别。
  2. 补充日志配置更改不会影响已生成的归档日志。如果需要对历史数据进行CDC同步，必须在产生这些变更前就配置好补充日志。
  3. 在RAC环境中，确保补充日志配置对所有实例都有效。
  4. 注意表结构变更对CDC的影响，特别是主键或唯一键的变更可能需要同步调整补充日志配置。
2.9 存储过程使用TRUNCATE无法触发CDC同步​

错误信息：错误:1292，Position:0，Sql-BEGIN sys.dbms logmnr.startlogmnr(startScn =>'1027988E04068'，endscn=>'102798824067'，OPTIONS=> DBMS_LOGMNR.DICT FROM_ONLIN ECATALOG+ DBMS LOGMN R.CONTINUOUS MINE+ DB MSLOGMNR.NO ROWID IN STMT):END:，OriginalSql=B EGINsys.dbms logmnr.start logmnr(startScn=>'10279880 4068',endScn=>'102798824 067'，OPTIONS=> DBMS LO GMNR.DICT FROM ONLINE CATALOG+DBMS LOGMNR。 CONTINUOUS MINE+ DBMS LOGMNR.NO ROWID IN ST MT);END;，错误消息=ORA-0 1292 当前 LogMiner 会话没有特定的日志文件

问题原因：

  1. TRUNCATE TABLE 属于 DDL 操作，不属于标准的 DML（如 DELETE）。
  2. Oracle 的 LogMiner 和大部分 CDC 采集工具仅能捕获 DML 变更（INSERT、UPDATE、DELETE），无法捕获 TRUNCATE。
  3. 由于 TRUNCATE 不会写入可供 CDC 采集的 REDO 日志，导致下游同步链路无法感知该操作。

解决方案：

  1. 禁止在需要 CDC 同步的表上使用 TRUNCATE TABLE 操作。
  2. 改用 DELETE FROM table; COMMIT; 语句清空表数据，确保该操作会写入 REDO 日志，CDC 能正常采集并同步 delete 事件到下游。
  3. 对已出现数据不一致的下游表，可手动执行清空操作后，重新全量同步一次数据，保证一致性。
2.10 归档日志未设置为全列导致同步字段为NULL​

问题描述：

在 Flink Oracle CDC 同步任务中，如果 Oracle 归档日志(LogMiner)参数未设置为全列模式，而是仅保留主键或者部分字段，则下游表（如 MySQL、Kafka 等）同步时，只有主键字段有实际值，其余字段为 NULL。问题原因：

  1. Oracle 归档日志的 LogMiner 组件支持配置抓取的列范围，如仅主键、部分字段或全字段。
  2. 若归档日志未设置为全列模式，则 redo log 仅记录被配置的字段数据，未配置的字段不会写入日志。
  3. Flink CDC 在解析 redo/归档日志时，只能提取日志中实际存在的字段，未写入日志的字段在下游表中表现为 NULL。
  4. 这种情况即使 Flink 表结构声明了所有字段，未被归档日志采集的字段依旧无法同步真实值。

解决方案：

  1. 确保 Oracle 归档日志（LogMiner）设置为全列（Full Column）模式，即所有需要同步的字段都被记录到日志。
  2. 配置全列同步后，重启 Flink CDC 任务，确保所有数据变更都能被完整采集。
  3. 对已经出现字段为 NULL 的下游表，需在修正归档日志配置后，重新进行全量同步，以修复历史数据缺失。
2.11 快照过旧ORA-01555​

错误信息： ORA-01555: snapshot too old: rollback segment number xxx with name "xxx" too small

问题原因：

  1. 全量快照查询时间过长，期间源表数据持续变更，UNDO 表空间无法保留足够的读一致性版本
  2. UNDO_RETENTION 设置过小或 UNDO 表空间不足
  3. 大表快照 + 高并发写入叠加

解决方案：

  1. 增大 UNDO 保留与表空间（需 DBA）： ALTER SYSTEM SET UNDO_RETENTION = 7200; -- 必要时扩大 UNDO 表空间或开启 AUTOEXTEND
  2. 调小 chunk size 缩短单次查询时长（见 Flink 章节 2.1）
  3. 尽量在源库低峰期执行全量快照
  4. 评估是否可跳过全量、仅做增量（确认不需要存量）
2.12 表或视图不存在ORA-00942​

错误信息： ORA-00942: table or view does not exist

问题原因：

  1. CDC 账号对目标表无 SELECT 权限（Oracle 区分 schema，跨 schema 需显式授权）
  2. 表名/owner 大小写不匹配（Oracle 默认大写，带引号的小写名需精确匹配）
  3. 配置的 schema-name / table 与实际不符
  4. 缺少访问数据字典或 LogMiner 相关视图的权限

解决方案：

  1. 授予表与字典权限： GRANT SELECT ON owner.table_name TO cdc_user; GRANT SELECT_CATALOG_ROLE TO cdc_user;
  2. 核对实际 owner 与表名大小写： SELECT OWNER, TABLE_NAME FROM ALL_TABLES WHERE UPPER(TABLE_NAME)=UPPER('表名');
  3. 配置中 schema/表名按数据库实际大小写填写
  4. 确认 LogMiner 所需 V$ 视图权限齐全（见 2.8）
2.13 PDB容器/多租户连接问题​

错误信息： 连接 Oracle 12c+ 多租户实例时报无法找到服务/找不到表，或 LogMiner 无法读取 CDB 重做日志。

问题原因：

  1. 连接串误连到 CDB$ROOT 而非业务 PDB（或相反）
  2. CDC 用户需为 common user（C##前缀）才能跨容器访问重做日志
  3. PDB 与 CDB 的服务名/权限边界配置不当

解决方案：

  1. 业务数据连接对应 PDB 的服务名；LogMiner 读取重做日志需有 CDB 级权限
  2. 创建具备跨容器权限的 common 用户（C##前缀）并授予 LOGMINING、SELECT ANY TRANSACTION 等
  3. 确认 enable_goldengate_replication / 补充日志在容器层面正确开启
  4. 多租户环境配置较复杂，必要时联系 DBA 协助规划用户与权限
2.14 共享池内存不足ORA-04031​

错误信息： ORA-04031: unable to allocate xxx bytes of shared memory ("shared pool",...)

问题原因：

  1. LogMiner 持续运行消耗共享池内存，叠加业务负载导致 SGA 共享池不足
  2. SGA/共享池规格偏小
  3. 硬解析过多、内存碎片化

解决方案：

  1. 检查并适当增大共享池/SGA（需 DBA）： ALTER SYSTEM SET SHARED_POOL_SIZE = '512M';
  2. 评估 LogMiner 挖掘频率与范围，避免长时间持续高强度挖掘
  3. 优化业务侧硬解析，使用绑定变量
  4. 内存类参数调整通常需 DBA 评估实例整体规划
2.15 跨Schema同名表导致多主键无法同步​

错误信息： 选择 Oracle 数据表时提示"该表有多个主键，暂时不支持同步"。

问题原因：

  1. 同一实例下多个不同 schema（owner）存在同名表，且各自都定义了主键
  2. 识别主键时通过 ALL_CONSTRAINTS / ALL_CONS_COLUMNS 查询，若未严格限定 owner，会把多个 schema 的同名表主键都查出来，表现为"多个主键"
  3. 常见于历史迁移场景（如 EKP、EKP1、EKPTEST 三个 schema 下都有 SYS_ORG_ELEMENT 且都有主键）

排查方法：

  1. 用以下 SQL 确认是否多个 owner 下存在同名表主键： SELECT owner, constraint_name, constraint_type, table_name FROM all_constraints WHERE table_name = 'SYS_ORG_ELEMENT' AND constraint_type = 'P';
  2. 若返回多行且 owner 不同，即为本问题

解决方案：

  1. 理想做法是限定 owner 只识别目标 schema 的主键；但若同步账号有权限访问多个同名表的 schema，限定 owner 仍可能不生效
  2. 客户线上业务无法调整 schema/表结构时，该表暂无法通过标准方式同步，需改用其它同步方式
  3. 规划上建议避免多 schema 同名表 + 同名主键并存；新建采集账号时尽量只授予目标 schema 的访问权限，减少同名表干扰
2.16 Oracle11g(11.2.0.4)PGA内存溢出已知bug​

问题描述： 源端为 Oracle 11g（具体 11.2.0.4.0），同步运行中出现内存溢出（out of memory）。

问题原因：

  1. 该 Oracle 版本存在已知 bug：在 PGA 内存配置较小的情况下会出现内存溢出
  2. 属数据库版本自身缺陷，非采集链路问题

解决方案：

  1. 适当调大 PGA 相关内存（如 PGA_AGGREGATE_TARGET），规避该 bug 的触发条件（需 DBA 评估）
  2. 参考 Oracle 官方说明（Doc/Bug 1934141.1 及社区讨论）评估打补丁或升级小版本
  3. 若条件允许，升级到不受该 bug 影响的版本

3. SQLServer相关问题​

3.1 SSL连接失败​

错误信息： The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "PKIX path building failed"

问题原因：

  1. SQL Server驱动试图建立SSL加密连接失败
  2. 证书验证路径构建失败-
  3. 默认情况下驱动会尝试使用SSL加密连接

解决方案：

  1. 在数据源配置中添加参数：

    • encrypt=false
    • trustServerCertificate=true

  2. 或配置正确的证书：

    • 导入SQL Server的SSL证书
    • 确保证书链完整
3.2 CDC同步异常​

错误信息： SQLServer数据库及表已启用CDC，但创建同步任务后无增量数据同步

问题原因：

  1. 数据库恢复模式被修改为简单模式
  2. CDC功能需要数据库处于完整恢复模式才能正常工作
  3. CDC代理作业未运行

解决方案：

  1. 检查并修改数据库恢复模式： ALTER DATABASE YourDatabase SET RECOVERY FULL;

  2. 验证CDC是否正常： SELECT name, is_cdc_enabled FROM sys.databases WHERE database_id = DB_ID();

SELECT name, is_tracked_by_cdc FROM sys.tables WHERE object_id = OBJECT_ID('YourTable');

  1. 检查CDC代理作业： EXEC sys.sp_cdc_help_jobs;
3.3 事务日志满​

错误信息： Could not allocate space for object in database 'xxx' because the 'PRIMARY' filegroup is full

问题原因：

  1. 事务日志空间不足
  2. 事务日志未及时备份
  3. 大事务导致日志增长过快

解决方案：

  1. 检查日志空间： DBCC SQLPERF(LOGSPACE);

  2. 收缩日志文件： BACKUP LOG DatabaseName WITH TRUNCATE_ONLY; DBCC SHRINKFILE(LogFileName);

3.4 死锁问题​

错误信息： Transaction (Process ID xx) was deadlocked on lock resources with another process and has been chosen as the deadlock victim

问题原因：

  1. 并发事务互相等待资源
  2. 事务执行时间过长
  3. 锁升级导致死锁

解决方案：

  1. 查看死锁信息： SELECT * FROM sys.dm_tran_locks;

  2. 优化事务处理：

  • 减少事务范围
  • 统一访问顺序
  • 添加适当的索引
3.5 TLS1.0协议不兼容​

问题描述：

当源数据库为 SQL Server，并通过 JDBC 参数设置不使用 SSL 时，测试连接依然失败，报错信息如下：

  • ErrorCode=0, SQLState=08S01

  • 日志中出现类似错误：

    复制

    Caused by: The server selected protocol version TLS10 is not accepted by client preferences [TLS13, TLS12]。

问题原因：

  1. SQL Server 即使未强制启用 SSL 连接，底层协议仍会自生成一个证书，对登录数据包进行加密。
  2. 较低版本的 SQL Server 可能默认只支持 TLS1.0 协议。
  3. 当前使用的 JRE（Java 运行环境）出于安全考虑，默认禁用了 TLS1.0 及以下协议。
  4. 因此，客户端无法与服务器协商出兼容的 TLS 协议，导致连接失败。

解决方案：

  1. 建议优先升级 SQL Server 端的 TLS 协议，支持 TLS1.2 或 TLS1.3。
    • 推荐在 SQL Server 服务器上升级操作系统及相关补丁，并按照 微软官方文档 启用更高版本的 TLS 协议。
    • 升级后重启 SQL Server 服务。
3.6 SQLServer字段类型datetime2同步异常​

异常描述：

  • SQL Server 源表字段为 datetime2 类型，数据中存在 2262 年以后的日期（如 9998 年）。

  • 使用 Flink CDC、JDBC 等 Java 生态工具同步到下游（如 Kafka、MySQL、Hudi 等）时，任务报错，常见堆栈为：

    复制

    Caused by: java.lang.IllegalArgumentException
      at org.apache.flink.table.data.TimestampData.fromEpochMillis(...)
      ...
    • 即使下游目标字段为字符串类型，也会出现该异常。

原因分析：

  • Java 和 Flink 的时间类型以 long 存储毫秒数，最大支持到 2262-04-11 23:47:16.854。
  • 超过此时间的数据，Flink CDC 解析时无法转换，直接报错。

适用范围：

  • 适用于所有通过 Java 生态工具同步 SQL Server datetime2 字段的场景。

建议处理：

  1. 源表数据建议控制在 2262 年以内，避免写入超大日期。
  2. 如确有需要存储更大日期，建议将该字段类型设计为字符串，且同步链路不做时间类型解析。
3.7 登录失败Login failed 18456​

错误信息： Login failed for user 'xxx'. (Microsoft SQL Server, Error: 18456)

问题原因：

  1. 用户名或密码错误
  2. 账号被禁用、过期，或仅允许 Windows 认证而非 SQL 认证
  3. 该登录名无权访问目标数据库（default database 不可达）
  4. 账号被锁定或超出登录策略

解决方案：

  1. 核对账号密码；确认实例启用了 SQL Server 与 Windows 混合认证模式
  2. 检查登录名状态与默认数据库： SELECT name, is_disabled FROM sys.sql_logins WHERE name='xxx';
  3. 为该登录映射目标数据库用户并授予读取/CDC 权限
  4. 查看 SQL Server 错误日志中 18456 的 state 码进一步定位（state 指明具体原因）
3.8 CDC清理作业导致变更丢失​

错误信息： 增量同步出现数据缺口，或任务报找不到对应的 LSN/变更记录。

问题原因：

  1. SQL Server CDC 的 cleanup 作业按 retention（默认约 3 天）清理变更表，任务停机过久导致所需变更被清理
  2. 变更表数据量大被清理过快
  3. CDC capture/cleanup 作业配置不当

解决方案：

  1. 调大 CDC 保留时长，给停机/积压留足空间： EXEC sys.sp_cdc_change_job @job_type='cleanup', @retention=4320; -- 分钟，约3天，可加大
  2. 控制任务停机时间不超过 retention
  3. 变更已被清理且无法续传时，需重新做全量同步
  4. 监控 CDC 变更表与 capture/cleanup 作业运行状态（EXEC sys.sp_cdc_help_jobs）
3.9 排序规则冲突Collation conflict​

错误信息： Cannot resolve the collation conflict between "xxx" and "yyy" in the equal to operation.

问题原因：

  1. 数据库/表/列使用了不同的排序规则（collation），关联或比较时冲突
  2. 源库与目标库 collation 不一致，导致字符串比较/去重异常
  3. 临时表与源表 collation 不匹配

解决方案：

  1. 统一相关列的 collation，或在比较时显式指定 COLLATE
  2. 目标库建表时与源库保持一致的 collation
  3. 涉及中文/大小写敏感场景，确认 collation 的语言与 CI/CS、AI/AS 设置符合预期
  4. 如仅同步不做库内比较，确保下游表字段 collation 能容纳源数据字符集
3.10 表结构变更后增量不同步(需重建表CDC)​

问题描述： 已创建过同步任务的 SQL Server 表，修改字段（增删改列）后，新的变更无法同步。

问题原因：

  1. SQL Server CDC 机制只会按"开启 CDC 时的表结构"捕获变更
  2. 表结构变动后，原 capture instance 仍按旧结构采集，导致变更不被正确捕获

解决方案：

  1. 对变更后的表禁用并重新启用 CDC（替换 schema_name / table_name）： -- 禁用表的CDC EXEC sys.sp_cdc_disable_table @source_schema = 'schema_name', @source_name = 'table_name', @capture_instance = 'all';

    -- 重新启用表的CDC EXEC sys.sp_cdc_enable_table @source_schema = 'schema_name', @source_name = 'table_name', @role_name = NULL, @supports_net_changes = 0;

  2. 重新启用后，按需重新发布同步任务

  3. 规范：对已纳入同步的表做 DDL 前，先评估是否需要重建 CDC，避免静默丢数据

4. PostgreSQL相关问题​

4.1 版本兼容问题​

错误信息： PG 9.6版本同步任务无法同步数据

问题原因：

  1. PostgreSQL 9.6版本不支持pgoutput编解码扩展
  2. 部分同步功能需要更高版本支持
  3. 复制槽配置不正确

解决方案：

  1. 安装并配置wal2json插件： CREATE EXTENSION IF NOT EXISTS wal2json;
  2. 修改postgresql.conf配置：
    • wal_level = logical
    • max_replication_slots = 10
    • max_wal_senders = 10
  3. 检查复制槽状态：
    • SELECT * FROM pg_replication_slots;
4.2 连接数超限​

错误信息： FATAL: remaining connection slots are reserved for non-replication superuser connections

问题原因：

  1. 达到max_connections限制
  2. 连接未及时释放
  3. 连接池配置不合理

解决方案：

  1. 检查当前连接： SELECT * FROM pg_stat_activity;

  2. 调整连接数限制： ALTER SYSTEM SET max_connections = '200';

4.3 复制延迟过大​

错误信息： ERROR: replication slot "xxx" is active but not used for too long

问题原因：

  1. 网络带宽不足
  2. 源库写入压力大
  3. 复制进程负载高

解决方案：

  1. 监控复制延迟： SELECT slot_name, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) as replication_lag FROM pg_replication_slots;

  2. 优化复制配置： ALTER SYSTEM SET max_wal_senders = 10; ALTER SYSTEM SET wal_keep_segments = 64;

4.4 从库没有复制连接主库的权限​

错误信息： no pg_hba.conf entry for replication connection from host "192.168.1.103", user "postgres", SSL off

问题原因：

  1. PostgreSQL 数据库的访问控制文件 pg_hba.conf 未为该主机、用户和连接类型（如 replication）配置允许访问的规则。

当外部服务（如数据同步、CDC、备份等）尝试以 replication 模式连接 PostgreSQL 时，若 pg_hba.conf 中没有相应的条目，则会被拒绝连接。

解决方案：

  1. 编辑 PostgreSQL 的 pg_hba.conf 文件，为需要访问的主机、用户和 replication 连接类型添加一条允许规则。例如，允许 192.168.1.103 主机使用 postgres 用户进行 replication 连接：

    oxygene

    复制

    # TYPE    DATABASE    USER        ADDRESS             METHOD
    host      replication  postgres   192.168.1.103/32    trust

    如需开启 SSL，可将 SSL off 部分调整为支持 SSL 的配置。

  2. 保存 pg_hba.conf 文件后，需重载 PostgreSQL 配置生效：

    bash

    复制

    pg_ctl reload
    # 或
    systemctl reload postgresql
    # 或
    SELECT pg_reload_conf();

  3. 建议：生产环境建议使用更安全的认证方式（如 md5），不要直接使用 trust，并严格限制允许的 IP 范围。

4.5 权限异常：permission denied for database XXX​

问题原因：

  1. 当前连接使用的数据库用户没有访问目标数据库的权限。
  2. 可能是该用户未被授权，或被限制连接特定数据库。

解决方案：

  1. 确认连接使用的用户名，确保该用户已被授权访问目标数据库。
  2. 可能需要superuser账户才行。
4.6 复制槽堆积导致WAL磁盘写满​

错误信息： 源库磁盘报警/写满，或 No space left on device；pg_replication_slots 中槽 active 为 false 但 WAL 持续堆积。

问题原因：

  1. CDC 任务长时间停止或消费缓慢，复制槽（replication slot）一直未推进 confirmed_flush_lsn
  2. PostgreSQL 为保留未确认的 WAL 不能回收，WAL 持续累积撑满磁盘
  3. 任务删除后未清理对应的复制槽，成为"僵尸槽"

解决方案：

  1. 查看槽与堆积量： SELECT slot_name, active, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS lag FROM pg_replication_slots;
  2. 尽快恢复任务消费，或对确认废弃的槽手动删除释放 WAL： SELECT pg_drop_replication_slot('slot_name'); -- 删除后该任务需重做全量
  3. 设置上限避免无限堆积（PG13+）： ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';
  4. 建立监控，任务长时间停机前应评估对源库磁盘的影响
4.7 发布Publication缺失或未含目标表​

错误信息： publication "xxx" does not exist / 增量无数据但任务无明显报错。

问题原因：

  1. pgoutput 逻辑解码需要 publication，未创建或名称不匹配
  2. publication 创建时未包含目标表（FOR TABLE 范围不全）
  3. 新增表后未把表加入 publication

解决方案：

  1. 检查/创建 publication： SELECT * FROM pg_publication; SELECT * FROM pg_publication_tables WHERE pubname='xxx'; CREATE PUBLICATION xxx FOR TABLE schema.table1, schema.table2;
  2. 新增表时追加进 publication： ALTER PUBLICATION xxx ADD TABLE schema.new_table;
  3. 确认 wal_level = logical 且复制槽、publication 名称与任务配置一致
  4. 如使用 FOR ALL TABLES，确认账号有相应权限
4.8 大字段TOAST更新值丢失(REPLICA IDENTITY)​

问题描述： 更新仅改了部分列时，下游同步到的大字段（text/jsonb 等 TOAST 存储字段）值变为空或保持旧值。

问题原因：

  1. 表 REPLICA IDENTITY 为 DEFAULT，UPDATE 时未变更的 TOAST 大字段不会写入 WAL
  2. 逻辑解码拿不到未变更的大字段值，下游表现为缺失
  3. 无主键表未设置 REPLICA IDENTITY FULL

解决方案：

  1. 对需要完整行镜像的表设置全行标识： ALTER TABLE schema.table REPLICA IDENTITY FULL;
  2. 注意 FULL 会增大 WAL 体积，按需在关键表上启用
  3. 有主键表通常用主键标识即可，仅大字段缺失场景才需 FULL
  4. 修改后对已出现缺失的下游数据重新全量同步修复
4.9 逻辑复制槽数量用完all replication slots are in use​

错误信息： org.apache.flink.runtime.JobException: Recovery is suppressed by FixedDelayRestartBackoffTimeStrategy ... Caused by: io.debezium.DebeziumException: Creation of replication slot failed Caused by: org.postgresql.util.PSQLException: ERROR: all replication slots are in use Hint: Free one or increase max_replication_slots.

问题原因：

  1. 每个 PG CDC 任务运行时会占用一个逻辑复制槽，并发任务数超过 max_replication_slots / max_wal_senders 上限
  2. 旧任务遗留的"僵尸槽"（active=false）一直占用名额未释放

排查方法：

  1. 查看当前上限： SELECT name, setting FROM pg_settings WHERE name IN ('max_replication_slots','max_wal_senders');
  2. 查看已存在的槽及是否在用： SELECT slot_name, active, database, plugin, restart_lsn FROM pg_replication_slots; （active = f 表示当前未被使用，可能是遗留槽）

解决方案：

  1. 方案一：调大上限（按需并发量设置，建议预留充足，可调至数百）： -- 配置文件 postgresql.conf max_replication_slots = 20 max_wal_senders = 20 -- 修改后重启数据库；或在线： ALTER SYSTEM SET max_replication_slots = 20; SELECT pg_reload_conf(); （部分参数需重启方可生效，以数据库提示为准）
  2. 方案二：释放无用槽，删除前务必确认对应任务已废弃： SELECT pg_drop_replication_slot('your_old_slot_name');
  3. 建立运维规范：任务删除时清理其复制槽，避免槽名额被僵尸槽长期占用
4.10 字符类型写入jsonb需stringtype=unspecified​

问题描述： 将字符串/JSON 文本同步写入 PostgreSQL 的 jsonb 字段时失败。

问题原因：

  1. PG 的 jsonb 是二进制 JSON 类型，不直接兼容字符串写入，即便内容是合法 JSON 文本也不会自动转换
  2. JDBC 默认以字符串类型绑定参数，与 jsonb 列类型不匹配

解决方案：

  1. 在 PostgreSQL 数据源的"其他连接串参数"中添加，让驱动对字符串做类型自适应转换： stringtype=unspecified
  2. 配置后字符串可被服务端按目标列类型（jsonb）正确转换写入
  3. 保存后重新发布任务使配置生效
4.11 非superuser账号创建同步任务(权限管控场景)​

背景： PostgreSQL CDC 默认需要拥有 superuser 权限的账号才能正常创建同步任务（创建 publication FOR ALL TABLES、创建/读取逻辑复制槽等动作默认需要超级权限）。

问题描述： 部分客户对数据库账号有严格权限管控，不允许对外提供 superuser 最高权限账号，导致"创建同步任务需要 superuser"的要求无法满足。

解决思路： 由 superuser 账号预先完成只需一次的"发布(publication)"创建，之后改用仅授予必要权限（REPLICATION + CONNECT + USAGE + SELECT）的普通账号来创建并运行同步任务。发布名称必须为 dbz_publication（Debezium 默认发布名）。

解决方案：

  1. 开启 PG 的逻辑复制（CDC 前提），按部署方式二选一：

    本地部署：修改 postgresql.conf 后重启：

    # 更改 wal 日志方式为 logical
    wal_level = logical
    # 复制槽最大数量（默认10），flink-cdc 默认一张表占一个 slot
    max_replication_slots = 100
    # wal 发送最大进程数（默认10），与上面的 slots 设为一致
    max_wal_senders = 100
    # 可适当调大空闲复制连接中断超时（默认60s）
    # wal_sender_timeout = 180s

    RDS-PG（如阿里云）：在控制台修改参数 wal_level、max_replication_slots、max_wal_senders，提交后重启实例生效。

  2. 用 superuser（如 postgres）登录，为所有表创建发布（仅此步需要超级权限，发布名必须为 dbz_publication）：

    CREATE PUBLICATION dbz_publication FOR ALL TABLES;
    -- 查看发布： SELECT * FROM pg_publication;
    -- 查看已发布的表： SELECT * FROM pg_publication_tables;

  3. 创建非 superuser 普通账号并最小化授权（库名/账号名按需替换，下例库 flink_test、账号 flink_user）：

    -- 创建用户
    CREATE USER flink_user WITH PASSWORD 'flink123';
    -- 授予 REPLICATION 权限（创建/读取复制槽所需）
    ALTER ROLE flink_user WITH REPLICATION;
    -- 授权数据库连接
    GRANT CONNECT ON DATABASE flink_test TO flink_user;
    -- 授权 Schema 访问
    GRANT USAGE ON SCHEMA public TO flink_user;
    -- 授权表查询：单表授权
    -- GRANT SELECT ON TABLE public.user_table TO flink_user;
    -- 或：把当前库 public 下所有表查询权限赋给用户
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO flink_user;

  4. 为需要同步的表设置 REPLICA IDENTITY FULL（确保 UPDATE/DELETE 能捕获完整前镜像，否则默认可能为 NOTHING 导致更新/删除数据丢失，参见 4.8）：

    ALTER TABLE public.user_table REPLICA IDENTITY FULL;
    -- 多个表分别执行
    -- ALTER TABLE public.other_table REPLICA IDENTITY FULL;
    -- 查看复制标识（值为 f 表示设置成功）
    -- SELECT relreplident FROM pg_class WHERE relname='user_table';

  5. 用 flink_user（非 superuser）创建并运行同步任务即可。

补充：为什么任务停止后复制槽不会自动删除

Flink CDC 的 PostgreSQL connector（底层基于 Debezium）启动时会创建一个逻辑复制槽，从 slot 读取 WAL 增量并保存消费位点（LSN）。任务正常停止时 Debezium 不会自动 drop 该 slot，因为它认为任务可能会重启/从 checkpoint 恢复；若 slot 被删，将无法从上次 LSN 续读，导致全量重跑或数据丢失。因此 slot 默认需手动管理（与 4.6 "复制槽堆积撑满 WAL" 同源）。

复制槽管理：

-- 查看所有复制槽及是否在用
SELECT slot_name, active, database, plugin, restart_lsn FROM pg_replication_slots;
-- 仅查未在用的遗留槽（注意：需要 WHERE 子句）
SELECT slot_name, active, database, plugin, restart_lsn
FROM pg_replication_slots WHERE active = false;
-- 删除确认废弃的无用槽（把 your_old_slot_name 换成上一步查到的 slot_name）
SELECT pg_drop_replication_slot('your_old_slot_name');

5. MongoDB相关问题​

5.1 副本集同步问题​

错误信息： 聚合表预览有数据，正式发布保存无数据

问题原因：

  1. MongoDB副本集未开启
  2. MongoDB版本过低
  3. 复制集配置不正确

解决方案：

  1. 开启MongoDB副本集：
rs.initiate({
   _id: "rs0",
   members: [
      { _id: 0, host: "localhost:27017" }
   ]
})

  1. 确认MongoDB版本，建议升级到4.0以上版本

  2. 验证复制集状态： rs.status()

5.2 Oplog窗口问题​

错误信息： Cannot find timestamp in oplog greater than or equal to timestamp

问题原因：

  1. Oplog大小设置过小
  2. 同步延迟导致Oplog数据过期
  3. 复制集负载过高

解决方案：

  1. 检查Oplog状态： db.printReplicationInfo()

  2. 调整Oplog大小：

db.adminCommand({
    "replSetResizeOplog": 1,
    "size": 16384
})
5.3 认证失败​

错误信息： Authentication failed for user xxx

问题原因：

  1. 用户认证机制不匹配
  2. 权限不足
  3. 认证数据库错误

解决方案：

  1. 检查用户权限： db.getUser("username")

  2. 授予必要权限： db.grantRolesToUser("username", ["readWrite", "XXX"] )

5.4 ChangeStream resume token失效​

错误信息： resume of change stream was not possible, as the resume point may no longer be in the oplog / ChangeStreamHistoryLost。

问题原因：

  1. 任务停机过久，断点对应的 oplog 已被覆盖（oplog 是固定大小循环写）
  2. oplog 窗口过小，承载不了停机/积压时间
  3. 复制集做过重大维护导致 oplog 不连续

解决方案：

  1. 增大 oplog 窗口以容纳更长停机（见 5.2）： db.adminCommand({ replSetResizeOplog: 1, size: 16384 })
  2. 用 db.printReplicationInfo() 评估 oplog 实际可回溯时间，控制停机不超过该窗口
  3. resume token 已失效无法续传时，需重新做一次全量同步
  4. CDC 任务建议基于 ChangeStream（需 MongoDB 4.0+ 副本集），并保证 oplog 充足
5.5 分片集群同步异常​

问题描述： 对分片集群（sharded cluster）做 CDC 时，出现漏数据、orphan 文档或连接对象错误。

问题原因：

  1. 连接到了单个 shard 的 mongod 而非 mongos 路由，导致只拿到部分数据
  2. 分片迁移（chunk migration）产生的 orphan 文档造成重复/异常
  3. 各 shard oplog 窗口不一致，个别 shard 断点失效
  4. 账号在分片集群上的权限不足（需在 admin 上有相应角色）

解决方案：

  1. CDC 连接分片集群应连 mongos 路由入口，由其统一汇聚 ChangeStream
  2. 确认 MongoDB 版本支持分片集群 ChangeStream（4.0+，部分特性需更高版本）
  3. 统一并充分配置各 shard 的 oplog 窗口
  4. 授予集群级读取权限，必要时使用 clusterMonitor / readAnyDatabase 等角色
  5. 关注 orphan 文档对下游一致性的影响，必要时在下游做去重

6. 明道云工作表(作为数据源)相关问题​

说明：本节针对以明道云"工作表"为数据源、同步到数据库/其它目的地的场景。工作表的字段以控件ID绑定、删除走回收站/物理删除、以及聚合表计算逻辑等特性，是这类问题的常见根因。

6.1 控件删除重建导致字段值为NULL​

问题描述： 下游/报表中某"选项"等字段在某段时间后持续为 NULL。

问题原因：

  1. 上游删除了原控件（如"店铺文本控件"），又新建了一个同名的"选项控件"
  2. 名称虽相同，但控件/字段的 ID 已变化；同步/映射按字段 ID 而非名称绑定，导致读不到值表现为 NULL

解决方案：

  1. 在配置层将映射重新绑定到新的控件/字段 ID，或恢复原控件并迁移数据
  2. 对已产生 NULL 的数据执行一次性回填修复
  3. 变更管控：
    • 禁止在生产直接"删除后新建同名控件"
    • 上线前做 Schema/字段ID Diff 校验并阻断不兼容变更
    • 监控关键字段 NULL 率，对新增/删除字段告警
6.2 仅显示字段或权限不足导致数据缺失​

问题描述： 内部 Web 工具查询某表显示"无数据/少数据"，怀疑同步缺失。

问题原因：

  1. Web 工具使用的账号/角色表或列权限不足，查询结果被过滤，造成"看起来缺失"
  2. 关联表中某字段被配置为"仅显示（Display Only）"，不参与保存/变更，不产生更新事件，因而不同步

解决方案：

  1. 用具备完整权限的账号在数据库执行原生 SQL 交叉验证；对齐 Web 工具与任务实际使用账号的 RBAC / 列权限 / 行权限
  2. 将"仅显示"的他表控件改为可存储，确保会触发更新事件/CDC
  3. 清理已有脏数据后重新同步
6.3 非rowid主键+工作流彻底删除导致同步中断​

错误信息： 监控报错（同步工作表数据到 MySQL）：Failed to deserialize consumer record ... Corrupt Debezium JSON message '{"op":"d","before":{"rowid":"xxxx"},"after":null}' ... Caused by: org.apache.flink.table.api.TableException: Column 'id' is NOT NULL, however, a null value is being written into it.

问题原因：

  1. 工作表选择了非 rowid 字段（如 id）作为同步主键
  2. 工作表通过工作流"彻底删除记录（不放入回收站）"
  3. 工作流产生的删除事件，内部推送给下游的 Debezium JSON 只包含 rowid，before 中没有 id 及其它字段
  4. 下游按 id 主键删除时拿不到 id，删除无法执行，且 id 列 NOT NULL 被写入 null 而报错，进而导致整个任务无法继续，后续新增/修改也都同步不了

解决方案：

  1. 首选：使用工作表的 rowid 作为同步主键（删除事件必带 rowid，能正常下发删除）
  2. 若必须用其它字段（如 id）作主键：避免使用工作流"彻底删除"操作（改为放入回收站等不丢字段的方式）
  3. 已出现任务中断的，修正主键/删除方式后重建任务并重新全量同步，修复一致性
  4. 可临时用 table.exec.sink.not-null-enforcer=DROP 静默丢弃此类记录，但会丢删除语义，不建议作为根治手段
6.4 聚合表计算字段在统计图中结果不准​

问题描述： 聚合表中的计算字段（如【数量完成率】=【销售数量】/【目标销售】、【销售完成率】=【销售额】/【目标销售额】）发布后单条计算正确；但在统计图中直接引用该聚合表计算字段做汇总时，相除结果不准确。

问题原因：

  1. 聚合表的公式是基于同步任务的单条记录逐条计算的
  2. 统计图做汇总时，不能直接套用聚合表已有的"单条相除"公式字段——分子分母应先各自汇总再相除，而非把每条的比值再聚合

解决方案：

  1. 在统计图里新增"计算值字段"，基于已汇总后的【销售数量】与【目标销售】（及销售额/目标销售额）再做一次相除
  2. 即：先 SUM 分子、SUM 分母，最后相除，避免"先逐条相除再聚合"导致的偏差
  3. 区分两类字段用途：聚合表计算字段用于单条/明细，统计图汇总比率用统计图自身的计算值字段

7. DB2相关问题​

7.1 字段类型不被CDC支持导致Agent无法启动​

问题描述： DB2 表中存在 CDC 不支持的字段类型时，会导致 CDC Agent 起不来，无法采集。

问题原因：

  1. DB2 CDC Agent 仅支持有限的字段类型集合，表中含其范围外的类型时 Agent 启动失败
  2. 常见不受支持类型多为特殊/图形/大对象等类型（如 GRAPHIC / VARGRAPHIC 等需结合实际版本确认）

解决方案：

  1. 核对待同步表的字段类型，识别出 CDC Agent 不支持的列
  2. 对不支持的列做改造：调整为受支持的兼容类型，或在同步中排除该列
  3. 确认 Agent 支持的类型清单（以所用 DB2 CDC 组件文档为准），按清单对齐表结构后再启动 Agent
  4. 改造完成后重启 CDC Agent 验证可正常采集

二、目的地连接问题​

1. 明道云工作表问题​

1.1 Topic相关异常​

错误信息：

  1. Topic不存在： Failed to write records to Kafka: Topic(tableSyncTopic) not present in metadata after 30000 ms

  2. Topic分区异常： org.apache.kafka.common.errors.NotLeaderForPartitionException: This server is not the leader for that topic-partition

  3. Topic连接超时： org.apache.kafka.common.errors.TimeoutException: Expiring records after 30000ms

  4. Topic授权失败： org.apache.kafka.common.errors.TopicAuthorizationException: Not authorized to access topics: [xxx]

问题原因：

  1. Topic未创建或已被删除
  2. Kafka集群异常或重平衡
  3. 网络连接不稳定
  4. 权限配置问题
  5. Broker节点异常

统一解决方案：

  1. 重新发布任务流程：
  • 进入数据集成页面
  • 找到对应的同步任务
  • 点击"更新发布"
  • 等待任务重新发布完成
  • 启动任务验证同步情况
  1. 请求运维支持：
  • 提供任务ID
  • 提供具体错误信息
  • 说明问题发生时间点
  • 运维协助检查集成环境
1.2 新增数据异常​

错误信息：

  1. 主键重复：
  2. 删除标记异常：

问题原因：

  1. 主键重复
  • 包含正常行记录的重复
  • 包含回收站中的重复
  1. 删除操作问题
  • 非物理删除标识导致的问题
  • 先删除后新增的顺序问题
  1. 大批量新增问题
  • 合并多表同步数据
  • 重复发布导致的全量新增
  • 数据推送顺序问题

解决方案：

  1. 检查数据情况：
  • 验证主键是否重复
  • 确认回收站数据状态
  • 检查删除标记的准确性
  1. 调整同步策略：
  • 考虑分批同步数据
  • 调整推送顺序
  • 优化删除处理逻辑
1.3 更新数据异常​

错误信息：

  1. 主键数据不存在：
  2. 操作顺序异常：

问题原因：

  1. 数据状态问题
  • 数据已物理删除
  • 数据已进入回收站
  1. 复合操作问题
  • 先新增后删除的顺序问题
  • 非物理删除标识导致的问题
  • 推送数据顺序混乱

解决方案：

  1. 数据状态检查：
  • 确认数据是否真实删除
  • 检查回收站数据状态
  • 验证数据更新条件
  1. 优化同步策略：
  • 调整操作顺序
  • 规范删除标识使用
  • 优化数据推送逻辑
1.4 覆盖更新异常​

错误信息：

  1. 唯一索引冲突：
  2. 数据匹配失败：

问题原因：

  1. 工作表系统字段thirdprimary（三方主键）唯一索引冲突
  • 切换了主键映射的表字段
  • 新字段找不到数据时会走新增逻辑
  • 新增遇到唯一索引导致失败
  1. 去重依据字段问题
  • controlIdForIdentifyDuplicate字段为空
  • 推送去重字段配置错误
  • 去重依据字段匹配到多条数据

解决方案：

  1. 重新发布任务时的注意事项：
  • 确认源表主键字段是否变更
  • 验证去重依据字段的唯一性
  • 检查工作表中数据情况
  • 必要时先清空目标工作表
  1. 运维支持：
  • 检查工作表服务状态
  • 查看具体错误日志
  • 协助处理数据冲突

2. MySQL目的地问题​

2.1 表空间已满异常​

错误信息： The table 'xxx' is full; Error Code: 1114

问题原因：

  1. 磁盘空间不足
  2. 数据文件增长受限
  3. 表空间配置限制
  4. innodb_data_file_path配置不合理

解决方案：

  1. 检查空间使用情况： SELECT table_schema, table_name, data_length/1024/1024 as data_mb, index_length/1024/1024 as index_mb FROM information_schema.TABLES WHERE table_schema = 'your_database';

  2. 联系运维处理：

  • 清理磁盘空间
  • 扩容数据目录
  • 调整表空间配置
2.2 唯一索引冲突​

错误信息： Duplicate entry 'xxx' for key 'xxx'

问题原因：

  1. 源数据存在重复记录
  2. 未正确处理主键或唯一键
  3. 数据同步顺序问题
  4. 更新策略配置不当

解决方案：

  1. 检查源数据： SELECT column_name, COUNT() FROM table_name GROUP BY column_name HAVING COUNT() > 1;

  2. 调整同步任务：

  • 修改更新策略
  • 调整同步条件
  • 优化数据处理逻辑
2.3 字段长度溢出​

错误信息： Data too long for column 'xxx' at row xxx

问题原因：

  1. 目标字段长度小于源字段
  2. 字符集编码不一致
  3. 数据转换问题
  4. 特殊字符处理问题

解决方案：

  1. 检查字段定义： SHOW CREATE TABLE table_name;

  2. 调整字段长度： ALTER TABLE table_name MODIFY COLUMN column_name VARCHAR(适当长度);

  3. 检查字符集： SHOW VARIABLES LIKE 'character%';

2.4 写入权限不足command denied​

错误信息： INSERT/UPDATE/DELETE command denied to user 'xxxx'@'host' for table 'yyyy'

问题原因：

  1. 目标库账号缺少对应表的 INSERT / UPDATE / DELETE 权限
  2. 连接到了只读库或使用了只读账号

解决方案：

  1. 为目标账号授予写权限： GRANT INSERT, UPDATE, DELETE ON db.table TO 'user'@'host'; FLUSH PRIVILEGES;
  2. 确认连接的是可写实例、可写账号（非只读副本/只读账号）
  3. 最小权限原则下，确保至少授予同步所需的增删改权限

3. Oracle目的地问题​

3.1 字段值超长异常​

错误信息： ORA-12899: value too large for column xxx

问题原因：

  1. 字段定义长度不足
  2. 字符集转换导致长度变化
  3. 数据类型不匹配

解决方案：

  1. 检查字段定义： SELECT column_name, data_type, data_length FROM user_tab_columns WHERE table_name = 'TABLE_NAME';

  2. 调整字段长度： ALTER TABLE table_name MODIFY (column_name VARCHAR2(新长度));

3.2 序列生成异常​

错误信息： ORA-08004: sequence SEQ_XXX.NEXTVAL exceeds internal limits

问题原因：

  1. 序列达到最大值
  2. 序列缓存设置不合理
  3. 并发获取序列值

解决方案：

  1. 检查序列状态： SELECT sequence_name, min_value, max_value, increment_by, cache_size FROM user_sequences WHERE sequence_name = 'SEQ_NAME';

  2. 重建序列： DROP SEQUENCE sequence_name; CREATE SEQUENCE sequence_name START WITH xxx INCREMENT BY 1 NOCACHE;

3.3 表空间不足​

错误信息： ORA-01653: unable to extend table xxx by xxx in tablespace xxx

问题原因：

  1. 表空间物理空间不足
  2. 表空间最大尺寸限制
  3. 数据文件无法自动扩展

解决方案：

  1. 检查表空间使用情况： SELECT tablespace_name, bytes/1024/1024 MB, maxbytes/1024/1024 MAX_MB FROM dba_data_files;

  2. 联系运维处理：

  • 新增数据文件
  • 调整自动扩展配置
  • 清理无用数据
3.4 并发写入冲突​

错误信息： ORA-00060: deadlock detected while waiting for resource

问题原因：

  1. 事务相互等待
  2. 索引竞争
  3. 锁等待超时
  4. 并发写入同一数据

解决方案：

  1. 查看锁状态： SELECT sid, serial#, blocking_session FROM v$session WHERE blocking_session IS NOT NULL;

  2. 优化并发策略：

  • 调整事务大小
  • 优化锁等待时间
  • 减少长事务

4. SQLServer目的地问题​

4.1 主键重复异常​

错误信息： Violation of PRIMARY KEY constraint 'PK_xxx'. Cannot insert duplicate key

问题原因：

  1. 源数据主键重复
  2. 同步策略配置问题
  3. 标识列(IDENTITY)设置问题

解决方案：

  1. 检查主键值： SELECT column_name, COUNT() FROM table_name GROUP BY column_name HAVING COUNT() > 1;

  2. 调整同步策略：

  • 设置正确的更新规则
  • 处理重复数据逻辑
  • 检查IDENTITY设置

三、任务执行问题​

1. 任务创建问题​

1.1 任务创建超时​

错误信息： 创建任务时报504 time out超时错误

问题原因：

  1. Nginx默认超时时间设置过短
  2. 任务创建过程耗时较长
  3. 网络连接不稳定

解决方案：

  1. 修改Nginx配置：
location /private-datapipeline {
    proxy_read_timeout 3600s;
    proxy_connect_timeout 3600s;
    proxy_send_timeout 3600s;
}
  1. 执行以下步骤：

  • 进入容器： docker exec -it $(docker ps |grep community|awk '{print $1}') bash

  • 进入Nginx配置目录： cd /usr/local/nginx/conf/conf.d

  • 修改配置文件： sed -ri '/private-datapipeline;/a\ \ \ \ \ \ \ \ proxy_read_timeout 3600s;' private.conf

  • 检查配置是否生效： grep -C 5 'private-datapipeline;' private.conf

  • 重载Nginx配置： /usr/local/nginx/sbin/nginx -s reload

1.2 文件上传失败​

错误信息： 发布同步任务失败,上传jar包失败

问题原因：

  1. Flink与集成中心的通信异常
  2. 网络连接不稳定
  3. 文件权限问题

解决方案：

  1. 检查网络连接：
  • 确保Flink和集成中心之间网络通畅
  • 检查防火墙配置
  • 验证端口是否开放
  1. 检查文件权限：
  • 确保上传目录具有正确的写入权限
  • 检查磁盘空间是否充足
1.3 消息大小超限​

错误信息： io.grpc.StatusRuntimeException: RESOURCE_EXHAUSTED: Sending message exceeds the maximum configured message size

问题原因：

  1. 一次性同步的数据量过大
  2. 同步的表字段数过多
  3. gRPC消息大小限制配置过小

解决方案：

  1. 优化同步策略：
  • 减少单次操作的记录数量
  • 减少同步的字段数量
  • 考虑分批同步数据
  1. 建议操作：
  • 选择必要的字段进行同步
  • 适当调整同步批次大小
  • 避免全表数据一次性同步

2. 任务运行问题​

2.1 Checkpoint异常​

错误信息： Exceeded checkpoint tolerable failure threshold. The latest checkpoint failed due to Asynchronous task checkpoint failed.

问题原因：

  1. Checkpoint的大小超出限制
  2. Checkpoint的时间过长
  3. 任务状态过大

解决方案：

  1. 重启任务，尝试清理历史状态

  2. 检查数据量是否过大：

  • 考虑增量同步替代全量同步
  • 适当调整同步频率
  1. 检查是否存在数据倾斜：
  • 审查数据分布情况
  • 考虑优化数据分片策略
2.2 Task取消超时​

错误信息： did not react to cancelling signal - interrupting; it is stuck for XXX seconds in method

问题原因：

  1. Task在取消过程中被阻塞
  2. 未能在指定时间内响应取消信号
  3. 可能由于逻辑问题或资源争用导致

解决方案：

  1. 检查task执行状态：
  • 查看task manager日志
  • 检查资源使用情况
  • 分析task执行耗时
  1. 必要时强制终止：
  • 记录当前任务状态
  • 使用kill命令强制终止
  • 重新提交任务
2.3 Schema获取失败​

错误信息： Retrieve schema history failed, the schema record for engine has been removed

问题原因：

  1. 数据库表在任务运行时发生结构性变更
  2. Schema历史记录丢失
  3. 权限不足无法读取schema信息

解决方案：

  1. Schema变更管理：
  • 避免在同步过程中修改表结构
  • 必要变更时先停止同步任务
  1. 任务操作建议：
  • 记录现有配置
  • 重新创建同步任务
  • 验证新任务配置
2.4 SourceCoordinator超时​

错误信息： Failed to close the SourceCoordinator before timeout of 60000 ms

问题原因：

  1. 数据源连接数限制
  2. 网络延迟过高
  3. 资源争用导致响应缓慢

解决方案：

  1. 数据库连接管理：
  • 创建专用同步账户
  • 合理设置连接池大小
  • 定期清理空闲连接

四、Flink引擎异常排查​

说明：本章面向使用 Flink / Flink CDC 引擎运行同步任务时的常见异常。多数问题可由用户依据下文"问题原因—解决方案"自助定位，仅当涉及集群参数（flink-conf.yaml）调整或需要扩容资源时，才需联系研发/运维协助。排查前请先准备：任务ID、完整异常堆栈、问题发生时间点、JobManager 与 TaskManager 日志、Flink Web UI 截图（Overview / Checkpoints / Backpressure 页面）。

1. 运行时核心异常​

1.1 Checkpoint失败超过容忍阈值​

错误信息： Exceeded checkpoint tolerable failure threshold. The latest checkpoint failed due to Asynchronous task checkpoint failed.

问题原因：

  1. 状态后端写入慢或状态过大，异步快照在超时时间内未完成
  2. 反压严重，barrier 无法及时对齐（aligned checkpoint 下尤其明显）
  3. 状态存储目标（HDFS/OSS/本地盘）写入失败、空间不足或权限不足
  4. TaskManager 频繁 Full GC，导致快照线程被拖慢

解决方案：

  1. 适当放宽容忍阈值与超时，给慢快照留出空间（flink-conf.yaml 或任务参数）： execution.checkpointing.tolerable-failed-checkpoints: 10 execution.checkpointing.timeout: 600000 execution.checkpointing.min-pause: 5000
  2. 排查反压（见 1.6），先消除反压再谈 Checkpoint 稳定性
  3. 检查状态存储后端可用性与剩余空间，确认任务账号对 checkpoint 目录有写权限
  4. 对大状态任务，开启非对齐 Checkpoint 缓解 barrier 对齐阻塞： execution.checkpointing.unaligned: true
  5. 若仅为偶发失败且数据未丢，可先重启任务清理历史状态再观察
1.2 Checkpoint长期Pending/超时​

错误信息： Checkpoint 在 Web UI 上长时间处于 IN_PROGRESS，最终 Checkpoint expired before completing.

问题原因：

  1. 某个 subtask 处于严重反压，barrier 长时间无法流到下游
  2. Source 端（如 CDC 快照阶段）单个 split 处理时间过长，barrier 被卡在 Source
  3. 状态过大，异步上传耗时超过 timeout
  4. 网络抖动或状态存储后端响应慢

解决方案：

  1. 打开 Web UI 的 Checkpoint 详情，定位 ack 最慢的 subtask（Acknowledged 列），针对性排查
  2. 增大超时时间：execution.checkpointing.timeout: 900000
  3. CDC 快照阶段建议先完成全量再观察增量阶段的 Checkpoint，是否快照阶段本就无法做 Checkpoint（部分版本快照阶段不切 Checkpoint 属正常现象）
  4. 开启非对齐 Checkpoint：execution.checkpointing.unaligned: true
  5. 缩小 Checkpoint 间隔不一定有效，反而加重负担；应优先解决反压与状态体积
1.3 Checkpoint状态过大导致同步缓慢​

问题描述： Checkpoint Size 持续增长到 GB 级别，每次 Checkpoint 耗时越来越长，任务吞吐下降。

问题原因：

  1. 使用了大状态算子（如全局去重、长时间窗口、regular join 维表缓存）
  2. 状态 TTL 未配置，历史状态无限累积
  3. CDC 任务 schema history / split 元数据状态膨胀
  4. 数据倾斜导致个别并行度状态远大于其它

解决方案：

  1. 为有状态算子配置状态 TTL，及时清理过期状态
  2. 大状态任务改用 RocksDB 状态后端并开启增量 Checkpoint： state.backend: rocksdb state.backend.incremental: true
  3. 评估是否真的需要全量状态，能用增量同步替代全量的尽量用增量
  4. 排查并缓解数据倾斜（见 1.16）
1.4 Savepoint触发失败​

错误信息： Triggering a savepoint for the job failed / Savepoint timed out.

问题原因：

  1. 任务正处于反压或异常状态，无法在超时内完成一致性快照
  2. Savepoint 目标路径不可写或磁盘空间不足
  3. 任务并行度极高、状态很大，Savepoint 耗时超出默认超时
  4. 任务正在 failover，状态不稳定

解决方案：

  1. 确认任务处于 RUNNING 且无持续反压后再触发 Savepoint
  2. 检查 Savepoint 目录（如 state.savepoints.dir）权限与剩余空间
  3. 大状态任务通过命令行加大超时，或改用 Checkpoint 进行恢复
  4. 若只是停机升级，可使用 stop-with-savepoint；若失败可退化为从最近一次成功 Checkpoint 恢复
1.5 从Checkpoint/Savepoint恢复失败​

错误信息： Cannot map checkpoint/savepoint state for operator xxx to the new program / Max parallelism mismatch / state schema incompatible.

问题原因：

  1. 任务拓扑发生变化（新增/删除算子）且算子未设置稳定的 uid
  2. 修改了并行度但超过了原 maxParallelism 上限
  3. 状态数据结构（Schema/序列化器）发生不兼容变更
  4. 状态文件损坏或路径不正确

解决方案：

  1. 为关键算子显式设置 uid，保证拓扑变更后状态可映射
  2. 恢复时允许跳过无法映射的状态：--allowNonRestoredState（确认可接受状态丢失再使用）
  3. maxParallelism 一经确定不可随意更改，扩并行度需在其上限内
  4. 若状态确实不兼容，停止任务后以无状态方式重新发布，并重新做一次全量同步
  5. 确认恢复路径指向完整的 _metadata 文件而非中间目录
1.6 反压(Backpressure)导致同步停滞​

问题描述： Flink Web UI 的 Backpressure 页面显示算子为 HIGH，吞吐下降、延迟升高、Checkpoint 频繁超时。

问题原因：

  1. 下游 Sink 写入慢（目标库索引多、单条 insert、网络 RTT 高、目标库反压）
  2. 某算子计算重（复杂 UDF、维表查询无缓存）
  3. 并行度不足，单并行度处理不过来
  4. 数据倾斜，个别 subtask 成为瓶颈
  5. 目标库锁等待、表空间不足等导致写入阻塞

解决方案：

  1. 用 Web UI 自上而下定位：第一个变红（HIGH）的算子的下游就是瓶颈所在
  2. Sink 瓶颈：开启批量写入、增大 batch size 与 flush 间隔、为目标表建合适索引、增大 Sink 并行度
  3. 计算瓶颈：为维表查询加缓存、优化 UDF、提升该算子并行度
  4. 数据倾斜：见 1.16
  5. 检查目标库是否存在锁、磁盘满、连接数打满等（参见本手册"目的地连接问题"章节）
1.7 任务反复重启(Restart Loop)​

错误信息： Job xxx switched from state RUNNING to RESTARTING / FAILING，并在短时间内循环。

问题原因：

  1. 存在持续性根因（如目标库连接失败、源库位点失效、序列化异常），每次重启都立刻再次失败
  2. 重启策略配置过于激进，掩盖了真实错误
  3. 资源不足导致 task 无法长时间稳定运行
  4. 周期性的网络/依赖服务抖动

解决方案：

  1. 不要只看"重启"现象，务必翻到第一次 FAILED 的根因异常（Web UI Exceptions 页 / JobManager 日志中第一条 root cause）
  2. 配置合理的重启策略，避免无限快速重启： restart-strategy: fixed-delay restart-strategy.fixed-delay.attempts: 3 restart-strategy.fixed-delay.delay: 30 s 或 exponential-delay 退避策略
  3. 针对根因解决（连接、位点、Schema、资源等）后再恢复任务
  4. 反复失败且已耗尽重启次数的任务会进入 FAILED，需修复根因后重新发布
1.8 Slot资源不足NoResourceAvailableException​

错误信息： org.apache.flink.runtime.jobmanager.scheduler.NoResourceAvailableException: Could not acquire the minimum required resources / Slot request bulk is not fulfillable.

问题原因：

  1. 集群可用 Slot 总数小于任务所需（并行度 × 任务数 超过 TaskManager 提供的 Slot）
  2. TaskManager 数量或单 TM 的 numberOfTaskSlots 配置过少
  3. 前序任务未释放 Slot，资源被占满
  4. Session 模式下多个任务争抢有限资源

解决方案：

  1. 核对所需 Slot：作业最大并行度即至少需要的 Slot 数（同一 SlotSharingGroup 内算子共享）
  2. 增加资源：提升 taskmanager.numberOfTaskSlots，或增加 TaskManager 实例数
  3. 降低任务并行度（parallelism.default 或任务级并行度）以匹配现有资源
  4. 清理/下线不再需要的历史任务，释放被占用的 Slot
  5. 资源扩容涉及集群配置变更，通常需运维协助
1.9 TaskManager心跳超时/失联​

错误信息： Heartbeat of TaskManager with id xxx timed out / Connection unexpectedly closed by remote task manager.

问题原因：

  1. TaskManager 进程因 OOM 被系统 Kill 或崩溃退出
  2. 长时间 Full GC（STW）导致心跳无法及时上报
  3. 网络抖动或机器负载过高
  4. 容器被资源管理器（YARN/K8s）因超限驱逐

解决方案：

  1. 检查对应 TM 是否还存活；若已退出，查看其退出前日志（OOM、被 Kill 的记录）
  2. GC 问题见 1.15；内存问题见 1.11~1.14
  3. 适当放宽心跳超时以容忍偶发抖动（不能掩盖真实 OOM）： heartbeat.timeout: 120000 heartbeat.interval: 10000
  4. 检查 K8s/YARN 是否因内存超 limit 驱逐容器，必要时调大容器内存配额
1.10 Akka/RPC调用超时​

错误信息： akka.pattern.AskTimeoutException: Ask timed out on [Actor...] after [10000 ms] / Could not complete the operation. Number of retries...

问题原因：

  1. JobManager 或 TaskManager 负载过高、GC 严重，RPC 响应缓慢
  2. 大量任务/大并行度导致 JM 元数据操作变慢
  3. 网络延迟过高
  4. 默认 ask timeout 偏小

解决方案：

  1. 适当增大 RPC 超时： akka.ask.timeout: 60 s web.timeout: 60000
  2. 排查 JM/TM 的 GC 与 CPU 负载，必要时给 JobManager 增加内存
  3. 减少单集群上的任务数量或降低并行度，减轻 JM 压力
  4. 检查节点间网络连通与延迟
1.11 TaskManager内存溢出(堆OOM)​

错误信息： java.lang.OutOfMemoryError: Java heap space

问题原因：

  1. 算子在堆内累积过多对象（大窗口、全量缓存、维表全量加载）
  2. 单条记录过大或批量缓冲过大
  3. TaskManager 堆内存（taskmanager.memory.task.heap.size）配置过小
  4. 内存泄漏（自定义函数中持有大对象）

解决方案：

  1. 增大 TaskManager 总内存：taskmanager.memory.process.size: 4096m（按需上调）
  2. 大状态场景改用 RocksDB 状态后端，将状态放到磁盘而非堆内
  3. 减小单批数据量，避免一次性加载全表到内存
  4. 检查自定义 UDF/维表是否无界缓存，加上容量上限或 TTL
  5. 保留 OOM 时的 heap dump 以便定位泄漏： env.java.opts: -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path
1.12 Metaspace内存溢出​

错误信息： java.lang.OutOfMemoryError: Metaspace

问题原因：

  1. 任务频繁提交/重启，旧 ClassLoader 未被回收，类元数据持续累积（典型于 Session 集群）
  2. 用户 jar 引入大量类或动态生成类（如频繁编译代码生成）
  3. taskmanager.memory.jvm-metaspace.size 配置过小

解决方案：

  1. 增大 Metaspace：taskmanager.memory.jvm-metaspace.size: 512m
  2. Session 模式下避免在同一 TM 上反复提交大量任务；问题严重时重启 TM 释放
  3. 排查类加载泄漏，确认连接器/驱动未在静态变量中残留引用
  4. 优先使用 Application 模式（每个作业独立 JVM），从根本上规避跨任务的 Metaspace 累积
1.13 堆外/直接内存溢出(Direct/Network Buffer)​

错误信息： java.lang.OutOfMemoryError: Direct buffer memory / Insufficient number of network buffers.

问题原因：

  1. 网络 buffer 不足（高并行度、shuffle 重的拓扑需要更多 buffer）
  2. 堆外内存（taskmanager.memory.framework.off-heap / task.off-heap）配置不足
  3. 使用了大量 Netty 直接内存的连接器

解决方案：

  1. 网络 buffer 不足时增大网络内存占比或总内存： taskmanager.memory.network.fraction: 0.2 taskmanager.memory.network.max: 1gb
  2. 适当增大堆外内存：taskmanager.memory.task.off-heap.size: 256m
  3. 过高的并行度会放大网络 buffer 需求，评估是否并行度设置过大
  4. 整体上调 taskmanager.memory.process.size 让各区域按比例增大
1.14 托管内存与RocksDB内存超限被Kill​

错误信息： 容器被 K8s/YARN 因超内存 limit 杀掉（OOMKilled / Container killed by YARN for exceeding memory limits）。

问题原因：

  1. RocksDB 实际使用内存超过 Flink 托管内存预算（block cache、write buffer 累加）
  2. 容器内存 limit 与 Flink process.size 之间未留出足够 JVM overhead
  3. 托管内存（taskmanager.memory.managed）配置偏小，RocksDB 频繁 spill 又被系统计入

解决方案：

  1. 适当增大托管内存占比：taskmanager.memory.managed.fraction: 0.4
  2. 让 RocksDB 受 Flink 内存管控（默认开启），不要手动放开 RocksDB 内存上限
  3. 增大 JVM overhead 留白，避免容器层面超 limit： taskmanager.memory.jvm-overhead.fraction: 0.1 taskmanager.memory.jvm-overhead.max: 1gb
  4. 容器 limit 应略大于 process.size，给 native 内存留余量
1.15 频繁Full GC导致任务卡顿​

问题描述： 任务周期性卡顿、心跳超时、Checkpoint 抖动；GC 日志显示频繁/长时间 Full GC。

问题原因：

  1. 堆内存偏小或对象创建/晋升过快
  2. 大状态全部放堆内（未用 RocksDB）
  3. 存在内存泄漏，老年代持续增长
  4. 数据倾斜使个别 TM 内存压力大

解决方案：

  1. 增大堆内存或改用 RocksDB 把状态移出堆
  2. 切换到更适合大堆的 GC（如 G1），并开启 GC 日志观察： env.java.opts: -XX:+UseG1GC -Xlog:gc*:file=/path/gc.log
  3. 排查并修复内存泄漏（heap dump 分析）
  4. 缓解数据倾斜（见 1.16）
1.16 数据倾斜导致单并行度过载​

问题描述： Web UI 上个别 subtask 的 records/bytes 远高于其它，该 subtask 持续反压、Checkpoint ack 最慢。

问题原因：

  1. keyBy / 分区键分布不均（如大量数据集中在某几个 key）
  2. 源表某个分片数据量远大于其它（CDC chunk 切分不均）
  3. 热点主键、空值 key 集中

解决方案：

  1. 优化分区键，避免使用低基数或高度集中的字段作为 key
  2. 对热点 key 做打散（加随机前缀两阶段聚合），聚合后再合并
  3. CDC 快照阶段可调小 chunk size 让分片更均匀： scan.incremental.snapshot.chunk.size: 8096
  4. 评估是否可在 Source 端过滤掉无意义的热点/空值数据
1.17 Watermark不推进导致窗口不触发​

问题描述： 基于事件时间的窗口/聚合迟迟不输出结果，下游"没有数据"。

问题原因：

  1. 某个并行 source/分区无数据，watermark 取所有分区最小值而被卡住（空闲分区问题）
  2. 事件时间字段存在异常值（远小于真实时间），拉低 watermark
  3. 乱序程度超过设定的 watermark 容忍，或根本未正确分配 watermark

解决方案：

  1. 为可能空闲的源配置空闲检测，让空闲分区不阻塞 watermark： table.exec.source.idle-timeout: 30 s
  2. 检查并清洗事件时间字段，剔除异常时间值
  3. 合理设置乱序容忍度（watermark 延迟），与业务乱序程度匹配
  4. 确认 source 已正确分配时间戳与 watermark 策略

2. CDC连接器专项​

2.1 快照阶段一直卡住无进度​

问题描述： 任务启动后长时间停留在全量快照阶段，Web UI 显示 source 一直在读取，下游无数据写入。

问题原因：

  1. 全量表数据量极大，快照本身就需要较长时间（属正常，但需评估）
  2. 快照查询在源库被慢查询/锁阻塞，或源库负载高
  3. chunk 切分键选择不当（无主键或主键分布极不均），导致个别 chunk 巨大
  4. 下游写入慢造成反压，回压到 source 使快照变慢
  5. 快照阶段默认不切 Checkpoint，给人"卡住"的错觉

解决方案：

  1. 评估源表行数，预估快照时长；大表属正常耗时
  2. 在源库查看是否存在该任务发起的慢查询或锁等待，必要时优化
  3. 调整 chunk 大小让分片更均匀：scan.incremental.snapshot.chunk.size: 8096
  4. 排查下游反压（见 1.6），消除 Sink 瓶颈
  5. 若只需增量，可将启动模式设为 latest-offset 跳过全量快照（确认不需要存量数据再使用）： scan.startup.mode: latest-offset
2.2 快照阶段OOM/全表加载内存爆掉​

错误信息： 快照阶段 java.lang.OutOfMemoryError: Java heap space，或读取大表时 TM 崩溃。

问题原因：

  1. 单个 chunk 过大，一次性拉取过多行到内存
  2. 表中存在超大字段（LOB、长文本、BLOB），单行内存占用高
  3. JDBC fetch size 过大或驱动一次性加载结果集
  4. TaskManager 堆内存偏小

解决方案：

  1. 调小 chunk size，减少单次内存占用：scan.incremental.snapshot.chunk.size: 4096
  2. 增大 TaskManager 内存（见 1.11）
  3. 对超大字段表评估是否必须同步该字段，能裁剪则裁剪
  4. 确认采用增量快照（incremental snapshot）而非一次性全表快照
2.3 增量阶段Binlog位点失效​

错误信息： The connector is trying to read binlog starting at ... but this is no longer available on the server / Could not find first log file name in binary log index file.

问题原因：

  1. 任务停机时间过长，所需起始 binlog 已被源库按 expire 策略清理
  2. 源库做过 reset master 或 binlog 被手动清理
  3. 主从切换后位点不连续（GTID 不一致）

解决方案：

  1. 延长源库 binlog 保留时间，避免位点被过早清理（见本手册 MySQL 1.4 相关说明）： SET GLOBAL binlog_expire_logs_seconds = 604800; -- 保留7天
  2. 位点已失效且无法续传时，需重新做一次全量同步以重建一致状态
  3. 使用 GTID 模式可提升主从切换后的位点连续性
  4. 制定停机上限（小于 binlog 保留期），避免任务长时间停机后无法续传
2.4 server-id冲突导致Binlog连接被断开​

错误信息： A slave with the same server_uuid/server_id as this slave has connected to the master（连接被反复踢下线）。

问题原因：

  1. 多个 CDC 任务/并行 source 使用了相同的 server-id
  2. 并行快照下每个并行度需要唯一 server-id，但只配置了单个值
  3. 与已有的真实从库 server-id 冲突

解决方案：

  1. 为每个 CDC 任务分配唯一的 server-id；并行 source 需配置一段范围： server-id: 5400-5404
  2. 范围大小应不小于 source 并行度，且与其它任务、真实从库互不重叠
  3. 规划全局 server-id 分配规则，避免多任务撞号
2.5 心跳/连接超时被MySQL主动断开​

错误信息： Communications link failure / The last packet successfully received from the server was X ms ago。

问题原因：

  1. 低峰期源表长时间无变更，连接空闲超过 wait_timeout 被服务端断开
  2. 网络设备（防火墙/LB）对空闲长连接做了超时回收
  3. 源库 net_write_timeout / wait_timeout 偏小

解决方案：

  1. 开启 CDC 心跳，定期发送心跳保活连接： heartbeat.interval: 30 s
  2. 适当调大源库相关超时（需 DBA 评估）： SET GLOBAL wait_timeout = 28800;
  3. 检查中间网络设备的空闲连接回收策略，必要时放宽
  4. 确认网络稳定性，排查丢包
2.6 表无主键导致并行快照报错​

错误信息： 'scan.incremental.snapshot.enabled' is true but the table xxx does not have a primary key / chunk key column not found.

问题原因：

  1. 增量快照需要一个分片键（默认主键）来切分 chunk，表无主键时无法自动切分
  2. 联合主键或无唯一键场景未指定 chunk key

解决方案：

  1. 为表显式指定一个分布均匀的列作为 chunk key： scan.incremental.snapshot.chunk.key-column: id
  2. 该列应有索引、基数高、分布均匀，否则切分不均（见 1.16）
  3. 确实无合适列时，可关闭增量快照退化为单并行度快照（吞吐下降）
  4. 从根本上建议为同步表补充主键/唯一键
2.7 DDL变更导致解析失败/任务中断​

错误信息： Schema change detected / Encountered change event for table whose schema isn't known / DDL 解析报错导致任务失败。

问题原因：

  1. 同步运行期间源表执行了 DDL（加列、改类型、改名）
  2. CDC 的 schema history 与当前表结构不一致
  3. 不兼容的结构变更（删列、改主键）破坏了下游映射

解决方案：

  1. 尽量避免在同步运行期间对源表做 DDL；必须变更时先停任务、变更后再启动
  2. 兼容性变更（末尾加列）多数可平滑处理，确认连接器已开启 schema 变更捕获
  3. 不兼容变更（删列/改主键/改类型）通常需重建任务并重新全量同步
  4. 与本手册"任务运行问题 2.3 Schema获取失败"配合排查 schema history 丢失问题
2.8 时间/Decimal/二进制类型解析异常​

错误信息： 常见为时间值溢出（见本手册 SQLServer 3.6 datetime2）、Decimal 精度丢失或被 Base64 编码、tinyint(1) 被解析为 boolean 等。

问题原因：

  1. Java/Flink 时间类型上限为 2262-04-11，超大日期解析报错
  2. Debezium 对 decimal 默认采用 precise（字节）模式，下游表现为乱码/Base64
  3. MySQL tinyint(1) 被默认当作 boolean 处理
  4. 二进制/枚举类型映射策略与下游期望不一致

解决方案：

  1. 超大日期问题见 SQLServer 3.6，建议源端控制日期范围或目标字段用字符串
  2. Decimal 选择合适的处理模式，避免精度丢失或编码问题： decimal.handling.mode: string （或 double，按精度需求选择）
  3. 控制 tinyint(1) 行为，避免被强转 boolean： tinyInt1isBit=false（JDBC 连接参数）
  4. 二进制类型选择合适的 binary.handling.mode（bytes / base64 / hex）与下游约定一致
2.9 Kafka Sink写入超时/批量过大​

错误信息： （参见本手册"明道云工作表问题 1.1"的 Kafka 异常族）TimeoutException: Expiring records after 30000ms / RecordTooLargeException: The message is larger than the maximum request size.

问题原因：

  1. 单条/单批消息超过 Kafka 的 message.max.bytes / max.request.size
  2. Broker 不可用、网络抖动或分区 leader 选举中
  3. 生产端 buffer 不足或 ack 等待超时
  4. 一次同步的数据量过大（大字段、多字段宽表）

解决方案：

  1. 增大生产端与 Broker 的消息上限（两侧都要调）： max.request.size、message.max.bytes、replica.fetch.max.bytes
  2. 适当增大超时与重试：request.timeout.ms、delivery.timeout.ms、retries
  3. 减小单批数据量、裁剪不必要的大字段（见"任务创建问题 1.3 消息大小超限"）
  4. Broker/重平衡类问题按本手册 1.1 的"重新发布 + 运维支持"流程处理
2.10 数据序列化/反序列化失败​

错误信息： com.esotericsoftware.kryo.KryoException / Could not forward element to next operator / SerializationException。

问题原因：

  1. 数据中包含连接器无法识别的类型或脏数据（编码异常、非法字符）
  2. 上下游 Schema 不一致导致字段错位
  3. 自定义类型未注册序列化器，回退到 Kryo 失败
  4. 源端字符集与解析配置不匹配（见本手册 MySQL 1.8 字符集问题）

解决方案：

  1. 定位报错的具体记录（开启 source 端日志或抽样），确认是否为脏数据
  2. 统一上下游 Schema 与字段类型映射
  3. 自定义 POJO 提供明确的 TypeInformation，避免回退 Kryo
  4. 校正源端字符集/时区配置（参见 MySQL 1.7、1.8）
  5. 对个别脏数据可在 Source 端做容错过滤，避免单条数据拖垮整个任务
2.11 多表/分库分表合并同步问题​

问题描述： 将多张分表/分库表合并到一张下游表时，出现主键冲突、数据错乱或部分表不同步。

问题原因：

  1. 各分表主键在合并后不再全局唯一，产生主键冲突
  2. 表名正则未覆盖全部分表，遗漏部分表
  3. 各分表结构存在细微差异，合并时字段不对齐
  4. 重复发布导致全量重新写入（参见"明道云工作表 1.2/1.4"重复发布问题）

解决方案：

  1. 合并场景为下游设计全局唯一键（如 库名+表名+原主键 或新增分布式ID）
  2. 用正则正确匹配所有分库分表（database-name / table-name 支持正则）
  3. 确认所有分表结构一致，差异字段做统一处理
  4. 重新发布前评估是否会触发全量，避免重复全量写入造成冲突

3. 部署运维与诊断​

3.1 类加载冲突(LinkageError/NoSuchMethod)​

错误信息： java.lang.LinkageError / NoSuchMethodError / java.lang.NoSuchFieldError / loader constraint violation。

问题原因：

  1. 用户 jar 与 Flink lib 中存在同一依赖的不同版本（如 guava、jackson、netty）
  2. 连接器 jar 重复放置（既在 lib 又打进作业 jar）
  3. 子类优先/父类优先的类加载策略与依赖打包方式不匹配

解决方案：

  1. 排查冲突依赖，对作业 jar 中与 Flink 自带冲突的库做 shade（重定位）或 provided
  2. 避免把 flink 核心、连接器同时打入作业 jar，连接器统一放 lib 或统一打包，二选一
  3. 必要时调整类加载顺序： classloader.resolve-order: parent-first （默认 child-first，冲突时可试 parent-first）
  4. 确认 lib 下无同一连接器的多个版本 jar
3.2 依赖jar缺失(ClassNotFound/NoClassDefFound)​

错误信息： java.lang.ClassNotFoundException / NoClassDefFoundError，常见于找不到连接器或 JDBC 驱动类。

问题原因：

  1. 对应连接器/数据库驱动 jar 未放入 Flink lib 或未打进作业 jar
  2. SQL 作业缺少对应的 connector 依赖
  3. 驱动 jar 版本与数据库不匹配
  4. jar 放置位置不被类加载器加载

解决方案：

  1. 将所需连接器 jar（如 flink-sql-connector-mysql-cdc）与 JDBC 驱动放入 $FLINK_HOME/lib 后重启集群
  2. 确认 jar 与 Flink、数据库版本相互兼容
  3. Application/Per-Job 模式下确认依赖随作业一并分发到各节点
  4. 放置 lib 后必须重启 TaskManager/JobManager 才会加载
3.3 JobManager HA与Zookeeper异常​

错误信息： Connection to ZooKeeper suspended / Could not retrieve the leader address / leader election 反复切换。

问题原因：

  1. Zookeeper 集群不稳定或网络抖动，导致 leader 会话超时
  2. HA 存储路径（high-availability.storageDir）不可写或被清理
  3. 多个集群误用同一 HA cluster-id，相互干扰
  4. JM GC 过长导致 ZK 会话超时丢失 leader

解决方案：

  1. 检查 Zookeeper 集群健康与网络连通，确保会话稳定
  2. 确认 HA 存储目录可访问、有写权限、空间充足
  3. 为每个集群配置唯一的 high-availability.cluster-id
  4. 适当增大 ZK 会话超时以容忍偶发抖动： high-availability.zookeeper.client.session-timeout: 60000
  5. 排查 JM GC（见 1.15），避免长 STW 丢 leader
3.4 任务提交失败/Web UI无法访问​

错误信息： 提交任务报连接被拒、上传 jar 失败、或 Web UI（默认 8081）打不开。

问题原因：

  1. JobManager 未启动或已崩溃
  2. REST/Web 端口被占用、被防火墙拦截或映射错误
  3. 上传 jar 超过大小限制或上传目录无写权限
  4. 集群与集成中心之间网络不通（参见"任务创建问题 1.2 文件上传失败"）

解决方案：

  1. 确认 JobManager 进程存活，查看其启动日志是否报错
  2. 检查 rest.port / rest.address 配置与端口连通性（telnet 测试）
  3. 上传相关：检查 web.upload.dir 权限与磁盘空间，必要时调大上传大小限制
  4. 打通集群与集成中心网络（防火墙、端口、安全组），与本手册 1.2 配合排查

五、排查方法论与故障处理建议​

说明：本章为通用排查指引，适用于全文各类数据源/目的地/引擎问题。建议先做前置检查（1），按方法论分层定位（2），再对照参数调优清单（3）与自助排查速查表（4）处理。绝大多数连接、权限、位点、类型、参数类问题均可自助解决；仅当需要调整集群参数（flink-conf.yaml）、扩容资源或确认平台侧缺陷时，再携带任务ID与完整堆栈联系研发/运维。

1. 前置检查​

1.1 数据源配置检查​

检查要点：

  1. 数据库配置：
  • 确认数据库版本是否符合要求
  • 验证数据库用户权限是否完整
  • 检查所需功能是否开启（如binlog、CDC、补充日志、复制槽等）
  1. 连接参数：
  • 检查连接地址和端口是否正确
  • 确认账号密码是否正确
  • 验证连接参数格式是否规范（如 SSL、时区、字符集、zeroDateTimeBehavior 等）
  1. 数据库状态：
  • 检查数据库运行状态
  • 确认数据库负载情况
  • 验证数据库连接数是否充足
  • ......
1.2 权限完整性检查​

检查要点：

  1. MySQL权限要求：
  • SELECT权限（读取数据）
  • REPLICATION CLIENT（读取binlog）
  • REPLICATION SLAVE（订阅binlog）
  • SHOW DATABASES（库表结构）
  1. Oracle权限要求：
  • SELECT ANY TABLE
  • EXECUTE_CATALOG_ROLE
  • SELECT ANY TRANSACTION
  • LOGMINING
  1. SQLServer权限要求：
  • db_owner角色
  • CDC相关权限
  • 数据库级别的读写权限
  1. 目的地写入权限：
  • 目标表的 INSERT / UPDATE / DELETE 权限（避免 command denied，见二.2.4）
1.3 网络连通性检查​

检查要点：

  1. 网络环境：
  • 确认防火墙配置
  • 检查端口开放情况
  • 验证网络延迟情况
  1. 连通性测试：
  • telnet测试端口连通性
  • ping测试网络可达性
  • 使用客户端工具测试连接
  1. 网络稳定性：
  • 检查网络波动情况
  • 验证带宽是否足够
  • 确认是否存在网络丢包

2. 故障定位与日志排查​

2.1 日志排查方法论​

排查任何同步异常时，建议遵循固定顺序，避免被"重启""超时"等表象误导：

  1. 保留关键信息：记录错误发生时间点、保存完整错误信息与堆栈、任务ID；必要时保留 heap dump / GC log 等现场证据。
  2. 分层看日志：
    • 任务/运行日志：任务启动日志、运行状态变更、异常中断记录
    • 系统日志：系统资源使用情况、系统异常信息、关键时间点
  3. Flink 引擎类问题先看 Web UI：
    • Overview 看任务状态与 failover 次数
    • Exceptions 页看 Root Exception 与 timeline（第一条根因最重要）
    • Checkpoints 页看成功率、耗时、最慢 subtask
    • Backpressure 页自上而下定位瓶颈算子
  4. 再看 JobManager 日志：定位作业级别的调度、failover、资源、leader 等问题。
  5. 然后看出问题的 TaskManager 日志：定位算子级别的异常、OOM、连接错误、GC。
  6. 抓住"第一现场"：循环重启时，永远找第一次 FAILED 的 root cause，而不是最后一次。
  7. GC 与内存：开启 GC 日志，结合第四章 1.11~1.15 判断是堆、Metaspace、直接内存还是托管内存问题。
2.2 常见问题排查​

排查步骤：

  1. 连接问题：
  • 验证数据源是否可访问
  • 检查认证信息是否正确
  • 确认网络环境是否稳定
  1. 同步异常：
  • 检查源表结构是否变更
  • 验证数据一致性
  • 查看增量数据捕获状态
  1. 性能问题：
  • 检查资源使用情况
  • 分析任务执行瓶颈
  • 评估优化可能性

3. 关键参数调优清单​

以下为同步任务最常调整的参数（具体以所用 Flink 版本为准；集群级参数改动通常需运维介入）：

  1. 内存类：
    • taskmanager.memory.process.size（TM 总内存，最常上调）
    • taskmanager.memory.managed.fraction（RocksDB/批处理托管内存占比）
    • taskmanager.memory.jvm-metaspace.size（Metaspace）
    • taskmanager.memory.network.fraction / .max（网络 buffer）
    • jobmanager.memory.process.size（JM 总内存）
  2. Checkpoint 类：
    • execution.checkpointing.interval（间隔）
    • execution.checkpointing.timeout（超时）
    • execution.checkpointing.tolerable-failed-checkpoints（容忍失败次数）
    • execution.checkpointing.unaligned（非对齐，缓解反压下的 Checkpoint）
    • state.backend: rocksdb / state.backend.incremental: true（大状态）
  3. 容错类：
    • restart-strategy（fixed-delay / exponential-delay）
    • restart-strategy.fixed-delay.attempts / .delay
    • heartbeat.timeout / heartbeat.interval
    • akka.ask.timeout
  4. 资源/并行度：
    • parallelism.default（默认并行度）
    • taskmanager.numberOfTaskSlots（单 TM Slot 数）
  5. CDC 连接器类：
    • scan.incremental.snapshot.chunk.size（chunk 大小）
    • scan.incremental.snapshot.chunk.key-column（无主键时指定 chunk key）
    • server-id（唯一/区间）
    • scan.startup.mode（initial / latest-offset 等）
    • heartbeat.interval（连接保活）
    • decimal.handling.mode / debezium.* 类型处理

4. 自助排查速查表​

下表"对应小节"中的引擎类问题（1.x / 2.x / 3.x）指向第四章 Flink 引擎异常排查。

现象优先怀疑对应小节
Checkpoint 频繁失败/超时反压、状态过大、状态后端四.1.1 1.2 1.3 1.6
任务不停重启找第一次 FAILED 根因四.1.7
启动报 NoResourceAvailableSlot 不足，需扩容或降并行度四.1.8
TM 频繁失联/被 KillOOM、GC、容器超 limit四.1.9 1.11~1.15
各种 OutOfMemoryError区分堆/Metaspace/直接/托管四.1.11~1.14
同步变慢、延迟升高反压、数据倾斜四.1.6 1.16
全量快照很久不动大表/反压/chunk 不均四.2.1 2.2
增量突然断且无法续传binlog 位点失效四.2.3
连接被反复断开server-id 冲突、空闲超时四.2.4 2.5
字段值为 NULL / 类型乱码补充日志/类型处理模式四.2.8（及一.Oracle 2.10）
ClassNotFound / NoSuchMethod缺 jar 或版本冲突四.3.1 3.2
Web UI 打不开/提交失败JM 状态、端口、网络四.3.4
数据源连接/认证/位点类对应数据库专项一、各库小节
目的地写入冲突/超长/权限对应目的地专项二、各目的地小节

自助排查建议：先用本章 2.1 的方法论锁定"第一现场"根因，再对照本速查表跳转到对应小节。

这篇文档对你有帮助吗？