# 常见问题-任务类（FAQ）

📚 温馨提示：据用户反馈统计，95% 的使用问题都能通过认真阅读文档得到解决。我们建议您在联系客服前，先查阅相关操作指南、配置说明或本 FAQ。这不仅能更快定位问题，还能帮助您更深入地掌握 DataMover 的强大能力。

阅读即赋能，理解即掌控。祝您使用愉快，数据流转如丝般顺滑！✨

📞 客服电话：18032410846

💬 微信技术客服：扫描官网二维码添加

📧 邮箱：service@datamover.cn

qq交流群：1081115584

恭喜你已经完成了DataMover的安装，管理界面和执行引擎都已正常启动，下面是常见的数据同步过程中的问题。

# 如何获取任务日志。

下载的日志文件压缩包中包含三个文件：

worker.log--调度引擎日志。
reader.log--源端数据读取日志。
worker.log--目的端数据写入日志。

打开日志文件搜索ERROR字符，将错误信息发送给AI，获取错误原因，根据错误原因进行相应处理。

# 1. 实时任务启动失败：未开启CDC

DataMover 支持两类任务：

普通任务
- 全量同步：适用于数据量较小的表，可选择“清空目标表后同步”，通常用于每日一次初始化。
- 增量同步：适用于大表，基于增量字段（如自增主键、create_time 或 update_time）周期性同步新增/变更数据。
实时任务
基于数据库的 CDC（Change Data Capture）机制，实时捕获源库的 INSERT / UPDATE / DELETE / TRUNCATE 操作，并在目标库重放对应 SQL。

# 🔍 排查步骤：

确认源数据库已正确开启 CDC 功能
不同数据库要求如下：
- MySQL：必须开启 binlog，且格式为 ROW，例如：
```
[mysqld]
log-bin=mysql-bin
binlog-format=ROW
server-id=1
```
- PostgreSQL：需开启 WAL 并设置 wal_level = logical，同时创建具有 REPLICATION 权限的用户。
- SQL Server：需启用数据库级 CDC 和具体表的 CDC。
- Oracle：需配置并启动 LogMiner，并授予相应权限。
确认 JDBC 账号具备 CDC 订阅权限
例如：
- MySQL 用户需拥有 REPLICATION SLAVE 和 REPLICATION CLIENT 权限；
- PostgreSQL 用户需有 LOGIN + REPLICATION 属性；

权限不足将导致任务启动即报错（常见错误如 CanalParseException）。

建议首次使用先验证基础连通性
- 先选择一张小表，创建一个普通全量任务进行一次性同步。
- 若成功，说明网络、账号、驱动等基础配置无误；
- 再在此基础上配置实时任务或复杂增量任务，降低排查难度。

# 2. 任务运行失败：内存不足

现象

任务跑了一半异常结束。

示例日志

ERROR 2026-01-10 19:17:22.668 [exec-61] 2da61d01c2814d3e8ea05bfb3f06ee50.run(95): task:2da61d01c2814d3e8ea05bfb3f06ee50,pipeline:2da61d01c2814d3e8ea05bfb3f06ee50,instance3T8jTaCIT5yEwCaznJVNXArunning exception:GC overhead limit exceeded
java.lang.OutOfMemoryError: GC overhead limit exceeded
	at java.util.Arrays.copyOf(Arrays.java:3181) ~[?:1.8.0_471]
	at java.text.DateFormatSymbols.copyMembers(DateFormatSymbols.java:849) ~[?:1.8.0_471]
	at java.text.DateFormatSymbols.initializeData(DateFormatSymbols.java:758) ~[?:1.8.0_471]
	at java.text.DateFormatSymbols.<init>(DateFormatSymbols.java:145) ~[?:1.8.0_471]
	at sun.util.locale.provider.DateFormatSymbolsProviderImpl.getInstance(DateFormatSymbolsProviderImpl.java:85) ~[?:1.8.0_471]
	at java.text.DateFormatSymbols.getProviderInstance(DateFormatSymbols.java:364) ~[?:1.8.0_471]

原因分析 GC overhead limit exceeded。JVM认为进行GC回收也无法满足任务需求。

worker安装是默认的JVM堆大小配置为2GB，在并行同步大表（千万级或者亿级表）时内存已满，则任务异常结束。

