Podman Quadlet 教程：用 systemd 管理 rootless 容器
使用 .container 与 .volume 声明文件管理 Podman 容器，覆盖 rootless 路径、开机启动、卷、端口、日志和生成器排错。
Podman Quadlet 教程：把容器交给 systemd
这篇 Podman Quadlet 教程介绍如何用声明文件生成 systemd 服务。Quadlet 支持 container、volume、network、pod 等单元类型，管理员维护简洁文件，Podman 生成器在 systemd 加载时转换为服务。下面采用 rootless 模式，降低容器获得主机高权限的风险。
确认环境与文件路径
官方参考指出 Quadlet 依赖 cgroup v2，可先用 podman info 检查。rootless 文件通常放在 ~/.config/containers/systemd/，rootful 文件放在 /etc/containers/systemd/。两种模式的 systemctl 和日志命令不同，不要混用。
为专用账号创建目录，并确认其他用户不能修改单元文件。rootless 服务若需在退出登录后继续运行，应由管理员评估并配置用户 linger。系统侧账户和 SSH 管理可参考Linux 安全基线。
创建第一个 container 单元
建立 web.container：
[Unit]
Description=Rootless web container
After=network-online.target
[Container]
Image=docker.io/library/nginx:alpine
PublishPort=127.0.0.1:8080:80
Volume=webdata.volume:/usr/share/nginx/html:Z
[Service]
Restart=on-failure
TimeoutStartSec=300
[Install]
WantedBy=default.target端口只绑定本机，适合由反向代理提供外部入口。镜像应在生产中固定到经过验证的标签或摘要，避免重启时意外取得不同内容。TimeoutStartSec 为首次拉取镜像留出时间；官方文档提醒，拉取或构建可能超过 systemd 默认启动等待。
创建持久卷并加载
建立 webdata.volume：
[Volume]
VolumeName=webdata
Label=purpose=web执行 systemctl --user daemon-reload 后，生成器会创建对应服务。用 systemctl --user start web.service 启动，再通过 systemctl --user status web.service 和 journalctl --user -u web.service 检查。Quadlet 生成的服务本身不应直接执行传统 enable；开机关系由源文件的 [Install] 部分声明并在重新加载时生成。
卷提供持久数据，但不是备份。删除容器通常不会删除命名卷，删除卷则可能造成数据不可恢复。应建立独立备份，并参考Docker Compose 数据备份教程理解数据库一致性与恢复演练。
配置依赖、机密与更新
多个容器可通过 .network、.volume 和 Unit 依赖建立启动顺序。不要仅依靠容器启动顺序判断应用已经就绪；数据库和 Web 服务仍需要健康检查、重试或显式等待机制。机密不要直接写入可读的 Quadlet 文件或镜像，应使用 Podman secret 或权限受限的环境文件。
更新镜像前，先备份数据，拉取目标版本并在临时端口验证。然后重启服务，观察日志和业务状态。保留上一版本镜像及回退步骤，避免把自动拉取最新标签当作发布策略。
排查 unit not found
如果 systemctl 找不到生成服务，最常见原因是源文件语法错误、文件路径错误或使用了当前 Podman 版本不支持的选项。官方基础指南建议通过 systemd generator 的验证模式查看具体错误。还应确认文件后缀正确、用户会话读取到预期目录，并在修改后执行 daemon-reload。
可用 systemctl --user cat web.service 查看生成结果，但不要直接编辑 /run 下的临时服务文件，因为下次重新加载会覆盖它。真正的配置来源始终是 .container、.volume 等 Quadlet 文件。
上线与回滚清单
上线前验证镜像来源、端口绑定、卷挂载标签、运行账号、重启策略、日志、备份和恢复。若启用 linger，还要明确账号生命周期和资源限制。回滚时恢复旧 Quadlet 文件与旧镜像，重新加载 systemd，再核对数据格式是否仍兼容。
Quadlet 的优势在于用 systemd 管理容器生命周期，同时保留简洁的容器声明。把源文件纳入版本控制、把机密独立管理、把数据持续备份，才能让 rootless 容器成为可审计的长期服务。
