使用 Podman 部署 Prefect 服务器

约 1165 字大约 4 分钟

prefect podman

2026-04-18

前言

Prefect 是一个现代的工作流编排平台，用于构建、调度和监控数据流水线。本文将介绍如何使用 Podman 部署 Prefect 服务器。

前置要求

在开始之前，请确保您已安装：

Podman 4.0 或更高版本
systemd（用于管理 Quadlet 服务）
足够的系统资源（建议至少 2CPU + 4GB 内存）
Rootless 模式已启用

第一步：验证 Podman 环境

首先，确认 Podman 已正确安装：

podman --version
podman info

第二步：创建 Podman 网络

为 Prefect 服务创建一个专用的网络，便于容器间通信。

创建网络配置文件

创建prefect.network文件：

[Network]
Name=prefect-network

部署网络

# 创建配置目录
mkdir -p $HOME/.config/containers/systemd

# 复制网络配置文件
cp prefect.network $HOME/.config/containers/systemd/

# 重新加载 systemd 配置
systemctl --user daemon-reload

# 查看网络状态
podman network inspect prefect-network

第三步：配置 Valkey 作为任务队列

Valkey 是 Redis 的一个分支，可用于 Prefect 的任务队列和缓存。

创建 Valkey Quadlet 配置

创建prefect-valkey.container文件：

[Unit]
Description=Valkey for Prefect

[Container]
Image=docker.io/valkey/valkey:9.0.3-alpine
ContainerName=prefect-valkey
Volume=%h/prefect-data/valkey:/data
PublishPort=127.0.0.1:6379:6379
Network=prefect.network
Exec=redis-server --appendonly yes

# Healthcheck
HealthCmd=redis-cli ping
HealthInterval=10s
HealthStartPeriod=5s

[Service]
Restart=always

[Install]
WantedBy=default.target

部署 Valkey

cp prefect-valkey.container $HOME/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start prefect-valkey.service

验证 Valkey

systemctl --user status prefect-valkey.service
podman exec -it prefect-valkey redis-cli ping

第四步：配置 PostgreSQL 作为元数据库

PostgreSQL 用于存储 Prefect 的元数据，如流程定义、运行历史等。

创建 PostgreSQL Quadlet 配置

创建prefect-postgres.container文件：

[Unit]
Description=PostgreSQL for Prefect

[Container]
Image=docker.io/library/postgres:18-alpine
ContainerName=prefect-postgres
Volume=%h/prefect-data/postgres:/var/lib/postgresql
PublishPort=127.0.0.1:5432:5432
Network=prefect.network
Environment=POSTGRES_DB=prefect
Environment=POSTGRES_USER=prefect
Environment=POSTGRES_PASSWORD=prefect

# Healthcheck
HealthCmd=pg_isready -U prefect
HealthInterval=10s
HealthStartPeriod=10s

[Service]
Restart=always

[Install]
WantedBy=default.target

部署 PostgreSQL

cp prefect-postgres.container $HOME/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start prefect-postgres.service

验证 PostgreSQL

systemctl --user status prefect-postgres.service
podman exec -it prefect-postgres psql -U prefect -d prefect -c "SELECT 1;"

第五步：配置 Prefect Server

Prefect Server 同时提供 API、UI 和后台服务。

创建配置文件

创建prefect-server.container文件：

[Unit]
Description=Prefect Server
Requires=prefect-valkey.service prefect-postgres.service
After=prefect-valkey.service prefect-postgres.service

[Container]
Image=docker.io/prefecthq/prefect:3-latest
ContainerName=prefect-server

# Persistence
Volume=%h/prefect-data/server:/root/.prefect

# Networking
PublishPort=127.0.0.1:4200:4200
Network=prefect.network

# Server Config
# PREFECT_API_URL and PREFECT_UI_API_URL set in env file
EnvironmentFile=%h/prefect-data/prefect.env
Environment=PREFECT_SERVER_API_HOST=0.0.0.0

