CarrotSkin/frontend
4
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

小清洗

Browse Source
This commit is contained in:
Mikuisnotavailable
2025-10-16 02:30:29 +08:00
parent 167c51b20d
commit 7a36c87ff0
5 changed files with 0 additions and 1205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
API测试指南.md
View File

@@ -1,114 +0,0 @@
# API连接测试指南
本指南将帮助您测试前端是否能够成功读取后端数据，以及验证登录和注册功能的实现状态。
## 登录和注册功能实现状态
根据代码分析，**登录和注册功能已经实现并连接到了真实的后端API**。系统采用了以下实现方式：
### 登录功能
- 支持使用用户名或邮箱登录
- 集成了NextAuth.js进行身份验证管理
- 在测试环境中提供测试账号（用户名: `test`, 密码: `test`）
- 非测试账号会调用真实的后端API进行认证：`https://code.littlelan.cn/CarrotSkin/APIgateway/api/v1/auth/login`
- 包含验证码验证机制（非测试账号需要）
### 注册功能
- 完整的表单验证逻辑（用户名、密码、邮箱、Minecraft用户名不能为空）
- 密码强度检查（至少6位）
- 邮箱格式验证
- 验证码验证
- 调用真实的后端注册API：`https://code.littlelan.cn/CarrotSkin/APIgateway/api/v1/auth/register`
## 如何测试后端数据连接
### 方法一：使用API测试页面
1. 访问 `http://localhost:3000/api-tester` 打开API测试工具（已修复）
2. 点击"开始API测试"按钮
3. 查看测试结果，了解各个API端点的连接状态
### 方法二：使用简化API测试页面
1. 访问 `http://localhost:3000/simple-api-test` 打开简化的API测试工具
2. 选择要测试的API端点
3. 输入必要的参数（如用户ID、角色ID等）
4. 点击"测试API"按钮查看返回结果
### 方法三：使用浏览器控制台进行测试
打开浏览器开发者工具（F12），切换到控制台（Console）选项卡，执行以下代码：
```javascript
// 测试材质列表API（无需登录）
fetch('/api/textures')
.then(response => response.json())
.then(data => console.log('材质列表数据:', data))
.catch(error => console.error('获取材质列表失败:', error));
// 如果已登录，可以测试需要认证的API
// 测试用户角色列表
fetch('/api/user-profiles?userId=1', { credentials: 'include' })
.then(response => response.json())
.then(data => console.log('用户角色列表数据:', data))
.catch(error => console.error('获取用户角色列表失败:', error));
```
## 测试登录功能
### 测试测试账号登录
1. 访问 `http://localhost:3000/login` 登录页面
2. 输入用户名：`test`，密码：`test`
3. 点击登录按钮
4. 成功后会自动跳转到用户主页 `http://localhost:3000/user-home`
### 测试注册功能
1. 访问 `http://localhost:3000/register` 注册页面
2. 填写完整的注册信息：
- 用户名：自定义
- 密码：至少6位
- 邮箱：有效的邮箱地址
- Minecraft用户名：自定义
3. 点击获取验证码，输入收到的验证码
4. 点击注册按钮
5. 成功后会提示注册成功并自动跳转到登录页面
## 常见问题排查
1. **API请求失败**
- 检查网络连接是否正常
- 确认后端服务器是否正在运行
- 查看浏览器控制台是否有错误信息
- 检查API端点URL是否正确
2. **登录失败**
- 确认用户名和密码是否正确
- 检查验证码是否输入正确
- 查看是否有网络错误提示
3. **注册失败**
- 确认所有必填项都已填写
- 检查密码是否满足长度要求
- 确认邮箱格式是否正确
- 检查用户名或邮箱是否已被注册
## 高级测试技巧
### 查看API请求详情
1. 打开浏览器开发者工具（F12）
2. 切换到网络（Network）选项卡
3. 刷新页面或执行API操作
4. 查看请求和响应详情，包括状态码、请求头、响应内容等
### 测试特定API端点
使用API测试页面，您可以测试以下主要端点：
- **材质列表**: `/api/textures` - 获取所有材质数据（无需登录）
- **用户角色列表**: `/api/user-profiles?userId={id}` - 获取指定用户的角色列表（需要登录）
- **角色详情**: `/api/profile?profileId={id}` - 获取指定角色的详细信息（需要登录）
- **角色及属性**: `/api/profile-props?profileId={id}` - 获取指定角色及其属性（需要登录）
通过以上测试方法，您可以全面验证前端与后端的连接状态和数据读取能力。

