labweb/README.md

# Traefik 反向代理 + 多服务部署平台

基于 Traefik 的统一网关架构，支持多个 Web 应用和后端服务的集中管理和部署。

## 🏗️ 系统架构

### 整体架构图

```
┌─────────────────────────────────────────────────────────┐
│                    Internet (HTTPS)                     │
│              https://amiap.hzau.edu.cn                  │
└────────────────────┬────────────────────────────────────┘
                     │
          ┌──────────▼──────────┐
          │   Traefik Gateway   │  ← Let's Encrypt 自动证书
          │   (反向代理+路由)    │
          └──────────┬──────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
   ┌────▼───┐  ┌────▼────┐  ┌───▼────┐
   │Supabase│  │Web Apps │  │Derper  │
   │ Stack  │  │  (多项目)│  │        │
   └────────┘  └─────────┘  └────────┘
```

### 目录结构

```text
/vol1/1000/docker_server/traefik/
│
├── 📁 核心配置
│   ├── docker-compose.yml              # Traefik 网关 + Derper
│   ├── .gitignore                      # Git 忽略规则
│   └── README.md                       # 本文档
│
├── 📁 docs/                            # 部署策略文档
│   ├── strategy-1-path-prefix.md      # 路径前缀方案
│   ├── strategy-2-subdomain.md        # 子域名方案
│   ├── strategy-3-hybrid.md           # 混合方案
│   └── strategy-comparison-report.md  # 策略对比
│
├── 📁 supabase-stack/                  # 🔥 Supabase 后端服务
│   ├── docker-compose.yml             # 核心服务（PostgreSQL, Auth, REST, etc.)
│   ├── docker-compose.s3.yml          # MinIO 对象存储
│   ├── README_CN.md                   # 中文使用指南
│   ├── README_STORAGE.md              # Storage 对象存储指南
│   ├── docs/                          # 详细文档
│   │   ├── QUICK_START.md            # 快速入门
│   │   ├── OPERATIONS_GUIDE.md       # 运维指南
│   │   └── VUE_API_INTEGRATION.md    # Vue 集成教程
│   └── examples/                      # 示例代码
│       ├── storage_client.py         # Python 客户端
│       ├── storage_client.js         # JavaScript 客户端
│       └── test_https_storage.py     # 测试脚本
│
└── 📁 web/                             # Web 应用项目
    ├── ws/                            # ABM 数据库项目
    │   ├── docker-compose.yml        # 项目配置
    │   ├── backend/                  # Go 后端
    │   └── postgres_data/            # PostgreSQL 数据
    ├── gzy/                           # GZY 项目（待部署）
    └── zz/                            # ZZ 项目（待部署）
```

## 🌐 URL 路由规划

基于 Traefik 的统一入口，所有服务通过路径前缀区分：

| 服务 | URL | 说明 | 状态 |
|------|-----|------|------|
| **主站** | `https://amiap.hzau.edu.cn/` | 实验室主页（待部署） | 🔜 |
| **Supabase API** | `https://amiap.hzau.edu.cn/supa` | 后端服务（Auth/REST/Storage/Realtime） | ✅ |
| **Supabase Dashboard** | `http://100.64.0.2:18000` | 管理面板（仅内网） | ✅ |
| **ABM 数据库** | `https://amiap.hzau.edu.cn/ABM` | WebSocket 项目 | ✅ |
| **Derper** | `https://amiap.hzau.edu.cn/derp` | Tailscale DERP 中继 | ✅ |
| **Decoy Site** | `https://amiap.hzau.edu.cn/` (fallback) | 默认页面 | ✅ |

### Supabase API 端点

```
https://amiap.hzau.edu.cn/supa/
├── auth/v1/         # 用户认证
├── rest/v1/         # 数据库 REST API
├── storage/v1/      # 文件存储
└── realtime/v1/     # 实时订阅
```

## 🚀 快速开始

### 1. 启动 Traefik 网关

```bash
cd /vol1/1000/docker_server/traefik

# 启动 Traefik + Derper
docker compose up -d

# 查看状态
docker compose ps
```

### 2. 启动 Supabase 后端

```bash
cd supabase-stack

# 🔥 推荐：同时启动核心服务 + S3 对象存储
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d

# 查看所有服务状态
docker compose ps

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

**详细文档**：
- [README_CN.md](supabase-stack/README_CN.md) - 中文完整指南
- [README_STORAGE.md](supabase-stack/README_STORAGE.md) - Storage 使用指南
- [docs/QUICK_START.md](supabase-stack/docs/QUICK_START.md) - 快速入门

### 3. 部署 Web 应用

#### ABM 数据库项目

```bash
cd web/ws

