编者按

有很多客户问我们NGINX商业版与开源版本到底有什么区别，在官方网站有一个对比列表，但看完之后感觉好像还是没有get到其增强的精髓。为了更好的让大家了解NGINX Plus增强的能力及其应用场景，特编发《NGINX Plus增强能力系列专题》。本系列一共包含10篇内容，为了精简，我们没有包含那些显而易见的增强例如dashboard，而是更聚焦商业版本的关键能力与场景。本专题内容由数位专家参与。

NGINX Plus增强能力系列专题目录：

• 视频直播HLS与RTMP
• 代理缓存状态统计与清理
• 动态KV模块
• NGINX实现动态黑白名单访问控制
• 主动健康检查
• NGINX集群
• JWT认证
• API接口
• 会话级log记录
• http_upstream与stream_upstream
• 下面我们就进入《NGINX Plus增强能力系列专题》的第二篇“动态KV模块”，作者林健。

林健

F5 金融行业资深技术顾问

应用交付领域从业12年有余，职业生涯前期专注于系统开发数据库调优，现热衷于coding，主持Ansible/K8S/Spring/BIG-IQ等多个F5专题。具备丰富编程以及软件化相关知识，对技术趋势有独立见解，成功帮助客户实施基于F5产品的应用多中心部署方案，多容器集群解决方案。致力于部署创新性项目，充分发挥F5技术优势打造下一代IT以及软件架构。拥有F5 101-304全系列产品认证证书。

动态KV模块

NGINX KV模块，全称ngx_stream_keyval_module/nginx_http_keyval_module，是nginx plus的商业化模块，主要实现为可以通过API进行管理的内部可持久化kv存储。

1. 使用KV模块的基本方法

步骤一:

需要建立一个http 的server，在server中配置一个使用api write = on指令的location，作为API接口的地址，类似如下：

如只是通过njs进行使用kv，类似F5的table命令，此时无需该配置。

步骤二：

使用keyval_zone命令声明一个kv zone，该命令格式为

请注意keyval_zone的上下文为http和stream，不要写在server中

参数中其中name为该zone的名称，size为大小，这两项为必须输入项目

以下为可选项目

State：持久化配置的本地文件,请注意如果修改了nginx的配置，然后运行重启，有可能会由于修改后的配置和该文件内容不匹配造成重启失败，比如原类型为string，后修改为ip，但是该文件还是string，此时会报错。

Timeout：存储在kv中的key pair保存时间,其格式为10m（10分钟），60s（60秒），在超过该时间后，记录失效，在通过API获取的时候无法看到该数值，可以在state文件中找到expire字段，每条记录的该字段可以通过api重写。

Type：1.17.1版本以上可用，包括下面的可选值

注意此处的type是指key的type步骤三：
在具体的业务配置中使用keyval命令，映射目标变量值为kv中的对应值。使用命令为keyval

其中key为输入变量，也就是在kv中的查找key值，$variable为输出变量，该命令上下文也是http。

2. 如何添加，修改，删除KV中的内容：

• API方式

使用nginx的api的rest接口，向对应的zone对象post，put，delete，类似如下

新创建一个zone

curl -X POST -d '{"linjian":"se","xufeng":"manager","linjing":"sa"}' http://localhost/api/1/http/keyvals/my_test_zone

修改其中一个key对应的value：

curl -X PATCH -d '{"linjian":"FSE"}' http://localhost/api/1/http/keyvals/my_test_zone

删除也是使用PATCH方法，只要设定其value为null即可，如下：

curl -X PATCH -d '{"linjian":null}' http://localhost/api/1/http/keyvals/my_test_zone

可以在patch方法中使用expire参数，修改kv对的超时时间，此时会override在配置文件中的zone timeout值。

类似：

{"key1" : "value1","key2" : "value2","key3" : {"value" : "value3","expire" : 30000}
}

需要注意，如果NGINX+是在一个sync集群中，删除操作只会在当前目标节点生效。

使用DELETE方法删除整个kv zone的内容

curl -X DELETE http://localhost/api/1/http/keyvals/my_test_zone

同样，删除整个zone的操作也只在当前目标节点生效

NJS方式：

用一个官方例子说明：

js_include js_requests.js;js_set $num_requests num_requests;keyval_zone zone=foo:10m;
keyval $remote_addr $foo zone=foo;log_format bar '$remote_addr [$time_local] $num_requests';
access_log logs/access.log bar;
server {listen 8000;location / {root html;}
}

js_requests.js:

function num_requests(r)
{var n = r.variables.foo;n = n ? Number(n) + 1 : 1;r.variables.foo = n;return n;
}

在上述例子在kv中记录每个ip地址的请求总数，njs修改kv内容需要使用一个nginx配置中的变量，使用<r.variables.变量名>进行读取和修改，此后无需额外的set操作，该值会直接写入对应的keyval zone,也可以使用njs的subrequest访问本机的API uri进行操作。

3. Keyval模块部署场景：

Keyval模块本身只是一个可以被api控制的kv，主要用途是根据动态条件执行后续操作，在某些场合可以实现数据，但是由于nginx配置本身并不是编程开发语言，缺少运算功能，在配置文件中用无法用原生的nginx配置在kv中添加数据，在很多一些场合建议配合njs模块可以更好的效果，注意在1.15.1版本后，njs模块可以在运行时动态

在条件场景下需要结合其他模块所提供的变量实现映射才可以发挥功效，在一些场合结合map指令对kv值进行进一步的分类

官方方案包含：

• Dynamic Bandwidth Limits Using the NGINX Plus Key-Value Store

https://www.nginx.com/blog/dynamic-bandwidth-limits-nginx-plus-key-value-store/

• Dynamic A/B Testing with NGINX Plus

https://www.nginx.com/blog/dynamic-a-b-testing-with-nginx-plus/

• Dynamic IP Blacklisting with NGINX Plus and fail2ban

https://www.nginx.com/blog/dynamic-ip-blacklisting-with-nginx-plus-and-fail2ban/

动态SSL证书：

https://gist.github.com/nginx-gists/7879b97e29b3d23fc72daef5591af74c