obcdc 配置项说明 - OceanBase 数据库 V4.2.2

配置项的 bool 类型配置均以 0 代表 False，1 代表 True。

集群配置

元信息配置

配置项	含义	默认值	可否动态变更	备注
init_log_level	启动时日志级别	ALL.*:INFO;SHARE.SCHEMA:INFO	否	启动时的日志级别，主要为了输出更详细的日志，启动后将调整为 log_level 的配置。
log_level	启动后日志级别	ALL.*:INFO;SHARE.SCHEMA:WARN	是	无
max_log_file_count	日志文件的数量上限	0	否	取值范围大于等于 0，值为 0 时表示不限制日志，调低日志文件数目需要重启 obcdc。
enable_log_limit	是否开启日志限流	1	是	1：开启 0：关闭
rootserver_list	启动时指定 rootservice 所在机器信息	`\|`（英文半角）	是	格式：`server_ip:server_rpc_port:server_sql_port`。
cluster_url	启动时指定的 cluster url	`\|`（英文半角）	否	当 OceanBase 具有 cluster url;obcdc 用于获取 rootserver 信息，支持 server 高可用。
cluster_user	sys 租户下用户名	空（用户指定，必填）	否	需配置 sys 租户下的用户，具有内部表（oceanbase 库）的读权限。
cluster_password	上述用户的密码	空（用户指定，必填）	否	无
tenant_endpoint	租户所在的机器列表	`\|`（英文半角）	否	格式：`host:sql_port`，多个机器间使用 `\|` 分隔。
tenant_user	租户用户名	`\|`（英文半角）	否	格式：`user_name@tenant_name` 或者`user_name@tenant_name#cluster`。
tenant_password	对应上述租户用户名的密码	`\|`（英文半角）	否	无
config_fpath	配置文件 dump 路径	etc/liboblog.conf	否	obcdc 所有配置信息会 dump 到该文件。
timezone	obcdc 所属时区	+8:00	否	影响数据格式化输出的时区，需和数据源配置保持一致，默认东 8 区。
timezone_info_path	用于指定 timezone 元信息文件所在目录	etc/timezone_info.conf	是	`meta_data_refresh_mode` 配置为 `data_dict` 时，需要将 RPM 包中的 `timezone_info.conf` 文件放入该目录下。
skip_ob_version_compat_check	是否跳过 OceanBase 版本兼容性检查	0	否	3.x 版本 obcdc 仅支持同步 2.x/3.x 版本 OceanBase 数据，且 obcdc 版本号需大于 OceanBase 版本号（比较时考虑大版本号和小版本号）。
cluster_version_refresh_interval_sec	查询 OceanBase 集群 OBServer 节点最小版本号的周期	600	否	指定刷新 OceanBase 集群版本的间隔，单位为秒。
log_router_background_refresh_interval_sec	日志流元信息刷新频率	10	是	日志流对应 server 信息后台刷新时间间隔，单位为秒。

工作模式相关

配置项	含义	默认值	可否动态变更	备注
working_mode	工作模式	storage（商业版）	否	业务请尽量控制事务大小。如果业务场景存在大事务，推荐使用持久化模式。持久化模式下，推荐将 obcdc 部署在 SSD 盘。
store_service_path	obcdc 持久化模式下存储数据的路径	./storage	否	仅持久化模式下生效。相对路径：存储在调用 obcdc 的进程所在路径下的相对路径。绝对路径：存储在指定的绝对路径下，比如 store_service_path=/data/1。

同步粒度

obcdc 支持同步多个维度数据，单个 obcdc 实例支持同步一个集群，1 个/多个租户，若干 database，若干表等。

同步粒度	单个 obcdc	多个 obcdc
集群	支持（不支持单 obcdc 同步多集群）	支持
租户	支持	支持
database	不支持	不支持
table	不支持	不支持（参考下面的多实例配置项）

如果租户流量非常大，单实例 obcdc 同步整个集群很难做到数据实时的情况下，可以使用多个 obcdc 实例同步同一个集群来分担压力，每个实例同步不同租户的数据。

黑白名单相关配置

