325 lines
9.1 KiB
Markdown
325 lines
9.1 KiB
Markdown
# Docker 一键启动
|
||
|
||
本章节介绍如何使用 `Docker Compose` 一键启动项目，无需手动安装 Python、Node.js 等运行环境。Docker 方式适合快速体验、测试部署和 CI/CD 场景。
|
||
|
||
:::tip 温馨提示
|
||
使用 Docker 方式启动前，请确保已安装以下软件：
|
||
1. [Docker Desktop](https://www.docker.com/products/docker-desktop/)（Windows / macOS）或 Docker Engine（Linux）
|
||
2. [Docker Compose](https://docs.docker.com/compose/install/)（Docker Desktop 已内置）
|
||
:::
|
||
|
||
## 前置准备
|
||
|
||
+ 安装 Docker Desktop
|
||
|
||
**Windows / macOS**
|
||
|
||
访问 [Docker Desktop 官网](https://www.docker.com/products/docker-desktop/)，下载并安装适合你操作系统的版本。
|
||
|
||
安装完成后，在终端中验证：
|
||
|
||
```bash
|
||
# 查看 Docker 版本
|
||
docker --version
|
||
Docker version 27.3.1, build ce12230
|
||
|
||
# 查看 Docker Compose 版本
|
||
docker compose version
|
||
Docker Compose version v2.29.7
|
||
```
|
||
|
||
**Linux（Ubuntu / Debian）**
|
||
|
||
```bash
|
||
# 安装 Docker
|
||
curl -fsSL https://get.docker.com | sh
|
||
|
||
# 将当前用户添加到 docker 组
|
||
sudo usermod -aG docker $USER
|
||
|
||
# 重新登录后验证
|
||
docker --version
|
||
```
|
||
|
||
+ 准备环境变量文件
|
||
|
||
```bash
|
||
# 复制环境变量示例文件
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，修改数据库和 Redis 的连接信息。Docker 模式下，服务间通信使用容器名称作为主机名：
|
||
|
||
```bash
|
||
# ============================================================
|
||
# 数据库配置（使用 MySQL 容器）
|
||
# 说明：连接 Docker 容器中运行的 MySQL 数据库
|
||
# ============================================================
|
||
DB_HOST=127.0.0.1 # 数据库主机地址（本地容器）
|
||
DB_PORT=3306 # 数据库端口（MySQL 默认 3306）
|
||
DB_DATABASE=djangoadmin.fastapi.antdvue # 数据库名称
|
||
DB_USERNAME=root # 数据库用户名
|
||
DB_PASSWORD=your_password # 数据库密码（请修改为实际密码）
|
||
|
||
# ============================================================
|
||
# Redis 配置
|
||
# 说明：用于缓存、Session 存储及消息队列等场景
|
||
# ============================================================
|
||
REDIS_HOST=127.0.0.1 # Redis 主机地址（本地容器）
|
||
REDIS_PORT=6379 # Redis 端口（默认 6379）
|
||
REDIS_PASSWORD=your_redis_password # Redis 密码（请修改为实际密码）
|
||
REDIS_AUTH=True # 是否启用密码认证（True/False）
|
||
|
||
# ============================================================
|
||
# JWT 配置（必填）
|
||
# 说明：用于生成和验证用户身份令牌，请务必修改为随机字符串
|
||
# ============================================================
|
||
JWT_SALT=your_generated_secret_key_here # JWT 加密盐值（建议 32 位以上随机字符串）
|
||
```
|
||
|
||
:::danger 重要提示
|
||
`JWT_SALT` 必须设置，否则应用无法启动。生成方式：
|
||
|
||
```bash
|
||
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||
```
|
||
:::
|
||
|
||
## Docker Compose 配置
|
||
|
||
项目的 `docker-compose.yml` 文件定义了后端服务的容器编排：
|
||
|
||
```yaml
|
||
# +======================================================================
|
||
# | 模块: Docker Compose 配置
|
||
# | 说明: FastAPI+AntdVue 应用服务容器编排
|
||
# +======================================================================
|
||
version: '3.7'
|
||
# ============================================================
|
||
# 应用服务
|
||
# ============================================================
|
||
services:
|
||
# ------------------------------------------------------------
|
||
# 后端服务
|
||
# ------------------------------------------------------------
|
||
fastapi_antdvue:
|
||
# 构建镜像名称
|
||
image: fastapi_antdvue
|
||
# 容器运行时名称
|
||
container_name: fastapi_antdvue
|
||
# 镜像构建配置
|
||
build:
|
||
context: ./ # 构建上下文路径（项目根目录）
|
||
dockerfile: Dockerfile # Dockerfile 文件名
|
||
# 容器重启策略：异常退出时自动重启
|
||
restart: always
|
||
# 网络模式：使用宿主机网络栈
|
||
# 说明：host 模式下容器直接使用宿主机网络，DB_HOST/REDIS_HOST 设为 127.0.0.1
|
||
# 时可直接连通宿主机上的服务；该模式下 ports 映射配置将被忽略
|
||
# 注意：若改用 bridge 网络，需将 DB_HOST/REDIS_HOST 改为宿主机可访问地址
|
||
# （如 host.docker.internal），并取消下方 ports 的注释
|
||
network_mode: host
|
||
# 端口映射（仅在 bridge 网络模式下生效；host 模式下无效）
|
||
# ports:
|
||
# - 8031:8031
|
||
# 数据卷挂载
|
||
volumes:
|
||
- $PWD/uploads:/data/apps/uploads # 挂载上传文件目录，便于持久化存储
|
||
# 从宿主机 .env 文件读取环境变量，注入容器进程
|
||
env_file:
|
||
- .env
|
||
# 容器启动执行的命令
|
||
command: python src/main.py
|
||
# 日志驱动配置
|
||
logging:
|
||
driver: "json-file" # 使用 JSON 文件日志驱动
|
||
options:
|
||
max-size: "500m" # 单个日志文件最大 500MB
|
||
max-file: "10" # 最多保留 10 个日志文件
|
||
```
|
||
|
||
:::tip 配置说明
|
||
| 配置项 | 说明 |
|
||
|:----|:----|
|
||
| `restart: always` | 容器异常退出时自动重启 |
|
||
| `network_mode: host` | 使用宿主机网络，DB_HOST/REDIS_HOST 可直接用 127.0.0.1 |
|
||
| `volumes` | 上传文件目录持久化挂载 |
|
||
| `env_file` | 从 `.env` 文件注入环境变量 |
|
||
| `logging` | 日志文件大小限制 500MB，最多保留 10 个文件 |
|
||
:::
|
||
|
||
## 一键启动
|
||
|
||
+ 构建并启动
|
||
|
||
```bash
|
||
# 构建镜像并启动容器（首次运行或代码变更后）
|
||
docker compose up --build
|
||
```
|
||
|
||
+ 后台启动
|
||
|
||
```bash
|
||
# 后台模式启动
|
||
docker compose up --build -d
|
||
```
|
||
|
||
+ 仅启动（镜像已构建）
|
||
|
||
```bash
|
||
# 直接启动，不重新构建
|
||
docker compose up
|
||
|
||
# 后台模式
|
||
docker compose up -d
|
||
```
|
||
|
||
启动成功后，终端输出类似以下信息：
|
||
|
||
```
|
||
[+] Building 45.2s (12/12) FINISHED
|
||
[+] Running 2/2
|
||
✔ Network djangoadmin_default Created
|
||
✔ Container fastapi_antdvue Started
|
||
```
|
||
|
||
:::tip 访问服务
|
||
容器启动后，通过以下地址访问：
|
||
|
||
```
|
||
后端服务：http://127.0.0.1:8031
|
||
Swagger 文档：http://127.0.0.1:8031/docs
|
||
```
|
||
:::
|
||
|
||
## 常用 Docker 命令
|
||
|
||
+ 查看容器状态
|
||
|
||
```bash
|
||
# 查看运行中的容器
|
||
docker compose ps
|
||
|
||
# 查看所有容器（包括已停止的）
|
||
docker compose ps -a
|
||
```
|
||
|
||
+ 查看日志
|
||
|
||
```bash
|
||
# 查看实时日志
|
||
docker compose logs -f
|
||
|
||
# 查看最近 100 行日志
|
||
docker compose logs --tail 100
|
||
|
||
# 查看指定服务日志
|
||
docker compose logs -f fastapi_antdvue
|
||
```
|
||
|
||
+ 停止与重启
|
||
|
||
```bash
|
||
# 停止容器
|
||
docker compose stop
|
||
|
||
# 停止并删除容器
|
||
docker compose down
|
||
|
||
# 重启容器
|
||
docker compose restart
|
||
```
|
||
|
||
+ 重新构建
|
||
|
||
```bash
|
||
# 强制重新构建镜像（不使用缓存）
|
||
docker compose build --no-cache
|
||
|
||
# 构建并启动
|
||
docker compose up --build
|
||
```
|
||
|
||
+ 进入容器
|
||
|
||
```bash
|
||
# 进入运行中的容器终端
|
||
docker compose exec fastapi_antdvue bash
|
||
|
||
# 在容器内执行 Python 命令
|
||
docker compose exec fastapi_antdvue python -c "print('hello')"
|
||
```
|
||
|
||
## 环境变量注入
|
||
|
||
Docker 模式下，环境变量通过 `env_file` 从 `.env` 文件注入到容器中。也可以通过 `docker run` 命令行参数覆盖：
|
||
|
||
```bash
|
||
# 使用 --env-file 指定环境变量文件
|
||
docker run --env-file .env fastapi_antdvue
|
||
|
||
# 通过 -e 参数覆盖单个变量
|
||
docker run -e FASTAPI_PORT=9090 fastapi_antdvue
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
容器内的环境变量优先级：`docker run -e` > `env_file` > `Dockerfile ENV`。
|
||
:::
|
||
|
||
## 数据持久化
|
||
|
||
+ 上传文件
|
||
|
||
`docker-compose.yml` 中配置了上传目录的挂载：
|
||
|
||
```yaml
|
||
volumes:
|
||
- $PWD/uploads:/data/apps/uploads
|
||
```
|
||
|
||
宿主机的 `$PWD/uploads` 目录与容器内的 `/data/apps/uploads` 目录双向同步，确保容器重建后上传文件不丢失。
|
||
|
||
+ 数据库数据
|
||
|
||
如果使用外部 MySQL 数据库（非 Docker 容器），数据存储在宿主机的 MySQL 数据目录中。如果需要在 Docker 中运行 MySQL，可以添加 MySQL 服务到 `docker-compose.yml`。
|
||
|
||
## 常见问题
|
||
|
||
+ 构建失败
|
||
|
||
```bash
|
||
# 清除 Docker 缓存后重新构建
|
||
docker compose build --no-cache
|
||
docker compose up --build
|
||
```
|
||
|
||
+ 端口冲突
|
||
|
||
如果端口 `8031` 被占用，可修改 `docker-compose.yml` 中的端口映射：
|
||
|
||
```yaml
|
||
ports:
|
||
- 9090:8031
|
||
```
|
||
|
||
+ 无法连接数据库
|
||
|
||
```
|
||
1. 确认 network_mode: host 模式下，DB_HOST 设置为 127.0.0.1
|
||
2. 如果使用 bridge 网络模式，DB_HOST 需要设置为宿主机 IP 或 host.docker.internal
|
||
3. 确认 MySQL 服务允许来自 Docker 网络的连接
|
||
```
|
||
|
||
+ 容器启动后立即退出
|
||
|
||
```bash
|
||
# 查看容器日志排查原因
|
||
docker compose logs fastapi_antdvue
|
||
```
|
||
|
||
常见原因：`JWT_SALT` 未配置、数据库连接失败、Redis 连接失败。
|
||
|
||
## 总结
|
||
|
||
本章节介绍了使用 Docker Compose 一键启动项目的完整流程：安装 Docker → 准备环境变量 → 构建并启动容器 → 常用运维命令。Docker 方式避免了手动安装 Python 和 Node.js 环境的繁琐步骤，适合快速体验和测试部署。生产环境部署时，建议结合 Nginx 反向代理和 HTTPS 证书进行配置。更多环境变量配置项，请参见 [环境变量速查表](/zh/volume1/env-vars)。
|