Redis

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 13 中文文档 /

本文档最新版为 12.x，旧版本可能放弃维护，推荐阅读最新版！

Redis

简介
配置
- 集群
- Predis
- PhpRedis
与 Redis 交互
- 事务
- 命令流水线
发布与订阅

简介

Redis 是一个开源的高级键值存储系统。由于键可以存储字符串、哈希表、列表、集合和有序集合，它也常被称为数据结构服务器。

在 Laravel 中使用 Redis 前，建议先通过 PECL 安装 PhpRedis PHP 扩展。与纯 PHP 包相比，该扩展的安装过程更复杂，但对于大量使用 Redis 的应用，可能提供更好的性能。如果你使用 Laravel Sail，应用的 Docker 容器中已经安装了此扩展。

如果无法安装 PhpRedis 扩展，可以通过 Composer 安装 predis/predis 包。Predis 是一个完全用 PHP 编写的 Redis 客户端，无需额外扩展：

composer require predis/predis

配置

你可以在 config/database.php 配置文件中设置应用的 Redis 连接。该文件中的 redis 数组包含应用使用的 Redis 服务器配置：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug((string) env('APP_NAME', 'laravel')).'-database-'),
    ],

    'default' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],

    'cache' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_CACHE_DB', '1'),
    ],

],

配置文件中定义的每个 Redis 服务器都需要指定名称、主机和端口，除非使用一个 URL 来表示整个 Redis 连接：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug((string) env('APP_NAME', 'laravel')).'-database-'),
    ],

    'default' => [
        'url' => 'tcp://127.0.0.1:6379?database=0',
    ],

    'cache' => [
        'url' => 'tls://user:password@127.0.0.1:6380?database=1',
    ],

],

配置连接协议

默认情况下，Redis 客户端使用 tcp 协议连接 Redis 服务器。你可以在服务器的配置数组中设置 scheme 选项，启用 TLS / SSL 加密：

'default' => [
    'scheme' => 'tls',
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
],

集群

如果应用使用 Redis 服务器集群，应在 Redis 配置的 clusters 键下定义集群。该配置键默认不存在，需要在应用的 config/database.php 配置文件中添加：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug((string) env('APP_NAME', 'laravel')).'-database-'),
    ],

    'clusters' => [
        'default' => [
            [
                'url' => env('REDIS_URL'),
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'username' => env('REDIS_USERNAME'),
                'password' => env('REDIS_PASSWORD'),
                'port' => env('REDIS_PORT', '6379'),
                'database' => env('REDIS_DB', '0'),
            ],
        ],
    ],

    // ...
],

默认情况下，options.cluster 的值为 redis，因此 Laravel 会使用原生 Redis 集群。它能够妥善处理故障转移，是合适的默认选择。

使用 Predis 时，Laravel 还支持客户端分片。但客户端分片不处理故障转移，因此主要适用于临时缓存数据，且这些数据仍可从另一个主数据存储中获取。

要改用客户端分片，可以从应用的 config/database.php 配置文件中移除 options.cluster 配置项：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'clusters' => [
        // ...
    ],

    // ...
],

Predis

要让应用通过 Predis 包与 Redis 交互，请确保 REDIS_CLIENT 环境变量的值为 predis：

'redis' => [

    'client' => env('REDIS_CLIENT', 'predis'),

    // ...
],

除了默认配置选项，Predis 还支持为每个 Redis 服务器定义额外的连接参数。要使用这些选项，请将其添加到应用 config/database.php 文件中对应的 Redis 服务器配置：

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_write_timeout' => 60,
],

PhpRedis

默认情况下，Laravel 使用 PhpRedis 扩展与 Redis 通信。所使用的客户端由 redis.client 配置项决定，该配置项通常取自 REDIS_CLIENT 环境变量：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    // ...
],

除了默认配置选项，PhpRedis 还支持以下连接参数：name、persistent、persistent_id、prefix、read_timeout、retry_interval、max_retries、backoff_algorithm、backoff_base、backoff_cap、timeout 和 context。你可以将这些选项添加到 config/database.php 文件中的 Redis 服务器配置：

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_timeout' => 60,
    'context' => [
        // 'auth' => ['username', 'secret'],
        // 'stream' => ['verify_peer' => false],
    ],
],

重试与退避配置

