# minio客户端

**Repository Path**: opencv265560/minio-client

## Basic Information

- **Project Name**: minio客户端
- **Description**: minio上传异步连接池动态伸缩
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-28
- **Last Updated**: 2025-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# MinIO C++ 客户端库

这个项目提供了基于MinIO C++ SDK的高级封装，实现了高性能的对象存储客户端，支持分片上传、断点续传、多线程并行上传等功能。

## **编译指南**

### 方法1 使用vcpkg安装依赖项：

```
# 建议在用户跟目录，（相当于这是应用宝，后面通过应用宝vcpkg安装软件）安装vcpkg（如果尚未安装）
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
拿到
-DCMAKE_TOOLCHAIN_FILE=/home/jbj/thirdparty/vcpkg/scripts/buildsystems/vcpkg.cmake

vim ~/.bashrc
export VCPKG_ROOT=/home/jbj/thirdparty/vcpkg/
export PATH=$VCPKG_ROOT:$PATH
source ~/.bashrc

```

#### vcpkg.json列出清单

vcpkg.json

```
{
 "name": "my-minio-project",
 "version-string": "0.1.0",
 "dependencies": [
  "minio-cpp",
  "openssl"
 ]
}
```

vcpkg install

得到vcpkg_installed/x64-linux/项目依赖打包文件

设置vcpkg_installed路劲

cmake -DCMAKE_PREFIX_PATH=/home/jbj/minio/vcpkg_installed/x64-linux ..

make使用

#### minio-cpp 编译成静态库

要将 minio-cpp 编译成静态库供其他服务使用，您需要执行以下步骤：

1. 首先，修改您的 vcpkg.json 文件以指定静态链接：

```json
{
  "name": "my-minio-project",
  "version-string": "0.1.0",
  "dependencies": [
    {
      "name": "minio-cpp"
    },
    {
      "name": "openssl"
    }
  ],
  "builtin-baseline": "8f54ef5453e7e76ff01e15988bf243e7247c5eb5"
}
```

2. **创建一个自定义的 triplet 文件，强制静态链接：**

```bash
# 创建一个自定义 triplet 文件
mkdir -p /home/jbj/minio/triplets
```

**创建文件 `/home/jbj/minio/triplets/x64-linux-static-custom.cmake`，内容如下：**

```cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME Linux)
```

3. **使用这个自定义 triplet 安装依赖：**

```bash
/home/jbj/thirdparty/vcpkg/vcpkg install --overlay-triplets=/home/jbj/minio/triplets --triplet=x64-linux-static-custom
```

4. 拷贝lib到当前目录

   ```
   cp /home/jbj/thirdparty/vcpkg/packages/curlpp_x64-linux-static-custom/lib/
   .a lib/ 
   ```

5. **创建一个 CMakeLists.txt 文件，将您的 MinIO 客户端代码编译成静态库：**

```cmake
cmake_minimum_required(VERSION 3.10)
project(miniocpp_example LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 添加源文件
set(SOURCES
    src/main.cpp
    src/minio_client.cpp
    # src/put.cpp
    # src/upload_manager.cpp
)

# 添加头文件
set(HEADERS
    src/minio_client.h
    # include/upload_manager.h
)

# 创建可执行文件
add_executable(minio_client ${SOURCES} ${HEADERS})

# 包含头文件目录
target_include_directories(minio_client PRIVATE 
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

# 设置静态库路径
link_directories(${CMAKE_CURRENT_SOURCE_DIR}/lib)

# 链接依赖库
target_link_libraries(minio_client PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libminiocpp.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libcurlpp.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libcurl.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libssl.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libcrypto.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libpugixml.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libz.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libINIReader.a
    ${CMAKE_CURRENT_SOURCE_DIR}/lib/libinih.a
    pthread
    dl
)

target_compile_features(minio_client PUBLIC cxx_std_17)
```



## 项目结构

