docs: 全面更新根目录 README.md 文档

完整重写根目录 README.md,提供系统级文档说明:

📝 新增内容:

1. 系统架构说明
   - 添加完整的架构图(Traefik → Supabase/Web Apps/Derper)
   - 详细的目录结构说明
   - 清晰的服务组织关系

2. 🚀 Supabase 启动说明
   - 完整的 docker compose override 启动命令
   - docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
   - 详细的启动流程和验证步骤

3. 🌐 URL 路由规划
   - 所有服务的访问地址和状态
   - Supabase API 端点树状结构
   - 路径前缀方案说明

4. Web 应用架构
   - web/ws (ABM 数据库项目) 详细说明
   - web/gzy, web/zz 待部署项目说明
   - 每个项目的启动和配置方法

5. 📊 完整的运维指南
   - 服务状态检查命令
   - 日志查看方法
   - 重启/停止/更新服务流程
   - 故障排查步骤

6. 📚 文档导航
   - Traefik 部署策略文档链接
   - Supabase 完整文档链接
   - 示例代码路径

7. ⚙️ 配置说明
   - Traefik 核心配置
   - Supabase 环境变量
   - Web 应用 Traefik 标签配置

8. 🔒 安全配置
   - SSL/TLS 证书管理
   - API 密钥说明
   - 访问控制建议

9. 📝 开发指南
   - 添加新 Web 应用的方法
   - Vue 项目集成 Supabase 示例
   - Storage API 使用示例 (Python/JavaScript)

10. 🎯 最佳实践
    - 部署流程
    - 备份策略
    - 监控和日志
    - 性能优化建议

变更统计:
  - 新增 529 行
  - 删除 26 行
  - 从简单说明扩展为完整的系统文档

目标受众:
  - 新加入的运维工程师
  - 需要部署新服务的开发者
  - 系统维护人员

相关文档:
  - supabase-stack/README_CN.md (Supabase 详细指南)
  - supabase-stack/README_STORAGE.md (Storage 使用)
  - docs/strategy-*.md (部署策略文档)
This commit is contained in:
zly
2025-11-22 21:54:33 +08:00
parent 9a261bb265
commit d6f40cc488

561
README.md
View File

@@ -1,49 +1,552 @@
# Traefik Docker Server
# Traefik 反向代理 + 多服务部署平台
该目录包含服务器的 Traefik 网关配置及各个子项目的 Docker Compose 部署文件
基于 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 服务
├── supabase-stack/ # [后端] Supabase 核心服务 (Auth, Realtime, Storage, etc.)
└── web/ # [应用] 各个 Web 应用项目
├── portal/ # [前端] 实验室主站 Vue 项目源码/部署配置 (https://amiap.hzau.edu.cn)
── ws/ # [项目] ABM 遗留项目 (/ABM)
├── zz/ # [项目] ZZ 项目
└── gzy/ # [项目] GZY 项目
/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 路由规划
## 🌐 URL 路由规划
基于 Traefik 的一入口架构
基于 Traefik 的一入口,所有服务通过路径前缀区分
| 服务名称 | 路径规则 | 说明 |
| :--- | :--- | :--- |
| **Main Portal** (Vue) | `Host(amiap.hzau.edu.cn)` | 实验室主站前端 |
| **Supabase Studio** | `Host(amiap.hzau.edu.cn) && PathPrefix(/supa)` | Supabase 管理后台 (Dashboard) |
| **Supabase API** | `Host(amiap.hzau.edu.cn) && PathPrefix(/supa/...)` | 包含 Auth, Rest, Storage 等 API |
| **Python API** | `Host(amiap.hzau.edu.cn) && PathPrefix(/api)` | 自研 Python 后端接口 |
| **Project ABM** | `Host(amiap.hzau.edu.cn) && PathPrefix(/ABM)` | 现有 WS 项目 |
| 服务 | 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 网关
### 1. 启动核心网关 (Traefik)
```bash
cd /vol1/1000/docker_server/traefik
# 启动 Traefik + Derper
docker compose up -d
# 查看状态
docker compose ps
```
### 2. 部署各个子服务
进入对应目录启动服务,例如部署 ABM 项目:
### 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
```
### 3. 首页/诱饵站 (Decoy Site)
Traefik 默认包含一个简单的 Nginx 诱饵站,位于 `derper/decoy-site`
```bash
nano derper/decoy-site/index.html
docker compose up -d --build decoy-site
## 📝 开发指南
### 添加新的 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 部署平台!**