当前位置： 首页 > article >正文

nginx ngx_http_module(9) 指令详解

article 2025/2/22 13:16:12

nginx ngx_http_module(9) 指令详解

nginx 模块目录

nginx 全指令目录

一、目录

1.1 模块简介

  • ngx_http_uwsgi_module：uWSGI支持模块，允许Nginx与uWSGI服务器进行通信。uWSGI是一种应用服务器协议，广泛用于Python Web应用的部署。通过该模块，Nginx可以将动态请求转发给uWSGI服务器处理，并将响应返回给客户端。常用的指令包括 uwsgi_pass 用于指定uWSGI服务器地址和端口。

1.2 指令目录

1.2.1 ngx_http_uwsgi_module
  • uwsgi_bind
  • uwsgi_buffer_size
  • uwsgi_buffering
  • uwsgi_buffers
  • uwsgi_busy_buffers_size
  • uwsgi_cache
  • uwsgi_cache_background_update
  • uwsgi_cache_bypass
  • uwsgi_cache_key
  • uwsgi_cache_lock
  • uwsgi_cache_lock_age
  • uwsgi_cache_lock_timeout
  • uwsgi_cache_max_range_offset
  • uwsgi_cache_methods
  • uwsgi_cache_min_uses
  • uwsgi_cache_path
  • uwsgi_cache_purge
  • uwsgi_cache_revalidate
  • uwsgi_cache_use_stale
  • uwsgi_cache_valid
  • uwsgi_connect_timeout
  • uwsgi_force_ranges
  • uwsgi_hide_header
  • uwsgi_ignore_client_abort
  • uwsgi_ignore_headers
  • uwsgi_intercept_errors
  • uwsgi_limit_rate
  • uwsgi_max_temp_file_size
  • uwsgi_modifier1
  • uwsgi_modifier2
  • uwsgi_next_upstream
  • uwsgi_next_upstream_timeout
  • uwsgi_next_upstream_tries
  • uwsgi_no_cache
  • uwsgi_param
  • uwsgi_pass
  • uwsgi_pass_header
  • uwsgi_pass_request_body
  • uwsgi_pass_request_headers
  • uwsgi_read_timeout
  • uwsgi_request_buffering
  • uwsgi_send_timeout
  • uwsgi_socket_keepalive
  • uwsgi_ssl_certificate
  • uwsgi_ssl_certificate_cache
  • uwsgi_ssl_certificate_key
  • uwsgi_ssl_ciphers
  • uwsgi_ssl_conf_command
  • uwsgi_ssl_crl
  • uwsgi_ssl_key_log
  • uwsgi_ssl_name
  • uwsgi_ssl_password_file
  • uwsgi_ssl_protocols
  • uwsgi_ssl_server_name
  • uwsgi_ssl_session_reuse
  • uwsgi_ssl_trusted_certificate
  • uwsgi_ssl_verify
  • uwsgi_ssl_verify_depth
  • uwsgi_store
  • uwsgi_store_access
  • uwsgi_temp_file_write_size
  • uwsgi_temp_path

二、解释

2.1 ngx_http_uwsgi_module

ngx_http_uwsgi_module 是 Nginx 的一个模块，用于与 uWSGI 应用服务器进行通信。uWSGI 是一个快速、自适应的 WSGI 服务器，广泛用于 Python Web 应用的部署。通过 ngx_http_uwsgi_module，Nginx 可以将请求转发给 uWSGI 服务器，并处理响应返回给客户端。

主要功能

  • 请求转发：将客户端的请求转发给 uWSGI 应用服务器。
  • 负载均衡：通过 upstream 指令实现多个 uWSGI 实例之间的负载均衡。
  • 缓存控制：设置缓存相关的头部信息，控制缓存行为。
  • 重试机制：当某个 uWSGI 服务器不可用时，可以自动尝试其他服务器。
  • 健康检查：结合 upstream 和 health_check 模块实现对 uWSGI 服务器的健康状态监控。

常用指令

以下是与 ngx_http_uwsgi_module 模块相关的常用配置指令及其简要说明：

  • uwsgi_pass：指定 uWSGI 服务器的地址和端口，或使用 Unix 域套接字路径。

  • uwsgi_param：在转发请求之前修改或添加 uWSGI 参数。

  • uwsgi_cache：启用缓存并指定缓存区域名称。

  • uwsgi_cache_valid：为不同的响应码设置缓存的有效时间。

  • uwsgi_next_upstream：定义在哪些情况下应尝试下一个上游服务器。

  • uwsgi_read_timeout：设置等待 uWSGI 服务器响应的超时时间。

  • uwsgi_connect_timeout：设置连接到 uWSGI 服务器的超时时间。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_uwsgi_module 来实现各种功能。

基本配置

假设你想将所有 /app/ 路径下的请求代理到一个 uWSGI 服务器：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;  # uWSGI 服务器地址和端口
    }

    server {
        listen 80;
        server_name example.com;

        location /app/ {
            # 将请求转发给 upstream 定义的 uwsgi_backend 组
            uwsgi_pass uwsgi_backend;

            # 修改请求头
            uwsgi_param Host $host;
            uwsgi_param X-Real-IP $remote_addr;
            uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
            uwsgi_param X-Forwarded-Proto $scheme;

            # 设置 uWSGI 协议版本
            uwsgi_protocol uwsgi;
        }
    }
}

在这个例子中：

  • upstream uwsgi_backend 定义了一个包含单个 uWSGI 服务器的组。
  • location /app/ 匹配 /app/ 路径下的请求，并将其转发给 uwsgi_backend 组中的服务器。
  • uwsgi_param 指令用于修改请求头，确保 uWSGI 服务器能获取客户端的真实 IP 地址和其他信息。

缓存配置

你可以结合 uwsgi_cache 指令启用缓存功能，以减少对 uWSGI 服务器的请求次数：

http {
    # 定义缓存区域
    uwsgi_cache_path /var/cache/nginx/uwsgi_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location /static/ {
            uwsgi_pass uwsgi_backend;

            # 启用缓存
            uwsgi_cache my_cache;
            uwsgi_cache_valid 200 302 10m;
            uwsgi_cache_valid 404 1m;

            # 添加缓存相关头部
            add_header X-UWSGI-Cache $upstream_cache_status;
        }

        location /dynamic/ {
            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • uwsgi_cache_path 定义了一个名为 my_cache 的缓存区域，位于 /var/cache/nginx/uwsgi_cache 目录下。
  • uwsgi_cache 启用了缓存，并指定了缓存区域。
  • uwsgi_cache_valid 设置了不同 HTTP 状态码的缓存有效期。
  • add_header X-UWSGI-Cache $upstream_cache_status; 添加了一个响应头，显示缓存状态（如 HIT 或 MISS）。

负载均衡和重试机制

你可以配置负载均衡策略，并在某些情况下自动重试其他服务器：

http {
    upstream uwsgi_backend {
        server 192.168.1.1:3031;
        server 192.168.1.2:3031;
        server backup.example.com:3031 backup;  # 备份服务器

        # 加权轮询
        # server 192.168.1.1:3031 weight=3;
        # server 192.168.1.2:3031 weight=1;

        # 最少连接
        # least_conn;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass uwsgi_backend;

            # 当出现错误或超时时重试其他服务器
            uwsgi_next_upstream error timeout http_500 http_502 http_503 http_504;

            # 连接超时时间
            uwsgi_connect_timeout 5s;

            # 读取响应超时时间
            uwsgi_read_timeout 30s;
        }
    }
}

在这个例子中：

  • upstream uwsgi_backend 定义了一个包含多个 uWSGI 服务器的组，并指定了一个备份服务器。
  • uwsgi_next_upstream 指令定义了在哪些情况下应尝试下一个上游服务器（如连接错误、超时、HTTP 500 错误等）。
  • uwsgi_connect_timeout 和 uwsgi_read_timeout 分别设置了连接和读取响应的超时时间。

请求头修改

你可以根据需要修改请求头，以便更好地控制请求转发过程：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass uwsgi_backend;

            # 修改请求头
            uwsgi_param Host $host;
            uwsgi_param X-Real-IP $remote_addr;
            uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
            uwsgi_param X-Forwarded-Proto $scheme;

            # 添加自定义请求头
            uwsgi_param X-Custom-Header "CustomValue";
        }
    }
}

在这个例子中：

  • uwsgi_param 指令用于修改请求头，确保 uWSGI 服务器能获取客户端的真实 IP 地址和其他信息。
  • 你还可以添加自定义请求头，如 X-Custom-Header。

健康检查

虽然 ngx_http_uwsgi_module 本身不直接提供健康检查功能，但可以通过结合 ngx_http_upstream_module 和 ngx_http_upstream_hc_module 实现健康检查：

http {
    upstream uwsgi_backend {
        server 192.168.1.1:3031;
        server 192.168.1.2:3031;

        # 启用健康检查
        health_check interval=10 fails=3 passes=2;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • health_check 指令启用了健康检查，默认情况下每 10 秒检查一次，连续失败 3 次即认为服务器不可用，连续成功 2 次即认为服务器恢复可用。

注意事项

  • 性能考虑：

    • 配置合理的超时时间和重试机制，避免不必要的延迟和资源浪费。
    • 如果有大量并发请求，考虑使用负载均衡和缓存机制来分担压力。

  • 安全性：

    • 确保 uWSGI 服务器的安全性，避免未经授权的访问。
    • 对敏感数据进行加密传输，防止中间人攻击。

  • 日志记录：

    • 合理配置日志级别和格式，便于监控和故障排查。特别是注意记录请求转发和响应处理的日志。
2.1.1 指令列表
uwsgi_bind

uwsgi_bind 指令用于指定 uWSGI 服务器绑定的地址和端口。这有助于控制 Nginx 如何与 uWSGI 后端通信。

Syntax:	uwsgi_bind address [transparent] | off;
Default: —
Context: http, server, location
  • address：uWSGI 服务器绑定的地址（IP 地址或主机名）和端口。
  • transparent：可选参数，启用透明代理模式，允许 Nginx 以客户端 IP 地址与 uWSGI 服务器通信。
  • off：禁用绑定配置。

案例

基本用法

最简单的 uwsgi_bind 用法是指定 uWSGI 服务器绑定的地址：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 绑定到 uWSGI 服务器的地址和端口
            uwsgi_bind 127.0.0.1:3031;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 example.com 时，Nginx 将通过 127.0.0.1:3031 与 uWSGI 服务器通信。

使用透明代理模式

你可以启用透明代理模式来保留客户端的真实 IP 地址：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 绑定到 uWSGI 服务器的地址和端口，并启用透明代理模式
            uwsgi_bind 127.0.0.1:3031 transparent;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • Nginx 将以客户端的实际 IP 地址与 uWSGI 服务器通信，而不是使用 Nginx 的 IP 地址。

注意事项

  • 安全性：确保透明代理模式不会暴露内部网络结构或导致安全风险。
  • 权限要求：透明代理模式通常需要特定的操作系统权限（如 CAP_NET_ADMIN），请确保正确配置。
uwsgi_buffer_size

uwsgi_buffer_size 指令用于设置用于读取 uWSGI 响应的第一部分的缓冲区大小。这对于处理大响应头非常有用。

Syntax:	uwsgi_buffer_size size;
Default: uwsgi_buffer_size 4k|8k;
Context: http, server, location
  • size：用于读取 uWSGI 响应第一部分的缓冲区大小，默认为 4 KB 或 8 KB。

案例

基本用法

最简单的 uwsgi_buffer_size 用法是设置缓冲区大小：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 设置 uwsgi 缓冲区大小为 16 KB
            uwsgi_buffer_size 16k;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 Nginx 从 uWSGI 服务器读取响应时，将使用 16 KB 的缓冲区来处理响应的第一部分。

注意事项

  • 性能优化：合理设置缓冲区大小以避免频繁的内存分配和释放，特别是在处理大响应头的情况下。
  • 资源平衡：确保设置的大小不会占用过多内存，特别是在高并发环境下。
uwsgi_buffering

uwsgi_buffering 指令用于控制是否启用 uWSGI 响应的缓冲功能。这有助于提高性能，但可能会影响实时性。

Syntax:	uwsgi_buffering on | off;
Default: uwsgi_buffering on;
Context: http, server, location
  • on：启用 uWSGI 响应的缓冲功能，默认行为。
  • off：禁用 uWSGI 响应的缓冲功能。

案例

基本用法

最简单的 uwsgi_buffering 用法是启用或禁用缓冲功能：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 禁用 uwsgi 响应的缓冲功能
            uwsgi_buffering off;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 example.com 时，Nginx 将直接将 uWSGI 响应传递给客户端，而不进行缓冲。

注意事项

  • 性能与实时性：启用缓冲功能可以提高性能，但在某些情况下（如实时应用）可能需要禁用缓冲。
  • 资源管理：禁用缓冲功能可能导致更高的内存和 CPU 使用率，特别是在处理大数据量时。
uwsgi_buffers

uwsgi_buffers 指令用于设置用于读取 uWSGI 响应的缓冲区数量和大小。这有助于优化响应处理的性能。

Syntax:	uwsgi_buffers number size;
Default: uwsgi_buffers 8 4k|8k;
Context: http, server, location
  • number：用于读取 uWSGI 响应的缓冲区数量。
  • size：每个缓冲区的大小，默认为 4 KB 或 8 KB。

案例

基本用法

最简单的 uwsgi_buffers 用法是设置缓冲区的数量和大小：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 设置 uwsgi 缓冲区的数量为 16，每个缓冲区大小为 8 KB
            uwsgi_buffers 16 8k;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • Nginx 将使用 16 个 8 KB 的缓冲区来读取 uWSGI 响应。

注意事项

  • 性能优化：合理设置缓冲区的数量和大小以避免频繁的内存分配和释放，特别是在处理大数据量响应时。
  • 资源平衡：确保设置的数量和大小不会占用过多内存，特别是在高并发环境下。
uwsgi_busy_buffers_size

uwsgi_busy_buffers_size 用于设置在处理 uwsgi 响应时，同时处于繁忙状态的缓冲区的最大总大小。这有助于控制内存使用并优化性能。

Syntax: uwsgi_busy_buffers_size size;
Default: uwsgi_busy_buffers_size 8k|16k;
Context: http, server, location
  • size：指定繁忙缓冲区的总大小，默认值为 8KB 或 16KB（取决于平台）。

案例

基本用法

最简单的 uwsgi_busy_buffers_size 用法是指定缓冲区大小：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_busy_buffers_size 16k;  # 设置繁忙缓冲区大小为 16KB
    }
}

