lolly/docs/35-nginx-keyval-module.md

# NGINX Keyval 模块详解

本文档详细介绍 NGINX Keyval 模块（动态键值存储）的配置与使用方法，包括 HTTP 和 Stream 两个子模块。

---

## 1. Keyval 模块概述

### 什么是 Keyval 模块

Keyval 模块是 NGINX 提供的**动态键值存储系统**，允许在运行时通过 API 动态管理键值对数据，无需重启 NGINX 即可更新配置逻辑。

### 模块组成

| 模块名称 | 上下文 | 商业版本 | 可用版本 |
|---------|--------|---------|---------|
| `ngx_http_keyval_module` | http | 需要 | 1.13.3+ |
| `ngx_stream_keyval_module` | stream | 需要 | 1.13.7+ |

### 核心特性

1. **动态更新**：通过 API 实时增删改查键值对
2. **内存存储**：使用共享内存，高性能访问
3. **持久化支持**：支持状态文件持久化，重启后数据不丢失
4. **过期机制**：支持键值对自动过期（TTL）
5. **集群同步**：支持多节点数据同步
6. **灵活匹配**：支持精确匹配、IP 子网匹配、前缀匹配

---

## 2. HTTP 与 Stream Keyval 模块对比

| 特性 | HTTP Keyval | Stream Keyval |
|------|-------------|---------------|
| **上下文** | `http` | `stream` |
| **模块名** | `ngx_http_keyval_module` | `ngx_stream_keyval_module` |
| **可用版本** | 1.13.3+ | 1.13.7+ |
| **键变量** | HTTP 变量（`$arg_*`, `$host`, `$uri` 等） | Stream 变量（`$ssl_server_name`, `$remote_addr` 等） |
| **使用场景** | HTTP 请求路由、限流白名单、动态配置 | TCP/UDP 四层代理路由、SSL 分流 |
| **API 管理** | `/api/{version}/http/keyvals/` | `/api/{version}/stream/keyvals/` |

### HTTP Keyval 典型应用

```nginx
http {
    # 根据请求参数动态返回值
    keyval $arg_user $user_data zone=user_db;

    server {
        location / {
            # $user_data 的值由 API 动态管理
            proxy_pass http://backend_$user_data;
        }
    }
}
```

### Stream Keyval 典型应用

```nginx
stream {
    # 根据 SSL SNI 名称路由到不同后端
    keyval $ssl_server_name $backend zone=ssl_routes;

    server {
        listen 443 ssl;
        proxy_pass $backend;
        ssl_certificate ...;
        ssl_certificate_key ...;
    }
}
```

---

## 3. HTTP Keyval 模块

### 3.1 指令详解

#### keyval_zone

定义存储键值对数据库的共享内存区域。

| 属性 | 说明 |
|------|------|
| **语法** | `keyval_zone zone=name:size [state=file] [timeout=time] [type=string\|ip\|prefix] [sync];` |
| **默认值** | — |
| **上下文** | http |

**参数说明**：

| 参数 | 说明 |
|------|------|
| `zone=name:size` | 共享内存区域名称和大小（如 `one:32k`） |
| `state=file` | 状态文件路径，JSON 格式持久化 |
| `timeout=time` | 键值对过期时间（1.15.0+） |
| `type` | 匹配类型：`string`（精确，默认）、`ip`（IP/CIDR）、`prefix`（前缀，1.17.5+） |
| `sync` | 启用集群同步（1.15.0+，需配合 `timeout`） |

**配置示例**：

```nginx
http {
    # 基本配置
    keyval_zone zone=one:32k;

    # 带持久化
    keyval_zone zone=two:64k state=/var/lib/nginx/state/two.keyval;

    # 带过期时间和同步
    keyval_zone zone=three:1m state=/var/lib/nginx/state/three.keyval timeout=1h sync;

    # IP 类型（用于 IP 黑白名单）
    keyval_zone zone=ip_list:256k type=ip;

    # 前缀类型（用于路由前缀匹配）
    keyval_zone zone=prefix_routes:128k type=prefix;
}
```

