frontend/backedREADME (1).md

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. 克隆项目

git clone <repository-url>
cd CarrotSkin/backend

2. 安装依赖

go mod download

3. 配置环境

# 复制环境变量文件
cp .env.example .env
# 编辑 .env 文件配置数据库、RustFS等服务连接信息

注意：项目完全依赖 .env 文件进行配置，不再使用 YAML 配置文件，便于 Docker 容器化部署。

4. 初始化数据库

# 创建数据库
createdb carrotskin
# 初始化表结构
psql -d carrotskin -f scripts/carrotskin_postgres.sql

5. 运行服务

Windows系统：

run.bat

Linux/Mac系统：

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. 容器部署: 直接在容器运行时设置环境变量即可

主要环境变量:

# 数据库配置
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 注册路由

部署

本地开发

# 安装依赖
go mod download

# 启动服务 (Windows)
run.bat

# 启动服务 (Linux/Mac)
go run cmd/server/main.go

生产部署

# 构建二进制文件
go build -o carrotskin-server cmd/server/main.go

# 运行服务
./carrotskin-server

Docker部署

# 构建镜像
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. 查看日志

# 实时查看日志
tail -f logs/app.log

# 搜索错误日志
grep "ERROR" logs/app.log

2. 测试Redis连接

redis-cli -h localhost -p 6379 -a your_password
> PING
> KEYS *

3. 测试数据库连接

psql -h localhost -U postgres -d carrotskin
\dt  # 查看所有表

4. 测试邮件配置
   • 使用Swagger文档测试 /api/v1/auth/send-code 接口
   • 检查邮件服务商是否限制发送频率

开发调试

启用详细日志：

# 在 .env 中设置
LOG_LEVEL=debug
SERVER_MODE=debug