文档中心 CDN Pro 支持的指令

支持的指令

更新时间:2022-07-21 10:15:24

支持的指令

支持的指令

这一页列出了您可以在CDN Pro的边缘逻辑里使用的全部指令。部分指令是未经修改的开源版本,部分指令经过了我们的 修改增强 以更好地满足CDN服务的需求。同时我们也引入了大量 全新特有 的指令来完善开源版本作为CDN服务器的不足。

以下列表中,标记为 标准 的指令对所有的客户都开放。它们应该可以满足绝大部分常见的CDN配置需求。标记为 高级 的指令通常会消耗更多的资源。对于这些指令,我们需要逐一审核来明确需求。如果您需要用到这些指令,请联系客服。您有可能需要为它们额外付费。

支持的指令列表

指令名称
描述
标记
add_header 修改发往客户端的响应头部 标准 修改增强
add_trailer 在响应正文之后添加一个尾部(trailer) 标准 修改增强
allow 指定允许的客户端IP范围 标准 修改增强
auth_request 通过 URI 授权请求 高级 修改增强
auth_request_set 根据授权验证结果设置变量 高级
break 终止执行当前 nginx rewrite 模块的指令 标准
client_body_timeout 等待请求正文的超时时间 高级 修改增强
client_header_timeout 等待请求头部的超时时间 高级 修改增强
client_max_body_size 允许的最大请求正文 高级
client_send_timeout 将响应发送给客户端的超时时间 高级 全新特有
custom_log_field 设置自定义日志字段的值 高级 全新特有
deny 指定被拒绝的 IP 范围 标准 修改增强
enable_websocket 启用websocket(默认超时=21s) 高级 全新特有
error_page 基于响应状态码的动作 高级
eval_func 调用内置函数为变量赋值 高级 全新特有
expires 配置发送给客户端的expires和cc头 标准
gzip 启用gzip自动压缩响应 标准
gzip_types 启用gzip的MIME类型 高级 修改增强
if 根据指定条件控制CDN Pro配置的指定流程 标准 修改增强
elseif 评估其他条件 标准 修改增强
else 如果所有条件均不满足,则使用默认配置 标准 修改增强
internal 内置location配置块的标识 高级
limit_rate 限制对客户端的响应传输速率(字节/秒) 标准
limit_rate_after 配置值以内的正文将不进行限速 标准
location 定义一个URI匹配条件和相关配置 标准
origin_connect_timeout 设置源站连接超时时间 高级 全新特有
origin_fast_route 启用回源快速路由 高级 全新特有
origin_follow_redirect 遵循来自源站的30X重定向 高级 全新特有
origin_header_modify 提前修改源站响应头 标准 全新特有
origin_limit_rate 限制源站响应速率 标准 全新特有
origin_pass 设置源站 标准 全新特有
origin_read_timeout 设置源站读取超时时间 高级 全新特有
origin_send_timeout 设置源站发送超时时间 高级 全新特有
origin_selection_algorithm 选择源站IP的策略 高级 全新特有
origin_set_header 修改发往源站的请求头 标准 全新特有
proxy_buffering 缓冲来自上游的响应 标准
proxy_cache_background_update 缓存优先响应,后台子请求更新缓存 标准
proxy_cache_bypass 设置不查询缓存的条件 标准
proxy_cache_lock 锁定机制以避免多个请求同时填充缓存 高级
proxy_cache_lock_age 设置填充缓存请求的最小间隔 标准
proxy_cache_lock_timeout 请求放行至上游之前的最长等待时间 标准
proxy_cache_max_stale 允许提供过期内容的最大过期时间 标准 全新特有
proxy_cache_methods 设置可缓存的HTTP方法 标准
proxy_cache_min_age 指定最短缓存时间 标准 全新特有
proxy_cache_use_stale 允许提供过期的内容 标准
proxy_cache_valid 设置默认缓存时间 标准 修改增强
proxy_cache_vary 遵循源站的Vary头 高级 全新特有
proxy_cookie_domain 替换cookie的作用域 高级
proxy_cookie_path 替换cookie的作用路径 高级
proxy_hide_header 不将某个头部从源站传递给客户端 标准
proxy_ignore_cache_control 忽略C-C中的一些参数 标准 全新特有
proxy_ignore_client_abort 忽略客户端中止行为,保持与源站连接 高级 LB Logic
proxy_ignore_headers 忽略来自上游的一些头部 标准
proxy_method 设置像源站发起回源请求时的HTTP协议方法 标准
proxy_next_upstream 设置对另一个源站IP发起重试的条件 高级
proxy_next_upstream_timeout 设置对另一个源站IP发起重试的超时时间 高级
proxy_next_upstream_tries 设置对另一个源站IP发起重试的请求次数 高级
proxy_no_cache 不缓存源站响应的条件 标准
proxy_pass_header 将默认情况下隐藏的响应头传递给客户端 标准
proxy_pass_request_body 将客户端的请求正文传递给源站 标准
proxy_pass_request_headers 将客户端的请求头传递给源站 标准
proxy_request_body_in_cache_key 在缓存key中添加请求正文 高级 全新特有
proxy_redirect 替换30X的location响应头 高级
proxy_set 根据响应为变量赋值 标准 全新特有
proxy_ssl_protocols 与源站通信的TLS协议版本 高级
realtime_log_downsample 设置实时日志采样系数 标准 全新特有
return 向客户端返回状态码和消息 标准
rewrite 改写URI 标准
satisfy 如何组合多个访问控制结果 标准
sanitize_accept_encoding 预处理A-E头 高级 全新特有
secure_link 设置一个内置访问控制方法 高级
secure_link_md5 设置一个内置访问控制方法(MD5) 高级
secure_link_secret 设置一个内置访问控制方法(保密信息) 高级
set 给一个变量赋值 标准
slice 将一个大文件切片从源站拉取或缓存 标准 修改增强
slice_ignore_etag 允许切片具有不同的Etag值 标准 全新特有
sorted_querystring_filter_parameter 删除一些查询参数 标准 全新特有
sub_filter 替换响应体里的字符串 高级
sub_filter_last_modified 同时更新L-M响应头 高级
sub_filter_once 只能替换一次匹配的字符串 高级
sub_filter_types 可替换的MINE类型 标准
valid_referers 指定合法的Referer值 标准
access_log_downsampling 设置访问日志采样系数 标准 LB Logic 全新特有

支持的指令说明

add_header

标准 修改增强

使用语法: add_header name value [policy=...] [if(...)] [always];

默认设置: -

可用位置: server, location, if in location

本指令的功能是修改发往客户端的响应头部。默认只在状态码为200, 201, 204, 206, 301-304, 307 或 308时生效。当配置了’always’参数时,则对全部状态码生效。我们在开源版本的基础上做了如下重大改进:

  1. 引入了policy=参数来更精确地控制指令的行为:
add_header X-My-Header $header_value policy=repeat|overwrite|preserve

overwrite: 添加一个头部。如果该头部名称已经存在,则覆盖原有的值。如果value是空字符串,则会将该头部删除。

preserve: 如果头部名称不存在,则添加。否则不做任何操作,保留原头部不变。

repeat: (默认行为) 添加一个头部。如果该头部名称已经存在,则新增一条。

该参数支持变量,其取值必须是上面3者之一。

局限: 对于下面这几个“特殊”头部,本指令的行为是固定的,不受policy参数的控制:

"特殊"头部名称 行为
Cache-Control repeat
Link repeat
Last-Modified overwrite
ETag overwrite

