模块 ngx_http_uwsgi_module

模块 ngx_http_uwsgi_module 允许将请求传递给uwsgi服务器。

location / {
    include    uwsgi_params;
    uwsgi_pass localhost:9000;
}

使出站到uwsgi服务器的连接从指定的本地IP地址发起，可选端口 (1.11.2)。参数值可以包含变量 (1.3.12)。特殊值 off (1.3.12) 取消了从上一个配置级别继承的 uwsgi_bind 指令的效果，从而允许系统自动分配本地IP地址和端口。

透明参数 (1.11.0) 允许从非本地IP地址发起出站到uwsgi服务器的连接，例如，从客户端的实际IP地址：

uwsgi_bind $remote_addr transparent;

为了使此参数工作，通常需要以 超级用户 权限运行nginx工作进程。在Linux上，这不是必需的 (1.13.8)，因为如果指定了 transparent 参数，工作进程会从主进程继承 CAP_NET_RAW 能力。还需要配置内核路由表以拦截从uwsgi服务器发出的网络流量。

uwsgi_buffer_size 4k|8k;

设置用于读取从uwsgi服务器接收到的响应的第一部分的缓冲区的 大小。此部分通常包含一个小的响应头。默认情况下，缓冲区大小等于一个内存页。这是4K或8K，取决于平台。但可以使其更小。

uwsgi_buffering on;

启用或禁用从uwsgi服务器接收响应的缓冲。

启用缓冲时，nginx尽快从uwsgi服务器接收响应，并将其保存到由 uwsgi_buffer_size 和 uwsgi_buffers 指令设置的缓冲区中。如果整个响应无法放入内存中，则部分响应可以保存到磁盘上的 临时文件 中。临时文件的写入由 uwsgi_max_temp_file_size 和 uwsgi_temp_file_write_size 指令控制。

禁用缓冲时，响应将同步地立即传递给客户端，就像它被接收到一样。nginx不会尝试从uwsgi服务器读取整个响应。nginx一次从服务器接收的数据的最大大小由 uwsgi_buffer_size 指令设置。

缓冲可以通过在“X-Accel-Buffering”响应头字段传递“yes”或“no”来启用或禁用。这个功能可以使用uwsgi_ignore_headers指令来禁用。

uwsgi_buffers 8 4k|8k;

设置用于从uwsgi服务器读取响应的缓冲区的数量和大小，用于单个连接。默认情况下，缓冲区大小等于一个内存页面。这要么是4K，要么是8K，取决于平台。

uwsgi_busy_buffers_size 8k|16k;

当从uwsgi服务器的响应启用缓冲时，限制可以忙于向客户端发送响应的缓冲区的总大小，同时响应尚未完全读取。与此同时，其余的缓冲区可以用于读取响应，并在需要时将响应的一部分缓冲到临时文件中。默认情况下，大小由uwsgi_buffer_size和uwsgi_buffers指令设置的两个缓冲区的大小限制。

uwsgi_cache off;

定义用于缓存的共享内存区域。相同的区域可以在几个地方使用。参数值可以包含变量（1.7.9）。参数off禁用从先前配置级别继承的缓存。

uwsgi_cache_background_update off;

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client. Note that it is necessary to allow the usage of a stale cached response when it is being updated.

Defines conditions under which the response will not be taken from a cache. If at least one value of the string parameters is not empty and is not equal to “0” then the response will not be taken from the cache:

uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma    $http_authorization;

可以与 uwsgi_no_cache 指令一起使用。

定义一个用于缓存的键，例如

uwsgi_cache_key localhost:9000$request_uri;

uwsgi_cache_lock off;

当启用时，只允许一次请求来填充一个新的缓存元素，该元素由 uwsgi_cache_key 指令识别，通过将请求传递给一个uwsgi服务器。同一缓存元素的其他请求将等待缓存中出现的响应或该元素的缓存锁被释放，直到由 uwsgi_cache_lock_timeout 指令设置的时间。

uwsgi_cache_lock_age 5s;

如果传递给uwsgi服务器以填充一个新的缓存元素的最后一个请求在指定的 时间 内未完成，可能会传递更多的请求给uwsgi服务器。

uwsgi_cache_lock_timeout 5s;

设置 uwsgi_cache_lock 的超时时间。当 时间 到期时，请求将被传递给uwsgi服务器，但是响应不会被缓存。

在 1.7.8 之前，响应可能会被缓存。

为字节范围请求设置一个字节偏移量。如果范围超过偏移量，范围请求将被传递给uwsgi服务器，响应不会被缓存。

uwsgi_cache_methods GET HEAD;