在这个例子中，设置了 uwsgi_busy_buffers_size 16k，这意味着繁忙缓冲区的总大小为 16KB。

调整缓冲区大小

根据实际需求调整缓冲区大小：

server {
    listen 80;
    server_name example.com;

    location /small_buffers/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_busy_buffers_size 8k;  # 较小的缓冲区大小
    }

    location /large_buffers/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_busy_buffers_size 32k;  # 较大的缓冲区大小
    }
}

在这个例子中：

  • 对于 /small_buffers/ 路径下的请求，设置了较小的缓冲区大小（8KB）。
  • 对于 /large_buffers/ 路径下的请求，设置了较大的缓冲区大小（32KB）。

注意事项

  • 性能优化：合理设置缓冲区大小，确保既能满足应用需求，又不会浪费资源。
  • 应用场景：根据具体的应用场景选择合适的缓冲区大小，例如高并发场景下可能需要更大的缓冲区。
uwsgi_cache

uwsgi_cache 用于启用或禁用 uwsgi 缓存，并指定缓存区域。这有助于提高响应速度，减少后端服务器的负载。

Syntax: uwsgi_cache zone | off;
Default: uwsgi_cache off;
Context: http, server, location
  • zone：指定要使用的共享缓存区域。
  • off：禁用 uwsgi 缓存（默认行为）。

案例

基本用法

最简单的 uwsgi_cache 用法是启用缓存并指定缓存区域：

http {
    uwsgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache my_cache;  # 启用 uwsgi 缓存并指定缓存区域
        }
    }
}

在这个例子中，启用了 uwsgi 缓存，并指定了名为 my_cache 的缓存区域。

禁用缓存

根据实际需求禁用 uwsgi 缓存：

server {
    listen 80;
    server_name example.com;

    location /no_cache/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_cache off;  # 禁用 uwsgi 缓存
    }
}

在这个例子中，对于 /no_cache/ 路径下的请求，禁用了 uwsgi 缓存。

注意事项

  • 缓存配置：确保正确配置缓存路径和参数，以避免磁盘空间不足或其他问题。
  • 缓存策略：根据实际需求选择合适的缓存策略，确保既能提高性能，又不会影响数据一致性。
uwsgi_cache_background_update

uwsgi_cache_background_update 用于控制是否在后台更新缓存内容。这有助于保持缓存的有效性，减少用户等待时间。

Syntax: uwsgi_cache_background_update on | off;
Default: uwsgi_cache_background_update off;
Context: http, server, location
This directive appeared in version 1.11.10.
  • on：启用后台更新（从版本 1.11.10 开始支持）。
  • off：禁用后台更新（默认行为）。

案例

基本用法

最简单的 uwsgi_cache_background_update 用法是启用后台更新：

http {
    uwsgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache my_cache;
            uwsgi_cache_background_update on;  # 启用后台更新
        }
    }
}

在这个例子中，启用了后台更新功能，确保缓存内容在后台进行更新。

禁用后台更新

根据实际需求禁用后台更新：

server {
    listen 80;
    server_name example.com;

    location /disable_bg_update/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_cache my_cache;
        uwsgi_cache_background_update off;  # 禁用后台更新
    }
}

在这个例子中，对于 /disable_bg_update/ 路径下的请求，禁用了后台更新功能。

注意事项

  • 用户体验：启用后台更新可以减少用户等待时间，但需要注意缓存一致性和更新频率。
  • 系统负载：后台更新可能会增加系统的负载，特别是在高并发场景下。
uwsgi_cache_bypass

uwsgi_cache_bypass 用于定义哪些条件下不使用缓存。这有助于灵活控制缓存的使用，确保某些请求总是直接访问后端服务器。

Syntax: uwsgi_cache_bypass string ...;
Default: —
Context: http, server, location
  • string：指定一个或多个条件表达式，当这些条件为真时，跳过缓存。

案例

基本用法

最简单的 uwsgi_cache_bypass 用法是指定条件来跳过缓存：

http {
    uwsgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache my_cache;
            uwsgi_cache_bypass $cookie_nocache $arg_nocache;  # 当存在特定 Cookie 或查询参数时不使用缓存
        }
    }
}

在这个例子中，当请求包含 $cookie_nocache 或 $arg_nocache 参数时，跳过缓存。

复杂条件

根据实际需求定义更复杂的条件：

server {
    listen 80;
    server_name example.com;

    location /complex_bypass/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_cache my_cache;
        uwsgi_cache_bypass $cookie_nocache $arg_nocache $http_x_custom_header;  # 多个条件组合
    }

    location /always_bypass/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_cache my_cache;
        uwsgi_cache_bypass 1;  # 总是跳过缓存
    }
}

在这个例子中：

  • 对于 /complex_bypass/ 路径下的请求，当存在 $cookie_nocache、$arg_nocache 或自定义头 $http_x_custom_header 时，跳过缓存。
  • 对于 /always_bypass/ 路径下的请求，总是跳过缓存。

注意事项

  • 灵活性：通过定义不同的条件，可以灵活控制哪些请求跳过缓存。
  • 一致性：确保跳过缓存的条件符合业务逻辑，避免不必要的性能损失。
uwsgi_cache_key

uwsgi_cache_key 指令用于定义缓存键值的字符串。这个指令帮助确定哪些请求会被视为相同的请求并使用相同的缓存。

Syntax:	uwsgi_cache_key string;
Default:	—
Context:	http, server, location
  • string：指定缓存键值的字符串表达式，通常包含变量如 $request_uri 或 $host。

案例

基本用法

最简单的 uwsgi_cache_key 用法是指定一个具体的缓存键值字符串：

http {
    uwsgi_cache_path /tmp/uwsgi_cache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_key $scheme$proxy_host$request_uri;
        }
    }
}

在这个例子中：

  • 设置了 uwsgi_cache_key $scheme$proxy_host$request_uri，这意味着Nginx将根据协议、代理主机和请求URI生成缓存键值。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的缓存键值字符串：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_cache mycache;
        uwsgi_cache_key $scheme$proxy_host$request_uri;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_cache mycache;
        uwsgi_cache_key $scheme$request_uri;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_cache_key $scheme$proxy_host$request_uri。
  • 对于 example2.com，设置了 uwsgi_cache_key $scheme$request_uri。

注意事项

  • 唯一性与一致性：确保缓存键值字符串能够唯一标识每个请求，避免冲突。
  • 适用场景：适用于需要缓存响应的应用场景。例如，在高并发网站、API网关等环境中使用。
  • 调试和监控：如果你遇到缓存键值问题，可以检查以下几点：
    • 确保缓存键值字符串设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_cache_lock

uwsgi_cache_lock 指令用于控制是否启用缓存锁功能。这个指令帮助防止缓存穿透（cache stampede）问题。

Syntax:	uwsgi_cache_lock on | off;
Default:	uwsgi_cache_lock off;
Context:	http, server, location
This directive appeared in version 1.1.12.
  • on：启用缓存锁功能。
  • off：禁用缓存锁功能（默认值）。

案例

基本用法

最简单的 uwsgi_cache_lock 用法是指定是否启用缓存锁功能：

http {
    uwsgi_cache_path /tmp/uwsgi_cache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_lock on;
        }
    }
}

在这个例子中：

  • 设置了 uwsgi_cache_lock on，这意味着Nginx将启用缓存锁功能。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置是否启用缓存锁功能：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock on;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock off;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_cache_lock on。
  • 对于 example2.com，设置了 uwsgi_cache_lock off。

注意事项

  • 性能与资源平衡：启用缓存锁可以防止缓存穿透，但可能会增加请求延迟。根据实际需求选择是否启用。
  • 适用场景：适用于需要防止缓存穿透的应用场景。例如，在高并发网站、API网关等环境中使用。
  • 调试和监控：如果你遇到缓存锁问题，可以检查以下几点：
    • 确保缓存锁设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_cache_lock_age

uwsgi_cache_lock_age 指令用于指定缓存锁的有效期。这个指令帮助控制缓存锁的时间窗口。

Syntax:	uwsgi_cache_lock_age time;
Default:	uwsgi_cache_lock_age 5s;
Context:	http, server, location
This directive appeared in version 1.7.8.
  • time：指定缓存锁的有效期，默认为 5s（5秒）。

案例

基本用法

最简单的 uwsgi_cache_lock_age 用法是指定一个具体的有效期：

http {
    uwsgi_cache_path /tmp/uwsgi_cache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_lock on;
            uwsgi_cache_lock_age 10s;
        }
    }
}

在这个例子中：

  • 设置了 uwsgi_cache_lock_age 10s，这意味着缓存锁的有效期为10秒。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的缓存锁有效期：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock on;
        uwsgi_cache_lock_age 5s;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock on;
        uwsgi_cache_lock_age 15s;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_cache_lock_age 5s。
  • 对于 example2.com，设置了 uwsgi_cache_lock_age 15s。

注意事项

  • 时间窗口管理：合理设置缓存锁的有效期，避免过长导致的资源占用或过短影响效果。
  • 适用场景：适用于需要精确控制缓存锁时间窗口的应用场景。例如，在需要精细调整缓存策略的高并发网站、API网关等环境中使用。
  • 调试和监控：如果你遇到缓存锁有效期问题，可以检查以下几点：
    • 确保缓存锁有效期设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_cache_lock_timeout

uwsgi_cache_lock_timeout 指令用于指定等待缓存锁释放的最大超时时间。这个指令帮助控制请求在等待缓存锁时的最大等待时间。

