f9f4560459
- FastAPI backend with SQLModel, Alembic migrations, AgentScope agents - Next.js 15 frontend with React 19, Tailwind, Zustand, React Flow - Multi-provider AI system (DashScope, Kling, MiniMax, Volcengine, OpenAI, etc.) - All HTTP clients migrated from sync requests to async httpx - Admin-managed API keys via environment variables - SSRF vulnerability fixed in ensure_url()
337 lines
8.1 KiB
Markdown
337 lines
8.1 KiB
Markdown
# Pixel - AI 视频创作平台
|
||
|
||
[English Documentation](README.md)
|
||
|
||
Pixel 是一个智能平台，利用 AI 从剧本创作漫画和视频。它简化了从剧本编写到素材管理、分镜生成以及最终视频制作的整个工作流，利用多智能体系统（Multi-Agent Systems）和先进的生成式模型提供强大的创作支持。
|
||
|
||
## ✨ 功能特性
|
||
|
||
- **智能剧本分析**：
|
||
- 自动解析剧本，识别角色、场景和道具。
|
||
- **Agent 工作流**：利用基于 AgentScope 的专用智能体进行深度的剧本理解和拆解。
|
||
- **多模型 AI 支持**：
|
||
- **LLM**: DashScope (通义千问), Google (Gemini), VolcEngine (豆包)。
|
||
- **生图**: Flux 1.1 Pro, 通义万相 (Wanx), 可图 (Kolors)。
|
||
- **生视频**: 可灵 (Kling 1.5), 海螺 (Hailuo/MiniMax), CogVideoX, 通义万相 2.1。
|
||
- **素材管理**：集中的“素材中心”，用于管理和编辑创意素材。
|
||
- **AI 分镜**：利用 AI 图像生成技术，根据剧本描述生成可视化分镜，并支持风格一致性控制。
|
||
- **视频生成与编辑**：
|
||
- 将静态分镜转化为动态视频。
|
||
- **精细控制**：支持首/尾帧控制、运镜控制（推拉摇移）、以及 Motion Bucket 参数调节。
|
||
- **无限画布**：基于节点的自由创作工作区（由 React Flow 驱动），支持多选拖拽、丝滑缩放和灵活的节点连接。
|
||
- **项目管理**：在结构化的工作区中组织您的创意作品，支持集（Episode）和场（Scene）管理。
|
||
|
||
## 🏗 架构
|
||
|
||
本项目采用 Monorepo 结构，后端采用清晰的三层架构：
|
||
|
||
- **`frontend/`**: 基于 **Next.js 15** (App Router) 的前端应用，使用 **React 19**、Tailwind CSS 和 `@xyflow/react` 构建画布界面。
|
||
- **`backend/`**: 基于 **FastAPI** 的后端服务，采用三层架构（API层、服务层、仓储层）。使用 **AgentScope** 进行智能体编排，并通过插件系统支持多种 AI 模型提供商。
|
||
|
||
## 📚 文档
|
||
|
||
完整的技术文档：
|
||
|
||
- **[ARCHITECTURE.md](ARCHITECTURE.md)**: 完整的系统架构、设计决策和技术栈
|
||
- **[backend/README.md](backend/README.md)**: 后端设置、API文档和开发指南
|
||
- **[frontend/README.md](frontend/README.md)**: 前端设置、组件结构和开发指南
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- **Node.js**: v20 或更高版本 (Next.js 15 必需)
|
||
- **Python**: v3.12 或更高版本
|
||
- **包管理器**: `pnpm` (前端), `uv` (后端 - 推荐)
|
||
- **Redis**: v7+ (可选但推荐用于缓存)
|
||
- **PostgreSQL**: v15+ (生产环境，开发环境使用 SQLite)
|
||
- **API Keys**: 根据使用的模型准备 阿里云 DashScope, 火山引擎 VolcEngine 或 Google AI Studio 的 Key
|
||
|
||
### 安装步骤
|
||
|
||
#### 1. 克隆仓库
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd pixel
|
||
```
|
||
|
||
#### 2. 后端设置
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 安装 uv（如果尚未安装）
|
||
pip install uv
|
||
|
||
# 安装依赖
|
||
uv sync
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入您的 API Keys
|
||
|
||
# 运行数据库迁移
|
||
alembic upgrade head
|
||
|
||
# 启动后端服务器
|
||
./start.sh
|
||
# 或手动运行: uv run uvicorn src.main:app --reload --port 8000
|
||
```
|
||
|
||
后端将在 http://localhost:8000 运行
|
||
|
||
#### 3. 前端设置
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
```
|
||
|
||
前端将在 http://localhost:3000 运行
|
||
|
||
### 环境配置
|
||
|
||
在 `backend/` 目录中创建 `.env` 文件：
|
||
|
||
```env
|
||
# AI 提供商
|
||
DASHSCOPE_API_KEY=your_dashscope_key
|
||
VOLCENGINE_ACCESS_KEY=your_volcengine_key
|
||
VOLCENGINE_SECRET_KEY=your_volcengine_secret
|
||
GOOGLE_API_KEY=your_google_key
|
||
KLING_API_KEY=your_kling_key
|
||
|
||
# 存储
|
||
OSS_ACCESS_KEY_ID=your_oss_key
|
||
OSS_ACCESS_KEY_SECRET=your_oss_secret
|
||
|
||
# 数据库（可选 - 默认使用 SQLite）
|
||
DATABASE_URL=postgresql://user:pass@localhost/pixel
|
||
|
||
# Redis（可选但推荐）
|
||
REDIS_URL=redis://localhost:6379
|
||
|
||
# 监控
|
||
ENABLE_METRICS=true
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
### Docker 部署（可选）
|
||
|
||
```bash
|
||
# 构建并启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
## 🔌 API 文档
|
||
|
||
后端提供完整的 RESTful API 文档：
|
||
|
||
- **[API 文档](docs/API.md)**: 完整的 API 参考和示例
|
||
- **交互式文档**: http://localhost:8000/docs (Swagger UI)
|
||
- **ReDoc**: http://localhost:8000/redoc
|
||
- **OpenAPI 规范**: http://localhost:8000/openapi.json
|
||
|
||
### 核心端点
|
||
|
||
* **生图**: `POST /api/v1/generations/image`
|
||
* **生视频**: `POST /api/v1/generations/video`
|
||
* **剧本分析**: `POST /api/v1/script/analyze`
|
||
* **任务状态**: `GET /api/v1/tasks/{task_id}`
|
||
* **项目管理**: `/api/v1/projects/*`
|
||
* **画布操作**: `/api/v1/canvas/*`
|
||
|
||
### 交互式文档
|
||
|
||
- **Swagger UI**: http://localhost:8000/docs
|
||
- **ReDoc**: http://localhost:8000/redoc
|
||
- **OpenAPI 规范**: http://localhost:8000/openapi.json
|
||
|
||
所有生成接口均支持 `extra_params` 字段，用于直接向底层 SDK 传递模型特定参数。
|
||
|
||
## 🧪 开发
|
||
|
||
### 运行测试
|
||
|
||
**后端:**
|
||
```bash
|
||
cd backend
|
||
pytest # 运行所有测试
|
||
pytest tests/test_integration.py # 运行集成测试
|
||
pytest --cov=src # 运行并生成覆盖率报告
|
||
```
|
||
|
||
**前端:**
|
||
```bash
|
||
cd frontend
|
||
pnpm test # 运行所有测试
|
||
pnpm test:watch # 监听模式运行
|
||
pnpm test:coverage # 运行并生成覆盖率报告
|
||
```
|
||
|
||
### 代码质量
|
||
|
||
**后端:**
|
||
```bash
|
||
# 格式化代码
|
||
black src/
|
||
isort src/
|
||
|
||
# 代码检查
|
||
flake8 src/
|
||
mypy src/
|
||
```
|
||
|
||
**前端:**
|
||
```bash
|
||
# 代码检查
|
||
pnpm lint
|
||
|
||
# 类型检查
|
||
pnpm type-check
|
||
|
||
# 格式化
|
||
pnpm format
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 创建新迁移
|
||
alembic revision --autogenerate -m "描述"
|
||
|
||
# 应用迁移
|
||
alembic upgrade head
|
||
|
||
# 回滚一个迁移
|
||
alembic downgrade -1
|
||
```
|
||
|
||
### API 类型生成
|
||
|
||
当后端 API 变更时，重新生成前端类型：
|
||
|
||
```bash
|
||
cd frontend
|
||
pnpm gen:api
|
||
```
|
||
|
||
## 📊 监控
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
### 指标（Prometheus）
|
||
|
||
```bash
|
||
curl http://localhost:8000/metrics
|
||
```
|
||
|
||
### 日志
|
||
|
||
后端日志采用 JSON 格式，便于解析：
|
||
```bash
|
||
tail -f backend/logs/app.log | jq
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||
5. 开启 Pull Request
|
||
|
||
### 开发指南
|
||
|
||
- 遵循三层架构（API层、服务层、仓储层）
|
||
- 为新功能编写测试
|
||
- 更新文档
|
||
- 遵循代码风格指南
|
||
- 使用约定式提交
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 后端问题
|
||
|
||
**Redis 连接错误:**
|
||
```bash
|
||
# 检查 Redis 是否运行
|
||
redis-cli ping
|
||
# 应返回: PONG
|
||
```
|
||
|
||
**数据库连接错误:**
|
||
```bash
|
||
# 检查数据库连接
|
||
psql -h localhost -U user -d pixel
|
||
```
|
||
|
||
**导入错误:**
|
||
```bash
|
||
# 重新安装依赖
|
||
uv sync --reinstall
|
||
```
|
||
|
||
### 前端问题
|
||
|
||
**模块未找到:**
|
||
```bash
|
||
# 清除缓存并重新安装
|
||
rm -rf node_modules .next
|
||
pnpm install
|
||
```
|
||
|
||
**API 类型不匹配:**
|
||
```bash
|
||
# 重新生成 API 类型
|
||
pnpm gen:api
|
||
```
|
||
|
||
## 📦 项目结构
|
||
|
||
```
|
||
pixel/
|
||
├── backend/ # FastAPI 后端
|
||
│ ├── src/
|
||
│ │ ├── controllers/ # API 层（HTTP 处理）
|
||
│ │ ├── services/ # 服务层（业务逻辑）
|
||
│ │ ├── repositories/ # 仓储层（数据访问）
|
||
│ │ ├── models/ # 数据模型（实体和模式）
|
||
│ │ ├── middlewares/ # API 中间件
|
||
│ │ └── utils/ # 工具函数
|
||
│ ├── tests/ # 测试套件
|
||
│ └── alembic/ # 数据库迁移
|
||
├── frontend/ # Next.js 前端
|
||
│ ├── src/
|
||
│ │ ├── app/ # Next.js 页面（App Router）
|
||
│ │ ├── components/ # React 组件
|
||
│ │ ├── lib/ # 工具和服务
|
||
│ │ └── store/ # 状态管理（Zustand）
|
||
│ └── tests/ # 测试套件
|
||
├── docs/ # 文档
|
||
├── ARCHITECTURE.md # 架构文档
|
||
└── docker-compose.yml # Docker 配置
|
||
```
|
||
|
||
## 📄 许可证
|
||
|
||
MIT
|