企业官网建设流程全解析

• 容器运行时
• 云原生
• CLI

【免费下载链接】podman

Podman: A tool for managing OCI containers and pods.

项目地址：https://gitcode.com/gh_mirrors/po/podman

点击查看免费下载

####> podman build, farm build, manifest push, push

即该选项由四个命令共享。在 `cmd/podman` 目录中可以找到各命令对它的注册： - `podman push`：[push.go](https://link.gitcode.com/i/99b104751b414ae1a636067c45d2c012) 通过 `flags.StringVar(&pushOptions.CompressionFormat, compFormat, compressionFormat(), "compression format to use")` 注册，并挂载补全函数 `common.AutocompleteCompressionFormat`； - `podman manifest push`：[manifest/push.go](https://link.gitcode.com/i/83f777243f940fe8aa77930197ac5cc2) 同样注册该选项； - `podman build` 与 `podman farm build`：通过 [common/build.go](https://link.gitcode.com/i/338992bc89bc8f351cd282b5832eef42) 在构建参数解析时读取该标志。 此外，shell 补全函数在 [common/completion.go](https://link.gitcode.com/i/2353889b3242f60d7a58693cfa79a4c3) 中明确列出了可补全的三个合法取值： ```go func AutocompleteCompressionFormat(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) { types := []string{"gzip", "zstd", "zstd:chunked"} return types, cobra.ShellCompDirectiveNoFileComp }

因此在交互式 shell 中输入podman push --compression-format <TAB>即可获得这三种格式的自动补全。

二、支持的取值与默认值

2.1 三种取值

选项的完整语法定义为：

--compression-format=gzip | zstd | zstd:chunked

取值	说明	典型适用场景
gzip	传统的 gzip 压缩，兼容性最好，几乎所有 registry 与运行时都支持	通用推送、跨平台分发、与旧工具链协作
zstd	Facebook 开源的 Zstandard 压缩，压缩/解压速度更快、同级别压缩率更优	追求推送速度与体积平衡的现代环境
zstd:chunked	基于 zstd 的分块压缩格式，支持服务端按需解压、延迟解压（lazy decompression）等增强能力	与支持该格式的 registry（如 Quay）配合使用时

2.2 默认值：gzip，但可被 containers.conf 覆盖

文档明确指出：

The default isgzipunless overridden in the containers.conf file.

这一默认值链路在源码中清晰可见。在 push.go 中：

func compressionFormat() string { if registry.IsRemote() { return "" } return containerConfig.ContainersConfDefaultsRO.Engine.CompressionFormat }

也就是说：

• 本地模式：--compression-format的默认值取自containers.conf的engine.compression_format配置项（未配置时该字段为空，最终解析回退为gzip）；
• 远程模式（podman-remote或服务端模式）：默认值为空字符串，由服务端按其配置决定。

2.3 在 containers.conf 中全局覆盖

用户可以通过containers.conf统一修改默认压缩格式，无需在每个命令上加参数。仓库中附带的默认配置模板位于 vendor/go.podman.io/common/pkg/config/containers.conf：

# The compression format to use when pushing an image. # Valid options are: `gzip`, `zstd` and `zstd:chunked`. # This field is ignored when pushing images to the docker-daemon and # docker-archive formats. It is also ignored when the manifest format is set # to v2s2. # `zstd:chunked` is incompatible with encrypting images, and will be treated as `zstd` with a warning # in that case. # #compression_format = "gzip"

配置示例（写入$HOME/.config/containers/containers.conf或/etc/containers/containers.conf）：

[engine] compression_format = "zstd"

需要注意模板注释中补充的两个重要限制：

1. 推送到docker-daemon与docker-archive目标格式时该配置被忽略（因为这些格式内部固定使用 gzip 层）；
2. manifest 格式为v2s2时同样忽略该配置。

podman build一侧的读取逻辑在 common/build.go：

} else { algo, err := compression.AlgorithmByName(podmanConfig.ContainersConfDefaultsRO.Engine.CompressionFormat) if err != nil { return nil, fmt.Errorf("parsing compression_format from containers.conf: %w", err) } ... }

可见如果containers.conf中配置了非法值，构建会直接报错并指明来源是compression_format解析失败。

三、zstd:chunked与镜像加密的不兼容处理

文档对zstd:chunked给出了一条明确警告：

