feat(yggdrasil): implement standard error responses and UUID format improvements

- Add YggdrasilErrorResponse struct and standard error codes for protocol compliance - Change UUID storage from varchar(36) to varchar(32) for unsigned format - Add utility functions: GenerateUUID, FormatUUIDToNoDash, RandomHex - Support unsigned query parameter in GetProfileByUUID endpoint - Improve refresh token response with available profiles list - Fix key pair retrieval to use correct database column (rsa_private_key) - Update UUID validator to accept both 32-char and 36-char formats - Add SignStringWithProfileRSA method for profile-specific signing - Fix profile assignment validation in refresh token flow
2026-02-23 13:26:53 +08:00
parent 3e8b7d150d
commit 29f0bad2bc
16 changed files with 719 additions and 89 deletions
--- a/internal/errors/errors.go
+++ b/internal/errors/errors.go
@@ -60,6 +60,10 @@ var (
 	ErrUUIDRequired        = errors.New("UUID不能为空")
 	ErrCertificateGenerate = errors.New("生成证书失败")

+	// Yggdrasil协议标准错误
+	ErrYggForbiddenOperation = errors.New("ForbiddenOperationException")
+	ErrYggIllegalArgument    = errors.New("IllegalArgumentException")
+
 	// 通用错误
 	ErrBadRequest     = errors.New("请求参数错误")
 	ErrInternalServer = errors.New("服务器内部错误")
@@ -138,3 +142,29 @@ func Wrap(err error, message string) error {
 	}
 	return fmt.Errorf("%s: %w", message, err)
 }
+
+// YggdrasilErrorResponse Yggdrasil协议标准错误响应格式
+type YggdrasilErrorResponse struct {
+	Error        string `json:"error"`           // 错误的简要描述（机器可读）
+	ErrorMessage string `json:"errorMessage"`    // 错误的详细信息（人类可读）
+	Cause        string `json:"cause,omitempty"` // 该错误的原因（可选）
+}
+
+// NewYggdrasilErrorResponse 创建Yggdrasil标准错误响应
+func NewYggdrasilErrorResponse(error, errorMessage, cause string) *YggdrasilErrorResponse {
+	return &YggdrasilErrorResponse{
+		Error:        error,
+		ErrorMessage: errorMessage,
+		Cause:        cause,
+	}
+}
+
+// YggdrasilErrorCodes Yggdrasil协议错误码常量
+const (
+	// ForbiddenOperationException 错误消息
+	YggErrInvalidToken       = "Invalid token."
+	YggErrInvalidCredentials = "Invalid credentials. Invalid username or password."
+
+	// IllegalArgumentException 错误消息
+	YggErrProfileAlreadyAssigned = "Access token already has a profile assigned."
+)
--- a/internal/handler/yggdrasil_handler.go
+++ b/internal/handler/yggdrasil_handler.go
@@ -3,6 +3,7 @@ package handler
 import (
 	"bytes"
 	"carrotskin/internal/container"
+	"carrotskin/internal/errors"
 	"carrotskin/internal/model"
 	"carrotskin/pkg/utils"
 	"io"
@@ -129,10 +130,11 @@ type (

 	// RefreshResponse 刷新令牌响应
 	RefreshResponse struct {
-		AccessToken     string                 `json:"accessToken"`
-		ClientToken     string                 `json:"clientToken"`
-		SelectedProfile map[string]interface{} `json:"selectedProfile,omitempty"`
-		User            map[string]interface{} `json:"user,omitempty"`
+		AccessToken       string                   `json:"accessToken"`
+		ClientToken       string                   `json:"clientToken"`
+		SelectedProfile   map[string]interface{}   `json:"selectedProfile,omitempty"`
+		AvailableProfiles []map[string]interface{} `json:"availableProfiles"`
+		User              map[string]interface{}   `json:"user,omitempty"`
 	}
 )

@@ -202,7 +204,11 @@ func (h *YggdrasilHandler) Authenticate(c *gin.Context) {
 		profile, err = h.container.ProfileRepo.FindByName(c.Request.Context(), request.Identifier)
 		if err != nil {
 			h.logger.Error("用户名不存在", zap.String("identifier", request.Identifier), zap.Error(err))
-			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+				"ForbiddenOperationException",
+				errors.YggErrInvalidCredentials,
+				"",
+			))
 			return
 		}
 		userId = profile.UserID
@@ -211,13 +217,21 @@ func (h *YggdrasilHandler) Authenticate(c *gin.Context) {

 	if err != nil {
 		h.logger.Warn("认证失败: 用户不存在", zap.String("identifier", request.Identifier), zap.Error(err))
-		c.JSON(http.StatusForbidden, gin.H{"error": "用户不存在"})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidCredentials,
+			"",
+		))
 		return
 	}

 	if err := h.container.YggdrasilService.VerifyPassword(c.Request.Context(), request.Password, userId); err != nil {
 		h.logger.Warn("认证失败: 密码错误", zap.Error(err))
-		c.JSON(http.StatusForbidden, gin.H{"error": ErrWrongPassword})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidCredentials,
+			"",
+		))
 		return
 	}

