配置参数说明

本文主要介绍v2.4版本开始的配置项，v2.4以前的配置项大体相同，名字上有过一些调整。 在配置文件里面，有过对各个参数的注释，但可能有些不足的地方，本文主要作为补充。

0. 版本号

• conf.version。当前配置文件的版本号，该参数将用于在不同版本之间进行兼容，比如2.6版本是否支持2.4的配置文件。请不要修改该值。

1. 全局配置

1.1 进程相关配置

• id。进程的id，将会用于存储pid信息，以防止同一个目录下有多个mongoshake同时启动。默认mongoshake。
• master_quorum。是否启动主备模式。表示只能启动1个mongoshake。配置true的话，用户可以启动2个mongoshake，拉取同一个源MongoDB，mongoshake将会自动选主，备在监测到主挂掉后，会接管过同步服务。注意，如果主是在全量同步阶段挂掉，那么备接管过服务是不会进行断点续传，而是会从头开始同步，而且如果配置项不当，可能还会有报错。主备模式主要用于在增量环节的HA容错切换。默认false

1.2 监控

• http_profile。对外提供restful接口，用户可以查看内部监控的情况。默认9100。
• system_profile。golang pprof端口，可以用户查看内部运行堆栈信息。默认9200。

1.3 日志

• log.level。日志的级别：debug, info, warning, error，对应日志里面的打印分别是[DEBG]，[INFO]，[WARN]，[EROR]。另外还有[CRIT]表示是最严重的错误，必须运维处理的。默认info。
• log.dir。log的输出路径，不配置将默认打到当前的logs目录。默认空。
• log.file。log的文件名，随着log变大，将会自动按天进行切割。默认mongoshake.log。
• log.flush。log是否及时缓存一部分再刷盘打印，默认为false以保证程序运行的性能，但可能程序中间崩溃退出，有部分log没有打印出来。true的话对于每条log都会进行刷盘，但是会降低部分性能。默认false。

1.4 连接相关配置（重要）

• sync_mode。同步的模式，有3种模式：all表示全量+增量同步，全量同步完毕以后进入增量同步；full表示仅进行全量同步，全量同步后进程将会退出；incr表示仅进行增量同步（默认），从给定的checkpoint（见下述）开始拉取增量数据。默认incr。
• mongo_urls。源MongoDB连接串的地址，其格式与mongo_shell使用的连接串格式保持一致。逗号分隔同一个副本集内的结点，分号分隔分片sharding实例，免密模式可以忽略“username:password@”，注意，密码里面不能含有'@'符号。
  举例：
  副本集的连接串格式（A是主节点，B和C是2个从节点）：mongodb://username1:password1@primaryA,secondaryB,secondaryC。
  分片集的连接串格式（shard1的结点是A,B,C；shard2是X,Y,Z）：mongodb://username1:password1@primaryA,secondaryB,secondaryC;mongodb://username2:password2@primaryX,secondaryY,secondaryZ。
  注意：如果mongo_connect_mode不是为standalone的话，每个副本集（分片）都需要配置primary+secondary的连接串，不能只配置一个secondary节点，但可以只配置primary的。
• mongo_cs_url。源MongoDB的config server的地址，如果源端是sharding，需要填写这个配置。默认空。
• mongo_connect_mode。数据是从源MongoDB的哪个节点进行拉取的，primary表示从主节点拉取；secondaryPreferred（默认）表示优先从secondary拉取，没有的话将会从primary拉取；standalone表示从给定的单个节点拉取。默认secondaryPreferred。

1.5 过滤相关

• filter.namespace.*。黑白名单过滤，有2个对应的参数：黑名单filter.namespace.black和白名单filter.namespace.white。目前不支持正则，白名单表示通过的namespace，黑名单表示过滤的namespace，不能同时指定。分号分割不同namespace，每个namespace可以是db，也可以是db.collection。例如，我想只通过db1，db2和db3中的collection1，那么配置filter.namespace.white=db1;db2;db3.collection1即可。默认空。
• filter.pass.special.db。指定特殊的namespace通过，比如admin，system.views，mongoshake，config。正常情况下，这几个都会被过滤，但是有可能有比较特殊的情况，例如，由于历史原因，用户的数据写入到admin库了，现在希望对这部分数据也进行同步，那么就可以执行filter.pass.special.db=admin。默认空。
• filter.ddl_enable。是否同步DDL。DML语句包括普通的insert，update，delete，DDL语句包括建/删索引，建/删库表，rename库表，事务等数据库结构的操作。false只同步DML，用户可以设置为true对DDL进行同步。默认false。

