# 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.flask.antdvue   # 数据库名称
DB_USERNAME=root                 # 数据库用户名
DB_PASSWORD=your_password        # 数据库密码（请修改为实际密码）
DB_PREFIX=flask_                 # 数据表前缀

# ============================================================
# 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 加密盐值（建议 16 位以上随机字符串）
```

:::danger 重要提示
`JWT_SALT` 必须设置，否则应用无法启动。生成方式：

```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
:::

## Docker Compose 配置

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

```yaml
# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: Flask+AntDesign 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
# 应用服务
# ============================================================
services:
  # ------------------------------------------------------------
  # 后端服务
  # ------------------------------------------------------------
  flask_antdvue:
    # 构建镜像名称
    image: flask_antdvue
    # 容器运行时名称
    container_name: flask_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:
    #   - 8021:8021
    # 数据卷挂载
    volumes:
      - $PWD/uploads:/data/apps/uploads   # 挂载上传文件目录，便于持久化存储
    # 从宿主机 .env 文件读取环境变量，注入容器进程
    env_file:
      - .env
    # 容器启动执行的命令
    command: python app.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 flask_antdvue Started
```

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

```
后端服务：http://127.0.0.1:8021
验证码接口：http://127.0.0.1:8021/api/v1/captcha
```
:::

## 常用 Docker 命令

+ 查看容器状态

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

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

+ 查看日志

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

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

# 查看指定服务日志
docker compose logs -f flask_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 flask_antdvue bash

# 在容器内执行 Python 命令
docker compose exec flask_antdvue python -c "print('hello')"
```

## 环境变量注入

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

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

# 通过 -e 参数覆盖单个变量
docker run -e FLASK_PORT=9090 flask_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
```

+ 端口冲突

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

```yaml
ports:
    - 9090:8021
```

+ 无法连接数据库

```
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 flask_antdvue
```

常见原因：`JWT_SALT` 未配置、数据库连接失败、Redis 连接失败。

## 总结

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