Debian 13 教程 / 用Quadlet管理rootless容器并验证linger与启动行为

在 Debian 13 上以用户服务的方式操作无根容器时,您需要创建原始 Quadlet 并管理由 systemd 用户管理器生成的服务。异常终止重启、显式停止、注销后的持久性以及启动时自动启动是不同的条件,因此每一项都必须单独检查。在本教程中,我们将创建专用的 Web 容器和卷,保留 linger 的原始值,然后验证 HTTP 响应。

区分 Quadlet 源文件和生成的服务

Quadlet 是 Podman 的一个功能,它读取诸如 .container 之类扩展名的文件来生成 systemd 服务。普通用户通常将源文件放在 ~/.config/containers/systemd 下,并通过 systemctl --user 来管理。如果您直接修改 /run/user/UID/systemd/generator 下生成的 .service 文件,它在重新生成时会消失,因此应修改原始文件。

本教程在 Podman 5.4.2、cgroup v2、systemd 用户管理器环境下运行。根据 Podman 5.4.2 的 Quadlet 文档,我们使用支持的键 Image、ContainerName、PublishPort、Volume 和 Pull。为了避免直接使用较新文档中的键而导致服务未生成的问题,首先检查已安装的版本和生成器输出。

生成的服务不像常规的永久服务文件那样可以通过 systemctl enable 管理。如果您在原始文件的 [Install] 部分中添加 WantedBy=default.target,生成器会创建一个指向用户默认目标的链接。不要试图通过在无根原始文件中添加 User= 来切换账户;应该以实际的普通用户身份工作。

准备用户会话、镜像和专用卷

使用在上一节课中验证过的普通用户 Podman 环境。只有软件包安装是通过 sudo 完成的,其余的 podman 和 systemctl --user 命令都以普通用户身份执行。端口 8080 和名称 lf-web28 应该可用。这个示例使用 lf-web28-data,它与上一节课中的卷不同。

sudo apt install podman uidmap passt fuse-overlayfs curl
podman --version
podman info --format json
systemctl --user is-system-running
loginctl show-user "$(id -un)" -p Linger
ss -ltn

在新的 Bash 终端中,执行以下准备块。Linger 会应用于该账户的整个用户管理器,因此在对包含其他用户服务的账户使用它之前,请考虑维护范围。保留原始值的单独记录,以避免在清理时将原本为 yes 的账户更改为 no。

set -euo pipefail
record="$HOME/lf-course28-linger-before.txt"
qdir="$HOME/.config/containers/systemd"
for p in "$record" "$qdir/lf-web28.container"; do
    if test -e "$p"; then
        echo "Path already exists: $p" >&2
        exit 1
    fi
done
if podman container exists lf-web28; then exit 1; fi
if podman volume exists lf-web28-data; then exit 1; fi
loginctl show-user "$(id -un)" -p Linger --value > "$record"
cat "$record"
podman pull docker.io/library/httpd:2.4.71-trixie
image=$(podman image inspect docker.io/library/httpd:2.4.71-trixie --format '{{index .RepoDigests 0}}')
case "$image" in
    docker.io/library/httpd@sha256:*) ;;
    *) echo "Check the image reference." >&2; exit 1 ;;
esac
podman image exists "$image"
podman volume create lf-web28-data
podman run --rm --network none -v lf-web28-data:/data --entrypoint /bin/sh "$image" -c 'printf "LF QUADLET 28\n" > /data/index.html'
mkdir -p "$qdir"

本练习提前获取镜像并使用摘要。服务中的 Pull=never 阻止它在启动时尝试下载,因此如果镜像不在本地,启动将失败。不要假设即使镜像被删除,它也会自动恢复;应同时建立镜像保留和更新的流程。官方 httpd 镜像的 web 根目录可以在 httpd 镜像指南 中查看。

编写完整的 Quadlet 并检查生成结果

