Uptime Kuma 3.0 Beta Linux 实测:v3 迁移必看

Uptime Kuma 属于那种会悄悄变成基础设施的工具。你打开它,只是为了回答一句”网站挂了,还是我 VPN 又抽风?”——但一旦它接进 Slack、Telegram 和你的公开状态页,谁都不想成为那个在升级时把它搞坏的人。所以 2026 年 11 月 17 日这一天格外关键:项目在同一天发布了 3.0.0-beta.1(大版本重写的首个公开测试版),以及带安全修复的稳定版 2.5.12。两条发布线,一个下午。

项目官网是 uptime.kuma.pet,源码在 github.com/louislam/uptime-kuma——MIT 协议,约 9.45 万 star,如今已是自托管领域 star 数最高的工具之一。如果你还没用过它,现在正是好时机:v3 重写了数据库层、认证栈和通知提供商列表,而稳定分支依然是最稳妥的起点。

Uptime Kuma 仪表盘:监控列表、可用率百分比、彩色心跳条与响应时间曲线

Uptime Kuma 到底能做什么

本质上,Uptime Kuma 是一个自带友好 Web UI 的自托管可用率监控器。你添加一个监控项——HTTP(S)、TCP、ping、DNS、MQTT、推送,以及 v3 新增的 SFTP——设定检查间隔,它就开始画出上面截图里那种心跳条。右侧是真正有用的数字:当前响应时间、24 小时平均值、24 小时与 30 天可用率百分比,以及证书到期时间。最后这一项其实是整个应用里最值钱的字段——一个不能告诉你”你的 TLS 证书还有九天就到期”的监控工具,说到底只是个花哨点的 ping。

围绕这个核心,还有让它留得住人的功能:关键字监控(盯页面上的某个字符串,比如 “in stock”)、可绑定独立域名和品牌样式的公开状态页、报表视图,以及一套可以扇出到非常长列表的通知系统。

深色模式公开状态页:全部系统正常横幅与各服务可用率列表

状态页正是大多数人选择 Uptime Kuma 而不是”定时脚本 + 发邮件”的原因。它会渲染一个公开的”全部系统正常”横幅,外加逐服务的可用率列表,你还可以给它配一个 CNAME。

新闻:v3 测试版与稳定版补丁同日发布

如果你是老用户,这段才是重点。11 月 17 日,维护者发布了 3.0.0-beta.1——v3 分支的首个测试版;大约一小时之前,稳定线上发布了 2.5.12。

v3 的发布说明分量十足。主要变化包括:新增支持密码与私钥认证的 SFTP 监控;API 与 MCP 骨架(alpha 阶段),便于以程序化方式驱动监控;一大批新的通知提供商——Trigv、OpsiMate、Microsoft Graph 邮件、Indigo、Signalgrid、Notify!、SMS Gateway、ClickUp、TurboSMTP、Milky、openwa 等;存储层改用 better-sqlite 重写。v3 分支的 Node.js 版本升到 26,认证则迁移到了 Better Auth。

再往底层看,维护者还从 3.0 分支里移除了 AWS SDK 与 Azure 相关包,并改为通过 uv 安装上游 Apprise 2.0.1。

稳定分支也没闲着。回顾最近几周的 2.5.x 发布,有一段值得注意的规律:最近六个稳定版里有五个是安全修复:

  • 2.5.12(11 月 17 日)——沙箱化了一个危险库,外加依赖更新。
  • 2.5.11(11 月 12 日)——GHSA-437w-j82f-9vjh:由上游包回归引入的仅限管理员的 RCE,由 Tomer-PL 报告。
  • 2.5.10(11 月 12 日)——修复内嵌 MariaDB 问题,以及 Node.js 安全更新。
  • 2.5.9(10 月 31 日)——修复 RSS 缓存投毒。
  • 2.5.8(10 月 26 日)——修复 Apprise RCE,以及 Docker 与 TLS 相关问题。

其中两个是远程代码执行漏洞。如果你运行着 Uptime Kuma 并且它暴露在公网——哪怕前面挂着反向代理——2.5.11 是你必须上的版本,而且要意识到你实例此前跑在受影响版本上的风险有多实际。

破坏性变更:按”先咬你一口”的顺序排

官方那份 v2 → v3 迁移指南 很短,这算优点,但密度很高。实际会变的有这些。

没有降级路径。 这是头号重点。v3 会就地升级数据库,指南说得很直白:升级前做的那份备份,是你唯一的退路。所以第一步不是执行升级命令,而是备份——整个 data 目录,包括 kuma.db 和 db-config.json——并且真的验证一次备份能恢复。

