FrankenPHP容器怎么暴露Prometheus指标-php教程-PHP中文网

frankenphp 指标依赖 caddy 的 metrics 配置，必须在全局块中启用 metrics 指令并正确配置 admin 端口（如 admin localhost:2019），否则 frankenphp_* 指标不会注册；docker/k8s 需确保端口映射与网络可达，prometheus 抓取目标应使用容器名或宿主机 ip 而非 localhost。

frankenphp容器怎么暴露prometheus指标

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 接口未生效或网络不通。先确认三件事：

容器日志里有没有 admin endpoint 启动成功的提示？没有说明 admin 指令配置错误或被覆盖
Docker 运行时是否加了 -p 2019:2019？Caddy 默认只监听 localhost，容器外无法访问
如果改过 admin 地址（比如写成 admin 0.0.0.0:2019），要同步更新 Prometheus 的 scrape_configs 目标地址

临时验证命令：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

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 不一致