URL 鉴权

URL 鉴权：给下载或播放链接加上过期时间和签名，节点校验通过才返回内容；含签名串格式、策略配置项和密钥轮换。

作用

URL 鉴权让链接带上过期时间和签名。节点收到请求后，用策略里的密钥重新计算签名，签名对得上、没过期才返回内容，否则返回 403。链接过期后无法再用，也无法被改成别的路径。

使用场景

• 付费下载、课程视频、安装包：由你的业务服务器生成带签名的链接发给登录用户。
• 链接只在几分钟或几小时内有效。
• 把链接绑定到发起请求的客户端 IP，避免转发给他人使用。
• 限制同一个签名最多使用几次。

在哪里配置

控制台：网站管理下的“URL鉴权”，创建策略并绑定到网站。策略保存后随网站配置自动下发到节点。

配置项

参数名只能用字母、数字、点、下划线、波浪号和连字符，不超过 64 个字符。

签名怎么算

对下面这段文本做 HMAC-SHA256，结果用十六进制小写写入签名参数：

CDNCA-URL-AUTH/1
tenant_id=<租户 ID>
site_id=<网站 ID>
method=<请求方法>
path=<路径>
query=<排序后的其他查询参数>
expires=<过期时间 Unix 秒>
key_id=<密钥 ID>
client_ip=<客户端 IP，未绑定 IP 时为空>复制

每个值做百分号编码；查询参数里去掉签名、到期、密钥 ID 三个参数和“签名排除参数”后，按名称和值排序再编码。链接形如 /video/a.mp4?expires=1767225600&kid=k1&sign=<签名>，参数名以策略里设置的为准。

密钥管理

• 创建策略时密钥只显示一次，关闭后无法再查看，请立即保存到你的凭据管理器。
• “轮换密钥”：当前密钥进入平滑轮换窗口，新旧两个密钥都能通过校验，新密钥同样只显示一次。
• “撤销前一密钥”：使用前一个密钥的请求立即失效。
• 禁用策略后，网站不再要求签名。

常见问题

请求返回 403

常见原因：缺少签名、到期或密钥 ID 参数；链接已过期，或过期时间离现在超过“签名有效期上限”；请求方法、路径或查询参数与签名时不一致；开启了绑定客户端 IP 而请求来自另一个 IP；签名使用次数超过上限。

请求返回 503

节点上还没有这个策略版本的密钥，或用于记录使用次数的状态暂时不可用。刚创建、刚轮换后短时间内可能出现，稍后会随配置下发恢复。

签名对不上

按“签名怎么算”逐项核对：路径和查询参数要做百分号编码，查询参数要去掉签名相关参数并按名称排序，过期时间是 Unix 秒，方法大小写与请求一致。

客户端经过了代理

在“可信代理 CIDR”里填这些代理的网段，节点才会从转发头里取真实客户端 IP 参与签名。