Skip to content
项目

liquidguru/docker-updater has 87 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 05:00 UTC. Last push 2026-11-02.

这些数字如何统计

可以做什么

  • Registry polling — compares local image digests against the registry without pulling, using the Docker Registry v2 manifest API (HEAD + Docker-Content-Digest); the digest compared is the one the container is actually running, so a container left behind by an out-of-band docker pull is still flagged
  • Multi-registry support — Docker Hub, GHCR (ghcr.io), LinuxServer (lscr.io), and any registry that implements the Bearer token challenge
  • Multi-host support — manage containers across multiple Docker hosts (SSH or TCP) from a single dashboard; SSH host keys are auto-accepted on first Test Connection (TOFU) and persisted across restarts; each host has a connection health indicator and containers are shown together with a host chip
  • Per-container control — update individually, defer for 7/14/30/90 days or indefinitely, or un-defer at any time. A deferred container stops appearing in update notifications until the deferral expires (the notification says how many are being held back, so nothing goes quietly missing)

实测星标增长

24小时
0
7天
更新延迟
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Self-hosted Docker update manager — manual-approval alternative to Watchtower

自托管

README.zh-CN.md

原文

docker-updater

English | 简体中文

注意: 本项目由英文母语者维护,英文 README 为权威版本。中文翻译由社区贡献,可能落后于最新版本 —— 如有出入,请以英文版为准,特别是「注意事项」中与安全和数据相关的说明。欢迎提交 PR 更新翻译。

一个用于管理 Docker 容器更新的轻量级自托管 Web UI,也是 Watchtower 的一种“人工确认后更新”替代方案。

与新镜像发布后立即自动拉取并重启容器不同,docker-updater 会按计划轮询镜像仓库,展示可用更新,并由你决定何时更新某个容器,或者是否更新。更新过程内置回滚保护:旧容器会被保留,如果新容器启动失败,可以自动恢复旧版本。为了进一步降低风险,你还可以选择在更新“成功”后继续保留旧容器备份,这样即使新版本启动正常、但之后才暴露问题,也能随时回滚。执行更新前,还可以直接查看 GitHub Release 更新说明。


更新页 — 待更新容器、批量选择和最近更新历史

正在更新的容器 — 卡片上显示实时下载进度

备份页 — 保留的回滚点,可一键回滚或删除

设置页 — 检查计划、备份保留、通知、清理和未使用镜像选项

主机页 — 本地与远程 Docker 主机管理

登录鉴权

为了兼容现有部署,面板默认保持开放访问。在公网或不受信任的网络中,请同时设置用户名和密码;只设置其中一项时,程序会输出警告并保持鉴权关闭。

变量 说明
AUTH_USERNAME 面板登录用户名
AUTH_PASSWORD 面板登录密码
FLASK_SECRET_KEY 可选的会话签名密钥;未设置时会在 /app/data/.secret_key 自动生成
API_KEY 可选的只读密钥,供仪表盘和小组件使用,详见只读 API 密钥

使用 Docker Compose 时,在 docker-compose.yml 同目录创建 .env:

AUTH_USERNAME=admin
AUTH_PASSWORD='请替换为新的高强度密码'
# FLASK_SECRET_KEY='请替换为足够长的随机值'

Compose 的 .env 只为 ${VARIABLE} 提供替换值,不会自动把所有变量传入容器。请直接使用下方完整的 docker-compose.yml 示例,其中已经转发了三项变量;不要再添加第二个 services: 或 environment: 块。

环境变量变化后必须重新创建容器,单纯重启不会生效:

docker compose config --quiet
docker compose up -d --force-recreate

在不输出真实值的情况下检查变量,再查看启动日志:

docker compose exec docker-updater sh -c '
  test -n "$AUTH_USERNAME" && echo "AUTH_USERNAME: set" || echo "AUTH_USERNAME: missing"
  test -n "$AUTH_PASSWORD" && echo "AUTH_PASSWORD: set" || echo "AUTH_PASSWORD: missing"
'
docker compose logs --tail=100 docker-updater

配置成功时日志显示 [auth] Login required (user='admin');[auth] Open access 表示变量为空或未进入容器。使用 Synology 单容器界面时,请在容器设置中填写两项变量并重新创建容器,因为旁边的 .env 不会被自动读取。Paramiko CryptographyDeprecationWarning / TripleDES 警告与面板鉴权无关。

文件名必须是 .env 而不是 .env.txt,等号两侧不要加空格;可执行 chmod 600 .env 限制权限,并且不要公开文件内容。会话有效期为 7 天。/webhook/github 无需登录即可访问,但仍依赖 GITHUB_WEBHOOK_SECRET。将 WebUI 暴露到公网时,请在前端配置 HTTPS。

修改密码不会使已有会话失效。 会话由 FLASK_SECRET_KEY 签名,与密码无关,因此在修改密码之前签发的会话仍然有效,直到过期(最长 7 天)。如果你是因为怀疑密码泄露而修改密码,请同时轮换签名密钥以使所有现有会话失效:设置新的 FLASK_SECRET_KEY,或删除 data/.secret_key 让程序重新生成,然后重建容器。

只读 API 密钥

Homepage、Homarr 等仪表盘只需要查看数量,但让它们登录就得交出管理员密码,而该密码同样可以触发更新和回滚。请改为设置可选的 API_KEY(至少 16 个字符,例如 openssl rand -hex 24):