将下面的整个配置保存在同一个终端中。由于 heredoc 的 CONF 未加引号,之前定义的 $image 将被展开为实际的摘要。此文件是该用户的配置文件。

cat > "$qdir/lf-web28.container" <<CONF
[Unit]
Description=LF rootless web lab 28

[Container]
Image=$image
ContainerName=lf-web28
PublishPort=127.0.0.1:8080:80
Volume=lf-web28-data:/usr/local/apache2/htdocs:ro
Pull=never

[Service]
Restart=on-failure
RestartSec=2
TimeoutStartSec=180

[Install]
WantedBy=default.target
CONF
设置 含义
PublishPort=127.0.0.1:8080:80 仅将端口发布到虚拟机的回环地址。
Volume=...:ro 以只读方式挂载网页数据卷。
Restart=on-failure 请求 systemd 重新启动因失败而退出的服务。
RestartSec=2 重启之间的等待时间。这不会移除重复失败的限制。
TimeoutStartSec=180 设置等待服务启动的时间限制。这不会检查 HTTP 就绪状态。
WantedBy=default.target 生成器连接以从用户管理器的默认目标启动。

在让用户管理器读取新源文件之前,将生成器搜索范围限定为实训目录,检查生成结果,再执行 daemon-reload。--dryrun 是查看生成内容的功能,并不会启动容器。

QUADLET_UNIT_DIRS="$qdir" /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
systemctl --user daemon-reload
systemctl --user cat lf-web28.service
systemctl --user show lf-web28.service -p FragmentPath -p SourcePath

在此虚拟机上,SourcePath 是主目录中的 lf-web28.container,FragmentPath 是 /run/user/1000/systemd/generator/lf-web28.service。生成的文件包括 Podman 的运行/清理命令及镜像摘要。如果服务不存在,请检查源路径、文件扩展名、支持的键和生成器错误,并且不要手动创建或覆盖生成的文件。

启用 linger,启动服务并检查 HTTP

启用 linger 会在启动时启动此账户的用户管理器,并在注销后保持其可用。正如 Debian loginctl 手册 所解释的,这影响的是用户管理器,而不仅仅是这个单个服务。在记录的实验中,linger 初始值为 no,仅在验证时改为 yes。

sudo loginctl enable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger
systemctl --user start lf-web28.service
systemctl --user is-active lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/
podman port lf-web28

预期响应为 LF QUADLET 28。“active” 意味着生成的服务处于活动状态,但不等同于 HTTP 已就绪。在验证中,启动后立即发出的一个请求以Empty reply from server(服务器返回空响应)失败,但在服务准备好后成功。不要将所有失败归因于就绪延迟;尝试在短时间后再次请求,如果继续失败,请检查以下日志以及端口和卷的状态。

systemctl --user status lf-web28.service --no-pager
journalctl --user -u lf-web28.service -n 50 --no-pager
podman logs lf-web28
podman inspect lf-web28

将失败重启与显式停止进行比较

以下比较仅限于提供静态文件的专用实践容器。不要将强制终止测试直接应用于实际写入服务(如数据库)。首先,记录容器ID和重启次数,然后发送KILL信号以产生故障终止。

first=$(podman inspect lf-web28 --format '{{.Id}}')
systemctl --user show lf-web28.service -p NRestarts
podman kill --signal KILL lf-web28
sleep 3
systemctl --user is-active lf-web28.service
systemctl --user show lf-web28.service -p NRestarts
podman inspect lf-web28 --format '{{.Id}}'
curl --noproxy '*' -fsS http://127.0.0.1:8080/

在验证中,NRestarts增加,容器ID发生变化,并且HTTP响应再次成功。3秒只是作为启动检查的示例,并不保证在所有环境下的恢复时间。如果重复故障达到上限,请纠正日志中发现的原因,然后仅对受影响的服务执行reset-failed并重启。重启次数可以通过管理员重启进行重置,并且不会原样用于长期故障统计。

