CarrotSkin/frontend

Fork 0

Files

Mikuisnotavailable 167c51b20d 修复角色中心组件中的类型不匹配错误，改进skinId和capeId的类型处理逻辑

2025-10-16 01:59:17 +08:00

8.5 KiB

Raw Blame History

ProfileService - 角色管理服务

ProfileService是CarrotSkin皮肤站的角色管理微服务，负责处理Minecraft角色的创建、管理、RSA密钥生成和签名验证等核心功能。

📋 目录

功能特性
技术架构
数据模型
API接口
部署指南
开发指南
故障排查

🚀 功能特性

核心功能

角色管理: 创建、查询、更新、删除Minecraft角色
RSA密钥管理: 自动生成RSA-2048密钥对，支持数据签名和验证
皮肤/披风关联: 管理角色与皮肤、披风的关联关系
用户角色列表: 支持查询用户下的所有角色
数据验证: 完整的参数验证和业务逻辑检查

安全特性

RSA签名: 支持使用私钥对数据进行签名
签名验证: 支持使用公钥验证数据签名
权限控制: 确保用户只能操作自己的角色
数据完整性: 完整的事务处理和数据一致性保证

🏗️ 技术架构

技术栈

框架: go-zero微服务框架
数据库: MySQL 8.0+
缓存: Redis (通过go-zero集成)
通信协议: gRPC
密钥算法: RSA-2048

服务架构

ProfileService
├── internal/
│   ├── config/          # 配置管理
│   ├── handler/         # gRPC处理器
│   ├── logic/           # 业务逻辑层
│   ├── model/           # 数据模型层
│   └── svc/            # 服务上下文
├── pb/                  # Protocol Buffers定义
└── docs/               # 文档和SQL脚本

📊 数据模型

数据库表结构

