labweb/supabase-stack/docs/STORAGE_FILE_BACKEND_MIGRATION.md

# Storage 后端迁移：从 MinIO (S3) 到文件系统

**日期**: 2025-12-05  
**状态**: ✅ 完成（部分功能限制）

## 迁移概述

将 Supabase Storage 从 MinIO (S3 兼容对象存储) 迁移到文件系统后端。

## 变更内容

### 1. docker-compose.yml 修改

**修改前** (S3 后端):
```yaml
storage:
  environment:
    STORAGE_BACKEND: s3
    GLOBAL_S3_BUCKET: ${GLOBAL_S3_BUCKET}
    GLOBAL_S3_ENDPOINT: ${GLOBAL_S3_ENDPOINT}
    GLOBAL_S3_PROTOCOL: ${GLOBAL_S3_PROTOCOL}
    GLOBAL_S3_FORCE_PATH_STYLE: ${GLOBAL_S3_FORCE_PATH_STYLE}
```

**修改后** (文件后端):
```yaml
storage:
  environment:
    STORAGE_BACKEND: file
    FILE_STORAGE_BACKEND_PATH: /var/lib/storage
    # GLOBAL_S3_BUCKET: ${GLOBAL_S3_BUCKET}  # 已注释
    # GLOBAL_S3_ENDPOINT: ${GLOBAL_S3_ENDPOINT}  # 已注释
    # GLOBAL_S3_PROTOCOL: ${GLOBAL_S3_PROTOCOL}  # 已注释
    # GLOBAL_S3_FORCE_PATH_STYLE: ${GLOBAL_S3_FORCE_PATH_STYLE}  # 已注释
```

### 2. MinIO 服务停用

```bash
# 停止 MinIO 容器
docker compose -f docker-compose.s3.yml down

# MinIO 不再启动（docker-compose.s3.yml 不再使用）
```

### 3. 文件存储目录

**存储路径**:
```
volumes/storage/undefined/stub/{bucket-name}/{file-name}/{version-id}
```

**示例**:
```
volumes/storage/undefined/stub/test-file-backend/hello.txt/59a6c5e4-fe40-4414-8f42-619cd0792619
```

**注意**: 路径中的 `undefined` 是文件后端的固定目录结构，不是错误。

## 测试结果

### ✅ 正常功能 (4/5)

| 功能 | 状态 | 说明 |
|------|------|------|
| 列出 Buckets | ✅ | 完全正常 |
| 上传文件 | ✅ | 完全正常 |
| 下载文件 | ✅ | 公共和认证访问都正常 |
| 删除文件 | ✅ | 完全正常 |
| **更新文件** | ❌ | **500 错误** |

### ❌ 已知问题

#### 1. 文件更新失败

**错误**:
```
PUT /storage/v1/object/{bucket}/{file}
Status: 500 Internal Server Error
```

**原因**: Supabase Storage 文件后端的已知 bug，更新文件时尝试删除旧版本时路径解析错误。

**临时方案**: 先删除再上传
```python
# 删除旧文件
requests.delete(f'{BASE_URL}/storage/v1/object/{bucket}/{file}', headers=headers)

# 上传新文件
requests.post(f'{BASE_URL}/storage/v1/object/{bucket}/{file}', headers=headers, data=new_data)
```

#### 2. S3 后端数据不兼容

- 之前 MinIO (S3) 后端创建的 buckets 中的文件无法访问
- 文件元数据存储格式不同
- **需要重新上传**旧文件到新 bucket

## 使用示例

### Python

