Linux服务器如何配置PHP-FPM Exporter监控并验证指标采集
在已经运行 PHP-FPM 的 Linux 服务器上部署 PHP-FPM Exporter,核心是让 Exporter 能够通过 PHP-FPM 的 Unix Socket 或 TCP 端口读取状态页,再把状态转换为 Prometheus 可采集的 /metrics 指标。首次部署时不需要把 PHP-FPM 状态页暴露给公网,推荐使用本机 Unix Socket,并将 Exporter 的监听地址限制为本机或监控网段。
以下步骤以 Debian/Ubuntu 常见的 PHP 8.2、systemd 和 Prometheus 环境为例,同时标注 RHEL、Rocky Linux 等发行版需要替换的路径和服务名。示例中的版本号、IP 地址和指标输出均为配置示例,部署前应根据服务器实际环境核验。
准备条件与环境核验
确认 PHP-FPM、systemd 和架构
先确认 PHP-FPM 已安装并正在运行。Debian/Ubuntu 中的服务名通常是 php8.2-fpm,RHEL、Rocky Linux 或 AlmaLinux 中通常是 php-fpm。
php -v
systemctl list-units --type=service --all | grep -E 'php.*fpm'
uname -m
预期可以看到 PHP 版本、PHP-FPM 服务名以及服务器架构,例如:
PHP 8.2.x (cli) ...
php8.2-fpm.service loaded active running The PHP 8.2 FastCGI Process Manager
x86_64
如果找不到 PHP-FPM 服务,先安装与当前 PHP 主版本匹配的 FPM 软件包。不要直接套用其他 PHP 版本的 Socket 路径,因为 PHP 8.1、PHP 8.2 和 PHP 8.3 的默认路径通常不同。
确认 PHP-FPM 配置文件和监听 Socket
使用以下命令查看 PHP-FPM 的服务状态和实际监听配置:
sudo systemctl status php8.2-fpm --no-pager
sudo grep -RInE '^[; ]*(listen|pm.status_path|listen.owner|listen.group|listen.mode)' \
/etc/php/8.2/fpm/pool.d/ 2>/dev/null
Debian/Ubuntu 常见配置文件为:
/etc/php/8.2/fpm/pool.d/www.conf
RHEL 系列常见配置文件为:
/etc/php-fpm.d/www.conf
常见的 Unix Socket 配置类似:
listen = /run/php/php8.2-fpm.sock
此处记下三个信息:
- PHP-FPM 服务名,例如
php8.2-fpm; - PHP-FPM Pool 配置文件,例如
/etc/php/8.2/fpm/pool.d/www.conf; - PHP-FPM Socket 路径,例如
/run/php/php8.2-fpm.sock。
后续的 Exporter 配置必须与这三个实际值一致。
检查 Exporter 端口
PHP-FPM Exporter 默认常用监听端口为 9253。确认该端口没有被其他进程使用:
sudo ss -lntp | grep ':9253' || true
没有输出表示端口当前未被占用。若已有其他服务监听 9253,应为 Exporter 选择其他端口,并在 systemd 配置和 Prometheus 抓取配置中保持一致。
配置 PHP-FPM 状态页
PHP-FPM Exporter 不是通过普通 PHP 页面读取运行状态,而是向 PHP-FPM 的状态 URI 发起 FastCGI 请求。因此,必须先启用 pm.status_path。

