517 lines
18 KiB
Markdown
517 lines
18 KiB
Markdown
# Docker 快速部署
|
||
|
||
本章节介绍如何使用 Docker 快速部署后端服务，无需手动安装 Python、MySQL、Redis 等环境。
|
||
|
||
:::tip 温馨提示
|
||
Docker 部署适合快速体验和生产环境。本地开发建议使用 [后端启动](/zh/volume1/backend) 章节的方式。
|
||
:::
|
||
|
||
## 前置条件
|
||
|
||
确保已安装 Docker 和 Docker Compose：
|
||
|
||
```bash
|
||
# 验证 Docker 安装
|
||
docker --version
|
||
# Docker version 24.0.x
|
||
|
||
# 验证 Docker Compose 安装
|
||
docker compose version
|
||
# Docker Compose version v2.x.x
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
### 1. 准备环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env，配置数据库密码、Redis 密码、JWT 密钥等
|
||
```
|
||
|
||
:::danger 重要提示
|
||
Docker 部署时，`.env` 中的 `DB_HOST` 和 `REDIS_HOST` 应指向 Docker 网络中的服务名称（如 `mysql`、`redis`），而非 `127.0.0.1`。
|
||
:::
|
||
|
||
### 2. 使用 Docker Compose 启动
|
||
|
||
```bash
|
||
# 构建并启动所有服务
|
||
docker compose up -d --build
|
||
|
||
# 查看服务状态
|
||
docker compose ps
|
||
|
||
# 查看日志
|
||
docker compose logs -f app
|
||
```
|
||
|
||
### 3. 访问服务
|
||
|
||
```
|
||
后端 API: http://127.0.0.1:8041/api/v1/health
|
||
```
|
||
|
||
## Dockerfile 说明
|
||
|
||
项目使用多阶段构建，减小镜像体积：
|
||
|
||
```dockerfile
|
||
# ======================================================================
|
||
# Stage 1: 构建依赖
|
||
# 使用一个临时镜像来解析 Poetry 依赖，避免把 Poetry 本身
|
||
# 和构建缓存带入最终运行镜像，从而减小镜像体积。
|
||
# ======================================================================
|
||
FROM python:3.12-slim AS builder
|
||
|
||
# 设置构建阶段的工作目录
|
||
WORKDIR /build
|
||
|
||
# 只拷贝依赖描述文件（先拷这些可以利用 Docker 层缓存：
|
||
# 只要依赖没变，后续 poetry export 就不会重新执行）
|
||
COPY pyproject.toml poetry.lock* ./
|
||
|
||
# 安装 Poetry，并把 pyproject.toml / poetry.lock 中的依赖
|
||
# 导出为普通的 requirements.txt，方便运行阶段用 pip 安装。
|
||
# --without-hashes：不写入哈希校验，简化后续安装。
|
||
RUN pip install --no-cache-dir poetry \
|
||
&& poetry export -f requirements.txt -o requirements.txt --without-hashes
|
||
|
||
|
||
# ======================================================================
|
||
# Stage 2: 运行
|
||
# 基于干净的 python:3.12-slim 构建最终镜像，只保留运行所需内容。
|
||
# ======================================================================
|
||
FROM python:3.12-slim AS runtime
|
||
|
||
# 环境变量配置：
|
||
# PYTHONUNBUFFERED=1 → 不缓冲 stdout/stderr，日志实时输出
|
||
# PYTHONDONTWRITEBYTECODE=1 → 不生成 .pyc 文件，保持镜像干净
|
||
# TZ=Asia/Shanghai → 设置容器时区为上海
|
||
ENV PYTHONUNBUFFERED=1 \
|
||
PYTHONDONTWRITEBYTECODE=1 \
|
||
TZ=Asia/Shanghai
|
||
|
||
# 设置应用运行的工作目录
|
||
WORKDIR /data/apps
|
||
|
||
# 从构建阶段拷贝导出的 requirements.txt
|
||
COPY --from=builder /build/requirements.txt ./
|
||
|
||
# 安装运行所需的 Python 依赖
|
||
RUN pip install --no-cache-dir -r requirements.txt
|
||
|
||
# 拷贝应用代码和资源文件到镜像中
|
||
COPY src ./src # 源码目录
|
||
COPY app.py ./ # 应用入口
|
||
COPY alembic ./alembic # 数据库迁移脚本
|
||
COPY alembic.ini ./ # 数据库迁移配置
|
||
COPY .env.example ./.env # 环境变量示例（默认作为 .env 使用）
|
||
COPY scripts ./scripts # 辅助脚本
|
||
COPY templates ./templates # 模板文件
|
||
COPY static ./static # 静态资源
|
||
|
||
# 创建运行时需要的上传目录和日志目录
|
||
RUN mkdir -p uploads logs
|
||
|
||
# 声明容器对外暴露的端口
|
||
EXPOSE 8041
|
||
|
||
# 容器启动命令：运行 Tornado 应用入口
|
||
CMD ["python", "app.py"]
|
||
```
|
||
|
||
### 多阶段构建原理
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Stage 1: builder │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ python:3.12-slim │ │
|
||
│ │ + Poetry │ │
|
||
│ │ + pyproject.toml / poetry.lock │ │
|
||
│ │ ─────────────────────────────────────────────────────── │ │
|
||
│ │ → poetry export → requirements.txt │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ 仅拷贝 requirements.txt │
|
||
│ Stage 2: runtime │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ python:3.12-slim │ │
|
||
│ │ + pip install -r requirements.txt │ │
|
||
│ │ + 应用源码 + 配置 + 脚本 │ │
|
||
│ │ ─────────────────────────────────────────────────────── │ │
|
||
│ │ → 最终镜像（不含 Poetry、不含构建缓存） │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## docker-compose.yml 说明
|
||
|
||
### 基础版（仅应用服务）
|
||
|
||
项目自带的 `docker-compose.yml` 仅包含应用服务，适用于数据库和 Redis 已有外部实例的场景：
|
||
|
||
```yaml
|
||
# ======================================================================
|
||
# Docker Compose 编排文件（基础版）
|
||
# 仅包含应用服务，适用于数据库和 Redis 已有外部实例的场景
|
||
# 使用方式：docker compose up -d
|
||
# 依赖根目录下的 .env 提供环境变量
|
||
# ======================================================================
|
||
|
||
services:
|
||
# ====================================================================
|
||
# 应用服务：构建并运行本项目
|
||
# ====================================================================
|
||
tornado_elevue:
|
||
image: tornado_elevue:latest # 镜像名称
|
||
container_name: tornado_elevue # 容器名称
|
||
build:
|
||
context: ./ # 构建上下文为项目根目录
|
||
dockerfile: Dockerfile # 使用项目根目录的 Dockerfile
|
||
restart: always # 总是自动重启（生产环境推荐）
|
||
ports:
|
||
- "8041:8041" # 宿主机端口:容器端口
|
||
environment:
|
||
- TORNADO_PORT=8041 # 应用监听端口
|
||
- TORNADO_ENV=production # 运行环境设为生产模式
|
||
env_file:
|
||
- .env # 从 .env 文件加载数据库密码等环境变量
|
||
volumes:
|
||
- ./uploads:/data/apps/uploads # 持久化上传文件到宿主机
|
||
- ./logs:/data/apps/logs # 持久化日志（与 Dockerfile WORKDIR 对应）
|
||
command: python app.py # 启动命令
|
||
logging:
|
||
driver: "json-file" # 日志驱动：JSON 文件
|
||
options:
|
||
max-size: "500m" # 单个日志文件最大 500MB
|
||
max-file: "10" # 最多保留 10 个日志文件
|
||
```
|
||
|
||
### 完整版（应用 + MySQL + Redis）
|
||
|
||
快速体验或小型部署推荐使用包含 MySQL 和 Redis 的完整版：
|
||
|
||
```yaml
|
||
# ======================================================================
|
||
# Docker Compose 编排文件（完整版）
|
||
# 包含三个服务：app（应用）、mysql（数据库）、redis（缓存）
|
||
# 使用方式：docker compose up -d
|
||
# 依赖根目录下的 .env 提供密码等环境变量
|
||
# ======================================================================
|
||
|
||
services:
|
||
# ====================================================================
|
||
# 应用服务：构建并运行本项目
|
||
# ====================================================================
|
||
app:
|
||
build: . # 使用当前目录的 Dockerfile 构建镜像
|
||
ports:
|
||
- "8041:8041" # 宿主机端口:容器端口（供外部访问）
|
||
env_file:
|
||
- .env # 从 .env 文件加载环境变量（数据库密码等）
|
||
environment:
|
||
- TORNADO_ENV=production # 运行环境设为生产模式
|
||
- DB_HOST=mysql # 数据库地址指向 Docker 网络中的 mysql 服务
|
||
- REDIS_HOST=redis # Redis 地址指向 Docker 网络中的 redis 服务
|
||
volumes:
|
||
- ./uploads:/data/apps/uploads # 持久化上传文件到宿主机
|
||
- ./logs:/data/apps/logs # 持久化日志（与 Dockerfile WORKDIR 对应）
|
||
depends_on:
|
||
- mysql # 声明依赖，但不保证 mysql 已就绪
|
||
- redis
|
||
restart: unless-stopped # 除非手动停止，否则总是自动重启
|
||
|
||
# ====================================================================
|
||
# MySQL 数据库
|
||
# ====================================================================
|
||
mysql:
|
||
image: mysql:8.0 # 官方 MySQL 8.0 镜像
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} # root 密码，从 .env 读取
|
||
MYSQL_DATABASE: ${DB_DATABASE} # 初始化时自动创建的数据库名
|
||
ports:
|
||
- "3306:3306" # 暴露到宿主机（生产环境建议去掉）
|
||
volumes:
|
||
- mysql_data:/var/lib/mysql # 命名卷持久化数据库数据
|
||
restart: unless-stopped
|
||
|
||
# ====================================================================
|
||
# Redis 缓存
|
||
# ====================================================================
|
||
redis:
|
||
image: redis:7-alpine # 轻量级 Redis 7 镜像
|
||
command: redis-server --requirepass ${REDIS_PASSWORD} # 启动时设置访问密码
|
||
ports:
|
||
- "6379:6379" # 暴露到宿主机（生产环境建议去掉）
|
||
volumes:
|
||
- redis_data:/data # 持久化 Redis 数据
|
||
restart: unless-stopped
|
||
|
||
# ======================================================================
|
||
# 命名卷：由 Docker 管理，数据存放在宿主机 /var/lib/docker/volumes 下
|
||
# ======================================================================
|
||
volumes:
|
||
mysql_data: # MySQL 数据持久化卷
|
||
redis_data: # Redis 数据持久化卷
|
||
```
|
||
|
||
### 完整版 .env 配置示例
|
||
|
||
使用完整版 docker-compose.yml 时，`.env` 文件中的数据库和 Redis 地址应指向 Docker 服务名称：
|
||
|
||
```bash
|
||
# ============================================================
|
||
# 数据库配置（指向 Docker 网络中的 mysql 服务）
|
||
# ============================================================
|
||
DB_DRIVER=mysql
|
||
DB_HOST=mysql # Docker 服务名称，不是 127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=djangoadmin.tornado.elevue
|
||
DB_USERNAME=root
|
||
DB_PASSWORD=your_mysql_password # 与 MYSQL_ROOT_PASSWORD 一致
|
||
DB_PREFIX=tornado_
|
||
|
||
# ============================================================
|
||
# Redis 配置（指向 Docker 网络中的 redis 服务）
|
||
# ============================================================
|
||
REDIS_HOST=redis # Docker 服务名称，不是 127.0.0.1
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=your_redis_password
|
||
REDIS_AUTH=True
|
||
|
||
# ============================================================
|
||
# JWT 配置（必填）
|
||
# ============================================================
|
||
JWT_SECRET=your_jwt_secret_key_at_least_32_bytes
|
||
|
||
# ============================================================
|
||
# 应用配置
|
||
# ============================================================
|
||
TORNADO_ENV=production
|
||
TORNADO_DEBUG=False
|
||
```
|
||
|
||
## 常用 Docker 命令
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker compose build
|
||
|
||
# 启动服务（后台运行）
|
||
docker compose up -d
|
||
|
||
# 停止服务
|
||
docker compose down
|
||
|
||
# 停止服务并删除数据卷（⚠️ 会丢失数据）
|
||
docker compose down -v
|
||
|
||
# 查看日志（实时跟踪）
|
||
docker compose logs -f app
|
||
|
||
# 查看所有服务日志
|
||
docker compose logs -f
|
||
|
||
# 进入容器
|
||
docker compose exec app bash
|
||
|
||
# 重启服务
|
||
docker compose restart app
|
||
|
||
# 查看容器状态
|
||
docker compose ps
|
||
|
||
# 查看容器资源占用
|
||
docker stats
|
||
```
|
||
|
||
## 数据持久化
|
||
|
||
Docker Compose 使用命名卷和绑定挂载持久化数据：
|
||
|
||
| 存储方式 | 卷名/路径 | 说明 |
|
||
|:---------|:----------|:-----|
|
||
| 命名卷 | `mysql_data` | MySQL 数据文件（由 Docker 管理） |
|
||
| 命名卷 | `redis_data` | Redis 数据文件（由 Docker 管理） |
|
||
| 绑定挂载 | `./uploads` | 上传文件（映射到宿主机） |
|
||
| 绑定挂载 | `./logs` | 日志文件（映射到宿主机） |
|
||
|
||
:::warning 数据备份
|
||
生产环境定期备份数据库：
|
||
|
||
```bash
|
||
# 备份 MySQL
|
||
docker compose exec mysql mysqldump -uroot -p${DB_PASSWORD} ${DB_DATABASE} > backup_$(date +%Y%m%d).sql
|
||
|
||
# 恢复 MySQL
|
||
docker compose exec -T mysql mysql -uroot -p${DB_PASSWORD} ${DB_DATABASE} < backup.sql
|
||
```
|
||
:::
|
||
|
||
## 生产环境部署建议
|
||
|
||
### 1. 关闭调试模式
|
||
|
||
```bash
|
||
# .env
|
||
TORNADO_DEBUG=False
|
||
TORNADO_ENV=production
|
||
```
|
||
|
||
### 2. 使用强密钥
|
||
|
||
```bash
|
||
# 生成 JWT 密钥
|
||
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||
```
|
||
|
||
### 3. 配置 Nginx 反向代理
|
||
|
||
```nginx
|
||
server {
|
||
# 监听 80 端口（HTTP）
|
||
listen 80;
|
||
|
||
# 域名配置（替换为实际域名）
|
||
server_name your-domain.com;
|
||
|
||
# 反向代理配置：将所有请求转发到 Tornado 应用
|
||
location / {
|
||
# 转发目标：Tornado 应用监听的地址和端口
|
||
proxy_pass http://127.0.0.1:8041;
|
||
|
||
# 传递原始请求头，让后端获取真实的客户端信息
|
||
proxy_set_header Host $host; # 原始域名
|
||
proxy_set_header X-Real-IP $remote_addr; # 客户端真实 IP
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 代理链 IP 列表
|
||
proxy_set_header X-Forwarded-Proto $scheme; # 原始协议（http/https）
|
||
|
||
# 超时配置（根据业务需求调整）
|
||
proxy_connect_timeout 60s; # 连接后端超时时间
|
||
proxy_send_timeout 60s; # 发送请求超时时间
|
||
proxy_read_timeout 60s; # 读取响应超时时间
|
||
|
||
# 缓冲配置
|
||
proxy_buffering on; # 开启响应缓冲，减轻后端压力
|
||
proxy_buffer_size 4k; # 响应头缓冲区大小
|
||
proxy_buffers 8 4k; # 响应体缓冲区数量和大小
|
||
}
|
||
|
||
# 静态文件直接由 Nginx 提供（可选，提升性能）
|
||
location /static/ {
|
||
alias /data/apps/static/; # 映射到容器内的静态文件目录
|
||
expires 7d; # 浏览器缓存 7 天
|
||
access_log off; # 关闭静态文件访问日志
|
||
}
|
||
|
||
# 上传文件直接由 Nginx 提供（可选）
|
||
location /uploads/ {
|
||
alias /data/apps/uploads/; # 映射到容器内的上传文件目录
|
||
expires 1d; # 浏览器缓存 1 天
|
||
access_log off;
|
||
}
|
||
|
||
# 安全配置：拒绝访问隐藏文件
|
||
location ~ /\. {
|
||
deny all;
|
||
access_log off;
|
||
log_not_found off;
|
||
}
|
||
}
|
||
```
|
||
|
||
:::tip HTTPS 配置
|
||
生产环境建议启用 HTTPS。可使用 Let's Encrypt 免费证书：
|
||
|
||
```bash
|
||
# 安装 certbot
|
||
apt install certbot python3-certbot-nginx
|
||
|
||
# 申请证书并自动配置 Nginx
|
||
certbot --nginx -d your-domain.com
|
||
```
|
||
:::
|
||
|
||
### 4. 限制端口暴露
|
||
|
||
生产环境建议不暴露 MySQL 和 Redis 端口到宿主机：
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
mysql:
|
||
# ports: # 注释掉或删除
|
||
# - "3306:3306" # 生产环境不暴露
|
||
...
|
||
|
||
redis:
|
||
# ports: # 注释掉或删除
|
||
# - "6379:6379" # 生产环境不暴露
|
||
...
|
||
```
|
||
|
||
### 5. 配置日志轮转
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
services:
|
||
app:
|
||
logging:
|
||
driver: "json-file"
|
||
options:
|
||
max-size: "500m" # 单个日志文件最大 500MB
|
||
max-file: "10" # 最多保留 10 个日志文件
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 容器启动失败
|
||
|
||
```bash
|
||
# 查看容器日志
|
||
docker compose logs app
|
||
|
||
# 常见原因：
|
||
# 1. .env 配置错误（数据库密码、Redis 密码）
|
||
# 2. 端口被占用（修改 docker-compose.yml 中的端口映射）
|
||
# 3. 磁盘空间不足
|
||
# 4. JWT_SECRET 未配置或过短
|
||
```
|
||
|
||
### 数据库连接失败
|
||
|
||
```
|
||
1. 确认 MySQL 容器已启动：docker compose ps
|
||
2. 确认 .env 中 DB_HOST=mysql（Docker 服务名称，不是 127.0.0.1）
|
||
3. 确认 DB_PASSWORD 与 MYSQL_ROOT_PASSWORD 一致
|
||
4. 确认 MySQL 已就绪：docker compose logs mysql
|
||
```
|
||
|
||
### Redis 连接失败
|
||
|
||
```
|
||
1. 确认 Redis 容器已启动：docker compose ps
|
||
2. 确认 .env 中 REDIS_HOST=redis（Docker 服务名称，不是 127.0.0.1）
|
||
3. 确认 REDIS_PASSWORD 与 docker-compose.yml 中的密码一致
|
||
```
|
||
|
||
### 容器内时区不对
|
||
|
||
Dockerfile 已设置 `TZ=Asia/Shanghai`，如果仍有时区问题：
|
||
|
||
```bash
|
||
# 进入容器检查时区
|
||
docker compose exec app date
|
||
|
||
# 手动设置时区（docker-compose.yml）
|
||
environment:
|
||
- TZ=Asia/Shanghai
|
||
```
|
||
|
||
## 总结
|
||
|
||
Docker 部署通过 Docker Compose 一键启动应用、MySQL、Redis 三个服务。多阶段构建减小镜像体积，命名卷保证数据持久化。生产环境建议关闭调试模式、使用强密钥、配置 Nginx 反向代理、限制端口暴露、配置日志轮转。
|