curl -H "Authorization: Bearer $API_KEY" http://your-host:9292/api/status
  • 它仅适用于 GET /api/status。其他所有接口以及面板本身仍然需要登录。它无法发起更新、回滚或检查,也不会创建会话。
  • 未设置 AUTH_USERNAME 和 AUTH_PASSWORD 时它不起作用(此时面板本来就是开放的);短于 16 个字符的密钥会被忽略,并在日志中给出警告。
  • 不设置则一切照旧。
  • 持有该密钥的人可以在 /api/status 中读取所有容器名称、镜像和主机,因此请当作机密对待;更换时修改变量并重建容器即可。

Homepage 的社区小组件正在开发中(gethomepage/homepage#7305),它可以使用此密钥。

语言

WebUI 支持 English 和 简体中文:

  • **自动(默认)**根据浏览器语言选择界面语言:zh* 使用中文,其它语言使用英文。
  • 在 设置 → 外观 → 语言 中可以立即切换“自动”、English 或中文。
  • 手动选择会保存在浏览器中,并用于决定推送通知的文案;自动模式会把当前浏览器的有效语言同步到服务端。
  • Docker 日志流、镜像名称和原始 Docker 错误保持原文。

功能

  • 镜像仓库轮询 — 通过 Docker Registry v2 Manifest API(HEAD + Docker-Content-Digest)比较本地与远程镜像摘要,无需先拉取镜像;用于比较的是容器实际正在运行的镜像摘要,因此即使标签被外部的 docker pull 更新过、容器却没有重建,仍能正确检测到更新
  • 多镜像仓库支持 — 支持 Docker Hub、GHCR(ghcr.io)、LinuxServer(lscr.io)以及任何实现 Bearer Token 质询的镜像仓库
  • 多主机支持 — 在一个面板中通过 SSH 或 TCP 管理多台 Docker 主机;首次测试 SSH 连接时自动接受并持久化主机密钥(TOFU),每台主机都有连接健康状态,容器卡片会显示所属主机
  • 单容器控制 — 可以单独更新、暂缓 7/14/30/90 天、无限期暂缓,或随时取消暂缓。暂缓期间该容器不会再出现在更新通知中,直到暂缓到期(通知中会说明有多少个被暂缓,因此不会有内容被悄悄遗漏)
  • 批量更新 — 选择多个容器并一次发起更新
  • 更新说明查看器 — 获取并内嵌显示最近 5 个 GitHub Release;带有 org.opencontainers.image.source 标签或托管在 GHCR 的镜像可自动识别,其它镜像可通过“设置更新说明来源…”指定 GitHub 仓库,并根据镜像名预填建议地址
  • 实时更新日志 — 日志弹窗实时显示拉取进度和容器重建状态;更新过程中刷新页面后会自动重新连接。更新卡片本身也会实时显示下载情况——下载时显示百分比和大小,随后是“正在解压镜像 · 已完成 3 / 8 层”(大型镜像最长的那段安静时间,现在带有计数),再到“正在替换容器……”
  • 拉取过程中取消更新 — 镜像下载期间,容器卡片上会出现 取消更新 按钮。取消会中止下载,并且完全不会影响正在运行的容器;一旦拉取完成、开始重建容器,就没有安全的中断点了,因此该按钮仅在下载阶段生效
  • 持久化更新日志 — 每次更新和回滚的完整日志都会保存到磁盘,即使容器重启,也可以通过历史记录中的“日志”按钮随时查看
  • 容器日志查看器 — 每张容器卡片都有“日志”按钮,可在弹窗中查看最近 200 行 docker logs,同时显示运行/停止状态并支持刷新,便于排查更新后的容器问题
  • 智能历史状态图标 — 最近更新使用 ✅(成功或仍在运行且已是最新)、⚠️(出现错误但容器仍在运行)或 ❌(出现错误且容器已停止),每行还会显示 ● 运行中 / ● 已停止;悬停图标可直接查看错误信息
  • 推送通知 — 首次运行自动生成私有 ntfy 主题,也可以使用自定义 Apprise URL(ntfy、Pushover、Discord、Slack 等)
  • 未使用的镜像(可选) — 一个默认关闭、开启前完全不可见的额外设置:同时检查没有运行中容器使用的带标签镜像,并在镜像仓库有新版本时通知你。仅作提示:它绝不会拉取任何内容,因为旧镜像可能属于某个数据库,而新版本未必能读取其数据
  • GitHub 通知 — 可选的 Webhook 接口可以接收任意仓库的 Issue、PR、Star、Push 和 Release 事件并转发为推送通知
  • 计划检查 — 可在“设置”中选择每 6/12 小时、每天、每周、每月或自定义 cron;修改立即生效并显示下次运行时间。计划保存在数据卷中,可跨重启、重建和镜像更新保留。只有计划任务会发送更新通知,启动扫描和手动检查不会发送通知
  • 卡片显示镜像大小 — 每张容器卡片都会显示该镜像在磁盘上占用的大小;当有可用更新时,↓ 标记会显示本次拉取实际需要下载的数据量(只统计本机尚未拥有的层),▤ 新增/总数 标记则显示层数,悬停可查看完整明细
  • Compose 栈标识 — 由 Docker Compose 启动的容器会在卡片上显示栈名称,该名称来自 com.docker.compose.project 标签;独立容器不受影响
  • 更新后重启 Compose 栈 — 可选设置,默认关闭。更新 Compose 管理的容器后,会重启而不是重建同一栈的其它成员,使其重新获取新容器的 IP/DNS,无需手动执行 docker compose restart。批量更新同一栈时只会触发一轮重启,并排除刚更新的容器、_old 备份、docker-updater 自身以及正在更新的成员
  • 自更新 — docker-updater 可以更新自己的容器:拉取新镜像后,由基于新镜像创建的短生命周期辅助容器在旧进程退出后完成停止和重建,无需人工干预
  • 安全重建 — 使用 Python Docker SDK 按 Watchtower 模式重建容器,沿用卷与命名挂载、端口、环境变量、网络、静态 IP 与别名、重启策略、Capabilities、设备、privileged/安全选项、DNS 与 extra hosts、PID/IPC 模式、tmpfs 以及其余所有主机设置,例如资源限制、GPU 请求、ulimits 和日志选项(不会沿用的内容见注意事项)
  • 备份与回滚 — 更新成功后可选择在指定时间内保留旧容器;如果新版本之后出现问题,可一键回滚,也可以提前删除备份以释放空间。远程主机同样适用:其备份会显示在“备份”页,并按时过期
  • 镜像清理 — 可选地在更新成功后删除被替代的镜像;若备份仍引用该镜像则不会删除。设置页还提供“显示可回收镜像”,可查看所有悬空镜像的仓库名、大小和创建时间,选择部分或全部删除。配置了多台主机时,可通过主机选择器切换查看哪一台的镜像(镜像是按主机独立存储的)。仍被容器占用的镜像(多为回滚备份)会显示原因,例如由哪个备份保留、保留到何时,且无法被选中,因此“全选”只会选中真正可以删除的镜像。删除在后台执行,离开页面后仍会继续:再次打开设置页即可看到进度,完成后会显示结果(直到你关闭它)。大镜像会获得充足的删除时间,仍在删除中的镜像会如实标注,而不是报为失败
  • 带健康校验的更新 — 在丢弃被替换的旧容器之前,会对新容器进行多次轮询检查;restarting 会被视为崩溃重启循环而非成功,如果镜像自带 HEALTHCHECK 且尚未通过,旧容器会作为备份暂时保留,直到健康检查通过后再自动删除——即使关闭了备份保留也是如此
  • 安全备份 — docker-updater 创建的备份容器({name}_old)会自动把重启策略设为 no,避免主机重启后正式容器和备份同时启动;回滚时会恢复原始策略,若回滚需要撤销则会再次重置
  • 崩溃恢复 — 如果 docker-updater 在更新或回滚过程中重启,会在启动时协调遗留备份,并恢复任何被中断而处于停止状态的服务
  • 隐藏辅助容器 — docker-updater 在操作过程中创建的容器({name}_old 备份和 {name}_rollingback)不会出现在更新列表、镜像仓库检查和面板中
  • 多架构镜像 — 发布 linux/amd64 和 linux/arm64 镜像,可运行在 x86 服务器和树莓派等 ARM 设备上
  • 跳过本地构建镜像 — 由本地 Dockerfile 构建的镜像无法与镜像仓库比较,因此会被自动忽略。判定依据是「没有 RepoDigests、但仍保留着构建时使用的标签」,这样就不会把丢失了摘要的已拉取镜像误判为本地构建
  • 持久化状态 — 更新历史、暂缓决定和上次检查时间都会跨容器重启保留
  • 可切换主题的 UI — 面板包含“待更新 / 已暂缓 / 备份 / 已最新 / 未检查 / 全部 / 主机 / 设置”标签页,并提供 GitHub Dark、Midnight、Nord、Dracula、Carbon 和 Light 六种主题;主题立即生效,并可跨重启和更新保留

运行要求

  • Docker,并允许访问 /var/run/docker.sock
  • 可运行在 Synology DSM、Unraid、Proxmox 或任何运行 Docker 的 Linux 主机上
  • 提供多架构镜像(linux/amd64 + linux/arm64),支持 x86 主机和树莓派等 ARM 设备

快速开始

mkdir docker-updater && cd docker-updater
mkdir -p data

docker run -d \
  --name docker-updater \
  --restart unless-stopped \
  -p 9292:9090 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/data:/app/data \
  -e CHECK_TIME=03:00 \
  -e TIMEZONE=Australia/Melbourne \
  ghcr.io/liquidguru/docker-updater:latest

然后打开 http://<你的主机>:9292。页面会显示一条绿色横幅,其中包含自动生成的 ntfy 主题;在 ntfy 应用中订阅该主题即可接收推送通知。


docker-compose.yml

services:
  docker-updater:
    image: ghcr.io/liquidguru/docker-updater:latest
    container_name: docker-updater
    restart: unless-stopped
    ports:
      - "9292:9090"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
    environment:
      CHECK_TIME: "03:00"
      TIMEZONE: Australia/Melbourne
      NOTIFY_URL: ${NOTIFY_URL:-}
      DOCKER_HOST: unix:///var/run/docker.sock
      # 从与本 Compose 文件同目录的 .env 读取以下值。
      AUTH_USERNAME: ${AUTH_USERNAME:-}
      AUTH_PASSWORD: ${AUTH_PASSWORD:-}
      FLASK_SECRET_KEY: ${FLASK_SECRET_KEY:-}
      API_KEY: ${API_KEY:-}
      DOCKERHUB_USERNAME: ${DOCKERHUB_USERNAME:-}
      DOCKERHUB_TOKEN: ${DOCKERHUB_TOKEN:-}

保存为 docker-compose.yml,在同一目录创建 data/ 和可选的 .env 文件,然后运行 docker compose up -d。无需克隆仓库。

端口说明: 容器内部监听 9090 端口。主机绑定 9292:9090 可以避免与通常使用 9090 的 Prometheus 冲突;你可以根据环境修改主机端口。


配置

环境变量 默认值 说明
CHECK_TIME 03:00 检查计划的初始默认值。可以是每天执行的 HH:MM,也可以是完整的 5 段 cron 表达式,例如 0 3 * * 0 表示每周日执行,0 */6 * * * 表示每 6 小时执行。在“设置”标签页保存计划后,该计划会写入数据卷并优先于此变量,详见检查计划。
TIMEZONE Australia/Melbourne 计划检查所使用的时区,可以是任意 tz 数据库名称
NOTIFY_URL (自动) 用于推送通知的 Apprise URL。未设置时会自动生成唯一的私有 ntfy.sh 主题。
CHECK_UNRUNNING_IMAGES false 是否同时检查没有运行中容器使用的镜像的初始默认值——详见未使用的镜像。仅作提示;绝不会拉取任何内容。在设置中保存的选择优先。
GITHUB_WEBHOOK_SECRET (空) 验证 GitHub Webhook 签名的密钥。使用 GitHub 通知功能时必须配置。
AUTH_USERNAME (空) 面板登录用户名;必须同时设置 AUTH_PASSWORD 才会启用鉴权。
AUTH_PASSWORD (空) 面板登录密码;绝不会写入 state.json。
API_KEY (空) 可选的只读密钥,仅可用于 GET /api/status,这样仪表盘小组件无需持有管理员密码。需要已启用登录且至少 16 个字符;详见只读 API 密钥。
FLASK_SECRET_KEY (自动生成) 可选的会话签名密钥;省略时持久化到 /app/data/.secret_key。
DOCKERHUB_USERNAME (空) Docker Hub 用户名,用于对检查更新的请求进行认证以提高速率限制。必须同时设置 DOCKERHUB_TOKEN。
DOCKERHUB_TOKEN (空) Docker Hub 个人访问令牌(不是密码)。仅发送给 Docker Hub;绝不会写入 state.json。
DOCKER_HOST unix:///var/run/docker.sock Docker Socket 路径

主题

在 设置 → 外观 中可以选择六种主题:GitHub Dark(默认)、Midnight、Nord、Dracula、Carbon 和 Light。选择后立即生效,并保存到数据卷中的 state.json,因此容器重启和镜像更新后仍会保留。主题由服务端直接渲染,页面加载时不会先闪现旧主题。

所有主题中的状态色含义保持一致:绿色始终表示正常,红色始终表示问题。每个主题会单独调整这些颜色以保证对比度,例如 Light 主题使用更深的绿色和红色,使其在浅色背景上仍清晰可读。

添加自定义主题也很简单:每个主题都是 templates/index.html 中一个包含 11 个 CSS 变量的 [data-theme="..."] 块;界面中的半透明色调均通过 color-mix() 从这些变量生成。添加 CSS 块后,再把主题名称加入 app.py 的 THEMES 即可。


Docker Hub 速率限制

每次检查更新时,每个被跟踪的容器都会消耗一次 manifest 请求。Docker Hub 会按 IP 对匿名请求做速率限制(目前为每小时 100 次),因此容器数量较多、检查频率较高,或多台机器共用同一个出口 IP 时,都可能耗尽配额。配额耗尽后,检查会开始失败,而不是报告更新。

使用账号认证可以提高该限制。请在 Docker Hub → Account settings → Personal access tokens 创建一个个人访问令牌(只读权限即可,docker-updater 只会读取 manifest),然后设置:

DOCKERHUB_USERNAME=your-username
DOCKERHUB_TOKEN=dckr_pat_...

在启动日志中确认是否生效:

[registry] Docker Hub: authenticating as 'your-username'

如果显示 [registry] Docker Hub: anonymous ...,说明变量没有传入容器 —— 请注意 Compose 的 .env 文件只提供 ${VAR} 替换,变量还必须列在 environment: 下(上文的 Compose 示例已经包含)。

每次检查后都会记录剩余配额,配额较低时会给出警告:

[checker] Complete — 2 total update(s). Registry rate limit — registry-1.docker.io: 87/100 left.

补充说明:

  • 凭据只会发送给 Docker Hub。GHCR、LSCR 等其他仓库不受影响,它们通常也有宽松得多的限制。
  • 如果凭据被拒绝,docker-updater 会记录日志并回退到匿名检查,而不是直接失败。
  • 以上只涉及检查更新。实际的 docker pull 由 Docker 守护进程使用它自己的凭据执行,因此如果拉取镜像也遇到限流,请在宿主机上另外执行 docker login。

检查计划

可以直接在设置标签页配置 docker-updater 轮询镜像仓库的频率,无需编辑 Compose 文件或重启容器。

预设覆盖了常见使用场景,不需要了解 cron:

  • 每 6 小时 / 每 12 小时
  • 每天 — 选择具体时间
  • 每周 — 选择星期和时间
  • 每月 — 选择日期和时间
  • 自定义(cron) — 使用标准 5 段表达式(分 时 日 月 星期),例如 0 3 * * 0 表示每周日凌晨 3 点

修改会立即生效,同时显示下一次计划运行时间,方便确认配置已经应用。

计划保存位置。 在“设置”中选择的计划会保存到数据卷的 state.json,与更新历史和备份设置位于同一位置,因此可以跨容器重启、重建以及 docker-updater 自身镜像更新保留。CHECK_TIME 仅作为全新安装时的初始默认值;一旦从 UI 保存过计划,就会以保存的计划为准。启动日志会明确显示当前生效来源:

[scheduler] Check scheduled: '30 4 * * 0' (from settings) Australia/Melbourne (next run: 2026-07-20T04:30:00+10:00)

如果计划因某种原因无法解析,程序会回退到每天 03:00,而不会阻止容器启动。在设置中输入无效 cron 时,请求会被拒绝,当前有效计划不会受到影响。


多主机支持

docker-updater 可以通过一个面板管理多台 Docker 主机上的容器。打开主机标签页即可添加远程主机。

支持的连接类型

URL 格式 说明
ssh://user@host SSH — 使用系统中的 SSH 配置和密钥
ssh://user@host:port 使用非标准端口的 SSH
tcp://host:2376 TCP — 需要在远程主机上启用 Docker Remote API

添加主机

  1. 打开主机标签页
  2. 输入名称和 Docker URL
  3. 保存前点击测试连接
    • 对于 SSH 主机,首次测试会自动获取并保存远程主机密钥(Trust On First Use)。界面会显示 🔑 提示进行确认。之后的所有连接都会验证已保存的密钥,无需手动执行 ssh-keyscan。
  4. 点击添加主机,程序会立即执行一次检查

之后,所有主机上的容器会统一显示在“待更新 / 已暂缓 / 已最新”等标签页中,每个容器都会带有主机标识。主机标签页会显示每台主机的连接健康状态和上次检查时间。

SSH 主机密钥

已接受的主机密钥保存在数据卷中的 data/known_hosts,因此容器重启和升级后仍会自动保留。

如果希望自行管理 SSH 密钥,例如固定特定主机密钥或共享宿主机上的 known_hosts,可以把现有的 ~/.ssh 目录挂载到容器中:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - ./data:/app/data
  - ~/.ssh:/root/.ssh:ro   # 可选:挂载宿主机的 SSH 配置和密钥

挂载进来的配置文件不会被修改。 如果 ~/.ssh/config 已存在,docker-updater 会原样保留并直接使用;只有在该文件不存在时(即未挂载的默认情况)才会写入自己的配置。

由此带来的一个影响:SSH 将使用你自己配置中指定的 UserKnownHostsFile(若未指定则为 ~/.ssh/known_hosts),而不是 data/known_hosts。如果该路径是只读的,通过 测试连接 接受的主机密钥将无法保存;此时请确保你现有的 known_hosts 中已包含该主机,或在配置中加入:

Host *
    UserKnownHostsFile /app/data/known_hosts

启动日志会说明当前生效的是哪一种:

[ssh] Persistent known_hosts: /app/data/known_hosts     # 默认情况,使用我们写入的配置
[ssh] Using the existing /root/.ssh/config as-is (not overwritten).

推送通知

只有计划检查发现更新时才会发送推送通知。启动扫描和手动点击“立即检查”始终保持静默,因此重启容器不会向手机发送大量通知。

自动配置(默认)

如果没有设置 NOTIFY_URL,docker-updater 会在首次运行时生成一个唯一的私有主题,例如 ntfy.sh/du-a3f8c12b,并保存到 data/state.json。面板会显示一条带有复制按钮的绿色横幅;把主题粘贴到 ntfy 应用中订阅即可。订阅后可以关闭该横幅。

为什么使用唯一主题? ntfy.sh 主题默认公开,任何知道主题名称的人都可以读取消息。docker-updater 自动生成的是不会在其它位置发布的随机字符串,从而保护通知隐私。

仅通知新的更新

默认情况下,每次计划检查都会列出所有仍待处理的更新,所以尚未应用的更新每天都会重复提醒。开启设置 → 仅通知新的更新后,每个更新只会通知一次:之后的检查保持静默,直到出现新的更新;发出的通知只列出新的更新,并注明还有多少个之前已通知过、仍待处理的更新。

“新”指的是与上次通知你的镜像不同,因此即使你一直没处理某个更新,它发布了更新的版本时仍会再次提醒。已应用的更新如果之后再次出现,也会重新通知。已暂缓的更新仍不会出现在通知中,暂缓到期后会通知一次。更新按容器和主机分别记录在 data/state.json 中;如果通知发送失败,会在下次检查时重试。开启该选项不会重复通知已知的更新。该选项默认关闭,不手动开启则行为不变。

自定义通知

将 NOTIFY_URL 设置为任意 Apprise 兼容 URL:

ntfy://ntfy.sh/my-private-topic
discord://webhookid/webhooktoken
slack://tokenA/tokenB/tokenC

GitHub 通知(可选)

docker-updater 可以接收 GitHub Webhook 事件,并将其转发为推送通知,包括所有仓库中的新 Issue、PR、Star、Push 和 Release。

配置方法

  1. 为容器添加 GITHUB_WEBHOOK_SECRET,并使用随机密钥:

    openssl rand -hex 32
    
  2. 让外网能够访问 docker-updater,例如使用 Cloudflare Tunnel 或反向代理。

  3. 在每个 GitHub 仓库中注册 Webhook:

    • 打开 Settings → Webhooks → Add webhook
    • Payload URL:https://your-host/webhook/github
    • Content type:application/json
    • Secret:步骤 1 中的密钥
    • Events:选择需要的事件(Issue、PR、Push、Star、Release)

    也可以通过 GitHub API 一次性为所有仓库注册:

    TOKEN="your-github-token"
    SECRET="your-webhook-secret"
    URL="https://your-host/webhook/github"
    curl -s -X POST \
      -H "Authorization: token $TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"name\":\"web\",\"active\":true,\"events\":[\"issues\",\"pull_request\",\"watch\",\"push\",\"release\",\"issue_comment\"],\"config\":{\"url\":\"$URL\",\"content_type\":\"json\",\"secret\":\"$SECRET\"}}" \
      https://api.github.com/repos/YOUR_USERNAME/REPO_NAME/hooks
    

支持的事件

事件 通知
Issue 创建 🐛 新 Issue — 仓库名
Issue 关闭 ✅ Issue 已关闭 — 仓库名
PR 创建 🔀 新 PR — 仓库名
PR 合并 ✅ PR 已合并 — 仓库名
Star ⭐ 新 Star — 仓库名
推送到 main/master 📦 推送到 main — 仓库名
Release 发布 🚀 新版本发布 — 仓库名
Issue 评论 💬 新评论 — 仓库名

工作原理

  1. 启动时会静默扫描,并在配置的 CHECK_TIME 到达时遍历所有正在运行的容器
  2. 对每个容器,从 RepoDigests 中提取对应的本地镜像摘要 —— 读取的是容器实际正在运行的那个镜像,而不是标签当前指向的镜像,因此外部拉取导致标签前移、容器却未重建时,比较结果依然正确
  3. 向镜像仓库发送 HEAD 请求获取 Manifest,并读取响应头中的 Docker-Content-Digest,整个过程不会传输镜像数据
  4. 对于多架构镜像,如果摘要不同,会继续检查当前平台的 Manifest/Config 摘要,避免只有镜像索引变化时产生错误更新提示
  5. 如果正在运行的镜像完全没有 RepoDigests(标签被外部拉取前移后遗留下来的镜像,既没有标签也没有摘要),则改为比较镜像 ID,通过解析当前平台的 Manifest Config 摘要来获取
  6. 只有当前平台的本地镜像确实与镜像仓库中的最新镜像不同时,容器才会被标记为存在更新
  7. 点击更新后,程序会:
    • 拉取新镜像,并把进度实时输出到日志弹窗,同时在容器卡片上显示实时状态
    • 停止旧容器并重命名为 {name}_old,作为回滚目标
    • 使用 Docker SDK 底层 API 按 Watchtower 模式,以完全相同的配置创建并启动新容器
    • 通过 NetworkConnect 重新连接所有网络,保留静态 IP、别名和 iptables 配置
    • 等待 2 秒,并检查新容器是否仍在运行
    • 成功时:删除 _old 容器;如果启用了备份保留,则在配置的时间内继续保留,以便之后回滚。如果健康检查尚未确认,_old 容器会一直保留到新容器报告健康后再删除(每 15 分钟检查一次,远程主机同样适用);若新容器报告 unhealthy,则保留备份,详见备份与回滚
    • 失败时:删除启动失败的新容器,把 _old 改回原名称,并重新启动旧版本

容器状态,包括更新可用性、暂缓决定、历史记录和备份,都会保存到 data/state.json。


未使用的镜像(可选)

默认情况下,docker-updater 只检查正在运行的容器。开启设置 → 同时检查没有容器在使用的镜像(或启动时设置 CHECK_UNRUNNING_IMAGES=true 作为初始默认值——在设置中保存的选择优先),它还会把每台主机上存放的、没有运行中容器使用的带标签镜像与镜像仓库进行比对。

镜像页 — 有新版本的未使用镜像,每个都附带可自行运行的 docker pull 命令

它默认关闭,关闭时不留任何痕迹:不会扫描、不会存储,面板上也不会出现“镜像”页或任何暗示该功能存在的内容(设置页里的开关本身除外)。再次关闭会删除它所存储的数据。

它绝不会拉取任何内容。 镜像页列出每个镜像及其状态,有新版本时会显示 docker pull 命令,由你自己运行——这里特意不提供按钮。很久没运行的镜像可能属于带有数据的服务(例如数据库),新版本可能无法读取旧版本写入的数据。请先阅读发行说明并备份数据。

检查范围:

  • 只检查带标签、来自镜像仓库的镜像。无标签镜像(每次更新都会留下的旧镜像)和本地构建的镜像会被跳过。
  • 正在运行的容器所使用的镜像由常规检查负责,因此不会重复出现。只被已停止容器保留的镜像算作未使用。
  • 你添加的每台主机,而不只是本机。

有新版本的未使用镜像会被加入定时检查的推送通知,并标注“(未使用的镜像)”,同样遵循仅通知新的更新。每个镜像都需要一次仓库查询,因此镜像很多的主机检查会明显变慢——测试中 32 个镜像约用了 70 秒——这些查询也会计入 Docker Hub 速率限制。


镜像拉取进度 API

GET /api/pulls 返回本应用发起且当前正在进行的所有镜像拉取,包括远程主机更新和自更新。它与其他 API 使用相同的会话鉴权(启用鉴权时请先登录)。更新期间可以轮询此接口:

{
  "pulls": [
    {
      "id": "web",
      "image": "nginx:latest",
      "container": "web",
      "host_id": "local",
      "started_at": "2026-10-16T17:00:00Z",
      "progress_bytes": 5242880,
      "total_bytes": 10485760,
      "percent_complete": 50.0,
      "total_estimated": false,
      "phase": "downloading",
      "layers_done": 3,
      "layers_total": 8
    }
  ]
}

progress_bytes 汇总 Docker 为每个镜像层报告的最新下载字节数,不会重复累加进度事件或解压字节。已缓存的层需要下载零字节。Docker 只有在某一层开始下载时才会报告它的大小,而且一次只下载几层,所以事件流要等到最后一层开始才能给出总量——对大型镜像来说,这已经是传输过程的一半以上。为避免进度条长时间空白,total_bytes 起初使用更新检查已从镜像仓库算出的压缩下载大小(只包含本机没有的层),此时 total_estimated 为 true;一旦 Docker 报告了所有层,事件流自己的总量会取而代之,total_estimated 变为 false。在其为 true 期间,percent_complete 不会超过 99,因此估算值不会宣称下载已完成。如果没有估算值——该容器尚未检查过、无法读取镜像仓库,或镜像已因其他容器先拉取了同一标签而存在于本机——则在 Docker 报告所有层之前,total_bytes 和 percent_complete 为 null(已是最新的镜像不会报告任何层)。完全缓存的拉取可能显示总量零字节且进度为 100%,若 Docker 不报告层信息则仍为未知。100% 仅表示已报告的下载字节完成,不代表解压或容器重建已完成。phase 说明当前实际所处的阶段:starting(Docker 尚未报告任何层)、downloading(至少还有一层在排队或下载中)、extracting(已无内容需要下载,但仍在解压各层)、finishing(所有层均已完成,或镜像本来就是最新的)。解压大型镜像可能比下载耗时长得多,因此在较慢的磁盘上,条目可能在 extracting 阶段以 100% 停留数分钟。解压没有字节数可统计,所以 layers_done 和 layers_total 给出了唯一真实的进度:Docker 目前已报告的各层中,有多少已完全解压(本机已有的层视为已完成)。下载过程中 layers_total 仍可能增加,因此只有当 phase 为 extracting 时它才有意义;面板此时显示为“正在解压镜像 · 已完成 3 / 8 层”。某一个大层可能占去大部分时间,所以临近结束时该计数可能会停留一阵子。

拉取在 Docker 请求开始前出现,在流结束、失败或取消后立即移除,不会保留到容器重建阶段。没有进行中的拉取时返回 {"pulls": []}。本地主机的 ID 为容器名,远程主机为 host_id:container;同一镜像的不同更新会分别列出。跟踪数据仅保存在本应用进程的内存中,重启后清空,不包含其他工具或直接执行 Docker 命令发起的拉取。面板上的更新卡片使用同一个接口来显示实时下载状态。同时运行多个更新时,Docker 在所有更新之间一次只下载几个镜像层,因此部分更新可能停在 0%,直到有空位——这是在排队,不是卡住。


备份与回滚

docker-updater 为每次更新提供两层安全保护。

失败时自动回滚(始终启用)

重建容器前,旧容器会被重命名为 {name}_old。如果新容器启动失败,docker-updater 会删除新容器,把旧容器恢复为原名称并重新启动。因此,一次损坏的更新不会让服务永久离线,旧版本会自动恢复。

为“启动正常但实际有问题”的更新保留备份(可选)

有些新镜像看似启动完全正常,但过一段时间后才会发现实际问题,例如功能回归、错误发布、默认值变化或端口被移除。上面的自动回滚无法发现这些问题,因为从 Docker 的角度看,容器已经成功启动。

为了进一步降低风险,可以在设置标签页启用更新成功后保留备份。启用后,更新“成功”时不会立即删除旧容器,而是将其保持停止状态并保留指定时间,默认 24 小时。如果之后发现问题,打开备份标签页并点击回滚,即可立刻恢复旧版本,即使此前的更新被判定为成功。如果提前确认不再需要备份,可以点击删除备份释放磁盘空间。

备份会自动维护:每条记录都会与实际的 _old 容器核对,过期或孤立的记录会自动清理,因此备份标签页始终反映真实状态。

备份容器创建后会立即把重启策略设为 no,避免主机重启时正式容器和备份同时启动,从而造成端口冲突或重复进程。原始重启策略会被保存,并在回滚时自动恢复。

⚠️ 回滚只恢复容器,不恢复数据

回滚会把容器恢复为上一版本的镜像和配置,但不会还原容器卷或绑定挂载中的任何内容——这些位置会保留新版本写入的所有数据。

这对于首次启动时会迁移数据的应用尤为重要。Homarr、Sonarr/Radarr、Immich、Nextcloud 等许多应用会就地升级其数据库结构,因此在此之后回滚,旧版本可能无法启动:它读不了新版本已经转换过的数据。

  • 更新这类应用之前,请先备份其数据——停止应用后复制其数据目录,或使用应用自带的备份功能。docker-updater 无法安全地替你完成这一步,因为在应用运行时复制正在使用的数据库,可能得到损坏的副本。
  • 如果回滚后应用无法启动,请从该备份恢复数据,然后再次启动。

回滚对话框会列出不会被还原的可写挂载,让你在确认之前清楚了解风险。

崩溃安全(启动恢复)

更新和回滚在后台线程中运行。如果 docker-updater 在操作进行中重启,例如手动重启、主机重启,甚至 docker-updater 自身更新,该线程会被中途终止,原本可能导致容器更新不完整或处于停止状态。

为避免这种情况,docker-updater 每次启动时都会扫描遗留的 {name}_old 备份容器,并逐一协调:

  • 新容器正在运行 → 保留新容器;如果启用了备份保留则继续保存备份,否则清理备份。
  • 正式容器不存在或未运行 → 自动从备份恢复旧版本并启动。

因此,被中断的操作会在下次启动时自动修复,而不会让服务持续离线。


更新说明查看器

待更新和已暂缓的容器卡片会显示更新说明按钮,从 GitHub Releases API 获取最近 5 个 Release,并使用基础 Markdown 格式内嵌显示。识别分为三个层级:

  1. OCI 来源标签 — 使用 org.opencontainers.image.source 标签指向 GitHub 仓库的镜像可自动工作。大多数维护良好的镜像都包含此标签,例如 Home Assistant、Homarr、Vaultwarden、Calibre-Web 和所有 LinuxServer 镜像。
  2. GHCR 镜像 — 托管在 ghcr.io 的任何镜像,例如 ghcr.io/owner/repo:tag,都会自动识别,因为 GHCR 名称可以直接映射到 GitHub 仓库。
  3. 手动覆盖 — 其它镜像会显示“设置更新说明来源…”链接。点击后会打开弹窗,并根据镜像名称预填推测的 GitHub URL,例如 owner/image → github.com/owner/image,官方镜像 redis → github.com/redis/redis。确认或修正后保存,“更新说明”按钮会立即替换原提示,URL 会持久化到 data/state.json。

从源码构建

如果希望进行开发或运行尚未提交的最新改动:

git clone https://github.com/liquidguru/docker-updater.git
cd docker-updater
mkdir -p data
docker compose up -d   # 使用仓库中的 build: . Compose 配置

提交 PR 前请先运行测试:

python -m unittest discover -s tests -v
node --check static/i18n.js

替换 Watchtower

如果正在使用 Watchtower,请先确认 docker-updater 工作正常,然后停止并删除 Watchtower:

docker stop watchtower
docker rm watchtower

注意事项

  • Docker Compose 栈:更新通过 Docker SDK 重建单个容器,不会修改容器对应的 docker-compose.yml。之后再次运行 docker compose up 时,Compose 会识别新镜像并正常工作,但 Compose 文件中的镜像标签不会被修改。可以选择在更新后重启同一栈的其它成员,使它们重新获取新容器的 IP(设置 → 更新后重启同一 Compose 栈的其它容器)。
  • 命名卷:自动保留。绑定挂载(HostConfig.Binds)和命名卷/--mount 卷(HostConfig.Mounts,Compose 在此保存挂载)都会在重建时重新连接。
  • 重建时保留的设置:自 v1.16.3 起,重建会复制 Docker 为该容器报告的完整主机配置(资源限制、GPU/设备请求、日志选项、ulimits、sysctls、只读根文件系统(read-only)、--init、shm-size、附加用户组、非默认 runtime 等),只有挂载、端口、网络和重启策略由 docker-updater 自行设置。终端和 stdin 标志,以及停止信号和超时也会沿用。不会沿用的:覆盖镜像自带检查的容器级 healthcheck。更早的版本只复制固定列表,其余设置在每次更新时都会丢失,例如需要 GPU 的容器更新后可能无法启动。
  • 本地构建镜像:由本地 Dockerfile 构建的镜像无法与镜像仓库比较,因此会被跳过。判定依据是「没有 RepoDigests、但仍保留着构建时使用的标签」—— 曾经拉取过、后来丢失了摘要的镜像(见下条)不会被跳过。
  • 被外部拉取遗留的镜像:如果其它工具或手动执行的 docker pull 拉取了容器正在使用的标签,标签会指向新镜像,而容器仍在运行旧镜像。根据镜像存储方式的不同,这个遗留镜像可能既没有标签也没有摘要。此时 docker-updater 会改为比较镜像 ID,因此容器仍会被正常标记,而不会被悄悄忽略。
  • 私有镜像仓库:支持匿名和 Bearer Token 镜像仓库,以及已认证的 Docker Hub(参见 Docker Hub 速率限制)。暂不支持为其他镜像仓库配置凭据 —— 如有需要,请提交 issue 并说明是哪个仓库。
  • 新版本破坏性变更:docker-updater 会保留容器原有的环境变量,但无法判断新镜像版本是否增加了新的必需环境变量。如果容器因此崩溃,会被检测到并自动回滚;但如果镜像能够正常启动、只是在应用层出现问题,则仍会通过健康检查,因此请查看镜像 Release Notes,确认是否新增了必需环境变量。
  • 回滚不会恢复数据:回滚会恢复容器和镜像,但卷和绑定挂载会保留新版本写入的内容。如果新版本在首次启动时迁移了数据,旧版本可能根本无法启动。更新会迁移数据的应用之前,请先备份其数据,详见备份与回滚。
  • 健康检查较为表层:判断新容器是否正常,依据的是它的 Docker 状态(以及镜像自带的 HEALTHCHECK,如果有的话),而不是测试你的服务是否真正可用。一个进程正常运行、但持续返回错误的容器,与健康容器无法区分。如果镜像的健康检查需要较长时间才能通过(大多需要 10–60 秒,而更新过程只观察几秒钟),更新仍会生效,旧容器会暂时保留,直到健康检查通过后再删除;如果报告 unhealthy,则保留备份,方便你回滚。
  • Host 网络模式:使用 --network host 的容器可以正确重建,此类容器会跳过网络重新连接步骤。
  • 备份保留与磁盘空间:启用备份保留后,每个备份都会保留一个已停止容器及旧镜像层,直到备份过期或在“备份”标签页中手动删除。磁盘空间有限时,请缩短保留时间,或在确认更新稳定后及时删除备份。另需注意:当新容器的健康状态无法确认时,即使关闭了备份保留,旧容器仍会被保留 —— 这是有意为之,以便始终有回退路径 —— 因此偶尔会出现你并未主动要求的 _old 容器。它会显示在“备份”标签页中,并按正常的过期时间清理。

许可证

MIT。如需报告安全问题,请参阅 SECURITY.md。

致谢

由 liquidguru 开发,并使用 AI 编程工具(Anthropic Claude 和 Codex)辅助。所有改动在发布前都会经过审核和测试;由 AI 辅助完成的提交会带有 Co-Authored-By 尾注。