PHP代码更新后OPcache为何仍返回旧内容?如何检查缓存失效与进程配置

发布人:A5数据发布时间:2026-11-02 12:22阅读量:85

PHP文件已经替换,浏览器或接口却仍然返回旧结果,通常不是“文件没有上传成功”这么简单。OPcache缓存的是PHP脚本编译后的字节码;当opcache.validate_timestamps关闭、PHP-FPM仍使用旧进程、请求实际到达另一台服务器,或者部署切换了软链接而缓存路径没有重新识别时,磁盘上的新代码和正在执行的代码就可能不一致。

排查时不要一开始就删除缓存目录或反复重启服务器。先确认旧内容来自浏览器、CDN、Nginx、错误的后端节点,还是PHP-FPM自身;再核对Web请求实际使用的PHP配置,最后才进行FPM重启或缓存重置。下面按低风险到高风险的顺序展开。

先确认“旧内容”究竟来自哪一层

对比响应头和后端节点

先使用一个确定会返回动态内容的页面或接口进行测试,避免把静态CSS、JS或图片缓存误认为PHP代码问题:

curl -sS -D /tmp/php-response.headers \
  -H 'Cache-Control: no-cache' \
  'https://www.example.com/health-check' \
  -o /tmp/php-response.body

cat /tmp/php-response.headers
cat /tmp/php-response.body

Cache-Control: no-cache只能要求中间层重新验证,不能替代CDN刷新,也不能绕过所有反向代理缓存。如果响应头中出现以下字段,应先检查HTTP缓存链路:

  • Age:响应在缓存中保留的时间。
  • X-Cache、CF-Cache-Status或类似字段:表示是否命中代理或CDN缓存。
  • Via:表示请求经过了中间代理。
  • ETag、Last-Modified:可能导致客户端或代理继续使用旧响应。
  • X-Backend、X-Server:如果站点主动添加,可用于判断请求落到了哪台后端。

如果应用允许在响应中输出版本号,建议使用发布批次号或代码提交标识,而不是直接输出服务器路径。例如响应中出现release-20250308-01,可以快速判断旧内容来自应用版本还是缓存层。

在负载均衡环境中,连续请求可能被分配到不同节点。可以临时连续请求并观察后端标识:

for i in $(seq 1 10); do
  printf '%02d ' "$i"
  curl -sS -H 'Cache-Control: no-cache' \
    -D - 'https://www.example.com/health-check' \
    -o /tmp/health.body 2>/dev/null |
    grep -iE '^(HTTP/|X-Backend:|Age:|X-Cache:)'
done

如果同一个URL有时返回新版本、有时返回旧版本,优先检查后端节点是否使用了不同代码目录或不同PHP-FPM服务。此时清理某一台机器上的OPcache并不能解决整体问题。

先确认“旧内容”究竟来自哪一层/对比响应头和后端节点配图

PHP-FPM是否持续执行旧脚本,既与进程配置和缓存状态有关,也与请求实际落到的服务器节点有关。A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,可承载网站、业务后台、数据库与接口服务;不同地区及产品系列有多种CPU、内存、NVMe或SSD存储和网络线路方案,为多节点部署及不同负载的PHP业务提供硬件与网络资源基础。

确认请求使用的代码目录

在每一台提供PHP服务的服务器上检查当前发布目录。下面的路径只是示例,需要替换为实际应用路径:

APP=/var/www/example/current

readlink -f "$APP"
stat -c '%n %y %s' "$APP/public/index.php"
sha256sum "$APP/public/index.php"

需要重点比较三项:

  1. readlink -f解析出的真实目录是否一致。
  2. 文件修改时间和文件大小是否符合本次发布。
  3. 文件哈希是否一致。

如果使用了类似current -> releases/20250308-01的软链接,不能只检查current这个目录名。某些部署方式只切换了软链接,但PHP进程仍然按照旧路径或旧缓存键执行脚本。还要确认Nginx的root和PHP入口文件确实指向该软链接:

先确认“旧内容”究竟来自哪一层/确认请求使用的代码目录配图

sudo nginx -T 2>/dev/null |
  grep -E '^\s*root\s|^\s*fastcgi_pass\s|^\s*fastcgi_param SCRIPT_FILENAME'

如果服务器使用容器,宿主机上的/var/www/example/current不一定是PHP进程看到的路径。此时必须进入实际运行PHP-FPM的容器或服务实例内检查:

docker ps
docker exec -it <php-container> sh

容器名称、运行时和路径应以实际环境为准。宿主机文件哈希正确,不代表容器内挂载的文件已经更新。

核对Web请求的PHP配置,而不是只看CLI

CLI和PHP-FPM可能不是同一套配置

很多排查误区来自下面的命令:

