labweb/supabase-stack/README_STORAGE.md

Supabase Storage 对象存储使用指南

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

---

📚 文档导航

快速开始

• 快速入门 - 5 分钟快速上手指南
• 运维指南 - 完整的系统架构和运维文档

集成文档

• Vue API 集成 - Vue 应用集成指南
• 部署信息 - 部署配置详情

---

💻 客户端代码

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

Python 客户端

# 查看完整客户端代码
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 客户端

# 查看完整客户端代码
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>

---

🧪 测试

运行完整的功能测试：

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

测试包含：

• ✓ 列出 Buckets
• ✓ 创建 Bucket
• ✓ 上传/更新文件
• ✓ 下载文件
• ✓ 生成签名 URL（临时下载链接）

---

🚀 快速开始

1. 启动服务

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

2. 测试服务

python3 examples/test_https_storage.py

3. 使用客户端

Python:

from examples.storage_client import SupabaseStorageClient

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

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 文件中：

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

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

---

⚙️ 服务管理

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f storage

# 重启服务
docker compose restart storage

# 停止服务
docker compose stop

---

🛠️ 故障排查

查看 运维指南 的故障排查章节。

---

📝 更多信息

• 完整文档: 查看 docs/ 目录
• 代码示例: 查看 examples/ 目录
• 原始 README: README.md

---

✅ 功能特性

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

---

🎯 使用场景

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

---

📞 技术支持

如有问题，请查看：

1. 快速入门 - 基础使用
2. 运维指南 - 深入了解
3. 测试脚本 - python3 examples/test_https_storage.py

🎉 开始使用 Supabase Storage！