Hui Wu
04/10/2026, 3:28 AMMarvin
04/10/2026, 3:28 AMMarvin
04/10/2026, 3:30 AMprefect cloud webhook create "my-webhook" --description "From GitHub" --template '{"event":"my.event","resource":{"prefect.resource.id":"my.resource"}}'
prefect cloud webhook ls
- Docs: Webhooks (concepts), Create a webhook (how-to), Automations
- Note: Receiving inbound webhooks is a Prefect Cloud feature.
- Outbound (send webhooks on events or from flows): Use the Webhook block directly or the “Call webhook” automation action.
- Python block:
from prefect.blocks.webhook import Webhook
webhook = Webhook(url="<https://example.com/webhook>", method="POST")
# inside an async context (e.g., in a flow or task)
await webhook.call(payload={"text": "Hello from Prefect!"})
- API ref: Webhook block API
- Notification blocks via webhooks: Built-ins for Slack, Microsoft Teams, PagerDuty, Discord, Mattermost, etc., if you want common destinations without writing custom requests.
Would you like to receive external webhooks to trigger runs, or send webhooks/notifications out (or both)? If you share your specific tool (e.g., GitHub, Stripe, Slack) and direction (inbound/outbound), I can give exact steps.Hui Wu
04/10/2026, 4:47 AMMarvin
04/10/2026, 4:47 AMMarvin
04/10/2026, 4:49 AMdocker run -p 6379:6379 --name prefect-redis -d redis:7
2) Configure Prefect to use Redis
# Point Prefect’s messaging to Redis
export PREFECT_MESSAGING_BROKER="prefect_redis.messaging"
export PREFECT_MESSAGING_CACHE="prefect_redis.messaging"
export PREFECT_SERVER_EVENTS_CAUSAL_ORDERING="prefect_redis.ordering"
export PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE="prefect_redis.lease_storage"
# Connection (choose one style)
export PREFECT_REDIS_MESSAGING_URL="<redis://localhost:6379/0>"
# or:
# export PREFECT_REDIS_MESSAGING_HOST="localhost"
# export PREFECT_REDIS_MESSAGING_PORT="6379"
# export PREFECT_REDIS_MESSAGING_DB="0"
# Docket (service coordination); use a different Redis DB index
export PREFECT_SERVER_DOCKET_URL="<redis://localhost:6379/1>"
3) Start the server
prefect server start
Multi-worker or multi-server notes
- If you run multiple API workers on one machine:
- Use Postgres (not SQLite) and Redis:
export PREFECT_API_DATABASE_CONNECTION_URL="<postgresql+asyncpg://user:pass@host:5432/prefect>"
prefect server start --workers 4
- If you split API and background services across processes/containers:
# API only
prefect server start --no-services
# Background services (scheduler, automations, late run detection)
prefect server services start
Minimal docker-compose example
version: '3.8'
services:
redis:
image: redis:7
ports: ["6379:6379"]
prefect:
image: prefecthq/prefect:3-latest
depends_on: [redis]
environment:
PREFECT_MESSAGING_BROKER: prefect_redis.messaging
PREFECT_MESSAGING_CACHE: prefect_redis.messaging
PREFECT_SERVER_EVENTS_CAUSAL_ORDERING: prefect_redis.ordering
PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE: prefect_redis.lease_storage
PREFECT_REDIS_MESSAGING_URL: <redis://redis:6379/0>
PREFECT_SERVER_DOCKET_URL: <redis://redis:6379/1>
command: prefect server start --host 0.0.0.0 --port 4200
ports: ["4200:4200"]
Tips
- Use rediss:// if your Redis requires TLS.
- It’s fine to use one Redis instance with different DB numbers (e.g., 0 for messaging, 1 for docket).
- For multi-worker or multi-server, switch to Postgres.
Docs and references
- Self-hosted overview: Self-hosted Prefect
- Docker Compose guide: Self-hosted with Docker Compose
- Server CLI: prefect server CLI
- Settings reference: Settings reference
If you share whether this is for local dev or a production/multi-node setup, I can tailor the exact env vars and compose file.Hui Wu
04/10/2026, 6:45 AMMarvin
04/10/2026, 6:45 AMMarvin
04/10/2026, 6:48 AMserver {
listen 80;
server_name <http://prefect.example.com|prefect.example.com>;
location /api/ {
proxy_pass <http://127.0.0.1:4200/api/;>
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_buffering off;
}
location / {
proxy_pass <http://127.0.0.1:4200/;>
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
2) 在容器里设置 UI 要用的外部 API 地址
- 将以下环境变量加到你的 Prefect Server 容器:
# 告诉 UI:浏览器应访问哪个 API(必须是外部可达的域名)
PREFECT_SERVER_UI_API_URL=<https://your.domain.com/api>
# 可选但推荐:限制 CORS 到你的域名
PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS=<https://your.domain.com>
# 服务器监听在容器内的地址与端口
PREFECT_SERVER_API_HOST=0.0.0.0
PREFECT_SERVER_API_PORT=4200
- 对运行在外部的 CLI/Workers,也把 PREFECT_API_URL 指向同一个外部地址:
PREFECT_API_URL=<https://your.domain.com/api>
3) 避免混合内容
- 如果你的域名是 HTTPS,但 server.ui.api_url 指向 HTTP,浏览器会因 Mixed Content 拒绝请求。
- 确保两者协议一致(均为 HTTPS)。
4) 快速自检
- 访问你的域名:`https://your.domain.com/ui-settings`,返回的 JSON 里应该能看到正确的 `apiUrl`(例如 `https://your.domain.com/api`)。
- 浏览器开发者工具 Network 面板查看 API 请求的实际 URL 和报错。
- 用 curl 测试 API 健康检查:
curl -i <https://your.domain.com/api/health/ready>
补充说明
- PREFECT_SERVER_UI_API_URL 是“给浏览器用的外部地址”;`PREFECT_SERVER_API_HOST/PORT` 是“后端在容器内监听的地址/端口”,两者用途不同。
- 如果你的反代挂在了子路径(比如 https://your.domain.com/prefect),也要把 PREFECT_SERVER_UI_API_URL 设成对应路径(例如 `https://your.domain.com/prefect/api`),并确保反代路径配置一致。
参考
- Settings 参考
- 自托管部署指南
如果你方便提供:
- 你的域名与协议(http/https)
- 当前反向代理配置(Nginx/Traefik 等)片段
- 访问 https://你的域名/ui-settings 的返回内容
我可以帮你把配置对齐到位。Hui Wu
04/10/2026, 7:34 AMMarvin
04/10/2026, 7:34 AMMarvin
04/10/2026, 7:37 AMdocker logs --tail 200 <prefect-server-container>
- 实时跟随
docker logs -f <prefect-server-container>
- 仅筛选错误
docker logs -f <prefect-server-container> | grep -i "error\|exception"
把日志“调到最啰嗦”(含完整 traceback)
- 临时设置环境变量后再启动 Server(或加到容器环境变量里):
# 提高 Prefect Server 及相关日志级别
PREFECT_SERVER_LOGGING_LEVEL=DEBUG
PREFECT_LOGGING_LEVEL=DEBUG
# 对可重试类错误也打印完整堆栈(如数据库锁/超时等)
PREFECT_SERVER_LOG_RETRYABLE_ERRORS=true
# 如需观测 SQL 语句(数据库层面):
PREFECT_SERVER_DATABASE_ECHO=true # 等同于旧名 PREFECT_API_DATABASE_ECHO=true
- 用 CLI 指定日志级别(等价于设置变量):
prefect server start --log-level debug
确认 UI/客户端指向正确 API
- 你是通过域名访问的反向代理场景,请确保:
- Server 容器设置了:
PREFECT_SERVER_UI_API_URL=<https://你的域名/api>
这样 Dashboard 获取 /ui-settings 后,浏览器才会把 API 请求发到外网可达的地址,而不是 127.0.0.1 或容器内网地址。
- 客户端/worker 侧也指向同一个 API:
PREFECT_API_URL=<https://你的域名/api>
- 用 curl 自检后端是否可达:
curl -i <https://你的域名/api/health/ready>
排查 500 的常见根因与定位
1) 数据库迁移/连接问题
- 现象:首次启动或升级后,访问 work_pools 相关接口报 500
- 检查:
- 执行数据库迁移(容器或主机内):
prefect server database upgrade -y
- 开启 SQL echo 后看日志是否有连接失败/权限不足/表不存在等:
PREFECT_SERVER_DATABASE_ECHO=true
- 如果是多进程/多实例,建议使用 Postgres 而非 SQLite。
2) 反向代理/路径不匹配
- 现象:UI 能打开,但 API 返回 404/500 或 Mixed Content
- 检查:
- Nginx/Traefik 等是否把 /api/ 准确转发到容器的 /api/(路径尾斜杠要一致)
- HTTPS 场景确保 PREFECT_SERVER_UI_API_URL 也是 https,避免浏览器拦截混合内容
3) 权限或认证配置(若启用)
- 现象:返回 401/403 或 500
- 检查:
- 是否设置了 `PREFECT_SERVER_API_AUTH_STRING`,客户端也相应配置了 PREFECT_API_AUTH_STRING
- 代理是否剥离/添加了额外认证头,导致后端解析异常(可在 DEBUG 日志中看到请求头)
4) CORS/CSRF
- 反代到不同域名或端口时,建议设置:
PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS=<https://你的域名>
PREFECT_SERVER_API_CSRF_PROTECTION_ENABLED=true
日志里若看到被拒绝的跨域或 CSRF 校验,可据此调整。
复现与最小化验证
- 直接在 server 容器里,用同样的环境变量,尝试创建 work pool 看具体返回:
prefect work-pool create "ude-local-pool" --type process
如果这里也 500,就能在 server 容器日志里同时看到对应的 traceback。
额外建议
- 你的报错里提示 “Work pool 'ude-local-pool' does not exist and no worker type was provided. Starting a process worker...”,推荐先显式创建一个 process 类型的工作池,然后再启动 worker,便于区分是 API 问题还是自动创建逻辑的问题:
prefect work-pool create "ude-local-pool" --type process
prefect worker start -p "ude-local-pool"
如果你把以下信息贴出来,我可以更精准定位:
- docker logs -f <server 容器> 中对应 500 时刻的完整 traceback(启用 DEBUG 后)
- 访问 https://你的域名/ui-settings 的返回内容(确认 apiUrl)
- 你的反向代理(Nginx/Traefik)配置片段(/ 与 /api/ 的转发规则)
- 数据库连接配置(SQLite 还是 Postgres;以及是否已执行 database upgrade)