为什么你的容器没有自动重启？on-failure策略的5个常见配置陷阱

关注

原创最新推荐文章于 2026-10-15 12:12:53 发布 1.1k 阅读 AI 写同款· GEO 优化 ›

Docker基础教程（126）docker容器之自动重启容器：打工人福音！Docker容器“永生“秘籍：老板再也不用担心我的服务挂掉了文深度剖析Docker容器自动重启机制，揭秘--restart策略的妙用。通过生动比喻和完整示例，讲解如何让容器拥有"打不死的小强"属性，实现服务高可用。从基础命令到Compose配置，从简单重启到健康检查，手把手教你打造自我修复的容器生态系统，确保服务7×24小时稳定运行，彻底告别半夜被告警吵醒的悲惨生活！阅读详情

第一章：为什么你的容器没有自动重启？

当容器意外终止时，预期行为通常是根据配置自动重启。然而，许多开发者发现容器并未如预期那样恢复运行。这通常与容器的重启策略（Restart Policy）未正确设置有关。

检查重启策略配置

在 Docker 或 Kubernetes 环境中，必须显式定义重启策略。例如，在 Docker 中运行容器时，需使用 --restart 参数指定行为：

# 启动容器并设置自动重启策略
docker run -d \
  --restart=unless-stopped \
  --name my-container \
  nginx:latest

上述命令中的 unless-stopped 表示除非手动停止，否则容器将在退出后自动重启。其他可选值包括 no、on-failure 和 always。

常见重启策略对比

策略	描述
no	容器退出时不自动重启
on-failure	仅在容器非正常退出（退出码非0）时重启，可限制重试次数
always	无论退出状态如何，始终重启容器
unless-stopped	始终重启，除非容器被手动停止

验证容器当前策略

可通过以下命令查看容器的重启策略设置：

# 查看容器详细信息中的 RestartPolicy 配置
docker inspect my-container | grep -i restart

输出将显示类似内容：

{
  "RestartPolicy": {
    "Name": "always",
    "MaximumRetryCount": 0
  }
}

若策略为 no，则容器不会自动重启。此时应重新运行容器并指定合适的策略。

确保使用正确的 --restart 参数启动容器
在 Kubernetes 中，应通过 Pod 的 restartPolicy 字段控制（默认为 Always）
宿主机重启或守护进程异常也可能影响容器恢复，需结合 systemd 或编排工具管理

第二章：on-failure重启策略的核心机制与常见误解

2.1 on-failure策略的工作原理：退出码决定重启行为

容器的重启策略中，on-failure 是一种基于退出码判断是否重启的关键机制。当容器非正常退出时，Docker 会检查其退出码，若不为0，则触发重启动作。

退出码与重启逻辑

退出码是进程终止时返回给操作系统的状态值。通常：

退出码0表示成功执行，不会重启；
非0退出码（如1、2、137等）表示异常，将触发重启。

配置示例

version: '3'
services:
  app:
    image: myapp
    restart: on-failure
    # 可选：限制最大重启次数
    deploy:
      restart_policy:
        condition: on-failure
        max_attempts: 3

上述配置中，容器仅在非0退出时重启，且最多尝试3次。该策略适用于批处理任务或希望避免无限循环崩溃的场景。

2.2 非零退出码≠触发重启：哪些情况被系统忽略

在某些场景下，即使进程返回非零退出码，系统也不会触发重启机制。这通常由配置策略或运行环境决定。

被忽略的典型场景

一次性任务（One-off Jobs）：如数据库迁移脚本，执行完毕后无论成功与否均不重启；
预检探针失败：健康检查中短暂异常可能被容忍；
手动停止的服务：用户主动终止被视为意图明确，不会自动恢复。

配置示例与逻辑分析

restart: on-failure
restart-retry-limit: 3

上述配置表示仅在失败时重启，且最多重试3次。超过限制后，即使进程崩溃也不会再拉起。

系统行为决策表

场景	是否重启	原因
Job 已完成但退出码非零	否	任务生命周期已结束
超过最大重启次数	否	防止无限循环
容器 OOM Kill	是	资源异常视为可恢复错误

2.3 restart参数的完整取值对比：always、unless-stopped与on-failure差异

在Docker容器生命周期管理中，`restart`策略决定了容器在退出或系统重启后的恢复行为。不同取值适用于不同的服务类型和可靠性需求。

核心取值说明

always：无论退出状态如何，始终自动重启容器
unless-stopped：除非被手动停止，否则始终重启
on-failure：仅当容器以非0状态码退出时重启（可选设置重试次数）

典型配置示例

version: '3'
services:
  web:
    image: nginx
    restart: unless-stopped

