Docker镜像离线迁移指南：save与load打包tar实操详解

1. 为什么要把Docker镜像打包成tar文件

先说个最常见的场景。我在某公司做部署时，经常要把一套服务从测试服务器搬到生产服务器，但这两台机器完全不在一个网络里，中间隔着一道严格的网络隔离，别说拉公共镜像仓库，就连公司内网的镜像仓库都不一定能连通。这时候如果用常规的 docker pull / docker push 思路，基本就卡死了——源服务器没法推出去，目标服务器也拉不回来，服务只能干瞪眼。

另外一种更典型的场景是离线交付。客户那边要求整套系统以离线包的形式交付，现场不能访问外网，也不允许配置在线镜像仓库。你如果在现场临时 docker pull nginx:latest，大概率等来的就是 Error response from daemon: Get ... 这样的超时或者连接失败。所以我最早做离线交付时，心里就一个想法：既然网络这条路走不通，那就把镜像变成文件带走。

docker save 和 docker load 这对命令解决的核心问题，就是让你在完全不依赖镜像仓库的情况下，把 Docker 镜像从一个环境迁移到另一个环境。docker save 会把一个或多个镜像打包成 .tar 归档文件，这个文件能拷进U盘、走 scp、挂到 HTTP 下载，甚至放在对象存储里中转；到了目标机器上再用 docker load 读回来，镜像就像没挪过窝一样直接可用。

这篇文章主要就是记录我在实际项目中反复使用这套流程的完整经验：从导出命令、压缩打包、跨机传输，到目标机器加载和验证，每个环节里有哪些容易踩的坑，以及各路参数到底怎么选。适合运维、部署工程师、后端开发，以及所有需要做镜像迁移或者离线交付的人参考。

开始之前得先强调一点，很多人把 docker save 和 docker export 搞混，顺手用了 docker export 导出一堆文件，结果到另一台机器上 docker load 直接报错。这俩名字长得像，功能却是完全两码事，后面我会专门拆开讲。

2. 导出镜像前的概念拆解：save和export千万别搞混

2.1 docker save与docker export的本质区别

docker save 和 docker export 是两条经常被混淆的命令，但它们的适用场景完全不一样。简单说，save 的对象是镜像，export 的对象是容器。

save 走的是完全保真的路线。它在打包时把镜像的元数据、每一层文件系统、标签、启动命令等全部写进 tar 包，所以 docker load 加载回来之后，镜像基本跟你导出前没有任何区别。export 则是在一个已经运行的容器上做“快照”，把当前容器的整个文件系统导出去，它丢失了镜像的历史层和元数据，所以丢失了 CMD、ENTRYPOINT 这些启动关键信息，docker import 回来之后往往要手动补充 docker run 参数才能跑起来。

我记得有一次同事 A 想迁移一个数据库镜像，他用了 docker export $(docker ps -q) 导出了一个 tar，然后拷到目标机器上执行 docker load，结果报错：Error processing tar file: ...，其实就是export出来的格式根本不是 load 能认的。后来改成重新 docker export 后用 docker import 导入，但导入后发现环境变量和默认命令全丢了，容器也没法正常启动。所以如果你想迁移一套完整镜像，尤其是要留在后面跑 docker run 的，老老实实用 docker save。

2.2 镜像的分层结构与打包逻辑

要理解为什么 save 能完整还原，得先明白 Docker 镜像的存储机制。镜像不是一个大平文件，而是一层一层叠加起来的文件系统。每一层只记录相对于上一层的文件变化，也就是说修改一个文件、增加一个依赖、安装一个软件包，Docker 都会把它作为新的一层记录。

这种分层结构有很多好处：比如同一台机器上两个镜像共用了底层的基础镜像，磁盘上就只保存一份底层数据，不重复占用空间。但坏处是，如果你只拷贝当前文件系统的快照，就会丢失这些层次关系和元信息。docker save 干的事情就是把每一层都完整地归档起来，同时把镜像的 Dockerfile 构建历史、标签信息、配置信息也一并写入 tar 包，所以 load 能按照原来的层次关系重建出完整镜像。

