Uptime Kuma · 自托管开源服务状态监控与告警页｜部署与使用全指南
项目仓库： https://github.com/louislam/uptime-kuma
开源协议：见仓库 LICENSE · 语言：Node.js · 默认端口：3001 · 部署：Docker / Docker Compose / Node.js 直跑 · 在线演示：demo.kuma.pet
1 项目简介
Uptime Kuma 是一个自托管的 uptime 监控工具，用于监控 HTTP(s)/TCP/HTTP 关键词/HTTP JSON Query/Websocket/Ping/DNS 记录/Push/Steam 游戏服务器/Docker 容器的可用性，并在异常时发出告警。它提供类似状态页的 Web 界面，可自托管替代外部监控服务。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Uptime Kuma |
| 仓库地址 | github.com/louislam/uptime-kuma |
| 项目定位 | 自托管 uptime 监控与状态页 |
| 默认端口 | 3001 |
| 部署方式 | Docker / Docker Compose / Node.js |
| 运行要求（非 Docker） | Node.js >= 20.4、Git、pm2 |
| 在线演示 | demo.kuma.pet |
1.2 适用场景
- 自建服务可用性监控与告警。
- 对外公开状态页。
- 替代付费 uptime 监控服务。
1.3 能力边界（官方口径）
- 不支持 NFS 等网络文件系统挂载数据卷，请用本地目录或 Docker volume。
- 不支持 FreeBSD/OpenBSD/NetBSD、Replit/Heroku。
2 功能特性
- 多类型监控：HTTP(s)、TCP、HTTP 关键词、HTTP JSON Query、Websocket、Ping、DNS 记录、Push、Steam 游戏服务器、Docker 容器。
- 告警通知：多渠道通知。
- 代理支持、2FA 支持。
- 状态页：对外展示服务可用性。
3 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/louislam/uptime-kuma | 源码 |
| Docker Hub | louislam/uptime-kuma | 镜像 |
| 安装 Wiki | How to Install | 高级安装 |
| 在线演示 | demo.kuma.pet | 演示 |
4 方式一：Docker Compose
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d启动后访问 http://localhost:3001。
5 方式二：Docker 命令
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2仅监听本机：
docker run ... -p 127.0.0.1:3001:3001 ...6 方式三：非 Docker（Node.js 直跑）
要求：Node.js >= 20.4、Git、pm2。
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
# 直接运行
node server/server.js
# 推荐：用 PM2 后台运行
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
# 开机自启
pm2 startup && pm2 save7 配置项说明
| 配置 | 位置 | 说明 |
|---|---|---|
| 端口 | -p 3001:3001 |
Web 界面 |
| 数据卷 | -v uptime-kuma:/app/data |
数据持久化（勿用 NFS） |
| 重启策略 | --restart=always |
容器自启 |
8 常见故障排查
- 数据卷挂在 NFS 上：官方明确不支持，请改本地目录或命名 volume。
- 端口冲突：修改
-p映射端口。 - 非 Docker 跑不起来：确认 Node.js >= 20.4。
9 风险与说明
- 许可证：以仓库 LICENSE 为准。
- 数据安全：监控数据与通知配置存于
/app/data，注意备份。 - 非官方声明：本文基于官方仓库 README 整理，命令以 master 分支最新为准。