现在在 systemd 中明确请求停止。即使设置了 Restart=on-failure,也不意味着服务会在管理员发出停止请求后自动重启。策略的条件请参见 systemd 服务重启说明 。

systemctl --user stop lf-web28.service
sleep 3
if systemctl --user is-active --quiet lf-web28.service; then
    echo "The explicitly stopped service is still active." >&2
    exit 1
fi
systemctl --user show lf-web28.service -p ActiveState
podman ps -a --filter name=lf-web28
systemctl --user start lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/

停止后,结果显示为非活动状态,并且专用容器也已被移除。如果容器仍处于活动状态,示例会报错停止;如果正常停止,会在重启前检查 ActiveState=inactive。如果在启动后响应未立即准备好,请按照上一节所述检查状态和日志,然后重试请求。卷在容器移除后仍独立存在。

验证登录前的启动和注销后的持久性

重启后,使用相同的用户通过SSH登录,而服务处于活动状态本身并不能证明在登录之前自动启动。这是因为用户管理的服务可能在登录过程中启动。在本教程中,调度了一个以 root 身份执行 HTTP GET 的独立观测探针,它不依赖用户服务,用于在没有登录会话存在的时间记录响应和会话列表。

为了以相同方式进行验证,在确认以下所有专用路径不存在后,可以准备一个root管理探针。它不会修改其他服务器上的现有定时器或日志。即使代码以root身份运行,它也仅执行HTTP GET和会话查询,并写入自己仅限root的证据日志;它不会添加诸如user@1000.service之类的依赖项。

for p in /var/backups/lf-debian13-28 /usr/local/sbin/lf-boot28-probe /etc/systemd/system/lf-boot28-probe.service /etc/systemd/system/lf-boot28-probe.timer; do
    if test -e "$p"; then echo "Already exists: $p" >&2; exit 1; fi
done
sudo install -d -m 700 /var/backups/lf-debian13-28
sudo tee /usr/local/sbin/lf-boot28-probe > /dev/null <<'PROBE'
#!/bin/bash
set -euo pipefail
label=${1:-boot}
case "$label" in boot|logout) ;; *) exit 1;; esac
dest="/var/backups/lf-debian13-28/$label-$(cat /proc/sys/kernel/random/boot_id).txt"
{
  date -u --iso-8601=seconds
  cat /proc/uptime
  loginctl list-sessions --no-legend
  for i in $(seq 1 15); do
    if curl --noproxy '*' --max-time 2 -fsS http://127.0.0.1:8080/ | grep -Fx 'LF QUADLET 28'; then echo HTTP_PROBE_PASSED; exit 0; fi
    sleep 1
  done
  exit 1
} > "$dest" 2>&1
PROBE
sudo chmod 700 /usr/local/sbin/lf-boot28-probe
sudo tee /etc/systemd/system/lf-boot28-probe.service > /dev/null <<'UNIT'
[Unit]
Description=Read-only HTTP evidence before user login for lab 28
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/lf-boot28-probe boot
UNIT
sudo tee /etc/systemd/system/lf-boot28-probe.timer > /dev/null <<'TIMER'
[Unit]
Description=One boot HTTP evidence for lab 28
[Timer]
OnBootSec=35s
AccuracySec=1s
Unit=lf-boot28-probe.service
[Install]
WantedBy=timers.target
TIMER
sudo systemctl daemon-reload
sudo systemctl enable lf-boot28-probe.timer

首先,测试在注销后是否仍然保持。如果下面的调度成功,请注销目标用户的所有交互式会话,至少等待70秒,然后重新登录以读取记录的数据。在调度后立即保持会话打开不是注销验证。如果一个具有相同名称的临时单元仍然存在,请检查现有状态并避免重复执行。

sudo systemd-run --unit=lf-logout28-probe --on-active=15s --timer-property=AccuracySec=1s /usr/local/sbin/lf-boot28-probe logout

