本地用内置服务器跑得好好的项目,第一次部署到服务器就 502。首页打不开,但 /assets/logo.png 能访问,说明 Nginx 活着,只是 PHP 那一环断了。翻 Nginx 的错误日志,最后一行写着 connect() failed (111: Connection refused) while connecting to upstream。

修好之后安稳了两周,又出现新的怪事:改了文案、传了代码、刷新浏览器还是旧的,重启服务器才生效。再过一段时间,流量一上来就间歇性 502,半夜还会 504。三个现象分别属于三个不同的层:Nginx 与 FPM 的接缝、OPcache 的缓存、FPM 的容量。

这篇按这条线讲:请求怎么从 Nginx 交给 FPM、进程池怎么配、502 和 504 分别意味着什么、OPcache 该怎么设置、最后给一套能回滚的发布流程。目标不是背配置,而是出问题时能判断该看哪里。

本机是 Windows 11,已装 PHP 8.3.36 CLI,但没有 PHP-FPM、Nginx、systemctl 和软链发布环境,这篇的 FPM/Nginx 配置与命令仍无法在本机实测,保留为 Linux 部署说明。

Nginx 与 FPM 是怎么对接的

Nginx 自己不会执行 PHP。它对 .php 请求的处理是「转发」:把请求参数通过 FastCGI 协议交给一个监听 socket 的 FPM 进程。最小配置大致这样:

