1. First | 序

Podman Quadlet 的核心价值在于将容器的灵活性与 Linux 系统服务管理 systemd 连接在一起。它通过引入声明式的单元文件（如本篇的 .container），允许开发者和管理员以一种直观、可复用的方式定义容器的配置、网络、存储和生命周期。Quadlet 充当一个智能生成器，在系统启动时自动将这些高级定义文件转换为原生的 systemd 服务单元。

本篇完全复制以下官方文档内容并专注于 Container options

podman-systemd.unit — Podman documentation

Podman

1.1. 核心概念：.container 单元文件解析

本章节旨在深入剖析 .container 单元文件的基本构成，它是使用 Quadlet 定义 systemd 服务化容器的蓝图。我们将探讨其文件结构、命名约定以及 Quadlet 是如何将其转换为 systemd 能够理解和管理的服务单元的。

.container 单元文件的核心作用是提供一个声明式的容器定义。它是一个以 .container 为扩展名的文本文件，其内部必须包含一个 [Container] 部分，该部分详细描述了作为服务运行的容器应具备的所有属性和行为。这本质上是将 podman run 命令及其众多参数以一种结构化、可读性强的方式固化下来。

Quadlet 的转换机制非常直观。当 systemd 重新加载其配置时，Quadlet 生成器会自动扫描指定的目录，并将每个名为 $name.container 的文件转换为一个对应的 $name.service 服务单元。这个生成的服务单元随后便可以像任何其他原生 systemd 服务一样被启动、停止、启用或禁用。

默认情况下，由 $name.container 文件创建的 Podman 容器会被命名为 systemd-%N（其中 %N 会被替换为单元文件名 $name），以避免与用户手动创建的容器产生命名冲突。当然，如果需要自定义容器名称，可以使用 ContainerName 选项来覆盖此默认行为。

在 [Container] 部分中，Image 是唯一一个必需的配置项。它明确指定了容器将要运行的基础镜像，是构成服务化容器的起点。所有其他的配置项都是可选的，用于对容器进行更精细的控制。

2. [Container] 单元配置选项全解

[Container] 部分是 Quadlet 的关键，它包含了将 podman run 命令参数化的所有配置项。通过这些键值对可以声明式地定义容器的镜像、命令、网络、存储、安全策略、资源限制以及健康检查等方方面面。本章节将对所有可用选项进行逻辑分类，并为每个选项提供详细的剖析，包括其功能描述、等效的 podman run 命令、默认值、适用场景及配置示例，以便能够精确地控制容器的每一个行为。

2.1. 基础配置 (Basic Configuration)

本节包含定义容器运行内容和基本行为最核心的选项，它们是构建任何服务化容器的基础。

Image

• 描述：指定容器运行所依赖的镜像。这是 [Container] 部分中唯一必需的选项。
• podman run 等效命令：podman run [IMAGE]
• 默认值：未指定 (必需项)
• 使用场景：定义容器服务的基础镜像。对于生产环境，强烈建议始终使用包含摘要（digest）的完全限定镜像名称（例如 image@sha256:...），而不是可变的标签（如 :latest），以确保部署的确定性和安全性。
• 注意事项：
  • 联动 .image 文件：如果值以 .image 结尾，Quadlet 会自动依赖于由同名 .image 单元文件拉取的镜像。
  • 联动 .build 文件：如果值以 .build 结尾，Quadlet 会自动依赖于由同名 .build 单元文件构建的镜像。

ContainerName

• 描述：覆盖默认的容器名称。
• podman run 等效命令：--name
• 默认值：systemd-%N
• 使用场景：当需要为容器指定一个易于识别的、固定的名称时使用，便于后续通过名称进行管理。

Exec

• 描述：在容器镜像指定的 ENTRYPOINT 之后追加的命令或参数。
• podman run 等效命令：在镜像名称后追加的 [COMMAND] [ARG...]
• 默认值：未指定
• 使用场景：向容器的主进程传递参数，或执行一个不同于默认 CMD 的命令。其行为类似于 Kubernetes Pod 定义中的 args 字段。

Entrypoint

• 描述：覆盖镜像中定义的默认 ENTRYPOINT。
• podman run 等效命令：--entrypoint
• 默认值：未指定 (使用镜像的默认 ENTRYPOINT)
• 使用场景：当需要完全替换容器启动时执行的主命令时使用。

Environment

• 描述：在容器内设置环境变量。
• podman run 等效命令：--env <key=value>
• 默认值：未指定
• 使用场景：为容器化应用注入配置信息，如数据库连接字符串、API 密钥等。此选项可多次使用。

