Podman Quadlet服务如何配置开机自启,并验证容器依赖关系?
要让 Podman Quadlet 容器在服务器开机后自动运行,需要把 Quadlet 文件放进正确的搜索目录,在需要自启的容器文件中写入 [Install],并确保对应的 systemd 管理器会在开机时启动。要验证容器依赖,不能只看两个容器是否都在运行:还要检查生成的 service 依赖、启动顺序,以及被依赖容器何时真正就绪。(docs.podman.io)
下面以 Linux 上的非 root 部署为例:PostgreSQL 提供数据库,Adminer 提供仅监听本机的管理界面。目标是开机后由 Adminer 的启动请求带起数据库,并等数据库通过健康检查后再启动 Adminer。示例用于说明 Quadlet 机制,不表示已经在您的服务器上执行;若服务器已有数据库或管理界面,请先核对名称、端口和数据卷,避免覆盖现有部署。
对于需要长期运行容器、数据库与管理后台的业务,A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器资源,覆盖Xeon、AMD EPYC、SSD及NVMe存储,并提供不同内存与带宽线路配置,可承载Podman容器服务、数据库和多任务后台。
准备条件
操作应由实际运行容器的普通用户在自己的登录会话中完成,不要一部分使用 sudo podman、另一部分使用普通用户的 podman:两者管理的容器和存储并不相同。服务器需要安装 Podman、systemd,并能以该用户访问镜像仓库;本机 TCP 8080 端口应未被占用。Quadlet 还要求系统使用 cgroup v2。先核对环境,而不是预设发行版或安装包名称。(docs.podman.io)
id -un
podman --version
systemctl --version
podman info --format '{{.Host.CgroupsVersion}}'
systemctl --user is-active default.target
ss -ltn '( sport = :8080 )'
预期 cgroup 检查输出 v2;用户管理器能够响应 systemctl --user;最后一条命令没有显示占用 8080 的监听项。如果用户管理器报“无法连接到总线”,先确认当前处于该用户的正常登录会话,再检查其 user manager 状态。不要在尚未解决会话问题时继续写自启配置。
本例使用 PostgreSQL 16 和 Adminer 5.5.1 镜像。先拉取并确认镜像存在,可把“开机时镜像下载失败”和“Quadlet 配置失败”区分开;具体标签在实施前也应以仓库可用情况核验。PostgreSQL 16 的数据卷挂载点采用 /var/lib/postgresql/data,不要直接照搬其他主版本的目录。
podman pull docker.io/library/postgres:16
podman pull docker.io/library/adminer:5.5.1
podman image exists docker.io/library/postgres:16
podman image exists docker.io/library/adminer:5.5.1
两条 image exists 均以退出状态 0 结束,才进入下一步。示例中的 Pull=never 随后会要求启动时使用这些本地镜像;它不会阻止管理员日后有计划地更新镜像。
写入 Quadlet 文件
1. 准备目录和数据库口令
普通用户的持久化 Quadlet 目录为 ~/.config/containers/systemd/。以下命令仅创建本例文件;若目录中已有配置,先检查同名文件,不要直接覆盖。数据库口令文件属于敏感输入,应限制读取权限,并纳入服务器备份及凭据管理安排。Quadlet 的 EnvironmentFile= 可以引用相对于 Quadlet 文件所在目录的路径。(docs.podman.io)
D="$HOME/.config/containers/systemd"
mkdir -p "$D"
ls -l "$D"/demo-net.network "$D"/demo-data.volume \
"$D"/demo-db.container "$D"/demo-ui.container "$D"/demo-db.env 2>/dev/null
若 ls 显示任何同名文件,先停下并备份、核对归属;在全新目录中找不到文件是预期情况。确认没有冲突后,在交互式 Bash 会话中输入一个不含换行符的强口令:
umask 077
read -r -s -p '设置 PostgreSQL 口令:' DB_PASSWORD
printf '\n'
printf 'POSTGRES_PASSWORD=%s\n' "$DB_PASSWORD" > "$D/demo-db.env"
unset DB_PASSWORD
chmod 600 "$D/demo-db.env"
stat -c '%a %n' "$D/demo-db.env"
预期权限显示为 600。不要用 cat 把口令打印到终端或工单中。环境文件适合演示首次部署,但环境变量仍可能通过容器检查接口等途径被有权限的人员读取;正式环境应按自身凭据管理要求评估 Podman secret 等方式。
2. 定义网络、数据卷和数据库
先写入网络与数据卷定义,再写数据库容器。Network=demo-net.network、Volume=demo-data.volume:... 引用的是 Quadlet 文件名,不是手工创建的 Podman 资源名。Quadlet 会为这些引用生成相应 service 依赖。本例让 PostgreSQL 使用网络别名 db,且不向宿主机发布数据库端口。
cat > "$D/demo-net.network" <<'EOF'
[Network]
Driver=bridge
EOF
cat > "$D/demo-data.volume" <<'EOF'
[Volume]
EOF
cat > "$D/demo-db.container" <<'EOF'
[Unit]
Description=Quadlet demo PostgreSQL
[Container]
Image=docker.io/library/postgres:16
Pull=never
ContainerName=demo-db
Network=demo-net.network
NetworkAlias=db
Volume=demo-data.volume:/var/lib/postgresql/data
EnvironmentFile=./demo-db.env
HealthCmd=pg_isready -h 127.0.0.1 -U postgres -d postgres
HealthInterval=5s
HealthTimeout=3s
HealthRetries=12
HealthStartPeriod=30s
Notify=healthy
[Service]
Restart=on-failure
TimeoutStartSec=300
EOF
这里没有给数据库写 [Install]:它会作为 Adminer 的必需依赖被拉起。Notify=healthy 配合 HealthCmd=,使数据库 service 等到容器健康检查通过才向 systemd 报告启动完成;仅写 After=、不设置就绪信号,只能保证启动任务的顺序,不能保证数据库已经可以连接。pg_isready 检查的是数据库是否接受连接,不是一次口令认证或业务查询。(docs.podman.io)
先核对文件内容和权限:网络、卷、容器文件应位于同一目录;demo-db.env 不应被其他用户读取。若原目录已有同名网络或数据卷定义,不要通过改名掩盖资源冲突,应先查清它们服务于哪些容器。
3. 定义需要开机启动的界面
Adminer 通过 Requires= 请求启动数据库,通过 After= 等待数据库 service 完成启动。两项作用不同:Requires= 不会自动规定顺序,After= 也不会单独把数据库拉起来。WantedBy=default.target 则让该用户的 systemd 管理器启动时带起 Adminer。

