ngx_http_keyval_module动态键值管理

一、模块安装与验证

1. 检查模块是否可用

   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
     

2. 创建持久化目录
   如果打算使用 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. 加入灰度（1 小时内有效）：

   curl -X POST http://example.com/api \-H "Content-Type: application/json" \-d '{"key":"192.168.1.0/24","value":"on"}'
   

2. 业务配置：

   location /new-feature {if ($gray_flag = "on") {proxy_pass http://new_backend;}return 403;  # 其他用户禁止访问
   }
   

3. 过期自动删除：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;

操作流程

1. 划分流量：

   # 前缀 "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"}'
   

2. 路由逻辑：

   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	指定共享内存区名称

六、常见问题与排查

1. 写入后未生效

   • 检查 /api 是否正确启用 write=on。
   • 查看 NGINX error 日志：sudo tail -n50 /var/log/nginx/error.log。

2. state 文件损坏

   • 若手动编辑产生语法错误，可临时移除或重命名，让模块重建：

     mv /var/lib/nginx/state/one.keyval /var/lib/nginx/state/one.keyval.bak
     sudo systemctl reload nginx
     

3. 内存不足报错

   • 增大 keyval_zone 的 size，如 64k、128k，保证索引空间充足。

七、结语

通过以上零基础、逐步演示，你已掌握：

• 模块安装验证
• 基础配置与 API 操作
• 灰度发布、A/B 测试等实战场景
• 参数详解与常见问题排查

借助 ngx_http_keyval_module，你可以在不重启 NGINX 的前提下，轻松实现动态路由、功能开关、访问控制等需求，大幅提升运维与业务迭代效率。祝你上手顺利！