如何在 Docker Compose 中实现 Elasticsearch 健康检查

1. 概述

在使用 Docker Compose 构建服务栈时，确保服务按顺序可靠启动是关键。尤其是在使用包含 Elasticsearch 的技术栈时，比如同时使用 Kibana、Logstash、Metricbeat 等依赖服务时，如果健康检查配置不当，Docker 可能会误判 Elasticsearch 容器状态，从而影响其他服务的正常启动。

本文将探讨为什么 Elasticsearch 在 Docker Compose 中的健康检查容易失败，并提供一个可靠、实用的解决方案，帮助你在服务启动时确保 Elasticsearch 真正就绪。

2. Docker Compose 中的健康检查定义

Docker Compose 提供了 healthcheck 配置项，用于定义容器健康状态的判断方式。它会定期执行指定命令，并根据返回值判断容器是否健康：

✅ Healthy：容器正常运行
❌ Unhealthy：命令执行失败或超时

通过合理配置健康检查，我们可以确保依赖服务仅在目标服务健康时才启动。

3. Elasticsearch 健康检查的特点

Elasticsearch 在日志、监控、搜索平台中扮演核心角色，许多服务（如 Kibana、Logstash）都依赖其启动完成。

3.1 与普通健康检查的区别

通常的健康检查方式是验证服务是否监听端口，例如：

test: ["CMD", "curl", "-f", "http://localhost"]

但这种方式对 Elasticsearch 不适用。因为 Elasticsearch 在初始化过程中就会响应 HTTP 请求，此时集群状态可能仍为黄色（yellow），而 Docker 默认只看命令是否成功，不判断返回内容。

3.2 为什么需要更精确的健康检查？

Elasticsearch 响应 / 或 /cluster/health 接口时，可能返回如下状态：

状态	含义
green	所有主分片和副本分片都已分配（生产环境理想状态）
yellow	所有主分片已分配，但副本分片未分配（开发环境常见）
red	有主分片未分配（严重问题）

我们希望健康检查至少确保集群状态为 yellow，表示 Elasticsearch 已准备好接受查询。

可以手动测试如下命令：

$ curl http://localhost:9200/_cluster/health?pretty
{
  "cluster_name" : "docker-cluster",
  "status" : "green",
  ...
}

4. 示例项目配置

我们构建一个简单的 Docker Compose 项目，演示如何配置 Elasticsearch 的健康检查，并确保依赖服务在 Elasticsearch 就绪后再启动。

4.1 项目结构

$ tree elasticsearch-healthcheck-project
elasticsearch-healthcheck-project
└── docker-compose.yml

0 directories, 1 file

4.2 docker-compose.yml 配置

version: '3.7'

services:
  elasticsearch:
    image: elasticsearch:7.12.1
    container_name: elasticsearch
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=5s || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - 9200:9200
    networks:
      - elastic

  app:
    image: alpine
    container_name: dummy-app
    command: ["sh", "-c", "echo 'Elasticsearch is healthy and app is running'; sleep 3600"]
    depends_on:
      elasticsearch:
        condition: service_healthy
    networks:
      - elastic

networks:
  elastic:

4.3 配置详解

✅ elasticsearch 服务

使用官方镜像 elasticsearch:7.12.1
设置单节点模式、关闭安全功能、限制内存

environment:
  - discovery.type=single-node
  - xpack.security.enabled=false
  - ES_JAVA_OPTS=-Xms512m -Xmx512m

✅ 健康检查配置

healthcheck:
  test: ["CMD-SHELL", "curl -fs http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=5s || exit 1"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 20s

wait_for_status=yellow：等待集群状态至少为 yellow
interval：每 10 秒检查一次
timeout：每次检查等待 5 秒
retries：失败 5 次后标记为 unhealthy
start_period：启动后等待 20 秒再开始健康检查

✅ 依赖服务 app

使用 Alpine 镜像模拟业务服务
仅在 Elasticsearch 健康时启动

depends_on:
  elasticsearch:
    condition: service_healthy

5. 验证配置

启动服务：

$ docker compose up -d

检查 Elasticsearch 健康状态：

$ docker inspect --format='{{json .State.Health}}' elasticsearch | jq
{
  "Status": "healthy",
  ...
}

手动访问集群状态：

$ curl http://localhost:9200/_cluster/health?pretty
{
  "cluster_name" : "docker-cluster",
  "status" : "yellow"
}

查看 dummy-app 日志：

$ docker logs dummy-app
Elasticsearch is healthy and app is running

输出确认服务已按预期顺序启动。

6. 小结

在 Docker Compose 中为 Elasticsearch 配置健康检查时，不能只依赖端口监听，而应深入检查其集群状态。

通过使用 /_cluster/health?wait_for_status=yellow 接口，我们可以确保依赖服务在 Elasticsearch 真正就绪后再启动，从而：

✅ 提高系统可靠性
✅ 减少因启动顺序不当导致的错误
✅ 提升服务初始化的可预测性

这是一个简单但非常实用的实践，特别适用于需要多服务协同工作的场景。

Persistence

REST

Security