# 启动服务（Go 后端 + PostgreSQL）
docker compose up -d

# 查看日志
docker compose logs -f
```

访问：`https://amiap.hzau.edu.cn/ABM`

#### 其他项目（待部署）

```bash
# GZY 项目
cd web/gzy
# 待添加 docker-compose.yml

# ZZ 项目
cd web/zz
# 待添加 docker-compose.yml
```

### 4. 诱饵站（可选）

Traefik 包含一个简单的 Nginx 诱饵站：

```bash
# 编辑首页
nano derper/decoy-site/index.html

# 重新构建
docker compose up -d --build decoy-site
```

## 📊 服务状态检查

### 查看所有服务

```bash
# Traefik + Derper
cd /vol1/1000/docker_server/traefik
docker compose ps

# Supabase
cd supabase-stack
docker compose ps

# Web 应用
cd web/ws
docker compose ps
```

### 测试 API

```bash
# 测试 Supabase Storage
curl https://amiap.hzau.edu.cn/supa/storage/v1/bucket

# 测试 Supabase Auth
curl https://amiap.hzau.edu.cn/supa/auth/v1/health

# 测试 ABM
curl https://amiap.hzau.edu.cn/ABM
```

### 查看日志

```bash
# Traefik 日志
docker compose logs -f traefik

# Supabase 日志
cd supabase-stack
docker compose logs -f kong
docker compose logs -f storage

# Web 应用日志
cd web/ws
docker compose logs -f
```

## 🔧 管理命令

### 重启服务

```bash
# 重启 Traefik
docker compose restart traefik

# 重启 Supabase 特定服务
cd supabase-stack
docker compose restart kong
docker compose restart storage

# 重启 Web 应用
cd web/ws
docker compose restart
```

### 停止服务

```bash
# 停止所有服务
docker compose down

# 停止并删除数据卷（慎用！）
docker compose down -v
```

### 更新服务

```bash
# 拉取最新镜像
docker compose pull

# 重新构建和启动
docker compose up -d --build
```

## 📚 详细文档

### Traefik 部署策略

- [strategy-1-path-prefix.md](docs/strategy-1-path-prefix.md) - 路径前缀方案（当前使用）
- [strategy-2-subdomain.md](docs/strategy-2-subdomain.md) - 子域名方案
- [strategy-3-hybrid.md](docs/strategy-3-hybrid.md) - 混合方案
- [strategy-comparison-report.md](docs/strategy-comparison-report.md) - 策略对比分析

### Supabase 文档

- [supabase-stack/README_CN.md](supabase-stack/README_CN.md) - 🔥 完整使用指南
- [supabase-stack/README_STORAGE.md](supabase-stack/README_STORAGE.md) - Storage 对象存储
- [supabase-stack/docs/QUICK_START.md](supabase-stack/docs/QUICK_START.md) - 快速入门
- [supabase-stack/docs/OPERATIONS_GUIDE.md](supabase-stack/docs/OPERATIONS_GUIDE.md) - 运维指南
- [supabase-stack/docs/VUE_API_INTEGRATION.md](supabase-stack/docs/VUE_API_INTEGRATION.md) - Vue 集成教程

### 示例代码

- [supabase-stack/examples/storage_client.py](supabase-stack/examples/storage_client.py) - Python 完整客户端
- [supabase-stack/examples/storage_client.js](supabase-stack/examples/storage_client.js) - JavaScript 完整客户端
- [supabase-stack/examples/test_https_storage.py](supabase-stack/examples/test_https_storage.py) - 测试脚本

## ⚙️ 配置说明

### Traefik 配置

**docker-compose.yml** 关键配置：

```yaml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.email=lyzeng@hzau.edu.cn"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"  # Dashboard
```

**访问 Traefik Dashboard**：`http://服务器IP:8080`

### Supabase 配置

主要配置文件：
- `.env` - 环境变量（密钥、数据库配置等）
- `docker-compose.yml` - 核心服务
- `docker-compose.s3.yml` - MinIO 对象存储

**关键环境变量**：

```bash
# API 密钥
ANON_KEY=eyJhbGc...    # 前端使用
SERVICE_ROLE_KEY=eyJ...  # 后端使用

# 数据库
POSTGRES_PASSWORD=your-password

# 对象存储
MINIO_ROOT_USER=supabase-minio
MINIO_ROOT_PASSWORD=your-minio-password
```

### Web 应用配置

每个项目独立配置，示例（web/ws）：

```yaml
services:
  webws:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.webws.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM`)"
      - "traefik.http.routers.webws.entrypoints=websecure"
      - "traefik.http.routers.webws.tls.certresolver=myresolver"
