大型 Docker 镜像导出导入工程化：可靠性、磁盘与压缩

摘要：分析二十多 GiB Docker 镜像在 save/load、临时 TAR、流式压缩、SHA256 和 zstd 之间的工程取舍，并给出更省磁盘的脚本结构。

@[toc]
普通镜像只有几百 MB 时，docker save 和 docker load 很少让人关心磁盘峰值。

但开发镜像如果包含完整 Yocto SDK，规模达到二十多 GiB，导出本身就会变成一个值得设计的流程。

真正的问题不再只是：

怎么导出？

而是：

失败时会不会留下假成功文件？
Ctrl+C 会不会留下几十 GiB 垃圾？
临时 TAR 会占多少磁盘？
压缩包是否需要先解压才能 docker load？
如何校验传输完整性？

1. save/load 的基本数据流

导出：

1	docker save -o cross-dev.tar cross-dev:20.04

导入：

1	docker load -i cross-dev.tar

可以理解成：

Docker image
    ↓ docker save
TAR archive
    ↓ docker load
Docker image

Docker 官方还明确说明，当前 docker load 可以直接读取：

tar
gzip
bzip2
xz
zstd

因此导入压缩包时，并不要求先手工解出完整 tar。

2. 为什么一个可靠的 POSIX sh 脚本会先生成 TAR

一个常见实现是：

TMP_TAR=$(mktemp ".image.XXXXXX.tar")
TMP_GZ=$(mktemp ".image.XXXXXX.gz")

trap cleanup EXIT HUP INT TERM

docker save -o "$TMP_TAR" "$IMAGE"
gzip -1 -c "$TMP_TAR" > "$TMP_GZ"
mv "$TMP_GZ" "$OUTPUT"
sha256sum "$OUTPUT" > "$OUTPUT.sha256"

看起来比：

1	docker save "$IMAGE" \| gzip -1 > "$OUTPUT"

麻烦很多。

但它在保护一个很重要的东西：失败语义。

标准 POSIX sh 没有 Bash 那样常用的 pipefail。对于：

A | B

pipeline 最终通常以最后一个命令 B 的退出状态为主。

因此理论上可能出现：

docker save 失败
    ↓
gzip 正常结束
    ↓
脚本误认为 pipeline 成功

先把 docker save -o 单独完成，就能明确知道镜像导出是否成功。

所以“临时 TAR”不是错误设计，它是在用磁盘换可靠性。

3. 问题在于大型镜像的磁盘峰值

假设一次导出实际产生：

1 2	临时 TAR：约 27 GiB 最终 gzip：约 12 GiB

压缩过程中可能同时存在：

1
2
3

27 GiB TAR
+
逐渐增长到 12 GiB 的 GZ

仅导出目录峰值就可能接近：

39 GiB

Docker 自己保存镜像的数据还没有计算在内。

因此大镜像导出前必须同时看：

1 2	df -h /path/to/export-dir docker system df

而不是只确认镜像“存在”。

上面的数字只是示例。镜像 SIZE、docker save TAR 和压缩归档大小不是固定比例，真正规划空间要看实际文件。

4. mktemp、trap 和最后 mv 都值得保留

这类脚本里最值得保留的是：

1 2	mktemp trap cleanup EXIT HUP INT TERM

因为大型临时文件一旦异常残留，代价非常高。

用户执行到一半按 Ctrl+C：

SIGINT
  ↓
trap
  ↓
删除临时文件

比几天后才发现根分区多了一个 20 GiB 隐藏文件好得多。

同样，最终最好：

生成 .partial
    ↓
全部成功
    ↓
mv 成最终文件名

不要从一开始就直接写：

1	cross-dev.tar.gz

否则半截压缩包看起来也像正式交付物。

5. 导入端其实可以简单很多

一种保守导入方式是：

1 2	gzip -dc "$ARCHIVE" > "$TMP_TAR" docker load -i "$TMP_TAR"

对于 20+ GiB 镜像，它的问题很直接：接收方 /tmp 还得额外容纳完整 TAR。

而当前 Docker 官方支持直接：

1	docker load -i cross-dev.tar.gz

或者：

1	docker load -i cross-dev.tar.zst

因此可以去掉：

1 2	gzip -dc /tmp/巨大临时 TAR

这通常是现有导入脚本最值得做的第一项优化。

6. SHA256 最好自动检查

导出端生成：

1	sha256sum "$OUTPUT" > "$OUTPUT.sha256"

接收端应该在 docker load 之前验证：

1	sha256sum -c cross-dev.tar.zst.sha256

如果想让导入脚本更完整，可以自动查找：

CHECKSUM="$ARCHIVE.sha256"

if [ -f "$CHECKSUM" ]; then
    sha256sum -c "$CHECKSUM"
fi

正式离线交付甚至可以规定：没有 .sha256 就拒绝导入。

这样交付链变成：

导出
  ↓
SHA256
  ↓
传输
  ↓
SHA256 验证
  ↓
