docs: 添加 nginx 高级主题文档 (Lua/安全/API网关/动态配置)

新增 5 篇深度文档：
- Lua 模块深度指南：OpenResty、ngx_lua、cosocket
- 安全深度指南：WAF、DDoS 防护、OWASP Top 10
- API 网关配置：路由设计、JWT 验证、限流配额
- 动态配置与服务发现：etcd/Consul、nginx-unit

Co-Authored-By: Claude <noreply@anthropic.com>

docs/README.md

@@ -31,6 +31,10 @@
 | 23 | [特殊功能模块](./23-nginx-special-modules.md) | WebDAV/图像过滤/FLV/MP4/HLS 流媒体/XSLT 转换 |
 | 24 | [核心与事件模块](./24-nginx-core-events.md) | worker_processes/events/epoll/kqueue/连接数计算 |
 | 25 | [内置变量速查表](./25-nginx-variables-reference.md) | HTTP/Stream/SSL/Upstream 变量完整列表（150+个） |
+| 26 | [Lua 模块深度指南](./26-nginx-lua-guide.md) | OpenResty、ngx_lua 指令、共享字典、cosocket API |
+| 27 | [安全深度指南](./27-nginx-security-deep-dive.md) | WAF/ModSecurity、DDoS 防护、OWASP Top 10、安全头部 |
+| 28 | [API 网关配置](./28-nginx-api-gateway.md) | API 路由设计、JWT 验证、限流配额、版本控制 |
+| 29 | [动态配置与服务发现](./29-nginx-dynamic-config.md) | 动态 upstream、etcd/Consul、dyups、nginx-unit |
 
 ---
 
@@ -63,6 +67,15 @@
 
 ### 扩展与第三方
 - [第三方扩展模块](./22-nginx-third-party-modules.md) - NJS, Lua, Brotli, RTMP 等
+- [Lua 模块深度指南](./26-nginx-lua-guide.md) - OpenResty、ngx_lua、cosocket
+
+### 安全深度
+- [安全与访问控制](./09-nginx-security.md) - 综合安全配置
+- [安全深度指南](./27-nginx-security-deep-dive.md) - WAF、DDoS、OWASP
+
+### API 与动态配置
+- [API 网关配置](./28-nginx-api-gateway.md) - API 路由、JWT、限流配额
+- [动态配置与服务发现](./29-nginx-dynamic-config.md) - 动态 upstream、etcd/Consul
 
 ### 参考手册
 - [内置变量速查表](./25-nginx-variables-reference.md) - 150+ 个变量完整列表

docs/nginx-docs-analysis.md