EnvironmentFile

• 描述：从一个文件中读取环境变量并设置到容器内。文件格式为每行一个 key=value。
• podman run 等效命令：--env-file
• 默认值：未指定
• 使用场景：集中管理大量环境变量，避免将敏感信息直接写入 .container 文件。路径可以是绝对路径，也可以是相对于单元文件的相对路径。

EnvironmentHost

• 描述：将宿主机的环境变量传递到容器内部。
• podman run 等效命令：--env-host
• 默认值：false
• 使用场景：当容器需要继承宿主机的某些环境配置时使用，例如代理设置或用户特定的配置。

WorkingDir

• 描述：设置容器内部的工作目录。
• podman run 等效命令：--workdir
• 默认值：根目录 (/)，除非镜像中 WORKDIR 指令设置了不同的默认值。
• 使用场景：为容器内执行的命令指定一个默认的当前目录。

AutoUpdate

• 描述：配置容器的自动更新策略（需配合 podman-auto-update 使用）。
• podman run 等效命令：--label "io.containers.autoupdate=registry"
• 默认值：未指定
• 使用场景：实现容器服务的自动更新。registry 值表示从注册表中拉取新镜像进行更新，local 表示当本地同名镜像更新后重启容器。
• 注意事项：
  • 使用 registry 策略时，Image 必须是完全限定的镜像引用。
  • 此机制依赖于 podman-auto-update.timer systemd 单元被启用并正在运行。否则，此设置将无效。

Pull

• 描述：设置镜像拉取策略。
• podman run 等效命令：--pull
• 默认值：未指定
• 使用场景：控制 podman run 在启动容器前是否以及如何拉取镜像。可选值包括 always、never、missing。

Timezone

• 描述：设置容器内部的时区。
• podman run 等效命令：--tz
• 默认值：如果未设置，则使用系统配置的默认时区。
• 使用场景：确保容器内应用（特别是日志记录和定时任务）使用正确的时区。设为 local 可直接同步宿主机时区。

2.2 资源与限制 (Resources & Limits)

此处的选项用于管理和限制容器可以使用的系统资源，这对于确保系统稳定性和多租户环境下的公平性至关重要。

Memory

• 描述：限制容器可以使用的内存大小。
• podman run 等效命令：--memory
• 默认值：未指定 (无限制)
• 使用场景：防止容器消耗过多内存，导致系统不稳定。支持单位如 m (兆字节) 和 g (吉字节)。

PidsLimit

• 描述：限制容器内可以创建的进程（PID）数量。
• podman run 等效命令：--pids-limit
• 默认值：未指定
• 使用场景：防止 "fork bomb" 等恶意行为耗尽系统进程资源。

ShmSize

• 描述：设置 /dev/shm 目录（共享内存）的大小。
• podman run 等效命令：--shm-size
• 默认值：未指定
• 使用场景：某些应用（如数据库、浏览器测试框架）需要较大的共享内存空间。

Ulimit

• 描述：设置容器内部的 ulimit 资源限制。
• podman run 等效命令：--ulimit <type=soft:hard>
• 默认值：未指定
• 使用场景：调整特定资源的限制，如打开文件描述符的数量 (nofile)。此选项可多次使用。

2.3 网络配置 (Network Configuration)

这些选项提供了对容器网络环境的精细化控制，从连接模式到端口映射，再到 DNS 解析。

Network

• 描述：将容器连接到一个或多个网络。
• podman run 等效命令：--network
• 默认值：未指定 (使用 Podman 默认网络)
• 使用场景：连接到自定义网络、使用主机网络 (host) 或禁用网络 (none)。此选项可多次使用。
• 注意事项：
  • 联动 .network 文件：如果值以 .network 结尾，Quadlet 会自动依赖于由同名 .network 单元文件创建的网络。
  • 联动 .container 文件：如果值以 .container 结尾，容器将共享此 .container 文件指定容器的网络命名空间。

PublishPort

• 描述：将容器的端口发布（映射）到宿主机上。
• podman run 等效命令：--publish hostPort:containerPort
• 默认值：未指定
• 使用场景：使外部网络能够访问容器内运行的服务。格式支持 ip:hostPort:containerPort、hostPort:containerPort 等多种形式。

ExposeHostPort

• 描述：在容器元数据中声明一个端口或端口范围，供其他容器链接时使用。
• podman run 等效命令：--expose
• 默认值：未指定
• 使用场景：声明一个容器计划使用的端口，以便在 Podman 网络内部被其他容器发现和连接，但不会将该端口发布到宿主机上。

