docker健康检查中，timeout应略大于服务p95响应时间并留余量（如轻量api设4–5s、spring boot设10–15s），retries需与interval协同以避免误判（常用retries=3，配合interval≥2×timeout）；start-period须覆盖冷启动时间，且检查命令须真实反映业务可用性（如curl -f）。

配置 docker 健康检查的 timeout 和 retries 不是凑数字，而是让容器能准确区分“还没好”和“真的坏了”。关键靠两者协同，再配合 interval 和 start-period 才有效。

timeout 要略大于服务真实响应上限

它不是越长越好，而是得覆盖服务健康接口在压力下的最慢合理耗时（比如 P95 值），再留一点余量：

• 轻量 HTTP 服务（如纯 API）：平均响应 1.2s，P95 约 2.8s → timeout 设 4–5s
• Spring Boot 应用（含 DB 连接、缓存校验）：P95 可能达 6–8s → timeout 设 10–15s
• 数据库容器（PostgreSQL 启动后首次查询）：可能卡在 WAL 恢复或同步 → timeout 设 20–30s
• 切忌设成 60s 甚至更大：单次检查拖太久，会阻塞下一轮检测，还掩盖真实性能问题

retries 是“连续失败几次才信你坏了”，不是“总共允许失败几次”

它和 interval 共同决定从第一次失败到标记 unhealthy 的总延迟。设太小易误判，设太大延误响应：

Docker Image Puller

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

下载

• retries = 2：两次失败间隔至少为 interval，适合对稳定性要求高、故障需快速干预的场景（如网关、核心 API）
• retries = 3：最常用，能过滤掉一次 GC、瞬时网络抖动或 CPU 抢占带来的偶发超时
• retries = 1：不推荐——一次超时就标 unhealthy，极容易被临时资源争抢误伤
• retries ≥ 5：除非服务本身极其缓慢且稳定（如批量 ETL 容器），否则可能等 5×interval 才触发告警，失去健康检查意义

必须和 interval、start-period 配合使用

单独调 timeout 或 retries 效果有限，它们需要节奏匹配：

• interval 至少是 timeout 的 2–3 倍：避免上一次检查还没结束，下一次就启动（curl 并发堆积、端口占用、连接池打满）
• start-period 必须覆盖完整冷启动时间：Web 应用建议 30–60s，带数据恢复的数据库建议 45–120s；这段时间内失败不计入 retries，状态保持 starting
• 典型组合示例：
  --interval=30s --timeout=10s --start-period=60s --retries=3
  表示：启动后 60 秒内不计失败；之后每 30 秒检查一次，每次最多等 10 秒；连续 3 次失败才标为 unhealthy（即最早也要等 90 秒后才触发）

命令本身要真实反映服务能力

timeout 和 retries 再合理，也救不了一个假检查：

• 别只测端口是否 open（nc -z localhost 8080）：进程活着但业务线程卡死，照样返回成功
• 优先用 curl -f http://localhost:8080/health：-f 参数确保非 2xx 状态码直接返回非零退出码
• 复杂服务可加逻辑判断，比如检查 DB 连接 + 缓存可用性：
  CMD wget --spider -q http://localhost:8080/health && curl -sf http://localhost:8080/actuator/health/db | grep -q '"status":"UP"'
• 退出码必须严格：0=成功，1=失败（计入 retries），2=跳过本次（Docker 忽略）