php -i | grep -E 'opcache.enable|opcache.validate_timestamps|opcache.revalidate_freq|opcache.preload'

这条命令检查的是命令行CLI配置,不一定是网站请求使用的PHP-FPM配置。服务器上可能同时存在PHP 8.1、PHP 8.2和PHP 8.3,也可能存在多个FPM池。CLI显示“已开启”或“已关闭”,都不能直接证明Web请求的实际状态。

先记录CLI环境,作为对照信息:

php -v
php --ini
php -i | grep -E 'Loaded Configuration File|Scan this dir for additional .ini files'

然后通过一个受保护的内部诊断页面,或者应用自身的管理诊断功能,读取实际Web请求的配置。诊断页面至少应输出以下信息:

<?php
declare(strict_types=1);

/*
 * 仅用于内网或受认证保护的临时诊断路由。
 * 不要将PHP版本、服务器路径和OPcache状态直接暴露给公众。
 */

header('Content-Type: text/plain; charset=utf-8');

echo 'PHP_VERSION=' . PHP_VERSION . PHP_EOL;
echo 'PHP_SAPI=' . PHP_SAPI . PHP_EOL;
echo 'DOCUMENT_ROOT=' . ($_SERVER['DOCUMENT_ROOT'] ?? '') . PHP_EOL;
echo 'SCRIPT_FILENAME=' . ($_SERVER['SCRIPT_FILENAME'] ?? '') . PHP_EOL;

$items = [
    'opcache.enable',
    'opcache.enable_cli',
    'opcache.validate_timestamps',
    'opcache.revalidate_freq',
    'opcache.revalidate_path',
    'opcache.preload',
    'opcache.file_cache',
    'opcache.file_cache_only',
];

foreach ($items as $item) {
    echo $item . '=' . var_export(ini_get($item), true) . PHP_EOL;
}

if (function_exists('opcache_get_status')) {
    $status = opcache_get_status(false);
    echo 'opcache_status=' . ($status === false ? 'false' : 'available') . PHP_EOL;

    if (is_array($status)) {
        echo 'opcache_enabled=' . var_export($status['opcache_enabled'] ?? null, true) . PHP_EOL;
        echo 'cache_full=' . var_export($status['cache_full'] ?? null, true) . PHP_EOL;
        echo 'restart_pending=' . var_export($status['restart_pending'] ?? null, true) . PHP_EOL;
    }
} else {
    echo 'opcache_status=unavailable' . PHP_EOL;
}

该页面应放在临时路由、内网地址或已有管理认证之后,验证完成后删除。不要在公开站点长期保留,因为它可能暴露PHP版本、目录结构和缓存状态。

重点查看的配置项

配置项作用排查时的判断
opcache.enable是否为当前SAPI启用OPcacheWeb请求为0时,不存在OPcache导致的旧字节码问题
opcache.enable_cli是否为CLI启用OPcache只影响CLI,不能代表PHP-FPM
opcache.validate_timestamps是否检查PHP文件的修改时间为0时,代码更新后通常需要重启或显式重置缓存
opcache.revalidate_freq两次时间戳检查之间的间隔,单位为秒为2时,文件刚更新后可能短暂返回旧代码
opcache.revalidate_path是否重新确认包含文件的真实路径软链接、include_path和多版本目录部署时需要重点关注
opcache.preloadPHP启动时预加载的脚本修改预加载类或函数后通常需要完整重启FPM
opcache.file_cache是否启用磁盘文件缓存需要结合file_cache_only和重启结果进一步判断

opcache.validate_timestamps检查的是文件时间戳,而不是每次比较文件内容哈希。如果部署工具保留了旧修改时间,或者通过复制操作产生了与旧文件相同的时间戳,即使内容已经改变,OPcache也可能认为脚本没有更新。因此,文件哈希和修改时间要一起核对。

如果配置为:

opcache.validate_timestamps=0

那么opcache.revalidate_freq不会让它自动恢复检查。该模式常用于变更频率较低的生产环境,但它要求每次发布都执行明确的缓存失效动作,例如重启PHP-FPM或在受控条件下调用opcache_reset()。

如果配置为:

opcache.validate_timestamps=1
opcache.revalidate_freq=2

文件修改后通常会在下一次时间戳检查时失效,但不能把“2秒”理解为所有请求都严格延迟2秒。请求是否到达同一节点、文件时间戳是否更新、FPM进程是否读取了相同路径,都会影响最终表现。

判断OPcache是否真的保留了旧脚本

查看共享内存和重启状态

通过受保护的Web诊断路由读取opcache_get_status(false),重点观察以下字段:

  • opcache_enabled:当前Web进程是否启用了OPcache。
  • cache_full:缓存空间是否已满。缓存已满通常会导致新脚本无法正常缓存,但它本身不一定是“旧内容”的直接原因。
  • restart_pending:是否有等待中的OPcache重启请求。
  • restart_in_progress:是否正在执行缓存重启。
  • memory_usage:已用、空闲和浪费的共享内存。
  • opcache_statistics:命中数、未命中数、缓存脚本数和重启统计。

