9fa602f21b
- 创建 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
238 lines
5.1 KiB
Markdown
238 lines
5.1 KiB
Markdown
# 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！**
|