retry_interval、max_retries、backoff_algorithm、backoff_base 和 backoff_cap 选项用于配置 PhpRedis 客户端重新连接 Redis 服务器的方式。支持的退避算法包括：default、decorrelated_jitter、equal_jitter、exponential、uniform 和 constant：

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
    'backoff_algorithm' => env('REDIS_BACKOFF_ALGORITHM', 'decorrelated_jitter'),
    'backoff_base' => env('REDIS_BACKOFF_BASE', 100),
    'backoff_cap' => env('REDIS_BACKOFF_CAP', 1000),
],

发生短暂的连接故障后，Laravel 会自动重试一次安全的读取命令。你可以使用 command_retries 选项，配置所有 Redis 命令的重试次数：

'default' => [
    // ...
    'command_retries' => env('REDIS_COMMAND_RETRIES', 0),
],

Predis 3.4.0 及更高版本通过 Retry 类内置了重试和退避支持。你可以使用 max_retries 选项配置重试次数，使用 retry 选项配置退避策略。retry 应为一个数组，以以下策略类之一作为键：NoBackoff、EqualBackoff 或 ExponentialBackoff：

use Predis\Retry\Strategy\ExponentialBackoff;

'default' => [
    'url' => env('REDIS_URL'),
    // ...
    'retry' => [
        ExponentialBackoff::class => [
            env('REDIS_BACKOFF_BASE', 100),
            env('REDIS_BACKOFF_CAP', 1000),
            true, // 启用抖动……
        ],
    ],
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
],

将 Predis 用于 Redis 集群时，可以在集群配置的 parameters 选项中定义重试配置：

use Predis\Retry\Strategy\NoBackoff;

'clusters' => [
    'default' => [
        // ...
    ],
],

'options' => [
    'cluster' => env('REDIS_CLUSTER', 'redis'),
    'parameters' => [
        'retry' => [
            NoBackoff::class => [],
        ],
        'max_retries' => env('REDIS_MAX_RETRIES', 3),
    ],
],

Unix 套接字连接

Redis 连接也可以使用 Unix 套接字。当 Redis 实例与应用位于同一台服务器上时，这样可以省去 TCP 连接的开销，提高性能。要使用 Unix 套接字，请将 REDIS_HOST 环境变量设为 Redis 套接字路径，并将 REDIS_PORT 设为 0：

REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0

PhpRedis 序列化与压缩

PhpRedis 扩展支持多种序列化器和压缩算法，可以通过 Redis 配置中的 options 数组进行设置：

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug((string) env('APP_NAME', 'laravel')).'-database-'),
        'serializer' => Redis::SERIALIZER_MSGPACK,
        'compression' => Redis::COMPRESSION_LZ4,
    ],

    // ...
],

目前支持的序列化器包括：Redis::SERIALIZER_NONE（默认）、Redis::SERIALIZER_PHP、Redis::SERIALIZER_JSON、Redis::SERIALIZER_IGBINARY 和 Redis::SERIALIZER_MSGPACK。

支持的压缩算法包括：Redis::COMPRESSION_NONE（默认）、Redis::COMPRESSION_LZF、Redis::COMPRESSION_ZSTD 和 Redis::COMPRESSION_LZ4。

与 Redis 交互

你可以调用 Redis 门面上的各种方法与 Redis 交互。Redis 门面支持动态方法，因此你可以在门面上调用任意 Redis 命令，命令会直接传递给 Redis。以下示例通过调用 Redis 门面的 get 方法，执行 Redis 的 GET 命令：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Redis;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 显示指定用户的资料。
     */
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => Redis::get('user:profile:'.$id)
        ]);
    }
}

如上所述，你可以在 Redis 门面上调用任意 Redis 命令。Laravel 通过魔术方法将命令传递给 Redis 服务器。如果命令需要参数，请将它们传给门面上对应的方法：

use Illuminate\Support\Facades\Redis;

Redis::set('name', 'Taylor');

$values = Redis::lrange('names', 5, 10);

你也可以使用 Redis 门面的 command 方法向服务器发送命令。该方法的第一个参数是命令名称，第二个参数是参数值数组：

$values = Redis::command('lrange', ['name', 5, 10]);

使用多个 Redis 连接

