440 lines
12 KiB
Markdown
440 lines
12 KiB
Markdown
# CarrotSkin Backend
|
||
|
||
一个功能完善的Minecraft皮肤站后端系统，采用单体架构设计，基于Go语言和Gin框架开发。
|
||
|
||
## ✨ 核心功能
|
||
|
||
- ✅ **用户认证系统** - 注册、登录、JWT认证、积分系统
|
||
- ✅ **邮箱验证系统** - 注册验证、找回密码、更换邮箱（基于Redis的验证码）
|
||
- ✅ **材质管理系统** - 皮肤/披风上传、搜索、收藏、下载统计
|
||
- ✅ **角色档案系统** - Minecraft角色创建、管理、RSA密钥生成
|
||
- ✅ **文件存储** - MinIO/RustFS对象存储集成、预签名URL上传
|
||
- ✅ **缓存系统** - Redis缓存、验证码存储、频率限制
|
||
- ✅ **权限管理** - Casbin RBAC权限控制
|
||
- ✅ **数据审计** - 登录日志、操作审计、下载记录
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── cmd/ # 应用程序入口
|
||
│ └── server/ # 主服务器
|
||
├── internal/ # 私有应用代码
|
||
│ ├── handler/ # HTTP处理器
|
||
│ ├── service/ # 业务逻辑服务
|
||
│ ├── model/ # 数据模型
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── middleware/ # 中间件
|
||
│ └── types/ # 类型定义
|
||
├── pkg/ # 公共库代码
|
||
│ ├── auth/ # 认证授权
|
||
│ ├── config/ # 配置管理
|
||
│ ├── database/ # 数据库连接
|
||
│ ├── email/ # 邮件服务
|
||
│ ├── logger/ # 日志系统
|
||
│ ├── redis/ # Redis客户端
|
||
│ ├── storage/ # 文件存储(RustFS/MinIO)
|
||
│ ├── utils/ # 工具函数
|
||
│ └── validator/ # 数据验证
|
||
├── docs/ # API定义和文档
|
||
├── configs/ # 配置文件
|
||
│ ├── casbin/ # Casbin权限配置
|
||
├── scripts/ # 脚本文件
|
||
│ ├── carrotskin.sql # 数据库初始化
|
||
├── go.mod # Go模块依赖
|
||
├── go.sum # Go模块校验
|
||
├── run.bat # Windows启动脚本
|
||
├── .env # 环境变量配置
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **语言**: Go 1.21+
|
||
- **框架**: Gin Web Framework
|
||
- **数据库**: PostgreSQL 15+
|
||
- **缓存**: Redis 6.0+
|
||
- **存储**: RustFS (S3兼容对象存储)
|
||
- **权限**: Casbin RBAC
|
||
- **日志**: Zap
|
||
- **配置**: 环境变量 (.env)
|
||
- **文档**: Swagger/OpenAPI 3.0
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.21或更高版本
|
||
- PostgreSQL 15或更高版本
|
||
- Redis 6.0或更高版本
|
||
- RustFS 或其他 S3 兼容对象存储服务
|
||
|
||
### 安装和运行
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd CarrotSkin/backend
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
3. **配置环境**
|
||
```bash
|
||
# 复制环境变量文件
|
||
cp .env.example .env
|
||
# 编辑 .env 文件配置数据库、RustFS等服务连接信息
|
||
```
|
||
|
||
**注意**：项目完全依赖 `.env` 文件进行配置，不再使用 YAML 配置文件，便于 Docker 容器化部署。
|
||
|
||
4. **初始化数据库**
|
||
```bash
|
||
# 创建数据库
|
||
createdb carrotskin
|
||
# 初始化表结构
|
||
psql -d carrotskin -f scripts/carrotskin_postgres.sql
|
||
```
|
||
|
||
5. **运行服务**
|
||
|
||
Windows系统：
|
||
```bash
|
||
run.bat
|
||
```
|
||
|
||
Linux/Mac系统：
|
||
```bash
|
||
chmod +x run.sh
|
||
./run.sh
|
||
```
|
||
|
||
> 💡 **提示**: 启动脚本会自动检查并安装 `swag` 工具，然后生成Swagger API文档，最后启动服务器。
|
||
|
||
服务启动后：
|
||
- **服务地址**: http://localhost:8080
|
||
- **Swagger文档**: http://localhost:8080/swagger/index.html
|
||
- **健康检查**: http://localhost:8080/health
|
||
|
||
## API接口
|
||
|
||
### 认证相关
|
||
- `POST /api/v1/auth/register` - 用户注册（需邮箱验证码）
|
||
- `POST /api/v1/auth/login` - 用户登录（支持用户名/邮箱）
|
||
- `POST /api/v1/auth/send-code` - 发送验证码（注册/重置密码/更换邮箱）
|
||
- `POST /api/v1/auth/reset-password` - 重置密码（需验证码）
|
||
|
||
### 用户相关（需认证）
|
||
- `GET /api/v1/user/profile` - 获取用户信息
|
||
- `PUT /api/v1/user/profile` - 更新用户信息（头像、密码）
|
||
- `POST /api/v1/user/avatar/upload-url` - 生成头像上传URL
|
||
- `PUT /api/v1/user/avatar` - 更新头像
|
||
- `POST /api/v1/user/change-email` - 更换邮箱（需验证码）
|
||
|
||
### 材质管理
|
||
公开接口：
|
||
- `GET /api/v1/texture` - 搜索材质
|
||
- `GET /api/v1/texture/:id` - 获取材质详情
|
||
|
||
认证接口：
|
||
- `POST /api/v1/texture/upload-url` - 生成材质上传URL
|
||
- `POST /api/v1/texture` - 创建材质记录
|
||
- `PUT /api/v1/texture/:id` - 更新材质
|
||
- `DELETE /api/v1/texture/:id` - 删除材质
|
||
- `POST /api/v1/texture/:id/favorite` - 切换收藏状态
|
||
- `GET /api/v1/texture/my` - 我的材质列表
|
||
- `GET /api/v1/texture/favorites` - 我的收藏列表
|
||
|
||
### 角色档案
|
||
公开接口：
|
||
- `GET /api/v1/profile/:uuid` - 获取档案详情
|
||
|
||
认证接口：
|
||
- `POST /api/v1/profile` - 创建角色档案（UUID由后端生成）
|
||
- `GET /api/v1/profile` - 我的档案列表
|
||
- `PUT /api/v1/profile/:uuid` - 更新档案
|
||
- `DELETE /api/v1/profile/:uuid` - 删除档案
|
||
- `POST /api/v1/profile/:uuid/activate` - 设置活跃档案
|
||
|
||
### 系统配置
|
||
- `GET /api/v1/system/config` - 获取系统配置
|
||
|
||
## 配置管理
|
||
|
||
### 环境变量配置
|
||
|
||
项目**完全依赖环境变量**进行配置，不使用 YAML 配置文件，便于容器化部署：
|
||
|
||
1. **配置来源**: 环境变量 或 `.env` 文件
|
||
2. **环境变量格式**: 使用下划线分隔，全大写，如 `DATABASE_HOST`
|
||
3. **容器部署**: 直接在容器运行时设置环境变量即可
|
||
|
||
**主要环境变量**:
|
||
```bash
|
||
# 数据库配置
|
||
DATABASE_HOST=localhost
|
||
DATABASE_PORT=5432
|
||
DATABASE_USERNAME=postgres
|
||
DATABASE_PASSWORD=your_password
|
||
DATABASE_NAME=carrotskin
|
||
|
||
# Redis配置
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=your_redis_password
|
||
REDIS_DATABASE=0
|
||
REDIS_POOL_SIZE=10
|
||
|
||
# RustFS对象存储配置 (S3兼容)
|
||
RUSTFS_ENDPOINT=127.0.0.1:9000
|
||
RUSTFS_ACCESS_KEY=your_access_key
|
||
RUSTFS_SECRET_KEY=your_secret_key
|
||
RUSTFS_USE_SSL=false
|
||
RUSTFS_BUCKET_TEXTURES=carrot-skin-textures
|
||
RUSTFS_BUCKET_AVATARS=carrot-skin-avatars
|
||
|
||
# JWT配置
|
||
JWT_SECRET=your-jwt-secret-key
|
||
JWT_EXPIRE_HOURS=168
|
||
|
||
# 邮件配置
|
||
EMAIL_ENABLED=true
|
||
EMAIL_SMTP_HOST=smtp.example.com
|
||
EMAIL_SMTP_PORT=587
|
||
EMAIL_USERNAME=noreply@example.com
|
||
EMAIL_PASSWORD=your_email_password
|
||
EMAIL_FROM_NAME=CarrotSkin
|
||
```
|
||
|
||
**动态配置（存储在数据库中）**:
|
||
- 积分系统配置（注册奖励、签到积分等）
|
||
- 用户限制配置（最大材质数、最大角色数等）
|
||
- 网站设置（站点名称、公告、维护模式等）
|
||
|
||
完整的环境变量列表请参考 `.env.example` 文件。
|
||
|
||
## 架构设计
|
||
|
||
### 三层架构
|
||
|
||
项目采用标准的三层架构设计，职责清晰，便于维护：
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Handler 层 (HTTP) │ ← 路由、参数验证、响应格式化
|
||
├─────────────────────────────────────┤
|
||
│ Service 层 (业务逻辑) │ ← 业务规则、权限检查、数据验证
|
||
├─────────────────────────────────────┤
|
||
│ Repository 层 (数据访问) │ ← 数据库操作、关联查询
|
||
├──────────────┬──────────────────────┤
|
||
│ PostgreSQL │ Redis │ RustFS │ ← 数据存储层
|
||
└──────────────┴──────────────────────┘
|
||
```
|
||
|
||
### 核心模块
|
||
|
||
1. **认证模块** (`internal/handler/auth_handler.go`)
|
||
- JWT令牌生成和验证
|
||
- bcrypt密码加密
|
||
- 邮箱验证码注册
|
||
- 密码重置功能
|
||
- 登录日志记录（支持用户名/邮箱登录）
|
||
|
||
2. **用户模块** (`internal/handler/user_handler.go`)
|
||
- 用户信息管理
|
||
- 头像上传（预签名URL）
|
||
- 密码修改（需原密码验证）
|
||
- 邮箱更换（需验证码）
|
||
- 积分系统
|
||
|
||
3. **邮箱验证模块** (`internal/service/verification_service.go`)
|
||
- 验证码生成（6位数字）
|
||
- 验证码存储（Redis，10分钟有效期）
|
||
- 发送频率限制（1分钟）
|
||
- 邮件发送（HTML格式）
|
||
|
||
4. **材质模块** (`internal/handler/texture_handler.go`)
|
||
- 材质上传（预签名URL）
|
||
- 材质搜索和收藏
|
||
- Hash去重
|
||
- 下载统计
|
||
|
||
5. **档案模块** (`internal/handler/profile_handler.go`)
|
||
- Minecraft角色管理
|
||
- RSA密钥生成（RSA-2048）
|
||
- 活跃状态管理
|
||
- 档案数量限制
|
||
|
||
### 技术特性
|
||
|
||
- **安全性**:
|
||
- bcrypt密码加密、JWT令牌认证
|
||
- 邮箱验证码（注册/重置密码/更换邮箱）
|
||
- Casbin RBAC权限控制
|
||
- 频率限制（防暴力破解）
|
||
|
||
- **性能**:
|
||
- PostgreSQL索引优化
|
||
- Redis缓存（验证码、会话等）
|
||
- 预签名URL减轻服务器压力
|
||
- 连接池管理
|
||
|
||
- **可靠性**:
|
||
- 事务保证数据一致性
|
||
- 完整的错误处理和日志记录
|
||
- 优雅关闭和资源清理
|
||
|
||
- **可扩展**:
|
||
- 清晰的三层架构
|
||
- 依赖注入设计
|
||
- 环境变量配置（便于容器化）
|
||
|
||
- **审计**:
|
||
- 登录日志（成功/失败）
|
||
- 操作审计
|
||
- 下载记录
|
||
|
||
## 开发指南
|
||
|
||
### 代码结构
|
||
|
||
- `cmd/server/` - 应用入口，初始化服务
|
||
- `internal/handler/` - HTTP请求处理
|
||
- `internal/service/` - 业务逻辑实现
|
||
- `internal/repository/` - 数据库操作
|
||
- `internal/model/` - 数据模型定义
|
||
- `internal/types/` - 请求/响应类型定义
|
||
- `internal/middleware/` - 中间件（JWT、CORS、日志等）
|
||
- `pkg/` - 可复用的公共库
|
||
|
||
### 开发规范
|
||
|
||
1. **代码风格**: 遵循Go官方代码规范，使用 `gofmt` 格式化
|
||
2. **错误处理**: 使用统一的错误响应格式 (`model.NewErrorResponse`)
|
||
3. **日志记录**: 使用 Zap 结构化日志，包含关键字段
|
||
4. **依赖注入**: Repository → Service → Handler 的依赖链
|
||
5. **RESTful API**: 遵循 REST 设计原则，合理使用HTTP方法
|
||
|
||
### 添加新功能
|
||
|
||
1. 在 `internal/model/` 定义数据模型
|
||
2. 在 `internal/repository/` 实现数据访问
|
||
3. 在 `internal/service/` 实现业务逻辑
|
||
4. 在 `internal/handler/` 实现HTTP处理
|
||
5. 在 `internal/handler/routes.go` 注册路由
|
||
|
||
## 部署
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 安装依赖
|
||
go mod download
|
||
|
||
# 启动服务 (Windows)
|
||
run.bat
|
||
|
||
# 启动服务 (Linux/Mac)
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
### 生产部署
|
||
|
||
```bash
|
||
# 构建二进制文件
|
||
go build -o carrotskin-server cmd/server/main.go
|
||
|
||
# 运行服务
|
||
./carrotskin-server
|
||
```
|
||
|
||
### Docker部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t carrotskin-backend:latest .
|
||
|
||
# 启动服务
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
|
||
1. **数据库连接失败**
|
||
- 检查 `.env` 中的数据库配置
|
||
- 确认PostgreSQL服务已启动
|
||
- 验证数据库用户权限
|
||
- 确认数据库已创建：`createdb carrotskin`
|
||
|
||
2. **Redis连接失败**
|
||
- 检查Redis服务是否运行：`redis-cli ping`
|
||
- 验证 `.env` 中的Redis配置
|
||
- 确认Redis密码是否正确
|
||
- 检查防火墙规则
|
||
|
||
3. **RustFS/MinIO连接失败**
|
||
- 检查存储服务是否运行
|
||
- 验证访问密钥是否正确
|
||
- 确认存储桶是否已创建
|
||
- 检查网络连接和端口
|
||
|
||
4. **邮件发送失败**
|
||
- 检查 `EMAIL_ENABLED=true`
|
||
- 验证SMTP服务器地址和端口
|
||
- 确认邮箱用户名和密码正确
|
||
- 检查邮件服务商是否需要开启SMTP
|
||
- 查看日志获取详细错误信息
|
||
|
||
5. **验证码相关问题**
|
||
- 验证码过期（10分钟有效期）
|
||
- 发送过于频繁（1分钟限制）
|
||
- Redis存储失败（检查Redis连接）
|
||
- 邮件未收到（检查垃圾邮件）
|
||
|
||
6. **JWT验证失败**
|
||
- 检查 `JWT_SECRET` 是否配置
|
||
- 验证令牌是否过期（默认168小时）
|
||
- 确认请求头中包含 `Authorization: Bearer <token>`
|
||
- Token格式是否正确
|
||
|
||
### 调试技巧
|
||
|
||
1. **查看日志**
|
||
```bash
|
||
# 实时查看日志
|
||
tail -f logs/app.log
|
||
|
||
# 搜索错误日志
|
||
grep "ERROR" logs/app.log
|
||
```
|
||
|
||
2. **测试Redis连接**
|
||
```bash
|
||
redis-cli -h localhost -p 6379 -a your_password
|
||
> PING
|
||
> KEYS *
|
||
```
|
||
|
||
3. **测试数据库连接**
|
||
```bash
|
||
psql -h localhost -U postgres -d carrotskin
|
||
\dt # 查看所有表
|
||
```
|
||
|
||
4. **测试邮件配置**
|
||
- 使用Swagger文档测试 `/api/v1/auth/send-code` 接口
|
||
- 检查邮件服务商是否限制发送频率
|
||
|
||
### 开发调试
|
||
|
||
启用详细日志：
|
||
```bash
|
||
# 在 .env 中设置
|
||
LOG_LEVEL=debug
|
||
SERVER_MODE=debug
|
||
``` |