Syntax:	uwsgi_cache_lock_timeout time;
Default:	uwsgi_cache_lock_timeout 5s;
Context:	http, server, location
This directive appeared in version 1.1.12.
  • time：指定等待缓存锁释放的最大超时时间，默认为 5s（5秒）。

案例

基本用法

最简单的 uwsgi_cache_lock_timeout 用法是指定一个具体的超时时间：

http {
    uwsgi_cache_path /tmp/uwsgi_cache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_lock on;
            uwsgi_cache_lock_timeout 10s;
        }
    }
}

在这个例子中：

  • 设置了 uwsgi_cache_lock_timeout 10s，这意味着请求在等待缓存锁时的最大等待时间为10秒。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的缓存锁超时时间：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock on;
        uwsgi_cache_lock_timeout 5s;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_cache mycache;
        uwsgi_cache_lock on;
        uwsgi_cache_lock_timeout 20s;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_cache_lock_timeout 5s。
  • 对于 example2.com，设置了 uwsgi_cache_lock_timeout 20s。

注意事项

  • 超时管理：合理设置最大等待时间，避免过长导致的请求阻塞或过短影响缓存命中率。
  • 适用场景：适用于需要控制请求等待缓存锁时的最大等待时间的应用场景。例如，在需要优化响应时间和缓存命中率的高并发网站、API网关等环境中使用。
  • 调试和监控：如果你遇到缓存锁超时问题，可以检查以下几点：
    • 确保缓存锁超时时间设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_cache_max_range_offset

uwsgi_cache_max_range_offset 指令用于设置缓存的最大范围偏移量（以字节为单位），用于处理 HTTP Range 请求。

Syntax:	uwsgi_cache_max_range_offset number;
Default:	—
Context:	http, server, location
This directive appeared in version 1.11.6.
  • number：指定最大范围偏移量的大小（以字节为单位）。

案例

基本用法

最简单的 uwsgi_cache_max_range_offset 用法是指定最大范围偏移量：

server {
    listen 80;
    server_name example.com;

    location /downloads/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 设置最大范围偏移量为 10MB
        uwsgi_cache_max_range_offset 10485760; # 10MB in bytes

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 最大范围偏移量设置为 10MB（即 10485760 字节）。

注意事项

  • 性能优化：合理设置最大范围偏移量可以避免缓存过多的大文件片段，从而节省缓存空间。
  • 适用场景：适用于需要处理大文件部分请求的应用场景。例如，在下载服务或视频流媒体应用中，适当设置最大范围偏移量可以优化缓存使用。
  • 调试和监控：如果你遇到范围偏移量问题，可以检查以下几点：
    • 确保数值设置合理，不会导致缓存溢出或浪费。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_cache_methods

uwsgi_cache_methods 指令用于设置哪些 HTTP 方法的响应可以被缓存。

Syntax:	uwsgi_cache_methods GET | HEAD | POST ...;
Default:	uwsgi_cache_methods GET HEAD;
Context:	http, server, location
  • GET：允许缓存 GET 请求的响应。
  • HEAD：允许缓存 HEAD 请求的响应。
  • POST：允许缓存 POST 请求的响应。
  • 其他方法：如 PUT、DELETE 等可以根据需要添加。

案例

基本用法

最简单的 uwsgi_cache_methods 用法是指定允许缓存的方法：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 允许缓存 GET、HEAD 和 POST 请求的响应
        uwsgi_cache_methods GET HEAD POST;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 允许缓存 GET、HEAD 和 POST 请求的响应。

使用默认值

你可以选择使用默认值：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 使用默认值（仅允许缓存 GET 和 HEAD 请求的响应）
        uwsgi_cache_methods GET HEAD;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 仅允许缓存 GET 和 HEAD 请求的响应（默认值）。

注意事项

  • 安全性：确保只有安全且适合缓存的 HTTP 方法被启用。例如，通常不建议缓存 POST 请求的响应，因为它们通常是动态生成的。
  • 适用场景：适用于需要根据不同的 HTTP 方法来管理缓存的应用场景。例如，在 RESTful API 中，可能需要缓存 GET 请求的结果，但不缓存 POST 请求的结果。
  • 调试和监控：如果你遇到缓存方法问题，可以检查以下几点：
    • 确保启用的 HTTP 方法符合实际需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_cache_min_uses

uwsgi_cache_min_uses 指令用于设置一个响应必须被请求多少次才能被缓存。

Syntax:	uwsgi_cache_min_uses number;
Default:	uwsgi_cache_min_uses 1;
Context:	http, server, location
  • number：指定响应必须被请求的次数，默认值为 1。

案例

基本用法

最简单的 uwsgi_cache_min_uses 用法是指定最小请求次数：

server {
    listen 80;
    server_name example.com;

    location /data/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 设置响应必须被请求 3 次才能被缓存
        uwsgi_cache_min_uses 3;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 响应必须被请求 3 次才能被缓存。

使用默认值

你可以选择使用默认值：

server {
    listen 80;
    server_name example.com;

    location /data/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 使用默认值（响应只需被请求 1 次即可被缓存）
        uwsgi_cache_min_uses 1;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 响应只需被请求 1 次即可被缓存（默认值）。

注意事项

  • 性能优化：合理设置最小请求次数可以减少不必要的缓存更新，特别是在高并发场景下。
  • 适用场景：适用于需要控制缓存频率的应用场景。例如，在高流量网站中，适当增加最小请求次数可以减少缓存的频繁更新。
  • 调试和监控：如果你遇到最小请求次数问题，可以检查以下几点：
    • 确保数值设置合理，不会导致缓存过早或过晚更新。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_cache_path

uwsgi_cache_path 指令用于定义缓存存储的位置及其参数。

Syntax:	uwsgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:	—
Context:	http
  • path：指定缓存存储的路径。
  • levels：指定缓存文件的目录层次结构。
  • use_temp_path：是否使用临时目录进行写入操作。
  • keys_zone：指定共享内存区的名称和大小。
  • inactive：指定缓存项在未访问期间保持有效的最大时间。
  • max_size：指定缓存的最大尺寸。
  • min_free：指定缓存分区中应保留的最小空闲空间。
  • manager_files：指定每次清理时要删除的缓存文件数。
  • manager_sleep：指定每次清理之间的睡眠时间。
  • manager_threshold：指定每次清理的最大执行时间。
  • loader_files：指定每次加载时要加载的缓存文件数。
  • loader_sleep：指定每次加载之间的睡眠时间。
  • loader_threshold：指定每次加载的最大执行时间。
  • purger：是否启用缓存清除器。
  • purger_files：指定每次清除时要删除的缓存文件数。
  • purger_sleep：指定每次清除之间的睡眠时间。
  • purger_threshold：指定每次清除的最大执行时间。

案例

基本用法

最简单的 uwsgi_cache_path 用法是指定缓存存储的基本参数：

http {
    uwsgi_cache_path /var/cache/nginx/uwsgi levels=1:2 keys_zone=my_cache:10m inactive=60m max_size=1g;

    server {
        listen 80;
        server_name example.com;

        location /api/ {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            uwsgi_cache my_cache;
            uwsgi_cache_valid 200 1h;
        }
    }
}

在这个例子中：

  • 缓存存储在 /var/cache/nginx/uwsgi 目录下。
  • 目录层次结构为 1:2。
  • 共享内存区名为 my_cache，大小为 10MB。
  • 缓存项在未访问期间保持有效的时间为 60 分钟。
  • 缓存的最大尺寸为 1GB。

更详细的配置

你可以进一步细化配置：

http {
    uwsgi_cache_path /var/cache/nginx/uwsgi 
                      levels=1:2 
                      use_temp_path=off 
                      keys_zone=my_cache:10m 
                      inactive=60m 
                      max_size=1g 
                      min_free=100m 
                      manager_files=100 
                      manager_sleep=50ms 
                      manager_threshold=200ms 
                      loader_files=100 
                      loader_sleep=50ms 
                      loader_threshold=200ms 
                      purger=on 
                      purger_files=100 
                      purger_sleep=50ms 
                      purger_threshold=200ms;

    server {
        listen 80;
        server_name example.com;

        location /api/ {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            uwsgi_cache my_cache;
            uwsgi_cache_valid 200 1h;
        }
    }
}

在这个例子中：

  • 启用了更多的缓存管理选项，如 min_free、manager_files、loader_files 和 purger。

注意事项

  • 缓存管理：合理配置缓存路径及相关参数可以显著提高缓存性能和稳定性。确保路径具有足够的存储空间，并定期清理无效缓存。
  • 适用场景：适用于需要详细管理缓存存储和性能的应用场景。例如，在高流量网站或复杂应用中，适当的缓存配置可以显著提升系统性能。
  • 调试和监控：如果你遇到缓存路径问题，可以检查以下几点：
    • 确保路径设置正确且具有足够的权限。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_cache_purge

uwsgi_cache_purge 指令用于指定哪些请求可以清除缓存。这对于在特定条件下（如内容更新时）手动或自动清除缓存非常有用。

Syntax:	uwsgi_cache_purge string ...;
Default:	—
Context:	http, server, location
This directive appeared in version 1.5.7.
  • string：指定一个或多个条件字符串，匹配这些条件的请求将触发缓存清除操作。

案例

基本用法

假设我们希望允许通过带有特定查询参数（如 purge=true）的请求来清除缓存：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_purge $arg_purge purge;  # 如果请求包含 ?purge=purge，则清除缓存
        }
    }
}

在这个例子中，如果请求包含 ?purge=purge 查询参数，Nginx 将清除相应的缓存条目。

注意事项

  • 安全性：确保只有授权用户或系统能够触发缓存清除操作，以防止滥用。
  • 性能影响：频繁的缓存清除操作可能会影响性能，需合理规划。
uwsgi_cache_revalidate

uwsgi_cache_revalidate 指令用于控制是否在缓存过期后重新验证缓存内容。这对于确保缓存数据的及时性和准确性非常重要。

Syntax:	uwsgi_cache_revalidate on | off;
Default:	uwsgi_cache_revalidate off;
Context:	http, server, location
This directive appeared in version 1.5.7.
  • on：当缓存过期时，Nginx 将向后端服务器发送一个条件请求（如 If-Modified-Since 或 If-None-Match），以检查是否有更新的内容。
  • off（默认）：当缓存过期时，Nginx 将直接从后端服务器获取新内容。

案例

启用重新验证

假设我们希望在缓存过期后重新验证缓存内容：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_revalidate on;  # 在缓存过期后重新验证
        }
    }
}

禁用重新验证

如果我们不希望在缓存过期后重新验证：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_revalidate off;  # 默认行为，直接从后端服务器获取新内容
        }
    }
}

注意事项

  • 性能优化：启用重新验证可以在一定程度上减少不必要的全量请求，提高缓存命中率。
  • 带宽节省：使用条件请求可以节省带宽，特别是在静态资源较多的情况下。
uwsgi_cache_use_stale

uwsgi_cache_use_stale 指令用于控制在某些错误情况下是否使用过期的缓存内容。这对于提高服务的可用性非常有用，尤其是在后端服务器不可用时。

Syntax:	uwsgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default:	uwsgi_cache_use_stale off;
Context:	http, server, location
  • error：当与后端服务器的连接发生错误时使用过期缓存。
  • timeout：当与后端服务器的连接超时时使用过期缓存。
  • invalid_header：当收到无效响应头时使用过期缓存。
  • updating：当正在更新缓存时使用过期缓存。
  • http_500、http_503、http_403、http_404、http_429：分别对应不同的HTTP状态码。
  • off（默认）：不使用过期缓存。

案例

使用多种错误情况下的过期缓存

假设我们希望在多种错误情况下使用过期缓存：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_use_stale error timeout invalid_header http_500 http_503;  # 在多种错误情况下使用过期缓存
        }
    }
}

禁用过期缓存

如果我们不希望在任何错误情况下使用过期缓存：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;
            uwsgi_cache_use_stale off;  # 默认行为，不使用过期缓存
        }
    }
}

