uWSGI#
允许将请求传递给 uwsgi 服务器。
配置示例#
location / {
include uwsgi_params;
uwsgi_pass localhost:9000;
}
指令#
uwsgi_bind#
使到 uwsgi 服务器的外发连接从指定的本地 IP 地址和可选端口发起。参数值可以包含变量。特殊值 off 取消从先前配置级别继承的 uwsgi_bind 指令的效果，允许系统自动分配本地 IP 地址和端口。
transparent 参数允许到 uwsgi 服务器的外发连接从非本地 IP 地址发起，例如，从客户端的真实 IP 地址发起：
uwsgi_bind $remote_addr transparent;
为了使此参数生效，通常需要以 超级用户 权限运行 Angie 工作进程。在 Linux 上不需要，因为如果指定了 transparent 参数，工作进程将从主进程继承 CAP_NET_RAW 能力。
重要
需要配置内核路由表以拦截来自 uwsgi 服务器的网络流量。
uwsgi_buffer_size#
设置用于读取从 uwsgi 服务器接收的响应第一部分的缓冲区大小。这部分通常包含一个小的响应头。默认情况下，缓冲区大小等于一个内存页。这是 4K 或 8K，取决于平台。它可以变小。
uwsgi_buffering#
启用或禁用从 uwsgi 服务器接收的响应的缓冲。
|
Angie 尽快从 uwsgi 服务器接收响应，将其保存在由 uwsgi_buffer_size 和 uwsgi_buffers 指令设置的缓冲区中。如果整个响应不适合内存，可以将部分响应保存到磁盘上的 临时文件 中。写入临时文件由 uwsgi_max_temp_file_size 和 uwsgi_temp_file_write_size 指令控制。 |
|
响应同步传递给客户端，立即接收。Angie 不会尝试从 uwsgi 服务器读取整个响应。Angie 从服务器一次可以接收的数据的最大大小由 uwsgi_buffer_size 指令设置。 |
缓冲也可以通过在 "X-Accel-Buffering" 响应头字段中传递 "yes" 或 "no" 来启用或禁用。可以使用 uwsgi_ignore_headers 指令禁用此功能。
uwsgi_buffers#
设置用于读取来自 uwsgi 服务器的响应的缓冲区的数量和大小，针对单个连接。
默认情况下，缓冲区大小等于一个内存页。这是 4K 或 8K，取决于平台。
uwsgi_busy_buffers_size#
当启用从 uwsgi 服务器接收的响应的 缓冲 时，限制在响应尚未完全读取时可以繁忙地向客户端发送响应的缓冲区的总大小。与此同时，其余缓冲区可以用于读取响应，如果需要，将响应的一部分缓冲到临时文件中。
默认情况下，大小由 uwsgi_buffer_size 和 uwsgi_buffers 指令设置的两个缓冲区的大小限制。
uwsgi_cache#
定义用于缓存的共享内存区。相同的区域可以在多个地方使用。参数值可以包含变量。
|
禁用从先前配置级别继承的缓存。 |
uwsgi_cache_background_update#
|
|
默认值 |
|
http, server, location |
允许启动后台子请求来更新过期的缓存项，同时将陈旧的缓存响应返回给客户端。
注意
请注意，必须 允许 在更新时使用陈旧的缓存响应。
uwsgi_cache_bypass#
定义在什么条件下不会从缓存中获取响应。如果字符串参数的至少一个值不为空且不等于 "0"，则不会从缓存中获取响应：
uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma $http_authorization;
可以与 uwsgi_no_cache 指令一起使用。
uwsgi_cache_key#
定义缓存的键，例如
uwsgi_cache_key localhost:9000$request_uri;
uwsgi_cache_lock#
启用时，同一时间将只允许一个请求通过向 uwsgi 服务器发送请求来填充一个新缓存元素，按照 uwsgi_cache_key 指令识别。相同缓存元素的其他请求将等待响应出现在缓存中或该元素的缓存锁被释放，最长等待时间由 uwsgi_cache_lock_timeout 指令设置。
uwsgi_cache_lock_age#
如果最后发送到 uwsgi 服务器的请求在指定时间内未完成，可以再向 uwsgi 服务器发送一个请求。
uwsgi_cache_lock_timeout#
设置 uwsgi_cache_lock 的超时时间。当时间到期时，请求将被传递给 uwsgi 服务器，但响应不会被缓存。
uwsgi_cache_max_range_offset#
为字节范围请求设置一个字节偏移量。如果范围超出偏移量，范围请求将被传递给 uwsgi 服务器，响应不会被缓存。
uwsgi_cache_methods#
|
|
默认值 |
|
http, server, location |
如果客户端请求方法在此指令中列出，则响应将被缓存。"GET" 和 "HEAD" 方法总是添加到列表中，但建议显式指定它们。另见 uwsgi_no_cache 指令。
uwsgi_cache_min_uses#
设置响应将被缓存的请求次数。
uwsgi_cache_path#
|
|
默认值 |
— |
http |
设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的文件名是应用 MD5 函数到 缓存键 的结果。
levels 参数定义缓存的层级结构：从 1 到 3，每个层级接受值 1 或 2。例如，在以下配置中：
uwsgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
缓存中的文件名将如下所示：
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
缓存的响应首先写入临时文件，然后重命名该文件。临时文件和缓存可以放置在不同的文件系统上。但是，请注意，在这种情况下，文件是跨两个文件系统复制的，而不是廉价的重命名操作。因此，建议在任何给定位置将缓存和存放临时文件的目录放在同一个文件系统中。
临时文件的目录是基于 use_temp_path 参数设置的。
|
如果此参数被省略或设置为 on，则将使用给定 location 的 uwsgi_temp_path 指令设置的目录。 |
|
临时文件将直接放在缓存目录中。 |
此外，所有活动的键和数据的信息都存储在共享内存区域中，其名称和大小由 keys_zone 参数配置。一个兆字节的区域可以存储大约 8000 个键。
在 inactive 参数指定的时间内未访问的缓存数据将从缓存中删除，而不考虑其新鲜度。
默认情况下，inactive 设置为 10 分钟。
一个特殊的 缓存管理 进程监控最大缓存大小和文件系统上的最小可用空间，当超出大小或可用空间不足时，它会删除最近最少使用的数据。数据在迭代中删除。
|
最大 uwsgi_cache 大小 |
|
文件系统上缓存的最小可用空间 |
|
限制在一次迭代中要删除的项目数量 默认情况下， |
|
限制一次迭代的持续时间 默认情况下， |
|
配置交互之间的间隔 默认情况下， |
Angie 启动一分钟后，特殊的 缓存加载器 进程被激活。它将文件系统上存储的以前缓存的数据的信息加载到缓存区域中。加载也是在迭代中完成的。
|
限制在一次迭代中要加载的项目数量 默认情况下， |
|
限制一次迭代的持续时间 默认情况下， |
|
配置交互之间的间隔 默认情况下， |
uwsgi_cache_revalidate#
启用使用 "If-Modified-Since" 和 "If-None-Match" 头字段的条件请求重新验证过期的缓存项目。
uwsgi_cache_use_stale#
|
|
默认值 |
|
http, server, location |
确定在与 uwsgi 服务器通信时可以使用过期缓存响应的情况。该指令的参数与 uwsgi_next_upstream 指令的参数相匹配。
|
如果无法选择 uwsgi 服务器来处理请求，则允许使用过期的缓存响应。 |
|
额外参数，允许在缓存响应正在更新时使用过期的缓存响应。这允许在更新缓存数据时最小化对 uwsgi 服务器的访问次数。 |
使用过期的缓存响应也可以直接在响应头中启用，指定响应过期后的一段秒数：
"Cache-Control" 头字段的 stale-while-revalidate 扩展允许在缓存响应正在更新时使用过期的缓存响应。
"Cache-Control" 头字段的 stale-if-error 扩展允许在发生错误时使用过期的缓存响应。
备注
这优先级低于使用指令参数。
为了在填充新缓存元素时最小化对 uwsgi 服务器的访问次数，可以使用 uwsgi_cache_lock 指令。
uwsgi_cache_valid#
为不同的响应代码设置缓存时间。例如，以下指令
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404 1m;
为代码 200 和 302 的响应设置 10 分钟的缓存时间，为代码 404 的响应设置 1 分钟。
如果只指定缓存时间
uwsgi_cache_valid 5m;
则仅缓存 200、301 和 302 响应。
此外，可以指定 any 参数以缓存任何响应：
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 301 1h;
uwsgi_cache_valid any 1m;
备注
缓存参数也可以直接在响应头中设置。这优先级高于使用指令设置的缓存时间
"X-Accel-Expires" 头字段以秒为单位设置响应的缓存时间。零值禁用响应的缓存。如果值以 @ 前缀开头，则设置自 Epoch 以来的秒数绝对时间，直到响应可能被缓存。
如果头中不包含 "X-Accel-Expires" 字段，缓存参数可以在头字段 "Expires" 或 "Cache-Control" 中设置。
如果头中包含 "Set-Cookie" 字段，则该响应将不被缓存。
如果头中包含值为 "*" 的 "Vary" 字段，则该响应将不被缓存。如果头中包含其他值的 "Vary" 字段，则该响应将被缓存，并考虑相应请求头字段。
可以使用 uwsgi_ignore_headers 指令禁用对这些响应头字段之一或多个的处理。
uwsgi_connect_timeout#
|
|
Default |
|
http, server, location |
定义与 uwsgi 服务器建立连接的超时时间。应注意，此超时时间通常不能超过 75 秒。
uwsgi_connection_drop#
|
|
Default |
|
http, server, location |
启用在代理服务器从组中移除或被 reresolve 进程或 API command DELETE 标记为永久不可用后终止所有连接。
当下一个读或写事件在客户端或代理服务器中处理时，连接被终止。
设置 time 启用连接终止 timeout；设置 on，连接立即断开。
uwsgi_force_ranges#
启用对来自 uwsgi 服务器的缓存和未缓存响应的字节范围支持，而不考虑这些响应中的 "Accept-Ranges" 字段。
uwsgi_hide_header#
默认情况下，Angie 不会将 uwsgi 服务器响应中的 "Status" 和 "X-Accel-..." 头字段传递给客户端。uwsgi_hide_header 指令设置不会传递的额外字段。如果需要允许传递字段，可以使用 uwsgi_pass_header 指令。
uwsgi_ignore_client_abort#
|
|
Default |
|
http, server, location |
确定当客户端在未等待响应的情况下关闭连接时，是否应关闭与 uwsgi 服务器的连接。
uwsgi_ignore_headers#
禁用对来自 uwsgi 服务器的某些响应头字段的处理。可以忽略以下字段："X-Accel-Redirect"、"X-Accel-Expires"、"X-Accel-Limit-Rate"、"X-Accel-Buffering"、"X-Accel-Charset"、"Expires"、"Cache-Control"、"Set-Cookie" 和 "Vary"。
如果未禁用，对这些头字段的处理将产生以下效果：
"X-Accel-Expires"、"Expires"、"Cache-Control"、"Set-Cookie" 和 "Vary" 设置响应 caching 的参数；
"X-Accel-Redirect" 执行 internal 重定向到指定的 URI；
"X-Accel-Limit-Rate" 设置将响应传输给客户端的 rate limit；
"X-Accel-Buffering" 启用或禁用响应的 buffering；
"X-Accel-Charset" 设置响应的所需 charset。
uwsgi_intercept_errors#
决定是否应将 uwsgi 服务器响应的代码大于或等于 300 的情况传递给客户端，或者拦截并重定向到 Angie 进行使用 error_page 指令的处理。
uwsgi_limit_rate#
限制从 uwsgi 服务器读取响应的速度。rate 以每秒字节数指定，并且可以包含变量。
|
禁用速率限制 |
备注
该限制是针对每个请求设置的，因此如果 Angie 同时打开两个到 uwsgi 服务器的连接，总的速率将是指定限制的两倍。仅在启用了对 uwsgi 服务器响应的 buffering 时，限制才有效。
uwsgi_max_temp_file_size#
当启用了对 uwsgi 服务器响应的 buffering，并且整个响应不适合由 uwsgi_buffer_size 和 uwsgi_buffers 指令设置的缓冲区时，可以将响应的一部分保存到临时文件中。此指令设置临时文件的最大大小。一次写入临时文件的数据大小由 uwsgi_temp_file_write_size 指令设置。
|
禁用响应到临时文件的缓冲 |
备注
此限制不适用于将被缓存或 存储在磁盘上 的响应。
uwsgi_modifier1#
设置 uwsgi 数据包头 中 modifier1 字段的值。
uwsgi_modifier2#
设置 uwsgi 数据包头 中 modifier2 字段的值。
uwsgi_next_upstream#
|
|
默认值 |
|
http, server, location |
指定在何种情况下应将请求传递给 上游池 中的下一个服务器：
|
在与服务器建立连接、传递请求或读取响应头时发生了错误； |
|
在与服务器建立连接、传递请求或读取响应头时发生了超时； |
|
服务器返回了空或无效的响应； |
|
服务器返回代码 500 的响应； |
|
服务器返回代码 503 的响应； |
|
服务器返回代码 403 的响应； |
|
服务器返回代码 404 的响应； |
|
服务器返回代码 429 的响应； |
|
通常，具有 非幂等 方法 ( |
|
禁用将请求传递给下一个服务器。 |
备注
需要注意的是，只有在尚未将任何数据发送给客户端时，才可以将请求传递给下一个服务器。也就是说，如果在响应传输过程中发生错误或超时，则无法修复。
该指令还定义了与服务器通信的 不成功尝试。
|
|
始终被视为不成功的尝试，即使它们未在指令中指定 |
|
|
仅当在指令中指定时才被视为不成功的尝试 |
|
|
永远不会被视为不成功的尝试 |
uwsgi_next_upstream_timeout#
限制在请求可以传递给 下一个 服务器的时间。
|
关闭此限制 |
uwsgi_next_upstream_tries#
限制将请求传递给 下一个 服务器的可能尝试次数。
|
关闭此限制 |
uwsgi_no_cache#
定义在何种条件下响应不会被保存到缓存中。如果字符串参数的至少一个值不为空且不等于 "0"，则响应不会被保存：
uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma $http_authorization;
可以与 uwsgi_cache_bypass 指令一起使用。
uwsgi_param#
设置应传递给 uwsgi 服务器的参数。该值可以包含文本、变量及其组合。如果且仅在当前级别未定义 uwsgi_param 指令时，这些指令会从先前的配置级别继承。
标准 CGI 环境变量 应作为 uwsgi 头提供，参见分发中提供的 uwsgi_params 文件：
location / {
include uwsgi_params;
# ...
}
如果指令使用 if_not_empty 指定，则仅在其值不为空时才将该参数传递给服务器：
uwsgi_param HTTPS $https if_not_empty;
uwsgi_pass#
设置 uwsgi 服务器的协议和地址，以及一个可选的 URI，将位置映射到该地址。作为协议，可以指定 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;
如果域名解析为多个地址，则所有地址将以轮询方式使用。此外，地址可以指定为 服务器组。如果使用组，则不能为其指定端口；而是为组内的每个服务器分别指定端口。
参数值可以包含变量。在这种情况下，如果地址指定为域名，则在描述的服务器组中搜索该名称，如果未找到，则使用 解析器 确定。
uwsgi_pass_header#
允许从uwsgi服务器传递 否则被禁用的 头字段到客户端。
uwsgi_pass_request_body#
指示是否将原始请求主体传递给uwsgi服务器。另请参见 uwsgi_pass_request_headers 指令。
uwsgi_pass_request_headers#
|
|
默认值 |
|
http, server, location |
指示是否将原始请求的头字段传递给uwsgi服务器。另请参见 uwsgi_pass_request_body 指令。
uwsgi_read_timeout#
定义从uwsgi服务器读取响应的超时时间。超时时间仅在两次连续读取操作之间设置，而不是用于整个响应的传输。如果uwsgi服务器在此时间内没有传输任何内容，则连接将关闭。
uwsgi_request_buffering#
启用或禁用客户端请求主体的缓冲。
|
在将请求发送到uwsgi服务器之前，从客户端读取整个请求主体。 |
|
请求主体在接收到时立即发送到uwsgi服务器。在这种情况下，如果Angie已经开始发送请求主体，请求无法传递给 下一个服务器。 |
当使用HTTP/1.1分块传输编码发送原始请求主体时，无论指令值如何，请求主体都将被缓冲。
uwsgi_send_timeout#
设置向uwsgi服务器传输请求的超时时间。超时时间仅在两次连续写入操作之间设置，而不是用于整个请求的传输。如果uwsgi服务器在此时间内没有接收到任何内容，则连接将关闭。
uwsgi_socket_keepalive#
配置到uwsgi服务器的传出连接的“TCP保持活动”行为。
|
默认为操作系统的设置对套接字生效。 |
|
为套接字启用 SO_KEEPALIVE 套接字选项。 |
uwsgi_ssl_certificate#
指定用于认证到安全uwsgi服务器的PEM格式证书文件。文件名中可以使用变量。
uwsgi_ssl_certificate_key#
指定用于认证到安全uwsgi服务器的PEM格式秘密密钥文件。
可以指定“engine:name:id”而不是文件，从OpenSSL引擎名称加载具有指定id的秘密密钥。文件名中可以使用变量。
uwsgi_ssl_ciphers#
指定请求到安全uwsgi服务器时启用的密码。密码以OpenSSL库理解的格式指定。
可以使用“openssl ciphers”命令查看完整列表。
uwsgi_ssl_conf_command#
在与安全uwsgi服务器建立连接时设置任意OpenSSL配置`命令 <https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html>`_。
重要
使用OpenSSL 1.0.2或更高版本时支持该指令。
可以在同一级别指定多个 uwsgi_ssl_conf_command 指令。如果且仅当当前级别没有定义 uwsgi_ssl_conf_command 指令时，这些指令将从上一级配置继承。
小心
请注意，直接配置OpenSSL可能导致意外行为。
uwsgi_ssl_crl#
指定用于 验证 安全uwsgi服务器证书的PEM格式撤销证书（CRL）文件。
uwsgi_ssl_name#
允许覆盖用于 验证 安全uwsgi服务器证书的服务器名称，并在与安全uwsgi服务器建立连接时通过SNI传递。默认情况下，使用 uwsgi_pass URL的主机部分。
uwsgi_ssl_password_file#
指定用于 秘密密钥 的密码短语文件，每个密码短语在单独的行中指定。在加载密钥时将依次尝试这些密码短语。
uwsgi_ssl_protocols#
|
|
默认值 |
|
http, server, location |
在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集。
启用请求到安全uwsgi服务器时指定的协议。
uwsgi_ssl_server_name#
启用或禁用通过 服务器名称指示 TLS扩展（SNI， RFC 6066） 在与安全uwsgi服务器建立连接时传递由 uwsgi_ssl_name 指令设置的服务器名称。
uwsgi_ssl_session_reuse#
确定与uwsgi服务器工作时是否可以重用SSL会话。如果日志中出现“SSL3_GET_FINISHED:digest check failed”错误，请尝试禁用 会话重用。
uwsgi_ssl_trusted_certificate#
指定用于 验证 安全uwsgi服务器证书的PEM格式可信CA证书文件。
uwsgi_ssl_verify#
启用或禁用对安全uwsgi服务器证书的验证。
uwsgi_ssl_verify_depth#
设置安全uwsgi服务器证书链的验证深度。
uwsgi_store#
启用将文件保存到磁盘。
可以使用带变量的 string 显式设置文件名：
uwsgi_store /data/www$original_uri;
文件的修改时间根据接收到的 "Last-Modified" 响应头字段设置。响应首先写入一个临时文件，然后将文件重命名。临时文件和持久存储可以放在不同的文件系统上。然而，请注意，这种情况下文件是在两个文件系统之间复制，而不是简单的重命名操作。因此，建议对于任何给定的 location，保存的文件和由 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#
|
|
默认值 |
|
http, server, location |
设置新创建文件和目录的访问权限，例如：
uwsgi_store_access user:rw group:rw all:r;
如果指定了任何 group 或 all 访问权限，则用户权限可以省略：
uwsgi_store_access group:rw all:r;
uwsgi_temp_file_write_size#
|
|
默认值 |
|
http, server, location |
限制在启用从 uwsgi 服务器到临时文件的响应缓冲时，一次写入临时文件的数据大小。默认情况下，大小由 uwsgi_buffer_size 和 uwsgi_buffers 指令设置的两个缓冲区限制。临时文件的最大大小由 uwsgi_max_temp_file_size 指令设置。
uwsgi_temp_path#
|
|
Default |
|
http, server, location |
定义一个目录，用于存储从 uwsgi 服务器接收到的数据的临时文件。最多可以在指定的目录下使用三层子目录结构。例如，在以下配置中
uwsgi_temp_path /spool/angie/uwsgi_temp 1 2;
一个临时文件可能看起来像这样：
/spool/angie/uwsgi_temp/7/45/00000123457
另请参见 uwsgi_cache_path 指令的 use_temp_path 参数。