项目架构指南

本文档介绍 Vibany 项目的整体架构设计,帮助开发者理解系统结构和各模块职责。

技术栈概览

层级技术说明
前端框架Next.js 16 + React 19App 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. 部署策略

  • 蓝绿部署
  • 金丝雀发布
  • 回滚机制
  • 版本管理

相关文档

© copyright Justin 2026. All rights reserved.