# MinIO Client (mc) 使用指南

本目录包含在 Woodpecker CI 中使用 MinIO Client (mc) 操作 RustFS/S3 对象存储的完整示例。

## 📋 目录

- [mc 简介](#mc-简介)
- [目录结构](#目录结构)
- [快速开始](#快速开始)
- [常用功能](#常用功能)
  - [上传文件](#上传文件)
  - [下载文件](#下载文件)
  - [列举文件](#列举文件)
  - [删除文件](#删除文件)
  - [生成临时下载链接](#生成临时下载链接)
  - [设置公开访问](#设置公开访问)
  - [清理旧文件](#清理旧文件)
- [临时链接详解](#临时链接详解)
- [命令速查表](#命令速查表)
- [最佳实践](#最佳实践)

---

## mc 简介

MinIO Client (mc) 是一个功能强大的命令行工具，用于操作 S3 兼容的对象存储服务。

### 为什么选择 mc？

✅ **功能全面**: 支持上传、下载、删除、同步、生成临时链接等  
✅ **跨平台**: 支持 Linux、macOS、Windows  
✅ **兼容性好**: 完全兼容 S3 API 和 RustFS  
✅ **易于使用**: 命令简洁，类似传统的文件操作命令  
✅ **可验证**: 可获取 ETag、VersionId 等元数据  
✅ **支持预签名**: 可生成无需认证的临时下载链接

---

## 目录结构

```
mc/
├── README.md                 # 本文档
├── linux/
│   └── woodpecker.yml       # Linux 环境完整示例
└── macos/
    └── woodpecker.yml       # macOS 环境完整示例
```

---

## 快速开始

### 安装 mc

**Linux:**
```bash
curl -sSL https://dl.min.io/client/mc/release/linux-amd64/mc \
  -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc
```

**macOS (Intel):**
```bash
curl -sSL https://dl.min.io/client/mc/release/darwin-amd64/mc \
  -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc
```

**macOS (Apple Silicon):**
```bash
curl -sSL https://dl.min.io/client/mc/release/darwin-arm64/mc \
  -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc
```

### 配置 mc 别名

```bash
# 配置 RustFS 连接
mc alias set rustfs https://your-rustfs-server:9000 YOUR_ACCESS_KEY YOUR_SECRET_KEY

# 验证配置
mc admin info rustfs
```

---

## 常用功能

### 上传文件

#### 上传单个文件
```bash
mc cp local-file.txt rustfs/my-bucket/path/remote-file.txt
```

#### 上传整个目录
```bash
mc cp --recursive ./dist/ rustfs/my-bucket/website/
```

#### 上传时删除源路径前缀
```bash
# 将 dist/css/style.css 上传为 css/style.css
mc mirror --overwrite ./dist/ rustfs/my-bucket/website/
```

#### 上传并获取 ETag
```bash
mc cp myfile.jar rustfs/my-bucket/builds/
mc stat rustfs/my-bucket/builds/myfile.jar | grep ETag
```

---

### 下载文件

#### 下载单个文件
```bash
mc cp rustfs/my-bucket/path/file.txt ./local-file.txt
```

#### 下载整个目录
```bash
mc cp --recursive rustfs/my-bucket/backup/ ./local-backup/
```

#### 下载最新版本
```bash
mc cp rustfs/my-bucket/versioned-file.txt ./
```

---

### 列举文件

#### 列出 bucket 内容
```bash
# 列出顶层文件
mc ls rustfs/my-bucket/

# 递归列出所有文件
mc ls --recursive rustfs/my-bucket/

# 列出并显示详细信息
mc ls --recursive --summarize rustfs/my-bucket/
```

#### 按时间过滤
```bash
# 列出最近 7 天修改的文件
mc ls --recursive --newer-than 7d rustfs/my-bucket/

# 列出 30 天前的文件
mc ls --recursive --older-than 30d rustfs/my-bucket/
```

---

### 删除文件

#### 删除单个文件
```bash
mc rm rustfs/my-bucket/path/file.txt
```

#### 删除整个目录
```bash
mc rm --recursive --force rustfs/my-bucket/old-builds/
```

#### 按时间删除
```bash
# 删除 30 天前的文件
mc rm --recursive --force --older-than 30d rustfs/my-bucket/builds/

# 删除 7 天前的日志
mc rm --recursive --force --older-than 7d rustfs/my-bucket/logs/
```

#### 按模式删除
```bash
# 删除所有 .log 文件
mc rm --recursive --force rustfs/my-bucket/logs/*.log

# 删除特定日期的构建
mc rm --recursive --force rustfs/my-bucket/builds/20241001/
```

---

### 生成临时下载链接

#### 基本用法（默认 7 天有效期）
```bash
mc share download rustfs/my-bucket/path/file.jar
```

**输出示例：**
```
URL: https://your-server:9000/my-bucket/path/file.jar?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
Expire: 7 days 0 hours 0 minutes 0 seconds
Share: https://your-server:9000/my-bucket/path/file.jar?X-Amz-Algorithm=...
```

#### 自定义有效期

##### 按小时
```bash
# 1 小时
mc share download --expire 1h rustfs/my-bucket/file.jar

# 6 小时
mc share download --expire 6h rustfs/my-bucket/file.jar

# 24 小时（1天）
mc share download --expire 24h rustfs/my-bucket/file.jar
```

##### 按天
```bash
# 1 天
mc share download --expire 1d rustfs/my-bucket/file.jar

# 3 天
mc share download --expire 3d rustfs/my-bucket/file.jar

# 7 天（最大值）
mc share download --expire 7d rustfs/my-bucket/file.jar

# 14 天（如果服务器支持）
mc share download --expire 14d rustfs/my-bucket/file.jar
```

##### 按分钟（短期分享）
```bash
# 30 分钟
mc share download --expire 30m rustfs/my-bucket/temp-file.txt

# 5 分钟（快速分享）
mc share download --expire 5m rustfs/my-bucket/quick-share.pdf
```

#### 批量生成链接
```bash
# 为目录下所有文件生成链接
mc ls rustfs/my-bucket/releases/ | awk '{print $NF}' | while read file; do
  echo "Generating link for: $file"
  mc share download --expire 7d rustfs/my-bucket/releases/$file
done
```

#### 生成链接并保存
```bash
# 保存到文件
mc share download --expire 7d rustfs/my-bucket/app.jar > download-link.txt

# 提取纯 URL
mc share download --expire 7d rustfs/my-bucket/app.jar | grep "Share:" | awk '{print $2}'
```

---

### 设置公开访问

#### 设置 bucket 为公开可读（永久链接）
```bash
# 公开整个 bucket
mc anonymous set download rustfs/my-bucket/

# 公开特定路径
mc anonymous set download rustfs/my-bucket/public/

# 取消公开访问
mc anonymous set none rustfs/my-bucket/
```

**公开访问后的 URL 格式：**
```
https://your-server:9000/my-bucket/path/file.jar
```

不需要签名参数，可直接访问。

---

### 清理旧文件

#### 按时间自动清理
```bash
# 清理 30 天前的构建
mc rm --recursive --force --older-than 30d rustfs/my-bucket/builds/

# 清理 7 天前的日志
mc rm --recursive --force --older-than 7d rustfs/my-bucket/logs/

# 清理 90 天前的备份
mc rm --recursive --force --older-than 90d rustfs/my-bucket/backups/
```

#### 保留最近 N 个版本
```bash
# 列出文件按时间排序
mc ls --recursive rustfs/my-bucket/releases/ | sort -k1,1 -r | tail -n +11 | awk '{print $NF}' | while read file; do
  mc rm rustfs/my-bucket/releases/$file
done
```

---

## 临时链接详解

### 临时链接的工作原理

临时下载链接（预签名 URL）使用 AWS Signature V4 算法生成，包含：
- 访问凭证（已签名）
- 过期时间戳
- 请求参数的签名

**优势：**
- ✅ 无需认证即可下载
- ✅ 可设置精确的过期时间
- ✅ 可分享给任何人
- ✅ 自动过期，安全可控

### 有效期时间单位

| 单位 | 说明 | 示例 |
|------|------|------|
| `m` | 分钟 (minutes) | `30m` = 30分钟 |
| `h` | 小时 (hours) | `6h` = 6小时 |
| `d` | 天 (days) | `7d` = 7天 |

### 有效期限制

- **最小值**: 1 分钟 (`1m`)
- **默认值**: 7 天 (`7d`)
- **最大值**: 取决于 S3 服务器配置（通常为 7 天）

### 常见使用场景

#### 场景 1: 内部快速分享（短期）
```bash
# 5分钟有效，用于即时分享
mc share download --expire 5m rustfs/bucket/temp-file.zip
```

#### 场景 2: 客户下载（中期）
```bash
# 24小时有效，给客户足够时间下载
mc share download --expire 24h rustfs/bucket/client-delivery.zip
```

#### 场景 3: 归档访问（长期）
```bash
# 7天有效，用于归档文件的临时访问
mc share download --expire 7d rustfs/bucket/archive/report.pdf
```

#### 场景 4: 公开发布（永久）
```bash
# 不设置过期时间，使用公开访问
mc anonymous set download rustfs/bucket/public/
# 现在可以直接访问: https://server/bucket/public/file.jar
```

---

## 命令速查表

### 文件操作

| 操作 | 命令 |
|------|------|
| 上传文件 | `mc cp file.txt rustfs/bucket/` |
| 上传目录 | `mc cp --recursive ./dir/ rustfs/bucket/` |
| 下载文件 | `mc cp rustfs/bucket/file.txt ./` |
| 下载目录 | `mc cp --recursive rustfs/bucket/dir/ ./` |
| 删除文件 | `mc rm rustfs/bucket/file.txt` |
| 删除目录 | `mc rm --recursive --force rustfs/bucket/dir/` |
| 列出文件 | `mc ls rustfs/bucket/` |
| 递归列出 | `mc ls --recursive rustfs/bucket/` |
| 查看信息 | `mc stat rustfs/bucket/file.txt` |

### 临时链接

| 操作 | 命令 |
|------|------|
| 生成链接（默认7天） | `mc share download rustfs/bucket/file.jar` |
| 1小时有效 | `mc share download --expire 1h rustfs/bucket/file.jar` |
| 1天有效 | `mc share download --expire 1d rustfs/bucket/file.jar` |
| 7天有效 | `mc share download --expire 7d rustfs/bucket/file.jar` |
| 30分钟有效 | `mc share download --expire 30m rustfs/bucket/file.jar` |

### 清理操作

| 操作 | 命令 |
|------|------|
| 删除30天前文件 | `mc rm --recursive --older-than 30d rustfs/bucket/` |
| 删除7天前文件 | `mc rm --recursive --older-than 7d rustfs/bucket/` |
| 删除所有.log | `mc rm --recursive rustfs/bucket/*.log` |
| 强制删除 | `mc rm --recursive --force rustfs/bucket/dir/` |

### 权限操作

| 操作 | 命令 |
|------|------|
| 设置公开下载 | `mc anonymous set download rustfs/bucket/` |
| 设置公开上传 | `mc anonymous set upload rustfs/bucket/` |
| 设置公开读写 | `mc anonymous set public rustfs/bucket/` |
| 取消公开访问 | `mc anonymous set none rustfs/bucket/` |
| 查看权限 | `mc anonymous get rustfs/bucket/` |

---

## 最佳实践

### 1. 密钥管理
```yaml
# ✅ 使用 Woodpecker Secrets
environment:
  AWS_ACCESS_KEY_ID:
    from_secret: AWS_ACCESS_KEY_ID
  AWS_SECRET_ACCESS_KEY:
    from_secret: AWS_SECRET_ACCESS_KEY

# ❌ 不要硬编码密钥
environment:
  AWS_ACCESS_KEY_ID: "AKIAIOSFODNN7EXAMPLE"
```

### 2. 错误处理
```bash
set -e  # 遇到错误立即退出

# 上传并验证
mc cp file.jar rustfs/bucket/
if mc stat rustfs/bucket/file.jar &>/dev/null; then
  echo "✅ Upload successful"
else
  echo "❌ Upload failed"
  exit 1
fi
```

### 3. 按日期组织
```bash
# 按日期创建目录
BUILD_DATE=$(date +%Y%m%d)
mc cp dist/ rustfs/bucket/builds/${BUILD_DATE}/
```

### 4. 定期清理
```bash
# 在 CI 中定期清理旧构建
mc rm --recursive --older-than 30d rustfs/bucket/builds/
```

### 5. 生成有意义的链接
```bash
# 保存链接到文件，方便分享
BUILD_ID=${CI_PIPELINE_NUMBER}
mc share download --expire 7d rustfs/bucket/app-${BUILD_ID}.jar > download-${BUILD_ID}.txt
```

### 6. 验证上传
```bash
# 上传后获取 ETag 验证完整性
mc cp file.jar rustfs/bucket/
ETAG=$(mc stat rustfs/bucket/file.jar | grep ETag | awk '{print $2}')
echo "File uploaded with ETag: $ETAG"
```

---

## 使用示例

### 示例 1: 上传并生成下载链接

```bash
#!/bin/bash
set -e

# 配置
mc alias set rustfs https://s3.example.com:9000 $ACCESS_KEY $SECRET_KEY

# 上传文件
mc cp myapp.jar rustfs/releases/v1.0.0/myapp.jar

# 生成 24 小时有效的下载链接
DOWNLOAD_LINK=$(mc share download --expire 24h rustfs/releases/v1.0.0/myapp.jar | grep Share | awk '{print $2}')

echo "✅ 上传成功！"
echo "📥 下载链接: $DOWNLOAD_LINK"
echo "⏰ 有效期: 24 小时"
```

### 示例 2: 清理旧构建并保留最新 10 个

```bash
#!/bin/bash
set -e

mc alias set rustfs https://s3.example.com:9000 $ACCESS_KEY $SECRET_KEY

# 列出所有构建，按时间排序，删除 30 天前的
echo "🧹 清理旧构建..."
mc rm --recursive --older-than 30d rustfs/builds/

# 统计剩余构建数
REMAINING=$(mc ls --recursive rustfs/builds/ | wc -l)
echo "✅ 清理完成，剩余 $REMAINING 个构建"
```

### 示例 3: 批量生成下载链接

```bash
#!/bin/bash
set -e

mc alias set rustfs https://s3.example.com:9000 $ACCESS_KEY $SECRET_KEY

echo "# 下载链接汇总" > links.md
echo "生成时间: $(date)" >> links.md
echo "" >> links.md

# 为 releases 目录下所有文件生成链接
mc ls rustfs/releases/ | awk '{print $NF}' | while read file; do
  LINK=$(mc share download --expire 7d rustfs/releases/$file | grep Share | awk '{print $2}')
  echo "- [$file]($LINK)" >> links.md
done

echo "✅ 链接汇总已保存到 links.md"
```

---

## 参考资源

- [MinIO Client 完整文档](https://min.io/docs/minio/linux/reference/minio-mc.html)
- [mc GitHub 仓库](https://github.com/minio/mc)
- [RustFS 文档](https://docs.rustfs.com)
- [AWS S3 API 参考](https://docs.aws.amazon.com/s3/)

---

## 故障排查

### 问题 1: mc 命令未找到
```bash
# 重新安装
curl -sSL https://dl.min.io/client/mc/release/linux-amd64/mc -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc
```

### 问题 2: 连接失败
```bash
# 检查别名配置
mc alias list

# 重新配置
mc alias set rustfs https://your-server:9000 ACCESS_KEY SECRET_KEY

# 测试连接
mc admin info rustfs
```

### 问题 3: 权限被拒绝
```bash
# 检查访问密钥是否正确
mc admin user info rustfs ACCESS_KEY

# 验证 bucket 权限
mc anonymous get rustfs/bucket/
```

### 问题 4: 临时链接无法访问
```bash
# 检查链接是否过期
# 重新生成链接
mc share download --expire 1d rustfs/bucket/file.jar

# 或设置为公开访问
mc anonymous set download rustfs/bucket/
```

---

**最后更新**: 2025-10-12  
**维护者**: RustFS Team