xfy/lolly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 nginx 模块翻译文档

Browse Source 
- 翻译 nginx grpc、uwsgi、高级特性、内部重定向、镜像切片、memcached 模块文档
- 添加模块大纲和更新提示文档

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
xfy 2026-04-03 10:55:02 +08:00
parent 6f3ecb0a9f
commit ac36cb629f
7 changed files with 1106 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
docs/14-nginx-grpc-uwsgi.md Normal file
View File

@ -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 以获得更好性能

95
docs/15-nginx-advanced-features.md Normal file
View File

@ -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 倍

118
docs/16-nginx-internal-redirect.md Normal file
View File

@ -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/<file_id>')
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;
}
}
```

142
docs/17-nginx-mirror-slice.md Normal file
View File

@ -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;
}
}
```

151
docs/18-nginx-memcached.md Normal file
View File

@ -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 提高性能

389
docs/nginx-modules-outline.md Normal file
View File

@ -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*

16
docs/update-prompts.md Normal file
View File

@ -0,0 +1,16 @@
## 更新配置文件实例
/ultrawork 分析配置文件，当前支持的配置和 --generate-config 是否有不一样的地方，--generate-config
需要完整且详细，包括所有字段的枚举值都要有
/ultrawork 分析下 @docs/plan.md 和 @docs/ 下的 nginx 文档，看看当前项目实现的怎么样了
## 单元测试
## 注释
/ultrawork 参考 @docs/comments.md，分析项目注释是否完善
## 优化
/ultrawork 分析下有没有已经实现的功能，但是却未实际用到的？