如果客户端请求方法在此指令中列出，则响应将被缓存。“GET”和“HEAD”方法始终添加到列表中，但建议明确指定它们。另请参阅uwsgi_no_cache指令。

uwsgi_cache_min_uses 1;

设置请求次数，在此次数之后响应将被缓存。

设置缓存的路径和其他参数。缓存数据存储在文件中。在缓存中，文件名是将MD5函数应用于缓存键的结果。 levels参数定义了缓存的层次结构：从1到3，每个级别都接受值1或2。例如，在以下配置中

uwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

缓存中的文件名看起来像这样：

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

缓存的响应首先写入临时文件，然后文件被重命名。从版本0.8.9开始，临时文件和缓存可以放在不同的文件系统上。然而，请注意，在这种情况下，文件被复制到两个文件系统而不是廉价的重命名操作。因此，建议对于任何给定位置，缓存和保存临时文件的目录都放在同一个文件系统上。临时文件目录是基于use_temp_path参数设置的（1.7.10）。如果省略此参数或将其设置为on，则将使用由uwsgi_temp_path指令为给定位置设置的目录。如果该值设置为off，则临时文件将直接放在缓存目录中。

此外，所有活动键和关于数据的信息都存储在一个共享内存区域中，其name和size由keys_zone参数配置。一个兆字节的区域可以存储约8000个键。

作为商业订阅的一部分，共享内存区域还存储扩展缓存信息，因此，对于相同数量的键，需要指定更大的区域大小。例如，一个兆字节的区域可以存储约4000个键。

在由inactive参数指定的时间内未访问的缓存数据将会被从缓存中移除，无论它们的新鲜度如何。默认情况下，inactive设置为10分钟。

特殊的“缓存管理器”进程监控由max_size参数设置的最大缓存大小，以及由min_free（1.19.1）参数在文件系统上设置的最小空闲空间。当超过大小或空间不足时，它将移除最不常用的数据。数据的移除是通过manager_files、manager_threshold和manager_sleep参数（1.11.5）配置的迭代完成的。在一次迭代中，最多删除manager_files项数据（默认为100）。一次迭代的持续时间由manager_threshold参数限制（默认为200毫秒）。迭代之间，由manager_sleep参数配置的暂停（默认为50毫秒）。

启动后一分钟，特殊的“缓存加载器”进程被激活。它将文件系统上存储的以前缓存的数据信息加载到缓存区。加载也是通过迭代完成的。在一次迭代中，最多加载loader_files项数据（默认为100）。此外，一次迭代的持续时间由loader_threshold参数限制（默认为200毫秒）。迭代之间，由loader_sleep参数配置的暂停（默认为50毫秒）。

此外，作为我们商业订阅的一部分，还提供以下参数：

purger=on|off

指示是否将与通配符键匹配的缓存条目通过缓存清理器从磁盘上移除（1.7.12）。将参数设置为on（默认为off）将激活“缓存清理器”进程，该进程将永久迭代所有缓存条目并删除与通配符键匹配的条目。

purger_files=number

设置在一次迭代中将扫描的项目数（1.7.12）。默认情况下，purger_files设置为10。

purger_threshold=number

设置一次迭代的持续时间（1.7.12）。默认情况下，purger_threshold设置为50毫秒。

purger_sleep=number

设置迭代之间的暂停时间（1.7.12）。默认情况下，purger_sleep设置为50毫秒。

在版本1.7.3、1.7.7和1.11.10中，缓存头格式已更改。升级到新版本的nginx后，之前缓存的响应将被视为无效。

Defines conditions under which the request will be considered a cache purge request. If at least one value of the string parameters is not empty and is not equal to “0” then the cache entry with a corresponding cache key is removed. The result of successful operation is indicated by returning the 204 (No Content) response.

如果清除请求的缓存键以星号（“*”）结尾，则将从缓存中删除与通配符键匹配的所有缓存条目。但是，这些条目将保留在磁盘上，直到它们由于不活动而被删除，或由缓存清除器（1.7.12）处理，或客户端尝试访问它们。

示例配置：

uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        uwsgi_pass        backend;
        uwsgi_cache       cache_zone;
        uwsgi_cache_key   $uri;
        uwsgi_cache_purge $purge_method;
    }
}

此功能作为我们的商业订阅的一部分提供。

uwsgi_cache_revalidate off;

启用使用带有“如果修改自”和“如果无匹配项”标头字段的条件请求重新验证过期的缓存项目。

uwsgi_cache_use_stale off;

确定在与uwsgi服务器通信期间发生错误时在哪些情况下可以使用过期的缓存响应。指令的参数与uwsgi_next_upstream指令的参数匹配。

