PHP Session 迁移到 Redis：从本机文件到集中存储的回归检查清单

PHP 项目从单机部署走向多台 PHP-FPM 节点后，Session 仍然保存在本机文件目录里，就很容易出现“登录后偶发掉线”“同一个用户刷新几次状态不一致”“某台机器 session 目录越来越大”这类问题。把 Session 迁移到 Redis 的目标不是追求新潮，而是把登录态放到集中存储里，让多节点共享、过期清理可控、故障时有明确回滚路径。

升级范围：哪些项目适合迁移 Session 存储

如果项目仍是单机、小流量、没有多节点负载均衡，本机文件 Session 未必马上成为瓶颈。但只要出现下面几类情况，就应该把 Session 存储纳入迁移计划：

• PHP-FPM 节点超过一台，负载均衡没有做严格粘性会话。
• 用户登录后偶发跳回登录页，刷新后又恢复。
• 容器重建、发布重启后登录态大量丢失。
• /var/lib/php/session 或自定义 session 目录占用过高。
• 需要跨节点读取登录态、购物车、验证码或后台操作上下文。

迁移前要先定边界：本文讨论的是 PHP 内置 Session 存储从 files 切到 Redis，不讨论 JWT、OAuth 登录协议或完全自研登录态。

变更表：从 files 到 Redis 改了哪些点

这个表能说明一个关键点：迁移不是只改一行 session.save_handler。存储介质换了，容量、锁、过期、监控和回滚都要一起调整。

旧代码风险：本机文件在多节点下的问题

PHP 默认文件 Session 的问题，通常在单机时不明显，到了多节点后才集中爆发。负载均衡把同一个用户的两次请求分到不同 PHP-FPM 节点，第二台机器读不到第一台机器写入的 session 文件，于是应用误以为用户没有登录。

另一类风险是清理滞后。文件 Session 依赖 session.gc_probability、session.gc_divisor、session.gc_maxlifetime 等配置触发清理。访问模式不稳定时，过期文件可能长时间留在磁盘上。磁盘满了以后，新的 session 可能写入失败，登录态问题就从“偶发”变成“大面积”。

新写法：配置 Redis Session 与锁参数

如果使用常见的 phpredis 扩展，配置可以放在 php.ini、FPM pool 配置或容器环境模板里。最小结构如下：

session.save_handler = redis
session.save_path = "tcp://10.0.0.11:6379?auth=your_password&database=2"
session.gc_maxlifetime = 1800

生产环境还要把 Redis 连接、密码、库编号、前缀、超时和锁参数整理成配置项，避免不同环境手工改文件。一个更接近生产的示例可以这样组织：

session.save_handler = redis
session.save_path = "tcp://10.0.0.11:6379?auth=your_password&database=2&prefix=PHPSESSID:&timeout=2.0&read_timeout=2.0"
session.gc_maxlifetime = 1800
session.cookie_httponly = 1
session.cookie_samesite = Lax
session.use_strict_mode = 1

锁等待也要关注。PHP Session 的典型行为是打开 session 后持有锁，直到 session_write_close() 或请求结束才释放。如果某个接口打开 session 后又做慢查询、远程请求或文件处理，其他同一会话请求可能被锁住。

因此迁移后可以补一个编码规则：只在需要读写登录态时打开 Session，读完不再修改就尽早调用：

session_start();

$userId = $_SESSION['user_id'] ?? null;

// 后续不再写 Session，就尽早释放锁。
session_write_close();

if ($userId === null) {
    http_response_code(401);
    echo json_encode(['message' => '请先登录'], JSON_UNESCAPED_UNICODE);
    return;
}

这一步能明显减少同一个用户并发打开多个页面时的排队感，尤其是后台系统、报表页和上传页。

回归检查：登录、并发、过期和回滚

迁移完成后，不能只点一下登录成功就算通过。至少要覆盖下面几类回归：

1. 登录与登出

• 登录后刷新页面，登录态保持。
• 登出后 Redis 中对应 session 数据被清理或失效。
• 密码修改、权限变更后，旧会话是否按业务规则失效。

2. 多节点互通

用同一个 Cookie 连续请求不同 PHP-FPM 节点，确认都能读到相同 Session。可以在测试环境临时让响应头输出节点名，方便观察是否真的跨节点。

3. 并发锁等待

打开同一账号的多个页面，同时发起请求，观察是否出现明显排队。如果某个接口耗时很长，检查它是否在持有 Session 锁期间做了重活。

4. 过期时间

检查 Redis key 的 TTL 是否接近 session.gc_maxlifetime。如果 TTL 不符合预期，可能是配置没有生效，或者应用里重复启动 Session 导致行为不一致。

5. 回滚路径

上线前准备好回滚配置，例如切回：

session.save_handler = files
session.save_path = /var/lib/php/session

回滚不只是改配置，还要验证 PHP-FPM 能快速重载、旧 session 影响范围可接受、用户提示是否清楚。登录态存储切换通常会影响在线用户，最好在低峰期执行。

迁移清单：上线前后看哪些指标

迁移前：

• 确认所有 PHP 节点都安装并启用了 Redis 扩展。
• 确认 Redis 网络、认证、库编号和 key 前缀。
• 估算 Session 数量、平均大小和过期时间，得到内存预算。
• 确认 session.cookie_secure、HttpOnly、SameSite 等 Cookie 策略没有被迁移误改。
• 准备回滚配置和重载命令。

迁移后：

• 观察登录成功率、401/403 比例、用户掉线反馈。
• 观察 Redis 内存水位、连接数、慢日志和 key 过期情况。
• 观察同一用户并发请求的锁等待和接口耗时。
• 抽查 Redis key 是否带有统一前缀，避免和其他业务数据混在一起。
• 保留回滚开关至少一个发布周期，确认稳定后再清理临时配置。

容量预算可以先用保守公式估算：在线会话数乘以平均 Session 大小，再加上 30% 到 50% 的峰值缓冲。如果 Redis 还承载缓存、队列或限流数据，Session 不要和高淘汰风险数据放在同一个库或同一套淘汰策略里。

总结

PHP Session 从本机文件迁移到 Redis，解决的是多节点共享、过期清理和运维可观测问题。真正的迁移重点不是一句 session.save_handler = redis，而是把登录态当成一份有容量、有锁、有过期时间、有回滚策略的运行数据。

建议按四步推进：先盘点旧文件模式下的会话丢失和磁盘风险，再配置 Redis 和 Cookie 安全参数，随后压测锁等待和 TTL，最后用登录、登出、多节点、回滚四组用例做回归。这样迁移既能提升可用性，也不会把问题从磁盘目录搬到 Redis 内存里。