labweb/README.md

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

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

🏗️ 系统架构

整体架构图

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

目录结构

/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 网关

cd /vol1/1000/docker_server/traefik

# 启动 Traefik + Derper
docker compose up -d

# 查看状态
docker compose ps

2. 启动 Supabase 后端

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 - 中文完整指南
• README_STORAGE.md - Storage 使用指南
• docs/QUICK_START.md - 快速入门

3. 部署 Web 应用

ABM 数据库项目

cd web/ws

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

# 查看日志
docker compose logs -f

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

其他项目（待部署）

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

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

4. 诱饵站（可选）

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

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

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

📊 服务状态检查

查看所有服务

# 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

# 测试 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

查看日志

# 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

🔧 管理命令

重启服务

# 重启 Traefik
docker compose restart traefik

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

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

停止服务

# 停止所有服务
docker compose down

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

更新服务

# 拉取最新镜像
docker compose pull

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

📚 详细文档

Traefik 部署策略

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

Supabase 文档

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

示例代码

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

⚙️ 配置说明

Traefik 配置

docker-compose.yml 关键配置：

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 对象存储

关键环境变量：

# 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）：

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 无法启动

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

# 查看日志
docker compose logs traefik

Supabase 服务问题

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）
2. Storage API 403 错误 - 检查 RLS 策略和 API 密钥
3. 数据库连接失败 - 检查 PostgreSQL 是否正常运行

Web 应用问题

cd web/ws

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f

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

SSL 证书问题

# 查看证书状态
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 标签

示例：

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：

// 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

Storage API 使用

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:

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. 生产环境 → 公网部署

备份策略

# 备份 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

监控和日志

# 实时监控资源使用
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 官方文档
• Supabase 官方文档
• Docker Compose 文档

项目维护

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

---

快速导航：

• Supabase 中文指南
• Storage 使用指南
• 部署策略文档

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