41
API连接说明.md
View File

@@ -1,41 +0,0 @@
# API后端连接说明
## 配置已完成
✅ 已将前端项目配置为连接到您提供的API后端服务：
- **API后端地址**: `https://code.littlelan.cn/CarrotSkin/APIgateway`
## 配置详情
环境变量已在 `.env.local` 文件中更新：
```
NEXT_PUBLIC_API_URL=https://code.littlelan.cn/CarrotSkin/APIgateway
```
## 如何测试连接
1. 确保开发服务器正在运行：
```bash
npm run dev
```
2. 访问应用并尝试登录或上传皮肤等功能，系统将自动连接到配置的API后端。
3. 前端项目中的主要API调用位于：
- `src/lib/api/actions.ts` - 包含登录、注册等用户操作
- `src/lib/api/auth.ts` - 包含认证相关配置
## 注意事项
- **CORS配置**: 请确保您的API后端已正确配置CORS，允许来自前端域名的请求
- **API路径映射**: 前端默认会在API URL后添加相应端点，例如登录API路径为 `/auth/login`
- **环境变量**: `.env.local` 文件不会被Git跟踪，如需在其他环境部署，请确保复制此配置
- **开发调试**: 您可以在浏览器控制台查看API调用情况，以便调试连接问题
## 测试账号
前端项目内置了测试账号功能（用于开发环境）：
- 用户名: `test`
- 密码: `test`
如果您希望禁用测试账号功能，请修改 `src/lib/api/actions.ts` 和 `src/lib/api/auth.ts` 文件中的相关代码。

440
backedREADME (1).md
View File

@@ -1,440 +0,0 @@
# 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. **克隆项目**
```bash
git clone <repository-url>
cd CarrotSkin/backend
```
2. **安装依赖**
```bash
go mod download
```
3. **配置环境**
```bash
# 复制环境变量文件
cp .env.example .env
# 编辑 .env 文件配置数据库、RustFS等服务连接信息
```
**注意**：项目完全依赖 `.env` 文件进行配置，不再使用 YAML 配置文件，便于 Docker 容器化部署。
4. **初始化数据库**
```bash
# 创建数据库
createdb carrotskin
# 初始化表结构
psql -d carrotskin -f scripts/carrotskin_postgres.sql
```
5. **运行服务**
Windows系统：
```bash
run.bat
```
Linux/Mac系统：
```bash
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. **容器部署**: 直接在容器运行时设置环境变量即可
**主要环境变量**:
```bash
# 数据库配置
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` 注册路由
## 部署
### 本地开发
```bash
# 安装依赖
go mod download
# 启动服务 (Windows)
run.bat
# 启动服务 (Linux/Mac)
go run cmd/server/main.go
```
### 生产部署
```bash
# 构建二进制文件
go build -o carrotskin-server cmd/server/main.go
# 运行服务
./carrotskin-server
```
### Docker部署
```bash
# 构建镜像
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. **查看日志**
```bash
# 实时查看日志
tail -f logs/app.log
# 搜索错误日志
grep "ERROR" logs/app.log
```
2. **测试Redis连接**
```bash
redis-cli -h localhost -p 6379 -a your_password
> PING
> KEYS *
```
3. **测试数据库连接**
```bash
psql -h localhost -U postgres -d carrotskin
\dt # 查看所有表
```
4. **测试邮件配置**
- 使用Swagger文档测试 `/api/v1/auth/send-code` 接口
- 检查邮件服务商是否限制发送频率
### 开发调试
启用详细日志：
```bash
# 在 .env 中设置
LOG_LEVEL=debug
SERVER_MODE=debug
```