#### keyval

创建变量，其值通过键值数据库查找获得。

| 属性 | 说明 |
|------|------|
| **语法** | `keyval key $variable zone=name;` |
| **默认值** | — |
| **上下文** | http |

**参数说明**：

| 参数 | 说明 |
|------|------|
| `key` | 查找键，可使用 NGINX 变量（如 `$arg_user`, `$uri`） |
| `$variable` | 创建的变量名，存储查找到的值 |
| `zone=name` | 指定查询的共享内存区域 |

**配置示例**：

```nginx
http {
    keyval_zone zone=users:64k state=/var/lib/nginx/state/users.keyval;

    # 根据 URL 参数查找
    keyval $arg_user_id $user_role zone=users;

    # 根据 Host 查找
    keyval $host $backend_pool zone=backend_map;

    # 根据 URI 查找
    keyval $uri $cache_ttl zone=ttl_config;

    server {
        listen 80;

        location / {
            # 使用查找到的值
            proxy_pass http://$user_role;
        }
    }
}
```

### 3.2 匹配类型详解

#### string（精确匹配，默认）

```nginx
http {
    keyval_zone zone=exact:32k type=string;
    keyval $arg_key $value zone=exact;
}
```

- 查找键必须与存储键完全相同
- 适用于：用户角色映射、配置项查找

#### ip（IP/CIDR 匹配，1.17.1+）

```nginx
http {
    keyval_zone zone=ip_allow:256k type=ip;
    keyval $remote_addr $allowed zone=ip_allow;

    server {
        listen 80;

        location /api {
            if ($allowed = "") {
                return 403 "Access denied";
            }
            proxy_pass http://api_backend;
        }
    }
}
```

- 存储键可以是 IPv4/IPv6 地址或 CIDR
- 查找时匹配包含该地址的子网
- 适用于：IP 黑白名单、地理位置限流

**IP 类型数据示例**：

```json
{
    "192.168.1.0/24": "allow",
    "10.0.0.0/8": "allow",
    "192.168.1.100": "admin"
}
```

#### prefix（前缀匹配，1.17.5+）

```nginx
http {
    keyval_zone zone=routes:64k type=prefix;
    keyval $uri $handler zone=routes;

    server {
        location / {
            # /api/v1/users 匹配键 /api/v1
            proxy_pass http://$handler;
        }
    }
}
```

- 存储键必须是查找键的前缀
- 适用于：路由前缀匹配、版本控制

**前缀类型数据示例**：

```json
{
    "/api/v1": "backend_v1",
    "/api/v2": "backend_v2",
    "/admin": "admin_backend"
}
```

---

## 4. Stream Keyval 模块

### 4.1 指令详解

#### keyval_zone（Stream）

| 属性 | 说明 |
|------|------|
| **语法** | `keyval_zone zone=name:size [state=file] [timeout=time] [type=string\|ip\|prefix] [sync];` |
| **默认值** | — |
| **上下文** | stream |

与 HTTP 版本的语法完全相同，仅在 `stream` 上下文中使用。

#### keyval（Stream）

| 属性 | 说明 |
|------|------|
| **语法** | `keyval key $variable zone=name;` |
| **默认值** | — |
| **上下文** | stream |

### 4.2 配置示例

#### SSL SNI 路由

```nginx
stream {
    # 根据 SSL SNI 路由到不同后端
    keyval_zone zone=ssl_routes:64k state=/var/lib/nginx/state/ssl_routes.keyval;
    keyval $ssl_server_name $backend zone=ssl_routes;

    server {
        listen 443 ssl;
        proxy_pass $backend;

        ssl_certificate /etc/nginx/certs/default.crt;
        ssl_certificate_key /etc/nginx/certs/default.key;
    }
}
```

