# Supabase Storage 对象存储使用指南

完整的 Supabase 对象存储解决方案，支持公网 HTTPS 访问。

---

## 📚 文档导航

### 快速开始
- **[快速入门](docs/QUICK_START.md)** - 5 分钟快速上手指南
- **[运维指南](docs/OPERATIONS_GUIDE.md)** - 完整的系统架构和运维文档

### 集成文档
- **[Vue API 集成](docs/VUE_API_INTEGRATION.md)** - Vue 应用集成指南
- **[部署信息](docs/DEPLOYMENT_INFO.md)** - 部署配置详情

---

## 💻 客户端代码

所有示例代码位于 `examples/` 目录：

### Python 客户端
```bash
# 查看完整客户端代码
cat examples/storage_client.py

# 使用示例
python3 << 'EOF'
import sys
sys.path.insert(0, 'examples')
from storage_client import SupabaseStorageClient

client = SupabaseStorageClient(
    'https://amiap.hzau.edu.cn/supa',
    'your-service-role-key'
)

# 上传文件
client.upload_file('bucket', 'photo.jpg', 'uploads/photo.jpg')

# 生成临时下载链接
url = client.create_signed_url('bucket', 'uploads/photo.jpg', 3600)
print(f'临时下载链接: {url}')
EOF
```

### JavaScript 客户端
```bash
# 查看完整客户端代码
cat examples/storage_client.js

# 在网页中使用
<script src="examples/storage_client.js"></script>
<script>
const client = new SupabaseStorageClient(
    'https://amiap.hzau.edu.cn/supa',
    'your-service-role-key'
);

// 上传文件
await client.uploadFile('bucket', fileObject, 'uploads/photo.jpg');

// 生成临时下载链接
const url = await client.createSignedUrl('bucket', 'uploads/photo.jpg', 3600);
</script>
```

---

## 🧪 测试

运行完整的功能测试：

```bash
# 测试所有 Storage API 功能
python3 examples/test_https_storage.py
```

测试包含：
- ✓ 列出 Buckets
- ✓ 创建 Bucket
- ✓ 上传/更新文件
- ✓ 下载文件
- ✓ 生成签名 URL（临时下载链接）

---

## 🚀 快速开始

### 1. 启动服务

```bash
# 启动 Supabase + MinIO
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
```

### 2. 测试服务

```bash
python3 examples/test_https_storage.py
```

### 3. 使用客户端

**Python**:
```python
from examples.storage_client import SupabaseStorageClient

client = SupabaseStorageClient(
    'https://amiap.hzau.edu.cn/supa',
    'your-api-key'
)
```

**JavaScript**:
```javascript
// 在浏览器中
const client = new SupabaseStorageClient(
    'https://amiap.hzau.edu.cn/supa',
    'your-api-key'
);
```

---

## 🌐 访问端点

- **Storage API**: `https://amiap.hzau.edu.cn/supa/storage/v1`
- **Dashboard**: `http://100.64.0.2:18000` (内网)

---

## 📂 项目结构

```
supabase-stack/
├── docs/                          # 📚 文档
│   ├── QUICK_START.md            # 快速入门
│   ├── OPERATIONS_GUIDE.md       # 运维指南
│   ├── VUE_API_INTEGRATION.md    # Vue 集成
│   ├── DEPLOYMENT_INFO.md        # 部署信息
│   └── versions.md               # 版本信息
│
├── examples/                      # 💻 示例代码
│   ├── storage_client.py         # Python 客户端
│   ├── storage_client.js         # JavaScript 客户端
│   └── test_https_storage.py    # 测试脚本
│
├── docker-compose.yml             # Supabase 核心服务
├── docker-compose.s3.yml          # MinIO 对象存储
├── .env                           # 环境变量配置
│
├── README.md                      # Supabase 原始说明
├── README_STORAGE.md              # Storage 使用指南（本文档）
└── CHANGELOG.md                   # 版本变更记录
```

---

## 🔑 认证密钥

在 `.env` 文件中：

```bash
# 服务密钥（后端使用，完全权限）
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 匿名密钥（前端使用，受权限控制）
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

---

## ⚙️ 服务管理

```bash
# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f storage

# 重启服务
docker compose restart storage

# 停止服务
docker compose stop
```

---

## 🛠️ 故障排查

查看 [运维指南](docs/OPERATIONS_GUIDE.md) 的故障排查章节。

---

## 📝 更多信息

- **完整文档**: 查看 `docs/` 目录
- **代码示例**: 查看 `examples/` 目录
- **原始 README**: [README.md](README.md)

---

## ✅ 功能特性

- ✅ 公网 HTTPS 访问
- ✅ 子路径支持（无需子域名）
- ✅ 文件上传/下载
- ✅ 生成临时下载链接（签名 URL）
- ✅ Bucket 管理
- ✅ 文件列表/移动/复制/删除
- ✅ Python 和 JavaScript 客户端
- ✅ 完整的 REST API

---

## 🎯 使用场景

1. **Web 应用文件上传** - 用户头像、附件等
2. **临时文件分享** - 生成带过期时间的下载链接
3. **静态资源托管** - 图片、视频、文档
4. **移动应用存储** - 跨平台数据同步
5. **数据备份** - 自动化备份脚本

---

## 📞 技术支持

如有问题，请查看：
1. [快速入门](docs/QUICK_START.md) - 基础使用
2. [运维指南](docs/OPERATIONS_GUIDE.md) - 深入了解
3. 测试脚本 - `python3 examples/test_https_storage.py`

🎉 **开始使用 Supabase Storage！**