ai/ARCHITECTURE.md

Pandora 系统架构设计

整体架构

Pandora 采用现代化的微服务架构，前后端分离，支持容器化部署。

技术栈

前端: Vue 3 + TypeScript + Tailwind CSS + Vite 后端: Node.js + Express.js + TypeScript + Prisma 数据库: PostgreSQL + Redis 部署: Docker + Docker Compose + Nginx

核心功能模块

1. 用户认证系统 - 多路径登录、二步验证
2. 权限管理系统 - 基于角色的访问控制
3. 账号管理系统 - 网站账号token存储和分配
4. 后台管理系统 - 用户和权限管理界面

安全特性

• JWT身份验证
• 密码加密存储
• 二步验证(TOTP/邮箱)
• API限流保护
• 审计日志记录

部署架构

• 开发环境: Docker Compose
• 生产环境: 支持负载均衡和监控
• 数据库: PostgreSQL主从复制
• 缓存: Redis集群

数据库设计

核心表结构

• users: 用户信息
• paths: 登录路径
• user_paths: 用户路径权限
• website_accounts: 网站账号
• account_assignments: 账号分配
• sessions: 用户会话
• audit_logs: 审计日志

API设计

RESTful API设计，支持用户管理、权限管理、账号管理等核心功能。

监控和日志

• 健康检查端点
• 性能监控
• 错误追踪
• 访问日志

┌─────────────────────────────────────────────────────────────┐
│                        用户层                                │
├─────────────────────────────────────────────────────────────┤
│  Domain A (path1.com)  │  Domain B (path2.com)  │  Domain C │
└─────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────────────┐
                    │   Nginx Proxy   │
                    │   (Load Bal.)   │
                    └─────────────────┘
                              │
                    ┌─────────────────┐
                    │   Frontend      │
                    │   (React SPA)   │
                    └─────────────────┘
                              │
                    ┌─────────────────┐
                    │   Backend API   │
                    │   (Express.js)  │
                    └─────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   PostgreSQL    │  │     Redis       │  │   File Storage  │
│   (Main DB)     │  │   (Cache/Session)│  │   (Uploads)     │
└─────────────────┘  └─────────────────┘  └─────────────────┘

技术栈选择

前端技术栈

• React 18: 现代化的前端框架，支持并发特性
• TypeScript: 类型安全，提高开发效率和代码质量
• Vite: 快速的构建工具，支持热重载
• Tailwind CSS: 实用优先的CSS框架，快速构建UI
• React Router: 客户端路由管理
• React Query: 数据获取和缓存管理
• Zustand: 轻量级状态管理
• React Hook Form: 表单处理
• React Hot Toast: 通知组件

后端技术栈

• Node.js: JavaScript运行时
• Express.js: 轻量级Web框架
• TypeScript: 类型安全
• Prisma: 现代化数据库ORM
• PostgreSQL: 关系型数据库
• Redis: 缓存和会话存储
• JWT: 身份验证
• bcrypt: 密码加密
• nodemailer: 邮件发送
• speakeasy: TOTP生成

基础设施

• Docker: 容器化部署
• Docker Compose: 多服务编排
• Nginx: 反向代理和负载均衡
• Let's Encrypt: SSL证书

安全架构

认证机制

1. 多因素认证: 支持邮箱验证码和TOTP
2. JWT Token: 无状态的身份验证
3. 会话管理: Redis存储会话信息
4. 密码安全: bcrypt加密，支持盐值

权限控制

1. 基于角色的访问控制(RBAC): 用户、管理员、超级管理员
2. 路径权限: 用户只能访问被授权的路径
3. 账号权限: 用户只能访问被分配的账号
4. API权限: 基于角色的API访问控制

数据安全

1. 敏感数据加密: 使用AES加密存储token
2. SQL注入防护: 使用Prisma ORM
3. XSS防护: 输入验证和输出转义
4. CSRF防护: Token验证
5. 限流保护: API访问频率限制

API设计

RESTful API

