labweb/supabase-stack/docs/README_CN.md

Supabase 部署完成 ✅

恭喜！Supabase 后端已成功部署在 https://amiap.hzau.edu.cn/supa

---

🚀 服务启动

完整启动命令

Supabase 服务包含核心服务和 S3 对象存储两部分，使用 Docker Compose 的 override 功能同时启动：

# 进入目录
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/

启动流程

# 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

快速管理命令

# 查看所有服务状态
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

// 公开密钥 - 可在前端使用
const ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzYzODAyNjY5LCJleHAiOjIwNzkxNjI2Njl9.ltGXvQKpguLaf8Vzomn310hLgOZbrjqZT-F3rR00ulg"

// 私密密钥 - 仅后端使用
const SERVICE_ROLE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaXNzIjoic3VwYWJhc2UiLCJpYXQiOjE3NjM4MDI2NjksImV4cCI6MjA3OTE2MjY2OX0.gQWUaTkZ6mjjlv2TED0cODp2meqqWuCGKZR1ptIbovg"

---

📚 文档

文档	说明
README_STORAGE.md	🔥 Storage 对象存储使用指南
docs/QUICK_START.md	Storage API 快速入门
docs/OPERATIONS_GUIDE.md	完整运维指南
docs/VUE_API_INTEGRATION.md	Vue 前端集成教程
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. 安装

npm install @supabase/supabase-js

2. 配置

// 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. 使用

<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

---

🧪 测试 API

运行测试脚本：

cd /vol1/1000/docker_server/traefik/supabase-stack

# 测试 Storage API
python3 examples/test_https_storage.py

或手动测试：

# 测试 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 服务重启问题 ⚠️

问题现象：

docker compose ps
# supabase-pooler    Restarting (1) 40 seconds ago

原因分析：

• supabase-pooler (Supavisor) 是数据库连接池服务
• 主要用于高并发场景的连接优化
• 在开发和小规模部署中不是必需的
• 可能因配置或依赖问题导致重启

解决方案：

方案 1：忽略（推荐）

连接池服务不影响任何核心功能，可以安全忽略：

# 所有 API 功能正常工作，无需处理

方案 2：禁用 Pooler

如果持续重启影响日志查看，可以禁用：

# 停止 pooler 服务
docker compose stop supavisor

# 或在 docker-compose.yml 中注释掉 supavisor 服务后重启
docker compose up -d

创建禁用配置：

# 创建 docker-compose.override.yml
cat > docker-compose.override.yml << 'OVERRIDE'
services:
  supavisor:
    restart: "no"
    # 或完全禁用
    # profiles: ["disabled"]
OVERRIDE

# 重启服务
docker compose up -d

方案 3：查看详细日志

如果需要修复，查看错误详情：

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

---

🔧 常用管理命令

服务管理

# 查看所有服务状态
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

日志查看

# 实时查看所有日志
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

数据库管理

# 连接数据库
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

清理和重置

# 停止服务（保留数据）
docker compose down

# 完全清理（删除所有数据，慎用！）
docker compose down -v

# 清理未使用的容器和镜像
docker system prune -a

---

📖 开发流程

1. 启动服务

   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 - Storage 对象存储完整指南
• docs/QUICK_START.md - 快速入门
• docs/OPERATIONS_GUIDE.md - 运维指南
• docs/VUE_API_INTEGRATION.md - Vue 集成
• Supabase 官方文档
• Supabase JS 客户端

---

💡 常见问题

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 和 examples/ 目录中的示例代码。

Q: MinIO 一定要启动吗？ A: 如果使用 Storage API 上传文件，MinIO 必须启动。使用 override 方式会自动启动。

---

🎉 总结

Supabase 后端已完整部署！

✅ 所有 API 功能正常
✅ 对象存储（S3）正常
✅ 可以开始 Vue 应用开发
✅ Dashboard 可通过内网管理
✅ 完整的开发文档已准备好

启动命令：

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