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

2025-11-30 08:33:17 +08:00
parent 4b4980820f
commit a4b6c5011e
58 changed files with 19353 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/快速开始.md
+++ b/.qoder/repowiki/zh/content/快速开始.md
@@ -0,0 +1,325 @@
+# 快速开始
+
+<cite>
+**本文引用的文件**
+- [go.mod](file://go.mod)
+- [cmd/server/main.go](file://cmd/server/main.go)
+- [pkg/config/config.go](file://pkg/config/config.go)
+- [pkg/config/manager.go](file://pkg/config/manager.go)
+- [pkg/database/manager.go](file://pkg/database/manager.go)
+- [pkg/storage/manager.go](file://pkg/storage/manager.go)
+- [internal/handler/swagger.go](file://internal/handler/swagger.go)
+- [scripts/dev.sh](file://scripts/dev.sh)
+- [run.sh](file://run.sh)
+- [run.bat](file://run.bat)
+- [scripts/check-env.sh](file://scripts/check-env.sh)
+- [configs/casbin/rbac_model.conf](file://configs/casbin/rbac_model.conf)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与运行建议](#性能与运行建议)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向首次接触 CarrotSkin 后端项目的开发者，帮助你从零开始完成开发环境准备、配置与依赖安装，并通过提供的脚本快速启动服务。你将学会：
+- 准备 Go、数据库与对象存储等运行所需环境
+- 复制并配置环境变量与配置文件
+- 安装 Swagger 工具并生成 API 文档
+- 使用 dev.sh、run.sh 和 run.bat 脚本启动项目
+- 面向初学者的路径指引与面向资深用户的常见问题排查
+
+## 项目结构
+CarrotSkin 后端采用模块化分层设计，主要目录与职责如下：
+- cmd/server：应用入口，负责初始化配置、数据库、中间件、路由与 HTTP 服务
+- pkg/*：通用能力封装，如配置、数据库、Redis、存储、日志、邮件等
+- internal/*：业务层实现，包括处理器、中间件、模型、仓库、服务与类型定义
+- scripts：开发与环境检查脚本
+- configs：静态配置与权限模型文件
+
+```mermaid
+graph TB
+A["cmd/server/main.go<br/>应用入口"] --> B["pkg/config/*<br/>配置加载与管理"]
+A --> C["pkg/database/*<br/>数据库初始化与迁移"]
+A --> D["pkg/redis/*<br/>Redis连接"]
+A --> E["pkg/storage/*<br/>对象存储(RustFS)"]
+A --> F["pkg/email/*<br/>邮件服务"]
+A --> G["internal/handler/*<br/>路由与Swagger"]
+A --> H["internal/middleware/*<br/>中间件"]
+A --> I["internal/service/*<br/>业务服务"]
+A --> J["internal/repository/*<br/>数据访问层"]
+A --> K["internal/model/*<br/>数据模型"]
+L["scripts/*<br/>启动与检查脚本"] --> A
+M["configs/casbin/*<br/>权限模型"] --> I
+```
+
+图表来源
+- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+- [pkg/database/manager.go](file://pkg/database/manager.go#L1-L114)
+- [pkg/storage/manager.go](file://pkg/storage/manager.go#L1-L49)
+- [internal/handler/swagger.go](file://internal/handler/swagger.go#L1-L63)
+- [scripts/dev.sh](file://scripts/dev.sh#L1-L29)
+- [configs/casbin/rbac_model.conf](file://configs/casbin/rbac_model.conf#L1-L15)
+
+章节来源
+- [go.mod](file://go.mod#L1-L92)
+- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)
+
+## 核心组件
+- 配置系统：支持从 .env 与环境变量加载，提供默认值与覆盖逻辑，便于本地与生产环境切换
+- 数据库：基于 GORM 的 PostgreSQL 连接与自动迁移
+- 对象存储：RustFS（S3 兼容），用于材质与头像等资源存储
+- 中间件：日志、恢复、CORS
+- Swagger：自动生成 API 文档并通过路由暴露
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L1-L68)
+- [pkg/database/manager.go](file://pkg/database/manager.go#L1-L114)
+- [pkg/storage/manager.go](file://pkg/storage/manager.go#L1-L49)
+- [internal/handler/swagger.go](file://internal/handler/swagger.go#L1-L63)
+
+## 架构总览
+下图展示了应用启动时的关键流程：加载配置 → 初始化日志 → 初始化数据库并迁移 → 初始化 JWT/Redis/存储/邮件 → 注册路由 → 启动 HTTP 服务。
+
+```mermaid
+sequenceDiagram
+participant CLI as "命令行"
+participant Main as "main.go"
+participant Cfg as "配置模块"
+participant Log as "日志模块"
+participant DB as "数据库模块"
+participant JWT as "JWT服务"
+participant Rds as "Redis"
+participant Store as "对象存储"
+participant Mail as "邮件服务"
+participant Router as "路由与中间件"
+participant HTTP as "HTTP服务器"
+CLI->>Main : "go run cmd/server/main.go"
+Main->>Cfg : "Init()"
+Cfg-->>Main : "配置加载完成"
+Main->>Log : "Init(日志配置)"
+Main->>DB : "Init(数据库配置)"
+DB-->>Main : "连接成功"
+Main->>DB : "AutoMigrate()"
+DB-->>Main : "迁移完成"
+Main->>JWT : "Init(JWT配置)"
+Main->>Rds : "Init(Redis配置)"
+Main->>Store : "Init(RustFS配置)"
+Store-->>Main : "连接成功/告警"
+Main->>Mail : "Init(邮件配置)"
+Main->>Router : "注册中间件与路由"
+Main->>HTTP : "ListenAndServe()"
+HTTP-->>CLI : "服务就绪"
+```
+
+图表来源
+- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L1-L68)
+- [pkg/database/manager.go](file://pkg/database/manager.go#L1-L114)
+- [pkg/storage/manager.go](file://pkg/storage/manager.go#L1-L49)
+- [internal/handler/swagger.go](file://internal/handler/swagger.go#L1-L63)
+
+## 详细组件分析
+
+### 配置系统与环境变量
+- 配置来源优先级：.env 文件 → 环境变量 → 默认值
+- 支持的环境变量前缀：CARROTSKIN（例如 CARROTSKIN_DATABASE_HOST）
+- 关键配置项（部分）：服务器端口、模式、读写超时；数据库主机、端口、用户名、密码、库名、SSL、时区、连接池；Redis 主机、端口、密码、库号、池大小；RustFS Endpoint、AccessKey、SecretKey、UseSSL、存储桶映射；JWT Secret、过期小时；日志级别、格式、输出、轮转参数；上传最大尺寸、类型限制；邮件 SMTP Host/Port/用户名/密码/发送者名称
+- 特殊覆盖逻辑：可通过独立环境变量覆盖连接池、Redis 池大小、上传限制、邮件开关等
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L1-L68)
+
+### 数据库初始化与迁移
+- 初始化：根据配置建立 PostgreSQL 连接
+- 迁移：按顺序创建用户、档案、材质、认证、Yggdrasil、系统配置、审计日志、权限规则等表
+- 关闭：优雅关闭 SQL 连接
+
+章节来源
+- [pkg/database/manager.go](file://pkg/database/manager.go#L1-L114)
+
+### 对象存储（RustFS/S3 兼容）
+- 初始化：根据配置连接到 S3 兼容存储
+- 行为：连接失败仅记录警告，不影响服务启动（部分功能受限）
+
+章节来源
+- [pkg/storage/manager.go](file://pkg/storage/manager.go#L1-L49)
+
+### Swagger 文档
+- 路由：/swagger/*any
+- 健康检查：/health
+- 文档生成：通过 swag 工具扫描注释生成
+
+章节来源
+- [internal/handler/swagger.go](file://internal/handler/swagger.go#L1-L63)
+
+### 权限模型（Casbin）
+- RBAC 模型文件位于 configs/casbin/rbac_model.conf
+
+章节来源
+- [configs/casbin/rbac_model.conf](file://configs/casbin/rbac_model.conf#L1-L15)
+
+## 依赖关系分析
+- 应用入口依赖配置、数据库、Redis、存储、邮件、日志与路由模块
+- 配置模块依赖 Viper 与 godotenv
+- 数据库模块依赖 GORM 与 PostgreSQL 驱动
+- 存储模块依赖 MinIO SDK
+- Swagger 依赖 Gin-Swagger 与 Swag 工具
+- Redis 依赖官方 Redis 客户端
+
+```mermaid
+graph LR
+Main["cmd/server/main.go"] --> Cfg["pkg/config/*"]
+Main --> DB["pkg/database/*"]
+Main --> Rds["pkg/redis/*"]
+Main --> Stor["pkg/storage/*"]
+Main --> Mail["pkg/email/*"]
+Main --> Log["pkg/logger/*"]
+Main --> Hdl["internal/handler/*"]
+Cfg --> Viper["spf13/viper"]
+Cfg --> DotEnv["joho/godotenv"]
+DB --> GORM["gorm.io/gorm"]
+DB --> PGX["jackc/pgx"]
+Stor --> MinIO["minio/minio-go"]
+Hdl --> Gin["gin-gonic/gin"]
+Hdl --> Swagger["swaggo/gin-swagger"]
+```
+
+图表来源
+- [go.mod](file://go.mod#L1-L92)
+- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)
+
+章节来源
+- [go.mod](file://go.mod#L1-L92)
+
+## 性能与运行建议
+- 数据库连接池：通过环境变量覆盖最大空闲/活动连接数与连接生命周期，以适配不同负载
+- Redis 池大小：根据并发与延迟需求调整
+- 日志轮转：合理设置日志文件大小、保留份数与保留天数，避免磁盘压力
+- Swagger 生成：仅在开发阶段生成，生产环境可预生成并禁用动态生成
+
+[本节为通用建议，无需特定文件来源]
+
+## 故障排除指南
+
+### 环境变量检查
+- 使用脚本检查 .env 是否存在、必需变量是否完整、敏感默认值是否已被修改
+- 建议在本地复制 .env.example 为 .env 并按需填写
+
+章节来源
+- [scripts/check-env.sh](file://scripts/check-env.sh#L1-L78)
+
+### Swagger 文档生成失败
+- 确认已安装 swag 工具（go install github.com/swaggo/swag/cmd/swag@latest）
+- 使用 run.sh 或 run.bat 自动安装与生成
+- 若使用 dev.sh，确保 swag 可用且目标入口文件路径正确
+
+章节来源
+- [run.sh](file://run.sh#L1-L37)
+- [run.bat](file://run.bat#L1-L42)
+- [scripts/dev.sh](file://scripts/dev.sh#L1-L29)
+
+### 数据库连接失败
+- 检查 DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USERNAME、DATABASE_PASSWORD
+- 确认数据库服务可达、SSL 模式与时区设置符合实际
+- 查看日志模块输出定位错误
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+- [pkg/database/manager.go](file://pkg/database/manager.go#L1-L114)
+
+### 对象存储连接失败
+- 检查 RUSTFS_ENDPOINT、RUSTFS_ACCESS_KEY、RUSTFS_SECRET_KEY、RUSTFS_USE_SSL
+- 确认存储服务可用且网络连通
+- 若仅部分功能受限，可在日志中看到警告
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+- [pkg/storage/manager.go](file://pkg/storage/manager.go#L1-L49)
+
+### JWT 密钥安全
+- 确保 JWT_SECRET 长度足够且非默认值
+- 生产环境务必更换默认密钥
+
+章节来源
+- [scripts/check-env.sh](file://scripts/check-env.sh#L1-L78)
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+
+### 服务器启动与停止
+- 正常启动：使用 run.sh 或 run.bat，或直接 go run cmd/server/main.go
+- 停止服务：在终端按 Ctrl+C 触发优雅关闭
+
+章节来源
+- [run.sh](file://run.sh#L1-L37)
+- [run.bat](file://run.bat#L1-L42)
+- [cmd/server/main.go](file://cmd/server/main.go#L1-L124)
+
+## 结论
+通过本指南，你可以快速完成 CarrotSkin 后端的环境准备与项目启动。建议在本地先用 run.sh 或 run.bat 完成一键启动，随后使用 scripts/check-env.sh 校验环境变量，最后在开发过程中使用 dev.sh 进行迭代调试。遇到问题时，优先检查环境变量、数据库与对象存储连通性，并确认 swag 工具可用。
+
+[本节为总结，无需特定文件来源]
+
+## 附录
+
+### 开发环境先决条件
+- Go 版本：项目要求 Go 1.23；工具链为 1.24.2
+- 数据库：PostgreSQL（驱动与连接参数见配置）
+- 对象存储：S3 兼容服务（RustFS Endpoint、AccessKey、SecretKey）
+- 其他：Redis（可选）、邮件 SMTP（可选）
+
+章节来源
+- [go.mod](file://go.mod#L1-L92)
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+
+### 配置与环境变量清单
+- 服务器：SERVER_PORT、SERVER_MODE、SERVER_READ_TIMEOUT、SERVER_WRITE_TIMEOUT
+- 数据库：DATABASE_DRIVER、DATABASE_HOST、DATABASE_PORT、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_NAME、DATABASE_SSL_MODE、DATABASE_TIMEZONE、DATABASE_MAX_IDLE_CONNS、DATABASE_MAX_OPEN_CONNS、DATABASE_CONN_MAX_LIFETIME
+- Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE、REDIS_POOL_SIZE
+- 对象存储：RUSTFS_ENDPOINT、RUSTFS_ACCESS_KEY、RUSTFS_SECRET_KEY、RUSTFS_USE_SSL、RUSTFS_BUCKET_TEXTURES、RUSTFS_BUCKET_AVATARS
+- JWT：JWT_SECRET、JWT_EXPIRE_HOURS
+- 日志：LOG_LEVEL、LOG_FORMAT、LOG_OUTPUT、LOG_MAX_SIZE、LOG_MAX_BACKUPS、LOG_MAX_AGE、LOG_COMPRESS
+- 上传：UPLOAD_MAX_SIZE、UPLOAD_TEXTURE_MAX_SIZE、UPLOAD_AVATAR_MAX_SIZE、UPLOAD_ALLOWED_TYPES
+- 邮件：EMAIL_ENABLED、EMAIL_SMTP_HOST、EMAIL_SMTP_PORT、EMAIL_USERNAME、EMAIL_PASSWORD、EMAIL_FROM_NAME
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L1-L305)
+
+### 启动脚本与命令说明
+- dev.sh（开发环境）
+  - 自动复制配置示例为正式配置
+  - 执行 go mod tidy
+  - 检测并生成 Swagger 文档
+  - 启动应用
+- run.sh（一次性安装并启动）
+  - 自动安装 swag
+  - 生成 Swagger 文档
+  - 启动应用并打印访问地址
+- run.bat（Windows）
+  - 自动安装 swag
+  - 生成 Swagger 文档
+  - 启动应用并打印访问地址
+
+章节来源
+- [scripts/dev.sh](file://scripts/dev.sh#L1-L29)
+- [run.sh](file://run.sh#L1-L37)
+- [run.bat](file://run.bat#L1-L42)
+
+### Swagger 文档访问
+- 服务地址：http://localhost:8080
+- Swagger 文档：http://localhost:8080/swagger/index.html
+- 健康检查：http://localhost:8080/health
+
+章节来源
+- [internal/handler/swagger.go](file://internal/handler/swagger.go#L1-L63)
+- [run.sh](file://run.sh#L1-L37)
+- [run.bat](file://run.bat#L1-L42)