# MinIO 文件服务器部署总结

## 🎉 部署完成

MinIO 对象存储服务已成功部署到 Kubernetes 集群，专门用于存储 Gitea Runner 的测试报告和构建产物。

## 📊 部署详情

### 组件状态

| 组件 | 状态 | 说明 |
|------|------|------|
| **MinIO Server** | ✅ Running | S3 兼容对象存储服务 |
| **PVC** | ✅ Bound | 20GB 持久化存储 |
| **Services** | ✅ Created | API + Console 服务 |
| **Buckets** | ✅ Initialized | 3 个预创建的 bucket |

### 访问信息

```bash
# MinIO Console（Web 管理界面）
URL: http://localhost:31001
用户名: minioadmin
密码: minioadmin123

# MinIO API（S3 兼容接口）
外部: http://localhost:31000
内部: http://minio.storage.svc.cluster.local:9000

# 默认凭据
Access Key: minioadmin
Secret Key: minioadmin123
```

### 已创建的 Buckets

1. **test-reports/** - 测试报告存储
   - HTML 测试报告
   - 覆盖率报告
   - 截图和附件
   - **访问策略**: 公开读取（方便查看报告）

2. **artifacts/** - 构建产物存储
   - 编译后的二进制文件
   - 打包文件（tar.gz, zip）
   - Docker 镜像导出
   - **访问策略**: 公开读取

3. **cache/** - CI/CD 缓存
   - 依赖包缓存（node_modules, pip packages）
   - 构建缓存
   - **访问策略**: 私有（默认）

## 🚀 快速验证

### 1. 运行验证脚本

```bash
cd /Users/brunogao/work/codes/tools/macos/k8s
./verify-minio.sh
```

**预期输出**：
```
✅ MinIO 部署验证完成！
✓ Namespace 'storage' 存在
✓ MinIO Pod 运行正常
✓ PVC 已绑定
✓ Bucket 'test-reports' 存在
✓ Bucket 'artifacts' 存在
✓ Bucket 'cache' 存在
✓ 文件上传/下载测试成功
```

### 2. 访问 MinIO Console

```bash
# 浏览器访问
open http://localhost:31001

# 登录后可以看到：
# - 3 个 buckets
# - 存储使用情况
# - 文件浏览器
```

### 3. 测试上传文件

#### 方式 1: MinIO Console（Web）

1. 访问 http://localhost:31001
2. 登录（minioadmin / minioadmin123）
3. 点击 `test-reports` bucket
4. 点击 "Upload" 按钮
5. 选择文件上传

#### 方式 2: MinIO Client (mc)

```bash
# 安装 mc（如果还没安装）
brew install minio/stable/mc

# 配置别名
mc alias set myminio http://localhost:31000 minioadmin minioadmin123

# 测试上传
echo "Hello MinIO!" > test.txt
mc cp test.txt myminio/test-reports/

# 查看文件
mc ls myminio/test-reports/

# 下载文件
mc cp myminio/test-reports/test.txt ./downloaded.txt

# 生成分享链接（7天有效）
mc share download myminio/test-reports/test.txt --expire=7d
```

## 🔌 Gitea Runner 集成

### 快速示例

将以下内容保存为 `.gitea/workflows/test.yaml`：

```yaml
name: Test and Upload Report

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run tests
        run: npm test -- --coverage --coverageReporters=html

      - name: Upload to MinIO
        run: |
          wget https://dl.min.io/client/mc/release/linux-amd64/mc
          chmod +x mc && sudo mv mc /usr/local/bin/

          mc alias set myminio http://minio.storage.svc.cluster.local:9000 \
            minioadmin minioadmin123

          REPORT_PATH="test-reports/${{ github.repository }}/${{ github.sha }}/$(date +%Y%m%d-%H%M%S)"
          mc cp --recursive coverage/ myminio/${REPORT_PATH}/coverage/

          echo "📊 Report: http://localhost:31000/${REPORT_PATH}/coverage/index.html"
```

### 完整示例

参考文件：`gitea-workflow-example.yaml`

包含：
- ✅ 多语言支持（Node.js / Python / Java）
- ✅ 自动生成索引页面
- ✅ PR 评论集成
- ✅ 构建产物上传
- ✅ 旧报告自动清理

## 📁 文件清单

```
k8s/
├── minio-deployment.yaml              # MinIO 部署配置
├── MINIO-README.md                    # 详细使用指南
├── MINIO-DEPLOYMENT-SUMMARY.md        # 本文件
├── verify-minio.sh                    # 验证脚本
└── gitea-workflow-example.yaml        # Workflow 示例
```

## 🛠️ 常用命令

### 管理命令

```bash
# 查看 MinIO 状态
kubectl get pods -n storage
kubectl get svc -n storage
kubectl get pvc -n storage

# 查看日志
kubectl logs -n storage deployment/minio --tail=50

# 重启 MinIO
kubectl rollout restart deployment minio -n storage

# 进入 MinIO pod
kubectl exec -it -n storage deployment/minio -- sh
```

### MinIO Client 命令

```bash
# 列出 buckets
mc ls myminio

# 列出 bucket 内容
mc ls myminio/test-reports

# 递归列出
mc ls --recursive myminio/test-reports

# 上传文件
mc cp report.html myminio/test-reports/
mc cp --recursive ./coverage/ myminio/test-reports/coverage/

# 下载文件
mc cp myminio/test-reports/report.html ./

# 删除文件
mc rm myminio/test-reports/report.html
mc rm --recursive myminio/test-reports/old-reports/

# 查看存储使用情况
mc du myminio/test-reports

# 生成分享链接
mc share download myminio/test-reports/report.html --expire=7d

# 设置 bucket 策略（公开读取）
mc anonymous set download myminio/test-reports

# 查看 bucket 策略
mc anonymous list myminio/test-reports
```

## 📈 查看报告

### 报告 URL 格式

```
http://localhost:31000/test-reports/<repo>/<branch>/<commit>/<timestamp>/
```

**示例**：
```
http://localhost:31000/test-reports/my-project/main/a1b2c3d/20251216-083000/
├── index.html              # 索引页面
├── coverage/
│   └── index.html          # 覆盖率报告
└── report.html             # 测试报告
```

### 在 Gitea Actions 中显示链接

```yaml
- name: Upload and show links
  run: |
    REPORT_URL="http://localhost:31000/test-reports/..."
    echo "📊 Test Report: $REPORT_URL"

    # 如果是 PR，可以添加评论
    # （需要 Gitea 支持相应的 action）
```

## 🔒 安全建议

### 1. 修改默认密码（生产环境必须）

```bash
# 方法 1: 通过 MinIO Console
# 访问 http://localhost:31001
# Account → Change Password

# 方法 2: 通过 kubectl
kubectl edit secret minio-credentials -n storage
# 修改 root-password 字段（需要 base64 编码）
```

### 2. 创建应用专用访问密钥

在 MinIO Console 中：
1. **Access Keys** → **Create Access Key**
2. 记录 **Access Key** 和 **Secret Key**
3. 在 Gitea 中配置为 Secret

### 3. 配置 Gitea Secrets

在 Gitea 仓库设置中：
```
Settings → Secrets → Actions

MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
MINIO_ACCESS_KEY: <your-access-key>
MINIO_SECRET_KEY: <your-secret-key>
```

Workflow 中使用：
```yaml
env:
  MINIO_ENDPOINT: ${{ secrets.MINIO_ENDPOINT }}
  MINIO_ACCESS_KEY: ${{ secrets.MINIO_ACCESS_KEY }}
  MINIO_SECRET_KEY: ${{ secrets.MINIO_SECRET_KEY }}
```

## 🧹 维护任务

### 定期清理旧报告

```bash
# 手动清理 30 天前的报告
mc rm --recursive --older-than 30d myminio/test-reports/

# 或在 Gitea Workflow 中自动清理
# 参考 gitea-workflow-example.yaml
```

### 设置生命周期规则（自动清理）

```bash
# 30 天后自动删除
mc ilm add myminio/test-reports --expiry-days 30

# 查看规则
mc ilm ls myminio/test-reports
```

### 监控存储使用

```bash
# 查看总使用量
mc du myminio

# 查看各 bucket 使用量
mc du myminio/test-reports
mc du myminio/artifacts
mc du myminio/cache

# 查看 PVC 使用情况
kubectl get pvc -n storage
```

### 扩容存储（如需要）

```bash
# 检查 StorageClass 是否支持扩容
kubectl get storageclass

# 扩容 PVC（20GB → 50GB）
kubectl patch pvc minio-storage -n storage \
  -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

# 验证
kubectl get pvc -n storage
```

## 🐛 故障排查

### MinIO 无法访问

```bash
# 检查 pod 状态
kubectl get pods -n storage

# 查看日志
kubectl logs -n storage deployment/minio --tail=100

# 检查服务
kubectl get svc -n storage

# 重启 MinIO
kubectl rollout restart deployment minio -n storage
```

### 无法上传文件

```bash
# 测试连接
mc ping myminio

# 检查权限
mc ls myminio/test-reports
mc policy get myminio/test-reports

# 查看错误日志
kubectl logs -n storage deployment/minio | grep -i error
```

### 空间不足

```bash
# 查看 PVC 使用情况
kubectl get pvc -n storage
kubectl describe pvc minio-storage -n storage

# 扩容（见上面"扩容存储"部分）
```

## 📚 相关文档

- **详细使用指南**: [MINIO-README.md](./MINIO-README.md)
- **Workflow 示例**: [gitea-workflow-example.yaml](./gitea-workflow-example.yaml)
- **MinIO 官方文档**: https://min.io/docs/minio/kubernetes/upstream/
- **MinIO Client 文档**: https://min.io/docs/minio/linux/reference/minio-mc.html

## 🎯 下一步

1. ✅ 访问 MinIO Console (http://localhost:31001)
2. ✅ 创建测试 Gitea Repository
3. ✅ 添加 `.gitea/workflows/test.yaml`（使用 gitea-workflow-example.yaml）
4. ✅ 推送代码触发 workflow
5. ✅ 查看测试报告上传到 MinIO
6. ✅ 在浏览器中查看报告

---

**部署日期**: 2025-12-16
**MinIO 版本**: latest
**存储容量**: 20GB
**状态**: ✅ 生产就绪
**Namespace**: storage