# MinIO Integration Guide for MarkBase

**Date**: 2026-06-25
**Status**: Ready for deployment
**Backend**: S3Vfs (已有实现，无需修改代码)

---

## Executive Summary

MinIO 是高性能、S3-compatible 的对象存储服务，完美契合 MarkBase 的定位：
- ✅ 跨平台支持（macOS/Linux/Windows）
- ✅ 轻量级部署（单节点即可）
- ✅ 已有 S3Vfs 支持（无需修改代码）
- ✅ 高性能（纠删码 + 分布式扩展）

---

## MinIO vs Ceph RADOS Comparison

| Aspect | MinIO | Ceph RADOS |
|--------|-------|------------|
| **Platform** | ✅ 全平台 | ❌ Linux-only |
| **Deployment** | ⚠️⚠️ 单节点即可 | ⚠️⚠️⚠️⚠️⚠️ 需完整集群 |
| **API** | ✅ S3-compatible HTTP | ❌ librados FFI |
| **Code change** | ✅ 0 行（已有 S3Vfs） | ❌ ~1350 行 |
| **Positioning** | ⭐⭐⭐⭐⭐ 完全匹配 | ❌ 不符合 Lightweight 定位 |

---

## MinIO Deployment

### macOS 单节点部署

```bash
# 安装 MinIO
brew install minio/stable/minio

# 启动 MinIO server
minio server /path/to/data --console-address ":9001"

# 输出：
# Endpoint:  http://192.168.1.100:9000  http://127.0.0.1:9000
# Console:   http://192.168.1.100:9001  http://127.0.0.1:9001
# AccessKey: minioadmin
# SecretKey: minioadmin
```

### Linux 生产部署

```bash
# Docker 单节点
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v /data/minio:/data \
  minio/minio server /data --console-address ":9001"

# 分布式集群（4节点）
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v /data1:/data1 \
  -v /data2:/data2 \
  minio/minio server http://node1/data1 http://node2/data2 http://node3/data1 http://node4/data2 --console-address ":9001"
```

### Kubernetes 部署（推荐生产）

```yaml
# minio-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minio
spec:
  replicas: 4
  selector:
    matchLabels:
      app: minio
  template:
    metadata:
      labels:
        app: minio
    spec:
      containers:
      - name: minio
        image: minio/minio:latest
        args:
        - server
        - http://minio-0/data http://minio-1/data http://minio-2/data http://minio-3/data
        - --console-address
        - ":9001"
        ports:
        - containerPort: 9000
        - containerPort: 9001
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        emptyDir: {}
```

---

## MarkBase S3Vfs Integration

### 配置方式

**环境变量**：
```bash
export MB_S3_ENDPOINT=http://localhost:9000
export MB_S3_REGION=us-east-1
export MB_S3_BUCKET=markbase
export MB_S3_ACCESS_KEY=minioadmin
export MB_S3_SECRET_KEY=minioadmin
```

**配置文件**（`config/s3.toml`）：
```toml
[s3]
enabled = true
endpoint = "http://localhost:9000"
region = "us-east-1"
bucket = "markbase"
access_key = "minioadmin"
secret_key = "minioadmin"

[s3.webdav]
# WebDAV 使用 S3 后端
enabled = true
user = "demo"
root_prefix = "webdav/"
```

### S3Vfs 使用示例

**WebDAV + MinIO**：
```bash
# 启动 WebDAV server（使用 MinIO 后端）
cargo run -- webdav-start \
  --user demo \
  --port 8002 \
  --s3 \
  --s3-endpoint http://localhost:9000 \
  --s3-bucket markbase \
  --s3-access-key minioadmin \
  --s3-secret-key minioadmin \
  --s3-region us-east-1 \
  --root webdav/
```

**SMB + MinIO**（通过 VFS backend）：
```bash
# 启动 SMB server（使用 MinIO 后端）
cargo run --features smb-server -- smb-start \
  --port 4445 \
  --share-name files \
  --s3 \
  --s3-endpoint http://localhost:9000 \
  --s3-bucket markbase \
  --s3-access-key minioadmin \
  --s3-secret-key minioadmin \
  --s3-region us-east-1 \
  --root smb/
```

---

## MinIO Bucket Management

### 创建 Bucket

```bash
# 使用 MinIO client (mc)
mc alias set myminio http://localhost:9000 minioadmin minioadmin
mc mb myminio/markbase

# 使用 AWS CLI
aws --endpoint-url http://localhost:9000 s3 mb s3://markbase
```

### 设置 Bucket Policy

```bash
# 公开读取 policy（用于 public shares）
mc anonymous set download myminio/markbase/public

# 私有 policy（默认）
mc anonymous set none myminio/markbase/private
```

### 设置 Bucket Quota

```bash
# 设置 quota（MinIO 企业版功能）
mc admin bucket quota myminio/markbase 10GB
```

---

## MinIO Features Relevant to MarkBase

