# 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 (可选)
```graphql
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!
}
```

## 部署架构

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

### 生产环境
```yaml
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网站账号共享系统提供了坚实的基础。