Bunny Storage

Bunny Storage is the object storage service provided by bunny.net. The OpenList driver uses the Bunny Storage HTTP API to list, upload, download, and delete objects. It can also return links through a connected Bunny CDN Pull Zone.

Bunny Storage 是 bunny.net 提供的对象存储服务。OpenList 通过 Bunny Storage HTTP API 列出、上传、下载和删除对象，并可通过关联的 Bunny CDN Pull Zone 返回下载链接。

1. Create a Storage Zone in the bunny.net dashboard.
2. Open the Storage Zone and go to Access > API / HTTP.
3. Copy the following values:
   • Storage Zone Name
   • Password: this is the Storage Zone password used by the AccessKey header.
   • API Endpoint: this depends on the primary region of the Storage Zone.
4. Optional: connect the Storage Zone to a CDN Pull Zone if you want OpenList to return CDN links.

Use the Storage Zone password instead of the account-level bunny.net API key.

See also:

• Bunny Storage quickstart
• Bunny Storage HTTP API

1. 在 bunny.net 控制台中创建一个 Storage Zone。
2. 打开该 Storage Zone，进入 Access > API / HTTP。
3. 复制以下信息：
   • Storage Zone Name（存储区名称）
   • Password：这是通过 AccessKey 请求头使用的 Storage Zone 密码。
   • API Endpoint：该地址取决于 Storage Zone 的主区域。
4. 可选：如果希望 OpenList 返回 CDN 链接，请将 Storage Zone 关联到一个 CDN Pull Zone。

请使用 Storage Zone 密码，不要填写 bunny.net 账户级 API Key。

相关文档：

• Bunny Storage 快速入门
• Bunny Storage HTTP API

The directory inside the Storage Zone to mount. Use / to mount the entire Storage Zone.

For example, use /media to expose only the media directory. The configured root path is automatically included when OpenList creates Storage API and CDN URLs.

要挂载的 Storage Zone 内部目录。填写 / 表示挂载整个 Storage Zone。

例如，填写 /media 只展示 media 目录。OpenList 生成 Storage API 和 CDN URL 时会自动包含此根路径。

Required. Enter the Storage Zone name shown on the Access > API / HTTP page. This is the name, not the numeric Storage Zone ID.

必填。填写 Access > API / HTTP 页面中显示的 Storage Zone 名称。这里需要填写名称， 不是数字形式的 Storage Zone ID。

Required. Enter the Storage Zone password shown on the Access > API / HTTP page.

This credential is different from all of the following:

• The account-level bunny.net API key
• A Stream library API key
• The CDN URL Token Authentication Key

Keep this value private. Anyone with this password can access the Storage Zone through the Storage API.

必填。填写 Access > API / HTTP 页面中显示的 Storage Zone 密码。

此凭据不同于以下密钥：

• bunny.net 账户级 API Key
• Stream Library API Key
• CDN URL Token Authentication Key

请妥善保管此值。获得该密码的人可以通过 Storage API 访问此 Storage Zone。

Required. Enter the API endpoint for the primary region of the Storage Zone. You can enter a hostname or a complete URL; when the protocol is omitted, OpenList uses HTTPS.

The default is storage.bunnycdn.com. Copy the exact endpoint from Access > API / HTTP whenever possible.

必填。填写 Storage Zone 主区域对应的 API Endpoint。可以填写主机名或完整 URL；省略协议时， OpenList 会使用 HTTPS。

默认值为 storage.bunnycdn.com。建议直接复制 Access > API / HTTP 页面中显示的准确地址。

Optional. Enter the hostname of a Pull Zone connected to this Storage Zone, for example:

https://example.b-cdn.net

You can also use a custom hostname bound to the Pull Zone. Usually, the URL should not contain the OpenList mount path or the configured root folder path because OpenList adds the object path automatically.

When this field is empty, downloads use the authenticated Storage API and are proxied by OpenList. When it is set, OpenList can return a CDN URL through a 302 redirect.

可选。填写与此 Storage Zone 关联的 Pull Zone 域名，例如：

https://example.b-cdn.net

也可以填写绑定到 Pull Zone 的自定义域名。通常不要在此 URL 中重复填写 OpenList 挂载路径或 已配置的根文件夹路径，因为 OpenList 会自动添加对象路径。

此字段为空时，下载使用需要鉴权的 Storage API，并由 OpenList 本机代理。填写后，OpenList 可通过 302 重定向返回 CDN URL。

Optional. Fill this field only when Token Authentication is enabled for the Pull Zone.

Go to CDN > your Pull Zone > Security, enable Token Authentication, and copy the URL Token Authentication Key. Do not use the Storage Zone password here.