备份并修改 Pool 配置
先备份配置文件。备份动作只复制文件,不会改变 PHP-FPM 当前运行状态。
sudo cp -a \
/etc/php/8.2/fpm/pool.d/www.conf \
/etc/php/8.2/fpm/pool.d/www.conf.bak.$(date +%Y%m%d%H%M%S)
编辑配置文件:
sudoedit /etc/php/8.2/fpm/pool.d/www.conf
在目标 Pool 的配置段中加入或修改以下配置:
pm.status_path = /status
如果配置文件中已经存在被注释的 pm.status_path,应取消注释并修改为 /status,不要在同一个 Pool 中保留多条相互冲突的配置。
同时核对 Socket 权限。典型配置如下:
listen = /run/php/php8.2-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
listen.owner、listen.group 和 listen.mode 不应为了部署 Exporter 而随意放宽。Exporter 服务用户只需要具备访问该 Socket 的权限即可,不建议将 Socket 改为 0666。
检查并重新加载 PHP-FPM
先执行配置语法检查:
FPM_BIN="$(command -v php-fpm8.2 || command -v php-fpm || true)"
test -n "$FPM_BIN"
sudo "$FPM_BIN" -t
成功时通常会看到类似结果:
NOTICE: configuration file /etc/php/8.2/fpm/php-fpm.conf test is successful
随后重新加载 PHP-FPM:
sudo systemctl reload php8.2-fpm
sudo systemctl is-active php8.2-fpm
test -S /run/php/php8.2-fpm.sock && echo "PHP-FPM socket exists"
预期结果为:
active
PHP-FPM socket exists
如果 reload 不受当前服务配置支持,可以在确认业务允许短暂重启的前提下执行:
sudo systemctl restart php8.2-fpm
重启可能中断正在处理的 PHP 请求,生产环境应优先使用 reload,并观察服务日志确认状态。
安装 PHP-FPM Exporter
下载并核对二进制文件
PHP-FPM Exporter 通常以 Linux 二进制压缩包形式发布。以下以 hipages/php-fpm_exporter 的 Linux amd64 发布包为例,2.2.0 仅作为示例版本,实际使用时应根据项目发布页选择需要的版本和架构。
VERSION=2.2.0
ARCH=amd64
TMP_DIR="$(mktemp -d)"
curl -fL \
-o "${TMP_DIR}/php-fpm_exporter-${VERSION}.linux-${ARCH}.tar.gz" \
"https://github.com/hipages/php-fpm_exporter/releases/download/v${VERSION}/php-fpm_exporter-${VERSION}.linux-${ARCH}.tar.gz"
tar -xzf \
"${TMP_DIR}/php-fpm_exporter-${VERSION}.linux-${ARCH}.tar.gz" \
-C "${TMP_DIR}"
BIN="$(find "${TMP_DIR}" -type f -name php-fpm_exporter | head -n 1)"
test -n "$BIN"
sudo install -o root -g root -m 0755 \
"$BIN" \
/usr/local/bin/php-fpm_exporter
如果服务器架构为 aarch64,应先查看发布包是否提供对应的 ARM64 文件,再将 ARCH 替换为发布包实际使用的名称。不要仅根据 uname -m 结果猜测压缩包文件名。
如果发布页提供 SHA-256 校验文件,应在安装前进行核对:
sha256sum "${TMP_DIR}/php-fpm_exporter-${VERSION}.linux-${ARCH}.tar.gz"
将命令输出与发布页提供的校验值逐字符比较。校验值不一致时不要继续安装。
确认二进制可以运行:
/usr/local/bin/php-fpm_exporter server --help | sed -n '1,100p'
预期会看到 server 子命令以及 Web 监听地址等选项。若当前版本的参数名称与示例不同,应以该命令输出为准调整 systemd 的 ExecStart,不要直接复制不兼容版本的启动参数。
创建受限服务用户
Exporter 不需要 root 权限运行。创建一个没有登录能力的系统用户:
if ! id php-fpm-exporter >/dev/null 2>&1; then
sudo useradd -r \
-d /nonexistent \
-s /usr/sbin/nologin \
php-fpm-exporter
fi
检查 PHP-FPM Socket 的实际属主、属组和权限:
sudo stat -c '%A %U:%G %n' /run/php/php8.2-fpm.sock
sudo namei -l /run/php/php8.2-fpm.sock
例如结果可能是:
srw-rw---- www-www-data /run/php/php8.2-fpm.sock
这表示 Exporter 服务用户需要加入 www-data 组,或者需要在 PHP-FPM 配置中为其提供一个合适的 Socket 组。优先使用附加组,不要直接放宽 Socket 权限。
配置 Exporter 的采集地址和 systemd 服务
设置 PHP-FPM 采集 URI
创建独立的环境变量文件:
sudo install -d -o root -g root -m 0755 /etc/php-fpm-exporter
sudo tee /etc/php-fpm-exporter/php-fpm_exporter.env >/dev/null <<'EOF'
PHP_FPM_SCRAPE_URI="unix:///run/php/php8.2-fpm.sock;/status"
EOF
sudo chown root:root /etc/php-fpm-exporter/php-fpm_exporter.env
sudo chmod 0644 /etc/php-fpm-exporter/php-fpm_exporter.env
这里的 URI 包含两个部分:
unix:///run/php/php8.2-fpm.sock:PHP-FPM 的 Unix Socket;/status:前面配置的pm.status_path。
Unix Socket 和状态路径之间使用分号分隔,这是 PHP-FPM Exporter 常见的配置格式。若 PHP-FPM 使用 TCP 监听,可以改为类似下面的写法:
PHP_FPM_SCRAPE_URI="tcp://127.0.0.1:9000/status"
只有在确认 PHP-FPM 的 listen 配置确实是 127.0.0.1:9000 时,才能使用 TCP 示例。
创建 systemd 单元
创建服务文件:
sudo tee /etc/systemd/system/php-fpm-exporter.service >/dev/null <<'EOF'
[Unit]
Description=PHP-FPM Prometheus Exporter
After=network.target php8.2-fpm.service
[Service]
Type=simple
User=php-fpm-exporter
Group=php-fpm-exporter
SupplementaryGroups=www-data
EnvironmentFile=/etc/php-fpm-exporter/php-fpm_exporter.env
ExecStart=/usr/local/bin/php-fpm_exporter server --web.listen-address=127.0.0.1:9253
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
EOF
如果是 RHEL、Rocky Linux 或 AlmaLinux,应将:
After=network.target php8.2-fpm.service中的 PHP-FPM 服务名替换为php-fpm.service;SupplementaryGroups=www-data替换为 PHP-FPM Socket 实际所属的组,例如apache。
如果 Socket 的属组已经允许 Exporter 用户访问,也可以删除 SupplementaryGroups,但仍应通过 namei -l 验证目录和 Socket 的访问权限。
检查 systemd 文件语法并启动服务:
sudo systemd-analyze verify /etc/systemd/system/php-fpm-exporter.service
sudo systemctl daemon-reload
sudo systemctl enable --now php-fpm-exporter
sudo systemctl status php-fpm-exporter --no-pager
预期状态为:
Active: active (running)
查看最近日志:
sudo journalctl -u php-fpm-exporter -n 50 --no-pager
正常启动时不应持续出现 permission denied、connection refused 或 scrape failed 等错误。
验证指标是否成功采集
验证 Exporter 监听端口
由于示例将监听地址设置为 127.0.0.1,只能在 PHP-FPM 所在服务器上执行检查:
sudo ss -lntp | grep ':9253'
curl -fsS http://127.0.0.1:9253/metrics | head -n 20
预期可以看到 Prometheus 文本格式内容,例如:
# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# TYPE go_gc_duration_seconds summary
...
继续筛选 PHP-FPM 指标:
curl -fsS http://127.0.0.1:9253/metrics \
| grep -E '^(phpfpm_|php_fpm_)' \
| head -n 30
不同版本的 Exporter 指标前缀或个别指标名称可能有所区别,实际结果应以当前版本返回的 /metrics 内容为准。常见指标包括:
- PHP-FPM 当前活动进程数;
- PHP-FPM 空闲进程数;
- PHP-FPM 总进程数;
- PHP-FPM 已接受连接数;
- 达到
pm.max_children的次数; - 慢请求数量;
- Exporter 对 PHP-FPM 的抓取失败次数。
如果只看到 Go 运行时指标,却看不到 PHP-FPM 指标,说明 Exporter Web 服务本身已经启动,但 PHP-FPM 状态采集仍未成功,需要检查 Socket、状态路径和权限。
配置 Prometheus 抓取
如果 Prometheus 与 PHP-FPM Exporter 在同一台服务器上,可以在 Prometheus 配置中加入:
scrape_configs:
- job_name: php-fpm-exporter
metrics_path: /metrics
static_configs:
- targets:
- "127.0.0.1:9253"
如果 Prometheus 在独立服务器上,127.0.0.1 指向的是 Prometheus 自身,而不是 PHP-FPM 服务器。此时应将 Exporter 监听地址改为服务器的内网地址,例如:
ExecStart=/usr/local/bin/php-fpm_exporter server --web.listen-address=10.0.0.12:9253
同时将 Prometheus 目标改为:
scrape_configs:
- job_name: php-fpm-exporter
static_configs:
- targets:
- "10.0.0.12:9253"
远程监听时,应只允许 Prometheus 所在的管理网段访问 9253,不要将 Exporter 端口直接开放到公网。修改监听地址后执行:

