Docker健康检查完全指南：原理、配置与生产环境最佳实践（2026最新）

1
健康检查通过 → Docker标记为healthy → 继续提供服务
2
              ↓
3
健康检查失败 → Docker标记为unhealthy → 触发自动重启/告警

1
healthcheck:
2
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
3
  interval: 30s
4
  timeout: 10s
5
  retries: 3

1
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
2
  CMD curl -f http://localhost:3000/health || exit 1

1
healthcheck:
2
  test: ["HTTP", "GET", "http://localhost:3000/health"]
3
  interval: 30s
4
  timeout: 10s
5
  retries: 3

1
healthcheck:
2
  test: ["TCP", "localhost", "3306"]
3
  interval: 30s
4
  timeout: 10s
5
  retries: 3

1
interval > timeout > 单次检查耗时

1
# 快速启动服务（Nginx）
2
healthcheck:
3
  test: ["HTTP", "GET", "http://localhost/health"]
4
  interval: 15s
5
  timeout: 5s
6
  retries: 3
7
  start_period: 5s
8

9
# 慢启动服务（MySQL）
10
healthcheck:
11
  test: ["TCP", "localhost", "3306"]
12
  interval: 30s
13
  timeout: 10s
14
  retries: 5
15
  start_period: 30s
16

17
# 关键核心服务（API网关）
18
healthcheck:
19
  test: ["CMD", "./health-check.sh"]
20
  interval: 60s
21
  timeout: 30s
22
  retries: 3
23
  start_period: 60s

1
healthcheck:
2
  disable: true

1
services:
2
  nginx:
3
    image: nginx:alpine
4
    healthcheck:
5
      test: ["CMD-SHELL", "curl -f http://localhost/health || exit 1"]
6
      interval: 15s
7
      timeout: 5s
8
      retries: 3
9
      start_period: 5s

1
location /health {
2
  access_log off;
3
  return 200 "healthy\n";
4
}

1
services:
2
  mysql:
3
    image: mysql:8.0
4
    environment:
5
      MYSQL_ROOT_PASSWORD: password
6
    healthcheck:
7
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
8
      interval: 30s
9
      timeout: 10s
10
      retries: 5
11
      start_period: 30s

1
healthcheck:
2
  test: ["CMD", "mysql", "-u", "root", "-ppassword", "-e", "SELECT 1"]

1
services:
2
  redis:
3
    image: redis:alpine
4
    healthcheck:
5
      test: ["CMD", "redis-cli", "ping"]
6
      interval: 10s
7
      timeout: 3s
8
      retries: 3
9
      start_period: 5s

1
services:
2
  api:
3
    build: .
4
    healthcheck:
5
      test: ["HTTP", "GET", "http://localhost:3000/api/health"]
6
      interval: 20s
7
      timeout: 5s
8
      retries: 3
9
      start_period: 15s

1
app.get('/api/health', (req, res) => {
2
  res.status(200).json({ status: 'healthy', timestamp: Date.now() });
3
});

1
services:
2
  mongo:
3
    image: mongo:latest
4
    healthcheck:
5
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
6
      interval: 30s
7
      timeout: 10s
8
      retries: 5
9
      start_period: 30s

1
services:
2
  postgres:
3
    image: postgres:15
4
    environment:
5
      POSTGRES_PASSWORD: password
6
    healthcheck:
7
      test: ["CMD", "pg_isready", "-U", "postgres"]
8
      interval: 30s
9
      timeout: 10s
10
      retries: 5
11
      start_period: 30s

1
services:
2
  rabbitmq:
3
    image: rabbitmq:management
4
    healthcheck:
5
      test: ["CMD", "rabbitmq-diagnostics", "check_port_connectivity"]
6
      interval: 30s
7
      timeout: 10s
8
      retries: 3
9
      start_period: 15s

1
services:
2
  nginx:
3
    image: nginx:alpine
4
    healthcheck:
5
      test: ["CMD-SHELL", "curl -f http://localhost/health || exit 1"]
6
      interval: 15s
7
      timeout: 5s
8
      retries: 3
9
      start_period: 5s
10

11
  api:
12
    build: ./api
13
    depends_on:
14
      db:
15
        condition: service_healthy
16
      redis:
17
        condition: service_healthy
18
    healthcheck:
19
      test: ["HTTP", "GET", "http://localhost:3000/health"]
20
      interval: 20s
21
      timeout: 5s
22
      retries: 3
23
      start_period: 15s
24

25
  db:
