podman-quadlet

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 # 持续跟踪(Ctrl+C 退出)

# 进入正在运行的容器
podman exec -it myapp bash # bash 可用时
podman exec -it myapp sh # Alpine 等精简镜像

# 查看容器详情(IP、挂载、环境变量等)
podman inspect myapp | less

# 查看资源占用(CPU、内存、网络、磁盘)
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
# Fedora/SELinux 必须加 :Z ─┘

# 删除卷
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 # 宿主机 8080 → 容器 80
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 # 系统级服务(不推荐 rootless 场景)

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
# 列出所有已发现的 Quadlet 文件及其状态
podman quadlet list

# 预览某个 .container 将生成的 systemd 单元内容(不实际加载)
podman quadlet print ~/.config/containers/systemd/astrbot.container

# 手动安装(将生成的单元写入 ~/.config/systemd/user/,通常不需要)
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
# 1. 写完 .container 后预览生成的 service
podman quadlet print ~/.config/containers/systemd/astrbot.container

# 2. 确认无误后重新加载
systemctl --user daemon-reload

# 3. 查看 Quadlet 自动生成的 service 文件
cat ~/.config/systemd/user/astrbot.service

# 4. 启动并跟踪日志
systemctl --user start astrbot.service
journalctl --user -u astrbot.service -f

# 5. 若启动失败,检查容器自身日志
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
# 1. 开启 linger(用户登出后服务不终止)
sudo loginctl enable-linger "$USER"

# 2. 创建 Quadlet 目录
mkdir -p ~/.config/containers/systemd # .container 文件
mkdir -p ~/.config/systemd/user # 生成的 service 文件

# 3. 验证
loginctl show-user "$USER" -p Linger # Linger=yes

.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
# 1. 创建数据目录
mkdir -p ~/astrbot/data

# 2. 写入 .container 文件
vim ~/.config/containers/systemd/astrbot.container

# 3. 重新加载 systemd(Quadlet 自动生成 service 单元)
systemctl --user daemon-reload

# 4. 拉取镜像并启动
systemctl --user start astrbot.service

# 5. 查看状态
systemctl --user status astrbot.service

# 6. 跟踪日志(确认启动成功)
journalctl --user -u astrbot.service -f

# 7. 开机自启
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
# 启停 → systemd
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
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

# 自动更新(需 [Container] 中配置 AutoUpdate=registry)
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          # 查看 SELinux 上下文
sudo ausearch -m avc -ts recent # 查看最近的 SELinux 拒绝事件

只读挂载宿主目录(工作方法)

适用场景:迁移 / 备份,容器只读访问宿主数据
目标:容器能读宿主机指定目录,但永远写不进去,宿主数据不被容器改动

方法流程

三步走:加挂载 -> 重载重启 -> 验证读写

1
2
# [Container] 段追加一行,`:ro` = 只读
Volume=/home/fedora/WorkSpace/Projects:/WorkSpace/Projects:ro
1
2
3
4
5
6
7
# 生效(restart 会中断容器几秒)
systemctl --user daemon-reload
systemctl --user restart astrbot

# 验证:读放行、写被拒
podman exec astrbot ls /WorkSpace/Projects # 应能列出
podman exec astrbot touch /WorkSpace/Projects/__ro__ # 应报 Read-only file system

关键坑::ro 只挡写,SELinux 连读一起拦

只加 :ro 时,写被拒(符合预期),但读也报 Permission denied:

1
2
podman exec astrbot ls /WorkSpace/
# ls: cannot open directory '/WorkSpace/': Permission denied

原因:宿主目录默认 user_home_t,容器域 container_t 无权读。对比两个挂载源的上下文:

1
2
3
ls -Zd /home/fedora/WorkSpace /home/fedora/astrbot/data
# unconfined_u:object_r:user_home_t:s0 ← 容器读不了
# system_u:object_r:container_file_t:s0:c82,c271 ← 可读写挂载(:Z 重标过)

放行读::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)

三个务必

  1. z 会递归重标宿主源目录——只改元数据不改内容,但含 .ssh/.gitconfig 等点文件的目录不要整目录挂,逐项挂子目录更安全
  2. 敏感目录直接不挂——Configs(含点文件软链)这类目录跳过,其余按文件树逐项挂载
  3. 迁移完整性——SQLite 库 data_v4.db 伴随 -wal/-shm 日志,运行中复制会不一致;先 systemctl --user stop astrbot 再整目录拷贝,拷完 start