Docker 用户要用独立标签。 v3 测试版标签和 v2 是分开的:

标签 说明
beta 最新 v3 测试版,测试首选
beta-slim 最新 v3 测试版的 slim 版
beta-rootless rootless 版
beta-slim-rootless slim + rootless
nightly 每日构建

所以在 compose 文件里就是改一行,从 louislam/uptime-kuma:2 换成 louislam/uptime-kuma:beta。

Prometheus 指标默认关闭。 为了降低 CPU 占用,v3 里 /metrics 端点默认禁用,需要去 Settings → General → Prometheus API 重新打开。如果你用 Prometheus 抓取 Uptime Kuma,这个改动会在凌晨三点把你叫醒——不是因为服务坏了,而是因为图变平了。

非 Docker 启动方式变了。 如果你从源码运行或用 PM2,node server/server.js 不再可用,要改成 node --run start。PM2 下则是 pm2 start,而不是 pm2 start server/server.js,因为项目为 v3 提供了更新后的 ecosystem 配置。而且 v3 分支要求 Node.js 26.2.0 或更高版本。

ARMv7 被移除了。 自 Node.js 24 起 linux/arm/v7 就不再支持,v3 镜像同样不支持。树莓派 2 代及更老的设备应继续留在 v2。 这是自托管用户最常见的升级翻车点,因为 Pi 系的 Docker 配置往往一路看着正常,直到镜像根本拉不下来。

第三方集成可能失效。 迁移到 Better Auth 改变了 API 密钥的签发方式,凡是依赖 Uptime Kuma 认证的东西——自建面板、抓 API 的 Grafana 面板、家庭自动化网关——都需要重新验证。普通用户的网页登录不受影响。

不停机完成迁移

Docker 路径最短:

Bash
# 1. 停掉正在运行的实例
docker stop uptime-kuma

# 2. 备份数据目录——并且验证恢复
docker cp uptime-kuma:/app/data ./kuma-data-backup
# 确认 kuma.db 与 db-config.json 都在里面,然后再往下走

# 3. 拉取 v3 测试版镜像
docker pull louislam/uptime-kuma:beta

# 4. 用新标签重新启动
docker run -d --restart=unless-stopped 
  -p 3001:3001 
  -v /your/path:/app/data 
  --name uptime-kuma 
  louislam/uptime-kuma:beta

# 5. 盯着迁移过程
docker logs -f uptime-kuma

用 compose 的话,把镜像标签改掉,然后 docker compose down、docker compose up -d,再 docker compose logs -f。迁移在启动时执行,日志就是你观察报错的地方。

之后记得检查两个悄悄变了的地方:先登录看看(Better Auth 可能重置了什么),再确认 Settings → General → Prometheus API——如果你之前抓过 /metrics。

Uptime Kuma 通知渠道示意图:中央铃铛向外辐射各通知提供商

现在该不该升级?

按发布说明的真实内容,我的建议是这么分的:

留在 2.5.x,如果你在 ARMv7 硬件上跑、有第三方集成依赖它的 API 认证,或者这周实在没空做迁移测试。稳定分支仍在持续修复——而且正是因为还在修,才有 2.5.11 和 2.5.12。

想尝鲜就在第二个实例上跑 beta,如果你想要 SFTP 监控、新通知提供商,或者 API/MCP 骨架,而且你愿意并行开一个容器来试。

别把生产状态页指向 beta,除非你有验证过的备份。 这不是因为维护者不用心——v3 的工作本身质量不错,3.0 测试期一直在修可用率百分比、推送实时更新和监控逻辑的回归问题——而是因为没有撤销按钮,而状态页恰恰是你最不能悄悄弄坏的东西。

Uptime Kuma 报表界面:横向可用率柱状图覆盖全部受监控服务

结语

对大多数人来说,Uptime Kuma 依然是最值得用的自托管可用率监控工具,而 v3 分支就是项目的下一站:一次真正的存储层重写、更现代的认证栈、一长串新通知提供商,以及一个能通过 MCP 被 AI agent 驱动的 API 雏形。同时它眼下还有一个比多数自托管软件修得还勤的稳定分支。

如果你是新用户,今天就装 2.5.12,测试版的事先放一放——稳定版离发布也不远了。如果你已经在用,不管怎样这周都升到 2.5.12,因为那个仅限管理员的 RCE 修复不是可选项;至于 v3 beta,把它当成一次有可靠备份兜底的实验室尝试。

最后修改: 2026年11月18日

作者

评论

发表评论

您的邮箱地址不会被公开。