做独立开发或者自己折腾 VPS 的朋友，大概都经历过这种尴尬时刻：自建的网站、博客或者 API 服务悄悄挂了大半天，自己还浑然不知，直到有热心访客发邮件或者朋友微信截图提醒，才手忙脚乱地上去救火。要想睡个安稳觉，一套可靠、灵敏的在线监控面板必不可少。Uptime Kuma 就是近几年自建监控圈子里公认的“门面担当”——它不仅开源免费、UI 现代漂亮，还支持 HTTP(s)、TCP 端口、Ping、DNS 等几乎所有常见协议，自带开箱即用的公共状态页，更打通了飞书、钉钉、企业微信、Telegram、邮件等数十种告警通道。不管你手里只有两三个小静态站，还是维护着一整套小型集群，它都能帮你把所有节点的心跳状态盯得明明白白。

不过需要特别提醒的是，网上大部分流传的教程还停留在 1.x 时代，照着老攻略操作极其容易踩坑。本文基于官方最新发布的 2.5.9 定版进行全流程实装验证（底层已更新至 Node.js 22）。在全新的 v2 架构下，系统首次初始化新增了专门的数据库选择向导，路由机制也发生了明显变动。如果你直接按照老版本的经验去找“一打开就是账号注册页”，大概率会摸不着头脑。接下来就跟着我们的实测步骤，只要五分钟，带你在自己的服务器上把监控底座稳稳搭起来。

成品长这样

部署完成后，你将拥有一个极为清爽直观的监控仪表盘。每一个服务的心跳连通性、即时响应耗时、近 24 小时乃至全年的可用率百分比都会以图表和卡片形式清晰呈现，状态异常时更能在第一时间推送到你的手机设备上：

Uptime Kuma 监控详情页显示 Up 状态与响应时间 — 图 1：监控项详情页，状态 Up、可用率 100%

准备工作

在正式敲命令行之前，请先确认你的服务器环境满足以下几项要求：

一台 Linux 云服务器：常见的 Ubuntu 22.04 / 24.04 或 Debian 12 均可，系统内需要预先装好 Docker 和 Docker Compose 插件。
放行 3001 端口：Uptime Kuma 默认使用 3001 端口同时承载 Web 管理界面和后台探测引擎。请在云厂商的“安全组”规则以及系统自带防火墙（如 ufw 或 iptables）中放行 TCP 3001 端口入站。
硬件配置要求极低：该程序性能极佳，单核 CPU、512MB 内存的入门级小主机即可轻松驾驭。如果监控项目在几十个以内，日常内存占用通常仅在 100MB 上下，完全不会给机器带来负担。

第一步：Docker Compose 部署

我们强烈建议使用 Docker Compose 来编排运行容器，这样日后的数据挂载、配置调整和一键升级都会非常规整，也不会污染宿主机原本的运行环境。

创建项目目录并编写配置文件

在你的服务器上规划一个独立目录（例如家目录下的 uptime-kuma），进入目录并创建 docker-compose.yml：
BASH
```
mkdir -p ~/uptime-kuma && cd ~/uptime-kuma
nano docker-compose.yml
```
将以下经实测验证的 Compose 配置完整粘贴进去：
BASH
```
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.9
    container_name: uptime-kuma
    restart: always
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"
```
拉取镜像并在后台启动容器

保存并退出文本编辑器，执行以下命令在后台启动服务：
BASH
```
docker compose up -d
```
由于官方镜像功能完整，解包后的总体积约 1.5GB（其中包含一个超过 400MB 的核心层）。若你的服务器网络拉取 Docker Hub 速度较慢，首次拉取可能需要等待一两分钟；如果中途遇到网络偶发中断，无需担心，重新执行该命令即可断点续拉。
查看启动日志确认就绪

容器启动后，你可以通过日志跟踪指令观察后台加载情况：
BASH
```
docker compose logs -f
```
当你看到日志末尾打印出 Uptime Kuma Version: 2.5.9 以及监听端口就绪的相关输出时，表明后端进程已经平稳启动。此时按下键盘上的 Ctrl + C 退出日志跟踪即可。

重要提示：关于数据持久化

Compose 文件中 ./data:/app/data 这一行是全篇的核心生命线。Uptime Kuma 的所有业务数据——包括 SQLite 主数据库 kuma.db（以及其 -wal 和 -shm 缓存文件）、引擎配置文件 db-config.json、自定义证书及上传的静态资源，全部存放在容器内部的 /app/data 中。必须把它映射到宿主机本地的 ./data 目录，否则日后任何一次容器重建或版本升级，都会导致你的账号密码、监控条目与历史可用率数据被瞬间清空！

第二步：选数据库并创建管理员

容器启动成功后，打开浏览器访问 http://<你的服务器IP>:3001。如果是刚接触 Uptime Kuma 2.x 的朋友，这里会发现它和老版本不太一样：页面并不会直接让你输用户名密码，而是自动重定向到了 /setup-database 数据库配置向导。

在向导页面中，系统会提供 SQLite 与 MariaDB / MySQL 两种数据库引擎供选择。如果是个人部署、小团队监控或者监控目标在几十到几百个以内，强烈建议直接点选 SQLite。它把所有数据直接存放在本地单个文件里，免去了额外搭建数据库服务与维护连接池的麻烦；只有打算做多实例高可用部署，或者超大规模监控集群时，才需要考虑外接 MariaDB。

这里有个交互小细节很容易让人卡壳：界面的「Next」按钮默认是灰色不可点击状态，你必须先在页面上手动点中「SQLite」这一项，右下角的 Next 按钮才会激活点亮。点完 Next 后，屏幕会短暂提示「Setting up the database」，稍等几秒钟，系统就会在后台完成数据表结构的初始化并自动跳到账号创建页面。

