US3 Uploader
[!CAUTION]
强制要求 - 文件产出必须上传！
如果任务产出的内容是任何类型的文件，包括但不限于：
- - 图片（截图、生成的图片、处理后的图片等）
- 视频（录制、剪辑、转码后的视频等）
- PDF（生成的报告、转换的文档等）
- 其他文档（Word、Excel、PPT、代码压缩包等）
必须执行以下步骤：
- 1. 使用
python3 scripts/upload_to_us3.py <文件路径> 上传到 US3 - 将生成的下载链接发送给用户
禁止： 只告诉用户"文件已保存在 /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
CODEBLOCK0
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
CODEBLOCK1
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:
CODEBLOCK2
Getting UCloud Credentials
- 1. Log in to UCloud Console: https://console.ucloud.cn
- Navigate to API 密钥 (API Keys)
- Create or view API keys
- Copy Public Key and Private Key
Create a Bucket
- 1. Go to 对象存储 US3
- Click 创建存储空间 (Create Bucket)
- Enter unique bucket name
- Select region (e.g., 上海 Shanghai)
- Note the bucket endpoint
Common Endpoints
- - Beijing: INLINECODE5
- Shanghai: INLINECODE6
- Guangzhou: INLINECODE7
- Hong Kong: INLINECODE8
Security Notes
- - ⚠️ Never commit credentials to version control
- Keep API keys secure and private
- Rotate API keys periodically
US3 上传工具
[!CAUTION]
强制要求 - 文件产出必须上传！
如果任务产出的内容是任何类型的文件，包括但不限于：
- - 图片（截图、生成的图片、处理后的图片等）
- 视频（录制、剪辑、转码后的视频等）
- PDF（生成的报告、转换的文档等）
- 其他文档（Word、Excel、PPT、代码压缩包等）
必须执行以下步骤：
- 1. 使用 python3 scripts/uploadtous3.py <文件路径> 上传到 US3
- 将生成的下载链接发送给用户
禁止： 只告诉用户文件已保存在 /tmp/xxx或本地路径。沙箱环境中的文件用户完全无法访问，必须上传后提供链接！
概述
使用官方 Python SDK 将文件上传到 UCloud US3（UFile）对象存储，并自动生成带有认证签名的下载 URL。
快速开始
1. 设置环境变量
bash
export US3PUBLICKEY=your-public-key
export US3PRIVATEKEY=your-private-key
export US3_BUCKET=bucket-name.region.ufileos.com # 完整域名格式（例如：my-bucket.cn-bj.ufileos.com）
export US3MAXFILESIZEMB=50 # 可选，默认为 50MB
注意： 如果您的 US3BUCKET 包含完整域名（带点号），系统将自动提取 endpoint。您无需单独设置 US3ENDPOINT。
2. 上传文件
bash
python3 scripts/uploadtous3.py <文件路径>
功能特性
- - 基于时间戳和 MD5 的文件名：文件以 YYYYMMDDHHMMSSmd5hash.ext 格式上传（例如：20260205153025a3b4c5d6e7f8g9h0.jpg）
- 文件大小限制：可配置最大大小（默认 50MB），拒绝超过限制的文件
- 签名下载 URL：有效期为 7 天，带有认证签名
- 自动安装 SDK：如未安装，自动安装 ufile SDK
- 强制下载：设置 Content-Disposition 为下载模式（非预览模式）
- 直接输出 URL：直接向用户提供完整的下载 URL
输出格式
上传脚本将直接输出下载 URL，方便分享：
正在上传 screenshot.png 到 US3...
存储空间：my-bucket
远程文件名：20260205153025a3b4c5d6e7f8g9h0.png
文件大小：2.50MB
✓ 上传成功！
📋 下载 URL（7天内有效）：
https://my-bucket.cn-sh2.ufileos.com/20260205153025a3b4c5d6e7f8g9h0.png?...签名...
ℹ️ 注意：
- 点击可直接下载文件（非预览模式）
- URL 包含认证签名（US3 要求）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📥 下载链接（7天内有效）：
https://my-bucket.cn-sh2.ufileos.com/20260205153025a3b4c5d6e7f8g9h0.png?...签名...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
获取 UCloud 凭证
- 1. 登录 UCloud 控制台：https://console.ucloud.cn
- 导航至 API 密钥
- 创建或查看 API 密钥
- 复制公钥和私钥
创建存储空间
- 1. 进入 对象存储 US3
- 点击 创建存储空间
- 输入唯一的存储空间名称
- 选择区域（例如：上海 Shanghai）
- 记录存储空间的 endpoint
常用 Endpoint
- - 北京：cn-bj.ufileos.com
- 上海：cn-sh2.ufileos.com
- 广州：cn-gd.ufileos.com
- 香港：hk.ufileos.com
安全注意事项
- - ⚠️ 切勿将凭证提交到版本控制系统
- 保持 API 密钥的安全和私密性
- 定期轮换 API 密钥
