Nginx教程

Appearance

代理超时配置 ​

合理配置代理超时参数对于保证服务稳定性和用户体验非常重要。

超时类型 ​

proxy_connect_timeout ​

连接后端服务器的超时时间。

nginx
proxy_connect_timeout 60s;

说明：

  • 单位：秒（s）、毫秒（ms）
  • 默认值：60s
  • 设置为0表示无限等待

proxy_send_timeout ​

向后端服务器发送请求的超时时间。

nginx
proxy_send_timeout 60s;

说明：

  • 两次成功写入操作之间的超时时间
  • 默认值：60s
  • 不是整个请求发送的超时时间

proxy_read_timeout ​

从后端服务器读取响应的超时时间。

nginx
proxy_read_timeout 60s;

说明：

  • 两次成功读取操作之间的超时时间
  • 默认值：60s
  • 不是整个响应读取的超时时间

基本配置 ​

标准配置 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

快速响应场景 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 10s;
    proxy_send_timeout 10s;
    proxy_read_timeout 10s;
}

慢速响应场景 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
}

不同场景配置 ​

API服务 ​

nginx
location /api/ {
    proxy_pass http://backend;

    proxy_connect_timeout 30s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;
}

文件上传 ​

nginx
location /upload/ {
    proxy_pass http://backend;

    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 上传限制
    client_max_body_size 100m;
    client_body_timeout 300s;
}

文件下载 ​

nginx
location /download/ {
    proxy_pass http://backend;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 300s;
}

WebSocket ​

nginx
location /ws/ {
    proxy_pass http://backend;

    proxy_connect_timeout 7d;
    proxy_send_timeout 7d;
    proxy_read_timeout 7d;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

全局配置 ​

在http块中配置 ​

nginx
http {
    # 全局代理超时
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    server {
        listen 80;
        server_name proxy.example.com;

        location / {
            proxy_pass http://backend;
        }
    }
}

在server块中配置 ​

nginx
server {
    listen 80;
    server_name proxy.example.com;

    # 服务器级别超时
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    location / {
        proxy_pass http://backend;
    }
}

在location块中配置 ​

nginx
server {
    listen 80;
    server_name proxy.example.com;

    location / {
        proxy_pass http://backend;

        # 位置级别超时
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

超时错误处理 ​

自动重试 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 5s;
    proxy_send_timeout 5s;
    proxy_read_timeout 5s;

    # 超时后尝试下一个后端
    proxy_next_upstream error timeout http_502 http_503 http_504;
    proxy_next_upstream_tries 2;
}

自定义错误页面 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 5s;
    proxy_send_timeout 5s;
    proxy_read_timeout 5s;

    # 拦截错误
    proxy_intercept_errors on;
}

error_page 504 502 /50x.html;
location = /50x.html {
    root /usr/share/nginx/html;
}

性能优化 ​

缓冲设置 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 缓冲设置
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 8k;
}

禁用缓冲 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 禁用缓冲（适合流式传输）
    proxy_buffering off;
}

监控和日志 ​

记录超时错误 ​

nginx
log_format proxy '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$request_time" '
                  '"$upstream_response_time"';

access_log /var/log/nginx/proxy.access.log proxy;

监控响应时间 ​

nginx
location / {
    proxy_pass http://backend;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 添加响应时间头
    add_header X-Response-Time $request_time;
    add_header X-Upstream-Response-Time $upstream_response_time;
}

完整示例 ​

生产环境配置 ​

nginx
upstream backend {
    server 192.168.1.10:8080;
    server 192.168.1.11:8080;
    server 192.168.1.12:8080;

    keepalive 32;
}

server {
    listen 80;
    server_name proxy.example.com;

    access_log /var/log/nginx/proxy.access.log;
    error_log /var/log/nginx/proxy.error.log;

    # API服务
    location /api/ {
        proxy_pass http://backend;

        proxy_connect_timeout 30s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;

        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # 文件上传
    location /upload/ {
        proxy_pass http://backend;

        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        client_max_body_size 100m;
        client_body_timeout 300s;
    }

    # 文件下载
    location /download/ {
        proxy_pass http://backend;

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 300s;

        proxy_buffering off;
    }

    # WebSocket
    location /ws/ {
        proxy_pass http://backend;

        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

常见问题 ​

504 Gateway Timeout ​

原因： 读取超时

解决：

nginx
proxy_read_timeout 300s;

502 Bad Gateway ​

原因： 连接超时或后端不可用

解决：

nginx
proxy_connect_timeout 60s;
proxy_next_upstream error timeout http_502;

上传中断 ​

原因： 发送超时

解决：

nginx
proxy_send_timeout 300s;
client_body_timeout 300s;

总结 ​

代理超时配置的关键点：

  • connect_timeout：连接超时
  • send_timeout：发送超时
  • read_timeout：读取超时
  • 场景配置：根据不同场景调整
  • 错误处理：重试和自定义错误页面
  • 性能优化：缓冲设置
  • 监控日志：记录超时错误

合理配置超时参数，平衡用户体验和系统稳定性。

Copyright © 2025-2026 京公网安备 11010102000001号 京ICP备2024078128号-1