简介面向需要快速搭建数据库迁移环境的开发与运维人员这套容器集合围绕 DBmotion 迁移服务整合了数据节点、监控告警、代理网关与可视化操作界面等依赖组件借助可执行的 docker-compose.yaml 即可一次性拉起整套服务显著降低环境准备与版本匹配成本。压缩包内共 11 个文件核心为 YAML 格式的编排配置文件其余 10 个均为 gz 压缩的镜像归档涵盖 MySQL 数据库、Prometheus 与 Grafana 监控体系、DBmotion 代理及 UI 等组件整体大小约 738MB。解压后无需逐个构建镜像直接参照编排文件修改端口、存储卷或连接参数便能在测试环境快速验证迁移流程也可作为生产部署前的模板。目前已有 48 人学习下载适合希望快速上手容器化数据库迁移工具、需要批量交付一致运行环境的技术人员。1. 这套容器集合解决的是数据库迁移里的“依赖沼泽”围绕 DBmotion 做数据库迁移最麻烦的往往不是迁移引擎本身而是它依赖的外部组件太多元数据库、调度组件、示例操作台、暂存数据源还有为不同数据库准备的连接器每样都得单独部署稍有疏漏任务跑到一半就断在“少起了一个容器”这种低级问题上。DBmotion 全量所需要容器集合想做的就是把整个迁移链路依赖的所有容器收拢在一个集合里配上一份可以直接执行的 docker-compose.yaml让“准备环境”这件事从半天缩到一条命令。这篇笔记我会把容器集合里每个成员的职责、编排文件的设计逻辑、可执行配置和启动验证步骤拆开讲再把我在私有化交付过程中踩过的几个坑写出来适合正在做跨数据库迁移、需要快速拉起一套可复现环境的团队对照复现。2. 容器集合里都有谁先弄清楚每个容器的职责再谈编排2.1 迁移引擎、元数据库、操作台、暂存库一个都不能少拿到“全量所需要容器集合”这个描述容易产生一个错觉所有东西塞进一个容器里跑不就行了。实际不行。DBmotion 的迁移引擎负责把源库的结构和数据搬到目标库但它自己需要一个地方记录迁移任务的状态、断点信息和调度配置这个任务落在元数据库头上操作台负责把迁移任务可视化日常查看进度、手动触发同步都会用到它某些复杂转换场景下数据要先落到一个暂存区做清洗这时候还需要一个轻量数据库实例来承担中转角色。我在实际使用中一般会把容器集合拆成四类迁移引擎本体、元数据库、操作台、暂存数据库。如果用更贴近 DBmotion 术语的说法元数据库承担了任务元信息和调度记录的持久化操作台则让不习惯命令行的人也能管理迁移任务。四类角色缺哪一个迁移链路都会有明面上的故障缺元数据库任务状态没法持久化重启后断点续传直接失效缺操作台纯命令行管理任务在多任务并行时非常痛苦缺暂存库依赖中转清洗的迁移流程只能另找外部实例一换环境配置就漂移。这个集合采用多容器而不是单容器还有一个实际考量迁移引擎升级迭代的频率远高于元数据库和操作台拆开以后升级其中一个服务不影响其他容器。用一句话概括容器集合的边界就是“DBmotion 跑一个完整迁移任务需要的最小服务集”少一个跑不通多一个没必要。2.2 为什么是 docker-compose依赖排序和网络共享是刚需搞清楚有哪几类容器之后接下来一个绕不开的问题是为什么选 docker-compose 而不是 shell 脚本逐个 docker run最直接的原因是容器之间存在启动顺序要求——迁移引擎必须在元数据库就绪之后启动如果拿 shell 脚本硬拼只能靠 sleep 撞运气跑十次可能挂三次。docker-compose 的 depends_on 配合 healthcheck 能做“服务健康后再启动下游”的编排这是脚本方案很难优雅实现的。第二个原因是网络。docker-compose 会自动创建一个自定义 bridge 网络容器之间通过服务名互相访问不需要关心 IP 地址变化。迁移引擎配置里填元数据库地址时直接写服务名就可以整套环境挪到另一台机器上IP 变了也不影响配置。这种网络特性还天然隔离了外部流量容器集合内部的服务端口不必全部暴露到宿主机只有操作台这种需要浏览器访问的服务才映射端口整体安全边界清晰很多。第三个原因是环境一致性。一份 compose 文件把镜像版本、环境变量、数据卷位置全部固化下来开发、测试、生产三套环境用同一份配置拉起减少“在我机器上是好的”这类问题。对于需要多次交付的团队compose 文件本身就是交付物的一部分配合 .env 文件调整不同环境的差异参数比维护一堆部署文档可靠得多。2.3 服务名和连接串的关系网络别名是这套方案的地基docker-compose 里有个隐藏规则新手经常忽略——服务名会成为容器在网络里的主机名。也就是说compose 文件里定义了一个叫 migration-engine 的服务那么在这个 compose 网络内的其他容器里migration-engine 这个域名就指向该容器的 IP。这是整个容器集合能协同工作的地基所有连接串配置都建立在服务名之上。实际配置时我会刻意把服务名设成简洁的小写单词比如 engine、metadata、console、stage-db。原因有两个一是容器网络 DNS 对大小写敏感大写服务名在某些镜像的内部配置解析里可能出问题二是连接串里写小写服务名更不容易出错。另一个需要留意的地方是通过 environment 注入连接串时连接串里的主机名部分应该写服务名而不是 localhost 或宿主机 IP。很多人第一次跑容器集合失败就是这个位置写错了。这里我整理了一张容器职责与依赖关系表方便你对照后续的编排文件理解每个服务的定位服务角色容器职责被谁依赖失败影响迁移引擎执行结构迁移、数据复制、增量同步操作台、调度触发迁移任务无法执行或中断元数据库持久化任务状态、断点、调度记录迁移引擎断点续传失效、状态丢失操作台可视化配置与监控迁移任务浏览器访问无法可视化管理和查看任务暂存数据库复杂转换场景的中转数据区迁移引擎特定迁移流程缺少中转实例3. 把容器集合写成可执行的 docker-compose.yaml3.1 最小可运行编排文件一份可以直接抄的配置有了上面的职责拆解现在落到最核心的部分一份能直接执行的 docker-compose.yaml。这份配置是我最常用的一套模板覆盖了四类服务、健康检查、数据卷持久化和端口映射结构上刻意保持了最小化方便你在此基础上按自己的镜像名和环境变量做替换。version: 3.8 networks: dbmotion_net: driver: bridge ipam: config: - subnet: 172.28.0.0/16 volumes: metadata_data: driver: local stage_data: driver: local services: metadata: image: metadata:2.0.0 container_name: dbmotion-metadata environment: TZ: Asia/Shanghai MYSQL_ROOT_PASSWORD: change-it-root MYSQL_DATABASE: dbmotion_meta volumes: - metadata_data:/var/lib/mysql networks: - dbmotion_net ports: - 127.0.0.1:3308:3306 healthcheck: test: [CMD, mysqladmin, ping, -h, 127.0.0.1, -uroot, -pchange-it-root] interval: 5s timeout: 3s retries: 12 stage-db: image: stage-db:1.4.0 container_name: dbmotion-stage environment: TZ: Asia/Shanghai POSTGRES_PASSWORD: change-it-stage POSTGRES_DB: stage_tmp volumes: - stage_data:/var/lib/postgresql/data networks: - dbmotion_net ports: - 127.0.0.1:5433:5432 healthcheck: test: [CMD-SHELL, pg_isready -U postgres -p 5432] interval: 5s timeout: 3s retries: 12 engine: image: dbmotion-engine:3.1.0 container_name: dbmotion-engine depends_on: metadata: condition: service_healthy stage-db: condition: service_healthy environment: TZ: Asia/Shanghai DB_MOTION_META_HOST: metadata DB_MOTION_META_PORT: 3306 DB_MOTION_META_USER: root DB_MOTION_META_PASSWORD: change-it-root DB_MOTION_META_DATABASE: dbmotion_meta DB_MOTION_STAGE_HOST: stage-db DB_MOTION_STAGE_PORT: 5432 DB_MOTION_STAGE_USER: postgres DB_MOTION_STAGE_PASSWORD: change-it-stage DB_MOTION_STAGE_DATABASE: stage_tmp JVM_HEAP_MAX: 2048m networks: - dbmotion_net restart: unless-stopped console: image: dbmotion-console:2.2.0 container_name: dbmotion-console depends_on: - engine environment: TZ: Asia/Shanghai CONSOLE_ENGINE_HOST: engine networks: - dbmotion_net ports: - 8080:8080这份文件把四个服务之间的依赖关系、连接方式和持久化逻辑都表达清楚了。迁移引擎通过环境变量拿到元数据库和暂存库的连接参数连接串里填的都是服务名而不是 IP这正是 compose 网络别名机制发挥作用的地方。3.2 healthcheck 的定义方式启动顺序不再靠猜上面的配置里metadata 和 stage-db 都定义了 healthcheckengine 的 depends_on 用的是 condition: service_healthy 这种带条件的写法。两者的配合逻辑是当 metadata 的 mysqladmin ping 返回成功、stage-db 的 pg_isready 返回成功compose 才会启动 engine 容器。这比简单 depends_on 的“先启动”语义要强得多因为在单机环境下容器启动成功不等于数据库初始化完成MySQL 首次建库可能要十几秒甚至更久。healthcheck 的 interval 参数表示检查间隔我习惯设为 5 秒timeout 是单次检查的超时时间3 秒够用retries 是连续失败多少次后判定容器不健康12 次意味着最多给数据库约 60 秒的初始化窗口。如果机器性能较差可以把 retries 调大到 20但很少需要超过这个值。另外要注意 healthcheck 里的密码是明文出现在 compose 文件里的所以我在端口映射里把元数据库端口绑到了 127.0.0.1避免直接暴露到外部网络。延时布局的另一个用途是排错。当 engine 启动异常时看它的容器状态是 Restarting然后通过 docker compose logs engine 看具体日志如果是连接不上元数据库日志里会显示连接被拒这时候先检查 metadata 容器的健康状态docker inspect 能看到 Health 字段比在应用日志里瞎猜高效得多。3.3 数据卷和端口映射的设计取舍数据卷部分metadata 和 stage-db 分别挂了独立 volume。这个设计的直接收益是容器删除以后数据还在迁移任务执行到一半需要升级镜像重新创建容器任务状态不会丢。这对 DBmotion 这类迁移工具来说非常重要因为断点续传依赖元数据库里的持久化记录如果 metadata 容器一删数据就没了重新跑全量迁移的成本完全不可接受。端口映射部分我提三个值得留意的点。一是元数据库端口映射成 3308 而不是 3306因为宿主机可能已有 MySQL 实例3306 是冲突高发区二是暂存库映射成 5433同理避开 PostgreSQL 默认端口三是 console 映射成 8080如果你的环境里有其他 Web 应用改成 8081 或 9090 都可以。所有映射都遵循“避免默认端口、显式绑定回环地址”的原则既防止冲突又不会把内部服务暴露到公网。这个环节还要提一句资源限制的预留位置。在 engine 服务下我给 JVM 堆设了 2048m 的上限这是通过环境变量传入的如果宿主机内存只有 8GB你还需要给容器本身加 mem_limit 和 cpus 限制方式是在 engine 服务下加deploy: resources: limits: memory: 4g cpus: 2.0不过 deploy 下的资源限制在 docker compose非 swarm 模式里并不生效单机时要在该服务下直接写 mem_limit 和 cpus 字段这是很多人配置了但没效果的原因。3.4 启动命令与验证步骤从 config 到 logs 的一整套检查编排文件准备好之后启动流程不建议直接 docker compose up -d 一把梭。我一般按下面这个顺序执行# 1. 先做语法和变量校验 docker compose config --quiet # 2. 拉取镜像并以后台方式启动 docker compose up -d # 3. 查看所有容器的状态 docker compose ps # 4. 连续观察 engine 的启动日志确认没有连接错误 docker compose logs -f engine # 5. 验证元数据库确实接受外部连接 docker run --rm --network dbmotion_net mysql:8.0 \ mysql -h metadata -P 3306 -uroot -pchange-it-root -e select 1 from dualdocker compose config --quiet 这一步非常值得养成习惯。它会校验 YAML 语法、变量引用和字段合法性如果配置文件里存在缩进错误、引号不匹配或服务名重复这里会直接报错省得 up 起来之后才暴露问题。第 5 步我单独解释一下这条命令临时起一个 mysql 客户端容器加入 compose 网络然后通过服务名 metadata 连接元数据库。它能验证两件事一是网络别名解析正常二是元数据库初始化完成且账号密码正确。执行成功后再去操作台配置迁移任务就是从干净环境开始的完整链路了。如果第 5 步报错优先检查 metadata 容器的健康状态用 docker inspect dbmotion-metadata 查看 State.Health.Status 字段然后看日志里有没有初始化错误。通常出现在这里的问题是容器启动完成后 MySQL 还在做数据目录初始化retries 不够导致引擎提前启动把 retries 调大就能解决。4. 容器集合编排的避坑记录五个高频故障的真实处理过程4.1 服务名大小写惹的祸现象compose 文件里把服务名写成 Metadata引擎启动后日志一直报拒绝连接元数据库但用 docker exec 进容器里手动 ping 这个域名偶尔又能通。原因容器网络里的 DNS 解析对大小写敏感某些镜像内部初始化流程会把服务名转成小写再去解析两边不一致就产生“时通时不通”的假象。解决把所有服务名统一改成小写engine、metadata、stage-db、console容器连接串里的主机名也跟着改小写。这个问题藏得比较深因为它不在启动时立即报错而是在引擎真正建立连接时才会暴露。4.2 元数据库初始化未完成导致引擎反复重启现象docker compose ps 里 engine 的状态一直是 Restarting进入容器看进程起不来。原因引擎连接元数据库失败后直接退出compose 的 restart: unless-stopped 策略又把容器拉起来形成重启循环。根因是 depends_on 只保证了元数据库容器先启动没保证数据库初始化完成——MySQL 建库建表需要时间引擎却在启动后立刻尝试连接。解决在元数据库服务里加 healthcheckengine 的 depends_on 改成 condition: service_healthy。这样 compose 会等元数据库真正可连接后再启动引擎重启循环直接消失。这套配合是最值得先做好的它避免了 90% 以上的启动顺序问题。4.3 JVM 内存参数与容器限制冲突现象引擎跑大表迁移时容器直接被系统杀掉docker compose ps 看到的状态是 Exited日志尾部没有任何异常堆栈。原因镜像默认 JVM 堆设置可能达到 4GB而我只给容器设了 2GB 内存限制JVM 分配内存超出 cgroup 限制被内核 OOM容器被杀时应用层来不及记录错误日志看起来像毫无征兆地消失。解决在引擎的 environment 里显式设置 JVM_HEAP_MAX 为容器内存限制的一半左右同时用 docker stats 观察实际内存占用。给容器设内存上限时堆设置一定要小于容器内存上限至少留出四分之一给元数据和堆外内存。4.4 默认端口撞车3306 和 5432 是重灾区现象docker compose up 报端口绑定失败提示 address already in use。原因宿主机上已经跑了 MySQL 或 PostgreSQLcompose 里元数据库映射 3306、暂存库映射 5432直接被占用。解决映射端口改成非常用端口我的习惯是 3308、5433 这类偏移并且绑定到 127.0.0.1。另外建议在 .env 文件里统一管理端口变量例如 MYSQL_PORT3308、PG_PORT5433迁移环境时只需要改一份文件。4.5 时区不一致导致时间字段错乱现象迁移到目标库的数据时间字段比源库早 8 小时但数据库服务器时区配置都正确。原因容器默认使用 UTC 时区迁移引擎在转换时间类型时按 UTC 处理写入目标库后与源库的本地时间产生偏移。解决在 compose 文件里所有服务统一设置 TZ: Asia/Shanghai 环境变量同时把源库和目标库的连接参数里显式加上时区设置。用 JDBC 连接串时URL 里加 serverTimezoneAsia/Shanghai 避免依赖容器系统的隐式时区推断。5. 从“能启动”到“能交付”验证整套容器集合可用的实战技巧当你把 docker compose up -d 执行成功容器集合“能启起来”但这不等于“能交付”。我经历过一次很典型的翻车所有容器状态都是 running到了客户现场测试迁移任务时却发现引擎日志里全是连接超时排错花了整整一个下午。从那以后我养成了一套固定的验证习惯——在客户现场收环境前先跑一轮容器集合的连通性演练确保交付状态是“环境可用”而不是“容器活着”。这套验证的核心思路是每个容器的健康状态都不等于链路的可用状态必须从连接方的视角主动探测。我的执行顺序是三步走先验证元数据库的读写能力再验证引擎能注册任务并写入状态最后跑一条最小数据量的全量迁移确认整个链路真的通。其中最小迁移验证我会用源库一张几百行的表目标库指向暂存库跑完后在目标库执行 count 对比这样既能验证引擎的核心转发逻辑又能观察时间字段、字符集这类容易出问题的转换点。在 docker-compose.yaml 层面我最后会把以下三个技巧一并检查掉。一是把 .env 文件和 compose 文件拆开连接账号、端口、密码等环境差异参数不进 compose避免交付时泄露内部配置二是给所有需要持久化的服务确认 volume 挂载路径与镜像内数据目录一致这个不对容器删除后数据照样丢三是在引擎服务上关掉 restart: always换成 restart: unless-stopped避免引擎因为代码缺陷在交付现场无限重启把问题掩盖成“环境不稳定”。还有一个小习惯交付前会在 compose 文件里临时把 console 的端口映射从 8080 改成 18080启动成功后确认能访问再把映射改回标准端口。这个动作不是多此一举它能验证端口映射配置不是“碰巧能用”而是真正经过了生效检查。整套容器集合我最后只会相信一条准则——不是进程存活而是链路留痕。希望帮到你。本文还有配套的精品资源点击获取
简介面向需要快速搭建数据库迁移环境的开发与运维人员这套容器集合围绕 DBmotion 迁移服务整合了数据节点、监控告警、代理网关与可视化操作界面等依赖组件借助可执行的 docker-compose.yaml 即可一次性拉起整套服务显著降低环境准备与版本匹配成本。压缩包内共 11 个文件核心为 YAML 格式的编排配置文件其余 10 个均为 gz 压缩的镜像归档涵盖 MySQL 数据库、Prometheus 与 Grafana 监控体系、DBmotion 代理及 UI 等组件整体大小约 738MB。解压后无需逐个构建镜像直接参照编排文件修改端口、存储卷或连接参数便能在测试环境快速验证迁移流程也可作为生产部署前的模板。目前已有 48 人学习下载适合希望快速上手容器化数据库迁移工具、需要批量交付一致运行环境的技术人员。1. 这套容器集合解决的是数据库迁移里的“依赖沼泽”围绕 DBmotion 做数据库迁移最麻烦的往往不是迁移引擎本身而是它依赖的外部组件太多元数据库、调度组件、示例操作台、暂存数据源还有为不同数据库准备的连接器每样都得单独部署稍有疏漏任务跑到一半就断在“少起了一个容器”这种低级问题上。DBmotion 全量所需要容器集合想做的就是把整个迁移链路依赖的所有容器收拢在一个集合里配上一份可以直接执行的 docker-compose.yaml让“准备环境”这件事从半天缩到一条命令。这篇笔记我会把容器集合里每个成员的职责、编排文件的设计逻辑、可执行配置和启动验证步骤拆开讲再把我在私有化交付过程中踩过的几个坑写出来适合正在做跨数据库迁移、需要快速拉起一套可复现环境的团队对照复现。2. 容器集合里都有谁先弄清楚每个容器的职责再谈编排2.1 迁移引擎、元数据库、操作台、暂存库一个都不能少拿到“全量所需要容器集合”这个描述容易产生一个错觉所有东西塞进一个容器里跑不就行了。实际不行。DBmotion 的迁移引擎负责把源库的结构和数据搬到目标库但它自己需要一个地方记录迁移任务的状态、断点信息和调度配置这个任务落在元数据库头上操作台负责把迁移任务可视化日常查看进度、手动触发同步都会用到它某些复杂转换场景下数据要先落到一个暂存区做清洗这时候还需要一个轻量数据库实例来承担中转角色。我在实际使用中一般会把容器集合拆成四类迁移引擎本体、元数据库、操作台、暂存数据库。如果用更贴近 DBmotion 术语的说法元数据库承担了任务元信息和调度记录的持久化操作台则让不习惯命令行的人也能管理迁移任务。四类角色缺哪一个迁移链路都会有明面上的故障缺元数据库任务状态没法持久化重启后断点续传直接失效缺操作台纯命令行管理任务在多任务并行时非常痛苦缺暂存库依赖中转清洗的迁移流程只能另找外部实例一换环境配置就漂移。这个集合采用多容器而不是单容器还有一个实际考量迁移引擎升级迭代的频率远高于元数据库和操作台拆开以后升级其中一个服务不影响其他容器。用一句话概括容器集合的边界就是“DBmotion 跑一个完整迁移任务需要的最小服务集”少一个跑不通多一个没必要。2.2 为什么是 docker-compose依赖排序和网络共享是刚需搞清楚有哪几类容器之后接下来一个绕不开的问题是为什么选 docker-compose 而不是 shell 脚本逐个 docker run最直接的原因是容器之间存在启动顺序要求——迁移引擎必须在元数据库就绪之后启动如果拿 shell 脚本硬拼只能靠 sleep 撞运气跑十次可能挂三次。docker-compose 的 depends_on 配合 healthcheck 能做“服务健康后再启动下游”的编排这是脚本方案很难优雅实现的。第二个原因是网络。docker-compose 会自动创建一个自定义 bridge 网络容器之间通过服务名互相访问不需要关心 IP 地址变化。迁移引擎配置里填元数据库地址时直接写服务名就可以整套环境挪到另一台机器上IP 变了也不影响配置。这种网络特性还天然隔离了外部流量容器集合内部的服务端口不必全部暴露到宿主机只有操作台这种需要浏览器访问的服务才映射端口整体安全边界清晰很多。第三个原因是环境一致性。一份 compose 文件把镜像版本、环境变量、数据卷位置全部固化下来开发、测试、生产三套环境用同一份配置拉起减少“在我机器上是好的”这类问题。对于需要多次交付的团队compose 文件本身就是交付物的一部分配合 .env 文件调整不同环境的差异参数比维护一堆部署文档可靠得多。2.3 服务名和连接串的关系网络别名是这套方案的地基docker-compose 里有个隐藏规则新手经常忽略——服务名会成为容器在网络里的主机名。也就是说compose 文件里定义了一个叫 migration-engine 的服务那么在这个 compose 网络内的其他容器里migration-engine 这个域名就指向该容器的 IP。这是整个容器集合能协同工作的地基所有连接串配置都建立在服务名之上。实际配置时我会刻意把服务名设成简洁的小写单词比如 engine、metadata、console、stage-db。原因有两个一是容器网络 DNS 对大小写敏感大写服务名在某些镜像的内部配置解析里可能出问题二是连接串里写小写服务名更不容易出错。另一个需要留意的地方是通过 environment 注入连接串时连接串里的主机名部分应该写服务名而不是 localhost 或宿主机 IP。很多人第一次跑容器集合失败就是这个位置写错了。这里我整理了一张容器职责与依赖关系表方便你对照后续的编排文件理解每个服务的定位服务角色容器职责被谁依赖失败影响迁移引擎执行结构迁移、数据复制、增量同步操作台、调度触发迁移任务无法执行或中断元数据库持久化任务状态、断点、调度记录迁移引擎断点续传失效、状态丢失操作台可视化配置与监控迁移任务浏览器访问无法可视化管理和查看任务暂存数据库复杂转换场景的中转数据区迁移引擎特定迁移流程缺少中转实例3. 把容器集合写成可执行的 docker-compose.yaml3.1 最小可运行编排文件一份可以直接抄的配置有了上面的职责拆解现在落到最核心的部分一份能直接执行的 docker-compose.yaml。这份配置是我最常用的一套模板覆盖了四类服务、健康检查、数据卷持久化和端口映射结构上刻意保持了最小化方便你在此基础上按自己的镜像名和环境变量做替换。version: 3.8 networks: dbmotion_net: driver: bridge ipam: config: - subnet: 172.28.0.0/16 volumes: metadata_data: driver: local stage_data: driver: local services: metadata: image: metadata:2.0.0 container_name: dbmotion-metadata environment: TZ: Asia/Shanghai MYSQL_ROOT_PASSWORD: change-it-root MYSQL_DATABASE: dbmotion_meta volumes: - metadata_data:/var/lib/mysql networks: - dbmotion_net ports: - 127.0.0.1:3308:3306 healthcheck: test: [CMD, mysqladmin, ping, -h, 127.0.0.1, -uroot, -pchange-it-root] interval: 5s timeout: 3s retries: 12 stage-db: image: stage-db:1.4.0 container_name: dbmotion-stage environment: TZ: Asia/Shanghai POSTGRES_PASSWORD: change-it-stage POSTGRES_DB: stage_tmp volumes: - stage_data:/var/lib/postgresql/data networks: - dbmotion_net ports: - 127.0.0.1:5433:5432 healthcheck: test: [CMD-SHELL, pg_isready -U postgres -p 5432] interval: 5s timeout: 3s retries: 12 engine: image: dbmotion-engine:3.1.0 container_name: dbmotion-engine depends_on: metadata: condition: service_healthy stage-db: condition: service_healthy environment: TZ: Asia/Shanghai DB_MOTION_META_HOST: metadata DB_MOTION_META_PORT: 3306 DB_MOTION_META_USER: root DB_MOTION_META_PASSWORD: change-it-root DB_MOTION_META_DATABASE: dbmotion_meta DB_MOTION_STAGE_HOST: stage-db DB_MOTION_STAGE_PORT: 5432 DB_MOTION_STAGE_USER: postgres DB_MOTION_STAGE_PASSWORD: change-it-stage DB_MOTION_STAGE_DATABASE: stage_tmp JVM_HEAP_MAX: 2048m networks: - dbmotion_net restart: unless-stopped console: image: dbmotion-console:2.2.0 container_name: dbmotion-console depends_on: - engine environment: TZ: Asia/Shanghai CONSOLE_ENGINE_HOST: engine networks: - dbmotion_net ports: - 8080:8080这份文件把四个服务之间的依赖关系、连接方式和持久化逻辑都表达清楚了。迁移引擎通过环境变量拿到元数据库和暂存库的连接参数连接串里填的都是服务名而不是 IP这正是 compose 网络别名机制发挥作用的地方。3.2 healthcheck 的定义方式启动顺序不再靠猜上面的配置里metadata 和 stage-db 都定义了 healthcheckengine 的 depends_on 用的是 condition: service_healthy 这种带条件的写法。两者的配合逻辑是当 metadata 的 mysqladmin ping 返回成功、stage-db 的 pg_isready 返回成功compose 才会启动 engine 容器。这比简单 depends_on 的“先启动”语义要强得多因为在单机环境下容器启动成功不等于数据库初始化完成MySQL 首次建库可能要十几秒甚至更久。healthcheck 的 interval 参数表示检查间隔我习惯设为 5 秒timeout 是单次检查的超时时间3 秒够用retries 是连续失败多少次后判定容器不健康12 次意味着最多给数据库约 60 秒的初始化窗口。如果机器性能较差可以把 retries 调大到 20但很少需要超过这个值。另外要注意 healthcheck 里的密码是明文出现在 compose 文件里的所以我在端口映射里把元数据库端口绑到了 127.0.0.1避免直接暴露到外部网络。延时布局的另一个用途是排错。当 engine 启动异常时看它的容器状态是 Restarting然后通过 docker compose logs engine 看具体日志如果是连接不上元数据库日志里会显示连接被拒这时候先检查 metadata 容器的健康状态docker inspect 能看到 Health 字段比在应用日志里瞎猜高效得多。3.3 数据卷和端口映射的设计取舍数据卷部分metadata 和 stage-db 分别挂了独立 volume。这个设计的直接收益是容器删除以后数据还在迁移任务执行到一半需要升级镜像重新创建容器任务状态不会丢。这对 DBmotion 这类迁移工具来说非常重要因为断点续传依赖元数据库里的持久化记录如果 metadata 容器一删数据就没了重新跑全量迁移的成本完全不可接受。端口映射部分我提三个值得留意的点。一是元数据库端口映射成 3308 而不是 3306因为宿主机可能已有 MySQL 实例3306 是冲突高发区二是暂存库映射成 5433同理避开 PostgreSQL 默认端口三是 console 映射成 8080如果你的环境里有其他 Web 应用改成 8081 或 9090 都可以。所有映射都遵循“避免默认端口、显式绑定回环地址”的原则既防止冲突又不会把内部服务暴露到公网。这个环节还要提一句资源限制的预留位置。在 engine 服务下我给 JVM 堆设了 2048m 的上限这是通过环境变量传入的如果宿主机内存只有 8GB你还需要给容器本身加 mem_limit 和 cpus 限制方式是在 engine 服务下加deploy: resources: limits: memory: 4g cpus: 2.0不过 deploy 下的资源限制在 docker compose非 swarm 模式里并不生效单机时要在该服务下直接写 mem_limit 和 cpus 字段这是很多人配置了但没效果的原因。3.4 启动命令与验证步骤从 config 到 logs 的一整套检查编排文件准备好之后启动流程不建议直接 docker compose up -d 一把梭。我一般按下面这个顺序执行# 1. 先做语法和变量校验 docker compose config --quiet # 2. 拉取镜像并以后台方式启动 docker compose up -d # 3. 查看所有容器的状态 docker compose ps # 4. 连续观察 engine 的启动日志确认没有连接错误 docker compose logs -f engine # 5. 验证元数据库确实接受外部连接 docker run --rm --network dbmotion_net mysql:8.0 \ mysql -h metadata -P 3306 -uroot -pchange-it-root -e select 1 from dualdocker compose config --quiet 这一步非常值得养成习惯。它会校验 YAML 语法、变量引用和字段合法性如果配置文件里存在缩进错误、引号不匹配或服务名重复这里会直接报错省得 up 起来之后才暴露问题。第 5 步我单独解释一下这条命令临时起一个 mysql 客户端容器加入 compose 网络然后通过服务名 metadata 连接元数据库。它能验证两件事一是网络别名解析正常二是元数据库初始化完成且账号密码正确。执行成功后再去操作台配置迁移任务就是从干净环境开始的完整链路了。如果第 5 步报错优先检查 metadata 容器的健康状态用 docker inspect dbmotion-metadata 查看 State.Health.Status 字段然后看日志里有没有初始化错误。通常出现在这里的问题是容器启动完成后 MySQL 还在做数据目录初始化retries 不够导致引擎提前启动把 retries 调大就能解决。4. 容器集合编排的避坑记录五个高频故障的真实处理过程4.1 服务名大小写惹的祸现象compose 文件里把服务名写成 Metadata引擎启动后日志一直报拒绝连接元数据库但用 docker exec 进容器里手动 ping 这个域名偶尔又能通。原因容器网络里的 DNS 解析对大小写敏感某些镜像内部初始化流程会把服务名转成小写再去解析两边不一致就产生“时通时不通”的假象。解决把所有服务名统一改成小写engine、metadata、stage-db、console容器连接串里的主机名也跟着改小写。这个问题藏得比较深因为它不在启动时立即报错而是在引擎真正建立连接时才会暴露。4.2 元数据库初始化未完成导致引擎反复重启现象docker compose ps 里 engine 的状态一直是 Restarting进入容器看进程起不来。原因引擎连接元数据库失败后直接退出compose 的 restart: unless-stopped 策略又把容器拉起来形成重启循环。根因是 depends_on 只保证了元数据库容器先启动没保证数据库初始化完成——MySQL 建库建表需要时间引擎却在启动后立刻尝试连接。解决在元数据库服务里加 healthcheckengine 的 depends_on 改成 condition: service_healthy。这样 compose 会等元数据库真正可连接后再启动引擎重启循环直接消失。这套配合是最值得先做好的它避免了 90% 以上的启动顺序问题。4.3 JVM 内存参数与容器限制冲突现象引擎跑大表迁移时容器直接被系统杀掉docker compose ps 看到的状态是 Exited日志尾部没有任何异常堆栈。原因镜像默认 JVM 堆设置可能达到 4GB而我只给容器设了 2GB 内存限制JVM 分配内存超出 cgroup 限制被内核 OOM容器被杀时应用层来不及记录错误日志看起来像毫无征兆地消失。解决在引擎的 environment 里显式设置 JVM_HEAP_MAX 为容器内存限制的一半左右同时用 docker stats 观察实际内存占用。给容器设内存上限时堆设置一定要小于容器内存上限至少留出四分之一给元数据和堆外内存。4.4 默认端口撞车3306 和 5432 是重灾区现象docker compose up 报端口绑定失败提示 address already in use。原因宿主机上已经跑了 MySQL 或 PostgreSQLcompose 里元数据库映射 3306、暂存库映射 5432直接被占用。解决映射端口改成非常用端口我的习惯是 3308、5433 这类偏移并且绑定到 127.0.0.1。另外建议在 .env 文件里统一管理端口变量例如 MYSQL_PORT3308、PG_PORT5433迁移环境时只需要改一份文件。4.5 时区不一致导致时间字段错乱现象迁移到目标库的数据时间字段比源库早 8 小时但数据库服务器时区配置都正确。原因容器默认使用 UTC 时区迁移引擎在转换时间类型时按 UTC 处理写入目标库后与源库的本地时间产生偏移。解决在 compose 文件里所有服务统一设置 TZ: Asia/Shanghai 环境变量同时把源库和目标库的连接参数里显式加上时区设置。用 JDBC 连接串时URL 里加 serverTimezoneAsia/Shanghai 避免依赖容器系统的隐式时区推断。5. 从“能启动”到“能交付”验证整套容器集合可用的实战技巧当你把 docker compose up -d 执行成功容器集合“能启起来”但这不等于“能交付”。我经历过一次很典型的翻车所有容器状态都是 running到了客户现场测试迁移任务时却发现引擎日志里全是连接超时排错花了整整一个下午。从那以后我养成了一套固定的验证习惯——在客户现场收环境前先跑一轮容器集合的连通性演练确保交付状态是“环境可用”而不是“容器活着”。这套验证的核心思路是每个容器的健康状态都不等于链路的可用状态必须从连接方的视角主动探测。我的执行顺序是三步走先验证元数据库的读写能力再验证引擎能注册任务并写入状态最后跑一条最小数据量的全量迁移确认整个链路真的通。其中最小迁移验证我会用源库一张几百行的表目标库指向暂存库跑完后在目标库执行 count 对比这样既能验证引擎的核心转发逻辑又能观察时间字段、字符集这类容易出问题的转换点。在 docker-compose.yaml 层面我最后会把以下三个技巧一并检查掉。一是把 .env 文件和 compose 文件拆开连接账号、端口、密码等环境差异参数不进 compose避免交付时泄露内部配置二是给所有需要持久化的服务确认 volume 挂载路径与镜像内数据目录一致这个不对容器删除后数据照样丢三是在引擎服务上关掉 restart: always换成 restart: unless-stopped避免引擎因为代码缺陷在交付现场无限重启把问题掩盖成“环境不稳定”。还有一个小习惯交付前会在 compose 文件里临时把 console 的端口映射从 8080 改成 18080启动成功后确认能访问再把映射改回标准端口。这个动作不是多此一举它能验证端口映射配置不是“碰巧能用”而是真正经过了生效检查。整套容器集合我最后只会相信一条准则——不是进程存活而是链路留痕。希望帮到你。本文还有配套的精品资源点击获取