DNS

• 描述：为容器设置自定义 DNS 服务器。
• podman run 等效命令：--dns
• 默认值：未指定
• 使用场景：当容器需要使用特定的 DNS 解析服务时，例如内部 DNS 或公共 DNS。可多次使用。

DNSOption

• 描述：设置自定义 DNS 选项。
• podman run 等效命令：--dns-option
• 默认值：未指定
• 使用场景：微调 DNS 解析行为，例如设置 ndots:1。可多次使用。

DNSSearch

• 描述：为容器设置 DNS 搜索域。
• podman run 等效命令：--dns-search
• 默认值：未指定
• 使用场景：在解析短名称时自动附加搜索域。可多次使用。

AddHost

• 描述：向容器的 /etc/hosts 文件中添加自定义条目。
• podman run 等效命令：--add-host host:ip
• 默认值：未指定
• 使用场景：为容器内部提供静态的主机名解析，常用于测试或连接遗留系统。可多次使用。

HostName

• 描述：设置容器的主机名。
• podman run 等效命令：--hostname
• 默认值：未指定 (通常为容器 ID 的一部分)
• 使用场景：为容器指定一个固定的、有意义的主机名。

IP

• 描述：为容器指定一个静态 IPv4 地址。
• podman run 等效命令：--ip
• 默认值：未指定
• 使用场景：在需要固定 IP 地址的场景下使用，通常需要配合自定义网络。

IP6

• 描述：为容器指定一个静态 IPv6 地址。
• podman run 等效命令：--ip6
• 默认值：未指定
• 使用场景：在 IPv6 环境中为容器分配固定的地址。

NetworkAlias

• 描述：为容器在所属网络中添加一个或多个网络别名。
• podman run 等效命令：--network-alias
• 默认值：未指定
• 使用场景：允许其他容器通过别名来发现和连接此容器，便于实现服务的负载均衡或分组。可多次使用。

HttpProxy

• 描述：控制是否将宿主机的代理环境变量（如 http_proxy）传递到容器中。
• podman run 等效命令：--http-proxy= <true|false>
• 默认值：未指定
• 使用场景：当宿主机需要通过代理访问网络，但容器本身不应使用或需要使用不同代理时，可设为 false。

2.4 安全与权限 (Security & Permissions)

安全是容器化部署的基石，本节的选项旨在通过最小权限原则，限制容器的潜在风险。

AddCapability

• 描述：向容器添加额外的 Linux 能力（Capabilities）。
• podman run 等效命令：--cap-add
• 默认值：未指定
• 使用场景：当容器需要执行默认能力集之外的特权操作时（如网络嗅探需要 CAP_NET_RAW）。此键可多次使用，或者在同一行内用空格分隔多个能力。

DropCapability

• 描述：从容器的默认能力集中移除指定的 Linux 能力。
• podman run 等效命令：--cap-drop
• 默认值：未指定
• 使用场景：遵循最小权限原则，剥离容器不需要的特权，增强安全性。ALL 值可移除所有能力。此键可多次使用，或者在同一行内用空格分隔多个能力。

NoNewPrivileges

• 描述：禁止容器内的进程通过 setuid 或文件能力等方式获得额外的权限。
• podman run 等效命令：--security-opt no-new-privileges
• 默认值：false
• 使用场景：一个重要的安全强化措施，用于防止容器内的提权攻击。

ReadOnly

• 描述：将容器的根文件系统挂载为只读。
• podman run 等效命令：--read-only
• 默认值：false
• 使用场景：强制实施不可变基础设施原则，显著减少攻击面。通常需要配合 Tmpfs 或 Volume 为需要写入的路径提供可写空间。

ReadOnlyTmpfs

• 描述：当 ReadOnly=true 时，自动在 /dev, /dev/shm, /run, /tmp, /var/tmp 挂载一个可写的 tmpfs。
• podman run 等效命令：--read-only-tmpfs
• 默认值：true
• 使用场景：配合 ReadOnly=true 使用，为标准临时目录提供可写空间，以保证许多应用的基本运行。

RunInit

• 描述：在容器内运行一个轻量级的 init 进程（PID 1），用于转发信号和回收僵尸进程。
• podman run 等效命令：--init
• 默认值：false
• 使用场景：当容器内需要运行多个进程，或者主进程不会正确处理信号和回收子进程时，启用此选项可避免僵尸进程累积。

如果容器镜像中已经存在了其他的 init system 如 s6-overlay

此时传递 RunInit=true 会造成 s6-overlay 无法占据 PID 1 而无法启动

