dbswitch数据库迁移与Docker容器化部署实战

数据库迁移这件事难的从来不是“把数据搬过去”这个动作而是搬完之后结构对不对、数据准不准、出了问题能不能三分钟内定位到是哪张表哪一列。dbswitch 这个工具我用了不短时间最早它还是个只支持少数几种库互转的小工具现在结构迁移、结构比对、全量数据搬运、增量同步这几件事都能在一个 Web 界面里点完省掉了大量手写 DDL 和导数据的体力活。而用 Docker 部署它解决的则是另一类痛点JDK 版本打架、驱动包冲突、换台机器就得重装一遍环境——这些琐事在迁移窗口期是致命的。这篇内容面向三类人一是手上有异构库互转需求、想快速把工具跑起来的开发二是需要在测试环境反复搭环境练手的运维三是对容器化部署还不太熟、想借一个真实工具练手的入门读者。下面我按“想清楚为什么—准备环境—动手部署—跑通一次迁移—踩坑排查”的顺序把能直接抄作业的部分和我自己踩过的坑都摆出来。1. 部署前先把思路捋顺为什么这套组合值得选1.1 dbswitch 在实际项目里到底承担哪几件事很多人第一次接触这个工具会把它当成“导数据的脚本”这个理解偏窄。它在实际项目里承担的是四件互相咬合的事。第一件是表结构迁移把源库的表、字段、主键、索引、外键、注释按目标库的方言重新生成一遍中间要做数据类型映射比如源端是无符号整型、目标端没有这个概念就得降级或放大到更大的类型上。第二件是结构比对已经迁过的库和生产库之间往往会漂移比对功能会把差异列出来甚至直接生成补齐用的 DDL。第三件是全量数据迁移按表批量读取、批量写入中间涉及批次大小、并发度、失败重试。第四件是增量同步基于时间戳字段或者自增主键做增量拉取适合迁移窗口内还在持续写入的业务库。这四件事如果全靠人工一张三十个字段的表就要写半小时 DDL还得反复对着两边的文档核对类型几百张表的库基本等于不可能在有限窗口内完成。工具的价值就在这里把重复劳动模板化把容易出错的类型映射固化成规则表。理解了这一点你才知道部署完之后该重点验证哪些能力而不是把界面点开看一眼就完事。需要明确一点这类工具擅长的是结构 数据的搬运它不做业务逻辑层面的数据清洗。如果你的源库里有大量需要脱敏、需要按业务规则重算的字段那该写 ETL 脚本还是得写工具只负责把“搬运”这一段做扎实。1.2 容器化部署相比裸装运行时的真实收益裸装的做法通常是装 JDK 8、配环境变量、把 jar 包丢上去、写个启动脚本、用 nohup 挂后台。这套流程在单机上没什么问题一旦要在三套环境开发、测试、生产各来一遍麻烦就来了。最常见的三种翻车宿主机上已经有别的服务占着 JDK 11你装 JDK 8 会互相干扰不同数据库的 JDBC 驱动版本不一样装到一个 classpath 里可能出冲突换了台机器忘了配时区日志时间和数据库时间差八小时增量同步直接漏数据。容器化把这几个问题一次性隔开了。运行时隔离是最直接的收益镜像里自带固定版本的 JRE跟宿主机上装了什么完全无关。配置外挂是第二个收益把配置文件、日志目录、临时数据目录挂到宿主机镜像本身保持无状态换机器只需要拷目录。回滚成本低是第三个收益新版本跑出问题把镜像 tag 切回去重启十秒钟的事情比重新装一遍 JDK 靠谱得多。但容器化不是没有代价。最典型的是网络链路变长容器里写localhost:3306是访问不到宿主机上的数据库的新手有相当一部分时间耗在这个问题上。其次是资源限制容器默认能吃满宿主机内存不加限制的话迁移大批量表时可能把宿主机拖垮。这两点在后面的章节里都会具体处理。1.3 哪些场景其实不适合用容器跑不是所有情况都推荐容器。有三种情况我建议直接裸装一是迁移窗口极短且数据量极大需要对宿主机内核参数、磁盘 IO 做非常细粒度的调优容器多一层抽象反而碍事二是完全隔离的内网环境连基础镜像都拉不下来构建镜像的成本高于直接装 JDK三是需要直接读取宿主机本地文件做批量导入比如从挂载的 NFS 或者本地磁盘直接喂数据文件容器的挂载路径和权限配置会引入额外复杂度。除此之外的常规场景——测试环境反复搭、多套环境要保持一致、需要快速切换版本验证——容器化的收益都是明显的。判断标准很简单这个环境会不会被反复重建会就用容器一辈子只装一次的生产机裸装也没问题。2. 环境盘点与关键决策这几项没定好后面全是坑2.1 宿主机资源下限与内核参数先说硬指标。JVM 堆建议给到 2G容器内存限制设 3G宿主机物理内存至少留 4G 给这个服务另外还要给数据库客户端连接、日志缓冲留余量。为什么堆要 2G因为数据迁移阶段工具会把一批数据读进内存再批量写入批次大小设成 5000 行、单行平均 1KB 的话一批就是 5MB加上结果集元数据、连接池、Spring 上下文1G 堆在中等表上很容易触发 Full GC表现出来就是迁移速度忽快忽慢日志里频繁出现 GC 字样。磁盘方面日志目录要留够空间。迁移任务跑起来后日志增长很快尤其是开了调试级别的情况下一天几个 G 不夸张。建议单独挂一个数据盘给日志和临时文件别跟系统盘混在一起。内核参数里最容易被忽略的是文件句柄数。迁移任务并发高的时候每个数据库连接、每个日志文件、每个 socket 都占一个句柄默认的 1024 很容易打满报错是Too many open files看起来像程序 bug实际是系统限制。容器里要通过ulimits显式放开这个在后面的编排文件里会写。还有一个隐性但很关键的点时间同步。增量同步依赖时间戳字段判断哪些是新数据如果应用服务器、源库、目标库三边时间不一致就会出现数据漏同步或者重复同步。部署前用date命令对着三台机器比一遍差超过几秒就先解决时间同步问题别急着跑任务。2.2 网络模式与端口规划怎么定端口这块比较简单Web 界面默认监听一个 HTTP 端口具体数值以你拿到的发布包里的配置为准常见是 8080 这一类。规划的时候注意两点一是别跟宿主机上已有服务撞端口部署前ss -lntp看一眼二是如果前面要挂反向代理记得把上传大小限制放开因为有些功能涉及文件上传。网络模式才是重点。默认的 bridge 模式下容器有自己独立的网络命名空间容器内的127.0.0.1指向容器自己不是宿主机。这带来一个非常高频的问题数据库装在宿主机上配置连接地址时习惯性写了localhost测试连接必然失败。解决办法有三个按推荐程度排第一种是把连接地址改成宿主机的真实内网 IP简单直接缺点是宿主机 IP 变了要改配置第二种是在 Linux 下用network_mode: host容器直接共享宿主机网络栈localhost就能通了代价是端口不再做映射、可能跟宿主机服务撞端口第三种是自建一个 docker 网络把数据库容器和工具容器放同一个网络里用服务名互访这是最干净的方案前提是你的数据库也是容器化的。我一般推荐第一种因为迁移作业往往是临时的改 IP 的成本最低也不用动网络模式引入新的不确定性。2.3 时区、字符集、JVM 参数三件事必须先定死这三项如果在启动时没定好后面排查起来会非常痛苦因为它们引发的问题都表现为“数据看起来不对”而不是明确的报错。时区要设成业务所在地的时区通过环境变量TZ和 JVM 参数-Duser.timezone双保险。只设环境变量不设 JVM 参数某些情况下 Java 读到的还是 UTC写入数据库的 datetime 字段会整体偏移。这个坑我踩过一次迁完之后对账发现所有时间字段差八小时回头查了半天才定位到是 JVM 时区没传。字符集要保证file.encodingUTF-8同时数据库连接串里显式带characterEncodingutf8。有些环境的默认编码是 GBK配置文件里的中文注释、表注释读进来就乱码然后写进目标库的中文注释也变成乱码事后清理非常麻烦。JVM 参数除了堆大小建议加上-XX:HeapDumpOnOutOfMemoryError和-XX:HeapDumpPath。迁移大表时内存溢出是有可能的有堆转储文件才能分析是哪一步撑爆的没有的话只能靠猜。这几个参数在编排文件里通过JAVA_OPTS环境变量注入改的时候不用重新构建镜像。3. 镜像获取与容器编排实操3.1 镜像来源的两种选择及取舍拿到可用镜像有两条路。第一条是直接用现成镜像如果发布方提供了镜像仓库地址docker pull拉下来就能跑这是最省事的。第二条是自己构建下载发布包里的可执行 jar写一个 Dockerfile 打进去。什么时候必须自己构建发布方没提供镜像、或者你需要往镜像里塞额外的 JDBC 驱动、或者你需要固定某个特定版本做回归验证。自己构建的好处是完全可控镜像里有什么你一清二楚出了问题能一层层查坏处是要自己维护 Dockerfile基础镜像有安全更新时得重新构建。我个人的习惯是验证阶段用现成镜像快速跑通正式落地前自己构建一版把驱动和配置都固化进去。下面这个 Dockerfile 是我常用的模板你可以直接拿去改FROM eclipse-temurin:8-jre ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone WORKDIR /app # 可执行 jar文件名以你实际拿到的发布包为准 COPY dbswitch-admin.jar /app/app.jar COPY config/ /app/config/ ENV JAVA_OPTS-Xms2g -Xmx2g -Dfile.encodingUTF-8 -Duser.timezoneAsia/Shanghai \ -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/app/logs EXPOSE 8080 ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar /app/app.jar \ --spring.config.additional-locationfile:/app/config/]几个细节说明一下。用sh -c包一层是为了让$JAVA_OPTS这个环境变量能被展开直接写ENTRYPOINT [java, $JAVA_OPTS, ...]是展开不了的这是很多人第一次写 Dockerfile 会犯的错。--spring.config.additional-location让外部配置目录优先生效这样改配置不用重新打镜像。基础镜像选 JRE 而不是 JDK体积能小一半迁移工具不需要编译代码。构建命令很简单docker build -t dbswitch:1.0.0 .构建完用docker images确认一下大小正常应该在两三百兆这个量级如果超过 800M大概率是把 JDK 或者一堆无关文件打进去了。3.2 docker-compose 编排与启动单容器用docker run也能跑但参数一多就难维护我一般直接写编排文件。下面这份是可以直接用的模板services: dbswitch: image: dbswitch:1.0.0 container_name: dbswitch restart: unless-stopped ports: - 8080:8080 environment: - TZAsia/Shanghai - JAVA_OPTS-Xms2g -Xmx2g -Dfile.encodingUTF-8 -Duser.timezoneAsia/Shanghai -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/app/logs volumes: - ./config:/app/config - ./logs:/app/logs - ./data:/app/data ulimits: nofile: soft: 65536 hard: 65536 logging: driver: json-file options: max-size: 100m max-file: 5逐项解释一下为什么这么配。restart: unless-stopped保证宿主机重启后服务自动起来除非你手动停过。volumes三个挂载分别对应配置、日志、临时数据这三个目录是必须持久化的容器删了重建不会丢。ulimits就是前面说的文件句柄65536 是个比较稳的数值。logging那段是很多人会忽略的Docker 默认的 json-file 日志驱动不限制大小一个长期运行的服务能把磁盘写满加上轮转限制就安全了。启动和查看状态docker compose up -d docker compose logs -f --tail100日志里看到类似“Started Application”或者监听的端口信息就说明起来了。第一次启动会慢一些因为要初始化内部表结构。3.3 首次启动后的五项验证清单服务起来不等于能用我习惯按下面五项过一遍全部通过才算部署完成。检查项验证方式异常表现端口可达浏览器访问http://宿主机IP:8080连接被拒绝检查端口映射和防火墙时区正确看日志首行时间戳跟本地时间差 8 小时检查 TZ 和 JVM 参数字符编码页面中文是否正常显示出现乱码方块检查 file.encoding目录挂载生效docker exec进容器看/app/logs有无文件日志写在容器内宿主机看不到外部库连通在界面里建一个测试数据源点“测试连接”连接超时多半是地址写成了 localhost这五项里第四项经常被漏掉。判断方法很简单宿主机上ls ./logs有内容说明挂载对了如果容器里日志在涨、宿主机目录是空的那就是挂载路径写错了或者容器内应用把日志写到了别的地方。账号方面首次登录用发布说明里提供的默认凭据登进去第一件事就是改密码。测试环境无所谓但只要这个服务能被内网其他人访问到默认密码就是个隐患。4. 完整跑通一次迁移从建连接到数据核对4.1 数据源配置的正确填法界面里第一步是配数据源本质就是填 JDBC 连接信息。这一步看着简单出问题的比例却最高。下面是三种常见库的连接串写法可以直接参考# MySQL jdbc:mysql://192.168.1.10:3306/order_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue # PostgreSQL jdbc:postgresql://192.168.1.20:5432/order_db?currentSchemapublic # SQL Server jdbc:sqlserver://192.168.1.30:1433;DatabaseNameorder_db;encryptfalse几个必须注意的点。MySQL 的连接串里serverTimezone一定要写不写的话驱动会用 JVM 默认时区去解析前面提过的时间偏移问题就是这么来的。allowPublicKeyRetrievaltrue在 MySQL 8 上不加会报公钥检索失败用老版本驱动反而没这个问题。PostgreSQL 的currentSchema指定了默认 schema不指定的话工具查表可能查不到。SQL Server 的encryptfalse在没配证书的环境里是必须的否则握手就失败。还有个大坑目标库的账号权限。建表、建索引、写数据、读元数据这几类权限缺一不可。有些环境只给了读写数据的权限不给建表权限结果结构迁移第一步就失败报的错还比较隐晦。部署前让 DBA 把权限一次性开够比中途来回沟通省事得多。4.2 表结构迁移里最耗时的字段类型映射结构迁移的核心是类型映射这也是最容易出问题的地方。工具内置了一套映射规则但异构图之间没有完美的一一对应总有些边界情况需要人工确认。下面这张表是我实际遇到过的典型场景源端类型目标端常见映射需要注意什么tinyint(1)boolean / smallintMySQL 里常被当布尔用映射成 smallint 会丢掉语义int unsignedint / bigint无符号整型上限翻倍映射成 int 会溢出datetime(3)timestamp / datetime毫秒精度是否保留取决于目标端支持text / longtexttext / clob超长文本字段目标端可能装不下enumvarchar枚举类型目标端未必支持建议转字符串加约束自增主键序列 / identity三种机制不一样迁移后自增值要从正确位置开始表格里最后一条特别值得展开说。自增主键迁完之后目标端的自增起始值必须大于已有数据的最大值否则应用一插入就主键冲突。有些工具会自动处理有些需要手工执行一条调整语句。我的习惯是迁移完成后固定执行一遍校验查出目标表的主键最大值跟自增值对比不一致就手工修正。这个动作花不了一分钟能避免上线后第一批写入就报错。另一个高频问题是索引名冲突。某些数据库对索引名有长度限制长表名拼上长字段名很容易超长工具截断之后可能出现两个索引重名。迁移完成后建议扫一遍目标库的索引列表看有没有缺失或者重名。4.3 全量数据迁移的批次参数怎么定数据迁移阶段最影响体验的是两个参数批次大小和并发线程数。这两个值没有通用最优解得看数据行长和网络延迟。批次大小的含义是“一次读多少行、一次写多少行”。设太小比如 100那网络往返次数极多速度慢得像蜗牛设太大比如 50000内存里一次装太多容易 GC 甚至 OOM。我的经验值是单行数据在 1KB 以内批次设 3000 到 5000单行超过 5KB有大字段批次降到 500 到 1000。判断单行大小的办法很土但有效查一下表的平均行长information_schema里有对应的统计字段或者直接看表的总大小除以行数。并发线程数取决于目标库能承受多少写入压力。测试环境可以开到 8 到 16 试速度生产环境我一般控制在 4 以下因为迁移往往跟业务并行跑压太狠会影响线上。有个判断标准迁移过程中观察目标库的 CPU 和磁盘写入如果持续打满就说明并发开高了往下调。还有一个实操技巧先拿小表试跑再上大表。挑一张几万行的表完整跑一遍全流程观察耗时和日志确认没问题再开大表。直接拿几千万行的表试水跑两小时才发现参数不对时间全浪费了。4.4 迁移过程中的监控与中断恢复大数据量迁移不可能一直盯着屏幕得有办法判断它是在正常走还是卡死了。我的做法是看两个东西日志的推进速度和目标库的行数增长。日志里通常会打印当前迁移到哪张表、已完成多少行隔几分钟看一眼数字在涨就是正常的如果十分钟没动基本可以判定卡住了。目标库这边直接select count(*)看行数增长跟日志对得上就说明数据确实落地了。卡住的原因通常是三类源库有长事务锁着表、目标库写入被锁等待、网络中间断了但连接没超时。前两类好查查一下两边的锁等待视图就能看到第三类麻烦一点表现为连接一直挂着但没数据流动只能靠连接超时参数兜底。建议在连接串里加上 socket 超时别让它无限期挂着。中断之后的恢复策略取决于工具支持粒度。如果支持按表续传那就把已完成的表排除掉重新跑如果只能整任务重跑那就在迁移前把表按大小排序先跑小表再跑大表减少重跑代价。有些版本支持基于主键断点续传这个能力在超大表上非常值钱值得花时间确认清楚你的版本有没有。4.5 迁移完成后的数据一致性核对这一步是很多人省掉的也是最不该省的。核对分三个层次。第一层是行数核对源库和目标库逐表对比 count。这一步能发现大部分整表漏迁的问题但发现不了部分行丢失。第二层是抽样核对随机抽若干行把关键字段逐列比对。抽样时注意覆盖边界数据主键最大和最小的行、时间字段最早和最晚的行、有 NULL 值的行、字符串最长的行。这几类是最容易出问题的。第三层是聚合核对对数值型字段做 sum 和 avg 对比。这个方法特别灵因为哪怕只丢了一行sum 也会对不上而且不用逐行拉数据几千万行的表跑聚合也就几十秒。-- 源库和目标库分别执行结果应完全一致 SELECT COUNT(*) AS cnt, SUM(amount) AS total_amount, MIN(create_time) AS min_t, MAX(create_time) AS max_t FROM order_main;如果三层都对上了基本可以认为迁移是成功的。有差异就按“行数→主键范围→时间范围”的顺序缩小范围定位到具体是哪一段数据没迁过去。5. 常见问题与排查技巧实录5.1 启动阶段容器起来了但页面打不开这个现象最常见排查顺序是固定的。先docker ps看容器状态如果是Restarting说明启动就崩了直接看日志。如果状态是Up那问题在网络链路上。第一查端口映射docker port 容器名看映射关系对不对第二查宿主机防火墙firewall-cmd --list-ports或者iptables -L看端口有没有放行第三查应用实际监听的端口进容器ss -lntp看有可能配置里改过端口跟映射的对不上第四查绑定地址如果应用只绑了127.0.0.1容器外访问不到需要改成0.0.0.0。这四步走完基本都能定位。我遇到最多的是第三种配置文件里端口是 A编排文件里映射的是 B自己改过其中一处忘了另一处。5.2 连接阶段数据源测试失败的四类原因报错关键字常见原因排查动作Connection refused地址或端口错或数据库没监听该地址宿主机上telnet IP 端口验证Communications link failure容器网络不通或写了 localhost换成宿主机真实 IP 重试Access denied账号密码错或该账号不允许从该 IP 登录检查账号的 host 授权范围Public Key RetrievalMySQL 8 认证插件限制连接串加 allowPublicKeyRetrievaltrueUnknown database库名拼错或该库不存在登客户端show databases确认第二行那个问题值得单独说。容器里配localhost失败几乎每个初次用容器部署的人都会遇到一次。判断方法很简单进容器执行ping 宿主机IP通说明网络没问题那就是地址写错了。第四行的公钥检索问题也高频。MySQL 8 默认用caching_sha2_password认证插件老版本驱动不支持会报这个错。两个解法连接串加参数或者把驱动升级到新版本。我一般选前者改配置比换驱动风险小。5.3 迁移阶段几个看起来像 bug 其实是配置问题的现象现象一迁移速度越跑越慢。前几万行很快后面越来越慢。这多半是目标库的索引在拖后腿每插一行都要更新索引数据量大了索引维护成本陡增。解决办法是迁移前先禁用非唯一索引迁完再重建速度能快好几倍。现象二迁移到某张表就卡住不动。先看源库有没有长事务再看是不是遇到了大字段比如一张表里有几个 longtext 字段一行就好几兆批次大小还按 5000 设一次要读几个 G 进内存直接卡在 GC 上。把这张表的批次单独调小就行。现象三迁完之后数据行数对得上但内容有差异。这类问题最难查通常是字符集或者精度问题。比如源端是 utf8mb4目标端是 utf8emoji 字符写进去就变成问号再比如源端是 decimal(18,6)目标端建成 decimal(18,2)小数位直接被截断。这类问题在结构迁移阶段就该发现所以强烈建议结构迁移完成后先人工过一遍关键表的字段定义别急着跑数据。现象四任务跑完了但日志里有大量重试记录。说明中间有失败重试虽然最终成功了但可能有数据重复写入的风险。检查目标表有没有唯一约束兜底没有的话建议迁移后做一次去重校验。5.4 性能阶段把迁移时间从小时级压到分钟级优化顺序我一般这么排先去索引再调批次最后加并发。去索引的收益最大能到 3 到 5 倍批次调优收益中等1.5 到 2 倍并发收益看目标库能力但风险也最高加多了容易把线上拖垮。还有一个容易被忽略的点关掉自动提交改成手动批量提交。很多工具的批量写入默认是每条一个事务开销巨大。确认工具是否支持事务批量提交支持的话务必打开这是免费的性能提升。最后提一个邪道但有效的办法如果是同构库之间迁移直接物理备份恢复比走工具快得多。走工具的价值在于异构、在于结构转换、在于能可视化比对。同构大库工具反而不是最优解。搞清楚工具擅长什么别拿锤子拧螺丝。6. 生产落地前值得多花半小时做的几件事6.1 把迁移任务拆成可回滚的小批次一次性迁几百张表中途失败就得从头再来这个代价太高。我的做法是按业务模块或者按表大小分成若干批次每批迁完做一次核对通过了再进下一批。这样即使出问题影响面可控回滚也只需要回滚当前批次。具体怎么分批先查一遍所有表的大小和行数按行数排序把超大表千万行以上单独拎出来作为独立批次中小表合并成几批。超大表单独跑的好处是可以针对它单独调参数不用迁就其他表。6.2 日志与现场证据的保留策略迁移出问题时最有价值的证据是日志和当时的数据库状态。建议在迁移前把两边的表结构导出成文件存档迁移过程中把工具日志实时落盘迁移后把核对结果也存一份。这三份东西放在一起事后复盘的时候能还原出完整的时间线。容器的日志默认存在 json-file 里前面编排文件已经配了轮转但那只保留了最近的。重要的迁移任务建议额外挂一个日志目录让应用自己往文件里写这样不会被 Docker 的日志轮转清掉。6.3 正式切之前先做一次完整演练演练的意思不是“跑一遍看看能不能通”而是完整模拟一次生产迁移同样的数据量级、同样的网络环境、同样的时间窗口、同样的操作人员。演练至少做一次理想情况做两次第二次专门演练“中途失败怎么恢复”。演练里最该记录的是耗时。结构迁移多久、数据迁移多久、核对多久加起来才是真实窗口需求。很多项目排期出问题就是因为只估了数据迁移的时间忘了结构和核对也要花时间最后窗口不够只能硬着头皮上。我个人在几次迁移里得到的体会是工具能解决 80% 的重复劳动剩下 20% 的边界情况才是真正吃经验的地方。类型映射的边角、自增主键的起始值、字符集的细微差异、索引名的长度限制——这些在文档里往往一笔带过但每一个都能让迁移卡住半天。所以我现在的习惯是每迁一个库就把遇到的特殊情况和处理方式记到一个自己的清单里下次遇到同类库直接翻清单比查文档快得多。这份清单攒到第三四个项目的时候价值就体现出来了。