awesome-compose 实战:React + Spring Boot + MySQL 全栈应用的 Docker Compose 部署指南

原创2026-09-29 18:36:022,234 阅读
文章标签:示例工程容器编排教程

awesome-compose 实战:React + Spring Boot + MySQL 全栈应用的 Docker Compose 部署指南

导读

本文以 awesome-compose 仓库中的 react-java-mysql 示例 为蓝本,系统讲解如何用 Docker Compose 一键编排一个由 React 前端、Spring Boot 后端与 MySQL/MariaDB 数据库组成的全栈应用。读完本文,你将掌握三服务 compose 文件的结构与关键配置(端口映射、健康检查、Docker Secrets、数据卷与自定义网络),理解多阶段构建在生产环境镜像中的作用,并能够独立完成从 docker compose up 到验证、清理的完整部署闭环。

react-java-mysql 示例应用运行页面

一、应用架构与三服务拓扑

该示例的核心是一条清晰的请求链路:

  • frontend(React 前端):负责渲染页面,通过开发服务器将 /api 请求代理到后端;
  • backend(Spring Boot 后端):提供 REST 接口,从数据库读取问候语数据并返回给前端;
  • db(MySQL/MariaDB 数据库):持久化存储业务数据。

Compose 文件在 services 下定义了这三个服务,并通过两张自定义网络将三者按需互联:

  • react-spring 网络:连接 frontend 与 backend,承载前后端之间的 HTTP 流量;
  • spring-mysql 网络:连接 backend 与 db,承载后端到数据库的 JDBC 流量。

frontend 与 backend 之间、backend 与 db 之间均通过服务名(Compose 网络内的 DNS 别名)互相访问,例如前端代理目标为 http://backend:8080(见 frontend/src/setupProxy.js),后端访问数据库的主机名为 MYSQL_HOST: db(见 compose.yaml)。

二、项目结构总览

仓库中该示例的目录组织如下(与 react-java-mysql/README.md 中给出的结构一致):

.
├── backend
│   ├── Dockerfile          # Spring Boot 后端多阶段构建
│   ├── pom.xml             # Maven 工程定义
│   └── src/main/java/...   # Spring Boot 源码
├── db
│   └── password.txt        # 数据库密码(由 Docker Secrets 注入)
├── frontend
│   ├── Dockerfile          # React 前端多阶段构建
│   ├── package.json
│   └── src/...             # React + TypeScript 源码
├── compose.yaml            # 三服务编排文件
└── README.md

三个服务的 Dockerfile 分别位于 backend/Dockerfile 与 frontend/Dockerfile,数据库密码通过 db/password.txt 文件提供。

三、compose.yaml 深度解析

示例核心编排文件位于 compose.yaml,下面按服务逐项拆解关键配置。

1. db 服务:数据库的持久化与健康检查

db:
  # We use a mariadb image which supports both amd64 & arm64 architecture
  image: mariadb:10.6.4-focal
  # If you really want to use MySQL, uncomment the following line
  #image: mysql:8.0.19
  environment:
    - MYSQL_DATABASE=example
    - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db-password
  restart: always
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
    interval: 3s
    retries: 5
    start_period: 30s
  secrets:
    - db-password
  volumes:
    - db-data:/var/lib/mysql
  networks:
    - spring-mysql

要点说明:

  • 镜像选择:默认使用 mariadb:10.6.4-focal,官方说明其同时支持 amd64 与 arm64 两种 CPU 架构(详见 react-java-mysql/README.md)。若业务必须使用 MySQL,可取消注释 #image: mysql:8.0.19(README 示例文本中为 mysql:8.0.27,请以仓库当前 compose.yaml 实际内容为准)。
  • 密码注入:数据库初始化时会读取 /run/secrets/db-password 文件内容作为 root 密码,这正是 Docker Secrets 的典型用法——避免把明文密码写死在镜像或环境变量中。
  • 健康检查:通过 mysqladmin ping 探测数据库就绪状态,interval: 3s 表示每 3 秒检查一次,retries: 5 表示最多重试 5 次,start_period: 30s 为容器启动预留的宽限期。
  • 数据持久化:命名卷 db-data 挂载到容器内 /var/lib/mysql,保证容器重建后数据不丢失。

2. backend 服务:依赖数据库就绪后再启动

backend:
  build: backend
  restart: always
  secrets:
    - db-password
  environment:
    MYSQL_HOST: db
  networks:
    - react-spring
    - spring-mysql
  depends_on:
    db:
      condition: service_healthy