用一个不太严谨但很好懂的生活类比：镜像像是一本菜谱，每一层是逐步加料的过程记录。save 保存的是整本菜谱，按步骤重新照着做，就能还原出同一道菜；export 只是拍了一张成品照片，你可以拿照片在别的地方仿照着摆盘，但你不知道原来用了哪些料、分几步做出来的。

2.3 为什么这些区别会影响你的操作结果

实际影响非常大。同样是迁移一个运行中的服务，如果用了 export，你拿到的只是一个“文件快照”，丢失了镜像配置。最典型的情况就是环境变量丢没丢、工作目录对不对、启动命令还在不在，以及最直接的——docker load 根本加载不了 export 出来的包，语法层面就错了。另外，即使你用 docker import 强行导入，得到一个镜像后，它的大小往往比原镜像小不少，标签也是 <none>，还得手动 docker tag，操作成本极高。

而用 save + load，镜像的 REPOSITORY、TAG、IMAGE ID 都能原样恢复。我在多台服务器之间迁移时通常完全不用改任何部署脚本，迁移完直接用原有的 docker-compose.yml 启动，省掉大把调试时间。

3. 导出镜像到.tar文件：完整实操与参数详解

3.1 最基础的save命令写法

docker save 的标准命令格式是：

bash复制docker save [OPTIONS] IMAGE [IMAGE...]

最简单的用法：

bash复制docker save nginx:latest -o nginx.tar

这条命令执行完，当前目录下就多了一个 nginx.tar 文件，里面是 nginx:latest 镜像的完整归档。-o 后面的路径可以是相对路径也可以是绝对路径，-o /data/backup/nginx.tar 就直接写到指定目录。

除了 -o 指定输出文件，还有一种用标准输出重定向的写法：

bash复制docker save nginx:latest > nginx.tar

两种写法效果一样，但实际使用中我推荐 -o。因为 docker save 在打包过程中的进度和错误信息会输出到标准错误，如果直接重定向到文件，出现异常时你可能把错误的日志也混进文件里。用 -o 参数时 Docker 会直接管理输出文件，相对更干净。

还有一个容易被忽略的参数是 --output，其实就是 -o 的完整写法，功能完全等价。记忆口诀就一句话：-o 就是 output，指定文件路径。

3.2 一次导出多个镜像与批量导出

docker save 支持一次打包多个镜像，只要在命令里依次列出镜像名即可：

bash复制docker save nginx:latest redis:7.0-alpine mysql:8.0 -o services.tar

执行完之后，services.tar 里同时包含了三个镜像，目标机器上执行 docker load -i services.tar 后，三个镜像会一次性全部恢复到本地。这个特性在做多服务迁移时非常有用，不用一个镜像打一个包，再挨个传过去。

还有一个实际经验：写批量导出脚本时，建议先把需要导出的镜像列表写进一个文本文件，用循环逐行导出。例如某项目需要迁移 5 个服务镜像，我会这样操作：

bash复制docker images --format "{{.Repository}}:{{.Tag}}" > image-list.txt

拿到列表后先人工过一遍，剔除掉不想迁移的镜像，然后循环导出：

bash复制while read img; do
  docker save "$img" -o "$(echo $img | tr '/:' '__').tar"
done < image-list.txt

这里文件名把 / 和 : 都替换成了下划线，避免镜像名里的斜杠造成目录层级混乱。这是个很小的细节，但用默认的 nginx:latest.tar 这种命名很容易在脚本循环里出错。

3.3 压缩导出：什么时候用gzip，什么时候不用

默认情况下 docker save 导出的 tar 文件是未压缩的。一个包含完整系统依赖的应用镜像动辄几百 MB，拷贝起来很费时间。常见的处理方式是导出后用 gzip 压缩：

bash复制docker save nginx:latest | gzip > nginx.tar.gz

或者用一条命令直接生成压缩包：

bash复制docker save nginx:latest | gzip -c > nginx.tar.gz

既然 gzip 能压缩，那是不是所有场景都建议压一把？实际并不是。压缩率效果取决于镜像内容。如果镜像里主要是二进制文件、静态编译产物、图片或者已经压缩过的资源，gzip 的压缩率会非常低，费半天 CPU 可能只省 1%-2% 的体积。反而是那些包含大量文本文件、依赖库的镜像，gzip 压缩率往往能达到 60% 以上，体积能缩一半多。

