Become a sponsor
Docker 一键启动
本章节介绍如何使用 Docker Compose 一键启动项目，无需手动安装 Python、Node.js 等运行环境。Docker 方式适合快速体验、测试部署和 CI/CD 场景。
温馨提示
使用 Docker 方式启动前，请确保已安装以下软件：
- Docker Desktop（Windows / macOS）或 Docker Engine（Linux）
- Docker Compose（Docker Desktop 已内置）
前置准备
- 安装 Docker Desktop
Windows / macOS
访问 Docker Desktop 官网，下载并安装适合你操作系统的版本。
安装完成后，在终端中验证：
bash
# 查看 Docker 版本
docker --version
Docker version 27.3.1, build ce12230
# 查看 Docker Compose 版本
docker compose version
Docker Compose version v2.29.7Linux（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.elevue # 数据库名称
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 位以上随机字符串）重要提示
JWT_SALT 必须设置，否则应用无法启动。生成方式：
bash
python -c "import secrets; print(secrets.token_urlsafe(48))"Docker Compose 配置
项目的 docker-compose.yml 文件定义了后端服务的容器编排：
yaml
# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: FastAPI+EleVue 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
# 应用服务
# ============================================================
services:
# ------------------------------------------------------------
# 后端服务
# ------------------------------------------------------------
fastapi_elevue:
# 构建镜像名称
image: fastapi_elevue
# 容器运行时名称
container_name: fastapi_elevue
# 镜像构建配置
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 个日志文件配置说明
| 配置项 | 说明 |
|---|---|
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_elevue Started访问服务
容器启动后，通过以下地址访问：
后端服务：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_elevue- 停止与重启
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_elevue bash
# 在容器内执行 Python 命令
docker compose exec fastapi_elevue python -c "print('hello')"环境变量注入
Docker 模式下，环境变量通过 env_file 从 .env 文件注入到容器中。也可以通过 docker run 命令行参数覆盖：
bash
# 使用 --env-file 指定环境变量文件
docker run --env-file .env fastapi_elevue
# 通过 -e 参数覆盖单个变量
docker run -e FASTAPI_PORT=9090 fastapi_elevue温馨提示
容器内的环境变量优先级：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_elevue常见原因：JWT_SALT 未配置、数据库连接失败、Redis 连接失败。
总结
本章节介绍了使用 Docker Compose 一键启动项目的完整流程：安装 Docker → 准备环境变量 → 构建并启动容器 → 常用运维命令。Docker 方式避免了手动安装 Python 和 Node.js 环境的繁琐步骤，适合快速体验和测试部署。生产环境部署时，建议结合 Nginx 反向代理和 HTTPS 证书进行配置。更多环境变量配置项，请参见 环境变量速查表。