s6-overlay-suexec: fatal: can only run as pid 1

SeccompProfile

• 描述：为容器指定一个自定义的 seccomp 安全计算配置文件。
• podman run 等效命令：--security-opt seccomp= <profile.json>
• 默认值：未指定 (使用 Podman 默认 seccomp 配置文件)
• 使用场景：通过限制容器可用的系统调用来进一步强化安全。值可以是 JSON 文件的路径，或 unconfined 来禁用 seccomp。

SecurityLabelDisable

• 描述：禁用容器的标签分离（如 SELinux 或 AppArmor）。
• podman run 等效命令：--security-opt label=disable
• 默认值：false
• 使用场景：在特定调试场景或标签配置冲突时临时禁用安全标签。

SecurityLabelFileType

• 描述：设置容器文件所使用的标签类型。
• podman run 等效命令：--security-opt label=filetype:
• 默认值：未指定
• 使用场景：在 SELinux 系统中，为挂载到容器的文件设置特定的类型标签。

SecurityLabelLevel

• 描述：设置容器进程的 MCS/MLS 级别标签。
• podman run 等效命令：--security-opt label=level:
• 默认值：未指定
• 使用场景：在多级安全（MLS）环境中，为容器分配特定的安全级别。

SecurityLabelNested

• 描述：允许在容器内部创建的容器也能使用安全标签。
• podman run 等效命令：--security-opt label=nested
• 默认值：false
• 使用场景：用于运行 "容器中的 Docker/Podman" (DinD/PinP) 场景。

SecurityLabelType

• 描述：设置容器进程所使用的标签类型。
• podman run 等效命令：--security-opt label=type:
• 默认值：未指定
• 使用场景：在 SELinux 系统中，为容器进程指定一个特定的类型标签，以控制其权限。

Mask

• 描述：屏蔽容器内的某些路径，使其无法被访问。路径之间用冒号分隔。
• podman run 等效命令：--security-opt mask= :
• 默认值：未指定
• 使用场景：增强安全性，阻止容器访问宿主机上敏感的 /proc 或 /sys 文件系统路径。

Unmask

• 描述：解除对某些默认被屏蔽或设为只读的路径的限制。
• podman run 等效命令：--security-opt unmask= <path|ALL>
• 默认值：未指定
• 使用场景：当容器需要访问默认被屏蔽的系统路径时使用。ALL 值会解除所有默认屏蔽。
• 注意事项：
  • 默认屏蔽的路径包括: /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, 和 /sys/fs/selinux。
  • 默认设置为只读的路径包括: /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup。

2.5 用户与命名空间 (User & Namespaces)

这些选项用于定义容器内部的运行时用户身份以及配置用户命名空间，这是实现多租户隔离和权限控制的关键。

User

• 描述：指定容器内进程运行的用户名或 UID。
• podman run 等效命令：--user <user|uid>
• 默认值：未指定 (使用镜像中 USER 指令定义的用户)
• 使用场景：用于指定容器内部运行进程的 UID（用户ID）或用户名，而不是主机上运行 Podman 进程的用户

Group

• 描述：指定容器内进程运行的组名或 GID。
• podman run 等效命令：--user :<group|gid>
• 默认值：未指定
• 使用场景：与 User 选项配合使用，精确指定进程的用户和主组。
• 注意事项：Group 必须与 User 一同指定，否则会报错。

GroupAdd

• 描述：为容器内的用户添加额外的附加组。
• podman run 等效命令：--group-add <group|keep-groups>
• 默认值：未指定
• 使用场景：当容器内的进程需要访问属于特定组的文件或设备时。keep-groups 会保留运行 podman 命令的用户所属的附加组。

UserNS

• 描述：配置容器的用户命名空间模式。
• podman run 等效命令：--userns
• 默认值：未指定
• 使用场景：启用用户命名空间以增强隔离性，例如使用 keep-id 将宿主机用户映射到容器内的同一 ID。

UIDMap

• 描述：定义容器内 UID 到宿主机 UID 的映射。
• podman run 等效命令：--uidmap <container_uid:host_uid:size>
• 默认值：未指定
• 使用场景：在启用用户命名空间时，手动控制 UID 的映射关系。

GIDMap

• 描述：定义容器内 GID 到宿主机 GID 的映射。
• podman run 等效命令：--gidmap <container_gid:host_gid:size>
• 默认值：未指定
• 使用场景：在启用用户命名空间时，手动控制 GID 的映射关系。

SubUIDMap