# PostgreSQL Configuration
Environment=PREFECT_API_DATABASE_CONNECTION_URL=postgresql+asyncpg://prefect:prefect@prefect-postgres:5432/prefect

# Valkey Configuration
Environment=PREFECT_MESSAGING_BROKER=prefect_redis.messaging
Environment=PREFECT_MESSAGING_CACHE=prefect_redis.messaging
Environment=PREFECT_REDIS_MESSAGING_HOST=prefect-valkey
Environment=PREFECT_REDIS_MESSAGING_PORT=6379
Environment=PREFECT_REDIS_MESSAGING_DB=0

Exec=prefect server start --host 0.0.0.0

# Healthcheck
HealthCmd=python3 -c "import urllib.request; exit(0 if urllib.request.urlopen('http://127.0.0.1:4200/api/health').read() == b'true' else 1)"
HealthInterval=30s
HealthTimeout=10s
HealthStartPeriod=60s

[Service]
Restart=always

[Install]
WantedBy=default.target

配置认证

为了增强安全性，我们启用了 basic auth 认证，因此我们需要将认证字符串存储到 Podman secret 中：

# 创建 Podman secret
echo -n 'username:password' | podman secret create prefect-api-auth -

# 查看 secret
podman secret inspect prefect-api-auth

更新prefect-server.container文件，添加 secret 支持：

[Container]
# ... 其他配置 ...

# Secret for API authentication
Secret=prefect-api-auth,PREFECT_API_AUTH_STRING

创建环境文件

创建$HOME/prefect-data/prefect.env文件，配置 API 地址，生产环境需要配置实际的 URL：

# Prefect API URL
PREFECT_API_URL=http://127.0.0.1:4200/api

# UI API URL
PREFECT_UI_API_URL=http://127.0.0.1:4200/api

# Optional: Log level
# PREFECT_LOG_LEVEL=INFO

部署

cp prefect-server.container $HOME/.config/containers/systemd/
cp -v ${SCRIPT_DIR}/podman/prefect.network $HOME/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start prefect-server.service

第六步：验证部署

访问 Prefect UI

服务启动后，可以通过 http://localhost:4200/ 访问 Prefect UI。

检查服务状态

# 查看所有 Prefect 相关服务
systemctl --user list-units | grep prefect

# 检查 Podman 容器运行状态
podman ps

# 检查 API 健康状态
curl http://127.0.0.1:4200/api/health

第七步：排错

常见问题

没有生成 systemd 服务：

ls /usr/lib/systemd/user-generators/podman-user-generator  # check existence
sudo ln -s /home/linuxbrew/.linuxbrew/Cellar/podman/5.8.2/libexec/podman/quadlet /usr/lib/systemd/user-generators/podman-user-generator  # create syslink

服务未启动：

journalctl --user -xeu prefect-valkey.service
journalctl --user -xeu prefect-postgres.service  # complained about iptables not found
journalctl --user -xeu prefect-server.service

网络问题：

podman network inspect prefect-network

健康检查失败：

podman inspect --format='{{.State.Health}}' prefect-server

数据库连接问题：

podman exec -it prefect-postgres psql -U prefect -d prefect -c "SELECT 1;"

Valkey 连接问题：

podman exec -it prefect-valkey redis-cli ping

如何清空数据库？

# 重置数据库
podman exec prefect-server prefect server database reset

如何查看服务日志？

# 查看系统日志
journalctl --user -f -u prefect-server.service

# 查看容器日志
podman logs -f prefect-server

如何备份数据？

# 备份数据目录
tar -czf prefect-backup.tar.gz $HOME/prefect-data/

如何更新 Prefect 版本？

# 更新容器镜像
systemctl --user stop prefect-server.service
podman pull docker.io/prefecthq/prefect:3-latest
systemctl --user start prefect-server.service

下一步

监控：添加 Prometheus 和 Grafana 监控
备份：设置定期备份策略
安全：配置 TLS 证书和认证
Worker 和 Flow：参见 Prefect Worker 和 Flow（在新窗口打开）