例如,下面这类输出可以作为判断参考,属于示例格式,不代表任何特定服务器的实际结果:

opcache_enabled=true
cache_full=false
restart_pending=false
restart_in_progress=false
used_memory=73400320
free_memory=198180864
num_cached_scripts=1268
num_cached_keys=1491
hits=582104
misses=1327
oom_restarts=0
manual_restarts=1

如果Web诊断页面显示opcache_enabled=false,就应转向检查应用缓存、HTTP缓存或实际执行路径,而不是继续清理OPcache。如果CLI显示开启、Web诊断显示关闭,则说明两个SAPI配置不同,不能用CLI的结果替代FPM判断。

检查FPM主进程和服务名称

先确定请求使用的是哪个FPM实例:

ps -ef | grep '[p]hp-fpm'
systemctl --type=service --no-pager | grep -Ei 'php.*fpm'

如果使用Unix Socket,还可以查看Nginx或Apache连接的Socket:

sudo nginx -T 2>/dev/null | grep -E 'fastcgi_pass|proxy_pass'
sudo ss -lxnp | grep -E 'php|fpm'

可能存在以下情况:

  • Nginx连接的是PHP 8.2,但管理员检查的是PHP 8.3的CLI配置。
  • Nginx连接的是另一个FPM Socket。
  • 修改的是某个FPM池的配置,实际流量使用了另一个池。
  • 重启了旧版本FPM服务,但请求仍由容器或另一台节点处理。
  • FPM池中使用了php_admin_value覆盖全局配置。

确认服务后,再检查对应FPM二进制的配置。命令名称因发行版和PHP版本不同,需要先核验:

FPM_BIN="$(command -v php-fpm8.2 || command -v php-fpm)"
printf '%s\n' "$FPM_BIN"

如果输出了正确的FPM程序,可以读取其配置:

sudo "$FPM_BIN" -i |
  grep -E 'Loaded Configuration File|Scan this dir|opcache.enable|opcache.validate_timestamps|opcache.revalidate_freq|opcache.preload'

这仍然不如实际Web诊断结果直接,因为FPM池配置和容器环境可能继续覆盖全局配置。最终判断应以请求实际到达的FPM进程为准。

按结果选择处理方式

下面的结果分支可以帮助确定下一步,而不是盲目重启。

观察结果更可能的原因处理方向
不同后端返回不同版本发布未同步、负载均衡节点不一致先统一代码目录和发布版本
文件哈希不一致文件未上传完整或部署目标错误修复发布流程,不必先清理OPcache
CLI是新配置,Web是旧配置SAPI、FPM版本或FPM池不同检查fastcgi_pass、FPM服务和池配置
validate_timestamps=0OPcache不会自动识别文件变化使用受控重置或重启FPM
validate_timestamps=1且刚刚发布尚未到时间戳检查周期等待一个检查周期后复测
诊断路由已是新代码,业务页面仍旧应用缓存、模板缓存、HTTP缓存或业务数据检查框架缓存和代理缓存
FPM重启后仍旧请求没有到达被重启的实例,或存在预加载/其他缓存重新确认节点、Socket、容器和预加载配置
只有软链接切换后的文件异常真实路径或缓存键未重新识别检查readlink -f、revalidate_path,发布时重启FPM

先处理HTTP和应用层缓存

如果响应头表明请求命中了CDN、Nginx fastcgi_cache或应用页面缓存,应先按对应系统的标准方式刷新缓存,并使用源站地址或内部入口进行对比。刷新公共缓存可能影响大量请求,操作前应确认缓存键、域名范围和刷新范围,避免进行不必要的全站清理。

OPcache只缓存PHP脚本的编译结果,不负责缓存以下内容:

  • Redis、Memcached或数据库中的配置数据。
  • 框架生成的配置、路由和模板缓存。
  • 应用生成的整页HTML。
  • Nginx、CDN或浏览器保存的HTTP响应。
  • 常驻队列进程、定时任务进程已经加载到内存中的类和配置。

如果诊断页面能够返回新的发布标识,而业务页面仍返回旧HTML,应优先检查这些层次。对于常驻PHP进程,还需要单独重启对应的队列或任务服务,FPM重启不会自动终止其他进程。

使用受控的opcache_reset()

在确认请求确实到达目标FPM实例后,可以通过受保护的管理动作调用opcache_reset()。该操作会使缓存脚本重新构建,下一批请求可能出现缓存预热带来的CPU升高。它不应被做成公开URL,也不应允许任意GET请求触发。