解决方案

根据服务器配置情况，修改worker/bin/start.sh

JVM_OPTS_CUSTOM="-Xms2048m -Xmx2048m"

若服务器内存充足，建议配置为8GB或者16GB。

JVM_OPTS_CUSTOM="-Xms8g -Xmx8g"
# 或者
JVM_OPTS_CUSTOM="-Xms16g -Xmx16g"

# 3. 任务运行失败001：目标字段非空约束冲突

现象同步任务因目标表字段设置了 NOT NULL 约束而失败，但源数据中该字段存在空值。

示例日志

ERROR 2026-01-07 09:09:18.144 [exec-8] xxxxxxxx.x(154): 数据库批量Upsert出错,table=sync_target_table(0,1000)：
org.springframework.dao.DataIntegrityViolationException: PreparedStatementCallback; SQL [INSERT INTO `sync_target_table`(`id`, `result_id`, `metric_a`, `metric_b`, `wavelength`, `value`) VALUES (?, ?, ?, ?, ?, ?) ON DUPLICATE KEY UPDATE `id` = VALUES(`id`), `result_id` = VALUES(`result_id`), `metric_a` = VALUES(`metric_a`), `metric_b` = VALUES(`metric_b`), `wavelength` = VALUES(`wavelength`), `value` = VALUES(`value`)]; Column 'wavelength' cannot be null; nested exception is java.sql.BatchUpdateException: Column 'wavelength' cannot be null

原因分析 目标表的 wavelength 字段不允许为空，但源表对应记录中该值为 NULL 或缺失，导致数据库拒绝写入。

解决方案 在 DataMover 的字段映射中，为该字段配置默认值，避免空值写入。例如：

default(wavelength, '0')

✅ 支持任意默认值，如 'N/A'、'未知'、0 等，根据业务语义选择。

# 4. 任务运行失败002：主键自增与多源同步冲突

现象目标表主键设置为自增（AUTO_INCREMENT），但在多源同步或保留源 ID 的场景下，容易引发主键重复或写入异常。

原因分析

若多个源表同步到同一张目标表，源端 ID 可能重复；
若目标表启用自增主键，又试图写入显式 ID 值，部分数据库（如 MySQL）会报错或产生意外行为。

推荐方案 不要依赖自增主键，而是新增一个全局唯一标识字段作为主键。在 DataMover 映射配置中，为目标表的主键字段使用内置函数生成 UUID：

uuid()

✅ 该方式确保每条记录全局唯一，彻底规避主键冲突问题，适用于多源合并、跨库同步等复杂场景。

# 5. 任务运行失败003：数据类型转换失败

现象源表以字符串（如 VARCHAR）存储数值或带单位的数据（如 "156CM"），但目标表字段为数值类型（如 DECIMAL），导致转换失败。

示例日志（脱敏）

ERROR 2026-01-07 11:54:59.699 [exec-16] 7ddd1167076944958678d209bb9e00c3.a(99): Data format conversion exception, field：wal_length, trying to convert 156CM to BigDecimal: java.lang.IllegalStateException: 转换出错,null

解决方案（二选一）

# 方案一：保留原始格式

将目标表字段类型改为 VARCHAR，直接存储原始字符串，避免清洗逻辑。

# 方案二：清洗为纯数值（推荐）

使用 DataMover 函数表达式提取有效数字。例如，将 "156CM"、"170 cm" 等清洗为 156、170：

int(trim(replace(replace(lower(val(height)), 'cm', ''), ' ', '')))

💡 不熟悉函数写法？只需将函数使用指南链接发送给任意 AI 助手（如通义千问），它能根据你的需求自动生成可用表达式！

# 6. 任务运行失败004：外面约束失败

目标表有外键约束，主表中值不存在，导致子表入库失败。

