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

内容分发网络

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

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

说明

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

Image

控制台配置说明

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

配置

说明

生效对象

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

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

主 KEY

指定一个主密钥。

备 KEY

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

签名参数

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

有效时间

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

鉴权算法

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

  • 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 是否在回源请求中包含签名参数。该配置启用后，回源请求会包含签名参数。

说明

无论该配置是否启用，CDN 均不会在缓存键中包含签名参数。

鉴权计算器

参见 鉴权计算器说明。

请求 URL 格式 

scheme://host/uri?sign=timestamp-rand-uid-<SIGNATURE>(&...)

说明

timestamp 的精度是秒。

请求 URL 示例 

https://www.example.com/img/image.png?sign=1644406401-2e1ca42a1bb248408fc9cf435e5af744-0-54959c1ec3448bf8e992554476248fab

签名计算公式

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

md5(uri-timestamp-rand-uid-key)

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

sha256(uri-timestamp-rand-uid-key)

说明

  • 公式中的 - 是实际的字符，用来分隔鉴权参数。
  • MD5 值是由 32 个十六进制字符组成的。SHA-256 值由 64 个十六进制字符组成的。

签名计算公式中各参数的说明如下：

参数

描述

key

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

uri

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

timestamp

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

rand

表示 请求 URL 格式 中的 rand 参数，是一个随机字符串。长度为 1-100 位。可以包含字母和数字。在 请求 URL 示例 中，该参数值是 2e1ca42a1bb248408fc9cf435e5af744。

uid

表示用户 ID，暂时未使用。您需要设置该参数值为 0 。

鉴权流程

在收到包含签名的客户端请求时，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

不能超过 120 个字符。

签名参数

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

有效时间

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

M3U8 改写

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

最近更新时间：2026.02.09 17:59:47
这个页面对您有帮助吗？
有用
有用
无用
无用