@@ -264,7 +278,7 @@ func (h *YggdrasilHandler) Authenticate(c *gin.Context) {
 // @Produce json
 // @Param request body ValidTokenRequest true "验证请求"
 // @Success 204 "令牌有效"
-// @Failure 403 {object} map[string]bool "令牌无效"
+// @Failure 403 {object} errors.YggdrasilErrorResponse "令牌无效"
 // @Router /api/v1/yggdrasil/authserver/validate [post]
 func (h *YggdrasilHandler) ValidToken(c *gin.Context) {
 	var request ValidTokenRequest
@@ -276,10 +290,14 @@ func (h *YggdrasilHandler) ValidToken(c *gin.Context) {

 	if h.container.TokenService.Validate(c.Request.Context(), request.AccessToken, request.ClientToken) {
 		h.logger.Info("令牌验证成功", zap.String("accessToken", request.AccessToken))
-		c.JSON(http.StatusNoContent, gin.H{"valid": true})
+		c.JSON(http.StatusNoContent, gin.H{})
 	} else {
 		h.logger.Warn("令牌验证失败", zap.String("accessToken", request.AccessToken))
-		c.JSON(http.StatusForbidden, gin.H{"valid": false})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
 	}
 }

@@ -301,19 +319,33 @@ func (h *YggdrasilHandler) RefreshToken(c *gin.Context) {
 		return
 	}

-	UUID, err := h.container.TokenService.GetUUIDByAccessToken(c.Request.Context(), request.AccessToken)
+	// 获取用户ID和当前绑定的Profile UUID
+	userID, err := h.container.TokenService.GetUserIDByAccessToken(c.Request.Context(), request.AccessToken)
 	if err != nil {
 		h.logger.Warn("刷新令牌失败: 无效的访问令牌", zap.String("token", request.AccessToken), zap.Error(err))
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
 		return
 	}

-	userID, _ := h.container.TokenService.GetUserIDByAccessToken(c.Request.Context(), request.AccessToken)
-	UUID = utils.FormatUUID(UUID)
-
-	profile, err := h.container.ProfileService.GetByUUID(c.Request.Context(), UUID)
+	currentUUID, err := h.container.TokenService.GetUUIDByAccessToken(c.Request.Context(), request.AccessToken)
 	if err != nil {
-		h.logger.Error("刷新令牌失败: 无法获取用户信息", zap.Error(err))
+		h.logger.Warn("刷新令牌失败: 无法获取当前Profile", zap.String("token", request.AccessToken), zap.Error(err))
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
+		return
+	}
+
+	// 获取用户的所有可用profiles
+	availableProfiles, err := h.container.ProfileService.GetByUserID(c.Request.Context(), userID)
+	if err != nil {
+		h.logger.Error("刷新令牌失败: 无法获取用户profiles", zap.Error(err), zap.Int64("userId", userID))
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
@@ -322,6 +354,7 @@ func (h *YggdrasilHandler) RefreshToken(c *gin.Context) {
 	var userData map[string]interface{}
 	var profileID string

+	// 处理selectedProfile
 	if request.SelectedProfile != nil {
 		profileIDValue, ok := request.SelectedProfile["id"]
 		if !ok {
@@ -337,25 +370,69 @@ func (h *YggdrasilHandler) RefreshToken(c *gin.Context) {
 			return
 		}

-		profileID = utils.FormatUUID(profileID)
+		// 确保profileID是32位无符号格式（用于向后兼容）
+		profileID = utils.FormatUUIDToNoDash(profileID)
+
+		// 根据Yggdrasil规范：当指定selectedProfile时，原令牌所绑定的角色必须为空
+		// 如果原令牌已绑定角色，则不允许更换角色，但允许选择相同的角色以兼容部分启动器
+		if currentUUID != "" && currentUUID != profileID {
+			h.logger.Warn("刷新令牌失败: 令牌已绑定其他角色，不允许更换",
+				zap.Int64("userId", userID),
+				zap.String("currentUUID", currentUUID),
+				zap.String("requestedUUID", profileID),
+			)
+			c.JSON(http.StatusBadRequest, errors.NewYggdrasilErrorResponse(
+				"IllegalArgumentException",
+				errors.YggErrProfileAlreadyAssigned,
+				"",
+			))
+			return
+		}
+
+		// 验证profile是否属于该用户
+		profile, err := h.container.ProfileService.GetByUUID(c.Request.Context(), profileID)
+		if err != nil {
+			h.logger.Warn("刷新令牌失败: Profile不存在", zap.String("profileId", profileID), zap.Error(err))
+			c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+				"ForbiddenOperationException",
+				errors.YggErrInvalidToken,
+				"",
+			))
+			return
+		}

 		if profile.UserID != userID {
 			h.logger.Warn("刷新令牌失败: 用户不匹配",
 				zap.Int64("userId", userID),
 				zap.Int64("profileUserId", profile.UserID),
 			)
-			c.JSON(http.StatusBadRequest, gin.H{"error": ErrUserNotMatch})
+			c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+				"ForbiddenOperationException",
+				errors.YggErrInvalidToken,
+				"",
+			))
 			return
 		}

 		profileData = h.container.YggdrasilService.SerializeProfile(c.Request.Context(), *profile)
+	} else {
+		// 如果未指定selectedProfile，使用当前token绑定的profile（如果存在）
+		if currentUUID != "" {
+			profile, err := h.container.ProfileService.GetByUUID(c.Request.Context(), currentUUID)
+			if err == nil && profile != nil {
+				profileID = currentUUID
+				profileData = h.container.YggdrasilService.SerializeProfile(c.Request.Context(), *profile)
+			}
+		}
 	}

+	// 获取用户信息（如果请求）
 	user, _ := h.container.UserService.GetByID(c.Request.Context(), userID)
 	if request.RequestUser && user != nil {
-		userData = h.container.YggdrasilService.SerializeUser(c.Request.Context(), user, UUID)
+		userData = h.container.YggdrasilService.SerializeUser(c.Request.Context(), user, currentUUID)
 	}

+	// 刷新token
 	newAccessToken, newClientToken, err := h.container.TokenService.Refresh(c.Request.Context(),
 		request.AccessToken,
 		request.ClientToken,
@@ -363,16 +440,27 @@ func (h *YggdrasilHandler) RefreshToken(c *gin.Context) {
 	)
 	if err != nil {
 		h.logger.Error("刷新令牌失败", zap.Error(err), zap.Int64("userId", userID))
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
 		return
 	}

+	// 序列化可用profiles
+	availableProfilesData := make([]map[string]interface{}, 0, len(availableProfiles))
+	for _, p := range availableProfiles {
+		availableProfilesData = append(availableProfilesData, h.container.YggdrasilService.SerializeProfile(c.Request.Context(), *p))
+	}
+
 	h.logger.Info("刷新令牌成功", zap.Int64("userId", userID))
 	c.JSON(http.StatusOK, RefreshResponse{
-		AccessToken:     newAccessToken,
-		ClientToken:     newClientToken,
-		SelectedProfile: profileData,
-		User:            userData,
+		AccessToken:       newAccessToken,
+		ClientToken:       newClientToken,
+		SelectedProfile:   profileData,
+		AvailableProfiles: availableProfilesData,
+		User:              userData,
 	})
 }

@@ -431,7 +519,11 @@ func (h *YggdrasilHandler) SignOut(c *gin.Context) {

 	if err := h.container.YggdrasilService.VerifyPassword(c.Request.Context(), request.Password, user.ID); err != nil {
 		h.logger.Warn("登出失败: 密码错误", zap.Int64("userId", user.ID))
-		c.JSON(http.StatusBadRequest, gin.H{"error": ErrWrongPassword})
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidCredentials,
+			"",
+		))
 		return
 	}