@@ -0,0 +1,288 @@
+# NGINX 文档完善建议
+
+基于对 nginx.org 官方文档的深度分析，对比 docs/ 目录下现有的 25 个文档，识别出以下可完善的部分。
+
+---
+
+## 一、缺失或需要新增的文档
+
+### 1. NGINX Lua 模块深度指南
+**优先级：高**
+
+现有 `22-nginx-third-party-modules.md` 对 NJS/Lua 有简要介绍，但 Lua 模块功能强大，值得独立文档。
+
+**建议内容：**
+- OpenResty 环境搭建
+- ngx_lua 核心指令（content_by_lua、access_by_lua、rewrite_by_lua）
+- Lua 共享字典（ngx.shared.DICT）
+- cosocket API（非阻塞网络 I/O）
+- 与 Redis/MySQL 集成
+- 性能优化技巧
+
+### 2. NGINX 作为 API 网关
+**优先级：中**
+
+现代架构中 nginx 常作为 API 网关使用。
+
+**建议内容：**
+- API 路由设计模式
+- 请求/响应转换
+- JWT 验证（通过 Lua 或 NJS）
+- 限流与配额管理
+- API 版本控制策略
+- OpenAPI/Swagger 集成
+
+### 3. NGINX 动态配置
+**优先级：中**
+
+现代部署需要动态配置能力。
+
+**建议内容：**
+- 动态 upstream（nginx-plus 或开源方案）
+- 使用 etcd/Consul 进行服务发现
+- dyups 模块使用
+- nginx-unit 简介
+- 动态 SSL 证书加载
+
+### 4. NGINX 安全最佳实践（增强版）
+**优先级：高**
+
+现有 `09-nginx-security.md` 内容良好，可扩展：
+
+**建议补充：**
+- Bot 检测与防护
+- WAF 配置深度指南（ModSecurity）
+- DDoS 防护策略
+- OWASP Top 10 防护
+- 安全响应头完整配置
+- CVE 历史漏洞与修复版本
+
+---
+
+## 二、现有文档可扩展的内容
+
+### 15-nginx-advanced-features.md
+**当前：** 仅 94 行，内容相对简略
+**建议扩展：**
+
+1. **调试与诊断**
+   - debug 日志级别
+   - debug_points 指令
+   - worker_debug_connection
+
+2. **错误处理**
+   - error_page 高级用法
+   - 自定义错误页面
+   - try_files 与 error_page 配合
+
+3. **请求拦截**
+   - post_action 指令
+   - 日志记录后操作
+
+### 16-nginx-internal-redirect.md
+**当前：** 119 行，内容较好
+**建议扩展：**
+
+1. **SSI（服务端包含）详解**
+   - SSI 指令列表
+   - 虚拟包含 vs 文件包含
+   - 条件执行
+
+2. **命名 location 深度解析**
+   - 命名 location 语法
+   - 与 error_page 配合
+   - 重定向链追踪
+
+### 17-nginx-mirror-slice.md
+**当前：** 143 行，内容较好
+**建议扩展：**
+
+1. **高级镜像场景**
+   - 条件镜像（基于请求头、路径）
+   - 镜像流量采样
+   - 镜像目标选择策略
+
+2. **slice 与缓存高级配置**
+   - 多级缓存配置
+   - 缓存预热策略
+   - 缓存失效策略
+
+### 19-nginx-http-modules-detail.md
+**当前：** 约 1200 行，内容丰富
+**建议补充：**
+
+1. **ngx_http_addition_module**
+   - before/after 内容追加
+   - 与 SSI 配合使用
+
+2. **ngx_http_sub_module 高级用法**
+   - 多规则替换
+   - 正则替换
+   - 变量替换
+
+---
+
+## 三、新增文档建议清单
+
+| 序号 | 文档名称 | 优先级 | 预计行数 |
+|------|----------|--------|----------|
+| 26 | nginx-lua-guide.md | 高 | 800+ |
+| 27 | nginx-api-gateway.md | 中 | 600+ |
+| 28 | nginx-dynamic-config.md | 中 | 500+ |
+| 29 | nginx-security-deep-dive.md | 高 | 700+ |
+| 30 | nginx-troubleshooting.md | 中 | 400+ |
+| 31 | nginx-observability.md | 中 | 500+ |
+
+---
+
+## 四、文档质量建议
+
+### 统一格式
+- 所有文档使用统一的标题层级
+- 配置示例添加语法高亮标记
+- 表格格式统一
+
+### 交叉引用
+- 添加相关文档链接
+- 引用官方文档链接
+
+### 版本标注
+- 功能版本要求标注
+- 已废弃功能标注
+
+---
+
+## 五、NGINX HTTP 模块深度分析（Agent 分析结果）
+
+### 5.1 HTTP 模块完整列表（按类别）
+
+#### 核心模块
+| 模块名称 | 功能描述 | 依赖关系 |
+|----------|----------|----------|
+| `ngx_http_core_module` | HTTP 核心功能 | 无（必需） |
+| `ngx_http_log_module` | 访问日志记录 | core |
+| `ngx_http_upstream_module` | 上游服务器负载均衡 | core |
+
+#### 请求处理与路由模块
+| 模块名称 | 功能描述 | 依赖关系 |
+|----------|----------|----------|
+| `ngx_http_rewrite_module` | URI 重写（支持正则） | core |
+| `ngx_http_proxy_module` | 反向代理 | upstream |
+| `ngx_http_fastcgi_module` | FastCGI 协议代理 | upstream |
+| `ngx_http_uwsgi_module` | uWSGI 协议代理 | upstream |
+| `ngx_http_scgi_module` | SCGI 协议代理 | upstream |
+
+#### 安全与访问控制模块
+| 模块名称 | 功能描述 | 依赖关系 |
+|----------|----------|----------|
+| `ngx_http_access_module` | IP 访问控制 | core |
+| `ngx_http_auth_basic_module` | HTTP 基本认证 | core |
+| `ngx_http_auth_request_module` | 子请求认证 | proxy |
+| `ngx_http_ssl_module` | SSL/TLS 支持 | core |
+| `ngx_http_limit_req_module` | 请求速率限制 | core |
+| `ngx_http_limit_conn_module` | 连接数限制 | core |
+| `ngx_http_realip_module` | 真实 IP 替换 | core |
+
+#### 压缩与优化模块
+| 模块名称 | 功能描述 | 依赖关系 |
+|----------|----------|----------|
+| `ngx_http_gzip_module` | GZIP 压缩 | core |
+| `ngx_http_gunzip_module` | GZIP 解压 | gzip |
+| `ngx_http_headers_module` | 响应头处理 | core |
+
+#### 上游负载均衡算法模块
+| 模块名称 | 功能描述 | 依赖关系 |
+|----------|----------|----------|
+| `ngx_http_upstream_hash_module` | 一致性哈希负载均衡 | upstream |
+| `ngx_http_upstream_ip_hash_module` | IP 哈希负载均衡 | upstream |
+| `ngx_http_upstream_least_conn_module` | 最少连接负载均衡 | upstream |
+| `ngx_http_upstream_keepalive_module` | 上游 keepalive 连接 | upstream |
+
+### 5.2 最常用的 15 个指令
+
+| 排名 | 指令 | 用途 |
+|------|------|------|
+| 1 | `listen` | 端口监听 |
+| 2 | `server_name` | 虚拟主机 |
+| 3 | `location` | 路由匹配 |
+| 4 | `root` | 根目录 |
+| 5 | `proxy_pass` | 代理目标 |
+| 6 | `try_files` | 文件尝试 |
+| 7 | `rewrite` | URL 重写 |
+| 8 | `return` | 返回响应 |
+| 9 | `index` | 索引文件 |
+| 10 | `error_page` | 错误页面 |
+| 11 | `client_max_body_size` | 上传限制 |
+| 12 | `keepalive_timeout` | 连接保持 |
+| 13 | `gzip` | 压缩开关 |
+| 14 | `ssl_certificate` | SSL 证书 |
+| 15 | `access_log` | 访问日志 |
+
+---
+
+## 六、NGINX Stream 模块深度分析（Agent 分析结果）
+
+### 6.1 Stream 核心模块指令
+
+| 指令 | 语法 | 上下文 | 说明 |
+|------|------|--------|------|
+| `stream` | `stream { ... }` | main | 定义 stream 配置块 |
+| `server` | `server { ... }` | stream | 定义虚拟服务器 |
+| `listen` | `listen address:port [options]` | server | 监听端口配置 |
+| `preread_buffer_size` | `preread_buffer_size size` | stream, server | 预读取缓冲区大小 |
+| `preread_timeout` | `preread_timeout timeout` | stream, server | 预读取超时时间 |
+
+### 6.2 Stream 子模块完整列表
+
+| 模块名称 | 功能描述 |
+|----------|----------|
+| **核心模块** | |
+| ngx_stream_core_module | Stream 核心功能 |
+| **代理模块** | |
+| ngx_stream_proxy_module | TCP/UDP 代理转发 |
+| ngx_stream_ssl_module | SSL/TLS 支持 |
+| ngx_stream_ssl_preread_module | SSL 预读取（SNI 路由） |
+| **上游模块** | |
+| ngx_stream_upstream_module | 上游服务器管理 |
+| ngx_stream_hash_module | 一致性哈希负载均衡 |
+| ngx_stream_least_conn_module | 最少连接负载均衡 |
+| ngx_stream_random_module | 随机负载均衡 |
+| **访问控制** | |
+| ngx_stream_access_module | 允许/拒绝访问控制 |
+| ngx_stream_limit_conn_module | 连接数限制 |
+| ngx_stream_geo_module | 基于 IP 的地理位置变量 |
+| ngx_stream_geoip_module | GeoIP 数据库支持 |
+| **日志与监控** | |
+| ngx_stream_log_module | 日志记录 |
+| ngx_stream_return_module | 返回指定值并关闭连接 |
+
+### 6.3 现有文档 10-nginx-stream-tcp-udp.md 对比
+
+现有文档已覆盖：
+- ✅ TCP/UDP 代理基础配置
+- ✅ 负载均衡算法
+- ✅ SSL 终止
+- ✅ PROXY 协议
+- ✅ 速率限制
+
+建议补充：
+- 🔧 健康检查详细配置（active health check）
+- 🔧 stream 日志格式自定义
+- 🔧 UDP 响应数配置（proxy_responses）
+- 🔧 SSL preread 模块（SNI 路由）
+
+---
+
+## 七、与 Lolly 项目的关系
+
+基于 docs/plan.md，Lolly 是一个类似 nginx 的 Go 实现。文档完善有助于：
+
+1. **功能对齐**：识别 nginx 功能，作为 Lolly 开发参考
+2. **配置翻译**：nginx 配置 → YAML 配置设计参考
+3. **测试用例**：文档中的配置示例可作为测试用例
+
+建议在 Lolly 开发过程中，同步更新 nginx 文档作为功能对照。
+
+---
+
+*生成时间：2026-04-03*