healthcheck 指令必须写在 dockerfile 中，位于最终镜像层且紧邻 cmd 或 entrypoint；docker-compose.yml 中的 healthcheck 仅能覆盖而非新增，需严格配置 test、interval、timeout、retries 和 start_period 等小写字段。
Healthcheck 指令写在哪？必须放在 Dockerfile 里
容器健康检查的配置必须通过 HEALTHCHECK 指令在构建镜像时写入 Dockerfile，运行时用 docker run --health-cmd 覆盖是临时方案，不推荐用于生产。Docker 不支持在 docker-compose.yml 中“新增” Healthcheck，只能用 healthcheck: 块去覆盖镜像自带的指令（如果有的话）。
常见错误：把 HEALTHCHECK 写在 CMD 后面却忘了加 ONBUILD（它不支持 ONBUILD），或误以为 docker run 的参数能“启用”未定义的健康检查——没有 HEALTHCHECK，docker ps 就永远显示 health: starting 或直接不显示健康状态。
-
HEALTHCHECK必须出现在 Dockerfile 的最终镜像层中（即不能被后续RUN覆盖掉） - 建议紧挨着
CMD或ENTRYPOINT放置，避免因基础镜像变更导致路径失效 - 如果应用监听 127.0.0.1:8080，但健康检查用
curl -f http://localhost:8080/health，在容器内通常可行；但若应用绑定的是0.0.0.0，而 curl 因 DNS 或 hosts 问题解析localhost失败，就会误报失败
curl 和 exit code 是健康判断的核心逻辑
Docker 只看健康检查命令的退出码：0 表示 healthy，非 0（包括 1、124、125 等）都算 unhealthy。别指望 Docker 理解 HTTP 状态码——curl http://x/ 返回 404 时退出码仍是 0，必须加 -f（fail on error）或显式检查 $?。
典型陷阱：用 curl http://localhost:3000/ping 测试 Node.js 应用，结果容器一直显示 unhealthy。查日志发现 curl 因超时返回 28，但没加 --max-time 3，导致默认超时过长（常达数分钟），拖慢健康轮询节奏，甚至卡住重启判断。
- 务必加
curl -f --max-time 3 http://localhost:8080/health，避免 hang 住 - 不要依赖
ps aux | grep myapp这类模糊检查——进程存在 ≠ 服务就绪（比如刚启动正在加载缓存） - Python 用户慎用
python -c "import requests; requests.get('http://...').raise_for_status()"，因为默认不带 timeout，且镜像里很可能没装requests
docker-compose.yml 中的 healthcheck 配置项怎么生效？
当 Dockerfile 已有 HEALTHCHECK，docker-compose.yml 中的 healthcheck: 块会完全替换它；如果镜像没定义，compose 文件里的配置才真正生效。注意字段名大小写敏感：test、interval、timeout、retries、start_period 全是必须小写。
最常被忽略的是 start_period：新容器启动后，Docker 默认立即开始健康检查，但很多服务（如 PostgreSQL、Elasticsearch）需要 10–30 秒初始化。没设 start_period 就直接失败，触发不必要的重启循环。
-
test: ["CMD-SHELL", "curl -f --max-time 2 http://localhost:8000/readyz || exit 1"]—— 注意|| exit 1是兜底，防止 shell 语法错误被忽略 -
interval: 30s和timeout: 3s要匹配：若检查本身耗时接近 3s，interval 设太短会导致并发堆积 -
retries: 3意味着连续 3 次失败才标为 unhealthy，适合容忍瞬时抖动；但start_period: 40s必须 ≥ 应用冷启动最大耗时
怎么验证健康检查是否真在工作？
别只信 docker ps 里那一行 healthy —— 它可能只是“最后一次成功”，掩盖了间歇性失败。真正要看的是 docker inspect 输出里的 Health 字段，里面有完整历史、最近一次命令、退出码和时间戳。
一个硬核验证法：手动进容器 docker exec -it myapp sh，然后重复执行健康检查命令（比如 curl -f --max-time 2 http://localhost:8000/health），观察是否真能稳定返回 200。如果手动跑通、但容器里始终 unhealthy，大概率是用户权限问题（比如健康检查以 root 运行，但应用绑定端口需要非 root 权限，而 curl 却被 seccomp 或 user namespace 拦截）。
- 运行
docker inspect myapp | jq '.[0].State.Health'（需装 jq）查看结构化健康详情 - 检查
Status是否为healthy，同时确认FailingStreak是 0，且Log[0].ExitCode最近几次都是 0 - 如果看到
"Error": "context deadline exceeded"，说明 timeout 太短或服务响应慢，不是命令写错了
健康检查不是加了就完事——它和应用启动顺序、资源限制、网络模型深度耦合。哪怕一行 HEALTHCHECK，漏掉 start_period 或写错 curl 参数，都可能导致容器反复重启却查不出原因。
