319 lines
10 KiB
Markdown
319 lines
10 KiB
Markdown
# 皮肤服务 (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控制台查看文件状态
|
||
- 监控数据库: 使用慢查询日志分析性能问题 |