配置项	含义	默认值	可否动态变更	备注
tb_white_list	同步的表的白名单	..*	否	格式：租户名.库名.表名（例如：mytenant1.db1.tb1\|mytenant2.db2.*）。
tb_black_list	同步的表的黑名单	`\|`	否	格式同上。
tablegroup_white_list	同步的 tablegroup 白名单	.	否	格式：租户名.tablegroup名,例如(mytenant1.\|or_tenant.tg*)。
tablegroup_black_list	同步的 tablegroup 黑名单	`\|`	否	格式同上。
enable_filter_sys_tenant	是否过滤 sys 租户同步数据	0	否	在 sys 租户异常但普通租户正常的情况下启用。

说明

obcdc 提供了基于表和 tablegroup 黑白名单的数据过滤能力：

只有在白名单且不再黑名单中的表 /tablegroup 才会同步下去，白名单默认为所有租户下的所有表 /tablegroup，黑名单默认为空；推荐生产环境使用白名单同步指定租户的数据，不要使用默认值（会拉取冗余数据）。
配置方式是通过 fnmatch 进行正则匹配，默认匹配规则为大小写不敏感，如果配置了 enable_oracle_mode_match_case_sensitive=1，则对 ORACLE 模式的租户进行大小写敏感对名称匹配。

多实例相关配置

配置项	含义	默认值	可否动态变更	备注
instance_num	分担流量的 obcdc 总数	1	否	无
instance_index	当前 obcdc 占总数量的 index（可以理解为 hash 桶 ID）	0	否	取值为 [0,instance_num)，每个 obcdc 只处理 `hash(tenant_id, ls_id) % instance_num = instance_idx` 的日志流的数据。
enable_global_unique_index_belong_to_multi_instance	是否允许多实例场景下同步全局唯一索引表	0	是	取值为 0 表示不允许多实例场景下同步全局唯一索引表。

监控相关配置

流量控制

obcdc 为了防止异常情况下导致内存中数据堆积触发 OOM 的问题，提供了流量控制的能力。根据 obcdc 内部状态触发流量控制，暂停拉取新的数据，待 obcdc 状态恢复后继续拉取数据。流量控制功能由如下参数控制，必要时调整相应参数调整限流程度。

配置项	含义	默认值	可否动态变更	备注
memory_limit	obcdc 触发流控时使用的内存限额	`20G`	是	流控参考参数之一，期望 obcdc 内存控制在 `memory_limit` 附近（obcdc 会尽可能控制），并不意味着 obcdc 最多只用 `memory_limit` 大小的内存，最小配置为 2G。
memory_usage_warn_threshold	设置触发拉日志限流时内存占比（与 memory_limit 相比）	85	是	无
system_memory_avail_percentage_lower_bound	系统可用内存下限阈值（百分比）	10	是	取值范围：[10, 80]。
part_trans_task_active_count_upper_bound	活跃的分区事务数量上限	200000	是	内存中活跃的分区事务结构体数量（分配出来且未被回收）。
storager_task_count_upper_bound	待 storager 模块持久化的任务数量的流控阈值	1000	是	最小值为 1。
storager_mem_percentage	控制持久化模块占用相对流控内存的倍数	1	是	取值为 0 时表示自动调节。
part_trans_task_reusable_count_upper_bound	待重用的分区事务上限	10240	是	待输出到用户队列+待用户输出+待用户归还+未被 GC 的任务数量。
ready_to_seq_task_upper_bound	待定序的任务数量上限	2000	是	待定序任务数量上限为：待解析任务+待格式化任务+待持久化任务数量。
pause_fetcher	强制暂停拉日志	0	是	取值为 0 表示不考虑流控计算逻辑的结果，强制暂停拉日志。

流控参考条件：

条件 1：活跃分区数量超过上限阈值（part_trans_task_active_count_upper_bound）|| obcdc 持有内存超过上限阈值（memory_limit） || 系统可用内存低于下限阈值（system_memory_avail_percentage_lower_bound）。
条件 2：待重用分区事务结构数量超过上限阈值（part_trans_task_reusable_count_upper_bound)） || 待定序任务数量超过上限阈值（ready_to_seq_task_upper_bound）。
条件 3（since 3.x）：待持久化的任务数量超过阈值（storager_task_count_upper_bound） && obcdc 持有内存超过流控触发内存（memory_limit） * 持久化模块占用相对流控内存的比值（storager_mem_percentage）。