Uptime Kuma 首次启动的数据库选择向导页 — 图 2：首次启动先选数据库，个人使用选 SQLite 即可

接下来就是创建初始管理员账号。填入你习惯的用户名，并设置一个高强度的管理密码（包含大小写字母、数字及符号），再次输入确认密码后点击「Create」。创建完成后，系统会自动完成鉴权并带你直接进入管理后台首页（Dashboard）。请务必当场记好并妥善保管你的管理凭证，以后任何监控项增删和通知渠道改动全靠这个账号。

Uptime Kuma 登录页 — 图 3：创建管理员后，未登录访问根路径就是登录表单

⚠️ 踩坑提醒：Uptime Kuma 没有独立的 /login 路由

很多朋友习惯在书签里存 http://IP:3001/login，但在 Uptime Kuma 2.x 中直接访问这个地址会返回「Page Not Found」404 错误。这是正常现象，系统本身并没有切出单独的 /login 页面路由。只要你处于未登录状态，直接访问根路径 http://IP:3001/ 展现出来的就是登录表单。浏览器书签直接存根路径即可，别再手敲 /login 吓自己一跳。

第三步：添加第一个监控项

进到 Dashboard 后，目前整个面板还是空空如也，左侧也没有任何状态条。我们马上添加第一个监控项来验证整个监控链路是否运转正常——最直接稳妥的办法，就是让它先「自我体检」，监控自身的 Web 面板。

点击 Dashboard 左上角的 「Add New Monitor」 按钮，进入监控项配置表单：

Monitor Type（监控类型）：保持默认的 HTTP(s)。这个类型最通用，它会定期向目标地址发 HTTP 请求并根据返回的状态码判定目标是否存活。
Friendly Name（显示名称）：起一个通俗易懂的名字，比如「本机面板自检」或「Uptime Kuma Dashboard」。
URL：填入 http://127.0.0.1:3001。因为是容器自身或同机检测，直接走回环地址效率最高也最稳定。
Heartbeat Interval（心跳间隔）：默认是 60 秒，也就是每隔一分钟发起一次探测，日常服务监控用默认值完全足够。

其他如重试次数（Retries）、通知渠道等高级项先不用急着配，直接滚到页面最底部点击 「Save」 保存。

Uptime Kuma 添加 HTTP 监控项的表单页 — 图 4：添加监控表单，填名称与被监控 URL

点击保存后页面会自动跳回仪表盘。无需刷新，等待大约数秒钟，后台的首次探测执行完毕，左侧列表里的监控项便会立刻点亮成代表健康的绿色，状态显示为 「Up」。点进监控项详情页可以看到实测数据：HTTP 状态码返回标准的 200 - OK，本机探测的响应时间基本压在 10–24ms 左右，上方的 24 小时、30 天与 1 年可用率（Uptime）指标全部工整地维持在 100%。到这一步，就说明你的 Uptime Kuma 监控引擎已经在后台稳定开跑了。

踩坑实录

1. v2 数据库向导导致 Next 按钮置灰
v2 相比 v1 新增了独立的数据库选择向导（/setup-database）。初次打开页面后必须先手动点选“SQLite”或“MariaDB”选项，“Next”按钮才会激活变亮；若对照 v1 老教程寻找“打开直接建管理员”，很容易误以为前端脚本卡死。

2. 访问 /login 路由触发 404 报错
Uptime Kuma v2 移除了独立的 /login 路由，手动访问 http://IP:3001/login 只会看到“Page Not Found”的 404 提示。在未登录状态下，系统的登录入口即为根路径 /，保存书签时直接保留域名或 IP 端口即可。

3. 镜像解包体积达 1.5GB 易在弱网断流
官方镜像解包后实际体积约为 1.5GB，且包含一个超过 430MB 的较大分层。在代理通道或弱网环境下执行拉取容易中途超时中断；遇到报错无需怀疑镜像损坏，直接反复执行 docker compose pull 断点续拉即可顺利完成。

4. SQLite 热备极易遗漏 WAL 临时文件
在默认 SQLite 模式下，系统数据全部归档在挂载目录的 kuma.db 主库中。备份虽只需打包 ./data，但若在容器运行状态下直接拷贝文件，务必同时带上 kuma.db-wal 与 kuma.db-shm，或者优先执行停机归档，否则会丢失尚未落盘的最近监控记录。

升级与备份

Uptime Kuma 支持无缝平滑升级，镜像内置了数据库迁移脚本。升级时修改 docker-compose.yml 中的版本标签，并依次执行拉取与重建命令：

# 1. 编辑 docker-compose.yml 修改 image 标签至新版本
docker compose pull
docker compose up -d

容器启动时将自动识别数据结构差异并执行迁移，完成后即可恢复正常监控。

数据备份方法
为避免 SQLite 处于 WAL 写入状态导致数据不一致，建议先停止容器再执行整包压缩：

docker compose down
tar -czvf uptime-kuma-data-$(date +%Y%m%d).tar.gz ./data
docker compose up -d

备份包内包含 SQLite 主从库（kuma.db*）、数据库配置文件（db-config.json）以及静态上传资源（upload/）。

灾难恢复方法
将备份压缩包解压到新主机的 docker-compose.yml 同级目录下，确保解压后的 ./data 目录与 compose 挂载点（./data:/app/data）路径对应，随后直接执行 docker compose up -d，容器启动后即可完全继承原有的全部监控项、通知渠道与历史可用率统计。

Uptime Kuma 安装教程：Docker Compose 部署 + 添加第一个监控（v2.5.9 实测）