签名链接

最后更新 2026年11月9日

签名链接让浏览器或 App 不持有你的密钥也能读取私有文件、上传文件或加载改过尺寸的图片。链接由你的服务器生成，过了过期时间就失效。

什么时候需要

域名	签名	过期时间
`<space>.vault`	必须	必须
`<space>.upload`	必须	必须
带改图参数的 `<space>.edge`	必须	不用
不带参数的 `<space>.edge`	不需要	不用

地址格式

https://k3x9q2m7.vault.binedge.net/production/tickets/screenshot.png
  ?exp=1798765200&sig=<signature>

exp 是 Unix 时间（秒，UTC），当前时间早于它时地址有效。sig 是对域名角色、空间名、对象 key 和其余参数做的 HMAC-SHA256，按 base64url 编码。

在服务器上签名

Laravel
签名串

Storage::disk('binedge')
    ->temporaryUrl('tickets/screenshot.png', now()->addMinutes(10));

磁盘会在路径前加上环境前缀（production/ 或 dev/），所以被签名的 key 是 production/tickets/screenshot.png。上传地址用 temporaryUploadUrl() 生成，改图地址用 imageUrl() 生成，见上传和图片处理。

上面这个地址要签名的字符串：

BINEDGE-HMAC-SHA256
vault
k3x9q2m7
production/tickets/screenshot.png
exp=1798765200

用签名密钥对它做 HMAC-SHA256，把结果作为 sig 加到地址上。每一行的规则见下文。

签名串怎么拼

把下面五行用换行符（0x0A）连起来，最后一行后面不加换行：

BINEDGE-HMAC-SHA256
<role>
<space>
<object key>
<canonical query>

<role> 是 vault、upload 或 edge，即域名的第二段。
<object key> 是去掉开头 / 的路径，解码一次后的 UTF-8 字符串。%2F 解码成 /，+ 保持 +。
<canonical query> 取除 sig 以外的全部参数，名和值各按 RFC 3986 编码（A-Z a-z 0-9 - . _ ~ 原样保留，其余字节写成大写 %XX），按编码后的名字排序，写成 名=值 并用 & 连接。没有参数时这一行是空串。
sig 是用签名密钥对整个字符串做的 HMAC-SHA256，按 base64url 编码，不带 = 填充。

哪把密钥签哪些对象

用哪把密钥由对象 key 的第一段决定，不由请求决定：

key 开头	签名密钥
`production/` 或 `shared/`	生产签名密钥
`dev/`	开发签名密钥
其他	拒绝，原因 `key_scope_unknown`

开发服务器只持有开发密钥，签不出 production/ 下的地址。

核对你的实现

下面的示例使用空间名 k3x9q2m7 和测试密钥 binedge-test-production-key。你的代码应当得到相同的签名串和相同的 sig。

key 带空格和中文的私有文件：

BINEDGE-HMAC-SHA256
vault
k3x9q2m7
production/tickets/截图 1.png
exp=1798765200

https://k3x9q2m7.vault.binedge.net/production/tickets/%E6%88%AA%E5%9B%BE%201.png?exp=1798765200&sig=OwicRpmPadfNbMpoA6zAMjfMR1pxvVyUY6b2vLQlCOk

接受 PNG 和 JPEG、最大 10 MiB 的上传。签名串里 types 中的 / 和 , 要编码：

BINEDGE-HMAC-SHA256
upload
k3x9q2m7
production/support-uploads/staging/7/b.jpg
exp=1798765200&max_bytes=10485760&types=image%2Fpng%2Cimage%2Fjpeg

https://k3x9q2m7.upload.binedge.net/production/support-uploads/staging/7/b.jpg?exp=1798765200&max_bytes=10485760&types=image%2Fpng%2Cimage%2Fjpeg&sig=nppbmNIXVrRWiR4ZPWQe9MYUuJSDUNpQ1wGN2oLf1mA

改过尺寸的公开图片。参数按名字排序，edge 地址不带 exp：

BINEDGE-HMAC-SHA256
edge
k3x9q2m7
production/groups/logo.png
crop=smart&fit=cover&fmt=webp&h=144&q=75&w=144

https://k3x9q2m7.edge.binedge.net/production/groups/logo.png?crop=smart&fit=cover&fmt=webp&h=144&q=75&w=144&sig=410RAzVg42KRbH5gEBlzbrYq5d7w-5avYm4J2EA9kro

错误

原因	含义
`signature_missing`	地址里没有 `sig`
`signature_invalid`	`sig` 与地址对不上
`signature_expired`	已过过期时间
`key_scope_unknown`	key 不以 `production/`、`shared/` 或 `dev/` 开头

四种都回 HTTP 403，错误正文里写明原因。在 edge 和 vault 上，访客的浏览器随后会被带到 binedge.net 的错误页，见分发地址格式；upload 原样返回正文：

{"error":{"class":"permission_denied","message":"调用方无权访问该目标或能力。","retryable":false,"platform_code":null,"platform_message":null,"operation_id":null,"reason":"signature_expired"}}

按 reason 判断，不要解析 message。