该配置确保容器在宿主机重启后自动启动，但若管理员执行docker stop则不再重启，适合生产环境长期运行服务。

策略对比表

策略	系统重启后启动	手动停止后是否重启	崩溃后重启
always	是	是	是
unless-stopped	是	否	是
on-failure	是	否	仅失败时

2.4 容器健康检查失败是否触发on-failure重启？实践验证结果

在Docker中，restart: on-failure 策略仅在容器以非零状态退出时触发重启，而健康检查（HEALTHCHECK）失败并不会导致容器退出。

实验验证过程

使用以下 Dockerfile 构建测试镜像：

FROM alpine
CMD while true; do echo "running"; sleep 10; done
HEALTHCHECK --interval=5s --timeout=3s --start-period=5s --retries=1 \
  CMD exit 1

该配置中健康检查始终失败（exit 1），但主进程持续运行。

关键结论

健康检查失败仅改变容器健康状态为 unhealthy；
容器仍处于运行状态（running），不会触发 on-failure 重启；
只有当进程异常退出（如崩溃、返回非零码）时，on-failure 才生效。

因此，健康检查机制需与编排系统（如Kubernetes）结合，才能实现基于健康状态的自动恢复。

2.5 Docker引擎版本差异对on-failure判断逻辑的影响

不同版本的Docker引擎在处理容器重启策略时，对`on-failure`条件的判定存在细微差异，尤其体现在退出码捕获和重试次数计算上。

行为差异对比

Docker 18.09及以下：仅当容器非正常退出（exit code ≠ 0）时触发on-failure重启
Docker 19.03+：引入了更精确的信号终止检测，支持区分SIGKILL与SIGTERM

配置示例

{
  "RestartPolicy": {
    "Name": "on-failure",
    "MaximumRetryCount": 3
  }
}

该配置在19.03以上版本中会严格记录每次失败尝试，而在旧版本中可能忽略短暂崩溃。

版本兼容性建议

引擎版本	最大重试支持	信号感知
≤18.09	有限	否
≥19.03	完整	是

第三章：配置文件中容易忽视的关键字段

3.1 restart: on-failure未生效？检查docker-compose.yml语法正确性

在使用 Docker Compose 部署服务时，若配置 `restart: on-failure` 未按预期触发重启机制，首要排查方向应为配置文件的语法正确性。

常见YAML缩进错误

Docker 对 YAML 缩进极为敏感。以下为正确写法示例：

version: '3.8'
services:
  app:
    image: nginx
    restart: on-failure

上述配置中，`restart` 必须与 `image` 处于同一层级，且前缀两个空格。若缩进错误，Docker 将忽略该指令而不报错。

支持的重启策略对照表

策略	触发条件	适用场景
no	从不重启	调试阶段
on-failure	非0退出码时重启	批处理任务
always	任何终止均重启	常驻服务

确保 `on-failure` 拼写无误且未被覆盖。某些部署环境会通过守护进程默认策略覆盖容器级设置。

3.2 exit_code条件限制：如何设置最大重试次数（on-failure:3）的实际效果

在Docker Compose中，通过restart: on-failure:3可限定容器仅在非零退出码时最多重启3次。

配置示例与行为解析

service:
  app:
    image: my-app
    restart: on-failure:3

该配置表示：若容器因异常（exit code ≠ 0）退出，将尝试重启，但累计失败3次后不再重试。例如，程序因内存溢出或未捕获异常退出，前3次会自动恢复，第4次则永久停止。

重试机制对照表

失败次数	是否重启	说明
1	是	首次失败，触发第一次重试
3	是	仍在允许范围内
4	否	超过最大重试阈值

此策略平衡了容错性与资源保护，避免无限重启导致系统负载过高。

3.3 依赖服务启动顺序导致的早期退出被误判为“失败”

在微服务架构中，主服务常依赖数据库、缓存等外部组件。若这些依赖未就绪，主服务可能因连接超时而提前退出，被容器编排系统误判为“启动失败”。

典型场景分析

当 Kubernetes 启动 Pod 时，若应用在依赖服务（如 MySQL）尚未可用时尝试连接并失败退出，健康检查机制会标记容器为 CrashLoopBackOff，但实际上服务逻辑并无缺陷。

解决方案：引入启动探针与重试机制

livenessProbe:
  tcpSocket:
    port: 8080
  initialDelaySeconds: 60
  periodSeconds: 10
startupProbe:
  tcpSocket:
    port: 8080
  failureThreshold: 30
  periodSeconds: 10

上述配置通过 startupProbe 延长启动容忍时间，避免因依赖服务初始化慢导致误判。