ERROR 2026-01-07 14:48:36.365 [exec-16] xxxxxxxx.x(154): 数据库批量Upsert出错,table=detail_table(22000,22994)：
org.springframework.dao.DataIntegrityViolationException: PreparedStatementCallback; SQL [INSERT INTO `detail_table`(`id`, `parent_id`, `wavelength`, `insertion_loss`, `return_loss`, `responsivity`, `directivity`, `sub_result`, `work_order`, `serial_no`) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON DUPLICATE KEY UPDATE `id` = VALUES(`id`), `parent_id` = VALUES(`parent_id`), `wavelength` = VALUES(`wavelength`), `insertion_loss` = VALUES(`insertion_loss`), `return_loss` = VALUES(`return_loss`), `responsivity` = VALUES(`responsivity`), `directivity` = VALUES(`directivity`), `sub_result` = VALUES(`sub_result`), `work_order` = VALUES(`work_order`), `serial_no` = VALUES(`serial_no`)]; Cannot add or update a child row: a foreign key constraint fails (`target_db`.`detail_table`, CONSTRAINT `detail_table_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `main_table` (`id`) ON DELETE CASCADE); nested exception is java.sql.BatchUpdateException: Cannot add or update a child row: a foreign key constraint fails (`target_db`.`detail_table`, CONSTRAINT `detail_table_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `main_table` (`id`) ON DELETE CASCADE)

错误原因：程序尝试向子表（detail_table）插入数据时，其关联的主表外键字段（parent_id）在主表（main_table）中不存在对应记录，违反了数据库的外键约束。

典型场景：

主表数据尚未同步完成，子表数据已开始写入；
源数据中的 parent_id 值有误或已被删除；
同步任务未按“先主表、后子表”的顺序执行。

解决建议：

确保主表（main_table）中已存在对应的 id 记录；
检查源数据中 parent_id 字段的值是否有效且一致；
调整同步任务依赖关系，保证主表数据先于子表写入，使用CRON调度，精确空值主表和子表的同步时间。

# 7. 任务运行失败004：无效的类型

PostgreSQL数据库目标表设置的字段类型为timestamp，但是源表中的数据存在非法值。

org.postgresql.util.PSQLException: 错误: 无效的类型 timestamp 输入语法: "CURRENT_TIMESTAMP"
  在位置：COPY dm_temp_55c40b81354e4974bae43af5b9824f0a, line 1, column content_datetime: "CURRENT_TIMESTAMP"
    at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryExecutorImpl.java:2675)
    at org.postgresql.core.v3.QueryExecutorImpl.processCopyResults(QueryExecutorImpl.java:1263)
    at org.postgresql.core.v3.QueryExecutorImpl.endCopy(QueryExecutorImpl.java:1068)
    at org.postgresql.core.v3.CopyInImpl.endCopy(CopyInImpl.java:49)
    at org.postgresql.copy.CopyManager.copyIn(CopyManager.java:227)
    at org.postgresql.copy.CopyManager.copyIn(CopyManager.java:203)
    at com.maomao.datamover.a.a.c.k.a(PostgresqlUpsertWriter.java:79)
    at com.maomao.datamover.worker.g.f.p.e(JdbcUpsertBaseWriter.java:83)
    at com.maomao.datamover.worker.d.a.c.a(PipelineExecutor.java:224)
    at com.maomao.datamover.a.a.c.b.a(FileWriteTransformer.java:181)
    at com.maomao.datamover.a.a.c.b.d(FileWriteTransformer.java:106)
    at com.maomao.datamover.worker.d.a.c.a(PipelineExecutor.java:218)
    at com.maomao.datamover.worker.g.h.b.d(AviatorTransformer.java:117)
    at com.maomao.datamover.worker.d.a.c.a(PipelineExecutor.java:218)
    at com.maomao.datamover.worker.g.i.c.ap(QueueReader.java:33)
    at com.maomao.datamover.worker.d.a.c.run(PipelineExecutor.java:72)
    at java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source)
    at java.util.concurrent.FutureTask.run(Unknown Source)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
    at java.lang.Thread.run(Unknown Source)

错误原因：

源数据文件（.bcp）中，data_datetime 字段的某个值是字符串字面量："CURRENT_TIMESTAMP"。
但 COPY 命令不会解释 SQL 表达式（如 CURRENT_TIMESTAMP），它只接受原始数据值（如 2026-01-19 19:53:56）。
PostgreSQL 尝试将 "CURRENT_TIMESTAMP" 当作时间字符串解析 → 失败。

典型场景：

源表的data_datetime 类型为VARCHAR，存储了非标准的时间字符串

解决建议：

