Add notes.md

CHANGELOG.md

@@ -7,7 +7,7 @@
 注意：从这个版本开始 doris 和 ccr-syncer 的 2.0 版本将不再更新，需要使用 ccr-syncer 的需要先升级到 2.1 及以上版本。
 
 
-这次引入了一个 behaviour change: 创建同步 JOB，需要上游的表开启 `light_schema_change` 属性 (selectdb/ccr-syncer#283)。
+这次引入了一个 behavior change: 创建同步 JOB，需要上游的表开启 `light_schema_change` 属性 (selectdb/ccr-syncer#283)。
 
 ### Fix
 

README.md

@@ -5,17 +5,29 @@ CCR（Cross Cluster Replication）也就是跨集群数据复制，能够在库/
 ## 原理
 ### 名词解释
 
-**源集群 (srcCluster)**：业务写入数据的集群
-**目标集群 (destCluster)**：跨集群复制的目标集群
-**binlog**：源集群变更日志，记录了源集群的数据修改和操作，是目标集群数据重放和恢复的凭据
-**Syncer**：一个轻量的CCR任务控制节点，可以单节点部署，也可以多节点高可用部署
+- **源集群 (src cluster)**：业务写入数据的集群
+- **目标集群 (dest cluster)**：跨集群复制的目标集群
+- **binlog**：源集群变更日志，记录了源集群的数据修改和操作，是目标集群数据重放和恢复的凭据
+- **Syncer**：一个轻量的CCR任务控制节点，可以单节点部署，也可以多节点高可用部署
 
 ### 架构说明
 
 ![framework](doc/pic/framework.png)
-Syncer从源集群批量获取库/表的binlog，并根据binlog中的信息在目标集群重放，从而实现数据的全量/增量复制。
-如果binlog是数据变更，则通知目标集群从源集群拉取数据。
-如果binlog是元数据变更，则在目标集群发起对应的操作。
+Syncer从源集群批量获取库/表的 binlog，并根据 binlog 中的信息在目标集群重放，从而实现数据的全量/部分/增量复制。
+
+具体的数据同步方式如下：
+- 全量同步（full sync）
+- 部分同步（partial sync）
+- 增量同步（incremental）
+
+全量同步和部分同步都依赖 doris 提供的备份（backup）和恢复（restore）机制。Syncer 会向源集群提交备份任务，原集群会生成一份数据快照，并把快照数据和元数据备份到本地磁盘上；原集群备份完成后 syncer 会向目标集群提交恢复任务，目标集群会从上游下载数据。全量同步会同步整个库（Database；在 table 级别同步下，则是整个 table），部分同步则会同步某张表（Table）或者某几个分区（Partition）。
+
+同步 job 创建后，首先会通过全量同步拉取上下游的存量数据，完成后进入增量同步。
+
+增量同步时，syncer 会从原集群拉取 binlog，并在目标集群回放。回放方式可以分为下面几种：
+- 如果 binlog 是数据变更，则通知目标集群从源集群拉取数据，并作为一次事务（Txn）导入到目标集群
+- 如果 binlog 是元数据变更，则再目标集群发起对应的操作（SQL）
+- 对于一些无法直接通过 SQL 发起变更的操作，则触发部分同步。
 
 ## 使用说明
 
@@ -83,4 +95,10 @@ Syncer从源集群批量获取库/表的binlog，并根据binlog中的信息在
         - 如果是db级别的同步，则填入dbName，tableName为空
         - 如果是表级别同步，则需要填入dbName、tableName
 
-    其他操作详见[操作列表](doc/operations.md)
+其他操作详见[操作列表](doc/operations.md)。
+
+在生产环境中使用前，请参考[使用须知](doc/notes.md) 调整源和目标集群配置。
+
+## 功能详情
+
+Doris 功能繁多，syncer 目前只支持了其中的一部分，具体细节可以参考[功能详情](https://doris.apache.org/zh-CN/docs/dev/admin-manual/data-admin/ccr/feature)。

doc/notes.md

@@ -0,0 +1,69 @@
+# 使用须知
+
+**ccr syncer 支持的最小 doris 版本是 2.1，2.0 版本将不再支持。**
+
+## 建议打开的配置
+
+- `restore_reset_index_id`：如果要同步的表中带有 inverted index，那么必须在目标集群上配置为 `false`。
+- `ignore_backup_tmp_partitions`：如果上游有创建 tmp partition，那么 doris 会禁止做 backup，因此 ccr-syncer 同步会中断；通过在 FE 设置 `ignore_backup_tmp_partitions=true` 可以避免这个问题。
+
+## 注意事项
+
+- CCR 同步期间 backup/restore job 和 binlogs 都在 FE 内存中，因此建议在 FE 给每个 ccr job 都留出 4GB 及以上的堆内存（源和目标集群都需要），同时注意修改下列配置减少无关 job 对内存的消耗：
+    - 修改 FE 配置 `max_backup_restore_job_num_per_db`:
+        记录在内存中的每个 DB 的 backup/restore job 数量。默认值是 10，设置为 2 就可以了。
+    - 修改源集群 db/table property，设置 binlog 保留限制
+        - `binlog.max_bytes`: binlog 最大占用内存，建议至少保留 4GB（默认无限制）
+        - `binlog.ttl_seconds`: binlog 保留时间，从 2.0.5 之前的老版本默认无限制；之后的版本默认值为一天（86400）
+        比如要修改 binlog ttl seconds 为保留一个小时: `ALTER TABLE  table SET ("binlog.ttl_seconds"="3600")`
+- CCR 正确性依也赖于目标集群的事务状态，因此要保证在同步过程中事务不会过快被回收，需要调大下列配置
+    - `label_num_threshold`：用于控制 TXN Label 数量
+    - `stream_load_default_timeout_second`：用于控制 TXN 超时时间
+    - `label_keep_max_second`: 用于控制 TXN 结束后保留时间
+    - `streaming_label_keep_max_second`：同上
+- 如果是 db 同步且源集群的 tablet 数量较多，那么产生的 ccr job 可能非常大，需要修改几个 FE 的配置：
+    - `max_backup_tablets_per_job`:
+        一次 backup 任务涉及的 tablet 上限，需要根据 tablet 数量调整（默认值为 30w，过多的 tablet 数量会有 FE OOM 风险，优先考虑能否降低 tablet 数量）
+    - `thrift_max_message_size`:
+        FE thrift server 允许的单次 RPC packet 上限，默认值为 100MB，如果 tablet 数量太多导致 snapshot info 大小超过 100MB，则需要调整该限制，最大 2GB
+        - Snapshot info 大小可以从 ccr syncer 日志中找到，关键字：`snapshot response meta size: %d, job info size: %d`，snapshot info 大小大约是 meta size + job info size。
+    - `fe_thrift_max_pkg_bytes`:
+        同上，一个额外的参数，2.0 中需要调整，默认值为 20MB
+    - `restore_download_task_num_per_be`:
+        发送给每个 BE download task 数量上限，默认值是 3，对 restore job 来说太小了，需要调整为 0（也就是关闭这个限制）； 2.1.8 和 3.0.4 起不再需要这个配置。
+    - `backup_upload_task_num_per_be`:
+        发送给每个 BE upload task 数量上限，默认值是 3，对 backup job 来说太小了，需要调整为 0 （也就是关闭这个限制）；2.1.8 和 3.0.4 起不再需要这个配置。
+    - 除了上述 FE 的配置外，如果 ccr job 的 db type 是 mysql，还需要调整 mysql 的一些配置：
+        - mysql 服务端会限制单次 select/insert 返回/插入数据包的大小。增加下列配置以放松该限制，比如调整到上限 1GB
+        ```
+        [mysqld]
+        max_allowed_packet = 1024MB
+        ```
+        - mysql client 也会有该限制，在 ccr syncer 2.1.6/2.0.15 及之前的版本，上限为 128MB；之后的版本可以通过参数 `--mysql_max_allowed_packet` 调整（单位 bytes），默认值为 1024MB
+        > 注：在 2.1.8 和 3.0.4 以后，ccr syncer 不再将 snapshot info 保存在 db 中，因此默认的数据包大小已经足够了。
+- 同上，BE 端也需要修改几个配置
+    - `thrift_max_message_size`: BE thrift server 允许的单次 RPC packet 上限，默认值为 100MB，如果 tablet 数量太多导致 agent task 大小超过 100MB，则需要调整该限制，最大 2GB
+    - `be_thrift_max_pkg_bytes`：同上，只有 2.0 中需要调整的参数，默认值为 20MB
+- 即使修改了上述配置，当 tablet 继续上升时，产生的 snapshot 大小可能会超过 2GB，也就是 doris FE edit log 和 RPC message size 的阈值，导致同步失败。从 2.1.8 和 3.0.4 开始，doris 可以通过压缩 snapshot 来进一步提高备份恢复支持的 tablet 数量。可以通过下面几个参数开启压缩：
+    - `restore_job_compressed_serialization`: 开启对 restore job 的压缩（影响元数据兼容性，默认关闭）
+    - `backup_job_compressed_serialization`: 开启对 backup job 的压缩（影响元数据兼容性，默认关闭）
+    - `enable_restore_snapshot_rpc_compression`: 开启对 snapshot info 的压缩，主要影响 RPC（默认开启）
+    > 注：由于识别 backup/restore job 是否压缩需要额外的代码，而 2.1.8 和 3.0.4 之前的代码中不包含相关代码，因此一旦有 backup/restore job 生成，那么就无法回退到更早的 doris 版本。有两种情况例外：已经 cancel 或者 finished 的 backup/restore job 不会被压缩，因此在回退前等待 backup/restore job 完成或者主动取消 job 后，就能安全回退。
+- Ccr 内部会使用 db/table 名作为一些内部 job 的 label，因此如果 ccr job 中碰到了 label 超过限制了，可以调整 FE 参数 `label_regex_length` 来放松该限制（默认值为 128）
+- 由于 backup 暂时不支持备份带有 cooldown tablet 的表，如果碰到了会导致同步终端，因此需要在创建 ccr job 前检查是否有 table 设置了 `storage_policy` 属性。
+
+## 性能相关参数
+
+- 如果用户的数据量非常大，备份、恢复执行完需要的时间可能会超过一天（默认值），那么需要按需调整下列参数
+    - `backup_job_default_timeout_ms` 备份/恢复任务超时时间，源、目标集群的 FE 都需要配置
+    - 上游修改 binlog 保留时间: `ALTER DATABASE $db SET PROPERTIES ("binlog.ttl_seconds" = "xxxx")`
+- 下游 BE 下载速度慢
+    - `max_download_speed_kbps` 下游单个 BE 中单个下载线程的下载限速，默认值为 50MB/s
+    - `download_worker_count` 下游执行下载任务的线程数，默认值为 1；需要结合客户机型调整，在不影响客户正常读写时跳到最大；如果调整了这个参数，就可以不用调整 `max_download_speed_kbps`。
+        - 比如客户机器网卡最大提供 1GB 的带宽，现在最大允许下载线程利用 200MB 的带宽，那么在不改变 `max_download_speed_kbps` 的情况下，`download_worker_count` 应该配置成 4。
+
+## 不建议使用版本
+
+Doris 版本
+- 2.1.5/2.0.14：如果从之前的版本升级到这两个版本，且用户有 drop partition 操作，那么会在升级、重启时碰到 NPE，原因是这个版本引入了一个新字段，旧版本没有所以默认值为 null。这个问题在 2.1.6/2.0.15 修复。
+