ngx_http_keyval_module动态键值管理

一、模块安装与验证

检查模块是否可用
bash 复制代码
```
nginx -V 2>&1 | grep --color -o ngx_http_keyval_module
```
- 如果看到 ngx_http_keyval_module，说明模块已编译进 NGINX。
- 若未找到，请联系你的 NGINX 供应商，获取商业版或重新编译并启用该模块：
  bash 复制代码
```
./configure --add-module=/path/to/ngx_http_keyval_module
make && make install
```
创建持久化目录

如果打算使用 state 持久化文件，先创建目录并设置权限：
bash 复制代码
```
sudo mkdir -p /var/lib/nginx/state
sudo chown nginx:nginx /var/lib/nginx/state
```

二、基础配置示例

将以下配置段加入到你的 nginx.conf（或包含在 http { ... } 块内）：

nginx 复制代码

# 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. 语法检查并重载

bash 复制代码

sudo nginx -t && sudo systemctl reload nginx

nginx -t：检查配置是否有语法错误。
reload：平滑重载，使新配置生效，无需重启服务。

2. 通过 API 写入键值对

请求方式 ：POST /api
请求头 ：Content-Type: application/json

请求体示例：

json 复制代码

{
  "key": "hello",
  "value": "world"
}

curl 命令：

bash 复制代码

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 测试：
bash 复制代码
```
curl "http://example.com/?arg_text=hello"
```
如果看到 world，说明查表成功。

4. 删除键值对

请求方式 ：DELETE /api
请求体示例：
json 复制代码
```
{ "key": "hello" }
```

curl 命令：

bash 复制代码

curl -X DELETE http://example.com/api \
     -H "Content-Type: application/json" \
     -d '{"key":"hello"}'

再次访问 /?arg_text=hello，返回空字符串，说明已删除。

四、进阶配置与场景

1. IP 白名单与灰度发布

配置

nginx 复制代码

# 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 小时内有效）：

bash 复制代码

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

业务配置：

nginx 复制代码

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

过期自动删除 ：1 小时后，192.168.1.0/24 会被移除，无需手动干预。

2. 前缀匹配做 A/B 测试

配置

nginx 复制代码

# 前缀匹配，24 小时过期
keyval_zone zone=ab:32k type=prefix timeout=24h state=/var/lib/nginx/state/ab.keyval;
keyval $arg_userid $bucket zone=ab;

操作流程

划分流量：

bash 复制代码

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

路由逻辑：

nginx 复制代码

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 文件损坏
- 若手动编辑产生语法错误，可临时移除或重命名，让模块重建：
  bash 复制代码
```
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 的前提下，轻松实现动态路由 、功能开关 、访问控制等需求，大幅提升运维与业务迭代效率。祝你上手顺利！