awesome-compose 实战:React + Spring Boot + MySQL 全栈应用的 Docker Compose 部署指南
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 到验证、清理的完整部署闭环。
一、应用架构与三服务拓扑
该示例的核心是一条清晰的请求链路:
- 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。
