FrankenPHP 指标依赖 Caddy 的 metrics 配置，必须在全局块中启用 metrics 指令并正确配置 admin 端口（如 admin localhost:2019），否则 frankenphp_* 指标不会注册；Docker/K8s 需确保端口映射与网络可达，Prometheus 抓取目标应使用容器名或宿主机 IP 而非 localhost。
FrankenPHP 容器本身不主动暴露 /metrics 端点，所有 Prometheus 指标都依赖 Caddy 的 metrics 能力——也就是说，**指标是否可见，完全取决于 Caddyfile 配置是否启用并正确暴露管理端点**。
必须在 Caddyfile 里启用 metrics 全局指令
FrankenPHP 的指标注册逻辑发生在 Caddy 启动时的 Provision 阶段，它会检查 Caddy 的 HTTP 模块是否启用了 metrics。没开这个，frankenphp_* 指标根本不会被创建。
常见错误是只配了 PHP 路由，却漏掉全局 metrics：
{
admin localhost:2019
metrics // ← 这行不能少！否则 curl http://localhost:2019/metrics 看不到 frankenphp_*
}
localhost {
route {
php { root /var/www }
}
}- 如果用 Docker Compose，确保容器内 Caddy 能监听
2019（admin 端口）且该端口映射到宿主机 -
metrics必须放在全局块{ }内，不能写在localhost { }块里 - 若部署在 Kubernetes，需在 Service 中显式暴露
2019端口，并在 Pod 的 readinessProbe 中避免误判（该端口不处理业务请求）
curl http://localhost:2019/metrics 返回空或 404 怎么办
这不是 FrankenPHP 的问题，而是 Caddy 的 admin 接口未生效或网络不通。先确认三件事：
立即学习“PHP免费学习笔记（深入）”；
- 容器日志里有没有
admin endpoint启动成功的提示？没有说明admin指令配置错误或被覆盖 - Docker 运行时是否加了
-p 2019:2019？Caddy 默认只监听 localhost，容器外无法访问 - 如果改过 admin 地址（比如写成
admin 0.0.0.0:2019），要同步更新 Prometheus 的scrape_configs目标地址
临时验证命令：
docker exec -it your-frankenphp-container curl -s http://localhost:2019/metrics | grep frankenphp
如果这行有输出，说明指标已注册；如果为空，说明 Caddyfile 缺 metrics 或没 reload。
Worker 指标带 worker="xxx" 标签，但看不到具体值
FrankenPHP 的 Worker 指标（如 frankenphp_worker_ready_count）只在真正运行了 worker 模式脚本后才会出现对应标签。普通 PHP 请求（非 worker）不会触发这些指标。
- 确保你的 PHP 脚本用了
frankenphp_worker_start()并保持长连接（不是执行完就退出） - 标签名来自脚本路径：比如
/var/www/queue-worker.php→worker="/var/www/queue-worker.php"，注意路径需与实际一致（符号链接可能影响匹配） - 若用相对路径启动 Worker，标签会包含工作目录前缀，容易导致 Grafana 查询时 label 不一致
Docker 环境下 Prometheus 抓不到指标的典型原因
容器网络隔离是最大干扰项。Prometheus 很可能和 FrankenPHP 容器不在同一网络，直接写 localhost:2019 会抓空。
- 不要在 Prometheus 的
targets里填localhost:2019—— 这是指 Prometheus 自己的 localhost - 应填容器名+端口（Docker Compose 场景）或宿主机 IP + 映射端口（Docker CLI 场景）
- 如果用 host 网络模式，
localhost:2019才有效，但不推荐用于生产 - Caddyfile 中
admin若绑定localhost，则必须通过端口映射+宿主机地址访问，不能靠容器间 DNS
最稳妥的调试顺序：容器内 curl localhost:2019/metrics → 宿主机 curl localhost:2019/metrics → Prometheus targets 页面看状态是否为 UP。