depends_on 与 db 服务的 healthcheck 配合,实现了严格的启动顺序控制:只有当 db 服务的健康检查通过(condition: service_healthy)后,backend 容器才会被创建启动,从根源上避免“数据库尚未就绪、后端连接失败”的经典竞态问题。

3. frontend 服务:开发模式与端口暴露

frontend:
  build:
    context: frontend
    target: development
  ports:
    - 3000:3000
  volumes:
    - ./frontend/src:/code/src
    - /project/node_modules
  networks:
    - react-spring
  depends_on:
    - backend
  expose:
    - 3306
    - 33060
  • ports: 3000:3000 将容器内 React 开发服务器的 3000 端口映射到宿主机 3000 端口,部署完成后浏览器访问 http://localhost:3000 即可看到页面。
  • build.target: development 指明构建 frontend/Dockerfile 中的 development 阶段;./frontend/src:/code/src 与匿名卷 /project/node_modules 组合,实现了源码热更新同时避免宿主目录覆盖容器内已安装的依赖。
  • 需要注意:启动前请确认宿主机 3000 端口未被占用,否则端口映射会冲突。

4. 全局段:卷、密钥与网络

volumes:
  db-data: {}
secrets:
  db-password:
    file: db/password.txt
networks:
  react-spring: {}
  spring-mysql: {}
  • secrets.db-password.file 指定密码来源文件 db/password.txt,Compose 会将其以只读方式挂载到各服务的 /run/secrets/db-password 路径下;
  • 两张自定义网络 react-spring 与 spring-mysql 均采用默认 bridge 驱动。

四、MariaDB 还是 MySQL:架构兼容性说明

示例选择 MariaDB 作为默认数据库,README 中的官方说明明确指出:出于 AMD64 与 ARM64 架构的兼容性考虑,使用 MariaDB 镜像替代 MySQL。这与在 Apple Silicon(arm64)等设备上运行 mysql 官方镜像可能遇到的兼容问题直接相关。

若你的部署环境明确需要 MySQL,只需取消 compose.yaml 中 db 服务的 #image: mysql:8.0.19 注释即可完成切换。后端代码通过 JPA 标准访问数据库(详见下文源码分析),对底层具体是 MariaDB 还是 MySQL 不敏感,因此两种方案均可无缝运行。

五、Spring Boot 后端:多阶段构建与源码实现

1. Dockerfile 多阶段构建

backend/Dockerfile 采用标准的多阶段构建,将“编译环境”与“运行环境”分离:

FROM --platform=$BUILDPLATFORM maven:3.8.5-eclipse-temurin-17 AS builder
WORKDIR /workdir/server
COPY pom.xml /workdir/server/pom.xml
RUN mvn dependency:go-offline
COPY src /workdir/server/src
RUN mvn install
  • 第一阶段 builder:先只拷贝 pom.xml 并执行 mvn dependency:go-offline 预下载依赖,充分利用 Docker 层缓存,源码变更时无需重新下载依赖;
  • prepare-production 阶段:将打出的 jar 解包到 target/dependency,为后续分层拷贝做准备;
  • 最终运行阶段:基于 eclipse-temurin:17-jre-focal(仅含 JRE,体积远小于完整 JDK),只拷贝 BOOT-INF/lib、META-INF 与 BOOT-INF/classes,通过 java -cp app:app/lib/* com.company.project.Application 启动应用,并 EXPOSE 8080。

此外镜像还内置了 dev-envs 阶段(创建 vscode 用户并注入 Docker CLI 工具),供容器内开发调试使用,生产部署不依赖该阶段。

2. 源码调用链

后端核心代码体现了典型的 Spring Boot + Spring Data JPA 分层:

  • Application.java:@SpringBootApplication + @ComponentScan(basePackages = {"com.company.project"}),作为应用启动入口;
  • HomeController.java:@RestController 暴露 GET / 接口,调用 repository.findById(1) 从数据库读取 id 为 1 的问候语,未命中时返回 new Greeting("Not Found 😕");
  • GreetingRepository.java:继承 CrudRepository<Greeting, Integer>,由 Spring Data 自动生成 CRUD 实现;
  • Greeting.java:@Entity + @Table(name = "greetings") 映射数据库表,id 为主键并自动生成,name 字段非空。

3. Docker Secrets 读取机制

一个值得关注的实现细节是 DockerSecretsProcessor.java。它实现了 Spring Boot 的 EnvironmentPostProcessor 接口,在环境初始化阶段检查 /run/secrets/db-password 文件是否存在;若存在且尚未设置 MYSQL_PASSWORD 系统属性,则读取该文件内容并写入系统属性:

Resource resource = new FileSystemResource("/run/secrets/db-password");
if (resource.exists() && System.getProperty("MYSQL_PASSWORD") == null) {
    String dbPassword = StreamUtils.copyToString(resource.getInputStream(), Charset.defaultCharset());
    System.setProperty("MYSQL_PASSWORD", dbPassword);
}

这就把 Compose 的 secrets 挂载路径与后端运行时配置打通:数据库密码只需维护在 db/password.txt 一处,既不用硬编码进代码,也不必写进镜像环境变量。

六、React 前端:开发镜像、代理与页面渲染

1. Dockerfile 多阶段构建

frontend/Dockerfile 同样采用多阶段:

  • development 阶段:基于 node:lts,先 npm ci 按锁文件精确安装依赖,再设置 CI=true、PORT=3000,以 npm start 启动 React 开发服务器(本示例 compose 默认使用该阶段以支持热更新);
  • build 阶段:执行 npm run build 产出静态资源;
  • 最终阶段:基于 nginx:1.13-alpine,将构建产物 build/ 拷贝到 Nginx 站点目录 /usr/share/nginx/html。若需要生产级部署,可将 compose 中 build.target 切换为最终阶段并结合 Nginx 提供静态服务。

2. 前后端代理打通

开发模式下,React 应用通过 setupProxy.js 将 /api 前缀的请求代理到后端服务:

app.use(
  "/api",
  createProxyMiddleware({
    target: "http://backend:8080",
    pathRewrite: { "^/api": "" }
  })
);

页面组件 App.tsx 中通过 fetch("/api") 请求后端,代理将其转发到 http://backend:8080/ 并将 /api 前缀剥离。后端 HomeController 返回的 Greeting JSON({ "id": ..., "name": ... })被前端解析后渲染为 Hello from {greeting.name} 的消息。最终浏览器看到的效果即本文开头截图所示:页面展示从 MySQL 数据库读取出的问候语。

七、部署与验证

1. 启动应用

在示例目录(react-java-mysql/)执行:

$ docker compose up -d

首次执行会构建 backend 与 frontend 镜像(输出中会看到 Building backend、Successfully tagged react-java-mysql_frontend:latest 等日志),随后依次创建 react-java-mysql-frontend-1、react-java-mysql-db-1、react-java-mysql-backend-1 三个容器。若镜像已存在但需强制重建,可改用 docker compose up --build。

2. 验证容器状态

用 docker ps 查看运行结果,应看到三个容器全部 Up,且 frontend 容器端口映射为 0.0.0.0:3000->3000/tcp(与 README 中给出的期望输出一致):

ONTAINER ID  IMAGE                      COMMAND                 STATUS          PORTS                   NAMES
a63dee74d79e react-java-mysql-backend   "java -Djava.securit…"  Up 37 seconds                            react-java-mysql_backend-1
6a7364c0812e react-java-mysql-frontend  "docker-entrypoint.s…"  Up 33 seconds   0.0.0.0:3000->3000/tcp  react-java-mysql_frontend-1
b176b18fbec4 mysql:8.0.19               "docker-entrypoint.s…"  Up 37 seconds   3306/tcp, 33060/tcp     react-java-mysql_db-1

3. 访问应用

待容器全部就绪后,在浏览器打开 http://localhost:3000,即可看到 React 页面显示从数据库读取的彩色欢迎消息。

八、停止与清理

部署完成后,可用以下命令停止并移除全部容器与默认网络:

$ docker compose down

执行后三个容器(backend、frontend、db)与 react-java-mysql-default 网络将被移除。由于数据库数据存放在命名卷 db-data 中,docker compose down 默认不会删除卷,业务数据得以保留;如需连同数据卷一并彻底清理,可显式追加 -v 参数(docker compose down -v),操作前请确认无需保留数据库数据。

九、小结

通过本示例可以完整掌握 Docker Compose 编排全栈应用的核心技能:

  • 三服务编排:frontend、backend、db 各自独立构建、独立扩展,通过自定义网络按需互联;
  • 启动顺序控制:depends_on + service_healthy 确保数据库就绪后后端才启动;
  • 敏感信息管理:Compose secrets 配合 Spring Boot 的 EnvironmentPostProcessor,实现密码的安全注入;
  • 镜像瘦身:多阶段构建将 Maven/Node 编译环境与 JRE/Nginx 运行环境分离,兼顾构建效率与运行镜像体积。

如需进一步研究本示例的完整源码与配置,可继续查阅仓库中的 react-java-mysql/compose.yaml、backend 源码、frontend 源码 以及 react-java-mysql/README.md。

登录后查看全文
awesome-compose