Skip to content
Storage

智能CDN

启用智能 CDN 缓存后，你数据库里的资源元数据会同步到边缘节点。当资源被更改或删除时，这会自动重新验证缓存。

🌐 With Smart CDN caching enabled, the asset metadata in your database is synchronized to the edge. This automatically revalidates the cache when the asset is changed or deleted.

而且，智能 CDN 通过屏蔽那些即使 URL 使用不同查询字符串但内容没变的资源请求，从而让缓存命中率更高，减轻了源服务器的压力。

🌐 Moreover, the Smart CDN achieves a greater cache hit rate by shielding the origin server from asset requests that remain unchanged, even when different query strings are used in the URL.

缓存时长 #

🌐 Cache duration

当启用智能 CDN 时，资源会尽可能长时间地缓存在 CDN 上。你仍然可以在上传文件时使用 cacheControl 选项来控制资源在浏览器中存储的时间。智能 CDN 缓存适用于包括带签名 URL 在内的所有类型的存储操作。

🌐 When Smart CDN is enabled, the asset is cached on the CDN for as long as possible. You can still control how long assets are stored in the browser using the cacheControl option when uploading a file. Smart CDN caching works with all types of storage operations including signed URLs.

当文件被更新或删除时，CDN 缓存会自动失效以反映更改（包括已转换的图片）。由于资源元数据需要传播到全球所有数据中心，CDN 缓存失效可能最多需要 60 秒。

🌐 When a file is updated or deleted, the CDN cache is automatically invalidated to reflect the change (including transformed images). It can take up to 60 seconds for the CDN cache to be invalidated as the asset metadata has to propagate across all the data-centers around the globe.

当一个资源在 CDN 级别被作废时，浏览器可能不会更新它的缓存。这时就需要用到缓存清理了。

🌐 When an asset is invalidated at the CDN level, browsers may not update its cache. This is where cache eviction comes into play.

缓存驱逐 #

🌐 Cache eviction

即使某个资源在 CDN 层被标记为无效，浏览器可能也不会刷新该资源的缓存。

🌐 Even when an asset is marked as invalidated at the CDN level, browsers may not refresh their cache for that asset.

如果你的资源经常更新，建议把新的资源上传到不同的路径。这样可以确保你总是能够访问到最新的资源。

🌐 If you have assets that undergo frequent updates, it is advisable to upload the new asset to a different path. This approach ensures that you always have the most up-to-date asset accessible.

如果你预料到你的资源可能会被删除，建议使用 cacheControl 选项设置一个较短的浏览器生存时间（TTL）值。默认的 TTL 通常设置为 1 小时，这通常是一个合理的默认值。

🌐 If you anticipate that your asset might be deleted, it's advisable to set a shorter browser Time-to-Live (TTL) value using the cacheControl option. The default TTL is typically set to 1 hour, which is generally a reasonable default value.

绕过缓存 #

🌐 Bypassing cache

如果你需要确保资源直接从源服务器刷新并绕过缓存，你可以通过在 URL 上添加一个唯一的查询字符串，比如 cacheNonce 来实现。

🌐 If you need to ensure assets refresh directly from the origin server and bypass the cache, you can achieve this by adding a unique query string such as cacheNonce to the URL.

例如，你可以使用像 /storage/v1/object/sign/profile-pictures/cat.jpg?cacheNonce=1 这样的 URL，并设置较长的浏览器缓存（例如 1 年）。要更新图片，只需在 URL 中增加 cacheNonce 查询参数，比如 /storage/v1/object/sign/profile-pictures/cat.jpg?cacheNonce=2。CDN 会将其识别为新的对象，并从源服务器获取更新后的版本。

🌐 For instance, you can use a URL like /storage/v1/object/sign/profile-pictures/cat.jpg?cacheNonce=1 with a long browser cache (e.g., 1 year). To update the picture, increment the cacheNonce query parameter in the URL, like /storage/v1/object/sign/profile-pictures/cat.jpg?cacheNonce=2. The CDN will recognize it as a new object and fetch the updated version from the origin.

签名 URL 和 CDN 缓存 #

🌐 Signed URLs and CDN caching

签名 URL 是将私有存储桶中的资源提供给终端用户的主要方式。启用智能 CDN 后，签名 URL 的响应会像其他存储请求一样缓存在 CDN 边缘。

🌐 Signed URLs are the primary way to serve assets from private buckets to end users. With Smart CDN enabled, signed URL responses are cached at the CDN edge, like any other storage request.

和公共桶 URL 不同，每个签名 URL 都包含一个唯一的令牌查询参数（?token=...）。智能 CDN 将每个唯一令牌视为独立的缓存键，这意味着使用任意给定签名 URL 的第一次请求会导致缓存未命中，只有随后使用完全相同 URL 的请求才会命中缓存。即使是几秒钟内生成的同一对象的两个不同签名 URL，也各自维护独立的缓存条目。

🌐 Unlike public bucket URLs, each signed URL contains a unique token query parameter (?token=...). Smart CDN treats each unique token as a separate cache key, meaning the first request with any given signed URL results in a cache miss, and only subsequent requests using that exact same URL will receive a cache hit. Two different signed URLs for the same object, even if generated seconds apart, each maintain their own independent cache entry.

这会影响你如何考虑提供私有资源：

🌐 This affects how you should think about serving private assets:

  • 如果你每次请求都生成一个新的带签名的 URL，缓存永远不会热起来，每次请求都会直接访问源服务器。
  • 如果你在多个请求中重复使用同一个签名 URL，后续请求会从缓存中提供。如果这个资源没有针对用户的访问限制，最好使用公共存储桶。这样可以提高缓存命中率，也完全不用管理签名 URL 的生成。
  • 撤销或过期一个令牌并不会清除它的 CDN 缓存条目。缓存的响应会一直保存在边缘节点，直到缓存时间到期。
  • 删除该对象会使所有令牌中该对象的缓存条目失效。这可能需要大约一分钟才能生效。

令牌过期（expiresIn）和对象的响应缓存 TTL（cacheControl）是独立的。一旦边缘缓存了响应，即使 URL 中的令牌已经过期，该缓存的响应仍然可以在相同的签名 URL 下继续被提供，直到 CDN 缓存时间到期。如果你需要阻止访问一个资源，最好直接从存储桶中删除对象，而不是仅仅依赖令牌过期。

🌐 Token expiry (expiresIn) and the object's response cache TTL (cacheControl) are independent. Once a response is cached at the edge, that cached response can continue to be served for the same signed URL until the CDN cache duration expires, even if the token in that URL has already expired. If you need to cut off access to an asset, delete the object from the bucket rather than relying on token expiry alone.