382 lines
8.6 KiB
Markdown
382 lines
8.6 KiB
Markdown
# 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 |