on-failure是Docker中仅在容器以非零退出码终止时触发重启的条件策略，支持设置最大重试次数（如on-failure:3），避免正常退出（exit 0）或手动停止后误重启，适用于需容错但防无限崩溃的生产服务。

on-failure 是 docker 中最实用的条件重启策略，核心就是“只在出错时重启”，避免正常退出（如主动关闭、健康停机）也被反复拉起。它不盲目兜底，也不放任失败，适合大多数需要容错但又怕无限崩溃的服务。

on-failure 的触发条件很明确

容器必须以非零退出码终止，Docker 才会尝试重启。常见情况包括：

• 应用 panic 或未捕获异常导致进程退出（如 Python 报 SystemExit(1)、Go os.Exit(2)）
• 配置加载失败、数据库连接超时等初始化错误
• 被系统 OOMKilled（退出码 137）或段错误（139）强制终止

而这些情况不会触发重启：

• 容器执行 exit 0 或主进程自然结束（比如脚本跑完）
• 手动执行 docker stop 或 docker kill（除非加了 --signal=SIGKILL 导致非零码）
• 容器收到 SIGTERM 并成功处理后优雅退出

如何配置 on-failure 策略

命令行方式（docker run）：

docker run -d \
  --name my-app \
  --restart on-failure:3 \
  nginx:alpine

on-failure:3 表示：仅当非零退出时重启，最多试 3 次；第 4 次失败就彻底停止，不再自动拉起。

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

省略数字（如 --restart on-failure）则无重试上限，但生产环境不建议——可能掩盖根本问题，还拖垮宿主机。

Docker Compose 方式：

version: '3.8'
services:
  api:
    image: my-api:v1
    restart: on-failure:5

若需更精细控制（如加延迟退避），可配合 deploy.restart_policy（仅 Swarm 模式支持）：

deploy:
  restart_policy:
    condition: on-failure
    max_attempts: 3
    delay: 10s

实际使用中的关键提醒

• 退出码是唯一判断依据：Docker 不看日志、不分析堆栈，只读 exit code。确保你的应用在真正失败时返回非零值（比如启动失败返回 1，而不是静默退出）。
• 它不解决根本问题：重启只是争取恢复窗口，务必搭配 docker logs my-app 或集中日志系统查清第 1 次失败原因。
• 别和健康检查混用却不设限：如果同时配了 HEALTHCHECK 和 on-failure:3，健康检查失败会导致容器被标记为 unhealthy，但是否重启仍取决于最终退出码——不是健康检查失败就自动重启。

不复杂但容易忽略。