通过 Docker 容器标签自动创建 Uptime Kuma 监控，免去手动配置

方案简介

AutoKuma 是一个自动化工具，用于根据 Docker 容器标签自动在 Uptime Kuma 中创建监控项，从而免除在 Uptime Kuma UI 中手动创建监控的需要。

该方案适合使用 Uptime Kuma 做可用性监控、同时用 Docker 管理服务的运维/自托管用户：只需在容器上添加约定格式的标签，AutoKuma 就会自动感知并在 Uptime Kuma 中生成对应监控，实现「基础设施即配置」的监控自动化。除 Docker 外，还支持从 ./.toml 文件、Docker Swarm 服务标签、Kubernetes CRD 等来源读取监控配置。

组成与分工

• AutoKuma：核心工具，监听监控来源（容器标签/文件等）并自动在 Uptime Kuma 中创建监控
• Uptime Kuma：开源可用性监控平台，作为监控的目标系统，AutoKuma 通过其 URL 与账号对接
• Docker：监控配置的来源之一，容器标签即监控定义；AutoKuma 需挂载 docker.sock
• Docker Compose：推荐的快速部署方式，一条 compose 文件即可拉起 AutoKuma
• Kuma CLI：命令行工具，可直接在终端管理 Uptime Kuma 的各类资源
• Kuma Client：Rust crate 客户端库，封装 Uptime Kuma 的 SocketIO API

实施步骤

最快的上手方式是使用 Docker Compose。

1. 编写 docker-compose.yml

yaml
version: '3'

services:
autokuma:
image: ghcr.io/bigboot/autokuma:latest
restart: unless-stopped
environment:
AUTOKUMA__KUMA__URL: http://uptime-kuma:3001
AUTOKUMA__KUMA__USERNAME:
AUTOKUMA__KUMA__PASSWORD:
volumes:

• /var/run/docker.sock:/var/run/docker.sock
• autokuma-data:/data

volumes:
autokuma-data:

2. 为需要监控的容器添加标签

yaml
labels:
kuma.my-app.http.name: "My App"
kuma.my-app.http.url: "https://my-app.example.com"

AutoKuma 会自动拾取标签并在 Uptime Kuma 中创建监控。

3. 最小配置

至少需要将 AutoKuma 指向你的 Uptime Kuma 实例：

bash
AUTOKUMA__KUMA__URL=http://localhost:3001
AUTOKUMA__KUMA__USERNAME=
AUTOKUMA__KUMA__PASSWORD=

使用与配置要点

标签遵循如下格式：

...:

• - 默认为 kuma，可通过 AUTOKUMA__DOCKER__LABEL_PREFIX 配置。
• - 监控项的唯一标识。
• - 监控类型（如 http、ping、dns）。
• - 要设置的属性。

验证方式：为容器添加标签后，AutoKuma 会自动在 Uptime Kuma 中创建对应监控，可在 Uptime Kuma UI 中确认监控项已生成。完整配置参考（TLS、Docker host 选项、secret 文件、配置文件位置）见官方 Configuration 文档。

注意事项与常见问题

• Docker Swarm 与 Kubernetes 来源属于 as-is 支持，作者目前并未运行这些环境，它们「基本上在寻找维护者」；如愿意接管或新增来源支持可以联系作者。
• Kubernetes 场景下使用 CRD（见 autokuma/kubernetes/crds-autokuma.yml），且视部署方式可能还需要 Files 和 Docker provider 配合。

优缺点

• ✓ 免去 UI 手动创建监控
• ✓ 支持 Docker/Swarm/K8s/
• ✕ Swarm/K8s 支持仅为 as-is

出处

本方案挖掘自开源项目 BigBoot/AutoKuma，方案内容与实施命令均来自其 README 原文。