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

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

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

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

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

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

• • 前言
  • 项目结构建议
  • docker-compose.yml 核心示例
  • Nginx 配置要点
  • 环境变量与 .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:stableports:-"80:80"volumes:-./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro-./frontend/build:/usr/share/nginx/html:rodepends_on:-backendbackend:build:./backendenvironment:-DB_HOST=mysql-DB_PORT=3306-DB_USER=app-DB_PASSWORD=${DB_PASSWORD}-DB_NAME=appdbdepends_on:mysql:condition:service_healthymysql:image:mysql:8environment:MYSQL_ROOT_PASSWORD:${MYSQL_ROOT_PASSWORD}MYSQL_DATABASE:appdbMYSQL_USER:appMYSQL_PASSWORD:${DB_PASSWORD}volumes:-mysql_data:/var/lib/mysqlhealthcheck:test:["CMD","mysqladmin","ping","-h","localhost"]interval:10stimeout:5sretries:5volumes: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 注入。

一键启动与常用命令

# 构建并后台启动dockercompose up -d --build# 查看日志dockercompose logs -f backend# 停止并删除容器（卷保留）dockercompose down# 停止并删除容器与命名卷dockercompose 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 部署，便于迁移与复现环境。