lolly/docs/nginx/14-nginx-grpc-uwsgi.md

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

配置示例

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 应用配置示例

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	透传响应头	-

配置示例

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 微服务代理

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)

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 通用应用

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