注意事项

  • 服务可用性：在后端服务器不可用时提供过期但可用的内容，可以显著提高用户体验。
  • 一致性：需要权衡缓存一致性和服务可用性之间的关系，避免长时间显示过期内容。
uwsgi_cache_valid

uwsgi_cache_valid 指令用于设置不同HTTP响应码的缓存有效期。这对于控制缓存策略和确保缓存内容的有效性非常重要。

Syntax:	uwsgi_cache_valid [code ...] time;
Default:	—
Context:	http, server, location
  • code：指定一个或多个HTTP响应码（如 200、404、500 等）。
  • time：指定缓存有效时间，格式为 time[units]，例如 1h 表示1小时。

案例

设置不同响应码的缓存有效期

假设我们希望对不同的HTTP响应码设置不同的缓存有效期：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;

            # 对200响应码设置1小时的缓存有效期
            uwsgi_cache_valid 200 1h;

            # 对404响应码设置1分钟的缓存有效期
            uwsgi_cache_valid 404 1m;

            # 对所有其他响应码设置5分钟的缓存有效期
            uwsgi_cache_valid any 5m;
        }
    }
}

设置统一的缓存有效期

如果我们希望对所有响应码设置相同的缓存有效期：

http {
    uwsgi_cache_path /tmp/uwsgicache levels=1:2 keys_zone=mycache:10m;

    server {
        listen 80;
        server_name example.com;

        location / {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_cache mycache;

            # 对所有响应码设置1小时的缓存有效期
            uwsgi_cache_valid any 1h;
        }
    }
}

注意事项

  • 缓存策略：根据实际需求设置合理的缓存有效期，确保缓存内容的新鲜度和有效性。
  • 性能优化：适当调整缓存有效期，可以显著提高性能并减少后端服务器负载。
uwsgi_connect_timeout

uwsgi_connect_timeout 指令用于设置 Nginx 与 uWSGI 服务器建立连接的超时时间。这有助于防止长时间等待导致的性能问题。

Syntax:	uwsgi_connect_timeout time;
Default: uwsgi_connect_timeout 60s;
Context: http, server, location
  • time：Nginx 与 uWSGI 服务器建立连接的超时时间，默认为 60 秒。

案例

基本用法

最简单的 uwsgi_connect_timeout 用法是指定连接超时时间：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 设置连接超时时间为 30 秒
            uwsgi_connect_timeout 30s;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 example.com 时，Nginx 将尝试在 30 秒内与 uWSGI 服务器建立连接。如果超过这个时间仍未成功连接，Nginx 将返回错误。

注意事项

  • 性能影响：过长的超时时间可能导致请求延迟，过短的超时时间可能导致频繁失败。
  • 可靠性：确保 uWSGI 服务器的可用性和响应速度，以避免不必要的超时。
uwsgi_force_ranges

uwsgi_force_ranges 指令用于强制启用对部分内容请求（Range Requests）的支持。这使得 Nginx 可以处理客户端的部分内容请求，即使 uWSGI 服务器未明确支持。

Syntax:	uwsgi_force_ranges on | off;
Default: uwsgi_force_ranges off;
Context: http, server, location
This directive appeared in version 1.7.7.
  • on：强制启用 Range Requests 支持。
  • off：不强制启用 Range Requests 支持，默认行为。

案例

基本用法

最简单的 uwsgi_force_ranges 用法是启用或禁用强制范围请求支持：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 强制启用 Range Requests 支持
            uwsgi_force_ranges on;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户发送部分内容请求时，Nginx 将处理这些请求并从 uWSGI 服务器获取相应的内容片段，即使 uWSGI 服务器本身未明确支持 Range Requests。

注意事项

  • 兼容性：确保应用程序能够正确处理部分内容请求，特别是在启用强制支持的情况下。
  • 性能优化：合理使用 Range Requests 可以提高大文件下载的用户体验，但也可能增加服务器负载。
uwsgi_hide_header

uwsgi_hide_header 指令用于隐藏来自 uWSGI 服务器响应中的特定 HTTP 头字段。这有助于控制传递给客户端的响应头信息。

Syntax:	uwsgi_hide_header field;
Default: —
Context: http, server, location
  • field：需要隐藏的 HTTP 头字段名称。

案例

基本用法

最简单的 uwsgi_hide_header 用法是指定要隐藏的响应头字段：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 隐藏 X-Powered-By 响应头
            uwsgi_hide_header X-Powered-By;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 uWSGI 服务器返回响应时，Nginx 将隐藏 X-Powered-By 响应头字段，使其不会传递给客户端。

注意事项

  • 安全性：隐藏敏感的响应头字段可以减少潜在的安全风险，如暴露技术栈信息。
  • 调试和监控：在开发和调试过程中，确保必要的响应头字段未被误隐藏。
uwsgi_ignore_client_abort

uwsgi_ignore_client_abort 指令用于控制当客户端中断连接时，Nginx 是否继续处理与 uWSGI 服务器的请求。这有助于提高后台任务的可靠性和完整性。

Syntax:	uwsgi_ignore_client_abort on | off;
Default: uwsgi_ignore_client_abort off;
Context: http, server, location
  • on：当客户端中断连接时，Nginx 继续处理与 uWSGI 服务器的请求。
  • off：当客户端中断连接时，Nginx 中止与 uWSGI 服务器的请求，默认行为。

案例

基本用法

最简单的 uwsgi_ignore_client_abort 用法是启用或禁用忽略客户端中断：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 启用忽略客户端中断
            uwsgi_ignore_client_abort on;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户中断连接时，Nginx 将继续处理与 uWSGI 服务器的请求，直到完成或遇到其他错误。

注意事项

  • 后台任务：对于需要保证执行完整性的后台任务（如数据导入/导出），启用该选项可以确保任务不会因客户端中断而终止。
  • 资源管理：注意不要滥用此选项，以免在高并发环境下占用过多资源。
uwsgi_ignore_headers

uwsgi_ignore_headers 用于指定哪些响应头不应传递给客户端。这有助于控制从 uwsgi 后端服务器返回的响应头，避免不必要的或潜在有害的头信息被传递。

Syntax: uwsgi_ignore_headers field ...;
Default: —
Context: http, server, location
  • field：指定一个或多个响应头字段名称，这些字段将不会传递给客户端。

案例

基本用法

最简单的 uwsgi_ignore_headers 用法是指定要忽略的响应头：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ignore_headers Set-Cookie X-Accel-Redirect;  # 忽略 Set-Cookie 和 X-Accel-Redirect 响应头
    }
}

在这个例子中，设置了 uwsgi_ignore_headers Set-Cookie X-Accel-Redirect，这意味着 Nginx 将不会将 Set-Cookie 和 X-Accel-Redirect 响应头传递给客户端。

多个响应头

根据实际需求忽略多个响应头：

server {
    listen 80;
    server_name example.com;

    location /ignore_multiple_headers/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ignore_headers Cache-Control Expires Pragma;  # 忽略多个响应头
    }

    location /ignore_single_header/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ignore_headers Server;  # 仅忽略 Server 响应头
    }
}

在这个例子中：

  • 对于 /ignore_multiple_headers/ 路径下的请求，忽略了 Cache-Control、Expires 和 Pragma 响应头。
  • 对于 /ignore_single_header/ 路径下的请求，仅忽略了 Server 响应头。

注意事项

  • 安全性：确保忽略不必要的响应头，以提高安全性并减少信息泄露。
  • 功能完整性：谨慎选择要忽略的响应头，确保不会影响应用的功能和性能。
uwsgi_intercept_errors

uwsgi_intercept_errors 用于控制是否拦截 uwsgi 后端返回的错误页面，并允许 Nginx 提供自定义的错误页面。这有助于提供一致的用户体验，并增强错误处理能力。

Syntax: uwsgi_intercept_errors on | off;
Default: uwsgi_intercept_errors off;
Context: http, server, location
  • on：启用错误拦截（Nginx 将处理后端返回的错误状态码）。
  • off：禁用错误拦截（默认行为，后端直接返回错误页面）。

案例

基本用法

最简单的 uwsgi_intercept_errors 用法是启用错误拦截：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_intercept_errors on;  # 启用错误拦截
        error_page 500 502 503 504 /50x.html;  # 定义自定义错误页面
    }
}

在这个例子中，启用了错误拦截，并指定了自定义的 5xx 错误页面 /50x.html。

禁用错误拦截

根据实际需求禁用错误拦截：

server {
    listen 80;
    server_name example.com;

    location /no_intercept/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_intercept_errors off;  # 禁用错误拦截
    }
}

在这个例子中，对于 /no_intercept/ 路径下的请求，禁用了错误拦截功能，后端直接返回错误页面。

注意事项

  • 用户体验：启用错误拦截可以提供更友好的用户界面，但需要确保自定义错误页面的设计合理。
  • 错误处理：结合 error_page 指令，定义合适的错误页面路径和内容。
uwsgi_limit_rate

uwsgi_limit_rate 用于限制从 uwsgi 后端传输到客户端的数据速率。这有助于控制带宽使用，特别是在高流量场景下。

Syntax: uwsgi_limit_rate rate;
Default: uwsgi_limit_rate 0;
Context: http, server, location
This directive appeared in version 1.7.7.
  • rate：指定数据传输速率（字节/秒）。默认值为 0，表示不限制速率。

案例

基本用法

最简单的 uwsgi_limit_rate 用法是指定传输速率：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_limit_rate 1024k;  # 限制传输速率为 1024 KB/s
    }
}

在这个例子中，设置了 uwsgi_limit_rate 1024k，这意味着传输速率限制为 1024 KB/s。

动态调整速率

根据实际需求动态调整传输速率：

server {
    listen 80;
    server_name example.com;

    location /low_rate/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_limit_rate 512k;  # 较低的传输速率
    }

    location /high_rate/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_limit_rate 2048k;  # 较高的传输速率
    }
}

在这个例子中：

  • 对于 /low_rate/ 路径下的请求，传输速率限制为 512 KB/s。
  • 对于 /high_rate/ 路径下的请求，传输速率限制为 2048 KB/s。

注意事项

  • 带宽管理：合理设置传输速率，确保既能满足应用需求，又不会过度占用带宽资源。
  • 用户体验：在高延迟或低带宽场景下，适当降低传输速率可能有助于改善用户体验。
uwsgi_max_temp_file_size

uwsgi_max_temp_file_size 用于设置 uwsgi 请求临时文件的最大大小。当 uwsgi 响应体超过此大小时，Nginx 将其写入临时文件而不是内存中。

Syntax: uwsgi_max_temp_file_size size;
Default: uwsgi_max_temp_file_size 1024m;
Context: http, server, location
  • size：指定临时文件的最大大小，默认值为 1024 MB。

案例

基本用法

最简单的 uwsgi_max_temp_file_size 用法是指定临时文件的最大大小：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_max_temp_file_size 512m;  # 设置临时文件最大大小为 512 MB
    }
}

在这个例子中，设置了 uwsgi_max_temp_file_size 512m，这意味着临时文件的最大大小为 512 MB。

调整临时文件大小

根据实际需求调整临时文件大小：

server {
    listen 80;
    server_name example.com;

    location /small_temp_files/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_max_temp_file_size 256m;  # 较小的临时文件大小
    }

    location /large_temp_files/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_max_temp_file_size 2048m;  # 较大的临时文件大小
    }
}

在这个例子中：

  • 对于 /small_temp_files/ 路径下的请求，临时文件的最大大小为 256 MB。
  • 对于 /large_temp_files/ 路径下的请求，临时文件的最大大小为 2048 MB。

注意事项

  • 内存管理：合理设置临时文件大小，避免因大响应体导致内存溢出或其他问题。
  • 磁盘使用：确保有足够的磁盘空间来存储临时文件，特别是在高负载情况下。
uwsgi_modifier1

uwsgi_modifier1 指令用于设置 UWSGI 协议的第一个修饰符（modifier1）。这个指令帮助定义请求如何被处理。

Syntax:	uwsgi_modifier1 number;
Default:	uwsgi_modifier1 0;
Context:	http, server, location
  • number：指定一个整数值作为第一个修饰符，默认为 0。

案例

