1. 项目概述为什么你需要一个自己的站点监控工具在运维和开发的世界里服务挂了用户先知道这绝对是最尴尬也最要命的事情之一。你可能经历过半夜被电话吵醒或者早上打开手机看到一堆用户投诉才发现自己的网站、API或者数据库已经悄无声息地宕机了几个小时。传统的解决方案要么是依赖云服务商昂贵的监控套餐要么就是自己写脚本前者成本高、灵活性差后者维护起来又是个无底洞。这时候一个轻量、自托管、功能全面且界面友好的监控工具就成了刚需。Uptime Kuma 正是在这个背景下脱颖而出的。它是一款开源的、自托管的站点监控工具核心目标就一个让你用最简单的方式知道你的服务是不是还“活着”。它不仅能监控 HTTP/HTTPS 服务还支持监控 TCP 端口、Ping、DNS 记录、推送通知比如通过 Telegram、Discord、企业微信等甚至能监控 Docker 容器和特定关键词。最关键的是它提供了一个非常直观的 Web 仪表盘所有监控状态一目了然。我最初接触 Uptime Kuma 是因为需要监控几个内部服务和边缘节点云监控的成本让我望而却步。在尝试了多个方案后Uptime Kuma 以其极低的资源占用一个 Docker 容器就能跑、丰富的通知集成和完全免费开源的特性吸引了我。经过一段时间的深度使用我发现它远不止一个“看门狗”那么简单其灵活的配置和扩展性足以应对从个人博客到中小型项目集群的监控需求。接下来我就结合自己的实操经验带你从零开始玩转这款利器。2. 核心设计与部署方案选型部署 Uptime Kuma 本身非常简单但“如何部署”却决定了后续维护的便利性和系统的可靠性。主流的部署方式有三种Docker、直接 Node.js 运行和宝塔面板一键部署。每种方式都有其适用场景。2.1 部署方式对比与选型理由对于绝大多数用户尤其是已经熟悉容器化技术的开发者Docker 部署是毫无争议的首选方案。理由如下环境隔离与一致性Uptime Kuma 依赖 Node.js 环境。使用 Docker 可以避免与宿主机上其他 Node.js 项目产生版本或依赖冲突真正做到“开箱即用用完即删”系统环境干干净净。升级与迁移极其方便这是 Docker 最大的优势。升级时只需要拉取新版本的镜像重新运行容器即可数据和配置因为做了卷映射Volume而得以保留。整个过程通常在一分钟内完成完美呼应了“docker安装的uptime kuma如何升级”这个高频搜索需求。迁移到新服务器也只需拷贝数据卷和docker-compose.yml文件。资源管理清晰通过 Docker 可以直观地限制容器的 CPU、内存使用量对于在资源有限的 VPS 上运行非常友好。直接通过 Node.js 和 PM2 部署更适合对 Docker 有抵触、或者希望进行深度定制开发的用户。而宝塔面板部署则极大降低了 Linux 新手的上手门槛适合纯运维小白。但考虑到长期维护的便利性和社区最佳实践本指南将重点围绕Docker Compose方案展开因为它用一份声明式的配置文件定义了应用、网络、存储卷的所有关系是生产环境部署的推荐做法。2.2 基础环境准备与 Docker 安装假设你有一台运行 Linux如 Ubuntu 22.04的云服务器或本地主机。首先需要安装 Docker 和 Docker Compose。对于 Ubuntu/Debian 系统可以执行以下命令。注意生产环境请务必参考官方文档进行安全配置。# 更新软件包索引 sudo apt-get update # 安装必要的依赖包允许 apt 通过 HTTPS 使用仓库 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker 的官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gosu tee /etc/apt/keyrings/docker.asc /dev/null # 设置 Docker 稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 更新 apt 源并安装 Docker 引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证 Docker 安装是否成功 sudo docker run hello-world安装成功后建议将当前用户加入docker组以便后续无需sudo即可运行 Docker 命令。sudo usermod -aG docker $USER # 执行此命令后需要退出当前终端并重新登录或者执行 newgrp docker 使组变更生效注意将用户加入 docker 组等同于赋予其 root 权限因为 Docker 守护进程以 root 身份运行。在个人或受控环境可以这样操作以方便使用但在多用户或对安全要求极高的生产服务器上应谨慎评估或使用更精细的权限控制策略。3. 使用 Docker Compose 部署 Uptime KumaDocker Compose 允许我们使用一个 YAML 文件来定义和运行多容器应用。对于 Uptime Kuma 这种单服务应用它同样能简化我们的管理。3.1 编写 Docker Compose 配置文件首先创建一个专门的工作目录例如~/uptime-kuma然后进入该目录创建docker-compose.yml文件。mkdir -p ~/uptime-kuma cd ~/uptime-kuma nano docker-compose.yml将以下内容粘贴到文件中。这个配置做了几件关键事指定了官方镜像louislam/uptime-kuma:latest。为了稳定性你也可以将latest替换为具体的版本号如1.23.0。将容器内的/app/data目录Uptime Kuma 存放所有配置、数据库文件的地方映射到宿主机的./data目录。这样即使容器被删除数据也不会丢失。将容器内的 3001 端口映射到宿主机的 3001 端口。你可以根据需要修改宿主机的端口号例如8080:3001。设置了容器自动重启策略为always确保服务器重启后监控服务也能自动恢复。version: 3.8 services: uptime-kuma: image: louislam/uptime-kuma:latest container_name: uptime-kuma volumes: - ./data:/app/data ports: - 3001:3001 restart: always # 可选设置时区使日志和时间显示与本地一致 environment: - TZAsia/Shanghai3.2 启动服务与初始配置保存文件后在docker-compose.yml所在目录下执行以下命令启动服务docker compose up -d-d参数代表在后台运行detached mode。首次运行会从 Docker Hub 拉取镜像可能需要一点时间。拉取完成后容器会自动启动。现在打开你的浏览器访问http://你的服务器IP:3001。你将看到 Uptime Kuma 的初始化设置页面。创建管理员账户输入你想要的用户名、邮箱和密码。这个账户拥有最高管理权限。完成设置点击创建系统会自动跳转到登录页面。用刚才创建的账户登录即可进入主仪表盘。至此Uptime Kuma 的核心服务已经部署完成。你看到的将是一个空旷的仪表盘接下来就是为它添加监控任务让它真正开始工作。实操心得强烈建议在docker-compose.yml同目录下运行命令这样 Docker Compose 会默认使用当前目录名uptime-kuma作为项目名方便管理。你可以通过docker compose ps查看服务状态docker compose logs -f uptime-kuma实时查看日志这对于排查启动问题非常有用。4. 核心功能详解与监控项配置登录后的主界面很简洁左上角是菜单栏。我们绝大部分操作都围绕“添加监控项”展开。点击仪表盘上的“添加监控项”按钮或通过左侧菜单“状态页面”-“监控项”进入管理界面。4.1 监控类型深度解析Uptime Kuma 支持多种监控类型理解每种类型的适用场景是关键。监控类型协议/方法主要用途关键配置项HTTP(s)GET/POST/...监控网站、API接口可用性URL, 请求方法, 请求头, 认证, 状态码校验, 关键词校验TCP 端口TCP 连接监控数据库如3306、SSH22、游戏服务器等端口是否开放主机名/IP, 端口号PingICMP监控服务器或网络设备是否在线需要宿主机支持PingIP 地址/域名DNSDNS 查询监控域名解析是否正确、是否被污染记录类型A, AAAA, CNAME等, 期望值推送监控被动接收由被监控服务主动“报平安”Heartbeat唯一的推送 URLSteam 游戏服务器Game Query监控特定 Steam 游戏服务器状态服务器 IP 和端口Docker 容器Docker API监控同一主机上 Docker 容器的运行状态容器名称HTTP(s) 监控这是最常用的类型。除了基本的 URL高级功能非常实用关键词校验比如你的网站首页应该包含“首页”这个词你可以设置“期望关键词”。如果返回的 HTML 里没有这个词即使状态码是200也会被判为“宕机”。反之可以设置“不期望的关键词”来检测错误页面。请求头与认证可以添加User-Agent或者Authorization头来监控需要登录的接口。状态码默认认为 2xx 和 3xx 是正常的你也可以自定义接受的状态码范围。推送监控 (Heartbeat)这是一个非常巧妙的“反向监控”模式。适用于那些无法从外部主动探测的服务比如你的家用 NAS、公司内网开发机。你需要在被监控的设备上设置一个定时任务Cron Job定期向 Uptime Kuma 生成的一个唯一 URL 发送 GET 或 POST 请求称为“心跳”。只要 Uptime Kuma 在预设时间间隔内收到心跳就认为服务正常。如果超时未收到则判定为宕机。这完美解决了 NAT 或防火墙后方服务的监控难题。4.2 创建一个完整的 HTTP 监控项让我们一步步配置一个对https://www.example.com的监控。基础信息监控类型选择 “HTTP(s)”。名称填写一个易于识别的名字如“公司官网”。URL输入https://www.example.com。心跳间隔默认是60秒。对于重要服务可以设置为30秒甚至更短但会增加对方服务器的负载。对于个人博客120秒或300秒也足够。重试次数默认是0即一次失败就标记为宕机。建议设置为1或2避免因网络短暂波动造成误报。超时时间默认30秒。对于一般网站10秒足够了。高级选项展开请求方法保持 GET。期望状态码保持200-299。关键词校验假设我们想确认页面包含“Welcome”就在“期望关键词”里填入Welcome。请求头可以添加一个自定义的User-Agent例如UptimeKuma-Monitor/1.0以便在对方服务器日志中识别。认证如果网站需要 Basic Auth可以在这里填写用户名和密码。通知设置先不选我们稍后会配置通知渠道。点击“保存”。保存后这个监控项会立即开始第一次检查并在仪表盘上显示状态绿色为正常红色为宕机灰色为暂停橙色为尚未检查。点击监控项名称可以进入详情页查看响应时间历史曲线、事件日志何时宕机、何时恢复等详细信息。注意事项监控 HTTPS 网站时确保你的 Uptime Kuma 服务器时间准确使用 NTP 同步否则可能因为证书有效期校验失败而导致监控失败。这也是为什么在 Docker Compose 文件中建议设置TZ环境变量的原因之一。5. 通知渠道集成让告警触手可及监控的核心价值在于“告警”。Uptime Kuma 支持数十种通知方式这里介绍最常用的几种Telegram、Discord 和电子邮件。5.1 配置 Telegram 机器人通知Telegram 通知实时性强配置简单是我个人的首选。创建 Telegram Bot在 Telegram 中搜索BotFather发送/newbot命令。按提示设置机器人名字和用户名。创建成功后BotFather会给你一个HTTP API Token形如1234567890:ABCDEFGhijklmnopQRSTUVwxyz。妥善保存。获取你的 Chat ID先给你创建的机器人发送一条任意消息例如/start。然后在浏览器中访问这个 URL将YourBotToken替换为你的 Tokenhttps://api.telegram.org/botYourBotToken/getUpdates在返回的 JSON 数据中找到message.chat.id字段的值这就是你的Chat ID通常是一个负数。在 Uptime Kuma 中配置进入 Uptime Kuma 设置 - 通知 - 添加通知。类型选择 “Telegram”。名称填写 “My Telegram”。Bot Token填入第一步获取的 Token。Chat ID填入第二步获取的 ID。点击“测试”如果配置正确你的 Telegram 会立即收到一条测试消息。然后保存。5.2 配置 Discord Webhook 通知Discord 适合团队协作可以将告警发送到指定的频道。创建 Discord Webhook进入你的 Discord 服务器选择某个文本频道点击编辑频道 - 集成 - Webhook - 新建 Webhook。设置名称和头像然后点击“复制 Webhook URL”。这个 URL 包含了所有认证信息。在 Uptime Kuma 中配置添加通知类型选择 “Discord”。名称填写 “Team Discord”。将复制的Webhook URL粘贴到对应字段。可以自定义“提及”字段例如here或用户ID以便在告警时提醒特定人或所有人。测试并保存。5.3 配置电子邮件 (SMTP) 通知电子邮件是通用且正式的通知方式但依赖外部 SMTP 服务器。准备 SMTP 信息你需要一个可用的 SMTP 服务器地址、端口、用户名和密码。可以使用企业邮箱、Gmail需应用专用密码或 SendGrid 等邮件服务。在 Uptime Kuma 中配置添加通知类型选择 “Email (SMTP)”。填写 SMTP 服务器主机名、端口如 465 for SSL 587 for TLS、用户名、密码。发件人邮箱和收件人邮箱填写你的邮箱地址。强烈建议先点击“测试”确保能收到测试邮件再保存。配置好通知渠道后回到监控项编辑页面在“通知”选项卡中勾选你希望接收该监控项告警的渠道。你还可以设置“延迟通知”例如宕机持续1分钟后再发通知避免瞬断干扰和“最大通知次数”。6. 状态页面与公开分享Uptime Kuma 不仅可以自己看还能生成一个公开的状态页面展示你所有或部分服务的健康状态类似于 status.example.com 这样的页面。这对于向用户透明展示服务状态非常有用。创建状态页面左侧菜单进入“状态页面”点击“创建新状态页面”。配置基本信息设置一个标题、描述、图标和自定义域名如果你有并配置了反向代理。你可以设置一个易于记忆的路径如status。关联监控项在状态页面的设置中选择要公开显示哪些监控项。你可以选择显示全部也可以只展示部分核心服务。访问与分享保存后状态页面的访问地址通常是http://你的服务器IP:3001/status/你设置的路径。你可以将这个链接分享给用户。进阶配置反向代理为了让状态页面更专业通常需要通过 Nginx 或 Caddy 配置反向代理使用你自己的域名和 HTTPS。例如将status.yourdomain.com代理到http://localhost:3001。这需要在你的 Web 服务器配置中添加相应的 server 块并申请 SSL 证书推荐使用 Let‘s Encrypt。7. 维护、升级与故障排查7.1 如何升级 Uptime KumaDocker 方式这是搜索热词“docker安装的uptime kuma如何升级”的标准答案。得益于 Docker Compose升级过程异常简单。停止并删除旧容器在docker-compose.yml文件所在目录执行。docker compose down这条命令会停止并删除名为uptime-kuma的容器但不会删除映射在./data目录下的数据卷。拉取最新镜像docker compose pull这条命令会从 Docker Hub 拉取louislam/uptime-kuma:latest标签对应的最新镜像。重新创建并启动容器docker compose up -d此时Docker Compose 会使用新镜像创建一个新容器并挂载原有的数据卷。你的所有配置、监控历史和通知设置都会完好无损。可选清理旧镜像升级后旧的镜像会变成none的悬空镜像可以清理以释放空间。docker image prune实操心得在重大版本升级前例如从 1.x 到 2.x建议先查阅项目的 GitHub Release Notes看是否有不兼容的变更。同时务必确保你的数据卷./data有定期备份。最简单的备份方式就是压缩拷贝整个./data目录。7.2 常见问题与排查技巧即使配置正确监控过程中也可能遇到各种问题。这里记录几个我踩过的坑和解决方法。问题现象可能原因排查步骤与解决方案监控状态频繁在“正常”和“宕机”间跳动1. 网络不稳定。2. 目标服务器负载高响应慢。3. 心跳间隔太短重试次数为0。1. 在服务器上ping或traceroute目标地址检查网络质量。2. 查看目标服务器资源使用情况CPU、内存、带宽。3.增加“重试次数”到2或3并适当延长“超时时间”如从30秒到45秒。HTTP监控返回状态码200但被判定为“宕机”1. “期望关键词”设置错误或页面内容已变更。2. 证书问题自签名证书或证书过期。3. 服务器返回了非标准内容如跳转。1. 检查监控项详情页的“最后响应体”确认返回内容是否包含你设置的关键词。2. 对于自签名证书可以在“高级选项”中勾选“接受不安全的SSL证书”。3. 使用curl -v 你的URL命令手动测试观察完整的请求响应过程。推送监控Heartbeat一直收不到心跳1. 被监控端的定时任务Cron没有正确执行。2. 推送 URL 错误。3. 防火墙或网络策略阻止了出站请求。1. 登录被监控端手动执行心跳命令如curl 你的推送URL看能否成功。2. 检查 Cron 任务的日志/var/log/syslog或cron日志。3. 确认被监控端网络可以访问到 Uptime Kuma 服务器的 IP 和端口。Docker 容器监控失败1. Uptime Kuma 容器无法连接到宿主机的 Docker 守护进程。2. 容器名称填写错误。1. 需要在运行 Uptime Kuma 容器时将宿主机的 Docker Socket 映射进去。修改docker-compose.yml在volumes下添加一行- /var/run/docker.sock:/var/run/docker.sock:ro。注意安全风险这赋予了容器控制宿主机所有容器的能力。2. 使用docker ps命令确认准确的容器名称。通知收不到1. 通知渠道配置错误Token、Chat ID、Webhook URL等。2. 触发条件未满足如未达到延迟通知时间。3. 被通知平台屏蔽如 Telegram 在某些网络环境。1. 务必使用通知配置页面的“测试”功能这是最直接的验证方法。2. 检查监控项的通知设置确认已关联该通知渠道且延迟时间设置合理。3. 查看 Uptime Kuma 容器日志docker compose logs uptime-kuma看发送通知时是否有错误信息。7.3 数据备份与迁移数据是监控系统的核心。Uptime Kuma 的所有数据SQLite 数据库、设置、证书等都存储在./data目录下。定期备份这个目录是必须的。备份直接打包压缩即可。cd ~/uptime-kuma tar -czf uptime-kuma-backup-$(date %Y%m%d).tar.gz data/可以将这个压缩包传到其他服务器或云存储。迁移在新服务器上安装好 Docker 和 Docker Compose拷贝docker-compose.yml文件和备份的data目录解压后到相同路径然后执行docker compose up -d。服务就会带着全部历史记录和配置在新环境启动。8. 进阶玩法与场景扩展掌握了基础监控和告警后Uptime Kuma 还能玩出更多花样解决一些特定场景的需求。场景一监控内部网络服务使用推送监控你的家庭 NAS 或公司内网的测试服务器没有公网 IP。你可以在这些设备上设置一个 Cron 任务每分钟向你的公网 Uptime Kuma 服务器的推送 URL 发送一次心跳。# 在内部服务器的Crontab中添加 */1 * * * * curl -fsS --retry 3 -o /dev/null https://你的kuma域名/api/push/你的推送令牌这样只要心跳中断你就知道内网服务可能出了问题或者网络连接断了。场景二组合监控与依赖关系Uptime Kuma 支持设置监控项的“依赖项”。例如你的应用监控项A依赖数据库监控项B和 Redis监控项C。你可以将 B 和 C 设置为 A 的父级依赖。当数据库挂了应用监控本身可能因为连接超时也显示宕机但状态页面上可以清晰地显示是底层依赖出了问题避免了告警风暴也让根因分析更直观。场景三利用 API 进行集成Uptime Kuma 提供了 REST API你可以用它来编程式地管理监控项、获取状态。例如结合 CI/CD 流水线在部署新服务后自动创建一个对应的监控项或者将监控状态集成到公司内部的统一仪表盘中。关于网络热词的联想虽然 Uptime Kuma 本身不直接处理“串口监控数据保存”或“安卓 GPU 监控”但它的设计思想可以借鉴。对于这类特殊监控需求一个常见的模式是编写一个专门的 Agent代理程序运行在目标设备上如安卓设备这个 Agent 负责采集 GPU、显存等数据然后定期通过HTTP API或推送监控的方式将数据或心跳发送到 Uptime Kuma。Uptime Kuma 的“关键词校验”功能甚至可以用于检查上报的数据是否在正常阈值内。这体现了自托管工具的灵活性——你可以围绕它构建适合自己的监控生态。最后监控的目的是为了保障服务的稳定性和提升响应速度而不是制造焦虑。合理的告警阈值、清晰的通知分级哪些需要立即打电话哪些可以早上再看以及定期的监控项审计清理不再需要的、更新变更的URL才能让 Uptime Kuma 真正成为你得力的助手而不是“狼来了”的噪音源。从我自己的使用体验来看自从用它盯住了几个关键服务晚上睡觉确实踏实多了。