#### 动态 TCP 代理

```nginx
stream {
    # 根据目标端口路由
    keyval_zone zone=port_map:32k type=string;
    keyval $server_port $upstream zone=port_map;

    server {
        listen 10000-20000;
        proxy_pass $upstream;
    }
}
```

#### 客户端 IP 限流

```nginx
stream {
    # IP 黑名单
    keyval_zone zone=blocked_ips:256k type=ip;
    keyval $remote_addr $is_blocked zone=blocked_ips;

    server {
        listen 3306;

        # 通过 njs 或 map 实现阻断
        # 注意：stream 需要配合其他模块实现拒绝逻辑
        proxy_pass mysql_backend;
    }
}
```

---

## 5. API 管理接口

### 5.1 HTTP Keyvals API

#### 端点概览

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/{version}/http/keyvals/` | GET | 列出所有 HTTP keyval zones |
| `/api/{version}/http/keyvals/{zone}` | GET | 查询指定 zone 的键值对 |
| `/api/{version}/http/keyvals/{zone}` | POST | 添加键值对 |
| `/api/{version}/http/keyvals/{zone}` | PATCH | 修改或删除单个键 |
| `/api/{version}/http/keyvals/{zone}` | DELETE | 清空整个 zone |

> **注意**：API 版本当前为 `9`

#### 查询键值对

```bash
# 获取所有键值对
curl http://localhost:8080/api/9/http/keyvals/one

# 获取特定键
curl http://localhost:8080/api/9/http/keyvals/one?key=user1
```

**响应示例**：

```json
{
    "user1": "backend_a",
    "user2": "backend_b",
    "user3": {
        "value": "backend_c",
        "expire": 1699123456789
    }
}
```

#### 添加键值对（POST）

```bash
# 添加单个键值对
curl -X POST http://localhost:8080/api/9/http/keyvals/one \
    -H "Content-Type: application/json" \
    -d '{"user4": "backend_d"}'

# 添加带过期时间的键值对（毫秒）
curl -X POST http://localhost:8080/api/9/http/keyvals/one \
    -H "Content-Type: application/json" \
    -d '{
        "user5": {
            "value": "backend_e",
            "expire": 3600000
        }
    }'
```

**状态码**：
- `201` - 创建成功
- `409` - 键已存在
- `400` - 格式错误
- `413` - 请求体过大（超过 `client_body_buffer_size`）

#### 修改/删除键值对（PATCH）

```bash
# 修改键值
curl -X PATCH http://localhost:8080/api/9/http/keyvals/one \
    -H "Content-Type: application/json" \
    -d '{"user1": {"value": "new_backend", "expire": 7200000}}'

# 删除键（设置为 null）
curl -X PATCH http://localhost:8080/api/9/http/keyvals/one \
    -H "Content-Type: application/json" \
    -d '{"user1": null}'
```

**注意**：PATCH 一次只能更新一个键

#### 清空 Zone（DELETE）

```bash
# 删除 zone 中所有键值对
curl -X DELETE http://localhost:8080/api/9/http/keyvals/one
```

### 5.2 Stream Keyvals API

Stream keyval 使用相同的 API 格式，只是端点路径不同：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/{version}/stream/keyvals/` | GET | 列出所有 Stream keyval zones |
| `/api/{version}/stream/keyvals/{zone}` | GET | 查询指定 zone |
| `/api/{version}/stream/keyvals/{zone}` | POST | 添加键值对 |
| `/api/{version}/stream/keyvals/{zone}` | PATCH | 修改或删除键 |
| `/api/{version}/stream/keyvals/{zone}` | DELETE | 清空 zone |

**使用示例**：

```bash
# 添加 SSL 路由
curl -X POST http://localhost:8080/api/9/stream/keyvals/ssl_routes \
    -H "Content-Type: application/json" \
    -d '{"api.example.com": "192.168.1.10:8443"}'

# 查询
curl http://localhost:8080/api/9/stream/keyvals/ssl_routes
```

