Docker Compose 一键部署前后端分离项目

网罗开发 （小红书、快手、视频号同名）

大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验 。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员

👋 大家好，我是展菲！

📱 全网搜索"展菲"，即可纵览我在各大平台的知识足迹。

📣 公众号"Swift社区"，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。

💬 微信端添加好友"fzhanfei"，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。

📅 最新动态：2025 年 3 月 17 日

快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

• • 前言
  • 项目结构建议
  • [docker-compose.yml 核心示例](#docker-compose.yml 核心示例)
  • [Nginx 配置要点](#Nginx 配置要点)
  • [环境变量与 .env](#环境变量与 .env)
  • 一键启动与常用命令
  • 前端构建方式选择
  • 总结

前言

前后端分离项目（如 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 部署，便于迁移与复现环境。