如何用Podman Quadlet将容器定义为系统服务,并验证开机启动与重启行为?

发布人:A5数据发布时间:2026-10-26 11:50阅读量:89

要把 Podman 容器作为系统服务运行,关键是写入 Quadlet 的 .container 文件,再由 systemd 生成并管理对应的 .service。首次部署不能只检查容器是否启动:还需要分别验证服务是否随开机目标启动,以及容器异常退出后是否按预期重启。

下面以一台使用 systemd、已安装支持 Quadlet 的 Podman 的 Linux 服务器为例,部署一个仅监听本机 127.0.0.1:8080 的 Nginx 示例容器。操作采用 rootful 系统服务:Quadlet 文件放在 /etc/containers/systemd/,命令中的 Podman 操作均使用 sudo。这样可以避免把系统级开机启动与登录用户的 rootless 服务混为一谈。

这类由 Podman Quadlet 和 systemd 管理的容器服务,可以部署在独立物理服务器上,承载网站、接口和业务后台。A5数据提供中国香港、美国、日本、新加坡等地区的物理服务器,涵盖 Xeon 与 AMD EPYC 平台,并有 SSD、NVMe 存储及不同线路的产品方案,为容器化业务提供计算、存储和网络资源基础,适配不同访问地区与程序负载。

准备条件:确认环境和部署边界

先确认服务器使用 systemd,Podman 可用,并具备拉取示例镜像的网络条件:

systemctl --version
podman --version
sudo podman info
command -v curl

这些命令应分别返回 systemd、Podman 信息,并找到 curl。Quadlet 随 Podman 提供,但不同发行版的打包方式可能不同;版本号和 podman info 正常,不等于 Quadlet 文件一定能被生成。后续执行 daemon-reload 后,还要用 systemctl cat 核验生成结果。

本例需要占用本机 8080 端口。写配置前检查端口,以及是否已有同名服务或容器:

sudo ss -ltn '( sport = :8080 )'
systemctl status web-demo.service --no-pager
sudo podman container exists quadlet-web-demo
echo $?
sudo test -e /etc/containers/systemd/web-demo.container
echo $?

ss 不应显示已有进程监听该端口;podman container exists 和 test -e 返回 1 表示对应对象不存在。如果已有同名对象,不要直接覆盖或删除,应先确认归属并另选名称或端口。示例镜像首次使用时需要下载:

sudo podman pull docker.io/library/nginx:stable

拉取成功后,sudo podman image exists docker.io/library/nginx:stable 应返回 0。正式业务部署建议按镜像摘要固定版本,并提前确认镜像来源;本例使用版本标签,是为了演示首次部署与验证流程。

写入 Quadlet 文件并检查生成结果

创建系统级 Quadlet 目录:

sudo install -d -m 0755 /etc/containers/systemd

在确认目标文件原本不存在后,写入 web-demo.container。下面使用 shell 的禁止覆盖选项,避免误覆盖已有同名文件:

sudo sh -c 'umask 022; set -C; cat > /etc/containers/systemd/web-demo.container' <<'EOF'
[Unit]
Description=Podman Quadlet web demo
Wants=network-online.target
After=network-online.target

[Container]
Image=docker.io/library/nginx:stable
ContainerName=quadlet-web-demo
PublishPort=127.0.0.1:8080:80

[Service]
Restart=on-failure
RestartSec=5s
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target
EOF

PublishPort 将宿主机本地 8080 端口映射到容器的 80 端口,不对外网接口直接开放。Restart=on-failure 用于处理服务异常退出;正常执行 systemctl stop 不应被当成需要恢复的故障。WantedBy=multi-user.target 则声明系统启动到该目标时拉起服务。network-online.target 仅表达启动顺序和依赖意图,不保证远端镜像仓库始终可达,因此前一步预拉取镜像有实际意义。

检查文件内容,再让 systemd 重新运行生成器:

sudo cat /etc/containers/systemd/web-demo.container
sudo systemctl daemon-reload
systemctl cat web-demo.service
systemctl show web-demo.service -p FragmentPath -p Restart

成功时,systemctl cat 应显示由 Quadlet 生成的 web-demo.service,FragmentPath 应指向 systemd 的生成单元目录,Restart 应为 on-failure。不要把普通服务的 systemctl enable web-demo.service 当作此处的必要步骤:Quadlet 由生成器依据 .container 文件中的 [Install] 段建立启动关系。若这里提示找不到服务,先处理生成问题,不要进入启动和重启测试。

写入 Quadlet 文件并检查生成结果配图

启动服务:同时核对 systemd 与容器状态

生成结果正常后,启动服务:

sudo systemctl start web-demo.service
systemctl is-active web-demo.service
sudo systemctl status web-demo.service --no-pager
sudo podman ps --filter name=quadlet-web-demo
curl -I --max-time 5 http://127.0.0.1:8080/

预期 is-active 输出 active,podman ps 列出运行中的 quadlet-web-demo,curl 收到 HTTP 响应,例如 HTTP/1.1 200 OK。这是示例预期,不代表服务器上的实际执行记录。