### 5.3 完整 API 配置示例

```nginx
http {
    # 定义 keyval zones
    keyval_zone zone=users:64k state=/var/lib/nginx/state/users.keyval timeout=1h;
    keyval_zone zone=routes:32k state=/var/lib/nginx/state/routes.keyval;
    keyval_zone zone=ip_blacklist:256k type=ip;

    # 使用 keyval
    keyval $arg_user $user_role zone=users;
    keyval $uri $backend zone=routes;
    keyval $remote_addr $blocked zone=ip_blacklist;

    # API 服务配置
    server {
        listen 8080;
        server_name localhost;

        location /api {
            # 启用 API 写权限
            api write=on;

            # 安全限制
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }
    }

    # 业务服务
    server {
        listen 80;
        server_name app.example.com;

        location / {
            # IP 黑名单检查
            if ($blocked = "blocked") {
                return 403 "IP blocked";
            }

            # 动态路由
            proxy_pass http://$backend;
        }
    }
}

stream {
    keyval_zone zone=ssl_routes:64k state=/var/lib/nginx/state/ssl_routes.keyval;
    keyval $ssl_server_name $backend zone=ssl_routes;

    server {
        listen 443 ssl;
        proxy_pass $backend;

        ssl_certificate /etc/nginx/certs/default.crt;
        ssl_certificate_key /etc/nginx/certs/default.key;
    }
}
```

---

## 6. 使用场景详解

### 6.1 动态 IP 黑名单

```nginx
http {
    # IP 类型 zone，支持 CIDR
    keyval_zone zone=blacklist:1m type=ip state=/var/lib/nginx/state/blacklist.keyval;
    keyval $remote_addr $blocked zone=blacklist;

    server {
        listen 80;

        location / {
            # 检查是否在黑名单
            if ($blocked = "blocked") {
                return 403 "Access denied";
            }

            proxy_pass http://backend;
        }
    }
}
```

**API 操作**：

```bash
# 封禁单个 IP
curl -X POST http://localhost:8080/api/9/http/keyvals/blacklist \
    -d '{"192.168.1.100": "blocked"}'

# 封禁 IP 段
curl -X POST http://localhost:8080/api/9/http/keyvals/blacklist \
    -d '{"10.0.0.0/8": "blocked"}'

# 解封
curl -X PATCH http://localhost:8080/api/9/http/keyvals/blacklist \
    -d '{"192.168.1.100": null}'
```

### 6.2 限流白名单

```nginx
http {
    # 限流白名单（这些 IP 不限流）
    keyval_zone zone=rate_whitelist:256k type=ip;
    keyval $remote_addr $rate_whitelisted zone=rate_whitelist;

    # 定义限流区域
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    server {
        listen 80;

        location /api {
            # 白名单跳过限流
            if ($rate_whitelisted = "whitelisted") {
                proxy_pass http://api_backend;
                break;
            }

            limit_req zone=api_limit burst=20 nodelay;
            proxy_pass http://api_backend;
        }
    }
}
```

### 6.3 动态路由映射

```nginx
http {
    keyval_zone zone=routes:64k type=prefix state=/var/lib/nginx/state/routes.keyval;
    keyval $uri $backend zone=routes;

    upstream backend_a {
        server 192.168.1.10:8080;
    }

    upstream backend_b {
        server 192.168.1.11:8080;
    }

    server {
        listen 80;

        location / {
            # 默认后端
            if ($backend = "") {
                set $backend "backend_a";
            }

            proxy_pass http://$backend;
        }
    }
}
```

**API 操作**：

```bash
# 设置路由规则
curl -X POST http://localhost:8080/api/9/http/keyvals/routes \
    -d '{
        "/api/v1": "backend_a",
        "/api/v2": "backend_b",
        "/admin": "backend_a"
    }'
```