基本用法

最简单的 uwsgi_modifier1 用法是指定一个具体的修饰符值：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_modifier1 1;
    }
}

在这个例子中：

  • 设置了 uwsgi_modifier1 1，这意味着Nginx将使用修饰符1来处理请求。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的修饰符值：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_modifier1 1;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_modifier1 2;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_modifier1 1。
  • 对于 example2.com，设置了 uwsgi_modifier1 2。

注意事项

  • 协议兼容性：确保设置的修饰符与UWSGI应用服务器的期望值一致，以避免通信问题。
  • 适用场景：适用于需要通过UWSGI协议传递特定信息的应用场景。例如，在需要自定义请求处理逻辑的复杂应用中使用。
  • 调试和监控：如果你遇到修饰符问题，可以检查以下几点：
    • 确保修饰符设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_modifier2

uwsgi_modifier2 指令用于设置 UWSGI 协议的第二个修饰符（modifier2）。这个指令进一步帮助定义请求如何被处理。

Syntax:	uwsgi_modifier2 number;
Default:	uwsgi_modifier2 0;
Context:	http, server, location
  • number：指定一个整数值作为第二个修饰符，默认为 0。

案例

基本用法

最简单的 uwsgi_modifier2 用法是指定一个具体的修饰符值：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_modifier2 1;
    }
}

在这个例子中：

  • 设置了 uwsgi_modifier2 1，这意味着Nginx将使用修饰符1来处理请求。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的修饰符值：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_modifier2 1;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_modifier2 2;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_modifier2 1。
  • 对于 example2.com，设置了 uwsgi_modifier2 2。

注意事项

  • 协议兼容性：确保设置的修饰符与UWSGI应用服务器的期望值一致，以避免通信问题。
  • 适用场景：适用于需要通过UWSGI协议传递更多特定信息的应用场景。例如，在需要更复杂的请求处理逻辑的高级应用中使用。
  • 调试和监控：如果你遇到修饰符问题，可以检查以下几点：
    • 确保修饰符设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_next_upstream

uwsgi_next_upstream 指令用于控制当出现某些错误时是否尝试转发到下一个上游服务器。这个指令帮助提高请求的成功率。

Syntax:	uwsgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:	uwsgi_next_upstream error timeout;
Context:	http, server, location
  • error：在发生错误时重试。
  • timeout：在超时时重试。
  • invalid_header：在接收到无效响应头时重试。
  • http_500：在接收HTTP 500响应时重试。
  • http_503：在接收HTTP 503响应时重试。
  • http_403：在接收HTTP 403响应时重试。
  • http_404：在接收HTTP 404响应时重试。
  • http_429：在接收HTTP 429响应时重试。
  • non_idempotent：允许对非幂等请求进行重试。
  • off：禁用重试功能。

案例

基本用法

最简单的 uwsgi_next_upstream 用法是指定哪些情况会触发重试：

upstream backend {
    server backend1.example.com;
    server backend2.example.com;
}

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_next_upstream error timeout http_500 http_503;
    }
}

在这个例子中：

  • 设置了 uwsgi_next_upstream error timeout http_500 http_503，这意味着Nginx将在发生错误、超时或接收到HTTP 500或503响应时重试。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的重试策略：

upstream backend_group1 {
    server backend1.example.com;
    server backend2.example.com;
}

upstream backend_group2 {
    server backend3.example.com;
    server backend4.example.com;
}

server {
    listen 80;
    server_name example.com;

    location /group1/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_group1.sock;
        uwsgi_next_upstream error timeout;
    }

    location /group2/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_group2.sock;
        uwsgi_next_upstream error timeout http_500 http_503;
    }
}

在这个例子中：

  • 对于 /group1/ 路径，设置了 uwsgi_next_upstream error timeout。
  • 对于 /group2/ 路径，设置了 uwsgi_next_upstream error timeout http_500 http_503。

注意事项

  • 重试策略：合理设置重试条件，避免不必要的重试影响性能或导致其他问题。
  • 适用场景：适用于需要提高请求成功率的应用场景。例如，在高可用性网站、API网关等环境中使用。
  • 调试和监控：如果你遇到重试策略问题，可以检查以下几点：
    • 确保重试条件设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_next_upstream_timeout

uwsgi_next_upstream_timeout 指令用于设置在尝试将请求传递给下一个上游服务器之前的最大等待时间。这个指令帮助控制请求在失败后重试其他上游服务器的超时时间。

Syntax:	uwsgi_next_upstream_timeout time;
Default:	uwsgi_next_upstream_timeout 0;
Context:	http, server, location
This directive appeared in version 1.7.5.
  • time：指定最大等待时间。如果设置为 0，则表示没有超时限制，默认值是 0。

案例

基本用法

最简单的 uwsgi_next_upstream_timeout 用法是指定一个具体的时间值：

http {
    upstream backend {
        server backend1.example.com;
        server backend2.example.com;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_next_upstream_timeout 5s;
        }
    }
}

在这个例子中：

  • 设置了 uwsgi_next_upstream_timeout 5s，这意味着Nginx将在尝试将请求传递给下一个上游服务器之前等待最多5秒。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的超时时间：

server {
    listen 80;
    server_name example1.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example1.sock;
        uwsgi_next_upstream_timeout 3s;
    }
}

server {
    listen 80;
    server_name example2.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi_example2.sock;
        uwsgi_next_upstream_timeout 10s;
    }
}

在这个例子中：

  • 对于 example1.com，设置了 uwsgi_next_upstream_timeout 3s。
  • 对于 example2.com，设置了 uwsgi_next_upstream_timeout 10s。

注意事项

  • 超时管理：合理设置最大等待时间，避免过长导致的请求阻塞或过短影响重试机制的有效性。
  • 适用场景：适用于需要在请求失败后自动重试其他上游服务器的应用场景。例如，在高可用性和负载均衡环境中使用。
  • 调试和监控：如果你遇到超时问题，可以检查以下几点：
    • 确保超时时间设置合理，并符合你的需求。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
    • 使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。
uwsgi_next_upstream_tries

uwsgi_next_upstream_tries 指令用于设置尝试将请求传递给下一个上游服务器的最大次数。

Syntax:	uwsgi_next_upstream_tries number;
Default:	uwsgi_next_upstream_tries 0;
Context:	http, server, location
This directive appeared in version 1.7.5.
  • number：指定最大尝试次数，默认值为 0（表示不限制）。

案例

基本用法

最简单的 uwsgi_next_upstream_tries 用法是指定最大尝试次数：

server {
    listen 80;
    server_name example.com;

    upstream backend {
        server backend1.example.com;
        server backend2.example.com;
        server backend3.example.com;
    }

    location /api/ {
        uwsgi_pass backend;
        include uwsgi_params;

        # 设置最多尝试 2 次将请求传递给下一个上游服务器
        uwsgi_next_upstream_tries 2;
    }
}

在这个例子中：

  • 最多尝试 2 次将请求传递给下一个上游服务器。

使用默认值

你可以选择使用默认值（不限制尝试次数）：

server {
    listen 80;
    server_name example.com;

    upstream backend {
        server backend1.example.com;
        server backend2.example.com;
        server backend3.example.com;
    }

    location /api/ {
        uwsgi_pass backend;
        include uwsgi_params;

        # 使用默认值（不限制尝试次数）
        uwsgi_next_upstream_tries 0;
    }
}

在这个例子中：

  • 不限制尝试次数（默认值）。

注意事项

  • 容错能力：合理设置最大尝试次数可以提高系统的容错能力，但过多的尝试可能会增加延迟。
  • 适用场景：适用于需要高可用性和容错能力的应用场景。例如，在负载均衡和故障转移场景中，适当设置最大尝试次数可以提高系统的稳定性。
  • 调试和监控：如果你遇到尝试次数问题，可以检查以下几点：
    • 确保数值设置合理，不会导致过多的重试或过早放弃。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_no_cache

uwsgi_no_cache 指令用于定义哪些条件下的响应不应被缓存。

Syntax:	uwsgi_no_cache string ...;
Default:	—
Context:	http, server, location
  • string：指定一个或多个条件表达式，满足这些条件时响应不应被缓存。

案例

基本用法

最简单的 uwsgi_no_cache 用法是指定不缓存的条件：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 当 $cookie_nocache 存在时不缓存响应
        uwsgi_no_cache $cookie_nocache;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 如果请求包含 $cookie_nocache 变量，则响应不会被缓存。

多个条件

你可以指定多个条件：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 当 $cookie_nocache 或 $arg_debug 存在时不缓存响应
        uwsgi_no_cache $cookie_nocache $arg_debug;

        uwsgi_cache my_cache;
    }
}

在这个例子中：

  • 如果请求包含 $cookie_nocache 或 $arg_debug 变量，则响应不会被缓存。

注意事项

  • 灵活性：通过设置不同的条件表达式，可以根据实际需求灵活地控制哪些响应不应被缓存。
  • 适用场景：适用于需要根据特定条件控制缓存行为的应用场景。例如，在处理用户登录状态或调试模式时，可能需要禁用缓存。
  • 调试和监控：如果你遇到不缓存条件问题，可以检查以下几点：
    • 确保条件表达式正确无误。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_param

uwsgi_param 指令用于向 uWSGI 服务器传递参数。

Syntax:	uwsgi_param parameter value [if_not_empty];
Default:	—
Context:	http, server, location
  • parameter：指定要传递的参数名称。
  • value：指定参数的值。
  • if_not_empty：可选参数，仅在值不为空时传递该参数。

案例

基本用法

最简单的 uwsgi_param 用法是传递一个参数：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 向 uWSGI 服务器传递自定义参数
        uwsgi_param CUSTOM_HEADER "CustomValue";
    }
}

在这个例子中：

  • 向 uWSGI 服务器传递了一个名为 CUSTOM_HEADER 的参数，其值为 CustomValue。

使用 if_not_empty 选项

你可以使用 if_not_empty 选项，仅在值不为空时传递参数：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 仅在值不为空时传递自定义参数
        uwsgi_param CUSTOM_HEADER $http_custom_header if_not_empty;
    }
}

在这个例子中：

  • 仅在 $http_custom_header 变量不为空时，才会向 uWSGI 服务器传递 CUSTOM_HEADER 参数。

注意事项

  • 参数传递：确保传递的参数与 uWSGI 应用的需求匹配，避免不必要的参数传递。
  • 适用场景：适用于需要在 Nginx 和 uWSGI 之间传递额外信息的应用场景。例如，在处理自定义 HTTP 头部或动态参数时，可以通过 uwsgi_param 进行传递。
  • 调试和监控：如果你遇到参数传递问题，可以检查以下几点：
    • 确保参数名称和值正确无误。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_pass

uwsgi_pass 指令用于指定 uWSGI 服务器的地址。

Syntax:	uwsgi_pass [protocol://]address;
Default:	—
Context:	location, if in location
  • protocol：可选参数，指定协议（通常为 unix:// 或 127.0.0.1:）。
  • address：指定 uWSGI 服务器的地址，可以是 Unix 套接字路径或 IP 地址加端口号。

案例

基本用法

最简单的 uwsgi_pass 用法是指定 uWSGI 服务器的地址：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        # 将请求转发到本地的 uWSGI 服务器，使用 Unix 套接字
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;
    }
}

在这个例子中：

  • 请求被转发到位于 /tmp/uwsgi.sock 的 uWSGI 服务器。

使用 IP 地址和端口

你也可以使用 IP 地址和端口：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        # 将请求转发到远程的 uWSGI 服务器
        uwsgi_pass 192.168.1.10:3031;
        include uwsgi_params;
    }
}

在这个例子中：

  • 请求被转发到 IP 地址为 192.168.1.10，端口号为 3031 的 uWSGI 服务器。

注意事项

  • 地址配置：确保 uWSGI 服务器的地址配置正确，并且具有适当的权限访问套接字或网络端口。
  • 适用场景：适用于需要将请求转发到 uWSGI 服务器的应用场景。例如，在部署 Python Web 应用时，通常会使用 uwsgi_pass 将请求转发到 uWSGI 服务器。
  • 调试和监控：如果你遇到转发地址问题，可以检查以下几点：
    • 确保套接字路径或 IP 地址和端口号正确无误。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_pass_header