• 描述：使用 /etc/subuid 文件中定义的映射名称来配置用户命名空间。
• podman run 等效命令：--subuidname
• 默认值：未指定
• 使用场景：简化用户命名空间的配置，利用系统预设的 subordinate ID 范围。

SubGIDMap

• 描述：使用 /etc/subgid 文件中定义的映射名称来配置用户命名空间。
• podman run 等效命令：--subgidname
• 默认值：未指定
• 使用场景：简化用户命名空间的配置，利用系统预设的 subordinate ID 范围。

2.5.1. 核心含义：不能通过“降权”来实现无根模式

你不能在系统级（Root）的 Quadlet 文件中，试图通过设置 systemd 的 User=、Group= 或 DynamicUser 选项，来让容器以普通用户身份运行。

• 错误的做法：在 /etc/containers/systemd/（系统目录）下创建一个 .container 文件，然后在生成的服务配置（或通过 Drop-in）中添加 [Service] User=bob，试图以此让 Podman 以用户 bob 的身份运行。
• 原因：Rootless Podman（无根模式）不仅仅是切换用户 ID。它严重依赖于用户特定的环境配置（如 XDG_RUNTIME_DIR）、用户命名空间（User Namespace）以及该用户专属的 D-Bus 会话。单纯使用 Systemd 的 User= 指令切换身份，无法加载这些必要的环境，导致 Podman 无法正确初始化。

2.5.2. 正确的做法：必须在“用户实例”中运行

“如果你想运行无根 Quadlet，你需要创建该用户，并将单元文件添加到上述无根单元搜索路径之一。”

这意味着无根模式的正确打开方式是登录为该用户（或进入该用户的 systemd 实例环境）：

1. 切换身份：你必须以目标用户（例如 bob）的身份操作。
2. 放置文件：将 Quadlet 文件（如 .container）放入该用户的专属配置目录。
   • $XDG_RUNTIME_DIR/containers/systemd/
   • $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/containers/systemd/
   • /etc/containers/systemd/users/$(UID)
   • /etc/containers/systemd/users/
3. 用户级守护进程：由该用户的 systemd --user 实例来加载和管理这些服务，而不是由系统级的 PID 1 守护进程管理。

在调试无根单元时，必须使用带有 --user 标志的命令（如 systemctl --user start ... 或 /usr/lib/systemd/system-generators/podman-system-generator --user）。这表明无根 Quadlet 是严格绑定在用户的 systemd 实例上的。

2.5.3. 容易混淆的概念：容器内用户 vs. 运行服务的用户

• 被禁止的用法（针对 Systemd）：
  这是指在 [Service] 部分（Systemd 层级）使用 User=。如前所述，Quadlet 不支持用这种方式启动无根容器。

• 支持的用法（针对 Podman）：
  Quadlet 的 [Container] 部分支持 User= 选项。

  • 含义：这里的 User= 对应的是 podman run --user，它指定的是容器内部进程运行的 UID（用户 ID）。
  • 作用：例如，你可以配置 [Container] User=1001，这会让容器里的进程以 ID 1001 运行，但这并不改变 Podman 引擎本身是作为 Root 运行还是作为普通用户运行的事实。

2.6 存储与挂载 (Storage & Mounts)

数据持久化和文件系统管理是容器应用的重要组成部分，本节的选项提供了灵活的卷、挂载点和设备管理能力。

Volume

• 描述：将宿主机目录或 Podman 命名卷挂载到容器中。
• podman run 等效命令：--volume source:destination:options
• 默认值：未指定
• 使用场景：为容器提供持久化存储，或在宿主机与容器间共享文件。
• 注意事项：如果源路径以 .volume 结尾，Quadlet 会自动依赖于由同名 .volume 单元文件创建的命名卷。

Mount

• 描述：以更灵活的方式将文件系统挂载到容器中，支持多种类型。
• podman run 等效命令：--mount <type=...,source=...,destination=...>
• 默认值：未指定
• 使用场景：用于更复杂的挂载场景，如挂载 tmpfs、bind 挂载，或者从一个镜像挂载文件。
• 注意事项：
  • type=volume 且 source 以 .volume 结尾时，联动 .volume 文件。
  • type=image 且 source 以 .image 结尾时，联动 .image 文件。

AddDevice

• 描述：将宿主机的设备节点添加到容器中。
• podman run 等效命令：--device <host_device:container_device:permissions>
• 默认值：未指定
• 使用场景：当容器需要直接访问硬件设备时，如 GPU、USB 设备或串口。

Tmpfs

• 描述：在容器内挂载一个 tmpfs（内存文件系统）。
• podman run 等效命令：--tmpfs dir:options
• 默认值：未指定
• 使用场景：为需要高性能临时存储的路径提供一个基于内存的文件系统。