### 6.4 A/B 测试动态分配

```nginx
http {
    keyval_zone zone=ab_test:32k state=/var/lib/nginx/state/ab_test.keyval;
    keyval $cookie_userid $ab_group zone=ab_test;

    upstream version_a {
        server 192.168.1.10:8080;
    }

    upstream version_b {
        server 192.168.1.11:8080;
    }

    server {
        listen 80;

        location / {
            # 未分配或指定为 a 的用户
            if ($ab_group = "a") {
                proxy_pass http://version_a;
                break;
            }

            # 指定为 b 的用户
            if ($ab_group = "b") {
                proxy_pass http://version_b;
                break;
            }

            # 新用户默认走版本 A
            proxy_pass http://version_a;
        }
    }
}
```

### 6.5 SSL 证书动态路由（Stream）

```nginx
stream {
    # 域名到后端的映射
    keyval_zone zone=ssl_routes:64k state=/var/lib/nginx/state/ssl_routes.keyval;
    keyval $ssl_server_name $backend zone=ssl_routes;

    server {
        listen 443 ssl;

        # 默认证书
        ssl_certificate /etc/nginx/certs/default.crt;
        ssl_certificate_key /etc/nginx/certs/default.key;

        proxy_pass $backend;
    }
}

http {
    # API 管理 Stream keyval
    server {
        listen 8080;

        location /api {
            api write=on;
        }
    }
}
```

---

## 7. 与 Lolly 项目的关系和建议

### 7.1 项目对比

