Laravel中phpredis scan方法在Redis集群无结果问题排查

核心原因 #

Redis集群环境下，Laravel默认的scan调用仅会扫描当前连接的单个节点，若你的缓存键分布在集群的其他节点中，就会返回空结果；另外如果Laravel的Redis连接未正确配置为集群模式，也会导致无法跨节点扫描到目标键。

解决步骤 #

1. 确认Redis集群配置正确性 #

打开config/database.php，检查Redis配置是否启用集群模式，确保所有集群节点都已配置：

'redis' => [
    'client' => env('REDIS_CLIENT', 'predis'),
    'clusters' => [
        'default' => [
            [
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'password' => env('REDIS_PASSWORD', null),
                'port' => env('REDIS_PORT', 6379),
                'database' => env('REDIS_DB', 0),
            ],
            // 添加集群内其他节点的配置
            [
                'host' => '127.0.0.1',
                'port' => 6380,
                'database' => 0,
            ],
        ],
    ],
],

2. 遍历所有集群节点执行扫描 #

Laravel的scan方法在集群模式下默认仅操作单个节点，需手动遍历所有节点完成全集群扫描：

$redis = Redis::connection('default');
$matchedKeys = [];

// 遍历集群中的每个节点
foreach ($redis->getCluster()->getNodes() as $node) {
    $cursor = '0';
    do {
        // 在当前节点执行scan
        $scanResult = $node->scan($cursor, [
            'match' => 'my_application_cache_*',
            'count' => 999,
        ]);
        $cursor = $scanResult[0];
        // 合并当前节点的匹配结果
        $matchedKeys = array_merge($matchedKeys, $scanResult[1]);
    } while ($cursor !== '0'); // 直到cursor回到0，完成当前节点的全量扫描
}

dd($matchedKeys);

3. 验证Redis数据库一致性 #

检查Laravel配置的Redis数据库（database字段）与redis-cli使用的数据库是否一致。若cli通过SELECT 1切换了数据库，而Laravel配置的是0，也会导致扫描结果为空。

4. 客户端兼容性检查 #

若使用phpredis客户端而非predis，集群模式下的扫描逻辑略有不同，可以尝试使用RedisCluster的原生扫描方法，或升级客户端版本确保集群兼容性。

内容的提问来源于stack exchange，提问作者gamedev