CREATE TABLE `profiles` (
  `uuid` VARCHAR(36) NOT NULL COMMENT '角色的UUID，通常为Minecraft玩家的UUID',
  `user_id` BIGINT UNSIGNED NOT NULL COMMENT '关联的用户ID',
  `name` VARCHAR(16) NOT NULL COMMENT '角色名 (Minecraft In-Game Name)',
  `skin_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '当前使用的皮肤ID',
  `cape_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '当前使用的披风ID',
  `rsa_private_key` TEXT NOT NULL COMMENT 'RSA-2048私钥 (PEM格式)',
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`uuid`),
  INDEX `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

数据类型映射

字段	SQL类型	Go Model类型	Proto类型	说明
uuid	VARCHAR(36)	string	string	角色UUID
user_id	BIGINT UNSIGNED	uint64	int64	用户ID
name	VARCHAR(16)	string	string	角色名
skin_id	BIGINT UNSIGNED NULL	sql.NullInt64	int64	皮肤ID (0表示无皮肤)
cape_id	BIGINT UNSIGNED NULL	sql.NullInt64	int64	披风ID (0表示无披风)
rsa_private_key	TEXT	string	string	RSA私钥
created_at	TIMESTAMP	time.Time	string	创建时间
updated_at	TIMESTAMP	time.Time	string	更新时间

🔌 API接口

对外接口 (Public APIs)

1. CreateProfile - 创建角色

rpc CreateProfile(CreateProfileRequest) returns (CreateProfileResponse);

功能: 创建新的Minecraft角色
验证: UUID格式、角色名格式、用户权限
特性: 自动生成RSA密钥对、角色名去重检查

2. GetProfile - 获取角色信息

rpc GetProfile(GetProfileRequest) returns (GetProfileResponse);

功能: 根据UUID获取角色基本信息
返回: 不包含私钥的公开信息

3. GetProfilesByUserId - 获取用户角色列表

rpc GetProfilesByUserId(GetProfilesByUserIdRequest) returns (GetProfilesByUserIdResponse);

功能: 获取指定用户的所有角色列表
特性: 支持空结果返回

4. UpdateProfile - 更新角色信息

rpc UpdateProfile(UpdateProfileRequest) returns (UpdateProfileResponse);

功能: 更新角色名、皮肤ID、披风ID
验证: 角色名重复检查、权限验证
特性: 支持NULL值处理 (0表示移除)

5. DeleteProfile - 删除角色

rpc DeleteProfile(DeleteProfileRequest) returns (DeleteProfileResponse);

功能: 删除指定角色
验证: 权限检查

6. GetProfilePublicKey - 获取角色公钥

rpc GetProfilePublicKey(GetProfilePublicKeyRequest) returns (GetProfilePublicKeyResponse);

功能: 获取角色的RSA公钥
用途: 用于验证角色签名

7. VerifyProfileSignature - 验证角色签名

rpc VerifyProfileSignature(VerifyProfileSignatureRequest) returns (VerifyProfileSignatureResponse);

功能: 验证使用角色私钥生成的签名
算法: RSA-2048 + SHA-256

8. GetProfileWithProperties - 查询角色属性

rpc GetProfileWithProperties(GetProfileWithPropertiesRequest) returns (GetProfileWithPropertiesResponse);

功能: 查询角色完整信息，包含Minecraft协议兼容的属性和签名
用途: 用于游戏客户端获取皮肤、披风等信息
特性: 支持生成带签名和不带签名的属性

9. GetProfilesByNames - 批量查询角色

rpc GetProfilesByNames(GetProfilesByNamesRequest) returns (GetProfilesByNamesResponse);

功能: 根据角色名称列表批量查询角色信息
返回: 简化的角色信息列表（UUID和名称）

10. GetUserIdByProfileName - 根据角色名获取用户ID

rpc GetUserIdByProfileName(GetUserIdByProfileNameRequest) returns (GetUserIdByProfileNameResponse);

功能: 根据角色名称查找关联的用户ID
用途: 支持使用角色名进行登录等操作

对内接口 (Internal APIs)

11. GetProfileInternalInfo - 获取角色内部信息

rpc GetProfileInternalInfo(GetProfileInternalInfoRequest) returns (ProfileInternalInfo);

功能: 获取包含私钥的完整角色信息
权限: 仅供内部微服务调用
安全: 包含敏感信息，需要严格权限控制

12. SignData - 使用私钥签名数据

rpc SignData(SignDataRequest) returns (SignDataResponse);

功能: 使用角色私钥对数据进行签名
算法: RSA-2048 + SHA-256
返回: Base64编码的签名结果

🚀 部署指南

环境要求

Go 1.19+
MySQL 8.0+
Redis 6.0+

配置文件示例

# etc/profile.yaml
Name: profile.rpc
ListenOn: 0.0.0.0:8082

#Etcd:
#  Hosts:
#    - 127.0.0.1:2379
#  Key: profile.rpc

DataSource: root:password@tcp(localhost:3306)/carrot_skin?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai

CacheConf:
  - Host: 127.0.0.1:6379
    Pass: ""
    Type: node

部署步骤

数据库初始化

mysql -u root -p carrot_skin < docs/profiles.sql

编译服务

go build -o profile-service .

启动服务

./profile-service -f etc/profile.yaml

🛠️ 开发指南

代码生成

使用提供的脚本重新生成代码：

# Windows
generate.bat

# Linux/Mac
chmod +x generate.sh
./generate.sh

业务逻辑扩展

所有业务逻辑都在 internal/logic/ 目录下：

createProfileLogic.go - 角色创建逻辑
getProfileLogic.go - 角色查询逻辑
updateProfileLogic.go - 角色更新逻辑
deleteProfileLogic.go - 角色删除逻辑
等等...

数据模型扩展

如需添加新的数据库方法，在 internal/model/profilesmodel.go 中扩展：

type ProfilesModel interface {
    profilesModel
    // 添加自定义方法
    FindByUserId(ctx context.Context, userId uint64) ([]*Profiles, error)
}

🔧 故障排查

常见问题

1. 数据类型转换错误

问题: sql.NullInt64 类型处理错误解决: 使用 nullInt64ToValue() 函数进行正确转换

2. RSA密钥生成失败

问题: RSA密钥生成或解析失败解决: 检查系统随机数生成器，确保有足够的熵

3. 角色名重复

问题: 同一用户下角色名重复解决: 创建和更新时都会进行重复检查

4. UUID格式错误

问题: UUID格式不符合标准解决: 确保UUID为36位标准格式 (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

日志级别

INFO: 正常业务操作
ERROR: 业务错误和系统错误
DEBUG: 详细的调试信息

性能监控

数据库连接池状态
Redis缓存命中率
gRPC请求响应时间
RSA密钥操作耗时

8.5 KiB Raw Blame History Unescape Escape