huace-aigc-oss-proxy-client 0.1.0__tar.gz

huace_aigc_oss_proxy_client-0.1.0/DESIGN.md

@@ -0,0 +1,498 @@
+# huace-aigc-oss-proxy-client — PyPI SDK 设计文档
+
+> **包名（PyPI）**：`huace-aigc-oss-proxy-client`  
+> **导入名**：`huace_aigc_oss`（建议，避免连字符）  
+> **定位**：面向 AIGC 插件与 Celery Worker 的统一对象存储 SDK，通过环境变量配置多后端、优先级与降级策略，对业务完全屏蔽 RustFS / 阿里云 OSS / 七牛云差异。
+
+---
+
+## 1. 背景与目标
+
+当前各插件（`plugin-tts-indextts`、`plugin-voiceprint-recognition-v2` 等）各自实现 `oss_util.py` / `oss_service.py`，仅对接阿里云 OSS，且下载无内网优先、上传无「内外网模式」区分。
+
+本 SDK 目标：
+
+| 目标 | 说明 |
+|------|------|
+| 统一入口 | 业务只依赖 `OssClient`，不感知底层实现 |
+| 多后端可插拔 | RustFS（自定义 S3 兼容内网）、阿里云 OSS、七牛云 Kodo |
+| 环境变量驱动 | 12-Factor，容器 / K8s / docker-compose 零代码改配置 |
+| 下载智能降级 | 按优先级尝试，失败自动下一跳；**进程内会话记忆**加速后续请求 |
+| 上传强可控 | 默认内网、可指定外网，**禁止**跨存储自动降级 |
+| 可发布 PyPI | 标准 `pyproject.toml`、语义化版本、可选 extras |
+
+---
+
+## 2. 核心规则（业务契约）
+
+### 2.1 下载（Download）
+
+```
+优先级链（可配置） → 例如：rustfs → aliyun → qiniu
+```
+
+1. 按 `OSS_DOWNLOAD_PRIORITY` 顺序依次尝试。
+2. 下列情况视为「当前后端失败」，触发下一跳：
+   - 连接超时 / 服务不可达
+   - HTTP/ SDK 层请求异常
+   - **对象不存在**（404 / NoSuchKey）
+3. 某一后端成功后，可选地将该 `object_key`（或 key 前缀）记入**进程内会话缓存**，同进程后续同 key 的 `download` / `exists` **跳过**已失败的后端，直接命中上次成功的后端（见 §5.3）。
+4. 全部后端失败 → 抛出统一异常 `OssDownloadError`，附带各后端最后一次错误摘要。
+
+### 2.2 上传（Upload）
+
+| 模式 | 行为 |
+|------|------|
+| `UploadMode.INTRANET`（默认） | 路由到「上传优先级」中第一个**已启用**的内网类后端（通常为 RustFS） |
+| `UploadMode.EXTRANET` | 路由到指定的外网后端（如 `aliyun`），**不经过** RustFS |
+| 失败 | 直接向上抛出，**不**尝试其他存储 |
+
+> 上传不做自动降级，保证对象落盘位置可预期、可审计。
+
+### 2.3 存在性检查（Exists）
+
+与 **下载** 共用同一套优先级与降级逻辑（先内网 RustFS，失败再外网等）。
+
+---
+
+## 3. 整体架构（四层）
+
+```mermaid
+flowchart TB
+    subgraph L1["1. 业务调用层"]
+        APP["插件 / Celery Task"]
+    end
+
+    subgraph L2["2. 调度核心层"]
+        CLIENT["OssClient"]
+        ROUTER["PriorityRouter"]
+        FALLBACK["DownloadFallbackController"]
+        STICKY["SessionStickyStore"]
+        CB["CircuitBreaker 可选"]
+    end
+
+    subgraph L3["3. 存储适配层"]
+        IFACE["StorageBackend Protocol"]
+        RUST["RustFsBackend"]
+        ALI["AliyunOssBackend"]
+        QIN["QiniuKodoBackend"]
+    end
+
+    subgraph L4["4. 配置层"]
+        CFG["OssConfig.from_env()"]
+        ENV["环境变量 / .env"]
+    end
+
+    APP --> CLIENT
+    CLIENT --> ROUTER
+    CLIENT --> FALLBACK
+    CLIENT --> STICKY
+    ROUTER --> IFACE
+    FALLBACK --> IFACE
+    RUST & ALI & QIN --> IFACE
+    CFG --> ENV
+    CFG --> CLIENT
+```
+
+| 层级 | 职责 | 关键类型 |
+|------|------|----------|
+| 业务调用层 | 只调 `download` / `upload` / `exists` | 各插件 `oss_service` 薄封装 |
+| 调度核心层 | 优先级排序、降级、会话粘性、日志与指标 | `OssClient`, `PriorityRouter` |
+| 存储适配层 | 统一接口，各云厂商独立实现 | `StorageBackend` |
+| 配置层 | 解析 env、默认值、校验 | `OssConfig` |
+
+---
+
+## 4. 统一存储接口（适配层）
+
+所有后端实现同一抽象，调度层**仅**依赖此接口：
+
+```python
+# huace_aigc_oss/backends/base.py
+
+from typing import Protocol, BinaryIO, Union
+from pathlib import Path
+
+class StorageBackend(Protocol):
+    name: str  # "rustfs" | "aliyun" | "qiniu"
+
+    def download(self, key: str, local_path: Union[str, Path]) -> None: ...
+    def upload(self, key: str, source: Union[str, Path, bytes, BinaryIO]) -> None: ...
+    def exists(self, key: str) -> bool: ...
+    def delete(self, key: str) -> None: ...  # 可选，v1.1
+
+    def health_check(self) -> bool: ...  # 启动时可选探测
+```
+
+### 4.1 RustFS（自定义 OSS / 内网）
+
+- 协议：**S3 兼容 API**（MinIO 客户端或 `boto3`）。
+- 典型场景：机房内网 `http://rustfs.internal:9000`。
+- 独立超时、重试，与公网 OSS 客户端实例隔离。
+
+### 4.2 阿里云 OSS
+
+- 依赖：`oss2`（与现有 `oss_util.py` 一致）。
+- 配置：`OSS_ALIYUN_*` 或兼容旧变量 `OSS_ACCESS_KEY_ID` 等（见 §7）。
+
+### 4.3 七牛云 Kodo
+
+- 依赖：`qiniu` SDK。
+- 配置：`OSS_QINIU_*`。
+- v1.0 可与 RustFS + 阿里云同版发布；未配置时自动从优先级链剔除。
+
+---
+
+## 5. 调度核心实现原理
+
+### 5.1 下载：优先调用 + 异常捕获兜底
+
+```text
+for backend in download_priority:
+    if session.should_skip(key, backend): continue
+    try:
+        backend.download(key, path)
+        session.remember_success(key, backend)
+        return
+    except (NotFound, Timeout, ConnectionError, BackendError) as e:
+        session.remember_failure(key, backend)
+        last_errors[backend] = e
+        continue
+raise OssDownloadError(key, last_errors)
+```
+
+- 每个 backend **独立** `connect_timeout` / `read_timeout` / `max_retries`。
+- 两次链路互不阻塞：RustFS 超时不会占用阿里云的超时预算（各自计时）。
+
+### 5.2 上传：参数路由、无兜底
+
+```python
+def upload(self, key: str, source: UploadSource, mode: UploadMode = UploadMode.INTRANET) -> UploadResult:
+    backend = self._router.resolve_upload(mode)  # 确定性单点
+    backend.upload(key, source)  # 失败即抛，不 fallback
+    return UploadResult(key=key, backend=backend.name, url=self._public_url(backend, key))
+```
+
+`UploadMode.EXTRANET` 时通过 `OSS_UPLOAD_EXTRANET_BACKEND=aliyun` 指定目标（默认 `aliyun`）。
+
+### 5.3 进程内会话记忆（Sticky Session）
+
+**需求**：本地 RustFS 不可达或文件不存在后，**本次进程生命周期内**同 object key 后续请求直接用阿里云，避免重复打挂掉的内网。
+
+| 数据结构 | 说明 |
+|----------|------|
+| `success_map: dict[str, BackendName]` | key → 上次成功的后端 |
+| `skip_map: dict[str, set[BackendName]]` | key → 已失败、本轮跳过的后端 |
+| `prefix_map: dict[str, BackendName]` | 可选：按 key 前缀粘性（如某 task 目录整体走外网） |
+
+**查找顺序**（`download` / `exists`）：
+
+1. 若 `key in success_map` → 仅用该 backend（失败则清除并走完整优先级链）。
+2. 否则按 `OSS_DOWNLOAD_PRIORITY` 遍历，跳过 `skip_map[key]` 中的 backend。
+3. 成功后写入 `success_map`；失败写入 `skip_map`。
+
+> 作用域：**单进程**（Celery worker 子进程、API 单 worker）。多进程不共享；需要跨进程时可后续接 Redis（v2，非 v1 范围）。
+
+### 5.4 故障隔离与熔断（可选）
+
+- 各 backend 独立连接池 / 客户端单例。
+- `OSS_CIRCUIT_BREAKER_ENABLED=true` 时：RustFS 连续失败 N 次 → 短期内**全局**跳过 RustFS（仅下载/exists），减少对不可用内网的等待。
+- 与 key 级 sticky 正交：熔断是后端级，sticky 是 key 级。
+
+---
+
+## 6. 对外 API（极简）
+
+```python
+from huace_aigc_oss import OssClient, UploadMode, OssConfig
+
+# 推荐：从环境变量构造（容器内零参数）
+client = OssClient.from_env()
+
+# 或显式配置（测试 / 本地）
+# client = OssClient(OssConfig(...))
+
+# 下载：内网优先，自动降级外网
+local_path = client.download("plugin-tts/task-1/out.wav", "/tmp/out.wav")
+
+# 上传：默认内网 RustFS
+client.upload("plugin-tts/task-1/out.wav", "/tmp/out.wav")
+
+# 上传：强制阿里云外网
+client.upload(
+    "plugin-tts/task-1/out.wav",
+    "/tmp/out.wav",
+    mode=UploadMode.EXTRANET,
+)
+
+# 存在性：与下载相同优先级
+if client.exists("plugin-tts/task-1/out.wav"):
+    ...
+```
+
+### 6.1 异常体系
+
+| 异常 | 场景 |
+|------|------|
+| `OssConfigError` | 环境变量缺失、优先级配置非法 |
+| `OssDownloadError` | 所有下载后端均失败 |
+| `OssUploadError` | 上传单后端失败 |
+| `OssNotFoundError` | 所有后端均报告不存在 |
+
+### 6.2 返回值（建议）
+
+```python
+@dataclass
+class UploadResult:
+    key: str
+    backend: str
+    url: str | None  # 若该后端支持生成公网 URL
+```
+
+---
+
+## 7. 环境变量规范
+
+### 7.1 全局
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OSS_DOWNLOAD_PRIORITY` | `rustfs,aliyun` | 逗号分隔，从左到右 |
+| `OSS_UPLOAD_INTRANET_BACKEND` | `rustfs` | 内网默认上传目标 |
+| `OSS_UPLOAD_EXTRANET_BACKEND` | `aliyun` | `UploadMode.EXTRANET` 目标 |
+| `OSS_KEY_PREFIX` | `""` | 全局 key 前缀，自动 strip/join `/` |
+| `OSS_FALLBACK_ENABLED` | `true` | `false` 时下载仅尝试第一后端 |
+| `OSS_STICKY_SESSION_ENABLED` | `true` | 进程内 key 级记忆 |
+| `OSS_CIRCUIT_BREAKER_ENABLED` | `false` | 内网熔断 |
+| `OSS_CIRCUIT_BREAKER_THRESHOLD` | `5` | 连续失败次数 |
+| `OSS_CIRCUIT_BREAKER_COOLDOWN_SEC` | `60` | 熔断恢复时间 |
+| `OSS_MAX_OBJECT_SIZE_MB` | `5120` | 上传大小上限 |
+
+### 7.2 RustFS（自定义内网 OSS）
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OSS_RUSTFS_ENABLED` | `false` | 是否参与优先级链 |
+| `OSS_RUSTFS_ENDPOINT` | — | 如 `http://10.0.0.5:9000` |
+| `OSS_RUSTFS_ACCESS_KEY` | — | |
+| `OSS_RUSTFS_SECRET_KEY` | — | |
+| `OSS_RUSTFS_BUCKET` | — | |
+| `OSS_RUSTFS_REGION` | `us-east-1` | S3 兼容 region |
+| `OSS_RUSTFS_USE_SSL` | `false` | |
+| `OSS_RUSTFS_CONNECT_TIMEOUT_SEC` | `3` | 内网宜短 |
+| `OSS_RUSTFS_READ_TIMEOUT_SEC` | `30` | |
+| `OSS_RUSTFS_MAX_RETRIES` | `2` | |
+
+### 7.3 阿里云 OSS
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OSS_ALIYUN_ENABLED` | `true` | |
+| `OSS_ALIYUN_ENDPOINT` | `https://oss-cn-hangzhou.aliyuncs.com` | |
+| `OSS_ALIYUN_ACCESS_KEY_ID` | — | **兼容** `OSS_ACCESS_KEY_ID` |
+| `OSS_ALIYUN_ACCESS_KEY_SECRET` | — | **兼容** `OSS_ACCESS_KEY_SECRET` |
+| `OSS_ALIYUN_BUCKET` | — | **兼容** `OSS_BUCKET_NAME` |
+| `OSS_ALIYUN_CONNECT_TIMEOUT_SEC` | `10` | |
+| `OSS_ALIYUN_READ_TIMEOUT_SEC` | `120` | |
+| `OSS_ALIYUN_MAX_RETRIES` | `3` | |
+
+### 7.4 七牛云
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OSS_QINIU_ENABLED` | `false` | |
+| `OSS_QINIU_ACCESS_KEY` | — | |
+| `OSS_QINIU_SECRET_KEY` | — | |
+| `OSS_QINIU_BUCKET` | — | |
+| `OSS_QINIU_DOMAIN` | — | 下载域名，可选 |
+| `OSS_QINIU_CONNECT_TIMEOUT_SEC` | `10` | |
+| `OSS_QINIU_MAX_RETRIES` | `3` | |
+
+### 7.5 配置示例：RustFS 优先，阿里云其次
+
+```bash
+# 启用双后端，下载 RustFS → 阿里云
+OSS_RUSTFS_ENABLED=true
+OSS_RUSTFS_ENDPOINT=http://rustfs.internal:9000
+OSS_RUSTFS_ACCESS_KEY=minioadmin
+OSS_RUSTFS_SECRET_KEY=minioadmin
+OSS_RUSTFS_BUCKET=aigc-intranet
+
+OSS_ALIYUN_ENABLED=true
+OSS_ALIYUN_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+OSS_ALIYUN_ACCESS_KEY_ID=***
+OSS_ALIYUN_ACCESS_KEY_SECRET=***
+OSS_ALIYUN_BUCKET=huace-shortmovie
+
+OSS_DOWNLOAD_PRIORITY=rustfs,aliyun
+OSS_UPLOAD_INTRANET_BACKEND=rustfs
+OSS_UPLOAD_EXTRANET_BACKEND=aliyun
+OSS_KEY_PREFIX=plugin-tts-indextts
+OSS_STICKY_SESSION_ENABLED=true
+OSS_FALLBACK_ENABLED=true
+```
+
+**运行时行为**：
+
+1. 首次 `download("foo/bar.wav")`：请求 RustFS → 超时或 404 → 自动阿里云 → 成功 → `success_map["foo/bar.wav"] = aliyun`。
+2. 同进程第二次 `download("foo/bar.wav")`：跳过 RustFS，直连阿里云。
+3. `upload(..., INTRANET)`：仅 RustFS；失败不转阿里云。
+4. `upload(..., EXTRANET)`：仅阿里云。
+
+---
+
+## 8. 项目结构（PyPI 包）
+
+```text
+huace-aigc-oss-proxy-client/
+├── pyproject.toml              # hatchling / setuptools, dynamic version
+├── README.md
+├── DESIGN.md                   # 本文档
+├── LICENSE
+├── src/
+│   └── huace_aigc_oss/
+│       ├── __init__.py         # 导出 OssClient, UploadMode
+│       ├── client.py           # OssClient 门面
+│       ├── config.py           # OssConfig.from_env()
+│       ├── router.py           # PriorityRouter
+│       ├── fallback.py         # DownloadFallbackController
+│       ├── session.py          # SessionStickyStore
+│       ├── circuit.py          # CircuitBreaker（可选）
+│       ├── exceptions.py
+│       ├── types.py            # UploadMode, UploadResult
+│       └── backends/
+│           ├── base.py
+│           ├── rustfs.py       # boto3 / minio
+│           ├── aliyun.py       # oss2
+│           └── qiniu.py
+└── tests/
+    ├── test_download_fallback.py
+    ├── test_upload_routing.py
+    ├── test_sticky_session.py
+    └── conftest.py             # moto / 本地 MinIO fixture
+```
+
+### 8.1 依赖分组（`pyproject.toml` extras）
+
+```toml
+[project.optional-dependencies]
+aliyun = ["oss2>=2.18.0"]
+rustfs = ["boto3>=1.34.0"]
+qiniu = ["qiniu>=7.12.0"]
+all = ["huace-aigc-oss-proxy-client[aliyun,rustfs,qiniu]"]
+dev = ["pytest", "moto", "pytest-env"]
+```
+
+默认 `pip install huace-aigc-oss-proxy-client[all]` 供插件使用；仅外网场景可 `pip install huace-aigc-oss-proxy-client[aliyun]`。
+
+### 8.2 版本与发布
+
+- 语义化版本：`0.1.0` 起，API 稳定后 `1.0.0`。
+- CI：`pytest` → `python -m build` → `twine upload`（PyPI token 在 CI secret）。
+- 包名与导入名分离：`pip install huace-aigc-oss-proxy-client`，`import huace_aigc_oss`。
+
+---
+
+## 9. 日志与可观测性
+
+| 事件 | 级别 | 字段 |
+|------|------|------|
+| 下载尝试 | DEBUG | `key`, `backend`, `attempt` |
+| 下载降级 | WARNING | `key`, `from_backend`, `to_backend`, `reason` |
+| 粘性命中 | DEBUG | `key`, `backend` |
+| 上传完成 | INFO | `key`, `backend`, `mode`, `bytes` |
+| 熔断打开 | WARNING | `backend`, `cooldown_sec` |
+
+建议结构化日志（`extra={}`），便于 ELK 统计「内网命中率 / 降级率」。
+
+---
+
+## 10. 与现有插件集成
+
+### 10.1 替换方式
+
+将各插件 `oss_service.py` 收敛为薄包装：
+
+```python
+from huace_aigc_oss import OssClient, UploadMode
+
+_client: OssClient | None = None
+
+def get_client() -> OssClient:
+    global _client
+    if _client is None:
+        _client = OssClient.from_env()
+    return _client
+
+def upload_local_file(local_path: str, oss_key: str, extranet: bool = False) -> str:
+    mode = UploadMode.EXTRANET if extranet else UploadMode.INTRANET
+    result = get_client().upload(oss_key, local_path, mode=mode)
+    return result.url or oss_key
+```
+
+### 10.2 环境变量迁移
+
+| 旧变量（插件内） | 新变量（SDK） |
+|------------------|---------------|
+| `OSS_ENDPOINT` | `OSS_ALIYUN_ENDPOINT`（SDK 同时读旧名） |
+| `OSS_ACCESS_KEY_ID` | `OSS_ALIYUN_ACCESS_KEY_ID` |
+| `OSS_BUCKET_NAME` | `OSS_ALIYUN_BUCKET` |
+| `OSS_NAME_PREFIX` | `OSS_KEY_PREFIX` |
+
+保证**向后兼容**：`OssConfig.from_env()` 先读 `OSS_ALIYUN_*`，缺失则 fallback 到现有 `OSS_*` 名称。
+
+---
+
+## 11. 测试策略
+
+| 类型 | 内容 |
+|------|------|
+| 单元 | Router 排序、sticky 读写、熔断状态机 |
+| 集成 | moto 模拟 S3 + 本地 MinIO 模拟 RustFS |
+| 契约 | 各 backend 对同一 key 的 put/get/exists 行为一致 |
+| 故障 | RustFS 超时后降级阿里云；上传失败不降级 |
+
+---
+
+## 12. 非目标（v1 不做）
+
+- 跨进程 / 分布式 sticky（Redis）
+- 上传自动降级、双写、异步复制
+- 分片上传大文件统一封装（可 v1.1 按 backend 暴露）
+- 预签名 URL 统一生成（各后端 API 差异大，v1.1）
+
+---
+
+## 13. 实施里程碑
+
+| 阶段 | 交付 |
+|------|------|
+| M1 | `OssConfig` + `AliyunOssBackend` + `download`/`upload`/`exists` 单后端 |
+| M2 | `RustFsBackend` + 下载降级 + sticky session |
+| M3 | `UploadMode.EXTRANET` + 旧 env 兼容 + 插件试点替换 |
+| M4 | `QiniuKodoBackend` + 熔断 + PyPI 0.1.0 |
+| M5 | 文档、集成测试、全插件 requirements 切换 |
+
+---
+
+## 14. 附录：下载降级触发条件一览
+
+| 条件 | 是否触发下一后端 |
+|------|------------------|
+| RustFS 连接超时 | 是 |
+| RustFS 服务不可达（连接拒绝） | 是 |
+| 对象不存在 | 是 |
+| 4xx/5xx（非鉴权致命） | 是（可配置） |
+| 鉴权失败（403 AK 错误） | **否**（立即失败，避免误降级） |
+| 阿里云成功 | 否（结束） |
+
+| 上传场景 | 是否跨后端重试 |
+|----------|----------------|
+| 内网模式 RustFS 失败 | 否 |
+| 外网模式阿里云失败 | 否 |
+
+---
+
+**文档版本**：1.0  
+**最后更新**：2026-06-02  
+**维护**：AIGC 插件平台组

huace_aigc_oss_proxy_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

huace_aigc_oss_proxy_client-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include QUICK_START.txt
+include DESIGN.md
+recursive-include huace_aigc_oss *.py
+global-exclude __pycache__
+global-exclude *.pyc

huace_aigc_oss_proxy_client-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: huace-aigc-oss-proxy-client
+Version: 0.1.0
+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
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+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**（S3 兼容）、**阿里云 OSS**、**七牛云**，支持下载自动降级与上传内外网路由。
+
+详细设计见 [DESIGN.md](./DESIGN.md)。
+
+## 安装
+
+```bash
+# 全量后端
+pip install huace-aigc-oss-proxy-client[all]
+
+# 仅阿里云
+pip install huace-aigc-oss-proxy-client[aliyun]
+```
+
+## 本地 RustFS 开发环境
+
+```bash
+docker compose -f docker-compose/rustfs/docker-compose.yml up -d
+```
+
+控制台：http://127.0.0.1:9001 （`minioadmin` / `minioadmin`）  
+API：`http://127.0.0.1:9000`，默认桶 `aigc-intranet`。
+
+## 环境变量
+
+```bash
+# RustFS 内网
+OSS_RUSTFS_ENABLED=true
+OSS_RUSTFS_ENDPOINT=http://127.0.0.1:9000
+OSS_RUSTFS_ACCESS_KEY=minioadmin
+OSS_RUSTFS_SECRET_KEY=minioadmin
+OSS_RUSTFS_BUCKET=aigc-intranet
+
+# 阿里云（兼容旧变量 OSS_ACCESS_KEY_ID 等）
+OSS_ALIYUN_ENABLED=true
+OSS_ALIYUN_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+OSS_ALIYUN_ACCESS_KEY_ID=***
+OSS_ALIYUN_ACCESS_KEY_SECRET=***
+OSS_ALIYUN_BUCKET=huace-shortmovie
+
+# 策略
+OSS_DOWNLOAD_PRIORITY=rustfs,aliyun
+OSS_UPLOAD_INTRANET_BACKEND=rustfs
+OSS_UPLOAD_EXTRANET_BACKEND=aliyun
+OSS_KEY_PREFIX=plugin-tts-indextts
+OSS_STICKY_SESSION_ENABLED=true
+OSS_FALLBACK_ENABLED=true
+```
+
+## 快速开始
+
+```python
+from huace_aigc_oss import OssClient, UploadMode
+
+client = OssClient.from_env()
+
+# 下载：RustFS 优先，失败自动切阿里云；同进程会记住成功的后端
+local = client.download("task-1/output.wav", "/tmp/output.wav")
+
+# 上传：默认内网 RustFS，无自动降级
+client.upload("task-1/output.wav", "/tmp/output.wav")
+
+# 上传：强制外网阿里云
+client.upload("task-1/output.wav", "/tmp/output.wav", mode=UploadMode.EXTRANET)
+
+client.exists("task-1/output.wav")
+```
+
+## 插件集成示例
+
+```python
+from huace_aigc_oss import OssClient, UploadMode
+
+_client = None
+
+def get_client() -> OssClient:
+    global _client
+    if _client is None:
+        _client = OssClient.from_env()
+    return _client
+
+def upload_local_file(local_path: str, oss_key: str, extranet: bool = False) -> str:
+    mode = UploadMode.EXTRANET if extranet else UploadMode.INTRANET
+    result = get_client().upload(oss_key, local_path, mode=mode)
+    return result.url or oss_key
+```
+
+## 发布
+
+见 [PUBLISH.md](./PUBLISH.md)。复制 `.pypirc.example` 为 `.pypirc` 并填入 PyPI Token。
+
+```bash
+python build_and_publish.py
+```
+
+## 核心行为
+
+| 操作 | 行为 |
+|------|------|
+| `download` | 按优先级尝试，失败降级；进程内 sticky 记住成功后端 |
+| `upload` | 确定性单后端，失败不降级 |
+| `exists` | 与 download 相同优先级链 |