触发流控的条件：((条件 1 && 条件 2)|| 条件 3) || (pause_fetcher != 0)。

监控信息输出

配置项	含义	默认值	可否动态变更	备注
enable_dump_pending_trans_info	控制是否定期统计 & 打印 obcdc 中持有的分布式事务的状态	0	是	取值为 0 表示不定期统计 & 打印 obcdc 中持有的分布式事务的状态。如果配置为 `1` 则 10s 打印一次。
print_fetcher_slowest_ls_num	打印拉日志最慢的分区的数量	10	是	无
print_rpc_handle_info	控制是否打印 RPC 相关信息	0	是	取值为 0 表示不打印 RPC 相关信息。
print_stream_dispatch_info	控制是否打印拉日志流信息	0	是	取值为 0 表示不打印拉日志流信息。
print_ls_heartbeat_info	控制是否打印分区心跳信息	0	是	取值为 0 表示不打印分区心跳信息。
print_ls_serve_info	控制是否打印分区服务信息（分区状态，分区事务数量）	0	是	取值为 0 表示不打印分区服务信息（分区状态，分区事务数量）。
print_participant_not_serve_info	控制是否打印所有分布式事务的不服务（不输出数据）的分区事务信息	0	是	取值为 0 表示不打印所有分布式事务的不服务（不输出数据）的分区事务信息。
print_ls_server_list_update_info	控制是否在更新分区 server 列表时打印 server 列表详细信息	0	是	取值为 0 表示不更新分区 server 列表时打印 server 列表详细信息。
enable_formatter_print_log	控制是否允许 formatter 输出部分忽略格式化数据时的日志	0	是	取值为 0 表示不允许 formatter 输出部分忽略格式化数据时的日志。

元数据管理

obcdc 4.1 版本支持通过数据字典来获取元信息（schema/日志流信息等），无需向 OBServer 节点发送 RPC 来拉取日志。

配置项	含义	默认值	可否动态变更	备注
meta_data_refresh_mode	用于指定 schema/日志流等元信息的获取方式	online	否	online 模式：通过 SchemaService 向 server 查询 schema 信息，需要能够访问 OBServer 节点。 data_dict 模式：通过日志中的数据字典解析 schema 信息。

租户管理

配置项	含义	默认值	可否动态变更	备注
skip_rename_tenant_ddl	是否忽略 rename 租户的 DDL	0	是	如果遇到重命名的租户不在 obcdc 同步白名单范围内，则无影响。否则正常会报错退出进程（因为此时 rename 操作会打破白名单限制，遇到这个情况建议修改白名单使之同时支持 rename 前后的租户）。该配置项设置为 true 时会跳过 rename 租户的 DDL 继续同步数据。
enable_oracle_mode_match_case_sensitive	OceanBase-Oracle 模式租户黑白名单匹配时大小写敏感	0	否	无

Fetcher 模块相关配置

配置项	含义	默认值	可否动态变更	备注
ls_count_upper_limit	分区进度的数量	2000000	否	最多支持 200 百万分区。
check_switch_server_interval_min	周期性检查分区是否需要切换拉日志机器	30	是	无

SQL 查询相关配置

配置项	含义	默认值	可否动态变更	备注
access_systable_helper_thread_num	执行 SQL 的连接池的连接数目上限	64	否	取值范围 [48, 1024]。
rs_sql_connect_timeout_sec	root service 的 SQL 连接超时时间	40	是	无
rs_sql_query_timeout_sec	root service 的 SQL 请求超时时间	30	是	无
tenant_sql_connect_timeout_sec	租户的 SQL 连接超时时间	40	是	无
tenant_sql_query_timeout_sec	租户的 SQL 请求超时时间	30	是	无
sql_server_change_interval_sec	SQL 请求切换执行机器的周期	60	是	无

基于 cluster_id 过滤数据

obcdc 提供了基于 cluster_id 黑名单的数据过滤能力：OceanBase 规定了有效的 cluster_id 范围，但为了防止同步到不想要的数据，用户写数据时可以指定 cluster_id。配置同步源端写入数据的 cluster_id，请参考 ob_org_cluster_id。

