You need to enable JavaScript to run this app.
内容分发网络

内容分发网络

请输入
  • 文档首页
    • 内容分发网络用户指南域名管理域名配置管理访问控制URL 鉴权E 类型配置
复制全文
我的收藏
URL 鉴权
E 类型配置
复制全文
我的收藏
E 类型配置

本文档介绍火山引擎内容分发网络（CDN）中 URL 鉴权模块的 E 类型配置。

说明

默认情况下，CDN 会在缓存键和回源请求中包含签名参数。但 CDN 提供了 去除鉴权参数缓存和回源 配置，参见配置说明。

Image

控制台中的配置

在 CDN 控制台中，您需要做以下配置。各配置的输入要求在文档末尾。

配置

说明

生效对象

表示一组匹配条件。CDN 对符合条件的用户请求进行鉴权。您至少需要添加一个条件，最多可以添加 10 个。您可以指定多个条件之间的关系，默认是 或。 或 表示匹配任何一个条件的请求就会被鉴权。且 表示只有匹配所有条件的请求才会被鉴权。每个条件包含匹配类型、匹配方式和匹配值。

匹配类型支持 文件后缀、文件目录、文件全路径 和 全路径正则表达式。其中，要指定 全路径正则表达式，请 提交工单。

主 KEY

指定一个主密钥。

备 KEY

指定一个备密钥。如果鉴权失败，CDN 会使用备密钥再计算一次签名并尝试与请求中的签名比对。

签名参数

指定请求中的签名参数名称，默认是 sign。参数名称不能与时间戳参数相同。

有效时间

指定签名的有效时间，单位是秒，默认值是 1800。该配置与客户端请求中的 timestamp 参数搭配使用，用来计算签名的过期时间。签名的过期时间 = timestamp + 有效时间。在 CDN 收到某个请求时，如果请求中包含的签名的过期时间早于当前时间，CDN 判定签名已过期。此时，CDN 返回 403 响应状态码，表示鉴权失败。

时间戳参数

指定请求中的时间戳参数的名称，默认是 t。参数名称不能与签名参数相同。

时间格式

指定 Unix 时间戳的格式。

鉴权算法

表示签名计算使用的算法。该配置有以下取值：

  • MD5：表示 MD5 算法。
  • SHA256：表示 SHA-256 算法。

说明

SHA-256 算法的安全性比 MD5 高，生成的哈希值出现碰撞的几率比 MD5 低，但是加密和解密过程的耗时比 MD5 长。

M3U8 改写

如果请求 URL 指向一个 HLS Manifest，也就是后缀为 .m3u8 的文件，您可以配置是否对文件中的视频分片 URI 进行改写，以添加签名。默认情况下，CDN 对 EXTINF 标签下的分片 URI 添加签名。

说明

当前，CDN 不支持改写压缩文件。因此，在以下任意情况下，CDN 不会修改 .m3u8 文件。

  • 源站响应中包含 Content-Encoding 头部。该头部表示文件是被压缩的。
  • 该 .m3u8 文件的请求匹配 "智能压缩" 中的配置，表示 CDN 会对该 .m3u8 文件进行压缩。

该配置还包含以下配置。

  • 分片 URI 原参数：表示在改写分片 URI 时是否保留 URI 中原有的查询参数。要使用该配置，请 提交工单。
  • 继承 M3U8 非签名参数：表示是否将请求 URL 中的非签名参数添加到分片 URI 中。要使用该配置，请 提交工单。
  • M3U8 标签改写：表示除默认标签外，需要对其下分片 URI 进行改写的额外标签。

需要留意的是，前两个配置会影响分片 URI 的签名计算。


例子：有一个分片 URI 是 /video.ts?version=1。您设置 分片 URI 原参数 是 删除，继承 M3U8 非签名参数 是 开启，请求 URL 中的查询参数是 q_m3u8=cool。那么改写后的分片 URI 是 /video.ts?q_m3u8=cool，签名是基于这个改写后的 URI 计算的。

在改写分片 URI 时，CDN 可以识别以下格式：

  • 完整 URL。例如 https://example.com/xxx/yyy/song.ts
  • 以根目录路径开头的 URI。例如 /xxx/yyy/song.ts
  • 以相对路径开头的 URI。例如 yyy/song.ts

对于其他不符合规范的 URI 格式，CDN 可能会无法识别，导致签名添加失败。

去除鉴权参数缓存和回源

表示 CDN 是否在缓存键和回源请求中包含签名参数。该配置启用后，缓存键和回源请求均不会包含签名参数。

计算规则

指定参与签名计算的鉴权参数以及这些参数的顺序。

鉴权计算器

参见 鉴权计算器说明。

添加参与签名计算的自定义变量

对于 E 类型，您可以添加自定义的变量用于签名计算。您最多可以添加 50 个变量。您可以点击 新增规则 添加一个变量获取的规则。规则的各配置说明如下：

配置

说明

变量类型

指定变量的类型。该配置有以下取值：

  • 请求参数：表示该变量是请求 URL 中的一个查询参数。
  • 请求头部：表示该变量是请求中的一个头部。

取值方式

表示 CDN 如何将 参数取值 与 请求中的参数匹配。该配置的取值只能是 精确匹配。

参数取值

