类型	选型
语言 / 运行时	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 的对象存储，用于皮肤与头像）

🚀 快速开始

克隆仓库
```
git clone <repo>
cd backend
```
安装依赖
```
go mod download
```

配置环境变量

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

初始化数据库
```
createdb carrotskin
# 或 psql -c "CREATE DATABASE carrotskin;"
```
应用启动时会执行 AutoMigrate，自动创建 / 更新表结构。
启动服务
- 推荐：./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
```
访问接口
- 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
}

🔒 安全特性

权限保护：所有管理接口都需要管理员权限（role=admin）
安全限制：管理员不能修改/删除自己的角色和状态
批量操作：支持批量设置角色和批量删除
操作日志：所有管理操作都会记录日志
封禁功能：通过 /users/status 接口可以封禁/解封用户

🤝 贡献指南

Fork & Clone
创建特性分支：git checkout -b feature/xxx
编写代码并补全测试 / Swagger 注释
提交时附上变更说明

📄 许可证

如需了解业务细节或 API 调用示例，请参考 docs/swagger.yaml 或运行服务后访问 Swagger UI。祝编码愉快！🍀

README.md Unescape Escape

CarrotSkin Backend

✨ 功能亮点

🛠 技术栈