# Docker 部署

相关源文件：

- [Dockerfile](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile)
- [docker-compose.yml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml)
- [settings.xml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/settings.xml)

本文档描述了如何使用 Docker 部署 SmartClass 后端应用。涵盖了容器化架构、部署流程、配置选项及相关运维内容。如需一般性部署信息，请参阅[部署与配置](https://deepwiki.com/Ubanillx/smartclass-backend/7-deployment-and-configuration)，具体配置选项请参考[配置选项](https://deepwiki.com/Ubanillx/smartclass-backend/7.2-configuration-options)。

## 部署架构

SmartClass 后端应用采用由 Docker Compose 管理的多容器架构。这种设置确保组件之间的隔离性、可扩展性以及简化部署流程。

### 容器架构

来源：[Dockerfile 21-49 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L21-L49) | [docker-compose.yml 1-55 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L1-L55)

## 前提条件

在使用 Docker 部署 SmartClass 后端之前，请确保具备以下条件：

1. Docker Engine（版本 19.03 或更高）
2. Docker Compose（版本 1.27 或更高）
3. 至少 2GB RAM 用于容器
4. 至少 2GB 的可用磁盘空间
5. 网络访问权限（用于拉取 Docker 镜像）

## 部署流程

### 使用 Docker Compose 构建并运行

整个应用栈可以通过一个命令部署：

```
docker-compose up -d
```

该命令会：

- 使用 Dockerfile 构建应用容器
- 拉取所需的 MySQL 和 Redis 镜像
- 设置容器间的网络
- 映射所需端口
- 创建和配置持久化卷
- 在后台启动所有服务

要停止服务：

```
docker-compose down
```

来源：[docker-compose.yml 1-65 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L1-L65)

## 容器详情

### 应用容器 (smartclass-app)

应用容器使用多阶段 Docker 构建流程，以优化镜像大小和构建效率。

构建过程如下：

1. 使用自定义设置的 Maven 下载依赖项
2. 编译应用源代码
3. 打包成 JAR 文件
4. 创建仅包含必要组件的最小运行时镜像
5. 以非 root 用户身份运行以提高安全性

来源：[Dockerfile 1-20 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L1-L20) | [Dockerfile 21-49 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L21-L49) | [Dockerfile 50-72 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L50-L72)

### 数据库容器 (MySQL)

MySQL 容器：

- 使用 MySQL 8.0 作为基础镜像
- 通过环境变量配置 root 密码
- 创建名为 `smart_class` 的数据库
- 使用持久化卷进行数据存储
- 可通过 3306 端口访问
- 从 `./sql` 目录加载初始化脚本

来源：[docker-compose.yml 28-42 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L28-L42)

### 缓存容器 (Redis)

Redis 容器：

- 使用 Redis 6.2 作为基础镜像
- 配置密码以增强安全性
- 使用持久化卷进行数据存储
- 可通过 6379 端口访问

来源：[docker-compose.yml 45-55 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L45-L55)

## 配置选项

### 环境变量

以下环境变量可用于定制应用配置：

| 变量 | 默认值 | 描述 |
|---|---|---|
| SPRING_PROFILES_ACTIVE | prod | 要激活的 Spring profile |
| JAVA_OPTS | -Xms512m -Xmx1024m | JVM 内存分配选项 |
| SERVER_PORT | 8101 | 应用服务器端口 |
| SPRING_DATASOURCE_URL | jdbc:mysql://localhost:3306/smart_class | 数据库连接 URL |
| SPRING_DATASOURCE_USERNAME | root | 数据库用户名 |
| SPRING_DATASOURCE_PASSWORD | root123456 | 数据库密码 |
| SPRING_REDIS_HOST | localhost | Redis 主机 |
| SPRING_REDIS_PORT | 6379 | Redis 端口 |
| SPRING_REDIS_PASSWORD | (空) | Redis 密码 |
| TZ | Asia/Shanghai | 时区设置 |

这些变量可以在 `docker-compose.yml` 文件中修改，或通过环境文件提供。

来源：[Dockerfile 51-66 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L51-L66) | [docker-compose.yml 12-19 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L12-L19)

### 自定义 docker-compose.yml

要自定义部署，请编辑 `docker-compose.yml` 文件。常见的自定义包括：

1. 更改暴露的端口
2. 修改数据库凭证
3. 调整卷挂载点
4. 添加特定环境变量

## 数据持久化

Docker 部署使用命名卷来确保数据持久化：

| 卷 | 容器 | 用途 |
|---|---|---|
| mysql-data | MySQL | 存储数据库文件 |
| redis-data | Redis | 存储 Redis 数据 |
| /app/data | 应用 | 存储上传文件和应用数据 |
| /app/logs | 应用 | 存储应用日志 |

即使容器被停止或删除，这些卷也会保留，确保跨部署的数据完整性。

来源：[Dockerfile 第 45 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L45-L45) | [docker-compose.yml 37-39 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L37-L39) | [docker-compose.yml 51-52 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L51-L52) | [docker-compose.yml 58-60 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L58-L60)

## 网络配置

容器通过名为 `smartclass-network` 的独立桥接网络进行通信：

此网络配置：

- 将应用组件与其他 Docker 容器隔离
- 允许容器通过服务名称相互引用
- 仅向主机暴露必要的端口

来源：[docker-compose.yml 23-25 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L23-L25) | [docker-compose.yml 40-42 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L40-L42) | [docker-compose.yml 53-55 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L53-L55) | [docker-compose.yml 63-65 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L63-L65)

## 健康检查

应用容器包含健康检查功能，用于验证 Java 运行环境是否正常工作。这有助于 Docker 的编排功能检测并从故障中恢复。

来源：[Dockerfile 67-69 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L67-L69)

## 故障排查

### 检查容器状态

```
docker-compose ps
```

### 查看应用日志

```
docker-compose logs smartclass-app
```

### 常见问题

1. **数据库连接失败**

    - 检查数据库容器是否正在运行：`docker-compose ps mysql`
    - 验证 docker-compose.yml 中的环境变量是否匹配

2. **应用无法启动**

    - 检查日志：`docker-compose logs smartclass-app`
    - 验证端口可用性：`netstat -tuln | grep 8101`

3. **Redis 连接问题**

    - 验证 Redis 是否正在运行：`docker-compose ps redis`
    - 检查 Redis 密码配置是否一致

## 安全考虑

Docker 部署实施了几项安全最佳实践：

1. 应用以非 root 用户 (`smartclass`) 身份运行
2. 数据库和 Redis 服务受密码保护
3. 服务通过隔离的 Docker 网络进行通信
4. 仅暴露必要端口

对于生产环境，建议采取以下额外措施：

- 实现带有 SSL 终止的反向代理
- 使用 Docker secrets 来管理敏感凭据
- 设置定期备份机制

来源：[Dockerfile 29-30 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L29-L30) | [Dockerfile 47-49 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L47-L49) | [docker-compose.yml 33-34 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L33-L34) | [docker-compose.yml 48 行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L48-L48)