表示需要额外参与签名计算的变量名称。变量名称不能超过 100 个字符。其他要求如下：

  • 如果 变量类型 是 请求参数，变量名称可以包含字母、数字、连字符（-）、逗号（,）、句号（.）、感叹号（!）。
  • 如果 变量类型 是 请求头部，变量名称可以包含可打印 ASCII 字符，除了以下这些字符：
    • 下划线（_）、空格、双引号（"）、冒号（:）、Delete（ASCII code 127）。

操作

表示您可以对该规则进行的操作。

在您添加自定义变量后，您就可以在设置 计算规则 时选择该变量了。
Image

请求 URL 格式 

scheme://host/uri?sign=\<signature\>&t=timestamp(&...)

说明

timestamp 的精度是秒。

请求 URL 示例 

https://www.example.com/product/cdn?sign=e954e253c33634b510443af72406600f&t=1620291453&query1=value1&query2=value2

签名计算公式

如果您在 URL 鉴权的配置中指定签名算法是 MD5，则签名 的计算公式如下：

md5(<自定义计算规则>)

如果您在 URL 鉴权的配置中指定签名算法是 SHA-256，则签名 的计算公式如下：

sha256(<自定义计算规则>)

说明

  • <自定义计算规则> 表示一个自定义的签名计算规则。在该规则中，您指定用于签名计算的鉴权参数以及这些参数的顺序。在计算签名时，CDN 先将这些参数的值拼接成一个字符串，然后计算该字符串的 MD5 值。该 MD5 值就是签名。
  • MD5 值是由 32 个十六进制字符组成的。SHA-256 值由 64 个十六进制字符组成的。

在计算签名时，其他鉴权类型只能使用固定的计算规则，但是 E 类型允许您自定义计算规则。
您可以指定计算规则包含以下参数，并且通过拖拽调整参数的在计算规则中的出现顺序。

参数

是否必选

描述

密钥

是

表示在 CDN 控制台配置的密钥。

uri

是

表示 请求 URL 格式 中的 uri 参数，以斜杠（/）开头，不包含域名。如果路径包含中文字符，您需要对路径编码。在 请求示例 中，该参数值是 /product/cdn。

时间戳参数

是

表示 请求 URL 格式 中的 timestamp 参数。该参数与控制台中的 有效时间 配置搭配使用，用来计算签名的过期时间。根据控制台中的 时间格式 配置，时间格式使用十进制或十六进制的 Unix 时间戳。在 请求 URL 示例 中，该参数值是 1620291453，是一个十进制 Unix 时间戳。

Referer

否

表示用户请求中 Referer 头部的值。

客户端域名

否

表示请求的加速域名。

Origin

否

表示请求中 Origin 头部的值。

客户端IP

否

表示客户端的 IP 地址。

User-Agent

否

表示请求中 User-Agent 头部的值。

自定义变量

否

表示您在自定义签名计算变量中定义的变量名称。您在 添加参与签名计算的自定义变量 步骤中添加的变量会出现在参数列表中。

鉴权流程

在收到包含签名的客户端请求时，CDN 使用的鉴权流程如下：

  1. 基于请求中包含的鉴权参数以及您在 CDN 控制台中配置的 key，使用 签名计算公式 计算签名。
  2. 判断 CDN 计算得到的签名和客户端请求中包含的签名是否一致。如果不一致，CDN 判断请求不合法，拒绝该请求。
  3. 判断请求是否过期。如果存在以下情况，CDN 判断请求过期，拒绝该请求。
    • (客户端请求中的 timestamp 参数) + (您在 CDN 控制台中配置的有效时间) < (CDN 收到该请求的时间)

输入要求

在配置 URL 鉴权时，请遵循以下输入要求：

配置项

输入要求

生效对象

匹配值字符限制：总长度不能超过 1,024 个字符。不能包含双斜杠（//）、空格、美元符号（$）、问号（?）。


不同匹配类型的额外要求：

  • 文件后缀：匹配值必须是一个或者多个以分号（;）分隔的文件后缀。不能以句点（.）开头。例如：png;txt。
  • 文件目录：匹配值必须是一个或者多个以分号（;）分隔的目录路径。必须以斜杠（/）开头和结尾。例如：/chs/foods/;/us/birds/。
  • 文件全路径：匹配值必须是一个或者多个以分号（;）分隔的文件路径。必须以斜杠（/）开头，可以包含星号（*）用来表示一个或者多个字符。例如：/chs/foods/local*sets;/us/birds/chickadee。
  • 全路径正则表达式：匹配值必须是一个或者多个以分号（;）分隔的正则表达式。例如：/a{1,2}(.*)g。

主 KEY / 备 KEY

由 6-40 个字符组成。

签名参数

  • 不能超过 100 个字符。
  • 大小写敏感。
  • 可以包含字母、数字、下划线（_）、中划线（-）、句号（.）、逗号（,）、感叹号（!）。
  • 至少包含一个字母或者数字。

时间戳参数

  • 不能超过 100 个字符。
  • 大小写敏感。
  • 可以包含字母、数字、下划线（_）、中划线（-）、句号（.）、逗号（,）、感叹号（!）。

有效时间

取值范围是 0-315,360,000。

M3U8 改写

M3U8 标签改写：最多指定 20 个标签，每个标签的长度为 1-100 个字符，不能包含 # 和 :。

最近更新时间：2026.01.08 14:24:31
这个页面对您有帮助吗？
有用
有用
无用
无用