Rootfs

• 描述：使用宿主机上的一个目录作为容器的根文件系统，而不是使用镜像。
• podman run 等效命令：--rootfs
• 默认值：未指定
• 使用场景：在不构建镜像的情况下，直接运行一个文件系统目录作为容器。
• 注意事项：此选项与 Image 选项互斥。

Secret

• 描述：将 Podman 密钥（secret）安全地挂载到容器中（作为文件或环境变量）。
• podman run 等效命令：--secret <secret_name,opt=opt...>
• 默认值：未指定
• 使用场景：向容器注入敏感信息（如密码、证书），而无需将其硬编码在配置文件或环境变量中。

2.7 健康检查与生命周期 (Health Checks & Lifecycle)

通过配置健康检查，可以让 systemd 感知容器内部应用的状态，并定义容器的启动、停止和重载行为，从而实现高可用性。

HealthCmd

• 描述：定义用于检查容器健康状况的命令。
• podman run 等效命令：--health-cmd
• 默认值：未指定
• 使用场景：定期执行一个命令（如 curl 一个健康端点），通过其退出码判断应用是否健康。

HealthInterval

• 描述：健康检查的执行间隔时间。
• podman run 等效命令：--health-interval
• 默认值：未指定
• 使用场景：设置两次健康检查之间的时间间隔。设为 disable 可禁用自动定时检查。

HealthRetries

• 描述：在将容器标记为不健康之前，允许的连续失败次数。
• podman run 等效命令：--health-retries
• 默认值：未指定
• 使用场景：防止因短暂的网络抖动或应用临时繁忙而误判为不健康。

HealthTimeout

• 描述：单次健康检查命令允许的最长执行时间。
• podman run 等效命令：--health-timeout
• 默认值：未指定
• 使用场景：防止健康检查命令卡死，导致状态无法更新。

HealthStartPeriod

• 描述：容器启动后的宽限期。在此期间，健康检查失败不会计入重试次数。
• podman run 等效命令：--health-start-period
• 默认值：未指定
• 使用场景：为需要较长启动时间的应用提供缓冲，避免在应用完全就绪前被误判为不健康。

HealthOnFailure

• 描述：当容器健康状态转为不健康时执行的操作。
• podman run 等效命令：--health-on-failure
• 默认值：未指定
• 使用场景：设置为 kill 可以杀死不健康的容器，然后 systemd 的重启策略会负责重启它，实现自动修复。

HealthStartupCmd, HealthStartupInterval, HealthStartupRetries, HealthStartupSuccess, HealthStartupTimeout

• 描述：这一组选项用于定义一个独立的“启动健康检查”，在常规健康检查开始前执行。
• podman run 等效命令：--health-startup-* 系列参数。
• 默认值：未指定
• 使用场景：这对于初始化过程漫长且分阶段的应用（如预热缓存、执行数据库迁移）至关重要。启动探针可确保服务在完全就绪前不被视为“已启动”或接受常规健康检查，从而防止过早重启。

HealthLogDestination

• 描述：设置健康检查日志的存储位置。
• podman run 等效命令：--health-log-destination
• 默认值：local
• 使用场景：将健康检查日志保存到指定目录或使用事件记录器，便于调试。

HealthMaxLogCount

• 描述：设置健康检查日志文件的最大数量。
• podman run 等效命令：--health-max-log-count
• 默认值：5
• 使用场景：与 HealthMaxLogSize 配合使用，管理健康检查日志的磁盘占用。

HealthMaxLogSize

• 描述：设置健康检查日志文件的最大大小（字符数）。
• podman run 等效命令：--health-max-log-size
• 默认值：500
• 使用场景：与 HealthMaxLogCount 配合使用，管理健康检查日志的磁盘占用。

Notify

• 描述：配置 systemd 的服务启动通知机制。
• podman run 等效命令：--sdnotify container
• 默认值：false
• 使用场景：
  • true：如果容器内应用支持 sd_notify，Podman 会将通知套接字传递给容器，由应用自行通知 systemd 启动完成。
  • healthy：systemd 会等到容器的健康检查状态变为健康后，才认为服务启动成功。

StopSignal

• 描述：停止容器时发送的信号。
• podman run 等效命令：--stop-signal
• 默认值：SIGTERM
• 使用场景：当应用需要特定的信号来进行优雅关闭时，可以修改此值。

StopTimeout

