在 nginx 中配置动态键值存储,核心是启用 ngx_http_keyval_module 模块。该模块允许将变量值持久化到共享内存或外部后端(如 redis),从而实现跨请求的状态保持。具体做法是在 http 块中使用 keyval_store 指令定义存储位置,并在 server 或 location 块中使用 keyval 指令进行读写操作。

如何配置基于共享内存的本地键值存储
使用共享内存是最常见的本地持久化方式,适用于单机部署且数据量不大的场景。通过 keyval_store 指定 zone 参数,Nginx 会在启动时分配一块固定大小的内存区域来存储键值对。这种方式无需额外依赖,配置简单,但重启后数据会丢失(除非配合 file 参数实现磁盘持久化)。

worker_processes 1;
events {
worker_connections 1024;
}
http {
# 定义一个名为 'my_zone' 的共享内存区域,大小 10m
keyval_store zone=my_zone:10m;
server {
listen 80;
server_name localhost;
location /api {
# 读取键 'user_id' 对应的值,存入变量 $uid
keyval $arg_uid $uid store=my_zone;
# 如果未找到,设置默认值
set $uid_default $uid;
if ($uid = "") {
set $uid_default "anonymous";
}
return 200 "User ID: $uid_default";
}
}
}
上述配置中,keyval_store 创建了一个名为 my_zone 的共享内存区。在 /api 路径下,keyval 指令尝试从 URL 参数 $arg_uid 获取键,并将查找到的值赋给 $uid。若键不存在,$uid 将为空。这种机制常用于简单的用户会话追踪或 A/B 测试分组,前提是客户端每次请求都携带相同的标识符。
如何配置基于 Redis 的外部键值存储
当需要跨多台 Nginx 实例共享状态,或存储大量数据时,应使用 Redis 作为后端。这需要编译安装带有 --with-http_keyval_module 和 Redis 支持的 Nginx 版本。通过 keyval_store 的 redis 参数连接远程服务,所有读写操作都会通过网络与 Redis 交互。

http {
# 配置 Redis 后端,地址为 127.0.0.1:6379
keyval_store redis=127.0.0.1:6379 db=0 prefix="nginx:";
server {
listen 80;
server_name localhost;
location /rate-limit {
# 以 IP 为键,查询访问次数
keyval $remote_addr $count store=redis;
# 假设逻辑:如果 count > 5,则拒绝
if ($count ~ "^[6-9]$|^[0-9]{2,}$") {
return 429 "Too Many Requests";
}
# 增加计数并写回 Redis
set $new_count $(( $count + 1 ));
keyval $remote_addr $new_count store=redis;
return 200 "Current Count: $new_count";
}
}
}
在此配置中,keyval_store 指向了本地的 Redis 实例,并使用 prefix 避免键冲突。在 /rate-limit 处理中,首先读取当前 IP 的访问次数,然后判断是否超限,最后更新计数。需要注意的是,Redis 模式下的读写是异步或同步的网络调用,可能会引入延迟,因此不适合对性能极度敏感的场景。此外,keyval 指令本身不支持原子递增,需先读后写,在高并发下可能存在竞态条件,实际生产环境建议结合 Lua 脚本或专用限流模块使用。
当 keyval 指令中 store 参数未指定时会发生什么
如果在 keyval 指令中省略了 store 参数,Nginx 将不会执行任何持久化操作,仅在当前请求上下文中进行临时变量赋值。这意味着键值对不会保存到任何共享内存或外部后端,重启 Nginx 后所有数据丢失,且其他 worker 进程无法访问这些数据。
例如,以下配置中 keyval 没有指定 store:
location /test {
keyval $arg_key $value; # 无 store 参数
return 200 "Value: $value";
}
在这种情况下,无论之前是否有其他请求设置了该键,当前请求中的 $value 始终为空。这是因为缺少 store 意味着没有关联的存储后端供查询。开发者在使用时应确保每个需要持久化的 keyval 调用都明确指定了 store 参数,否则功能将失效。同时,若多个 keyval 指令引用同一个 store,它们将共享同一份数据源,需注意键名唯一性以避免覆盖。


