如果无法选择用于处理请求的uwsgi服务器，则error参数还允许使用过期的缓存响应。

此外，updating参数允许在当前正在更新时使用过期的缓存响应。这样可以在更新缓存数据时将对uwsgi服务器的访问次数最小化。

在响应变为过期后的指定秒数内，还可以直接在响应标头中启用使用过期的缓存响应（1.11.10）。这比使用指令参数的优先级低。

• The “stale-while-revalidate” extension of the “Cache-Control” header field permits using a stale cached response if it is currently being updated.
• The “stale-if-error” extension of the “Cache-Control” header field permits using a stale cached response in case of an error.

为了在填充新缓存元素时将对uwsgi服务器的访问次数最小化，可以使用uwsgi_cache_lock指令。

为不同的响应代码设置缓存时间。例如，以下指令

uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404      1m;

为代码为200和302的响应设置10分钟的缓存时间，为代码为404的响应设置1分钟。

如果只指定缓存time

uwsgi_cache_valid 5m;

那么只有代码为200、301和302的响应会被缓存。

此外，还可以指定any参数以缓存任何响应：

uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 301      1h;
uwsgi_cache_valid any      1m;

还可以直接在响应标头中设置缓存的参数。这比使用指令设置缓存时间的优先级高。

• The “X-Accel-Expires” header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
• If the header does not include the “X-Accel-Expires” field, parameters of caching may be set in the header fields “Expires” or “Cache-Control”.
• If the header includes the “Set-Cookie” field, such a response will not be cached.
• If the header includes the “Vary” field with the special value “*”, such a response will not be cached (1.7.7). If the header includes the “Vary” field with another value, such a response will be cached taking into account the corresponding request header fields (1.7.7).

可以使用uwsgi_ignore_headers指令来禁用其中一个或多个响应头字段的处理。

uwsgi_connect_timeout 60s;

定义与uwsgi服务器建立连接的超时时间。应注意，此超时通常不能超过75秒。

uwsgi_force_ranges off;

无论这些响应中的“Accept-Ranges”字段如何，都会为uwsgi服务器的缓存和非缓存响应启用字节范围支持。

默认情况下，nginx不会将uwsgi服务器的响应中的“Status”和“X-Accel-...”字段传递给客户端。`uwsgi_hide_header`指令设置将不传递的额外字段。相反，如果需要允许字段的传递，可以使用uwsgi_pass_header指令。

uwsgi_ignore_client_abort off;

确定当客户端在等待响应的情况下关闭连接时，与uwsgi服务器的连接是否应该关闭。

禁用来自uwsgi服务器的某些响应头字段的处理。以下字段可以被忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate” (1.1.6)、“X-Accel-Buffering” (1.1.6)、“X-Accel-Charset” (1.1.6)、“Expires”、“Cache-Control”、“Set-Cookie” (0.8.44) 和 “Vary” (1.7.7)。

如果没有禁用，处理这些头字段会产生以下效果：

• “X-Accel-Expires”, “Expires”, “Cache-Control”, “Set-Cookie”, and “Vary” set the parameters of response caching;
• “X-Accel-Redirect” performs an internal redirect to the specified URI;
• “X-Accel-Limit-Rate” sets the rate limit for transmission of a response to a client;
• “X-Accel-Buffering” enables or disables buffering of a response;
• “X-Accel-Charset” sets the desired charset of a response.

uwsgi_intercept_errors off;

确定uwsgi服务器响应的状态码是否大于或等于300应该传递给客户端还是被拦截并重定向到nginx以使用error_page指令进行处理。

uwsgi_limit_rate 0;

限制从uwsgi服务器读取响应的速度。 rate以每秒字节为单位指定。零值禁用速率限制。限制设置为每个请求，因此如果nginx同时打开两个连接到uwsgi服务器，则总速率将是指定限制的两倍。仅当启用对来自uwsgi服务器的响应的缓冲时，限制才起作用。

uwsgi_max_temp_file_size 1024m;

当启用来自uwsgi服务器的响应的缓冲并且整个响应不适合由uwsgi_buffer_size和uwsgi_buffers指令设置的缓冲区时，响应的一部分可以保存到临时文件中。此指令设置临时文件的最大size。写入临时文件的数据大小由uwsgi_temp_file_write_size指令设置。

零值禁用将响应缓冲到临时文件。

此限制不适用于将缓存或存储在磁盘上的响应。

uwsgi_modifier1 0;

设置uwsgi数据包头中的modifier1字段的值。

uwsgi_modifier2 0;

设置uwsgi数据包头中的modifier2字段的值。