认证相关:
POST   /api/auth/register     - 用户注册
POST   /api/auth/login        - 用户登录
POST   /api/auth/logout       - 用户登出
POST   /api/auth/verify-email - 邮箱验证
POST   /api/auth/verify-totp  - TOTP验证

用户管理:
GET    /api/users             - 获取用户列表
GET    /api/users/:id         - 获取用户详情
PUT    /api/users/:id         - 更新用户信息
DELETE /api/users/:id         - 删除用户

路径管理:
GET    /api/paths             - 获取路径列表
GET    /api/paths/:id         - 获取路径详情
POST   /api/paths             - 创建路径
PUT    /api/paths/:id         - 更新路径
DELETE /api/paths/:id         - 删除路径

账号管理:
GET    /api/accounts          - 获取账号列表
GET    /api/accounts/:id      - 获取账号详情
POST   /api/accounts          - 创建账号
PUT    /api/accounts/:id      - 更新账号
DELETE /api/accounts/:id      - 删除账号

权限管理:
GET    /api/permissions       - 获取权限列表
POST   /api/permissions       - 分配权限
DELETE /api/permissions/:id   - 撤销权限

GraphQL API (可选)

type Query {
  users: [User!]!
  user(id: ID!): User
  paths: [Path!]!
  accounts: [Account!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  assignPermission(input: AssignPermissionInput!): Permission!
}

部署架构

开发环境

services:
  postgres: PostgreSQL 数据库
  redis: Redis 缓存
  backend: Express.js API 服务
  frontend: React 开发服务器
  nginx: 反向代理

生产环境

services:
  postgres: PostgreSQL 数据库 (主从复制)
  redis: Redis 集群
  backend: Express.js API 服务 (负载均衡)
  frontend: Nginx 静态文件服务
  nginx: 反向代理和SSL终止
  prometheus: 监控服务
  grafana: 监控面板

监控和日志

应用监控

• 健康检查: 每个服务都有健康检查端点
• 性能监控: 使用Prometheus收集指标
• 错误追踪: 集成错误监控服务
• 日志聚合: 集中化日志管理

安全监控

• 访问日志: 记录所有API访问
• 审计日志: 记录敏感操作
• 异常检测: 检测异常访问模式
• 实时告警: 安全事件实时通知

扩展性设计

水平扩展

• 无状态设计: 后端服务无状态，支持水平扩展
• 数据库分片: 支持数据库水平分片
• 缓存分层: 多级缓存策略
• CDN集成: 静态资源CDN加速

功能扩展

• 插件系统: 支持功能插件扩展
• API版本控制: 支持API版本管理
• 多租户: 支持多租户架构
• 国际化: 支持多语言

性能优化

前端优化

• 代码分割: 按路由分割代码
• 懒加载: 组件和图片懒加载
• 缓存策略: 静态资源缓存
• 预加载: 关键资源预加载

后端优化

• 数据库索引: 优化查询性能
• 连接池: 数据库连接池管理
• 缓存策略: Redis缓存热点数据
• 异步处理: 非关键操作异步处理

故障恢复

高可用性

• 服务冗余: 关键服务多实例部署
• 数据库备份: 定期数据库备份
• 故障转移: 自动故障转移机制
• 灾难恢复: 完整的灾难恢复计划

数据保护

• 数据备份: 定期数据备份
• 版本控制: 数据版本管理
• 加密存储: 敏感数据加密
• 访问控制: 严格的数据访问控制

开发流程

代码管理

• Git工作流: 基于Git的版本控制
• 代码审查: 强制代码审查
• 自动化测试: 单元测试和集成测试
• CI/CD: 持续集成和部署

质量保证

• 代码规范: ESLint和Prettier
• 类型检查: TypeScript严格模式
• 测试覆盖: 高测试覆盖率
• 安全扫描: 定期安全扫描

这个架构设计确保了系统的安全性、可扩展性和可维护性，为Pandora网站账号共享系统提供了坚实的基础。