一、模塊安裝與驗證
-
檢查模塊是否可用
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 的前提下，輕松實現動態路由、功能開關、訪問控制等需求，大幅提升運維與業務迭代效率。祝你上手順利！
