# MinioStorage 使用指南

## 概述

`MinioStorage` 提供 APK 云存储功能，支持通过 `MINIO_ENABLED` 配置开关控制是否启用。

## 配置开关

在配置文件（如 `config/local.yaml` 或环境变量）中设置：

```yaml
# 启用 Minio（默认）
MINIO_ENABLED: true
MINIO_ENDPOINT: "minio.example.com:9000"
MINIO_ACCESS_KEY: "your-access-key"
MINIO_SECRET_KEY: "your-secret-key"
MINIO_BUCKET: "apk-storage"
MINIO_SECURE: false

# 禁用 Minio（跨团队部署或无 Minio 服务时）
MINIO_ENABLED: false
```

## 使用方式

### 方式 1：直接实例化（不推荐）

```python
from apk_cloud.storage import MinioStorage

try:
    storage = MinioStorage()
    # 使用 storage 进行操作
except RuntimeError as e:
    print(f"Minio 功能已禁用: {e}")
    # 降级到直接下载模式
```

**缺点**：当 `MINIO_ENABLED=False` 时会抛出异常，需要额外的异常处理。

### 方式 2：工厂方法（推荐）

```python
from apk_cloud.storage import MinioStorage

storage = MinioStorage.create()
if storage is None:
    print("Minio 已禁用，使用直接下载模式")
    # 执行降级逻辑，例如直接从 APK 源下载
else:
    # 使用 storage 进行 Minio 操作
    storage.push_download_queue(tasks)
```

**优点**：无需异常处理，代码更简洁清晰。

### 方式 3：预检查

```python
from apk_cloud.storage import MinioStorage

if MinioStorage.is_enabled():
    storage = MinioStorage()
    # 使用 Minio 功能
else:
    # 使用降级方案
    print("Minio 已禁用，跳过云存储同步")
```

## 降级方案

当 `MINIO_ENABLED=False` 时，推荐的降级方案：

### 1. APK 直接下载模式

配置 `APK_DOWNLOAD_MODE='direct'`，直接从 APK 源（如 Google Play、APKPure）下载到本地，不经过 Minio 中转。

```python
from config import APK_DOWNLOAD_MODE

if APK_DOWNLOAD_MODE == 'direct':
    # 直接下载到 worker 本地
    apk_path = download_apk_from_source(package_name)
else:
    # 从 Minio 下载
    storage = MinioStorage.create()
    if storage:
        apk_path = storage.download_apk(package_name, manifest, dest_dir)
```

### 2. 队列同步跳过

当 Minio 禁用时，跳过下载队列的云端同步，改为本地队列管理：

```python
storage = MinioStorage.create()
if storage:
    # 同步云端队列
    storage.push_download_queue(tasks)
else:
    # 使用本地队列文件
    with open("local_queue.json", "w") as f:
        json.dump(tasks, f)
```

### 3. 结果存储本地化

下载结果存储到本地文件系统，而非 Minio：

```python
storage = MinioStorage.create()
if storage:
    storage.write_download_result(package_name, result)
else:
    # 本地存储
    result_path = f"results/{package_name}.json"
    os.makedirs("results", exist_ok=True)
    with open(result_path, "w") as f:
        json.dump(result, f)
```

## 向后兼容性

- **默认行为不变**：`MINIO_ENABLED` 默认为 `True`，现有代码无需修改即可继续使用。
- **旧代码兼容**：直接调用 `MinioStorage()` 的旧代码仍然有效（启用时），禁用时会抛出友好的错误提示。
- **新代码建议**：新代码推荐使用 `MinioStorage.create()` 工厂方法，以便更好地处理禁用场景。

## 部署场景示例

### 场景 1：单团队部署（有 Minio 服务）

```yaml
# config/prod.yaml
MINIO_ENABLED: true
MINIO_ENDPOINT: "minio.internal:9000"
APK_DOWNLOAD_MODE: "minio"  # 通过 Minio 分发 APK
```

### 场景 2：跨团队部署（无 Minio 服务）

```yaml
# config/prod.yaml
MINIO_ENABLED: false
APK_DOWNLOAD_MODE: "direct"  # 每个 worker 直接下载
```

### 场景 3：开发环境（可选 Minio）

```yaml
# config/local.yaml
MINIO_ENABLED: false  # 本地开发不依赖 Minio
APK_DOWNLOAD_MODE: "direct"
```

## 常见问题

### Q: 为什么不用环境变量 `MINIO_ENDPOINT` 空值判断？

A: 配置项可能因网络分区、配置错误等原因为空，不能作为功能开关的可靠信号。显式的 `MINIO_ENABLED` 开关语义更清晰，避免歧义。

### Q: 禁用 Minio 后，已有的云端数据会丢失吗？

A: 不会。禁用仅影响新操作，Minio 服务端的数据保持不变。重新启用后可继续访问。

### Q: 可以在运行时动态切换吗？

A: 不建议。`MINIO_ENABLED` 应在启动时通过配置文件或环境变量设置，运行时修改可能导致状态不一致。