-
Notifications
You must be signed in to change notification settings - Fork 444
配置参数说明
zhangst edited this page Dec 13, 2022
·
35 revisions
本文主要介绍v2.4版本开始的配置项，v2.4以前的配置项大体相同，名字上有过一些调整。 在配置文件里面，有过对各个参数的注释，但可能有些不足的地方，本文主要作为补充。
- conf.version。当前配置文件的版本号，该参数将用于在不同版本之间进行兼容，比如2.6版本是否支持2.4的配置文件。请不要修改该值。
- id。进程的id，将会用于存储pid信息，以防止同一个目录下有多个mongoshake同时启动。默认mongoshake。
- master_quorum。是否启动主备模式。false表示只能启动1个mongoshake。配置true的话，用户可以启动2个mongoshake，拉取同一个源MongoDB，mongoshake将会自动选主，备在监测到主挂掉后，会接管过同步服务。注意，如果主是在全量同步阶段挂掉，那么备接管过服务是不会进行断点续传，而是会从头开始同步，而且如果配置项不当，可能还会有报错。主备模式主要用于在增量环节的HA容错切换。默认false
- full_sync.http_port。全量阶段对外提供restful接口，用户可以查看内部监控的情况。默认9101。
- incr_sync.http_port。增量阶段对外提供restful接口，用户可以查看内部监控的情况。默认9100。
- system_profile_port。golang pprof端口，可以用户查看内部运行堆栈信息。默认9200。
- 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。
- 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_s_url。源MongoDB的mongos地址，如果源端是sharding，需要填写这个配置。默认空。
- mongo_connect_mode。数据是从源MongoDB的哪个节点进行拉取的，primary表示从主节点拉取；secondaryPreferred（默认）表示优先从secondary拉取，没有的话将会从primary拉取；standalone表示从给定的单个节点拉取。需要注意的是，如果源端是sharding，且版本小于3.6，而且是全量同步（sync_mode=full），或者全量+增量同步（sync_mode=incr），建议这里配置primary以避免孤儿文档，参考MongoShake从mongos拉取仍旧存在duplicate key error。默认secondaryPreferred。
- tunnel。通道类型，direct表示目的端对接的是MongoDB，rpc，file，kafka用于远程传输，mock仅用于调试。默认direct。
- tunnel.address。通道地址，不同类型的通道需要配置不同的地址。
对于direct，此处配置目的端MongoDB的地址。
对于rpc，此处配置目的端receiver的rpc接收地址。
对于tcp，此处配置目的端receiver的tcp接收地址。
对于file，此处配置文件的路径，比如data。
对于kafka，此处配置kafka的地址，例如topic@brokers1,brokers2，默认的topic是mongoshake，目前partition只用到0。
- tunnel.message。发送到tunnel的数据的类型，通常情况，对于非kafka通道，用户不需要关注该参数。raw是默认的类型，json表示以json格式输出oplog，bson表示以bson格式输出oplog。详见：如何使用kafka-tcp-rpc-file等异步通道进行数据的发送和消费。关于oplog的格式详见：oplog各字段的解析。
- tunnel.kafka.partition_number。v2.4.21引入。控制写入的partition个数，具体oplog是写入到哪个partition是由
incr_sync.shard_key参数决定，默认按照表进行hash，保证单个partition的有序。默认为1。 详见v2.4.21优化kafka写入性能和写入格式
- 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。
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。如果不配置，对于副本集，默认写到源MongoDB；对于集群版，默认写到configure server（从2.4.6版本开始，集群版checkpoint地址改为默认写到源端mongos）。默认空。 - checkpoint.storage.db。checkpoint存储的表名地址，默认mongoshake。也就是说，对于副本集来说，checkpoint存在源库的的mongoshake db里面；对于sharding，2.4.6开始默认写mongos。默认mongoshake。
- checkpoint.storage.collection。checkpoint存储的表名地址，默认ckpt_default。也就是说，对于副本集来说，checkpoint存在mongoshake.ckpt_default里面，对于集群版，checkpoint存在于cs的admin.ckpt_default里（从2.4.6版本开始，集群版checkpoint地址改为默认写到源端mongos）。默认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。
- transform.namespace。是否开启命名空间转换，比如源库的a.b，转换到目的库变成c.d。默认不开启，开启将会消耗比较大的资源，从而导致同步速率的大幅度的降低。谨慎建议开启。默认空。
不同客户需要根据自己的实际情况选择不同的参数，例如用户shake所在的机器，或者源和目的的MongoDB性能比较低，那么可以适当调低下列参数以降低对MongoDB的影响；如果用户的机器和MongoDB性能较高，那么可以适当调大相应参数以增大同步效率。
- full_sync.reader.collection_parallel。一次最大并发拉取的表的数目。默认6。
- full_sync.reader.write_document_parallel。对一个表内部，启动多少个线程进行并发写入。默认8。
- full_sync.reader.document_batch_size。1次写入将会聚合多少个文档。128表示shake一次写入将会聚合128个文档进行发送到目的MongoDB。默认128。
- full_sync.reader.read_document_count。2.4.7版本开始启用，2.6.4版本废弃。表示1个table切分的块大小，比如该值为1000，那么假如table有5000个文档，那么会切分成5个块并发拉取。0表示不启用切分，建议该值不要设置过低导致并发度过高，会对shake本身机器负载以及目的端MongoDB造成压力，一个表并发在4-32为最佳值。默认0。
- full_sync.reader.parallel_thread。2.6.4版本引入。单表并发拉取的线程个数，_默认为1_表示沿用单线程拉取。
- full_sync.reader.parallel_index。2.6.4版本引入。单表切分成多个段所依赖的索引，对于副本集建议配置_id（默认）；对于分片集群，建议配置shard key，不过目前只支持单个字段，不支持多个字段的联合索引。
- full_sync.collection_exist_drop。同步前如果发现目的端已经存在同样的表，是否需要先删除再进行同步，false表示不删除直接同步，但可能会存在_id一样的文档从而报错（参考full_sync.executor.*相关参数），true表示在目的端先删除对应的表再进行同步。默认true。
- full_sync.create_index。全量期间数据同步完毕后，是否需要创建前台索引，"foreground"表示前台创建索引，"none"表示不创建，2.4.1版本开始支持"background"后台创建索引。默认foreground
- full_sync.reader.oplog_store_disk。2.4版本废弃。一旦启用，在全量同步期间，对源库的oplog进行拉取并本地磁盘持久化，避免增量同步所需的oplog被源库删除，造成增量同步失败。默认false。
- full_sync.reader.oplog_store_disk_max_size。在全量同步期间，oplog本地持久化的容量上限，单位MB，若超过该值全量还没结束，则不再写入磁盘。默认256000。
- 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。
- 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本身的限制(不支持在ChangeStream输出这些命令)，对于建/删索引，convertToCapped，applyOps等都不支持。默认oplog。
- incr_sync.target_delay。控制延迟同步的时间，目的端可以落后于源端指定的秒数，详细请参考：v2.4.6版本增加延迟同步功能 。默认0
- incr_sync.oplog.gids。仅用于阿里云云MongoDB，开源请忽略。云上版本请在控制台开启global id（目前还没开启），或咨询响应售后同学。默认空。
- incr_sync.shard_key。内部并发分发给worker线程的方式。id表示按主键
_id进行哈希，collection表示按表哈希，auto表示自动识别，如果不存在索引那么会按照_id，存在则按照collection。如果修改为auto或者id，需要确认所有表都没有索引，并且后续也不会创建索引，按主键_id哈希的性能将会非常可观。默认collection。 - incr_sync.shard_by_object_id_whitelist。按
_id并发的白名单，具体请参考v2.4.12 增加incr_sync.shard_by_object_id_whitelist参数解决没有唯一索引情况下的单表倾斜问题。 - incr_sync.worker.worker线程的个数，默认为8，越大以为内部并发度将会越大。可以根据机器的负载情况适当调大/调小该参数。默认8。
- incr_sync.worker.oplog_compressor。2.4.21废弃。仅用于非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。
- incr_sync.tunnel.write_thread。v2.4.21版本引入。控制序列化的线程个数，默认为1个tunnel（worker）对应1个。该参数必须为worker的倍数，比如worker默认是8，如果该参数为24，则每个worker对应3个解析线程。默认为空。 详见v2.4.21优化kafka写入性能和写入格式
- 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。
- incr_sync.change_stream.watch_full_document。change stream专用参数。更新文档后，只需要更新的字段则设为false，需要全部文档内容则设为true。不设置在$set/$unset只会显示差异化的字段，而不会展示所有文档的字段。启用会导致性能有所下降。默认false。
- special.source.db.flag。特殊形态支持，比如阿里云的serverless请选择
aliyun_serverless。默认为空。