如何检查 Watchtower 是否正常工作及更新未生效的排查方法【日常排错】

---

前言

写这篇文章主要记录一次实际生产环境遇到的问题。起因是公司有两个镜像库，一个是无需认证的公共镜像库，一个是需要账号密码认证的私有镜像库。都通过docker + watchtower 实现自动容器更新，但是私有库死活不生效。下面记录了排查过程。我这里是用了 5分钟 的定时检查。

虽然下文有很多方法都不是解决本次事故的原因，但是如果你不是站在 上帝视角你又怎么能知道到底是因为什么原因引起的呢？所以我把排查方法都罗列出来了。

---

一、验证 Watchtower 是否正在运行

1. 检查 Watchtower 容器状态

docker ps -f name=watchtower

正常应该看到类似输出：

CONTAINER ID   IMAGE                       COMMAND        CREATED       STATUS       PORTS     NAMES
a1b2c3d4e5f6   containrrr/watchtower:latest   "/watchtower"   2 days ago    Up 2 days             watchtower

如果 STATUS 不是 "Up" ，说明容器没有正常运行。

2. 查看 Watchtower 日志

docker logs watchtower

正常运行的 Watchtower 会有类似这样的周期性日志：

time="2023-05-01T12:00:00Z" level=info msg="Checking for new images"
time="2023-05-01T12:00:01Z" level=info msg="No new images found for nginx"

二、检查5分钟间隔设置是否正确

1. 确认启动命令

你的启动命令应该包含类似这样的环境变量设置：

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e WATCHTOWER_POLL_INTERVAL=300 \  # 300秒=5分钟containrrr/watchtower

常见错误：

• 拼写错误：WATCHTOWER(错误) vs WATCHTOWER(正确)
• 值不是秒数：应该直接写300(秒)，而不是"5m"或"5 minutes"

2. 验证环境变量

docker inspect watchtower | grep -i poll_interval

应该能看到类似：

"WATCHTOWER_POLL_INTERVAL=300"

三、排查更新未生效的原因

1. 检查是否有镜像更新

Watchtower 只会在镜像仓库有新版本时才会更新。确认你的镜像确实有新版本：

docker pull 你的镜像名:latest
docker images | grep 你的镜像名

2. 检查容器标签

某些标签会阻止 Watchtower 更新：

docker inspect 你的容器名 | grep -i watchtower.enable

如果看到 "com.centurylinklabs.watchtower.enable=false"，说明该容器被排除在更新外。

3. 检查监控范围

默认 Watchtower 监控所有容器，但如果你指定了特定容器，确认包含了你想要更新的容器：

docker inspect watchtower | grep -A5 "Cmd"

四、测试 Watchtower 功能

1. 手动触发检查🎯

docker exec watchtower /watchtower --run-once

这会立即执行一次检查更新操作，查看日志确认：

docker logs watchtower --tail 50

2. 创建测试容器

启动一个专门用于测试的容器：

docker run -d --name test-watchtower alpine tail -f /dev/null

然后推送一个新版本的 alpine 镜像到仓库，观察 Watchtower 是否会更新这个测试容器。

五、常见问题解决方案

1. 时间间隔不生效

可能原因：

• 环境变量名称拼写错误
• 值格式不正确（必须是秒数）
• Watchtower版本过旧

解决方案：

# 停止并删除旧容器
docker stop watchtower && docker rm watchtower# 使用最新版Watchtower并正确设置
docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e WATCHTOWER_POLL_INTERVAL=300 \containrrr/watchtower:latest

2. Watchtower 完全不工作

检查点：

• 确保 Docker 守护进程正常运行
• 检查 /var/run/docker.sock 的权限
• 尝试使用 --debug 模式获取更多日志信息：

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e WATCHTOWER_POLL_INTERVAL=300 \-e WATCHTOWER_DEBUG=true \containrrr/watchtower

然后查看详细日志：📃

docker logs watchtower

六、推荐的生产环境监控方案

对于生产环境，建议配置通知功能以便及时了解更新情况：

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e WATCHTOWER_POLL_INTERVAL=300 \-e WATCHTOWER_NOTIFICATIONS=email \-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=your@email.com \-e WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@email.com \-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.email.com \-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=your@email.com \-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=yourpassword \containrrr/watchtower

通过以上步骤，你应该能够确定为什么5分钟更新间隔没有生效，并根据具体情况解决问题。如果问题仍然存在，可以提供更多日志信息以便进一步诊断。

七、分析日志

上面方法我都试了，然而还是不行，我就把日志拷贝出来分析了下，后来恍然大悟，有没有可能是我们拉取镜像时没有登录授权，因为这个镜像库是私有的。一拍脑袋，没错。日志如下：

time="2025-05-07T07:36:21Z" level=debug msg="Got response to challenge request" header="Bearer realm=\"https://dockerauth.cn-hangzhou.aliyuncs.com/auth\",service=\"registry.aliyuncs.com:cn-beijing:26842\"" status="401 Unauthorized"

1. 阿里云私有仓库认证失败（主要问题）

多个容器出现类似错误：

time="2025-05-07T07:36:21Z" level=debug msg="No credentials for registry.cn-beijing.aliyuncs.com found"
time="2025-05-07T07:36:21Z" level=debug msg="Error pulling image registry.cn-beijing.aliyuncs.com/itdos/os.itdos.com:latest, Error response from daemon: pull access denied..."

问题分析：

• 所有来自 registry.cn-beijing.aliyuncs.com 的镜像都无法拉取
• Watchtower 没有配置私有仓库的认证信息
• 错误明确显示 "pull access denied"

根本原因：
私有仓库需要登录凭证，但 Watchtower 未配置这些凭证。

2. 解决方案

方案1：配置 Watchtower 使用私有仓库凭证
方法A：通过环境变量传递凭证

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e REPO_USER=your_username \-e REPO_PASS=your_password \-e WATCHTOWER_POLL_INTERVAL=300 \containrrr/watchtower \--debug

方法B：使用 Docker 配置文件（推荐）
首先登录私有仓库：

docker login registry.cn-beijing.aliyuncs.com

然后启动 Watchtower 并挂载 Docker 配置文件：

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-v $HOME/.docker/config.json:/config.json \-e WATCHTOWER_POLL_INTERVAL=300 \containrrr/watchtower

3. 问题解决

我用了第一种方法，通过环境变量传递凭证

docker run -d \--name watchtower \-v /var/run/docker.sock:/var/run/docker.sock \-e REPO_USER=your_username \-e REPO_PASS=your_password \-e WATCHTOWER_POLL_INTERVAL=300 \containrrr/watchtower \--debug

果然问题解决✅