簡介面向部署數(shù)據(jù)庫遷移工具的開發(fā)與運(yùn)維人員這份容器鏡像集合將遷移引擎、代理服務(wù)、監(jiān)控告警、可視化界面等組件打包為可一鍵編排的部署方案。包內(nèi)共十一個(gè)文件包含十個(gè)gz格式的容器鏡像包和一個(gè)YAML編排文件整體大小約七百三十八兆。鏡像覆蓋數(shù)據(jù)庫、消息代理、監(jiān)控、可視化等核心服務(wù)配合編排文件執(zhí)行單條命令即可批量啟動(dòng)所有依賴組件省去手工配置網(wǎng)絡(luò)、卷掛載與環(huán)境變量的繁瑣步驟。對(duì)于需要快速搭建數(shù)據(jù)庫同步或遷移環(huán)境的技術(shù)團(tuán)隊(duì)該資源能顯著縮短環(huán)境準(zhǔn)備時(shí)間并借助監(jiān)控與可視化組件獲得清晰的運(yùn)行狀態(tài)視圖。目前已有四十八人學(xué)習(xí)下載適合具備基礎(chǔ)容器使用經(jīng)驗(yàn)、希望直接復(fù)用現(xiàn)成編排方案的讀者。1. 為什么說 DBmotion 的全量遷移先從一份容器集合開始做數(shù)據(jù)遷移的人應(yīng)該都有這種體會(huì)真正耗時(shí)間的往往不是遷移任務(wù)本身而是把源端、采集端、傳輸通道、目標(biāo)端這一整套依賴環(huán)境湊齊。DBmotion 這類遷移工具雖然把同步邏輯封裝得很好但它的全量遷移鏈路里ZooKeeper、Kafka、etcd、采集與寫入服務(wù)一個(gè)都少不了。手動(dòng)一個(gè)個(gè)裝、一個(gè)個(gè)調(diào)半天過去了還沒開始遷移數(shù)據(jù)。所謂“DBmotion 全量所需要容器集合包含可執(zhí)行的 docker-compose.yaml”就是把這條鏈路里的每個(gè)環(huán)節(jié)都做成容器用一份 docker-compose 編排文件一次性拉起來。適合兩種人一是想快速評(píng)估 DBmotion 遷移效果、不想在環(huán)境搭建上花太多時(shí)間的開發(fā)者二是要給客戶或內(nèi)部環(huán)境交付遷移方案需要一套可復(fù)現(xiàn)、可移植的部署模板。這篇文章按我實(shí)際搭建這套環(huán)境的順序把容器集合怎么設(shè)計(jì)、compose 文件怎么寫、參數(shù)怎么調(diào)、哪些坑必踩一次講清楚。2. 拆開 DBmotion 的容器集合每個(gè)容器解決遷移鏈路里的哪個(gè)環(huán)節(jié)2.1 一條全量遷移鏈路里哪些組件是不能省的DBmotion 做全量遷移簡單說就是“讀源庫 → 傳輸 → 寫目標(biāo)庫”。但中間為了保證數(shù)據(jù)不丟、順序不亂、斷點(diǎn)能續(xù)引入了一組支撐組件。我最早做模擬項(xiàng)目X的時(shí)候就想著精簡只起源端和目標(biāo)端兩個(gè)容器結(jié)果根本跑不通。后來把鏈路理清楚才發(fā)現(xiàn)下面這些角色各有各的活誰也替不了誰。源端數(shù)據(jù)庫容器承擔(dān)“數(shù)據(jù)從哪來”的角色。全量遷移要驗(yàn)證數(shù)據(jù)一致性沒有真實(shí)的源庫實(shí)例后面所有環(huán)節(jié)都是空轉(zhuǎn)。我一般用 MySQL 或 PostgreSQL 的官方鏡像直接掛初始化腳本造數(shù)據(jù)。采集端容器是 DBmotion 里干累活的。它連上源庫把全量數(shù)據(jù)按表讀出來轉(zhuǎn)成統(tǒng)一的消息格式發(fā)到 Kafka。這個(gè)角色通常對(duì)應(yīng) DBmotion 的采集服務(wù)如果只是做功能驗(yàn)證可以用輕量模擬程序代替但正式評(píng)估時(shí)必須用真實(shí)的采集節(jié)點(diǎn)。Kafka 是核心傳輸通道。全量數(shù)據(jù)量大采集端不可能直接往目標(biāo)庫灌那樣源庫和目標(biāo)庫會(huì)互相拖垮。Kafka 在這里相當(dāng)于一個(gè)高速緩沖帶采集端只管往里面寫寫入端只管從里面讀兩者解耦。Kafka 本身依賴 ZooKeeper 做元數(shù)據(jù)管理所以 ZooKeeper 容器成了隱藏的必需項(xiàng)。etcd 管的是遷移任務(wù)的元數(shù)據(jù)。哪些表遷移完了、遷移到哪個(gè)偏移量了、任務(wù)當(dāng)前什么狀態(tài)這些都存在 etcd 里。沒有它斷點(diǎn)續(xù)傳就是空話。最后是寫入端容器它消費(fèi) Kafka 里的數(shù)據(jù)把全量數(shù)據(jù)按目標(biāo)庫的方言寫入同時(shí)往 etcd 上報(bào)進(jìn)度。這么一拆就很清楚了源端、采集端、Kafka、ZooKeeper、etcd、寫入端、目標(biāo)端七個(gè)角色缺一個(gè)鏈路就斷。我見過有人想把 ZooKeeper 省掉直接連 Kafka只能說那是給自己挖坑。2.2 為什么用 ZooKeeper Kafka etcd 三件套而不是單機(jī)版很多人第一次看到這套組合會(huì)問都是存元數(shù)據(jù)為什么 Kafka 要配 ZooKeeperDBmotion 自己又要一個(gè) etcd這倆不能合并嗎答案是職責(zé)不同。Kafka 用 ZooKeeper 存的是 broker 列表、分區(qū)分配、消費(fèi)者組偏移量這些“消息系統(tǒng)自己的狀態(tài)”。Kafka 的歷史版本把 ZooKeeper 當(dāng)成硬依賴雖然新版本在做 KRaft 模式去 ZooKeeper但 DBmotion 官方鏈路默認(rèn)還是走 ZooKeeper 的方式實(shí)盤驗(yàn)證時(shí)扯皮最少。我自己試過 KRaft 模式不是說不行而是排查問題時(shí)社區(qū)資料少一旦出狀況很難判斷是 DBmotion 的問題還是 Kafka 自身的問題。etcd 管的是遷移任務(wù)級(jí)別的元數(shù)據(jù)比如哪個(gè)表遷移到哪條記錄了。這不是 Kafka 的分區(qū)偏移量是業(yè)務(wù)數(shù)據(jù)在遷移管道里的進(jìn)度。如果硬塞進(jìn) Kafka 的 topic 里任務(wù)一旦重建歷史偏移量會(huì)污染新任務(wù)。所以這套“三件套”不是重復(fù)造輪子而是各自守住各自的邊界。ZooKeeper 守消息系統(tǒng)etcd 守遷移任務(wù)。明白了這一點(diǎn)編排容器時(shí)就能理解為什么每個(gè)服務(wù)都要獨(dú)立部署而不是圖省事塞進(jìn)同一個(gè)容器里。進(jìn)程混在一起日志、重啟、擴(kuò)容全都互相干擾全量遷移跑到一半某個(gè)組件掛了排查起來想死的心都有。2.3 容器集合的拓?fù)渑c端口規(guī)劃我把整套容器集合的拓?fù)涔潭ǔ闪艘粡埍砻看未钚颅h(huán)境直接照著抄。拓?fù)渖戏譃槿龑訑?shù)據(jù)層、傳輸層、任務(wù)層。數(shù)據(jù)層是源端和目標(biāo)端數(shù)據(jù)庫傳輸層是 Kafka 加 ZooKeeper任務(wù)層是采集端、寫入端和 etcd。DBmotion 本身的管理端如果有放在任務(wù)層最上面負(fù)責(zé)下發(fā)任務(wù)和查看狀態(tài)。服務(wù)鏡像類型默認(rèn)端口數(shù)據(jù)持久化職責(zé)source-dbMySQL/PostgreSQL 官方鏡像3306/5432是初始化腳本掛載全量數(shù)據(jù)來源target-db目標(biāo)數(shù)據(jù)庫官方鏡像3306/5432是全量數(shù)據(jù)寫入目標(biāo)zookeeperZooKeeper 官方鏡像2181是dataDir 掛載Kafka 元數(shù)據(jù)存儲(chǔ)kafkaKafka 官方鏡像9092是log.dirs 掛載全量數(shù)據(jù)傳輸通道etcdetcd 官方鏡像2379, 2380是data 目錄掛載遷移任務(wù)進(jìn)度/狀態(tài)dbmotion-collectorDBmotion 采集端鏡像無外部端口否讀源庫寫 Kafkadbmotion-writerDBmotion 寫入端鏡像無外部端口否讀 Kafka寫目標(biāo)庫端口規(guī)劃有個(gè)原則只有需要被外部訪問的服務(wù)才映射到宿主機(jī)服務(wù)間通信用 Docker 內(nèi)部網(wǎng)絡(luò)。Kafka 比較特殊因?yàn)榭蛻舳瞬杉恕懭攵伺茉趧e的容器里Kafka 自己的 advertised.listeners 必須配成容器網(wǎng)絡(luò)內(nèi)的地址否則會(huì)踩“容器里連不上 Kafka”的經(jīng)典大坑。這一點(diǎn)后面專門講。etcd 的 2380 是集群內(nèi)部 peer 通信用的單節(jié)點(diǎn)部署不需要映射到宿主機(jī)2379 看需要再?zèng)Q定要不要暴露。3. 寫一份可執(zhí)行的 docker-compose.yaml部署模型與關(guān)鍵參數(shù)3.1 先從 compose 文件結(jié)構(gòu)入手網(wǎng)絡(luò)、卷、服務(wù)三段式一份可執(zhí)行的 compose 文件結(jié)構(gòu)上分三塊networks 定義容器間通信網(wǎng)絡(luò)volumes 定義持久化存儲(chǔ)services 定義每個(gè)容器。全量遷移的場景里容器之間都是“服務(wù)發(fā)現(xiàn)”的關(guān)系——采集端通過 etcd 找任務(wù)通過 Kafka 發(fā)數(shù)據(jù)寫入端從 Kafka 拉數(shù)據(jù)。所以網(wǎng)絡(luò)必須用自定義 bridge 網(wǎng)絡(luò)而不是默認(rèn)的 default 網(wǎng)絡(luò)這樣才能用服務(wù)名互相訪問。下面是我整理出來的精簡版文件框架。注意 source-db 和 target-db 的初始化腳本我用的是掛載目錄而不是鏡像內(nèi)嵌這樣換表結(jié)構(gòu)、換數(shù)據(jù)都不用重新 build 鏡像。version: 3.8 networks: dbmotion-net: driver: bridge ipam: config: - subnet: 172.28.0.0/16 volumes: zk-data: kafka-data: etcd-data: source-db-data: target-db-data: services: zookeeper: image: zookeeper:3.8 container_name: dbmotion-zookeeper networks: dbmotion-net: ipv4_address: 172.28.0.10 ports: - 2181:2181 volumes: - zk-data:/data - ./zk-conf:/conf environment: ZOO_MY_ID: 1 ZOO_SERVERS: server.1zookeeper:2888:3888;2181 healthcheck: test: [CMD, zkServer.sh, status] interval: 10s timeout: 5s retries: 5network 指定了固定子網(wǎng)和固定 IP。這個(gè)做法在 compose 里不是必須的但配合 healthcheck 和 depends_on 的 condition 時(shí)服務(wù)名解析穩(wěn)定排查網(wǎng)絡(luò)問題也少一層干擾。volumes 全部用 named volume而不是 bind mount 到宿主機(jī)目錄原因是遷移環(huán)境經(jīng)常要在不同機(jī)器之間搬named volume 隨 compose 項(xiàng)目走不會(huì)被宿主機(jī)路徑差異絆倒。zookeeper 這里指定了 ZOO_MY_ID 和 ZOO_SERVERS。單節(jié)點(diǎn)時(shí) ZOO_MY_ID 寫 1 就行ZOO_SERVERS 的格式是 server.1主機(jī)名:2888:3888;21812888 是 Leader 選舉端口3888 是集群內(nèi)通信端口。單節(jié)點(diǎn)不涉及選舉但配全了以后想擴(kuò)成三節(jié)點(diǎn)集群只需再追加 server.2 和 server.3不用改其他配置。healthcheck 用的是 zkServer.sh status這條命令在容器里返回 0 表示服務(wù)健康。3.2 中間件服務(wù)的參數(shù)陷阱Kafka 的 advertised.listeners 與健康檢查Kafka 是這套容器集合里最容易翻車的服務(wù)沒有之一。官方鏡像默認(rèn)的 listener 配置只對(duì)宿主機(jī)訪問友好容器內(nèi)其他服務(wù)通過服務(wù)名訪問時(shí)Kafka 返回的 broker 地址是容器 ID客戶端拿著這個(gè)地址去連必然超時(shí)。這就是業(yè)界說的“Kafka 容器網(wǎng)絡(luò)黑匣子”問題。解決辦法是在 environment 里顯式指定三組 listenerPLAINTEXT 負(fù)責(zé)容器內(nèi)通信EXTERNAL 負(fù)責(zé)宿主機(jī)訪問CONTROLLER 是給新版本 Kafka 用的。advertised.listeners 必須寫成服務(wù)名 kafka:9092而不是 localhost 或宿主機(jī) IP。如果寫 127.0.0.1采集容器里的客戶端能連上 broker但 broker 返回的元數(shù)據(jù)里寫的地址還是 127.0.0.1客戶端拿這個(gè)地址根本路由不到 Kafka 容器。kafka: image: bitnami/kafka:3.4 container_name: dbmotion-kafka networks: dbmotion-net: ipv4_address: 172.28.0.11 ports: - 9092:9092 volumes: - kafka-data:/bitnami/kafka environment: KAFKA_CFG_NODE_ID: 1 KAFKA_CFG_PROCESS_ROLES: broker,controller KAFKA_CFG_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093 KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 1kafka:9093 KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: true KAFKA_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 KAFKA_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1 KAFKA_CFG_TRANSACTION_STATE_LOG_MIN_ISR: 1 ALLOW_PLAINTEXT_LISTENER: yes KAFKA_HEAP_OPTS: -Xmx512m -Xms256m healthcheck: test: [CMD, kafka-topics.sh, --bootstrap-server, localhost:9092, --list] interval: 15s timeout: 10s retries: 5 start_period: 30s這里用的是 bitnami 鏡像環(huán)境變量前綴 KAFKA_CFG_ 是 bitnami 的封裝規(guī)范和 Apache 官方鏡像的 KAFKA_ 前綴不一樣。選 bitnami 的原因是其健康檢查腳本更完整kafka-topics.sh --list 能真實(shí)反映 broker 是否對(duì)外可用而 Apache 鏡像默認(rèn)的 healthcheck 經(jīng)常只是檢查進(jìn)程在不在。KAFKA_CFG_PROCESS_ROLES 寫成 broker,controller 是讓單節(jié)點(diǎn)同時(shí)承擔(dān) broker 和 controller 職責(zé)。全量遷移的最小環(huán)境不需要獨(dú)立的 KRaft controller 節(jié)點(diǎn)。副本因子全部設(shè)成 1因?yàn)閱喂?jié)點(diǎn) Kafka 上不允許配大于 1 的副本因子這個(gè)參數(shù)不影響遷移正確性但能避免一堆 “Replication factor is larger than available brokers” 的報(bào)錯(cuò)刷屏。KAFKA_HEAP_OPTS 限制 JVM 內(nèi)存后面避坑章節(jié)專門講內(nèi)存問題。etcd 的配置相對(duì)清爽主要注意 client 端口和 peer 端口的區(qū)分。etcd: image: quay.io/coreos/etcd:v3.5.5 container_name: dbmotion-etcd networks: dbmotion-net: ipv4_address: 172.28.0.12 ports: - 2379:2379 volumes: - etcd-data:/etcd-data command: - /usr/local/bin/etcd - --nameetcd0 - --data-dir/etcd-data - --advertise-client-urlshttp://etcd:2379 - --listen-client-urlshttp://0.0.0.0:2379 - --listen-peer-urlshttp://0.0.0.0:2380 - --initial-advertise-peer-urlshttp://etcd:2380 - --initial-clusteretcd0http://etcd:2380 - --initial-cluster-statenew healthcheck: test: [CMD, etcdctl, endpoint, health] interval: 10s timeout: 5s retries: 5advertise-client-urls 寫容器服務(wù)名 etcd 而不是 IP這樣 DBmotion 寫入端的容器不管調(diào)度到哪個(gè)網(wǎng)絡(luò)位置都能通過服務(wù)名穩(wěn)定訪問。initial-cluster-state 必須寫 new如果寫 existingetcd 會(huì)去找舊集群狀態(tài)單節(jié)點(diǎn)場景下會(huì)一直卡在等待集群就緒。3.3 DBmotion 相關(guān)服務(wù)的啟動(dòng)順序與 depends_on 的正確用法容器編排里啟動(dòng)順序是個(gè)老生常談但永遠(yuǎn)有人踩坑的問題。DBmotion 采集端啟動(dòng)時(shí)必須能連上 etcd 和 Kafka寫入端必須能連上 Kafka 和 etcd而 Kafka 又要等 ZooKeeper 就緒。這些依賴如果用默認(rèn)的 depends_ondocker compose 只保證“先啟動(dòng)”不保證“真就緒”采集端大概率在 Kafka 還在初始化時(shí)就嘗試連接然后崩潰退出。容器退出后 compose 不會(huì)自動(dòng)重啟整套環(huán)境就癱在那里。正確做法是 depends_on 配 condition: service_healthy再配合每個(gè)中間件的 healthcheck。compose 會(huì)先啟動(dòng)依賴服務(wù)等 healthcheck 通過后才啟動(dòng)下游服務(wù)。dbmotion-collector: image: dbmotion-collector:latest container_name: dbmotion-collector networks: dbmotion-net: ipv4_address: 172.28.0.20 depends_on: kafka: condition: service_healthy etcd: condition: service_healthy environment: DBMOTION_ROLE: collector DBMOTION_ETCD_ENDPOINTS: http://etcd:2379 DBMOTION_KAFKA_BOOTSTRAP: kafka:9092 DBMOTION_SOURCE_DSN: root:sourcepasstcp(source-db:3306)/migration_db?charsetutf8mb4 command: [/app/dbmotion-collector, --config, /etc/dbmotion/collector.yaml] dbmotion-writer: image: dbmotion-writer:latest container_name: dbmotion-writer networks: dbmotion-net: ipv4_address: 172.28.0.21 depends_on: kafka: condition: service_healthy etcd: condition: service_healthy environment: DBMOTION_ROLE: writer DBMOTION_ETCD_ENDPOINTS: http://etcd:2379 DBMOTION_KAFKA_BOOTSTRAP: kafka:9092 DBMOTION_TARGET_DSN: root:targetpasstcp(target-db:3306)/migration_target?charsetutf8mb4 command: [/app/dbmotion-writer, --config, /etc/dbmotion/writer.yaml]DBMOTION_SOURCE_DSN 和 DBMOTION_TARGET_DSN 里的主機(jī)名全部寫服務(wù)名tcp(source-db:3306) 這種格式是 Go 語言數(shù)據(jù)庫驅(qū)動(dòng)的標(biāo)準(zhǔn)寫法。這里有個(gè)容易忽略的點(diǎn)source-db 和 target-db 這兩個(gè)容器本身也要配 healthcheck否則 depends_on 里如果加了它們condition 會(huì)檢查不到健康狀態(tài)而一直等待。MySQL 鏡像的 healthcheck 建議用 mysqladmin pingPostgreSQL 用 pg_isready。啟動(dòng)順序變長了以后整套環(huán)境冷啟動(dòng)可能要等 1 到 2 分鐘這不是卡死是中間件在做初始化。后面加了一個(gè) start_period 參數(shù)專門解決“啟動(dòng)慢被 healthcheck 誤殺”的問題。采集端和寫入端的鏡像這里用 dbmotion-collector:latest 指代實(shí)際使用時(shí)換成你自己的鏡像名。4. 把容器集合跑起來從 docker compose up 到第一個(gè)遷移任務(wù)4.1 啟動(dòng)前檢查端口沖突、內(nèi)存預(yù)算、鏡像源啟動(dòng)之前有三次檢查能幫你省掉后面至少兩個(gè)小時(shí)的排查時(shí)間。第一次檢查端口沖突。2181、9092、2379 這三個(gè)端口是中間件默認(rèn)端口本機(jī)如果已經(jīng)跑著別的 ZooKeeper、Kafka 或 etcdcompose 起服務(wù)時(shí)會(huì)直接報(bào) bind: address already in use。檢查命令很簡單lsof -i :2181 -i :9092 -i :2379有輸出說明端口被占了。解決方式有兩個(gè)關(guān)掉宿主機(jī)的舊服務(wù)或者在 compose 文件里改 ports 映射的宿主機(jī)側(cè)端口比如把 Kafka 改成 19092:9092。要注意改宿主機(jī)側(cè)端口不影響容器間通過服務(wù)名訪問因?yàn)槿萜鏖g走的是 9092 這個(gè)容器內(nèi)端口。第二次檢查內(nèi)存預(yù)算。Kafka 默認(rèn)的 JVM 堆上限是 1G加上 ZooKeeper、etcd、兩個(gè)數(shù)據(jù)庫實(shí)例整套環(huán)境冷啟動(dòng)大概需要 3 到 4G 可用內(nèi)存。如果機(jī)器只有 2GKafka 會(huì)頻繁 Full GC然后被 healthcheck 判死compose 就會(huì)反復(fù)重啟它日志里全是內(nèi)存溢出。建議在 compose 里給 Kafka 顯式限制 KAFKA_HEAP_OPTS給 MySQL/PostgreSQL 用 shm_size 控制共享內(nèi)存。第三次檢查鏡像源。DBmotion 相關(guān)鏡像如果是私有倉庫docker compose 不會(huì)自動(dòng)登錄需要先手動(dòng) docker login。ZooKeeper、Kafka、etcd 這幾個(gè)中間件鏡像建議提前 docker pull 到本地免得 compose up 時(shí)才開始拉一旦網(wǎng)絡(luò)不穩(wěn)定整個(gè)環(huán)境起得斷斷續(xù)續(xù)。4.2 啟動(dòng)整套環(huán)境與驗(yàn)證每個(gè)容器狀態(tài)檢查做完就可以啟動(dòng)了。我習(xí)慣用后臺(tái)模式啟動(dòng)然后把日志輸出到文件方便后面排查。docker compose up -d這個(gè)命令會(huì)按依賴順序依次啟動(dòng)所有容器。等第一次執(zhí)行完別急著配遷移任務(wù)先花 30 秒確認(rèn)每個(gè)容器都進(jìn)入了 healthy 狀態(tài)docker compose ps輸出里每個(gè)服務(wù)對(duì)應(yīng)一行STATUS 列應(yīng)該有 healthy 字樣。這一步非常重要因?yàn)椴杉撕蛯懭攵说膯?dòng)依賴于 Kafka 和 etcd 健康如果中間件還處于 starting下游容器會(huì)卡在等待狀態(tài)?？吹?unhealthy 的容器立即看它的日志docker compose logs -f kafka docker compose logs -f etcd日志出現(xiàn)的常見關(guān)鍵字也有套路。ZooKeeper 日志里出現(xiàn) bind to port 2181 說明監(jiān)聽成功Kafka 日志里出現(xiàn) [KafkaRaftServer nodeId1] Started 說明 KRaft 模式啟動(dòng)完成etcd 日志出現(xiàn) serving insecure client requests on 0.0.0.0:2379 說明客戶端接口可用。如果等了兩分鐘這些關(guān)鍵字還沒出現(xiàn)基本可以斷定配置有問題而不是啟動(dòng)慢。所有容器都 healthy 之后再驗(yàn)證一下容器間的網(wǎng)絡(luò)連通性。我一般會(huì)進(jìn)入采集端容器里用內(nèi)置工具測試到 Kafka 和 etcd 的連通性docker exec -it dbmotion-collector bash # 在容器內(nèi)執(zhí)行 curl http://etcd:2379/health # 期望輸出 {health:true} kafka-topics.sh --bootstrap-server kafka:9092 --list # 期望輸出不報(bào)錯(cuò)哪怕沒有 topic這一步驗(yàn)證的是服務(wù)名解析和端口連通。curl 輸出 health true 說明 etcd 正常kafka-topics.sh 能連上說明 Kafka 的 advertised.listeners 配置生效了。如果這兩步有一處失敗不要繼續(xù)往下配任務(wù)先回頭改配置。4.3 跑通一個(gè)最小全量遷移任務(wù)環(huán)境就緒后遷移任務(wù)本身怎么下發(fā)DBmotion 的做法是通過 etcd 寫入任務(wù)配置采集端和寫入端監(jiān)聽 etcd 的變化然后開始干活。所以我需要往 etcd 里寫入一個(gè)最小的遷移任務(wù)配置。任務(wù)配置的核心內(nèi)容包括源庫連接信息、目標(biāo)庫連接信息、要遷移的表列表、Kafka topic 名稱。docker exec -it dbmotion-etcd etcdctl put /dbmotion/tasks/task001 { name: full_migration_demo, source: root:sourcepasstcp(source-db:3306)/migration_db, target: root:targetpasstcp(target-db:3306)/migration_target, tables: [users, orders], kafka_topic: dbmotion-full-001, mode: full, batch_size: 1000 }這段配置我一般在源庫和目標(biāo)庫里都先建好同名表再填到 etcd。batch_size 控制每個(gè)批次寫入的記錄數(shù)設(shè) 1000 是保守值主要考慮目標(biāo)庫寫入性能和 Kafka 消息大小。模式寫成 full表示只做全量遷移不做增量同步。字段名和結(jié)構(gòu)按實(shí)際 DBmotion 版本可能略有差異但核心信息就是這四類兩端連接、表清單、通道、批大小。任務(wù)寫進(jìn)去之后采集端監(jiān)聽到配置變化會(huì)去源庫讀數(shù)據(jù)然后發(fā)到 Kafka寫入端從 Kafka 拉數(shù)據(jù)寫入目標(biāo)庫。整個(gè)過程中可以通過 etcd 查看任務(wù)進(jìn)度docker exec -it dbmotion-etcd etcdctl get /dbmotion/tasks/task001/status看到 status 字段變成 finished 或 done說明全量遷移跑完了。這時(shí)進(jìn)目標(biāo)庫查一下數(shù)據(jù)量docker exec -it dbmotion-target-db mysql -uroot -ptargetpass -e SELECT COUNT(*) FROM migration_target.users;如果和目標(biāo)庫源表行數(shù)一致第一個(gè)全量遷移任務(wù)就算通了。第一次跑通的意義不在于遷移了多大數(shù)據(jù)量而在于驗(yàn)證了從容器集合到任務(wù)下發(fā)的整條鏈路是通的后續(xù)換真實(shí)庫、加表、調(diào)并發(fā)都在這條鏈路上迭代。5. 容器集合落地避坑五個(gè)最容易翻車的點(diǎn)5.1 Kafka 容器起來了客戶端卻連不上現(xiàn)象docker compose ps 顯示 Kafka 是 healthy但采集端容器日志里反復(fù)報(bào) connection refused 或者 timeoutKafka 的 topic 列表也拉取失敗。原因絕大多數(shù)情況是 advertised.listeners 配置不對(duì)。Kafka 容器對(duì)外廣播的地址寫成了 localhost 或 127.0.0.1容器內(nèi)的采集端拿到這個(gè)地址后嘗試連自己自然連不上。我見過有人排查了一下午最后發(fā)現(xiàn)是 KAFKA_CFG_ADVERTISED_LISTENERS 漏了 KAFKA_CFG_ 前綴導(dǎo)致配置根本沒生效。 解決把 advertised.listeners 顯式寫成 PLAINTEXT://kafka:9092注意主機(jī)名必須和 compose 服務(wù)名一致。改完之后重啟 Kafka 容器然后進(jìn)入采集端容器里執(zhí)行 kafka-topics.sh --bootstrap-server kafka:9092 --list 驗(yàn)證。改完配置不重啟、只看 docker inspect 里的 Environment 字段是不會(huì)生效的。5.2 depends_on 直接寫服務(wù)名下游容器還是崩潰退出現(xiàn)象dbmotion-collector 容器啟動(dòng)后立即退出日志顯示連接 etcd 超時(shí)或 Kafka 未就緒但 Kafka 容器明明是 running。原因depends_on 只保證服務(wù)啟動(dòng)先后順序不保證服務(wù)內(nèi)部就緒。Kafka 容器進(jìn)程起來了但 broker 還在加載磁盤里的日志、注冊(cè) controller這個(gè)窗口可能持續(xù)幾十秒。采集端這個(gè)時(shí)候去連必然失敗。容器退出之后 compose 不會(huì)自動(dòng)拉起它所以整個(gè)環(huán)境就靜默地“半死”了。 解決depends_on 里加上 condition: service_healthy然后給 Kafka 和 etcd 都配上真正的 healthcheck。注意 Kafka 的 healthcheck 不要用 telnet 端口要用 kafka-topics.sh --list因?yàn)槎丝谕瞬淮?broker 完成注冊(cè)。這是一個(gè)很典型的“玄學(xué)問題”其實(shí)不是玄學(xué)是就緒語義沒搞清。5.3 etcd 容器啟動(dòng)失敗名叫“permission denied”現(xiàn)象docker compose up 時(shí) etcd 容器反復(fù)重啟日志里出現(xiàn) mkdir /etcd-data: permission denied。原因etcd 官方鏡像里的進(jìn)程默認(rèn)以非 root 用戶運(yùn)行而掛載進(jìn)來的 named volume 初始所有權(quán)是 root。容器用戶沒有寫權(quán)限etcd 建不了數(shù)據(jù)目錄。這個(gè)坑在大部分 Linux 發(fā)行版上都會(huì)踩macOS 上因?yàn)?Docker Desktop 的特殊權(quán)限模型可能不觸發(fā)反而增加了迷惑性。 解決最簡單的方式是在 compose 的 etcd 服務(wù)里加 user: 0:0 強(qiáng)制以 root 運(yùn)行或者用初始化容器預(yù)先 chown 數(shù)據(jù)目錄。生產(chǎn)環(huán)境建議用初始化容器本地評(píng)估可以直接加 user。改完記得 docker compose down -v 把舊的卷刪掉重建否則權(quán)限修復(fù)不會(huì)套用到已創(chuàng)建的卷上。5.4 整套環(huán)境跑著跑著某個(gè)容器被系統(tǒng)殺掉現(xiàn)象遷移任務(wù)跑到一半Kafka 或兩個(gè)數(shù)據(jù)庫容器突然消失docker compose ps 里看不到系統(tǒng)日志里出現(xiàn) oom-kill 記錄。原因宿主機(jī)內(nèi)存被占滿。Kafka 默認(rèn)的 JVM 堆內(nèi)存上限是 1G加上 ZooKeeper、etcd、兩個(gè)數(shù)據(jù)庫實(shí)例再算上 Docker 本身的開銷2G 內(nèi)存的機(jī)器根本扛不住。系統(tǒng) OOM killer 會(huì)優(yōu)先殺掉內(nèi)存占用最大的進(jìn)程Kafka 首當(dāng)其沖。 解決在 compose 里給每個(gè)服務(wù)加 mem_limitKafka 設(shè) 512mZooKeeper 設(shè) 256metcd 設(shè) 256m數(shù)據(jù)庫各自設(shè) 512m。同時(shí)給 Kafka 設(shè)置 KAFKA_HEAP_OPTS 為 -Xmx512m -Xms256m讓 JVM 在容器內(nèi)存限制之內(nèi)運(yùn)行。壓內(nèi)存之前先用 docker stats 看實(shí)時(shí)占用確定是誰在吃內(nèi)存。5.5 數(shù)據(jù)“丟了”重啟后源庫或目標(biāo)庫是空的現(xiàn)象整套環(huán)境重啟之后遷移任務(wù)的任務(wù)還在但目標(biāo)庫里的數(shù)據(jù)沒了有時(shí)候源庫的初始化數(shù)據(jù)也沒了。原因數(shù)據(jù)庫容器雖然掛了 volumes但掛的是匿名卷或沒掛卷。compose down 的時(shí)候如果沒加 -v匿名卷會(huì)保留但 docker compose down -v 會(huì)把匿名卷一起刪掉。更隱蔽的場景是鏡像自帶的數(shù)據(jù)目錄路徑和你在 volumes 里掛載的容器內(nèi)路徑不一致比如 MySQL 鏡像的數(shù)據(jù)目錄是 /var/lib/mysql你掛成了 /var/lib/mysql/data卷里存了文件但 MySQL 根本不認(rèn)識(shí)啟動(dòng)時(shí)生成一個(gè)空的數(shù)據(jù)目錄看起來就是“數(shù)據(jù)丟了”。 解決先確認(rèn)鏡像文檔里的數(shù)據(jù)目錄路徑。MySQL 官方鏡像是 /var/lib/mysqlPostgreSQL 是 /var/lib/postgresql/dataetcd 的路徑通過 --data-dir 參數(shù)自己指定。compose 里 volumes 的容器側(cè)路徑必須和實(shí)際數(shù)據(jù)目錄完全一致。養(yǎng)成一個(gè)好習(xí)慣改動(dòng)環(huán)境之前先 docker compose down不要直接 docker compose down -v-v 是刪除數(shù)據(jù)卷的操作沒有后悔藥。6. 讓這套容器集合更順手參數(shù)化模板與多環(huán)境復(fù)用容器集合能跑通只是第一步第二步是讓它能復(fù)用。我最常用的是 .env 配合 compose 變量替換。把端口、密碼、數(shù)據(jù)目錄這些環(huán)境相關(guān)的值抽到 .env 文件里compose 文件本身保持一份不動(dòng)。# .env 示例 SOURCE_DB_PORT3306 TARGET_DB_PORT3307 MYSQL_ROOT_PASSWORDsourcepass TARGET_MYSQL_ROOT_PASSWORDtargetpass KAFKA_PORT9092compose 文件里用 ${MYSQL_ROOT_PASSWORD} 引用這些變量。這樣同一份 compose 文件開發(fā)環(huán)境、測試環(huán)境、客戶現(xiàn)場只要改 .env 就能遷移不用動(dòng) YAML 本身。變量替換是 compose 原生的能力不需要額外工具。數(shù)據(jù)校驗(yàn)是另一個(gè)值得養(yǎng)成的習(xí)慣。全量遷移結(jié)束只對(duì)比行數(shù)遠(yuǎn)遠(yuǎn)不夠。行數(shù)一樣但內(nèi)容對(duì)不上比如字符集編碼問題、時(shí)區(qū)轉(zhuǎn)換問題、浮點(diǎn)數(shù)精度問題都會(huì)讓遷移“成功但錯(cuò)誤”。我一般用一個(gè)簡單的校驗(yàn)?zāi)_本把源表和目標(biāo)表按主鍵排序后做哈希對(duì)比docker exec source-db mysql -e SELECT CRC32(GROUP_CONCAT(col1, col2, col3 ORDER BY id)) FROM users; docker exec target-db mysql -e SELECT CRC32(GROUP_CONCAT(col1, col2, col3 ORDER BY id)) FROM users;兩邊的 CRC32 值一致說明這批數(shù)據(jù)內(nèi)容層面也對(duì)上了。不一致時(shí)把排序后的主鍵列表導(dǎo)出做 diff就能定位到具體哪一行差異。這個(gè)校驗(yàn)方法簡單直接不用引入額外的工具鏈。這套容器集合做到現(xiàn)在這個(gè)程度我最大的教訓(xùn)是不要因?yàn)樽非蟆碍h(huán)境小”而閹割依賴組件。最早我為了省內(nèi)存把 ZooKeeper 換成嵌入式模式把 etcd 塞進(jìn)采集端進(jìn)程里結(jié)果每次排查問題都要先懷疑自己改過的地方反而浪費(fèi)更多時(shí)間。按標(biāo)準(zhǔn)鏈路把容器集合完整拉起來雖然占資源多一點(diǎn)但每一步行為和線上行為一致驗(yàn)證出來的結(jié)論才作數(shù)。希望這篇筆記能幫你把環(huán)境搭建這一步真正省下來把精力留給遷移任務(wù)本身。本文還有配套的精品資源點(diǎn)擊獲取