US3 Uploader

> [!CAUTION]

> 强制要求 - 文件产出必须上传！

>

> 如果任务产出的内容是任何类型的文件，包括但不限于：

> - 图片（截图、生成的图片、处理后的图片等）

> - 视频（录制、剪辑、转码后的视频等）

> - PDF（生成的报告、转换的文档等）

> - 其他文档（Word、Excel、PPT、代码压缩包等）

>

> 必须执行以下步骤：

> 1. 使用 python3 scripts/upload_to_us3.py <文件路径> 上传到 US3

> 2. 将生成的下载链接发送给用户

>

> 禁止： 只告诉用户"文件已保存在 /tmp/xxx"或本地路径。沙箱环境中的文件用户完全无法访问，必须上传后提供链接！

Overview

Upload files to UCloud US3 (UFile) object storage using the official Python SDK and automatically generate download URLs with authentication signatures.

Quick Start

1. Set Environment Variables

export US3_PUBLIC_KEY='your-public-key'
export US3_PRIVATE_KEY='your-private-key'
export US3_BUCKET='bucket-name.region.ufileos.com'  # full domain format (e.g., my-bucket.cn-bj.ufileos.com)
export US3_MAX_FILE_SIZE_MB='50'  # optional, defaults to 50MB

Note: If your US3_BUCKET contains the full domain (with dots), the endpoint will be automatically extracted. You don't need to set US3_ENDPOINT separately.

2. Upload a File

python3 scripts/upload_to_us3.py <file_path>

Features

• Timestamp and MD5-based filename: Files are uploaded with format YYYYMMDD_HHMMSS_md5hash.ext (e.g., 20260205_153025_a3b4c5d6e7f8g9h0.jpg)
• File size limit: Configurable max size (default 50MB), rejects larger files
• Signed download URLs: Valid for 7 days with authentication
• Auto-install SDK: Installs ufile SDK if not present
• Force download: Sets Content-Disposition to download (not preview)
• Direct URL output: Provides complete download URL directly to users

Output Format

The upload script will output the download URL directly for easy sharing:

Uploading screenshot.png to US3...
  Bucket: my-bucket
  Remote name: 20260205_153025_a3b4c5d6e7f8g9h0.png
  File size: 2.50MB

✓ Upload successful!

📋 Download URL (valid for 7 days):
https://my-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.png?...signature...

ℹ️  Note:
   - Click to download file directly (not preview)
   - URL contains authentication signature (required by US3)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📥 下载链接（7天内有效）：
https://my-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.png?...signature...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Getting UCloud Credentials

1. Log in to UCloud Console: https://console.ucloud.cn
2. Navigate to API 密钥 (API Keys)
3. Create or view API keys
4. Copy Public Key and Private Key

Create a Bucket

1. Go to 对象存储 US3
2. Click 创建存储空间 (Create Bucket)
3. Enter unique bucket name
4. Select region (e.g., 上海 Shanghai)
5. Note the bucket endpoint

Common Endpoints

• Beijing: cn-bj.ufileos.com
• Shanghai: cn-sh2.ufileos.com
• Guangzhou: cn-gd.ufileos.com
• Hong Kong: hk.ufileos.com

Security Notes

• ⚠️ Never commit credentials to version control
• Keep API keys secure and private
• Rotate API keys periodically