Back to Details

r2-upload

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

R2 Upload

R2 上传

Upload files to R2/S3-compatible storage and return a URL.
将文件上传至R2/S3兼容的存储服务并返回URL。

Use when

适用场景

  • Upload images, documents, or other assets to object storage
  • Generate public URLs for web/CDN use
  • Generate presigned URLs for temporary access
  • Provide upload helpers to other skills (like tech-news)
  • 将图片、文档或其他资源上传至对象存储
  • 生成用于网页/CDN的公开URL
  • 生成用于临时访问的预签名URL
  • 为其他技能（如tech-news）提供上传辅助工具

Prerequisites

前置条件

  • Python 3.8+ available as 
    python3
  • PyYAML (
    python3 -m pip install pyyaml
    )
  • Config at 
    ~/.r2-upload.yml
    (or set 
    R2_UPLOAD_CONFIG
    )
  • Decide the bucket, object key/path, and visibility (public vs presigned)
  • If you skip 
    --key
    /
    --key-prefix
    , the default is 
    YYYY/MM/DD/<filename>
  • 已安装Python 3.8+，且可通过
    python3
    调用
  • 已安装PyYAML（执行
    python3 -m pip install pyyaml
    安装）
  • 配置文件位于
    ~/.r2-upload.yml
    （或设置环境变量
    R2_UPLOAD_CONFIG
    指定路径）
  • 确定存储桶、对象键/路径，以及可见性（公开或预签名）
  • 如果省略
    --key
    /
    --key-prefix
    参数，默认路径为
    YYYY/MM/DD/<filename>

Recommended workflow

推荐工作流程

  1. Confirm bucket/key and whether the URL should be public or presigned (avoid overwrites unless asked).
  2. Verify config and bucket exist.
  3. Upload with the CLI (recommended) or Python helper.
  4. Return the URL and key; note whether it is public or temporary and the expiration.
  1. 确认存储桶/键以及URL应为公开还是预签名（除非明确要求，否则避免覆盖现有文件）。
  2. 验证配置文件和存储桶是否存在。
  3. 使用CLI（推荐方式）或Python辅助工具执行上传。
  4. 返回URL和键；同时注明该URL是公开还是临时的，以及过期时间（如果是预签名URL）。

Quick commands

快速命令示例

bash
python3 scripts/r2-upload.py ./photo.jpg --public
python3 scripts/r2-upload.py ./photo.jpg --key images/YYYY/MM/DD/cover.jpg --public
python3 scripts/r2-upload.py ./report.pdf --key reports/YYYY/MM/DD/report.pdf
python3 scripts/r2-upload.py ./image.png --key-prefix images/YYYY/MM/DD --public
python3 scripts/r2-upload.py ./file.zip --expires 600
bash
python3 scripts/r2-upload.py ./photo.jpg --public
python3 scripts/r2-upload.py ./photo.jpg --key images/YYYY/MM/DD/cover.jpg --public
python3 scripts/r2-upload.py ./report.pdf --key reports/YYYY/MM/DD/report.pdf
python3 scripts/r2-upload.py ./image.png --key-prefix images/YYYY/MM/DD --public
python3 scripts/r2-upload.py ./file.zip --expires 600

Key options

主要参数选项

  • --bucket <name>
    : override the default bucket in config
  • --key <path>
    : set the object key/path
  • --key-prefix <prefix>
    : prepend prefix to the local filename
  • --public
    : return a public URL instead of a presigned URL
  • --expires <seconds>
    : presigned URL expiration (1-604800)
  • --config <path>
    : use a custom config file
  • --timeout <seconds>
    : network timeout
  • --content-type <mime>
    : override content type
  • --cache-control <value>
    : set Cache-Control header
  • --content-disposition <value>
    : set Content-Disposition header
  • --bucket <name>
    ：覆盖配置文件中的默认存储桶
  • --key <path>
    ：设置对象键/路径
  • --key-prefix <prefix>
    ：在本地文件名前添加前缀
  • --public
    ：返回公开URL而非预签名URL
  • --expires <seconds>
    ：预签名URL的过期时间（取值范围1-604800秒）
  • --config <path>
    ：使用自定义配置文件
  • --timeout <seconds>
    ：网络超时时间
  • --content-type <mime>
    ：覆盖默认的内容类型
  • --cache-control <value>
    ：设置Cache-Control请求头
  • --content-disposition <value>
    ：设置Content-Disposition请求头

Behavior notes

行为说明

  • Default behavior returns a presigned URL (temporary access).
  • If no key is provided, the default key is 
    YYYY/MM/DD/<filename>
    .
  • --public
    returns a public URL. For private buckets, use presigned URLs instead.
  • Presigned URLs always use the storage endpoint (custom CDN domains are for public URLs).
  • 默认行为是返回预签名URL（临时访问权限）。
  • 如果未指定对象键，默认键为
    YYYY/MM/DD/<filename>
    。
  • --public
    参数会返回公开URL。对于私有存储桶，请使用预签名URL。
  • 预签名URL始终使用存储服务的端点（自定义CDN域名仅适用于公开URL）。

Programmatic usage

程序化调用示例

python
import sys
from pathlib import Path

r2_dir = Path("/path/to/r2-upload")  # update to your local path
sys.path.insert(0, str(r2_dir / "scripts"))

from upload import upload_file, batch_upload, fetch_and_upload

url = upload_file(
    local_path="./image.jpg",
    key="images/YYYY/MM/DD/image.jpg",
    make_public=True
)
python
import sys
from pathlib import Path

r2_dir = Path("/path/to/r2-upload")  # 更新为你的本地路径
sys.path.insert(0, str(r2_dir / "scripts"))

from upload import upload_file, batch_upload, fetch_and_upload

url = upload_file(
    local_path="./image.jpg",
    key="images/YYYY/MM/DD/image.jpg",
    make_public=True
)

Scripts

脚本说明

  • scripts/r2-upload.py
    : CLI upload tool
  • scripts/upload.py
    : Python helpers (
    upload_file
    , 
    batch_upload
    , 
    fetch_and_upload
    )
  • scripts/r2-upload.py
    ：CLI上传工具
  • scripts/upload.py
    ：Python辅助函数库（包含
    upload_file
    、
    batch_upload
    、
    fetch_and_upload
    函数）

References

参考文档

  • references/CONFIGURATION.md
    (provider config examples)
  • references/IMAGES.md
    (image workflow)
  • references/TROUBLESHOOTING.md
    (common errors)
  • references/CONFIGURATION.md
    （云服务商配置示例）
  • references/IMAGES.md
    （图片处理工作流程）
  • references/TROUBLESHOOTING.md
    （常见错误排查）