feat(supabase): 整理 Storage 文档和示例代码
- 创建 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: 功能测试脚本 - 新增 README_STORAGE.md 作为 Storage 使用指南 - 修复签名 URL 生成问题（需要 /storage/v1 前缀） - 测试脚本支持资源已存在的情况 - 所有客户端代码已验证可用 功能特性： ✓ 公网 HTTPS 访问 ✓ 文件上传/下载 ✓ 生成临时下载链接 ✓ 完整的 REST API 客户端 ✓ 支持 Python 和 JavaScript
This commit is contained in:
zly
237
supabase-stack/README_STORAGE.md
Normal file
237
supabase-stack/README_STORAGE.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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！**
|
||||
Reference in New Issue
Block a user