名称¶
podman-build - 使用 Containerfile 构建容器镜像
简介¶
podman build [选项] [上下文]
podman image build [选项] [上下文]
描述¶
podman build 使用一个或多个 Containerfile 或 Dockerfile 中的指令以及指定的构建上下文目录来构建镜像。Containerfile 内部使用与 Dockerfile 相同的语法。在本文档中，被称为 Containerfile 的文件可以是名为“Containerfile”或“Dockerfile”的文件。任何附加了额外扩展名的文件都不会被 podman build . 识别，除非使用 -f 标志来指定该文件。
构建上下文目录可以指定为存档、git 仓库或 Containerfile 的 http(s) URL。
当使用 -f 和 Containerfile 的路径调用，且没有明确的 CONTEXT 目录时，Podman 使用 Containerfile 的父目录作为其构建上下文。
以“.in”后缀结尾的 Containerfile 会通过 CPP(1) 进行预处理。这对于将 Containerfile 分解成多个可重用的部分很有用，这些部分可以通过 CPP 的 #include 指令使用。以 .in 结尾的 Containerfile 仅限于没有注释行，除非它们是 CPP 命令。注意，一个 Containerfile.in 文件仍然可以被其他工具使用，只需通过 cpp -E 手动预处理即可。
当 URL 是一个存档时，URL 的内容会在执行前下载到临时位置并解压缩。
当 URL 是一个 Containerfile 时，该 Containerfile 会被下载到临时位置。
当将 Git 仓库设置为 URL 时，该仓库会被本地克隆，然后设置为上下文。如果 URL 具有 git:// 前缀或 .git 后缀，则该 URL 被视为 Git 仓库。
注意：podman build 使用源自 Buildah 项目的代码来构建容器镜像。此 Buildah 代码为容器存储中的 RUN 选项创建 Buildah 容器。在某些情况下，当 podman build 崩溃或用户终止 podman build 进程时，这些外部容器可能会留在容器存储中。使用 podman ps --all --external 命令可以查看这些容器。
podman buildx build 命令是 podman build 的别名。并非所有 buildx build 功能都在 Podman 中可用。提供 buildx build 选项是为了脚本兼容性。
选项¶
--add-host=hostname[;hostname[;…]]:ip¶
向容器的 /etc/hosts 文件中添加一个自定义的主机到 IP 的映射。
该选项接受一个或多个以分号分隔的主机名，映射到一个由冒号分隔的 IPv4 或 IPv6 地址。它也可以用来覆盖 Podman 默认添加到 /etc/hosts 的主机名 IP 地址（另见 --name 和 --hostname 选项）。此选项可以多次指定以向 /etc/hosts 添加额外的映射。它与 --no-hosts 选项冲突，并与 containers.conf 中的 no_hosts=true 冲突。
可以使用特殊标志 host-gateway 代替 IP 地址。这会解析为一个容器可以用来连接主机的 IP 地址。选择的 IP 地址取决于您的网络设置，因此不能保证 Podman 能够自动确定 host-gateway 地址，这会导致 Podman 失败并显示错误消息。您可以使用 containers.conf 中的 host_containers_internal_ip 选项覆盖此 IP 地址。
host-gateway 地址也被 Podman 用来自动将 host.containers.internal 和 host.docker.internal 主机名添加到 /etc/hosts。您可以通过提供 --no-hosts 选项，或者在 containers.conf 中设置 host_containers_internal_ip=”none” 来阻止此行为。如果没有手动配置 host-gateway 地址且 Podman 无法自动确定 IP 地址，Podman 将静默跳过将这些内部主机名添加到 /etc/hosts。如果 Podman 在使用 podman machine 的虚拟机中运行（这包括 Mac 和 Windows 主机），除非手动配置了 IP 地址，否则 Podman 将静默跳过将内部主机名添加到 /etc/hosts；内部主机名将由 gvproxy DNS 解析器解析。
Podman 默认会使用主机的 /etc/hosts 文件作为基础，即此文件中存在的任何主机名也将在容器的 /etc/hosts 文件中存在。可以使用 containers.conf 中的 base_hosts_file 配置来配置不同的基础文件。
--all-platforms¶
不为使用 --platform 选项指定的一组平台构建，而是检查构建的基础镜像，并为它们都可用的所有平台进行构建。使用 scratch 作为起点的阶段无法被检查，因此必须至少存在一个非 scratch 阶段才能使检测有效地工作。
--annotation=annotation=value¶
向镜像元数据中添加一个镜像注解（例如 annotation=value）。可以多次使用。
注意：此信息在 Docker 镜像格式中不存在，因此在以 Docker 格式写入镜像时会被丢弃。
--arch=arch¶
将要构建的镜像的体系结构，以及如果构建使用基础镜像时要拉取的基础镜像的体系结构，设置为提供的值，而不是使用构建主机的体系结构。除非被覆盖，否则后续在本地存储中对同一镜像的查找将匹配此体系结构，而不管主机如何。（示例：arm、arm64、386、amd64、ppc64le、s390x）
--authfile=path¶
认证文件的路径。在 Linux 上默认为 ${XDG_RUNTIME_DIR}/containers/auth.json，在 Windows/macOS 上默认为 $HOME/.config/containers/auth.json。该文件由 podman login 创建。如果在那里找不到授权状态，则会检查 $HOME/.docker/config.json，该文件由 docker login 设置。
注意：还有一种选择是通过设置 REGISTRY_AUTH_FILE 环境变量来覆盖认证文件的默认路径。这可以通过 export REGISTRY_AUTH_FILE=path 来完成。
--build-arg=arg=value¶
指定一个构建参数及其值，该值会像环境变量一样被插入到从 Containerfile 中读取的指令中，但不会添加到最终镜像配置的环境变量列表中。
--build-arg-file=path¶
指定一个包含 arg=value 格式的构建参数行的文件。建议的文件名是 argfile.conf。
以 # 开头的注释行以及空行会被忽略。所有其他行必须是传递给 --build-arg 的 arg=value 格式。
如果通过 --build-arg-file 和 --build-arg 选项提供了多个参数，构建参数将在所有提供的文件和命令行参数中合并。
在 --build-arg-file 选项中提供的任何文件都会在通过 --build-arg 选项提供的参数之前被读取。
当一个给定的参数名称被多次指定时，最后一次指定的实例会被传递给最终的构建。这意味着 --build-arg 的值总是会覆盖 --build-arg-file 中的值。
--build-context=name=value¶
使用其简称和位置指定一个额外的构建上下文。额外的构建上下文可以像我们在 COPY 指令中访问不同阶段一样被引用。
有效值为：
本地目录 – 例如 --build-context project2=../path/to/project2/src （此选项不适用于远程 Podman 客户端。在 Podman machine 设置中（即 macOS 和 Windows），路径必须存在于 machine VM 上）
指向 tarball 的 HTTP URL – 例如 --build-context src=https://example.org/releases/src.tar
容器镜像 – 使用 container-image:// 前缀指定，例如 --build-context alpine=container-image://alpine:3.15, (也接受 docker://, docker-image://)
在 Containerfile 方面，在所有接受“from”参数的命令上引用构建上下文。这看起来可能是这样：
FROM [name]
COPY --from=[name] ...
RUN --mount=from=[name] …
[name] 的值按以下优先顺序匹配：
使用 --build-context [name]=.. 定义的命名构建上下文
在 Containerfile 中使用 AS [name] 定义的阶段
镜像 [name]，可以是本地的或在远程仓库中的
--cache-from=image¶
用作潜在缓存源的仓库。指定此选项后，Buildah 会尝试在指定的仓库中查找缓存镜像，并尝试拉取缓存镜像而不是在本地实际执行构建步骤。Buildah 只有在缓存镜像被认为是有效的缓存命中时才会尝试拉取之前缓存的镜像。
使用 --cache-to 选项来用缓存内容填充远程仓库。
示例
# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
注意：除非指定了 --layers，否则 --cache-from 选项将被忽略。
--cache-to=image¶
设置此标志以指定一个用于存储缓存镜像的远程仓库。Buildah 会尝试将新构建的缓存镜像推送到该远程仓库。
注意：使用 --cache-from 选项以便使用远程仓库中的缓存内容。
示例
# populate a cache and also consult it
buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
注意：除非指定了 --layers，否则 --cache-to 选项将被忽略。
--cache-ttl¶
限制缓存镜像的使用，仅考虑创建时间戳在指定时长内的镜像。例如，如果指定了 --cache-ttl=1h，Buildah 会考虑创建时间在一小时内的中间缓存镜像，而超过此时长的中间缓存镜像将被忽略。
注意：手动设置 --cache-ttl=0 在实现上等同于使用 --no-cache，因为这意味着用户根本不想使用缓存。
--cap-add=CAP_xxx¶
在执行 RUN 指令时，使用指定的权能（capability）添加到其权能集中来运行指令中指定的命令。默认情况下会授予某些权能；此选项可用于添加更多权能。
--cap-drop=CAP_xxx¶
在执行 RUN 指令时，从其权能集中移除指定的权能来运行指令中指定的命令。默认授予 CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID, CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP 和 CAP_SETUID 权能；此选项可用于移除它们。
如果一个权能同时被指定给 --cap-add 和 --cap-drop 选项，它将被移除，无论选项的给出顺序如何。
--cert-dir=path¶
使用 path 路径下的证书（*.crt, *.cert, *.key）连接到镜像仓库。（默认值：/etc/containers/certs.d）详情请参阅 containers-certs.d(5)。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）
--cgroup-parent=path¶
创建 cgroup 的 cgroup 路径。如果路径不是绝对路径，则该路径被视为相对于 init 进程的 cgroup 路径。如果 cgroup 不存在，则会创建它们。
--cgroupns=how¶
设置处理 RUN 指令时 cgroup 命名空间的配置。配置的值可以是“” (空字符串) 或 “private” 以指示创建新的 cgroup 命名空间，或者可以是 “host” 以指示重用 buildah 本身正在运行的 cgroup 命名空间。
--compat-volumes¶
处理使用 VOLUME 指令标记的目录（包括在本次构建中和从基础镜像继承的），使其内容只能由 ADD 和 COPY 指令修改。RUN 指令在这些位置所做的任何更改都将被还原。在此选项引入之前，此行为是默认行为，但现在默认是禁用的。
--compress¶
添加此选项是为了与其他容器 CLI 保持一致。Podman 不与守护进程或远程服务器通信。因此，在发送数据前压缩数据对 Podman 来说无关紧要。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）
--cpp-flag=flags¶
设置传递给 C 预处理器 cpp(1) 的附加标志。以“.in”后缀结尾的 Containerfile 会通过 cpp(1) 进行预处理。此选项可用于向 cpp 传递附加标志。注意：您也可以通过设置 BUILDAH_CPPFLAGS 环境变量来设置默认的 CPPFLAGS（例如，export BUILDAH_CPPFLAGS=”-DDEBUG”）。
--cpu-period=limit¶
为完全公平调度器（CFS）设置 CPU 周期，这是一个以微秒为单位的时长。一旦容器的 CPU 配额用尽，它将不会被调度运行，直到当前周期结束。默认为 100000 微秒。
在某些系统上，非 root 用户可能不允许更改资源限制。更多详情，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--cpu-quota=limit¶
限制 CPU 完全公平调度器（CFS）的配额。
限制容器的 CPU 使用率。默认情况下，容器使用全部 CPU 资源运行。限制值是以微秒为单位的数字。如果提供了数字，则允许容器使用那么多的 CPU 时间，直到 CPU 周期结束（可通过 --cpu-period 控制）。
在某些系统上，非 root 用户可能不允许更改资源限制。更多详情，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--cpuset-cpus=number¶
允许执行的 CPU。可以指定为逗号分隔的列表（例如 0,1），范围（例如 0-3），或两者的任意组合（例如 0-3,7,11-15）。
在某些系统上，非 root 用户可能不允许更改资源限制。更多详情，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--cpuset-mems=nodes¶
允许执行的内存节点（MEMs）（0-3, 0,1）。仅在 NUMA 系统上有效。
如果系统上有四个内存节点（0-3），使用 --cpuset-mems=0,1，则容器中的进程将只使用前两个内存节点的内存。
在某些系统上，非 root 用户可能不允许更改资源限制。更多详情，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--created-annotation¶
向镜像元数据中添加一个镜像注解（另见 --annotation），将“org.opencontainers.image.created”设置为当前时间，或者如果使用了 --source-date-epoch 或 --timestamp 标志，则设置为该标志指定的时间戳。如果为 false，则写入的镜像中将不存在此类注解。
注意：此信息在 Docker 镜像格式中不存在，因此在以 Docker 格式写入镜像时会被丢弃。
--creds=[username[:password]]¶
用于向镜像仓库进行身份验证的 [username[:password]]（如果需要）。如果未提供一个或两个值，则会出现命令行提示，可以输入该值。密码输入时无回显。
请注意，指定的凭据仅用于对目标仓库进行身份验证。它们不用于镜像源或当仓库被重写时（参见 containers-registries.conf(5)）；要对这些进行身份验证，请考虑使用 containers-auth.json(5) 文件。
--cw=options¶
生成一个适用于作为机密工作负载在可信执行环境（TEE）中使用 krun（即，启用了 libkrun 功能并作为 krun 调用的 crun）运行的镜像。与传统内容不同，镜像的根文件系统将包含一个加密的磁盘镜像和 krun 的配置信息。
options 的值是一个逗号分隔的 key=value 对列表，提供生成容器镜像中包含的附加数据所需的配置信息。
可识别的 keys 是：
attestation_url：密钥代理/证明服务器的位置。如果指定了值，新镜像的工作负载 ID 以及用于加密磁盘镜像的密码短语将注册到该服务器，并且服务器的位置将存储在容器镜像中。在运行时，krun 期望使用同样存储在容器镜像中的工作负载 ID 联系服务器以检索密码短语。如果未指定值，则必须指定一个 passphrase 值。
cpus：镜像期望在运行时使用的虚拟 CPU 数量。如果未指定，将提供一个默认值。
firmware_library：libkrunfw-sev 共享库的位置。如果未指定，buildah 会在多个硬编码位置检查其是否存在。
memory：镜像期望在运行时使用的内存量，以兆字节为单位的数字。如果未指定，将提供一个默认值。
passphrase：用于加密将包含在容器镜像中的磁盘镜像的密码短语。如果未指定值，但指定了 attestation_url 值，则将使用随机生成的密码短语。作者建议设置 attestation_url 但不设置 passphrase。
slop：与容器镜像内容大小相比，为磁盘镜像分配的额外空间，表示为百分比 (..%) 或大小值（字节，如果存在 KB 或 MB 等后缀，则为更大的单位），或两个或多个此类规范的总和。如果未指定，buildah 会猜测比内容多 25% 的空间就足够了，但提供此选项以防其猜测错误。
type：镜像应标记为使用的可信执行环境（TEE）类型。接受的值为“SEV”（AMD 安全加密虚拟化 - 加密状态）和“SNP”（AMD 安全加密虚拟化 - 安全嵌套分页）。如果未指定，默认为“SNP”。
workload_id：将记录在容器镜像中的工作负载标识符，用于在运行时检索用于加密磁盘镜像的密码短语。如果未指定，将从基础镜像的镜像 ID 派生一个半随机值。
此选项在远程客户端上不受支持，包括 Mac 和 Windows（不包括 WSL2）机器。
--decryption-key=key[:passphrase]¶
用于解密镜像的 [key[:passphrase]]。Key 可以指向密钥和/或证书。会尝试使用所有密钥进行解密。如果密钥受密码短语保护，则必须在参数中传递它，否则省略。
--device=host-device[:container-device][:permissions]¶
向容器添加一个主机设备。格式为 HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]，其中 HOST-DEVICE 是主机上的设备节点路径，CONTAINER-DEVICE 是容器内的设备节点路径，PERMISSIONS 是权限列表，组合了 'r'（读）、'w'（写）和 'm'（mknod(2)）。
示例：--device=/dev/sdc:/dev/xvdc:rwm。
注意：如果 host-device 是一个符号链接，则会首先解析它。容器只存储主机设备的主设备号和次设备号。
Podman 可能会加载使用指定设备所需的内核模块。Podman 在必要时加载模块的设备是：/dev/fuse。
在无根（rootless）模式下，新设备是从主机绑定挂载到容器中的，而不是由 Podman 在容器空间内创建。因为在 SELinux 系统上，绑定挂载会保留其 SELinux 标签，所以容器在访问挂载的设备时可能会遇到权限被拒绝的问题。可以通过以下命令修改 SELinux 设置，允许容器使用所有设备标签：
$ sudo setsebool -P container_use_devices=true
注意：如果用户仅通过组获得访问权限，则从无根容器内部访问设备会失败。crun(1) 运行时通过添加选项 --annotation run.oci.keep_original_groups=1 为此提供了解决方法。
--disable-compression, -D¶
在构建镜像时不压缩文件系统层，除非写入镜像的位置要求压缩。这是默认设置，因为镜像层在推送到镜像仓库时会自动压缩，而写入本地存储的镜像只需再次解压缩即可存储。可以通过指定 --disable-compression=false 在所有情况下强制压缩。
--disable-content-trust¶
这是一个 Docker 特定的选项，用于禁用对容器仓库的镜像验证，Podman 不支持此选项。此选项是一个空操作（NOOP），仅为脚本兼容性而提供。
--dns=ipaddr¶
设置自定义 DNS 服务器。
此选项可用于覆盖传递给容器的 DNS 配置。当主机 DNS 配置对容器无效时（例如 127.0.0.1），通常需要此选项。在这种情况下，每次运行时都需要 --dns 标志。
可以指定特殊值 none 来禁止 Podman 在容器中创建 /etc/resolv.conf。然后，镜像中的 /etc/resolv.conf 文件将不加修改地使用。
请注意，ipaddr 可能会直接添加到容器的 /etc/resolv.conf 中。但这并不能保证。例如，将 dns_enabled 设置为 true 的自定义网络传递给 --network 将导致 /etc/resolv.conf 仅引用 aardvark-dns 服务器。然后，aardvark-dns 会将所有非容器名称查询转发到提供的 ipaddr。
此选项不能与设置为 none 的 --network 结合使用。
注意：此选项仅在构建过程中的 RUN 指令期间生效。它不影响最终镜像中的 /etc/resolv.conf。
--dns-option=option¶
设置在构建期间使用的自定义 DNS 选项。
--dns-search=domain¶
设置在构建期间使用的自定义 DNS 搜索域。
--env=env[=value]¶
向构建的镜像添加一个值（例如 env=value）。可以多次使用。如果既没有指定 = 也没有指定 value，但 env 在当前环境中已设置，则会将当前环境中的值添加到镜像中。
要从构建的镜像中移除环境变量，请使用 --unsetenv 选项。
--file, -f=Containerfile¶
指定一个包含构建镜像指令的 Containerfile，可以是一个本地文件或一个 http 或 https URL。如果指定了多个 Containerfile，则只有最后一个指定的文件中的 FROM 指令会被接受。
如果未指定构建上下文，并且至少有一个 Containerfile 是本地文件，则其所在的目录将用作构建上下文。
指定选项 -f - 会导致从标准输入读取 Containerfile 内容。
--force-rm¶
总是在构建后移除中间容器，即使构建失败也是如此（默认为 true）。
--format¶
控制构建镜像的清单（manifest）和配置数据的格式。可识别的格式包括 oci (OCI image-spec v1.0，默认值) 和 docker (版本 2，清单使用 schema format 2)。
注意：您也可以通过设置 BUILDAH_FORMAT 环境变量来覆盖默认格式。export BUILDAH_FORMAT=docker
--from¶
覆盖 Containerfile 中的第一个 FROM 指令。如果 Containerfile 中有多个 FROM 指令，则只有第一个会被更改。
使用远程 podman 客户端时，并非所有容器传输方式都能按预期工作。例如，oci-archive:/x.tar 引用的是远程机器上的 /x.tar，而不是客户端上的。使用 podman 远程客户端时，最好限制使用 containers-storage 和 docker:// 传输方式。
--group-add=group | keep-groups¶
为在容器进程内运行的主用户分配额外的组。
keep-groups是一个特殊标志，告诉 Podman 保留补充组访问权限。
允许容器使用用户的补充组访问权限。如果文件系统或设备仅能由无根用户的组访问，此标志会告诉 OCI 运行时将组访问权限传递到容器中。目前仅适用于 crun OCI 运行时。注意：keep-groups 是排他性的，不能与其他组一起指定此标志。（不适用于远程命令，包括 Mac 和 Windows（不包括 WSL2）机器）
--help, -h¶
打印用法说明
--hooks-dir=path¶
路径中的每个 *.json 文件都为 buildah 构建的容器配置一个钩子。有关 JSON 文件的语法和钩子注入语义的更多详细信息。Buildah 目前支持 1.0.0 和 0.1.0 两种钩子模式，尽管 0.1.0 模式已被弃用。
此选项可以设置多次；来自后面选项的路径具有更高的优先级。
对于注解条件，buildah 使用生成的 OCI 配置中设置的任何注解。
对于绑定挂载条件，只考虑调用者通过 --volume 明确请求的挂载。buildah 默认插入的绑定挂载（例如 /dev/shm）不被考虑。
如果 root 调用者未设置 --hooks-dir，Buildah 目前默认使用 /usr/share/containers/oci/hooks.d 和 /etc/containers/oci/hooks.d，优先级递增。使用这些默认值已被弃用。请迁移到明确设置 --hooks-dir。
--http-proxy¶
默认情况下，如果为 Podman 进程设置了代理环境变量，则会将它们传递到容器中。这可以通过将值设置为 false 来禁用。传递的环境变量包括 http_proxy, https_proxy, ftp_proxy, no_proxy，以及这些变量的大写版本。此选项仅在主机系统必须使用代理而容器不使用任何代理时需要。以任何其他方式为容器指定的代理环境变量会覆盖从主机传递过来的值。（为容器指定代理的其他方式包括使用 --env 标志传递值，或在容器构建时硬编码代理环境。）当与远程客户端一起使用时，它使用在服务器进程上设置的代理环境变量。
默认为 true。
--identity-label¶
如果设置，则添加默认的身份标签 io.buildah.version。（默认为 true）。
--ignorefile¶
备用 .containerignore 文件的路径。
--iidfile=ImageIDfile¶
将构建的镜像 ID 写入文件。当多次指定 --platform 时，尝试使用此选项会触发错误。
--inherit-annotations=bool-value¶
从基础镜像或基础阶段继承注解。（默认为 true）。将此标志设置为 false 的用例可能也需要对 --created-annotation 标志执行相同的操作。
--inherit-labels¶
从基础镜像或基础阶段继承标签。（默认为 true）。
--ipc=how¶
设置处理 RUN 指令时 IPC 命名空间的配置。配置的值可以是“” (空字符串) 或 “container” 以指示创建新的 IPC 命名空间，也可以是 “host” 以指示重用 podman 本身正在运行的 IPC 命名空间，或者可以是另一个进程已经使用的 IPC 命名空间的路径。
--isolation=type¶
控制在执行 RUN 指令时运行进程所使用的隔离类型。可识别的类型包括 oci (OCI 兼容的运行时，默认值)、rootless (使用修改后的配置并启用其 --rootless 选项调用的 OCI 兼容运行时，在其 create 调用中添加了 --no-new-keyring --no-pivot，禁用了网络和 UTS 命名空间，并启用了 IPC、PID 和用户命名空间；非特权用户的默认值) 和 chroot (一个内部包装器，更倾向于 chroot(1) 而非容器技术)。
注意：您也可以通过设置 BUILDAH_ISOLATION 环境变量来覆盖默认的隔离类型。export BUILDAH_ISOLATION=oci
--jobs=number¶
并行运行最多 N 个并发阶段。如果作业数大于 1，则从 /dev/null 读取标准输入。如果指定为 0，则并行运行的作业数没有限制。
--label=label¶
向镜像元数据添加一个镜像标签（例如 label=value）。可以多次使用。
用户可以在 Containerfile 中设置一个特殊的 LABEL io.containers.capabilities=CAP1,CAP2,CAP3，它指定了容器正常运行所需的 Linux 权能列表。容器镜像中指定的这个标签告诉 Podman 只用这些权能来运行容器。只要这个权能列表是默认列表的子集，Podman 就会只用指定的权能来启动容器。
如果指定的权能不在默认集合中，Podman 会打印一条错误消息，并使用默认的权能运行容器。
--layer-label=label[=value]¶
向中间镜像元数据添加一个中间镜像标签（例如 label=value）。可以多次使用。
如果 label 已命名，但既没有提供 = 也没有提供 value，那么 label 将被设置为空值。
--layers¶
在构建过程中缓存中间镜像（默认为 true）。
注意：您也可以通过设置 BUILDAH_LAYERS 环境变量来覆盖默认的 layers 值。export BUILDAH_LAYERS=true
--logfile=filename¶
将发送到标准输出和标准错误的日志输出记录到指定文件，而不是标准输出和标准错误。此选项在远程客户端上不受支持，包括 Mac 和 Windows（不包括 WSL2）机器。
--logsplit=bool-value¶
如果指定了 --logfile 和 --platform，--logsplit 选项允许最终用户将每个平台的日志文件拆分到不同的文件中，格式如下：${logfile}_${platform-os}_${platform-arch}。此选项在远程客户端上不受支持，包括 Mac 和 Windows（不包括 WSL2）机器。
--manifest=manifest¶
要将镜像添加到的清单列表的名称。如果清单列表不存在，则创建它。此选项对于构建多架构镜像很有用。
--memory, -m=number[unit]¶
内存限制。unit 可以是 b (字节)，k (千字节)，m (兆字节)，或 g (吉字节)。
允许限制容器可用的内存。如果主机支持交换内存，那么 --m 内存设置可以大于物理内存。如果指定限制为 0（不使用 --m），则容器的内存不受限制。实际限制可能会向上舍入到操作系统页面大小的倍数（该值非常大，数百万万亿）。
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--memory-swap=number[unit]¶
一个等于内存加交换空间的限制值。unit 可以是 b (字节)，k (千字节)，m (兆字节)，或 g (吉字节)。
必须与 -m (--memory) 标志一起使用。参数值必须大于 -m (--memory) 的值。默认情况下，它被设置为 --memory 值的两倍。
将 number 设置为 -1 以启用无限制的交换空间。
在 cgroups V1 的无根（rootless）系统上不支持此选项。
--network=mode, --net¶
设置处理 RUN 指令时网络命名空间的配置。
有效的 mode 值为：
none：无网络。
host：使用 Podman 主机网络栈。注意：host 模式赋予容器对本地系统服务（如 D-bus）的完全访问权限，因此被认为是不安全的。
ns:path：要加入的网络命名空间的路径。
private：为容器创建一个新的命名空间（默认）
<network name|ID>：加入具有给定名称或 ID 的网络，例如使用
--network mynet加入名为 mynet 的网络。仅支持有根用户。slirp4netns[:OPTIONS,…]：使用 slirp4netns(1) 创建用户网络栈。可以指定这些附加选项，它们也可以通过 containers.conf 中的
network_cmd_options设置。allow_host_loopback=true|false：允许 slirp4netns 访问主机回环 IP（默认为 10.0.2.2 或当更改 slirp4netns cidr 子网时的第二个 IP，见下面的 cidr 选项）。默认为 false。
mtu=MTU：指定此网络使用的 MTU。（默认为
65520）。cidr=CIDR：指定此网络使用的 IP 范围。（默认为
10.0.2.0/24）。enable_ipv6=true|false：启用 IPv6。默认为 true。（
outbound_addr6需要）。outbound_addr=INTERFACE：指定 slirp 绑定的出站接口（仅限 ipv4 流量）。
outbound_addr=IPv4：指定 slirp 绑定的出站 ipv4 地址。
outbound_addr6=INTERFACE：指定 slirp 绑定的出站接口（仅限 ipv6 流量）。
outbound_addr6=IPv6：指定 slirp 绑定的出站 ipv6 地址。
pasta[:OPTIONS,…]：使用 pasta(1) 创建一个用户模式的网络栈。
这是无根容器的默认设置，并且仅在无根模式下受支持。
默认情况下，IPv4 和 IPv6 地址和路由，以及 pod 接口名称，都从主机复制。如果未配置端口转发，则在任一侧（init 命名空间或容器命名空间）绑定服务时，端口会动态转发。端口转发会保留原始源 IP 地址。pasta(1) 中描述的选项可以作为逗号分隔的参数指定。
就 pasta(1) 选项而言，默认情况下会给出 --config-net，以便在容器启动时配置网络，并且默认情况下也假定 --no-map-gw，以避免容器使用网关地址直接访问主机。后者可以通过在 pasta 特定选项中传递 --map-gw 来覆盖（尽管它不是一个实际的 pasta(1) 选项）。
此外，会传递 -t none 和 -u none 来禁用基于绑定端口的自动端口转发。类似地，会给出 -T none 和 -U none 来禁用从容器到主机的相同功能。
一些示例：pasta:--map-gw：允许容器使用网关地址直接访问主机。
pasta:--mtu,1500：为容器中的 tap 接口指定一个 1500 字节的 MTU。
pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp，等同于默认的 slirp4netns(1) 选项：禁用 IPv6，将
10.0.2.0/24分配给容器中的tap0接口，网关为10.0.2.3，启用可在10.0.2.3访问的 DNS 转发器，将 MTU 设置为 1500 字节，禁用 NDP、DHCPv6 和 DHCP 支持。pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp，等同于带有 Podman 覆盖的默认 slirp4netns(1) 选项：与上面相同，但将 MTU 保留为 65520 字节
pasta:-t,auto,-u,auto,-T,auto,-U,auto：启用基于从主机和容器两侧观察到的绑定端口的自动端口转发
pasta:-T,5201：启用从容器到主机的 TCP 端口 5201 的转发，使用回环接口而不是 tap 接口以提高性能
--no-cache¶
不使用现有的缓存镜像进行容器构建。从头开始使用一组新的缓存层进行构建。
--no-hostname¶
不在容器中创建 /etc/hostname 文件。
默认情况下，Podman 管理 /etc/hostname 文件，添加容器自己的主机名。当设置 --no-hostname 选项时，如果镜像的 /etc/hostname 文件存在，它将保持不变。
--no-hosts¶
不修改容器中的 /etc/hosts 文件。
Podman 默认控制容器的 /etc/hosts 文件，并为容器名称（见 --name 选项）和主机名（见 --hostname 选项）、内部主机 host.containers.internal 和 host.docker.internal，以及任何使用 --add-host 选项添加的主机名添加条目。有关详细信息，请参阅 --add-host 选项。传递 --no-hosts 会禁用此功能，因此镜像的 /etc/hosts 文件将保持不变。通过在 containers.conf 中设置 no_hosts=true 也可以实现全局相同的效果。
此选项与 --add-host 冲突。
--omit-history¶
在构建的镜像中省略构建历史信息。（默认为 false）。
当最终用户明确希望设置 --omit-history 以从构建的镜像中省略可选的 History 时，或者在使用不包含 History 信息的构建工具构建的镜像时，此选项非常有用。
--os=string¶
将要构建的镜像的操作系统，以及如果构建使用基础镜像时要拉取的基础镜像的操作系统，设置为提供的值，而不是使用构建主机的当前操作系统。除非被覆盖，否则后续在本地存储中对同一镜像的查找将匹配此操作系统，而不管主机如何。
--os-feature=feature¶
为所构建的镜像设置所需的操作系统特性的名称。默认情况下，如果镜像不是基于 scratch，则会保留基础镜像所需的操作系统特性列表（如果基础镜像指定了任何特性）。此选项通常仅在镜像的操作系统为 Windows 时有意义。
如果 feature 带有后缀 -，则该 feature 将从镜像中列出的所需特性集中移除。
--os-version=version¶
为所构建的镜像设置确切的所需操作系统版本。默认情况下，如果镜像不是基于 scratch，则会保留基础镜像所需的操作系统版本（如果基础镜像指定了一个）。此选项通常仅在镜像的操作系统为 Windows 时有意义，并且通常在 Windows 基础镜像中设置，因此通常不需要使用此选项。
--output, -o=output-opts¶
输出目的地 (格式: type=local,dest=path)
--output (或 -o) 选项扩展了构建容器镜像的默认行为，允许用户将镜像内容导出为本地文件系统上的文件，这对于生成本地二进制文件、代码生成等非常有用。（此选项在远程 Podman 客户端上不可用，包括 Mac 和 Windows（不包括 WSL2）机器）
--output 的值是一个逗号分隔的 key=value 对序列，定义了输出类型和选项。
支持的 keys 是：
dest：导出输出的目标路径。有效值为绝对或相对路径，
-表示标准输出。type：定义要使用的输出类型。有效值如下所述。
有效的 type 值为：
local：将生成的构建文件写入客户端的目录。
tar：将生成的文件写成一个 tarball (.tar)。
如果未指定类型，则该值默认为 local。或者，--output 的值可以只是一个目的地（以 dest 格式）（例如 --output some-path, --output -），其中 --output some-path 被视为 type=local，而 --output - 被视为 type=tar。
--pid=pid¶
设置处理 RUN 指令时 PID 命名空间的配置。配置的值可以是“” (空字符串) 或 “container” 以指示创建新的 PID 命名空间，也可以是 “host” 以指示重用 podman 本身正在运行的 PID 命名空间，或者可以是另一个进程已经使用的 PID 命名空间的路径。
--platform=os/arch[/variant][,…]¶
将构建的镜像（以及其基础镜像，如果使用的话）的 os/arch 设置为提供的值，而不是使用主机的当前操作系统和架构（例如 linux/arm）。除非被覆盖，否则后续在本地存储中对同一镜像的查找将匹配此平台，而不管主机如何。
如果设置了 --platform，则会覆盖 --arch、--os 和 --variant 选项的值。
--platform 选项可以多次指定，或者给出一个逗号分隔的值列表作为其参数。当指定多个平台时，将使用 --manifest 选项而不是 --tag 选项。
Os/arch 对是 Go 编程语言使用的那些。在某些情况下，平台的 arch 值与 arch 命令等其他工具产生的值不同。有效的操作系统和架构名称组合列为 $GOOS 和 $GOARCH 的值，可在 https://golang.ac.cn/doc/install/source#environment 找到，也可以通过运行 go tool dist list 找到。
虽然 podman build 乐于为任何存在的平台使用基础镜像和构建镜像，但如果没有 qemu-user-static 等软件包提供的仿真帮助，RUN 指令将无法成功。
--pull=policy¶
拉取镜像策略。默认为 missing。
always：总是拉取镜像，如果拉取失败则抛出错误。
missing：仅在本地容器存储中不存在镜像时才拉取。如果找不到镜像且拉取失败，则抛出错误。
never：从不拉取镜像，而是使用本地容器存储中的镜像。如果找不到镜像，则抛出错误。
newer：如果仓库中的镜像比本地容器存储中的镜像新，则拉取。当摘要不同时，镜像被认为是更新的。比较时间戳容易出错。如果找到了本地镜像，则会抑制拉取错误。
--quiet, -q¶
抑制指示正在处理哪个指令的输出消息，以及从仓库拉取镜像和写入输出镜像时的进度消息。
--retry=attempts¶
在仓库和本地存储之间拉取或推送镜像失败时重试的次数。默认为 3。
--retry-delay=duration¶
在仓库和本地存储之间拉取或推送镜像失败时重试尝试之间的延迟时间。默认是从两秒开始，然后指数退避。设置此值时将使用该延迟，并且不会发生指数退避。
--rewrite-timestamp¶
在为镜像生成新层时，确保任何新添加的内容的时间戳不晚于 --source-date-epoch 标志使用的值（如果提供了的话），方法是将任何晚于该值的时间戳替换为该值。
--rm¶
在成功构建后移除中间容器（默认为 true）。
--runtime=path¶
备用 OCI 兼容运行时的路径，用于运行 RUN 指令指定的命令。
注意：您也可以通过设置 BUILDAH_RUNTIME 环境变量来覆盖默认运行时。export BUILDAH_RUNTIME=/usr/local/bin/runc
--runtime-flag=flag¶
为容器运行时添加全局标志。要列出支持的标志，请查阅所选容器运行时的手册页。
注意：不要将前导的 -- 传递给标志。要将 runc 标志 --log-format json 传递给 buildah build，给出的选项是 --runtime-flag log-format=json。
--sbom=preset¶
通过使用指定的扫描器镜像、扫描器命令和合并策略的组合扫描工作容器和构建上下文，为输出镜像生成 SBOM（软件物料清单）。必须与 --sbom-image-output、--sbom-image-purl-output、--sbom-output 和 --sbom-purl-output 中的一个或多个一起指定。可识别的预设及其等效的选项集：
“syft”, “syft-cyclonedx”: --sbom-scanner-image=ghcr.io/anchore/syft --sbom-scanner-command=”/syft scan -q dir:{ROOTFS} --output cyclonedx-json={OUTPUT}” --sbom-scanner-command=”/syft scan -q dir:{CONTEXT} --output cyclonedx-json={OUTPUT}” --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version
“syft-spdx”: --sbom-scanner-image=ghcr.io/anchore/syft --sbom-scanner-command=”/syft scan -q dir:{ROOTFS} --output spdx-json={OUTPUT}” --sbom-scanner-command=”/syft scan -q dir:{CONTEXT} --output spdx-json={OUTPUT}” --sbom-merge-strategy=merge-spdx-by-package-name-and-versioninfo
“trivy”, “trivy-cyclonedx”: --sbom-scanner-image=ghcr.io/aquasecurity/trivy --sbom-scanner-command=”trivy filesystem -q {ROOTFS} --format cyclonedx --output {OUTPUT}” --sbom-scanner-command=”trivy filesystem -q {CONTEXT} --format cyclonedx --output {OUTPUT}” --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version
“trivy-spdx”: --sbom-scanner-image=ghcr.io/aquasecurity/trivy --sbom-scanner-command=”trivy filesystem -q {ROOTFS} --format spdx-json --output {OUTPUT}” --sbom-scanner-command=”trivy filesystem -q {CONTEXT} --format spdx-json --output {OUTPUT}” --sbom-merge-strategy=merge-spdx-by-package-name-and-versioninfo
--sbom-image-output=path¶
生成 SBOM 时，将生成的 SBOM 存储在输出镜像中的指定路径。没有默认值。
--sbom-image-purl-output=path¶
生成 SBOM 时，扫描它们以获取 PURL（package URL）信息，并将找到的 PURL 列表保存到输出镜像中的指定路径。没有默认值。
--sbom-merge-strategy=method¶
如果使用了多个 --sbom-scanner-command 值，请使用指定的方法将后续命令的输出与先前命令的输出合并。可识别的值包括：
cat 连接文件。
merge-cyclonedx-by-component-name-and-version 合并 JSON 文档的“component”字段，当文档的“name”和“version”值组合已存在时，忽略该文档的值。文档按其生成顺序处理，即生成它们的命令被指定的顺序。
merge-spdx-by-package-name-and-versioninfo 合并 JSON 文档的“package”字段，当文档的“name”和“versionInfo”值组合已存在时，忽略该文档的值。文档按其生成顺序处理，即生成它们的命令被指定的顺序。
--sbom-output=file¶
生成 SBOM 时，将生成的 SBOM 存储在本地文件系统上的指定文件中。没有默认值。
--sbom-purl-output=file¶
生成 SBOM 时，扫描它们以获取 PURL（package URL）信息，并将找到的 PURL 列表保存到本地文件系统中的指定文件中。没有默认值。
--sbom-scanner-command=image¶
通过运行扫描器镜像中的指定命令来生成 SBOM。如果指定了多个命令，它们将按照指定的顺序运行。会执行以下文本替换：
{ROOTFS} 构建镜像文件系统的根目录，以绑定挂载方式挂载。
{CONTEXT} 构建上下文和其他构建上下文，以绑定挂载方式挂载。
{OUTPUT} 一个临时输出文件的名称，将被读取并与其他文件合并或复制到别处。
--sbom-scanner-image=image¶
使用指定的扫描器镜像生成 SBOM。
--secret=id=id[,src=envOrFile][,env=ENV][,type=file | env]¶
以安全的方式传递用于在 Containerfile 中构建镜像的秘密信息，这些信息最终不会存储在最终镜像中，也不会在其他阶段被看到。秘密的值将从“id”选项指定的、或“src”选项（如果已指定）命名的环境变量或文件中读取，或者从“env”选项指定的环境变量中读取。请参阅示例。默认情况下，该秘密将挂载在容器的 /run/secrets/id 路径下。
要稍后使用该秘密，请在 Containerfile 的 RUN 指令中使用 --mount 标志。
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
可以使用 RUN --mount 标志的“target”、“dst”或“destination”选项来覆盖秘密在容器中的位置。
RUN --mount=type=secret,id=mysecret,target=/run/secrets/myothersecret cat /run/secrets/myothersecret
注意：更改秘密文件的内容不会触发使用这些秘密的层的重建。
--security-opt=option¶
安全选项
apparmor=unconfined：关闭容器的 apparmor 限制。apparmor=alternate-profile：为容器设置 apparmor 限制配置文件。label=user:USER：为容器进程设置标签用户。label=role:ROLE：为容器进程设置标签角色。label=type:TYPE：为容器进程设置标签进程类型。label=level:LEVEL：为容器进程设置标签级别。label=filetype:TYPE：为容器文件设置标签文件类型。label=disable：关闭容器的标签分离。no-new-privileges：禁止容器进程获得额外权限。seccomp=unconfined：关闭容器的 seccomp 限制。seccomp=profile.json：用作容器 seccomp 过滤器的 JSON 文件。
--shm-size=number[unit]¶
/dev/shm 的大小。unit 可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。如果省略单位，系统将使用字节。如果省略大小，默认为 64m。当 size 为 0 时，用于 IPC 的内存量没有限制。此选项与 --ipc=host 冲突。
--sign-by=fingerprint¶
使用具有指定 FINGERPRINT 的 GPG 密钥对镜像进行签名。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）。
--skip-unused-stages¶
在多阶段构建中跳过不影响目标阶段的阶段。（默认：true）。
--source-date-epoch=seconds¶
将构建的镜像的“created”时间戳设置为自纪元（Unix 时间 0，即 1970 年 1 月 1 日 00:00:00 UTC）以来的秒数（默认是使用 SOURCE_DATE_EPOCH 环境变量中设置的值，如果未设置，则使用当前时间）。
在提交镜像时，“created”时间戳会写入镜像的配置和清单中，因此即使 Containerfile 和构建上下文没有其他更改，两次不同的构建通常也会产生具有不同 sha256 哈希值的镜像。
设置此标志后，一个 SOURCE_DATE_EPOCH 构建参数将为其声明的阶段提供其值。
设置此标志后，镜像配置的“created”时间戳总是设置为指定的时间，这应该允许在不同时间使用相同的输入集构建相同的镜像。
设置此标志后，写入到 --output 标志指定位置的输出将带有确切指定的时间戳。
与类似的 --timestamp 标志冲突，后者也会将其指定的时间设置到新层的内容上。
--squash¶
将镜像的所有新层压缩成一个单一的新层；任何预先存在的层都不会被压缩。
--squash-all¶
将新镜像的所有层（包括从基础镜像继承的层）压缩成一个单一的新层。
--ssh=default | id[=socket>¶
要暴露给构建过程的 SSH 代理套接字或密钥。套接字路径可以留空以使用 default=$SSH_AUTH_SOCK 的值。
要稍后使用 ssh 代理，请在 Containerfile 的 RUN 指令中使用 --mount 选项。
RUN --mount=type=ssh,id=id mycmd
--stdin¶
将 stdin 传递给 RUN 容器。有时在 Containerfile 中运行的命令希望向用户请求信息。例如，apt 在安装时请求确认。使用 --stdin 可以在构建过程中从终端进行交互。
--tag, -t=imageName¶
指定如果构建过程成功完成，分配给结果镜像的名称。如果 imageName 不包含注册表名称，则注册表名称 localhost 会被前置到镜像名称中。
--target=stageName¶
设置要构建的目标构建阶段。当构建具有多个构建阶段的 Containerfile 时，可以使用 --target 按名称指定一个中间构建阶段作为结果镜像的最终阶段。目标阶段之后的命令将被跳过。
--timestamp=seconds¶
将创建时间戳设置为自纪元以来的秒数，以允许确定性构建（默认为当前时间）。默认情况下，每次提交时，创建时间戳都会被更改并写入镜像清单，这会导致镜像的 sha256 哈希值不同，即使源文件完全相同。当设置了 --timestamp 时，创建时间戳总是设置为指定的时间，因此不会改变，从而允许镜像的 sha256 哈希值保持不变。提交到镜像层的所有文件都将使用该时间戳创建。
如果 Containerfile 中唯一的指令是 FROM，则此标志无效。
--tls-verify¶
在联系注册表时需要 HTTPS 并验证证书（默认：true）。如果明确设置为 true，则使用 TLS 验证。如果设置为 false，则不使用 TLS 验证。如果未指定，则使用 TLS 验证，除非目标注册表在 containers-registries.conf(5) 中被列为不安全注册表。
--ulimit=type=soft-limit[:hard-limit]¶
指定在处理 RUN 指令时应用于启动的进程的资源限制。此选项可以指定多次。可识别的资源类型包括：“core”：最大核心转储大小（ulimit -c）；“cpu”：最大 CPU 时间（ulimit -t）；“data”：进程数据段的最大大小（ulimit -d）；“fsize”：新文件的最大大小（ulimit -f）；“locks”：最大文件锁数量（ulimit -x）；“memlock”：最大锁定内存量（ulimit -l）；“msgqueue”：消息队列中的最大数据量（ulimit -q）；“nice”：nice 值调整（nice -n, ulimit -e）；“nofile”：最大打开文件数（ulimit -n）；“nproc”：最大进程数（ulimit -u）；“rss”：进程的最大大小（ulimit -m）；“rtprio”：最大实时调度优先级（ulimit -r）；“rttime”：阻塞 syscall 之间的最大实时执行时间量；“sigpending”：最大待处理信号数（ulimit -i）；“stack”：最大堆栈大小（ulimit -s）。
--unsetannotation=annotation¶
取消设置镜像注解，使该注解不会从基础镜像继承。
--unsetenv=env¶
从最终镜像中取消设置环境变量。
--unsetlabel=label¶
取消设置镜像标签，使该标签不会从基础镜像继承。
--userns=how¶
设置处理 RUN 指令时用户命名空间的配置。配置值可以是“” (空字符串) 或 “container” 以表示创建一个新的用户命名空间，可以是 “host” 以表示重用 podman 自身运行的用户命名空间，也可以是另一个进程已经使用的用户命名空间的路径。
--userns-gid-map=mapping¶
直接指定一个 GID 映射，用于在文件系统级别设置工作容器内容的属主关系。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。
此映射中的条目采用一个或多个三元组的形式：起始的容器内 GID、对应的主机级别起始 GID，以及该映射条目所代表的连续 ID 数量。
此选项会覆盖 /etc/containers/storage.conf 中 options 部分的 remap-gids 设置。
如果未指定此选项，但提供了全局的 --userns-gid-map 设置，则将使用全局选项的设置。
如果 --userns-uid-map-user、--userns-gid-map-group 或 --userns-gid-map 均未指定，但指定了 --userns-uid-map，则 GID 映射将被设置为使用与 UID 映射相同的数值。
--userns-gid-map-group=group¶
指定一个 GID 映射，用于在文件系统级别上设置工作容器内容的属主关系，该映射可以在 /etc/subgid 文件中与指定组对应的条目中找到。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。如果指定了 --userns-uid-map-user 但未指定 --userns-gid-map-group，podman 会假定指定的用户名也是一个合适的组名，用作此选项的默认设置。
注意：当此选项由无根用户指定时，指定的映射是相对于容器内的无根用户命名空间，而不是像以 root 身份运行时那样相对于主机。
--userns-uid-map=mapping¶
直接指定一个 UID 映射，用于在文件系统级别设置工作容器内容的属主关系。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。
此映射中的条目采用一个或多个三元组的形式：起始的容器内 UID、对应的主机级别起始 UID，以及该映射条目所代表的连续 ID 数量。
此选项会覆盖 /etc/containers/storage.conf 中 options 部分的 remap-uids 设置。
如果未指定此选项，但提供了全局的 --userns-uid-map 设置，则将使用全局选项的设置。
如果 --userns-uid-map-user、--userns-gid-map-group 或 --userns-uid-map 均未指定，但指定了 --userns-gid-map，则 UID 映射将被设置为使用与 GID 映射相同的数值。
--userns-uid-map-user=user¶
指定一个 UID 映射，用于在文件系统级别上设置工作容器内容的属主关系，该映射可以在 /etc/subuid 文件中与指定用户对应的条目中找到。处理 RUN 指令时运行的命令默认在它们自己的用户命名空间中运行，使用 UID 和 GID 映射进行配置。如果指定了 --userns-gid-map-group 但未指定 --userns-uid-map-user，podman 会假定指定的组名也是一个合适的用户名，用作此选项的默认设置。
注意：当此选项由无根用户指定时，指定的映射是相对于容器内的无根用户命名空间，而不是像以 root 身份运行时那样相对于主机。
--uts=how¶
设置处理 RUN 指令时 UTS 命名空间的配置。配置值可以是“” (空字符串) 或 “container” 以表示创建一个新的 UTS 命名空间，也可以是 “host” 以表示重用 podman 自身运行的 UTS 命名空间，还可以是另一个进程已经使用的 UTS 命名空间的路径。
--variant=VARIANT¶
将要构建的镜像的架构变体，以及如果构建使用了基础镜像，则要拉取的基础镜像的架构变体，设置为提供的值，而不是使用构建主机的架构变体。
--volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]¶
在构建过程中执行 RUN 指令时，将主机目录挂载到容器中。
OPTIONS 是一个逗号分隔的列表，可以是一个或多个：
[rw|ro]
[z|Z|O]
[U]
[
[r]shared|[r]slave|[r]private][1]
CONTAINER-DIR 必须是绝对路径，例如 /src/docs。HOST-DIR 也必须是绝对路径。Podman 在处理 RUN 指令时会将 HOST-DIR 绑定挂载到指定路径。
您可以指定多个 -v 选项来挂载一个或多个挂载点。
您可以在卷上添加 :ro 或 :rw 后缀，分别以只读或读写模式挂载。默认情况下，卷以读写模式挂载。请参阅示例。
Chowning Volume Mounts（更改卷挂载的属主）
默认情况下，Podman 不会更改挂载的源卷目录的所有者和组。当使用用户命名空间运行时，命名空间内的 UID 和 GID 可能对应于主机上的另一个 UID 和 GID。
:U 后缀告诉 Podman 根据命名空间内的 UID 和 GID 使用正确的主机 UID 和 GID，以递归方式更改源卷的所有者和组。
警告：请谨慎使用，因为这会修改主机文件系统。
Labeling Volume Mounts（为卷挂载添加标签）
像 SELinux 这样的标签系统要求在挂载到容器中的卷内容上放置正确的标签。没有标签，安全系统可能会阻止容器内运行的进程使用这些内容。默认情况下，Podman 不会更改操作系统设置的标签。
要在容器上下文中更改标签，请向卷挂载添加这两个后缀之一：:z 或 :Z。这些后缀告诉 Podman 重新标记共享卷上的文件对象。z 选项告诉 Podman 两个容器共享卷内容。因此，Podman 会用共享内容标签来标记内容。共享卷标签允许所有容器读写内容。Z 选项告诉 Podman 用私有非共享标签来标记内容。只有当前容器可以使用私有卷。
注意：不要重新标记系统文件和目录。重新标记系统内容可能会导致主机上其他受限服务失败。对于这类容器，建议禁用 SELinux 分离。选项 --security-opt label=disable 会禁用容器的 SELinux 分离。例如，如果用户想将他们的整个主目录挂载到构建容器中，他们需要禁用 SELinux 分离。
$ podman build --security-opt label=disable -v $HOME:/home/user .
Overlay Volume Mounts（覆盖卷挂载）
:O 标志告诉 Podman 使用 Overlay 文件系统将主机上的目录作为临时存储挂载。RUN 命令容器被允许修改挂载点内的内容，这些内容存储在容器存储的一个单独目录中。用 Overlay FS 的术语来说，源目录是 lower 层，而容器存储目录是 upper 层。对挂载点的修改在 RUN 命令执行完毕后会被销毁，类似于 tmpfs 挂载点。
任何后续的 RUN 命令执行都会看到原始的源目录内容，之前 RUN 命令所做的任何更改都不再存在。
overlay 挂载的一个用例是将主机的软件包缓存共享到容器中，以加快构建速度。
注意
覆盖挂载目前在无根模式下不受支持。
O标志不允许与Z或z标志一起指定。挂载到容器中的内容会被标记为私有标签。在 SELinux 系统上，源目录中的标签需要能被容器标签读取。如果不能，则必须为容器禁用 SELinux 容器分离才能工作。修改使用覆盖挂载挂载到容器中的目录卷可能会导致意外失败。在容器运行结束之前，不要修改该目录。
默认情况下，绑定挂载的卷是 private（私有的）。这意味着在容器内进行的任何挂载在主机上都不可见，反之亦然。可以通过指定卷挂载传播属性来改变此行为。
当挂载传播策略设置为 shared（共享）时，在该卷上容器内完成的任何挂载对主机和容器都可见。当挂载传播策略设置为 slave（从属）时，启用单向挂载传播，主机上为该卷完成的任何挂载仅在容器内部可见。要控制卷的挂载传播属性，请使用 :[r]shared、:[r]slave 或 :[r]private 传播标志。要使挂载传播在源挂载点（源目录挂载在其上的挂载点）上起作用，该挂载点必须具有正确的传播属性。对于共享卷，源挂载点必须是共享的。对于从属卷，源挂载点必须是共享或从属的。[1]
使用 df <source-dir> 来确定源挂载点，然后使用 findmnt -o TARGET,PROPAGATION <source-mount-dir> 来确定源挂载点的传播属性。如果 findmnt 工具不可用，可以通过查看 /proc/self/mountinfo 中的挂载条目来确定源挂载点。查看 optional fields（可选字段）并检查是否指定了任何传播属性。shared:X 表示挂载是 shared（共享的），master:X 表示挂载是 slave（从属的），如果什么都没有，则表示挂载是 private（私有的）。[1]
要更改挂载点的传播属性，请使用 mount 命令。例如，要绑定挂载源目录 /foo，请执行 mount --bind /foo /foo 和 mount --make-private --make-shared /foo。这将 /foo 转换为一个 shared（共享）挂载点。源挂载点的传播属性可以直接更改。例如，如果 / 是 /foo 的源挂载点，则使用 mount --make-shared / 将 / 转换为一个 shared（共享）挂载。
示例¶
使用本地 Containerfile 构建镜像¶
使用当前目录内容的 Containerfile 构建镜像
$ podman build .
使用指定的 Containerfile 和当前目录的内容构建镜像
$ podman build -f Containerfile.simple .
使用来自 stdin 的 Containerfile 和当前目录的内容构建镜像
$ cat $HOME/Containerfile | podman build -f - .
使用多个 Containerfile 和当前目录的内容构建镜像
$ podman build -f Containerfile.simple -f Containerfile.notsosimple .
使用指定的 Containerfile 和 $HOME 目录的内容构建镜像。注意，在作为 Containerfile 处理之前，cpp 会应用于 Containerfile.in
$ podman build -f Containerfile.in $HOME
使用指定的标签、Containerfile 和当前目录的内容构建镜像
$ podman build -t imageName .
构建镜像时忽略通过 Containerfile 拉取的任何镜像的注册表验证
$ podman build --tls-verify=false -t imageName .
使用指定的日志记录格式构建镜像
$ podman build --runtime-flag log-format=json .
使用调试模式进行日志记录来构建镜像
$ podman build --runtime-flag debug .
从选定的 Containerfile 拉取镜像时，使用指定的注册表属性构建镜像
$ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .
在构建过程中运行容器时，使用指定的资源控制来构建镜像
$ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
在构建过程中运行容器时，使用指定的 SELinux 标签和 cgroup 配置来构建镜像
$ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
构建镜像时，将来自主机的只读且经过 SELinux 重新标记的卷挂载到正在运行的容器中
$ podman build --volume /home/test:/myvol:ro,Z -t imageName .
构建镜像时，将来自主机的覆盖卷挂载到正在运行的容器中
$ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
使用层构建镜像，然后在构建失败时也移除中间容器。
$ podman build --layers --force-rm -t imageName .
构建镜像时忽略缓存，并且即使构建成功也不移除中间容器
$ podman build --no-cache --rm=false -t imageName .
在构建过程中运行容器时，使用指定的网络来构建镜像
$ podman build --network mynet .
使用存储在名为 mysecret 的环境变量或文件中的秘密来构建一个镜像，该秘密将与指令 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret 一起使用
$ podman build --secret=id=mysecret .
使用存储在名为 MYSECRET 的环境变量中的秘密来构建一个镜像，该秘密将与指令 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret 一起使用
$ podman build --secret=id=mysecret,env=MYSECRET .
$ podman build --secret=id=mysecret,src=MYSECRET,type=env .
使用存储在名为 .mysecret 的文件中的秘密来构建一个镜像，该秘密将与指令 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret 一起使用
$ podman build --secret=id=mysecret,src=.mysecret .
$ podman build --secret=id=mysecret,src=.mysecret,type=file .
使用 --manifest 选项构建多架构镜像（需要仿真软件）¶
使用指定的架构构建镜像，并在成功完成后链接到一个单一的清单
$ podman build --arch arm --manifest myimage /tmp/mysrc
$ podman build --arch amd64 --manifest myimage /tmp/mysrc
$ podman build --arch s390x --manifest myimage /tmp/mysrc
同样地，使用单个命令构建
$ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
使用多个指定的架构构建镜像，并在成功完成后链接到单一的清单
$ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
使用 URL、Git 仓库或归档文件构建镜像¶
构建上下文目录可以指定为一个指向 Containerfile 的 URL、一个 Git 仓库或一个指向归档文件的 URL。如果 URL 是一个 Containerfile，它将被下载到临时位置并用作上下文。当一个 Git 仓库被设置为 URL 时，该仓库会被本地克隆到临时位置，然后用作上下文。最后，如果 URL 是一个归档文件，它会被下载到临时位置并解压，然后用作上下文。
使用指向 Containerfile 的 URL 构建镜像¶
从下载到临时位置的 Containerfile 构建镜像，该位置用作构建上下文
$ podman build https://10.10.10.1/podman/Containerfile
使用 Git 仓库构建镜像¶
Podman 将指定的 GitHub 仓库克隆到临时位置，并将其用作上下文。将使用仓库根目录下的 Containerfile，这仅在 GitHub 仓库是专用仓库时才有效。
从下载到临时位置的指定 git 仓库构建镜像，该位置用作构建上下文
$ podman build -t hello https://github.com/containers/PodmanHello.git
$ podman run hello
注意：由于最近的安全指南变更（https://github.blog/2021-09-01-improving-git-protocol-security-github/），GitHub 不支持使用 git:// 来执行 clone 操作。如果源仓库托管在 GitHub 上，请使用 https:// URL。
使用指向归档文件的 URL 构建镜像¶
Podman 获取归档文件，解压缩它，并将其内容用作构建上下文。归档文件根目录下的 Containerfile 和归档文件的其余部分被用作构建的上下文。同时传递 -f PATH/Containerfile 选项会告诉系统在归档文件内容中查找该文件。
$ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
注意：支持的压缩格式有‘xz’、‘bzip2’、‘gzip’和‘identity’（无压缩）。
文件¶
.containerignore/.dockerignore¶
如果上下文目录中存在 .containerignore 或 .dockerignore 文件，podman build 会读取其内容。使用 --ignorefile 选项可以覆盖 .containerignore 的路径位置。Podman 使用其内容在 Containerfile/Dockerfile 中执行 COPY 和 ADD 指令时，从上下文目录中排除文件和目录。
.containerignore 和 .dockerignore 文件使用相同的语法；如果两者都在上下文目录中，podman build 只会使用 .containerignore。
用户可以在 .containerignore 文件中指定一系列 Unix shell glob 模式来识别要排除的文件/目录。
Podman 支持一个特殊的通配符字符串 **，它可以匹配任意数量的目录（包括零个）。例如，**/*.go 会排除在所有目录中找到的所有以 .go 结尾的文件。
示例 .containerignore 文件
# exclude this content for image
*/*.c
**/output*
src
*/*.c 排除任何顶层子目录中名称以 .c 结尾的文件和目录。例如，源文件 include/rootless.c。
**/output* 排除任何目录中以 output 开头的文件和目录。
src 排除名为 src 的文件和目录 src 以及其中的任何内容。
以 ! (感叹号) 开头的行可用于创建排除的例外。以下是一个使用此机制的 .containerignore 文件示例：
*.doc
!Help.doc
从镜像中排除所有 doc 文件，除了 Help.doc。
此功能与此处描述的 .containerignore 文件处理兼容：containerignore(5)
registries.conf (/etc/containers/registries.conf)¶
registries.conf 是一个配置文件，它指定在补全不包含注册表或域部分的镜像名称时应查询哪些容器注册表。请参阅 containers-registries.conf(5)
故障排除¶
lastlog 稀疏文件¶
在 Containerfile 中使用带有大 UID/GID 的 useradd 命令会创建一个大的稀疏文件 /var/log/lastlog。这可能导致构建永久挂起。Go 语言不能正确支持稀疏文件，这可能导致在容器镜像中创建一些巨大的文件。
在构建脚本中使用 useradd 命令时，请将 --no-log-init 或 -l 选项传递给 useradd 命令。此选项告诉 useradd 停止创建 lastlog 文件。
另请参阅¶
podman(1)、buildah(1)、containers-certs.d(5)、containers-registries.conf(5)、crun(1)、runc(8)、useradd(8)、podman-ps(1)、podman-rm(1)、Containerfile(5)、containerignore(5)
故障排除¶
有关常见问题的解决方案，请参阅 podman-troubleshooting(7)。
有关无根（rootless）问题，请参阅 podman-rootless(7)。
历史¶
2020 年 8 月，Dan Walsh <dwalsh@redhat.com> 添加了额外选项和 .containerignore。
2018 年 5 月，Joe Doss <joe@solidadmin.com> 进行了少量修订。
2017 年 12 月，最初由 Tom Sweeney <tsweeney@redhat.com> 编译。
脚注¶
1：Podman 项目致力于包容性，这是开源的核心价值观。此处使用的 master 和 slave 挂载传播术语存在问题且具有分裂性，需要更改。然而，这些术语目前在 Linux 内核中使用，并且目前必须按原样使用。当内核维护者纠正此用法时，Podman 将立即跟进。