uwsgi_next_upstream error timeout;

指定请求在哪些情况下应该传递到下一个服务器：

error

与服务器建立连接、向其传递请求或读取响应标头时发生错误；

timeout

与服务器建立连接、向其传递请求或读取响应标头时发生超时；

invalid_header

服务器返回空或无效响应；

http_500

服务器返回代码为500的响应；

http_503

服务器返回代码为503的响应；

http_403

服务器返回代码为403的响应；

http_404

服务器返回代码为404的响应；

http_429

服务器返回代码为429的响应（1.11.13）；

non_idempotent

通常，具有非幂等方法（POST、LOCK、PATCH）的请求如果已发送到上游服务器，则不会传递到下一个服务器（1.9.13）；显式启用此选项可允许重试此类请求；

off

禁用将请求传递到下一个服务器。

应该牢记，只有在尚未向客户端发送任何内容时才能将请求传递到下一个服务器。也就是说，如果在传输响应的过程中发生错误或超时，则无法修复此问题。

该指令还定义了什么被视为与服务器通信的失败尝试。error、timeout和invalid_header的情况始终被视为失败尝试，即使它们未在指令中指定。只有在指令中指定了http_500、http_503和http_429的情况下，才将它们视为失败尝试。http_403和http_404的情况永远不被视为失败尝试。

将请求传递到下一个服务器可以受到尝试次数和时间的限制。

uwsgi_next_upstream_timeout 0;

限制将请求传递到下一个服务器的时间。值0将关闭此限制。

uwsgi_next_upstream_tries 0;

限制将请求传递给下一个服务器的尝试次数。值为 0 时关闭此限制。

定义响应不会保存到缓存的条件。如果字符串参数的至少一个值不为空且不等于“0”，则响应不会保存：

uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma    $http_authorization;

可与 uwsgi_cache_bypass 指令一起使用。

设置应传递给uwsgi服务器的 parameter。 value 可包含文本、变量及其组合。仅当当前级别上没有定义 uwsgi_param 指令时，这些指令才会从前一配置级别继承。

应提供标准的 CGI 环境变量 作为uwsgi头，参见分发中提供的 uwsgi_params 文件：

location / {
    include uwsgi_params;
    ...
}

如果使用 if_not_empty (1.1.11) 指定了该指令，则仅当其值不为空时才将此参数传递给服务器：

uwsgi_param HTTPS $https if_not_empty;

设置uwsgi服务器的协议和地址。作为 protocol，可以指定“uwsgi”或“suwsgi”（安全的uwsgi，SSL上的uwsgi）。地址可以指定为域名或IP地址，及端口：

uwsgi_pass localhost:9000;
uwsgi_pass uwsgi://localhost:9000;
uwsgi_pass suwsgi://[2001:db8::1]:9090;

或作为UNIX域套接字路径：

uwsgi_pass unix:/tmp/uwsgi.socket;

如果域名解析到多个地址，则所有地址都将循环使用。此外，地址还可以指定为一个 服务器组。

参数值可以包含变量。在这种情况下，如果地址指定为域名，则会在描述的 服务器组 中搜索该名称，如果未找到，则使用 resolver 确定。

自版本 1.5.8 起支持安全的uwsgi协议。

允许从uwsgi服务器传递已禁用的标头字段到客户端。

uwsgi_pass_request_body on;

指示是否将原始请求正文传递给uwsgi服务器。也请参阅uwsgi_pass_request_headers指令。

uwsgi_pass_request_headers on;

指示是否将原始请求的标头字段传递给uwsgi服务器。也请参阅uwsgi_pass_request_body指令。

uwsgi_read_timeout 60s;

定义从uwsgi服务器读取响应的超时时间。该超时仅在两个连续读取操作之间设置，而不是针对整个响应的传输。如果uwsgi服务器在此时间内未传输任何内容，则连接将关闭。

uwsgi_request_buffering on;

启用或禁用对客户端请求正文的缓冲。

启用缓冲时，将从客户端读取整个请求正文，然后将请求发送到uwsgi服务器。

禁用缓冲时，将原样将请求正文发送到uwsgi服务器。在这种情况下，如果nginx已开始发送请求正文，则无法将请求传递给下一个服务器。

当使用HTTP/1.1分块传输编码发送原始请求正文时，无论指令值如何，请求正文都将被缓冲。

uwsgi_send_timeout 60s;

设置向uwsgi服务器传输请求的超时时间。超时时间仅在两次连续写操作之间设置，而不是整个请求的传输时间。如果uwsgi服务器在此时间内未收到任何内容，连接将关闭。

uwsgi_socket_keepalive off;

