modem7/docker-autoheal Docker 镜像 - 轩辕镜像

Docker Autoheal

镜像概述和主要用途

Docker Autoheal用于监控并重启不健康的Docker容器。尽管Docker的HEALTHCHECK功能已实现，但原生并未包含自动重启不健康容器的机制（相关功能提案参见#22719和#28400）。本镜像作为临时解决方案，填补这一功能空白，直至原生支持--exit-on-unhealthy。

支持的标签和Dockerfile链接

• latest (Dockerfile) - 每周构建
• pinned

核心功能和特性

• 监控容器健康状态，自动重启不健康容器
• 支持通过标签或环境变量灵活指定监控范围
• 兼容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 \
    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 \
    modem7/docker-autoheal

容器监控范围配置

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

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

时区配置

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

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

Apprise通知集成

1. 启动Apprise容器：参见 Apprise Docker镜像
2. 为Autoheal创建Apprise配置：
   访问 http://localhost:8000/cfg/autoheal 配置通知渠道（配置详情参见 Apprise文档）
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