Docker Compose实现一键部署前后端分离项目的完整指南

前言

前后端分离项目（如 React + Python FastAPI）在生产环境往往还依赖 Nginx、MySQL 等，若逐个起容器、配网络和卷，容易出错且难复现。用 Docker Compose 把前端、后端、Nginx、数据库写进一个 docker-compose.yml，一条命令即可拉起整套环境，便于本机联调与服务器部署。

本文只讲 Compose 的编排思路和关键配置，不贴完整可运行 Demo。

项目结构建议

app/
├── docker-compose.yml
├── nginx/
│   └── default.conf
├── frontend/
│   ├── Dockerfile
│   └── build/          # 或由 CI 构建后放入
├── backend/
│   ├── Dockerfile
│   └── main.py
└── mysql/
    └── .gitkeep        # 占位，数据卷挂载用

• Nginx 只做反向代理和静态资源，配置放在 nginx/default.conf。
• 前端可以「先本地/CI 构建再 COPY 进镜像」，也可以「在镜像里 npm build」；后者镜像更大、构建更慢，适合快速验证。
• 后端镜像内只放代码和依赖，数据库等通过环境变量注入。
• MySQL 数据持久化到宿主机目录或命名卷，避免容器删除后丢数据。

docker-compose.yml 核心示例

version: "3.9"

services:
  nginx:
    image: nginx:stable
    ports:
      - "80:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./frontend/build:/usr/share/nginx/html:ro
    depends_on:
      - backend

  backend:
    build: ./backend
    environment:
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_USER=app
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=appdb
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: appdb
      MYSQL_USER: app
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  mysql_data:

要点：

• nginx：挂载自定义配置和前端静态目录；depends_on: backend 保证启动顺序，但不保证后端已就绪，若需要可给 backend 做 healthcheck 再依赖。
• backend：build: ./backend 使用 backend 目录下的 Dockerfile 构建；环境变量里 DB_HOST 写服务名 mysql，Compose 会解析为 MySQL 容器 IP；depends_on.mysql.condition: service_healthy 表示等 MySQL 健康后再起 backend，避免启动时连不上库。
• mysql：用 healthcheck 让 Compose 判断「已就绪」；敏感信息用 ${DB_PASSWORD} 等从 .env 或环境传入，不要写死在 yml 里。
• volumes：mysql_data 命名卷由 Docker 管理，数据持久化；也可改为 ./mysql:/var/lib/mysql 绑定宿主机目录。

Nginx 配置要点

nginx/default.conf 中需包含：静态资源 root、SPA 的 try_files、以及 /api 反向代理到 backend 服务名：

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;
    location / {
        try_files $uri $uri/ /index.html;
    }
    location /api {
        proxy_pass http://backend:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

这里 proxy_pass http://backend:8000 中的 backend 是 Compose 里后端服务的名字，端口为容器内端口（如 8000）。若后端以 /api 为前缀，保持 location /api 与后端一致；若后端根路径是 /，可写 location /api/ { proxy_pass http://backend:8000/; } 做路径剥离。

环境变量与 .env

在项目根目录建 .env（不要提交到 Git），例如：

DB_PASSWORD=your_app_db_password
MYSQL_ROOT_PASSWORD=your_root_password

在 docker-compose.yml 里用 ${DB_PASSWORD} 引用，Compose 会自动读取 .env。生产环境也可在宿主机设置环境变量或使用 CI 注入。

一键启动与常用命令

# 构建并后台启动
docker compose up -d --build

# 查看日志
docker compose logs -f backend

# 停止并删除容器（卷保留）
docker compose down

# 停止并删除容器与命名卷
docker compose down -v

首次部署或依赖变更后建议 docker compose up -d --build，平时只改代码可只重建后端：docker compose up -d --build backend。

前端构建方式选择

方式一：宿主机/CI 先构建，Compose 只挂载 build 目录

• 宿主机执行 cd frontend && npm run build，docker-compose.yml 中 nginx 挂载 ./frontend/build。
• 优点：镜像小、构建快；缺点：需保证宿主机有 Node 环境且 build 目录存在。

方式二：前端也做成镜像，在镜像内 npm build

• frontend/Dockerfile 多阶段：先 node 镜像 npm install && npm run build，再 nginx 镜像只 COPY build 结果。
• Compose 中 nginx 改用该前端镜像，或仍用 nginx 镜像但静态资源从「前端镜像」的某路径挂载（需多一步 volume from）。
• 更常见的做法是：前端镜像产出静态文件，Compose 里 nginx 的 build 阶段 COPY 前端构建产物，或使用多服务配合 volume。简单起见，很多项目采用方式一 + 仅 backend 和 mysql 用 Compose 构建。

按团队习惯选择即可：要「一条命令包含前端构建」就做前端镜像；要「前端单独 CI 构建、Compose 只负责运行」就挂载 build 目录。

总结

• Compose 把 nginx、backend、mysql 放同一网络，nginx 反向代理到 backend，静态资源挂载或从前端镜像提供，mysql 用健康检查 + depends_on 保证启动顺序。
• 敏感信息用 .env 或环境变量，数据持久化用命名卷或绑定目录。
• 一键启动用 docker compose up -d --build，日常排错用 logs、down。

这样即可实现前后端分离项目的一站式 Docker 部署，便于迁移与复现环境。

到此这篇关于Docker Compose实现一键部署前后端分离项目的完整指南的文章就介绍到这了,更多相关Docker Compose部署项目内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！