配置传出到uwsgi服务器的连接的“TCP keepalive”行为。默认情况下，套接字使用操作系统的设置。如果将指令设置为“on”，则为套接字启用SO_KEEPALIVE套接字选项。

指定用于对安全uwsgi服务器进行身份验证的PEM格式证书的file。

自版本1.21.0起，可以在file名称中使用变量。

指定用于对安全uwsgi服务器进行身份验证的PEM格式密钥的file。

可以指定值engine:name:id代替file（1.7.9），它从OpenSSL引擎name中加载具有指定id的密钥。

自版本1.21.0起，可以在file名称中使用变量。

uwsgi_ssl_ciphers DEFAULT;

指定对安全uwsgi服务器的请求启用的密码。密码以OpenSSL库理解的格式指定。

可以使用“openssl ciphers”命令查看完整列表。

在与安全uwsgi服务器建立连接时设置任意的OpenSSL配置命令。

指令在使用 OpenSSL 版本 1.0.2 或更高版本时受支持。

可以在同一级别上指定多个uwsgi_ssl_conf_command指令。仅当当前级别上未定义uwsgi_ssl_conf_command指令时，这些指令才会从上一配置级别继承。

配置 OpenSSL 可能导致意外行为。

指定用于验证受保护的 uwsgi 服务器证书的 PEM 格式中吊销证书（CRL）的file。

uwsgi_ssl_name host from uwsgi_pass;

允许覆盖用于验证受保护的 uwsgi 服务器证书并在与受保护的 uwsgi 服务器建立连接时通过 SNI 传递的服务器名称。

默认情况下，使用来自uwsgi_pass的主机部分。

指定包含密钥密码的file，其中每个密码都在单独的一行上指定。 加载密钥时，逐个尝试密码。

uwsgi_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

启用对发送到受保护的 uwsgi 服务器的请求的指定协议。

默认自 1.23.4 版本开始使用TLSv1.3参数。

uwsgi_ssl_server_name off;

启用或禁用通过TLS服务器名称指示扩展（SNI，RFC 6066）在与安全uwsgi服务器建立连接时传递服务器名称。

uwsgi_ssl_session_reuse on;

确定在与安全uwsgi服务器一起工作时是否可以重用SSL会话。如果日志中出现“SSL3_GET_FINISHED:digest check failed”错误，请尝试禁用会话重用。

指定一个以PEM格式的受信任CA证书文件file，用于验证安全uwsgi服务器的证书。

uwsgi_ssl_verify off;

启用或禁用验证安全uwsgi服务器证书。

uwsgi_ssl_verify_depth 1;

设置安全uwsgi服务器证书链中的验证深度。

uwsgi_store off;

启用文件保存到磁盘。 on 参数使用与指令alias或root相对应的路径保存文件。 off 参数禁用文件保存。此外，可以使用带有变量的string来显式设置文件名：

uwsgi_store /data/www$original_uri;

文件的修改时间根据接收到的“Last-Modified”响应头字段进行设置。响应首先被写入临时文件，然后文件被重命名。从版本0.8.9开始，临时文件和持久存储可以放在不同的文件系统上。但是，请注意，在这种情况下，文件是在两个文件系统之间复制而不是廉价的重命名操作。因此建议对于任何给定的位置，保存的文件和保存临时文件的目录（由uwsgi_temp_path指令设置）都放在同一个文件系统上。

此指令可用于创建静态不可变文件的本地副本，例如：

location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    uwsgi_pass         backend:9000;
    ...

    uwsgi_store        on;
    uwsgi_store_access user:rw group:rw all:r;
    uwsgi_temp_path    /data/temp;

    alias              /data/www/;
}

uwsgi_store_access user:rw;

设置新创建的文件和目录的访问权限，例如：

uwsgi_store_access user:rw group:rw all:r;

如果指定了任何组或全部访问权限，则可以省略用户权限：

uwsgi_store_access group:rw all:r;

uwsgi_temp_file_write_size 8k|16k;

当启用从uwsgi服务器到临时文件的响应缓冲时，限制一次写入临时文件的数据大小。默认情况下，大小由uwsgi_buffer_size和uwsgi_buffers指令设置的两个缓冲区限制。临时文件的最大大小由uwsgi_max_temp_file_size指令设置。

uwsgi_temp_path uwsgi_temp;

定义用于存储从uwsgi服务器接收到的临时文件数据的目录。指定目录下可以使用最多三级子目录层次结构。例如，在以下配置中

uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;

临时文件可能如下所示：

/spool/nginx/uwsgi_temp/7/45/00000123457

另请参阅uwsgi_cache_path指令的use_temp_path参数。