• 描述：在发送停止信号后，等待容器优雅退出的最长时间（秒），超时后会强制杀死容器。
• podman run 等效命令：--stop-timeout
• 默认值：未指定
• 使用场景：为需要较长时间进行清理和关闭的应用提供充足的时间。

ReloadCmd

• 描述：定义当执行 systemctl reload 时，在容器内执行的命令。
• podman run 等效命令：无 (此为 systemd 集成特性)
• 默认值：未指定
• 使用场景：让服务支持不中断重载配置，例如向 Nginx 发送重载配置文件的命令。
• 注意事项：与 ReloadSignal 互斥。

ReloadSignal

• 描述：定义当执行 systemctl reload 时，向容器主进程发送的信号。
• podman run 等效命令：无 (此为 systemd 集成特性)
• 默认值：未指定
• 使用场景：对于通过接收特定信号来重载配置的应用（如 SIGHUP），此选项比 ReloadCmd 更高效。
• 注意事项：与 ReloadCmd 互斥。

2.8 高级与集成选项 (Advanced & Integration Options)

这些选项用于处理更复杂的场景，例如将容器集成到 Pod 中、传递原生 Podman 参数以及调整系统级配置。

Pod

• 描述：将此容器加入到一个由 .pod 单元文件定义的 Pod 中。
• podman run 等效命令：--pod <pod_name>
• 默认值：未指定
• 使用场景：构建多容器应用，使多个容器共享网络命名空间和其他资源。值必须是 .pod 文件的名称。

StartWithPod

• 描述：如果设置了 Pod，此选项决定容器是否随 Pod 一同启动。
• podman run 等效命令：无
• 默认值：true
• 使用场景：设置为 false 可以创建一个不会随 Pod 自动启动的“边车”容器，这里指该容器具有独立的生命周期。它们可以独立于应用容器启动、停止和重启。

CgroupsMode

• 描述：设置容器的 cgroups 模式。
• podman run 等效命令：--cgroups
• 默认值：split
• 使用场景：当容器加入 Pod 并希望应用 Pod 级别的 cgroup 资源限制时，可能需要将其更改为 no-conmon 或 enabled。
• 注意事项：Quadlet 默认的 split 模式与 Podman CLI 的默认 enabled 模式不同。

LogDriver

• 描述：设置容器的日志驱动。
• podman run 等效命令：--log-driver
• 默认值：journald
• 使用场景：将容器日志发送到 journald、json-file 等不同的后端。可以使用 podman info --format '{{ .Host.LogDriver }}' 命令查看默认日志驱动。

LogOpt

• 描述：为日志驱动设置特定选项。
• podman run 等效命令：--log-opt <key=value>
• 默认值：未指定
• 使用场景：配置日志驱动的行为，如设置 json-file 的最大大小。可多次使用。

Sysctl

• 描述：在容器内配置内核参数（sysctl）。
• podman run 等效命令：--sysctl <name=value>
• 默认值：未指定
• 使用场景：调整容器网络栈等命名空间化的内核参数。此键可多次使用，或者在同一行内用空格分隔多个参数。

Retry

• 描述：在拉取镜像时，遇到 HTTP 错误时的重试次数。
• podman run 等效命令：--retry
• 默认值：未指定
• 使用场景：在网络不稳定的环境中提高镜像拉取的成功率。

RetryDelay

• 描述：每次重试拉取镜像之间的延迟时间。
• podman run 等效命令：--retry-delay
• 默认值：未指定
• 使用场景：与 Retry 配合使用，避免过于频繁地重试。

ContainersConfModule

• 描述：加载指定的 containers.conf 模块。
• podman run 等效命令：--module
• 默认值：未指定
• 使用场景：为特定容器加载自定义的 Podman 配置模块。可多次使用。

GlobalArgs

• 描述：将原生参数直接插入到 podman 和 run 命令之间。
• podman run 等效命令：直接添加的全局参数
• 默认值：未指定
• 使用场景：用于使用 Quadlet 尚未直接支持的 Podman 全局新特性。
• 注意事项：不推荐使用此选项。由于 Quadlet 生成器无法预知这些参数可能带来的未知交互，使用此选项可能导致意外行为，需自行承担风险。

PodmanArgs

• 描述：将原生参数直接插入到 podman run 命令的末尾，紧邻镜像名称之前。
• podman run 等效命令：直接添加的 run 子命令参数
• 默认值：未指定
• 使用场景：用于使用 Quadlet 尚未直接支持的 podman run 新特性。
• 注意事项：不推荐使用此选项。与 GlobalArgs 类似，这是一种“逃生舱口”，但可能导致不可预知的行为，使用时需谨慎。