示例逻辑如下,实际使用时应接入现有认证、权限和审计机制:

<?php
declare(strict_types=1);

/*
 * 仅作为受保护的管理动作示例。
 * 不能直接以公开URL部署。
 */

if (!function_exists('opcache_reset')) {
    http_response_code(503);
    exit('OPcache is unavailable');
}

$result = opcache_reset();

header('Content-Type: application/json; charset=utf-8');
echo json_encode(
    [
        'reset' => $result,
        'sapi' => PHP_SAPI,
        'time' => date(DATE_ATOM),
    ],
    JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);

如果配置了opcache.restrict_api,调用可能被拒绝。命令行执行php -r 'var_dump(opcache_reset());'也通常只作用于CLI环境,不能据此清理PHP-FPM的缓存。预加载脚本中的类和函数还可能需要完整重启FPM,不能把opcache_reset()当作所有场景的替代方案。

必要时重启PHP-FPM

当validate_timestamps=0、启用了预加载、软链接切换后路径识别异常,或者缓存状态无法确认时,重启对应FPM服务通常比删除缓存目录更可靠。

重启前先确认服务和配置:

systemctl --type=service --no-pager | grep -Ei 'php.*fpm'
sudo systemctl status php8.2-fpm --no-pager

服务名不能照抄。如果实际服务不是php8.2-fpm,应替换为上一步确认的名称。配置文件有修改时,先进行语法检查:

sudo "$FPM_BIN" -t

预期结果应表示配置测试通过。如果检查失败,不要继续重启;应根据报错修复配置,或者恢复最近一次备份。单节点网站执行重启可能造成短暂连接失败或502;多节点环境应先摘除一台节点,重启并验证健康检查,再按批次处理其他节点。

sudo systemctl restart php8.2-fpm
sudo systemctl status php8.2-fpm --no-pager

reload和restart不要混为一谈。reload通常用于重新读取配置并平滑处理工作进程,但不同发行版和服务脚本的行为可能不同,不能默认它一定清空了旧OPcache。需要确定缓存已经失效时,应使用经过维护窗口评估的完整FPM重启。

重启后如果服务无法启动,可查看日志:

sudo journalctl -u php8.2-fpm --since '10 minutes ago' --no-pager

如果只是修改了OPcache配置,应保留修改前的配置副本。配置备份、语法测试和服务状态检查都通过后,再进行恢复操作。例如:

sudo cp -a /etc/php/8.2/fpm/conf.d/10-opcache.ini \
  /etc/php/8.2/fpm/conf.d/10-opcache.ini.bak

sudo "$FPM_BIN" -t

实际配置路径需要使用php --ini、FPM配置或发行版目录确认。不要在未确认路径的情况下执行覆盖或删除命令,也不要直接使用rm -rf清理OPcache文件缓存目录。若怀疑opcache.file_cache中存在异常,应先停止相关FPM服务、备份或改名缓存目录,确认权限和回滚方式后再处理;这属于后置手段,不是第一步操作。

修复后如何验证缓存已经失效

修复不能只看“重启命令执行成功”。至少完成以下验证:

  1. 重新检查活动代码目录和文件哈希,确认运行节点使用的是目标发布版本。
  2. 通过实际业务域名访问受保护诊断路由,确认PHP_SAPI为预期的FPM环境。
  3. 再次读取opcache.validate_timestamps、opcache.preload和opcache_get_status()。
  4. 访问业务接口,确认响应中的发布标识已经变化。
  5. 在多节点环境中重复请求,确认所有节点返回一致版本。
  6. 观察FPM日志、CPU、请求延迟和缓存命中变化,确认缓存预热没有造成异常。

可以使用下面的方式记录多次响应,具体字段以站点实际响应头为准:

for i in $(seq 1 10); do
  curl -sS -D - \
    -H 'Cache-Control: no-cache' \
    'https://www.example.com/health-check' \
    -o /tmp/health.body 2>/dev/null |
    grep -iE '^(HTTP/|X-Backend:|X-Release:|Age:|X-Cache:)'
done

如果所有请求都返回同一发布标识,且源文件哈希、FPM配置和Web诊断状态一致,说明这次缓存失效已经完成。若仍然偶发旧版本,应继续沿着后端节点、容器实例、FPM Socket和HTTP缓存方向排查,而不是继续增加重启次数。

后续发布可以把“发布标识、活动目录真实路径、入口文件哈希、目标FPM服务、缓存失效动作和复测结果”写入发布记录。对于关闭时间戳检查的生产环境,应把FPM重启或受控OPcache重置作为发布流程的一部分;对于频繁开发环境,则可以保留时间戳检查,并根据性能和更新频率设置合理的revalidate_freq。这样能把一次偶发的旧代码问题,转化为每次发布都可验证的流程。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7103.html

相关推荐