# minio-data-downloader

**Repository Path**: YoungJJ/minio-data-downloader

## Basic Information

- **Project Name**: minio-data-downloader
- **Description**: 基于 Electron + Vue 3 + TypeScript 开发的跨平台桌面应用，用于从 MinIO 对象存储批量下载文件，支持断点续传、自动重试、并发控制，采用 AES-256-GCM 加密存储连接凭证，具备实时进度显示和网络错误容错能力，使用 Element Plus 构建深色主题响应式界面。
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">
  <img src="resources/icon.png" alt="Logo" width="80" height="80">
  <br>
  MinIO 文件下载器
</h1>

<p align="center">
  <strong>跨平台桌面应用 - 从 MinIO 对象存储批量下载文件</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Electron-28.2.0-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron">
  <img src="https://img.shields.io/badge/Vue-3.4-4FC08D?style=flat-square&logo=vue.js&logoColor=white" alt="Vue">
  <img src="https://img.shields.io/badge/TypeScript-5.3-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/Vite-5.0-646CFF?style=flat-square&logo=vite&logoColor=white" alt="Vite">
  <img src="https://img.shields.io/badge/MinIO-SDK-C72E49?style=flat-square&logo=minio&logoColor=white" alt="MinIO">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform">
  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License">
</p>

---

## ✨ 功能特性

| 功能 | 描述 |
|------|------|
| 📦 **批量下载** | 按目录前缀批量下载文件，自动过滤缩略图 |
| 🔄 **断点续传** | 中断后可继续下载，自动跳过已完成文件 |
| ⚡ **并发控制** | 根据 CPU 核心数动态调整，支持手动配置 |
| 🔁 **自动重试** | 智能识别网络错误，指数退避重试机制 |
| 📊 **实时进度** | 显示下载速度、进度百分比、当前文件 |
| 🔐 **安全存储** | AES-256-GCM 加密存储连接凭证 |
| 🌐 **域名支持** | 支持 IP、域名、完整 URL 多种连接方式 |
| 🎨 **深色主题** | 响应式设计，自适应窗口大小 |

---

## 🛠️ 技术架构

### 三层进程模型

| 进程 | 职责 | 核心模块 |
|------|------|----------|
| **Main Process** | Node.js 运行时，负责系统级操作 | MinIO Client、File System、Config Manager |
| **Preload Script** | 安全桥接层，暴露受限 API | IPC Bridge (contextBridge) |
| **Renderer Process** | Vue 3 应用，负责 UI 渲染 | App.vue、Settings.vue、Element Plus |

### 数据流向

```
用户操作 → Vue 组件 → IPC 调用 → Main 进程 → MinIO/文件系统 → 回调更新 UI
```

### 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **框架** | Electron 28 | 跨平台桌面应用 |
| **前端** | Vue 3 + TypeScript | Composition API |
| **UI** | Element Plus | 组件库 |
| **构建** | Vite + electron-vite | 快速构建 |
| **存储** | MinIO SDK | 对象存储客户端 |
| **加密** | CryptoJS (AES-256-GCM) | 凭证加密 |

---

## 📁 项目结构

```
xzhk-oss-client/
├── src/
│   ├── main/                 # Electron 主进程
│   │   └── index.ts          # MinIO 操作、IPC 处理、窗口管理
│   ├── preload/              # 预加载脚本
│   │   ├── index.ts          # API 桥接
│   │   └── index.d.ts        # 类型声明
│   └── renderer/             # Vue 渲染进程
│       └── src/
│           ├── App.vue       # 主页面
│           ├── components/
│           │   └── Settings.vue  # 设置页面
│           └── utils/
│               └── encryption.ts # AES 加密工具
├── resources/
│   └── icon.png              # 应用图标
├── config.json               # 默认配置模板
├── electron-builder.yml      # 打包配置
└── electron.vite.config.ts   # Vite 配置
```

---

## 🔧 核心技术点

### 1. 并发下载控制

```typescript
class ConcurrencyController {
  private running = 0
  private queue: (() => void)[] = []

  async run<T>(fn: () => Promise<T>): Promise<T> {
    while (this.running >= this.maxConcurrent) {
      await new Promise<void>(resolve => this.queue.push(resolve))
    }
    this.running++
    try {
      return await fn()
    } finally {
      this.running--
      this.queue.shift()?.()
    }
  }
}
```

### 2. 网络错误重试机制

- 自动识别 `ENOTFOUND`、`ECONNRESET`、`ETIMEDOUT` 等网络错误
- 指数退避策略：错误次数越多，等待时间越长
- 最大重试 10 次，单次超时 3 分钟

### 3. 断点续传实现

```typescript
interface DownloadProgressRecord {
  prefix: string
  completedFiles: string[]  // 已完成文件列表
  totalFiles: number
  lastUpdateTime: number
}
```

- 每批次完成后保存进度到本地 JSON 文件
- 重新下载时自动比对已完成文件和本地文件大小
- 支持取消后继续、失败后重试

### 4. 安全的 IPC 通信

```typescript
// preload/index.ts
contextBridge.exposeInMainWorld('api', {
  getMinioConfig: () => ipcRenderer.invoke('get-minio-config'),
  downloadMinioFilesBatch: (files, prefix) =>
    ipcRenderer.invoke('download-minio-files-batch', files, prefix)
})
```

---

## 🚀 快速开始

### 环境要求

- Node.js >= 18
- npm 或 pnpm

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

### 构建应用

```bash
# Windows
npm run build:win

# macOS
npm run build:mac

# Linux
npm run build:linux
```

---

## ⚙️ 配置说明

首次运行时需要在设置页面配置 MinIO 连接信息：

| 配置项 | 说明 | 示例 |
|--------|------|------|
| 服务器地址 | MinIO 服务地址 | `minio.example.com` 或 `192.168.1.100:9000` |
| 端口 | 服务端口 | `9000` |
| SSL | 是否启用 HTTPS | 开/关 |
| Access Key | 访问密钥 | `minioadmin` |
| Secret Key | 密钥 | `minioadmin` |
| Bucket | 存储桶名称 | `my-bucket` |
| 并发数 | 同时下载文件数 | 根据 CPU 核心数推荐 |

---

## 📝 使用说明

1. **配置连接**：点击右上角设置按钮，填写 MinIO 连接信息
2. **测试连接**：点击"测试连接"验证配置是否正确
3. **输入目录**：在主页输入要下载的目录前缀（如 `photos/2024/`）
4. **选择路径**：选择本地保存位置
5. **开始下载**：点击"开始下载"按钮
6. **断点续传**：如果中断，再次下载时会提示是否继续

---

## 🎨 界面预览

- **深色主题**：护眼的深色设计
- **响应式布局**：自适应不同窗口大小
- **实时反馈**：进度条、下载速度、错误信息实时显示

---

## 📄 License

MIT License © 2026

---

<p align="center">
  Made with ❤️ using Electron + Vue 3
</p>