cat > "$D/demo-ui.container" <<'EOF'
[Unit]
Description=Quadlet demo Adminer
Requires=demo-db.service
After=demo-db.service
[Container]
Image=docker.io/library/adminer:5.5.1
Pull=never
ContainerName=demo-ui
Network=demo-net.network
Environment=ADMINER_DEFAULT_SERVER=db
PublishPort=127.0.0.1:8080:8080
[Service]
Restart=on-failure
TimeoutStartSec=300
[Install]
WantedBy=default.target
EOF
demo-db.container 生成 demo-db.service,所以依赖中必须写 .service,不能写 .container。Adminer 只绑定宿主机的 127.0.0.1:8080,适合在服务器本机检查;这不是对公网开放管理界面的配置。Adminer 镜像支持用 ADMINER_DEFAULT_SERVER 预填数据库主机。(docs.podman.io)
生成服务并验证依赖
Quadlet 文件写好后,先重新运行用户级 systemd 生成器,再检查 service 是否出现。不要对生成的 Quadlet service 执行 systemctl --user enable:它的开机挂载关系由生成器依据源文件的 [Install] 建立。(docs.podman.io)
systemctl --user daemon-reload
systemctl --user list-unit-files 'demo-*.service'
systemctl --user show demo-ui.service -p Requires -p After -p FragmentPath
systemctl --user list-dependencies default.target | grep demo-ui.service
预期可以看到 demo-db.service、demo-ui.service、demo-net-network.service 和 demo-data-volume.service 等生成单元;demo-ui.service 的 Requires 与 After 中均包含 demo-db.service;用户的 default.target 依赖列表包含 demo-ui.service。卷与网络的 Podman 资源默认分别使用 systemd-demo-data、systemd-demo-net 这样的名称,不要把资源名误认为 service 名。(docs.podman.io)
接着只启动界面 service,观察数据库是否被自动带起:

systemctl --user start demo-ui.service
systemctl --user is-active demo-db.service demo-ui.service
podman inspect demo-db --format '{{.State.Health.Status}}'
podman ps --format '{{.Names}} {{.Status}}'
curl -I http://127.0.0.1:8080/
预期两个 service 均为 active,数据库健康状态为 healthy,podman ps 中有 demo-db 与 demo-ui,本机 HTTP 请求返回响应头。curl 能收到登录页,只证明管理界面可达;再用浏览器在本机打开该地址,选择 PostgreSQL,以服务器 db、用户 postgres 和刚设置的口令登录,并执行 SELECT 1;,才能进一步确认网络别名和数据库认证链路。
需要观察启动过程时,可看同一次启动中的日志:
journalctl --user -b -u demo-db.service -u demo-ui.service \
--no-pager -o short-iso
日志可辅助判断先后,但验收依据应以生成的依赖、数据库 healthy 状态和实际连接结果为主。对于已经运行的服务,单看某次时间戳还不足以证明下一次开机也会自启。
让非 root 服务在开机时运行
非 root Quadlet 属于用户级 systemd 服务。如果用户管理器只在登录期间存在,那么 [Install] 写对了,也不能据此断言“无人登录时已在开机运行”。在有授权的前提下,为运行容器的用户启用 lingering;它会让该用户的管理器在开机时启动,并在用户登出后继续存在。此操作影响该用户的其他用户级服务,实施前先记录原值。

