ljwx-k8s/MINIO-README.md

MinIO 文件服务器部署指南

📋 概述

MinIO 是一个高性能的对象存储服务，与 AWS S3 完全兼容。本部署用于存储 Gitea Runner 的测试报告、构建产物和 CI/CD 缓存。

✅ 部署状态

已部署组件

• ✅ MinIO Server - S3 兼容对象存储服务
• ✅ MinIO Console - Web 管理界面
• ✅ 持久化存储 - 20GB PVC
• ✅ 预创建 Buckets - test-reports, artifacts, cache

访问信息

服务	地址	端口	用途
MinIO Console	http://localhost:31001	31001	Web 管理界面
MinIO API	http://localhost:31000	31000	S3 API 端点
内部 API	http://minio.storage.svc.cluster.local:9000	9000	K8s 内部访问

默认凭据

用户名: minioadmin
密码: minioadmin123

⚠️ 重要: 生产环境请立即修改默认密码！

🚀 快速开始

1. 访问 MinIO Console

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

# 登录
# 用户名: minioadmin
# 密码: minioadmin123

2. 查看已创建的 Buckets

登录后，你应该能看到 3 个 bucket：

• test-reports/ - 存储测试报告（HTML、XML、JSON）
• artifacts/ - 存储构建产物（二进制文件、包）
• cache/ - 存储 CI/CD 缓存（依赖、中间文件）

3. 测试上传文件

使用 MinIO Console（Web 界面）

1. 点击 test-reports bucket
2. 点击 "Upload" 按钮
3. 选择文件并上传
4. 上传后可以直接在浏览器中预览

使用 MinIO Client (mc)

# 安装 mc（macOS）
brew install minio/stable/mc

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

# 列出 buckets
mc ls myminio

# 上传文件
mc cp /path/to/report.html myminio/test-reports/

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

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

使用 AWS CLI（S3 兼容）

# 安装 AWS CLI
brew install awscli

# 配置（交互式）
aws configure

# 或直接使用环境变量
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin123
export AWS_ENDPOINT_URL=http://localhost:31000

# 列出 buckets
aws s3 ls --endpoint-url http://localhost:31000

# 上传文件
aws s3 cp report.html s3://test-reports/ --endpoint-url http://localhost:31000

# 下载文件
aws s3 cp s3://test-reports/report.html . --endpoint-url http://localhost:31000

🔌 Gitea Runner 集成

场景 1: 上传测试报告到 MinIO

在 Gitea Actions workflow 中上传测试报告：

.gitea/workflows/test.yaml

name: Run Tests and Upload Reports

on: [push, pull_request]

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

      - name: Run tests
        run: |
          # 运行测试并生成报告
          npm test -- --coverage --coverageReporters=html
          # 或
          pytest --html=report.html --self-contained-html

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

      - name: Upload test report to MinIO
        env:
          MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
          MINIO_ACCESS_KEY: minioadmin
          MINIO_SECRET_KEY: minioadmin123
        run: |
          # 配置 MinIO
          mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY

          # 创建报告目录（使用 commit SHA 和时间戳）
          REPORT_DIR="${GITHUB_REPOSITORY}/${GITHUB_SHA:0:7}/$(date +%Y%m%d-%H%M%S)"

          # 上传测试报告
          mc cp --recursive coverage/ myminio/test-reports/$REPORT_DIR/coverage/
          mc cp report.html myminio/test-reports/$REPORT_DIR/

          # 生成可访问的 URL
          echo "📊 Test Report: http://localhost:31000/test-reports/$REPORT_DIR/report.html"
          echo "📈 Coverage Report: http://localhost:31000/test-reports/$REPORT_DIR/coverage/index.html"

      - name: Comment PR with report links
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const reportUrl = `http://localhost:31000/test-reports/${context.repo.repo}/${context.sha.substring(0,7)}/${new Date().toISOString().split('T')[0]}/report.html`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `📊 Test report is available at: ${reportUrl}`
            });

场景 2: 缓存依赖到 MinIO

使用 MinIO 缓存 npm/pip/maven 依赖：

.gitea/workflows/build-with-cache.yaml

name: Build with MinIO Cache

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

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

      - name: Restore cache from MinIO
        env:
          MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
          MINIO_ACCESS_KEY: minioadmin
          MINIO_SECRET_KEY: minioadmin123
        run: |
          mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY

          # 下载缓存（如果存在）
          CACHE_KEY="node_modules-$(sha256sum package-lock.json | cut -d' ' -f1)"
          mc cp --recursive myminio/cache/$CACHE_KEY/ ./ || echo "Cache miss"

      - name: Install dependencies
        run: |
          if [ ! -d "node_modules" ]; then
            npm ci
          fi

      - name: Build project
        run: npm run build

      - name: Save cache to MinIO
        if: success()
        env:
          MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
          MINIO_ACCESS_KEY: minioadmin
          MINIO_SECRET_KEY: minioadmin123
        run: |
          mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY

          CACHE_KEY="node_modules-$(sha256sum package-lock.json | cut -d' ' -f1)"
          mc cp --recursive node_modules/ myminio/cache/$CACHE_KEY/

      - name: Upload build artifacts
        env:
          MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
          MINIO_ACCESS_KEY: minioadmin
          MINIO_SECRET_KEY: minioadmin123
        run: |
          mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY

          ARTIFACT_DIR="${GITHUB_REPOSITORY}/${GITHUB_SHA:0:7}"
          mc cp --recursive dist/ myminio/artifacts/$ARTIFACT_DIR/

场景 3: Python + Pytest HTML 报告

name: Python Tests with HTML Report