如果需要的话,可以使用proxy_hide_header指令来删除从源站收到的 "Cache-Control"或"Link"响应头部。

使用举例:

add_header X-Cache-Status $upstream_cache_status policy=preserve;

使用变量的例子:

set $cache_status_method "preserve";  
if ($arg_debug = cache_status) {
    set $cache_status_method "overwrite";
}
add_header X-Cache-Status $upstream_cache_status policy=$cache_status_method;
  1. 引入了if(condition)参数来控制本指令生效的条件。只有当条件为真的时候,本指令才会修改发往客户端的头部,否则完全不起作用。这个if()参数必须出现在本指令的末尾。condition可以是如下条件表达式:
  • 变量名,如果该变量不存在或者其值为‘0’或空,则条件不成立,否则条件成立;
  • 用"=“或者”!="来比较一个变量是否等于一个字符串;
  • 用"~"(区分大小写)或者"~*"(不区分大小写)来对一个变量进行正则匹配。也支持用"!~“或者”!~*"来进行反向匹配。请注意如果正则表达式包含‘}’或‘;’字符,则需要用引号来包裹该表达式。

使用举例:

add_header X-Upstream-Status-OK 1 if($upstream_response_status = 200);
add_header X-Status-Good 1 if($upstream_response_status ~ ^[23]);
  1. 针对该指令的另一个改进是支持合并不同层级(server/location/if)里的配置。但是如果同一个头部名称出现在了不同的层级里,则只有最内层的配置会生效。

add_trailer

标准 修改增强

使用语法: add_trailer name value [always];

默认设置: -

可用位置: server, location, if in location

该指令可用于在响应正文之后添加一个尾部(trailer)。默认只在状态码为200, 201, 206, 301, 302, 303, 307或308时生效。当携带 “always” 参数时,则对所有状态码生效。参数 value 可以是变量。CDN Pro 在 开源版本 的基础上做了如下修改和增强:

  1. 该指令的主要设计用途是可以在边缘逻辑里传递一些数据给7层负载均衡器,从而使实时日志可以用 $upstream_trailer_* 变量来获取这些数据。尽管大部分的数据都可以用 add_header 指令通过响应头来传递,有些数据在生成响应头时还并不存在,比如:$upstream_bytes_received$upstream_bytes_sent$upstream_response_time$request_cpu_time。这些数据必须要等到响应正文结束以后才完整。使用本指令是唯一可以将这些数据传递给实时日志的方法。

  2. 如果来自源站的响应携带有 Content-Length 头,开源版本会将其去掉,并且把 Transfer-Encoding 改成 “chunked”。CDN Pro 修改了这个逻辑以确保客户端收到的响应保持正常编码,并仍然携带 Content-Length 头。本指令添加的尾部并不会出现在发给客户的响应里。

allow

标准 修改增强

使用语法: allow address | CIDR | all;

默认设置: -

可用位置: server, location

允许来自指定的网址或者网段的客户访问,该指令通常会和 deny 指令一起使用。
CDN Pro 在 nginx 开源版本 基础上上进行了部分代码优化,使其能更好地适配 CDN 分层缓存结构。

auth_request

高级 修改增强

使用语法: auth_request uri | off;

默认设置: auth_request off;

可用位置: server, location

本指令支持指定一个URI路径来进行访问控制。CDN Pro 服务器将发起针对该 URI 的鉴权子请求,并根据该子请求的结果对原始请求进行访问控制。我们对 Nginx 开源版本做了改进以允参数里包含变量。这使得用户可以把URL里的参数传递给鉴权逻辑:

auth_request /auth$is_args$args;

auth_request_set

高级

使用语法: auth_request_set $variable value;

默认设置:

可用位置: server, location

须与 auth_request 指令一起使用,在鉴权子请求完成后将响应中的某些数据值(如响应头,状态码等)赋值给变量。代码逻辑源自 Nginx 开源版本,无改动。

break

标准

使用语法: break;

默认设置:

可用位置: server, location, if

终止执行当前 nginx rewrite 模块的指令。代码逻辑源自 Nginx 开源版本,无改动。
该指令属于 nginx rewrite 模块。在 CDN Pro 对请求处理的早期阶段中,它将与同一模块中的其他指令一同被执行。

注意: 如果一个 location 中包含了 break 指令,它有可能使之后的"return"指令失效。因此我们要求该 location 必须直接包含一个 origin_pass 指令来确保正确生成响应。

client_body_timeout

高级 修改增强

使用语法: client_body_timeout time;

默认设置: 匹配 origin_send_timeout 的设置(如果存在),或 20s

可用位置: server

该指令用于设置 CDN Pro 边缘服务器从客户端接收请求正文时的最长空闲等待时间。如果您需要在加速项中更改它的默认值,请联系我们的技术支持团队。可设最大值为 60 秒。

client_header_timeout

高级 修改增强

使用语法: client_header_timeout time;

默认设置: client_header_timeout 10;

可用位置: server

该指令设置 CDN Pro 边缘服务器从客户端接收完整请求头的最长空闲等待时间。如果您需要在加速项中更改它的默认值,请联系我们的技术支持团队。可设最大值为 60 秒。请注意,该配置对Host 请求头无效,因为服务器需要其值来确定对应的Edge Logic。如果在 10 秒内没有收到来自客户端的 Host 请求头,服务器将关闭连接。

client_max_body_size

高级

使用语法: client_max_body_size size;

默认设置: client_header_timeout 128m;

可用位置: server, location

设置允许的最大请求正文。如果请求正文超过此大小,则向客户端返回错误码413 (Request Entity Too Large)。请注意部分浏览器无法正确显示该错误。 如果把 size 配置成 0 则会停止检查请求正文大小。

一般来说,您需要在 Load Balancer 和 Edge Logic 里同时配置本指令。

client_send_timeout

高级 全新特有

使用语法: client_send_timeout time;

默认设置: matches origin_read_timeout if it is set, or 20s

可用位置: server

该指令与开源版本的 send_timeout 指令非常相似,用于设置向客户端发送响应时的最大空闲等待时间。如果您需要在加速项中更改它的默认值,请联系我们的技术支持团队。可设最大值为 60 秒。

custom_log_field

高级 全新特有

使用语法: custom_log_field id value;

默认设置: -

可用位置: server, location, if in location

该指令允许您将最多 2 个自定义字段添加到访问日志中。id的值可以是1或者2,value的值可以包含变量。您在自定义日志下载格式,或使用我们的高级分析工具时,可以通过关键字 “custom1” 和 “custom2” 来引用这两个字段。如果您需要开启此功能,请联系我们的技术支持团队。

示例:

location / {
  custom_log_field 1 $http_x_data; # 将请求头X-Data的值保存到custom1
  custom_log_field 2 $cookie_abc; # 将cookie abc的值保存到custom2
  ...
}

deny

标准 修改增强

使用语法: deny address | CIDR | all;

默认设置:

可用位置: server, location

拒绝(返回 403)来自指定网络或地址的访问请求。该指令通常与 allow 一起使用。 CDN Pro 在 nginx 开源版本 基础上进行了部分代码优化,使其能更好适配 CDN 分层缓存结构。

enable_websocket

高级 全新特有

使用语法: enable_websocket;

默认设置: -

可用位置: server, location

该指令用于开启 WebSocket 协议。客户端必须确保不使用 HTTP/2。默认读取和发送超时设置为 21 秒,您也可以使用 origin_read_timeoutorigin_send_timeout 指令修改超时时间。

error_page

高级