1.6 checkpoint相关（重要）

  checkpoint作为断点续传的位点信息，存储的是64位的混合逻辑时钟，对应MongoDB oplog的ts字段（32位时间戳+32位自增计数）。checkpoint将会不定期进行更新，所以一旦中间发生重启，将会从上次记录的checkpoint开始继续进行增量同步。如果sync_mode=oplog，第一次启动，由于没有checkpoint信息，将会从给定的checkpoint.start_position开始同步；对于sync_mode=document，将不会记录checkpoint信息，全量同步完毕直接退出；对于sync_mode=all的，全量同步完毕才会记录checkpoint。

• checkpoint.storage.url。格式跟mongo_urls一致，标识checkpoint存储的位置。如果不配置，对于副本集，默认写到源MongoDB；对于集群版，默认写到configure server。默认空。
• checkpoint.storage.db。checkpoint存储的表名地址，默认mongoshake。也就是说，对于副本集来说，checkpoint存在源库的的mongoshake db里面；对于sharding，这里需要强制配置admin库（cs里别的库不可写）。默认mongoshake。
• checkpoint.storage.collection。checkpoint存储的表名地址，默认ckpt_default。也就是说，对于副本集来说，checkpoint存在mongoshake.ckpt_default里面，对于集群版，checkpoint存在于cs的admin.ckpt_default里。默认ckpt_default。
• checkpoint.start_position。仅用于sync_mode是oplog的情况，第一次将会从这个指定的位点开始拉取。其格式是UTC的时间戳：2000-01-01T00:00:01Z。如果checkpoint在给定位置存在（参见checkpoint.storage.url和checkpoint.address），那么将会从checkpoint位置开始同步，忽略checkpoint.start_position参数；若checkpoint不存在，且该值为1970-01-01T00:00:01Z，则会拉取源端所有oplog；若checkpoint不存在，且该值不为1970-01-01T00:00:01Z，则会先检查源端oplog最老的时间是否大于给定的时间，如果是则会直接报错退出。所以，如果需要强制该位置开始拉取，在需要保证该位点有效的情况下，还需要删除原来的checkpoint。（用户可以通过rs.printReplicationInfo查看最老oplog的信息）默认1970-01-01T00:00:01Z。

1.7 其他

• transform.namespace。是否开启命名空间转换，比如源库的a.b，转换到目的库变成c.d。默认不开启，开启将会消耗比较大的资源，从而导致同步速率的大幅度的降低。谨慎建议开启。默认空。

2. 全量同步相关配置

2.1 并发相关参数

  不同客户需要根据自己的实际情况选择不同的参数，例如用户shake所在的机器，或者源和目的的MongoDB性能比较低，那么可以适当调低下列参数以降低对MongoDB的影响；如果用户的机器和MongoDB性能较高，那么可以适当调大相应参数以增大同步效率。

• full_sync.reader.collection_parallel。一次最大并发拉取的表的数目。默认6。
• full_sync.reader.document_parallel。对一个表内部，启动多少个线程进行并发拉取。默认8。
• full_sync.reader.document_batch_size。1次写入将会聚合多少个文档。128表示shake一次写入将会聚合128个文档进行发送到目的MongoDB。默认128。

2.2 结构化相关参数

• full_sync.collection_exist_no_drop。同步前如果发现目的端已经存在同样的表，是否需要先删除再进行同步，true表示不删除直接同步，但可能会存在_id一样的文档从而报错（参考full_sync.executor.*相关参数），false表示在目的端先删除对应的表再进行同步。默认false。
• full_sync.create_index。全量期间数据同步完毕后，是否需要创建前台索引，"foreground"表示前台创建索引，"none"表示不创建。默认foreground

2.3 增量持久化参数

