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;
   }
   

五、参数详解汇总

六、常见问题与排查

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 的前提下，轻松实现动态路由、功能开关、访问控制等需求，大幅提升运维与业务迭代效率。祝你上手顺利！