ngx_http_scgi_module 技术指南
一、快速上手示例
http {# 定义 SCGI 参数（标准 CGI 环境变量）include /etc/nginx/scgi_params;server {listen 80;location /app/ {# 将请求转发到本地 9000 端口的 SCGI 服务器scgi_pass localhost:9000;# 只转发非空的 HTTPS 参数scgi_param HTTPS $https if_not_empty;# 关闭请求体缓冲（边读边发）scgi_request_buffering off;# 读响应超时 30sscgi_read_timeout 30s;# 仅 100KB 缓冲首部scgi_buffer_size 100k;scgi_buffering on;}}
}
二、核心指令速览
| 指令 | 功能概述 |
|---|---|
| scgi_pass | 设置 SCGI 服务器地址（host:port 或 unix:/path.sock） |
| scgi_param | 传递 SCGI 请求参数（CGI 环境变量），支持 if_not_empty |
| scgi_bind | 指定本地出站 IP（或 transparent） |
| scgi_buffering | 开启/关闭响应缓冲 |
| scgi_buffer_size / scgi_buffers | 缓冲区大小及数量 |
| scgi_busy_buffers_size | 发送中与未读缓冲区的最大占用 |
| scgi_read_timeout | 读取 SCGI 响应超时（两次读之间） |
| scgi_send_timeout | 发送请求到 SCGI 服务器超时 |
| scgi_request_buffering | 缓冲客户端请求体 |
| scgi_connect_timeout | 建立与 SCGI 服务器连接超时 |
| scgi_cache_path…/scgi_cache | 配置共享内存缓存路径及缓存区，用于响应缓存 |
| scgi_cache_key | 自定义缓存键 |
| scgi_cache_valid | 设置不同响应码的缓存有效期 |
| scgi_cache_use_stale | 在错误/超时时返回旧缓存 |
| scgi_cache_background_update | 背景更新过期缓存，同时先返回旧数据 |
| scgi_cache_lock… | 单并发填充缓存时的锁与超时设置 |
| scgi_store / scgi_store_access | 将 SCGI 响应保存为本地文件，并设置权限 |
| scgi_temp_path | 临时文件存放目录及层级 |
上下文：大部分指令支持
http,server,location级别；scgi_pass和scgi_param还可出现在if块中。
三、常见配置示例
1. 关闭请求体缓冲，减少延迟
location /upload/ {include scgi_params;scgi_pass backend:9000;scgi_request_buffering off;scgi_read_timeout 60s;
}
2. 限制缓冲区大小，防止内存暴增
location /media/ {include scgi_params;scgi_pass media-server:9000;scgi_buffering on;scgi_buffer_size 8k;scgi_buffers 4 16k;scgi_max_temp_file_size 50m;scgi_temp_path /var/spool/nginx/scgi_temp 1 2;
}
3. 启用响应缓存
# 在 http{} 块中定义缓存
scgi_cache_path /data/nginx/scgi_cache levels=1:2 keys_zone=scgi_zone:20m inactive=30m max_size=10g;server {location /api/ {include scgi_params;scgi_pass api-backend:9000;scgi_cache scgi_zone;scgi_cache_key $scheme$host$request_uri;scgi_cache_valid 200 302 5m;scgi_cache_use_stale error timeout updating;scgi_cache_background_update on;scgi_cache_lock on;}
}
四、性能与调优要点
-
缓冲 vs. 无缓冲
scgi_buffering off可减少响应延迟，适用于流式或大文件；on时结合scgi_buffers/scgi_max_temp_file_size控制内存、磁盘使用。
-
超时设置
- 合理设置
scgi_connect_timeout、scgi_read_timeout与scgi_send_timeout，防止后端长时间挂起连接。
- 合理设置
-
缓存锁与并发填充
scgi_cache_lock on可避免缓存风暴（多请求同时击穿）；scgi_cache_background_update on让第一个请求回源更新缓存，其余快速返回旧值。
-
文件存储
scgi_store on可将静态响应写盘，并通过scgi_store_access控制权限；- 配合
error_page，用于本地化缓存后端未命中资源。
通过以上配置与最佳实践，您可灵活地将 Nginx 与 SCGI 后端集成，兼顾性能、可靠性与扩展性。