# Jointo 后端部署指南

> **项目**: Jointo 视频制作工作台后端服务  
> **技术栈**: FastAPI + PostgreSQL 17 + Redis + MinIO  
> **更新时间**: 2026-01-24

## 快速开始

### 1. 一键启动所有服务

```bash
cd server/
./start_docker.sh
```

**启动模式**：
- **默认模式**: `./start_docker.sh` - 快速启动（保留容器数据）
- **清理模式**: `./start_docker.sh --clean` - 清除旧容器和卷后重新构建
- **构建模式**: `./start_docker.sh --build` - 强制重新构建镜像
- **组合使用**: `./start_docker.sh --clean --build` - 完全重建

**启动的服务**：
- **PostgreSQL 17** 数据库（端口 6181）
- **Redis 7** 缓存（端口 6183）
- **MinIO** 对象存储（端口 6185 API / 6187 控制台）
- **Adminer** 数据库管理工具（端口 6184）
- **FastAPI** 应用（端口 6170）

### 2. 数据库迁移

#### 增量迁移（默认，安全）

```bash
./migrate_db.sh
```

- ✅ 只创建不存在的表
- ✅ 保留现有数据
- ✅ 安全操作，可重复执行
- ✅ 自动检查 Docker 容器状态

#### 清空迁移（危险）

```bash
./migrate_db.sh --fresh
```

- ⚠️ 删除所有表
- ⚠️ 所有数据会丢失
- ⚠️ 需要输入 `YES` 确认
- ⚠️ 仅用于开发环境

#### 查看帮助

```bash
./migrate_db.sh --help
```

## 常用命令

### 服务管理

```bash
# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f app
docker compose logs -f postgres
docker compose logs -f redis
```

### 数据库操作

```bash
# 连接数据库（用户名：jointoAI，密码：123456）
docker exec -it jointo-server-postgres psql -U jointoAI -d jointo

# 查看所有表
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\dt"

# 查看表结构
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d users"
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d projects"
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d folders"

# 查看表数据统计
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "
SELECT 
    schemaname,
    tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size,
    n_live_tup AS row_count
FROM pg_stat_user_tables
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
"

# 执行 SQL 查询
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "SELECT COUNT(*) FROM users;"
```

### 应用操作

```bash
# 进入应用容器
docker exec -it jointo-server-app bash

# 查看应用日志
docker compose logs -f app

# 重启应用
docker compose restart app

# 查看应用环境变量
docker exec jointo-server-app env | grep -E "DATABASE|REDIS|MINIO"
```

## 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| **API 文档** | http://localhost:6170/api/docs | Swagger UI 交互式文档 |
| **健康检查** | http://localhost:6170/health | 服务健康状态 |
| **MinIO 控制台** | http://localhost:6187 | 对象存储管理界面 (minioadmin/minioadmin) |
| **Adminer** | http://localhost:6184 | 数据库管理工具 |
| **PostgreSQL** | localhost:6181 | 数据库连接 (jointoAI/123456) |
| **Redis** | localhost:6183 | 缓存服务 |

## 开发流程

### 首次启动

```bash
# 1. 进入 server 目录
cd server/

# 2. 启动所有服务
./start_docker.sh

# 3. 执行数据库迁移
./migrate_db.sh

# 4. 访问 API 文档
open http://localhost:6170/api/docs
```

### 日常开发

```bash
# 启动服务（如果已停止）
docker compose up -d

# 查看日志
docker compose logs -f app

# 代码修改后自动重载（已配置 --reload）
# 无需手动重启
```

### 数据库变更

```bash
# 修改模型后，执行增量迁移
./migrate_db.sh

# 如需重置数据库（开发环境）
./migrate_db.sh --fresh
```

## 环境变量

### 配置文件

- **开发环境**: `server/.env`（从 `.env.example` 复制）
- **Docker 环境**: `server/docker-compose.yml` 中的 `environment` 配置

### 关键配置