我用一个实际例子算过账。某项目的基础镜像未压缩 1.2GB，gzip 之后变成了 520MB，传输时间明显缩短。而另一个纯静态资源镜像，未压缩 800MB，压缩后才降到 750MB，几乎没什么收益，却多花了 1 分多钟的压缩时间。

所以在明确知道镜像内容之前，我的习惯是先用 docker image inspect 或者直接 docker save 导出一个大文件测一下压缩效果。如果是迁移到内网机器，带宽有限，建议优先压缩；如果两台服务器在同一局域网内、网络很好，直接传未压缩 tar 反而更快，省掉压缩和解压的 CPU 时间。

另外，压缩包也有代价：目标机器加载前必须解压。虽然 docker load 本身能直接读取 gzip 压缩的文件，但它在内部会做解压操作，加载时间会比直接加载未压缩文件长。所以我的建议是：离线交付场景，压缩；内网高速传输，不压缩。

3.4 跨机传输方式与校验

镜像打包好之后，怎么把它从源服务器传到目标服务器，也是一个很关键的操作环节。一般在公司内网里我常用 scp 或者 rsync：

bash复制scp nginx.tar.gz user@目标服务器IP:/data/images/

如果文件特别大，超过几个 GB，scp 上传中断后要重来，很痛苦。这种情况下我推荐 rsync，它支持断点续传，中断后重新执行会从上次断掉的地方继续传输：

bash复制rsync -avP --partial nginx.tar.gz user@目标服务器IP:/data/images/

--partial 参数表示保留未传完的部分文件，下次传输继续，实测在网络不稳定的跨地域传输场景下非常救命。另外，在传输之前和之后要养成校验文件的习惯，否则传半个文件过去，docker load 会给你报一个不友好的错误。

用 sha256sum 校验：

bash复制sha256sum nginx.tar.gz

在源服务器执行一次，把结果记下来，传到目标服务器后再执行一次比对。两边哈希一致，再继续 docker load 操作。这个步骤看似多花几秒钟，但能避免“传了一个损坏的 tar 包，加载到一半才报错，白白折腾半小时”的尴尬局面。

4. 在另一台服务器上加载镜像：load的完整流程

4.1 load命令的基础用法

镜像文件到了目标服务器，接下来就是加载。docker load 的标准用法：

bash复制docker load -i nginx.tar

-i 参数指定输入文件，上述命令会把 nginx.tar 里的镜像恢复到 Docker 本地镜像库。加载过程会显示每一层的信息，比如 Loaded image: nginx:latest，看到这行说明镜像已经导入成功。

如果路径写错了或者文件格式不对，通常会报：

bash复制Error processing tar file: unexpected EOF

或者：

bash复制open /var/lib/docker/tmp/docker-import-...: no such file or directory

之前说过 docker save 可以导出到标准输出，那么 docker load 也支持从标准输入读取。对应的管道写法：

bash复制cat nginx.tar.gz | docker load

这个写法在线上应急时非常实用——比如你在一台机器上导出镜像，通过 SSH 直接管道到另一台机器加载，中间不用落地文件：

bash复制docker save nginx:latest | ssh user@目标服务器IP "docker load"

一条命令完成跨机镜像同步，省去中间拷贝环节。不过这要求两台机器之间 SSH 链路带宽足够稳定，否则大文件通过 SSH 传输时一旦中断，所有读取进程都可能受到影响，所以大文件我还是更倾向于先落地再校验。

4.2 加载后的验证清单

加载不等于万事大吉。docker load 成功之后，至少要做三件验证工作。

先看镜像列表，确认镜像和标签都在：

bash复制docker images

如果镜像名和标签没有出现在列表里，而是显示一堆 <none>，说明打包时可能没有指定完整标签，或者镜像本身就没有打 tag。这种情况我会继续用 docker image inspect 查看具体镜像 ID，手动补齐标签。

然后跑一次容器冒烟测试，确认镜像能被正常启动。命令很直观：

bash复制docker run --rm nginx:latest nginx -v

