13 KiB

Raw Blame History

Jointo 后端部署指南

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

快速开始

1. 一键启动所有服务

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. 数据库迁移

增量迁移（默认，安全）

./migrate_db.sh

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

清空迁移（危险）

./migrate_db.sh --fresh

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

查看帮助

./migrate_db.sh --help

常用命令

服务管理

# 启动服务
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

数据库操作

# 连接数据库（用户名：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;"

应用操作

# 进入应用容器
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	缓存服务

开发流程

首次启动

# 1. 进入 server 目录
cd server/

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

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

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

日常开发

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

# 查看日志
docker compose logs -f app

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

数据库变更

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

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

环境变量

配置文件

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

关键配置

# 应用配置
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

故障排查

服务无法启动

# 查看详细日志
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

数据库连接失败

# 检查 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

应用报错

# 查看应用日志
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 连接问题

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

# 查看 MinIO 日志
docker compose logs minio

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

生产部署

环境准备

修改 .env 配置（使用生产环境值）
- 设置强密码（数据库、Redis、MinIO）
- 修改 SECRET_KEY 为随机字符串
- 设置 DEBUG=False
- 配置正确的 CORS_ORIGINS
配置域名和 SSL 证书
- 使用 Nginx 反向代理
- 配置 Let's Encrypt SSL 证书
资源配置
- 调整 PostgreSQL 内存配置
- 配置 Redis 持久化
- 设置 MinIO 存储路径

部署步骤

# 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

备份与恢复

# 备份数据库
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 索引优化查询
外键约束: 完整的外键关系和级联删除

迁移脚本

已执行的迁移

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

执行迁移

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

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

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

性能优化

数据库优化

-- 查看慢查询
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 缓存

# 查看 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

13 KiB Raw Blame History

Jointo 后端部署指南

快速开始

1. 一键启动所有服务

2. 数据库迁移

增量迁移（默认，安全）

清空迁移（危险）

查看帮助

常用命令

服务管理

数据库操作

应用操作

访问地址

开发流程

首次启动

日常开发

数据库变更

环境变量

配置文件

关键配置

故障排查

服务无法启动

数据库连接失败

应用报错

MinIO 连接问题

生产部署

环境准备

部署步骤

备份与恢复

架构说明

服务架构

数据库表结构

核心表

项目表

AI 服务表

数据库特性

迁移脚本

已执行的迁移

执行迁移

性能优化

数据库优化

Redis 缓存

相关文档

架构文档

后端文档

需求文档

13 KiB

Raw Blame History