Redis MODULE LOAD加载自定义模块扩展命令

Redis 自定义模块允许开发者使用 C 语言（或其他支持 C 接口的语言）编写新命令，并将其动态加载到 Redis 服务器中，从而突破原生命令的限制。本文将详细介绍从环境搭建到模块加载的完整流程。

第一阶段：环境准备与依赖安装

在编写和加载自定义模块之前，必须确保系统中已安装必要的编译工具和 Redis 服务。

1. 检查 Redis 版本。
   Redis 模块功能是在 4.0 版本引入的。执行以下命令确认版本号：

   redis-server -v

   如果版本低于 4.0，请先升级 Redis。

2. 安装 编译工具链。
   编写 Redis 模块通常使用 C 语言，因此需要安装 GCC 编译器和 Make 工具。在 Ubuntu/Debian 系统中，运行：

   sudo apt-get update
   sudo apt-get install build-essential

   在 CentOS/RedHat 系统中，运行：

   sudo yum groupinstall "Development Tools"

3. 获取 Redis 模块头文件。
   编写模块时必须依赖 redismodule.h 头文件。执行以下命令从 Redis 官方 GitHub 仓库下载该文件：

   wget https://raw.githubusercontent.com/redis/redis/unstable/src/redismodule.h

   将该文件保存在你即将编写代码的同一目录下。

第二阶段：编写自定义模块代码

我们将编写一个简单的模块，实现一个名为 HELLO.SIMPLE 的命令，该命令返回字符串 "Hello from custom module!"。

1. 创建 源代码文件。
   新建一个名为 hellotest.c 的文件，并输入以下代码：

   #include "redismodule.h"
   #include <string.h>
   
   /* 命令实现函数 */
   int HelloSimple_RedisCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
       /* 必须处理参数，即使不使用 */
       REDISMODULE_NOT_USED(argv);
       REDISMODULE_NOT_USED(argc);
   
       /* 自动回收内存标志 */
       RedisModule_AutoMemory(ctx);
   
       /* 向客户端返回字符串 */
       RedisModule_ReplyWithSimpleString(ctx, "Hello from custom module!");
       return REDISMODULE_OK;
   }
   
   /* 模块加载时的初始化函数 */
   int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
       /* 处理模块加载时的参数（本例暂不使用） */
       REDISMODULE_NOT_USED(argv);
       REDISMODULE_NOT_USED(argc);
   
       /* 注册模块名称和版本 */
       if (RedisModule_Init(ctx, "hellotest", 1, REDISMODULE_APIVER_1) == REDISMODULE_ERR) {
           return REDISMODULE_ERR;
       }
   
       /* 注册命令：HELLO.SIMPLE */
       /* 参数：上下文, 命令名, 回调函数, 属性标志位, 首个键参数位置, 末尾键参数位置, 步数 */
       if (RedisModule_CreateCommand(ctx, "hello.simple", HelloSimple_RedisCommand, "readonly", 0, 0, 0) == REDISMODULE_ERR) {
           return REDISMODULE_ERR;
       }
   
       return REDISMODULE_OK;
   }

2. 理解 核心函数逻辑。

   • RedisModule_OnLoad：这是模块的入口点。当 Redis 执行 MODULE LOAD 时会调用此函数。它负责初始化模块并注册新命令。
   • RedisModule_CreateCommand：将具体的命令名字符串（如 hello.simple）与对应的 C 函数（如 HelloSimple_RedisCommand）绑定。
   • RedisModule_ReplyWithSimpleString：用于向客户端返回执行结果。

第三阶段：编译动态链接库

编写完代码后，需要将其编译为 Redis 可以识别的动态链接库（即 .so 文件）。

1. 执行 编译命令。
   在 hellotest.c 所在目录下，运行以下命令：

   gcc -fPIC -shared -o hellotest.so hellotest.c

   • -fPIC：生成位置无关代码，这是动态库所必需的。
   • -shared：生成共享库文件。
   • -o hellotest.so：指定输出文件名为 hellotest.so。

2. 验证 文件生成。
   使用 ls 命令查看目录，确认生成了 hellotest.so 文件。

第四阶段：加载模块

加载模块有两种方式：一种是在 Redis 命令行中临时加载，另一种是通过配置文件持久化加载。

方式一：使用命令行动态加载 (临时)

这种方式适合开发调试，重启 Redis 后模块会失效。

1. 启动 Redis 服务器。
   确保有一个 Redis 实例正在运行：

   redis-server

2. 连接 Redis 客户端。
   打开一个新的终端窗口，运行：

   redis-cli

3. 执行 加载命令。
   在 CLI 中，输入 MODULE LOAD 命令并指定 .so 文件的绝对路径：

   MODULE LOAD /path/to/your/hellotest.so

   如果返回 OK，说明模块加载成功。

方式二：使用配置文件加载 (持久)

这种方式适用于生产环境，Redis 每次启动都会自动加载指定模块。

1. 打开 Redis 配置文件。
   通常位于 /etc/redis/redis.conf 或你的安装目录下。

2. 添加 加载配置。
   在文件中找到 loadmodule 部分，或者直接在文件末尾添加一行：

   loadmodule /path/to/your/hellotest.so

3. 重启 Redis 服务。
   执行重启命令使配置生效：

   sudo systemctl restart redis

   或直接杀掉进程重启。

第五阶段：验证与测试

模块加载成功后，就可以像使用原生命令（如 GET、SET）一样使用自定义命令。

1. 测试 自定义命令。
   在 redis-cli 中，输入：

   hello.simple

2. 检查 返回结果。
   如果一切正常，终端将显示：

   "Hello from custom module!"

3. 查看 模块列表。
   若确认当前加载了哪些模块，运行：

   MODULE LIST

   输出将包含四个字段：模块 ID、名称、引擎版本和 API 版本。

第六阶段：卸载模块与管理

当不再需要某个模块，或者需要更新模块代码重新编译时，需要将其卸载。

1. 执行 卸载命令。
   运行以下命令：

   MODULE UNLOAD hellotest

   参数是模块的名称（即代码中 RedisModule_Init 的第一个参数），而不是文件名。

2. 处理 卸载失败。
   如果系统提示 ERR Unloading failed，通常是因为当前有客户端正在阻塞使用该模块的命令，或者有脚本正在执行。关闭所有连接或脚本后再次尝试。

3. 安全注意事项。

   • 权限控制：由于模块拥有与 Redis 进程相同的系统权限，禁止加载来源不明的 .so 文件，恶意模块可能导致数据泄露或系统被控。
   • 参数清理：在代码中务必严格校验 argc 和 argv，防止因参数格式错误导致进程崩溃。

通过以上步骤，你已成功掌握了 Redis 模块的编写、编译、加载及卸载全流程，可以利用 MODULE LOAD 灵活扩展 Redis 的功能。