docker load

每一步都有明确完成条件。

7. gzip -1 并不是坏选择

gzip -1 的思路是：

1
2
3

更重视压缩速度
牺牲一些压缩率
保持极高兼容性

对于大型 SDK 镜像，目标往往不是把文件压到理论最小，而是：

1
2
3

不要压几个小时
不要吃满磁盘
接收端容易使用

所以把 -1 直接改成 -9 通常不是最有价值的优化。

真正应该先优化的是临时文件和数据流。

8. zstd 适合什么场景

如果团队环境允许安装 zstd，可以考虑：

1	zstd -T0 -3

其中：

1 2	-T0 使用所有可用线程 -3 常用压缩级别

zstd 是否一定比 gzip 更小、更快，取决于镜像内容、CPU 和磁盘，不应该绝对化。

但有一个确定优势：

当前 Docker load 官方支持 zstd 压缩归档。

所以：

1	cross-dev.tar.zst

可以直接作为 Docker 导入文件，不要求先解压。

9. 真正省磁盘的是流式压缩

理想数据链是：

flowchart LR
    Image["Docker Image"] -->|"docker save stdout"| Compressor["gzip / zstd"]
    Compressor --> Partial["压缩临时文件"]
    Partial -->|"成功后 mv"| Final["最终归档"]

也就是不再落盘完整 TAR。

如果允许使用 Bash，可以：

#!/usr/bin/env bash
set -Eeuo pipefail

IMAGE=${IMAGE:-cross-dev:20.04}
OUTPUT=${1:-cross-dev-20.04.tar.zst}
PARTIAL="${OUTPUT}.partial"

cleanup() {
    rm -f "$PARTIAL"
}
trap cleanup EXIT HUP INT TERM

docker image inspect "$IMAGE" >/dev/null

docker save "$IMAGE" | zstd -T0 -3 -o "$PARTIAL"

mv "$PARTIAL" "$OUTPUT"
trap - EXIT
sha256sum "$OUTPUT" > "$OUTPUT.sha256"

这里关键是：

1	set -o pipefail

它让 docker save 或 zstd 任意一端失败时，pipeline 都能返回失败。

这解决了 POSIX sh 简单管道的主要可靠性问题。

10. 如果必须坚持 POSIX sh 呢

可以继续使用当前“临时 TAR”方案，它虽然占磁盘，但逻辑简单、容易审计。

也可以设计 named pipe / FIFO：

1	docker save -> FIFO -> compressor

然后分别记录两个后台进程 PID，再分别 wait，从而获取双方退出状态。

这可以同时做到：

1
2
3

POSIX sh
流式压缩
独立失败检测

但代码复杂度会上升不少。

如果脚本只是团队内部 Linux 开发环境使用，与其为了“纯 POSIX”写复杂同步代码，不如明确要求 Bash，通常更容易维护。

11. 导入脚本可以保持 POSIX sh

导入端没有复杂 pipeline，可以很简单：

#!/usr/bin/env sh
set -eu

ARCHIVE=${1:?usage: import-image.sh IMAGE_ARCHIVE}
CHECKSUM="$ARCHIVE.sha256"

[ -f "$ARCHIVE" ] || exit 1

if [ -f "$CHECKSUM" ]; then
    sha256sum -c "$CHECKSUM"
else
    printf 'WARNING: checksum missing: %s\n' "$CHECKSUM" >&2
fi

docker load -i "$ARCHIVE"
docker image ls

无论文件是：

1
2
3

.tar
.tar.gz
.tar.zst

都可以直接交给 docker load，前提是格式属于 Docker 官方支持类型。

12. 扩展名必须和格式一致

如果脚本内部永远执行 gzip，却允许用户指定：

1	./export-image.sh image.tar

那就可能得到：

1 2	名字：image.tar 实际：gzip 数据

更合理的是明确：

1
2
3

.tar      不压缩
.tar.gz   gzip
.tar.zst  zstd

或者干脆固定输出格式，不接受任意后缀。

交付脚本最怕的不是“功能少”，而是文件名和真实行为不一致。

13. 传输也要考虑中断恢复

大型归档生成以后，局域网更适合：

1 2	rsync -avP cross-dev-20.04.tar.zst \ devuser@host:~/images/

接收端：

1 2	sha256sum -c cross-dev-20.04.tar.zst.sha256 docker load -i cross-dev-20.04.tar.zst

最后：

1	docker image ls cross-dev:20.04

整个流程的重点不是“命令少”，而是每一步都能明确知道有没有成功。

14. 几种方案怎么选

方案	临时磁盘	失败判断	依赖	适合场景
先 TAR 再 gzip	很高	清晰	POSIX sh	最保守、磁盘足够
`save	gzip`	低	POSIX sh 下较弱	POSIX sh
Bash `pipefail` + gzip	低	清晰	Bash	通用团队环境
Bash `pipefail` + zstd	低	清晰	Bash + zstd	大镜像、重视吞吐