on: [push]

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

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install pytest pytest-html pytest-cov

      - name: Run tests
        run: |
          pytest --html=report.html --self-contained-html \
                 --cov=. --cov-report=html

      - name: Upload reports to MinIO
        env:
          MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
          MINIO_ACCESS_KEY: minioadmin
          MINIO_SECRET_KEY: minioadmin123
        run: |
          # 安装 mc
          wget https://dl.min.io/client/mc/release/linux-amd64/mc
          chmod +x mc
          sudo mv mc /usr/local/bin/

          # 配置并上传
          mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY

          REPORT_PATH="test-reports/$GITHUB_REPOSITORY/$GITHUB_SHA/$(date +%Y%m%d-%H%M%S)"
          mc cp report.html myminio/$REPORT_PATH/
          mc cp --recursive htmlcov/ myminio/$REPORT_PATH/coverage/

          echo "✅ Report uploaded to: http://localhost:31000/$REPORT_PATH/report.html"

🔒 安全配置

修改默认密码

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

# 使用 mc 修改密码
mc admin user add myminio newuser newpassword123

# 创建只读用户（用于查看报告）
mc admin user add myminio readonly readonly123

# 设置策略
mc admin policy attach myminio readonly --user readonly

创建应用专用凭据

在 MinIO Console 中：

1. 进入 Access Keys 菜单
2. 点击 Create Access Key
3. 输入名称（如 gitea-runner）
4. 选择权限（如 readwrite）
5. 复制 Access Key 和 Secret Key
6. 在 Gitea 中配置为 Secret

在 Gitea 中配置 MinIO Secrets

在 Gitea 仓库设置中添加 Secrets：

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 中使用：

- name: Upload to MinIO
  env:
    MINIO_ENDPOINT: ${{ secrets.MINIO_ENDPOINT }}
    MINIO_ACCESS_KEY: ${{ secrets.MINIO_ACCESS_KEY }}
    MINIO_SECRET_KEY: ${{ secrets.MINIO_SECRET_KEY }}
  run: |
    mc alias set myminio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY
    mc cp report.html myminio/test-reports/

📊 查看报告

方式 1: 直接浏览器访问

# 报告 URL 格式
http://localhost:31000/test-reports/<repo>/<commit>/<timestamp>/report.html

# 示例
http://localhost:31000/test-reports/my-project/a1b2c3d/20251216-083000/report.html

方式 2: MinIO Console

1. 访问 http://localhost:31001
2. 登录后点击 test-reports bucket
3. 浏览文件夹并点击 HTML 文件查看

方式 3: 生成预签名 URL（临时链接）

# 使用 mc 生成 7 天有效的分享链接
mc share download myminio/test-reports/report.html --expire=7d

# 输出示例
# URL: http://localhost:31000/test-reports/report.html?X-Amz-...
# Expires: 7 days

🛠️ 维护和管理

查看存储使用情况

# 在 MinIO Console 中查看（推荐）
# Monitoring → Usage

# 或使用 mc
mc du myminio/test-reports
mc du myminio/artifacts
mc du myminio/cache

清理旧报告

# 删除 30 天前的报告
mc rm --recursive --older-than 30d myminio/test-reports/

# 删除特定目录
mc rm --recursive myminio/test-reports/my-project/old-branch/

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

在 MinIO Console 中：

1. 进入 test-reports bucket
2. 点击 Lifecycle 标签
3. 添加规则：
   • 名称：auto-cleanup
   • 前缀：*/ （所有文件）
   • 过期天数：30

或使用 mc：

# 创建生命周期规则（30 天后自动删除）
mc ilm add myminio/test-reports --expiry-days 30

# 查看生命周期规则
mc ilm ls myminio/test-reports

备份 MinIO 数据

# 备份整个 bucket
mc mirror myminio/test-reports ./backup/test-reports/

# 恢复
mc mirror ./backup/test-reports/ myminio/test-reports/

🔧 故障排查

MinIO 无法访问

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

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

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

无法上传文件

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

# 测试连接
mc ping myminio

空间不足

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

# 扩容（如果 StorageClass 支持）
kubectl patch pvc minio-storage -n storage \
  -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

📚 参考资源

• MinIO 官方文档
• MinIO Client (mc) 文档
• AWS S3 API 兼容性

🎯 最佳实践

1. 报告命名规范

test-reports/
  ├── <repo-name>/
  │   ├── <branch-name>/
  │   │   ├── <commit-sha>/
  │   │   │   ├── <timestamp>/
  │   │   │   │   ├── report.html
  │   │   │   │   ├── coverage/
  │   │   │   │   └── screenshots/

2. 使用环境变量

env:
  MINIO_ENDPOINT: http://minio.storage.svc.cluster.local:9000
  MINIO_BUCKET: test-reports
  REPORT_PREFIX: ${GITHUB_REPOSITORY}/${GITHUB_REF_NAME}/${GITHUB_SHA}

3. 添加报告元数据

# 上传时添加元数据
mc cp report.html myminio/test-reports/report.html \
  --attr "commit=$GITHUB_SHA;branch=$GITHUB_REF_NAME;build=$GITHUB_RUN_ID"

# 查看元数据
mc stat myminio/test-reports/report.html

4. 生成索引页面

创建一个 index.html 列出所有报告：

cat > index.html <<EOF
<!DOCTYPE html>
<html>
<head>
    <title>Test Reports - ${GITHUB_REPOSITORY}</title>
</head>
<body>
    <h1>Test Reports</h1>
    <ul>
        <li><a href="./report.html">Latest Test Report</a></li>
        <li><a href="./coverage/index.html">Coverage Report</a></li>
    </ul>
    <p>Build: ${GITHUB_SHA} | Date: $(date)</p>
</body>
</html>
EOF

mc cp index.html myminio/test-reports/$REPORT_PREFIX/

---

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