143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
# ViGent2 后端开发指南
|
||
|
||
本文档为后端开发人员提供架构概览、接口规范以及开发流程指南。
|
||
|
||
---
|
||
|
||
## 🏗️ 架构概览
|
||
|
||
后端采用 **FastAPI** 框架，基于 Python 3.10+ 构建，主要负责业务逻辑处理、AI 任务调度以及与各微服务组件的交互。
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── api/ # API 路由定义 (endpoints)
|
||
│ ├── core/ # 核心配置 (config.py, security.py)
|
||
│ ├── models/ # Pydantic 数据模型 (schemas)
|
||
│ ├── services/ # 业务逻辑服务层
|
||
│ │ ├── auth_service.py # 用户认证服务
|
||
│ │ ├── glm_service.py # GLM-4 大模型服务
|
||
│ │ ├── lipsync_service.py # LatentSync 唇形同步
|
||
│ │ ├── publish_service.py # 社交媒体发布
|
||
│ │ └── voice_clone_service.py# Qwen3-TTS 声音克隆
|
||
│ └── tests/ # 单元测试与集成测试
|
||
├── scripts/ # 运维脚本 (watchdog.py, init_db.py)
|
||
└── requirements.txt # 依赖清单
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API 接口规范
|
||
|
||
后端服务默认运行在 `8006` 端口。
|
||
|
||
- **文档地址**: `http://localhost:8006/docs` (Swagger UI)
|
||
- **认证方式**: Bearer Token (JWT)
|
||
|
||
### 核心模块
|
||
|
||
1. **认证 (Auth)**
|
||
* `POST /api/auth/login`: 用户登录 (手机号)
|
||
* `POST /api/auth/register`: 用户注册
|
||
* `GET /api/auth/me`: 获取当前用户信息
|
||
|
||
2. **视频生成 (Videos)**
|
||
* `POST /api/videos/generate`: 提交生成任务
|
||
* `GET /api/videos/{task_id}`: 查询任务状态
|
||
* `GET /api/videos/history`: 获取历史视频列表
|
||
|
||
3. **素材管理 (Materials)**
|
||
* `POST /api/materials/upload`: 上传素材 (Direct Upload to Supabase)
|
||
* `GET /api/materials`: 获取素材列表
|
||
|
||
4. **社交发布 (Publish)**
|
||
* `POST /api/publish`: 发布视频到 B站/抖音/小红书
|
||
|
||
---
|
||
|
||
## 🛠️ 开发环境搭建
|
||
|
||
### 1. 虚拟环境
|
||
|
||
```bash
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/macOS
|
||
# .\venv\Scripts\activate # Windows
|
||
```
|
||
|
||
### 2. 依赖安装
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 环境变量配置
|
||
|
||
复制 `.env.example` 到 `.env` 并配置必要的 Key：
|
||
|
||
```ini
|
||
# Supabase
|
||
SUPABASE_URL=http://localhost:8008
|
||
SUPABASE_KEY=your_service_role_key
|
||
|
||
# GLM API (用于 AI 标题生成)
|
||
GLM_API_KEY=your_glm_api_key
|
||
|
||
# LatentSync 配置
|
||
LATENTSYNC_GPU_ID=1
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
**开发模式 (热重载)**:
|
||
```bash
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🧩 服务集成指南
|
||
|
||
### 集成新模型
|
||
|
||
如果需要集成新的 AI 模型 (例如新的 TTS 引擎)：
|
||
|
||
1. 在 `app/services/` 下创建新的 Service 类 (如 `NewTTSService`)。
|
||
2. 实现 `generate` 方法，可以使用 subprocess 调用，也可以是 HTTP 请求。
|
||
3. **重要**: 如果模型占用 GPU，请务必使用 `asyncio.Lock` 进行并发控制，防止 OOM。
|
||
4. 在 `app/api/` 中添加对应的路由调用。
|
||
|
||
### 添加定时任务
|
||
|
||
目前推荐使用 **APScheduler** 或 **Crontab** 来管理定时任务。
|
||
社交媒体的定时发布功能目前依赖 `playwright` 的延迟执行，未来计划迁移到 Celery 队列。
|
||
|
||
---
|
||
|
||
## 🛡️ 错误处理
|
||
|
||
全项目统一使用 `Loguru` 进行日志记录。
|
||
|
||
```python
|
||
from loguru import logger
|
||
|
||
try:
|
||
# 业务逻辑
|
||
except Exception as e:
|
||
logger.error(f"操作失败: {str(e)}")
|
||
raise HTTPException(status_code=500, detail="服务器内部错误")
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
运行测试套件：
|
||
|
||
```bash
|
||
pytest
|
||
```
|