CarrotSkin/backend

Fork 0

Files

lan a4b6c5011e

SonarQube Analysis / sonarqube (push) Has been cancelled

Details

chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00

13 KiB

Raw Blame History

对象存储配置

**本文引用的文件列表** - [pkg/config/config.go](file://pkg/config/config.go) - [pkg/config/manager.go](file://pkg/config/manager.go) - [pkg/storage/manager.go](file://pkg/storage/manager.go) - [pkg/storage/minio.go](file://pkg/storage/minio.go) - [internal/service/upload_service.go](file://internal/service/upload_service.go) - [cmd/server/main.go](file://cmd/server/main.go) - [start.sh](file://start.sh)

简介

本文件面向开发者，系统性说明 CarrotSkin 项目与 RustFS（S3 兼容）对象存储的集成配置。重点涵盖以下方面：

核心配置项 rustfs.endpoint、access_key、secret_key、use_ssl 的作用与含义
存储桶配置 buckets 的动态加载机制，以及通过 RUSTFS_BUCKET_TEXTURES 和 RUSTFS_BUCKET_AVATARS 环境变量为不同用途（材质与头像）设置存储桶
基于 RustFSConfig 结构体的安全配置最佳实践，包括凭证管理与 SSL 配置建议

项目结构

CarrotSkin 的对象存储配置由“配置层 → 存储层 → 业务层”三层协作完成：

配置层：负责从环境变量加载并合并 RustFSConfig，支持运行时覆盖
存储层：封装 S3 兼容客户端（minio-go），提供桶名映射与预签名上传能力
业务层：根据文件类型生成上传 URL，按需选择对应存储桶

graph TB
subgraph "配置层"
CFG["RustFSConfig<br/>endpoint/access_key/secret_key/use_ssl/buckets"]
CMGR["配置管理器<br/>Init/GetRustFSConfig"]
end
subgraph "存储层"
SMGR["存储管理器<br/>Init/GetClient"]
SCLI["StorageClient<br/>minio.Client + buckets 映射"]
end
subgraph "业务层"
SVC["上传服务<br/>生成头像/材质上传URL"]
end
CMGR --> CFG
SMGR --> SCLI
SVC --> SCLI
CFG --> SMGR
SCLI --> SVC

图表来源

章节来源

核心组件

RustFSConfig：定义对象存储的端点、凭证、协议开关与桶映射
配置管理器：提供全局单例的配置加载与获取能力
存储管理器：提供全局单例的存储客户端初始化与获取能力
StorageClient：封装 minio-go 客户端，提供桶名映射与预签名上传能力
上传服务：按文件类型生成预签名上传 URL，并选择对应存储桶

章节来源

架构总览

下图展示从应用启动到生成上传 URL 的关键流程，以及各组件之间的依赖关系。

sequenceDiagram
participant Main as "主程序"
participant CfgMgr as "配置管理器"
participant Cfg as "RustFSConfig"
participant StorMgr as "存储管理器"
participant StorCli as "StorageClient"
participant Svc as "上传服务"
Main->>CfgMgr : 调用 Init()
CfgMgr->>CfgMgr : 加载环境变量并合并默认值
CfgMgr-->>Main : 返回全局 RustFSConfig
Main->>StorMgr : 调用 Init(RustFSConfig)
StorMgr->>StorCli : NewStorage(cfg)
StorCli-->>StorMgr : 返回 StorageClient
StorMgr-->>Main : 初始化完成
Svc->>StorCli : GetBucket("avatars"/"textures")
Svc->>StorCli : GeneratePresignedPostURL(...)
StorCli-->>Svc : 返回 PostURL + FormData + FileURL

图表来源

详细组件分析

RustFSConfig 结构体与配置项说明

endpoint：RustFS 服务地址（含端口）。用于构建预签名上传 URL 的最终访问地址与协议选择
access_key / secret_key：访问凭证，用于构造静态凭据并建立 S3 兼容客户端
use_ssl：是否启用 HTTPS 协议；影响预签名上传 URL 的协议与文件访问 URL 的协议
buckets：存储桶映射，键为用途标识（如 "textures"、"avatars"），值为实际桶名

章节来源

pkg/config/config.go

配置加载与动态覆盖

默认值：通过 viper 设置默认值，包含 endpoint 与 use_ssl 的默认值
环境变量映射：将 CARROTSKIN 前缀的环境变量绑定到配置键
动态覆盖：overrideFromEnv 支持通过 RUSTFS_BUCKET_TEXTURES 与 RUSTFS_BUCKET_AVATARS 动态注入存储桶映射，无需修改配置文件

章节来源

存储客户端初始化与连接测试

客户端创建：基于 endpoint、access_key、secret_key、use_ssl 构造 minio-go 客户端
连接测试：当凭证非空时，尝试列举桶以验证连通性
桶映射：将 RustFSConfig 中的 buckets 直接注入 StorageClient

章节来源

pkg/storage/minio.go

存储桶映射与上传 URL 生成

GetBucket：按用途键（"textures" 或 "avatars"）从映射中取桶名
预签名上传：根据文件类型与大小范围生成 POST 策略，返回 PostURL、FormData 与最终 FileURL
协议选择：根据 use_ssl 决定协议（http/https）

章节来源

业务层调用链（头像上传）

sequenceDiagram
participant Svc as "上传服务"
participant StorCli as "StorageClient"
participant Cfg as "RustFSConfig"
Svc->>Svc : 校验文件名与扩展名
Svc->>StorCli : GetBucket("avatars")
StorCli-->>Svc : 返回桶名
Svc->>StorCli : GeneratePresignedPostURL(bucket, objectName, min/max/expire, useSSL, endpoint)
StorCli-->>Svc : 返回 PostURL + FormData + FileURL
Svc-->>Svc : 组装响应并返回

图表来源

业务层调用链（材质上传）

sequenceDiagram
participant Svc as "上传服务"
participant StorCli as "StorageClient"
participant Cfg as "RustFSConfig"
Svc->>Svc : 校验文件名与扩展名
Svc->>Svc : 校验材质类型(SKIN/CAPE)
Svc->>StorCli : GetBucket("textures")
StorCli-->>Svc : 返回桶名
Svc->>StorCli : GeneratePresignedPostURL(...)
StorCli-->>Svc : 返回 PostURL + FormData + FileURL
Svc-->>Svc : 组装响应并返回

图表来源

存储桶动态加载机制

环境变量注入：RUSTFS_BUCKET_TEXTURES 与 RUSTFS_BUCKET_AVATARS 分别为“材质”和“头像”用途注入桶名
映射合并：overrideFromEnv 在 RustFS.Buckets 为空时创建映射，再写入对应键值
无配置文件依赖：完全通过环境变量驱动，便于容器化部署与多环境切换

flowchart TD
Start(["启动"]) --> LoadEnv["加载环境变量"]
LoadEnv --> Override["overrideFromEnv 动态覆盖"]
Override --> CheckTextures{"RUSTFS_BUCKET_TEXTURES 是否存在"}
CheckTextures --> |是| PutTextures["写入 buckets['textures']"]
CheckTextures --> |否| Next1["跳过"]
PutTextures --> Next2["继续检查"]
Next1 --> Next2
Next2 --> CheckAvatars{"RUSTFS_BUCKET_AVATARS 是否存在"}
CheckAvatars --> |是| PutAvatars["写入 buckets['avatars']"]
CheckAvatars --> |否| End(["结束"])
PutAvatars --> End

图表来源

pkg/config/config.go

章节来源

pkg/config/config.go

依赖关系分析

配置层依赖 viper 与 godotenv，负责环境变量加载与默认值设置
存储层依赖 minio-go，封装客户端与桶映射
业务层依赖存储层提供的预签名上传能力
启动流程在 main 中依次初始化配置、日志、数据库、JWT、Redis、对象存储与邮件服务

graph LR
Viper["viper/godotenv"] --> Config["RustFSConfig"]
Config --> Manager["配置管理器"]
Manager --> StorageMgr["存储管理器"]
StorageMgr --> StorageClient["StorageClient(minio-go)"]
StorageClient --> UploadSvc["上传服务"]
Main["main"] --> Manager
Main --> StorageMgr

图表来源

章节来源

性能考量

预签名上传避免了服务端中转，降低带宽与延迟
上传 URL 过期时间短（默认 15 分钟），减少凭证暴露风险
桶映射为内存查找，开销极低
连接测试仅在凭证非空时进行，避免不必要的网络往返

[本节为通用指导，不涉及具体文件分析]

故障排查指南

配置未初始化
- 现象：调用 GetRustFSConfig/MustGetRustFSConfig 或 GetClient/MustGetClient 报错
- 排查：确认已在 main 中调用 config.Init() 与 storage.Init()
凭证为空导致连接测试跳过
- 现象：NewStorage 成功但未进行 ListBuckets 测试
- 排查：若需验证连通性，请提供 access_key 与 secret_key
存储桶不存在
- 现象：GetBucket 返回错误
- 排查：确认 RUSTFS_BUCKET_TEXTURES/RUSTFS_BUCKET_AVATARS 已正确设置，且与 RustFS 实际桶名一致
预签名上传失败
- 现象：GeneratePresignedPostURL 返回错误
- 排查：检查 min/max 大小范围、过期时间、use_ssl 与 endpoint 是否匹配

章节来源

结论

CarrotSkin 通过 RustFSConfig 将对象存储配置集中管理，并以环境变量驱动，实现灵活部署
通过 RUSTFS_BUCKET_TEXTURES 与 RUSTFS_BUCKET_AVATARS 实现“材质/头像”两类资源的桶级隔离
基于 minio-go 的预签名上传机制，既保证安全性又提升性能
建议遵循安全最佳实践（最小权限、短期凭证、HTTPS）以保障生产安全

[本节为总结性内容，不涉及具体文件分析]

附录

环境变量与默认值对照

RUSTFS_ENDPOINT：RustFS 服务地址，默认值由 viper 设置
RUSTFS_ACCESS_KEY：访问密钥
RUSTFS_SECRET_KEY：私有密钥
RUSTFS_USE_SSL：是否启用 HTTPS
RUSTFS_BUCKET_TEXTURES：材质用途桶名
RUSTFS_BUCKET_AVATARS：头像用途桶名

章节来源

启动脚本示例

start.sh 展示了如何设置对象存储相关环境变量，便于本地开发与测试

章节来源

start.sh

13 KiB Raw Blame History Unescape Escape

对象存储配置

目录

简介

项目结构

核心组件

架构总览

详细组件分析

RustFSConfig 结构体与配置项说明

配置加载与动态覆盖

存储客户端初始化与连接测试

存储桶映射与上传 URL 生成

业务层调用链（头像上传）

业务层调用链（材质上传）

存储桶动态加载机制

依赖关系分析

性能考量

故障排查指南

结论

附录

环境变量与默认值对照

启动脚本示例

13 KiB

Raw Blame History