```
.
├── CMakeLists.txt     # CMake 构建文件
├── include/           # 头文件目录
├── lib/               # 静态库目录
├── src/               # 源代码目录
│   ├── minio_client.h       # MinIO客户端封装类头文件
│   ├── minio_client.cpp     # MinIO客户端封装类实现
│   ├── StoreServerManager.h # 存储服务管理器头文件
│   ├── StoreServerManager.cpp # 存储服务管理器实现
│   └── main.cpp             # 示例程序入口
└── triplets/          # vcpkg 自定义 triplet
```

## 核心功能

### 1. 动态线程池管理

- 支持动态伸缩的线程池，根据任务负载自动调整线程数量
- 可配置的最小/最大线程数和空闲超时时间
- 线程资源智能管理，避免资源浪费

### 2. 高级上传功能

- **分片上传**：将大文件分割成多个小块并行上传，提高传输效率
- **断点续传**：支持上传中断后从断点处继续上传，避免重复传输
- **多线程并行上传**：利用多线程同时上传多个文件或分片
- **上传进度回调**：实时获取上传进度信息
- **上传状态通知**：上传完成或失败时的状态回调

### 3. 存储服务管理

- 支持同时管理多个存储服务（MinIO、S3等）
- 统一的服务配置和任务调度接口
- 服务健康检查和自动重连

### 4. 错误处理与重试机制

- 可配置的重试次数和重试延迟
- 详细的错误报告和日志记录
- 异常安全的资源管理

## 架构设计

项目采用分层架构设计：

1. **底层封装层**：`MinIOClient` 类
   - 封装原始MinIO C++ SDK
   - 提供基础的文件上传、下载、分片上传等功能
   - 实现错误处理和重试逻辑
2. **线程池管理层**：`UploadThreadPool` 类
   - 管理工作线程的创建、销毁和调度
   - 实现任务队列和优先级管理
   - 提供动态伸缩能力
3. **服务管理层**：`StoreServerManager` 类
   - 管理多个存储服务实例
   - 提供统一的任务提交接口
   - 负责资源分配和释放

## 使用方法

### 1. 初始化存储服务管理器

```
// 设置线程池配置
ThreadPoolConfig thread_config;
thread_config.thread_dynamic_scaling = true;  // 启用动态伸缩
thread_config.thread_max_count = 8;           // 最大线程数
thread_config.thread_min_count = 1;           // 最小线程数
thread_config.thread_current_count = 4;       // 初始线程数
thread_config.thread_idle_time = std::chrono::seconds(10);  // 空闲超时时间

// 初始化管理器
StoreServerManager::getInstance().initialize(thread_config);
```

### 2. 添加存储服务

```
// 创建存储服务配置
StoreServiceConfig config;
config.type = StoreServiceType::MINIO;        // 服务类型
config.endpoint = "play.min.io:9000";         // 服务端点
config.access_key = "YOUR_ACCESS_KEY";        // 访问密钥
config.secret_key = "YOUR_SECRET_KEY";        // 秘密密钥
config.bucket = "your-bucket-name";           // 存储桶名称
config.use_ssl = true;                        // 是否使用SSL

// 添加服务
std::string service_id = "minio-service";
if (!StoreServerManager::getInstance().addService(service_id, config)) {
    std::cerr << "添加存储服务失败" << std::endl;
    return;
}
```

### 3. 配置上传任务

```
// 配置分片上传参数
UploadShardingConfig upload_config;
upload_config.part_size = 10 * 1024 * 1024;   // 分片大小(10MB)
upload_config.thread_count = 4;               // 分片上传并行数
upload_config.retry_count = 3;                // 重试次数
upload_config.retry_delay_ms = 1000;          // 重试延迟(1秒)

// 创建上传任务
StoreUploadTask task;
task.service_id = service_id;                 // 服务ID
task.object_name = "remote-file.mp4";         // 对象名称
task.local_file_path = "/path/to/local/file.mp4"; // 本地文件路径
task.config = upload_config;                  // 上传配置
task.task_id = "unique-task-id";              // 任务唯一标识

// 设置进度回调
task.progress_cb = [](size_t uploaded, size_t total) {
    double percentage = static_cast<double>(uploaded) / total * 100.0;
    std::cout << "\rProgress: " << percentage << "%" << std::flush;
};

// 设置状态回调
task.status_cb = [](bool success, const std::string& message, const StoreUploadTask& task) {
    if (success) {
        std::cout << "\nUpload successful, ETag: " << message << std::endl;
    } else {
        std::cerr << "\nUpload failed: " << message << std::endl;
    }
};
```

