标签： RHEL

RHEL 10 使用 Podman Quadlet 实现容器开机自动启动
在 RHEL 10 Server 上使用 Podman 部署容器服务时，可以通过 Podman Quadlet 与 systemd 进行集成，将容器以 systemd 服务的方式统一管理。本文介绍如何使用 Kubernetes YAML 定义 Pod 和容器，并通过 Quadlet 配置实现容器服务的开机自动启动、停止、重启及状态管理，同时结合实际部署场景说明目录挂载、持久化数据以及服务管理中的常见问题，帮助在 RHEL Server 环境中建立更加规范、稳定的 Podman 容器运行方式。

相比手动执行：
```
podman kube play xxx.yaml
```
使用 Quadlet 后，可以让 systemd 负责容器服务的启动、停止和开机自动启动。

本文以 Uptime Kuma 为例，使用已有的 Kubernetes YAML 文件，通过 Quadlet 实现开机自动启动。

1. 准备 Podman Kube YAML

假设 Uptime Kuma 的 Kubernetes YAML 保存在：
```
/opt/data/uptime-kuma/uptime-kuma.yaml
```
例如：
```
apiVersion: v1
kind: Pod
metadata:
  name: uptime-kuma

spec:
  restartPolicy: Always

  containers:
    - name: uptime-kuma
      image: docker.io/louislam/uptime-kuma:2

      ports:
        - containerPort: 3001
          hostPort: 3001
          protocol: TCP

      env:
        - name: TZ
          value: "Asia/Shanghai"

      volumeMounts:
        - name: data
          mountPath: /app/data

      securityContext:
        capabilities:
          add:
            - NET_RAW
        runAsUser: 0
        runAsGroup: 0

  volumes:
    - name: data
      hostPath:
        path: /opt/data/uptime-kuma/data
        type: DirectoryOrCreate
```
先创建数据目录：
```
mkdir -p /opt/data/uptime-kuma
```
2. 创建 Quadlet 配置目录

root 用户使用的 Quadlet 文件可以放在：
```
/etc/containers/systemd/
```
创建目录：
```
mkdir -p /etc/containers/systemd
```
Podman 官方文档将 /etc/containers/systemd/ 作为 rootful Quadlet 的系统管理员配置目录。

3. 创建 .kube 文件

创建：
```
vim /etc/containers/systemd/uptime-kuma.kube
```
写入：
```
[Unit]
Description=Uptime Kuma Podman Pod

[Kube]
Yaml=/opt/data/uptime-kuma/uptime-kuma.yaml

[Install]
WantedBy=multi-user.target
```
这里最重要的是：
```
[Kube]
Yaml=/opt/data/uptime-kuma/uptime-kuma.yaml
```
它告诉 Quadlet 使用哪个 Kubernetes YAML 文件。

而：
```
[Install]
WantedBy=multi-user.target
```
表示该服务加入系统正常运行目标，从而实现系统启动时自动启动。

Podman 官方文档也明确给出了 .kube 配合 [Install] WantedBy=multi-user.target 实现开机启动的方式。

4. 重新加载 systemd

创建 Quadlet 文件后执行：
```
systemctl daemon-reload
```
Quadlet 会通过 systemd generator 根据：
```
/etc/containers/systemd/uptime-kuma.kube
```
生成对应的：
```
uptime-kuma.service
```
可以检查：
```
systemctl cat uptime-kuma.service
```
如果看到类似：
```
# Automatically generated by /usr/lib/systemd/system-generators/podman-system-generator
```
说明 Quadlet 已经正常识别。

也可以：
```
systemctl status uptime-kuma.service
```
5. 启动服务

直接启动：
```
systemctl start uptime-kuma.service
```
检查：
```
systemctl status uptime-kuma.service
```
正常情况下应该看到：
```
Active: active (running)
```
同时检查 Podman：
```
podman ps
```
应该可以看到 Uptime Kuma 容器正在运行。

6. 为什么不能执行 systemctl enable

这里有一个和普通 systemd 服务不同的地方。

不要执行：
```
systemctl enable uptime-kuma.service
```
Quadlet 生成的 systemd 服务属于 generated/transient unit，不能按照普通 .service 文件的方式执行 systemctl enable。

如果执行：
```
systemctl enable uptime-kuma.service
```
可能看到：
```
Failed to enable unit:
Unit /run/systemd/generator/uptime-kuma.service
is transient or generated
```
这不是 Quadlet 配置失败。

Quadlet 会在生成 systemd unit 时，根据 .kube 文件里的：
```
[Install]
WantedBy=multi-user.target
```
自动建立对应的启动关系。

这是 Podman Quadlet 与普通 systemd unit 的一个重要区别。

7. 验证开机自动启动

可以查看生成的服务：
```
systemctl cat uptime-kuma.service
```
确认存在：
```
[Install]
WantedBy=multi-user.target
```
然后可以重启服务器进行实际验证：
```
reboot
```
服务器重新启动后：
```
systemctl status uptime-kuma.service
```
以及：
```
podman ps
```
如果 Uptime Kuma 已经自动运行，就说明配置完成。

8. 日常管理

以后不需要再手动执行：
```
podman kube play uptime-kuma.yaml
```
直接使用 systemd：