使用语法: error_page code ... uri;

默认设置: -

可用位置: server, location, if in location

本指令允许您将源站的响应状态码作为条件来跳转到一个指定的URI。本指令可依照以下顺序,携带3组参数:
第一组:(必填项)作为判定条件的一个或多个原始状态码,以空格隔开。比如 “400 401 402 403 404 406 501 502 503 504”;
第二组:(非必填)设置一个新的响应状态码,格式为 “=200”。也可以用 “=” 使用新的URI返回的状态码;
第三组:(必填项)设置新的响应正文,格式为 URI 或者一个完整的 URL。比如 “@error”(named URI) 或 “http://www.abc.com” (完整URL)。当使用完整 URL 时,会把响应状态码改为302(除非第二组参数为 “=301”,则新响应状态码为301,其余情况下皆为302)。;
代码逻辑源自 Nginx 开源版本无改动。 同时 CDN Pro 默认开启了 proxy_intercept_errors on 来支持将源的响应状态码作为判断条件。

例如,下述指令可以在第一个源站返回状态码 401或403 时尝试第二个源站:

location /abc {
  origin_pass my-origin1;
  error_page 401 403 = @try_origin2;
}
location @try_origin2 {
  origin_pass my-origin2;
}

eval_func

高级 全新特有

使用语法: eval_func $result {function name} {parameters};

默认设置: -

可用位置: server, location, if

该指令用于执行一些常见的编码、解码、哈希计算、HMAC、加解密和变量对比操作。CDN Pro将其添加到了rewrite 模块 中。目前支持的功能有:

Type Name Syntax
计算哈希值 SHA256, MD5
CRC32
eval_func $output SHA256 $input;
SHA256 和 MD5 返回二进制串; CRC32 返回文本串
BASE64
编解码
BASE64_ENCODE
BASE64_DECODE
eval_func $output BASE64_ENCODE $input;
URL
编解码
URL_ENCODE
URL_DECODE
eval_func $output URL_ENCODE $input;
HEX
编解码
HEX_ENCODE
HEX_DECODE
eval_func $output HEX_ENCODE $input;
AES
加解密
ENCRYPT_AES_256_CBC
DECRYPT_AES_256_CBC
eval_func $output ENCRYPT_AES_256_CBC $key $iv $message;
$key$iv都应为32字节的二进制串。
计算
HMAC
HMAC
HMAC_HEXKEY
eval_func $output HMAC $key $message {dgst-alg};
eval_func $output HMAC_HEXKEY $hexkey $msg {dgst-alg};
{dgst-alg} 可以是 MD5, SHA1, SHA256
RSA
签名
RSA_SIGN
RSA_VERIFY
eval_func $sig RSA_SIGN {dgst-alg} $msg $privkey;
eval_func $ok RSA_VERIFY {dgst-alg} $msg $sig $pubkey;
{dgst-alg} 目前只支持 SHA256
比较
整数
COMPARE_INT eval_func $output COMPARE_INT $data1 $data2;
$data1 > $data2时 $output 的值为 “1”,相等时为 “0”,小于时为 “-1”。
整数
计算器
CALC_INT eval_func $output CALC_INT "$integer + 1000";
计算这个表达式并把结果赋予 $output. 仅支持整数的 +, -, *, / 操作。非法的输入表达式会导致结果为 “NAN”。
整数
绝对值
ABS_INT eval_func $output ABS_INT $integer;
$output 会被赋予 $integer 的绝对值。非法输入会导致结果为空。
字符串
替换
REPLACE eval_func $output REPLACE <old> <new> $input;
字符串
修改
TO_UPPER eval_func $output TO_UPPER $input;
把输入字符串转成大写。
字符串
修改
TO_LOWER eval_func $output TO_LOWER $input;
把输入字符串转成小写。
字符串
修改
SUBSTR eval_func $output SUBSTR <start> <length> $input;
获取输入字符串的一个子串,长度为<length>,起始位置为<start><start>可以是一个负数,就像Javascript的substr()函数一样.
一日之内
的时间
DAY_PERIOD eval_func $out DAY_PERIOD 19:00+0800 12h CN-night;
如果时间在19:00+0800之后的12小时内,则返回’CN-night’

注意: 使用加粗字体 标记的函数的输出值是一个可能无法打印的二进制字符串。因此您需要使用 BASE64_ENCODE、URL_ENCODE 或 HEX_ENCODE 将其转换为可打印格式。

样例:

    eval_func $secret_key SHA256 "mySecret123!";
    eval_func $text HEX_ENCODE $secret_key;
    #the value of $text should be 
    #"ad8fdcda140f607697ec80a8c38e86af19f4bb79ee7f7544abcfaadd827901af"
    eval_func $aseout ENCRYPT_AES_256_CBC $secret_key $iv $message;
    eval_func $hmacout HMAC $secret_key $message SHA256;
    eval_func $hmacout1 HMAC_HEXKEY $text $message SHA256;
    #$hmacout and $hmacout1 should be equal

该指令属于 nginx rewrite 模块。在 CDN Pro 对请求处理的早期阶段中,它将与同一模块中的其他指令一同被执行。

expires

标准

使用语法: expires time; expires epoch | max | off;

默认设置: expires off;

可用位置: server, location, if in location

该指令用于控制 CDN Pro 根据所配时长,在发给客户的响应中添加并修改“ Expires ”和“ Cache-Control ”头部。代码逻辑源自 NGINX 开源版本 ,无改动。该指令仅影响发送到客户端的响应头,它不会改变CDN Pro本身对内容的缓存时间。

gzip

标准

使用语法: gzip on|off;

默认设置: gzip on;

可用位置: server, location, if in location

该指令用于开启或者关闭 CDN Pro 的自动压缩响应功能。源自 NGINX 开源版本,无改动。

gzip_types

高级 修改增强

使用语法: gzip_types mime-type ...;

默认设置: gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/javascript application/xml;

可用位置: server, location

