djangoadmin/djangoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
gitadmin
2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_FastAPI_NaiveVue/zh/volume1/docker.md
+324
View File
@@ -0,0 +1,324 @@
# 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.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 位以上随机字符串）
```
:::danger 重要提示
`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 个日志文件
```
:::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_elevue 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_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
```
:::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_elevue
```
常见原因：`JWT_SALT` 未配置、数据库连接失败、Redis 连接失败。
## 总结
本章节介绍了使用 Docker Compose 一键启动项目的完整流程：安装 Docker → 准备环境变量 → 构建并启动容器 → 常用运维命令。Docker 方式避免了手动安装 Python 和 Node.js 环境的繁琐步骤，适合快速体验和测试部署。生产环境部署时，建议结合 Nginx 反向代理和 HTTPS 证书进行配置。更多环境变量配置项，请参见 [环境变量速查表](/zh/volume1/env-vars)。