server {
    listen 80;
    server_name example.com;
    root /var/www/app/public;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

三行关键配置。第一,root 必须指向项目的 public,不要指到项目根目录。第二,SCRIPT_FILENAME 必须把「文档根目录 + 脚本路径」拼对,写错会得到 File not found 或者 404。第三,fastcgi_pass 的地址必须和 FPM 池里 listen 的地址一致,一个用 socket、一个用 TCP 端口,是最常见的 502 原因。

try_files 那一行也别漏。没有它,不存在的 .php 路径会被交给 PHP,由 PHP 自己报 404,行为不一致,还可能被用来探测路径。加 =404 或转发到入口文件,按项目路由方式选。

Ubuntu/Debian 用包管理器装的 PHP,socket 路径通常带版本号,比如 /run/php/php8.2-fpm.sock。升级 PHP 后路径会变,Nginx 配置不改就是全站 502。

FPM 的进程模型与进程数

FPM 由一个 master 进程和一组 worker 进程组成。master 负责读配置、管理 worker;worker 真正执行 PHP 脚本。一个 worker 同一时间只处理一个请求,所以「能同时处理多少请求」约等于 worker 数量。

master只负责管理:启动、回收、平滑重载。不执行用户代码。
worker执行请求。内存占用等于「PHP 基础开销 + 框架 + 本次请求的数据」。
listen 队列worker 都在忙时,新连接进入 backlog 排队。队列满了,Nginx 收到拒绝,就是 502。

进程池有三种调度方式:static 固定数量,启动就占满内存,延迟稳定;dynamic 按负载伸缩,省内存但有启动开销;ondemand 有请求才拉起,最省内存但冷启动慢。业务站点常用 dynamic。

pm = dynamic
pm.max_children = 30
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10
pm.max_requests = 800
request_terminate_timeout = 30s

pm.max_children 怎么估:先测一个 worker 的常驻内存(ps 看 RSS,常见业务在 30 到 80MB),再用「可用内存除以单进程内存」得出上限,并留出系统和数据库的余量。比如 4GB 内存的机器,留 1GB 给系统和缓存,单进程 50MB,理论上限约 60 个,再保守一点配 30 到 40。

配得太少,队列堆积,表现为间歇 502、响应变慢;配得太多,内存打满,触发 OOM,worker 被杀,现象更乱。pm.max_requests 让 worker 处理一定请求数后重启,能缓解第三方库的内存泄漏,代价是偶发的重启开销。request_terminate_timeout 是 FPM 层的硬超时,比 PHP 的 max_execution_time 更可靠,后者在阻塞 IO 时不一定按时中断。

光看日志很难判断「是不是进程不够」,得打开 FPM 的状态页。在池配置里设 pm.status_path = /status,Nginx 里只允许内网访问这个路径,请求它能拿到当前空闲进程、活跃进程、排队请求数、慢请求数。活跃进程长期等于 pm.max_children、空闲为 0,就说明池被打满了,加进程或者优化慢接口。另一个有用的是 slowlog 加 request_slowlog_timeout,超过阈值的请求会把当时的 PHP 调用栈写下来,比在代码里到处插计时要快得多。这两项都只对内网开放,不要再暴露到公网。

有了状态页,pm.max_children 就可以实测,而不是照公式拍脑袋。用 ab -c 40 -n 400 或 wrk 对着一个真实接口压,同时每隔几秒取一次状态,看 active processes 是否顶到上限、listen queue 是否持续大于 0。再取所有 worker 的内存:ps -o rss= -C php-fpm8.2 | awk '{s+=$1; n++} END {print s/n/1024 " MB"}',进程名按实际安装的版本改,得到单进程的平均常驻内存。理论上限就是「机器内存减去系统、数据库、缓存的余量」除以这个平均值,实际再打八折,因为请求高峰时单进程会比空闲时大不少。

502、504、499 分别是什么

四个状态码经常被混着说,其实各指一段:

状态码谁返回的含义先去查
502Nginx连不上 FPM,或 FPM 拒绝了连接FPM 是否运行、socket 路径、权限、进程是否打满
504NginxFPM 接了请求,但在超时时间内没返回慢查询、外部接口、fastcgi_read_timeout
499Nginx客户端在响应前主动断开用户等不及刷新或关闭,通常是后端太慢的结果
500PHP / FPM脚本执行出错PHP 错误日志最后几条

区分 502 和 504 的意义很大:502 说明请求根本没进 PHP,查进程和连接;504 说明进去了但没出来,查代码和下游。方向搞错,会浪费很多时间。

502 的排查从下往上,每条命令都有明确输出,不用一次把所有东西都翻一遍:

$ systemctl status php8.2-fpm --no-pager
Active: active (running)
$ ss -lx | grep php
u_str LISTEN 0 511 /run/php/php8.2-fpm.sock
$ tail -n 20 /var/log/nginx/error.log
connect() failed (111: Connection refused) while connecting to upstream
$ curl -v http://127.0.0.1/ 2>&1 | tail -n 5
< HTTP/1.1 502 Bad Gateway

四行输出对应四种结论。服务不是 active,去看 journalctl -u php8.2-fpm -n 50 --no-pager 里的启动失败原因,常见是配置写错或端口被别的进程占住。服务活着但 ss 里没有那个 socket,说明池的 listen 和 Nginx 的 fastcgi_pass 指的不是同一个地址,或者这个池压根没启用。socket 在、日志里是 111 拒绝,多半是权限,Nginx 的运行用户读不到 /run/php 下的文件。三项都正常还是 502,再回到状态页看 active 是否等于上限、listen queue 是否在涨。

504 反过来,请求已经进了 PHP,要查它卡在哪。Nginx 日志会写 upstream timed out (110: Connection timed out) while reading response header from upstream,并带上具体的 request URI;拿着这个 URI 去查 FPM 的 slowlog,栈顶就是当时执行到的函数。如果栈顶停在 PDO 或 curl,问题在数据库或外部接口,不在 FPM。这时把 fastcgi_read_timeout 调大只是把爆炸延后,该做的是给慢查询加索引,或者把长任务挪到命令行。

Nginx 侧的 fastcgi_read_timeout 默认 60 秒,FPM 侧的 request_terminate_timeout 默认关闭。两个都要设,并且前者略大于后者,这样 FPM 先杀,Nginx 能拿到一个明确的错误,而不是双方都超时。

上传失败还有个容易漏的链条:请求体要依次过 Nginx 的 client_max_body_size、PHP 的 post_max_size、单个文件的 upload_max_filesize,三处都够大才走得通。只改 php.ini 里的 upload_max_filesize 而不管 Nginx,大文件会直接被 Nginx 挡在门外,返回 413,PHP 根本没被调用,所以日志里什么都看不到。三者应该按「Nginx ≥ post_max_size ≥ upload_max_filesize」的顺序配,改完都要重启或重载对应的服务。

文件权限:别用 777 糊过去

PHP 以 FPM 池配置的用户运行,通常是 www-data 或 nginx。部署用户和运行用户往往不是同一个,权限问题就来了:代码目录要可读,缓存和日志目录要可写,上传目录要可写但不可执行。

推荐做法:代码目录归部署用户所有,目录 755、文件 644;需要写的目录单独授权给运行用户,比如 storage/、var/。不要整个项目 chmod -R 777,那等于让任何进程都能改你的代码,出了事故连现场都保不住。

chown -R deploy:deploy /var/www/app
find /var/www/app -type d -exec chmod 755 {} \;
find /var/www/app -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/app/storage

如果系统开了 SELinux 或 AppArmor,光改权限位还不够,需要对应的策略。表现通常是「权限看着都对,就是不能写」,日志里提示 permission denied。

部署用户和运行用户分开,本身也是一条安全边界。运行进程的权限越小,代码里出现一个上传漏洞或者模板注入时,攻击者能做的事就越少;如果 FPM 以 root 跑,或者运行用户对整站有写权限,一个很小的洞就能直接改代码、留后门。所以正确的方向是「运行用户只读代码、只写指定目录」,而不是图省事给 777 让它什么都能干。这条和上一篇讲的上传目录不能执行脚本是同一个思路。

OPcache:为什么改了代码不生效

PHP 每次请求都要把源码解析成可执行的指令,开销不小。OPcache 把解析结果缓存在共享内存里,后续请求直接复用。开启后性能提升很明显,但也带来一个副作用:你改了文件,OPcache 里还是旧版本。

关键配置是 opcache.validate_timestamps 和 opcache.revalidate_freq:

配置行为适合
validate_timestamps=1,revalidate_freq=2每 2 秒检查一次文件修改时间开发、频繁发布的环境
validate_timestamps=1,revalidate_freq=0每次请求都检查调试「改了不生效」,性能略低
validate_timestamps=0永不检查,必须重启或重载 FPM生产,配合发布脚本 reload
opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
opcache.revalidate_freq=0

max_accelerated_files 要大于项目里的文件总数,不够时缓存会频繁淘汰,性能反而下降。这个值会被向上取到附近的质数,不用追求精确。

OPcache 的 CLI 和 FPM 是两套缓存,opcache.enable_cli 默认关闭。用命令行脚本测试时看不到 Web 端的缓存效果,别据此判断「OPcache 没生效」。

命中率也不能靠感觉,要读 FPM 自己的数据。写一个只允许内网访问的脚本,输出 opcache_get_status(false) 里的统计,然后取其中的命中率:

$ curl -s http://127.0.0.1/__opcache | grep -o '"opcache_hit_rate":[^,]*'
"opcache_hit_rate":99.87

稳定运行一段时间后,这个值应该在 99% 以上;如果只有七八十,说明脚本在频繁失效,常见原因是 max_accelerated_files 太小导致缓存被淘汰,或者发布太频繁。还要看 num_cached_scripts 是否接近 max_cached_keys,接近了就调大。这个数据必须从 FPM 请求里取,命令行跑 php -r 看到的是另一套缓存,值永远是空的。

PHP 8 的 JIT 常被当成性能银弹。对典型的数据库型业务,瓶颈在 IO 和 SQL,JIT 收益有限,还可能增加排查复杂度。先把 OPcache、进程数、索引做好,再考虑 JIT。

发布流程:能切能回

直接覆盖线上文件是最危险的发布方式:传到一半,新旧文件混在一起,用户可能看到白屏;出问题想回滚,只能凭记忆再传一遍。更稳的做法是「新目录 + 软链」:

一次可回滚的发布
构建产物
传到新目录
安装依赖
切换软链
重载 FPM
冒烟检查
set -e

RELEASE=/var/www/releases/$(date +%Y%m%d%H%M%S)
rsync -a --delete ./build/ "$RELEASE"/
cd "$RELEASE" && composer install --no-dev -o --no-scripts

ln -sfn "$RELEASE" /var/www/app
sudo systemctl reload php8.2-fpm
sudo nginx -t && sudo systemctl reload nginx

curl -fsS https://example.com/health > /dev/null

systemctl reload 是平滑重载,worker 处理完当前请求再退出,不会掐断用户连接。如果 OPcache 设了 validate_timestamps=0,这一步是必须的,否则新代码永远不会被加载。

脚本中途失败是最容易被忽略的情况。开头的 set -e 只保证「出错就停」,不保证「停的时候线上没被改坏」。所以顺序要设计成:构建、传输、安装依赖、检查配置全在新目录里完成,软链切换放在最后。这样 composer install 失败、磁盘写满、rsync 断线时,旧软链一动不动,用户完全无感。真正危险的是切了软链之后 reload 失败,此时磁盘上是新代码、FPM 里是旧字节码,必须立刻把软链指回上一个 release 再 reload,并用 readlink -f /var/www/app 确认指向已经恢复。发布脚本最好加一段失败钩子,把当前软链目标和失败步骤打进日志,事后不用靠回忆。

本地验证这套流程不需要真服务器。用 php-fpm8.2 -t 检查池配置语法,返回 configuration file /etc/php/8.2/fpm/php-fpm.conf test is successful 才算通过;把 listen 改成 127.0.0.1:9000,用 Nginx 指过去请求一个 phpinfo() 页面,看到 Server API: FPM/FastCGI 就说明链路通了。改一个文件后不 reload 再请求,确认拿到旧内容;reload 后再请求,确认变成新内容,这组对比能把手感建立起来。

出问题时,把软链指回上一个 release,再 reload 一次,几十秒内恢复。旧目录保留几份,别发布完立刻删。数据库迁移要单独考虑,回滚代码不一定能回滚数据,破坏性变更要拆成两步发布。

场景走查:一台 2C4G 的服务器从 502 到稳定

第一版:装 Nginx 和 PHP-FPM,把项目传上去,配置写完访问首页 502。Nginx 日志说要连的 socket 不存在,FPM 池实际监听的是另一个版本的路径。改 fastcgi_pass 后恢复。

第二版:上线一周,晚高峰间歇 502。查 FPM 状态,发现 worker 全部处于忙碌,队列在排队;配置里 pm.max_children 还是默认的 5。按单进程内存估算后改成 30,并把 pm.max_requests 设为 800,问题消失。

第三版:运营改了文案,开发传完代码刷新还是旧的。检查发现生产把 validate_timestamps 设成了 0,而发布脚本没有 reload。把 reload 加进发布流程,并把发布说明里「传完即生效」这句话删掉。

第四版:报表导出接口偶尔 504。查慢日志,发现是在 Web 请求里循环查库、生成大文件,跑了四十多秒。把导出改成命令行脚本,由后台任务触发,页面只轮询进度,504 不再出现。

第五版:补监控。Nginx 的 502/504 计数、FPM 的活跃进程和队列长度、PHP 慢日志、OPcache 命中率,四项进了面板。之后再出问题,先看面板定位到层,再查日志。

第六版最隐蔽:发布完成后,客服说还有用户看到旧价格。查软链是对的,readlink -f /var/www/app 已经指向新 release;问题出在这台机器的 FPM 没 reload,opcache.validate_timestamps=0,worker 里跑的还是发布前的字节码。判断标准很直接:在 opcache_get_status() 里看 start_time,如果它早于本次发布时间,缓存就没重建过。另一个佐证是响应头,让应用在每个响应里输出 X-Release: 20261106-2,用 curl -I https://example.com/ 看到旧编号,就能确定命中的是旧代码,而不是浏览器缓存。

多机部署还要多查一层。负载均衡后面四台机器,发布脚本只在一台上跑了 reload,其余三台仍是旧进程;用户刷新几次,请求轮流落到不同机器,于是「一会儿新一会儿旧」。逐台用内网 IP 请求带版本号的接口,四台的输出必须完全一致,才算发布完成。只 curl 域名不够,域名走负载均衡,你只能看到其中一台的答案。

现象、原因与第一步

现象真实原因第一步查什么
所有 PHP 页面 502,静态文件正常Nginx 连不上 FPM:进程没起、socket 路径不对、权限不足systemctl status php-fpm;Nginx error log 里的 upstream 地址
高峰期间歇 502worker 用满,listen 队列溢出FPM status 的 active/idle 进程数,pm.max_children
页面 504,接口特别慢请求进了 PHP 但超时:慢查询、外部接口、长任务FPM slowlog、数据库慢查询、fastcgi_read_timeout
改代码刷新不生效OPcache 未失效,或发布没 reload FPMvalidate_timestamps;发布脚本有没有重载
上传大文件失败upload_max_filesize、post_max_size、Nginx client_max_body_size 三处任一不够逐项对比限制值和实际文件大小
缓存目录写不进去目录属主是部署用户,FPM 运行用户没权限ps 看 FPM 用户;ls -l 看目录权限
发布后整站 500新代码有语法错误,或依赖没装全PHP 错误日志;composer install 输出
首页 404,明明文件在Nginx root 指错,或 try_files 配置不对打印 $document_root,核对实际目录

边界与代价

FPM 是「一个请求一个进程」的模型,适合短请求,不适合常驻任务。WebSocket、长轮询、大批量计算都应该交给别的进程或服务。硬塞进 FPM,表现为 worker 被占满、超时、整站排队。

进程数调优没有万能值,只能按机器、代码、流量实测。静态池延迟稳定但内存占用固定;动态池省内存但有冷启动;按需池最省但第一个请求慢。选哪种,取决于业务对延迟的敏感程度和内存余量。

OPcache 关掉时间戳校验能省一点开销,代价是发布必须严格重载。团队里如果有人习惯「传上去就好」,那就把校验打开,用几毫秒换确定性。

软链发布也不是银弹。多个 release 目录占磁盘,要定期清理;软链切换的瞬间,正在执行的请求还指向旧目录,删旧目录前要确认没有请求在跑;数据库迁移仍然是不可逆的那部分。

当天能自己验证的练习

  1. 本地用 Docker 起 Nginx 加 PHP-FPM,故意把 fastcgi_pass 指向不存在的 socket,观察 502 和 Nginx 错误日志。
  2. 把 pm.max_children 设为 1,用并发请求打一个 sleep(2) 的页面,观察排队和超时。
  3. 修改一个 PHP 文件,在 validate_timestamps=0 下刷新,确认不生效;执行 reload 后再确认生效。
  4. 用 ps 查看一个 FPM worker 的 RSS,按 4GB 内存算一遍 pm.max_children 的合理范围。
  5. 写一个发布脚本:rsync 到新目录、切换软链、reload、curl 健康检查,然后手动把软链切回去,验证回滚。

小结

三句话:502 查 Nginx 和 FPM 的连接,504 查 PHP 和下游的耗时,500 才查代码;进程数按内存和单进程占用估算,宁少勿多;OPcache 让生产变快,也让发布必须重载。

下一篇是这个系列的最后一篇:PHP 8 的现代写法。部署环境稳定之后,回头看代码,会发现很多从旧教程抄来的写法已经废弃或者不再推荐。下一篇从一个 2012 年的项目升级到 8.3 讲起,列出该改什么、不该盲目改什么。