labweb/supabase-stack/README.md

# Supabase Self-Hosted Stack

**架构**: Supabase + MinIO (内网)  
**状态**: ✅ 生产就绪  
**版本**: v3.0 (MinIO 内网化)

## 🌐 服务访问

### 公网 HTTPS

| 服务 | URL | 说明 |
|------|-----|------|
| **Supabase Storage** | `https://amiap.hzau.edu.cn/supa/storage/v1/` | 文件上传下载 API |
| **Supabase API** | `https://amiap.hzau.edu.cn/supa/` | Auth/REST/Realtime |

### 内网 Tailscale

| 服务 | URL | 说明 |
|------|-----|------|
| **MinIO S3 API** | `http://100.64.0.2:9000` | 对象存储 API |
| **MinIO Console** | `http://100.64.0.2:9001` | Web 管理界面 |
| **Supabase Dashboard** | `http://100.64.0.2:18000` | 数据库管理 |

## 🚀 快速启动

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

# 启动所有服务
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d

# 测试 Storage API
python3 examples/test_https_storage.py
```

**期望结果**: 5/5 测试通过 ✅

## 📊 架构说明

### 存储流程

**公网访问**:
```
用户
  ↓ HTTPS
https://amiap.hzau.edu.cn/supa/storage/v1/
  ↓ Traefik → Kong Gateway
Supabase Storage Service
  ↓ 内部网络 (http://minio:9000)
MinIO 对象存储
  ↓
物理存储: /vol1/1000/s3
```

**内网访问** (需要 Tailscale VPN):
```
管理员
  ↓
http://100.64.0.2:9000 (MinIO S3 API)
http://100.64.0.2:9001 (MinIO Console)
  ↓
MinIO 对象存储
  ↓
物理存储: /vol1/1000/s3
```

### 关键特性

✅ **MinIO 内网化**: 不暴露到公网  
✅ **统一入口**: 公网访问通过 Supabase Storage API  
✅ **权限控制**: 支持 RLS (Row Level Security)  
✅ **安全隔离**: 管理界面仅内网访问

## 🔐 MinIO 登录

**Console**: `http://100.64.0.2:9001`

**凭证** (见 `.env` 文件):
- 用户名: `MINIO_ROOT_USER`
- 密码: `MINIO_ROOT_PASSWORD`

## 💾 Supabase Storage API 使用

### Python 示例

```python
import requests

BASE_URL = 'https://amiap.hzau.edu.cn/supa'
API_KEY = 'your_anon_key'  # 见 .env 文件

headers = {
    'apikey': API_KEY,
    'Authorization': f'Bearer {API_KEY}'
}

# 上传文件
with open('file.txt', 'rb') as f:
    response = requests.post(
        f'{BASE_URL}/storage/v1/object/bucket-name/file.txt',
        headers={**headers, 'Content-Type': 'text/plain'},
        data=f
    )

# 下载文件
response = requests.get(
    f'{BASE_URL}/storage/v1/object/bucket-name/file.txt',
    headers=headers
)
content = response.content
```

### JavaScript 示例

```javascript
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://amiap.hzau.edu.cn/supa',
  'your_anon_key'
)

// 上传文件
const { data, error } = await supabase.storage
  .from('bucket-name')
  .upload('file.txt', file)

// 下载文件
const { data: fileData } = await supabase.storage
  .from('bucket-name')
  .download('file.txt')
```

## 📁 配置文件

```
supabase-stack/
├── docker-compose.yml          # Supabase 主配置
├── docker-compose.s3.yml       # MinIO 配置（内网）
├── .env                        # 环境变量和凭证
├── examples/
│   └── test_https_storage.py  # Storage API 测试脚本
└── docs/
    ├── FINAL_ARCHITECTURE_MINIO_INTERNAL.md  # 详细架构
    ├── MINIO_LOGIN_FIX.md                    # 登录问题修复
    ├── OPERATIONS_GUIDE.md                   # 运维指南
    └── VUE_API_INTEGRATION.md                # Vue.js 集成指南
```

## 🛠️ 常用命令

### 服务管理

```bash
# 启动
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d

# 停止
docker compose -f docker-compose.yml -f docker-compose.s3.yml down

# 重启
docker compose -f docker-compose.yml -f docker-compose.s3.yml restart

# 查看状态
docker ps | grep -E "supabase|minio"
```

### 日志查看

```bash
docker logs supabase-kong --tail 50
docker logs supabase-storage --tail 50
docker logs supabase-minio-1 --tail 50
docker logs supabase-auth --tail 50
```

### 测试验证

```bash
# Storage API 完整测试
python3 examples/test_https_storage.py

# MinIO 健康检查
curl -I http://100.64.0.2:9000/minio/health/live

# MinIO Console 访问
curl -I http://100.64.0.2:9001

# Supabase API 健康检查
curl -I https://amiap.hzau.edu.cn/supa/
```

## 🔍 故障排查

### Storage API 返回 404

```bash
# 检查 Kong 状态
docker ps | grep kong
docker inspect supabase-kong --format='{{.State.Health.Status}}'
docker logs supabase-kong --tail 50
```

### MinIO 内网无法访问

```bash
# 确认 Tailscale 连接
tailscale status
ping 100.64.0.2

# 检查 MinIO 容器和端口
docker ps | grep minio
docker port supabase-minio-1
```

### 文件上传失败

```bash
# 检查 Storage 服务
docker logs supabase-storage --tail 50

# 验证 Storage 到 MinIO 的连接
docker exec supabase-storage ping -c 1 minio

# 检查环境变量
docker exec supabase-storage env | grep -E "GLOBAL_S3|MINIO"
```

## 📚 详细文档

| 文档 | 说明 |
|------|------|
| `docs/FINAL_ARCHITECTURE_MINIO_INTERNAL.md` | MinIO 内网化详细架构 |
| `docs/MINIO_LOGIN_FIX.md` | MinIO Console 登录问题修复 |
| `docs/OPERATIONS_GUIDE.md` | 运维指南 |
| `docs/VUE_API_INTEGRATION.md` | Vue.js 与 Supabase API 集成 |
| `docs/DEPLOYMENT_GUIDE.md` | 部署指南 |

## 环境变量

关键配置在 `.env` 文件中：

```bash
# MinIO 凭证
MINIO_ROOT_USER=...
MINIO_ROOT_PASSWORD=...

# Supabase API Keys
ANON_KEY=...
SERVICE_ROLE_KEY=...

# S3 配置
GLOBAL_S3_BUCKET=stub
GLOBAL_S3_ENDPOINT=http://minio:9000
```

---

**架构版本**: v3.0 (MinIO 内网化)  
**最后更新**: 2025-11-23  
**测试状态**: ✅ 5/5 通过