AI 参与说明（Agent：Codex）：本文由 Agent 根据用户问题与 Cloudflare 官方文档整理，并区分官方事实与界面现象推断；资料核对于 2026-08-23。R2 Data Catalog 仍处于 Public Beta，界面、命令与计费可能变化，请以链接的一手资料为准。
结论：R2 Data Catalog 不是一种会根据文件内容自动识别的 bucket 类型，而是可以附加到既有 R2 bucket 上的 Apache Iceberg catalog 能力。 一个只存放图片的旧 bucket 出现在 R2 Data Catalog 相关界面中，与图片格式、对象数量和创建时间无关；更可能是 Dashboard 改版后展示了可选的既有 bucket，或者这个 bucket 曾被某个流程显式启用过 catalog。即使已经启用，原有 PNG、JPEG 等对象也不会自动变成 Iceberg table，底层 bucket 仍然是普通 R2 object storage。
R2 Data Catalog 解决什么问题#
R2 Data Catalog 是 Cloudflare 托管的 Apache Iceberg REST catalog，并直接与 R2 bucket 集成。它面向数据仓库和 lakehouse 场景，负责维护：
- namespace 与 table 的清单；
- table 当前指向哪一版 Iceberg metadata；
- snapshot、schema evolution 和并发提交所需的协调状态；
- Spark、Snowflake、DuckDB、PyIceberg 等 Iceberg 客户端使用的标准 REST catalog 接口。
Iceberg 的 Parquet data files、manifest 和 metadata files 仍存放在 object storage 中；catalog 充当这些 table 的“索引和当前版本指针”。它本身不是负责执行 SQL 的查询引擎。Cloudflare 自己的查询引擎是 R2 SQL，也可以改用其他 Iceberg-compatible engine。
flowchart TB A["Spark / Snowflake / DuckDB / PyIceberg / R2 SQL"] B["R2 Data Catalog\nIceberg REST catalog 与事务协调"] C["同一个 R2 bucket"] D["Iceberg tables\nParquet、manifest、metadata"] E["普通 objects\n图片、压缩包及其他文件"] A --> B B --> C C --> D C --> E
这个分层也说明了它的适用边界：
| 需求 | 合适的能力 |
|---|---|
| 保存和通过 CDN 分发图片、附件或备份 | 直接使用 R2 object storage |
| 管理大型结构化分析数据的 schema、snapshot 和并发提交 | R2 Data Catalog + Apache Iceberg |
| 对 Iceberg tables 执行 SQL | R2 SQL 或其他 Iceberg-compatible engine |
| 事务型业务数据和低延迟点查询 | D1、PostgreSQL、Convex 等数据库，而不是 Iceberg catalog |
它目前确实是 Public Beta#
截至 2026-08-23，Cloudflare 官方概览仍将 R2 Data Catalog 标为 Public Beta，所有具有 R2 subscription 的开发者都可以使用。Beta 表示接口、限制和运维行为仍可能变化，不等于免费：Cloudflare 已于 2026-08-03 对非 Enterprise 账户启用计费。
当前费用是在普通 R2 storage 与 operations 之外计算的：catalog metadata operations 每月包含 100 万次，超出后按每 100 万次 9 美元计费；自动 compaction 另按处理的数据量和对象数计费，只有为 table 开启 compaction 才产生该部分费用。详细数字和免费额度应以 R2 Data Catalog pricing 为准。
普通图片的上传、读取和 CDN 访问仍属于 R2 的存储与对象操作。Cloudflare 不会因为对象扩展名是 .jpg、.png 或 .webp，就把这些请求算成 Iceberg catalog operations。
为什么旧图片 bucket 会出现在这个产品下面#
要先区分两种界面：
情况一：它只出现在 Create catalog 的 bucket 选择器中#
这只表示该 bucket 可以被选择来启用 R2 Data Catalog，并不表示已经启用。官方的 Manage catalogs 流程明确允许选择一个 existing bucket，也允许输入新名称并顺便创建 bucket。
因此，“选择器里看得到旧 bucket”只是资源复用入口。Dashboard 不需要先分析里面存的是图片、日志还是 Parquet。
情况二：它出现在 catalog overview，并有 Catalog URI、Warehouse 或 Disable 设置#
这表示该 bucket 至少曾经启用过 catalog，而且对应的 catalog resource 仍然存在。Cloudflare 的 List R2 Data Catalogs API 将该列表定义为“已启用为 Apache Iceberg catalogs 的 R2 buckets”；catalog 还可能处于 active 或 inactive 状态。启用操作会为 bucket 打开 Iceberg REST catalog interface，并返回 Catalog URI 与 Warehouse。可能的来源包括：
- 以前在 R2 bucket 的 Settings 中手动启用；
- 运行过
wrangler r2 bucket catalog enable； - 通过 API 或 Terraform 创建
cloudflare_r2_data_catalog； wrangler pipelines setup的 Simple setup 在缺少 catalog 时自动启用。
Cloudflare 在 2026-05-28 为 R2 Data Catalog 上线了独立的 Dashboard 区域，替代原来嵌在单个 R2 bucket Settings 中的面板，并把 catalog resources 集中展示。这会让一个很早创建的 bucket 看起来像是后来被“挪进”了新产品分类。Overview 中的 R2 Bucket Size 是底层整个 bucket 的大小，普通图片也会计入这个数字；这同样不表示 catalog 已经把图片登记成 table data。
公开文档没有描述“根据 bucket 中的文件类型自动启用 catalog”的机制；相反，所有官方入口都包含明确的 enable 或 Create catalog 动作。因此可以确定，图片内容不是归类依据；但仅凭界面截图之外的描述，无法断定具体是哪一次操作启用了某个账户中的 bucket。
启用后，原有图片会发生什么#
启用 catalog 不会：
- 迁移、转码或重写现有图片；
- 自动从 object key 或 MIME type 推导 table schema；
- 把既有图片注册成 Iceberg table；
- 改变原有 S3-compatible API、Workers binding 或 custom domain 的对象访问方式。
官方 Getting started 的顺序也是先在 bucket 上启用 catalog，再通过 PyIceberg 等客户端显式创建 namespace、table 并写入 table data。换句话说，catalog 能力与普通 objects 可以存在于同一个 bucket 中，但两者不是同一套数据语义。
技术上可以混放，工程上通常不建议把网站图片 bucket 同时当作 Iceberg warehouse。Cloudflare 会在 catalog-enabled bucket 上执行手工 object 删除时发出警告：绕过 catalog 修改 Iceberg 管理的文件，可能让 table metadata 指向不存在的文件。把图片和 analytical tables 分到不同 bucket，权限、生命周期规则、删除流程和成本归因都会更清楚。
如何确认 bucket 是否真的启用了 catalog#
先看 Dashboard：
- 只在 Create catalog 的 existing bucket 选择器里出现：不能据此判断已经启用。
- 能打开 catalog detail，并看到 Catalog URI、Warehouse、table maintenance 或 Disable：可以判断至少曾经启用；再看 status 是
active还是inactive。 - 再检查 namespace 与 table 列表；空列表表示尚未创建 Iceberg table，不代表 catalog 没有启用。
也可以使用当前 Wrangler 的只读查询命令：
npx wrangler r2 bucket catalog get <BUCKET_NAME>该命令只读取指定 bucket 的 Data Catalog 状态。若返回 Catalog URI、Warehouse 和 status，说明 catalog resource 存在；若返回未启用错误，则 Dashboard 中看到的更可能只是创建向导候选项。当前命令名是 get，可在 Wrangler R2 command reference 中核对。
如果确认 catalog 已启用、没有任何 namespace/table，也没有 Pipelines、R2 SQL、Spark 或其他客户端依赖它，可以再评估是否关闭。Disable R2 Data Catalog API 会停止 REST catalog interface，并保留 metadata 与 data files，以便之后重新启用；它不是删除 bucket 或清空普通图片的操作。执行前仍应先核对 table 与调用方，避免把“当前没有查询”误判成“从未使用”。
对图片 bucket 的直接建议#
如果这个 bucket 的职责只是为博客或网站提供图片：
- 继续把它当作普通 R2 object storage 使用，不需要为了 Data Catalog 改上传或 CDN 方案。
- 用 Dashboard detail 或
catalog get确认真实状态，不要根据左侧导航或选择器位置判断。 - 若未来要尝试 R2 Data Catalog，单独创建 analytical data bucket，写入 Parquet/Iceberg tables，不与公开图片 bucket 混用。
- 如果旧 bucket 确实莫名被启用，检查团队成员、Wrangler、Terraform 和 Pipelines 的历史配置；文件内容本身不会触发启用。