bluish/ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
65b8fdd09f4b6d8629d129e4d31dc49c647164c3
ai/backend/README.md
liangweihao aa2416c5d6 first commit
2025-07-08 00:52:10 +08:00

6.4 KiB
Raw Blame History

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        # 初始化测试数据

🚨 注意事项

  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 限流和安全防护