huace-aigc-oss-proxy-client 0.1.17

华策 AIGC OSS Proxy Client - 统一 RustFS / 阿里云 OSS / 七牛云上传，支持内网/公网默认上传网络

AIGC OSS Proxy Python SDK

华策 AIGC 插件对象存储上传 SDK，支持内网 RustFS 与公网（阿里云 OSS / 七牛云）。

Python 版本：>= 3.10

安装

# 全量（RustFS + 阿里云 + 七牛）
pip install huace-aigc-oss-proxy-client[all]

# 按需安装
pip install huace-aigc-oss-proxy-client[aliyun]   # 仅阿里云
pip install huace-aigc-oss-proxy-client[rustfs]   # 仅 RustFS
pip install huace-aigc-oss-proxy-client[qiniu]    # 仅七牛

快速开始

1. 配置环境变量

复制 env.example 为 .env，填入 AK/SK、Bucket 等。变量名统一前缀 HUACE_AIGC_。

cp env.example .env

2. 上传文件

from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

# 上传到内网
result = proxy.upload("/tmp/output.wav", "output.wav", route="local")
print(result.url)   # 内网访问地址
print(result.key)   # 对象 key

# 上传到公网
result = proxy.upload("/tmp/output.wav", "output.wav", route="public")
print(result.url)   # 公网访问地址

# 不指定 route，走环境变量 HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE
result = proxy.upload("/tmp/output.wav", "output.wav")
print(result.url)

参数说明

参数	说明
第 1 个参数	本地文件路径
download_name	下载时显示的文件名（必填）
route	local（内网）或 public（公网）；可省略，见下方环境变量

省略 route 时，使用环境变量 HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE 的值。

内网转公网

将内网 RustFS 链接转为阿里云公网链接；若传入的已是公网链接，则原样返回。

from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

public_url = proxy.local_to_public_url(
    "http://oss.aigc-transdubbing.huacemedia.com/huace-shortmovie/tmp/abc.mp4"
)
print(public_url)

前提：HUACE_AIGC_OSS_ALIYUN_ENABLED=true，且阿里云凭证已配置。

环境变量

OssProxy.from_env() / OssClient.from_env() 从进程环境读取配置。变量名统一前缀 HUACE_AIGC_。完整模板见 env.example。

上传网络

变量	字段含义	是否必填	默认值
HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE	upload() 未传 route 时的默认上传网络；代码里传了 route= 则以代码为准	与代码 route 至少填一处	无
HUACE_AIGC_OSS_ALIYUN_ENABLED	是否启用阿里云 OSS 作为公网后端	否	true
HUACE_AIGC_OSS_QINIU_ENABLED	是否启用七牛云作为公网后端	否	false

HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE 取值

• local — 上传到内网 RustFS
• public — 上传到公网；具体厂商由上方 ALIYUN_ENABLED / QINIU_ENABLED 决定，二者均启用时优先阿里云

公网后端选择规则（route=public 时生效，无需单独配置 provider 变量）

• 仅 ALIYUN_ENABLED=true → 阿里云 OSS
• 仅 QINIU_ENABLED=true → 七牛云
• 二者均为 true → 优先阿里云
• 二者均为 false → 公网上传报错

RustFS（内网）

变量	字段含义	是否必填	默认值
HUACE_AIGC_OSS_RUSTFS_ENDPOINT	RustFS 服务端点（含协议，不含端口则走默认 80）	否	http://oss.aigc-transdubbing.huacemedia.com
HUACE_AIGC_OSS_RUSTFS_ACCESS_KEY	RustFS 访问 Access Key	是	无
HUACE_AIGC_OSS_RUSTFS_SECRET_KEY	RustFS 访问 Secret Key	是	无
HUACE_AIGC_OSS_RUSTFS_BUCKET	RustFS 桶名	是	无
HUACE_AIGC_OSS_RUSTFS_KEY_PREFIX	上传对象 key 前缀，最终 key 为 {prefix}/{sha256}{ext}	否	tmp

阿里云 OSS（公网）

变量	字段含义	是否必填	默认值
HUACE_AIGC_OSS_ALIYUN_ENABLED	是否启用阿里云后端（见上方公网选择规则）	否	true
HUACE_AIGC_OSS_ALIYUN_ACCESS_KEY_ID	阿里云 AccessKey ID	启用时必填	无
HUACE_AIGC_OSS_ALIYUN_ACCESS_KEY_SECRET	阿里云 AccessKey Secret	启用时必填	无
HUACE_AIGC_OSS_ALIYUN_BUCKET	阿里云 Bucket 名称	启用时必填	无
HUACE_AIGC_OSS_ALIYUN_KEY_PREFIX	上传对象 key 前缀	否	tmp

七牛云（公网，可选）

变量	字段含义	是否必填	默认值
HUACE_AIGC_OSS_QINIU_ENABLED	是否启用七牛后端（见上方公网选择规则）	否	false
HUACE_AIGC_OSS_QINIU_ACCESS_KEY	七牛 Access Key	启用时必填	无
HUACE_AIGC_OSS_QINIU_SECRET_KEY	七牛 Secret Key	启用时必填	无
HUACE_AIGC_OSS_QINIU_BUCKET	七牛存储空间名	启用时必填	无
HUACE_AIGC_OSS_QINIU_DOMAIN	七牛绑定的访问域名（用于生成公网 URL）	启用时必填	无
HUACE_AIGC_OSS_QINIU_KEY_PREFIX	上传对象 key 前缀	否	tmp

Docker 部署

容器内需能解析内网 OSS 域名，添加 extra_hosts：

extra_hosts:
  - "oss.aigc-transdubbing.huacemedia.com:192.168.1.18"

示例项目

更多命令行示例见 example/ 目录：

cd example
cp .env.example .env   # 填入凭证
pip install -r requirements.txt
python upload_file.py "assert/2.mp4" "2.mp4" --route public

AI Agent 迁移指南

AI Agent 执行 OSS 迁移时，加载 skill migrate-to-huace-oss-proxy 获取完整步骤、环境变量清单、验证标准和常见遗漏。

该 skill 涵盖：requirements 替换、环境变量迁移、Python OSS 代码改造、config.py 清理、Docker Compose extra_hosts 添加。