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)

参数说明

省略 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://<rustfs-endpoint>/<bucket>/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（公网）

七牛云（公网，可选）

HUACE_AIGC_OSS_QINIU_KEY_PREFIX 的前缀约定：

• uplodas/{你的项目名字}：永久地址
• tmp/{你的项目名字}：临时地址

前端直传凭证

后端可通过 SDK 生成浏览器直传所需的临时凭证。七牛云返回 upload_token， 前端用七牛 JS SDK 直传；key_prefix 由业务后端返回给前端拼接对象 key。

from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()
cred = proxy.create_direct_upload_credential(provider="qiniu", expires=3600)

print(cred.provider)      # qiniu
print(cred.upload_token)  # 七牛 upload token
print(cred.bucket)
print(cred.domain)
print(cred.key_prefix)
print(cred.expired_at)

Skill：前端使用后端临时凭证接入七牛云直传

当项目需要“前端直传 OSS / 七牛云”、“前端通过后端接口获取 STS 临时凭证”、 “使用项目配置的七牛自定义域名生成访问地址”时，按本 skill 完成前后端接入。

代码位置

• 前端代码：<project-root>/frontend
• 后端代码：<project-root>/backend
• 生产配置：<project-root>/backend/docker/.env.prod

后端配置

在后端生产环境中启用七牛云 Kodo，并让公网默认上传路由走七牛：

HUACE_AIGC_OSS_DEFAULT_UPLOAD_ROUTE=public
HUACE_AIGC_OSS_ALIYUN_ENABLED=false
HUACE_AIGC_OSS_QINIU_ENABLED=true
HUACE_AIGC_OSS_QINIU_ACCESS_KEY=<Qiniu Access Key>
HUACE_AIGC_OSS_QINIU_SECRET_KEY=<Qiniu Secret Key>
HUACE_AIGC_OSS_QINIU_BUCKET=<bucket>
HUACE_AIGC_OSS_QINIU_DOMAIN=https://<your-qiniu-custom-domain>
HUACE_AIGC_OSS_QINIU_KEY_PREFIX=tmp/<project-name>

七牛对象前缀按保存时长区分：

# 永久地址
HUACE_AIGC_OSS_QINIU_KEY_PREFIX=uplodas/{你的项目名字}

# 临时地址
HUACE_AIGC_OSS_QINIU_KEY_PREFIX=tmp/{你的项目名字}

不要把 ACCESS_KEY / SECRET_KEY 暴露给前端。前端只通过后端接口拿 uploadToken、bucket、domain、keyPrefix 等临时上传信息。

后端接口

提供统一凭证接口：

GET /api/v1/oss/sts-token

后端实现时调用 SDK 生成七牛直传凭证：

from huace_aigc_oss import OssClient

proxy_client = OssClient.from_env()
credential = proxy_client.create_direct_upload_credential(
    provider="qiniu",
    expires=3600,
)

key_prefix = (credential.key_prefix or "").strip("/")
if key_prefix:
    key_prefix = f"{key_prefix}/"

data = {
    "provider": "qiniu",
    "uploadToken": credential.upload_token,
    "bucket": credential.bucket,
    "domain": credential.domain,
    "keyPrefix": key_prefix,
    "expiredAt": credential.expired_at,
    "expiresIn": credential.expires_in,
}

接口返回给前端的 domain 必须来自 HUACE_AIGC_OSS_QINIU_DOMAIN，用于生成 https://<your-qiniu-custom-domain>/{object_key} 形式的文件访问地址。

前端接入

前端安装并使用七牛云浏览器上传包：

npm install qiniu-js

前端上传流程：

1. 调用 GET /api/v1/oss/sts-token 获取临时凭证。
2. 校验 provider === "qiniu" 且存在 uploadToken。
3. 使用后端返回的 keyPrefix 拼接对象 key，例如 tmp/<project-name>/files/{sha256}.{ext} 或 tmp/<project-name>/transcode_input/files/{sha256}.{ext}。
4. 使用 qiniu.upload(file, key, uploadToken, putExtra, config) 直传文件。
5. 上传成功后保存对象 key；需要公网地址时，用后端返回的 domain 拼接完整 URL。

前端类型建议保持为：

interface StsCredentials {
  provider: "qiniu";
  uploadToken: string;
  bucket: string;
  domain?: string;
  keyPrefix: string;
  expiredAt: string;
  expiresIn?: number;
}

前端拼接访问地址时以接口返回的 domain 为准，不再使用硬编码 OSS 域名：

function buildOssPublicUrl(key: string, creds: StsCredentials): string {
  const domain = creds.domain?.replace(/\/+$/g, "");
  if (!domain) throw new Error("七牛访问域名缺失，无法生成文件完整链接");
  return `${domain}/${key.replace(/^\/+/g, "")}`;
}

验证标准

• 前端代码中存在 qiniu-js 上传调用，且上传 token 来自 /api/v1/oss/sts-token。
• 前端没有出现七牛 ACCESS_KEY / SECRET_KEY。
• 后端接口返回 provider=qiniu、uploadToken、bucket、domain、keyPrefix、expiredAt。
• 生成的访问 URL 使用 HUACE_AIGC_OSS_QINIU_DOMAIN 配置的自定义域名。
• 对象 key 统一落在 HUACE_AIGC_OSS_QINIU_KEY_PREFIX 配置的项目前缀下。

Docker 部署

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

extra_hosts:
  - "<rustfs-host>:<rustfs-ip>"

示例项目

更多命令行示例见 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 域名：<rustfs-host> → <rustfs-ip>。

改动范围和目标

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/<project-name-a>、tmp/<project-name-b>。

需要保留的变量（不是 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
• 内容：- "<rustfs-host>:<rustfs-ip>"
• 插入位置：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 "<rustfs-host>"

常见遗漏

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