进阶 uptime.kuma.pet 2026-11-20 10:30:00 · 9 阅读

第3章 从 v1 迁移到 v2

第3章:从 v1 迁移到 v2 警告 这是大版本升级,包含一些破坏性变更。如果你打算从 v1 升级到 v2,请仔细阅读迁移指南。

提示

开始前

停止你的 Uptime Kuma,并执行以下操作:

备份你的数据目录。 再确认一次,确保你有数据目录的备份。 再三确认,再次确认你有数据目录的备份。

迁移过程可能需要一些时间,具体取决于数据库的大小。这是因为我们需要将 heartbeat 表聚合到新的、经过优化的格式中。

你应该可以在控制台中查看迁移过程的日志。 切勿中断迁移过程。如果迁移过程中断,你必须从备份恢复并重试升级。 参考案例:我的 Uptime Kuma 有 20 个监控器和 90 天的数据,迁移耗时大约 7 分钟。在较慢的硬件上或监控器更多时,这可能耗费数小时。

破坏性变更

为保证准确性,这些徽章端点的 :duration 参数现在仅接受 24、24h、30d、1y 这样的值。 提醒一下,这些徽章端点如下:

/api/badge/:monitorID/ping/:duration /api/badge/:monitorID/uptime/:duration

具体而言,我们添加了以下限制:

小时级最多 720h 分钟级最多 1440m 天数级最多 365d

弃用对旧版浏览器的支持

移除已弃用的 JSON 备份/恢复功能。目前备份数据目录是唯一支持的备份方法。

移除已弃用的 HTTP 监控器 DNS 缓存功能。对于 Docker 安装,建议使用自带的 nscd。

将新建监控器的默认重试次数从 1 改为 0,以避免用户困惑

邮件 (SMTP) 通知的主题/正文模板从自定义正则表达式迁移到 LiquidJS。在 LiquidJS 中:

变量现在区分大小写,且 所有不匹配的变量将被忽略。 支持的变量有:name, msg, status, heartbeatJSON, monitorJSON, hostnameOrUrl。我们尚未为这些变量编写文档,但你可以参考源代码了解数据结构。

仅 Docker 的破坏性变更

弃用对基于 Alpine 的 Docker 镜像的支持(但你仍然可以迁移到 v2)。 如果你的宿主机使用 Debian / Raspbian Buster,请勿升级。由于 libseccomp2 库存在一个 bug,会导致启动问题。阅读更多:https://github.com/louislam/uptime-kuma/issues/41#issuecomment-896164516

非 Docker 的破坏性变更

弃用对 Node.js 14、16 和 18 的支持。Node.js 最低支持版本为 20.4。

Docker 标签 v2 中有一些新标签可用,例如 *-slim、*-rootless 标签。 请阅读 /docs/Docker-Tags 警告 不推荐使用 Rootless 镜像从 v1 升级到 v2,你很可能会遇到启动问题。

迁移步骤 (Docker)

停止你的 Uptime Kuma 容器。

docker stop uptime-kuma

备份你的数据目录。 将镜像标签更改为 louislam/uptime-kuma:2。

docker run -d --restart=unless-stopped -p :3001 -v :/app/data --name uptime-kuma louislam/uptime-kuma:2

检查日志以查看迁移过程。

docker logs -f uptime-kuma 迁移步骤 (Docker Compose)

停止你的 Uptime Kuma 堆栈。

docker compose down

备份你的数据目录。

将镜像标签更改为 louislam/uptime-kuma:2。

services: uptime-kuma: image: louislam/uptime-kuma:2 ....

启动你的 Uptime Kuma 堆栈。

docker compose up -d

检查日志以查看迁移过程。

docker compose logs -f 迁移步骤 (非 Docker)

停止你的 Uptime Kuma。

pm2 stop uptime-kuma

备份你的数据目录。 检查你的 Node.js 版本,要求 Node.js >= 20.4。

node --version

按照 /docs/How-to-Update#—non-docker 进行更新

常见问题 我可以将现有的 SQLite 数据库迁移到 MariaDB 吗? 不能直接进行,官方也不支持。你需要使用第三方工具将数据从 SQLite 导出并导入到 MariaDB。

❌ 不推荐 sqlite3tomysql,它没有创建所有必要的索引,会严重影响性能。

重要 我们没有资源去处理由此类迁移引发的问题。如果你在之后遇到任何问题,请先在一个全新安装中复现,以确认该问题是由我们造成的,而非由你执行的迁移操作导致。 通知方式 Uptime Kuma 支持广泛的通知服务。(Beta) 从 v2 迁移到 v3 下一页

评论 (0)