zstd:chunkedis incompatible with encrypting images, and will be treated aszstdwith a warning in that case.

即：当你在podman push --encryption-key ... --compression-format zstd:chunked这样的组合中使用分块压缩时，Podman 不会直接报错终止，而是：

1. 打印一条警告信息；
2. 静默地将压缩格式降级为普通zstd继续推送。

这是因为zstd:chunked依赖服务端对镜像层的分块解析能力，而加密后的层内容无法被 registry 端识别与按需解压，二者在功能上互斥。相同的行为约束也原样写入了containers.conf的模板注释（见上文第 486-487 行），保证命令行与配置文件两条路径的行为一致。

四、与相邻选项的交互规则

4.1 自动联动--force-compression

--force-compression的官方说明（见 force-compression.md）规定：

Defaults totrueif--compression-formatis explicitly specified on the command-line,falseotherwise.

对应实现位于 push.go：

if cmd.Flags().Changed("compression-format") { if !cmd.Flags().Changed("force-compression") { // If `compression-format` is set and no value for `--force-compression` // is selected then defaults to `true`. pushOptions.ForceCompressionFormat = true } }

podman manifest push的 manifest/push.go 中实现了完全相同的逻辑。这意味着：只要你显式指定了--compression-format，Podman 就会强制以该格式重新压缩并覆盖目标上已有的其他格式变体，确保推送出去的层一定是你指定的压缩格式；若目标 registry 已存在同层不同压缩格式的 blob，也不会复用旧 blob 而直接以新格式写入。

4.2 与--compression-level配合

--compression-level用于指定压缩级别，取值范围与格式强相关（可从 scp_compression_test.go 的测试用例侧面印证格式与级别的范围校验逻辑）：

• gzip：合法范围1-9，默认 5；
• zstd：合法范围1-20，默认 3；
• 级别超出对应格式范围会直接报错（例如对gzip传 10 会得到 “compression level 10 is out of range for gzip, must be between 1 and 9”）。

两个选项可以同时使用，如：

podman push --compression-format zstd --compression-level 10 myimage quay.io/example/myimage:latest

4.3 与--disable-compression互斥

在构建场景中，--compression-format不能与--disable-compression同时使用。common/build.go 会在两者同时出现时直接返回错误：

if c.Flag("disable-compression").Changed && flags.DisableCompression { if c.Flag("compression-format").Changed { return nil, errors.New("--disable-compression and --compression-format cannot be used together") } ... }

原因很直观：一个选项要求禁用压缩，另一个选项要求指定压缩算法，语义互相矛盾，Podman 选择在参数校验阶段就拒绝该组合。

五、易混淆点：podman image scp的压缩选项

需要特别提醒：podman image scp也有自己的--compression-format选项，但它不共享本选项的取值集合。从 scp.go 可以看到其合法值来自utils.ScpCompressionValues()，根据 podman-image-scp.1.md，其取值仅为gzip、zstd与none（默认none，即按podman save的原始形态传输）。

相关测试 scp_compression_test.go 明确断言zstd:chunked对podman image scp是不接受的：

{ name: "zstd:chunked is not accepted", opts: entities.ScpCompressionOptions{CompressionFormat: "zstd:chunked"}, // c/image knows this one, podman image scp deliberately does not. wantErr: `unsupported compression format "zstd:chunked"`, },

因此在查阅文档或编写脚本时，务必区分两种语境：构建/推送/清单推送使用的是本文所述的gzip | zstd | zstd:chunked；镜像传输（image scp）则只支持gzip | zstd | none。

六、快速上手与推荐实践

# 1. 显式使用 zstd 压缩推送，级别 10 podman push --compression-format zstd --compression-level 10 myimage quay.io/example/myimage:latest # 2. 使用 zstd:chunked（需目标 registry 支持；且不能与镜像加密同时使用） podman push --compression-format zstd:chunked myimage quay.io/example/myimage:latest # 3. 构建镜像时指定压缩格式 podman build --compression-format zstd -t myimage . # 4. 全局默认改为 zstd（写入 containers.conf 的 [engine] 段） # compression_format = "zstd"

• 容器运行时
• 云原生
• CLI

【免费下载链接】podman

Podman: A tool for managing OCI containers and pods.

项目地址：https://gitcode.com/gh_mirrors/po/podman

点击查看免费下载