11 KiB
部署
**本文档引用的文件** - [start.sh](file://start.sh) - [run.sh](file://run.sh) - [scripts/check-env.sh](file://scripts/check-env.sh) - [scripts/dev.sh](file://scripts/dev.sh) - [pkg/config/config.go](file://pkg/config/config.go) - [pkg/logger/logger.go](file://pkg/logger/logger.go) - [internal/handler/swagger.go](file://internal/handler/swagger.go) - [internal/handler/routes.go](file://internal/handler/routes.go)目录
简介
CarrotSkin 是一个为 Minecraft 皮肤站设计的后端服务，提供用户管理、材质上传下载、档案管理等功能。本部署文档详细介绍了如何在生产环境中部署和运行 CarrotSkin 服务，包括使用 start.sh 和 run.sh 脚本的完整流程、环境变量配置、依赖项管理以及运维监控等方面的内容。文档既为初学者提供了简单的部署步骤，也为经验丰富的开发者提供了高可用性和可扩展性部署的高级策略。
项目结构
CarrotSkin 项目采用标准的 Go 项目结构，主要包含以下目录：
configs/：配置文件目录，包含 Casbin 权限模型等配置internal/：核心业务逻辑，包括处理器、中间件、模型、仓库和服务pkg/：可重用的包，如数据库、Redis、日志、配置管理等scripts/：脚本目录，包含环境检查和开发环境启动脚本- 根目录：包含主启动脚本
start.sh、run.sh和 Go 模块文件
项目通过环境变量进行配置，不依赖传统的 YAML 配置文件，这使得部署更加灵活，特别适合容器化环境。
Section sources
环境准备
在部署 CarrotSkin 服务之前，需要确保以下依赖项已正确安装和配置：
- Go 语言环境：项目需要 Go 1.23.0 或更高版本。可以通过
go version命令检查当前 Go 版本。 - PostgreSQL 数据库：服务依赖 PostgreSQL 作为主数据库。需要确保数据库服务已启动，并创建了相应的数据库和用户。
- Redis 服务：用于缓存和会话管理。需要确保 Redis 服务正在运行。
- RustFS (S3 兼容对象存储)：用于存储用户上传的皮肤和头像文件。需要配置一个 S3 兼容的对象存储服务。
- swag 工具：用于生成 Swagger API 文档。如果未安装，
run.sh脚本会自动安装。
对于生产环境，建议使用 Docker 或 Kubernetes 来管理这些依赖服务，以确保环境的一致性和可移植性。
Section sources
部署流程
CarrotSkin 提供了多种部署方式，从简单的本地部署到复杂的生产环境部署。
基础部署步骤
- 克隆代码库：将 CarrotSkin 后端代码克隆到目标服务器。
- 安装依赖：运行
go mod tidy安装所有 Go 依赖包。 - 配置环境变量：根据
start.sh脚本中的示例，设置所有必需的环境变量。 - 生成 API 文档：运行
swag init生成 Swagger API 文档。 - 启动服务：执行
run.sh或start.sh脚本启动服务。
使用 run.sh 脚本
run.sh 脚本是推荐的开发和部署方式，它自动化了大部分部署步骤：
- 自动检查并安装
swag工具 - 生成最新的 Swagger API 文档
- 启动 Go 服务
./run.sh
使用 start.sh 脚本
start.sh 脚本直接设置了所有环境变量并启动服务，适合在环境变量管理不便的场景下使用。
./start.sh
Section sources
启动脚本详解
CarrotSkin 提供了多个启动脚本以适应不同的使用场景。
start.sh 脚本
start.sh 脚本是一个自包含的启动脚本，它在脚本内部定义了所有必需的环境变量，然后直接启动服务。这种方式简单直接，但不推荐用于生产环境，因为敏感信息（如数据库密码）直接暴露在脚本中。
Section sources
run.sh 脚本
run.sh 脚本是一个更智能的启动脚本，它分为三个阶段：
- 检查 swag 工具：确保
swag命令可用，如果不存在则自动安装。 - 生成 Swagger 文档：运行
swag init命令生成 API 文档，确保 API 文档与代码同步。 - 启动服务器：最后启动 Go 服务。
这个脚本的优势在于它确保了 API 文档的实时性，并且不包含敏感的环境变量。
Section sources
check-env.sh 脚本
scripts/check-env.sh 是一个环境检查脚本，用于验证必需的环境变量是否已正确设置。它会检查 .env 文件是否存在，并验证关键变量（如数据库连接、RustFS 凭证、JWT 密钥）是否已配置。此外，它还会检查 JWT 密钥的长度和是否使用了默认值，提供安全建议。
Section sources
生产环境配置
在生产环境中部署 CarrotSkin 时，必须进行严格的安全和性能配置。
环境变量配置
所有配置都通过环境变量进行。关键的环境变量包括：
- 数据库配置：
DATABASE_HOST,DATABASE_PORT,DATABASE_USERNAME,DATABASE_PASSWORD,DATABASE_NAME - Redis 配置：
REDIS_HOST,REDIS_PORT,REDIS_PASSWORD - 对象存储配置：
RUSTFS_ENDPOINT,RUSTFS_ACCESS_KEY,RUSTFS_SECRET_KEY - 安全配置：
JWT_SECRET（必须使用至少 32 位的强随机字符串）
配置管理
项目使用 Viper 库从环境变量中读取配置。pkg/config/config.go 文件定义了所有配置项的结构和默认值。生产环境中应避免使用脚本中硬编码的默认值，而是通过环境变量或配置管理工具（如 Kubernetes ConfigMap/Secret）来设置。
flowchart TD
A[环境变量] --> B[pkg/config/config.go]
B --> C[应用配置]
C --> D[数据库连接]
C --> E[Redis连接]
C --> F[RustFS连接]
C --> G[JWT配置]
Diagram sources
Section sources
健康检查与监控
CarrotSkin 内置了健康检查功能，便于集成到监控系统中。
健康检查端点
服务提供了一个 /health 的健康检查端点，返回简单的 JSON 响应：
{
"status": "ok",
"message": "CarrotSkin API is running"
}
该端点由 internal/handler/swagger.go 中的 HealthCheck 函数实现，无需认证即可访问，适合用于负载均衡器和容器编排平台的健康探测。
监控建议
建议将以下指标纳入监控系统：
- HTTP 请求延迟和错误率
- 数据库连接池使用情况
- Redis 内存使用和命中率
- 对象存储的读写性能
sequenceDiagram
participant 监控系统
participant CarrotSkin服务
participant 数据库
participant Redis
participant 对象存储
监控系统->>CarrotSkin服务 : GET /health
CarrotSkin服务->>数据库 : 检查连接
CarrotSkin服务->>Redis : 检查连接
CarrotSkin服务->>对象存储 : 检查连接
CarrotSkin服务-->>监控系统 : 返回健康状态
Diagram sources
Section sources
日志管理
CarrotSkin 使用 Zap 日志库进行日志记录，提供了结构化日志输出。
日志配置
日志行为由以下环境变量控制：
LOG_LEVEL：日志级别（debug, info, warn, error）LOG_FORMAT：日志格式（json 或 console）LOG_OUTPUT：日志输出位置（文件路径或 stdout）
日志轮转
日志文件支持自动轮转，配置包括最大文件大小、备份数量和最大保留天数。日志文件默认存储在 logs/app.log。
flowchart TD
A[应用事件] --> B[pkg/logger/logger.go]
B --> C{日志级别}
C --> |高于配置级别| D[忽略]
C --> |低于或等于| E[格式化]
E --> F{输出目标}
F --> |stdout| G[控制台输出]
F --> |文件| H[写入日志文件]
H --> I[日志轮转]
Diagram sources
Section sources
高级部署策略
对于生产环境，建议采用以下高级部署策略。
Docker 部署
虽然项目未提供 Dockerfile，但可以轻松创建。Docker 部署的优势包括环境隔离、版本控制和易于扩展。
FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod tidy
RUN go build -o carrotskin cmd/server/main.go
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/carrotskin .
COPY --from=builder /app/docs docs
EXPOSE 8080
CMD ["./carrotskin"]
CI/CD 集成
建议将部署流程集成到 CI/CD 管道中：
- 代码推送触发 CI 构建
- 运行单元测试和集成测试
- 构建 Docker 镜像
- 推送镜像到镜像仓库
- 在目标环境部署新版本
高可用性部署
对于高可用性要求，建议：
- 使用 Kubernetes 部署多个服务实例
- 配置负载均衡器分发流量
- 使用外部的 PostgreSQL 集群和 Redis 集群
- 实现蓝绿部署或金丝雀发布
故障排除
常见问题
- 服务无法启动：检查
check-env.sh脚本，确保所有必需的环境变量已设置。 - 数据库连接失败：验证数据库主机、端口、用户名和密码是否正确。
- JWT 密钥警告：生产环境中必须更改默认的 JWT 密钥。
- Swagger 文档缺失：确保已运行
swag init命令。
调试建议
- 查看日志文件
logs/app.log获取详细错误信息 - 使用
curl http://localhost:8080/health检查服务健康状态 - 检查依赖服务（数据库、Redis、对象存储）是否正常运行
Section sources