CDN 加速与缓存

PG 模式云存储的 CDN 加速、自定义域名、缓存配置等高级能力与传统模式云存储共用。本文聚焦 PG 模式 Bucket 在访问、权限和缓存设计上的使用建议；具体配置入口和完整能力说明参见 CDN 加速。

访问链路

开启 CDN 加速后，文件访问链路可以理解为：

用户浏览器
   │
   ▼
CDN 边缘节点
   │  缓存命中：直接返回
   │  缓存未命中：回源
   ▼
CloudBase Storage API / 对象存储后端

CDN 的核心价值是让用户尽量从就近边缘节点获取文件，降低回源延迟和源站压力。是否容易命中缓存，取决于 URL 是否稳定、是否可被不同用户复用，以及访问请求是否带有用户级鉴权上下文。

Public Bucket 更适合 CDN 缓存

公开资源不需要按用户做差异化鉴权，多个用户访问同一个 URL 时更容易复用同一份 CDN 缓存。适合使用 CDN 的典型资源包括：

Logo、图标、字体、前端静态资源；
公开文章图片、商品图片、活动 Banner；
公开头像、公开媒体内容。

推荐组合：

配置	建议
Bucket	使用独立的公开资源 Bucket，例如 `public-assets`
权限	写明确的公开读 RLS，仅让可信服务端或管理员写入
URL	使用 `getPublicUrl()` 生成稳定公开 URL
路径	使用版本化路径，例如 `assets/logo.v2.png`
缓存	上传时设置合适的 `cacheControl`

const bucket = app.storage.from('public-assets');

await bucket.upload('assets/logo.v2.png', file, {
  contentType: 'image/png',
  cacheControl: 'max-age=31536000',
});

const { data } = bucket.getPublicUrl('assets/logo.v2.png');
console.log(data.publicUrl);

对应的公开读策略示例：

CREATE POLICY public_assets_read ON storage.objects
  FOR SELECT TO anon, authenticated
  USING (bucket_id = 'public-assets');

公开读不等于公开写。生产环境中通常不建议对 anon 开放 INSERT / UPDATE / DELETE。

Private Bucket 的缓存命中率通常更低

私有文件访问通常依赖登录态、Authorization Header 或签名 URL。即使两个用户访问同一个对象，权限上下文也可能不同，因此更难像公开资源一样共享 CDN 缓存。

私有资源建议：

使用 download() 或短期 createSignedUrl()；
不要把签名 URL 当作长期静态资源 URL 使用；
对敏感文件使用较短有效期；
如需长期高缓存命中，应评估文件是否可以转为公开资源 Bucket，并通过 RLS 明确公开读范围。

访问方式	CDN 友好程度	建议
`getPublicUrl()`	高	适合公开、稳定、可缓存资源
`createSignedUrl()`	中 / 低	适合临时分享，不适合作长期静态资源 URL
`download()` + 登录态	低	适合私有文件直接读取
服务端转发下载	取决于实现	适合统一鉴权、审计、限速

覆盖文件与 CDN 缓存

如果同一路径文件已经被 CDN 缓存，覆盖上传后边缘节点可能在一段时间内仍返回旧内容。和 Supabase Storage 类似，推荐优先使用新路径表达新版本，而不是频繁覆盖同一路径。

Cache-Control 建议

cacheControl 应与路径策略配合使用：

资源类型	路径策略	`cacheControl` 建议
版本化静态资源	`assets/logo.v2.png`	可设置较长缓存时间
文章 / 商品图片	带版本、时间戳或 hash	可设置较长缓存时间
头像	固定路径 + URL 版本参数	设置中等缓存时间，或按业务调整
私有签名 URL	临时 URL	不建议依赖长期缓存

如果资源 URL 长期不变，就不要设置过长缓存时间；如果需要长缓存，就尽量让路径本身带版本。

业务需求	推荐做法
公开静态资源，希望高缓存命中	Public Bucket + `getPublicUrl()` + 版本化路径 + 长 `cacheControl`
私有附件，只有本人可访问	Private Bucket + `download()` 或短期 `createSignedUrl()`
临时分享文件给外部用户	`createSignedUrl()`，设置较短有效期
图片更新后必须立刻全量生效	使用新路径并更新业务引用，不依赖覆盖旧路径
头像固定路径	可 `upsert`，但展示 URL 加版本参数

AI 友好提示

让 AI 生成 CDN 相关方案时，建议明确以下信息：

Bucket: public-assets
资源类型：公开静态资源
访问方式：getPublicUrl
路径策略：使用版本化路径，例如 assets/logo.v2.png
缓存策略：长期缓存，上传时设置 cacheControl
是否允许覆盖：不允许，发布新版本时使用新路径
权限：anon/authenticated 可读，仅 service_role 可写

这能帮助 AI 避免把私有签名 URL 当作长期 CDN 地址，也能减少生成「覆盖同一路径 + 长缓存」这类容易产生旧内容问题的方案。

访问链路​

Public Bucket 更适合 CDN 缓存​

Private Bucket 的缓存命中率通常更低​

覆盖文件与 CDN 缓存​

Cache-Control 建议​

推荐决策表​

AI 友好提示​