437 lines
10 KiB
Markdown
437 lines
10 KiB
Markdown
# Pilates Server
|
||
|
||
一个基于 NestJS 的恋爱话题和聊天建议 API 服务，为移动应用提供后端支持，包含用户管理、Apple 登录、话题收藏、任务生成等功能。
|
||
|
||
## 🚀 功能特性
|
||
|
||
- **用户管理系统**
|
||
- Apple Sign-In 集成
|
||
- 游客登录支持
|
||
- JWT 认证和刷新令牌
|
||
- 用户资料管理
|
||
- 账户删除功能
|
||
|
||
- **话题管理**
|
||
- 话题库管理
|
||
- 话题收藏功能
|
||
- 话题分类和搜索
|
||
- 个性化推荐
|
||
|
||
- **任务系统**
|
||
- 任务创建和管理
|
||
- 任务重新生成
|
||
- 任务分类管理
|
||
|
||
- **支付集成**
|
||
- App Store 服务器通知处理
|
||
- RevenueCat Webhook 支持
|
||
- 订阅状态管理
|
||
|
||
- **安全特性**
|
||
- AES-256-GCM 端到端加密
|
||
- 数据传输加密
|
||
- 安全的密钥管理
|
||
|
||
- **云服务集成**
|
||
- 腾讯云 COS 存储
|
||
- 客户端日志收集
|
||
- 文件上传管理
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **框架**: NestJS 11.x
|
||
- **语言**: TypeScript
|
||
- **数据库**: MySQL 3.x + Sequelize ORM
|
||
- **认证**: JWT + Apple Sign-In
|
||
- **文档**: Swagger/OpenAPI
|
||
- **部署**: PM2 + 自动化部署脚本
|
||
- **云服务**: 腾讯云 COS
|
||
- **加密**: AES-256-GCM
|
||
- **测试**: Jest
|
||
|
||
## 📋 环境要求
|
||
|
||
- Node.js >= 18.0.0
|
||
- MySQL >= 8.0
|
||
- yarn 或 npm
|
||
- PM2 (生产环境)
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd pilates-server
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
yarn install
|
||
# 或
|
||
npm install
|
||
```
|
||
|
||
### 3. 环境配置
|
||
|
||
创建 `.env` 文件并配置以下环境变量：
|
||
|
||
```bash
|
||
# 数据库配置
|
||
DB_HOST=localhost
|
||
DB_PORT=3306
|
||
DB_USERNAME=your_username
|
||
DB_PASSWORD=your_password
|
||
DB_DATABASE=love_tips
|
||
|
||
# JWT 配置
|
||
JWT_SECRET=your_jwt_secret
|
||
JWT_EXPIRES_IN=7d
|
||
REFRESH_TOKEN_SECRET=your_refresh_token_secret
|
||
REFRESH_TOKEN_EXPIRES_IN=30d
|
||
|
||
# Apple 配置
|
||
APPLE_BUNDLE_ID=com.yourcompany.yourapp
|
||
APPLE_KEY_ID=your_key_id
|
||
APPLE_ISSUER_ID=your_issuer_id
|
||
APPLE_PRIVATE_KEY_PATH=path/to/your/private/key.p8
|
||
APPLE_APP_SHARED_SECRET=your_shared_secret
|
||
|
||
# 加密配置
|
||
ENCRYPTION_KEY=your-32-character-secret-key-here
|
||
|
||
# 腾讯云 COS 配置
|
||
COS_SECRET_ID=your_secret_id
|
||
COS_SECRET_KEY=your_secret_key
|
||
COS_REGION=your_region
|
||
COS_BUCKET=your_bucket
|
||
|
||
# 服务配置
|
||
PORT=3000
|
||
NODE_ENV=development
|
||
```
|
||
|
||
### 4. 数据库初始化
|
||
|
||
```bash
|
||
# 创建数据库
|
||
mysql -u root -p -e "CREATE DATABASE love_tips;"
|
||
|
||
# 运行迁移（如果有）
|
||
yarn run migration:run
|
||
```
|
||
|
||
### 5. 启动开发服务器
|
||
|
||
```bash
|
||
# 开发模式
|
||
yarn start:dev
|
||
|
||
# 或使用脚本
|
||
./start-dev.sh
|
||
```
|
||
|
||
服务器将在 `http://localhost:3000` 启动，API 文档可在 `http://localhost:3000/api/docs` 查看。
|
||
|
||
## 📖 API 文档
|
||
|
||
### 主要接口
|
||
|
||
#### 用户认证
|
||
- `POST /api/users/auth/apple/login` - Apple 登录
|
||
- `POST /api/users/auth/guest/login` - 游客登录
|
||
- `POST /api/users/auth/refresh` - 刷新令牌
|
||
- `POST /api/users/delete-account` - 删除账户
|
||
|
||
#### 用户管理
|
||
- `GET /api/users` - 获取用户资料
|
||
- `PUT /api/users/update` - 更新用户信息
|
||
- `PUT /api/users/relations` - 更新用户关系信息
|
||
- `GET /api/users/relations/:userId` - 获取用户关系信息
|
||
|
||
#### 话题管理
|
||
- `POST /api/topic/list` - 获取话题列表
|
||
- `POST /api/topic/favorite` - 收藏话题
|
||
- `POST /api/topic/unfavorite` - 取消收藏
|
||
- `POST /api/topic/favorites` - 获取收藏列表
|
||
|
||
#### 任务管理
|
||
- `POST /api/tasks` - 创建任务
|
||
- `GET /api/tasks/:id` - 获取任务详情
|
||
- `POST /api/tasks/recreate` - 重新生成任务
|
||
- `POST /api/tasks/categories` - 获取任务分类
|
||
|
||
#### 系统接口
|
||
- `POST /api/users/logs` - 创建客户端日志
|
||
- `POST /api/users/app-store-notifications` - App Store 通知
|
||
- `POST /api/users/revenuecat-webhook` - RevenueCat Webhook
|
||
|
||
完整的 API 文档请访问：`http://localhost:3000/api/docs`
|
||
|
||
## 🚀 部署指南
|
||
|
||
项目提供了三种部署方式：
|
||
|
||
### 1. 优化版部署（推荐）
|
||
|
||
```bash
|
||
./deploy-optimized.sh
|
||
```
|
||
|
||
- 只上传源代码，服务器端构建
|
||
- 传输文件少，部署速度快
|
||
- 包含完整的错误处理和备份
|
||
|
||
### 2. 完整版部署
|
||
|
||
```bash
|
||
# 查看帮助
|
||
./deploy.sh --help
|
||
|
||
# 模拟运行
|
||
./deploy.sh --dry-run
|
||
|
||
# 正式部署
|
||
./deploy.sh
|
||
```
|
||
|
||
### 3. 简化版部署
|
||
|
||
```bash
|
||
./deploy-simple.sh
|
||
```
|
||
|
||
### 服务器配置
|
||
|
||
- **服务器地址**: 129.204.155.94
|
||
- **用户**: root
|
||
- **部署目录**: /usr/local/web/pilates-server
|
||
|
||
### 生产环境启动
|
||
|
||
```bash
|
||
# 使用 PM2 启动
|
||
yarn pm2:start
|
||
|
||
# 查看状态
|
||
yarn pm2:status
|
||
|
||
# 查看日志
|
||
yarn pm2:logs
|
||
|
||
# 重启服务
|
||
yarn pm2:restart
|
||
```
|
||
|
||
详细部署说明请参考 [`DEPLOY.md`](DEPLOY.md)
|
||
|
||
## 🏗 项目结构
|
||
|
||
```
|
||
pilates-server/
|
||
├── src/ # 源代码目录
|
||
│ ├── app.module.ts # 应用主模块
|
||
│ ├── main.ts # 应用入口文件
|
||
│ ├── base.dto.ts # 基础 DTO
|
||
│ ├── common/ # 通用模块
|
||
│ │ ├── decorators/ # 装饰器
|
||
│ │ ├── guards/ # 守卫
|
||
│ │ └── encryption.service.ts # 加密服务
|
||
│ ├── database/ # 数据库模块
|
||
│ ├── users/ # 用户模块
|
||
│ │ ├── users.controller.ts # 用户控制器
|
||
│ │ ├── users.service.ts # 用户服务
|
||
│ │ ├── dto/ # 数据传输对象
|
||
│ │ ├── models/ # 数据模型
|
||
│ │ └── services/ # 业务服务
|
||
│ └── tasks/ # 任务模块
|
||
│ ├── task.controller.ts # 任务控制器
|
||
│ ├── task.service.ts # 任务服务
|
||
│ ├── dto/ # 数据传输对象
|
||
│ └── models/ # 数据模型
|
||
├── docs/ # 文档目录
|
||
│ ├── topic-favorite-api.md # 话题收藏 API 文档
|
||
│ ├── app-store-server-notifications.md # App Store 通知文档
|
||
│ └── ios-encryption-guide.md # iOS 加密对接指南
|
||
├── test/ # 测试文件
|
||
├── deploy*.sh # 部署脚本
|
||
├── start*.sh # 启动脚本
|
||
├── ecosystem.config.js # PM2 配置
|
||
├── package.json # 项目配置
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## ⚙️ 开发指南
|
||
|
||
### 开发环境设置
|
||
|
||
```bash
|
||
# 安装依赖
|
||
yarn install
|
||
|
||
# 启动开发服务器
|
||
yarn start:dev
|
||
|
||
# 运行测试
|
||
yarn test
|
||
|
||
# 运行 E2E 测试
|
||
yarn test:e2e
|
||
|
||
# 代码格式化
|
||
yarn format
|
||
|
||
# 代码检查
|
||
yarn lint
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 使用 TypeScript 严格模式
|
||
- 遵循 ESLint 配置规则
|
||
- 使用 Prettier 进行代码格式化
|
||
- 编写单元测试和集成测试
|
||
- 使用 Swagger 注解生成 API 文档
|
||
|
||
### Git 工作流
|
||
|
||
1. 从 `main` 分支创建功能分支
|
||
2. 提交代码前运行测试和代码检查
|
||
3. 创建 Pull Request
|
||
4. 代码审查通过后合并
|
||
|
||
## 🔒 安全特性
|
||
|
||
### 数据加密
|
||
|
||
项目支持 AES-256-GCM 端到端加密：
|
||
|
||
- **算法**: AES-256-GCM
|
||
- **密钥长度**: 256位 (32字节)
|
||
- **IV长度**: 96位 (12字节)
|
||
- **认证标签长度**: 128位 (16字节)
|
||
|
||
详细的 iOS 端对接指南请参考 [`docs/ios-encryption-guide.md`](docs/ios-encryption-guide.md)
|
||
|
||
### 认证授权
|
||
|
||
- JWT 令牌认证
|
||
- Apple Sign-In 集成
|
||
- 刷新令牌机制
|
||
- 角色权限控制
|
||
|
||
## 📊 监控和日志
|
||
|
||
### 日志管理
|
||
|
||
```bash
|
||
# 查看应用日志
|
||
pm2 logs pilates-server
|
||
|
||
# 查看错误日志
|
||
tail -f logs/error.log
|
||
|
||
# 查看访问日志
|
||
tail -f logs/output.log
|
||
```
|
||
|
||
### 性能监控
|
||
|
||
- PM2 进程监控
|
||
- 内存使用限制 (1GB)
|
||
- 自动重启机制
|
||
- 集群模式支持
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 UNLICENSED 许可证。
|
||
|
||
## 📞 支持
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
|
||
- 创建 Issue
|
||
- 发送邮件至项目维护者
|
||
- 查看项目文档
|
||
|
||
---
|
||
|
||
**注意**: 生产环境部署前请确保所有环境变量已正确配置，特别是数据库连接和 Apple 相关配置。
|
||
|
||
## 恢复购买功能
|
||
|
||
### 功能说明
|
||
恢复购买功能允许用户将之前在 RevenueCat 中的购买记录与当前登录的账号关联，确保用户能够访问他们已购买的内容。
|
||
|
||
### API 接口
|
||
|
||
**POST** `/users/restore-purchase`
|
||
|
||
### 请求参数
|
||
```json
|
||
{
|
||
"revenueCatUserId": "可选的RevenueCat用户ID，如果不提供将使用当前登录用户ID"
|
||
}
|
||
```
|
||
|
||
### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "购买记录恢复成功",
|
||
"data": {
|
||
"restoredPurchases": [
|
||
{
|
||
"productId": "com.app.premium.monthly",
|
||
"transactionId": "1000000123456789",
|
||
"purchaseDate": "2024-01-15T10:30:00Z",
|
||
"expirationDate": "2024-02-15T10:30:00Z",
|
||
"entitlementId": "premium",
|
||
"store": "app_store"
|
||
}
|
||
],
|
||
"membershipExpiration": "2024-02-15T10:30:00Z",
|
||
"message": "成功恢复 1 个购买记录，会员有效期至 2024-02-15T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 环境变量配置
|
||
|
||
需要在 `.env` 文件中配置以下 RevenueCat API 密钥：
|
||
|
||
```env
|
||
# RevenueCat 公开 API 密钥（用于读取用户信息）
|
||
REVENUECAT_PUBLIC_API_KEY=your_public_api_key_here
|
||
|
||
# RevenueCat 私密 API 密钥（用于用户关联，可选）
|
||
REVENUECAT_SECRET_API_KEY=your_secret_api_key_here
|
||
```
|
||
|
||
### 工作原理
|
||
|
||
1. **获取购买历史**: 通过 RevenueCat REST API 获取指定用户的购买历史
|
||
2. **解析购买记录**: 解析订阅和非续费购买，提取产品信息和过期时间
|
||
3. **更新用户状态**: 将最新的会员过期时间更新到当前用户
|
||
4. **用户关联**: 如果提供了不同的 RevenueCat 用户ID，会尝试进行用户关联
|
||
|
||
### 使用场景
|
||
|
||
- 用户更换设备后需要恢复购买
|
||
- 用户重新安装应用后需要恢复会员状态
|
||
- 用户使用不同的账号登录但想关联之前的购买
|
||
|
||
### 注意事项
|
||
|
||
- 需要确保 RevenueCat 项目已正确配置
|
||
- 公开 API 密钥用于读取用户信息，私密 API 密钥用于用户关联
|
||
- 恢复购买不会重复收费，只是将现有购买记录与当前账号关联 |