djangoadmin/djangoadmin-wiki

Fork 0

Files

T

gitadmin 91998056ca 签入版本

2026-09-12 23:12:15 +08:00

8.7 KiB

Raw Blame History

Docker 一键启动

本章节介绍如何使用 Docker Compose 一键启动项目，无需手动安装 Python、Node.js 等运行环境。Docker 方式适合快速体验、测试部署和 CI/CD 场景。

:::tip 温馨提示使用 Docker 方式启动前，请确保已安装以下软件：

Docker Desktop（Windows / macOS）或 Docker Engine（Linux）
Docker Compose（Docker Desktop 已内置） :::

前置准备

安装 Docker Desktop

Windows / macOS

访问 Docker Desktop 官网，下载并安装适合你操作系统的版本。

安装完成后，在终端中验证：

# 查看 Docker 版本
docker --version
Docker version 27.3.1, build ce12230

# 查看 Docker Compose 版本
docker compose version
Docker Compose version v2.29.7

Linux（Ubuntu / Debian）

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 重新登录后验证
docker --version

准备环境变量文件

# 复制环境变量示例文件
cp .env.example .env

编辑 .env 文件，修改数据库和 Redis 的连接信息。Docker 模式下，服务间通信使用容器名称作为主机名：

# ============================================================
# 数据库配置（使用 MySQL 容器）
# 说明：连接 Docker 容器中运行的 MySQL 数据库
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_HOST=127.0.0.1                # 数据库主机地址（本地容器）
DATABASE_PORT=3306                     # 数据库端口（MySQL 默认 3306）
DATABASE_USER=root                     # 数据库用户名
DATABASE_PASSWORD=your_password        # 数据库密码（请修改为实际密码）
DATABASE_PREFIX="django_"              # 数据表前缀

# ============================================================
# Redis 配置
# 说明：用于缓存、验证码存储及 JWT 令牌黑名单等场景
# ============================================================
REDIS_HOST=127.0.0.1                   # Redis 主机地址（本地容器）
REDIS_PORT=6379                        # Redis 端口（默认 6379）
REDIS_PASSWORD=your_redis_password     # Redis 密码（请修改为实际密码）
REDIS_DB=0                             # Redis 数据库索引

Docker Compose 配置

项目的 docker-compose.yml 文件定义了后端服务的容器编排：

# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: Django+EleVue 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
# 应用服务
# ============================================================
services:
  # ------------------------------------------------------------
  # 后端服务
  # ------------------------------------------------------------
  django_elevue:
    # 构建镜像名称
    image: django_elevue
    # 容器运行时名称
    container_name: django_elevue
    # 镜像构建配置
    build:
      context: ./              # 构建上下文路径（项目根目录）
      dockerfile: Dockerfile   # Dockerfile 文件名
    # 容器重启策略：异常退出时自动重启
    restart: always
    # 网络模式：使用宿主机网络栈
    # 说明：host 模式下容器直接使用宿主机网络，DATABASE_HOST/REDIS_HOST 设为 127.0.0.1
    #       时可直接连通宿主机上的服务；该模式下 ports 映射配置将被忽略
    # 注意：若改用 bridge 网络，需将 DATABASE_HOST/REDIS_HOST 改为宿主机可访问地址
    #       （如 host.docker.internal），并取消下方 ports 的注释
    network_mode: host
    # 端口映射（仅在 bridge 网络模式下生效；host 模式下无效）
    # ports:
    #   - 8000:8000
    # 数据卷挂载
    volumes:
      - $PWD/public/uploads:/app/public/uploads   # 挂载上传文件目录，便于持久化存储
    # 从宿主机 .env 文件读取环境变量，注入容器进程
    env_file:
      - .env
    # 容器启动执行的命令
    command: python manage.py runserver 0.0.0.0:8000
    # 日志驱动配置
    logging:
      driver: "json-file"              # 使用 JSON 文件日志驱动
      options:
        max-size: "500m"               # 单个日志文件最大 500MB
        max-file: "10"                 # 最多保留 10 个日志文件

