Metadata-Version: 2.4
Name: huace-aigc-oss-proxy-client
Version: 0.1.9
Summary: 华策 AIGC OSS Proxy Client - 统一 RustFS / 阿里云 OSS / 七牛云上传，支持内网/公网默认上传网络
Author-email: Huace <support@huace.com>
License: MIT
Project-URL: Homepage, https://github.com/huace/huace-aigc-oss-proxy-client
Project-URL: Repository, https://github.com/huace/huace-aigc-oss-proxy-client
Keywords: aigc,oss,huace,sdk,rustfs,aliyun,s3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: aliyun
Requires-Dist: oss2>=2.18.0; extra == "aliyun"
Provides-Extra: rustfs
Requires-Dist: boto3>=1.34.0; extra == "rustfs"
Provides-Extra: qiniu
Requires-Dist: qiniu>=7.12.0; extra == "qiniu"
Requires-Dist: requests>=2.20.0; extra == "qiniu"
Provides-Extra: all
Requires-Dist: oss2>=2.18.0; extra == "all"
Requires-Dist: boto3>=1.34.0; extra == "all"
Requires-Dist: qiniu>=7.12.0; extra == "all"
Requires-Dist: requests>=2.20.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-env>=1.0.0; extra == "dev"
Requires-Dist: moto[s3]>=5.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# AIGC OSS Proxy Python SDK

[![Python Version](https://img.shields.io/pypi/pyversions/huace-aigc-oss-proxy-client.svg)](https://pypi.org/project/huace-aigc-oss-proxy-client/)

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

**Python 版本**：`>= 3.10`

## 安装

```bash
# 全量（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.example) 为 `.env`，填入 AK/SK、Bucket 等。变量名统一前缀 `HUACE_AIGC_`。

```bash
cp env.example .env
```

### 2. 上传文件

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

**参数说明**

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

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

## 内网转公网

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

```python
from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

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

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

## 环境变量

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

### 上传网络

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

**`HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK` 取值**

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

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

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

**配置示例**

```bash
# 内网 Worker：upload 可省略 route
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=local

# 公网（阿里云）
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=public
HUACE_AIGC_OSS_ALIYUN_ENABLED=true
HUACE_AIGC_OSS_QINIU_ENABLED=false

# 公网（七牛）
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=public
HUACE_AIGC_OSS_ALIYUN_ENABLED=false
HUACE_AIGC_OSS_QINIU_ENABLED=true
```

### RustFS（内网）

| 变量 | 字段含义 | 是否必填 | 默认值 |
|------|----------|----------|--------|
| `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`：

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

## 示例项目

更多命令行示例见 [example/](./example/) 目录：

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