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)   # 公网访问地址

# 七牛公网后端上传时设置文件 7 天后删除
result = proxy.upload(
    "/tmp/output.wav",
    "output.wav",
    route="public",
    delete_after_days=7,
)

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

参数说明

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

七牛前端直传与生命周期

当公网后端启用七牛云时，可以在后端生成前端直传凭证，并在上传策略中设置 deleteAfterDays：

from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

token = proxy.create_qiniu_upload_token(
    "output.wav",
    expires=3600,
    delete_after_days=7,
)

print(token.token)  # 前端表单/SDK 上传凭证
print(token.key)    # 前端上传时使用的对象 key
print(token.url)    # 上传成功后的访问 URL（需配置 HUACE_AIGC_OSS_QINIU_DOMAIN）

也可以给已经存在于七牛空间中的文件设置或更新生存时间：

proxy.set_qiniu_delete_after_days("tmp/output.wav", 10)

set_qiniu_delete_after_days() 的 key 传七牛空间内完整对象 key，通常可以直接使用 upload() 或 create_qiniu_upload_token() 返回的 key。

内网转公网

将内网 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 取值

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

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

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

RustFS（内网）

阿里云 OSS（公网）

七牛云（公网，可选）

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

迁移阿里云 OSS → 华策 OSS 代理 SDK

SDK 发布地址：https://pypi.org/project/huace-aigc-oss-proxy-client/

执行迁移前必须先访问该页面阅读 SDK README，了解 OssProxy.from_env() 和 proxy.upload() 的接口细节。

目标

将项目从直接调用阿里云 OSS (oss2) 切换为华策 OSS 代理 SDK (huace-aigc-oss-proxy-client)，实现内网 RustFS + 公网阿里云双路由上传。

上传默认走内网 RustFS（HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE=local）， 公网阿里云作为备选和 URL 转换通道。

容器需解析内网 OSS 域名：oss.aigc-transdubbing.huacemedia.com → 192.168.1.18。

改动范围和目标

1. requirements.txt

• 目标：删除所有 oss2 依赖，替换为 huace-aigc-oss-proxy-client[all]>=0.1.11
• 涉及文件：项目中所有 requirements*.txt

2. 环境变量文件

• 目标：删除旧的阿里云 OSS 凭据变量，替换为 HUACE_AIGC_* 前缀的新变量
• 涉及文件：.env、.env.prod、.env.test、.env.local（含 docker/ 目录下的）

需要删除的旧变量：

• OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET
• OSS_ENDPOINT、OSS_BUCKET_NAME
• OSS_REGION、OSS_URL_EXPIRE、OSS_SIGN_URL、OSS_CUSTOM_DOMAIN
• OSS_KEY_PREFIX、OSS_NAME_PREFIX、OSS_PREFIX

需要新增的新变量：

每个项目使用独立的前缀，格式 tmp/<项目名>，如 tmp/voiceprint、tmp/tts-indextts。

需要保留的变量（不是 SDK 凭据，是业务逻辑变量，不要删除）：

• OSS_OUTPUT_PREFIX、OSS_DELETE_LOCAL_AFTER_UPLOAD、OSS_UPLOAD_RETRIES
• 仅用于构造文件路径/healthcheck key 的 OSS_NAME_PREFIX

3. Python OSS 服务代码

• 目标：所有直接使用 oss2 的 Python 文件，内部实现替换为 OssProxy.from_env()
• 约束：保持原有函数名、类名、参数签名不变（调用方无需修改）
• 涉及模式：
  • 模块级函数（惰性初始化全局实例）
  • 类封装（构造时初始化，方法中调用）
  • 带 task_id 的上传（文件路径或 bytes 输入，返回 {"url": ..., "oss_key": ...}）

新 SDK 与旧 SDK 的关键差异：

• 不需要 oss2.Auth / oss2.Bucket，用 OssProxy.from_env() 从环境变量读取
• Key 由 SHA256 自动生成，无法手动指定；object_key 参数降级为 download_name
• URL 由 result.url 直接返回，不需要手动拼接
• 不支持签名 URL（代理统一管理），sign_url 参数保留但忽略
• 不需要 HAS_OSS2 标志位（新 SDK 始终可用）
• download_file 改为 HTTP 下载（新 SDK 不暴露 bucket.get_object_to_file）
• generate_url / generate_signed_url / public_url 等不再需要，可标记为废弃

4. config.py

• 目标：删除 OSS_ACCESS_KEY_*、OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_REGION、OSS_URL_EXPIRE、OSS_SIGN_URL、OSS_CUSTOM_DOMAIN 的 os.environ.get 读取
• 目标：删除未被调用的辅助函数（如 oss_endpoint_host()）
• 保留：业务逻辑变量（OSS_OUTPUT_PREFIX 等）

5. 调用方代码

• 目标：清理已删除 config 变量的 import；清理 app_celery.py 中对 OSS_ENDPOINT/OSS_BUCKET_NAME 的读取
• 目标：如有日志消息引用旧变量名，更新为 HUACE_AIGC_*
• 目标：返回值中 bucket/endpoint 字段无法再提供，设为空字符串

6. Docker Compose

• 目标：所有 docker-compose*.yml 文件的每个 service 添加 extra_hosts
• 内容：- "oss.aigc-transdubbing.huacemedia.com:192.168.1.18"
• 插入位置：restart: 行之后，与 restart: 同级缩进
• 缩进要求：必须根据每个文件现有的 service key 缩进风格来设置，不能硬编码（2 空格/4 空格/8 空格项目均存在）
• network_mode: host 的 service 也照加（保持一致性）
• 已存在该域名的文件跳过

验证标准

全部改动完成后，以下 grep 应无输出（或仅剩项目特有变量）：

# import oss2 全部清除
grep -rn "import oss2\|from oss2" --include="*.py" . | grep -v .venv | grep -v __pycache__

# .env 旧凭据全部替换
grep -rn "OSS_ACCESS_KEY_ID\|OSS_ACCESS_KEY_SECRET\|OSS_ENDPOINT\|OSS_BUCKET_NAME=" --include=".env*" . | grep -v .venv

# requirements 无 oss2
grep -rn "oss2" --include="requirements*.txt" . | grep -v .venv

# config.py 旧 OSS 变量全部删除
grep -rn "OSS_ACCESS_KEY_ID\|OSS_ENDPOINT\|OSS_BUCKET_NAME\|OSS_REGION\|OSS_URL_EXPIRE\|OSS_SIGN_URL\|OSS_CUSTOM_DOMAIN" --include="config.py" . | grep -v .venv

# docker-compose 每个 service 都有 extra_hosts
grep -A1 "extra_hosts:" **/docker-compose*.yml | grep "oss.aigc-transdubbing"

常见遗漏

1. docker/ 子目录下的 .env.prod / .env.test 文件
2. app_celery.py 等非 OSS 服务文件中的环境变量读取
3. 多 service 的 docker-compose 文件漏加某些 service
4. 不同缩进风格的 docker-compose 硬编码导致结构损坏
5. 项目特有业务变量被误删（OSS_OUTPUT_PREFIX 等）
6. 调用方残留已删除变量的 import