325 lines
13 KiB
Markdown
325 lines
13 KiB
Markdown
# 快速开始
|
||
|
||
<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) |