存储与 CDN

存储与 CDN（302 卸带宽）

imgli 支持 本地盘、S3 兼容对象存储、WebDAV，以及 FTP 兼容层（v0.4+）。生产推荐：热存储用 local 或 S3；对象存储 + 应用门禁 + 公开图 302 到 CDN。FTP 非默认热盘——优先 OpenList/rclone 外置代理，详见 FTP 兼容存储。

概念

概念	说明
存储策略	后台配置的一组驱动参数；可切换默认策略
对象键	按可见性使用 `public/` / `private/` 前缀（surface）
应用门禁	浏览器先打到 `base_url` 的 `/i/{key}`（鉴权、热链、max_views、带宽、私有检查）
cdn_domain	策略上的对象 CDN 前缀；公开图可 302 卸带宽；绝不为 `private/` 键生成
预签名	私有图可短时预签名直连对象存储，或经应用流式输出
源站计量	管理端流量/Referer 只计门禁命中；边缘缓存命中不回源则不计

本地存储

文件落在 IMGLI_DATA_DIR
适合个人/内网；公网大流量时磁盘与出口带宽会成为瓶颈
备份 = 拷贝 data 目录（含 DB 与对象）

S3 兼容

后台填写（名称因 UI 可能略有差异）：

Endpoint、Region、Bucket
Access Key / Secret
Path-style 强制（MinIO 常见需要）
CDN 域名（cdn_domain）：公开对象 302 目标前缀
（可选）与预签名相关的域/配置

桶必须默认私有：关闭匿名 GetObject / ListBucket。
已验证与社区矩阵见 S3 兼容。

WebDAV

独立驱动，适合已有 WebDAV 的网盘/NAS，以及 OpenList 等将 FTP 转为 WebDAV 的出口。无对象预签名模型；CDN 302 非典型（策略页 Caps 会提示）。按后台字段配置即可。

FTP（兼容层 · v0.4+）

定位：tier=compat；管理后台展示 Caps 与启用确认。
能力：读写删 + 连接探测；无 S3 级预签名与推荐 CDN 卸带宽。
性能：包内连接池 + SIZE/流式 Open（v0.4.1）改善 TTFB；大图下载仍受 imgli↔FTP 带宽 限制。
配置与细节：FTP 兼容存储 · 仓库 docs/storage-ftp.md。

CDN 302 推荐拓扑

用户浏览器
  → https://img.example.com/i/{key}     # 应用门禁（鉴权、计量、私有检查）
  → 302 https://cdn.example.com/...     # 仅公开对象
  → 源站对象存储 / 回源

要点：

CDN 不要匿名暴露 private/*（桶 ACL + CDN 源站规则）。
应用层：CDNEligibleObjectKey — 永不为 private/（及 private 缩略图）拼公开 CDN URL。
私有图：短 TTL 预签名或走应用；勿把完整私有 URL 贴到公共 Issue。
配置了 cdn_domain 后，管理后台流量 < CDN 账单是预期现象（见下「源站计量」）。
可选：后台启用热链白名单，限制哪些 Referer 可打 /i。

匿名探测

部署后对私有对象跑：

./scripts/probe-private-object-anon.sh 'https://your-bucket-or-cdn/private/.../object.ext'

期望 非 2xx。若 200，说明桶/CDN 层 S4 失败。

月流量计量（属主出站）

在应用门禁成功放行时按属主记账（自然月，账期语义 Asia/Shanghai）。
用户组可配置 月流量硬顶；用尽后非属主直链超限；quota=0 表示不限制。
上传配额与出站配额是不同维度。

自托管可按用户组自由配置；公共实例运营默认值见公共实例。

源站计量与 doctor

管理端 流量 / Referer 统计的是源站 /i 等门禁路径上的 stats.Record，不是 CDN 边缘全量请求。

公开图常见路径：/i/{key} → 302 → {cdn_domain}/… → 边缘可缓存。
边缘命中不再回源时，仪表盘会低估真实外链热度。
看成本：CDN / 桶账单；看盗链线索：Referer Top + 热链策略。
imgli doctor：启用策略带 cdn_domain 时会 WARN 提示该边界。

仓库说明：deploy/ops/admin-stats-metering.md（与生产 CF 清单分离）。

切换 / 迁移存储

新策略可在后台添加并切换默认；存量对象是否搬迁取决于版本是否提供 storage-migrate 与运维剧本。
切换前备份 DB；确认旧桶在迁完前不要删。

相关：配置 · 安全 · S3 · WebDAV · FTP · admin

工程矩阵（GitHub SSOT）：s3-compatibility · webdav-compatibility · storage-ftp。

校对：2026-07-30 · v0.4.1 · 文档 SSOT。

最后更新: 2026-08-06