@@ -447,22 +539,35 @@ func (h *YggdrasilHandler) SignOut(c *gin.Context) {
 // @Accept json
 // @Produce json
 // @Param uuid path string true "用户UUID"
+// @Param unsigned query string false "是否不返回签名（true/false，默认false）"
 // @Success 200 {object} map[string]interface{} "档案信息"
-// @Failure 500 {object} APIResponse "服务器错误"
+// @Failure 404 {object} errors.YggdrasilErrorResponse "档案不存在"
 // @Router /api/v1/yggdrasil/sessionserver/session/minecraft/profile/{uuid} [get]
 func (h *YggdrasilHandler) GetProfileByUUID(c *gin.Context) {
-	uuid := utils.FormatUUID(c.Param("uuid"))
+	uuid := c.Param("uuid")
 	h.logger.Info("获取配置文件请求", zap.String("uuid", uuid))

 	profile, err := h.container.ProfileService.GetByUUID(c.Request.Context(), uuid)
 	if err != nil {
 		h.logger.Error("获取配置文件失败", zap.Error(err), zap.String("uuid", uuid))
-		standardResponse(c, http.StatusInternalServerError, nil, err.Error())
+		c.JSON(http.StatusNotFound, errors.NewYggdrasilErrorResponse(
+			"Not Found",
+			"Profile not found",
+			"",
+		))
 		return
 	}

-	h.logger.Info("成功获取配置文件", zap.String("uuid", uuid), zap.String("name", profile.Name))
-	c.JSON(http.StatusOK, h.container.YggdrasilService.SerializeProfile(c.Request.Context(), *profile))
+	// 读取 unsigned 查询参数
+	unsignedParam := c.DefaultQuery("unsigned", "false")
+	unsigned := unsignedParam == "true"
+
+	h.logger.Info("成功获取配置文件",
+		zap.String("uuid", uuid),
+		zap.String("name", profile.Name),
+		zap.Bool("unsigned", unsigned))
+
+	c.JSON(http.StatusOK, h.container.YggdrasilService.SerializeProfileWithUnsigned(c.Request.Context(), *profile, unsigned))
 }

 // JoinServer 加入服务器
@@ -482,7 +587,11 @@ func (h *YggdrasilHandler) JoinServer(c *gin.Context) {

 	if err := c.ShouldBindJSON(&request); err != nil {
 		h.logger.Error("解析加入服务器请求失败", zap.Error(err), zap.String("ip", clientIP))
-		standardResponse(c, http.StatusBadRequest, nil, ErrInvalidRequest)
+		c.JSON(http.StatusBadRequest, errors.NewYggdrasilErrorResponse(
+			"Bad Request",
+			"Invalid request format",
+			"",
+		))
 		return
 	}

@@ -499,7 +608,11 @@ func (h *YggdrasilHandler) JoinServer(c *gin.Context) {
 			zap.String("userUUID", request.SelectedProfile),
 			zap.String("ip", clientIP),
 		)
-		standardResponse(c, http.StatusInternalServerError, nil, ErrJoinServerFailed)
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
 		return
 	}

@@ -557,7 +670,7 @@ func (h *YggdrasilHandler) HasJoinedServer(c *gin.Context) {
 		return
 	}

-	profile, err := h.container.ProfileService.GetByUUID(c.Request.Context(), username)
+	profile, err := h.container.ProfileService.GetByProfileName(c.Request.Context(), username)
 	if err != nil {
 		h.logger.Error("获取用户配置文件失败", zap.Error(err), zap.String("username", username))
 		standardResponse(c, http.StatusNoContent, nil, ErrProfileNotFound)
@@ -628,7 +741,11 @@ func (h *YggdrasilHandler) GetMetaData(c *gin.Context) {
 	signature, err := h.container.YggdrasilService.GetPublicKey(c.Request.Context())
 	if err != nil {
 		h.logger.Error("获取公钥失败", zap.Error(err))
-		standardResponse(c, http.StatusInternalServerError, nil, ErrInternalServer)
+		c.JSON(http.StatusInternalServerError, errors.NewYggdrasilErrorResponse(
+			"Internal Server Error",
+			"Failed to get public key",
+			"",
+		))
 		return
 	}

@@ -648,27 +765,40 @@ func (h *YggdrasilHandler) GetMetaData(c *gin.Context) {
 // @Produce json
 // @Param Authorization header string true "Bearer {token}"
 // @Success 200 {object} map[string]interface{} "证书信息"
-// @Failure 401 {object} map[string]string "未授权"
-// @Failure 500 {object} APIResponse "服务器错误"
+// @Failure 401 {object} errors.YggdrasilErrorResponse "未授权"
+// @Failure 403 {object} errors.YggdrasilErrorResponse "令牌无效"
+// @Failure 500 {object} errors.YggdrasilErrorResponse "服务器错误"
 // @Router /api/v1/yggdrasil/minecraftservices/player/certificates [post]
 func (h *YggdrasilHandler) GetPlayerCertificates(c *gin.Context) {
 	authHeader := c.GetHeader("Authorization")
 	if authHeader == "" {
-		c.JSON(http.StatusUnauthorized, gin.H{"error": "Authorization header not provided"})
+		c.JSON(http.StatusUnauthorized, errors.NewYggdrasilErrorResponse(
+			"Unauthorized",
+			"Authorization header not provided",
+			"",
+		))
 		c.Abort()
 		return
 	}

 	bearerPrefix := "Bearer "
 	if len(authHeader) < len(bearerPrefix) || authHeader[:len(bearerPrefix)] != bearerPrefix {
-		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid Authorization format"})
+		c.JSON(http.StatusUnauthorized, errors.NewYggdrasilErrorResponse(
+			"Unauthorized",
+			"Invalid Authorization format",
+			"",
+		))
 		c.Abort()
 		return
 	}

 	tokenID := authHeader[len(bearerPrefix):]
 	if tokenID == "" {
-		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid Authorization format"})
+		c.JSON(http.StatusUnauthorized, errors.NewYggdrasilErrorResponse(
+			"Unauthorized",
+			"Invalid Authorization format",
+			"",
+		))
 		c.Abort()
 		return
 	}
@@ -676,16 +806,24 @@ func (h *YggdrasilHandler) GetPlayerCertificates(c *gin.Context) {
 	uuid, err := h.container.TokenService.GetUUIDByAccessToken(c.Request.Context(), tokenID)
 	if uuid == "" {
 		h.logger.Error("获取玩家UUID失败", zap.Error(err))
-		standardResponse(c, http.StatusInternalServerError, nil, ErrInternalServer)
+		c.JSON(http.StatusForbidden, errors.NewYggdrasilErrorResponse(
+			"ForbiddenOperationException",
+			errors.YggErrInvalidToken,
+			"",
+		))
 		return
 	}

-	uuid = utils.FormatUUID(uuid)
+	// UUID已经是32位无符号格式，无需转换

 	certificate, err := h.container.YggdrasilService.GeneratePlayerCertificate(c.Request.Context(), uuid)
 	if err != nil {
 		h.logger.Error("生成玩家证书失败", zap.Error(err))
-		standardResponse(c, http.StatusInternalServerError, nil, ErrInternalServer)
+		c.JSON(http.StatusInternalServerError, errors.NewYggdrasilErrorResponse(
+			"Internal Server Error",
+			"Failed to generate player certificate",
+			"",
+		))
 		return
 	}

--- a/internal/model/client.go
+++ b/internal/model/client.go
@@ -5,10 +5,10 @@ import "time"
 // Client 客户端实体，用于管理Token版本
 // @Description Yggdrasil客户端Token管理数据
 type Client struct {
-	UUID        string    `gorm:"column:uuid;type:varchar(36);primaryKey" json:"uuid"`                                         // Client UUID
+	UUID        string    `gorm:"column:uuid;type:varchar(32);primaryKey" json:"uuid"`                                         // Client UUID
 	ClientToken string    `gorm:"column:client_token;type:varchar(64);not null;uniqueIndex" json:"client_token"`               // 客户端Token
 	UserID      int64     `gorm:"column:user_id;not null;index:idx_clients_user_id" json:"user_id"`                            // 用户ID
-	ProfileID   string    `gorm:"column:profile_id;type:varchar(36);index:idx_clients_profile_id" json:"profile_id,omitempty"` // 选中的Profile
+	ProfileID   string    `gorm:"column:profile_id;type:varchar(32);index:idx_clients_profile_id" json:"profile_id,omitempty"` // 选中的Profile
 	Version     int       `gorm:"column:version;not null;default:0;index:idx_clients_version" json:"version"`                  // 版本号
 	CreatedAt   time.Time `gorm:"column:created_at;type:timestamp;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
 	UpdatedAt   time.Time `gorm:"column:updated_at;type:timestamp;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
--- a/internal/model/profile.go
+++ b/internal/model/profile.go
@@ -7,7 +7,7 @@ import (
 // Profile Minecraft 档案模型
 // @Description Minecraft角色档案数据模型
 type Profile struct {
-	UUID          string     `gorm:"column:uuid;type:varchar(36);primaryKey" json:"uuid"`
+	UUID          string     `gorm:"column:uuid;type:varchar(32);primaryKey" json:"uuid"`
 	UserID        int64      `gorm:"column:user_id;not null;index:idx_profiles_user_created,priority:1" json:"user_id"`
 	Name          string     `gorm:"column:name;type:varchar(16);not null;uniqueIndex:idx_profiles_name" json:"name"` // Minecraft 角色名
 	SkinID        *int64     `gorm:"column:skin_id;type:bigint;index:idx_profiles_skin_id" json:"skin_id,omitempty"`
--- a/internal/repository/profile_repository.go
+++ b/internal/repository/profile_repository.go
@@ -131,8 +131,8 @@ func (r *profileRepository) GetKeyPair(ctx context.Context, profileId string) (*

 	var profile model.Profile
 	result := r.db.WithContext(ctx).
-		Select("key_pair").
-		Where("id = ?", profileId).
+		Select("rsa_private_key").
+		Where("uuid = ?", profileId).
 		First(&profile)

 	if result.Error != nil {
@@ -142,7 +142,9 @@ func (r *profileRepository) GetKeyPair(ctx context.Context, profileId string) (*
 		return nil, fmt.Errorf("获取key pair失败: %w", result.Error)
 	}

-	return &model.KeyPair{}, nil
+	return &model.KeyPair{
+		PrivateKey: profile.RSAPrivateKey,
+	}, nil
 }

 func (r *profileRepository) UpdateKeyPair(ctx context.Context, profileId string, keyPair *model.KeyPair) error {
@@ -154,12 +156,9 @@ func (r *profileRepository) UpdateKeyPair(ctx context.Context, profileId string,
 	}

 	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		result := tx.Table("profiles").
-			Where("id = ?", profileId).
-			UpdateColumns(map[string]interface{}{
-				"private_key": keyPair.PrivateKey,
-				"public_key":  keyPair.PublicKey,
-			})
+		result := tx.Model(&model.Profile{}).
+			Where("uuid = ?", profileId).
+			Update("rsa_private_key", keyPair.PrivateKey)

 		if result.Error != nil {
 			return fmt.Errorf("更新 keyPair 失败: %w", result.Error)
--- a/internal/service/captcha_service.go
+++ b/internal/service/captcha_service.go
@@ -3,13 +3,13 @@ package service
 import (
 	"carrotskin/pkg/config"
 	"carrotskin/pkg/redis"
+	"carrotskin/pkg/utils"
 	"context"
 	"errors"
 	"fmt"
 	"log"
 	"time"

-	"github.com/google/uuid"
 	"github.com/wenlng/go-captcha-assets/resources/imagesv2"
 	"github.com/wenlng/go-captcha-assets/resources/tiles"
 	"github.com/wenlng/go-captcha/v2/slide"
@@ -87,7 +87,7 @@ func NewCaptchaService(redisClient *redis.Client, logger *zap.Logger) CaptchaSer
 // Generate 生成验证码
 func (s *captchaService) Generate(ctx context.Context) (masterImg, tileImg, captchaID string, y int, err error) {
 	// 生成uuid作为验证码进程唯一标识
-	captchaID = uuid.NewString()
+	captchaID = utils.GenerateUUID()
 	if captchaID == "" {
 		err = errors.New("生成验证码唯一标识失败")
 		return
--- a/internal/service/interfaces.go
+++ b/internal/service/interfaces.go
@@ -79,6 +79,7 @@ type TextureService interface {
 type TokenService interface {
 	// 令牌管理
 	Create(ctx context.Context, userID int64, uuid, clientToken string) (*model.Profile, []*model.Profile, string, string, error)
+	CreateWithProfile(ctx context.Context, userID int64, profileUUID string, clientToken string) (*model.Profile, []*model.Profile, string, string, error)
 	Validate(ctx context.Context, accessToken, clientToken string) bool
 	Refresh(ctx context.Context, accessToken, clientToken, selectedProfileID string) (string, string, error)
 	Invalidate(ctx context.Context, accessToken string)
@@ -116,6 +117,7 @@ type YggdrasilService interface {

 	// 序列化
 	SerializeProfile(ctx context.Context, profile model.Profile) map[string]interface{}
+	SerializeProfileWithUnsigned(ctx context.Context, profile model.Profile, unsigned bool) map[string]interface{}
 	SerializeUser(ctx context.Context, user *model.User, uuid string) map[string]interface{}

 	// 证书
--- a/internal/service/profile_service.go
+++ b/internal/service/profile_service.go
@@ -4,6 +4,7 @@ import (
 	"carrotskin/internal/model"
 	"carrotskin/internal/repository"
 	"carrotskin/pkg/database"
+	"carrotskin/pkg/utils"
 	"context"
 	"crypto/rand"
 	"crypto/rsa"
@@ -12,7 +13,6 @@ import (
 	"errors"
 	"fmt"

-	"github.com/google/uuid"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
@@ -64,7 +64,7 @@ func (s *profileService) Create(ctx context.Context, userID int64, name string)
 	}

 	// 生成UUID和RSA密钥
-	profileUUID := uuid.New().String()
+	profileUUID := utils.GenerateUUID()
 	privateKey, err := generateRSAPrivateKeyInternal()
 	if err != nil {
 		return nil, fmt.Errorf("生成RSA密钥失败: %w", err)
--- a/internal/service/signature_service.go
+++ b/internal/service/signature_service.go
@@ -274,3 +274,26 @@ func FormatPublicKey(publicKeyPEM string) string {
 	}
 	return strings.Join(keyLines, "")
 }
+
+// SignStringWithProfileRSA 使用Profile的RSA私钥签名字符串
+func (s *SignatureService) SignStringWithProfileRSA(data string, privateKeyPEM string) (string, error) {
+	// 解析PEM格式的私钥
+	block, _ := pem.Decode([]byte(privateKeyPEM))
+	if block == nil {
+		return "", fmt.Errorf("解析PEM私钥失败")
+	}
+
+	privateKey, err := x509.ParsePKCS1PrivateKey(block.Bytes)
+	if err != nil {
+		return "", fmt.Errorf("解析RSA私钥失败: %w", err)
+	}
+
+	// 签名
+	hashed := sha1.Sum([]byte(data))
+	signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA1, hashed[:])
+	if err != nil {
+		return "", fmt.Errorf("签名失败: %w", err)
+	}
+
+	return base64.StdEncoding.EncodeToString(signature), nil
+}
--- a/internal/service/token_service_redis.go
+++ b/internal/service/token_service_redis.go
@@ -4,12 +4,12 @@ import (
 	"carrotskin/internal/model"
 	"carrotskin/internal/repository"
 	"carrotskin/pkg/auth"
+	"carrotskin/pkg/utils"
 	"context"
 	"errors"
 	"fmt"
 	"time"

-	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5"
 	"go.uber.org/zap"
 )
@@ -63,9 +63,13 @@ func (s *tokenServiceRedis) Create(ctx context.Context, userID int64, UUID strin
 		}
 	}

-	// 生成ClientToken
+	// 生成ClientToken（使用32字符十六进制字符串）
 	if clientToken == "" {
-		clientToken = uuid.New().String()
+		var err error
+		clientToken, err = utils.RandomHex(16) // 16字节 = 32字符十六进制
+		if err != nil {
+			return selectedProfileID, availableProfiles, "", "", fmt.Errorf("生成ClientToken失败: %w", err)
+		}
 	}

 	// 获取或创建Client
@@ -73,7 +77,10 @@ func (s *tokenServiceRedis) Create(ctx context.Context, userID int64, UUID strin
 	existingClient, err := s.clientRepo.FindByClientToken(ctx, clientToken)
 	if err != nil {
 		// Client不存在，创建新的
-		clientUUID := uuid.New().String()
+		clientUUID, err := utils.RandomHex(16) // 16字节 = 32字符十六进制
+		if err != nil {
+			return selectedProfileID, availableProfiles, "", "", fmt.Errorf("生成ClientUUID失败: %w", err)
+		}
 		client = &model.Client{
 			UUID:        clientUUID,
 			ClientToken: clientToken,
@@ -173,6 +180,11 @@ func (s *tokenServiceRedis) Create(ctx context.Context, userID int64, UUID strin
 	return selectedProfileID, availableProfiles, accessToken, clientToken, nil
 }

+// CreateWithProfile 创建Token并绑定指定Profile（使用JWT + Redis存储）
+func (s *tokenServiceRedis) CreateWithProfile(ctx context.Context, userID int64, profileUUID string, clientToken string) (*model.Profile, []*model.Profile, string, string, error) {
+	return s.Create(ctx, userID, profileUUID, clientToken)
+}
+
 // Validate 验证Token（使用JWT验证 + Redis存储验证）
 func (s *tokenServiceRedis) Validate(ctx context.Context, accessToken, clientToken string) bool {
 	// 设置超时上下文
--- a/internal/service/yggdrasil_serialization_service.go
+++ b/internal/service/yggdrasil_serialization_service.go
@@ -14,6 +14,8 @@ import (
 type SerializationService interface {
 	// SerializeProfile 序列化档案为Yggdrasil格式
 	SerializeProfile(ctx context.Context, profile model.Profile) map[string]interface{}
+	// SerializeProfileWithUnsigned 序列化档案为Yggdrasil格式（支持unsigned参数）
+	SerializeProfileWithUnsigned(ctx context.Context, profile model.Profile, unsigned bool) map[string]interface{}
 	// SerializeUser 序列化用户为Yggdrasil格式
 	SerializeUser(ctx context.Context, user *model.User, uuid string) map[string]interface{}
 }
@@ -45,8 +47,13 @@ func NewSerializationService(
 	}
 }

-// SerializeProfile 序列化档案为Yggdrasil格式
+// SerializeProfile 序列化档案为Yggdrasil格式（默认返回签名）
 func (s *yggdrasilSerializationService) SerializeProfile(ctx context.Context, profile model.Profile) map[string]interface{} {
+	return s.SerializeProfileWithUnsigned(ctx, profile, false)
+}
+
+// SerializeProfileWithUnsigned 序列化档案为Yggdrasil格式（支持unsigned参数）
+func (s *yggdrasilSerializationService) SerializeProfileWithUnsigned(ctx context.Context, profile model.Profile, unsigned bool) map[string]interface{} {
 	// 创建基本材质数据
 	texturesMap := make(map[string]interface{})
 	textures := map[string]interface{}{
@@ -99,26 +106,36 @@ func (s *yggdrasilSerializationService) SerializeProfile(ctx context.Context, pr
 	}

 	textureData := base64.StdEncoding.EncodeToString(bytes)
-	signature, err := s.signatureService.SignStringWithSHA1withRSA(textureData)
-	if err != nil {
-		s.logger.Error("签名textures失败",
-			zap.Error(err),
-			zap.String("profileUUID", profile.UUID),
-		)
-		return nil
+
+	// 只有在 unsigned=false 时才签名
+	var signature string
+	if !unsigned {
+		signature, err = s.signatureService.SignStringWithSHA1withRSA(textureData)
+		if err != nil {
+			s.logger.Error("签名textures失败",
+				zap.Error(err),
+				zap.String("profileUUID", profile.UUID),
+			)
+			return nil
+		}
+	}
+
+	// 构建属性
+	property := Property{
+		Name:  "textures",
+		Value: textureData,
+	}
+
+	// 只有在 unsigned=false 时才添加签名
+	if !unsigned {
+		property.Signature = signature
 	}

 	// 构建结果
 	data := map[string]interface{}{
-		"id":   profile.UUID,
-		"name": profile.Name,
-		"properties": []Property{
-			{
-				Name:      "textures",
-				Value:     textureData,
-				Signature: signature,
-			},
-		},
+		"id":         profile.UUID,
+		"name":       profile.Name,
+		"properties": []Property{property},
 	}
 	return data
 }
--- a/internal/service/yggdrasil_service_composite.go
+++ b/internal/service/yggdrasil_service_composite.go
@@ -85,8 +85,8 @@ func (s *yggdrasilServiceComposite) JoinServer(ctx context.Context, serverID, ac
 		return fmt.Errorf("验证Token失败: %w", err)
 	}

-	// 格式化UUID并验证与Token关联的配置文件
-	formattedProfile := utils.FormatUUID(selectedProfile)
+	// 确保UUID是32位无符号格式（用于向后兼容）
+	formattedProfile := utils.FormatUUIDToNoDash(selectedProfile)
 	if uuid != formattedProfile {
 		return errors.New("selectedProfile与Token不匹配")
 	}
@@ -115,6 +115,11 @@ func (s *yggdrasilServiceComposite) SerializeProfile(ctx context.Context, profil
 	return s.serializationService.SerializeProfile(ctx, profile)
 }

+// SerializeProfileWithUnsigned 序列化档案（支持unsigned参数）
+func (s *yggdrasilServiceComposite) SerializeProfileWithUnsigned(ctx context.Context, profile model.Profile, unsigned bool) map[string]interface{} {
+	return s.serializationService.SerializeProfileWithUnsigned(ctx, profile, unsigned)
+}
+
 // SerializeUser 序列化用户
 func (s *yggdrasilServiceComposite) SerializeUser(ctx context.Context, user *model.User, uuid string) map[string]interface{} {
 	return s.serializationService.SerializeUser(ctx, user, uuid)
--- a/internal/service/yggdrasil_validator.go
+++ b/internal/service/yggdrasil_validator.go
@@ -57,16 +57,38 @@ func (v *Validator) ValidateEmail(email string) error {
 	return nil
 }

-// ValidateUUID 验证UUID格式（简单验证）
+// ValidateUUID 验证UUID格式（支持32位无符号和36位带连字符格式）
 func (v *Validator) ValidateUUID(uuid string) error {
 	if uuid == "" {
 		return errors.New("UUID不能为空")
 	}
-	// UUID格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32个十六进制字符 + 4个连字符)
-	if len(uuid) < 32 || len(uuid) > 36 {
-		return errors.New("UUID格式无效")
+
+	// 验证32位无符号UUID格式（纯十六进制字符串）
+	if len(uuid) == 32 {
+		// 检查是否为有效的十六进制字符串
+		for _, c := range uuid {
+			if !((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F')) {
+				return errors.New("UUID格式无效：包含非十六进制字符")
+			}
+		}
+		return nil
 	}
-	return nil
+
+	// 验证36位标准UUID格式（带连字符）
+	if len(uuid) == 36 && uuid[8] == '-' && uuid[13] == '-' && uuid[18] == '-' && uuid[23] == '-' {
+		// 检查除连字符外的字符是否为有效的十六进制
+		for i, c := range uuid {
+			if i == 8 || i == 13 || i == 18 || i == 23 {
+				continue // 跳过连字符位置
+			}
+			if !((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F')) {
+				return errors.New("UUID格式无效：包含非十六进制字符")
+			}
+		}
+		return nil
+	}
+
+	return errors.New("UUID格式无效：长度应为32位或36位")
 }

 // ValidateAccessToken 验证访问令牌
--- a/internal/types/common.go
+++ b/internal/types/common.go
@@ -154,7 +154,7 @@ type TextureInfo struct {
 // ProfileInfo 角色信息
 // @Description Minecraft档案信息
 type ProfileInfo struct {
-	UUID       string     `json:"uuid" example:"550e8400-e29b-41d4-a716-446655440000"`
+	UUID       string     `json:"uuid" example:"550e8400e29b41d4a716446655440000"`
 	UserID     int64      `json:"user_id" example:"1"`
 	Name       string     `json:"name" example:"PlayerName"`
 	SkinID     *int64     `json:"skin_id,omitempty" example:"1"`
--- a/pkg/utils/format.go
+++ b/pkg/utils/format.go
@@ -1,8 +1,12 @@
 package utils

 import (
-	"go.uber.org/zap"
+	"crypto/rand"
+	"encoding/hex"
 	"strings"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
 )

 // FormatUUID 将UUID格式化为带连字符的标准格式
@@ -45,3 +49,49 @@ func FormatUUID(uuid string) string {
 	logger.Warn("[WARN] UUID格式无效: ", zap.String("uuid:", uuid))
 	return uuid
 }
+
+// GenerateUUID 生成无符号UUID（32位十六进制字符串，不带连字符）
+// 使用github.com/google/uuid库生成标准UUID，然后移除连字符
+// 返回格式示例: "123e4567e89b12d3a456426614174000"
+func GenerateUUID() string {
+	return strings.ReplaceAll(uuid.New().String(), "-", "")
+}
+
+// FormatUUIDToNoDash 将带连字符的UUID转换为无符号格式（移除连字符）
+// 输入: "123e4567-e89b-12d3-a456-426614174000"
+// 输出: "123e4567e89b12d3a456426614174000"
+// 如果输入已经是32位格式，直接返回
+// 如果输入格式无效，返回原值并记录警告
+func FormatUUIDToNoDash(uuid string) string {
+	// 如果为空，直接返回
+	if uuid == "" {
+		return uuid
+	}
+
+	// 如果已经是32位格式（无连字符），直接返回
+	if len(uuid) == 32 {
+		return uuid
+	}
+
+	// 如果是36位标准格式，移除连字符
+	if len(uuid) == 36 && uuid[8] == '-' && uuid[13] == '-' && uuid[18] == '-' && uuid[23] == '-' {
+		return strings.ReplaceAll(uuid, "-", "")
+	}
+
+	// 如果格式无效，记录警告并返回原值
+	var logger *zap.Logger
+	logger.Warn("[WARN] UUID格式无效，无法转换为无符号格式: ", zap.String("uuid:", uuid))
+	return uuid
+}
+
+// RandomHex 生成指定长度的随机十六进制字符串
+// 参数 n: 需要生成的十六进制字符数量（每个字节生成2个十六进制字符）
+// 返回: 长度为 2*n 的十六进制字符串
+// 示例: RandomHex(16) 返回 "a1b2c3d4e5f67890abcdef1234567890" (32字符)
+func RandomHex(n uint) (string, error) {
+	bytes := make([]byte, n)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(bytes), nil
+}
--- a/plans/unsigned_uuid_design.md
+++ b/plans/unsigned_uuid_design.md
@@ -0,0 +1,332 @@
+# 无符号UUID实现方案设计
+
+## 1. 概述
+
+### 1.1 背景
+当前项目中UUID使用带连字符的标准格式（36位：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）。为了与Yggdrasil协议更好的兼容并优化存储空间，需要实现无符号UUID（32位十六进制字符串）。
+
+### 1.2 目标
+- 定义无符号UUID的格式规范
+- 设计UUID生成、保存、读取、返回的转换逻辑
+- 确保与Yggdrasil协议的兼容性
+- 提供向后兼容和数据迁移策略
+
+### 1.3 无符号UUID格式
+- **格式**: 32位十六进制字符串（小写）
+- **示例**: `123e4567e89b12d3a456426614174000`
+- **数据库存储**: varchar(32)
+
+---
+
+## 2. 当前UUID使用分析
+
+### 2.1 UUID使用场景
+
+| 场景 | 文件位置 | 用途 |
+|------|----------|------|
+| Profile创建 | [`internal/service/profile_service.go:67`](internal/service/profile_service.go:67) | 生成Profile UUID |
+| Client创建 | [`internal/service/token_service_redis.go:76`](internal/service/token_service_redis.go:76) | 生成Client UUID |
+| 数据库存储 | [`internal/model/profile.go:10`](internal/model/profile.go:10) | Profile表主键 varchar(36) |
+| 数据库存储 | [`internal/model/client.go:8`](internal/model/client.go:8) | Client表主键 varchar(36) |
+| API返回 | [`internal/model/profile.go:34`](internal/model/profile.go:34) | ProfileResponse.JSON |
+| Yggdrasil序列化 | [`internal/service/yggdrasil_serialization_service.go:54`](internal/service/yggdrasil_serialization_service.go:54) | profileId字段 |
+| Yggdrasil序列化 | [`internal/service/yggdrasil_serialization_service.go:113`](internal/service/yggdrasil_serialization_service.go:113) | id字段 |
+
+### 2.2 现有转换函数
+项目已在 [`pkg/utils/format.go`](pkg/utils/format.go) 中实现了 `FormatUUID` 函数：
+- 功能：32位字符串 → 带连字符的36位标准格式
+- 使用场景：Handler层接收参数后转换为标准格式
+
+---
+
+## 3. 转换逻辑设计
+
+### 3.1 核心转换函数
+
+在 [`pkg/utils/format.go`](pkg/utils/format.go) 中扩展以下函数：
+
+```go
+// FormatUUIDToNoDash 将带连字符的UUID转换为无符号UUID（移除连字符）
+// 输入: "123e4567-e89b-12d3-a456-426614174000"
+// 输出: "123e4567e89b12d3a456426614174000"
+func FormatUUIDToNoDash(uuid string) string
+
+// FormatUUIDToDash 将无符号UUID转换为带连字符的标准格式
+// 输入: "123e4567e89b12d3a456426614174000"
+// 输出: "123e4567-e89b-12d3-a456-426614174000"
+func FormatUUIDToDash(uuid string) string
+```
+
+### 3.2 UUID生成策略
+
+```go
+// GenerateUUID 生成无符号UUID
+// 使用github.com/google/uuid库生成标准UUID，然后移除连字符
+func GenerateUUID() string {
+    return uuid.New().String() // 默认生成带连字符的UUID
+    // 移除连字符
+    return strings.ReplaceAll(uuid.New().String(), "-", "")
+}
+```
+
+---
+
+## 4. 数据流转设计
+
+### 4.1 总体数据流
+
+```
+生成UUID (36位标准格式)
+        ↓
+移除连字符 (32位无符号UUID)
+        ↓
+存储到数据库 (varchar(32))
+        ↓
+读取时根据场景转换
+        ├─→ Yggdrasil API: 保持无符号格式
+        └─→ 内部处理/调试: 转换为标准格式
+```
+
+### 4.2 各环节处理
+
+| 环节 | 操作 | 说明 |
+|------|------|------|
+| **生成** | `uuid.New().String()` → 移除`-` | 保持与google/uuid库兼容 |
+| **保存** | 直接存储32位字符串 | 数据库字段改为varchar(32) |
+| **读取** | 直接读取 | 无需转换 |
+| **返回** | 根据API类型选择 | 见4.3节 |
+
+### 4.3 API返回策略
+
+| API类型 | 返回格式 | 原因 |
+|---------|----------|------|
+| Yggdrasil协议 | 32位无符号 | Mojang/Yggdrasil标准 |
+| 内部REST API | 保持存储格式 | 统一简洁 |
+| 调试/日志 | 可选转换 | 便于阅读 |
+
+---
+
+## 5. 需要修改的文件
+
+### 5.1 核心文件修改
+
+| 文件 | 修改内容 |
+|------|----------|
+| [`pkg/utils/format.go`](pkg/utils/format.go) | 添加 `FormatUUIDToNoDash`、`FormatUUIDToDash`、`GenerateUUID` 函数 |
+| [`pkg/utils/format_test.go`](pkg/utils/format_test.go) | 添加新函数的单元测试 |
+| [`internal/model/profile.go`](internal/model/profile.go) | UUID字段类型改为varchar(32) |
+| [`internal/model/client.go`](internal/model/client.go) | UUID字段类型改为varchar(32) |
+
+### 5.2 服务层修改
+
+| 文件 | 修改内容 |
+|------|----------|
+| [`internal/service/profile_service.go`](internal/service/profile_service.go) | UUID生成改用新函数 |
+| [`internal/service/token_service_redis.go`](internal/service/token_service_redis.go) | UUID生成改用新函数 |
+
+### 5.3 Handler层修改
+
+| 文件 | 修改内容 |
+|------|----------|
+| [`internal/handler/yggdrasil_handler.go`](internal/handler/yggdrasil_handler.go) | Yggdrasil API返回无符号UUID |
+| [`internal/handler/profile_handler.go`](internal/handler/profile_handler.go) | 内部API返回无符号UUID |
+
+### 5.4 序列化服务修改
+
+| 文件 | 修改内容 |
+|------|----------|
+| [`internal/service/yggdrasil_serialization_service.go`](internal/service/yggdrasil_serialization_service.go) | profileId和id字段使用无符号UUID |
+
+---
+
+## 6. 实现步骤
+
+### 6.1 第一步：扩展工具函数
+
+在 [`pkg/utils/format.go`](pkg/utils/format.go) 中添加：
+
+1. `FormatUUIDToNoDash(uuid string) string` - 移除连字符
+2. `FormatUUIDToDash(uuid string) string` - 添加连字符（现有函数增强）
+3. `GenerateUUID() string` - 生成无符号UUID
+
+### 6.2 第二步：修改数据模型
+
+1. 修改 [`internal/model/profile.go`](internal/model/profile.go):
+   ```go
+   UUID string `gorm:"column:uuid;type:varchar(32);primaryKey" json:"uuid"`
+   ```
+
+2. 修改 [`internal/model/client.go`](internal/model/client.go):
+   ```go
+   UUID string `gorm:"column:uuid;type:varchar(32);primaryKey" json:"uuid"`
+   ```
+
+### 6.3 第三步：修改服务层
+
+1. 修改 [`internal/service/profile_service.go`](internal/service/profile_service.go:67):
+   ```go
+   // 生成无符号UUID
+   profileUUID := utils.GenerateUUID() // 或 uuid.New().String() 后转换
+   ```
+
+2. 修改 [`internal/service/token_service_redis.go`](internal/service/token_service_redis.go:76):
+   ```go
+   clientUUID := utils.GenerateUUID()
+   ```
+
+### 6.4 第四步：修改Handler层
+
+1. 修改 [`internal/handler/yggdrasil_handler.go`](internal/handler/yggdrasil_handler.go):
+   - 移除 `utils.FormatUUID()` 调用（因为存储的已经是无符号格式）
+   - Yggdrasil API直接返回无符号UUID
+
+2. 修改 [`internal/handler/profile_handler.go`](internal/handler/profile_handler.go):
+   - 同样移除 `utils.FormatUUID()` 调用
+
+### 6.第五步：修改序列化服务
+
+修改 [`internal/service/yggdrasil_serialization_service.go`](internal/service/yggdrasil_serialization_service.go):
+
+```go
+// SerializeProfile - profileId使用无符号UUID
+"profileId": profile.UUID,  // 直接使用存储的32位UUID
+
+// SerializeProfile - id使用无符号UUID  
+"id": profile.UUID,  // 直接使用存储的32位UUID
+```
+
+---
+
+## 7. 向后兼容性设计
+
+### 7.1 双格式支持（可选）
+
+如果需要同时支持新旧客户端，可以：
+
+1. **数据库字段保持varchar(36)** - 存储带连字符的格式
+2. **新增转换函数** - 在返回Yggdrasil响应时转换为无符号格式
+
+### 7.2 推荐策略：渐进式迁移
+
+1. **第一阶段**: 实现新代码，生成和存储无符号UUID
+2. **第二阶段**: 运行数据迁移脚本
+3. **第三阶段**: 移除旧格式支持
+
+---
+
+## 8. 数据迁移策略
+
+### 8.1 迁移脚本设计
+
+```sql
+-- 将profiles表的UUID转换为无符号格式
+UPDATE profiles 
+SET uuid = REPLACE(REPLACE(REPLACE(REPLACE(uuid, '-', ''), 
+    SUBSTRING(uuid, 9, 1), ''), '', ''), '', '')
+WHERE LENGTH(uuid) = 36;
+
+-- 实际迁移SQL（分步骤）
+UPDATE profiles 
+SET uuid = CONCAT(
+    SUBSTRING(uuid, 1, 8),
+    SUBSTRING(uuid, 10, 4),
+    SUBSTRING(uuid, 15, 4),
+    SUBSTRING(uuid, 20, 4),
+    SUBSTRING(uuid, 25, 12)
+)
+WHERE LENGTH(uuid) = 36 AND uuid LIKE '%-%-%-%-%';
+
+-- 同样迁移clients表
+UPDATE clients 
+SET uuid = CONCAT(
+    SUBSTRING(uuid, 1, 8),
+    SUBSTRING(uuid, 10, 4),
+    SUBSTRING(uuid, 15, 4),
+    SUBSTRING(uuid, 20, 4),
+    SUBSTRING(uuid, 25, 12)
+)
+WHERE LENGTH(uuid) = 36 AND uuid LIKE '%-%-%-%-%';
+```
+
+### 8.2 迁移注意事项
+
+1. **备份数据** - 迁移前务必备份数据库
+2. **停服迁移** - 建议在低峰期执行
+3. **验证迁移** - 迁移后验证数据完整性
+4. **回滚方案** - 准备回滚脚本
+
+---
+
+## 9. 测试计划
+
+### 9.1 单元测试
+
+在 [`pkg/utils/format_test.go`](pkg/utils/format_test.go) 中添加：
+
+1. `TestFormatUUIDToNoDash` - 测试移除连字符
+2. `TestFormatUUIDToDash` - 测试添加连字符
+3. `TestGenerateUUID` - 测试UUID生成（32位、唯一性）
+
+### 9.2 集成测试
+
+1. 创建Profile后验证数据库存储格式
+2. Yggdrasil认证流程验证UUID格式
+3. 批量操作（BatchUpdate/BatchDelete）验证UUID处理
+
+---
+
+## 10. 注意事项
+
+### 10.1 Yggdrasil协议兼容性
+
+根据Yggdrasil/Mojang协议规范：
+- 玩家UUID应为32位无符号十六进制字符串
+- profileId字段应为小写
+- 与Minecraft客户端交互时使用此格式
+
+### 10.2 性能考虑
+
+- 新UUID生成无需额外转换（直接生成32位）
+- 数据库varchar(32)比varchar(36)节省约10%存储空间
+- 索引查询效率略有提升
+
+### 10.3 安全性
+
+- UUID应使用加密安全的随机数生成器
+- github.com/google/uuid库默认使用crypto/rand，安全可靠
+
+---
+
+## 11. Mermaid数据流图
+
+```mermaid
+flowchart TD
+    A[uuid.New] --> B{需要格式}
+    B -->|存储| C[FormatUUIDToNoDash]
+    B -->|Yggdrasil返回| C
+    B -->|内部API返回| D[直接使用]
+    
+    C --> E[数据库 varchar(32)]
+    D --> E
+    
+    E --> F{读取场景}
+    F -->|Yggdrasil API| G[保持无符号]
+    F -->|调试/日志| H[FormatUUIDToDash]
+    
+    G --> I[响应客户端]
+    H --> J[控制台输出]
+```
+
+---
+
+## 12. 总结
+
+本方案实现了以下目标：
+
+1. **格式统一定义**: 32位无符号十六进制字符串
+2. **最小化修改**: 保持核心逻辑不变，仅调整格式转换
+3. **Yggdrasil兼容**: 符合Mojang协议的UUID格式要求
+4. **平滑迁移**: 支持渐进式数据迁移
+5. **测试覆盖**: 完整的单元测试和集成测试计划
+
+方案实施后，项目将统一使用无符号UUID格式，提升与Yggdrasil协议的兼容性，并优化存储空间。