```bash
# 应用配置
APP_NAME=Jointo API
APP_VERSION=1.0.0
DEBUG=True
ENVIRONMENT=development
HOST=0.0.0.0
PORT=6170

# 数据库配置（Docker 内部）
DATABASE_URL=postgresql+asyncpg://jointoAI:123456@postgres:5432/jointo
DATABASE_ECHO=True

# 数据库配置（本地连接）
DATABASE_URL=postgresql+asyncpg://jointoAI:123456@localhost:6181/jointo

# Redis 配置
REDIS_URL=redis://redis:6379/0

# JWT 配置
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS 配置
CORS_ORIGINS=["http://localhost:6160","http://192.168.31.178:6160"]

# MinIO 配置
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=jointo
MINIO_SECURE=False

# Celery 配置（异步任务）
CELERY_BROKER_URL=redis://redis:6379/1
CELERY_RESULT_BACKEND=redis://redis:6379/2
```

## 故障排查

### 服务无法启动

```bash
# 查看详细日志
docker compose logs

# 检查端口占用
lsof -i :6170  # FastAPI
lsof -i :6181  # PostgreSQL
lsof -i :6183  # Redis
lsof -i :6185  # MinIO API
lsof -i :6187  # MinIO Console

# 清理并重启
docker compose down
docker compose up --build -d

# 完全清理（包括卷）
docker compose down -v
./start_docker.sh --clean --build
```

### 数据库连接失败

```bash
# 检查 PostgreSQL 容器状态
docker compose ps postgres

# 查看 PostgreSQL 日志
docker compose logs postgres

# 测试连接
docker exec jointo-server-postgres psql -U jointoAI -c "SELECT 1;"

# 检查数据库是否存在
docker exec jointo-server-postgres psql -U jointoAI -c "\l"

# 检查健康状态
docker exec jointo-server-postgres pg_isready -U jointoAI
```

### 应用报错

```bash
# 查看应用日志
docker compose logs -f app

# 进入容器调试
docker exec -it jointo-server-app bash

# 测试数据库连接
docker exec -it jointo-server-app python -c "
import asyncio
from app.core.database import init_db
asyncio.run(init_db())
"

# 查看 Python 环境
docker exec jointo-server-app python --version
docker exec jointo-server-app pip list
```

### MinIO 连接问题

```bash
# 检查 MinIO 容器状态
docker compose ps minio

# 查看 MinIO 日志
docker compose logs minio

# 测试 MinIO 健康检查
curl http://localhost:6185/minio/health/live
```

## 生产部署

### 环境准备

1. **修改 `.env` 配置**（使用生产环境值）
   - 设置强密码（数据库、Redis、MinIO）
   - 修改 `SECRET_KEY` 为随机字符串
   - 设置 `DEBUG=False`
   - 配置正确的 `CORS_ORIGINS`

2. **配置域名和 SSL 证书**
   - 使用 Nginx 反向代理
   - 配置 Let's Encrypt SSL 证书

3. **资源配置**
   - 调整 PostgreSQL 内存配置
   - 配置 Redis 持久化
   - 设置 MinIO 存储路径

### 部署步骤

```bash
# 1. 拉取代码
git pull origin main

# 2. 构建镜像
docker compose build

# 3. 启动服务
docker compose up -d

# 4. 执行迁移
./migrate_db.sh

# 5. 检查状态
docker compose ps
curl http://localhost:6170/health

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

### 备份与恢复

```bash
# 备份数据库
docker exec jointo-server-postgres pg_dump -U jointoAI jointo > backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复数据库
docker exec -i jointo-server-postgres psql -U jointoAI jointo < backup_20260124_120000.sql

# 备份 MinIO 数据
docker exec jointo-server-minio mc mirror /data /backup

# 定时备份（crontab）
0 2 * * * cd /path/to/jointo/server && docker exec jointo-server-postgres pg_dump -U jointoAI jointo > /backup/jointo_$(date +\%Y\%m\%d).sql
```

## 架构说明

### 服务架构

```
┌─────────────────────────────────────────────────────────┐
│              Docker Compose 网络 (jointo-network)        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   FastAPI    │  │ PostgreSQL   │  │    Redis     │ │
│  │     App      │──│   17-alpine  │  │  7-alpine    │ │
│  │   :6170      │  │    :6181     │  │    :6183     │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│         │                                                │
│         ├──────────────┐                                 │
│         │              │                                 │
│  ┌──────────────┐  ┌──────────────┐                    │
│  │    MinIO     │  │   Adminer    │                    │
│  │   Storage    │  │   DB Admin   │                    │
│  │ :6185/:6187  │  │    :6184     │                    │
│  └──────────────┘  └──────────────┘                    │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

