架构
了解 VideoFly 的架构和设计决策
项目架构
VideoFly 是一个基于 Next.js 15 的单体应用架构,采用模块化设计,便于维护和扩展。
技术栈
核心框架
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | 15.5 | React 全栈框架 |
| React | 19.2 | UI 库 |
| TypeScript | 5.4 | 类型系统 |
数据层
| 技术 | 版本 | 用途 |
|---|---|---|
| PostgreSQL | - | 关系型数据库 |
| Drizzle ORM | 0.45 | 类型安全的 ORM |
| Neon | - | 托管数据库(推荐) |
身份验证
| 技术 | 版本 | 用途 |
|---|---|---|
| Better Auth | 1.4 | 身份验证解决方案 |
| next-intl | 4.7 | 国际化 |
UI 组件
| 技术 | 版本 | 用途 |
|---|---|---|
| Tailwind CSS | 4.0 | 样式框架 |
| shadcn/ui | - | UI 组件库 |
| Magic UI | - | 动画组件 |
| Animate UI | - | 动画效果 |
| Framer Motion | 12.2 | React 动画库 |
| Three.js | 0.163 | 3D 渲染 |
状态管理
| 技术 | 版本 | 用途 |
|---|---|---|
| Zustand | 5.0 | 状态管理 |
| TanStack Query | 5.90 | 数据同步 |
表单验证
| 技术 | 版本 | 用途 |
|---|---|---|
| React Hook Form | 7.71 | 表单管理 |
| Zod | 4.2 | 模式验证 |
支付集成
| 技术 | 用途 |
|---|---|
| Creem | 主要支付提供商 |
| Stripe | 备用支付提供商 |
存储
| 技术 | 用途 |
|---|---|
| R2/S3 | 对象存储(兼容) |
邮件
| 技术 | 用途 |
|---|---|
| Resend | 邮件发送服务 |
目录结构
应用层 (src/app/)
Next.js App Router 的核心目录,包含所有页面和 API 路由。
组件层 (src/components/)
所有 React 组件的统一目录。
服务层 (src/services/)
业务逻辑的核心层,封装了所有复杂的业务操作。
| 文件 | 职责 |
|---|---|
credit.ts | 积分系统(冻结/结算/释放) |
video.ts | 视频生成服务 |
customer.ts | 客户管理 |
billing.ts | 账单管理 |
k8s.ts | K8s 集群管理 |
AI 层 (src/ai/)
AI 提供商的抽象层,统一接口管理多个 AI 服务。
数据层 (src/db/)
数据库 Schema 和连接管理。
核心模块
1. 积分系统
采用 FIFO(先进先出) 消费模式,确保积分公平过期。
2. AI 视频生成
统一的 AI 提供商接口,支持多个 AI 服务:
支持流程:
3. 身份验证
由 Better Auth 驱动的完整认证系统:
- 邮箱/密码登录
- Google OAuth
- GitHub OAuth(可选)
- 魔法链接登录
- 会话管理
4. 支付集成
支持两种支付提供商:
| 提供商 | 状态 | 功能 |
|---|---|---|
| Creem | 主要 | 订阅、一次性购买 |
| Stripe | 备用 | 订阅、一次性购买 |
API 设计
REST API v1
所有业务 API 都在 /api/v1/ 路径下:
| 端点 | 方法 | 功能 |
|---|---|---|
/api/v1/user/me | GET | 获取当前用户 |
/api/v1/credit/balance | GET | 获取积分余额 |
/api/v1/credit/history | GET | 获取积分历史 |
/api/v1/video/generate | POST | 创建视频生成任务 |
/api/v1/video/list | GET | 获取视频列表 |
/api/v1/video/[uuid] | GET/DELETE | 获取/删除视频 |
/api/v1/video/[uuid]/status | GET | 轮询视频状态 |
/api/v1/upload/presign | POST | 获取预签名上传 URL |
Auth API
由 Better Auth 自动处理,位于 /api/auth/。
数据库 Schema
核心表
| 表名 | 用途 |
|---|---|
users | 用户信息 |
sessions | 会话管理 |
accounts | OAuth 账户 |
credit_packages | 积分包 |
credit_holds | 积分冻结记录 |
credit_transactions | 积分交易历史 |
videos | 视频生成记录 |
customers | 客户信息 |
creem_subscriptions | 订阅信息 |
枚举类型
状态管理
Zustand Store
TanStack Query
用于服务端状态同步:
国际化
使用 next-intl 实现中英文双语:
路由结构:/[locale]/...
设计决策
为什么选择 Drizzle ORM?
类型安全: Drizzle 提供完整的 TypeScript 类型推导,无需手动维护类型定义。
轻量级: 相比 Prisma,Drizzle 的运行时开销更小。
SQL 优先: 不隐藏 SQL,开发者可以完全控制查询。
为什么选择 Better Auth?
现代设计: 专为全栈框架设计,与 Next.js 完美集成。
灵活: 支持多种认证方式,易于扩展。
类型安全: 端到端的类型安全认证体验。
为什么选择单体应用?
简化部署: 无需管理多个应用和复杂的微服务通信。
快速迭代: 所有代码在一个仓库中,开发和部署更简单。
成本更低: 单一部署,基础设施成本更低。
性能优化
1. 静态生成
尽可能使用 generateStaticParams 预生成页面。
2. 数据库索引
在常用查询字段上创建索引:
3. CDN 加速
静态资源和视频文件都通过 CDN 分发。
4. 缓存策略
使用 TanStack Query 的缓存功能减少重复请求。
安全性
1. 环境变量
敏感信息(API 密钥、数据库凭证)都通过环境变量管理。
2. SQL 注入防护
使用 Drizzle ORM 的参数化查询。
3. XSS 防护
React 自动转义用户输入,配合 zod 验证所有输入。
4. CSRF 保护
Better Auth 内置 CSRF 保护。