backend/README.md

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. 克隆仓库

   git clone <repo>
   cd backend
   

2. 安装依赖

   go mod download
   

3. 配置环境变量

   cp .env.example .env
   # 根据实际环境填写数据库、Redis、对象存储、邮件等信息
   

4. 初始化数据库

   createdb carrotskin
   # 或 psql -c "CREATE DATABASE carrotskin;"
   

   应用启动时会执行 AutoMigrate，自动创建 / 更新表结构。

5. 启动服务

   • 推荐：./start.sh（自动 swag init，随后 go run cmd/server/main.go）
   • 手动启动：

     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。

🧪 常用命令

# 运行单元测试
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	获取系统统计数据（用户数、材质数、下载量等）

响应示例：

{
  "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	获取所有可用角色列表

响应示例：

{
  "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): 每页数量

设置用户状态请求示例：

{
  "user_id": 123,
  "status": 0
}

• status: 1=正常，0=禁用，-1=删除

批量设置角色请求示例：

{
  "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): 每页数量

更新材质请求示例：

{
  "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。祝编码愉快！🍀