对于基础镜像，可以只验证入口命令能执行；对于完整业务镜像，建议直接按原部署方式启动容器，看日志是否正常。如果加载的镜像包含多个服务，往往还需要检查镜像内环境变量。用 docker inspect 能查看镜像的 Config.Env、Entrypoint、Cmd等信息，确认这些配置没有丢。

最后看一眼镜像大小，和源服务器的 docker images 结果对比。如果体积有明显变化，要么是压缩包损坏，要么是加载过程丢了内容，这种情况下建议重新传输。

4.3 批量导入多镜像

如果之前是批量导出的单个 tar 包，在目标服务器上可以一次导入多个文件。最直接的方法是依次执行 docker load -i，也可以写一个小脚本循环：

bash复制for f in /data/images/*.tar; do
  echo "Loading $f ..."
  docker load -i "$f"
done

如果想让脚本更健壮，还可以在循环里加上退出码判断，加载失败时及时中断并输出错误日志：

bash复制for f in /data/images/*.tar; do
  docker load -i "$f" || { echo "$f load failed"; exit 1; }
done

注意，docker load 的输入文件如果不是 tar 包或者 gzip 包，它会尝试解析并失败，所以脚本里最好先判断文件扩展名。也可以统一把所有文件命名成 .tar 或 .tar.gz，保证脚本简单可依赖。

4.4 加载过程中关于标签和版本的坑

加载之后镜像的标签能不能保留，取决于 docker save 时镜像本身有没有标签信息。如果你执行的是：

bash复制docker save 镜像ID -o xxx.tar

导出的 tar 包虽然包含镜像数据，但标签信息会丢失，加载后镜像会变成 <none>:<none>。所以导出时尽量用“仓库名:标签”的形式指定镜像，而不是直接写镜像 ID。

还有一种情况：你想给镜像换个标签，可以在导出前先用 docker tag 打上目标标签，再导出。比如源机器上有个镜像叫 registry.internal:5000/nginx:v1，目标机器上希望它叫 nginx:latest：

bash复制docker tag registry.internal:5000/nginx:v1 nginx:latest
docker save nginx:latest -o nginx.tar

这样加载到目标机器后，镜像名字直接就是 nginx:latest，省得再手动 tag 一次。

5. 常见问题与排查技巧实录

这一节我把自己实际遇到过的坑汇总成了一张速查表，按“现象-原因-解决”的思路梳理，方便你以后照着排查。

5.1 架构不一致导致的启动失败

这个坑在跨机器迁移时非常常见，尤其你是从一台 Intel/AMD 的服务器迁移到 ARM 架构的服务器，或者反过来。docker load 本身不会拒绝任何架构的镜像，但加载成功后，用 docker run 启动时可能会因为可执行文件架构不匹配而失败。比如在 ARM 机器上运行 amd64 的二进制，会提示 exec format error。

所以在迁移之前，先确认两边的 CPU 架构：

bash复制uname -m

如果一边是 x86_64、一边是 aarch64，那直接 save/load 是跑不起来的。这种情况要么去源机器上找对应 ARM 架构的镜像版本，重新 docker pull、docker save；要么用支持多架构的镜像，在导出前通过 docker manifest inspect 确认是否存在对应平台的镜像。如果实在没有，可以考虑用 docker buildx build --platform linux/arm64 单独构建一份目标平台镜像，再打 tar 包带走。

还有一个容易被忽略的点：即使源机器能跑容器，目标机器的内核版本如果太低，某些镜像里的系统调用也可能不兼容，启动时会出现 operation not permitted 之类的错误。排查时先用 docker info 看内核版本，再对照镜像要求做判断。

5.2 tar包损坏后的处理办法

tar 文件在传输过程中损坏是离线交付最常见的故障之一。我遇到过一次特别坑的情况：从某测试环境导出 3 个镜像，统一打包成一个 tar，大小约 4.5GB。拷到客户机器的U盘上后加载，前面 2 个镜像都成功了，第 3 个加载到一半报 unexpected EOF，但 docker images 里已经多出了部分镜像层。结果就是 Docker 的镜像存储结构被搞出了残留，后续再加载别的镜像也会报磁盘问题。

后来我总结了一套处理原则：大文件迁移，拆小包优于打大包。不要把多个镜像塞进一个大 tar 里，而是每个镜像单独导出，单独校验。这样某个包坏了，重传那一个就行，不用整个流程重来。如果项目必须一次性交付多个镜像，也可以先传一份 sha256sum 校验清单，到现场先校验再加载。坏了就立刻反馈，别等加载到一半才发现。

5.3 磁盘空间不够时的预判

docker load 加载到一半报 no space left on device 的情况，我也踩过。原因很简单：tar 包本身可能只有 1GB，但镜像解压后的实际占用可能达到 2-3GB。很多人只看到 tar 包大小就觉得没问题，忽略了镜像分层展开后的真实空间需求。

加载前先检查目标机器的 Docker 数据目录空间：

bash复制df -h /var/lib/docker

如果空间紧张，优先清理不用的旧镜像：

bash复制docker image prune -a

但要注意，prune -a 会把所有未被容器使用的镜像都清掉，操作前务必确认没有需要保留的东西。另外，Docker 加载镜像时会把中间层也展开到本地，如果目标磁盘是机械盘且 inode 耗尽，也会报空间不足。用 df -i 检查 inode 余量是很多老手才会注意到的排查点。

5.4 save/load与registry push/pull的使用取舍

最后聊一下什么时候用 save/load，什么时候用 docker push/docker pull。很多人会问，既然有镜像仓库，为什么还要折腾 tar 包？答案核心在“网络可达性”。

如果你的环境里有一台所有人都能访问的镜像仓库，而且网络畅通，那直接用 push/pull 确实是最高效的。但实际生产里经常遇到几个问题：私有仓库地址在目标环境不可达、仓库认证信息没有下发到目标机器、目标环境不允许往外网推镜像。这些情况下，save/load 就成了唯一方案。

另外，一次性批量迁移场景下，save/load 也比 push/pull 更可控。从源机器导出一个离线包，到目标机器一次load，整个过程不依赖任何中间服务，流程显著简化。而 push/pull 一旦仓库出问题，调试成本比重新传文件高得多。

但如果是持续集成场景，比如每天都要自动构建部署，那还是应该优先把镜像推送到仓库，让目标机器自动拉取。手动传 tar 包做持续同步，既慢又容易出错。说到底，两者是互补关系，不是替代关系，我的选择标准就一条：离线和一次性用 save/load，在线和持续用 push/pull。

6. 影响范围与实际使用心得

这块操作看着简单，但影响面其实不小。日常工作中，它帮我解决的不只是“把镜像搬过去”这一个问题，而是整个环境一致性问题的兜底方案。测试环境、预发布环境、生产环境之间的差异，往往就出在依赖版本不一致、系统库版本偏差上。用一个 tar 包把镜像完整搬到另一台机器，镜像内打包好的所有依赖、配置、代码全都保持原样，跑起来的行为也最能保持一致。

我自己的团队在做某个跨平台系统（内部项目代号叫“某跨平台系统”）迁移时，就是靠这套流程把 6 个服务镜像从一套环境整体搬到了另一套环境。整个过程如果走仓库推送，得先准备仓库、配置认证、改脚本、再验证，至少大半天；用 save/load 之后，导出压缩用了约 15 分钟，rsync 传输用了约 10 分钟，load 加验证用了约 20 分钟，整个迁移半天以内就完成了。中间还跨了不同机房，网络条件一般，但流程依然顺利。

另外一个小技巧：我习惯在导出镜像后用脚本同时生成一份镜像清单，记录每个镜像的 IMAGE ID 和 CREATED 时间，作为交付附件。客户验收时能快速确认版本，也方便后续回滚时核对。这个“顺手”做的步骤，后来在多次交付中成了双方都认的规范。

最后说说这个流程还能怎么扩展。如果你需要频繁在多个服务器间同步镜像，可以写一个定时脚本，定期把新构建的镜像导出并传输到目标服务器。也可以把它集成到上线流程中，作为发布前的一个预操作步骤。这样既保留离线交付的可靠性，又不至于完全手工操作。我实际用下来最大的感受是，这套流程最大的价值不是省了那几分钟，而是把“环境差异”这个不可控变量变成了可控项。镜像一到，环境就在，剩下的只是业务本身的验证。