启动：
```
systemctl start uptime-kuma.service
```
停止：
```
systemctl stop uptime-kuma.service
```
重启：
```
systemctl restart uptime-kuma.service
```
查看状态：
```
systemctl status uptime-kuma.service
```
查看日志：
```
journalctl -u uptime-kuma.service
```
实时查看日志：
```
journalctl -fu uptime-kuma.service
```
9. Quadlet 的工作原理

整个启动流程实际上是：
```
服务器开机
    │
    ▼
systemd
    │
    ▼
podman-system-generator
    │
    ▼
/etc/containers/systemd/uptime-kuma.kube
    │
    ▼
uptime-kuma.service
    │
    ▼
podman kube play
    │
    ▼
Uptime Kuma Pod
    │
    ▼
Uptime Kuma Container
```
因此，Kubernetes YAML 负责描述容器，Quadlet 负责把它交给 systemd 管理。

Podman 官方文档中，.kube 文件就是用于通过 podman kube play 将 Kubernetes YAML 作为 systemd 服务运行的 Quadlet 类型。

10. 最终目录结构

最终可以保持这样的结构：
```
/opt/data/uptime-kuma/
└── uptime-kuma.yaml

/opt/data/uptime-kuma/data
└── Uptime Kuma 数据

/etc/containers/systemd/
└── uptime-kuma.kube
```
其中：
```
uptime-kuma.yaml
```
负责定义 Pod 和容器。
```
uptime-kuma.kube
```
负责告诉 systemd 如何使用这个 YAML。
```
/opt/data/uptime-kuma/data
```
负责保存 Uptime Kuma 的持久化数据。
2026年10月3日
使用 Podman 部署 Cockpit 和 Immich 机器学习容器
使用 Podman 部署安装 Cockpit 管理工具并使用 Podman 启动 Immich 的机器学习容器。以便在浏览器中方便配置和访问

一、开放所需端口

在默认情况下，Linux 防火墙（firewalld）可能会阻止一些端口的外部访问。为了确保 Cockpit 和 Immich 模块能够正常被访问，需要永久放行相关端口。

1. 放行 9090 端口（用于 Cockpit）
```
firewall-cmd --add-port=9090/tcp --permanent
firewall-cmd --reload
```
2. 放行 3003 端口（用于 Immich 机器学习容器）
```
firewall-cmd --permanent --add-port=3003/tcp
firewall-cmd --reload
```
二、安装 Cockpit 和 Podman

Cockpit 是一款轻量级的 Web 管理工具，可用于查看系统信息、容器、服务等。
```
dnf install podman cockpit cockpit-podman -y
```
安装完成后，启用并启动 Cockpit：
```
systemctl enable --now cockpit.socket
```
然后可通过浏览器访问 Cockpit：
```
https://<你的服务器IP>:9090
```
注意：首次访问时浏览器可能提示 SSL 证书不安全，可选择“继续前往”。

三、部署 Immich Machine Learning 容器

Immich 是一个支持自动图片整理、面部识别等功能的自托管照片管理系统。我们配置immich的远程机器学习提高计算速度

1. 下载镜像
```
podman pull ghcr.io/immich-app/immich-machine-learning:release
```
2. 运行容器
```
podman run \
  --name immich_machine_learning \
  --restart=always \
  --replace \
  -p 3003:3003 \
  -v model-cache:/cache \
  -e TZ=Asia/Shanghai \
  -d \
  ghcr.io/immich-app/immich-machine-learning:release
```
此命令的作用如下：
- --name: 指定容器名称
- --restart=always: 容器自动重启策略
- --replace: 替换已有同名容器
- -p 3003:3003: 映射本地端口
- -v model-cache:/cache: 使用持久卷缓存模型
- -e TZ=Asia/Shanghai: 设置时区
- -d: 后台运行容器
四、配置容器开机自动启动（可选但推荐）

虽然运行容器时使用了 --restart=always，但 Podman 默认并不会像 Docker 一样在系统启动时自动重启容器。要实现真正的“开机自启”，需依赖 systemd 启动服务。

1. 生成并安装 systemd 单元文件
```
podman generate systemd --name immich_machine_learning --files --restart-policy=always
```
这将在当前目录生成 container-immich_machine_learning.service 文件。将其移动到系统服务目录并启用：
```
mv container-immich_machine_learning.service /etc/systemd/system/
systemctl daemon-reexec
systemctl enable container-immich_machine_learning.service
```
五、验证部署
- 访问 Cockpit Web 控制台查看容器状态：
  https://<你的服务器IP>:9090
- 访问 Immich ML 控制台查看容器状态：
  http://<你的服务器IP>:3003
2025年7月4日

标签： RHEL

RHEL 10 使用 Podman Quadlet 实现容器开机自动启动

1. 准备 Podman Kube YAML

2. 创建 Quadlet 配置目录

3. 创建 .kube 文件

4. 重新加载 systemd

5. 启动服务

6. 为什么不能执行 systemctl enable

7. 验证开机自动启动

8. 日常管理

9. Quadlet 的工作原理

10. 最终目录结构

使用 Podman 部署 Cockpit 和 Immich 机器学习容器

一、开放所需端口

1. 放行 9090 端口（用于 Cockpit）

2. 放行 3003 端口（用于 Immich 机器学习容器）

二、安装 Cockpit 和 Podman

三、部署 Immich Machine Learning 容器

1. 下载镜像

2. 运行容器

四、配置容器开机自动启动（可选但推荐）

1. 生成并安装 systemd 单元文件

五、验证部署

3. 创建 `.kube` 文件

6. 为什么不能执行 `systemctl enable`