关于 StartWithPod 选项中提到的 边车容器

Kubernetes Doc 中有详细的解析

边车容器

特性状态： Kubernetes v1.33 [stable](enabled by default) 边车容器是与主应用容器在同一个 Pod 中运行的辅助容器。 这些容器通过提供额外的服务或功能（如日志记录、监控、安全性或数据同步）来增强或扩展主应用容器的功能， 而无需直接修改主应用代码。 通常，一个 Pod 中只有一个应用容器。 例如，如果你有一个需要本地 Web 服务器的 Web 应用， 则本地 Web 服务器以边车容器形式运行，而 Web 应用本身以应用容器形式运行。 Kubernetes 中的边车容器 Kubernetes 将边车容器作为 Init 容器的一个特例来实现， Pod 启动后，边车容器仍保持运行状态。 本文档使用术语”常规 Init 容器”来明确指代仅在 Pod 启动期间运行的容器。 如果你的集群启用了 SidecarContainers 特性门控 （该特性自 Kubernetes v1.29 起默认启用），你可以为 Pod 的 initContainers 字段中列出的容器指定 restartPolicy。 这些可重新启动的边车（Sidecar） 容器独立于其他 Init 容器以及同一 Pod 内的主应用容器， 这些容器可以启动、停止和重新启动，而不会影响主应用容器和其他 Init 容器。 你还可以运行包含多个未标记为 Init 或边车容器的 Pod。 如果作为一个整体而言，某个 Pod 中的所有容器都要运行，但你不需要控制哪些容器先启动或停止，那么这种设置是合适的。 如果你使用的是不支持容器级 restartPolicy 字段的旧版本 Kubernetes，你也可以这样做。

Kubernetes

使用 LogDriver=journald 显示指定日志驱动后

Podman 不再写入本地的 JSON 文件并且由 Systemd 统一管理日志轮转

它会写入额外的 Key-Value 字段，例如：

• CONTAINER_ID_FULL
• CONTAINER_NAME
• CONTAINER_ID

示例如下:

➜  ~ journalctl -N | grep "CONTAINER"
CONTAINER_ID_FULL
CONTAINER_NAME
CONTAINER_ID
➜  ~ journalctl -F CONTAINER_ID
40a1ecf95cb5
ce1947cbb639
4a261656234e
bda07093ee59
bf60d0e4447a
a2ffa2ee477d
73c980de34a5
c363e83be650
3a726ef183b0
97916016f64c
c9c72c167935
b87ba89b4f4e
210ebdb75287
26be6f479a8b
0421fb234881
05d4e6d608a2
73dd6c6a2491
485471852c2f
988dac31aaba
1ec07202dbbe
2fb9e032fedd
6eedfa76e7fa
9188a86b2425
025a5b379c8b
d63d5ad2dc3f
c3d1392c3e94
9956af62d1dc
9b478a5021ce
10616f4923ef
48af66d71daf
f364594ebfa1
7b8e06e3e826
8b2b2b7b6865
264a313c9b1a
5ea491cb0de6
b351220625b3

这使得你可以使用上述三种字段查询日志

journalctl CONTAINER_NAME=my_web_server

journalctl CONTAINER_ID=84c902c1ab24

journalctl CONTAINER_ID_FULL=84c902c1ab248bc61e4f17cd06627e62d509d22e3f2a21cbc3ea42a3f6037d0c

3. 故障排查与调试

即便是最精心设计的服务也可能遇到问题，以下是调试 Quadlet 单元文件和生成过程的关键。

3.1. 查看生成错误

如果 systemctl start example.service 失败并提示 Unit not found，很可能是 .container 文件存在语法错误或使用了当前版本不支持的选项，导致 systemd 服务文件生成失败。您可以直接运行生成器来查看所有生成的单元或错误信息：

/usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun

3.2. 深度分析与验证

要对生成的服务单元进行更深入的检查，systemd-analyze 是一个强大的工具。它不仅能显示生成错误，还能对生成的服务单元进行额外的验证：

systemd-analyze {--user} --generators=true verify example.service

3.3. 调试有限的单元集

在拥有大量单元文件的系统中，为了减少调试输出的干扰，您可以将需要调试的少数几个单元文件复制到一个临时目录，然后通过设置 QUADLET_UNIT_DIRS 环境变量来指示生成器仅处理该目录中的文件：

QUADLET_UNIT_DIRS=/path/to/debug/dir /usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun

这种方法可以极大地简化复杂环境下的问题定位过程。

Thanks & Copy

podman-systemd.unit — Podman documentation

Podman