确保源表中数据正确，删除错误数据；
使用函数将非法的时间字符串清空，设置为一个默认值。

# 8. 任务运行失败004：数据超过目标表字段长度限制

PostgreSQL数据库目标表设置的字段类型为timestamp，但是源表中的数据存在非法值。

org.springframework.dao.DataIntegrityViolationException: 
PreparedStatementCallback; SQL [INSERT INTO `country_table`(...)];
Data truncation: Data too long for column 'countries' at row 1;
nested exception is java.sql.BatchUpdateException: 
Data truncation: Data too long for column 'countries' at row 1

Caused by: java.sql.BatchUpdateException: 
Data truncation: Data too long for column 'countries' at row 1

Caused by: com.mysql.cj.jdbc.exceptions.MysqlDataTruncation: 
Data truncation: Data too long for column 'countries' at row 1
    at com.mysql.cj.jdbc.exceptions.SQLExceptionsMapping.translateException(...)
    at com.mysql.cj.jdbc.ServerPreparedStatement.serverExecute(...)
    at com.mysql.cj.jdbc.ClientPreparedStatement.executeBatchedInserts(...)
    ... (Spring JDBC / DBCP layers) ...
    at com.maomao.datamover.worker.g.f.r.e(MysqlJdbcUpsertWriter.java:126)
    at com.maomao.datamover.worker.d.a.c.a(PipelineExecutor.java:224)
    ... (task execution chain) ...

错误原因：

表 tour_base_country_role 中的 countries 字段定义长度不足（例如 VARCHAR(255)）。
实际写入的数据（如国家 ID 列表 "CN,US,JP,KR,DE,FR,IT,ES,MX,BR,..."）超过该长度限制。
MySQL 在严格模式下（默认）会拒绝插入并抛出 Data truncation 错误。

解决建议：

立即扩容字段：使用 ALTER TABLE ... MODIFY COLUMN countries VARCHAR(N) 将 N 调整为合理上限（如 1000）或改用 TEXT 类型；
评估数据模型：避免在单字段中存储集合数据，建议拆分为一对多关联表；
增加数据校验：在数据同步前加入长度校验逻辑，提前拦截超长数据并告警；
统一环境规范：确保开发、测试、生产环境的表结构一致，避免“本地能跑，线上报错”。

# 9. 任务运行失败004：日期时间格式错误

在尝试向MySQL表 t_guest 插入数据时，由于字段 created_at 的值不符合数据库中该字段的预期格式或范围，导致 SQL 执行失败。具体表现为插入了不被接受的日期时间值 '1955-08-07 23:00:00'，触发了 MySQL 的数据截断保护机制。

Data truncation: Incorrect datetime value: '1955-08-07 23:00:00' for column 'created_at' at row 494;
nested exception is java.sql.BatchUpdateException: 
Data truncation: Incorrect datetime value: '1955-08-07 23:00:00' for column 'created_at' at row 494

错误原因：

程序试图向表 tour_group_aid_apply_guest 写入数据时，字段 created_at 中包含了一个无效的日期时间值 '1955-08-07 23:00:00'，这超出了 MySQL 对于 TIMESTAMP 类型支持的有效范围或格式要求，从而导致插入操作失败。

解决建议：

检查目标表的created_time字段是否是timestamp类型，将字段改为datetime类型
清洗异常数据
- 使用validateDate(create_date, '2025-01-01 00:00:00')，将异常的时间设置为一个默认值。
- 使用validateDate(create_date)，将异常的时间设置为null入库到目标表。

# 10. 任务运行失败004：日期时间值超出范围

在尝试通过 COPY 命令向 PostgreSQL 表 public.project 插入数据时，由于字段 create_date 包含了一个无效的日期时间值 '2023-02-30 00:00:00'，导致导入操作失败。具体表现为该日期时间值不符合标准的日期格式（2月没有30号），触发了 PostgreSQL 的数据验证错误。

ERROR: date/time field value out of range: "2023-02-30 00:00:00"
位置：COPY dm_temp_ba12bcbcb9ae4c6b925f8b8a94e7bf64, line 3579, column start_date: "2023-02-30 00:00:00"

