Cloudflare R2 Data Catalog 配置完全指南启用 Catalog、认证授权与客户端接入【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是一份以 Cloudflare R2 Data Catalog 的配置为主题的实操指南覆盖在 R2 存储桶上启用 Iceberg Catalog、创建具备 R2 Storage 与 Data Catalog 双重权限的 API Token、以及通过 PyIceberg 等客户端完成认证接入的完整流程。读者按本文操作后将掌握 Wrangler CLI、Cloudflare Dashboard 与 REST API 三种启用方式能正确构造 Catalog URI、Warehouse 与 Token 三元组并据此写出可运行的 PyIceberg 连接代码与安全的密钥管理方案。R2 Data Catalog 是什么R2 Data Catalog 是 Cloudflare 提供的一项托管式 Apache Iceberg REST Catalog直接内置于 R2 存储桶中无需自建 Catalog 服务端。它支持 ACID 事务、schema 演进、time-travel 查询并通过标准 REST API 供 Spark、PyIceberg、Snowflake、Trino、DuckDB 等多种查询引擎使用且不产生跨云/跨区域的数据出口费用。其完整架构与适用场景可参见仓库中的 r2-data-catalog/README.md。在开始配置前理解三个核心概念非常关键Catalog URICatalog 的 REST 端点形如https://account-id.r2.cloudflarestorage.com/iceberg/bucketWarehouse表的逻辑分组通常与存储桶名一致Vended credentialsCatalog 在数据访问时为查询引擎临时下发的 S3 凭据。前置条件根据 configuration.md 原文开始配置前需要具备一个已开通R2 订阅的 Cloudflare 账户一个已创建好的 R2 存储桶可访问Cloudflare Dashboard或安装有Wrangler CLI的环境可通过npx wrangler直接运行。提示在执行任何wrangler命令前建议先用npx wrangler whoami确认已认证登录该命令会显示当前账户 ID而账户 ID 正是构造 Catalog URI 所需参数之一。在存储桶上启用 Catalog启用 Catalog 有三种方式任选其一即可。方式一Wrangler CLI推荐执行如下命令将BUCKET_NAME替换为你的存储桶名npx wrangler r2 bucket catalog enable BUCKET_NAME命令成功后会输出类似以下内容✅ Data Catalog enabled for bucket my-bucket Catalog URI: https://account-id.r2.cloudflarestorage.com/iceberg/my-bucket Warehouse: my-bucket请务必记下输出的 Catalog URI 与 Warehouse这是后续所有客户端连接的必要参数。方式二Cloudflare Dashboard图形界面进入R2→ 选择目标存储桶 → 打开Settings选项卡滚动到 R2 Data Catalog 区域 → 点击Enable记录页面展示的Catalog URI与Warehouse name。通过 Dashboard 启用后得到的结果与 Wrangler 一致Catalog URIhttps://account-id.r2.cloudflarestorage.com/iceberg/bucket-nameWarehousebucket-name与存储桶同名方式三Cloudflare API程序化对需要自动化或基础设施即代码IaC的场景可直接调用 Cloudflare REST APIcurl -X POST \ https://api.cloudflare.com/client/v4/accounts/account-id/r2/buckets/bucket/catalog \ -H Authorization: Bearer api-token \ -H Content-Type: application/json响应示例{ result: { catalog_uri: https://account-id.r2.cloudflarestorage.com/iceberg/bucket, warehouse: bucket }, success: true }Cloudflare 的 REST API 是这套 Skill 参考中其余能力如 api 参考 所描述的 Iceberg REST Catalog API的底层通道本文的启用接口即位于client/v4/accounts/{account-id}/r2/buckets/{bucket}/catalog。检查 Catalog 状态启用后可用以下命令随时确认状态npx wrangler r2 bucket catalog status BUCKET_NAME输出示例Catalog Status: enabled Catalog URI: https://account-id.r2.cloudflarestorage.com/iceberg/my-bucket Warehouse: my-bucket禁用 Catalog如确有必要npx wrangler r2 bucket catalog disable BUCKET_NAME⚠️重要警告禁用 Catalog不会删除任何表或数据数据文件仍保留在存储桶中但元数据将变为不可访问直到重新启用为止。因此在执行禁用前务必确认后续计划。创建 API Token认证的核心环节R2 Data Catalog 要求 API Token同时具备 R2 Storage 与 R2 Data Catalog 两类权限这是客户端能否完成认证的关键前提。Dashboard 方法推荐进入R2→Manage R2 API Tokens→Create API Token选择权限级别Admin Read WriteCatalog 存储的完整读写权限Admin Read only只读权限适合查询引擎使用立即复制 Token 值仅显示一次之后不可再查看。创建后 Token 将包含以下权限组Workers R2 Data Catalog Write或 ReadWorkers R2 Storage Bucket Item Write或 ReadAPI 方法程序化也可以通过 Cloudflare API 程序化创建 Token所需权限组同上Workers R2 Data Catalog Write或 ReadWorkers R2 Storage Bucket Item Write或 Read从 gotchas.md 的排障经验可以印证这一要求当收到401 Unauthorized时最常见的根因就是 Token 缺少 R2 Data Catalog 权限当在访问数据文件时收到403 Forbidden则是 Token 缺少 R2 Storage Bucket Item 权限。两个权限组缺一不可。客户端配置连接 R2 Data CatalogPyIcebergPyIceberg 是 Python 生态中最常用的 Iceberg 客户端。基础连接方式from pyiceberg.catalog.rest import RestCatalog catalog RestCatalog( namemy_catalog, warehousebucket-name, # Same as bucket name uricatalog-uri, # From enable command tokenapi-token, # From token creation )带凭据管理的完整示例推荐将凭据放入环境变量import os from pyiceberg.catalog.rest import RestCatalog # Store credentials in environment variables WAREHOUSE os.getenv(R2_WAREHOUSE) # e.g., my-bucket CATALOG_URI os.getenv(R2_CATALOG_URI) # e.g., https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket TOKEN os.getenv(R2_TOKEN) # API token catalog RestCatalog( namer2_catalog, warehouseWAREHOUSE, uriCATALOG_URI, tokenTOKEN, ) # Test connection print(catalog.list_namespaces())其中catalog.list_namespaces()是验证连接与权限是否正确的标准探针——在 gotchas.md 的调试清单中它被列为排查认证问题的第三步检查项。Spark / Trino / DuckDBR2 Data Catalog 暴露的是标准 Iceberg REST Catalog API因此 Spark、Trino、DuckDB 等引擎同样可以接入。具体集成示例见 patterns.md其中 Pattern 8 给出了 PyIceberg 与 DuckDB 组合分析的示例将扫描结果注册为 DuckDB 视图后执行 SQL 聚合。连接字符串速查为便于快速参考连接所需的三个核心值汇总如下Catalog URI: https://account-id.r2.cloudflarestorage.com/iceberg/bucket Warehouse: bucket-name Token: r2-api-token参数来源对照表值来源account-idDashboard URL 或wrangler whoamibucketR2 存储桶名称Catalog URIwrangler r2 bucket catalog enable命令的输出TokenR2 API Token 创建页面关于 URI 的格式细节gotchas.md 补充了三点易错提示URI 必须是 HTTPS、必须包含/iceberg/路径段、存储桶名区分大小写同时 Warehouse 必须与存储桶名完全一致否则将出现无法创建或加载表的问题。安全最佳实践为保障凭据安全官方建议遵循以下六项实践安全存储 Token—— 使用环境变量或密钥管理器严禁硬编码最小权限原则—— 查询引擎用只读 Token仅在必要时授予写权限定期轮换 Token—— 创建新 Token → 测试 → 再吊销旧 Token每个应用单独一个 Token—— 便于泄露时精准追踪与吊销监控 Token 使用情况—— 通过 R2 Analytics 观察异常访问模式按存储桶隔离 Token—— 为每个存储桶单独创建 Token而非账户级通配。环境变量模式推荐将凭据统一放入环境变量.env文件切勿提交到版本库# .env (never commit) R2_CATALOG_URIhttps://account-id.r2.cloudflarestorage.com/iceberg/bucket R2_WAREHOUSEbucket-name R2_TOKENapi-token对应的 PyIceberg 读取方式import os from pyiceberg.catalog.rest import RestCatalog catalog RestCatalog( namer2, urios.getenv(R2_CATALOG_URI), warehouseos.getenv(R2_WAREHOUSE), tokenos.getenv(R2_TOKEN), )故障排查速查表配置过程中最常见的三类错误及其解决方案如下问题解决方案404 catalog not found运行wrangler r2 bucket catalog enable bucket启用 Catalog401 unauthorized检查 Token 是否同时具备 Catalog Storage 权限403 访问数据文件被拒Token 需要同时包含两组权限更详细的排障内容可查阅 gotchas.md其中包括Schema 演进报422 Validation只能新增可空列与做兼容类型放宽如 int→long、float→double、空扫描结果先无过滤测试table.scan().to_pandas()、PyArrow 类型不匹配需转为 Iceberg 默认的 int64等常见坑位以及一份按顺序执行的调试检查清单。进一步阅读patterns.mdPyIceberg 实战模式日志分析流水线、time-travel、schema 演进、分区表、表维护、并发写重试、DuckDB 集成等api.mdIceberg REST Catalog 端点与 PyIceberg 客户端 API 参考含表维护、元数据检查gotchas.md详细的故障排查与限制说明r2-data-catalog/README.md产品概念、架构图、适用场景决策树与资源限制【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考