first commit

2025-07-08 00:52:10 +08:00
commit aa2416c5d6
69 changed files with 16628 additions and 0 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,288 @@
+# 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网站账号共享系统提供了坚实的基础。