不同步不符合 OceanBase 和 OMS 规定的合法的 cluster_id 范围的数据（合法范围是[1, 4294901759] U [4294901760, 4294967295]）。
不同步 cluster_id 在 cluster_id_black_list 中的数据。
cluster_id_black_list 中的每一个 cluster_id 需取值在 cluster_id_value_min 和 cluster_id_value_max 之间。

配置项	含义	默认值	可否动态变更	备注
cluster_id_black_list	同步的 cluster_id 的黑名单	`\|`	否	多个 cluster_id 间用半角字符 `\|` 分隔，每个 cluster_id 取值在 cluster_id_value_min 和 cluster_id_value_max 之间。
cluster_id_black_value_min	同步的 cluster_id 黑名单下限	2147473648	否	无
cluster_id_black_value_max	同步的 cluster_id 黑名单上限	2147483647	否	无

Server 级黑名单

obcdc 会向 OBServer 节点发起 SQL 和 RPC，我们分别提供了配置项目屏蔽部分 SQL 执行机器和 RPC 执行机器（对所有请求有效）。

此外，obcdc 拉日志是分区级别，因此内置实现了分区级别对拉日志黑名单，对于拉取分区日志超时/报错的机器都加入这个分区拉日志机器黑名单，机器加入黑名单和从黑名单中洗白的过程是自动的。

配置项	含义	默认值	可否动态变更	备注
server_blacklist	配置 RPC 请求的机器黑名单，obcdc 不向此黑名单中的机器发送 RPC 请求	`\|`	是	格式为 `svr_ip:rpc_port`，多个 OBServer 间用 `\|` 分隔；不会从这个 OBServer 列表中的机器拉取日志，当 OBServer 节点不能正常提供日志服务（比如网络分区/延迟过高等）时可人工配置到该列表中。
sql_server_blacklist	配置 SQL 请求的机器黑名单，obcdc 不向此黑名单中的机器发送 SQL 请求	`\|`	是	格式为 `svr_ip:rpc_port`，多个 OBServer 间用 `\|` 分隔。

分区级拉日志 server 黑名单调控（一般不修改）

配置项	含义	默认值	可否动态变更	备注
blacklist_survival_time_sec	机器在黑名单中的等待时间	30	否	无
blacklist_survival_time_upper_limit_min	机器在黑名单中的时间上限	4	是	无
blacklist_survival_time_penalty_period_min	机器重复加入黑名单时，黑名单时间翻倍的间隔阈值	1	是	无
blacklist_history_overdue_time_min	机器在黑名单历史待多久后删除	30	是	最小值为 10
blacklist_history_clear_interval_min	清理黑名单中机器信息的周期	20	是	最小值为 10

server 缓存信息相关配置

配置项	含义	默认值	可否动态变更
all_server_cache_update_interval_sec	机器列表信息缓存更新周期	5	是
all_zone_cache_update_interval_sec	Zone 信息缓存更新周期	5	是

拉日志相关配置

