From 5f4ddf3820b36eaee7044e7cfd0864b10a405b19 Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 14:23:07 +0800 Subject: [PATCH 1/9] add ticdc kafka faq --- ticdc/ticdc-faq.md | 6 +++-- ticdc/ticdc-sink-to-kafka.md | 45 ++++++++++++++++++++++++++++++++---- ticdc/troubleshoot-ticdc.md | 14 +++++++---- 3 files changed, 53 insertions(+), 12 deletions(-) diff --git a/ticdc/ticdc-faq.md b/ticdc/ticdc-faq.md index 359473732894..7b07c4b9aaa9 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -240,9 +240,11 @@ cdc cli changefeed create --server=http://127.0.0.1:8300 --sink-uri="kafka://127 ## TiCDC 把数据同步到 Kafka 时，能在 TiDB 中控制单条消息大小的上限吗？ -对于 Avro 和 Canal-JSON 格式，消息是以行变更为单位发送的，一条 Kafka Message 仅包含一条行变更。一般情况下，消息的大小不会超过 Kafka 单条消息上限，因此，一般不需要限制单条消息大小。如果单条 Kafka 消息大小确实超过 Kafka 上限，请参考[为什么 TiCDC 到 Kafka 的同步任务延时越来越大](/ticdc/ticdc-faq.md#为什么-ticdc-到-kafka-的同步任务延时越来越大)。 +`max-message-bytes` 控制 TiCDC 将多条行变更合并为一条 Kafka message 时的大小，默认值为 `10 MB`。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。 -对于 Open Protocol 格式，一条 Kafka Message 可能包含多条行变更。因此，有可能存在某条 Kafka Message 消息过大。可以通过 `max-message-bytes` 控制每次向 Kafka broker 发送消息的最大数据量（可选，默认值 10 MB），通过 `max-batch-size` 参数指定每条 kafka 消息中变更记录的最大数量（可选，默认值 `16`）。 +对于 Open Protocol，一条 Kafka message 可能包含多条行变更。可以通过 `max-message-bytes` 控制合 batch 的大小，并通过 `max-batch-size` 控制每条 Kafka message 中的最大行变更数量。如果单条行变更编码后的消息超过 `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 仍会将其作为一条独立的 Kafka message 发送。 + +如果需要限制 Kafka 实际接收的消息大小，请配置 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes`。详情参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 ## 在一个事务中对一行进行多次修改，TiCDC 会输出多条行变更事件吗？ diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index 27591c2f0ca5..0a617936ae1b 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -77,7 +77,7 @@ URI 中可配置的的参数如下： | `kafka-version` | 下游 Kafka 版本号。该值需要与下游 Kafka 的实际版本保持一致。 | | `kafka-client-id` | 指定同步任务的 Kafka 客户端的 ID（可选，默认值为 `TiCDC_sarama_producer_同步任务的 ID`）。 | | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量，否则创建同步任务会失败，默认值 `3`）。| -| `max-message-bytes` | 每次向 Kafka broker 发送消息的最大数据量（可选，默认值 `10MB`，最大值为 `100MB`）。从 v5.0.6 和 v4.0.6 开始，默认值分别从 `64MB` 和 `256MB` 调整至 `10MB`。| +| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。| | `replication-factor` | Kafka 消息保存副本数（可选，默认值 `1`），需要大于等于 Kafka 中 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 的值。 | | `required-acks` | 在 `Produce` 请求中使用的配置项，用于告知 broker 需要收到多少副本确认后才进行响应。可选值有：`0`（`NoResponse`：不发送任何响应，只有 TCP ACK），`1`（`WaitForLocal`：仅等待本地提交成功后再响应）和 `-1`（`WaitForAll`：等待所有同步副本提交后再响应。最小同步副本数量可通过 broker 的 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 配置项进行配置）。（可选，默认值为 `-1`）。 | | `compression` | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。注意 Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。| @@ -108,15 +108,14 @@ URI 中可配置的的参数如下： ### 最佳实践 -* TiCDC 推荐用户自行创建 Kafka Topic，你至少需要设置该 Topic 每次向 Kafka broker 发送消息的最大数据量和下游 Kafka partition 的数量。在创建 changefeed 的时候，这两项设置分别对应 `max-message-bytes` 和 `partition-num` 参数。 +* TiCDC 推荐用户自行创建 Kafka Topic，并根据业务需要设置该 Topic 的 `max.message.bytes` 和 partition 数量。创建 changefeed 时，可以通过 `partition-num` 指定 partition 数量。`max-message-bytes` 只控制 TiCDC 合 batch 的大小，不会修改 Kafka Topic 的 `max.message.bytes`。 * 如果你在创建 changefeed 时，使用了尚未存在的 Topic，那么 TiCDC 会尝试使用 `partition-num` 和 `replication-factor` 参数自行创建 Topic，建议明确指定这两个参数。 * 在大多数情况下，建议使用 `canal-json` 协议。 * 如果 TiCDC 上游的数据变更很少，比如可能会出现超过 10 分钟没有数据变更的情况，建议在 Kafka broker 的配置文件中调大 Kafka 的连接空闲超时时间，详情参考[为什么 TiCDC 同步到 Kafka 的任务经常因 `broken pipe` 报错而失败](/ticdc/ticdc-faq.md#为什么-ticdc-同步到-kafka-的任务经常因-broken-pipe-报错而失败)。 > **注意：** > -> 当 `protocol` 为 `open-protocol` 时，TiCDC 会将多个事件编码到同一个 Kafka 消息中，并尽量避免在此过程中生成长度超过 `max-message-bytes` 的消息。 -> 如果单条数据变更编码得到的消息大小超过了 `max-message-bytes` 个字节，changefeed 会报错，并打印错误日志。 +> 当 `protocol` 为 `open-protocol` 时，TiCDC 会将多个事件编码到同一个 Kafka message 中，并使用 `max-message-bytes` 控制合 batch 的大小。如果单条数据变更编码后的消息超过 `max-message-bytes`，但没有超过 Kafka Topic 的 `max.message.bytes`，TiCDC 仍会将其作为一条独立的 Kafka message 发送。 ### TiCDC 使用 Kafka 的认证与授权 @@ -387,9 +386,45 @@ write-key-threshold = 30000 SELECT COUNT(*) FROM INFORMATION_SCHEMA.TIKV_REGION_STATUS WHERE DB_NAME="database1" AND TABLE_NAME="table1" AND IS_INDEX=0; ``` +## 配置 Kafka 消息大小 + +TiCDC Kafka sink 和 Kafka 分别通过以下参数控制消息大小： + +| 参数 | 作用 | +| --- | --- | +| TiCDC `max-message-bytes` | 控制 TiCDC 将多条行变更合并为一条 Kafka message 时的大小。默认值为 `10 MB`。 | +| Kafka Topic `max.message.bytes` | 控制目标 Kafka Topic 可以接收的消息大小。 | +| Kafka broker `message.max.bytes` | 当目标 Topic 不存在或没有使用独立限制时，控制 broker 可以接收的消息大小。 | + +Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如果目标 Topic 不存在，TiCDC 会读取 broker 的 `message.max.bytes`。TiCDC 实际使用的 batch 大小阈值为： + +```text +min(TiCDC max-message-bytes, Kafka 消息大小限制) +``` + +`max-message-bytes` 只影响 TiCDC 是否继续向当前 batch 合入更多行变更，不会阻止 Kafka 已经能够接收的单条消息。 + +例如，使用以下配置时： + +```text +TiCDC max-message-bytes = 10 MiB +Kafka Topic max.message.bytes = 20 MiB +单条行变更编码后的消息大小 = 12 MiB +``` + +TiCDC 不会再向这条 12 MiB 的消息合入其他行变更，但可以将它作为一条独立的 Kafka message 发送。 + +如果单条消息超过 Kafka 当前的消息大小限制，TiCDC 会返回 `ErrMessageTooLarge`。此时，请调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 broker 的 `message.max.bytes`。Kafka sink 重试或重建后会重新读取 Kafka 配置，不需要同时修改 TiCDC changefeed 的 `max-message-bytes`。 + +> **注意：** +> +> 如果 TiCDC 因 Kafka ACL 等原因无法读取 Topic 或 broker 配置，会使用 TiCDC `max-message-bytes` 的值作为 producer 消息大小上限。若需要 TiCDC 自动读取 Kafka 的消息大小限制，请确保 TiCDC 使用的 Kafka 账号具有相应的配置读取权限。 + ## 处理超过 Kafka Topic 限制的消息 -Kafka Topic 对可以接收的消息大小有限制，该限制由 [`max.message.bytes`](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes) 参数控制。当 TiCDC Kafka sink 在发送数据时，如果发现数据大小超过了该限制，会导致 changefeed 报错，无法继续同步数据。为了解决这个问题，TiCDC 新增一个参数 `large-message-handle-option` 并提供如下解决方案。 +Kafka Topic 对可以接收的消息大小有限制，该限制由 [`max.message.bytes`](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes) 参数控制。当原始消息超过 Kafka 当前的消息大小限制时，TiCDC 可以通过 `large-message-handle-option` 处理该消息。 + +`large-message-handle-option` 不会仅因为消息超过 TiCDC `max-message-bytes` 而触发。如果消息超过 TiCDC `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 会直接发送原始消息。 目前，如下功能支持 Canal-JSON 和 Open Protocol 两种编码协议。使用 Canal-JSON 协议时，你需要在 `sink-uri` 中设置 `enable-tidb-extension=true`。 diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index cd39eb9df321..d48bed31cf1b 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -104,17 +104,21 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin ## 使用 TiCDC 同步消息到 Kafka 时 Kafka 报错 `Message was too large`，该如何处理？ -仅在 Sink URI 中为 Kafka 配置 `max-message-bytes` 参数不能有效控制输出到 Kafka 的消息大小，需要在 Kafka server 配置中加入如下配置以增加 Kafka 接收消息的字节数限制。 +TiCDC `max-message-bytes` 参数只控制 TiCDC 合 batch 的大小，不控制 Kafka 能接收的消息大小。出现该错误时，请根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。 ``` -# broker 能接收消息的最大字节数 -message.max.bytes=2147483648 +# Topic 能接收消息的最大字节数 +max.message.bytes=<不小于待发送消息的大小> +# broker 能接收消息的最大字节数，使用 broker 默认限制时配置 +message.max.bytes=<不小于待发送消息的大小> # broker 可复制的消息的最大字节数 -replica.fetch.max.bytes=2147483648 +replica.fetch.max.bytes=<不小于 message.max.bytes> # 消费者端的可读取的最大消息字节数 -fetch.message.max.bytes=2147483648 +fetch.message.max.bytes=<不小于 Kafka 中实际允许的消息大小> ``` +Kafka sink 重试或重建后会重新读取 Kafka 配置。通常不需要同时修改 changefeed 的 `max-message-bytes`。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 + ## TiCDC 同步时，在下游执行 DDL 语句失败会有什么表现，如何恢复？ 如果某条 DDL 语句执行失败，同步任务 (changefeed) 会自动停止，checkpoint-ts 断点时间戳为该条出错 DDL 语句的结束时间戳 (finish-ts)。如果希望让 TiCDC 在下游重试执行这条 DDL 语句，可以使用 `cdc cli changefeed resume` 恢复同步任务。例如： From ce6fec48e075da407812e3a01ab45b00cec4953a Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 15:08:55 +0800 Subject: [PATCH 2/9] add ticdc kafka faq --- ticdc/ticdc-faq.md | 8 -------- ticdc/ticdc-open-protocol.md | 19 +++++++++++++++++++ ticdc/ticdc-sink-to-kafka.md | 31 +++++++++---------------------- ticdc/troubleshoot-ticdc.md | 6 ++++-- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/ticdc/ticdc-faq.md b/ticdc/ticdc-faq.md index 7b07c4b9aaa9..6d2d086a3c8c 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -238,14 +238,6 @@ cdc cli changefeed create --server=http://127.0.0.1:8300 --sink-uri="kafka://127 * `replica.fetch.max.bytes`，将 Kafka 的 `server.properties` 中该参数调大到 `1073741824` (1 GB)。 * `fetch.message.max.bytes`，适当调大 `consumer.properties` 中该参数，确保大于 `message.max.bytes`。 -## TiCDC 把数据同步到 Kafka 时，能在 TiDB 中控制单条消息大小的上限吗？ - -`max-message-bytes` 控制 TiCDC 将多条行变更合并为一条 Kafka message 时的大小，默认值为 `10 MB`。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。 - -对于 Open Protocol，一条 Kafka message 可能包含多条行变更。可以通过 `max-message-bytes` 控制合 batch 的大小，并通过 `max-batch-size` 控制每条 Kafka message 中的最大行变更数量。如果单条行变更编码后的消息超过 `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 仍会将其作为一条独立的 Kafka message 发送。 - -如果需要限制 Kafka 实际接收的消息大小，请配置 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes`。详情参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 - ## 在一个事务中对一行进行多次修改，TiCDC 会输出多条行变更事件吗？ 不会，在进行事务操作时，对于在一个事务内多次修改同一行的情况，TiDB 仅会将最新一次的修改结果发送给 TiKV。因此 TiCDC 仅能获取到最新一次修改的结果。 diff --git a/ticdc/ticdc-open-protocol.md b/ticdc/ticdc-open-protocol.md index d1f6d8e065ea..33b88a6fc7ae 100644 --- a/ticdc/ticdc-open-protocol.md +++ b/ticdc/ticdc-open-protocol.md @@ -44,6 +44,25 @@ Value: * 长度及协议版本号均为大端序 int64 类型 * 当前协议版本号为 `1` +### 控制 Message 中的 Event 数量和大小 + +使用 Open Protocol 将数据同步到 Kafka 时，TiCDC 可以将多个 Row Changed Event 编码到同一条 Kafka message 中。相关参数如下： + +| 参数 | 作用 | +| --- | --- | +| `max-batch-size` | 每条 Kafka message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | +| `max-message-bytes` | TiCDC 将多个 Row Changed Event 编码到同一条 Kafka message 时使用的大小阈值。实际生效值参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 | + +当继续加入一个 Row Changed Event 会使消息大小超过 `max-message-bytes`，或者消息中的 Event 数量已经达到 `max-batch-size` 时，TiCDC 会创建一条新的 Kafka message。例如： + +```shell +--sink-uri="kafka://127.0.0.1:9092/topic-name?protocol=open-protocol&max-message-bytes=1048576&max-batch-size=64" +``` + +`max-message-bytes` 不会拆分单个 Row Changed Event。从 v8.5.8 起，如果单个 Row Changed Event 编码后的消息超过 `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 会将其作为一条独立的 Kafka message 发送。 + +关于 Kafka 消息大小限制以及 `ErrMessageTooLarge` 的处理方法，参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)和[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时-kafka-报错-message-was-too-large该如何处理)。 + ## Event 格式定义 本部分介绍 Row Changed Event、DDL Event 和 Resolved Event 的格式定义。 diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index 0a617936ae1b..fc18da63b60f 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -77,13 +77,13 @@ URI 中可配置的的参数如下： | `kafka-version` | 下游 Kafka 版本号。该值需要与下游 Kafka 的实际版本保持一致。 | | `kafka-client-id` | 指定同步任务的 Kafka 客户端的 ID（可选，默认值为 `TiCDC_sarama_producer_同步任务的 ID`）。 | | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量，否则创建同步任务会失败，默认值 `3`）。| -| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。| +| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。使用 Open Protocol 时的详细说明，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| | `replication-factor` | Kafka 消息保存副本数（可选，默认值 `1`），需要大于等于 Kafka 中 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 的值。 | | `required-acks` | 在 `Produce` 请求中使用的配置项，用于告知 broker 需要收到多少副本确认后才进行响应。可选值有：`0`（`NoResponse`：不发送任何响应，只有 TCP ACK），`1`（`WaitForLocal`：仅等待本地提交成功后再响应）和 `-1`（`WaitForAll`：等待所有同步副本提交后再响应。最小同步副本数量可通过 broker 的 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 配置项进行配置）。（可选，默认值为 `-1`）。 | | `compression` | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。注意 Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。| | `auto-create-topic` | 当传入的 `topic-name` 在 Kafka 集群不存在时，TiCDC 是否要自动创建该 topic（可选，默认值 `true`）。 | | `enable-tidb-extension` | 可选，默认值是 `false`。当输出协议为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [WATERMARK 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 Kafka 消息中添加 TiDB 扩展字段。从 6.1.0 开始，该参数也可以和输出协议 `avro` 一起使用。如果该值为 `true`，TiCDC 会在 Kafka 消息中添加[三个 TiDB 扩展字段](/ticdc/ticdc-avro-protocol.md#tidb-扩展字段)。| -| `max-batch-size` | 从 v4.0.9 开始引入。当消息协议支持把多条变更记录输出至一条 Kafka 消息时，该参数用于指定这一条 Kafka 消息中变更记录的最多数量。目前，仅当 Kafka 消息的 `protocol` 为 `open-protocol` 时有效（可选，默认值 `16`）。| +| `max-batch-size` | 从 v4.0.9 开始引入。当消息协议支持把多条变更记录输出至一条 Kafka 消息时，该参数用于指定这一条 Kafka 消息中变更记录的最多数量。目前，仅当 Kafka 消息的 `protocol` 为 `open-protocol` 时有效（可选，默认值 `16`）。详细说明参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| | `enable-tls` | 连接下游 Kafka 实例是否使用 TLS（可选，默认值 `false`）。 | | `ca` | 连接下游 Kafka 实例所需的 CA 证书文件路径（可选）。 | | `cert` | 连接下游 Kafka 实例所需的证书文件路径（可选）。 | @@ -113,10 +113,6 @@ URI 中可配置的的参数如下： * 在大多数情况下，建议使用 `canal-json` 协议。 * 如果 TiCDC 上游的数据变更很少，比如可能会出现超过 10 分钟没有数据变更的情况，建议在 Kafka broker 的配置文件中调大 Kafka 的连接空闲超时时间，详情参考[为什么 TiCDC 同步到 Kafka 的任务经常因 `broken pipe` 报错而失败](/ticdc/ticdc-faq.md#为什么-ticdc-同步到-kafka-的任务经常因-broken-pipe-报错而失败)。 -> **注意：** -> -> 当 `protocol` 为 `open-protocol` 时，TiCDC 会将多个事件编码到同一个 Kafka message 中，并使用 `max-message-bytes` 控制合 batch 的大小。如果单条数据变更编码后的消息超过 `max-message-bytes`，但没有超过 Kafka Topic 的 `max.message.bytes`，TiCDC 仍会将其作为一条独立的 Kafka message 发送。 - ### TiCDC 使用 Kafka 的认证与授权 使用 Kafka 的 SASL 认证时配置样例如下所示： @@ -388,33 +384,24 @@ SELECT COUNT(*) FROM INFORMATION_SCHEMA.TIKV_REGION_STATUS WHERE DB_NAME="databa ## 配置 Kafka 消息大小 -TiCDC Kafka sink 和 Kafka 分别通过以下参数控制消息大小： +Kafka 通过以下参数控制可以接收的消息大小： | 参数 | 作用 | | --- | --- | -| TiCDC `max-message-bytes` | 控制 TiCDC 将多条行变更合并为一条 Kafka message 时的大小。默认值为 `10 MB`。 | | Kafka Topic `max.message.bytes` | 控制目标 Kafka Topic 可以接收的消息大小。 | -| Kafka broker `message.max.bytes` | 当目标 Topic 不存在或没有使用独立限制时，控制 broker 可以接收的消息大小。 | +| Kafka broker `message.max.bytes` | 当目标 Topic 没有配置独立限制时，控制 broker 可以接收的消息大小。 | -Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如果目标 Topic 不存在，TiCDC 会读取 broker 的 `message.max.bytes`。TiCDC 实际使用的 batch 大小阈值为： +Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如果无法从 Topic 配置中获取该参数，TiCDC 会读取 broker 的 `message.max.bytes`。 -```text -min(TiCDC max-message-bytes, Kafka 消息大小限制) -``` - -`max-message-bytes` 只影响 TiCDC 是否继续向当前 batch 合入更多行变更，不会阻止 Kafka 已经能够接收的单条消息。 - -例如，使用以下配置时： +TiCDC 实际使用的 batch 大小阈值为： ```text -TiCDC max-message-bytes = 10 MiB -Kafka Topic max.message.bytes = 20 MiB -单条行变更编码后的消息大小 = 12 MiB +min(TiCDC max-message-bytes, Kafka 消息大小限制) ``` -TiCDC 不会再向这条 12 MiB 的消息合入其他行变更，但可以将它作为一条独立的 Kafka message 发送。 +从 v8.5.8 起，TiCDC 将 batch 大小阈值与 Kafka 的消息大小限制分开处理。TiCDC 的 `max-message-bytes` 用于控制 batch 大小，不会阻止 Kafka 已经能够接收的单条消息。使用 Open Protocol 时，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。 -如果单条消息超过 Kafka 当前的消息大小限制，TiCDC 会返回 `ErrMessageTooLarge`。此时，请调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 broker 的 `message.max.bytes`。Kafka sink 重试或重建后会重新读取 Kafka 配置，不需要同时修改 TiCDC changefeed 的 `max-message-bytes`。 +如果 TiCDC 返回 `ErrMessageTooLarge`，或者 Kafka 返回 `Message was too large`，参见[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时-kafka-报错-message-was-too-large该如何处理)。 > **注意：** > diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index d48bed31cf1b..b2342c20673f 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -104,7 +104,7 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin ## 使用 TiCDC 同步消息到 Kafka 时 Kafka 报错 `Message was too large`，该如何处理？ -TiCDC `max-message-bytes` 参数只控制 TiCDC 合 batch 的大小，不控制 Kafka 能接收的消息大小。出现该错误时，请根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。 +当 TiCDC 返回 `ErrMessageTooLarge` 或 Kafka 返回 `Message was too large` 时，表示待发送的消息超过了 Kafka 当前允许的消息大小。请根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。 ``` # Topic 能接收消息的最大字节数 @@ -117,7 +117,9 @@ replica.fetch.max.bytes=<不小于 message.max.bytes> fetch.message.max.bytes=<不小于 Kafka 中实际允许的消息大小> ``` -Kafka sink 重试或重建后会重新读取 Kafka 配置。通常不需要同时修改 changefeed 的 `max-message-bytes`。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 +从 v8.5.8 起，Kafka sink 重试或重建后会重新读取 Kafka 配置。调大 Kafka 的消息大小限制后，TiCDC 可以在重试过程中自动恢复同步，不需要同时修改 changefeed 的 `max-message-bytes`，也不需要暂停或恢复 changefeed。 + +如果不希望调大 Kafka 的消息大小限制，可以配置 `large-message-handle-option`，使用 Claim-Check 或只输出 Handle Key 的方式处理大消息。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)和[处理超过 Kafka Topic 限制的消息](/ticdc/ticdc-sink-to-kafka.md#处理超过-kafka-topic-限制的消息)。 ## TiCDC 同步时，在下游执行 DDL 语句失败会有什么表现，如何恢复？ From c4edd7dcb68ea9e16666f9bb6d82c195495d898a Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 15:19:39 +0800 Subject: [PATCH 3/9] update document --- ticdc/ticdc-open-protocol.md | 10 +++------- ticdc/ticdc-sink-to-kafka.md | 16 +++------------- ticdc/troubleshoot-ticdc.md | 17 ++++++++++++----- 3 files changed, 18 insertions(+), 25 deletions(-) diff --git a/ticdc/ticdc-open-protocol.md b/ticdc/ticdc-open-protocol.md index 33b88a6fc7ae..c65392477961 100644 --- a/ticdc/ticdc-open-protocol.md +++ b/ticdc/ticdc-open-protocol.md @@ -46,23 +46,19 @@ Value: ### 控制 Message 中的 Event 数量和大小 -使用 Open Protocol 将数据同步到 Kafka 时，TiCDC 可以将多个 Row Changed Event 编码到同一条 Kafka message 中。相关参数如下： +使用 Open Protocol 将数据同步到 Kafka 时，TiCDC 会先分别序列化每个 Row Changed Event，再将多个序列化后的 Event 组成一条 Kafka message。你可以通过以下参数控制一条 Kafka message 中的 Event 数量和大小： | 参数 | 作用 | | --- | --- | | `max-batch-size` | 每条 Kafka message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | -| `max-message-bytes` | TiCDC 将多个 Row Changed Event 编码到同一条 Kafka message 时使用的大小阈值。实际生效值参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 | +| `max-message-bytes` | Kafka message 的大小阈值。实际生效值为 `min(TiCDC max-message-bytes, Kafka 消息大小限制)`。Kafka 消息大小限制的确定方式参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 | -当继续加入一个 Row Changed Event 会使消息大小超过 `max-message-bytes`，或者消息中的 Event 数量已经达到 `max-batch-size` 时，TiCDC 会创建一条新的 Kafka message。例如： +当 Kafka message 中的 Event 数量已经达到 `max-batch-size`，或者继续加入下一个序列化后的 Event 会使消息超过实际生效的大小阈值时，TiCDC 会创建一条新的 Kafka message。例如： ```shell --sink-uri="kafka://127.0.0.1:9092/topic-name?protocol=open-protocol&max-message-bytes=1048576&max-batch-size=64" ``` -`max-message-bytes` 不会拆分单个 Row Changed Event。从 v8.5.8 起，如果单个 Row Changed Event 编码后的消息超过 `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 会将其作为一条独立的 Kafka message 发送。 - -关于 Kafka 消息大小限制以及 `ErrMessageTooLarge` 的处理方法，参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)和[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时-kafka-报错-message-was-too-large该如何处理)。 - ## Event 格式定义 本部分介绍 Row Changed Event、DDL Event 和 Resolved Event 的格式定义。 diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index fc18da63b60f..4da6ffc64c87 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -77,7 +77,7 @@ URI 中可配置的的参数如下： | `kafka-version` | 下游 Kafka 版本号。该值需要与下游 Kafka 的实际版本保持一致。 | | `kafka-client-id` | 指定同步任务的 Kafka 客户端的 ID（可选，默认值为 `TiCDC_sarama_producer_同步任务的 ID`）。 | | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量，否则创建同步任务会失败，默认值 `3`）。| -| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。该参数不限制单条行变更编码后的消息大小。Kafka 能接收的消息大小由 topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 决定。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。使用 Open Protocol 时的详细说明，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| +| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。使用 Open Protocol 时的详细说明，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| | `replication-factor` | Kafka 消息保存副本数（可选，默认值 `1`），需要大于等于 Kafka 中 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 的值。 | | `required-acks` | 在 `Produce` 请求中使用的配置项，用于告知 broker 需要收到多少副本确认后才进行响应。可选值有：`0`（`NoResponse`：不发送任何响应，只有 TCP ACK），`1`（`WaitForLocal`：仅等待本地提交成功后再响应）和 `-1`（`WaitForAll`：等待所有同步副本提交后再响应。最小同步副本数量可通过 broker 的 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 配置项进行配置）。（可选，默认值为 `-1`）。 | | `compression` | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。注意 Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。| @@ -108,7 +108,7 @@ URI 中可配置的的参数如下： ### 最佳实践 -* TiCDC 推荐用户自行创建 Kafka Topic，并根据业务需要设置该 Topic 的 `max.message.bytes` 和 partition 数量。创建 changefeed 时，可以通过 `partition-num` 指定 partition 数量。`max-message-bytes` 只控制 TiCDC 合 batch 的大小，不会修改 Kafka Topic 的 `max.message.bytes`。 +* TiCDC 推荐用户自行创建 Kafka Topic，并根据业务需要设置该 Topic 的 `max.message.bytes` 和 partition 数量。创建 changefeed 时，可以通过 `partition-num` 指定 partition 数量。 * 如果你在创建 changefeed 时，使用了尚未存在的 Topic，那么 TiCDC 会尝试使用 `partition-num` 和 `replication-factor` 参数自行创建 Topic，建议明确指定这两个参数。 * 在大多数情况下，建议使用 `canal-json` 协议。 * 如果 TiCDC 上游的数据变更很少，比如可能会出现超过 10 分钟没有数据变更的情况，建议在 Kafka broker 的配置文件中调大 Kafka 的连接空闲超时时间，详情参考[为什么 TiCDC 同步到 Kafka 的任务经常因 `broken pipe` 报错而失败](/ticdc/ticdc-faq.md#为什么-ticdc-同步到-kafka-的任务经常因-broken-pipe-报错而失败)。 @@ -393,15 +393,7 @@ Kafka 通过以下参数控制可以接收的消息大小： Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如果无法从 Topic 配置中获取该参数，TiCDC 会读取 broker 的 `message.max.bytes`。 -TiCDC 实际使用的 batch 大小阈值为： - -```text -min(TiCDC max-message-bytes, Kafka 消息大小限制) -``` - -从 v8.5.8 起，TiCDC 将 batch 大小阈值与 Kafka 的消息大小限制分开处理。TiCDC 的 `max-message-bytes` 用于控制 batch 大小，不会阻止 Kafka 已经能够接收的单条消息。使用 Open Protocol 时，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。 - -如果 TiCDC 返回 `ErrMessageTooLarge`，或者 Kafka 返回 `Message was too large`，参见[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时-kafka-报错-message-was-too-large该如何处理)。 +如果 TiCDC 返回 `ErrMessageTooLarge`，或者 Kafka 返回 `Message was too large`，参见[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时遇到-errmessagetoolarge-或-message-was-too-large该如何处理)。 > **注意：** > @@ -411,8 +403,6 @@ min(TiCDC max-message-bytes, Kafka 消息大小限制) Kafka Topic 对可以接收的消息大小有限制，该限制由 [`max.message.bytes`](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes) 参数控制。当原始消息超过 Kafka 当前的消息大小限制时，TiCDC 可以通过 `large-message-handle-option` 处理该消息。 -`large-message-handle-option` 不会仅因为消息超过 TiCDC `max-message-bytes` 而触发。如果消息超过 TiCDC `max-message-bytes`，但没有超过 Kafka 的消息大小限制，TiCDC 会直接发送原始消息。 - 目前，如下功能支持 Canal-JSON 和 Open Protocol 两种编码协议。使用 Canal-JSON 协议时，你需要在 `sink-uri` 中设置 `enable-tidb-extension=true`。 ### TiCDC 层数据压缩功能 diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index b2342c20673f..1c2168b13739 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -102,9 +102,18 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin - 如果 PD 是由 v4.0.8 或更低版本滚动升级到新版，详见 [PD issue #3366](https://github.com/tikv/pd/issues/3366)。 - 对于其他情况，请将上述命令执行结果反馈到 [AskTUG 论坛](https://pingkai.cn/tidbcommunity/forum/tags/ticdc)。 -## 使用 TiCDC 同步消息到 Kafka 时 Kafka 报错 `Message was too large`，该如何处理？ +## 使用 TiCDC 同步消息到 Kafka 时遇到 `ErrMessageTooLarge` 或 `Message was too large`，该如何处理？ -当 TiCDC 返回 `ErrMessageTooLarge` 或 Kafka 返回 `Message was too large` 时，表示待发送的消息超过了 Kafka 当前允许的消息大小。请根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。 +处理方式取决于 TiCDC 版本： + +| TiCDC 版本 | 处理方式 | +| --- | --- | +| v8.5.8 及之后版本 | 根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。Kafka sink 重试或重建后会重新读取 Kafka 配置并自动恢复同步，不需要修改、暂停或恢复 changefeed。 | +| v8.5.8 之前的版本 | 调大 changefeed 的 `max-message-bytes`，并确保 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 不小于待发送消息的大小。更新 changefeed 配置后，TiCDC 会使用新的限制重新创建 Kafka sink。 | + +对于 v8.5.8 及之后版本，如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 TiCDC 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 + +调整 Kafka 消息大小限制时，还需要检查以下相关配置： ``` # Topic 能接收消息的最大字节数 @@ -117,9 +126,7 @@ replica.fetch.max.bytes=<不小于 message.max.bytes> fetch.message.max.bytes=<不小于 Kafka 中实际允许的消息大小> ``` -从 v8.5.8 起，Kafka sink 重试或重建后会重新读取 Kafka 配置。调大 Kafka 的消息大小限制后，TiCDC 可以在重试过程中自动恢复同步，不需要同时修改 changefeed 的 `max-message-bytes`，也不需要暂停或恢复 changefeed。 - -如果不希望调大 Kafka 的消息大小限制，可以配置 `large-message-handle-option`，使用 Claim-Check 或只输出 Handle Key 的方式处理大消息。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)和[处理超过 Kafka Topic 限制的消息](/ticdc/ticdc-sink-to-kafka.md#处理超过-kafka-topic-限制的消息)。 +如果不希望调大 Kafka 的消息大小限制，可以配置 `large-message-handle-option`，使用 Claim-Check 或只输出 Handle Key 的方式处理大消息。更多信息参见[处理超过 Kafka Topic 限制的消息](/ticdc/ticdc-sink-to-kafka.md#处理超过-kafka-topic-限制的消息)。 ## TiCDC 同步时，在下游执行 DDL 语句失败会有什么表现，如何恢复？ From c9a7de26dc06f897caf4801068a1936e5bfde8aa Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 15:27:37 +0800 Subject: [PATCH 4/9] update document --- ticdc/ticdc-open-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-open-protocol.md b/ticdc/ticdc-open-protocol.md index c65392477961..938e6d17bbd3 100644 --- a/ticdc/ticdc-open-protocol.md +++ b/ticdc/ticdc-open-protocol.md @@ -46,14 +46,14 @@ Value: ### 控制 Message 中的 Event 数量和大小 -使用 Open Protocol 将数据同步到 Kafka 时，TiCDC 会先分别序列化每个 Row Changed Event，再将多个序列化后的 Event 组成一条 Kafka message。你可以通过以下参数控制一条 Kafka message 中的 Event 数量和大小： +在 Open Protocol 中，每个 Row Changed Event 会先被单独序列化，多个序列化后的 Event 可以组成一条 Message。对于 Kafka Sink，你可以通过以下参数控制一条 Kafka message 中的 Event 数量和大小： | 参数 | 作用 | | --- | --- | | `max-batch-size` | 每条 Kafka message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | | `max-message-bytes` | Kafka message 的大小阈值。实际生效值为 `min(TiCDC max-message-bytes, Kafka 消息大小限制)`。Kafka 消息大小限制的确定方式参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 | -当 Kafka message 中的 Event 数量已经达到 `max-batch-size`，或者继续加入下一个序列化后的 Event 会使消息超过实际生效的大小阈值时，TiCDC 会创建一条新的 Kafka message。例如： +当 Kafka message 中的 Event 数量已经达到 `max-batch-size`，或者继续加入下一个序列化后的 Event 会使消息超过实际生效的大小阈值时，后续 Event 会被写入一条新的 Kafka message。例如： ```shell --sink-uri="kafka://127.0.0.1:9092/topic-name?protocol=open-protocol&max-message-bytes=1048576&max-batch-size=64" From a882d2fc303a8fff39f3be7e5407739be153c57d Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 16:01:36 +0800 Subject: [PATCH 5/9] update document --- ticdc/ticdc-open-protocol.md | 12 +++++------- ticdc/ticdc-sink-to-kafka.md | 6 +++--- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/ticdc/ticdc-open-protocol.md b/ticdc/ticdc-open-protocol.md index 938e6d17bbd3..db9bfc1ebf72 100644 --- a/ticdc/ticdc-open-protocol.md +++ b/ticdc/ticdc-open-protocol.md @@ -46,18 +46,16 @@ Value: ### 控制 Message 中的 Event 数量和大小 -在 Open Protocol 中，每个 Row Changed Event 会先被单独序列化，多个序列化后的 Event 可以组成一条 Message。对于 Kafka Sink，你可以通过以下参数控制一条 Kafka message 中的 Event 数量和大小： +Open Protocol 可将一个或多个 Row Changed Event 编码为一条 Message。Kafka Sink 的以下参数分别控制一条 Message 中的 Row Changed Event 数量和 Message 大小： | 参数 | 作用 | | --- | --- | -| `max-batch-size` | 每条 Kafka message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | -| `max-message-bytes` | Kafka message 的大小阈值。实际生效值为 `min(TiCDC max-message-bytes, Kafka 消息大小限制)`。Kafka 消息大小限制的确定方式参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 | +| `max-batch-size` | 每条 Message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | +| `max-message-bytes` | 控制 Message 的大小阈值。 | -当 Kafka message 中的 Event 数量已经达到 `max-batch-size`，或者继续加入下一个序列化后的 Event 会使消息超过实际生效的大小阈值时，后续 Event 会被写入一条新的 Kafka message。例如： +Kafka Sink 会比较 changefeed 中配置的 `max-message-bytes` 与 Kafka 允许的消息大小限制，并使用其中的较小值作为实际阈值，避免批量编码后的 Message 超过 Kafka 允许的大小。Kafka 消息大小限制的确定方式参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 -```shell ---sink-uri="kafka://127.0.0.1:9092/topic-name?protocol=open-protocol&max-message-bytes=1048576&max-batch-size=64" -``` +当 Message 中的 Row Changed Event 数量已经达到 `max-batch-size`，或者继续加入下一个 Row Changed Event 会使 Message 超过实际生效的大小阈值时，后续 Row Changed Event 会被写入一条新的 Message。 ## Event 格式定义 diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index 4da6ffc64c87..e64cbac21f94 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -77,13 +77,13 @@ URI 中可配置的的参数如下： | `kafka-version` | 下游 Kafka 版本号。该值需要与下游 Kafka 的实际版本保持一致。 | | `kafka-client-id` | 指定同步任务的 Kafka 客户端的 ID（可选，默认值为 `TiCDC_sarama_producer_同步任务的 ID`）。 | | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量，否则创建同步任务会失败，默认值 `3`）。| -| `max-message-bytes` | TiCDC 将多条行变更编码到同一条 Kafka message 时使用的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。从 v5.0.6 和 v4.0.6 开始，该参数的默认值分别从 `64 MB` 和 `256 MB` 调整至 `10 MB`。使用 Open Protocol 时的详细说明，参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| +| `max-message-bytes` | Open Protocol Message 的大小阈值（可选，默认值 `10 MB`，最大值为 `100 MB`）。实际生效规则参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| +| `max-batch-size` | Open Protocol Message 最多包含的 Row Changed Event 数量（可选，默认值 `16`）。详细说明参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| | `replication-factor` | Kafka 消息保存副本数（可选，默认值 `1`），需要大于等于 Kafka 中 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 的值。 | | `required-acks` | 在 `Produce` 请求中使用的配置项，用于告知 broker 需要收到多少副本确认后才进行响应。可选值有：`0`（`NoResponse`：不发送任何响应，只有 TCP ACK），`1`（`WaitForLocal`：仅等待本地提交成功后再响应）和 `-1`（`WaitForAll`：等待所有同步副本提交后再响应。最小同步副本数量可通过 broker 的 [`min.insync.replicas`](https://kafka.apache.org/33/documentation.html#brokerconfigs_min.insync.replicas) 配置项进行配置）。（可选，默认值为 `-1`）。 | | `compression` | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。注意 Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。| | `auto-create-topic` | 当传入的 `topic-name` 在 Kafka 集群不存在时，TiCDC 是否要自动创建该 topic（可选，默认值 `true`）。 | | `enable-tidb-extension` | 可选，默认值是 `false`。当输出协议为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [WATERMARK 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 Kafka 消息中添加 TiDB 扩展字段。从 6.1.0 开始，该参数也可以和输出协议 `avro` 一起使用。如果该值为 `true`，TiCDC 会在 Kafka 消息中添加[三个 TiDB 扩展字段](/ticdc/ticdc-avro-protocol.md#tidb-扩展字段)。| -| `max-batch-size` | 从 v4.0.9 开始引入。当消息协议支持把多条变更记录输出至一条 Kafka 消息时，该参数用于指定这一条 Kafka 消息中变更记录的最多数量。目前，仅当 Kafka 消息的 `protocol` 为 `open-protocol` 时有效（可选，默认值 `16`）。详细说明参见[控制 Message 中的 Event 数量和大小](/ticdc/ticdc-open-protocol.md#控制-message-中的-event-数量和大小)。| | `enable-tls` | 连接下游 Kafka 实例是否使用 TLS（可选，默认值 `false`）。 | | `ca` | 连接下游 Kafka 实例所需的 CA 证书文件路径（可选）。 | | `cert` | 连接下游 Kafka 实例所需的证书文件路径（可选）。 | @@ -397,7 +397,7 @@ Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如 > **注意：** > -> 如果 TiCDC 因 Kafka ACL 等原因无法读取 Topic 或 broker 配置，会使用 TiCDC `max-message-bytes` 的值作为 producer 消息大小上限。若需要 TiCDC 自动读取 Kafka 的消息大小限制，请确保 TiCDC 使用的 Kafka 账号具有相应的配置读取权限。 +> 如果 Kafka Sink 因 Kafka ACL 等原因无法读取 Topic 或 broker 的消息大小配置，会使用 changefeed 的 `max-message-bytes` 作为本地消息大小限制。若需要 Kafka Sink 自动读取 Kafka 的消息大小限制，请确保 changefeed 使用的 Kafka 账号具有相应的配置读取权限。 ## 处理超过 Kafka Topic 限制的消息 From ecf273d7c90da501f32e00d3bc55d06dbaa5789f Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 16:33:29 +0800 Subject: [PATCH 6/9] add more --- ticdc/ticdc-open-protocol.md | 2 +- ticdc/ticdc-sink-to-kafka.md | 14 ++++++-------- ticdc/troubleshoot-ticdc.md | 8 ++++---- 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/ticdc/ticdc-open-protocol.md b/ticdc/ticdc-open-protocol.md index db9bfc1ebf72..67fbea7d8f8c 100644 --- a/ticdc/ticdc-open-protocol.md +++ b/ticdc/ticdc-open-protocol.md @@ -53,7 +53,7 @@ Open Protocol 可将一个或多个 Row Changed Event 编码为一条 Message。 | `max-batch-size` | 每条 Message 最多包含的 Row Changed Event 数量，默认值为 `16`。 | | `max-message-bytes` | 控制 Message 的大小阈值。 | -Kafka Sink 会比较 changefeed 中配置的 `max-message-bytes` 与 Kafka 允许的消息大小限制，并使用其中的较小值作为实际阈值，避免批量编码后的 Message 超过 Kafka 允许的大小。Kafka 消息大小限制的确定方式参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 +Kafka Sink 会比较 changefeed 中配置的 `max-message-bytes` 与 Kafka 允许的消息大小限制，并使用其中的较小值作为实际阈值，避免批量编码后的 Message 超过 Kafka 允许的大小。Kafka 消息大小限制的确定方式参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 当 Message 中的 Row Changed Event 数量已经达到 `max-batch-size`，或者继续加入下一个 Row Changed Event 会使 Message 超过实际生效的大小阈值时，后续 Row Changed Event 会被写入一条新的 Message。 diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index e64cbac21f94..4f9ae31371a4 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -382,22 +382,20 @@ write-key-threshold = 30000 SELECT COUNT(*) FROM INFORMATION_SCHEMA.TIKV_REGION_STATUS WHERE DB_NAME="database1" AND TABLE_NAME="table1" AND IS_INDEX=0; ``` -## 配置 Kafka 消息大小 +## Kafka 消息大小限制 -Kafka 通过以下参数控制可以接收的消息大小： +Kafka 对可以接收的消息大小设有默认限制，通常无需调整。只有当 changefeed 需要发送的单条消息超过当前限制时，才需要调大该限制，或者使用[大消息处理功能](#处理超过-kafka-topic-限制的消息)。 | 参数 | 作用 | | --- | --- | -| Kafka Topic `max.message.bytes` | 控制目标 Kafka Topic 可以接收的消息大小。 | -| Kafka broker `message.max.bytes` | 当目标 Topic 没有配置独立限制时，控制 broker 可以接收的消息大小。 | +| Kafka Topic `max.message.bytes` | 为指定 Topic 设置消息大小限制，覆盖 broker 的默认值。 | +| Kafka broker `message.max.bytes` | Topic 未设置 `max.message.bytes` 时使用的默认值。 | -Kafka sink 启动时，TiCDC 会读取目标 Topic 的 `max.message.bytes`。如果无法从 Topic 配置中获取该参数，TiCDC 会读取 broker 的 `message.max.bytes`。 - -如果 TiCDC 返回 `ErrMessageTooLarge`，或者 Kafka 返回 `Message was too large`，参见[使用 TiCDC 同步消息到 Kafka 时遇到消息过大错误的处理方法](/ticdc/troubleshoot-ticdc.md#使用-ticdc-同步消息到-kafka-时遇到-errmessagetoolarge-或-message-was-too-large该如何处理)。 +Kafka Sink 启动时会读取目标 Topic 当前生效的消息大小限制，用于在发送前判断消息是否过大。如果编码后的单条消息超过该限制且未配置大消息处理，Kafka Sink 会返回 `ErrMessageTooLarge`。处理方法参见[Kafka Sink 返回 `ErrMessageTooLarge` 时，如何处理？](/ticdc/troubleshoot-ticdc.md#kafka-sink-返回-errmessagetoolarge-时如何处理)。 > **注意：** > -> 如果 Kafka Sink 因 Kafka ACL 等原因无法读取 Topic 或 broker 的消息大小配置，会使用 changefeed 的 `max-message-bytes` 作为本地消息大小限制。若需要 Kafka Sink 自动读取 Kafka 的消息大小限制，请确保 changefeed 使用的 Kafka 账号具有相应的配置读取权限。 +> 如果 Kafka Sink 因 Kafka ACL 等原因无法读取 Topic 或 broker 的消息大小配置，会使用 changefeed 的 `max-message-bytes` 作为本地消息大小限制。如果该值与 Kafka 实际生效的限制不一致，Kafka Sink 可能无法准确判断消息能否发送，调大 Kafka 的限制后也可能无法自动恢复。请确保 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限；如果无法授予该权限，需要手动保持 changefeed 的 `max-message-bytes` 与 Kafka 的消息大小限制一致。 ## 处理超过 Kafka Topic 限制的消息 diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index 1c2168b13739..9975da21f246 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -102,16 +102,16 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin - 如果 PD 是由 v4.0.8 或更低版本滚动升级到新版，详见 [PD issue #3366](https://github.com/tikv/pd/issues/3366)。 - 对于其他情况，请将上述命令执行结果反馈到 [AskTUG 论坛](https://pingkai.cn/tidbcommunity/forum/tags/ticdc)。 -## 使用 TiCDC 同步消息到 Kafka 时遇到 `ErrMessageTooLarge` 或 `Message was too large`，该如何处理？ +## Kafka Sink 返回 `ErrMessageTooLarge` 时，如何处理？ 处理方式取决于 TiCDC 版本： | TiCDC 版本 | 处理方式 | | --- | --- | -| v8.5.8 及之后版本 | 根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。Kafka sink 重试或重建后会重新读取 Kafka 配置并自动恢复同步，不需要修改、暂停或恢复 changefeed。 | -| v8.5.8 之前的版本 | 调大 changefeed 的 `max-message-bytes`，并确保 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 不小于待发送消息的大小。更新 changefeed 配置后，TiCDC 会使用新的限制重新创建 Kafka sink。 | +| v8.5.8 及之后版本 | 根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。Kafka Sink 重试或重建后会重新读取 Kafka 配置，changefeed 随后自动恢复，无需修改、暂停或恢复 changefeed。 | +| v8.5.8 之前的版本 | 调大 changefeed 的 `max-message-bytes`，并确保 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 不小于待发送消息的大小。更新 changefeed 配置后，Kafka Sink 会使用新的限制。 | -对于 v8.5.8 及之后版本，如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 TiCDC 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[配置 Kafka 消息大小](/ticdc/ticdc-sink-to-kafka.md#配置-kafka-消息大小)。 +对于 v8.5.8 及之后版本，如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 调整 Kafka 消息大小限制时，还需要检查以下相关配置： From a7e87c1c27410a55b0e1d0ae944f82891fb1fdf3 Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 17:29:40 +0800 Subject: [PATCH 7/9] add more --- ticdc/ticdc-sink-to-kafka.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/ticdc/ticdc-sink-to-kafka.md b/ticdc/ticdc-sink-to-kafka.md index 4f9ae31371a4..3a4c477e5371 100644 --- a/ticdc/ticdc-sink-to-kafka.md +++ b/ticdc/ticdc-sink-to-kafka.md @@ -157,13 +157,12 @@ URI 中可配置的的参数如下： - 对 Cluster 资源类型的 `DescribeConfig` 权限。 各权限的使用场景如下： - | 资源类型 | 操作类型 | 使用场景 | - | :-------------| :------------- | :--------------------------------| - | Cluster | `DescribeConfig` | Changefeed 运行过程中，获取集群元数据 | - | Topic | `Describe` | Changefeed 启动时，尝试创建 Topic | - | Topic | `Create` | Changefeed 启动时，尝试创建 Topic | - | Topic | `Write` | 发送数据到 Topic | + | :-------------| :--------------- | :--------------------------------| + | Cluster | `DescribeConfig` | Changefeed 运行过程中，获取集群元数据 | + | Topic | `Describe` | Changefeed 启动时，尝试创建 Topic | + | Topic | `Create` | Changefeed 启动时，尝试创建 Topic | + | Topic | `Write` | 发送数据到 Topic | 创建或启动 Changefeed 时，如果指定的 Kafka Topic 已存在，可以不用开启 `Describe` 和 `Create` 权限。 @@ -384,22 +383,22 @@ SELECT COUNT(*) FROM INFORMATION_SCHEMA.TIKV_REGION_STATUS WHERE DB_NAME="databa ## Kafka 消息大小限制 -Kafka 对可以接收的消息大小设有默认限制，通常无需调整。只有当 changefeed 需要发送的单条消息超过当前限制时，才需要调大该限制，或者使用[大消息处理功能](#处理超过-kafka-topic-限制的消息)。 +Kafka 会限制每个 Topic 可以接收的消息大小。目标 Topic 当前生效的限制由以下配置决定： | 参数 | 作用 | | --- | --- | -| Kafka Topic `max.message.bytes` | 为指定 Topic 设置消息大小限制，覆盖 broker 的默认值。 | -| Kafka broker `message.max.bytes` | Topic 未设置 `max.message.bytes` 时使用的默认值。 | +| Kafka Topic [`max.message.bytes`](https://kafka.apache.org/43/configuration/topic-configs/#topicconfigs_max.message.bytes) | 为指定 Topic 设置消息大小限制，覆盖 broker 的默认值。 | +| Kafka broker [`message.max.bytes`](https://kafka.apache.org/43/configuration/broker-configs/#brokerconfigs_message.max.bytes) | Topic 未设置 `max.message.bytes` 时使用的默认值。 | Kafka Sink 启动时会读取目标 Topic 当前生效的消息大小限制，用于在发送前判断消息是否过大。如果编码后的单条消息超过该限制且未配置大消息处理，Kafka Sink 会返回 `ErrMessageTooLarge`。处理方法参见[Kafka Sink 返回 `ErrMessageTooLarge` 时，如何处理？](/ticdc/troubleshoot-ticdc.md#kafka-sink-返回-errmessagetoolarge-时如何处理)。 > **注意：** > -> 如果 Kafka Sink 因 Kafka ACL 等原因无法读取 Topic 或 broker 的消息大小配置，会使用 changefeed 的 `max-message-bytes` 作为本地消息大小限制。如果该值与 Kafka 实际生效的限制不一致，Kafka Sink 可能无法准确判断消息能否发送，调大 Kafka 的限制后也可能无法自动恢复。请确保 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限；如果无法授予该权限，需要手动保持 changefeed 的 `max-message-bytes` 与 Kafka 的消息大小限制一致。 +> 如果 Kafka Sink 因 Kafka ACL 等原因无法读取 Topic 或 broker 的消息大小配置，会使用 changefeed 的 `max-message-bytes` 作为本地消息大小限制。如果该值与 Kafka 实际生效的限制不一致，Kafka Sink 可能无法准确判断消息能否发送，调大 Kafka 的限制后也可能无法自动恢复。请确保 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限；如果无法授予该权限，需要设置 changefeed 的 `max-message-bytes` 与 Kafka 的消息大小限制一致。 ## 处理超过 Kafka Topic 限制的消息 -Kafka Topic 对可以接收的消息大小有限制，该限制由 [`max.message.bytes`](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes) 参数控制。当原始消息超过 Kafka 当前的消息大小限制时，TiCDC 可以通过 `large-message-handle-option` 处理该消息。 +当消息超过 Kafka 大小限制时，可以配置 `large-message-handle-option`，避免消息因过大而无法发送。 目前，如下功能支持 Canal-JSON 和 Open Protocol 两种编码协议。使用 Canal-JSON 协议时，你需要在 `sink-uri` 中设置 `enable-tidb-extension=true`。 From 7953c429c78a9df0d3d5d679a5b6ab09b6734f4a Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 17:39:44 +0800 Subject: [PATCH 8/9] add more --- ticdc/troubleshoot-ticdc.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index 9975da21f246..7881f35d4216 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -106,12 +106,11 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin 处理方式取决于 TiCDC 版本： -| TiCDC 版本 | 处理方式 | -| --- | --- | -| v8.5.8 及之后版本 | 根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。如果目标 Topic 使用 broker 的默认配置，请调大 Kafka server 的 `message.max.bytes`。Kafka Sink 重试或重建后会重新读取 Kafka 配置，changefeed 随后自动恢复，无需修改、暂停或恢复 changefeed。 | -| v8.5.8 之前的版本 | 调大 changefeed 的 `max-message-bytes`，并确保 Kafka Topic 的 `max.message.bytes` 或 broker 的 `message.max.bytes` 不小于待发送消息的大小。更新 changefeed 配置后，Kafka Sink 会使用新的限制。 | +**v8.5.8 及之后版本**：根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。changefeed 自动重建会读取该配置恢复同步。 -对于 v8.5.8 及之后版本，如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 +如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 + +**v8.5.8 之前的版本**：确认导致错误的待发送消息的大小，调整 Kafka Topic 的 `max.message.bytes` 该值，暂停 changefeed，然后调整 changefeed 的 `max-message-bytes` 为该值。恢复 changefeed。 调整 Kafka 消息大小限制时，还需要检查以下相关配置： @@ -143,7 +142,7 @@ cdc cli changefeed resume -c test-cf --server=http://127.0.0.1:8300 3. 恢复被暂停的 changefeed。 > **注意：** -> +> > 虽然将 changefeed 的 `start-ts` 设为报错时的 `checkpoint-ts` 值加上 1，然后重建任务也可以跳过该 DDL 语句，但同时会导致 TiCDC 丢失 `checkpointTs+1` 时刻对应的 DML 数据变更。严禁在生产环境执行这样的操作。 ```shell @@ -156,5 +155,5 @@ cdc cli changefeed create --server=http://127.0.0.1:8300 --sink-uri="mysql://roo 该问题通常是由于 TiCDC 与 Kafka 集群连接失败导致。你可以通过检查 Kafka 的日志以及网络状况来排查。一个常见的原因是在创建同步任务时没有指定正确的 `kafka-version` 参数，导致 TiCDC 内部的 Kafka client 在访问 Kafka server 时使用了错误的 Kafka API 版本。你可以通过配置 [`--sink-uri`](/ticdc/ticdc-sink-to-kafka.md#sink-uri-配置-kafka) 指定正确的 `kafka-version` 参数来修复。例如： ```shell -cdc cli changefeed create --server=http://127.0.0.1:8300 --sink-uri "kafka://127.0.0.1:9092/test?topic=test&protocol=open-protocol&kafka-version=2.4.0" +cdc cli changefeed create --server=http://127.0.0.1:8300 --sink-uri "kafka://127.0.0.1:9092/test?topic=test&protocol=open-protocol&kafka-version=2.4.0" ``` From 2361e1ddb4870e7a3e9972e4c1e05fa5e159bd18 Mon Sep 17 00:00:00 2001 From: 3AceShowHand Date: Thu, 23 Jul 2026 17:47:37 +0800 Subject: [PATCH 9/9] adjust --- ticdc/troubleshoot-ticdc.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/ticdc/troubleshoot-ticdc.md b/ticdc/troubleshoot-ticdc.md index 7881f35d4216..be59c7b2a333 100644 --- a/ticdc/troubleshoot-ticdc.md +++ b/ticdc/troubleshoot-ticdc.md @@ -106,11 +106,15 @@ Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skippin 处理方式取决于 TiCDC 版本： -**v8.5.8 及之后版本**：根据错误信息中的消息大小调大 Kafka Topic 的 `max.message.bytes`。changefeed 自动重建会读取该配置恢复同步。 +**v8.5.8 及之后版本**：根据错误信息中的消息大小，调大 Kafka Topic 的 `max.message.bytes`。Kafka Sink 重建时会重新读取该配置，changefeed 随后自动恢复同步。 -如果调大 Kafka 的消息大小限制后同步任务没有自动恢复，请确认 changefeed 使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 +如果 changefeed 未自动恢复，请确认其使用的 Kafka 账号具有读取 Topic 和 broker 配置的权限。更多信息参见[Kafka 消息大小限制](/ticdc/ticdc-sink-to-kafka.md#kafka-消息大小限制)。 -**v8.5.8 之前的版本**：确认导致错误的待发送消息的大小，调整 Kafka Topic 的 `max.message.bytes` 该值，暂停 changefeed，然后调整 changefeed 的 `max-message-bytes` 为该值。恢复 changefeed。 +**v8.5.8 之前的版本**： + +1. 根据错误信息确认待发送消息的大小。 +2. 将 Kafka Topic 的 `max.message.bytes` 调整为不小于该消息大小。 +3. 暂停 changefeed，将 `max-message-bytes` 设置为与 `max.message.bytes` 相同的值，然后恢复 changefeed。 调整 Kafka 消息大小限制时，还需要检查以下相关配置：