uwsgi_pass_header 指令用于指定哪些请求头字段应该传递给后端的 uWSGI 服务器。这对于在某些情况下需要控制哪些头部信息传递到后端非常有用。

Syntax:	uwsgi_pass_header field;
Default:	—
Context:	http, server, location
  • field：指定要传递的请求头字段名称。

案例

基本用法

假设我们希望将特定的请求头字段（如 X-Custom-Header）传递给后端的 uWSGI 服务器：

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

        location /custom {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 传递 X-Custom-Header 请求头
            uwsgi_pass_header X-Custom-Header;
        }
    }
}

在这个例子中，uwsgi_pass_header X-Custom-Header; 确保了 X-Custom-Header 请求头会被传递给后端的 uWSGI 服务器。

注意事项

  • 安全性：确保只传递必要的请求头字段，避免泄露敏感信息。
  • 灵活性：可以根据具体需求灵活配置需要传递的请求头字段。
uwsgi_pass_request_body

uwsgi_pass_request_body 指令用于控制是否将请求体传递给后端的 uWSGI 服务器。这对于处理某些特殊场景（如上传文件或大请求体时）非常有用。

Syntax:	uwsgi_pass_request_body on | off;
Default:	uwsgi_pass_request_body on;
Context:	http, server, location
  • on（默认）：将请求体传递给后端的 uWSGI 服务器。
  • off：不将请求体传递给后端的 uWSGI 服务器。

案例

启用请求体传递

假设我们希望将请求体传递给后端的 uWSGI 服务器：

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

        location /upload {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 默认行为，启用请求体传递
            uwsgi_pass_request_body on;
        }
    }
}

禁用请求体传递

如果我们不希望将请求体传递给后端的 uWSGI 服务器：

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

        location /no-body {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 禁用请求体传递
            uwsgi_pass_request_body off;
        }
    }
}

注意事项

  • 性能影响：禁用请求体传递可以减少网络传输的数据量，但可能导致后端无法正确处理请求。
  • 适用场景：适用于不需要请求体的场景，如健康检查或简单的状态查询。
uwsgi_pass_request_headers

uwsgi_pass_request_headers 指令用于控制是否将请求头传递给后端的 uWSGI 服务器。这对于处理某些特殊场景（如自定义请求头过滤）非常有用。

Syntax:	uwsgi_pass_request_headers on | off;
Default:	uwsgi_pass_request_headers on;
Context:	http, server, location
  • on（默认）：将请求头传递给后端的 uWSGI 服务器。
  • off：不将请求头传递给后端的 uWSGI 服务器。

案例

启用请求头传递

假设我们希望将请求头传递给后端的 uWSGI 服务器：

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

        location /default {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 默认行为，启用请求头传递
            uwsgi_pass_request_headers on;
        }
    }
}

禁用请求头传递

如果我们不希望将请求头传递给后端的 uWSGI 服务器：

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

        location /no-headers {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 禁用请求头传递
            uwsgi_pass_request_headers off;
        }
    }
}

注意事项

  • 安全性：禁用请求头传递可以防止潜在的安全风险，特别是当请求头包含敏感信息时。
  • 灵活性：可以根据具体需求灵活配置是否传递请求头。
uwsgi_read_timeout

uwsgi_read_timeout 指令用于设置从后端 uWSGI 服务器读取响应的超时时间。这对于确保请求不会因为后端响应过慢而长时间挂起非常有用。

Syntax:	uwsgi_read_timeout time;
Default:	uwsgi_read_timeout 60s;
Context:	http, server, location
  • time：指定超时时间，格式为 time[units]，例如 60s 表示60秒。

案例

设置较长的超时时间

假设我们希望设置较长的超时时间为120秒（2分钟）：

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

        location /long-processing {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 设置120秒的读取超时时间
            uwsgi_read_timeout 120s;
        }
    }
}

使用默认超时时间

如果我们希望使用默认的60秒超时时间：

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

        location /default-timeout {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 使用默认的60秒超时时间
            uwsgi_read_timeout 60s;
        }
    }
}

注意事项

  • 性能优化：适当调整超时时间，可以在保证响应速度的同时避免不必要的等待。
  • 用户体验：过长的超时时间可能导致用户长时间等待，需根据实际业务需求进行调整。
uwsgi_request_buffering

uwsgi_request_buffering 指令用于控制是否启用客户端请求的缓冲功能。这有助于提高性能，但可能会影响实时性。

Syntax:	uwsgi_request_buffering on | off;
Default: uwsgi_request_buffering on;
Context: http, server, location
This directive appeared in version 1.7.11.
  • on：启用客户端请求的缓冲功能，默认行为。
  • off：禁用客户端请求的缓冲功能。

案例

基本用法

最简单的 uwsgi_request_buffering 用法是启用或禁用请求缓冲功能：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 禁用请求缓冲功能
            uwsgi_request_buffering off;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 example.com 时，Nginx 将直接将客户端请求传递给 uWSGI 服务器，而不进行缓冲。

注意事项

  • 性能与实时性：启用缓冲功能可以提高性能，但在某些情况下（如实时应用）可能需要禁用缓冲。
  • 资源管理：禁用缓冲功能可能导致更高的内存和 CPU 使用率，特别是在处理大数据量请求时。
uwsgi_send_timeout

uwsgi_send_timeout 指令用于设置 Nginx 向 uWSGI 服务器发送请求的超时时间。这有助于防止长时间等待导致的性能问题。

Syntax:	uwsgi_send_timeout time;
Default: uwsgi_send_timeout 60s;
Context: http, server, location
  • time：Nginx 向 uWSGI 服务器发送请求的超时时间，默认为 60 秒。

案例

基本用法

最简单的 uwsgi_send_timeout 用法是指定发送超时时间：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 设置发送超时时间为 30 秒
            uwsgi_send_timeout 30s;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 example.com 时，Nginx 将尝试在 30 秒内向 uWSGI 服务器发送请求。如果超过这个时间仍未成功发送，Nginx 将返回错误。

注意事项

  • 性能影响：过长的超时时间可能导致请求延迟，过短的超时时间可能导致频繁失败。
  • 可靠性：确保 uWSGI 服务器的可用性和响应速度，以避免不必要的超时。
uwsgi_socket_keepalive

uwsgi_socket_keepalive 指令用于控制是否启用与 uWSGI 服务器之间的套接字保持连接（Keep-Alive）。这有助于减少建立新连接的开销。

Syntax:	uwsgi_socket_keepalive on | off;
Default: uwsgi_socket_keepalive off;
Context: http, server, location
This directive appeared in version 1.15.6.
  • on：启用与 uWSGI 服务器之间的套接字保持连接。
  • off：不启用与 uWSGI 服务器之间的套接字保持连接，默认行为。

案例

基本用法

最简单的 uwsgi_socket_keepalive 用法是启用或禁用套接字保持连接：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            # 启用套接字保持连接
            uwsgi_socket_keepalive on;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 Nginx 与 uWSGI 服务器通信时，将使用 Keep-Alive 连接，从而减少每次请求建立新连接的开销。

注意事项

  • 性能优化：启用套接字保持连接可以显著提高性能，尤其是在高并发环境下。
  • 资源管理：注意不要滥用此选项，以免在高负载下占用过多资源。
uwsgi_ssl_certificate

uwsgi_ssl_certificate 指令用于指定用于与 uWSGI 服务器进行 SSL/TLS 通信的证书文件路径。这有助于确保安全的通信通道。

Syntax:	uwsgi_ssl_certificate file;
Default: —
Context: http, server, location
This directive appeared in version 1.7.8.
  • file：SSL/TLS 证书文件的路径。

案例

基本用法

最简单的 uwsgi_ssl_certificate 用法是指定 SSL/TLS 证书文件的路径：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031 ssl;
    }

    server {
        listen 443 ssl;
        server_name example.com;

        ssl_certificate /etc/nginx/ssl/example.crt;
        ssl_certificate_key /etc/nginx/ssl/example.key;

        location / {
            # 指定用于与 uWSGI 服务器进行 SSL/TLS 通信的证书文件路径
            uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi_example.crt;
            uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi_example.key;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 Nginx 与 uWSGI 服务器通过 SSL/TLS 进行通信时，将使用 /etc/nginx/ssl/uwsgi_example.crt 作为证书文件。

注意事项

  • 安全性：确保证书文件的安全性，防止未经授权的访问。
  • 证书有效性：定期检查并更新证书，确保其有效性和可信度。
uwsgi_ssl_certificate_cache

uwsgi_ssl_certificate_cache 用于控制 uwsgi SSL 证书的缓存行为。这有助于提高 SSL/TLS 握手的效率，特别是在频繁使用相同证书的情况下。

Syntax: uwsgi_ssl_certificate_cache off;
        uwsgi_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: uwsgi_ssl_certificate_cache off;
Context: http, server, location
This directive appeared in version 1.27.4.
  • off：禁用证书缓存（默认行为）。
  • max=N：指定缓存的最大条目数。
  • [inactive=time]：可选参数，指定条目在未被访问的时间超过指定时间后将被移除（如 10m 表示 10 分钟）。
  • [valid=time]：可选参数，指定条目的有效时间（如 1h 表示 1 小时）。

案例

基本用法

最简单的 uwsgi_ssl_certificate_cache 用法是启用证书缓存并设置最大条目数：

http {
    uwsgi_ssl_certificate_cache max=1000 inactive=10m valid=1h;  # 启用证书缓存，并设置相关参数

    server {
        listen 80;
        server_name example.com;

        location / {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_ssl_certificate_cache max=1000 inactive=10m valid=1h;  # 在 location 中启用证书缓存
        }
    }
}

在这个例子中，设置了证书缓存的最大条目数为 1000，条目在未被访问超过 10 分钟后将被移除，且条目的有效时间为 1 小时。

禁用证书缓存

根据实际需求禁用证书缓存：

server {
    listen 80;
    server_name example.com;

    location /no_cert_cache/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_certificate_cache off;  # 禁用证书缓存
    }
}

在这个例子中，对于 /no_cert_cache/ 路径下的请求，禁用了证书缓存功能。

注意事项

  • 性能优化：合理设置缓存大小和有效期，确保既能提高性能，又不会占用过多内存资源。
  • 安全性：定期更新证书，并确保缓存中的证书保持最新状态。
uwsgi_ssl_certificate_key

uwsgi_ssl_certificate_key 用于指定 uwsgi SSL 连接使用的私钥文件路径。这有助于配置 SSL/TLS 安全连接。

Syntax: uwsgi_ssl_certificate_key file;
Default: —
Context: http, server, location
This directive appeared in version 1.7.8.
  • file：指定包含私钥的文件路径。

案例

基本用法

最简单的 uwsgi_ssl_certificate_key 用法是指定私钥文件路径：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;  # 指定私钥文件路径

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
    }
}

在这个例子中，指定了私钥文件路径 /etc/nginx/ssl/example.key。

多个私钥文件

根据实际需求指定不同的私钥文件：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    location /secure_endpoint/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/example_secure.key;  # 特定路径的私钥文件
    }

    location /default_endpoint/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;  # 默认路径的私钥文件
    }
}

在这个例子中：

  • 对于 /secure_endpoint/ 路径下的请求，使用了特定路径的私钥文件 /etc/nginx/ssl/example_secure.key。
  • 对于 /default_endpoint/ 路径下的请求，使用了默认路径的私钥文件 /etc/nginx/ssl/example.key。

注意事项

  • 安全性：确保私钥文件的安全性，避免未经授权的访问。
  • 正确配置：确保私钥文件与对应的证书文件匹配，以避免 SSL 配置错误。
uwsgi_ssl_ciphers

uwsgi_ssl_ciphers 用于指定 uwsgi SSL 连接允许的加密套件列表。这有助于增强 SSL/TLS 连接的安全性。

