labweb/supabase-stack/docs/README_CN.md

# 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/ 文件夹