• full_sync.reader.oplog_store_disk。一旦启用，在全量同步期间，对源库的oplog进行拉取并本地磁盘持久化，避免增量同步所需的oplog被源库删除，造成增量同步失败。默认false。
• full_sync.reader.oplog_store_disk_max_size。在全量同步期间，oplog本地持久化的容量上限，单位MB，若超过该值全量还没结束，则不再写入磁盘。默认256000。

2.3 写入端相关参数

• full_sync.executor.insert_on_dup_update。如果_id存在在目的库，是否将insert语句修改为update语句。若用户本来目的端就已经有数据，建议开启。默认false。
• full_sync.executor.filter.orphan_document。源端是sharding，是否需要过滤orphan文档。默认false。
• full_sync.executor.majority_enable。全量阶段写入端是否启用majority write。默认false。

3. 增量同步相关配置

3.1 拉取相关参数

• incr_sync.mongo_fetch_method。从源MongoDB拉取增量的方式，oplog（默认）表示以oplog进行拉取，change_stream表示以change stream进行对接拉取。oplog方式支持所有大于等于3.0的MongoDB版本，但对于sharding的同步，需要关掉balancer进行同步，否则会有时序不一致的问题。change_stream支持大于等于4.0的MongoDB版本，对于部分DDL的同步不支持，目前只支持库表的建/删，重命名，由于MongoDB本身的限制，对于建/删索引，convertToCapped，applyOps等都不支持。默认oplog。

3.2 双向同步

• incr_sync.oplog.gids。仅用于阿里云云MongoDB，开源请忽略。云上版本请在控制台开启global id（目前还没开启），或咨询响应售后同学。默认空。

3.3 并发控制参数

• incr_sync.shard_key。内部并发分发给worker线程的方式。id表示按主键_id进行哈希，collection表示按表哈希，auto表示自动识别，如果不存在索引那么会按照_id，存在则按照collection。如果修改为auto或者id，需要确认所有表都没有索引，并且后续也不会创建索引，按主键_id哈希的性能将会非常可观。默认collection。
• incr_sync.worker。worker线程的个数，默认为8，越大以为内部并发度将会越大。可以根据机器的负载情况适当调大/调小该参数。默认8。
• incr_sync.worker.oplog_compressor。仅用于非direct通道跨网络传输的情况，用户可以配置gzip, zlib或者deflate三种压缩方式，发送前数据将会进行压缩，以减少网络带宽的使用。默认none。
• incr_sync.worker.batch_queue_size。调优参数，不建议修改，参考FAQ。默认64。
• incr_sync.adaptive.batching_max_size。调优参数，不建议修改，参考FAQ。默认1024。
• incr_sync.fetcher.buffer_capacity。调优参数，不建议修改，参考FAQ。默认256。

3.4 通道参数

• incr_sync.tunnel。通道类型，direct表示目的端对接的是MongoDB，rpc，file，kafka用于远程传输，mock仅用于调试。默认direct。
• incr_sync.tunnel.address。通道地址，不同类型的通道需要配置不同的地址。
  对于direct，此处配置目的端MongoDB的地址。
  对于rpc，此处配置目的端receiver的rpc接收地址。
  对于tcp，此处配置目的端receiver的tcp接收地址。
  对于file，此处配置文件的路径，比如data。
  对于kafka，此处配置kafka的地址，例如topic@brokers1,brokers2，默认的topic是mongoshake，目前partition只用到0。
  
• incr_sync.tunnel.message。发送到tunnel的数据的类型，通常情况，对于非kafka通道，用户不需要关注该参数。raw是默认的类型，json表示以json格式输出oplog，bson表示以bson格式输出oplog。详见：如何使用kafka-tcp-rpc-file等异步通道进行数据的发送和消费。关于oplog的格式详见：oplog各字段的解析。

3.5 direct通道写入端相关配置

• incr_sync.executor.upsert。如果_id不存在在目的库，是否将update语句修改为insert语句。默认false。如果目的端是sharding，不能开启该参数。默认false。
• incr_sync.executor.insert_on_dup_update。如果_id存在在目的库，是否将insert语句修改为update语句。默认false。
• incr_sync.conflict_write_to。如果写入存在冲突，记录冲突的文档。db表示将冲突记录到checkpoint url对应的db里面。sdk表示写入sdk（开源没有用）。默认none。
• incr_sync.executor.majority_enable。增量阶段写入端是否启用majority write。默认false。