```python
import requests

BASE_URL = 'https://amiap.hzau.edu.cn/supa'
API_KEY = 'your_service_role_key'

headers = {
    'apikey': API_KEY,
    'Authorization': f'Bearer {API_KEY}'
}

# 创建 bucket
response = requests.post(
    f'{BASE_URL}/storage/v1/bucket',
    headers=headers,
    json={'name': 'my-bucket', 'public': True}
)

# 上传文件
with open('file.txt', 'rb') as f:
    response = requests.post(
        f'{BASE_URL}/storage/v1/object/my-bucket/file.txt',
        headers={**headers, 'Content-Type': 'text/plain'},
        data=f
    )

# 下载文件（公共 bucket）
response = requests.get(
    f'{BASE_URL}/storage/v1/object/public/my-bucket/file.txt'
)
content = response.content

# 删除文件
response = requests.delete(
    f'{BASE_URL}/storage/v1/object/my-bucket/file.txt',
    headers=headers
)
```

### JavaScript

```javascript
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://amiap.hzau.edu.cn/supa',
  'your_anon_key'
)

// 上传文件
const { data, error } = await supabase.storage
  .from('my-bucket')
  .upload('file.txt', file)

// 下载文件
const { data: fileData } = await supabase.storage
  .from('my-bucket')
  .download('file.txt')

// 删除文件
await supabase.storage
  .from('my-bucket')
  .remove(['file.txt'])
```

## 架构对比

### MinIO (S3) 后端

```
用户 → Supabase Storage API
     → MinIO 容器 (S3协议)
     → /vol1/1000/s3 (对象存储)
```

**优势**:
- ✅ 完整的 S3 API 支持
- ✅ 可以用 MinIO Console 管理
- ✅ 文件更新功能正常
- ✅ 可扩展性好

**劣势**:
- ❌ 需要额外的 MinIO 容器
- ❌ 占用更多资源

### 文件系统后端

```
用户 → Supabase Storage API
     → 本地文件系统
     → volumes/storage/undefined/stub/...
```

**优势**:
- ✅ 简单，无需额外容器
- ✅ 直接访问文件系统
- ✅ 资源占用少

**劣势**:
- ❌ 文件更新功能有bug
- ❌ 无管理界面
- ❌ 扩展性差
- ❌ 与 S3 后端数据不兼容

## 回滚到 MinIO

如需回滚到 MinIO (S3) 后端：

```bash
cd /vol1/1000/docker_server/traefik/supabase-stack

# 1. 恢复配置
cp docker-compose.yml.backup-before-rustfs docker-compose.yml

# 2. 重启 Storage
docker compose stop storage
docker compose rm -f storage
docker compose up -d storage

# 3. 启动 MinIO
docker compose -f docker-compose.s3.yml up -d

# 4. 测试
python3 examples/test_https_storage.py
```

## 备份文件

迁移过程中创建的备份：
- `docker-compose.yml.backup-before-rustfs` - S3 后端配置
- `docker-compose.s3.yml.backup-before-rustfs` - MinIO 配置

## 物理存储位置

### 文件后端
- **路径**: `volumes/storage/undefined/stub/{bucket}/{file}/{version}`
- **格式**: 本地文件系统
- **管理**: 直接文件访问

### MinIO (旧)
- **路径**: `/vol1/1000/s3`
- **格式**: S3 对象存储
- **管理**: MinIO Console (http://100.64.0.2:9001)

## 建议

### 生产环境

**不推荐**使用文件后端，原因：
1. 文件更新功能有已知bug
2. 功能不完整
3. 无管理界面
4. 官方主要支持 S3 后端

**推荐**继续使用 MinIO (S3) 后端。

### 开发/测试环境

可以使用文件后端，注意：
1. 避免文件更新操作（使用删除+上传）
2. 定期备份 volumes/storage 目录
3. 监控存储空间

## 相关文档

- `README.md` - 主文档
- `docs/FINAL_ARCHITECTURE_MINIO_INTERNAL.md` - MinIO 架构说明
- `examples/test_https_storage.py` - Storage API 测试

---

**迁移日期**: 2025-12-05  
**执行人**: 系统管理员  
**状态**: ✅ 完成（功能受限）  
**建议**: 生产环境使用 MinIO