291
profileServiceREADME (1).md
View File

@@ -1,291 +0,0 @@
# ProfileService - 角色管理服务
ProfileService是CarrotSkin皮肤站的角色管理微服务，负责处理Minecraft角色的创建、管理、RSA密钥生成和签名验证等核心功能。
## 📋 目录
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [数据模型](#数据模型)
- [API接口](#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脚本
```
## 📊 数据模型
### 数据库表结构
```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 - 创建角色
```protobuf
rpc CreateProfile(CreateProfileRequest) returns (CreateProfileResponse);
```
- **功能**: 创建新的Minecraft角色
- **验证**: UUID格式、角色名格式、用户权限
- **特性**: 自动生成RSA密钥对、角色名去重检查
#### 2. GetProfile - 获取角色信息
```protobuf
rpc GetProfile(GetProfileRequest) returns (GetProfileResponse);
```
- **功能**: 根据UUID获取角色基本信息
- **返回**: 不包含私钥的公开信息
#### 3. GetProfilesByUserId - 获取用户角色列表
```protobuf
rpc GetProfilesByUserId(GetProfilesByUserIdRequest) returns (GetProfilesByUserIdResponse);
```
- **功能**: 获取指定用户的所有角色列表
- **特性**: 支持空结果返回
#### 4. UpdateProfile - 更新角色信息
```protobuf
rpc UpdateProfile(UpdateProfileRequest) returns (UpdateProfileResponse);
```
- **功能**: 更新角色名、皮肤ID、披风ID
- **验证**: 角色名重复检查、权限验证
- **特性**: 支持NULL值处理 (0表示移除)
#### 5. DeleteProfile - 删除角色
```protobuf
rpc DeleteProfile(DeleteProfileRequest) returns (DeleteProfileResponse);
```
- **功能**: 删除指定角色
- **验证**: 权限检查
#### 6. GetProfilePublicKey - 获取角色公钥
```protobuf
rpc GetProfilePublicKey(GetProfilePublicKeyRequest) returns (GetProfilePublicKeyResponse);
```
- **功能**: 获取角色的RSA公钥
- **用途**: 用于验证角色签名
#### 7. VerifyProfileSignature - 验证角色签名
```protobuf
rpc VerifyProfileSignature(VerifyProfileSignatureRequest) returns (VerifyProfileSignatureResponse);
```
- **功能**: 验证使用角色私钥生成的签名
- **算法**: RSA-2048 + SHA-256
#### 8. GetProfileWithProperties - 查询角色属性
```protobuf
rpc GetProfileWithProperties(GetProfileWithPropertiesRequest) returns (GetProfileWithPropertiesResponse);
```
- **功能**: 查询角色完整信息，包含Minecraft协议兼容的属性和签名
- **用途**: 用于游戏客户端获取皮肤、披风等信息
- **特性**: 支持生成带签名和不带签名的属性
#### 9. GetProfilesByNames - 批量查询角色
```protobuf
rpc GetProfilesByNames(GetProfilesByNamesRequest) returns (GetProfilesByNamesResponse);
```
- **功能**: 根据角色名称列表批量查询角色信息
- **返回**: 简化的角色信息列表（UUID和名称）
#### 10. GetUserIdByProfileName - 根据角色名获取用户ID
```protobuf
rpc GetUserIdByProfileName(GetUserIdByProfileNameRequest) returns (GetUserIdByProfileNameResponse);
```
- **功能**: 根据角色名称查找关联的用户ID
- **用途**: 支持使用角色名进行登录等操作
### 对内接口 (Internal APIs)
#### 11. GetProfileInternalInfo - 获取角色内部信息
```protobuf
rpc GetProfileInternalInfo(GetProfileInternalInfoRequest) returns (ProfileInternalInfo);
```
- **功能**: 获取包含私钥的完整角色信息
- **权限**: 仅供内部微服务调用
- **安全**: 包含敏感信息，需要严格权限控制
#### 12. SignData - 使用私钥签名数据
```protobuf
rpc SignData(SignDataRequest) returns (SignDataResponse);
```
- **功能**: 使用角色私钥对数据进行签名
- **算法**: RSA-2048 + SHA-256
- **返回**: Base64编码的签名结果
## 🚀 部署指南
### 环境要求
- Go 1.19+
- MySQL 8.0+
- Redis 6.0+
### 配置文件示例
```yaml
# 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
```
### 部署步骤
1. **数据库初始化**
```bash
mysql -u root -p carrot_skin < docs/profiles.sql
```
2. **编译服务**
```bash
go build -o profile-service .
```
3. **启动服务**
```bash
./profile-service -f etc/profile.yaml
```
## 🛠️ 开发指南
### 代码生成
使用提供的脚本重新生成代码：
```bash
# 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` 中扩展：
```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密钥操作耗时

319
skinserviceREADME .md
View File

@@ -1,319 +0,0 @@
# 皮肤服务 (SkinService)
此项目是一个使用 **Go-zero** 框架构建的、专注于材质管理的纯 RPC 微服务。它为CarrotSkin皮肤站提供了完整的材质上传、存储、查询和管理功能，并集成了基于 MinIO 的高效文件存储系统。
## 核心功能
- **安全材质上传**: 利用 MinIO 预签名 POST URL，实现客户端直传，支持PNG格式限制和文件大小控制（1KB-1MB）
- **智能去重机制**: 基于 SHA-256 哈希值自动检测并复用相同材质，节省存储空间
- **完整材质管理**: 提供材质的增、删、改、查（CRUD）等全套操作
- **分类存储**: 支持皮肤（SKIN）和披风（CAPE）两种材质类型的分类管理
- **个人皮肤库**: 用户可查看和管理自己上传的所有材质
- **皮肤广场**: 公开材质展示平台，支持按类型浏览和搜索
- **收藏夹功能**: 支持用户收藏和管理自己的收藏列表
- **高性能查询**: 支持分页查询、批量获取和条件搜索
- **权限控制**: 严格的材质所有权验证，确保用户只能操作自己的材质
## 技术特性
- **微服务架构**: 基于 gRPC 的高性能服务间通信
- **对象存储**: MinIO 分布式存储，支持海量文件管理
- **数据库缓存**: go-zero 内置缓存机制，提升查询性能
- **类型安全**: 完整的 protobuf 定义和数据验证
- **容错设计**: 优雅的错误处理和日志记录
- **代码生成**: 使用 `goctl` 从 `.proto` 和 `.sql` 文件自动生成代码
## API 接口参考
服务通过 gRPC 暴露，接口定义于 `docs/textures.proto`。
### 材质上传流程
| 方法名 | 功能描述 | 请求类型 | 响应类型 |
|--------|----------|----------|----------|
| `GenerateTextureUploadURL` | 生成材质上传预签名URL | `GenerateTextureUploadURLRequest` | `GenerateTextureUploadURLResponse` |
| `CreateTexture` | 创建材质记录（上传完成后调用） | `CreateTextureRequest` | `CreateTextureResponse` |
**上传流程说明**：
1. 客户端调用 `GenerateTextureUploadURL` 获取预签名上传URL和表单数据
2. 客户端使用返回的 `post_url` 和 `form_data` 直接向MinIO上传文件
3. 上传成功后，客户端调用 `CreateTexture` 将材质信息记录到数据库
### 材质管理接口
| 方法名 | 功能描述 | 请求类型 | 响应类型 |
|--------|----------|----------|----------|
| `GetTexture` | 获取单个材质信息 | `GetTextureRequest` | `GetTextureResponse` |
| `UpdateTexture` | 更新材质信息（公开/私有状态） | `UpdateTextureRequest` | `UpdateTextureResponse` |
| `DeleteTexture` | 删除材质（含MinIO文件清理） | `DeleteTextureRequest` | `DeleteTextureResponse` |
### 查询接口
| 方法名 | 功能描述 | 请求类型 | 响应类型 |
|--------|----------|----------|----------|
| `GetUserTextures` | 获取用户个人材质库 | `GetUserTexturesRequest` | `GetUserTexturesResponse` |
| `GetPublicTextures` | 获取皮肤广场公开材质 | `GetPublicTexturesRequest` | `GetPublicTexturesResponse` |
| `SearchTextures` | 搜索材质 | `SearchTexturesRequest` | `SearchTexturesResponse` |
### 高级功能接口
| 方法名 | 功能描述 | 请求类型 | 响应类型 |
|--------|----------|----------|----------|
| `GetTextureByHash` | 根据哈希值查找材质（防重复上传） | `GetTextureByHashRequest` | `GetTextureByHashResponse` |
| `GetTexturesByIds` | 批量获取材质信息 | `GetTexturesByIdsRequest` | `GetTexturesByIdsResponse` |
### 收藏夹功能接口
| 方法名 | 功能描述 | 请求类型 | 响应类型 |
|---|---|---|---|
| `AddFavorite` | 添加材质到收藏夹 | `AddFavoriteRequest` | `AddFavoriteResponse` |
| `RemoveFavorite` | 从收藏夹移除材质 | `RemoveFavoriteRequest` | `RemoveFavoriteResponse` |
| `GetUserFavorites` | 获取用户收藏列表 | `GetUserFavoritesRequest` | `GetUserFavoritesResponse` |
| `CheckFavoriteStatus` | 检查材质收藏状态 | `CheckFavoriteStatusRequest` | `CheckFavoriteStatusResponse` |
## 数据模型
### 材质信息 (TextureInfo)
```protobuf
message TextureInfo {
int64 id = 1; // 材质ID
int64 uploader_id = 2; // 上传者用户ID
TextureType type = 3; // 材质类型（SKIN/CAPE）
string url = 4; // MinIO中的永久访问URL
string hash = 5; // SHA-256哈希值
bool is_public = 6; // 是否公开到皮肤广场
string created_at = 7; // 创建时间
string updated_at = 8; // 更新时间
}
```
### 材质类型枚举
```protobuf
enum TextureType {
SKIN = 0; // 皮肤
CAPE = 1; // 披风
}
```
### 收藏夹相关数据模型
#### 收藏材质信息 (FavoriteTextureInfo)
```protobuf
message FavoriteTextureInfo {
TextureInfo texture = 1; // 材质信息
string favorite_at = 2; // 收藏时间
}
```
## 存储结构
### MinIO 对象存储结构
```
textures/ # 存储桶根目录
├── skins/ # 皮肤材质目录
│ └── user_{userId}/ # 按用户分组
│ └── {timestamp}_{filename}.png
└── capes/ # 披风材质目录
└── user_{userId}/ # 按用户分组
└── {timestamp}_{filename}.png
```
### 数据库表结构
```sql
CREATE TABLE textures (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
uploader_id BIGINT NOT NULL,
type VARCHAR(10) NOT NULL, -- 'SKIN' 或 'CAPE'
url VARCHAR(500) NOT NULL, -- MinIO访问URL
hash VARCHAR(64) NOT NULL UNIQUE, -- SHA-256哈希值
is_public BOOLEAN DEFAULT FALSE, -- 是否公开
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_uploader_type (uploader_id, type),
INDEX idx_hash (hash),
INDEX idx_public_type (is_public, type, created_at)
);
```
### `user_texture_favorites` 表
```sql
-- 用户材质收藏表
CREATE TABLE `user_texture_favorites` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '收藏记录的唯一ID',
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户ID (对应UserService中的users.id)',
`texture_id` BIGINT UNSIGNED NOT NULL COMMENT '收藏的材质ID (对应textures.id)',
`created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '收藏时间',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_user_texture` (`user_id`, `texture_id`),
INDEX `idx_user_id` (`user_id`),
INDEX `idx_texture_id` (`texture_id`),
INDEX `idx_created_at` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户材质收藏表';
```
## 配置说明
### 服务配置 (etc/textures.yaml)
```yaml
Name: textures.rpc
ListenOn: 0.0.0.0:8080
# 数据库配置
DataSource: root:password@tcp(localhost:3306)/carrot_skin?charset=utf8mb4&parseTime=true&loc=Local
# 缓存配置
CacheRedis:
- Host: localhost:6379
Pass: ""
Type: node
# MinIO配置
MinIO:
Endpoint: "localhost:9000"
AccessKeyID: "minioadmin"
SecretAccessKey: "minioadmin"
UseSSL: false
Buckets:
Textures: "carrot-skin-textures"
```
## 安全特性
### 文件上传安全
- **格式限制**: 仅允许PNG格式文件
- **大小限制**: 文件大小限制在1KB-1MB之间
- **时效控制**: 预签名URL 15分钟过期
- **内容验证**: MinIO层面的Content-Type验证
### 权限控制
- **所有权验证**: 用户只能删除/更新自己上传的材质
- **参数校验**: 所有接口都有完整的输入验证
- **错误处理**: 不暴露敏感的系统信息
### 数据完整性
- **哈希去重**: SHA-256确保文件唯一性
- **事务处理**: 数据库操作的原子性保证
- **文件同步**: 删除材质时同步清理MinIO文件
## 性能优化
### 查询优化
- **分页查询**: 支持高效的大数据量分页
- **索引优化**: 针对常用查询场景建立复合索引
- **缓存机制**: go-zero内置的Redis缓存层
### 存储优化
- **智能去重**: 相同文件自动复用，节省存储空间
- **分类存储**: 按材质类型和用户分目录存储
## 部署说明
### 环境要求
- Go 1.19+
- MySQL 8.0+
- Redis 6.0+
- MinIO Server
### 启动服务
```bash
# 1. 安装依赖
go mod tidy
# 2. 生成代码（如果修改了proto或sql文件）
goctl rpc protoc docs/textures.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.
goctl model mysql ddl --src="docs/textures.sql" --dir="./internal/model"
# 3. 启动服务
go run textures.go -f etc/textures.yaml
```
### Docker 部署
```dockerfile
FROM golang:1.19-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod tidy && go build -o textures textures.go
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/textures .
COPY --from=builder /app/etc ./etc
CMD ["./textures", "-f", "etc/textures.yaml"]
```
## 监控与日志
### 日志记录
- **操作日志**: 记录所有材质操作的详细信息
- **错误日志**: 详细的错误堆栈和上下文信息
- **性能日志**: 查询耗时和系统性能指标
### 监控指标
- **接口调用量**: 各接口的QPS统计
- **存储使用量**: MinIO存储空间使用情况
- **缓存命中率**: Redis缓存效果监控
- **错误率统计**: 接口错误率和错误类型分析
## 开发指南
### 添加新接口
1. 在 `docs/textures.proto` 中定义新的RPC方法
2. 运行 `goctl rpc protoc` 生成代码
3. 在 `internal/logic/` 中实现业务逻辑
4. 添加相应的数据库查询方法（如需要）
### 自定义数据库查询
在 `internal/model/texturesModel.go` 中添加自定义查询方法：
```go
// 在 TexturesModel 接口中添加方法声明
type TexturesModel interface {
texturesModel
// 自定义方法
FindByCustomCondition(ctx context.Context, condition string) ([]*Textures, error)
}
// 在 customTexturesModel 中实现方法
func (m *customTexturesModel) FindByCustomCondition(ctx context.Context, condition string) ([]*Textures, error) {
query := `SELECT * FROM textures WHERE custom_field = ?`
var resp []*Textures
err := m.QueryRowsNoCacheCtx(ctx, &resp, query, condition)
return resp, err
}
```
## 故障排查
### 常见问题
1. **上传失败**: 检查MinIO连接和存储桶配置
2. **查询缓慢**: 检查数据库索引和Redis缓存
3. **文件不一致**: 检查MinIO文件清理逻辑
4. **权限错误**: 检查用户ID和材质所有权
### 调试技巧
- 启用详细日志: 设置日志级别为 `debug`
- 检查MinIO状态: 使用MinIO控制台查看文件状态
- 监控数据库: 使用慢查询日志分析性能问题