:::tip 配置说明

配置项	说明
`restart: always`	容器异常退出时自动重启
`network_mode: host`	使用宿主机网络，DATABASE_HOST/REDIS_HOST 可直接用 127.0.0.1
`volumes`	上传文件目录持久化挂载
`env_file`	从 `.env` 文件注入环境变量
`logging`	日志文件大小限制 500MB，最多保留 10 个文件
:::

一键启动

构建并启动

# 构建镜像并启动容器（首次运行或代码变更后）
docker compose up --build

后台启动

# 后台模式启动
docker compose up --build -d

仅启动（镜像已构建）

# 直接启动，不重新构建
docker compose up

# 后台模式
docker compose up -d

启动成功后，终端输出类似以下信息：

[+] Building 45.2s (12/12) FINISHED
[+] Running 2/2
 ✔ Network djangoadmin_default Created
 ✔ Container django_elevue    Started

:::tip 访问服务容器启动后，通过以下地址访问：

后端服务：http://127.0.0.1:8000
Django Admin：http://127.0.0.1:8000/admin/

:::

常用 Docker 命令

查看容器状态

# 查看运行中的容器
docker compose ps

# 查看所有容器（包括已停止的）
docker compose ps -a

查看日志

# 查看实时日志
docker compose logs -f

# 查看最近 100 行日志
docker compose logs --tail 100

# 查看指定服务日志
docker compose logs -f django_elevue

停止与重启

# 停止容器
docker compose stop

# 停止并删除容器
docker compose down

# 重启容器
docker compose restart

重新构建

# 强制重新构建镜像（不使用缓存）
docker compose build --no-cache

# 构建并启动
docker compose up --build

进入容器

# 进入运行中的容器终端
docker compose exec django_elevue bash

# 在容器内执行 Django 命令
docker compose exec django_elevue python manage.py shell

环境变量注入

Docker 模式下，环境变量通过 env_file 从 .env 文件注入到容器中。也可以通过 docker run 命令行参数覆盖：

# 使用 --env-file 指定环境变量文件
docker run --env-file .env django_elevue

# 通过 -e 参数覆盖单个变量
docker run -e DJANGO_DEBUG=False django_elevue

:::tip 温馨提示容器内的环境变量优先级：docker run -e > env_file > Dockerfile ENV。 :::

数据持久化

上传文件

docker-compose.yml 中配置了上传目录的挂载：

volumes:
    - $PWD/public/uploads:/app/public/uploads

宿主机的 public/uploads 目录与容器内的 /app/public/uploads 目录双向同步，确保容器重建后上传文件不丢失。

数据库数据

如果使用外部 MySQL 数据库（非 Docker 容器），数据存储在宿主机的 MySQL 数据目录中。如果需要在 Docker 中运行 MySQL，可以添加 MySQL 服务到 docker-compose.yml。

常见问题

构建失败

# 清除 Docker 缓存后重新构建
docker compose build --no-cache
docker compose up --build

端口冲突

如果端口 8000 被占用，可修改 docker-compose.yml 中的端口映射：

ports:
    - 9000:8000

无法连接数据库

1. 确认 network_mode: host 模式下，DATABASE_HOST 设置为 127.0.0.1
2. 如果使用 bridge 网络模式，DATABASE_HOST 需要设置为宿主机 IP 或 host.docker.internal
3. 确认 MySQL 服务允许来自 Docker 网络的连接

容器启动后立即退出

# 查看容器日志排查原因
docker compose logs django_elevue

常见原因：数据库连接失败、Redis 连接失败、数据库未创建。

总结

本章节介绍了使用 Docker Compose 一键启动项目的完整流程：安装 Docker → 准备环境变量 → 构建并启动容器 → 常用运维命令。Docker 方式避免了手动安装 Python 和 Node.js 环境的繁琐步骤，适合快速体验和测试部署。生产环境部署时，建议结合 Nginx 反向代理和 HTTPS 证书进行配置。更多环境变量配置项，请参见环境变量速查表。

8.7 KiB Raw Blame History Unescape Escape