| Feature | Description | MarkBase Use Case |
|---------|-------------|-------------------|
| **Erasure Coding** | 数据冗余（默认 EC:2） | 自动容错，类似 RAID |
| **Versioning** | 对象版本控制 | 可替代 Snapshot 功能 |
| **Bucket Policy** | ACL 管理 | 用户权限控制 |
| **Lifecycle Rules** | 自动过期 | 旧 backup 清理 |
| **Object Lock** | WORM 模式 | 合规性备份保护 |
| **Replication** | 跨站点复制 | Disaster recovery |

### Versioning（替代 Snapshot）

```bash
# 启用 versioning
mc version enable myminio/markbase

# 列出对象版本
mc ls --versions myminio/markbase/file.txt

# 恢复旧版本
mc cp myminio/markbase/file.txt#version-id myminio/markbase/file.txt
```

### Lifecycle Rules（Backup 清理）

```bash
# 设置 30 天后自动删除
mc ilm add myminio/markbase --expire-days 30
```

---

## Performance Optimization

### MinIO 性能参数

```bash
# 高性能配置
minio server /data \
  --console-address ":9001" \
  --parallel 8 \
  --cache /cache:1000
```

### S3Vfs 性能优化

**并发上传**（已在 S3Vfs 实现）：
- Multipart upload（大于 5MB 自动分片）
- 并发上传分片（默认 4 并发）

**缓存**：
- ReadCache: 64MB, 64KB blocks, 5min TTL（已在 cache.rs 实现）
- WriteCache: 32MB（已在 cache.rs 实现）

---

## Docker Compose Example

```yaml
version: '3'
services:
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio-data:/data
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin

  markbase-webdav:
    build: .
    command: webdav-start --user demo --port 8002 --s3 --s3-endpoint http://minio:9000 --s3-bucket markbase --s3-access-key minioadmin --s3-secret-key minioadmin
    ports:
      - "8002:8002"
    environment:
      - MB_S3_ENDPOINT=http://minio:9000
    depends_on:
      - minio

volumes:
  minio-data:
```

---

## Integration Checklist

| Task | Status | Notes |
|------|--------|-------|
| **MinIO 部署** | ⏳ User action | macOS/Linux/Docker |
| **创建 Bucket** | ⏳ User action | `mc mb myminio/markbase` |
| **S3Vfs 配置** | ✅ 已支持 | 无需修改代码 |
| **WebDAV + S3** | ✅ 已支持 | CLI 参数已实现 |
| **SMB + S3** | ✅ 已支持 | CLI 参数已实现 |
| **SFTP + S3** | ⏳ 待实现 | 需要 SFTP S3 backend |
| **Backup to S3** | ✅ 已支持 | BackupManifest + S3Vfs |

---

## Troubleshooting

### MinIO 连接问题

```bash
# 检查 MinIO status
mc admin info myminio

# 检查 endpoint 连接
curl -I http://localhost:9000/minio/health/live
```

### S3Vfs 错误

**常见错误**：
- `VfsError::NotFound` → Bucket 或 object 不存在
- `VfsError::PermissionDenied` → Access key/secret key 错误
- `VfsError::Io("S3 PUT failed: 403")` → Bucket policy 拒绝写入

**调试方法**：
```bash
# 查看 MinIO logs
docker logs minio

# 使用 mc 测试
mc cp test.txt myminio/markbase/test.txt
mc ls myminio/markbase/
```

---

## MinIO vs S3Vfs Feature Mapping

| VfsBackend Method | MinIO S3 API | Status |
|-------------------|--------------|--------|
| `read_dir()` | ListObjectsV2 | ✅ |
| `open_file()` | GetObject / PutObject | ✅ |
| `stat()` | HeadObject | ✅ |
| `create_dir()` | PutObject (0-byte) | ✅ |
| `remove_dir()` | DeleteObject | ✅ |
| `remove_file()` | DeleteObject | ✅ |
| `rename()` | CopyObject + DeleteObject | ✅ |
| `exists()` | HeadObject | ✅ |
| `copy()` | CopyObject | ✅ |
| `hard_link()` | CopyObject | ✅ |
| `create_snapshot()` | Versioning | ⚠️ 需启用 versioning |
| `list_snapshots()` | ListObjectVersions | ⚠️ 需实现 |
| `set_quota()` | Bucket quota | ⚠️ MinIO 企业版 |
| `set_acl()` | Bucket policy | ⚠️ 需实现 |

---

## Next Steps

1. **部署 MinIO**（用户 action）
   - macOS: `brew install minio && minio server /data`
   - Docker: `docker run minio/minio server /data`

2. **创建 Bucket**（用户 action）
   - `mc alias set myminio http://localhost:9000 minioadmin minioadmin`
   - `mc mb myminio/markbase`

3. **配置 MarkBase**
   - 设置 `MB_S3_*` 环境变量
   - 或使用 CLI 参数 `--s3 --s3-endpoint ...`

4. **测试连接**
   - WebDAV: `curl -X PROPFIND http://localhost:8002/webdav/`
   - SMB: `smbclient -p 4445 -L localhost`

---

**文档创建**: 2026-06-25
**最后更新**: 2026-06-25