266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# 项目概述
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [carrotskin](file://go.mod#L1-L92)
|
||
- [routes.go](file://internal/handler/routes.go#L1-L140)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
- [yggdrasil.go](file://internal/model/yggdrasil.go#L1-L49)
|
||
- [config.go](file://pkg/config/config.go#L1-L305)
|
||
- [postgres.go](file://pkg/database/postgres.go#L1-L74)
|
||
- [redis.go](file://pkg/redis/redis.go#L1-L175)
|
||
- [minio.go](file://pkg/storage/minio.go#L1-L121)
|
||
- [auth.go](file://internal/middleware/auth.go#L1-L79)
|
||
- [manager.go](file://pkg/auth/manager.go#L1-L46)
|
||
- [user_service.go](file://internal/service/user_service.go#L1-L249)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L1-L252)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L1-L202)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概述](#架构概述)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
CarrotSkin 是一个为 Minecraft 玩家提供皮肤管理服务的后端系统。该项目旨在为用户提供一个稳定、安全且功能丰富的平台，用于上传、管理和分享 Minecraft 皮肤与披风。系统支持用户认证、材质管理、档案系统以及与 Yggdrasil 协议的集成，确保与 Minecraft 客户端的无缝对接。通过 Gin 框架构建的分层架构，CarrotSkin 实现了清晰的职责分离，便于维护和扩展。
|
||
|
||
## 项目结构
|
||
CarrotSkin 项目采用模块化设计，主要分为 `internal` 和 `pkg` 两个目录。`internal` 目录包含应用的核心逻辑，包括处理器（handler）、中间件（middleware）、模型（model）、仓库（repository）和服务（service）。`pkg` 目录则封装了可重用的工具和第三方服务集成，如数据库、Redis、对象存储等。这种结构有助于保持代码的整洁和可维护性。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "内部模块"
|
||
Handler[handler]
|
||
Middleware[middleware]
|
||
Model[model]
|
||
Repository[repository]
|
||
Service[service]
|
||
end
|
||
subgraph "公共包"
|
||
Config[config]
|
||
Database[database]
|
||
Redis[redis]
|
||
Storage[storage]
|
||
Auth[auth]
|
||
Logger[logger]
|
||
Utils[utils]
|
||
end
|
||
Handler --> Service
|
||
Service --> Repository
|
||
Repository --> Database
|
||
Repository --> Redis
|
||
Repository --> Storage
|
||
Auth --> Middleware
|
||
```
|
||
|
||
**图源**
|
||
- [go.mod](file://go.mod#L1-L92)
|
||
- [routes.go](file://internal/handler/routes.go#L1-L140)
|
||
|
||
**本节来源**
|
||
- [go.mod](file://go.mod#L1-L92)
|
||
- [routes.go](file://internal/handler/routes.go#L1-L140)
|
||
|
||
## 核心组件
|
||
CarrotSkin 的核心组件包括用户认证、材质管理、档案系统和 Yggdrasil 协议集成。用户认证模块负责用户的注册、登录和权限验证，使用 JWT 进行安全的会话管理。材质管理模块允许用户上传、搜索和下载皮肤与披风，支持收藏和下载统计。档案系统为每个用户提供了多个 Minecraft 角色档案，支持设置活跃档案和管理皮肤与披风。Yggdrasil 协议集成确保了与 Minecraft 客户端的兼容性，支持身份验证和服务器加入。
|
||
|
||
**本节来源**
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
- [yggdrasil.go](file://internal/model/yggdrasil.go#L1-L49)
|
||
|
||
## 架构概述
|
||
CarrotSkin 采用基于 Gin 框架的分层架构，分为处理器（Handler）、服务（Service）和仓库（Repository）三层。处理器层负责处理 HTTP 请求和响应，服务层实现业务逻辑，仓库层负责数据访问。这种分层设计确保了各层之间的职责分离，提高了代码的可测试性和可维护性。系统与 PostgreSQL、Redis 和 MinIO/RustFS 等外部系统集成，分别用于持久化存储、缓存和对象存储。
|
||
|
||
```mermaid
|
||
graph TD
|
||
Client[客户端] --> Handler[处理器]
|
||
Handler --> Service[服务]
|
||
Service --> Repository[仓库]
|
||
Repository --> PostgreSQL[(PostgreSQL)]
|
||
Repository --> Redis[(Redis)]
|
||
Repository --> MinIO[(MinIO/RustFS)]
|
||
```
|
||
|
||
**图源**
|
||
- [routes.go](file://internal/handler/routes.go#L1-L140)
|
||
- [config.go](file://pkg/config/config.go#L1-L305)
|
||
|
||
**本节来源**
|
||
- [routes.go](file://internal/handler/routes.go#L1-L140)
|
||
- [config.go](file://pkg/config/config.go#L1-L305)
|
||
|
||
## 详细组件分析
|
||
### 用户认证分析
|
||
用户认证模块是 CarrotSkin 的安全基石，负责用户的注册、登录和权限验证。通过 JWT 实现无状态的会话管理，确保了系统的可扩展性。用户信息存储在 PostgreSQL 中，密码经过哈希处理以保证安全性。Redis 用于缓存用户会话和验证码，提高响应速度。
|
||
|
||
#### 类图
|
||
```mermaid
|
||
classDiagram
|
||
class User {
|
||
+int64 ID
|
||
+string Username
|
||
+string Email
|
||
+string Avatar
|
||
+int Points
|
||
+string Role
|
||
+int16 Status
|
||
+string Properties
|
||
+*time.Time LastLoginAt
|
||
+time.Time CreatedAt
|
||
+time.Time UpdatedAt
|
||
}
|
||
class Token {
|
||
+int64 ID
|
||
+int64 UserID
|
||
+string AccessToken
|
||
+string RefreshToken
|
||
+string ProfileId
|
||
+time.Time ExpiresAt
|
||
+time.Time CreatedAt
|
||
}
|
||
class Yggdrasil {
|
||
+int64 ID
|
||
+string Password
|
||
}
|
||
User --> Token : "拥有"
|
||
User --> Yggdrasil : "关联"
|
||
```
|
||
|
||
**图源**
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [yggdrasil.go](file://internal/model/yggdrasil.go#L1-L49)
|
||
|
||
**本节来源**
|
||
- [user_service.go](file://internal/service/user_service.go#L1-L249)
|
||
- [auth.go](file://internal/middleware/auth.go#L1-L79)
|
||
|
||
### 材质管理分析
|
||
材质管理模块允许用户上传、搜索和下载 Minecraft 皮肤与披风。每个材质记录包含上传者信息、名称、描述、类型、URL、哈希值等元数据。系统通过 MinIO/RustFS 存储实际的材质文件，PostgreSQL 存储元数据。Redis 用于缓存热门材质和下载统计，提高性能。
|
||
|
||
#### 序列图
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Handler as "处理器"
|
||
participant Service as "服务"
|
||
participant Repository as "仓库"
|
||
participant MinIO as "MinIO/RustFS"
|
||
Client->>Handler : 上传材质
|
||
Handler->>Service : 调用CreateTexture
|
||
Service->>Repository : 检查哈希是否存在
|
||
Repository->>PostgreSQL : 查询数据库
|
||
Repository-->>Service : 返回结果
|
||
Service->>MinIO : 生成预签名URL
|
||
MinIO-->>Service : 返回URL
|
||
Service-->>Handler : 返回上传URL
|
||
Handler-->>Client : 返回预签名URL
|
||
```
|
||
|
||
**图源**
|
||
- [texture_service.go](file://internal/service/texture_service.go#L1-L252)
|
||
- [minio.go](file://pkg/storage/minio.go#L1-L121)
|
||
|
||
**本节来源**
|
||
- [texture_service.go](file://internal/service/texture_service.go#L1-L252)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
|
||
### 档案系统分析
|
||
档案系统为每个用户提供了多个 Minecraft 角色档案，支持设置活跃档案和管理皮肤与披风。每个档案包含 UUID、用户名、皮肤和披风的引用。系统通过 RSA 密钥对确保档案的安全性，支持 Yggdrasil 协议的身份验证。
|
||
|
||
#### 流程图
|
||
```mermaid
|
||
flowchart TD
|
||
Start([创建档案]) --> ValidateUser["验证用户存在"]
|
||
ValidateUser --> CheckName["检查角色名是否已存在"]
|
||
CheckName --> GenerateUUID["生成UUID"]
|
||
GenerateUUID --> GenerateKey["生成RSA密钥对"]
|
||
GenerateKey --> CreateProfile["创建档案记录"]
|
||
CreateProfile --> SetActive["设置为活跃档案"]
|
||
SetActive --> End([档案创建成功])
|
||
```
|
||
|
||
**图源**
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
|
||
**本节来源**
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
|
||
### Yggdrasil 协议集成分析
|
||
Yggdrasil 协议集成确保了 CarrotSkin 与 Minecraft 客户端的兼容性。系统实现了身份验证、令牌验证、刷新和服务器加入等功能。通过 Redis 存储会话信息，确保玩家在加入服务器时的身份验证。
|
||
|
||
#### 序列图
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "Minecraft客户端"
|
||
participant Handler as "处理器"
|
||
participant Service as "服务"
|
||
participant Repository as "仓库"
|
||
participant Redis as "Redis"
|
||
Client->>Handler : authenticate
|
||
Handler->>Service : 调用Authenticate
|
||
Service->>Repository : 验证用户凭证
|
||
Repository->>PostgreSQL : 查询用户
|
||
Repository-->>Service : 返回用户信息
|
||
Service->>Redis : 存储会话数据
|
||
Redis-->>Service : 确认存储
|
||
Service-->>Handler : 返回认证结果
|
||
Handler-->>Client : 返回访问令牌
|
||
```
|
||
|
||
**图源**
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L1-L202)
|
||
- [redis.go](file://pkg/redis/redis.go#L1-L175)
|
||
|
||
**本节来源**
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L1-L202)
|
||
- [yggdrasil.go](file://internal/model/yggdrasil.go#L1-L49)
|
||
|
||
## 依赖分析
|
||
CarrotSkin 依赖于多个外部系统和库，包括 PostgreSQL 用于持久化存储，Redis 用于缓存和会话管理，MinIO/RustFS 用于对象存储。Gin 框架提供了高效的 HTTP 路由和中间件支持，GORM 简化了数据库操作。JWT 用于安全的用户认证，Viper 用于配置管理。
|
||
|
||
```mermaid
|
||
graph TD
|
||
CarrotSkin --> PostgreSQL
|
||
CarrotSkin --> Redis
|
||
CarrotSkin --> MinIO
|
||
CarrotSkin --> Gin
|
||
CarrotSkin --> GORM
|
||
CarrotSkin --> JWT
|
||
CarrotSkin --> Viper
|
||
```
|
||
|
||
**图源**
|
||
- [go.mod](file://go.mod#L1-L92)
|
||
- [config.go](file://pkg/config/config.go#L1-L305)
|
||
|
||
**本节来源**
|
||
- [go.mod](file://go.mod#L1-L92)
|
||
- [config.go](file://pkg/config/config.go#L1-L305)
|
||
|
||
## 性能考虑
|
||
CarrotSkin 在设计时充分考虑了性能优化。通过 Redis 缓存频繁访问的数据，如用户会话、验证码和热门材质，减少了数据库的负载。MinIO/RustFS 提供了高效的对象存储，支持大规模文件上传和下载。Gin 框架的高性能特性确保了快速的请求处理。此外，系统通过分页和限制查询结果数量，避免了大数据量查询对性能的影响。
|
||
|
||
## 故障排除指南
|
||
在使用 CarrotSkin 时，可能会遇到一些常见问题。例如，用户无法登录可能是由于密码错误或账户被禁用。材质上传失败可能是由于文件大小超出限制或存储桶配置错误。Yggdrasil 身份验证失败可能是由于令牌过期或会话数据不匹配。建议检查日志文件以获取详细的错误信息，并确保所有外部服务（如 PostgreSQL、Redis 和 MinIO）正常运行。
|
||
|
||
**本节来源**
|
||
- [user_service.go](file://internal/service/user_service.go#L1-L249)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L1-L252)
|
||
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L1-L202)
|
||
|
||
## 结论
|
||
CarrotSkin 是一个功能丰富且安全可靠的 Minecraft 皮肤站后端服务。通过分层架构和模块化设计，系统实现了清晰的职责分离，便于维护和扩展。与 PostgreSQL、Redis 和 MinIO/RustFS 的集成确保了数据的持久性和高性能。Yggdrasil 协议的支持使得系统能够无缝对接 Minecraft 客户端。未来，可以进一步优化性能，增加更多的用户功能，如皮肤编辑器和社区互动。 |