```

## 🔒 安全配置

### SSL/TLS 证书

- 使用 Let's Encrypt 自动申请和续期
- 证书存储在 `acme-data` Docker volume 中
- 自动 HTTP 到 HTTPS 重定向

### 访问控制

- Supabase Dashboard 仅内网访问（`http://100.64.0.2:18000`）
- Traefik Dashboard 端口 8080（建议配置认证）
- 生产环境建议配置防火墙规则

### API 密钥

- `ANON_KEY` - 前端使用，权限受 RLS 限制
- `SERVICE_ROLE_KEY` - 后端使用，完全权限，需保密

## 🛠️ 故障排查

### Traefik 无法启动

```bash
# 检查端口占用
sudo netstat -tlnp | grep ':80\|:443\|:8080'

# 查看日志
docker compose logs traefik
```

### Supabase 服务问题

```bash
cd supabase-stack

# 查看所有服务状态
docker compose ps

# 查看特定服务日志
docker compose logs -f kong
docker compose logs -f storage
docker compose logs -f db

# 重启服务
docker compose restart
```

**常见问题**：

1. **supabase-pooler 一直重启** - 可以忽略，不影响功能（详见 [README_CN.md](supabase-stack/README_CN.md)）
2. **Storage API 403 错误** - 检查 RLS 策略和 API 密钥
3. **数据库连接失败** - 检查 PostgreSQL 是否正常运行

### Web 应用问题

```bash
cd web/ws

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f

# 进入容器调试
docker compose exec webws /bin/sh
```

### SSL 证书问题

```bash
# 查看证书状态
docker compose logs traefik | grep -i "certificate"

# 删除旧证书重新申请（慎用）
docker volume rm traefik_acme-data
docker compose up -d
```

## 📝 开发指南

### 添加新的 Web 应用

1. 在 `web/` 下创建项目目录
2. 创建 `docker-compose.yml`
3. 配置 Traefik 标签

示例：

```yaml
services:
  myapp:
    image: myapp:latest
    networks:
      - frontend
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/myapp`)"
      - "traefik.http.routers.myapp.entrypoints=websecure"
      - "traefik.http.routers.myapp.tls.certresolver=myresolver"
      - "traefik.http.middlewares.myapp-stripprefix.stripprefix.prefixes=/myapp"
      - "traefik.http.routers.myapp.middlewares=myapp-stripprefix"

networks:
  frontend:
    external: true
```

### 前端开发集成

**Vue 项目集成 Supabase**：

```javascript
// src/lib/supabaseClient.js
import { createClient } from '@supabase/supabase-js'

export const supabase = createClient(
  'https://amiap.hzau.edu.cn/supa',
  'your-anon-key'
)
```

详细教程：[VUE_API_INTEGRATION.md](supabase-stack/docs/VUE_API_INTEGRATION.md)

### Storage API 使用

**Python**:
```python
from examples.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)
```

**JavaScript**:
```javascript
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);
```

## 🎯 最佳实践

### 部署流程

1. **开发环境** → 本地测试
2. **测试环境** → 内网测试
3. **生产环境** → 公网部署

### 备份策略

```bash
# 备份 Supabase 数据库
cd supabase-stack
docker exec supabase-db pg_dump -U postgres postgres > backup_$(date +%Y%m%d).sql

# 备份 MinIO 数据
tar -czf minio_backup_$(date +%Y%m%d).tar.gz /vol1/1000/s3/stub/

# 备份配置文件
tar -czf config_backup_$(date +%Y%m%d).tar.gz .env docker-compose*.yml
```

### 监控和日志

```bash
# 实时监控资源使用
docker stats

# 查看所有容器日志
docker compose logs -f --tail=100

# 日志持久化（可选）
mkdir -p /var/log/docker
docker compose logs > /var/log/docker/traefik_$(date +%Y%m%d).log
```

### 性能优化

1. **数据库连接池** - Supabase pooler（可选）
2. **CDN 加速** - 静态资源使用 CDN
3. **缓存策略** - Traefik 支持缓存中间件
4. **负载均衡** - 多实例部署

## 📞 技术支持

### 相关链接

- [Traefik 官方文档](https://doc.traefik.io/traefik/)
- [Supabase 官方文档](https://supabase.com/docs)
- [Docker Compose 文档](https://docs.docker.com/compose/)

### 项目维护

- **部署日期**: 2025-11-22
- **服务器**: amiap.hzau.edu.cn
- **维护团队**: Lab Admin

---

**快速导航**：
- [Supabase 中文指南](supabase-stack/README_CN.md)
- [Storage 使用指南](supabase-stack/README_STORAGE.md)
- [部署策略文档](docs/)

🎉 **开始使用 Traefik + Supabase 部署平台！**