From ac36cb629f425d27f45707d2f75d8469f96d176c Mon Sep 17 00:00:00 2001 From: xfy Date: Fri, 3 Apr 2026 10:55:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20nginx=20=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E7=BF=BB=E8=AF=91=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 翻译 nginx grpc、uwsgi、高级特性、内部重定向、镜像切片、memcached 模块文档 - 添加模块大纲和更新提示文档 Co-Authored-By: Claude --- docs/14-nginx-grpc-uwsgi.md | 195 +++++++++++++++ docs/15-nginx-advanced-features.md | 95 +++++++ docs/16-nginx-internal-redirect.md | 118 +++++++++ docs/17-nginx-mirror-slice.md | 142 +++++++++++ docs/18-nginx-memcached.md | 151 +++++++++++ docs/nginx-modules-outline.md | 389 +++++++++++++++++++++++++++++ docs/update-prompts.md | 16 ++ 7 files changed, 1106 insertions(+) create mode 100644 docs/14-nginx-grpc-uwsgi.md create mode 100644 docs/15-nginx-advanced-features.md create mode 100644 docs/16-nginx-internal-redirect.md create mode 100644 docs/17-nginx-mirror-slice.md create mode 100644 docs/18-nginx-memcached.md create mode 100644 docs/nginx-modules-outline.md create mode 100644 docs/update-prompts.md diff --git a/docs/14-nginx-grpc-uwsgi.md b/docs/14-nginx-grpc-uwsgi.md new file mode 100644 index 0000000..03996a8 --- /dev/null +++ b/docs/14-nginx-grpc-uwsgi.md @@ -0,0 +1,195 @@ +# Nginx gRPC、uWSGI 与 SCGI 代理模块详解 + +## 1. gRPC 代理模块 (ngx_http_grpc_module) + +### 概述 +- gRPC 是 Google 开源的高性能 RPC 框架 +- 基于 HTTP/2 和 Protocol Buffers +- 支持双向流、多路复用 + +### 核心指令表格 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| grpc_pass | gRPC 服务器地址 | - | +| grpc_set_header | 设置请求头 | - | +| grpc_connect_timeout | 连接超时 | 60s | +| grpc_send_timeout | 发送超时 | 60s | +| grpc_read_timeout | 读取超时 | 60s | +| grpc_buffering | 缓冲开关 | on | +| grpc_buffer_size | 缓冲区大小 | 4k/8k | +| grpc_ssl_verify | SSL 验证 | off | +| grpc_ssl_server_name | SNI 支持 | off | + +### 配置示例 +```nginx +location /grpc/ { + grpc_pass grpc://backend:50051; + grpc_set_header X-Real-IP $remote_addr; +} +``` + +### 与 HTTP 代理对比 +- 必须使用 HTTP/2 +- 二进制协议 +- 原生双向流 + +--- + +## 2. uWSGI 代理模块 (ngx_http_uwsgi_module) + +### 概述 +- 专为 Python/WSGI 应用设计 +- 二进制协议，性能优于 FastCGI + +### 核心指令表格 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| uwsgi_pass | uWSGI 服务器地址 | - | +| uwsgi_param | 传递参数 | - | +| uwsgi_modifier1 | 数据包修饰符1 | 0 | +| uwsgi_modifier2 | 数据包修饰符2 | 0 | +| uwsgi_connect_timeout | 连接超时 | 60s | +| uwsgi_read_timeout | 读取超时 | 60s | +| uwsgi_buffer_size | 缓冲区大小 | 4k/8k | + +### Python 应用配置示例 +```nginx +location / { + include uwsgi_params; + uwsgi_pass unix:/tmp/uwsgi.sock; + uwsgi_param UWSGI_PYHOME /var/www/venv; +} +``` + +### 与 FastCGI 对比 +| 特性 | uWSGI | FastCGI | +|------|-------|---------| +| 协议类型 | 二进制 | 二进制 | +| Python 支持 | 原生优化 | 需适配 | +| 性能 | 更高 | 较高 | +| 配置复杂度 | 简单 | 复杂 | +| 多语言支持 | 通用 | PHP 优先 | + +--- + +## 3. SCGI 代理模块 (ngx_http_scgi_module) + +### 概述 +- 简单通用的 CGI 协议 +- 纯文本协议头 + +### 核心指令 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| scgi_pass | SCGI 服务器地址 | - | +| scgi_param | 传递参数 | - | +| scgi_connect_timeout | 连接超时 | 60s | +| scgi_read_timeout | 读取超时 | 60s | +| scgi_buffer_size | 缓冲区大小 | 4k/8k | +| scgi_hide_header | 隐藏响应头 | - | +| scgi_pass_header | 透传响应头 | - | + +### 配置示例 +```nginx +location /scgi/ { + include scgi_params; + scgi_pass 127.0.0.1:4000; + scgi_param SCRIPT_FILENAME /var/www/app.py; +} +``` + +### 最佳实践 +- 适合简单的 CGI 应用 +- 调试友好（纯文本头） +- 性能略低于 uWSGI/FastCGI + +--- + +## 4. 三种代理对比 + +| 特性 | gRPC | uWSGI | SCGI | FastCGI | +|------|------|-------|------|---------| +| 协议 | HTTP/2 + Protobuf | 二进制 | 纯文本 | 二进制 | +| 语言支持 | 多语言 | Python 优先 | 通用 | PHP 优先 | +| 性能 | 最高 | 高 | 中 | 高 | +| 双向流 | ✅ | ❌ | ❌ | ❌ | +| 多路复用 | ✅ | ❌ | ❌ | ✅ | +| 配置复杂度 | 中等 | 低 | 低 | 高 | +| 适用场景 | 微服务 | Python Web | 简单 CGI | PHP Web | + +--- + +## 5. 完整配置示例 + +### gRPC 微服务代理 +```nginx +upstream grpc_backend { + server grpc1:50051; + server grpc2:50051; +} + +server { + listen 1443 ssl http2; + + ssl_certificate /etc/nginx/ssl/server.crt; + ssl_certificate_key /etc/nginx/ssl/server.key; + + location /api/ { + grpc_pass grpc://grpc_backend; + grpc_set_header Host $host; + grpc_set_header X-Real-IP $remote_addr; + grpc_connect_timeout 30s; + grpc_read_timeout 30s; + } +} +``` + +### Django 应用 (uWSGI) +```nginx +server { + listen 80; + server_name django.example.com; + + location / { + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app.sock; + uwsgi_read_timeout 300s; + } + + location /static/ { + alias /var/www/django/static/; + } +} +``` + +### SCGI 通用应用 +```nginx +server { + listen 80; + server_name scgi.example.com; + + location / { + include scgi_params; + scgi_pass 127.0.0.1:4000; + scgi_param PATH_INFO $fastcgi_script_name; + } +} +``` + +--- + +## 6. 性能优化建议 + +### gRPC 优化 +- 启用连接池（keepalive） +- 合理设置 HTTP/2 初始窗口大小 +- 使用 SSL 会话缓存 + +### uWSGI 优化 +- 使用 Unix Socket 而非 TCP（同机部署） +- 启用缓冲减少后端压力 +- 合理设置工作进程数 + +### SCGI 优化 +- 仅用于简单场景 +- 考虑升级到 uWSGI 或 FastCGI 以获得更好性能 diff --git a/docs/15-nginx-advanced-features.md b/docs/15-nginx-advanced-features.md new file mode 100644 index 0000000..8c03c22 --- /dev/null +++ b/docs/15-nginx-advanced-features.md @@ -0,0 +1,95 @@ +# Nginx 高级特性 + +## 1. 动态模块管理 + +### load_module 指令 +- 语法：`load_module file;` +- 上下文：main（顶层） +- 示例：`load_module modules/ngx_http_geoip_module.so;` + +### 静态编译 vs 动态加载 +| 特性 | 静态模块 | 动态模块 | +|------|----------|----------| +| 编译方式 | 编译进二进制 | 独立 .so 文件 | +| 添加/移除 | 需重新编译 | 修改配置即可 | +| 内存占用 | 始终占用 | 按需加载 | + +### 编译动态模块 +```bash +./configure --with-compat --add-dynamic-module=/path/to/module +make modules +``` + +### 配置示例 +```nginx +load_module modules/ngx_http_geoip_module.so; +load_module modules/ngx_stream_module.so; +``` + +## 2. 线程池与异步 I/O + +### thread_pool 指令 +```nginx +thread_pool default threads=32 max_queue=65536; +thread_pool fast threads=64 max_queue=131072; +``` + +### aio 指令选项 +| 值 | 说明 | +|----|------| +| off | 禁用 AIO | +| on | 内核 AIO | +| threads | 默认线程池 | +| threads=pool | 指定线程池 | + +### 大文件优化配置 +```nginx +location /videos/ { + sendfile on; + aio threads=fast; + directio 4m; + output_buffers 2 1m; +} +``` + +### 性能影响 +- 小文件：无显著提升 +- 大文件：2-10x 提升 +- 高并发：5-20x 提升 + +## 3. 开放文件缓存 (open_file_cache) + +### 指令详解 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| open_file_cache | 缓存配置 | - | +| open_file_cache_valid | 有效期 | 60s | +| open_file_cache_min_uses | 最小访问次数 | 1 | +| open_file_cache_errors | 缓存错误 | off | + +### 缓存内容 +- 文件描述符 +- 文件大小 +- 修改时间 +- 文件存在性 + +### 配置示例 +```nginx +open_file_cache max=10000 inactive=60s; +open_file_cache_valid 30s; +open_file_cache_min_uses 2; +open_file_cache_errors on; +``` + +### 配置建议矩阵 +| 场景 | max | inactive | valid | +|------|-----|----------|-------| +| 高流量 CDN | 50000+ | 60s | 30s | +| 企业网站 | 10000 | 60s | 30s | +| 下载服务 | 5000 | 300s | 60s | + +## 4. 最佳实践 + +- 核心模块静态编译，可选模块动态加载 +- 线程数设置为 CPU 核心数 2-4 倍 +- open_file_cache max 值为总文件数 1.5-2 倍 diff --git a/docs/16-nginx-internal-redirect.md b/docs/16-nginx-internal-redirect.md new file mode 100644 index 0000000..2ce44f1 --- /dev/null +++ b/docs/16-nginx-internal-redirect.md @@ -0,0 +1,118 @@ +## 1. internal 指令 + +### 概述 +- 标记 location 为内部专用 +- 外部请求返回 404 + +### 内部请求触发方式 +| 方式 | 说明 | +|------|------| +| X-Accel-Redirect | 上游响应头触发 | +| error_page | 错误页面重定向 | +| rewrite ... internal | 重写内部跳转 | +| SSI 包含 | 服务端包含 | + +### 配置示例 +```nginx +location /internal/ { + internal; + alias /data/protected/; +} +``` + +## 2. X-Accel-Redirect 响应头 + +### 工作原理 +1. 客户端请求 → nginx → 应用服务器 +2. 应用服务器验证权限 +3. 返回 X-Accel-Redirect 头 +4. nginx 内部重定向到受保护文件 +5. 文件直接传输给客户端 + +### 文件下载授权示例 +```nginx +# 下载入口 +location /download/ { + proxy_pass http://backend; + proxy_hide_header X-Accel-Redirect; +} + +# 受保护文件 +location /internal/files/ { + internal; + alias /var/www/private/; + limit_rate 500k; +} +``` + +### 应用服务器代码（Python 示例） +```python +@app.route('/download/') +def download(file_id): + if not user.has_permission(file_id): + return "无权限", 403 + response.headers['X-Accel-Redirect'] = f'/internal/files/{file_id}' + return response +``` + +## 3. X-Accel-* 系列响应头 + +| 响应头 | 功能 | 示例值 | +|--------|------|--------| +| X-Accel-Redirect | 内部重定向路径 | /internal/files/report.pdf | +| X-Accel-Expires | 缓存过期时间(秒) | 3600 | +| X-Accel-Limit-Rate | 限速(字节/秒) | 102400 | +| X-Accel-Buffering | 缓冲控制 | yes/no | +| X-Accel-Charset | 字符集 | utf-8 | + +### VIP 用户不限速示例 +```python +if user.is_vip(): + response.headers['X-Accel-Limit-Rate'] = '0' # 不限速 +else: + response.headers['X-Accel-Limit-Rate'] = '512000' # 500KB/s +``` + +## 4. 安全注意事项 + +### 必须标记 internal +```nginx +# 错误：外部可直接访问 +location /protected/ { + alias /data/secret/; +} + +# 正确：仅内部访问 +location /internal/protected/ { + internal; + alias /data/secret/; +} +``` + +### 路径验证 +- 后端必须验证路径合法性 +- 防止目录遍历攻击 + +### 完整配置示例 +```nginx +server { + location /download/ { + proxy_pass http://backend; + proxy_set_header X-Real-IP $remote_addr; + } + + location /internal/premium/ { + internal; + alias /var/www/premium/; + sendfile on; + limit_rate_after 1m; + limit_rate 1m; + } + + location /internal/standard/ { + internal; + alias /var/www/standard/; + limit_rate 500k; + } +} +``` diff --git a/docs/17-nginx-mirror-slice.md b/docs/17-nginx-mirror-slice.md new file mode 100644 index 0000000..f6fe654 --- /dev/null +++ b/docs/17-nginx-mirror-slice.md @@ -0,0 +1,142 @@ +## 1. 请求镜像模块 (ngx_http_mirror_module) + +### 概述 +- 版本要求：1.13.4+ +- 实时流量复制到测试环境 +- 不影响原请求响应 + +### 核心指令 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| mirror | 镜像目标 location | off | +| mirror_request_body | 是否镜像请求体 | on | + +### 基础配置示例 +```nginx +server { + location / { + proxy_pass http://production_backend; + mirror /mirror; + } + + location = /mirror { + internal; + proxy_pass http://test_backend$request_uri; + } +} +``` + +### 多目标镜像 +```nginx +location / { + proxy_pass http://production; + mirror /mirror_test; + mirror /mirror_staging; +} +``` + +### 条件镜像 +```nginx +map $http_x_mirror $do_mirror { + default ""; + "true" "/mirror"; +} + +server { + location / { + proxy_pass http://production; + mirror $do_mirror; + } +} +``` + +### 应用场景 +- 灰度测试验证 +- 压力测试（真实流量） +- 安全审计 +- A/B 测试对比 + +### 最佳实践 +- 使用 internal 标记镜像目标 +- 设置短超时 `proxy_read_timeout 1s` +- 大文件上传关闭 `mirror_request_body off` + +## 2. 大文件分片模块 (ngx_http_slice_module) + +### 概述 +- 版本要求：1.9.8+ +- 将大文件分割成小块请求 +- 支持 Range 请求高效缓存 + +### 核心指令 +| 指令 | 说明 | 默认值 | +|------|------|--------| +| slice | 分片大小 | 0（禁用）| + +### 内置变量 +| 变量 | 说明 | +|------|------| +| $slice_range | 当前分片范围（bytes=0-1048575）| + +### 配置示例 +```nginx +location /videos/ { + slice 1m; + proxy_set_header Range $slice_range; + proxy_cache my_cache; + proxy_cache_key $uri$slice_range; + proxy_cache_valid 200 206 1d; + proxy_pass http://video_backend; +} +``` + +### 工作原理 +``` +客户端请求 Range: bytes=0-2M + ↓ +nginx 分割为： + - Range: bytes=0-1M (分片1) + - Range: bytes=1M-2M (分片2) + ↓ +每个分片独立缓存 +``` + +### 应用场景 +- 视频流媒体（边下边播） +- 大文件下载（断点续传） +- CDN 源站 + +### 最佳实践 +- 视频文件：1-2MB 分片 +- 大文件下载：5-10MB 分片 +- 必须设置 `proxy_set_header Range $slice_range` +- 缓存键必须包含 `$slice_range` +- 缓存 206 状态码 + +## 3. 综合配置示例 + +```nginx +proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=media:10m max_size=10g; + +server { + # 生产服务 + location /videos/ { + slice 2m; + proxy_set_header Range $slice_range; + proxy_cache media; + proxy_cache_key $uri$slice_range; + proxy_cache_valid 200 206 7d; + proxy_pass http://video_backend; + + # 同时镜像到测试环境 + mirror /mirror; + } + + # 镜像目标 + location = /mirror { + internal; + proxy_pass http://test_video_backend$request_uri; + proxy_read_timeout 1s; + } +} +``` diff --git a/docs/18-nginx-memcached.md b/docs/18-nginx-memcached.md new file mode 100644 index 0000000..2d055ea --- /dev/null +++ b/docs/18-nginx-memcached.md @@ -0,0 +1,151 @@ +## 1. 模块概述 + +### ngx_http_memcached_module +- 与 Memcached 缓存服务器交互 +- 支持从 Memcached 读取数据 +- 适合缓存动态内容 + +### 特性 +- 通过 key 从 Memcached 读取 +- 与 nginx 变量系统集成 +- 支持 upstream 负载均衡 + +## 2. 核心指令 + +| 指令 | 说明 | 默认值 | +|------|------|--------| +| memcached_pass | Memcached 服务器地址 | - | +| memcached_bind | 本地绑定地址 | - | +| memcached_connect_timeout | 连接超时 | 60s | +| memcached_read_timeout | 读取超时 | 60s | +| memcached_send_timeout | 发送超时 | 60s | +| memcached_buffer_size | 缓冲区大小 | 4k/8k | +| memcached_next_upstream | 失败转发条件 | error timeout | +| memcached_gzip_flag | gzip 标志位 | - | + +## 3. 关键变量 + +| 变量 | 说明 | +|------|------| +| $memcached_key | 缓存键（必须设置）| +| $memcached_expires | 过期时间（秒）| + +## 4. 配置示例 + +### 基础配置 +```nginx +location /cache/ { + set $memcached_key "$uri?$args"; + memcached_pass 127.0.0.1:11211; + + # 缓存未命中回源 + error_page 404 502 504 = @fallback; +} + +location @fallback { + proxy_pass http://backend; +} +``` + +### 多服务器负载均衡 +```nginx +upstream memcached_backend { + server 192.168.1.10:11211 weight=5; + server 192.168.1.11:11211; + keepalive 32; +} + +server { + location /api/ { + set $memcached_key "api:$uri:$args"; + memcached_pass memcached_backend; + error_page 404 = @api_backend; + } +} +``` + +### API 缓存示例 +```nginx +location /user/ { + # 从缓存读取用户数据 + set $memcached_key "user:$arg_id"; + memcached_pass 127.0.0.1:11211; + memcached_connect_timeout 100ms; + memcached_read_timeout 200ms; + + # 未命中时查询数据库 + error_page 404 = @database; +} + +location @database { + proxy_pass http://app_server; + + # 响应后写入缓存（需应用逻辑） + # 或使用 srcache-nginx-module +} +``` + +## 5. 与 proxy_cache 对比 + +| 特性 | memcached_module | proxy_cache | +|------|------------------|-------------| +| 数据来源 | Memcached 服务 | 本地磁盘 | +| 缓存方式 | 主动读取 | 被动缓存 | +| 预填充 | 支持 | 不支持 | +| 分布式 | 原生支持 | 单机 | +| 写入支持 | 需外部工具 | 自动 | + +## 6. 应用场景 + +| 场景 | 说明 | +|------|------| +| API 缓存 | 缓存 JSON 响应 | +| Session 存储 | 分布式 session 读取 | +| 页面片段缓存 | 头部、侧边栏组件 | +| 临时数据 | 高频读取的低频变化数据 | + +## 7. 最佳实践 + +### 缓存键设计 +```nginx +# API 请求：包含完整路径和参数 +set $memcached_key "api:$request_uri"; + +# 用户数据：包含用户 ID +set $memcached_key "user:$cookie_user_id"; + +# 页面片段：包含版本号 +set $memcached_key "fragment:$uri:v2"; +``` + +### 超时设置 +```nginx +# 快速失败，避免阻塞 +memcached_connect_timeout 100ms; +memcached_read_timeout 200ms; +``` + +### 错误处理 +```nginx +# 始终配置回源 +error_page 404 502 504 = @fallback; + +# 多服务器故障转移 +memcached_next_upstream error timeout invalid_response; +``` + +### 连接复用 +```nginx +upstream memcached_servers { + server 10.0.0.1:11211; + server 10.0.0.2:11211; + keepalive 64; # 保持连接池 +} +``` + +## 8. 注意事项 + +- 模块只支持读取，不支持写入 +- 写入缓存需要应用服务器或第三方模块 +- 建议使用短超时（100-500ms） +- 使用 upstream + keepalive 提高性能 diff --git a/docs/nginx-modules-outline.md b/docs/nginx-modules-outline.md new file mode 100644 index 0000000..8dd16df --- /dev/null +++ b/docs/nginx-modules-outline.md @@ -0,0 +1,389 @@ +# nginx 模块文档大纲 + +## 1. ngx_http_grpc_module (gRPC 代理) + +### 1.1 模块概述 + +ngx_http_grpc_module 模块用于将请求代理到 gRPC 服务器。该模块自 nginx 1.13.10 版本开始提供，支持 HTTP/2 协议上的 gRPC 通信。 + +**主要特性：** +- 支持 gRPC-over-HTTP/2 协议 +- 支持 gRPC 服务端流、客户端流和双向流 +- 支持 SSL/TLS 加密连接 +- 支持负载均衡和健康检查 +- 支持请求头自定义和超时配置 + +### 1.2 核心指令表格 + +| 指令 | 语法 | 说明 | 默认值 | 上下文 | +|------|------|------|--------|--------| +| grpc_pass | `grpc_pass address;` | 设置 gRPC 服务器地址 | - | location, if in location | +| grpc_set_header | `grpc_set_header field value;` | 设置传递给 gRPC 服务器的请求头 | - | http, server, location | +| grpc_hide_header | `grpc_hide_header field;` | 隐藏 gRPC 响应中的指定头字段 | - | http, server, location | +| grpc_pass_header | `grpc_pass_header field;` | 允许传递隐藏的头字段 | - | http, server, location | +| grpc_buffer_size | `grpc_buffer_size size;` | 设置读取响应的缓冲区大小 | 4k/8k | http, server, location | +| grpc_buffering | `grpc_buffering on/off;` | 启用/禁用响应缓冲 | on | http, server, location | +| grpc_connect_timeout | `grpc_connect_timeout time;` | 设置与服务器建立连接的超时 | 60s | http, server, location | +| grpc_send_timeout | `grpc_send_timeout time;` | 设置向服务器发送请求的超时 | 60s | http, server, location | +| grpc_read_timeout | `grpc_read_timeout time;` | 设置读取服务器响应的超时 | 60s | http, server, location | +| grpc_socket_keepalive | `grpc_socket_keepalive on/off;` | 启用 TCP keepalive | off | http, server, location | +| grpc_ssl_certificate | `grpc_ssl_certificate file;` | 指定客户端 SSL 证书 | - | http, server | +| grpc_ssl_certificate_key | `grpc_ssl_certificate_key file;` | 指定客户端 SSL 证书密钥 | - | http, server | +| grpc_ssl_ciphers | `grpc_ssl_ciphers ciphers;` | 指定 SSL 加密算法 | DEFAULT | http, server | +| grpc_ssl_protocols | `grpc_ssl_protocols protocols;` | 指定 SSL 协议版本 | TLSv1 TLSv1.1 TLSv1.2 | http, server | +| grpc_ssl_verify | `grpc_ssl_verify on/off;` | 启用服务器证书验证 | off | http, server | + +### 1.3 配置示例 + +**基本配置：** +```nginx +location / { + grpc_pass grpc://localhost:50051; +} +``` + +**带 SSL 的配置：** +```nginx +location / { + grpc_pass grpcs://grpc.example.com:443; + grpc_ssl_certificate /etc/nginx/client.crt; + grpc_ssl_certificate_key /etc/nginx/client.key; + grpc_ssl_verify on; + grpc_ssl_trusted_certificate /etc/nginx/ca.crt; +} +``` + +**自定义请求头：** +```nginx +location / { + grpc_set_header Host $host; + grpc_set_header X-Real-IP $remote_addr; + grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + grpc_set_header X-Forwarded-Proto $scheme; + grpc_pass grpc://localhost:50051; +} +``` + +**超时和缓冲配置：** +```nginx +location / { + grpc_pass grpc://localhost:50051; + grpc_connect_timeout 5s; + grpc_send_timeout 10s; + grpc_read_timeout 30s; + grpc_buffering off; + grpc_buffer_size 16k; +} +``` + +**负载均衡配置：** +```nginx +upstream grpc_backend { + server 127.0.0.1:50051 weight=5; + server 127.0.0.1:50052; + server 127.0.0.1:50053 backup; + keepalive 32; +} + +location / { + grpc_pass grpc://grpc_backend; + grpc_socket_keepalive on; +} +``` + +### 1.4 与普通 HTTP 代理的区别 + +| 特性 | gRPC 代理 | 普通 HTTP 代理 (proxy_pass) | +|------|-----------|------------------------------| +| 协议 | HTTP/2 必须 | HTTP/1.0, HTTP/1.1, HTTP/2 | +| 传输 | 二进制协议 (Protocol Buffers) | 文本协议 | +| 流支持 | 原生支持双向流 | 需要特殊配置 (chunked) | +| 连接复用 | 多路复用 (Multiplexing) | 连接池 | +| 头部传递 | 使用 grpc_set_header | 使用 proxy_set_header | +| 错误处理 | gRPC 状态码 | HTTP 状态码 | + +### 1.5 应用场景 + +1. **微服务架构网关**：作为 gRPC 服务的统一入口 +2. **SSL/TLS 终止**：对外提供 HTTPS，内部使用明文 gRPC +3. **负载均衡**：在多个 gRPC 服务实例间分发请求 +4. **A/B 测试**：基于路由规则将流量导向不同版本的服务 +5. **流量监控**：收集 gRPC 调用指标和日志 + +--- + +## 2. ngx_http_uwsgi_module (uWSGI 代理) + +### 2.1 模块概述 + +ngx_http_uwsgi_module 模块用于将请求代理到 uwsgi 协议服务器，主要用于 Python WSGI 应用程序（如 Django、Flask）的部署。 + +**主要特性：** +- 专为 Python WSGI 应用设计 +- 使用 uwsgi 协议（比 HTTP/FastCGI 更高效） +- 支持 Unix 域套接字和 TCP 套接字 +- 支持参数传递和环境变量设置 +- 支持缓冲、缓存和超时配置 + +### 2.2 核心指令表格 + +| 指令 | 语法 | 说明 | 默认值 | 上下文 | +|------|------|------|--------|--------| +| uwsgi_pass | `uwsgi_pass address;` | 设置 uwsgi 服务器地址 | - | location, if in location | +| uwsgi_param | `uwsgi_param parameter value [if_not_empty];` | 设置传递给 uWSGI 的参数 | - | http, server, location | +| uwsgi_modifier1 | `uwsgi_modifier1 number;` | 设置 uWSGI 数据包修饰符1 | 0 | http, server, location | +| uwsgi_modifier2 | `uwsgi_modifier2 number;` | 设置 uWSGI 数据包修饰符2 | 0 | http, server, location | +| uwsgi_bind | `uwsgi_bind address [transparent];` | 绑定到特定地址 | - | http, server, location | +| uwsgi_buffering | `uwsgi_buffering on/off;` | 启用/禁用响应缓冲 | on | http, server, location | +| uwsgi_buffer_size | `uwsgi_buffer_size size;` | 设置响应缓冲区大小 | 4k/8k | http, server, location | +| uwsgi_buffers | `uwsgi_buffers number size;` | 设置缓冲区数量和大小 | 8 4k/8k | http, server, location | +| uwsgi_busy_buffers_size | `uwsgi_busy_buffers_size size;` | 设置忙缓冲区大小 | 8k/16k | http, server, location | +| uwsgi_cache | `uwsgi_cache zone;` | 启用响应缓存 | - | http, server, location | +| uwsgi_cache_key | `uwsgi_cache_key string;` | 设置缓存键 | - | http, server, location | +| uwsgi_cache_valid | `uwsgi_cache_valid time;` | 设置缓存有效期 | - | http, server, location | +| uwsgi_connect_timeout | `uwsgi_connect_timeout time;` | 连接超时 | 60s | http, server, location | +| uwsgi_send_timeout | `uwsgi_send_timeout time;` | 发送超时 | 60s | http, server, location | +| uwsgi_read_timeout | `uwsgi_read_timeout time;` | 读取超时 | 60s | http, server, location | +| uwsgi_hide_header | `uwsgi_hide_header field;` | 隐藏响应头 | - | http, server, location | +| uwsgi_pass_header | `uwsgi_pass_header field;` | 允许传递隐藏头 | - | http, server, location | +| uwsgi_ignore_client_abort | `uwsgi_ignore_client_abort on/off;` | 忽略客户端中止 | off | http, server, location | +| uwsgi_intercept_errors | `uwsgi_intercept_errors on/off;` | 拦截错误码 | off | http, server, location | + +### 2.3 配置示例 + +**基本 Django/Flask 配置：** +```nginx +location / { + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app.sock; +} +``` + +**TCP 套接字配置：** +```nginx +location / { + include uwsgi_params; + uwsgi_pass 127.0.0.1:3031; +} +``` + +**自定义参数：** +```nginx +location / { + uwsgi_param SCRIPT_NAME /myapp; + uwsgi_param PATH_INFO $1; + uwsgi_param QUERY_STRING $query_string; + uwsgi_param REQUEST_METHOD $request_method; + uwsgi_param CONTENT_TYPE $content_type; + uwsgi_param CONTENT_LENGTH $content_length; + uwsgi_param REQUEST_URI $request_uri; + uwsgi_param DOCUMENT_ROOT $document_root; + uwsgi_param SERVER_PROTOCOL $server_protocol; + uwsgi_param HTTPS $https if_not_empty; + uwsgi_param REMOTE_ADDR $remote_addr; + uwsgi_param REMOTE_PORT $remote_port; + uwsgi_param SERVER_PORT $server_port; + uwsgi_param SERVER_NAME $server_name; + uwsgi_pass unix:/run/uwsgi/app.sock; +} +``` + +**带缓存的配置：** +```nginx +http { + uwsgi_cache_path /var/cache/nginx/uwsgi levels=1:2 keys_zone=uwsgi:10m max_size=1g; + + server { + location / { + uwsgi_cache uwsgi; + uwsgi_cache_key $host$request_uri; + uwsgi_cache_valid 200 10m; + uwsgi_cache_valid 404 1m; + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app.sock; + } + } +} +``` + +**负载均衡配置：** +```nginx +upstream uwsgi_backend { + server 127.0.0.1:3031 weight=5; + server 127.0.0.1:3032; + server 127.0.0.1:3033 backup; + keepalive 32; +} + +location / { + include uwsgi_params; + uwsgi_pass uwsgi_backend; +} +``` + +### 2.4 与 FastCGI 的对比 + +| 特性 | uWSGI | FastCGI | +|------|-------|---------| +| 设计目标 | Python WSGI 专用 | 通用语言接口 | +| 协议开销 | 更低（二进制协议） | 较高（文本协议）| +| 性能 | 更高 | 较低 | +| 配置复杂度 | 简单 | 较复杂 | +| 语言支持 | 主要为 Python | PHP、Perl、Ruby 等 | +| 功能扩展 | 丰富的插件系统 | 有限 | +| 进程管理 | 内置多种模式 | 依赖外部管理器 | + +### 2.5 应用场景 + +1. **Django 应用部署**：高性能 Python Web 框架部署 +2. **Flask 应用部署**：轻量级 Python Web 框架部署 +3. **Python API 服务**：RESTful API 后端服务 +4. **机器学习模型服务**：部署 ML 模型推理服务 +5. **数据科学应用**：Jupyter、Streamlit 等应用托管 + +--- + +## 3. ngx_http_scgi_module (SCGI 代理) + +### 3.1 模块概述 + +ngx_http_scgi_module 模块用于将请求代理到 SCGI（Simple Common Gateway Interface）服务器。SCGI 是一种简化版的 CGI 协议，旨在提供比传统 CGI 更好的性能。 + +**主要特性：** +- 简化的 CGI 协议实现 +- 比传统 CGI 更快的性能（保持持久连接） +- 支持 Unix 域套接字和 TCP 套接字 +- 支持参数传递和环境变量设置 +- 轻量级，适合小型项目 + +### 3.2 核心指令表格 + +| 指令 | 语法 | 说明 | 默认值 | 上下文 | +|------|------|------|--------|--------| +| scgi_pass | `scgi_pass address;` | 设置 SCGI 服务器地址 | - | location, if in location | +| scgi_param | `scgi_param parameter value [if_not_empty];` | 设置传递给 SCGI 的参数 | - | http, server, location | +| scgi_bind | `scgi_bind address [transparent];` | 绑定到特定地址 | - | http, server, location | +| scgi_buffering | `scgi_buffering on/off;` | 启用/禁用响应缓冲 | on | http, server, location | +| scgi_buffer_size | `scgi_buffer_size size;` | 设置响应缓冲区大小 | 4k/8k | http, server, location | +| scgi_buffers | `scgi_buffers number size;` | 设置缓冲区数量和大小 | 8 4k/8k | http, server, location | +| scgi_busy_buffers_size | `scgi_busy_buffers_size size;` | 设置忙缓冲区大小 | 8k/16k | http, server, location | +| scgi_cache | `scgi_cache zone;` | 启用响应缓存 | - | http, server, location | +| scgi_cache_key | `scgi_cache_key string;` | 设置缓存键 | - | http, server, location | +| scgi_cache_valid | `scgi_cache_valid time;` | 设置缓存有效期 | - | http, server, location | +| scgi_connect_timeout | `scgi_connect_timeout time;` | 连接超时 | 60s | http, server, location | +| scgi_send_timeout | `scgi_send_timeout time;` | 发送超时 | 60s | http, server, location | +| scgi_read_timeout | `scgi_read_timeout time;` | 读取超时 | 60s | http, server, location | +| scgi_hide_header | `scgi_hide_header field;` | 隐藏响应头 | - | http, server, location | +| scgi_pass_header | `scgi_pass_header field;` | 允许传递隐藏头 | - | http, server, location | +| scgi_ignore_client_abort | `scgi_ignore_client_abort on/off;` | 忽略客户端中止 | off | http, server, location | +| scgi_intercept_errors | `scgi_intercept_errors on/off;` | 拦截错误码 | off | http, server, location | +| scgi_pass_request_headers | `scgi_pass_request_headers on/off;` | 传递请求头 | on | http, server, location | +| scgi_pass_request_body | `scgi_pass_request_body on/off;` | 传递请求体 | on | http, server, location | + +### 3.3 配置示例 + +**基本配置：** +```nginx +location / { + include scgi_params; + scgi_pass localhost:4000; +} +``` + +**Unix 域套接字配置：** +```nginx +location / { + include scgi_params; + scgi_pass unix:/tmp/scgi.sock; +} +``` + +**自定义参数：** +```nginx +location / { + scgi_param SCRIPT_NAME /myapp; + scgi_param PATH_INFO $1; + scgi_param QUERY_STRING $query_string; + scgi_param REQUEST_METHOD $request_method; + scgi_param CONTENT_TYPE $content_type; + scgi_param CONTENT_LENGTH $content_length; + scgi_param REQUEST_URI $request_uri; + scgi_param DOCUMENT_ROOT $document_root; + scgi_param SERVER_PROTOCOL $server_protocol; + scgi_param REMOTE_ADDR $remote_addr; + scgi_param REMOTE_PORT $remote_port; + scgi_param SERVER_PORT $server_port; + scgi_param SERVER_NAME $server_name; + scgi_pass localhost:4000; +} +``` + +**带缓存的配置：** +```nginx +http { + scgi_cache_path /var/cache/nginx/scgi levels=1:2 keys_zone=scgi:10m max_size=1g; + + server { + location / { + scgi_cache scgi; + scgi_cache_key $host$request_uri; + scgi_cache_valid 200 5m; + include scgi_params; + scgi_pass localhost:4000; + } + } +} +``` + +### 3.4 与 FastCGI/uWSGI 的对比 + +| 特性 | SCGI | FastCGI | uWSGI | +|------|------|---------|-------| +| 协议复杂度 | 简单（纯文本）| 中等 | 复杂（二进制）| +| 性能 | 中等 | 中等 | 最高 | +| 资源占用 | 低 | 中等 | 中等 | +| 连接方式 | 持久连接 | 持久连接 | 持久连接 | +| 功能丰富度 | 基础功能 | 较丰富 | 最丰富 | +| 语言支持 | 通用 | PHP 为主 | Python 为主 | +| 实现难度 | 简单 | 中等 | 复杂 | +| 适用场景 | 小型项目 | 中型项目 | 大型生产环境 | + +**SCGI vs FastCGI：** +- **SCGI**：协议更简单，实现更容易，适合轻量级应用 +- **FastCGI**：更成熟，生态更好，PHP 应用首选 + +**SCGI vs uWSGI：** +- **SCGI**：通用协议，不绑定特定语言 +- **uWSGI**：Python 专用，功能最丰富 + +### 3.5 应用场景 + +1. **小型 CGI 应用**：简单脚本语言的 Web 接口 +2. **自定义语言运行环境**：为特定语言实现 SCGI 接口 +3. **嵌入式系统**：资源受限环境下的轻量级方案 +4. **原型开发**：快速验证 Web 应用概念 +5. **学习目的**：理解 CGI 协议的简化实现 + +--- + +## 4. 三个模块对比总结 + +| 维度 | ngx_http_grpc_module | ngx_http_uwsgi_module | ngx_http_scgi_module | +|------|---------------------|----------------------|---------------------| +| **协议类型** | HTTP/2 (gRPC) | uwsgi (二进制) | SCGI (文本) | +| **主要语言** | 多语言 | Python | 多语言 | +| **性能** | 高（HTTP/2 多路复用）| 很高 | 中等 | +| **典型应用** | 微服务通信 | Django/Flask | CGI 脚本 | +| **配置复杂度** | 中等 | 简单 | 简单 | +| **功能特性** | 流、SSL、LB | 缓冲、缓存 | 基础代理 | +| **生态成熟度** | 快速增长 | 成熟（Python）| 小众 | + +## 5. 选择建议 + +- **微服务/API 网关**：选择 **grpc_module** +- **Python Web 应用**：选择 **uwsgi_module** +- **简单 CGI/轻量级**：选择 **scgi_module** 或 **fastcgi_module** + +--- + +*文档生成时间：2026-04-03* diff --git a/docs/update-prompts.md b/docs/update-prompts.md new file mode 100644 index 0000000..2c452e9 --- /dev/null +++ b/docs/update-prompts.md @@ -0,0 +1,16 @@ +## 更新配置文件实例 + +/ultrawork 分析配置文件，当前支持的配置和 --generate-config 是否有不一样的地方，--generate-config +需要完整且详细，包括所有字段的枚举值都要有 + +/ultrawork 分析下 @docs/plan.md 和 @docs/ 下的 nginx 文档，看看当前项目实现的怎么样了 + +## 单元测试 + +## 注释 + +/ultrawork 参考 @docs/comments.md，分析项目注释是否完善 + +## 优化 + +/ultrawork 分析下有没有已经实现的功能，但是却未实际用到的？