CDN Pro 默认支持上述 MIME 类型文件(匹配不区分大小写)的 gzip 压缩响应(仅当响应正文大小大于 1000 字节时压缩功能才会生效)。该默认行为应该适用于大多数用户。
该指令可用于对其他类型启用压缩。CDN Pro 对开源版本进行了改进以支持形如 text/**javascript 的前、后缀模糊匹配。该指令最多支持20个模糊匹配参数。

if/elseif/else

标准 修改增强

使用语法: if (condition) { ... } elseif (condition) { ... } else {...}

默认设置:

可用位置: server, location

根据指定条件控制 CDN Pro 配置的执行流程。使用之前请确保您完全了解 rewrite 模块 控制流的工作原理。为此我们还编写了使用指导,并在其中推荐了关于该指令的最佳使用方式。同时 CDN Pro 对该指令进行了一些重大改进:

  • 支持&& 运算符,用于执行子条件的逻辑“与”判断。例如:
if ($http_x = 1 && $http_y != 2abc && $http_z) { ... }
  • 支持|| 运算符,用于执行子条件的逻辑“或”判断。例如:
if ($http_x = 1 || $http_y != 2abc && $http_z) { ... }

请注意,当被一起使用时,&& 的优先级高于||。该指令不支持使用括号对子条件进行分组。
我们最多支持 9 个子条件的判断,edge logic的执行逻辑会智能跳过不影响最终结果的子条件。

  • 支持字符串前缀匹配。 如果变量$s1 的值以 $s2开始,那么判断条件 $s1 ^ $s2 将会返回 true 。 $s1 !^ $s2 将会返回 false.
  • 支持用 <<=>>= 进行整数值比较。请确保两个操作数都是有效整数,否则结果将是 false。有效整数可以是十进制数字或者是前缀为“0x”的十六进制数字。
  • 支持多个 elseifelse 语法。例如:
if ($http_x = 1) { ... }
elseif ($http_x = 2) { ... }
elseif ($http_x >= 0xa) { ... }
else { ... }

该指令属于 nginx rewrite 模块。在 CDN Pro 对请求处理的早期阶段中,它将与同一模块中的其他指令一同被执行。

internal

高级

使用语法: internal;

默认设置:

可用位置: location

指定某个 location 块内的逻辑只能用于内部请求,不允许被客户端直接访问。代码逻辑源自 Nginx 开源版本,无改动。

limit_rate

标准

使用语法: limit_rate rate;

默认设置: limit_rate 4m;

可用位置: server, location, if in location

限制对客户端的响应传输速率,以字节/秒为单位。可配范围为 [1-8]m 或 [1-8192]k。默认值为 4MByte/s。

limit_rate_after

标准

使用语法: limit_rate_after size;

默认设置: limit_rate_after 4m;

可用位置: server, location, if in location

响应正文给客户端时,配置值以内的正文将不进行限速,超过配置的值之后的响应的将受到速率限制。可配范围为 [1-8]m,单位为字节。

location

标准

使用语法: location [ = | ~ | ~* | ^~ ] pattern { ... }

默认设置: -

可用位置: server, location

按照请求 URI(不带问号后参数) 进行分类匹配,并在 {} 中设置此类请求的处理逻辑。代码源自NGINX 开源版本,无变更。为了确保服务器能正确生成响应,我们要求每个 locaiton 里须直接(不在嵌套的if或location里)包含一个 return 或者 origin_pass 指令。如果一个 location 里包含了 break 指令,则其必须直接包含 origin_pass。

origin_connect_timeout

高级 全新特有

使用语法: origin_connect_timeout time;

默认设置: origin_connect_timeout 5s;

可用位置: server

该指令是 proxy_connect_timeout 的增强版本。它设置了 CDN Pro 与源站服务器建立连接的超时时间。该值仅限于 [1,15] 中的整数,后跟“s”。 CDN Pro 已确保回源链路上所有节点都遵守此超时值。该指令不能出现在 location 配置块中。

origin_fast_route

高级 全新特有

使用语法: origin_fast_route on|off;

默认设置: origin_fast_route off;

可用位置: server, location, if in location

该指令用于在访问源站时开启使用快速路由功能。此功能由我们专有的 HDT 技术提供支持,可提供更稳定的连接并减少延迟。通过快速路由传输的回源流量可能会被收取比边缘流量更高的费率。

origin_follow_redirect

高级 全新特有

使用语法: origin_follow_redirect;

默认设置: -

可用位置: location

当源站响应 30x 状态码并携带一个 Location 跳转地址时,您或许希望 CDN360 继续对这个地址发起请求直至获取到实际的响应文件,然后再进行缓存和客户端响应。如果将跳转地址传递给客户端来发起新请求会导致更长的时间来获取最终内容。如果需要实现上述行为,您可以在任意一个配置了 origin_pass location 块中使用本指令。

origin_header_modify

标准 全新特有

使用语法: origin_header_modify field value policy=value if(condition);

默认设置: -

可用位置: server, location, if in location

该指令可用于在所有其他处理之前对源站的响应头进行添加、删除或者改写。换句话说,其他指令看到的源站响应头部和值都可能受到该指令的影响。该指令支持使用 nginx 变量作为配置值。

policy 的可能取值是 repeat,overwrite, 以及 preserve。 policy 参数同样支持使用变量作为值。默认的策略是repeat

  • repeat 不管指定响应头原先是否存在,强制添加响应头部和值到上游响应中。
  • overwrite 如果指定响应头已存在,则对已有响应头的值进行改写;否则将配置响应头和值添加到上游响应中。
  • preserve 仅当指定响应头不存在时,才将配置的响应头和值加到上游响应中。

指令后最后的参数 if 可用于设置该指令的生效条件。条件可以是以下之一:

  • 变量名;如果变量的值为空字符串或"0",则为 false。
  • 使用“=”和“!=”运算符将变量与字符串进行比较。
  • 用"~"(区分大小写)或者"~*"(不区分大小写)来对一个变量进行正则匹配。也支持用"!~“或者”!~*"来进行反向匹配。请注意如果正则表达式包含‘}’或‘;’字符,则需要用引号来包裹该表达式。

示例:

根据源站的响应状态码,添加一个响应头 X-Status

origin_header_modify X-Status Good if($upstream_response_status ~ "^[23]");
origin_header_modify X-Status ClientErr if($upstream_response_status ~ "^4");
origin_header_modify X-Status ServerErr if($upstream_response_status ~ "^5");

删除源站响应的 Cache-Control响应头

origin_header_modify Cache-Control "" policy=overwrite;

该指令可跨不同层级(http/server/location/location if)合并。如果不同层级存在针对相同的响应头的配置,则最内层的配置生效。

尽管 CDN360 具有分层缓存结构,该指令仅更改源站响应中的头部(不会更改来自中间节点的响应头)。

origin_limit_rate

标准 全新特有

使用语法: origin_limit_rate rate;

默认设置: origin_limit_rate 0;

可用位置: server, location

该指令在 proxy_limit_rate 指令基础上进行了优化提升,用于限制从源服务器读取正文的速度。

origin_pass

标准 全新特有

使用语法: origin_pass _origin_name[URI];

默认设置: none

可用位置: location, if in location

该指令用于指定获取内容的源站以及URI。它在 nginx proxy_pass 指令的基础上进行了优化提升。该指令携带的参数是在加速项“源站配置”中提前设置好的源站名。源站名后可以选择配置一个 URI,该 URI 中支持使用变量。如果未指定 URI,则 CDN Pro 将以携带问号后参数的完整 URI(可能已被 rewrite 指令更改) 发起对源站的请求。如果您希望回源时去掉问号后参数,请在源名称后添加 $uri。例如:

# 如果没有配置URI,nginx会自动添加URL编码过的$uri以及query string。
origin_pass my_origin;
eval_func $uri_uenc URL_ENCODE $uri;
origin_pass my_origin$uri_uenc$is_args$args; #效果完全同上
origin_pass my_origin$uri_uenc; #不带query string回源
origin_pass my_origin/abc$uri_uenc;

请注意nginx变量$uri的值是被URL解码过的,所以其有可能包含二进制格式,比如UTF-8。
如果源站无法处理二进制的URL,您可以使用eval_func将其URL编码后再用来生成回源请求。

origin_read_timeout

高级 全新特有

使用语法: origin_read_timeout time;

默认设置: origin_read_timeout 20s;

可用位置: server

该指令在 proxy_read_timeout 指令的基础上进行了优化提升。它定义了 CDN Pro 从源服务器读取响应的超时时间。可配值仅限于 [1,60] 中的整数,后跟“s”。CDN Pro 已确保回源链路上所有节点都都遵守此超时值。此指令不支持在 location {}中使用。

origin_send_timeout

高级 全新特有

使用语法: origin_send_timeout time;

默认设置: origin_send_timeout 20s;

可用位置: server

该指令在 proxy_send_timeout 指令的基础上进行了优化提升。它设置了将回源请求从 CDN Pro 节点发送到源站的超时时间。该值仅限于 [1,60] 中的整数,后跟“s”。CDN Pro 已确保回源链路上所有节点都都遵守此超时值。此指令不支持在 location {}中使用。

origin_selection_algorithm

高级 全新特有

使用语法: origin_selection_algorithm {algorithm name};

默认设置: origin_selection_algorithm round_robin;

可用位置: server, location

当源站的域名解析为多个 IP 地址时,该指令用于设置使用哪个算法来选择源站IP。有效值为:

  • round_robin : 轮询回源,默认设置,它尝试将回源流量均匀分配到所有的源站IP上。
  • consistent_hash : 一致性哈希回源,基于回源 URL 的哈希值。如果源站有缓存,可以提高其命中率。
  • sorted_list : 优选回源,按照源站的链路质量状况回最优的源IP。当源站IP地理分布广泛时,此回源方式有助于确保回源性能稳定。

origin_set_header

标准 全新特有

使用语法: origin_set_header field value if(condition);

默认设置: origin_set_header host $host;

可用位置: server, location, if in location

该指令在 proxy_set_header 的指令基础上进行了优化提升,用于增、删、改回源请求头。CDN Pro 对开源版本代码进行了以下提升:

  1. 不同层级(server/location/if)的配置会被合并。但是,如果同一个回源请求头出现在上述不同位置,则只有配置最内层的指令才会生效。
  2. CDN Pro 采用了分层缓存结构,我们确保此指令设置仅在回源站时(而不是回上传父节点时)才会生效。
  3. 使用参数 if(判定条件) 来设置生效条件。如果条件为真,该指令才生效。if 参数需要配置在该指令的末尾。条件可以是以下之一:
  • 变量名,如果该变量不存在或者其值为‘0’或空,则条件不成立,否则条件成立;
  • 用"=“或者”!="来比较一个变量是否等于一个字符串;
  • 用"~"(区分大小写)或者"~*"(不区分大小写)来对一个变量进行正则匹配。也支持用"!~“或者”!~*"来进行反向匹配。请注意如果正则表达式包含‘}’或‘;’字符,则需要用引号来包裹该表达式。

使用本指令需要注意以下事项:

  1. 由于 CDN Pro 采用了分层缓存结构,因此不能使用内置变量 $scheme 和 $remote_addr 作为该指令中 if 的判断条件。如果您需要将客户端使用的协议或 IP 地址传递给源服务器,请使用以下变量:

示例如下:

origin_set_header X-Client-IP $client_real_ip; # 将客户端IP添加到 X-Client-IP 回源请求头中并传递给源站
  1. 如果要使用该指令修改传给源站的 Host 请求头,则需要确保 加速项配置 中的“origins.hostHeader”字段配置为空。否则在配置校验环节将出现校验失败。
  2. CDN Pro 的边缘服务器会默认将来自客户端的大多数请求头部原样传递给父服务器和源站,只有这几个例外:If-Modified-SinceIf-Unmodified-SinceIf-None-MatchIf-MatchRange,以及 If-Range。对于可缓存的请求,服务器在回源的时候会根据缓存策略自动重新生成这些头部。对于不可缓存的请求,如果您希望将这些请求头部原样传递给源站,请参考下面这个示例使用本指令:
proxy_no_cache 1;      # 不要缓存
proxy_cache_bypass 1;  # 不使用缓存文件响应客户
# 将客户端的If-Modified-Since请求头传递给源站
origin_set_header If-Modified-Since $http_if_modified_since;
origin_pass My-Dynamic-Origin;

由于本指令对发往父节点的请求不生效,您需要将源站配置里的"direct connection"选项设为"always direct"来确保边缘服务器会直接联系源站。否则发往父节点的请求仍会缺失这些头部。

proxy_buffering

标准

使用语法: proxy_buffering on | off;

默认设置: proxy_buffering on;

可用位置: server, location

启用或禁用 CDN Pro 的响应缓冲功能。代码源自 NGINX 开源版本,无变更。

proxy_cache_background_update

标准

使用语法: proxy_cache_background_update on | off;;

默认设置: proxy_cache_background_update off;

可用位置: server, location

该指令用于允许 CDN Pro 先将旧缓存响应给客户端,同时通过后台子请求的方式来更新过期缓存。在分发某些需要较长时间才能从源站获取完整数据的大文件时,该配置项有助于提高响应能力,减少客户端的等待时长。通常情况下,它应该与带有 updating 选项的 `proxy_cache_use_stale’ 指令结合使用。

proxy_cache_bypass

标准

使用语法: proxy_cache_bypass string ...;

默认设置: -

可用位置: server, location

该指令用于设置 CDN Pro 不使用已有缓存(意味着必须回源)来响应符合条件的请求。如果字符串参数中至少有一个值不为空且不等于“0”,则 CDN Pro 不会从缓存中取出响应。您可以使用它来强制某些请求回源获取最新的响应,样例如下:

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

该指令不会阻止将源站给的响应保存在 cache 缓存中。这个 "保存"行为是由另一个指令 proxy_no_cache 控制的。一般情况下这两个配置项会同时使用来实现某些文件不缓存。

proxy_cache_lock

高级

使用语法: proxy_cache_lock on/off;

默认设置: proxy_cache_lock on;

可用位置: server, location

当该指令被启用时,如果有多个客户端同时请求同一个缓存中不存在,或者过期的文件,CDN Pro 服务器只会“放行”一个请求至源站去获取内容并填充缓存。其他请求会等待该请求得到结果之后在缓存中读取文件。但是如果等待时间超过 proxy_cache_lock_timeout 指令设置的时间后也会被“放行”至源站。默认情况下,出于减少对源站带宽消耗的考虑,CDN Pro 将该指令设置为开启。同时为了避免该功能在大部分内容不可缓存时引入不必要的延迟,我们将 proxy_cache_lock_timeout 默认值设置为 0。如果您已事先预知了大部分内容是可缓存的,您可以增加该超时的值来降低源站负载。如果您可以通过请求里的变量来鉴别不可缓存的内容,那么请使用 proxy_cache_bypassproxy_no_cache 来跳过缓存处理操作并尽可能降低处理延迟。

proxy_cache_lock_age

标准

使用语法: proxy_cache_lock_age time;

默认设置: proxy_cache_lock_age 15s;

可用位置: server, location

前一个“放行”至源站的请求,没有在该指令设置的时间内完成,则 CDN Pro 将会放行下一个请求用来填充缓存。逻辑源自开源公共版本,无变更。

proxy_cache_lock_timeout

标准

使用语法: proxy_cache_lock_timeout time;

默认设置: proxy_cache_lock_timeout 0s;

可用位置: server, location

该指令为 proxy_cache_lock 指令设置一个超时时间。如果客户端请求等待时间超过该设置,则 CDN Pro 服务器将“放行”等待请求至源站。但响应的内容不会被用来填充缓存。(proxy_cache_lock_age 决定应该多久发送一次请求来填充缓存。)逻辑源自公共版本,无变更。出于优化延迟的考虑默认值为 0s。如果您事先知道该域名下大部分内容都是可缓存的并希望减少源站流量,则可以将其更改为更高的值。

proxy_cache_max_stale

标准 全新特有

使用语法: proxy_cache_max_stale if_error=$time while_revalidate=$time;

默认设置: -

可用位置: server, location

本指令允许边缘服务器返回缓存中过期不太久的内容,以提高终端用户的体验。他的的功能和 Cache-Control 响应头里的 stale-if-errorstale-while-revalidate 参数相同。但是优先级低于该响应头。

其中的 ‘if_error=’ 参数要求 proxy_cache_use_stale 的配置里包含 ‘error’。参数 ‘while_revalidate=’ 必须和 proxy_cache_background_update on; 一同配置,同时要求 proxy_cache_use_stale 的配置里包含 ‘updating’。

proxy_cache_methods

标准

使用语法: proxy_cache_methods GET | HEAD | POST ...;

默认设置: proxy_cache_methods GET HEAD;

可用位置: server, location

该指令用于配置可被 CDN Pro 缓存的客户端请求方法,默认情况下 “GET” 和 “HEAD” 这两种方法将会被配置为可缓存。逻辑源自 NGINX 开源版本 ,无变更。

proxy_cache_min_age

标准 全新特有

使用语法: proxy_cache_min_age time;

默认设置: proxy_cache_min_age 0s;

可用位置: server, location, if in location

Description:

该指令允许您为响应文件配置最小缓存时间。如果源给的 Cache-Control 响应头中的 max-age 小于所指定的参数值,则使用指定的参数值作为缓存时间。例如,如果源站的 Cache-Control 响应头中的max-age值为100s,而该指令配置的值为200s,则内容的有效缓存时间为200s。

CDN Pro服务器将根据源站提供的响应头以及 nginx 指令按照以下优先顺序确定缓存时间:

X-Accel-Expires > Cache-Control (max-age),proxy_cache_min_age > Expires > proxy_cache_valid

当 nginx 根据 Cache-Control 头中的 max-age 值计算缓存时间时,它将该值与 proxy_cache_min_age 中配置的值进行比较,并按照两者的最大值进行内容缓存。
当 nginx 不根据 Cache-Control 头中的 max-age 值计算缓存时间时(例如通过 proxy_ignore_headers 忽略了 Cache-Control 响应头 ), proxy_cache_min_age 指令中的值将不起作用。

注意:该指令中的时间变量可以是带有以下后缀之一的数字,或以下后缀组合而成的数字:

  • s = 秒 (默认值, 例如: 10s)
  • m = 分 (例如: 5m)
  • h = 小时 (例如: 1h)
  • d = 天 (例如: 1d)
  • w = 周 (例如: 1w)
  • M = 月 (例如: 2M)
  • y = 年 (例如: 1y)

如果配置的时间参数没有后缀,则该配置项的单位会被视为秒。

proxy_cache_use_stale

标准

使用语法: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;

默认设置: proxy_cache_use_stale error timeout;

可用位置: server, location

该指令用于确定 CDN Pro 在哪些情况下可以响应过期的缓存给客户端。 逻辑源自 NGINX 开源版本 ,没有变化。根据默认设置,当 CDN Pro 与源建立连接时出现问题时,会响应过期的缓存内容。

proxy_cache_valid

标准 修改增强

使用语法: proxy_cache_valid [code ...] time;

默认设置:

可用位置: server, location

该指令用于给不同的响应状态码设置缓存时间。如果没有显式配置状态码,默认值为200, 301和302。只有当源站提供的响应头中没有缓存规则时(如 Cache-Control\Expire 响应头)时,该配置项才会生效。换句话说,源站的响应头字段 Cache-ControlExpiresSet-Cookie 等具有更高的优先级,除非这些响应头被 proxy_ignore_cache_controlproxy_ignore_headers 忽略。CDN Pro 在NGINX 开源版本 基础上上进行了部分代码优化以支持使用变量来设置缓存时间。变量的值如果不是一个合法的时间参数,则该指令不生效,内容不会缓存。参数值 0 表示缓存响应并将其视为已过期。当 location 模块中没有该配置项时,上一层( server 层)的配置会被继承到 location 中。如果您可以根据请求中的某些参数识别动态/不可缓存的内容,请使用 proxy_cache_bypassproxy_no_cache 来绕过缓存执行过程并提高性能。

proxy_cache_vary

高级 全新特有

使用语法: proxy_cache_vary on | off;

默认设置: proxy_cache_vary off;

可用位置: server, location

如果该指令的参数值为“on”,则 CDN Pro 将遵循源站的 Vary 响应头来区分缓存不同版本的响应正文。请注意,开启了该配置项后的对应缓存需使用“目录刷新”方式来清除。

如果该指令的参数值为“off”,则 CDN Pro 将不会缓存任何携带 Vary 头的响应。

相关信息请查阅:关于 Vary 响应头的处理方式

proxy_cookie_domain

高级

使用语法: proxy_cookie_domain off; proxy_cookie_domain {domain} {replacement};

默认设置: proxy_cookie_domain off;

可用位置: server, location

该指令用于转换源站 set-cookie 响应头中的 domain 选项,将其中原本设置的域名(参数1)转换成更新后的域名(参数2)。源自 NGINX 开源版本,无变更。

proxy_cookie_path

高级

使用语法: proxy_cookie_path off; proxy_cookie_path {path} {replacement};

默认设置: proxy_cookie_path off;

可用位置: server, location

该指令用于转换源站 set-cookie 响应头中的 path 选项,将其中原本设置的path(参数1)转换成更新后的path(参数2)。源自NGINX 开源版本,无变更。

proxy_hide_header

标准

使用语法: proxy_hide_header {field};

默认设置: -

可用位置: server, location

该指令用于隐藏掉某些响应头,从而让这些信息对客户端不可见。源自NGINX 开源版本,无变更。您可以使用该指令来隐藏掉多个响应头。当 location 模块中没有该配置项时,上一层( server 层)的配置会被继承到 location 中。

proxy_ignore_cache_control

标准 全新特有

使用语法: proxy_ignore_cache_control directives…;

默认设置: none

可用位置: server, location, if in location

该指令用于设置 CDN Pro 忽略来自源站 cache-control 响应头中的某些参数。可以忽略以下指令:

  • no-cache
  • no-store
  • private
  • max-age
  • s-maxage
  • stale-while-revalidate
  • stale-if-error

示例:忽略掉来自源响应头中的 no-cache 和 no-store:

proxy_ignore_cache_control no-cache no-store;

注意:该指令并不会修改或者重写 cache-control 响应头。

proxy_ignore_client_abort

高级 LB Logic

使用语法: proxy_ignore_client_abort on | off;

默认设置: proxy_ignore_client_abort off;

可用位置: server, location

设置在客户端中止连接的时候,是否要中止与源站的连接。配置成 on 意味着忽略客户端的中止行为,继续保持与源站的连接和数据传输。off 意味着中止从源站接收数据,如果数据是不可缓存的。可缓存的数据会继续完成传输,不受本指令影响。本指令只能在load balancer logic 里使用。

proxy_ignore_headers

标准

使用语法: proxy_ignore_headers field ...;

默认设置: -

可用位置: server, location

该指令用于设置 CDN Pro 忽略掉来自源站的某些响应头。最常用的情景是用于忽略缓存相关标记,例如 “Cache-Control” 或 “Expires” 响应头。 源自 NGINX 开源版本 无修改。如果您只需要忽略 cache-control 响应头中的部分值,请使用 proxy_ignore_cache_control 指令。

proxy_method

标准

使用语法: proxy_method {method};

默认设置: -

可用位置: server, location

该指令用于设置 CDN Pro 向源站发起回源请求时的 HTTP 协议方法,其参数值可以包含变量。对 开源版本 无修改。

proxy_next_upstream

高级

使用语法: proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;

默认设置: proxy_next_upstream error timeout;

可用位置: server, location

该指令用于设置 CDN Pro 在哪些情况下向源站配置里的下一个服务器发起重试请求。源自 NGINX 公共版本没有变化。

proxy_next_upstream_timeout

高级

使用语法: proxy_next_upstream_timeout {time};

默认设置: proxy_next_upstream_timeout 0;

可用位置: server, location

该指令用于设置 CDN Pro 向源站配置里的下一个服务器发起重试请求的超时时间。默认配置‘0’表示没有超时限制。源自 NGINX 公共版本没有变化。

proxy_next_upstream_tries

高级

使用语法: proxy_next_upstream_tries {number};

默认设置: proxy_next_upstream_tries 0;

可用位置: server, location

该指令用于设置 CDN Pro 向源站配置里的下一个服务器发起重试请求的尝试次数。默认配置‘0’表示没有次数限制。源自 NGINX 公共版本没有变化。

proxy_no_cache

标准

使用语法: proxy_no_cache string ...;

默认设置: -

可用位置: server, location

该指令用于设置 CDN Pro 不对响应进行缓存的条件。如果携带的参数值至少有一个不为空且不为0,则此响应将不被缓存:

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; 
proxy_no_cache $http_pragma    $http_authorization;

由于响应没有被保存,所以在相同条件下也没有必要检索缓存。因此,该指令通常搭配 proxy_cache_bypass 指令一起使用。

proxy_pass_header

标准

使用语法: proxy_pass_header {field};

默认设置: proxy_pass_header Date;

可用位置: server, location

该指令用于设置 CDN Pro 将指定的某个 Nginx 默认隐藏的响应头 传递给客户端。默认设置会将源站返回的 Date 响应头传递给客户端。该响应头携带了 CDN Pro 从源站获取响应的时间点。该指令支持多次配置以传递多个不同的响应头给客户端。只有当一个 location 配置块中没有该指令时,上一层(server 层)的配置才会被继承到 location 中,否则上层的配置会被忽略。

proxy_pass_request_body

标准

使用语法: proxy_pass_request_body on | off;

默认设置: proxy_pass_request_body on;

可用位置: server, location

该指令用于允许或禁止将客户端的请求正文传递给源站。源自 NGINX 开源版本,无变更。

proxy_pass_request_headers

标准

使用语法: proxy_pass_request_headers on | off;

默认设置: proxy_pass_request_headers on;

可用位置: server, location

该指令用于允许或禁止将客户端的请求头传递给源站。源自 NGINX 开源版本,无变更。

proxy_redirect

高级

使用语法: proxy_redirect default; proxy_redirect off; proxy_redirect redirect replacement;

默认设置: proxy_redirect default;

可用位置: server, location

该指令用于修改 CDN Pro 传给客户端的"Location"和"Refresh"响应头中的内容。源自 NGINX 开源版本,无变更。

proxy_set

标准 全新特有

使用语法: proxy_set $variable value [if(...)];

默认设置: none

可用位置: server, location, if in location

该指令将参数 value 的值赋值给变量 $variablevalue 可以是另一个变量或变量和字符串的组合。该指令与 set 指令非常相似,但是它们在请求处理的不同阶段被执行。set 指令是在收到请求后很早的 “rewrite” 阶段中被执行。而 proxy_set 是在从源接收到响应头(在缓存未命中的情况下)或从缓存中读取完毕后才被执行。因此,proxy_set 指令可以将响应头中的信息赋值给目标变量。请注意,响应头有可能被 origin_header_modify 指令修改过。此外,该指令支持 if() 参数,用于指定该指令生效的条件。示例如下:

set $cache_time 1d; # 设置cache_time变量的默认值为 1d
# 如果源站的响应中有 “cachetime” 响应头,则使用该响应头覆盖掉上述默认值
proxy_set $cache_time $upstream_http_cachetime if($upstream_http_cachetime);
proxy_cache_valid $cache_time;
# 截取源站响应头 “version” 中的一段,并发送给客户端
proxy_set $version_number $1 if($upstream_http_version ~ "Version:(.*)$");
add_header version-number $version_number;
# 如果源站响应了 301 或者 302 ,则该响应不缓存 
proxy_set $no_store 1 if($upstream_response_status ~ 30[12]);
proxy_no_cache $no_store;

该指令会跨不同层级(server/location/location if)合并。如果不同层级中使用该指令试图对同一个变量进行赋值,则只有最内层的配置生效。

proxy_request_body_in_cache_key

高级 全新特有

使用语法: proxy_request_body_in_cache_key on/off;
默认设置: proxy_request_body_in_cache_key off
可用位置: server, location, if in location

当参数值是 ‘on’(支持变量)时,服务器将计算请求正文的 MD5 哈希值并将其加到缓存 key 的末尾。此指令主要针对使用 POST 请求来查询信息,并且查询参数携带在请求正文的情形。这类请求通常跟 GET 一样是 idempotent 和安全的,而且其响应也是可缓存的。请注意您需要使用 proxy_cache_methods 指令来启用对 POST 请求的缓存。

此指令的一个限制是它只在请求正文小于4kB时生效。当请求正文大于此门限时,不会有哈希值被添加到缓存 key 中,同时变量 $ignored_body_in_cache_key 的值会被设为 ‘1’。您可以将此变量用于 proxy_cache_bypass 指令来避免缓存这样的请求。如果一定要把更大的请求正文添加到缓存 key 里,您需要在客户端计算哈希值,并通过请求头传递到服务器,然后将其添加到 $cache_misc 变量中。

proxy_ssl_protocols

高级

使用语法: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

默认设置: proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

可用位置: server, location

该指令用于设置 CDN Pro 回源时的握手协议。源自 Nginx 开源版本,无变更。

realtime_log_downsample

标准 全新特有

使用语法: realtime_log_downsample factor;

默认设置: -

可用位置: server, location

该指令用于覆盖加速项配置 实时日志 的“采样率”。 其参数 factor 可以是一个 [0, 65535] 中的整数或一个变量。值 0 表示关闭实时日志功能;1 表示不对实时日志进行采样;N>1 表示每 N 个请求才生成一条实时日志。如果该指令的变量值为空,则指令不生效,维持配置项里的默认值;如果变量值无法被正常解析(非整数的字符串),则该参数将被视为100。最终生效的采样率可通过内置变量 $realtime_log_ds_factor 记录到实时日志中。

return

标准

使用语法: return code [text]; return code URL; return URL;

默认设置: -

可用位置: server, location, if

停止当前的请求处理,并将指定的响应状态码以及正文(如有配置text或URL)返回给客户端。 对 开源版本 没有修改。

该指令属于nginx的 rewrite 模块。它在请求处理的早期阶段同该模块里的其他指令一道被顺序(imperatively)执行。

rewrite

标准

使用语法: rewrite regex replacement [flag];

默认设置: -

可用位置: server, location, if

如果请求URI匹配正则表达式regex,则将其改写为replacement的值。功能上和开源版本完全一致。请注意该指令匹配的对象是变量$uri,一个经过归一化,不带query string的请求URI。如果匹配成功,则会把replacement的值赋给变量$uri.

该指令属于nginx的rewrite模块。它在请求处理的早期阶段同该模块里的其他指令一道被顺序(imperatively)执行。

satisfy

标准

使用语法: satisfy all | any;

默认设置: satisfy all;

可用位置: server, location

该指令用于设置 CDN Pro 对多个访问控制功能的校验方式。当配置值为 all 时,只有当边缘逻辑中所有的 allow, deny 以及 auth_request 的结果都为 pass 时,请求才会通过校验。配置值为 any 时,只要上述指令结果有一个为 pass ,请求就可通过校验。代码逻辑源自 NGINX 开源版本,无变更。
请注意,所有这些校验指令都在 rewrite 模块指令之后才被执行。

sanitize_accept_encoding

高级 全新特有

使用语法: sanitize_accept_encoding enc1 enc2 … ;

默认设置: sanitize_accept_encoding gzip;

可用位置: server

该指令用于修改 Accept-Encoding 请求头,确保其可能的取值不超过5个以提高缓存的利用率。此指令最多可以携带4个参数,每个参数都是一个或多个(以逗号为分隔的)“内容编码格式”,例如“gzip,br”或“br”。对于每个请求,CDN Pro 会把接收到的 Accept-Encoding 请求头与本指令的参数从左至右逐个进行匹配。如果一个参数里的所有格式都出现在了此请求头里,则用该参数值替换掉请求头的值。如果没有能匹配的参数,则将请求头的值改写为“identity”。

示例如下:假设边缘逻辑中的配置是:

sanitize_accept_encoding "gzip,br" "gzip" "deflate" "br";

那么处理逻辑将是:

if (A-E-header.contains("gzip") && A-E-header.contains("br"))
    A-E-header="gzip,br";
else if (A-E-header.contains("gzip")) A-E-header="gzip";
else if (A-E-header.contains("deflate")) A-E-header="deflate";
else if (A-E-header.contains("br")) A-E-header="br";
else A-E-header="identity";

不难看出,该指令的默认设置(“gzip”)会将请求头 Accept-Encoding 的值重写为“gzip”或“identity”。结合 CDN Pro 的默认缓存策略,服务器将仅缓存这两种编码格式中的一种。如果客户端请求另一种格式,服务器将会通过把缓存的版本在线压缩或解压缩来响应。

如果您使用了此指令,那么很可能您还希望 CDN Pro 能根据 Accept-Encoding 请求头的值来区别缓存响应。您可以通过将该请求头的值添加到cache key中来实现此目的:

set $cache_misc $cache_misc."ae=$http_accept_encoding";

secure_link

高级

使用语法: secure_link expression;

默认设置:

可用位置: server, location

该指令定义一个带有变量的字符串,CDN Pro 将从中提取该请求链接的校验值和生存期。代码逻辑源自 Nginx 开源版本,无改动。

secure_link_md5

高级

使用语法: secure_link_md5 expression;

默认设置:

可用位置: server, location

该指令定义一个用于进行 MD5 哈希计算的表达式,计算出的哈希值将与请求中传递的值进行比较。源自 Nginx 开源版本,无改动。

secure_link_secret

高级

使用语法: secure_link_secret word;

默认设置:

可用位置: location

该指令定义了检查请求合法性的秘钥。代码逻辑源自 Nginx 开源版本,无改动。

set

标准

使用语法: set $variable value;

默认设置: -

可用位置: server, location, if

该指令为指定的变量赋值。代码逻辑源自 Nginx 开源版本,无改动。CDN Pro 定义了一个特殊的变量 $cache_misc。用户可以通过给这个变量赋值来 自定义 缓存键。

该指令属于 nginx rewrite 模块。它在请求处理的早期阶段与同一模块中的其他指令一道被顺序(imperatively)执行。

slice

标准 修改增强

使用语法: slice size;

默认设置: slice 0;

可用位置: server, location

该指令用于设置 CDN Pro 从源获取大文件时切片的大小。合法的参数值可以是 0(禁用切片),或一个介于 512k 和 512m 之间(含)的nginx 尺寸 。源站必须支持 range 请求并响应 206 状态码。如果需要将切片的响应进行缓存,请使用指令 proxy_cache_valid 206 ... 来启用对 206 状态码缓存。同时我们在开源版本的基础上对该指令进行了以下修改和增强:

  • CDN Pro 要求所有缓存的切片都携带相同的 ETag 值,以确保这些切片归属于同一个原始文件。当从源站新获取的切片与先前已缓存切片有不同的 Etag 值时,当前与客户端的响应传输将被终止,并且所有已缓存的切片都会立即清除。因此源站在一个文件内容未发生变更的情况下,请务必确保该文件的 ETag 值不会变化。在确实必要的情况下,您可以使用 slice_ignore_etag on; 指令来禁用此校验。
  • 启用切片功能后,CDN Pro 会自动在回源请求里删除 “Accept-Encoding” 头来避免获取压缩响应。如果此行为被其他指令覆盖,例如,origin_set_header Accept-Encoding ... 指令,那么客户端可能会收到损坏的响应。

slice_ignore_etag

标准 全新特有

使用语法: slice_ignore_etag on/off;

默认设置: slice_ignore_etag off;

可用位置: server

该指令用于关闭切片文件的 ETag 一致性检查。如果源无法确保为同一文件生成相同的 ETag 值时,可用该指令作为临时解决方案。

sorted_querystring_filter_parameter

标准 全新特有

使用语法: sorted_querystring_filter_parameter {param1} {param2} … ;

默认设置: -

可用位置: server, location, if in location

从变量$sorted_querystring_args 中删除一些查询参数。
此功能是基于这个 开源模块 实现的。

sub_filter

高级

使用语法: sub_filter {string} {replacement};

默认设置:

可用位置: server, location

该指令用于实现响应正文内容的替换。参数一为期待被替换的原始字符串,参数二为用于替换参数一的新字符串。对 NGINX 开源版本无变更。请注意,当响应被压缩时,搜索和替换操作可能无法正常工作。

sub_filter_last_modified

高级

使用语法: sub_filter_last_modified on | off;

默认设置: sub_filter_last_modified off;

可用位置: server, location

该指令允许在替换期的同时保留原始响应中的 Last-Modified 头字段,以便于响应缓存。代码源自NGINX开源版本,无变更。

sub_filter_once

高级

使用语法: sub_filter_once on | off;

默认设置: sub_filter_once on;

可用位置: server, location

该指用于配置只替换第一次匹配的字符串,还是反复匹配替换。代码源自NGINX开源版本,无变更。

sub_filter_types

标准

使用语法: sub_filter_types {mime-type} ...;

默认设置: sub_filter_types text/html;

可用位置: server, location

该指令表示允许替换的文件类型,默认值为 “text/html” 。您可以使用该指令添加除 “text/html” 以外其他需要执行替换操作的MIME类型。代码源自NGINX开源版本,无变更。

valid_referers

标准

使用语法: valid_referers none | blocked | server_names | {string} ...;

默认设置:

可用位置: server, location

该指令用于设置将内置变量 $invalid_referer 赋值为的空字符串的条件。当请求头 Referer 的值不满足这些条件的时候,内置变量 $invalid_referer 将被赋值为1。代码源自NGINX开源版本,无变更。

access_log_downsampling

标准 LB Logic 全新特有

使用语法: access_log_downsampling factor;

默认设置: -

可用位置: server

本指令用于设置对保存访问日志进行采样的“因子”。数值 N 意味着平均每 N 个请求生产一条访问日志。它可用于减少从 Portal 或 API 下载的访问日志量。可以在日志中用 %samplerate 关键字记录该采样“因子”。该指令对边缘服务器的行为没有影响,包括实时日志(实时日志的采样由 realtime_log_downsample 控制)。在极端情况下,我们可能对某些请求量巨大的域名使用该本令来避免日志系统过载。本指令只能在Load Balancer Logic里使用。

本篇文档内容对您是否有帮助?
有帮助
没帮助
提交成功!非常感谢您的反馈,我们会继续努力做到更好!