sudo systemctl daemon-reload
sudo systemctl restart php-fpm-exporter
在 Prometheus 服务器上检查配置语法:
promtool check config /etc/prometheus/prometheus.yml
Prometheus 重新加载配置后,可以通过 Web 页面或 API 查询目标状态。使用 API 时,示例查询如下:
curl -G 'http://127.0.0.1:9090/api/v1/query' \
--data-urlencode 'query=up{job="php-fpm-exporter"}'
返回结果中的 value 为 1,表示 Prometheus 已经成功抓取 Exporter。value 为 0 通常表示网络访问、监听地址、端口访问控制或目标服务状态存在问题。
常见失败处理
| 现象 | 优先检查项 | 处理方向 |
|---|---|---|
Exporter 启动后日志显示 permission denied | Socket 属组、Socket 权限、父目录权限 | 将服务用户加入实际 Socket 属组,并使用 namei -l 检查目录遍历权限 |
日志显示 connection refused | PHP-FPM 是否运行、TCP 端口是否正确 | 检查 systemctl status、ss -lx 或 ss -lntp,修正采集 URI |
| 日志显示找不到状态页 | pm.status_path 是否配置在正确的 Pool 中 | 确认配置为 /status,执行 PHP-FPM 语法检查并 reload |
/metrics 可访问但没有 phpfpm_ 指标 | Exporter 到 PHP-FPM 的连接失败 | 查看 journalctl -u php-fpm-exporter,重点检查 URI 分隔符和 Socket 路径 |
| Prometheus 显示目标为 Down | Exporter 只监听了 127.0.0.1 或端口被访问控制拦截 | 同机使用回环地址,跨主机则监听内网地址并限制来源 |
| systemd 服务反复重启 | 启动参数、环境文件或端口配置错误 | 执行 server --help、systemd-analyze verify,查看完整服务日志 |
| PHP-FPM reload 失败 | 配置语法错误或重复配置 | 恢复备份文件,修正配置后重新执行 php-fpm -t |
处理权限问题时,先确认 PHP-FPM Socket 的实际属组,再决定是否修改 SupplementaryGroups。如果修改了 listen.group 或 listen.mode,该变化可能影响 Nginx、Apache 或其他 PHP-FPM 客户端,必须在修改前记录原值并在业务低峰期验证。
如果一台服务器上有多个 PHP-FPM Pool,且每个 Pool 使用不同的 Socket,应确认当前 Exporter 版本是否支持多个采集地址。若只支持单个 PHP_FPM_SCRAPE_URI,可以为不同 Pool 分别创建独立的 Exporter 服务实例,并使用不同监听端口,避免把一个 Pool 的状态误认为整台服务器的 PHP-FPM 状态。
验收与回滚检查项
部署完成后,建议按以下顺序验收:
- PHP-FPM 服务处于
active (running)状态; pm.status_path = /status已写入正确的 Pool 配置;- PHP-FPM Socket 存在,且 Exporter 服务用户具备访问权限;
php-fpm_exporter二进制能够执行,版本和架构匹配;php-fpm-exporter.service处于active (running)状态;curl http://127.0.0.1:9253/metrics能返回 Prometheus 文本格式;- 返回内容中包含 PHP-FPM 相关指标,而不只是 Go 运行时指标;
- Prometheus 目标状态为
UP,查询up{job="php-fpm-exporter"}的值为1; - 远程部署时,9253 端口只对 Prometheus 或指定监控网段开放。
需要回滚时,先停止并禁用 Exporter,避免删除文件后 systemd 仍不断尝试启动:
sudo systemctl disable --now php-fpm-exporter
sudo systemctl daemon-reload
确认没有其他服务依赖该二进制后,再移除本次创建的服务文件、环境文件和安装目录:
sudo rm -f /etc/systemd/system/php-fpm-exporter.service
sudo rm -f /etc/php-fpm-exporter/php-fpm_exporter.env
sudo rmdir /etc/php-fpm-exporter 2>/dev/null || true
sudo rm -f /usr/local/bin/php-fpm_exporter
sudo systemctl daemon-reload
如果回滚范围还包括 PHP-FPM 状态页,则使用部署前生成的备份恢复原配置。恢复前先确认备份文件对应本次变更,避免覆盖其他运维修改:
sudo cp -a \
/etc/php/8.2/fpm/pool.d/www.conf.bak.YYYYMMDDHHMMSS \
/etc/php/8.2/fpm/pool.d/www.conf
sudo "$FPM_BIN" -t
sudo systemctl reload php8.2-fpm
sudo systemctl is-active php8.2-fpm
回滚验收应确认 PHP-FPM 能正常运行、业务 PHP 请求不受影响、9253 端口不再监听,以及 Prometheus 中对应的抓取目标已按预期移除或标记为不可用。
PHP-FPM 与 Prometheus 监控可用于持续观察业务服务器上的 PHP 服务状态。A5数据提供香港、美国、日本等地区的物理服务器,涵盖 Xeon 与 AMD EPYC 平台,并有 SSD、NVMe 等存储配置及不同网络线路方案,可为网站、业务后台和接口服务提供运行 PHP-FPM 与监控组件所需的服务器资源。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5971.html



