Linux服务器如何配置PHP-FPM Exporter监控并验证指标采集

发布人:A5数据发布时间:2026-10-27 09:40阅读量:76

在已经运行 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。

配置 PHP-FPM 状态页配图

备份并修改 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 端口直接开放到公网。修改监听地址后执行:

验证指标是否成功采集/配置 Prometheus 抓取配图

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 deniedSocket 属组、Socket 权限、父目录权限将服务用户加入实际 Socket 属组,并使用 namei -l 检查目录遍历权限
日志显示 connection refusedPHP-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 显示目标为 DownExporter 只监听了 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

相关推荐