配置项	含义	默认值	可否动态变更	备注
idle_pool_thread_num	处理待发起分区拉日志任务的线程数目	4	否	取值范围 [1,32]。
dead_pool_thread_num	处理回收分区拉日志任务的线程数目	1	否	取值范围 [1,32]。
stream_worker_thread_num	分派分区拉日志任务的线程数	8	否	取值范围 [1,64]。
start_lsn_locator_thread_num	定位分区日志起点的线程数	4	否	取值范围 [1,32]。
lob_data_merger_thread_num	lob 数据处理线程数目	2	否	取值范围 [1, +∞)。
start_lsn_locator_locate_count	完成定位日志起点任务的请求数目	1	否	最小值为 1。定位分区起始日志 ID 需要指定数目的分区副本返回相同的起始日志 ID。
skip_start_lsn_locator_result_consistent_check	跳过起始日志 ID 一致性检查	否	否	无
svr_stream_cached_count	机器日志流对象池初始化大小	16	否	最小值为 1。
fetch_stream_cached_count	分区日志流对象池初始化大小	16	否	最小值为 1。
start_lsn_locator_rpc_timeout_sec	定位分区起始日志 ID 的 RPC 超时时间	60	是	最小值为 1。
start_lsn_locator_batch_count	定位分区起始日志 ID 的 RPC 批量大小	2000	是	最小值为 1。
heartbeat_interval_sec	分区心跳 RPC 周期	1	是	最小值为 1。
fetch_log_rpc_timeout_sec	拉分区日志 RPC 超时时间	15	是	最小值为 1。
progress_limit_sec_for_dml	DML 数据拉日志进度上限	300	是	最小值为 1。为了保证各分区进度基本一致（防止某些分区拉日志过快），限制 server 提供该的日志上限为所有分区进度最小值+progress_limit_sec_for_dml。
ls_fetch_progress_update_timeout_sec	判断分区拉日志 RPC 超时的阈值	3	是	最小值为 1。
ls_fetch_progress_update_timeout_sec_for_lagged_replica	落后副本上拉日志超时的阈值	15	是	最小值为 1。
enable_continue_use_cache_server_list	是否使用 Cache 的 Server 信息	0	否	在 sys 租户异常但普通租户正常的情况下启用。
fetching_log_mode	用于指定拉取日志模式	integrated	否	integrated 模式：默认的日志拉取模式，通过向 OBServer 节点发送 RPC 来拉取日志，需要用户配置 OBServer 节点地址（cluter_url 或者 rootserver_list）以及系统租户下的用户名(cluster_user)和密码(cluster_password)。 direct 模式：直接消费归档日志，无需向 OBServer 节点发送 RPC 来拉取日志，需要用户配置归档目的端（nfs 路径/oss 信息等），归档目的端详见日志归档概述，obcdc 所在的机器需要能够直接访问到归档目的端。注意 obcdc 不支持拉取不连续的归档日志。

拉日志优先级相关

配置项	含义	默认值	可否动态变更	备注
region	配置 obcdc 优先拉取日志的 Region	default_region	是	Region 需要从 OceanBase 数据库内部表中查取，obcdc 会优先从配置的 Region 中的 OBServer 节点上拉取日志。

RPC 模块配置（不建议修改）

配置项	含义	默认值	取值范围	可否动态变更
io_thread_num	rpc io 线程数目	4	[1, +∞)	否
rpc_result_cached_count	拉日志 RPC 结果对象池初始大小	16	[1, +∞)	否
rpc_process_handler_time_upper_limit_msec	RPC 处理最长时间	200	[1, +∞)	是
rpc_result_count_per_rpc_upper_limit	单个拉日志流中未处理的拉日志 RPC 结果数量上限，达到上线后将暂停拉取日志 RPC	16	[1, +∞)	是

安全通信相关

配置项	含义	默认值	可否动态变更	备注
ssl_client_authentication	是否开启安全通信	0	否	默认为 0 表示不开启安全通信。
ssl_external_kms_info	安全通信方法	file	否	外部使用仅支持文件模式，密钥文件放置在 obcdc 启动目录下的 wallet 目录下（请自建 wallet 目录），其下放置如下密钥文件： ca.pem/client-cert.pem/client-key.pem。

Sequencer 模块相关配置

配置项	含义	默认值	取值范围	可否动态变更
sequencer_thread_num	分布式事务定序线程池大小	5	[1, +∞)	否
sequencer_queue_length	待定序的分区事务队列	102400	[1, +∞)	否

REDO 读取控制模块

配置项	含义	默认值	取值范围	可否动态变更
redo_dispatched_memory_limit_exceed_ratio	控制 enable_output_trans_order_by_sql_operation=1 时，下发处理的 redo 的大小限制（即允许内存中处理中的 redo 大小为 redo_dispatched_memory_limit_exceed_ratio * redo_dispatcher_memory_limit）。	2	[1, +∞)	是
redo_dispatcher_memory_limit	控制下发处理的 redo 大小的限制	512M	[128M, +∞)	是
extra_redo_dispatch_memory_size	用于数据倾斜场景下，为倾斜参与者多分配的 REDO 余额，防止死锁导致obcdc不输出数据	4M	[0M, 512M]	是

行数据排序模块

