Watchtower HTTP API 模式指南：用 `/v1/update` 按需触发容器镜像更新

Watchtower HTTP API 模式指南用/v1/update按需触发容器镜像更新【免费下载链接】watchtowerA process for automating Docker container base image updates.项目地址: https://gitcode.com/gh_mirrors/wa/watchtower本指南讲解 Watchtower 的 HTTP API 模式通过--http-api-update启动一个 HTTP 端点用带 Token 鉴权的请求按需触发容器镜像更新而非依赖周期轮询。文章覆盖完整的 Docker Compose 部署示例、WATCHTOWER_HTTP_API_TOKEN鉴权机制、按镜像名定向更新的image查询参数用法并结合 pkg/api 与 pkg/api/update 源码深入剖析 Token 校验、并发更新锁与过滤链的底层实现读完即可在生产环境中落地一套更新由你掌控的 Watchtower 部署。为什么需要 HTTP API 模式默认情况下Watchtower 会按照--interval轮询间隔默认 86400 秒即 24 小时或--schedulecron 表达式周期性地扫描并更新镜像。但在某些场景下你并不希望 Watchtower 自作主张地按时拉取新镜像而是希望在合适的时间点例如维护窗口、发版之后手动触发一次更新。HTTP API 模式正是为此设计启用后Watchtower 暴露一个 HTTP 端点由外部请求来触发更新。该模式与 运行多个实例、监控指标 等功能互相独立可以按需组合使用。启用 HTTP API 模式在启动 Watchtower 时加上--http-api-update标志即可启用该模式对应的环境变量为WATCHTOWER_HTTP_API_UPDATE。以下是一个完整的 docker-compose.yml 示例原样取自 docs/http-api-mode.mdversion: 3 services: app-monitored-by-watchtower: image: myapps/monitored-by-watchtower labels: - com.centurylinklabs.watchtower.enabletrue watchtower: image: containrrr/watchtower volumes: - /var/run/docker.sock:/var/run/docker.sock command: --debug --http-api-update environment: - WATCHTOWER_HTTP_API_TOKENmytoken labels: - com.centurylinklabs.watchtower.enablefalse ports: - 8080:8080这个示例包含几个值得注意的要点挂载 Docker 套接字/var/run/docker.sock:/var/run/docker.sock是 Watchtower 与 Docker 守护进程通信的前提没有它 Watchtower 无法管理任何容器。标签控制监控范围被监控的应用容器打了com.centurylinklabs.watchtower.enabletrue标签而 Watchtower 自身容器打了com.centurylinklabs.watchtower.enablefalse避免看门人更新自己造成循环。在 internal/flags/flags.go 中--label-enableWATCHTOWER_LABEL_ENABLE控制是否只监控打了 enable 标签的容器而com.centurylinklabs.watchtower.enablefalse的排除逻辑则由 pkg/filters/filters.go 中的FilterByDisabledLabel实现。端口映射8080:8080把 Watchtower 内置 HTTP 服务的 8080 端口暴露到宿主机从而可以通过localhost:8080访问。相关的三个核心标志在 internal/flags/flags.go 中可以看到 HTTP API 模式相关的三个标志及其环境变量对应关系命令行标志环境变量类型作用--http-api-updateWATCHTOWER_HTTP_API_UPDATEBoolean启用 HTTP API 模式镜像更新必须由 HTTP 请求触发--http-api-tokenWATCHTOWER_HTTP_API_TOKENString为 HTTP API 请求设置鉴权 Token--http-api-periodic-pollsWATCHTOWER_HTTP_API_PERIODIC_POLLSBoolean在启用 HTTP API 的同时仍然保留--interval/--schedule指定的周期轮询需要说明的是HTTP API 模式默认会阻止周期轮询。也就是说仅启用--http-api-update后--interval或--schedule配置的定时更新不会生效更新只能通过请求触发。如果你希望两者共存——既允许手动触发也保留定时自动更新——需要额外传递--http-api-periodic-polls。从 cmd/root.go 的启动流程可以验证这一行为unblockHTTPAPI变量来自--http-api-periodic-polls只有它为真时调度器runUpgradesOnSchedule才会继续按计划运行否则 Watchtower 会手动写出启动消息Periodic runs are not enabled.并让 HTTP 服务以阻塞方式独占进程httpAPI.Start(enableUpdateAPI !unblockHTTPAPI)。Token 鉴权防止外部服务误触发更新为了让外部服务无法误触更新所有 HTTP API 请求都必须在请求头中携带名为Authorization、格式为Bearer token的字段其中token的值必须与WATCHTOWER_HTTP_API_TOKEN或--http-api-token定义的一致。上述示例中的鉴权请求如下原样取自 docs/http-api-mode.mdcurl -H Authorization: Bearer mytoken localhost:8080/v1/update鉴权中间件的源码实现Token 校验由 pkg/api/api.go 中的RequireToken中间件完成func (api *API) RequireToken(fn http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { auth : r.Header.Get(Authorization) want : fmt.Sprintf(Bearer %s, api.Token) if auth ! want { w.WriteHeader(http.StatusUnauthorized) return } log.Debug(Valid token found.) fn(w, r) } }关键实现细节校验方式是精确字符串比对请求头中的Authorization值必须严格等于Bearer Token任何多余或缺失的空格、大小写差异都会导致校验失败。校验失败时直接返回401 Unauthorized不会执行后续的更新逻辑。这一点在 pkg/api/api_test.go 中有对应的单元测试覆盖未提供 Token 时返回 401、Token 无效时返回 401、Token 有效时返回 200。所有注册到 API 的路由都会经过RequireToken包装RegisterFunc与RegisterHandlerpkg/api/api.go在注册时即套上鉴权中间件同时将hasHandlers置为 true作为后续是否真正启动 HTTP 服务的依据。Token 为空时的行为在 pkg/api/api.go 的Start方法中如果已注册处理器但api.Token为空Watchtower 会直接以log.Fatal退出错误信息为api token is empty or has not been set. exiting也就是说HTTP API 模式强制要求配置 Token防止出现裸奔的无鉴权端点。这从设计层面保证了暴露到宿主机的 8080 端口不会成为任何人都能触发的更新开关。通过文件提供 Token推荐做法Token 属于敏感信息直接写进 docker-compose.yml 或命令行会留下明文痕迹。在 docs/arguments.md 的 Secrets/Files 一节中Watchtower 支持让http-api-token引用一个文件取文件内容作为实际 Tokensecrets: access_token: file: access_token services: watchtower: secrets: - access_token environment: - WATCHTOWER_HTTP_API_TOKEN/run/secrets/access_token其底层实现位于 internal/flags/flags.go 的GetSecretsFromFiles启动时PreRun阶段见 cmd/root.go会检测http-api-token的值是否指向一个真实存在的文件若是则读取文件内容去除首尾空白替换原值。支持该文件引用机制的参数还包括notification-url、notification-email-server-password、notification-slack-hook-url、notification-msteams-hook、notification-gotify-token。端点一览/v1/update启用 HTTP API 模式后当前可用的端点列表如下端点方法作用/v1/updateHTTPGET/POST 均可文档示例用 GET触发本 Watchtower 实例监控的所有容器的更新在 pkg/api/update/update.go 中该端点的路径被定义为常量Path: /v1/update并在 cmd/root.go 中注册updateHandler : update.New(func(images []string) { metric : runUpdatesWithNotifications(filters.FilterByImage(images, filter)) metrics.RegisterScan(metric) }, updateLock) httpAPI.RegisterFunc(updateHandler.Path, updateHandler.Handle)当请求到达时处理函数Handle会记录日志 Updates triggered by HTTP API request.解析 URL 中的image查询参数详见下一节获取更新锁确保同一时刻只有一个更新任务在运行调用更新回调走与定时轮询完全相同的actions.Update更新流水线包括拉取镜像、重建/重启容器、发送通知等。更新锁防止并发触发互相冲突HTTP 触发与定时轮询共享同一把更新锁updateLock见 cmd/root.go这一点在注释中写得很明确The lock is shared between the scheduler and the HTTP API. It only allows one update to run at a time.在 pkg/api/update/update.go 中可以看到两种不同的锁行为指定了镜像列表len(images) 0阻塞等待锁即使当前已有更新在运行也会排队等它完成后再执行本次定向更新未指定镜像列表使用非阻塞的selectdefault如果另一场更新正在进行本次请求会被跳过并记录Skipped. Another update already running.的调试日志避免重复触发全量更新。定时调度侧cmd/root.go也采用同样的锁策略因此 HTTP 请求与 cron 任务之间不会出现两场更新同时操作同一批容器的竞态。定向更新通过image查询参数指定镜像如果不加任何参数/v1/update会更新该实例监控的所有容器。若只想更新特定的某些镜像可以在 URL 中以查询参数image提供镜像名多个镜像名用英文逗号分隔curl -H Authorization: Bearer mytoken localhost:8080/v1/update?imagefoo/bar,foo/baz上述命令会仅触发foo/bar与foo/baz两个镜像的更新示例原样取自 docs/http-api-mode.md。查询参数解析与过滤链解析逻辑在 pkg/api/update/update.go从r.URL.Query()[image]取出所有image参数值再对每个值按逗号,切分从而支持多个参数值 逗号分隔的两种写法。切分出的镜像列表随后进入 pkg/filters/filters.go 的FilterByImage过滤链func FilterByImage(images []string, baseFilter t.Filter) t.Filter { if images nil { return baseFilter } return func(c t.FilterableContainer) bool { image : strings.Split(c.ImageName(), :)[0] for _, targetImage : range images { if image targetImage { return baseFilter(c) } } return false } }实现要点镜像名会先去掉:之后的 tag 部分例如foo/bar:latest会被归一化为foo/bar再与请求中的目标镜像名做精确匹配该过滤是叠加在基础过滤链之上的即使请求中指定了imagefoo/bar最终仍会受到启动参数如--label-enable、--disable-containers、--scope等以及容器上com.centurylinklabs.watchtower.enablefalse标签的约束只有既匹配请求的镜像名、又通过基础过滤链的容器才会被更新未指定image参数时images为nilFilterByImage直接返回基础过滤链即更新所有被监控容器。与周期轮询、监控指标等其他模式的组合HTTP API 模式可以与 Watchtower 的其他标志自由组合常见的搭配包括--http-api-update --http-api-periodic-polls手动触发与定时更新共存。此时 HTTP 服务与 cron 调度器并行运行并通过共享更新锁保证互斥。--http-api-update --http-api-metrics同时启用更新 API 与 Prometheus 指标端点。--http-api-metricsWATCHTOWER_HTTP_API_METRICS在 internal/flags/flags.go 中定义其端点注册与使用说明见 pkg/api/metrics 与 监控指标指南。--http-api-update --interval 300或--schedule注意仅当同时设置--http-api-periodic-polls时这里的间隔/计划才会生效否则 HTTP API 模式会按前述规则阻止周期轮询。--http-api-update --scope结合 运行多个实例 的 scope 机制让不同的 Watchtower 实例分别监听不同的容器集合并通过各自的 HTTP 端点独立触发更新。部署形态请求触发 vs. 阻塞运行从 cmd/root.go 可以看到HTTP 服务的启动方式取决于是否启用周期轮询仅 HTTP API无周期轮询httpAPI.Start(true)以阻塞方式运行 HTTP 服务此时 Watchtower 进程的生命周期就是 HTTP 服务的生命周期调度器不会启动HTTP API 周期轮询httpAPI.Start(false)在 goroutine 中启动 HTTP 服务随后进入正常的调度循环等待 SIGINT/SIGTERM 信号后优雅退出。无论哪种形态HTTP 服务都固定监听:8080端口pkg/api/api.go 中的http.ListenAndServe(:8080, nil)。源码注释// TODO: make listen port configurable表明端口目前尚不可配置部署时若宿主机 8080 已被占用需要通过端口映射如9080:8080来规避。快速验证与故障排查启用后可通过以下方式快速验证不带 Token 访问curl localhost:8080/v1/update应返回401HTTP 状态码说明鉴权生效Token 错误curl -H Authorization: Bearer wrong localhost:8080/v1/update同样返回401可对照 pkg/api/api_test.go 的测试用例Token 正确curl -H Authorization: Bearer mytoken localhost:8080/v1/update应触发更新并在 Watchtower 日志中看到Updates triggered by HTTP API request.与随后的会话摘要Session done含 Scanned/Updated/Failed 计数查看启动日志启用--debug后启动时会输出The HTTP API is enabled at :8080.见 cmd/root.go 的writeStartupMessage若该行未出现请确认--http-api-update与WATCHTOWER_HTTP_API_TOKEN均已正确设置。常见问题与对应检查项现象可能原因排查方向启动即退出日志报api token is empty or has not been set. exiting未设置 Token配置WATCHTOWER_HTTP_API_TOKEN或--http-api-token请求返回 401Token 值不匹配或请求头格式错误确认Authorization: Bearer token的精确格式请求成功但容器未更新容器不在监控范围被标签/参数过滤检查com.centurylinklabs.watchtower.enable标签与过滤参数请求无响应效果日志出现Skipped. Another update already running.另一场更新正在进行未指定 image 时稍后重试或通过image参数指定镜像排队更新设置了--interval却从不自动更新未启用--http-api-periodic-polls补上该标志或WATCHTOWER_HTTP_API_PERIODIC_POLLStrue小结Watchtower 的 HTTP API 模式将何时更新的决定权从定时器交还到调用方手中--http-api-update启用端点WATCHTOWER_HTTP_API_TOKEN提供强制鉴权/v1/update支持全量触发与image参数定向触发--http-api-periodic-polls则允许手动与定时两种方式共存。从 pkg/api/api.go 的 Token 中间件、pkg/api/update/update.go 的并发锁与参数解析到 cmd/root.go 中与调度器共享的更新锁整个机制在源码层面环环相扣既安全强制鉴权、杜绝并发冲突又灵活按需全量或定向更新适合作为 CI/CD 流水线或运维脚本中按需升级镜像的标准入口。【免费下载链接】watchtowerA process for automating Docker container base image updates.项目地址: https://gitcode.com/gh_mirrors/wa/watchtower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考