探针在其重试循环之前记录会话列表,因此仅凭该列表是不够的,如果您在它仍在重试时登录。重新连接后,检查 sudo journalctl -b -u lf-logout28-probe.service --no-pager 并将成功作业完成时间与 loginctl session-status 显示的登录时间进行比较。重启后使用 lf-boot28-probe.service 的等效日志查询。仅在探针成功并在目标用户登录前完成时接受证据。在比较 UTC 文件时间戳与日志/会话时间时要考虑时区偏移。70/90 秒的等待时间是为了允许探针在正常负荷下进行有限重试;仅凭经过时间并不能作为证据。

再次登录后,使用以下命令检查探针的时间、会话列表和 HTTP_PROBE_PASSED。区分 class=manager 的用户管理器会话与 class=user 的实际登录会话。若执行探针时目标账户仍有其他实际登录会话,就不能将结果作为该账户全部登出后服务仍持续运行的证据。

sudo cat "/var/backups/lf-debian13-28/logout-$(cat /proc/sys/kernel/random/boot_id).txt"
sudo systemctl show lf-logout28-probe.service -p Result -p ExecMainStatus

在检查控制台访问权限及对其他正在运行服务的影响后,正常重启虚拟机的步骤如下。重启前记录启动 ID,重启后保持该用户至少 90 秒未登录。在计时结束前访问可能会导致结果混淆,因此也要将记录的时间与实际登录时间进行比较。

cat /proc/sys/kernel/random/boot_id
sudo systemctl reboot

再次登录后,检查新的启动 ID 是否与之前不同,并读取该启动的记录。如果没有日志或操作失败,则不视为自动启动成功。

cat /proc/sys/kernel/random/boot_id
sudo cat "/var/backups/lf-debian13-28/boot-$(cat /proc/sys/kernel/random/boot_id).txt"
systemctl --user is-active lf-web28.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/

在验证虚拟机上,当仅存在管理会话且状态为 lingering 时,新启动后大约 46 秒 HTTP 请求成功。另行的注销测试在没有实际用户会话时也成功。由于最初使用默认计时器精度安排的探测与验证重新登录时间重叠,因此未被作为证据,它已被重新检查,指定 AccuracySec=1s。标准是查看登录前结果是否保持,而不是精确执行时间。

移除源文件与卷并恢复原来的 linger 设置

停止将会中止当前执行,但如果原始文件带有[Install],它可能会在下次用户管理器启动时恢复。要删除练习设置,请删除相应的原始文件并运行daemon-reload以清理生成的链接。下面的第一个块应以普通用户身份运行。

systemctl --user stop lf-web28.service
rm -- "$HOME/.config/containers/systemd/lf-web28.container"
systemctl --user daemon-reload
podman ps -a --filter name=lf-web28
podman volume rm lf-web28-data

删除卷意味着删除数据,所以首先保存任何必要的内容。然后,仅删除练习系统定时器和脚本。证据记录可以保留在仅限root的备份路径中。

sudo systemctl disable --now lf-boot28-probe.timer
sudo rm -- /etc/systemd/system/lf-boot28-probe.timer /etc/systemd/system/lf-boot28-probe.service /usr/local/sbin/lf-boot28-probe
sudo systemctl daemon-reload
original_linger=$(cat "$HOME/lf-course28-linger-before.txt")
case "$original_linger" in
    no) sudo loginctl disable-linger "$(id -un)" ;;
    yes) echo "Preserving the original enabled linger state." ;;
    *) echo "Cannot determine the original linger value." >&2; exit 1 ;;
esac
loginctl show-user "$(id -un)" -p Linger
ss -ltn

在实际清理过程中,专用的 Quadlet 源文件、生成的服务、容器、卷和探针已被删除,8080 端口监听器已关闭,linger 设置恢复为原来的“no”。现有的镜像和其他服务被保留。在决定是否继续运行常规用户服务时,需要一起管理账户生命周期、数据保留,以及更新和恢复程序。