配置项	含义	默认值	取值范围	可否动态变更
msg_sorter_task_count_upper_limit	事务内行数据排序模块任务数量上限	200000	[1, +∞)	否
msg_sorter_thread_num	事务内行数据排序模块线程数量	1	[1, 32]	否

持久化模式下生效的配置

Storager 模块相关配置

配置项	含义	默认值	可否动态变更
storager_thread_num	持久化模块的线程池大小	10	否
storager_queue_length	待持久化的任务数量	102400	否
rocksdb_flush_interval	主动 FLUSH ROCKSDB 的周期	默认 10 分钟	是
rocksdb_compact_interval	主动 COMPACT ROCKSDB 的周期	默认 6 小时	是

Data Processor 模块相关配置

配置项	含义	默认值	可否动态变更
reader_thread_num	从持久化模块读数据的线程池大小	10	否
reader_queue_length	等待反序列化数据的任务数量	102400	否

REDO 批量持久化相关配置

配置项	含义	默认值	取值范围	可否动态变更
batch_buf_count	redo 批量持久化的内存 buffer 数量	10	[5, +∞)	否
batch_buf_size	redo 批量持久化的聚合 buffer 的大小	20MB	[2MB, +∞)	否

Parser 模块相关配置

配置项	含义	默认值	可否动态变更	备注
dml_parser_thread_num	解析 DML 的语句的线程池大小	5	否	最小值为 1。
ddl_parser_thread_num	解析 DDL 的语句的线程池大小	1	否	最小值为 1。
skip_reversed_schema_version	忽略 schema 版本回跳的异常	0	否	DDL 处理过程一般是 schema 单调推高的过程，如果 schema version 回跳说明有异常，提供配置跳过该异常。

Formatter 模块相关配置

配置项	含义	默认值	可否动态变更	备注
formatter_thread_num	数据格式化线程池大小	10	否	最小值为 1。
skip_dirty_data	跳过异常数据	0	是	当前异常情况：非全列日志（指 CLOG 中只记录有变更的列的信息，配置项：binlog_row_image）。异常的物理备份恢复租户的 DDL。

输出 binlog record 相关配置

配置项	含义	默认值	可否动态变更	备注
enable_output_trans_order_by_sql_operation	是否将事务内行数据按 SQL 执行顺序输出	0	否	是指 OceanBase 内部变更数据的顺序，可能和客户端发送的 SQL 顺序不完全一致。
sort_trans_participants	按分布式事务参与者进行排序	1	否	是指按分区键排序，配合 enable_output_trans_order_by_sql_operation 可以得到稳定的语句输出顺序。
enable_output_hidden_primary_key	是否输出无主键表的隐藏主键	0	否	无主键表支持输出隐藏主键 enable_output_hidden_primary_key=1，输出无主键表隐藏主键。
enable_convert_timestamp_to_unix_timestamp	是否将 timestamp 时间戳转换为 UNIX 整型时间	0	否	无
enable_output_invisible_column	是否输出隐藏列	0	否	无
output_heartbeat_interval_msec	输出安全位点信息的间隔	1000	是	无

资源回收相关配置（不建议修改）

配置项	含义	默认值	可否动态变更	备注
resource_collector_thread_num	资源回收线程池大小	10	否	最小值为 1。
resource_collector_thread_num_for_br	用于回收 binlog record 线程池大小	7	否	需要大于 resource_collector_thread_num。

注意

不在本配置项说明文档里的配置不建议修改。

应急配置

应对 OceanBase 数据库异常情况下确保 obcdc 正常运行的应急配置：

配置项	含义	默认值	取值范围	可否动态变更	备注
lsn_black_list	控制忽略部分 LSN 的日志	`\|`	不涉及	否	应急情况下使用。
skip_delete_tablet_op	控制 obcdc 内是否忽略删除 tablet 的操作	0	{0, 1}	是	应急情况下使用，部分旁路导入/offline ddl 可能会导致 obcdc parser 模块报错 `ENTRY_NOT_EXIST`，需要配置该应急配置跳过错误，V4.2.1 BP2 后提供该配置。
skip_empty_outrow_lob_update	控制 obcdc 是否忽略空的 outrow LOB 的异常	0	{0, 1}	是	应急情况下使用。