If this field is empty, OpenList returns an unsigned CDN URL. The Pull Zone must allow that URL to be accessed without a token.

可选。仅在 Pull Zone 已启用 Token Authentication 时填写。

进入 CDN > 对应的 Pull Zone > Security，启用 Token Authentication，然后复制 URL Token Authentication Key。此处不要填写 Storage Zone 密码。

此字段为空时，OpenList 返回未签名的 CDN URL，因此 Pull Zone 必须允许无 Token 访问。

The signing method must match the Token Authentication method accepted by the Pull Zone.

The Bunny Basic MD5 token method is not supported by this driver.

For the current Bunny signing format, see Advanced Token Authentication.

签名方式必须与 Pull Zone 接受的 Token Authentication 方式一致。

本驱动不支持 Bunny Basic MD5 Token 方式。

当前 Bunny 签名格式请参考 Advanced Token Authentication。

When enabled, the client IP address is included in the CDN signature. Enable Token IP Validation for the Pull Zone at the same time.

Consider the following before enabling it:

• Bunny Token IP Validation supports IPv4 addresses.
• A link generated for one IP cannot be used from another IP.
• Proxies, VPNs, mobile networks, or an incorrectly configured reverse proxy can cause a valid link to return 403 Forbidden.
• OpenList caches these links separately for each client IP.

Leave this option disabled unless IP locking is required.

启用后，客户端 IP 地址会参与 CDN 签名，同时还需要在 Pull Zone 中启用 Token IP Validation。

启用前请注意：

• Bunny Token IP Validation 支持 IPv4 地址。
• 为一个 IP 生成的链接不能从另一个 IP 使用。
• 代理、VPN、移动网络或错误配置的反向代理可能导致有效链接返回 403 Forbidden。
• OpenList 会按客户端 IP 分别缓存此类链接。

如无 IP 锁定需求，建议保持关闭。

The validity period of a signed CDN URL, in hours. The default is 4. Values less than or equal to 0 are reset to 4.

签名 CDN URL 的有效期，单位为小时。默认值为 4；小于或等于 0 的值会重置为 4。

The file name used to represent an empty directory. The default is .openlist.

Bunny Storage stores objects rather than real empty directories. When OpenList creates a directory, it uploads an empty placeholder object and normally hides that object from listings.

Avoid using the placeholder name for a real file. If you change this setting after directories have already been created, old placeholder objects may become visible.

用于表示空目录的占位文件名，默认值为 .openlist。

Bunny Storage 保存的是对象，不存在真正的空目录。OpenList 创建目录时会上传一个空的占位 对象，并在正常列出目录时隐藏该对象。

请勿将此名称用于真实文件。在已经创建目录后更改此设置，旧的占位对象可能会显示出来。

The general Web proxy and WebDAV policy settings can still be used to select a proxy strategy when required.

如有需要，仍可通过通用的 Web 代理 和 WebDAV 策略 设置选择代理方式。

• Confirm that Access key contains the Storage Zone password, not the account API key.
• Confirm that Storage zone name contains the name rather than the numeric ID.
• Confirm that Endpoint matches the primary region shown on the Storage Zone access page.

• 确认 Access Key 填写的是 Storage Zone 密码，而不是账户 API Key。
• 确认 Storage Zone 名称 填写的是名称，而不是数字 ID。
• 确认 Endpoint 与 Storage Zone Access 页面显示的主区域一致。

• Confirm that CDN token key is the URL Token Authentication Key of the same Pull Zone.
• Confirm that CDN token method matches the Pull Zone configuration. Current Advanced Token Authentication normally uses hmac_sha256.
• When IP validation is enabled, confirm that OpenList receives the real client IPv4 address.
• Check whether the signed URL has expired.

• 确认 CDN Token Key 是同一个 Pull Zone 的 URL Token Authentication Key。
• 确认 CDN Token 签名方式 与 Pull Zone 配置一致。当前 Advanced Token Authentication 通常使用 hmac_sha256。
• 启用 IP 验证时，确认 OpenList 获取到了真实的客户端 IPv4 地址。
• 检查签名 URL 是否已经过期。

Set CDN base URL to the Pull Zone hostname only, such as https://my-pull-zone.b-cdn.net. Do not repeat the OpenList mount path or root folder path in that field. OpenList removes the mount path and adds the configured Storage Zone root path when building the CDN URL.

将 CDN 基础 URL 设置为 Pull Zone 域名本身，例如 https://my-pull-zone.b-cdn.net。不要在此字段中重复填写 OpenList 挂载路径或根文件夹 路径。OpenList 构造 CDN URL 时会移除挂载路径，并自动添加配置的 Storage Zone 根路径。