347 lines
6.4 KiB
Markdown
347 lines
6.4 KiB
Markdown
# 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 限流和安全防护 |