Podman-Quadlet
Podman
核心概念:无守护进程
Podman 没有后台守护进程,每个容器都是 fork 出的子进程
- 不需要超级用户权限(
sudo systemctl start docker)开箱即用
- Rootless 运行,容器在用户UID下运行,无需root权限
- 语法与docker基本兼容
镜像管理
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
| podman search nginx
podman pull docker.io/library/nginx:latest
podman images
podman image inspect nginx:latest
podman rmi nginx:latest
podman image prune
|
容器生命周期
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
| podman run --rm -it alpine:latest sh
podman run -d --name myapp -p 8080:80 nginx:latest
podman ps
podman ps -a
podman stop myapp
podman start myapp
podman restart myapp
podman rm myapp
podman rm -f myapp
|
调试与查看
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
| podman logs myapp podman logs -f myapp
podman exec -it myapp bash podman exec -it myapp sh
podman inspect myapp | less
podman stats podman stats myapp
podman top myapp
|
卷与数据持久化
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
| podman volume create mydata
podman volume ls
podman run -d -v mydata:/data --name app myimage:latest
podman run -d -v /home/fedora/app:/data:Z --name app myimage:latest
podman volume rm mydata
podman volume prune
|
网络
1 2 3 4 5 6 7 8 9
| podman network ls
podman network inspect podman
podman run -d -p 8080:80 nginx:latest podman run -d -p 127.0.0.1:8080:80 nginx
|
清理
1 2 3 4 5
| podman container prune
podman system prune -a --volumes
|
与 Docker 的关键差异
|
Docker |
Podman |
| 守护进程 |
dockerd 常驻后台 |
无守护进程 |
| Rootless |
需要额外配置 |
原生支持 |
| 镜像存储 |
/var/lib/docker |
~/.local/share/containers |
| Compose |
docker compose |
podman compose(需装 podman-compose) |
| SELinux 卷标 |
通常不需要 |
绑定挂载必须加 :Z |
| 开机自启 |
restart policy |
Quadlet / systemd |
核心命令速记
1 2 3 4 5
| podman ps # 正在运行的镜像 podman logs -f <name> # <name>容器的运行日志 podman exec -it <name> sh # <name>容器内环境 podman inspect <name> # <name>容器的配置 podman system prune -a # 大清洗(慎用)
|
Quadlet
核心定位:Podman 原生的 systemd 集成方案
- Podman 项目第一方组件(
podman RPM 包内置),零额外依赖
.container 文件 → systemd 单元,自动生成 service
- 容器的生命周期交给 systemd 管理:开机自启、崩溃重启、日志走 journald
- 对比 podman-compose:无守护进程,不需要额外安装,适合长期运行的生产服务
Quadlet 配置与使用方式
核心机制:systemd 生成器
Quadlet 本身不运行任何守护进程,它是挂载在 systemd 上的 generator。每次执行 systemctl --user daemon-reload 时,Podman 的 systemd 生成器扫描 ~/.config/containers/systemd/ 目录,将 .container / .volume / .network / .pod / .build 文件实时转换成对应的 service 单元。这意味着:
- 文件→服务的转换是幂等的,改配置后只需
daemon-reload + restart
- 生成的 service 文件在
/run/user/1000/systemd/generator/ 或 ~/.config/systemd/user/ 下,可以直接 cat 查看
- 容器的整个生命周期由 systemd 接管,Quadlet 不参与运行时
文件类型与命名
Quadlet 根据文件后缀决定生成什么:
| 后缀 |
生成单元 |
用途 |
.container |
.service |
最常用,定义单个容器 |
.volume |
.volume |
命名卷(可跨容器共享) |
.network |
.network |
自定义网络 |
.pod |
.pod |
Pod(一组共享网络的容器) |
.build |
.image |
从 Containerfile 构建镜像 |
文件名中的 - 会被映射为 systemd 单元名中的 -,例如 astrbot-bot.container → astrbot-bot.service。
.container 文件标准结构
[Container] 段 —— 容器运行时参数,指令名与 podman run 参数一一对应:
| 指令 |
等价 CLI |
说明 |
Image= |
podman run <image> |
镜像地址,必填 |
ContainerName= |
--name |
容器名,省略则用单元名 |
PublishPort= |
-p |
端口映射,可多次出现 |
Volume= |
-v |
卷或绑定挂载,可多次出现 |
Environment= |
-e |
环境变量,可多次出现 |
Network= |
--network |
指定网络 |
Enforce=always |
podman rm -f + podman run |
每次启动强制重建容器(等价 --replace) |
AutoUpdate=registry |
— |
允许 podman auto-update 更新此容器 |
Pull=always |
--pull=always |
每次启动前拉取最新镜像 |
[Service] 段 —— 映射到 systemd service 单元,控制服务行为:
| 指令 |
说明 |
Restart=on-failure |
异常退出时自动重启 |
RestartSec=10 |
重启前的等待秒数 |
TimeoutStartSec=120 |
启动超时(秒),镜像较大的建议设长一些 |
Environment= |
也可放这里,效果相同 |
[Install] 段 —— systemd 启用/启动策略:
1 2 3
| [Install] WantedBy=default.target WantedBy=multi-user.target
|
Quadlet 内置变量
[Container] 段中以下占位符自动展开:
| 变量 |
展开值 |
%h |
当前用户 home 目录 |
%U |
当前用户名 |
%u |
当前 UID |
%t |
用户 systemd 运行时目录(/run/user/UID) |
%T |
系统临时目录(/tmp) |
Quadlet CLI 工具
Podman 内置了辅助管理 Quadlets 的命令:
1 2 3 4 5 6 7 8 9 10 11
| podman quadlet list
podman quadlet print ~/.config/containers/systemd/astrbot.container
podman quadlet install
podman quadlet rm astrbot.container
|
podman quadlet print 是调试利器——改完配置后先用它预览生成的 service,确认参数转换正确,再 daemon-reload。
调试流程
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
| podman quadlet print ~/.config/containers/systemd/astrbot.container
systemctl --user daemon-reload
cat ~/.config/systemd/user/astrbot.service
systemctl --user start astrbot.service journalctl --user -u astrbot.service -f
podman logs astrbot
|
Quadlet vs Podman Compose
|
Quadlet |
Podman Compose |
| 定位 |
Podman 原生方案 |
Docker Compose 兼容层 |
| 工作方式 |
.container 文件 → systemd 单元 |
翻译 compose.yml → podman 命令 |
| 生命周期管理 |
systemd(开机自启、崩溃重启) |
手动 up/down |
| 语法 |
systemd unit 风格,ini 格式 |
YAML,完全兼容 docker-compose |
| 依赖 |
零额外依赖(Podman 内置) |
需要安装 podman-compose |
| 适用场景 |
生产环境、长期运行的服务 |
开发调试、快速原型、Docker 迁移 |
环境要求与准备
1 2 3 4 5 6 7 8 9
| sudo loginctl enable-linger "$USER"
mkdir -p ~/.config/containers/systemd mkdir -p ~/.config/systemd/user
loginctl show-user "$USER" -p Linger
|
.container 文件参考(AstrBot 为例)
1 2 3 4 5 6 7 8 9 10 11 12 13 14
| [Container] Image=docker.io/soulter/astrbot:latest ContainerName=astrbot PublishPort=6185:6185 Volume=%h/astrbot/data:/AstrBot/data:Z Environment=TZ=Asia/Shanghai AutoUpdate=registry
[Service] Restart=on-failure RestartSec=10
[Install] WantedBy=default.target
|
字段说明:
%h — 自动展开为当前用户 home 目录
:Z — SELinux 标签重映射,Fedora 绑定挂载必须加
AutoUpdate=registry — 允许 podman auto-update 自动更新镜像
Restart=on-failure — 容器异常退出时自动重启,间隔 10 秒
部署流程
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
| mkdir -p ~/astrbot/data
vim ~/.config/containers/systemd/astrbot.container
systemctl --user daemon-reload
systemctl --user start astrbot.service
systemctl --user status astrbot.service
journalctl --user -u astrbot.service -f
systemctl --user enable astrbot.service
|
日常管理命令(AstrBot 场景)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
| systemctl --user start astrbot systemctl --user stop astrbot systemctl --user restart astrbot systemctl --user status astrbot journalctl --user -u astrbot -f systemctl --user enable astrbot systemctl --user disable astrbot
podman ps -a podman logs astrbot podman exec -it astrbot bash podman inspect astrbot | less podman stats astrbot
podman pull docker.io/soulter/astrbot:latest systemctl --user restart astrbot
podman auto-update
|
SELinux 注意事项
Fedora/RHEL 下 SELinux 默认 Enforcing,绑定挂载卷必须添加 :Z 后缀:
1 2
| Volume=%h/data:/app/data:Z ← 正确:自动重标 SELinux 上下文 Volume=%h/data:/app/data ← 错误:容器无法写入
|
podman logs 若报 Permission denied 相关错误,排查 SELinux:
1 2
| ls -Z ~/astrbot/data sudo ausearch -m avc -ts recent
|
只读挂载宿主目录(工作方法)
适用场景:迁移 / 备份,容器只读访问宿主数据
目标:容器能读宿主机指定目录,但永远写不进去,宿主数据不被容器改动
方法流程
三步走:加挂载 -> 重载重启 -> 验证读写
1 2
| Volume=/home/fedora/WorkSpace/Projects:/WorkSpace/Projects:ro
|
1 2 3 4 5 6 7
| systemctl --user daemon-reload systemctl --user restart astrbot
podman exec astrbot ls /WorkSpace/Projects podman exec astrbot touch /WorkSpace/Projects/__ro__
|
关键坑::ro 只挡写,SELinux 连读一起拦
只加 :ro 时,写被拒(符合预期),但读也报 Permission denied:
1 2
| podman exec astrbot ls /WorkSpace/
|
原因:宿主目录默认 user_home_t,容器域 container_t 无权读。对比两个挂载源的上下文:
1 2 3
| ls -Zd /home/fedora/WorkSpace /home/fedora/astrbot/data
|
放行读::ro 改为 :ro,z(z = 共享重标为 container_file_t:s0):
1
| Volume=/home/fedora/WorkSpace/Projects:/WorkSpace/Projects:ro,z
|
z or Z:
z — 共享标签 container_file_t:s0,可被多个容器读,只读共享场景用它
Z — 私有标签 container_file_t:s0:cXX,cYY(MCS 隔离),互不共享的数据卷用它(现有数据挂载即 Z)
三个务必
z 会递归重标宿主源目录——只改元数据不改内容,但含 .ssh/.gitconfig 等点文件的目录不要整目录挂,逐项挂子目录更安全
- 敏感目录直接不挂——
Configs(含点文件软链)这类目录跳过,其余按文件树逐项挂载
- 迁移完整性——SQLite 库
data_v4.db 伴随 -wal/-shm 日志,运行中复制会不一致;先 systemctl --user stop astrbot 再整目录拷贝,拷完 start