### 4. 提交上传任务

```
// 提交上传任务(非阻塞)
if (!StoreServerManager::getInstance().submitUploadTask(task)) {
    std::cerr << "提交上传任务失败" << std::endl;
}

// 主线程可以继续执行其他操作
std::cout << "上传任务已在后台运行..." << std::endl;
```

### 5. 取消上传任务

```
// 取消指定的上传任务
StoreServerManager::getInstance().cancelUpload(service_id, task.task_id);
```

### 6. 清理资源

```
// 程序结束前销毁管理器，释放资源
StoreServerManager::getInstance().destroy();
```

## 高级用例

### 多文件并行上传

```
std::vector<std::string> files = {"file1.mp4", "file2.mp4", "file3.mp4"};
for (int i = 0; i < files.size(); i++) {
    StoreUploadTask task;
    task.service_id = service_id;
    task.object_name = "remote-" + files[i];
    task.local_file_path = "/path/to/" + files[i];
    task.config = upload_config;
    task.task_id = "task-" + std::to_string(i);
    task.progress_cb = printProgress;
    task.status_cb = uploadStatusCallback;

    StoreServerManager::getInstance().submitUploadTask(task);
}
```

### 多存储服务管理

```
// 添加MinIO服务
StoreServiceConfig minio_config;
minio_config.type = StoreServiceType::MINIO;
minio_config.endpoint = "minio.example.com:9000";
minio_config.access_key = "MINIO_ACCESS_KEY";
minio_config.secret_key = "MINIO_SECRET_KEY";
minio_config.bucket = "minio-bucket";
minio_config.use_ssl = true;
StoreServerManager::getInstance().addService("minio-service", minio_config);

// 添加Amazon S3服务
StoreServiceConfig s3_config;
s3_config.type = StoreServiceType::S3;
s3_config.endpoint = "s3.amazonaws.com";
s3_config.access_key = "AWS_ACCESS_KEY";
s3_config.secret_key = "AWS_SECRET_KEY";
s3_config.bucket = "s3-bucket";
s3_config.use_ssl = true;
StoreServerManager::getInstance().addService("s3-service", s3_config);

// 根据需要选择不同的服务上传
task.service_id = "minio-service";  // 使用MinIO服务
// 或
task.service_id = "s3-service";     // 使用S3服务
```

## 依赖项

本项目使用以下依赖项：

- C++17 编译器支持
- CMake 3.10 或更高版本
- vcpkg 包管理器（用于依赖项管理）
- minio-cpp（MinIO官方C++客户端）
- libcurl 和 curlpp（HTTP 通信）
- OpenSSL（加密和 TLS 支持）
- pugixml（XML 解析）
- nlohmann-json（JSON 解析）
- zlib（压缩）

## 编译与构建

### 使用CMake构建

```
mkdir -p build
cd build
cmake ..
make
```

### 运行示例程序

```
./minio_example
```

## 性能优化

- **分片大小选择**：根据网络条件和文件大小调整分片大小，通常10MB-100MB之间
- **线程数量配置**：根据CPU核心数和网络带宽调整线程数量
- **内存使用优化**：使用流式处理避免将整个文件加载到内存
- **重试策略**：对网络不稳定的环境增加重试次数和延迟时间

## 故障排除

1. **连接问题**：
   - 检查endpoint是否正确
   - 确认网络连接是否正常
   - 验证SSL配置是否正确
2. **认证错误**：
   - 验证access_key和secret_key是否正确
   - 检查bucket权限设置
3. **上传失败**：
   - 检查磁盘空间是否足够
   - 增加重试次数和延迟
   - 查看详细错误日志

## 许可证

请参考MinIO C++ 客户端的许可证。