first commit

2025-07-08 00:52:10 +08:00
commit aa2416c5d6
69 changed files with 16628 additions and 0 deletions
--- a/backend/README.md
+++ b/backend/README.md
@@ -0,0 +1,347 @@
+# Pandora 后端 API
+
+这是 Pandora 项目的后端 API 服务，提供完整的用户认证系统和权限管理功能。
+
+## 🚀 功能特性
+
+### 用户认证系统
+- ✅ 用户注册和登录
+- ✅ JWT 令牌认证
+- ✅ 邮箱验证
+- ✅ 密码重置
+- ✅ TOTP 二步验证
+- ✅ 会话管理
+- ✅ 密码加密 (bcrypt)
+
+### 权限管理系统
+- ✅ 基于角色的权限控制
+- ✅ 路径权限验证
+- ✅ 用户权限分配
+- ✅ 权限审计日志
+
+### 账号管理系统
+- ✅ 网站账号管理
+- ✅ 账号分配和撤销
+- ✅ 账号使用统计
+- ✅ 多用户共享控制
+
+### 安全特性
+- ✅ API 限流
+- ✅ CORS 配置
+- ✅ 安全头部 (Helmet)
+- ✅ 输入验证
+- ✅ 错误处理
+- ✅ 审计日志
+
+## 📋 技术栈
+
+- **运行时**: Node.js + TypeScript
+- **框架**: Express.js
+- **数据库**: PostgreSQL + Prisma ORM
+- **缓存**: Redis
+- **认证**: JWT + bcrypt
+- **二步验证**: TOTP (Google Authenticator)
+- **邮件**: Nodemailer
+- **日志**: Winston
+- **验证**: express-validator
+
+## 🛠️ 安装和设置
+
+### 1. 安装依赖
+
+```bash
+cd backend
+npm install
+```
+
+### 2. 环境配置
+
+复制环境变量文件：
+
+```bash
+cp env.example .env
+```
+
+编辑 `.env` 文件，配置以下变量：
+
+```env
+# 数据库配置
+DATABASE_URL="postgresql://username:password@localhost:5432/pandora"
+
+# JWT 配置
+JWT_SECRET="your-super-secret-jwt-key-here"
+JWT_EXPIRES_IN="7d"
+
+# 邮件配置 (用于邮箱验证和密码重置)
+SMTP_HOST="smtp.gmail.com"
+SMTP_PORT=587
+SMTP_USER="your-email@gmail.com"
+SMTP_PASS="your-app-password"
+EMAIL_FROM="noreply@pandora.com"
+
+# Redis 配置
+REDIS_URL="redis://localhost:6379"
+
+# 服务器配置
+PORT=3001
+NODE_ENV="development"
+
+# 安全配置
+BCRYPT_ROUNDS=12
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# TOTP 配置
+TOTP_ISSUER="Pandora"
+TOTP_LABEL="Pandora Authentication"
+```
+
+### 3. 数据库设置
+
+```bash
+# 生成 Prisma 客户端
+npm run db:generate
+
+# 运行数据库迁移
+npm run db:migrate
+
+# 初始化测试数据
+npm run db:seed
+```
+
+### 4. 启动服务
+
+```bash
+# 开发模式
+npm run dev
+
+# 生产模式
+npm run build
+npm start
+```
+
+## 📚 API 文档
+
+### 认证相关 API
+
+#### 用户注册
+```http
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "username": "username",
+  "password": "password123",
+  "firstName": "张",
+  "lastName": "三"
+}
+```
+
+#### 用户登录
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+#### 邮箱验证
+```http
+POST /api/auth/verify-email
+Content-Type: application/json
+
+{
+  "token": "verification-token"
+}
+```
+
+#### 设置 TOTP
+```http
+POST /api/auth/setup-totp
+Authorization: Bearer <token>
+```
+
+#### 验证 TOTP
+```http
+POST /api/auth/verify-totp
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "token": "123456"
+}
+```
+
+#### 获取当前用户信息
+```http
+GET /api/auth/me
+Authorization: Bearer <token>
+```
+
+### 用户管理 API
+
+#### 获取所有用户 (管理员)
+```http
+GET /api/users
+Authorization: Bearer <admin-token>
+```
+
+#### 获取用户详情
+```http
+GET /api/users/:id
+Authorization: Bearer <token>
+```
+
+#### 更新用户信息
+```http
+PUT /api/users/:id
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "firstName": "新名字",
+  "lastName": "新姓氏"
+}
+```
+
+### 账号管理 API
+
+#### 获取用户账号
+```http
+GET /api/accounts/user/assigned
+Authorization: Bearer <token>
+```
+
+#### 创建账号 (管理员)
+```http
+POST /api/accounts
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "website": "claude.ai",
+  "accountName": "claude_pro_1",
+  "token": "sk-ant-api03-xxx",
+  "maxUsers": 3
+}
+```
+
+## 🔐 安全说明
+
+### 密码安全
+- 使用 bcrypt 进行密码哈希，默认 12 轮加密
+- 密码最小长度 8 位
+- 支持密码重置功能
+
+### 会话管理
+- JWT 令牌有效期 7 天
+- 支持令牌刷新
+- 会话存储在数据库中，支持强制登出
+
+### 二步验证
+- 支持 TOTP (Google Authenticator)
+- 提供 10 个备用码
+- 可选择性启用
+
+### API 安全
+- 所有敏感 API 需要认证
+- 管理员 API 需要管理员权限
+- 实现 API 限流防止滥用
+- 输入验证和清理
+
+## 🧪 测试账户
+
+运行 `npm run db:seed` 后会创建以下测试账户：
+
+### 管理员账户
+- 邮箱: `admin@pandora.com`
+- 密码: `admin123`
+- 权限: 所有账号
+
+### 测试用户账户
+- 邮箱: `user@pandora.com`
+- 密码: `user123`
+- 权限: claude.ai 和 openai.com 账号
+
+## 📝 开发说明
+
+### 项目结构
+```
+src/
+├── config/          # 配置文件
+│   ├── database.ts  # 数据库连接
+│   └── redis.ts     # Redis 连接
+├── controllers/     # 控制器
+│   ├── authController.ts
+│   ├── userController.ts
+│   └── accountController.ts
+├── middleware/      # 中间件
+│   ├── authMiddleware.ts
+│   ├── adminMiddleware.ts
+│   ├── validateRequest.ts
+│   ├── errorHandler.ts
+│   └── notFoundHandler.ts
+├── routes/          # 路由
+│   ├── auth.ts
+│   ├── users.ts
+│   └── accounts.ts
+├── utils/           # 工具函数
+│   └── logger.ts
+└── index.ts         # 入口文件
+```
+
+### 数据库模型
+- `User`: 用户信息
+- `WebsiteAccount`: 网站账号
+- `AccountAssignment`: 账号分配
+- `Session`: 用户会话
+- `AuditLog`: 审计日志
+
+### 开发命令
+```bash
+# 开发模式
+npm run dev
+
+# 构建
+npm run build
+
+# 数据库操作
+npm run db:generate    # 生成 Prisma 客户端
+npm run db:migrate     # 运行迁移
+npm run db:push        # 推送 schema 到数据库
+npm run db:studio      # 打开 Prisma Studio
+npm run db:seed        # 初始化测试数据
+```
+
+## 🚨 注意事项
+
+1. **环境变量**: 确保所有必需的环境变量都已正确配置
+2. **数据库**: 确保 PostgreSQL 数据库正在运行
+3. **Redis**: 确保 Redis 服务正在运行
+4. **邮件服务**: 如果使用邮箱验证功能，需要配置有效的 SMTP 服务
+5. **JWT 密钥**: 生产环境请使用强随机密钥
+6. **HTTPS**: 生产环境建议使用 HTTPS
+
+## 📞 支持
+
+如有问题，请查看：
+1. 日志文件 (`logs/` 目录)
+2. 数据库连接状态
+3. Redis 连接状态
+4. 环境变量配置
+
+## 🔄 更新日志
+
+### v1.0.0
+- ✅ 完整的用户认证系统
+- ✅ JWT 令牌认证
+- ✅ 邮箱验证功能
+- ✅ TOTP 二步验证
+- ✅ 权限管理系统
+- ✅ 账号管理系统
+- ✅ 审计日志
+- ✅ API 限流和安全防护