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;

            # 读响应超时 30s
            scgi_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;
    }
}

四、性能与调优要点

1. 缓冲 vs. 无缓冲

   • scgi_buffering off 可减少响应延迟，适用于流式或大文件；
   • on 时结合 scgi_buffers/scgi_max_temp_file_size 控制内存、磁盘使用。

2. 超时设置

   • 合理设置 scgi_connect_timeout、scgi_read_timeout 与 scgi_send_timeout，防止后端长时间挂起连接。

3. 缓存锁与并发填充

   • scgi_cache_lock on 可避免缓存风暴（多请求同时击穿）；
   • scgi_cache_background_update on 让第一个请求回源更新缓存，其余快速返回旧值。

4. 文件存储

   • scgi_store on 可将静态响应写盘，并通过 scgi_store_access 控制权限；
   • 配合 error_page，用于本地化缓存后端未命中资源。

通过以上配置与最佳实践，您可灵活地将 Nginx 与 SCGI 后端集成，兼顾性能、可靠性与扩展性。