feat: 迁移 Storage 后端从 MinIO 到文件系统
## 主要变更
### 1. Storage 配置修改
- 修改 docker-compose.yml: STORAGE_BACKEND 从 s3 改为 file
- 注释所有 GLOBAL_S3_* 环境变量
- 启用 FILE_STORAGE_BACKEND_PATH=/var/lib/storage
- 停止使用 MinIO 容器（docker-compose.s3.yml）
### 2. 文档更新
- 新增 docs/STORAGE_FILE_BACKEND_MIGRATION.md - 迁移详细文档
- 新增 docs/STORAGE_TROUBLESHOOTING.md - 故障排查指南
- 更新 README.md - 反映新的架构
### 3. 存储架构变更
- 从 MinIO S3 对象存储 -> 本地文件系统
- 存储路径: volumes/storage/undefined/stub/{bucket}/{file}/{version}
- 不再需要额外的 MinIO 容器
## 测试结果
- ✅ 上传文件 - 正常
- ✅ 下载文件 - 正常
- ✅ 删除文件 - 正常
- ✅ 签名 URL - 正常
- ⚠️ 更新文件 - 已知bug（使用删除+上传代替）
## 注意事项
- 旧的 S3 后端数据需要清理数据库元数据
- 文件更新操作有已知bug，需使用删除+重新上传
- 备份文件保存在 *.backup-before-rustfs
## 回滚方法
如需回滚到 MinIO:
```bash
cp docker-compose.yml.backup-before-rustfs docker-compose.yml
docker compose -f docker-compose.s3.yml up -d
docker compose restart storage
```
日期: 2025-12-05
状态: ✅ 测试通过 (4/5 功能正常)
This commit is contained in:
zly
426
supabase-stack/docs/README_CN.md
Normal file
426
supabase-stack/docs/README_CN.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# Supabase 部署完成 ✅
|
||||
|
||||
恭喜！Supabase 后端已成功部署在 `https://amiap.hzau.edu.cn/supa`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 服务启动
|
||||
|
||||
### 完整启动命令
|
||||
|
||||
Supabase 服务包含**核心服务**和 **S3 对象存储**两部分，使用 Docker Compose 的 override 功能同时启动：
|
||||
|
||||
```bash
|
||||
# 进入目录
|
||||
cd /vol1/1000/docker_server/traefik/supabase-stack
|
||||
|
||||
# 🔥 推荐：使用 override 方式启动（同时启动核心服务 + S3）
|
||||
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
|
||||
|
||||
# 查看服务状态
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
### 服务组成说明
|
||||
|
||||
#### 核心服务（docker-compose.yml）
|
||||
- **PostgreSQL**: 数据库
|
||||
- **Kong**: API 网关
|
||||
- **REST API**: PostgREST 自动 API
|
||||
- **Auth**: 用户认证
|
||||
- **Storage**: 文件存储
|
||||
- **Realtime**: 实时订阅
|
||||
- **Studio**: 管理面板
|
||||
- **Analytics**: 数据分析
|
||||
- **Pooler**: 连接池（可选，见下方说明）
|
||||
|
||||
#### S3 对象存储（docker-compose.s3.yml）
|
||||
- **MinIO**: S3 兼容的对象存储后端
|
||||
- 为 Storage API 提供文件存储能力
|
||||
- 数据持久化到 `/vol1/1000/s3/stub/`
|
||||
|
||||
### 启动流程
|
||||
|
||||
```bash
|
||||
# 1. 确保 Traefik 已启动
|
||||
cd /vol1/1000/docker_server/traefik
|
||||
docker compose ps traefik
|
||||
|
||||
# 2. 启动 Supabase（核心 + S3）
|
||||
cd supabase-stack
|
||||
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
|
||||
|
||||
# 3. 等待服务就绪（约 30-60 秒）
|
||||
watch -n 2 'docker compose ps'
|
||||
|
||||
# 4. 验证服务
|
||||
curl -s https://amiap.hzau.edu.cn/supa/rest/v1/ | jq
|
||||
python3 examples/test_https_storage.py
|
||||
```
|
||||
|
||||
### 快速管理命令
|
||||
|
||||
```bash
|
||||
# 查看所有服务状态
|
||||
docker compose ps
|
||||
|
||||
# 查看特定服务日志
|
||||
docker compose logs -f kong
|
||||
docker compose logs -f storage
|
||||
docker compose logs -f rest
|
||||
|
||||
# 重启服务
|
||||
docker compose restart
|
||||
|
||||
# 停止服务（保留数据）
|
||||
docker compose down
|
||||
|
||||
# 完全清理（删除所有数据，慎用！）
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 快速开始
|
||||
|
||||
### 访问地址
|
||||
|
||||
**API 端点（用于开发）**
|
||||
```
|
||||
https://amiap.hzau.edu.cn/supa
|
||||
```
|
||||
|
||||
**Dashboard（管理界面）**
|
||||
```
|
||||
http://100.64.0.2:18000
|
||||
用户名: lab-admin
|
||||
密码: 017b7076cfb25bd18410d1e5f4f7ec5a
|
||||
```
|
||||
|
||||
### API Keys
|
||||
|
||||
```javascript
|
||||
// 公开密钥 - 可在前端使用
|
||||
const ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzYzODAyNjY5LCJleHAiOjIwNzkxNjI2Njl9.ltGXvQKpguLaf8Vzomn310hLgOZbrjqZT-F3rR00ulg"
|
||||
|
||||
// 私密密钥 - 仅后端使用
|
||||
const SERVICE_ROLE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaXNzIjoic3VwYWJhc2UiLCJpYXQiOjE3NjM4MDI2NjksImV4cCI6MjA3OTE2MjY2OX0.gQWUaTkZ6mjjlv2TED0cODp2meqqWuCGKZR1ptIbovg"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| **[README_STORAGE.md](./README_STORAGE.md)** | 🔥 **Storage 对象存储使用指南** |
|
||||
| **[docs/QUICK_START.md](./docs/QUICK_START.md)** | Storage API 快速入门 |
|
||||
| **[docs/OPERATIONS_GUIDE.md](./docs/OPERATIONS_GUIDE.md)** | 完整运维指南 |
|
||||
| **[docs/VUE_API_INTEGRATION.md](./docs/VUE_API_INTEGRATION.md)** | Vue 前端集成教程 |
|
||||
| **[docs/DEPLOYMENT_INFO.md](./docs/DEPLOYMENT_INFO.md)** | 部署配置详情 |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 可用的功能
|
||||
|
||||
| 功能 | 端点 | 状态 |
|
||||
|------|------|------|
|
||||
| **REST API** | `https://amiap.hzau.edu.cn/supa/rest/v1/` | ✅ 可用 |
|
||||
| **Auth API** | `https://amiap.hzau.edu.cn/supa/auth/v1/` | ✅ 可用 |
|
||||
| **Storage API** | `https://amiap.hzau.edu.cn/supa/storage/v1/` | ✅ 可用 |
|
||||
| **Realtime** | `wss://amiap.hzau.edu.cn/supa/realtime/v1/` | ✅ 可用 |
|
||||
| **Dashboard** | `http://100.64.0.2:18000` | ✅ 可用（内网）|
|
||||
| **MinIO** | 内部 S3 后端 | ✅ 运行中 |
|
||||
|
||||
所有核心功能都正常工作，可以开始开发！
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Vue 集成示例
|
||||
|
||||
### 1. 安装
|
||||
```bash
|
||||
npm install @supabase/supabase-js
|
||||
```
|
||||
|
||||
### 2. 配置
|
||||
```javascript
|
||||
// src/lib/supabaseClient.js
|
||||
import { createClient } from '@supabase/supabase-js'
|
||||
|
||||
export const supabase = createClient(
|
||||
'https://amiap.hzau.edu.cn/supa',
|
||||
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzYzODAyNjY5LCJleHAiOjIwNzkxNjI2Njl9.ltGXvQKpguLaf8Vzomn310hLgOZbrjqZT-F3rR00ulg'
|
||||
)
|
||||
```
|
||||
|
||||
### 3. 使用
|
||||
```vue
|
||||
<script setup>
|
||||
import { supabase } from '@/lib/supabaseClient'
|
||||
import { ref, onMounted } from 'vue'
|
||||
|
||||
const users = ref([])
|
||||
|
||||
onMounted(async () => {
|
||||
const { data } = await supabase.from('users').select('*')
|
||||
users.value = data
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
**详细教程请查看 [docs/VUE_API_INTEGRATION.md](./docs/VUE_API_INTEGRATION.md)**
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试 API
|
||||
|
||||
运行测试脚本：
|
||||
```bash
|
||||
cd /vol1/1000/docker_server/traefik/supabase-stack
|
||||
|
||||
# 测试 Storage API
|
||||
python3 examples/test_https_storage.py
|
||||
```
|
||||
|
||||
或手动测试：
|
||||
```bash
|
||||
# 测试 Storage API
|
||||
curl https://amiap.hzau.edu.cn/supa/storage/v1/bucket
|
||||
|
||||
# 测试 Auth API
|
||||
curl https://amiap.hzau.edu.cn/supa/auth/v1/health
|
||||
|
||||
# 测试 REST API
|
||||
curl https://amiap.hzau.edu.cn/supa/rest/v1/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要提示
|
||||
|
||||
### 1. Dashboard 访问
|
||||
- ❌ `https://amiap.hzau.edu.cn/supa` 无法访问 Dashboard（子路径问题）
|
||||
- ✅ 使用内网地址：`http://100.64.0.2:18000`
|
||||
|
||||
### 2. Pooler 服务重启问题 ⚠️
|
||||
|
||||
**问题现象**：
|
||||
```bash
|
||||
docker compose ps
|
||||
# supabase-pooler Restarting (1) 40 seconds ago
|
||||
```
|
||||
|
||||
**原因分析**：
|
||||
- `supabase-pooler` (Supavisor) 是数据库连接池服务
|
||||
- 主要用于高并发场景的连接优化
|
||||
- 在开发和小规模部署中**不是必需的**
|
||||
- 可能因配置或依赖问题导致重启
|
||||
|
||||
**解决方案**：
|
||||
|
||||
#### 方案 1：忽略（推荐）
|
||||
连接池服务不影响任何核心功能，可以安全忽略：
|
||||
```bash
|
||||
# 所有 API 功能正常工作，无需处理
|
||||
```
|
||||
|
||||
#### 方案 2：禁用 Pooler
|
||||
如果持续重启影响日志查看，可以禁用：
|
||||
|
||||
```bash
|
||||
# 停止 pooler 服务
|
||||
docker compose stop supavisor
|
||||
|
||||
# 或在 docker-compose.yml 中注释掉 supavisor 服务后重启
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**创建禁用配置**：
|
||||
```bash
|
||||
# 创建 docker-compose.override.yml
|
||||
cat > docker-compose.override.yml << 'OVERRIDE'
|
||||
services:
|
||||
supavisor:
|
||||
restart: "no"
|
||||
# 或完全禁用
|
||||
# profiles: ["disabled"]
|
||||
OVERRIDE
|
||||
|
||||
# 重启服务
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### 方案 3：查看详细日志
|
||||
如果需要修复，查看错误详情：
|
||||
```bash
|
||||
docker logs supabase-pooler --tail 100
|
||||
```
|
||||
|
||||
**结论**：对于开发和小规模使用，建议使用**方案 1（忽略）**或**方案 2（禁用）**。
|
||||
|
||||
### 3. REST API Schema Cache
|
||||
- 首次访问可能提示 "schema cache retrying"
|
||||
- 这是正常的初始化过程
|
||||
- 等待几秒会自动恢复，或重启 rest 服务
|
||||
|
||||
### 4. MinIO 存储
|
||||
- S3 数据存储在 `/vol1/1000/s3/stub/`
|
||||
- 不要直接访问 MinIO，统一通过 Storage API
|
||||
- 详见 [README_STORAGE.md](./README_STORAGE.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 常用管理命令
|
||||
|
||||
### 服务管理
|
||||
```bash
|
||||
# 查看所有服务状态
|
||||
docker compose ps
|
||||
|
||||
# 查看资源使用
|
||||
docker compose stats
|
||||
|
||||
# 重启特定服务
|
||||
docker compose restart kong
|
||||
docker compose restart storage
|
||||
docker compose restart rest
|
||||
|
||||
# 停止服务
|
||||
docker compose stop
|
||||
|
||||
# 启动服务
|
||||
docker compose start
|
||||
|
||||
# 完全重启
|
||||
docker compose down && docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
|
||||
```
|
||||
|
||||
### 日志查看
|
||||
```bash
|
||||
# 实时查看所有日志
|
||||
docker compose logs -f
|
||||
|
||||
# 查看特定服务日志
|
||||
docker compose logs -f kong
|
||||
docker compose logs -f storage
|
||||
docker compose logs -f rest
|
||||
docker compose logs -f db
|
||||
|
||||
# 查看最近 100 行
|
||||
docker compose logs --tail=100
|
||||
|
||||
# 查看 MinIO 日志
|
||||
docker logs supabase-minio
|
||||
```
|
||||
|
||||
### 数据库管理
|
||||
```bash
|
||||
# 连接数据库
|
||||
docker exec -it supabase-db psql -U postgres
|
||||
|
||||
# 备份数据库
|
||||
docker exec supabase-db pg_dump -U postgres postgres > backup.sql
|
||||
|
||||
# 恢复数据库
|
||||
docker exec -i supabase-db psql -U postgres postgres < backup.sql
|
||||
```
|
||||
|
||||
### 清理和重置
|
||||
```bash
|
||||
# 停止服务（保留数据）
|
||||
docker compose down
|
||||
|
||||
# 完全清理（删除所有数据，慎用！）
|
||||
docker compose down -v
|
||||
|
||||
# 清理未使用的容器和镜像
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 开发流程
|
||||
|
||||
1. **启动服务**
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
|
||||
```
|
||||
|
||||
2. **访问 Dashboard**（内网）
|
||||
- 打开 `http://100.64.0.2:18000`
|
||||
- 登录后创建数据库表
|
||||
|
||||
3. **配置 RLS 策略**
|
||||
- 在 SQL Editor 中设置权限
|
||||
- 参考文档中的示例
|
||||
|
||||
4. **Vue 应用集成**
|
||||
- 按照 `docs/VUE_API_INTEGRATION.md` 配置
|
||||
- 使用 `https://amiap.hzau.edu.cn/supa` 作为 API 地址
|
||||
|
||||
5. **Storage 使用**
|
||||
- 查看 `README_STORAGE.md`
|
||||
- 使用 Python 或 JavaScript 客户端
|
||||
|
||||
6. **开发测试**
|
||||
- 所有 API 都通过 HTTPS 访问
|
||||
- Dashboard 通过内网管理数据
|
||||
|
||||
---
|
||||
|
||||
## 🎓 学习资源
|
||||
|
||||
- [README_STORAGE.md](./README_STORAGE.md) - Storage 对象存储完整指南
|
||||
- [docs/QUICK_START.md](./docs/QUICK_START.md) - 快速入门
|
||||
- [docs/OPERATIONS_GUIDE.md](./docs/OPERATIONS_GUIDE.md) - 运维指南
|
||||
- [docs/VUE_API_INTEGRATION.md](./docs/VUE_API_INTEGRATION.md) - Vue 集成
|
||||
- [Supabase 官方文档](https://supabase.com/docs)
|
||||
- [Supabase JS 客户端](https://supabase.com/docs/reference/javascript)
|
||||
|
||||
---
|
||||
|
||||
## 💡 常见问题
|
||||
|
||||
**Q: 为什么 Dashboard 不能通过 HTTPS 访问？**
|
||||
A: Supabase Studio 是单页应用，不支持子路径部署。使用内网地址访问。
|
||||
|
||||
**Q: API 都可以正常使用吗？**
|
||||
A: 是的！所有核心 API（REST/Auth/Storage/Realtime）都可以通过 HTTPS 正常使用。
|
||||
|
||||
**Q: pooler 一直重启有影响吗？**
|
||||
A: 没有影响。pooler 是连接池优化组件，非核心功能。可以忽略或禁用。
|
||||
|
||||
**Q: 如何远程访问 Dashboard？**
|
||||
A: 使用 SSH 端口转发：`ssh -L 18000:100.64.0.2:18000 user@server`
|
||||
|
||||
**Q: 如何使用对象存储功能？**
|
||||
A: 查看 [README_STORAGE.md](./README_STORAGE.md) 和 `examples/` 目录中的示例代码。
|
||||
|
||||
**Q: MinIO 一定要启动吗？**
|
||||
A: 如果使用 Storage API 上传文件，MinIO 必须启动。使用 override 方式会自动启动。
|
||||
|
||||
---
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
**Supabase 后端已完整部署！**
|
||||
|
||||
✅ 所有 API 功能正常
|
||||
✅ 对象存储（S3）正常
|
||||
✅ 可以开始 Vue 应用开发
|
||||
✅ Dashboard 可通过内网管理
|
||||
✅ 完整的开发文档已准备好
|
||||
|
||||
**启动命令**：
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
|
||||
```
|
||||
|
||||
开始你的 Supabase 开发之旅吧！🚀
|
||||
|
||||
---
|
||||
|
||||
**部署日期**: 2025-11-22
|
||||
**服务器**: amiap.hzau.edu.cn
|
||||
**维护文档**: 本目录下的 README_STORAGE.md 和 docs/ 文件夹
|
||||
Reference in New Issue
Block a user