一、模块安装与验证
-
检查模块是否可用
nginx -V 2>&1 | grep --color -o ngx_http_keyval_module-
如果看到
ngx_http_keyval_module，说明模块已编译进 NGINX。 -
若未找到，请联系你的 NGINX 供应商，获取商业版或重新编译并启用该模块：
./configure --add-module=/path/to/ngx_http_keyval_module make && make install
-
-
创建持久化目录
如果打算使用state持久化文件，先创建目录并设置权限：sudo mkdir -p /var/lib/nginx/state sudo chown nginx:nginx /var/lib/nginx/state
二、基础配置示例
将以下配置段加入到你的 nginx.conf（或包含在 http { ... } 块内）：
# 1. 定义共享内存区 “one”，大小 32k，状态文件持久化到 /var/lib/nginx/state/one.keyval
keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval;
# 2. 定义查表规则：用请求参数 arg_text 作为“键”，查到的“值”放入 $text 变量
keyval $arg_text $text zone=one;
server {
listen 80;
server_name example.com;
# 3. 普通访问：直接返回 $text 的内容
location / {
# 如果没查到，$text 为空，返回空白
return 200 $text;
}
# 4. API 端点：允许 POST/DELETE 操作来增删键值对
location /api {
api write=on;
}
}
说明：
keyval_zone：声明共享内存，zone=name:size；可选state=path持久化；keyval：定义查表，key为输入变量，$variable为输出变量；location /api { api write=on; }：开启 HTTP API 管理。
三、部署与测试
1. 语法检查并重载
sudo nginx -t && sudo systemctl reload nginx
nginx -t：检查配置是否有语法错误。reload：平滑重载，使新配置生效，无需重启服务。
2. 通过 API 写入键值对
-
请求方式：
POST /api -
请求头：
Content-Type: application/json -
请求体示例：
{ "key": "hello", "value": "world" } -
curl 命令：
curl -X POST http://example.com/api \ -H "Content-Type: application/json" \ -d '{"key":"hello","value":"world"}' -
响应：HTTP 204 No Content 表示写入成功。
3. 验证查表结果
-
访问：
GET /?text=hello -
期望返回：
world -
curl 测试：
curl "http://example.com/?arg_text=hello"如果看到
world，说明查表成功。
4. 删除键值对
-
请求方式：
DELETE /api -
请求体示例：
{ "key": "hello" } -
curl 命令：
curl -X DELETE http://example.com/api \ -H "Content-Type: application/json" \ -d '{"key":"hello"}' -
再次访问
/?arg_text=hello，返回空字符串，说明已删除。
四、进阶配置与场景
1. IP 白名单与灰度发布
配置
# 16k 内存，IP 类型索引，1 小时后过期，开启同步
keyval_zone zone=gray:16k type=ip timeout=1h sync state=/var/lib/nginx/state/gray.keyval;
# 客户端 IP 作为查表键，结果写入 $gray_flag
keyval $remote_addr $gray_flag zone=gray;
操作流程
-
加入灰度（1 小时内有效）：
curl -X POST http://example.com/api \ -H "Content-Type: application/json" \ -d '{"key":"192.168.1.0/24","value":"on"}' -
业务配置：
location /new-feature { if ($gray_flag = "on") { proxy_pass http://new_backend; } return 403; # 其他用户禁止访问 } -
过期自动删除：1 小时后，
192.168.1.0/24会被移除，无需手动干预。
2. 前缀匹配做 A/B 测试
配置
# 前缀匹配，24 小时过期
keyval_zone zone=ab:32k type=prefix timeout=24h state=/var/lib/nginx/state/ab.keyval;
keyval $arg_userid $bucket zone=ab;
操作流程
-
划分流量：
# 前缀 "A" 组 curl -X POST http://example.com/api \ -H "Content-Type: application/json" \ -d '{"key":"A","value":"blue"}' # 前缀 "B" 组 curl -X POST http://example.com/api \ -H "Content-Type: application/json" \ -d '{"key":"B","value":"green"}' -
路由逻辑：
location / { if ($bucket = "blue") { proxy_pass http://blue_backend; } if ($bucket = "green") { proxy_pass http://green_backend; } # 默认回退 proxy_pass http://default_backend; }
五、参数详解汇总
| 指令 | 参数 | 含义 | ||
|---|---|---|---|---|
| keyval_zone | zone=name:size | 共享内存区名称和大小（如 one:32k） | ||
state=path | 持久化 JSON 文件路径 | |||
timeout=duration | 键值对自动过期时间（如 1h、24h） | |||
| `type=string | ip | prefix` | 索引类型： - string：精确匹配- ip：CIDR/IP 匹配- prefix：前缀匹配 | |
sync | 开启多节点删除同步（需配合 timeout） | |||
| keyval | key | 用于查表的 NGINX 变量（如 $arg_text、$remote_addr） | ||
$variable | 存储查表结果的变量名（如 $text、$gray_flag） | |||
zone=name | 指定共享内存区名称 |
六、常见问题与排查
-
写入后未生效
- 检查
/api是否正确启用write=on。 - 查看 NGINX error 日志：
sudo tail -n50 /var/log/nginx/error.log。
- 检查
-
state 文件损坏
-
若手动编辑产生语法错误，可临时移除或重命名，让模块重建：
mv /var/lib/nginx/state/one.keyval /var/lib/nginx/state/one.keyval.bak sudo systemctl reload nginx
-
-
内存不足报错
- 增大
keyval_zone的size，如64k、128k，保证索引空间充足。
- 增大
七、结语
通过以上零基础、逐步演示，你已掌握：
- 模块安装验证
- 基础配置与 API 操作
- 灰度发布、A/B 测试等实战场景
- 参数详解与常见问题排查
借助 ngx_http_keyval_module，你可以在不重启 NGINX 的前提下，轻松实现动态路由、功能开关、访问控制等需求，大幅提升运维与业务迭代效率。祝你上手顺利！
