Watchtower：让 Docker 容器镜像保持自动更新

Docker 作为当下热门的容器化平台，为 Homelab 玩家提供了轻量、便携的应用打包、分发与运行方案。但是，在实际使用中，如何保持容器镜像的及时更新，一直都是基础运维不可忽视的一环。

今天，我们要介绍一款 Docker 镜像自动更新工具——Watchtower。接下来，会先从它的核心功能、工作原理讲起，再到如何使用它来简化容器镜像的更新任务。

01. Watchtower 是什么？

如果你在玩 Homelab，要管理几十个容器 😅，手动更新容器镜像就会变成一件既耗时又容易出错的事。维护工作会变得相当繁琐。

你对这些命令有没有很眼熟？

docker stop ……
docker rm ……
docker pull ……
docker run ……

可以想象，如果要同时维护多个容器，或者你的集群横跨多台主机，这种手动更新的方式，简直就是对体力和耐心的双重考验。

1.1 工作机制

Watchtower 是一款轻量级、开源的容器管理工具，专门用于 Docker 容器镜像的更新自动化。

• 它会在「指定时间」连接到远程 Docker 镜像仓库（例如 Docker Hub，或私有镜像库），检查当前运行的容器是否有镜像更新。
• 一旦发现镜像更新，它就会自动拉取最新版本，并基于初始部署时所使用的参数，优雅地关闭并重建对应的容器。

默认情况下，它会每隔 24 小时（86400 秒）进行一次检查。你也可以根据自己的需要，通过WATCHTOWER_POLL_INTERVAL或WATCHTOWER_SCHEDULE环境变量，来灵活调整检测频率。

此外，Watchtower 还支持自定义定时策略、滚动更新和通知推送等丰富功能，帮你灵活配置自动更新流程，满足多样化的场景需求。

02. 如何使用 Watchtower

2.1 基本使用

1Watchtower 自身也是通过 Docker 镜像进行分发的，部署过程非常简单：

docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

只需要注意一点：由于需要通过 Docker API 来监控和管理运行中的容器，所以要将主机的/var/run/docker.sock挂载到 Watchtower 容器中。

2你可以随时通过以下命令，查看 Watchtower 的操作日志：

docker logs watchtower

每次自动检测、拉取和更新容器镜像的全过程，都会被详细记录在日志中，方便你追踪和排查问题。

2.2 设置时区

为了配合定时任务，建议指定一个「时区变量」，确保检测时间与本地时间保持一致。不然，就会默认以 UTC 时区执行，可能会造成时间偏差。

比如，国内一般用Asia/Shanghai时区，其它时区代码可以参考 tz 数据库：

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

2.3 设置更新「时间点」或「间隔」

如前所述，默认 Watchtower 会每 24 小时「检测 → 更新」一次。但我们可以选择以下 2 个环境变量（之一）来灵活调整频率：

• WATCHTOWER_POLL_INTERVAL：指定时间间隔，比如每 21600 秒（6 小时）执行一次。

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -e WATCHTOWER_POLL_INTERVAL=21600 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

• WATCHTOWER_SCHEDULE：通过 Cron 表达式（非传统的 5 字段）指定时间点，比如每天凌晨 4 点执行一次。

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -e WATCHTOWER_SCHEDULE="0 0 4 * * *" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

2.4 自动清理旧版镜像

默认 Watchtower 并不会自动删除旧版镜像。这样一来，在长时间运行后，系统中可能会堆积大量无用的老旧「悬空镜像」，白白占用磁盘空间。

如果你不想，定期执行 Docker 环境清理。推荐添加WATCHTOWER_CLEANUP=true环境变量 ，在容器切换到新镜像后，自动清理旧版「悬空镜像」：

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -e WATCHTOWER_SCHEDULE="0 0 */6 * * *" \
  -e WATCHTOWER_CLEANUP=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

2.5 灵活指定监控（或排除）容器

Watchtower 会自动监控并更新主机上的所有容器镜像。但在一些场景中，我们只想让它管理特定的几个容器。这时，就需要分两步来设置：

1在启动特定容器时，打上com.centurylinklabs.watchtower.enable=true标签，表示允许 Watchtower 对其进行管理。

docker run -d --label=com.centurylinklabs.watchtower.enable=true someimage

2然后在启动 Watchtower 时，添加WATCHTOWER_LABEL_ENABLE=true环境变量。这样它就只会监控并更新设置了「上述标签」的容器。

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -e WATCHTOWER_SCHEDULE="0 0 */6 * * *" \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_LABEL_ENABLE=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

2.6 记录并追踪 Watchtower 行为

虽然自动化更新能大大减轻我们的管理负担，但也存在一定的「翻车风险」。更新是否成功、更新内容是否符合预期，都需要我们及时掌握。

• 我比较推荐的做法是：定期查看 Watchtower 运行日志，了解它的操作细节：

docker logs watchtower

• 你也可以配置 Watchtower 在完成更新或重启操作后，主动发送通知给你。它支持多种通知方式，比如邮件、Slack、Microsoft Teams 和 Gotify 等。具体配置方式请参考官方文档。

与 Homepage 面板集成

在启用了 Watchtower 的 Metrics 功能之后，就可以很方便地在 Homepage 面板中，通过小组件查看 Watchtower 的扫描情况、升级成功或失败的记录：

1在启动 Watchtower 时，添加以下两个环境变量：

• WATCHTOWER_HTTP_API_METRICS=true：启用 Metrics 端点，开放 Prometheus 指标。
• WATCHTOWER_HTTP_API_TOKEN=mytoken：设置一个用于访问的 Token，提升安全性。

以下是我自用的完整启动命令，仅供参考：

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -e WATCHTOWER_SCHEDULE="0 0 */6 * * *" \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_LABEL_ENABLE=true \
  -e WATCHTOWER_HTTP_API_TOKEN=mytoken \
  -e WATCHTOWER_HTTP_API_METRICS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8088:8080 \
  containrrr/watchtower

2接下来，在 Homepage 面板的services.yaml配置文件中，启用 Watchtower 小组件：

- Automation:
    - watchtower:
        icon: watchtower.png
        widget:
            type: watchtower
            url: http://ip:port
            key: mytoken

总的来说，Watchtower 能极大地简化 Docker 镜像的更新维护流程。除了以上介绍的常用功能外，它还支持更多高级参数和选项。你可以根据自身情况进行设置，详细文档与进阶用法请参考 Watchtower 项目官网。