使用指数退避重试连接依赖服务
结合启动探针（Startup Probe）延长初始化窗口
分离就绪性与存活性检查逻辑

第四章：典型故障场景与排错方法论

4.1 应用短暂启动失败后不再重启：日志分析与时间窗口判断

在容器化环境中，应用启动失败后的频繁重启可能导致资源浪费和雪崩效应。为避免此类问题，需结合日志分析与时间窗口机制判断是否继续重启。

失败模式识别

通过解析应用启动日志，可识别出短暂性错误（如依赖超时）与永久性错误（如配置缺失）。例如：


2025-04-05T10:23:01Z ERROR failed to connect to database: context deadline exceeded
2025-04-05T10:24:02Z FATAL config.yaml not found: open /etc/app/config.yaml: no such file

前者可能具备重试价值，后者则无需重复尝试。

时间窗口控制策略

采用滑动时间窗口统计失败次数。若在5分钟内失败超过3次，则停止自动重启：

时间窗口	最大尝试次数	冷却时间
5分钟	3次	30分钟

该机制防止系统陷入无限重启循环，同时保留恢复可能性。

4.2 容器因资源限制（OOM）退出时on-failure是否起作用

当容器因内存溢出（OOM, Out-of-Memory）被系统终止时，其退出码为 137。Docker 的重启策略 `on-failure` 仅在容器以非零退出码退出且不是由 OOMKilled 显式终止时生效。

退出码与重启策略判定

退出码 137 表示进程被 SIGKILL 信号终止，通常由内核 OOM Killer 触发；
Docker 将 OOM 视为严重异常，默认不触发 on-failure 重启；
若容器因应用逻辑崩溃（如退出码 1），on-failure 会按配置重试。

验证示例

docker run --memory=100m --restart=on-failure:3 alpine \
  sh -c "dd if=/dev/zero of=/tmp/file bs=1M count=200"

该命令限制内存为 100MB，并尝试分配 200MB 数据。容器将因 OOM 被杀，尽管设置了 on-failure:3，但 Docker 不会重启。

解决方案

合理设置容器内存限制与应用需求匹配，或使用 restart: always 确保重启，但需警惕资源耗尽风险。

4.3 自定义入口脚本错误导致反复崩溃但无重启的深层原因

当自定义入口脚本存在逻辑缺陷时，容器可能陷入“启动 → 崩溃 → 快速重启 → 再崩溃”的循环。然而，在某些运行时配置下，Kubernetes 或 Docker 并未触发预期的重启策略，导致服务长时间不可用。

常见错误模式

脚本中未正确处理依赖就绪状态
启动命令阻塞或陷入无限重试
忽略信号捕获，无法响应终止指令

典型问题代码示例

#!/bin/sh
while ! nc -z db:5432; do
  echo "Waiting for database..."
  sleep 2
done
exec ./app  # 若app立即崩溃，且父进程退出，容器终止但可能不重启

该脚本在数据库未就绪时持续轮询，一旦应用启动后因异常退出，父 shell 进程也随之结束，容器进入终止状态。若 Pod 的 `restartPolicy` 配置不当（如 OnFailure 但退出码为0），则不会触发重启。

关键排查点

检查项	建议值
restartPolicy	OnFailure 或 Always
启动脚本是否使用 exec	确保替换主进程

4.4 使用docker stop或API主动终止容器后on-failure策略的行为变化

当通过 docker stop 命令或 Docker API 主动停止容器时，Docker 会向容器内主进程发送 SIGTERM 信号，并在超时后发送 SIGKILL。这种终止方式被视为“正常退出”，即使容器返回非零退出码，on-failure 重启策略也不会触发。

on-failure 策略的触发条件

该策略仅在容器**非正常退出**时生效，即容器因内部错误、崩溃或意外中断导致退出（退出码非0且非人为终止）。若使用 docker stop，则退出码为 0 或由用户指定，被视为预期行为。

docker run --restart=on-failure:3 my-app

此命令设置容器最多重试3次，但仅在非人为终止的失败场景下生效。

行为对比表

终止方式	是否触发 on-failure	原因
docker stop	否	主动控制，视为正常退出
容器崩溃（panic/segfault）	是	非零退出码且非人为干预

第五章：构建高可用容器化服务的最佳实践建议

合理设计 Pod 健康检查机制

Kubernetes 依赖 liveness 和 readiness 探针判断容器状态。不合理的配置可能导致服务误重启或流量进入未就绪实例。

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  failureThreshold: 3

上述配置确保应用启动后有足够时间初始化，同时避免将请求路由到尚未准备好的实例。