295 lines
9.3 KiB
Markdown
295 lines
9.3 KiB
Markdown
# CarrotSkin Backend
|
||
|
||
一个功能完善的 Minecraft 皮肤站后端，基于 Go + Gin 构建，覆盖用户认证、材质管理、角色档案、审计日志等核心能力，并提供完整的 Swagger 文档与容器友好的环境变量配置。
|
||
|
||
## ✨ 功能亮点
|
||
|
||
- **账号体系**：注册 / 登录 / JWT 鉴权 / Yggdrasil 密码同步 / 用户积分
|
||
- **邮箱与验证码**：验证码发送频率控制、邮箱绑定与变更
|
||
- **材质中心**：皮肤/披风上传、搜索、收藏、下载统计、Hash 去重
|
||
- **角色档案**：Minecraft Profile 管理、RSA 密钥对生成、活跃档案切换
|
||
- **存储与上传**：RustFS/MinIO 预签名 URL，减轻服务器带宽压力
|
||
- **任务与日志**：登录日志、操作审计、材质下载记录、定时任务
|
||
- **权限体系**：Casbin RBAC，支持细粒度路线授权
|
||
- **配置管理**：100% 依赖环境变量，`SERVER_SWAGGER_ENABLED` 控制 Swagger
|
||
- **可观测性**：Zap 结构化日志、统一 API 响应模型
|
||
|
||
## 🛠 技术栈
|
||
|
||
| 类型 | 选型 |
|
||
| --- | --- |
|
||
| 语言 / 运行时 | Go 1.24+ |
|
||
| Web 框架 | Gin |
|
||
| ORM | GORM (PostgreSQL 驱动) |
|
||
| 数据库 | PostgreSQL 15+ |
|
||
| 缓存 / 消息 | Redis 6+ |
|
||
| 对象存储 | RustFS / MinIO（S3 兼容） |
|
||
| 权限控制 | Casbin |
|
||
| 配置 | Viper + `.env` |
|
||
| API 文档 | swaggo / Swagger UI |
|
||
| 日志 | Uber Zap |
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
backend/
|
||
├── cmd/server/ # 应用入口（main.go）
|
||
├── internal/
|
||
│ ├── handler/ # HTTP Handler 与 Swagger 注解
|
||
│ ├── service/ # 业务逻辑
|
||
│ ├── repository/ # 数据访问
|
||
│ ├── model/ # GORM 数据模型
|
||
│ ├── types/ # 请求/响应 DTO
|
||
│ ├── middleware/ # Gin 中间件
|
||
│ └── task/ # 定时任务与后台作业
|
||
├── pkg/ # 可复用组件（config、database、auth、logger、redis、storage 等）
|
||
├── docs/ # swagger 生成产物（docs.go / swagger.json / swagger.yaml）
|
||
├── start.sh # 启动脚本（自动 swag init）
|
||
├── docker-compose.yml # 本地容器编排
|
||
├── .env.example # 环境变量示例
|
||
└── go.mod # Go Module 定义
|
||
```
|
||
|
||
## ✅ 前置要求
|
||
|
||
- Go 1.24+
|
||
- PostgreSQL 15+
|
||
- Redis 6+
|
||
- RustFS / MinIO（或其他兼容 S3 的对象存储，用于皮肤与头像）
|
||
|
||
## 🚀 快速开始
|
||
|
||
1. **克隆仓库**
|
||
```bash
|
||
git clone <repo>
|
||
cd backend
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
3. **配置环境变量**
|
||
```bash
|
||
cp .env.example .env
|
||
# 根据实际环境填写数据库、Redis、对象存储、邮件等信息
|
||
```
|
||
|
||
4. **初始化数据库**
|
||
```bash
|
||
createdb carrotskin
|
||
# 或 psql -c "CREATE DATABASE carrotskin;"
|
||
```
|
||
> 应用启动时会执行 `AutoMigrate`，自动创建 / 更新表结构。
|
||
|
||
5. **启动服务**
|
||
- **推荐**：`./start.sh`（自动 `swag init`，随后 `go run cmd/server/main.go`）
|
||
- **手动启动**：
|
||
```bash
|
||
swag init -g cmd/server/main.go -o docs
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
6. **访问接口**
|
||
- API Root: `http://localhost:8080`
|
||
- Swagger: `http://localhost:8080/swagger/index.html`（需 `SERVER_SWAGGER_ENABLED=true`）
|
||
|
||
## ⚙️ 关键环境变量
|
||
|
||
| 变量 | 说明 | 示例 |
|
||
| --- | --- | --- |
|
||
| `SERVER_PORT` | 服务监听端口 | `8080` |
|
||
| `SERVER_MODE` | Gin 模式（debug/release） | `debug` |
|
||
| `SERVER_SWAGGER_ENABLED` | 是否暴露 Swagger UI | `true` |
|
||
| `DATABASE_HOST` / `DATABASE_PORT` | PostgreSQL 地址 | `localhost` / `5432` |
|
||
| `DATABASE_USERNAME` / `DATABASE_PASSWORD` | 数据库凭据 | `postgres` |
|
||
| `DATABASE_NAME` | 数据库名称 | `carrotskin` |
|
||
| `REDIS_HOST` / `REDIS_PORT` | Redis 地址 | `localhost` / `6379` |
|
||
| `REDIS_PASSWORD` | Redis 密码（无可为空） | `` |
|
||
| `RUSTFS_ENDPOINT` | RustFS/MinIO 访问地址 | `127.0.0.1:9000` |
|
||
| `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` | 对象存储凭据 | `minioadmin` |
|
||
| `RUSTFS_BUCKET_TEXTURES` / `RUSTFS_BUCKET_AVATARS` | 存储桶名称 | `carrotskin-textures` |
|
||
| `JWT_SECRET` | JWT 签名密钥 | `change-me` |
|
||
| `EMAIL_ENABLED` | 是否开启邮件服务 | `true` |
|
||
| `EMAIL_SMTP_HOST` / `EMAIL_SMTP_PORT` | SMTP 配置 | `smtp.example.com` / `587` |
|
||
|
||
更多变量请参考 `.env.example` 与 `.env.docker.example`。
|
||
|
||
## 🧪 常用命令
|
||
|
||
```bash
|
||
# 运行单元测试
|
||
go test ./...
|
||
|
||
# 重新生成 swagger
|
||
swag init -g cmd/server/main.go -o docs
|
||
|
||
# 代码格式化 / 静态检查
|
||
gofmt -w .
|
||
golangci-lint run (若已安装)
|
||
```
|
||
|
||
## 🧱 架构说明
|
||
|
||
- **分层设计**：Handler -> Service -> Repository -> Model，层次清晰、职责单一。
|
||
- **依赖管理器**：`pkg/*/manager.go` 使用 `sync.Once` 实现线程安全单例（DB / Redis / Logger / Storage / Email / Auth / Config）。
|
||
- **Swagger 注解**：所有 Handler、模型、DTO 均补齐 `@Summary` / `@Description` / `@Success`，可直接生成 OpenAPI 文档。
|
||
- **配置优先级**：`.env` -> 系统环境变量，所有配置均可通过容器注入。
|
||
- **自动任务**：`internal/task` 承载后台作业，可按需扩展。
|
||
|
||
## 📝 Swagger 说明
|
||
|
||
- `start.sh` 会在启动前执行 `swag init -g cmd/server/main.go -o docs`
|
||
- 若手动运行，需要保证 `docs/` 下的 `docs.go`、`swagger.json`、`swagger.yaml` 与代码同步
|
||
- 通过 `SERVER_SWAGGER_ENABLED=false` 可在生产环境关闭 Swagger UI 暴露
|
||
|
||
## 🔐 管理后台 API
|
||
|
||
管理后台接口均需要管理员权限（`role=admin`），所有接口路径前缀为 `/api/v1/admin`。
|
||
|
||
### 📊 统计信息
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/stats` | GET | 获取系统统计数据（用户数、材质数、下载量等） |
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"total_users": 100,
|
||
"active_users": 80,
|
||
"banned_users": 5,
|
||
"admin_users": 3,
|
||
"total_textures": 500,
|
||
"public_textures": 300,
|
||
"pending_textures": 10,
|
||
"total_downloads": 1000,
|
||
"total_favorites": 500
|
||
}
|
||
}
|
||
```
|
||
|
||
### 👥 角色管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/roles` | GET | 获取所有可用角色列表 |
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"roles": [
|
||
{
|
||
"name": "user",
|
||
"display_name": "普通用户",
|
||
"description": "拥有基本用户权限"
|
||
},
|
||
{
|
||
"name": "admin",
|
||
"display_name": "管理员",
|
||
"description": "拥有所有管理权限"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 👤 用户管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/users` | GET | 获取用户列表（分页） |
|
||
| `/users/search` | GET | 搜索用户（支持关键词、角色、状态筛选、排序） |
|
||
| `/users/{id}` | GET | 获取用户详情 |
|
||
| `/users/{id}` | DELETE | 删除用户（软删除） |
|
||
| `/users/role` | PUT | 设置单个用户角色 |
|
||
| `/users/status` | PUT | 设置单个用户状态（封禁/解封） |
|
||
| `/users/batch-role` | PUT | 批量设置用户角色 |
|
||
| `/users/batch-delete` | DELETE | 批量删除用户 |
|
||
|
||
**搜索用户请求参数：**
|
||
- `keyword` (string): 搜索关键词（用户名或邮箱）
|
||
- `role` (string): 角色筛选
|
||
- `status` (int): 状态筛选（1=正常，0=禁用，-1=删除）
|
||
- `sort_by` (string): 排序字段
|
||
- `sort_desc` (bool): 是否降序
|
||
- `page` (int): 页码
|
||
- `page_size` (int): 每页数量
|
||
|
||
**设置用户状态请求示例：**
|
||
```json
|
||
{
|
||
"user_id": 123,
|
||
"status": 0
|
||
}
|
||
```
|
||
- `status`: 1=正常，0=禁用，-1=删除
|
||
|
||
**批量设置角色请求示例：**
|
||
```json
|
||
{
|
||
"user_ids": [1, 2, 3],
|
||
"role": "admin"
|
||
}
|
||
```
|
||
|
||
### 🎨 材质管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/textures` | GET | 获取材质列表（分页） |
|
||
| `/textures/search` | GET | 搜索材质（支持关键词、类型、状态、上传者筛选、排序） |
|
||
| `/textures/{id}` | PUT | 更新材质信息（名称、描述、公开状态、审核状态） |
|
||
| `/textures/{id}` | DELETE | 删除材质 |
|
||
| `/textures/batch-delete` | DELETE | 批量删除材质 |
|
||
|
||
**搜索材质请求参数：**
|
||
- `keyword` (string): 搜索关键词
|
||
- `type` (string): 材质类型（SKIN/CAPE）
|
||
- `status` (int): 状态筛选
|
||
- `uploader_id` (int): 上传者ID筛选
|
||
- `sort_by` (string): 排序字段
|
||
- `sort_desc` (bool): 是否降序
|
||
- `page` (int): 页码
|
||
- `page_size` (int): 每页数量
|
||
|
||
**更新材质请求示例：**
|
||
```json
|
||
{
|
||
"name": "新皮肤名称",
|
||
"description": "新描述",
|
||
"is_public": true,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 🔒 安全特性
|
||
|
||
1. **权限保护**：所有管理接口都需要管理员权限（`role=admin`）
|
||
2. **安全限制**：管理员不能修改/删除自己的角色和状态
|
||
3. **批量操作**：支持批量设置角色和批量删除
|
||
4. **操作日志**：所有管理操作都会记录日志
|
||
5. **封禁功能**：通过 `/users/status` 接口可以封禁/解封用户
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork & Clone
|
||
2. 创建特性分支：`git checkout -b feature/xxx`
|
||
3. 编写代码并补全测试 / Swagger 注释
|
||
4. 提交时附上变更说明
|
||
|
||
## 📄 许可证
|
||
|
||
该项目未附带开源许可证，默认保留所有权利。若需对外使用，请先与作者确认协议。
|
||
|
||
---
|
||
|
||
如需了解业务细节或 API 调用示例，请参考 `docs/swagger.yaml` 或运行服务后访问 Swagger UI。祝编码愉快！🍀
|