loginctl show-user "$USER" -p Linger
sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" -p Linger
预期第二次检查显示 Linger=yes。如果首次检查已经是 yes,无需重复设置,并在回滚时保留原状态。启用 lingering 不代替前面的 [Install]:前者解决用户管理器何时运行,后者决定哪些 Quadlet 服务随该管理器启动。
最终开机验证应安排在允许重启的维护窗口,先确认远程登录与其他业务的恢复方案。重启后,以同一普通用户登录并检查:
loginctl show-user "$USER" -p Linger
systemctl --user is-active demo-db.service demo-ui.service
podman inspect demo-db --format '{{.State.Health.Status}}'
journalctl --user -b -u demo-db.service -u demo-ui.service \
--no-pager -o short-iso
如果日志显示服务是在本次开机期间启动、两个 service 为 active、数据库为 healthy,再完成一次 Adminer 登录,即可把“配置了自启”和“重启后实际可用”区分验证。
常见失败及处理
按低风险到高风险排查,避免一看到启动失败就删除容器或数据卷。

- 找不到
demo-ui.service:先检查文件是否位于当前用户的 Quadlet 目录、扩展名是否为.container,再运行systemctl --user daemon-reload。仍找不到时,用systemd-analyze --user --generators=true verify demo-ui.service检查生成错误,并对照本机man podman-systemd.unit核验配置项是否受已安装版本支持。不要手工改写生成的.service文件。(docs.podman.io) - 生成了 service,但数据库未健康:查看
journalctl --user -u demo-db.service -b --no-pager与podman logs demo-db。如果提示口令文件不存在或权限不符,核对demo-db.env的位置和权限;如果提示数据目录问题,先确认卷中是否已有数据、镜像主版本是否匹配,再决定恢复方案。PostgreSQL 初始化口令只对空数据目录的首次初始化起作用,改环境文件不会自动修改已有数据库口令。 - 数据库健康、界面却无法连接:先检查
demo-ui.service状态及日志,再检查两个容器是否接入同一网络,以及界面预填的服务器是否为db。若 HTTP 可达但登录失败,应区分数据库认证失败与网络失败;不要通过开放 PostgreSQL 宿主机端口来绕过本例的容器网络。 - 手动启动正常、重启后不运行:分别核对
Linger=yes、default.target是否包含demo-ui.service,以及本次开机的用户级日志。前两者任何一项缺失,都是与“开机自启”直接相关的线索。 - 启动超时:确认镜像确实已由该普通用户拉取、
Pull=never没有指向不存在的镜像,并检查健康命令及数据库初始化日志。只有在明确知道初始化需要更久时,才调整TimeoutStartSec;增加超时时间不能修复口令或数据目录错误。
验收与回滚检查
验收时应同时确认:default.target 会带起 demo-ui.service;demo-ui.service 同时具有指向 demo-db.service 的 Requires 和 After;数据库健康后界面才完成启动;重启后两个 service 仍为 active;Adminer 能以 db 为主机完成登录。这里的依赖解决的是首次启动顺序与就绪等待,不应把它理解为数据库在运行期出现任何故障时,界面和业务连接都能自动恢复。
如果需要撤销本例,先确认这五个文件确实由本次部署创建,并记录 lingering 原状态。停止服务会中断当前管理界面及数据库访问;移动配置会取消后续自动生成。以下操作将文件保存在权限为 700 的备份目录,不删除数据库数据卷:
D="$HOME/.config/containers/systemd"
B="$HOME/quadlet-demo-backup-$(date +%Y%m%d%H%M%S)"
install -d -m 700 "$B"
systemctl --user stop demo-ui.service demo-db.service
mv "$D/demo-ui.container" "$D/demo-db.container" \
"$D/demo-net.network" "$D/demo-data.volume" \
"$D/demo-db.env" "$B/"
systemctl --user daemon-reload
systemctl --user list-unit-files 'demo-*.service'
podman volume exists systemd-demo-data
预期 Quadlet 示例 service 不再出现在生成单元列表中;podman volume exists 成功则表示数据卷仍在,不代表数据库备份已经完成。如需恢复,确认未改变数据库镜像主版本后,把文件移回原目录、执行 systemctl --user daemon-reload,再启动 demo-ui.service 并重做健康及登录检查。只有当本次实施把 lingering 从 no 改为 yes,且确认该用户没有其他依赖它的服务时,才考虑运行 sudo loginctl disable-linger "$USER";否则保留原设置。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8680.html