你可以在应用的 config/database.php 配置文件中定义多个 Redis 连接或服务器，再通过 Redis 门面的 connection 方法获取指定连接：

$redis = Redis::connection('connection-name');

调用 connection 方法时不传参数，即可获取默认 Redis 连接的实例：

$redis = Redis::connection();

事务

Redis 门面的 transaction 方法封装了 Redis 原生的 MULTI 和 EXEC 命令。该方法只接受一个闭包参数，闭包会接收一个 Redis 连接实例，你可以向该实例发送任意命令。闭包内发送的所有 Redis 命令都会在同一个原子事务中执行：

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::transaction(function (Redis $redis) {
    $redis->incr('user_visits', 1);
    $redis->incr('total_visits', 1);
});

[!WARNING]
定义 Redis 事务时，不能从 Redis 连接中读取值。事务会作为一个原子操作执行，只有整个闭包完成命令的提交后，这些命令才会真正执行。

Lua 脚本

eval 方法也可以在一个原子操作中执行多条 Redis 命令，并且允许在操作过程中读取和修改 Redis 键值。Redis 脚本使用 Lua 编程语言编写。

初次接触 eval 可能觉得复杂，我们先看一个基本示例。该方法依次接受以下参数：Lua 脚本字符串、脚本要操作的键的数量（整数），以及这些键的名称。最后，还可以传入脚本中需要访问的其他参数。

以下示例先递增第一个计数器并检查新值。如果新值大于 5，就递增第二个计数器，最后返回第一个计数器的值：

$value = Redis::eval(<<<'LUA'
    local counter = redis.call("incr", KEYS[1])

    if counter > 5 then
        redis.call("incr", KEYS[2])
    end

    return counter
LUA, 2, 'first-counter', 'second-counter');

[!WARNING]
关于 Redis 脚本的更多信息，请参阅 Redis 文档。

命令流水线

有时需要执行数十条 Redis 命令。你可以使用 pipeline 方法，将命令一次性发送到 Redis 服务器，减少网络往返次数。该方法接受一个闭包参数，闭包会接收一个 Redis 实例，你可以向该实例发送所有命令。命令仍会按发送顺序执行：

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::pipeline(function (Redis $pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", $i);
    }
});

发布与订阅

Laravel 为 Redis 的 publish 和 subscribe 命令提供了便捷接口。你可以监听指定「频道」上的消息，也可以从其他应用，甚至使用其他编程语言向该频道发布消息，方便应用和进程之间通信。

首先，使用 subscribe 方法设置频道监听器。由于调用该方法会启动一个长时间运行的进程，我们将它放在 Artisan 命令中：

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Redis;

class RedisSubscribe extends Command
{
    /**
     * 控制台命令的名称和签名。
     *
     * @var string
     */
    protected $signature = 'redis:subscribe';

    /**
     * 控制台命令的描述。
     *
     * @var string
     */
    protected $description = 'Subscribe to a Redis channel';

    /**
     * 执行控制台命令。
     */
    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}

现在可以使用 publish 方法向频道发布消息：

use Illuminate\Support\Facades\Redis;

Route::get('/publish', function () {
    // ...

    Redis::publish('test-channel', json_encode([
        'name' => 'Adam Wathan'
    ]));
});

通配符订阅

使用 psubscribe 方法，可以通过通配符订阅频道，从而接收所有匹配频道的消息。频道名称会作为第二个参数传给闭包：

Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/13.x/re...

译文地址：https://learnku.com/docs/laravel/13.x/re...

Markdown 文本

你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程，JWT 概念及使用和 API 开发相关的进阶知识。

从零开始带你一步步开发一个 Go 博客项目，让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。

贡献者：1

Redis

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Redis

简介

配置

配置连接协议

集群

Predis

PhpRedis

重试与退避配置

Unix 套接字连接

PhpRedis 序列化与压缩

与 Redis 交互

使用多个 Redis 连接

事务

Lua 脚本

命令流水线

发布与订阅

通配符订阅

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

Redis 13.x 13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Redis

简介

配置

配置连接协议

集群

Predis

PhpRedis

重试与退避配置

Unix 套接字连接

PhpRedis 序列化与压缩

与 Redis 交互

使用多个 Redis 连接

事务

Lua 脚本

命令流水线

发布与订阅

通配符订阅

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录

Redis

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1