07_dockerfile/7.12_healthcheck.md
HEALTHCHECK [选项] CMD <命令>
HEALTHCHECK NONE
HEALTHCHECK 指令告诉 Docker 如何判断容器状态是否正常。这是保障服务高可用的重要机制。
在没有 HEALTHCHECK 之前，Docker 只能通过 进程退出码 来判断容器状态。问题场景：
引入 HEALTHCHECK 后： Docker 定期执行指定的检查命令，根据返回值判断容器是否 “健康”。
容器状态转换：
Starting ──成功──> Healthy ──失败N次──> Unhealthy
▲ │
└──────成功──────┘
# 注：nginx 镜像推荐使用具体的版本标签（如 nginx:1.30-alpine）
FROM nginx
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
CMD curl -fs http://localhost/ || exit 1
0：成功 (healthy)1：失败 (unhealthy)2：保留值 (不使用)| 选项 | 说明 | 默认值 |
|---|---|---|
--interval | 两次检查的间隔 | 30s |
--timeout | 检查命令的超时时间 | 30s |
--start-period | 启动缓冲期 (期间失败不计入次数) | 0s |
--retries | 连续失败多少次标记为 unhealthy | 3 |
如果基础镜像定义了 HEALTHCHECK，但你不想使用它：
FROM my-base-image
HEALTHCHECK NONE
使用 curl 或 wget：
## 使用 curl
HEALTHCHECK CMD curl -f http://localhost/ || exit 1
## 使用 wget（Alpine 默认包含）
HEALTHCHECK CMD wget -q --spider http://localhost/ || exit 1
## MySQL
HEALTHCHECK CMD mysqladmin ping -h localhost || exit 1
## Redis
HEALTHCHECK CMD redis-cli ping || exit 1
COPY healthcheck.sh /usr/local/bin/
HEALTHCHECK CMD ["healthcheck.sh"]
可以在 compose.yaml (或 docker-compose.yml) 中覆盖或定义健康检查：
services:
web:
image: nginx
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 40s
带健康检查的依赖启动：
services:
web:
depends_on:
db:
condition: service_healthy # 等待 db 变健康才启动 web
db:
image: mysql
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
## 查看容器状态（包含健康信息）
$ docker ps
CONTAINER ID STATUS
abc123 Up 1 minute (healthy)
def456 Up 2 minutes (unhealthy)
## 查看详细健康日志
$ docker inspect --format '{{json .State.Health}}' mycontainer | jq
{
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "...",
"End": "...",
"ExitCode": 0,
"Output": "..."
}
]
}
健康检查会被频繁执行，不要在检查脚本中进行写操作或消耗大量资源的操作。
优先使用镜像中已有的工具 (如 wget)，避免为了健康检查安装庞大的依赖 (如 curl)。
应用启动可能需要时间 (如 Java 应用)。设置 --start-period 可以防止在启动阶段因检查失败而误判。
## 给应用 1 分钟启动时间
HEALTHCHECK --start-period=60s CMD curl -f http://localhost/ || exit 1
健康检查应主要关注 当前服务 是否可用，而不是检查其下游依赖 (数据库等)。下游依赖的检查应由应用逻辑处理。
不同平台对 HEALTHCHECK 的支持有所不同：
compose.yaml 中覆盖livenessProbe 和 readinessProbe 机制如果应用同时部署在 Docker Compose 和 Kubernetes 环境中，建议在 Dockerfile 中保留 HEALTHCHECK（供 Compose 使用），同时在 Kubernetes 的 Pod 配置中定义对应的探针。