video-gen/DEPLOYMENT.md

VideoGen 部署文档

项目结构

video_item/
├── video-gen-api/          # 后端 (Python FastAPI)
├── video-gen-app/          # 前台 (React + Vite)
├── video-gen-admin/        # 后台管理 (React + Vite)
└── DEPLOYMENT.md           # 本文档

一、环境要求

组件	版本要求
Python	>= 3.10
Node.js	>= 18
PostgreSQL	>= 14
Redis	>= 6 (可选)

---

二、后端部署 (video-gen-api)

1. 安装依赖

cd video-gen-api

# 创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 安装依赖 (生产环境带 PostgreSQL 支持)
pip install -e ".[pg]"
# 如需 Redis 支持
pip install -e ".[pg,redis]"

2. 配置环境变量

复制 .env.example 为 .env，修改以下关键配置：

cp .env.example .env

# App
APP_NAME=VideoGen API
DEBUG=false
SECRET_KEY=改成一个随机的长字符串

# Database - PostgreSQL
DATABASE_URL=postgresql+asyncpg://用户名:密码@localhost:5432/videogen

# Redis (可选，不填则禁用)
REDIS_URL=redis://localhost:6379/0

# JWT
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440

# 视频生成引擎 (火山引擎)
SEEDANCE_API_KEY=你的API Key
SEEDANCE_API_BASE=https://ark.cn-beijing.volces.com/api/v3
SEEDANCE_CALLBACK_URL=https://你的域名/api/generation-records/callback

# LLM 提示词优化 (通过后台模型配置管理，此处为 fallback)
LLM_MOCK=false

# 加密 (32字节 base64)
ENCRYPTION_KEY=你的32字节base64密钥

# 存储
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./storage/videos

# 跨域 - 填写前端域名
CORS_ORIGINS=["https://你的前台域名.com", "https://你的后台域名.com"]

3. 初始化数据库

# 创建 PostgreSQL 数据库
psql -U postgres -c "CREATE DATABASE videogen OWNER videogen;"

# 启动后端，自动建表和种子数据
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

首次启动会自动：

• 创建所有数据表
• 创建管理员账号: admin / admin123
• 创建演示用户: demo / demo123
• 填充系统配置、菜单、充值套餐等初始数据
• 行业需要在后台手动添加

4. 数据库迁移 (Alembic)

项目使用 Alembic 管理数据库结构变更。

cd video-gen-api

# 修改 model 后，自动生成迁移文件
python -m alembic revision --autogenerate -m "描述改动内容"

# 执行迁移
python -m alembic upgrade head

# 查看当前版本
python -m alembic current

# 查看迁移历史
python -m alembic history

部署流程： 拉取代码后先执行 alembic upgrade head，再重启后端服务。

新增 model 时： 需要在 alembic/env.py 中添加对应的 import。

5. 生产运行

# 方式一：直接运行
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

# 方式二：使用 systemd (Linux)

systemd 服务文件 /etc/systemd/system/videogen-api.service:

[Unit]
Description=VideoGen API
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/video-gen-api
Environment=PATH=/opt/video-gen-api/.venv/bin
ExecStart=/opt/video-gen-api/.venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable videogen-api
sudo systemctl start videogen-api

6. Nginx 反向代理

server {
    listen 80;
    server_name api.yourdomain.com;

    # 上传文件大小限制
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }

    # 静态文件 (上传的视频/图片)
    location /uploads/ {
        alias /opt/video-gen-api/uploads/;
        expires 7d;
    }
}

---

三、前台部署 (video-gen-app)

1. 安装依赖 & 构建

cd video-gen-app

npm install

# 配置 API 地址
# 创建 .env.production
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production

# 构建
npm run build

构建产物在 dist/ 目录。

2. Nginx 配置

server {
    listen 80;
    server_name yourdomain.com;
    root /opt/video-gen-app/dist;
    index index.html;

    # SPA 路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

---

四、后台管理部署 (video-gen-admin)

1. 安装依赖 & 构建

cd video-gen-admin

npm install

# 配置 API 地址
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production

# 构建
npm run build

2. Nginx 配置

server {
    listen 80;
    server_name admin.yourdomain.com;
    root /opt/video-gen-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

---

五、完整 Nginx 配置示例 (单机部署)

# 后端 API
server {
    listen 80;
    server_name api.yourdomain.com;
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }

    location /uploads/ {
        alias /opt/video-gen-api/uploads/;
        expires 7d;
    }
}

# 前台
server {
    listen 80;
    server_name yourdomain.com;
    root /opt/video-gen-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
    }
}

# 后台管理
server {
    listen 80;
    server_name admin.yourdomain.com;
    root /opt/video-gen-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
    }
}

---

六、SSL 配置 (推荐)

使用 Certbot 获取免费证书：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain.com

---

七、默认账号

角色	用户名	手机号	密码	积分
管理员	admin	13800000000	admin123	10000
演示用户	demo	13800000001	demo123	2680

首次部署后务必修改默认密码。

---

八、目录结构 (部署后)

/opt/
├── video-gen-api/              # 后端
│   ├── .env                    # 环境变量
│   ├── .venv/                  # Python 虚拟环境
│   ├── app/                    # 应用代码
│   ├── uploads/                # 上传文件
│   └── storage/videos/         # 生成的视频
├── video-gen-app/dist/         # 前台构建产物
└── video-gen-admin/dist/       # 后台构建产物

---

九、常用运维命令

# 查看后端日志
sudo journalctl -u videogen-api -f

# 重启后端
sudo systemctl restart videogen-api

# 重新构建前端
cd /opt/video-gen-app && npm run build
cd /opt/video-gen-admin && npm run build

# 数据库备份
pg_dump -U videogen videogen > backup_$(date +%Y%m%d).sql

# 数据库恢复
psql -U videogen videogen < backup_20260512.sql