Docker Compose 健康检查:同时覆盖前后端服务的实践
Docker Compose 健康检查:同时覆盖前后端服务的实践
在前后端分离项目中,healthcheck 只检查后端接口很容易造成误判:后端接口正常,但前端页面已经不可用,容器却仍然显示 healthy。本文以 EduSwarm 智慧课堂工作台的 docker-compose.yml 为例,说明如何把前端服务也纳入健康检查,并给出可复用的配置与验证方法。
问题背景
很多 Compose 项目会先给后端服务增加健康检查,例如只请求 /api/edu/health。这个检查能确认后端进程和数据库连接是否正常,却不能证明用户真的能打开前端页面。
如果前端容器启动失败、构建产物缺失或 5173 端口没有监听,后端仍然可能返回 200。此时 docker compose ps 显示服务 healthy,但用户访问页面会失败,排障时容易把问题归因到浏览器或网络。
为什么只检查后端不够
健康检查应该回答一个更贴近用户的问题:这个服务现在能不能被正常访问?
对于前后端分离架构,至少有两个独立风险点:
- 后端 API 进程是否存活,依赖是否可用;
- 前端静态页面或开发服务器是否能够返回 HTTP 响应。
只覆盖其中一项,就无法完整反映部署状态。
方案一:前后端分别增加 healthcheck
下面是一个简化的 Compose 配置示例。实际端口和健康接口请按项目调整:
services:
backend:
image: example/edu-swarm-backend:latest
ports:
- "19200:19200"
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:19200/api/edu/health || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
frontend:
image: example/edu-swarm-frontend:latest
ports:
- "5173:5173"
depends_on:
backend:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://localhost:5173/ >/dev/null || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
如果镜像中没有 curl,可以使用 wget;如果前端使用 Nginx,则把 5173 换成实际监听端口,例如 80。健康检查命令应尽量轻量,避免每次探测都触发复杂业务逻辑。
方案二:使用统一探针
当服务较多时,可以增加一个轻量探针容器,统一检查多个地址:
services:
health-probe:
image: curlimages/curl:latest
command:
- sh
- -c
- |
curl -fsS http://backend:19200/api/edu/health &&
curl -fsS http://frontend:5173/ >/dev/null
depends_on:
- backend
- frontend
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://backend:19200/api/edu/health && curl -fsS http://frontend:5173/ >/dev/null"]
interval: 30s
timeout: 10s
retries: 3
这种方式适合需要同时验证多个依赖的场景,但会增加一个容器,建议只在确有统一健康状态需求时使用。
验证方法
修改配置后,先做静态检查:
docker compose config
再启动并观察状态:
docker compose up -d
docker compose ps
需要查看详细健康日志时,可以执行:
docker inspect --format '{{json .State.Health}}' <container_name>
建议分别模拟两种故障:
- 停止前端进程,确认前端容器变为 unhealthy;
- 停止后端进程,确认后端容器变为 unhealthy。
只有两种故障都能被状态反映出来,健康检查才算真正覆盖完整服务链路。
注意事项
- start_period 要给足应用启动时间,避免首次启动被误判;
- interval 和 timeout 不宜过短,防止健康检查本身造成额外负载;
- 健康检查只代表基础可用性,不能替代业务监控和日志告警;
- 生产环境应结合反向代理、证书、静态资源和关键业务接口做综合探测。
结论
Docker Compose 的 healthcheck 不应只看后端接口。把前端端口和关键依赖一起纳入探测,才能让 docker compose ps 更准确地反映用户可访问状态,减少“显示 healthy 但页面打不开”的排障成本。
对于前后端分离项目,最实用的起点是分别给前后端增加轻量 healthcheck;当服务数量增加后,再考虑统一探针方案。
- 点赞
- 收藏
- 关注作者
评论(0)