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. 安装依赖
cd backend
npm install
2. 环境配置
复制环境变量文件：
cp env.example .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. 数据库设置
# 生成 Prisma 客户端
npm run db:generate
# 运行数据库迁移
npm run db:migrate
# 初始化测试数据
npm run db:seed
4. 启动服务
# 开发模式
npm run dev
# 生产模式
npm run build
npm start
📚 API 文档
认证相关 API
用户注册
POST /api/auth/register
Content-Type: application/json
{
"email": "user@example.com",
"username": "username",
"password": "password123",
"firstName": "张",
"lastName": "三"
}
用户登录
POST /api/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "password123"
}
邮箱验证
POST /api/auth/verify-email
Content-Type: application/json
{
"token": "verification-token"
}
设置 TOTP
POST /api/auth/setup-totp
Authorization: Bearer <token>
验证 TOTP
POST /api/auth/verify-totp
Authorization: Bearer <token>
Content-Type: application/json
{
"token": "123456"
}
获取当前用户信息
GET /api/auth/me
Authorization: Bearer <token>
用户管理 API
获取所有用户 (管理员)
GET /api/users
Authorization: Bearer <admin-token>
获取用户详情
GET /api/users/:id
Authorization: Bearer <token>
更新用户信息
PUT /api/users/:id
Authorization: Bearer <token>
Content-Type: application/json
{
"firstName": "新名字",
"lastName": "新姓氏"
}
账号管理 API
获取用户账号
GET /api/accounts/user/assigned
Authorization: Bearer <token>
创建账号 (管理员)
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: 审计日志
开发命令
# 开发模式
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 # 初始化测试数据
🚨 注意事项
- 环境变量: 确保所有必需的环境变量都已正确配置
- 数据库: 确保 PostgreSQL 数据库正在运行
- Redis: 确保 Redis 服务正在运行
- 邮件服务: 如果使用邮箱验证功能，需要配置有效的 SMTP 服务
- JWT 密钥: 生产环境请使用强随机密钥
- HTTPS: 生产环境建议使用 HTTPS
📞 支持
如有问题，请查看：
- 日志文件 (
logs/目录) - 数据库连接状态
- Redis 连接状态
- 环境变量配置
🔄 更新日志
v1.0.0
- ✅ 完整的用户认证系统
- ✅ JWT 令牌认证
- ✅ 邮箱验证功能
- ✅ TOTP 二步验证
- ✅ 权限管理系统
- ✅ 账号管理系统
- ✅ 审计日志
- ✅ API 限流和安全防护