276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# 部署
|
||
|
||
<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) |