Syntax: uwsgi_ssl_ciphers ciphers;
Default: uwsgi_ssl_ciphers DEFAULT;
Context: http, server, location
This directive appeared in version 1.5.8.
  • ciphers：指定一个或多个加密套件名称，使用冒号分隔。

案例

基本用法

最简单的 uwsgi_ssl_ciphers 用法是指定加密套件列表：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;
    uwsgi_ssl_ciphers HIGH:!aNULL:!MD5;  # 指定加密套件列表

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
    }
}

在这个例子中，设置了加密套件列表为 HIGH:!aNULL:!MD5，这意味着只允许高安全性的加密套件，并排除匿名 Diffie-Hellman 和 MD5 加密算法。

自定义加密套件

根据实际需求自定义加密套件列表：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;

    location /strong_security/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384;  # 强加密套件
    }

    location /default_security/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_ciphers DEFAULT;  # 默认加密套件
    }
}

在这个例子中：

  • 对于 /strong_security/ 路径下的请求，使用了强加密套件。
  • 对于 /default_security/ 路径下的请求，使用了默认加密套件。

注意事项

  • 安全性：选择合适的加密套件列表，确保连接的安全性。
  • 兼容性：确保所选加密套件与客户端兼容，避免不必要的连接失败。
uwsgi_ssl_conf_command

uwsgi_ssl_conf_command 用于向 OpenSSL 发送额外的配置命令。这有助于更细粒度地控制 SSL/TLS 配置。

Syntax: uwsgi_ssl_conf_command name value;
Default: —
Context: http, server, location
This directive appeared in version 1.19.4.
  • name：指定 OpenSSL 配置命令的名称。
  • value：指定 OpenSSL 配置命令的值。

案例

基本用法

最简单的 uwsgi_ssl_conf_command 用法是指定 OpenSSL 配置命令及其值：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;
    uwsgi_ssl_conf_command Options Mode=TLSv1.2;  # 设置 OpenSSL 配置命令

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
    }
}

在这个例子中，设置了 OpenSSL 配置命令 Options Mode=TLSv1.2，这意味着强制使用 TLS 1.2 协议。

多个配置命令

根据实际需求添加多个 OpenSSL 配置命令：

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/ssl/example.crt;
    uwsgi_ssl_certificate_key /etc/nginx/ssl/example.key;

    location /custom_tls_settings/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_conf_command Options Mode=TLSv1.2;  # 强制使用 TLS 1.2
        uwsgi_ssl_conf_command CipherString DOWNGRADE_SERVER;  # 设置降级服务器策略
    }

    location /default_tls_settings/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_ssl_conf_command Options Mode=TLSv1.3;  # 强制使用 TLS 1.3
    }
}

在这个例子中：

  • 对于 /custom_tls_settings/ 路径下的请求，设置了强制使用 TLS 1.2 和降级服务器策略。
  • 对于 /default_tls_settings/ 路径下的请求，设置了强制使用 TLS 1.3。

注意事项

  • 细粒度控制：通过 uwsgi_ssl_conf_command 可以进行更细粒度的 SSL/TLS 控制，但需要谨慎使用，以免影响连接的兼容性和安全性。
  • OpenSSL 文档：参考 OpenSSL 的官方文档，了解可用的配置命令及其作用。
uwsgi_ssl_crl

uwsgi_ssl_crl 指令用于指定包含吊销证书列表（CRL）的文件路径。

Syntax:	uwsgi_ssl_crl file;
Default:	—
Context:	http, server, location
This directive appeared in version 1.7.0.
  • file：指定包含 CRL 的文件路径。

案例

基本用法

最简单的 uwsgi_ssl_crl 用法是指定包含 CRL 的文件路径：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 启用 SSL 并指定 CRL 文件
        uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi.crt;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi.key;
        uwsgi_ssl_crl /etc/nginx/ssl/crl.pem;
    }
}

在这个例子中：

  • 使用 /etc/nginx/ssl/crl.pem 文件作为 CRL 文件，以确保连接到 uWSGI 服务器时验证客户端证书的有效性。

注意事项

  • 安全性：确保 CRL 文件是最新的，并定期更新以保持系统的安全性。
  • 适用场景：适用于需要对客户端证书进行严格验证的应用场景。例如，在企业级应用或需要高安全性的环境中，使用 CRL 可以防止使用已吊销的证书。
  • 调试和监控：如果你遇到 CRL 文件问题，可以检查以下几点：
    • 确保文件路径正确且具有适当的权限。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_ssl_key_log

uwsgi_ssl_key_log 指令用于指定记录 SSL 私钥材料的日志文件路径。

Syntax:	uwsgi_ssl_key_log path;
Default:	—
Context:	http, server, location
This directive appeared in version 1.27.2.
  • path：指定日志文件的路径。

案例

基本用法

最简单的 uwsgi_ssl_key_log 用法是指定日志文件的路径：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 启用 SSL 并指定私钥日志文件
        uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi.crt;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi.key;
        uwsgi_ssl_key_log /var/log/nginx/uwsgi_ssl_key.log;
    }
}

在这个例子中：

  • 将 SSL 私钥材料记录到 /var/log/nginx/uwsgi_ssl_key.log 文件中。

注意事项

  • 安全性：确保私钥日志文件存储在一个安全的位置，并限制访问权限，以防止敏感信息泄露。
  • 适用场景：适用于需要调试 SSL/TLS 连接或分析 SSL 私钥材料的应用场景。例如，在开发和测试阶段，记录私钥材料可以帮助排查连接问题。
  • 调试和监控：如果你遇到私钥日志文件问题，可以检查以下几点：
    • 确保文件路径正确且具有适当的权限。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_ssl_name

uwsgi_ssl_name 指令用于指定用于 SSL 握手的主机名。

Syntax:	uwsgi_ssl_name name;
Default:	uwsgi_ssl_name host from uwsgi_pass;
Context:	http, server, location
This directive appeared in version 1.7.0.
  • name：指定用于 SSL 握手的主机名，默认值为从 uwsgi_pass 中提取的主机名。

案例

基本用法

最简单的 uwsgi_ssl_name 用法是指定用于 SSL 握手的主机名：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 启用 SSL 并指定用于 SSL 握手的主机名
        uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi.crt;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi.key;
        uwsgi_ssl_name backend.example.com;
    }
}

在这个例子中：

  • 使用 backend.example.com 作为用于 SSL 握手的主机名。

使用默认值

你可以选择使用默认值（从 uwsgi_pass 提取的主机名）：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 启用 SSL 并使用默认的主机名
        uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi.crt;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi.key;
    }
}

在这个例子中：

  • 使用从 uwsgi_pass 提取的主机名作为用于 SSL 握手的主机名（默认值）。

注意事项

  • 主机名匹配：确保指定的主机名与 SSL 证书中的主机名匹配，以避免 SSL 验证失败。
  • 适用场景：适用于需要明确指定用于 SSL 握手的主机名的应用场景。例如，在多域名或多服务器环境中，明确指定主机名可以确保正确的 SSL 配置。
  • 调试和监控：如果你遇到主机名问题，可以检查以下几点：
    • 确保主机名正确无误，并与 SSL 证书中的主机名匹配。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_ssl_password_file

uwsgi_ssl_password_file 指令用于指定包含 SSL 私钥密码的文件路径。

Syntax:	uwsgi_ssl_password_file file;
Default:	—
Context:	http, server, location
This directive appeared in version 1.7.8.
  • file：指定包含 SSL 私钥密码的文件路径。

案例

基本用法

最简单的 uwsgi_ssl_password_file 用法是指定包含私钥密码的文件路径：

server {
    listen 80;
    server_name example.com;

    location /api/ {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

        # 启用 SSL 并指定私钥密码文件
        uwsgi_ssl_certificate /etc/nginx/ssl/uwsgi.crt;
        uwsgi_ssl_certificate_key /etc/nginx/ssl/uwsgi.key;
        uwsgi_ssl_password_file /etc/nginx/ssl/uwsgi_password.txt;
    }
}

在这个例子中：

  • 使用 /etc/nginx/ssl/uwsgi_password.txt 文件中的密码来解密 SSL 私钥。

注意事项

  • 安全性：确保私钥密码文件存储在一个安全的位置，并限制访问权限，以防止密码泄露。
  • 适用场景：适用于需要加密私钥并使用密码保护的应用场景。例如，在生产环境中，使用加密的私钥和密码可以增加额外的安全层。
  • 调试和监控：如果你遇到私钥密码文件问题，可以检查以下几点：
    • 确保文件路径正确且具有适当的权限。
    • 查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。
uwsgi_ssl_protocols

uwsgi_ssl_protocols 指令用于指定允许的SSL/TLS协议版本。这有助于确保与后端 uWSGI 服务器之间的通信安全，通过禁用不安全的协议版本来减少潜在的安全风险。

Syntax:	uwsgi_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:	uwsgi_ssl_protocols TLSv1.2 TLSv1.3;
Context:	http, server, location
This directive appeared in version 1.5.8.
  • [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]：指定允许使用的SSL/TLS协议版本，默认为 TLSv1.2 和 TLSv1.3。

案例

启用特定的SSL/TLS协议版本

假设我们希望仅启用 TLSv1.2 和 TLSv1.3 协议：

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

        location /secure {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 仅启用 TLSv1.2 和 TLSv1.3 协议
            uwsgi_ssl_protocols TLSv1.2 TLSv1.3;
        }
    }
}

禁用所有旧版本的协议

如果我们希望禁用所有旧版本的协议（如 SSLv2, SSLv3, TLSv1, TLSv1.1），仅使用最新的协议版本：

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

        location /latest {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 仅启用最新的 TLSv1.3 协议
            uwsgi_ssl_protocols TLSv1.3;
        }
    }
}

注意事项

  • 安全性：建议禁用不安全的旧版本协议（如 SSLv2, SSLv3, TLSv1, TLSv1.1），以防止中间人攻击和其他安全漏洞。
  • 兼容性：确保后端服务器支持所需的TLS版本，避免因不兼容导致连接失败。
uwsgi_ssl_server_name

uwsgi_ssl_server_name 指令用于控制是否在与后端 uWSGI 服务器建立SSL连接时发送服务器名称指示（SNI）。这对于多域名环境中的正确SSL证书匹配非常有用。

Syntax:	uwsgi_ssl_server_name on | off;
Default:	uwsgi_ssl_server_name off;
Context:	http, server, location
This directive appeared in version 1.7.0.
  • on：启用SNI，将在SSL握手时发送服务器名称。
  • off（默认）：禁用SNI，不会发送服务器名称。

案例

启用SNI

假设我们在一个多域名环境中需要启用SNI：

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

        location /secure {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 启用SNI
            uwsgi_ssl_server_name on;
        }
    }
}

禁用SNI

如果我们不需要或不希望发送服务器名称：

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

        location /no-sni {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 禁用SNI
            uwsgi_ssl_server_name off;
        }
    }
}

注意事项

  • 多域名支持：在多域名环境下，启用SNI可以确保正确的SSL证书匹配，避免证书错误。
  • 兼容性：确保后端服务器支持SNI，特别是在处理多个域名时。
uwsgi_ssl_session_reuse

uwsgi_ssl_session_reuse 指令用于控制是否重用SSL会话。这可以显著提高性能，尤其是在高并发场景下。

Syntax:	uwsgi_ssl_session_reuse on | off;
Default:	uwsgi_ssl_session_reuse on;
Context:	http, server, location
This directive appeared in version 1.5.8.
  • on（默认）：启用SSL会话重用。
  • off：禁用SSL会话重用。

案例

启用会话重用

假设我们希望启用SSL会话重用以提高性能：

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

        location /secure {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 启用SSL会话重用
            uwsgi_ssl_session_reuse on;
        }
    }
}

禁用会话重用

如果我们出于某些原因（如调试或测试）需要禁用SSL会话重用：

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

        location /no-reuse {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 禁用SSL会话重用
            uwsgi_ssl_session_reuse off;
        }
    }
}

注意事项

  • 性能优化：启用SSL会话重用可以显著减少SSL握手的时间，提高性能。
  • 安全性：在某些情况下，禁用会话重用可能有助于缓解特定的安全问题，但通常应保持启用状态。
