# 项目概述 **本文档引用的文件** - [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) ## 目录 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 客户端。未来，可以进一步优化性能，增加更多的用户功能，如皮肤编辑器和社区互动。