项目架构指南
本文档介绍 Vibany 项目的整体架构设计,帮助开发者理解系统结构和各模块职责。
技术栈概览
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端框架 | Next.js 16 + React 19 | App Router, Server Components |
| 编程语言 | TypeScript | 严格模式 |
| 样式方案 | Tailwind CSS + shadcn/ui | 原子化 CSS + 组件库 |
| 状态管理 | Zustand | 轻量级状态管理 |
| 数据库 | PostgreSQL + Drizzle ORM | 类型安全的数据库操作 |
| 认证 | Clerk | 用户认证和会话管理 |
| 存储 | Cloudflare R2 | 图片和视频存储 |
| AI 服务 | Tuzi, OpenAI, Gemini 等 | 图像生成 API |
目录结构
├── app/ # Next.js App Router
│ ├── (routes)/ # 页面路由
│ │ ├── page.tsx # 首页
│ │ ├── draw/ # AI 绘图页面
│ │ ├── explore/ # 探索/分享页面
│ │ ├── pricing/ # 价格页面
│ │ └── ...
│ ├── admin/ # 管理后台
│ │ ├── page.tsx # 仪表板
│ │ ├── users/ # 用户管理
│ │ ├── orders/ # 订单管理
│ │ └── ...
│ ├── api/ # API 路由
│ │ ├── admin/ # 管理员 API
│ │ ├── draw/ # 绘图 API
│ │ ├── public/ # 公开 API
│ │ └── ...
│ └── manuals/ # 文档页面
├── components/ # React 组件
│ ├── ui/ # shadcn/ui 基础组件
│ ├── draw/ # 绘图相关组件
│ ├── admin/ # 管理后台组件
│ ├── landing/ # 落地页组件
│ └── global/ # 全局组件
├── lib/ # 核心业务逻辑
│ ├── db/ # 数据库 schema 和查询
│ ├── ai/ # AI 模型集成
│ ├── draw/ # 绘图业务逻辑
│ ├── payment/ # 支付系统
│ ├── storage/ # 文件存储
│ └── utils/ # 工具函数
├── store/ # Zustand 状态管理
├── constants/ # 常量配置
│ ├── draw/models.ts # 绘图模型配置
│ └── chat/models.ts # LLM 模型配置
├── contents/manuals/ # MDX 文档
└── drizzle/ # 数据库迁移文件
核心模块架构
1. 认证层 (Authentication)
技术:Clerk
流程:
用户登录 → Clerk 验证 → 创建/更新本地用户 → 初始化钱包 → 跳转到首页
文件位置:
middleware.ts- 认证中间件app/login/page.tsx- 登录页面app/register/page.tsx- 注册页面lib/db/user.ts- 用户同步逻辑
2. 数据库层 (Database)
技术:PostgreSQL + Drizzle ORM
核心表:
// 用户相关
users - 用户基本信息
wallets - 用户积分钱包
// 业务数据
histories - 图像生成历史
videos - 视频生成历史
shares - 分享记录
favorites - 收藏记录
// 交易相关
orders - 充值订单
invitations - 邀请码
invitation_usages - 邀请使用记录
// 系统管理
blocklists - 黑名单
templates - 用户模板
executions - 异步任务执行记录
文件位置:
lib/db/schema.ts- 表结构定义lib/db/queries.ts- 常用查询drizzle/- 迁移文件
3. AI 服务层 (AI Services)
支持的提供商:
- Tuzi - 主要图像生成服务
- OpenAI - GPT-4o-image, DALL-E
- XAI - Grok 图像生成
- Gemini - Google 多模态模型
- Doubao - Seedream 系列
架构设计:
用户请求 → 模型选择 → 积分检查 → AI API 调用 → 结果处理 → 图片上传 → 历史记录
文件位置:
lib/ai/- AI 服务集成lib/draw/- 绘图业务逻辑constants/draw/models.ts- 模型配置
4. 存储层 (Storage)
技术:Cloudflare R2 (S3 兼容)
存储结构:
bucket/
├── images/ # 生成的图片
│ └── {userId}/
│ └── {historyId}/
├── temp/ # 临时文件
└── videos/ # 生成的视频
└── {userId}/
└── {videoId}/
文件位置:
lib/storage/r2.ts- R2 存储管理
5. 支付层 (Payment)
支持的支付方式:
- 易支付 - 支付宝/微信支付
- Stripe - 信用卡/国际支付
支付流程:
创建订单 → 生成支付链接 → 用户支付 → 回调通知 → 验证签名 → 充值积分 → 更新订单
文件位置:
lib/payment/- 易支付集成lib/stripe/- Stripe 集成app/api/public/epay/notify/- 易支付回调app/api/public/stripe/notify/- Stripe 回调
数据流架构
图像生成流程
1. 用户提交生成请求
↓
2. 验证用户权限和积分
↓
3. 检查并发限制
↓
4. 扣除积分
↓
5. 调用 AI API
↓
6. 等待生成完成
↓
7. 上传图片到 R2
↓
8. 保存历史记录
↓
9. 返回结果给用户
支付流程
1. 用户选择充值套餐
↓
2. 创建订单(PENDING)
↓
3. 生成支付二维码/链接
↓
4. 用户完成支付
↓
5. 支付平台发送回调
↓
6. 验证签名
↓
7. 更新订单(SUCCESS)
↓
8. 充值用户积分
↓
9. 处理邀请奖励(如果有)
安全架构
1. 认证安全
- Clerk 处理所有认证逻辑
- JWT Token 自动刷新
- Session 管理
- 多因素认证(可选)
2. API 安全
- Rate Limiting - 限流保护
- Input Validation - 输入验证
- SQL Injection - Drizzle ORM 防护
- CORS - 跨域控制
3. 数据安全
- 敏感信息加密 - 环境变量管理
- HTTPS - 全站加密
- 数据库安全 - 访问控制
- 备份策略 - 定期备份
性能优化
1. 前端优化
- Next.js Image - 图片优化
- Code Splitting - 代码分割
- Streaming - 流式渲染
- Caching - 客户端缓存
2. 后端优化
- Connection Pool - 数据库连接池
- Query Optimization - 查询优化
- Indexing - 索引策略
- Async Processing - 异步处理
3. 部署优化
- CDN - 静态资源 CDN
- Edge Functions - 边缘计算
- Compression - Gzip/Brotli 压缩
- Lazy Loading - 懒加载
扩展性设计
1. 水平扩展
- 无状态设计,支持多实例部署
- 数据库读写分离
- Redis 缓存层(可选)
2. 垂直扩展
- 模块化解耦
- 插件化架构
- 配置驱动
3. 功能扩展
- 新 AI 模型接入
- 新支付方式接入
- 新功能模块开发
监控与日志
1. 应用监控
- Vercel Analytics - 性能监控
- Error Tracking - 错误追踪
- Custom Metrics - 自定义指标
2. 业务监控
- Dashboard - 管理后台仪表板
- Logs - 应用日志
- Alerts - 告警通知
最佳实践
1. 代码规范
- TypeScript 严格模式
- ESLint + Prettier
- Conventional Commits
- 组件文档
2. 开发流程
- Git Flow 工作流
- Code Review
- CI/CD 自动化
- 测试策略
3. 部署策略
- 蓝绿部署
- 金丝雀发布
- 回滚机制
- 版本管理