autool-dispatcher/apk_cloud/MINIO_USAGE.md

MinioStorage 使用指南

概述

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

配置开关

在配置文件（如 config/local.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：直接实例化（不推荐）

from apk_cloud.storage import MinioStorage

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

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

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

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：预检查

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 中转。

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 禁用时，跳过下载队列的云端同步，改为本地队列管理：

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：

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 服务）

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

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

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

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

# 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 应在启动时通过配置文件或环境变量设置，运行时修改可能导致状态不一致。