uwsgi_ssl_trusted_certificate

uwsgi_ssl_trusted_certificate 指令用于指定信任的CA证书文件路径。这对于验证后端 uWSGI 服务器的SSL证书非常有用，确保通信的安全性。

Syntax:	uwsgi_ssl_trusted_certificate file;
Default:	—
Context:	http, server, location
This directive appeared in version 1.7.0.
  • file：指定包含信任的CA证书的文件路径。

案例

配置信任的CA证书

假设我们需要配置一个信任的CA证书文件 /etc/nginx/trusted_ca.crt：

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

        location /secure {
            uwsgi_pass unix:/tmp/uwsgi.sock;
            include uwsgi_params;

            # 配置信任的CA证书文件
            uwsgi_ssl_trusted_certificate /etc/nginx/trusted_ca.crt;
        }
    }
}

注意事项

  • 安全性：确保配置的CA证书文件是可信的，以防止中间人攻击。
  • 路径管理：确保提供的文件路径正确且Nginx进程有权限读取该文件。
uwsgi_ssl_verify

uwsgi_ssl_verify 指令用于控制是否启用对 uWSGI 服务器 SSL/TLS 证书的验证。这有助于确保与 uWSGI 服务器的安全通信。

Syntax:	uwsgi_ssl_verify on | off;
Default: uwsgi_ssl_verify off;
Context: http, server, location
This directive appeared in version 1.7.0.
  • on：启用对 uWSGI 服务器 SSL/TLS 证书的验证。
  • off：禁用对 uWSGI 服务器 SSL/TLS 证书的验证，默认行为。

案例

基本用法

最简单的 uwsgi_ssl_verify 用法是启用或禁用 SSL/TLS 证书验证：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031 ssl;
    }

    server {
        listen 443 ssl;
        server_name example.com;

        ssl_certificate /etc/nginx/ssl/example.crt;
        ssl_certificate_key /etc/nginx/ssl/example.key;

        location / {
            # 启用对 uWSGI 服务器 SSL/TLS 证书的验证
            uwsgi_ssl_verify on;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 Nginx 与 uWSGI 服务器通过 SSL/TLS 进行通信时，将验证 uWSGI 服务器提供的 SSL/TLS 证书的有效性。

注意事项

  • 安全性：启用证书验证可以防止中间人攻击（MITM），但在开发环境中可能会因为自签名证书等原因导致验证失败。
  • 配置要求：确保正确的 CA 证书路径和配置，以便成功验证 uWSGI 服务器的证书。
uwsgi_ssl_verify_depth

uwsgi_ssl_verify_depth 指令用于设置 SSL/TLS 证书链验证的最大深度。这有助于控制证书链验证的范围。

Syntax:	uwsgi_ssl_verify_depth number;
Default: uwsgi_ssl_verify_depth 1;
Context: http, server, location
This directive appeared in version 1.7.0.
  • number：SSL/TLS 证书链验证的最大深度，默认为 1。

案例

基本用法

最简单的 uwsgi_ssl_verify_depth 用法是指定证书链验证的最大深度：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031 ssl;
    }

    server {
        listen 443 ssl;
        server_name example.com;

        ssl_certificate /etc/nginx/ssl/example.crt;
        ssl_certificate_key /etc/nginx/ssl/example.key;

        location / {
            # 设置 SSL/TLS 证书链验证的最大深度为 3
            uwsgi_ssl_verify on;
            uwsgi_ssl_verify_depth 3;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 Nginx 验证 uWSGI 服务器的 SSL/TLS 证书时，允许的最大证书链深度为 3。

注意事项

  • 证书链长度：根据实际使用的证书链长度合理设置验证深度，避免因深度不足而导致验证失败。
  • 性能考虑：增加验证深度可能会增加验证时间，特别是在高并发环境下。
uwsgi_store

uwsgi_store 指令用于控制是否将 uWSGI 服务器响应的内容存储到本地文件系统中。这有助于缓存动态内容或保存上传文件。

Syntax:	uwsgi_store on | off | string;
Default: uwsgi_store off;
Context: http, server, location
  • on：启用存储功能，存储路径基于 uwsgi_store_path 指令。
  • off：禁用存储功能，默认行为。
  • string：指定存储路径，支持变量（如 $request_filename）。

案例

基本用法

最简单的 uwsgi_store 用法是启用或禁用存储功能：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location /downloads {
            # 启用存储功能并将响应存储到 /var/www/downloads 目录下
            uwsgi_store on;
            uwsgi_store_path /var/www/downloads;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当用户访问 /downloads 路径时，Nginx 将 uWSGI 服务器的响应内容存储到 /var/www/downloads 目录下。

注意事项

  • 存储路径：确保指定的存储路径存在并且 Nginx 对其具有写权限。
  • 资源管理：注意不要滥用此选项，以免占用过多磁盘空间。
uwsgi_store_access

uwsgi_store_access 指令用于设置存储文件的访问权限。这有助于控制谁可以读取或修改存储的文件。

Syntax:	uwsgi_store_access users:permissions ...;
Default: uwsgi_store_access user:rw;
Context: http, server, location
  • users:permissions：指定哪些用户或用户组可以访问存储的文件以及他们的权限。例如 user:rw 表示文件所有者具有读写权限。

案例

基本用法

最简单的 uwsgi_store_access 用法是指定存储文件的访问权限：

http {
    upstream uwsgi_backend {
        server 127.0.0.1:3031;
    }

    server {
        listen 80;
        server_name example.com;

        location /downloads {
            # 启用存储功能并将响应存储到 /var/www/downloads 目录下
            uwsgi_store on;
            uwsgi_store_path /var/www/downloads;

            # 设置存储文件的访问权限为文件所有者读写，组和其他用户只读
            uwsgi_store_access user:rw group:r others:r;

            uwsgi_pass uwsgi_backend;
        }
    }
}

在这个例子中：

  • 当 uWSGI 服务器的响应内容被存储到 /var/www/downloads 目录下时，文件的所有者具有读写权限，而组和其他用户只有读权限。

注意事项

  • 权限设置：根据实际需求合理设置文件的访问权限，确保安全性和可用性的平衡。
  • 文件管理：定期检查和清理存储目录，避免不必要的文件积累。
uwsgi_temp_file_write_size

uwsgi_temp_file_write_size 用于设置在处理 uwsgi 响应时，写入临时文件的最大块大小。这有助于控制内存使用和优化性能，特别是在处理大响应体时。

Syntax: uwsgi_temp_file_write_size size;
Default: uwsgi_temp_file_write_size 8k|16k;
Context: http, server, location
  • size：指定每次写入临时文件的最大块大小，默认值为 8KB 或 16KB（取决于平台）。

案例

基本用法

最简单的 uwsgi_temp_file_write_size 用法是指定写入块大小：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_file_write_size 16k;  # 设置每次写入块大小为 16KB
    }
}

在这个例子中，设置了 uwsgi_temp_file_write_size 16k，这意味着每次写入临时文件的最大块大小为 16KB。

调整写入块大小

根据实际需求调整写入块大小：

server {
    listen 80;
    server_name example.com;

    location /small_chunk/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_file_write_size 8k;  # 较小的写入块大小
    }

    location /large_chunk/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_file_write_size 32k;  # 较大的写入块大小
    }
}

在这个例子中：

  • 对于 /small_chunk/ 路径下的请求，设置了较小的写入块大小（8KB）。
  • 对于 /large_chunk/ 路径下的请求，设置了较大的写入块大小（32KB）。

注意事项

  • 性能优化：合理设置写入块大小，确保既能满足应用需求，又不会浪费资源。
  • 应用场景：根据具体的应用场景选择合适的写入块大小，例如高并发或大响应体场景下可能需要更大的写入块大小。
uwsgi_temp_path

uwsgi_temp_path 用于指定存储 uwsgi 临时文件的目录路径，并可配置多级子目录结构。这有助于更好地管理临时文件，避免单个目录下文件过多导致的性能问题。

Syntax: uwsgi_temp_path path [level1 [level2 [level3]]];
Default: uwsgi_temp_path uwsgi_temp;
Context: http, server, location
  • path：指定临时文件存储的根目录。
  • [level1 [level2 [level3]]]：可选参数，指定多级子目录结构的深度和每级的哈希位数（如 1:2:2 表示第一级目录有 2 位哈希，第二级和第三级各有 2 位哈希）。

案例

基本用法

最简单的 uwsgi_temp_path 用法是指定临时文件存储路径：

server {
    listen 80;
    server_name example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_path /var/tmp/nginx/uwsgi_temp;  # 指定临时文件存储路径
    }
}

在这个例子中，指定了临时文件存储路径为 /var/tmp/nginx/uwsgi_temp。

配置多级子目录

根据实际需求配置多级子目录结构：

server {
    listen 80;
    server_name example.com;

    location /single_level/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_path /var/tmp/nginx/uwsgi_temp 1;  # 单级子目录结构
    }

    location /multi_level/ {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/uwsgi.sock;
        uwsgi_temp_path /var/tmp/nginx/uwsgi_temp 1:2:2;  # 多级子目录结构
    }
}

在这个例子中：

  • 对于 /single_level/ 路径下的请求，设置了单级子目录结构，每级目录有 1 位哈希。
  • 对于 /multi_level/ 路径下的请求，设置了多级子目录结构，第一级目录有 2 位哈希，第二级和第三级各有 2 位哈希。

完整配置示例

结合多个指令进行完整配置：

http {
    uwsgi_temp_path /var/tmp/nginx/uwsgi_temp 1:2:2;  # 全局配置，适用于所有服务器和位置块

    server {
        listen 80;
        server_name example.com;

        location /default_temp_path/ {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_temp_file_write_size 16k;  # 设置每次写入块大小为 16KB
        }

        location /custom_temp_path/ {
            include uwsgi_params;
            uwsgi_pass unix:/tmp/uwsgi.sock;
            uwsgi_temp_path /var/tmp/nginx/custom_uwsgi_temp 1:2:2;  # 自定义临时文件存储路径和子目录结构
            uwsgi_temp_file_write_size 32k;  # 设置每次写入块大小为 32KB
        }
    }
}

在这个例子中：

  • 对于 /default_temp_path/ 路径下的请求，使用了全局配置的临时文件存储路径和默认写入块大小。
  • 对于 /custom_temp_path/ 路径下的请求，使用了自定义的临时文件存储路径 /var/tmp/nginx/custom_uwsgi_temp 和多级子目录结构 1:2:2，并设置了写入块大小为 32KB。

注意事项

  • 文件管理：合理配置临时文件路径和子目录结构，避免单个目录下文件过多影响性能。
  • 磁盘空间：确保有足够的磁盘空间来存储临时文件，特别是在高负载情况下。
  • 权限设置：确保 Nginx 进程对指定的临时文件路径具有适当的读写权限。

http://www.kler.cn/a/553004.html

相关文章：

  • Webpack，Vite打包的理解
  • 框架--Mybatis 2
  • 第三方库XLSX: 前端上传excel文件，并对excel文件内容做校验。
  • ERP对制造业务有何价值？
  • No.39 蓝队 | 网络安全实战笔记：系统加固与资产梳理
  • Spring框架详解(一)
  • DeepSeek私有化部署3：openEuler 24.03-LTS-SP1国产化操作系统安装nVidia驱动
  • 纯新手教程：用llama.cpp本地部署DeepSeek蒸馏模型
  • Windows逆向工程入门之堆栈回溯
  • 关于uniApp的面试题及其答案解析
  • Python在网络安全中的应用 python与网络安全
  • 萌新学 Python 之 for 循环语句
  • 设置SCP无需输入密码
  • Linux下ioctl的应用
  • 极限网关可视化——Elasticsearch 请求流量分析实战
  • docker安装kafka,并通过springboot快速集成kafka
  • 每日一题之喜糖摆放
  • 图片粘贴上传实现
  • 深入探讨优先队列：原理、实现与应用
  • 4.6 模型训练基类Trainer：Hugging Face工业级训练引擎深度剖析