这几项检查回答的问题不同:systemctl 证明 systemd 正在管理服务,podman ps 证明容器进程存在,curl 证明端口上的应用能够响应。只看到容器处于 running,不足以证明开机启动关系或应用可用。

验证异常重启与开机启动

让容器异常退出,观察服务是否恢复

先记录容器 ID 和服务重启次数:

sudo podman inspect -f '{{.Id}} {{.State.Status}}' quadlet-web-demo
systemctl show web-demo.service -p NRestarts -p ActiveState

在本例中,以下命令会强制终止指定的示例容器,导致一次短暂服务中断;只应在确认名称、影响范围和测试窗口后执行。它不是日常停止服务的方式。

sudo podman kill --signal KILL quadlet-web-demo

等待超过配置的 RestartSec=5s,再检查:

systemctl show web-demo.service -p NRestarts -p ActiveState
sudo podman inspect -f '{{.Id}} {{.State.Status}}' quadlet-web-demo
curl -I --max-time 5 http://127.0.0.1:8080/

预期服务重新变为 active,容器状态为 running,HTTP 请求恢复成功;容器 ID 通常会变化,NRestarts 应体现这次服务重启。如果刚终止容器就立刻查询,可能正处于等待重启阶段,应在数秒后复查。若容器没有恢复,以服务日志为准,不要仅凭 HTTP 失败判断重启策略未生效。

重启主机,验证开机关系

主机重启会中断该服务器上的业务和当前连接,应在有维护窗口、具备重新登录途径时进行。重启前先确认 Quadlet 文件仍在,且生成服务具有启动目标关系:

sudo test -f /etc/containers/systemd/web-demo.container && echo "Quadlet file present"
systemctl list-dependencies multi-user.target --all | grep web-demo.service

若依赖列表没有显示该服务,应重新检查 .container 文件的 [Install] 段及 daemon-reload 后的生成结果。确认后再重启:

sudo systemctl reboot

重新登录服务器后,执行:

systemctl is-active web-demo.service
sudo podman ps --filter name=quadlet-web-demo
curl -I --max-time 5 http://127.0.0.1:8080/
sudo journalctl -b -u web-demo.service --no-pager -n 50

验收重点是:本次开机后服务为 active、容器正在运行、HTTP 可响应,并且 journalctl -b 能看到本次启动过程。重启主机后的重启计数不能直接拿来与上一次开机前的数值比较;它不是验证开机启动的主要依据。

验证异常重启与开机启动配图

失败时按生成、启动、访问的顺序排查

若 systemctl cat web-demo.service 提示单元不存在,说明问题尚在 Quadlet 生成阶段。先检查文件名是否以 .container 结尾、是否位于 /etc/containers/systemd/、段落与键名是否拼写正确,然后重新执行 sudo systemctl daemon-reload。可查看生成器或管理器日志中的相关报错:

sudo journalctl -b --no-pager | grep -Ei 'quadlet|web-demo|podman-system-generator'

若服务已生成但启动失败,先读服务日志,再核对镜像、同名容器和端口:

sudo journalctl -b -u web-demo.service --no-pager -n 100
sudo podman image exists docker.io/library/nginx:stable
sudo podman ps -a --filter name=quadlet-web-demo
sudo ss -ltn '( sport = :8080 )'

镜像不存在或拉取失败时,处理镜像访问问题;端口被其他进程占用时,确认进程归属后更换本例端口;同名容器已存在时,先确认它是否属于本服务,不要为让示例启动而直接删除生产容器。

若服务与容器都在运行,但 curl 失败,先确认访问的是宿主机 127.0.0.1:8080,再查看端口映射和容器日志:

sudo podman port quadlet-web-demo
sudo podman logs --tail 50 quadlet-web-demo

本例绑定的是回环地址,从其他主机访问服务器公网 IP 不通是预期的访问边界,并不表示本机服务启动失败。

验收与回滚检查项

  • 配置验收: /etc/containers/systemd/web-demo.container 存在;systemctl cat web-demo.service 能显示生成单元,Restart 为 on-failure。
  • 运行验收: 服务为 active、容器为 running,本机访问 http://127.0.0.1:8080/ 有 HTTP 响应。
  • 行为验收: 指定容器异常退出后服务恢复;主机重启后,无需人工启动即可再次通过运行状态与 HTTP 检查。

如果决定撤销本次示例部署,先停止服务,再移除本次创建且已确认路径无误的 Quadlet 文件,最后重新加载 systemd。删除前如曾修改文件,应先复制留存;停止服务会立即中断该示例的访问。

sudo systemctl stop web-demo.service
sudo cp -a /etc/containers/systemd/web-demo.container \
  /etc/containers/systemd/web-demo.container.bak
sudo rm /etc/containers/systemd/web-demo.container
sudo systemctl daemon-reload

回滚后检查 web-demo.service 不再处于运行状态、quadlet-web-demo 不再运行,且本机 8080 端口不再由本例监听。备份文件使用 .bak 后缀,不会作为 .container 单元生成;如需恢复,确认端口和名称仍可用后,将备份复制回原路径,执行 daemon-reload 并重新启动、验证服务。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5846.html

相关推荐