错误原因：程序试图向表 public.project 写入数据时，字段 create_date 中包含了一个不合法的日期时间值 '2023-02-30 00:00:00'，这超出了 PostgreSQL 对于 date 和 timestamp 类型支持的有效范围或格式要求，从而导致插入操作失败。

典型场景：

数据源中的日期时间信息可能存在异常或输入错误；
数据转换过程中可能出现了错误，生成了非法的日期时间值；
源数据文件中存在人为输入错误或其他系统生成的错误数据；
数据处理逻辑未对日期进行有效性校验。

解决建议：

确认数据源中 start_date 字段的所有值都在合法范围内。
清洗异常数据
- 使用validateDate(create_date, '2025-01-01 00:00:00')，将异常的时间设置为一个默认值。
- 使用validateDate(create_date)，将异常的时间设置为null入库到目标表。

# 11. MySQL实时任务启动失败：Debezium 连接 MySQL 时区识别失败

Debezium 在尝试启动 MySQL CDC（变更数据捕获）任务时失败，原因是无法识别 MySQL 服务器返回的时区值。错误信息显示：

The server time zone value '?й???׼ʱ?' is unrecognized or represents more than one time zone.
You must configure either the server or JDBC driver (via the 'connectionTimeZone' configuration property)
to use a more specific time zone value if you want to utilize time zone support.
...
Debezium engine error: Unable to initialize and start connector's task class 'io.debezium.connector.mysql.MySqlConnectorTask'
...
Unexpected error while connecting to MySQL and looking at BINLOG_FORMAT mode

错误原因：

MySQL 服务器返回的时区名称包含非 ASCII 字符（如中文“中国标准时间”），但 Debezium 使用的 MySQL JDBC 驱动（mysql-connector-java）无法正确解析该时区字符串，导致连接初始化失败。

根本原因通常是：

MySQL 服务器配置了 default_time_zone = 'SYSTEM'；
操作系统时区为中文（如 Windows 系统区域设置为中文），返回类似 "中国标准时间" 的本地化名称；
JDBC 驱动只认标准 IANA 时区名（如 Asia/Shanghai），不支持本地化别名。

💡 日志中的乱码 ?й???׼ʱ? 是 Java 应用在 UTF-8 环境下读取 GBK 编码的中文时区名时产生的字符解码错误。

解决建议：

该问题一在新版本中进行了修复适配，请在官网下载升级。

# 11. MySQL实时任务启动失败：Debezium 执行 `MASTER STATUS` 语法错误

DataMover 为了兼容JDK1.8，使用嵌入式Debezium 1.9.8版本支持MySQL CDC，该版本不支持8.0.28+、8.4+ 或阿里云 RDS 8.0 高版本

java.sql.SQLSyntaxErrorException: 
You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version 
for the right syntax to use near 'MASTER STATUS' at line 1

...
Debezium engine error: Error while trying to run connector class 'io.debezium.connector.mysql.MySqlConnector'
...
An exception occurred in the change event producer. This connector will be stopped.

解决建议：

将worker/lib目录和connectors\datamover-connector-mysql\lib目录中的debezium相关的jar包升级为2.5+版本，进行尝试。

← 常见问题-安装类（FAQ）我们反对“过度设计”：DataMover 专为“数据流转”而生的生存哲学 →

# 常见问题-任务类（FAQ）

# 如何获取任务日志。

# 1. 实时任务启动失败：未开启CDC

# 🔍 排查步骤：

# 2. 任务运行失败：内存不足

# 3. 任务运行失败001：目标字段非空约束冲突

# 4. 任务运行失败002：主键自增与多源同步冲突

# 5. 任务运行失败003：数据类型转换失败

# 方案一：保留原始格式

# 方案二：清洗为纯数值（推荐）

# 6. 任务运行失败004：外面约束失败

# 7. 任务运行失败004：无效的类型

# 8. 任务运行失败004：数据超过目标表字段长度限制

# 9. 任务运行失败004：日期时间格式错误

# 10. 任务运行失败004：日期时间值超出范围

# 11. MySQL实时任务启动失败：Debezium 连接 MySQL 时区识别失败

# 11. MySQL实时任务启动失败：Debezium 执行 MASTER STATUS 语法错误

# 11. MySQL实时任务启动失败：Debezium 执行 `MASTER STATUS` 语法错误