healthcheck 指令用于定义容器健康检测机制，通过定期执行命令并依据返回码（0=healthy，1=unhealthy）判断状态，支持编排工具自动恢复；语法为 healthcheck [options] cmd command，含 --interval、--timeout、--start-period、--retries 等参数；需确保命令轻量、环境兼容且依赖已安装。

dockerfile 中的 healthcheck 指令用于定义容器启动后如何主动检测其内部服务是否正常运行，它让 docker 能定期执行命令并根据返回值判断容器“健康”状态，从而支持编排工具（如 swarm、kubernetes）做出自动恢复决策。

HEALTHCHECK 基本语法与参数含义

HEALTHCHECK 支持两种模式：ON（启用检查）和 NONE（禁用父镜像的检查）。常用写法为：

HEALTHCHECK [OPTIONS] CMD command

关键选项包括：

• --interval=DURATION：两次检查间隔，默认 30s（如 --interval=10s）
• --timeout=DURATION：单次检查超时时间，默认 30s（如 --timeout=3s）
• --start-period=DURATION：容器启动后等待多久再开始检查，默认 0s（适合需冷启动的服务，如 --start-period=30s）
• --retries=N：连续失败多少次才标记为 unhealthy，默认 3 次

常见服务的 HEALTHCHECK 编写示例

检测逻辑必须轻量、快速、无副作用。推荐使用服务自带的健康端点或简单网络/进程检查：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

• Nginx：用 curl 访问 /healthz 或 / 并检查 HTTP 状态码
  HEALTHCHECK --interval=10s --timeout=3s --retries=3 CMD curl -f http://localhost/healthz || exit 1
• Node.js 应用（Express）：确保监听端口且能响应 GET /health
  HEALTHCHECK --interval=15s CMD wget --quiet --tries=1 --spider http://localhost:3000/health || exit 1
• MySQL 容器：用 mysql client 执行简单查询
  HEALTHCHECK --interval=20s CMD mysqladmin ping -h localhost -u root -prootpw --silent || exit 1

注意事项与避坑要点

HEALTHCHECK 不是万能探针，实际使用中容易忽略以下细节：

• 命令在容器内执行，路径、依赖、权限需与容器环境一致（例如 curl/wget/mysqladmin 必须已安装）
• 避免使用耗时操作（如大文件读取、复杂数据库查询），否则可能拖慢检查节奏或误判
• 返回码决定状态：0 = healthy，1 = unhealthy，2 = reserved（Docker 当前忽略）
• 若基础镜像已有 HEALTHCHECK，可用 HEALTHCHECK NONE 清除后再自定义
• 本地测试时，用 docker ps 查看 STATUS 列中的 healthy/unhealthy；用 docker inspect CONTAINER_ID | jq '.State.Health' 查看详细结果

与 docker run 的 --health-* 参数关系

Dockerfile 中定义的 HEALTHCHECK 是默认策略，但可在运行时覆盖：

• 用 docker run --health-cmd="..." --health-interval=5s ... 可临时替换指令
• 用 docker run --no-healthcheck 可完全禁用
• 运行时参数优先级高于 Dockerfile，适合不同部署环境差异化配置