### 数据库表结构

#### 核心表
- **users** - 用户表（UUID 主键）
- **user_sessions** - 会话表（JWT 令牌管理）
- **folders** - 文件夹表（树形结构，支持分类）
- **folder_members** - 文件夹成员表（权限管理）
- **folder_shares** - 文件夹分享表
- **folder_export_jobs** - 文件夹导出任务表

#### 项目表
- **projects** - 项目表（UUID v7 主键）
- **project_members** - 项目成员表
- **project_shares** - 项目分享表
- **project_versions** - 项目版本表（预留）

#### AI 服务表
- **ai_models** - AI 模型配置表
- **ai_jobs** - AI 任务记录表
- **ai_usage_logs** - AI 使用日志表
- **ai_quotas** - AI 配额管理表

### 数据库特性

- **UUID v7**: 所有主键使用 UUID v7（时间排序）
- **SMALLINT 枚举**: 使用 SMALLINT (1-255) 代替 PostgreSQL ENUM
- **软删除**: 使用 `deleted_at` 时间戳
- **自动时间戳**: `created_at`, `updated_at` 自动维护
- **GIN 索引**: JSONB 字段使用 GIN 索引优化查询
- **外键约束**: 完整的外键关系和级联删除

## 迁移脚本

### 已执行的迁移

1. **001_uuid_migration.py** - UUID v7 迁移
2. **002_folder_enhancement.py** - 文件夹功能增强
3. **003_project_tables.py** - 项目表创建
4. **004_add_folder_category.py** - 文件夹分类
5. **005_project_status_enhancement.py** - 项目状态增强
6. **006_folder_enum_to_smallint.py** - 文件夹枚举重构
7. **007_ai_service_tables.py** - AI 服务表创建

### 执行迁移

```bash
# 执行所有迁移
./migrate_db.sh

# 执行特定迁移
python run_migration.py --migration 007

# 查看迁移状态
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\dt"
```

## 性能优化

### 数据库优化

```sql
-- 查看慢查询
SELECT * FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;

-- 查看索引使用情况
SELECT * FROM pg_stat_user_indexes;

-- 分析表统计信息
ANALYZE users;
ANALYZE projects;
ANALYZE folders;
```

### Redis 缓存

```bash
# 查看 Redis 信息
docker exec jointo-server-redis redis-cli INFO

# 查看缓存键
docker exec jointo-server-redis redis-cli KEYS "*"

# 清空缓存
docker exec jointo-server-redis redis-cli FLUSHDB
```

## 相关文档

### 架构文档
- [技术栈规范](../../docs/architecture/tech-stack.md)
- [UUID v7 迁移 ADR](../../docs/architecture/adrs/001-uuid-v7-migration.md)
- [PostgreSQL 17 升级 ADR](../../docs/architecture/adrs/002-postgresql-17-uuid-v7.md)
- [枚举类型重构 ADR](../../docs/architecture/adrs/005-variant-to-tag-system-refactor.md)

### 后端文档
- [Folder 服务 RFC](../../docs/server/rfcs/016-folder-service-implementation.md)
- [项目服务 RFC](../../docs/server/rfcs/121-project-service-implementation.md)
- [AI 服务实现](../../docs/server/changelogs/2026-01-23-ai-service-implementation.md)
- [枚举重构 RFC](../../docs/server/rfcs/130-enum-to-smallint-refactor.md)

### 需求文档
- [API 设计规范](../../docs/requirements/api-design-specification.md)
- [数据库设计](../../docs/requirements/database-design.md)
- [后端架构](../../docs/requirements/backend/01-architecture-overview.md)

---

**维护者**: Jointo 开发团队  
**最后更新**: 2026-01-24