核心用法
r2-upload 是一个面向开发者和自动化工作流的文件上传工具，采用MCP（Model Context Protocol）协议，允许AI助手直接调用。核心功能包括：
1. 多平台存储支持：原生兼容Cloudflare R2、AWS S3、MinIO等任意S3 API兼容服务
2. 安全链接生成：自动创建预签名URL（presigned URL），默认5分钟有效期，支持自定义过期时间（秒/h/d单位）
3. 灵活配置：通过YAML配置文件管理多桶，支持环境变量覆盖和默认桶设置
4. 智能路径处理：可选自定义上传路径（--key），自动添加UUID前缀防冲突，自动识别Content-Type
配置流程
用户需创建 ~/.r2-upload.yml，包含endpoint、access_key_id、secret_access_key、bucket_name等字段。R2用户需特别注意region设为auto，并从Cloudflare Dashboard生成限定桶权限的API Token。
工具链
r2_upload：上传并返回签名URLr2_list：查看近期上传记录r2_delete：删除指定文件
显著优点
- 安全性设计：预签名URL避免长期暴露存储凭证，短时效降低泄露风险
- 多租户友好：单配置文件支持多桶切换，适合团队/个人项目隔离
- 零运维成本：R2提供 generous free tier（10GB/月），小团队友好
- 协议标准化：MCP协议确保与Claude、Cursor等AI IDE无缝集成
潜在局限
1. 凭证管理风险：明文存储access_key于本地YAML文件，需配合文件权限控制（建议600）
2. 无服务端加密选项：配置中未体现SSE-S3/SSE-KMS等加密参数
3. 过期时间粒度：仅支持到秒级，无更细粒度控制
4. 无自动刷新机制：预签名URL过期后需重新上传或手动续签
5. 依赖网络可达性：无本地缓存或断点续传能力
适合人群
- 需要AI辅助生成临时分享链接的内容创作者
- 构建MCP生态的开发者，需文件上传能力的Agent
- 使用R2/S3作为对象存储的中小团队
- 避免长期暴露CDN域名的安全敏感型用户
常规风险
| 风险类型 | 描述 | 缓解建议 |
|---------|------|---------|
| 凭证泄露 | YAML文件权限不当或被提交至Git | 使用`chmod 600`，添加至`.gitignore`，或改用环境变量注入 |
| URL滥用 | 预签名URL在有效期内被截获传播 | 缩短有效期，配合WAF规则限制referer |
| 配置错误 | endpoint格式错误导致上传失败 | 严格遵循`https://<account_id>.r2.cloudflarestorage.com`格式 |
| 成本失控 | 大文件/高频上传超出免费额度 | 设置R2使用告警，启用请求计费监控 |
| 数据残留 | 删除操作仅移除引用，存储桶版本控制可能保留历史 | 显式配置生命周期策略或禁用版本控制 |