# 部署

<cite>
**本文档引用的文件**   
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [环境准备](#环境准备)
4. [部署流程](#部署流程)
5. [启动脚本详解](#启动脚本详解)
6. [生产环境配置](#生产环境配置)
7. [健康检查与监控](#健康检查与监控)
8. [日志管理](#日志管理)
9. [高级部署策略](#高级部署策略)
10. [故障排除](#故障排除)

## 简介
CarrotSkin 是一个为 Minecraft 皮肤站设计的后端服务，提供用户管理、材质上传下载、档案管理等功能。本部署文档详细介绍了如何在生产环境中部署和运行 CarrotSkin 服务，包括使用 `start.sh` 和 `run.sh` 脚本的完整流程、环境变量配置、依赖项管理以及运维监控等方面的内容。文档既为初学者提供了简单的部署步骤，也为经验丰富的开发者提供了高可用性和可扩展性部署的高级策略。

## 项目结构
CarrotSkin 项目采用标准的 Go 项目结构，主要包含以下目录：

- `configs/`：配置文件目录，包含 Casbin 权限模型等配置
- `internal/`：核心业务逻辑，包括处理器、中间件、模型、仓库和服务
- `pkg/`：可重用的包，如数据库、Redis、日志、配置管理等
- `scripts/`：脚本目录，包含环境检查和开发环境启动脚本
- 根目录：包含主启动脚本 `start.sh`、`run.sh` 和 Go 模块文件

项目通过环境变量进行配置，不依赖传统的 YAML 配置文件，这使得部署更加灵活，特别适合容器化环境。

**Section sources**
- [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)

## 环境准备
在部署 CarrotSkin 服务之前，需要确保以下依赖项已正确安装和配置：

1. **Go 语言环境**：项目需要 Go 1.23.0 或更高版本。可以通过 `go version` 命令检查当前 Go 版本。
2. **PostgreSQL 数据库**：服务依赖 PostgreSQL 作为主数据库。需要确保数据库服务已启动，并创建了相应的数据库和用户。
3. **Redis 服务**：用于缓存和会话管理。需要确保 Redis 服务正在运行。
4. **RustFS (S3 兼容对象存储)**：用于存储用户上传的皮肤和头像文件。需要配置一个 S3 兼容的对象存储服务。
5. **swag 工具**：用于生成 Swagger API 文档。如果未安装，`run.sh` 脚本会自动安装。

对于生产环境，建议使用 Docker 或 Kubernetes 来管理这些依赖服务，以确保环境的一致性和可移植性。

**Section sources**
- [go.mod](file://go.mod)
- [pkg/config/config.go](file://pkg/config/config.go)
- [scripts/check-env.sh](file://scripts/check-env.sh)

## 部署流程
CarrotSkin 提供了多种部署方式，从简单的本地部署到复杂的生产环境部署。

### 基础部署步骤
1. **克隆代码库**：将 CarrotSkin 后端代码克隆到目标服务器。
2. **安装依赖**：运行 `go mod tidy` 安装所有 Go 依赖包。
3. **配置环境变量**：根据 `start.sh` 脚本中的示例，设置所有必需的环境变量。
4. **生成 API 文档**：运行 `swag init` 生成 Swagger API 文档。
5. **启动服务**：执行 `run.sh` 或 `start.sh` 脚本启动服务。

### 使用 run.sh 脚本
`run.sh` 脚本是推荐的开发和部署方式，它自动化了大部分部署步骤：
- 自动检查并安装 `swag` 工具
- 生成最新的 Swagger API 文档
- 启动 Go 服务

```bash
./run.sh
```

### 使用 start.sh 脚本
`start.sh` 脚本直接设置了所有环境变量并启动服务，适合在环境变量管理不便的场景下使用。

```bash
./start.sh
```

**Section sources**
- [run.sh](file://run.sh)
- [start.sh](file://start.sh)
- [scripts/dev.sh](file://scripts/dev.sh)

## 启动脚本详解
CarrotSkin 提供了多个启动脚本以适应不同的使用场景。

### start.sh 脚本
`start.sh` 脚本是一个自包含的启动脚本，它在脚本内部定义了所有必需的环境变量，然后直接启动服务。这种方式简单直接，但不推荐用于生产环境，因为敏感信息（如数据库密码）直接暴露在脚本中。

**Section sources**
- [start.sh](file://start.sh)

### run.sh 脚本
`run.sh` 脚本是一个更智能的启动脚本，它分为三个阶段：
1. **检查 swag 工具**：确保 `swag` 命令可用，如果不存在则自动安装。
2. **生成 Swagger 文档**：运行 `swag init` 命令生成 API 文档，确保 API 文档与代码同步。
3. **启动服务器**：最后启动 Go 服务。

这个脚本的优势在于它确保了 API 文档的实时性，并且不包含敏感的环境变量。

**Section sources**
- [run.sh](file://run.sh)

### check-env.sh 脚本
`scripts/check-env.sh` 是一个环境检查脚本，用于验证必需的环境变量是否已正确设置。它会检查 `.env` 文件是否存在，并验证关键变量（如数据库连接、RustFS 凭证、JWT 密钥）是否已配置。此外，它还会检查 JWT 密钥的长度和是否使用了默认值，提供安全建议。

**Section sources**
- [scripts/check-env.sh](file://scripts/check-env.sh)

## 生产环境配置
在生产环境中部署 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）来设置。

```mermaid
flowchart TD
A[环境变量] --> B[pkg/config/config.go]
B --> C[应用配置]
C --> D[数据库连接]
C --> E[Redis连接]
C --> F[RustFS连接]
C --> G[JWT配置]
```

**Diagram sources**
- [pkg/config/config.go](file://pkg/config/config.go)

**Section sources**
- [pkg/config/config.go](file://pkg/config/config.go)
- [start.sh](file://start.sh)

## 健康检查与监控
CarrotSkin 内置了健康检查功能，便于集成到监控系统中。

### 健康检查端点
服务提供了一个 `/health` 的健康检查端点，返回简单的 JSON 响应：
```json
{
  "status": "ok",
  "message": "CarrotSkin API is running"
}
```
该端点由 `internal/handler/swagger.go` 中的 `HealthCheck` 函数实现，无需认证即可访问，适合用于负载均衡器和容器编排平台的健康探测。

### 监控建议
建议将以下指标纳入监控系统：
- HTTP 请求延迟和错误率
- 数据库连接池使用情况
- Redis 内存使用和命中率
- 对象存储的读写性能

```mermaid
sequenceDiagram
participant 监控系统
participant CarrotSkin服务
participant 数据库
participant Redis
participant 对象存储
监控系统->>CarrotSkin服务 : GET /health
CarrotSkin服务->>数据库 : 检查连接
CarrotSkin服务->>Redis : 检查连接
CarrotSkin服务->>对象存储 : 检查连接
CarrotSkin服务-->>监控系统 : 返回健康状态
```

**Diagram sources**
- [internal/handler/swagger.go](file://internal/handler/swagger.go)
- [internal/handler/routes.go](file://internal/handler/routes.go)

**Section sources**
- [internal/handler/swagger.go](file://internal/handler/swagger.go)

## 日志管理
CarrotSkin 使用 Zap 日志库进行日志记录，提供了结构化日志输出。

### 日志配置
日志行为由以下环境变量控制：
- `LOG_LEVEL`：日志级别（debug, info, warn, error）
- `LOG_FORMAT`：日志格式（json 或 console）
- `LOG_OUTPUT`：日志输出位置（文件路径或 stdout）

### 日志轮转
日志文件支持自动轮转，配置包括最大文件大小、备份数量和最大保留天数。日志文件默认存储在 `logs/app.log`。

```mermaid
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**
- [pkg/logger/logger.go](file://pkg/logger/logger.go)

**Section sources**
- [pkg/logger/logger.go](file://pkg/logger/logger.go)
- [pkg/config/config.go](file://pkg/config/config.go)

## 高级部署策略
对于生产环境，建议采用以下高级部署策略。

### Docker 部署
虽然项目未提供 Dockerfile，但可以轻松创建。Docker 部署的优势包括环境隔离、版本控制和易于扩展。

```dockerfile
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 管道中：
1. 代码推送触发 CI 构建
2. 运行单元测试和集成测试
3. 构建 Docker 镜像
4. 推送镜像到镜像仓库
5. 在目标环境部署新版本

### 高可用性部署
对于高可用性要求，建议：
- 使用 Kubernetes 部署多个服务实例
- 配置负载均衡器分发流量
- 使用外部的 PostgreSQL 集群和 Redis 集群
- 实现蓝绿部署或金丝雀发布

## 故障排除
### 常见问题
- **服务无法启动**：检查 `check-env.sh` 脚本，确保所有必需的环境变量已设置。
- **数据库连接失败**：验证数据库主机、端口、用户名和密码是否正确。
- **JWT 密钥警告**：生产环境中必须更改默认的 JWT 密钥。
- **Swagger 文档缺失**：确保已运行 `swag init` 命令。

### 调试建议
- 查看日志文件 `logs/app.log` 获取详细错误信息
- 使用 `curl http://localhost:8080/health` 检查服务健康状态
- 检查依赖服务（数据库、Redis、对象存储）是否正常运行

**Section sources**
- [scripts/check-env.sh](file://scripts/check-env.sh)
- [pkg/logger/logger.go](file://pkg/logger/logger.go)
- [internal/handler/swagger.go](file://internal/handler/swagger.go)