26
    image: mysql:8.0
27
    environment:
28
      MYSQL_ROOT_PASSWORD: password
29
    healthcheck:
30
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
31
      interval: 30s
32
      timeout: 10s
33
      retries: 5
34
      start_period: 30s
35

36
  redis:
37
    image: redis:alpine
38
    healthcheck:
39
      test: ["CMD", "redis-cli", "ping"]
40
      interval: 10s
41
      timeout: 3s
42
      retries: 3
43
      start_period: 5s

1
healthcheck:
2
  test: ["CMD-SHELL", "./health-check.sh"]
3
  interval: 10s
4
  timeout: 5s
5
  retries: 12
6
  start_period: 10s

1
#!/bin/bash
2

3
# 阶段1：端口检查（快速）
4
if ! nc -z localhost 3000; then
5
  echo "Port not ready"
6
  exit 1
7
fi
8

9
# 阶段2：API检查（中等）
10
if ! curl -f http://localhost:3000/health; then
11
  echo "API not ready"
12
  exit 1
13
fi
14

15
# 阶段3：业务检查（全面）
16
if ! curl -f http://localhost:3000/api/ready; then
17
  echo "Service not fully ready"
18
  exit 1
19
fi
20

21
echo "Healthy"
22
exit 0

1
services:
2
  app:
3
    build: .
4
    depends_on:
5
      db:
6
        condition: service_healthy
7
      redis:
8
        condition: service_healthy
9
      rabbitmq:
10
        condition: service_healthy

1
services:
2
  api:
3
    build: .
4
    restart: always          # 总是重启
5
    restart: on-failure      # 仅失败时重启
6
    restart: unless-stopped  # 除非手动停止
7
    restart: no              # 不自动重启（默认）

1
services:
2
  api:
3
    build: .
4
    restart: on-failure:5    # 最多重启5次
5
    healthcheck:
6
      test: ["HTTP", "GET", "http://localhost:3000/health"]
7
      interval: 30s
8
      timeout: 10s
9
      retries: 3

1
容器启动 → start_period等待 → 开始健康检查
2
    ↓
3
检查失败 → retries计数 +1 → 继续检查
4
    ↓
5
retries达到阈值 → 标记为unhealthy
6
    ↓
7
restart策略触发 → 自动重启容器
8
    ↓
9
重启后重新开始检查流程

1
services:
2
  cadvisor:
3
    image: gcr.io/cadvisor/cadvisor:latest
4
    ports:
5
      - "8080:8080"
6
    volumes:
7
      - "/:/rootfs:ro"
8
      - "/var/run:/var/run:rw"
9
      - "/sys:/sys:ro"
10
      - "/var/lib/docker:/var/lib/docker:ro"

1
# 不健康容器数量
2
count(container_last_health_status{status="unhealthy"})
3

4
# 容器重启次数
5
container_restart_count
6

7
# 健康检查失败率
8
rate(container_health_checks_failed_total[5m])

1
groups:
2
- name: docker-health
3
  rules:
4
  - alert: ContainerUnhealthy
5
    expr: container_last_health_status == "unhealthy"
6
    for: 5m
7
    labels:
8
      severity: critical
9
    annotations:
10
      summary: "容器 {{ $labels.name }} 不健康"
11
      description: "容器 {{ $labels.name }} 已持续不健康5分钟"
12

13
  - alert: ContainerRestarting
14
    expr: rate(container_restart_count[10m]) > 3
15
    labels:
16
      severity: warning
17
    annotations:
18
      summary: "容器 {{ $labels.name }} 重启频繁"
19
      description: "容器 {{ $labels.name }} 10分钟内重启超过3次"

1
□ 为每个关键服务配置健康检查
2
□ 选择合适的检查方式（HTTP/TCP/CMD）
3
□ 合理设置interval/timeout/retries/start_period
4
□ 使用depends_on + service_healthy控制启动顺序
5
□ 配置restart策略实现自动恢复
6
□ 集成监控系统（Prometheus/Grafana）
7
□ 设置告警规则
8
□ 在Dockerfile和docker-compose中保持配置一致
9
□ 定期测试健康检查失效场景
10
□ 记录健康检查历史数据用于分析

1
healthcheck:
2
  test: ["HTTP", "GET", "http://localhost:3000/health"]
3
  interval: 30s
4
  timeout: 10s
5
  retries: 3
6
  start_period: 60s  # 延长启动等待时间

1
depends_on:
2
  db:
3
    condition: service_healthy  # 等待健康而非启动