[Lolly](https://github.com/xfy/lolly) 是一个使用 Go 语言编写的高性能 HTTP 服务器与反向代理。与 NGINX Keyval 模块相比：

| 特性 | NGINX Keyval | Lolly |
|------|--------------|-------|
| **动态配置** | 通过 API 实时更新 | 通过配置热重载（HUP 信号） |
| **键值存储** | 共享内存，API 管理 | 配置文件/YAML |
| **持久化** | state 文件自动持久化 | 配置文件持久化 |
| **匹配类型** | string、ip、prefix | 需自定义实现 |
| **商业限制** | NGINX Plus 专有功能 | 开源免费 |
| **集群同步** | 内置支持 | 需自行实现 |

### 7.2 Lolly 的动态配置建议

虽然 Lolly 当前不支持类似 Keyval 的动态键值存储，但可以通过以下方式实现类似功能：

#### 方案 1：配置热重载

Lolly 已支持 SIGHUP 信号触发配置重载：

```go
// 在配置中定义映射表
proxy:
  - path: "/api"
    dynamic_routes:
      - key: "user1"
        target: "http://backend1:8080"
      - key: "user2"
        target: "http://backend2:8080"
```

修改配置后执行：

```bash
kill -HUP <lolly_pid>
```

#### 方案 2：自定义中间件实现

可以在 Lolly 中实现类似 Keyval 的动态路由中间件：

```go
// internal/middleware/keyval/keyval.go
package keyval

import (
    "sync"
    "time"
)

type KeyvalStore struct {
    mu     sync.RWMutex
    data   map[string]Entry
    file   string
}

type Entry struct {
    Value   string
    Expires time.Time
}

func (s *KeyvalStore) Get(key string) (string, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    entry, ok := s.data[key]
    if !ok {
        return "", false
    }

    if !entry.Expires.IsZero() && time.Now().After(entry.Expires) {
        return "", false
    }

    return entry.Value, true
}

func (s *KeyvalStore) Set(key, value string, ttl time.Duration) {
    s.mu.Lock()
    defer s.mu.Unlock()

    entry := Entry{Value: value}
    if ttl > 0 {
        entry.Expires = time.Now().Add(ttl)
    }

    s.data[key] = entry
}
```

#### 方案 3：外部存储集成

建议 Lolly 集成外部键值存储：

- **Redis**：支持过期、持久化、集群
- **etcd**：支持监听变更、服务发现
- **Consul**：服务发现与健康检查

```go
// Redis 集成示例
import "github.com/redis/go-redis/v9"

type RedisKeyval struct {
    client *redis.Client
}

func (r *RedisKeyval) Get(ctx context.Context, key string) (string, error) {
    return r.client.Get(ctx, key).Result()
}

func (r *RedisKeyval) Set(ctx context.Context, key, value string, ttl time.Duration) error {
    return r.client.Set(ctx, key, value, ttl).Err()
}
```

### 7.3 Lolly 潜在增强功能

参考 NGINX Keyval 模块，建议 Lolly 可考虑实现：

1. **内置动态键值 API**
   - RESTful API 管理键值对
   - 支持内存存储与持久化
   - TTL 过期机制

2. **多种匹配类型**
   - 精确匹配
   - IP/CIDR 匹配（用于黑白名单）
   - 前缀匹配（用于路由）

3. **集群同步**
   - 基于 Raft 或 gossip 协议
   - 配置变更广播

4. **NGINX Plus 兼容 API**
   - 兼容 `/api/{version}/http/keyvals/` 接口
   - 便于迁移现有 NGINX Plus 用户

---

## 8. 最佳实践

### 8.1 内存大小规划

```nginx
# 估算每个键值对大小
# key: 平均 50 字节
# value: 平均 100 字节
# overhead: 约 50 字节
# 总计: 约 200 字节/键值对

# 10万键值对约需 20MB
keyval_zone zone=large:20m;

# 设置合理超时，避免内存无限增长
keyval_zone zone=with_ttl:32k timeout=1h;
```

### 8.2 持久化策略

```nginx
# 重要数据启用持久化
keyval_zone zone=critical:64k state=/var/lib/nginx/state/critical.keyval;

# 临时数据不持久化
keyval_zone zone=temp:32k timeout=5m;
```

### 8.3 安全建议

```nginx
http {
    # API 严格访问控制
    server {
        listen 8080;

        location /api {
            api write=on;

            # 只允许特定 IP
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;

            # 可选：添加基础认证
            auth_basic "API Access";
            auth_basic_user_file /etc/nginx/api.htpasswd;
        }
    }
}
```

### 8.4 监控与日志

```nginx
http {
    # 记录 keyval 相关请求
    log_format keyval '$remote_addr - $time_local '
                      'keyval_zone=$keyval_zone key=$key val=$value';

    server {
        location / {
            # 添加自定义头便于调试
            add_header X-Keyval-Value $user_role;

            proxy_pass http://backend;
        }
    }
}
```

### 8.5 集群部署注意事项

启用 `sync` 时的限制：

```nginx
http {
    # sync 需要 timeout 参数
    keyval_zone zone=shared:64k timeout=1h sync;

    # 注意：
    # 1. DELETE 操作只在目标节点立即生效
    # 2. 其他节点需等待 timeout 过期
    # 3. PATCH 删除（设为 null）同样受此限制
}
```

---

## 9. 完整配置示例

### 综合应用场景

```nginx
# nginx.conf

user nginx;
worker_processes auto;

events {
    worker_connections 4096;
}

http {
    # ========== Keyval Zones ==========

    # 用户角色映射（持久化）
    keyval_zone zone=user_roles:64k state=/var/lib/nginx/state/user_roles.keyval;
    keyval $arg_user $user_role zone=user_roles;

    # IP 黑名单（IP 类型，支持 CIDR）
    keyval_zone zone=ip_blacklist:1m type=ip state=/var/lib/nginx/state/blacklist.keyval;
    keyval $remote_addr $blocked zone=ip_blacklist;

    # 限流白名单
    keyval_zone zone=rate_whitelist:512k type=ip;
    keyval $remote_addr $whitelisted zone=rate_whitelist;

    # 路由映射（前缀匹配）
    keyval_zone zone=routes:128k type=prefix state=/var/lib/nginx/state/routes.keyval;
    keyval $uri $backend zone=routes;

    # 临时会话（5分钟过期）
    keyval_zone zone=sessions:32k timeout=5m;
    keyval $cookie_session $session_data zone=sessions;

    # ========== Rate Limit ==========
    limit_req_zone $binary_remote_addr zone=general:10m rate=100r/s;

    # ========== Upstreams ==========
    upstream backend_admin {
        server 192.168.1.10:8080;
    }

    upstream backend_api {
        server 192.168.1.11:8080;
        server 192.168.1.12:8080;
    }

    upstream backend_default {
        server 192.168.1.20:8080;
    }

    # ========== API Server ==========
    server {
        listen 127.0.0.1:8080;

        location /api {
            api write=on;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }
    }

    # ========== Main Server ==========
    server {
        listen 80;
        server_name app.example.com;

        # 安全头
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;

        location / {
            # 1. 检查 IP 黑名单
            if ($blocked = "blocked") {
                return 403 "Access denied";
            }

            # 2. 限流（白名单除外）
            if ($whitelisted = "") {
                limit_req zone=general burst=200 nodelay;
            }

            # 3. 根据路由映射选择后端
            if ($backend = "") {
                set $backend "default";
            }

            # 4. 根据用户角色选择后端
            if ($user_role = "admin") {
                set $backend "admin";
            }

            # 5. 代理到对应后端
            proxy_pass http://backend_$backend;

            # 传递 keyval 信息到后端
            proxy_set_header X-User-Role $user_role;
            proxy_set_header X-Session-Data $session_data;
        }
    }
}

stream {
    # SSL 证书动态路由
    keyval_zone zone=ssl_routes:64k state=/var/lib/nginx/state/ssl_routes.keyval;
    keyval $ssl_server_name $backend zone=ssl_routes;

    server {
        listen 443 ssl;

        ssl_certificate /etc/nginx/certs/default.crt;
        ssl_certificate_key /etc/nginx/certs/default.key;

        proxy_pass $backend;
        proxy_ssl on;
    }
}
```

---

## 10. 常见问题

### Q1: Keyval 数据在重启后会丢失吗？

**A**: 如果配置了 `state` 参数，数据会持久化到 JSON 文件，重启后自动加载。未配置 `state` 的数据会丢失。

### Q2: 如何备份 Keyval 数据？

**A**: 直接备份 state 文件即可：

```bash
cp /var/lib/nginx/state/*.keyval /backup/
```

### Q3: 集群同步有什么限制？

**A**: 启用 `sync` 后：
- 添加操作会同步到所有节点
- 删除操作只在目标节点立即生效，其他节点需等待 `timeout` 过期

### Q4: 可以手动编辑 state 文件吗？

**A**: 不建议。state 文件由 NGINX 自动管理，手动编辑可能导致数据损坏。

### Q5: 与 map 模块有什么区别？

**A**: 
- `map` 是静态配置，重启生效
- `keyval` 是动态存储，API 实时更新

### Q6: Stream 模块可以使用哪些变量作为 key？

**A**: Stream 上下文的可用变量包括：
- `$remote_addr` - 客户端地址
- `$remote_port` - 客户端端口
- `$server_addr` - 服务器地址
- `$server_port` - 服务器端口
- `$ssl_server_name` - SSL SNI 名称
- `$ssl_session_id` - SSL 会话 ID

---

## 参考链接

- [NGINX HTTP Keyval 模块官方文档](https://nginx.org/en/docs/http/ngx_http_keyval_module.html)
- [NGINX Stream Keyval 模块官方文档](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html)
- [NGINX HTTP API 模块官方文档](https://nginx.org/en/docs/http/ngx_http_api_module.html)
- [Lolly 项目 GitHub](https://github.com/xfy/lolly)