modem7/docker-autoheal

Docker Autoheal

镜像概述和主要用途

Docker Autoheal用于监控并重启不健康的Docker容器。尽管Docker的HEALTHCHECK功能已实现，但原生并未包含自动重启不健康容器的机制（相关功能提案参见https://github.com/docker/docker/pull/22719%E5%92%8Chttps://github.com/moby/moby/issues/28400%EF%BC%89%E3%80%82%E6%9C%AC%E9%95%9C%E5%83%8F%E4%BD%9C%E4%B8%BA%E4%B8%B4%E6%97%B6%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%EF%BC%8C%E5%A1%AB%E8%A1%A5%E8%BF%99%E4%B8%80%E5%8A%9F%E8%83%BD%E7%A9%BA%E7%99%BD%EF%BC%8C%E7%9B%B4%E8%87%B3%E5%8E%9F%E7%94%9F%E6%94%AF%E6%8C%81%60--exit-on-unhealthy%60%E3%80%82

支持的标签和Dockerfile链接

• latest https://github.com/modem7/docker-autoheal/blob/master/Dockerfile - 每周构建
• pinned

https://images.microbadger.com/badges/image/modem7/docker-autoheal.svg](http://microbadger.com/images/modem7/docker-autoheal "Docker layer breakdown")

核心功能和特性

• 监控容器健康状态，自动重启不健康容器
• 支持通过标签或环境变量灵活指定监控范围
• 兼容UNIX套接字和TCP套接字（含TLS加密）连接Docker API
• 支持时区配置，匹配宿主机时区
• 集成Apprise实现通知功能
• 提供重启后脚本执行能力，支持自定义操作
• 可通过环境变量和标签自定义监控间隔、启动延迟、停止超时等参数

使用场景和适用范围

• 需要确保服务持续可用的Docker环境
• 依赖容器健康检查实现自动恢复的部署场景
• 暂未支持Docker原生--exit-on-unhealthy功能的环境
• 需要对容器异常重启进行通知或后续处理的场景

详细使用方法和配置说明

基础使用方式

UNIX套接字连接

bash
docker run -d \
    --name autoheal \
    --restart=always \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -v /var/run/docker.sock:/var/run/docker.sock \
    docker.xuanyuan.run/modem7/docker-autoheal

TCP套接字连接

bash
docker run -d \
    --name autoheal \
    --restart=always \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -e DOCKER_SOCK=tcps://HOST:PORT \
    -v /path/to/certs/:/certs/:ro \
    docker.xuanyuan.run/modem7/docker-autoheal

容器监控范围配置

• 方式a：为目标容器添加标签 autoheal=true 以启用监控
• 方式b：设置环境变量 AUTOHEAL_CONTAINER_LABEL=all 监控所有运行中容器
• 方式c：设置环境变量 AUTOHEAL_CONTAINER_LABEL 为现有标签名（标签值需为true）

注意：若使用方式b监控所有容器，可通过为特定容器添加标签 autoheal=false 排除监控
注意：必须先为容器镜像配置 HEALTHCHECK，详情参见 https://docs.docker.com/engine/reference/builder/#healthcheck
TCP连接说明：tcp:// 用于未加密连接，tcps:// 用于TLS加密连接。TLS配置参见 https://docs.docker.com/engine/security/https/
TLS证书要求：需在挂载目录中包含以下文件：ca.pem（CA证书）、client-cert.pem（客户端证书）、client-key.pem（客户端密钥）

时区配置

如需容器时区与宿主机一致，挂载宿主机时区文件：

bash
docker run ... -v /etc/localtime:/etc/localtime:ro

Apprise通知集成

1. 启动Apprise容器：参见 https://hub.docker.com/r/caronc/apprise
2. 为Autoheal创建Apprise配置：
   访问 http://localhost:8000/cfg/autoheal 配置通知渠道（配置详情参见 https://github.com/caronc/apprise/wiki%EF%BC%89
3. 设置环境变量启用通知：
   APPRISE_URL="http://localhost:8000/notify/autoheal"

环境变量默认值

AUTOHEAL_CONTAINER_LABEL=autoheal      # 监控标签名，默认值为"autoheal"
AUTOHEAL_INTERVAL=5                    # 健康检查间隔（秒），默认5秒
AUTOHEAL_START_PERIOD=0                # 首次健康检查延迟时间（秒），默认0秒
AUTOHEAL_DEFAULT_STOP_TIMEOUT=10       # 容器重启时的停止超时时间（秒），默认10秒（Docker默认值，可通过标签覆盖）
DOCKER_SOCK=/var/run/docker.sock       # Docker API连接地址，默认UNIX套接字
CURL_TIMEOUT=30                        # Docker API请求超时时间（秒），默认30秒
WEBHOOK_URL=""                         # 容器重启后发送通知的Webhook URL
WEBHOOK_JSON_KEY="content"             # Webhook请求中消息内容的JSON键名
APPRISE_URL=""                         # Apprise通知配置URL
POST_RESTART_SCRIPT=""                 # 容器重启后执行的脚本路径（需挂载到容器内）

可选容器标签

• autoheal.stop.timeout=20：为特定容器设置重启时的停止超时时间（秒），覆盖默认值

重启后脚本执行示例

以下示例演示如何在容器重启后执行自定义脚本，脚本接收参数：CONTAINER_NAME（容器名称）、CONTAINER_SHORT_ID（容器短ID）、CONTAINER_STATE（容器状态）、RESTART_TIMEOUT（重启超时时间）

bash
# 构建测试镜像（可选，直接使用modem7/docker-autoheal亦可）
docker build -t autoheal .

# 运行容器并配置重启后脚本
docker run -d \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -e POST_RESTART_SCRIPT=/scripts/post_restart.sh \
    -v ./scripts:/scripts \  # 挂载宿主机脚本目录到容器内
    -v /var/run/docker.sock:/var/run/docker.sock \
    autoheal

测试方法

bash
# 构建测试镜像
docker build -t autoheal .

# 启动测试容器
docker run -d \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -e POST_RESTART_SCRIPT=/scripts/post_restart.sh \
    -v /var/run/docker.sock:/var/run/docker.sock \
    autoheal