Uptime Kuma：自托管监控与告警面板（轻量开源）｜部署与使用全指南
本文基于 Uptime Kuma 官方 GitHub README（master 分支）与 2026 年公开维护信息整理，面向中文自托管用户，覆盖从零部署、配置、实操到排障、升级、合规的完整链路。
官方主控制台截图：
一、项目简介与适用场景
Uptime Kuma 是一款由 Louis Lam（louislam）主导开发的自托管（self-hosted）服务可达性与延迟监控面板，使用 Vue 3 + Node.js 构建，定位是「开源版的 Uptime Robot」。它把你在乎的网站、API、端口、证书、容器等统一纳入一个轻量仪表盘，按最短 20 秒的间隔探活，并在异常时通过 90+ 种通知渠道推送告警。
适用场景
个人 / 家庭实验室（Homelab）：在树莓派、NAS、迷你主机上监控家中服务（NAS 面板、Pi-hole、Home Assistant、自建网盘）是否在线。
小微企业 / 创业团队：用一台低配云服务器监控官网、API、数据库端口，省去 SaaS 订阅费。
运维 / 开发自监控：监控内部系统（GitLab、Jenkins、数据库、中间件端口），通过 Telegram / 钉钉（Webhook 中转）/ 邮件第一时间获知宕机。
对客户公示状态：用「状态页（Status Page）」对外展示各服务可用率与事故时间线，提升透明度。
SSL 证书到期提醒：内置证书信息展示与告警，避免证书过期导致服务不可用。
不适用场景（边界）
它不是 APM / 全链路性能分析工具（不采集吞吐、错误率、RUM），需要更细指标请用 Grafana / Datadog 等。
它本身也需要被监控（「谁来监控监控者」），生产环境建议配合外部心跳或独立部署。
社区项目，无商业 SLA 支持。
二、核心功能逐条拆解
下表逐条拆解 README「Features」及 v2 实际能力：
浅色模式界面示例：
三、全套官方链接
关于 Demo：官方在 README 中提供了一个临时在线 Demo（https://demo.kuma.pet/start-demo，位于德国法兰克福），但所有数据会在 10 分钟后清空，仅用于体验、不可作为长期可用服务。按本教程设定「无独立/长期 Demo」，正式使用请自行部署。
四、硬件与环境前置要求
4.1 硬件建议（经验值，随监控数量线性增长）
官方运维站点的实测建议：最小 1 vCPU / 1 GB RAM / 20 GB 存储（基于 ~25 个探针的测试环境）。资源消耗主要取决于监控项数量与历史保留时长。
4.2 运行环境
4.3 关键注意
存储后端限制：Uptime Kuma 不支持 NFS（网络文件系统） 作为数据目录（
/app/data）。务必映射到本地目录或 Docker 卷，否则会出现数据库锁/损坏。v2 镜像默认 Rootless：官方 Docker 镜像 v2 起默认以非 root 用户（UID 1000）运行，数据目录需保证该用户可读写（见第六章与第九章）。
端口预留：默认占用宿主机
3001，部署前确认未被占用。
五、多平台部署实战
所有方式最终均监听容器内
3001，通过-p或 composeports映射到宿主机。
5.1 Docker Compose（最推荐、最易维护）
# 1. 创建工作目录
mkdir uptime-kuma && cd uptime-kuma
# 2. 拉取官方 compose 文件（master 分支）
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
# 3. 启动（后台）
docker compose up -d
官方 compose.yaml 内容如下（已自带 restart: unless-stopped 与数据卷）：
services:
uptime-kuma:
image: louislam/uptime-kuma:2
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
# <Host Port>:<Container Port>
- "3001:3001"
启动后访问 http://localhost:3001 或 http://<你的服务器IP>:3001。
5.2 单条 Docker 命令（快速验证）
docker run -d \
--restart=always \
-p 3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:2
若只想在本机访问（不暴露到局域网/公网），把端口映射改为
-p 127.0.0.1:3001:3001。
5.3 Linux 源码运行（Node.js + PM2）
要求 Node.js ≥ 20.4。适合需要深度定制或无法用 Docker 的环境。
# 1. 克隆仓库
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
# 2. 安装依赖并构建（npm run setup 会完成依赖安装与前端构建）
npm run setup
# 方式 A：前台直接运行（调试用）
node server/server.js
# 方式 B（推荐）：用 PM2 后台常驻
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
# 查看日志
pm2 monit
# 设为开机启动
pm2 startup && pm2 save
访问同样为 http://localhost:3001。
5.4 NAS 部署简述
Synology（群晖）DSM 7+
套件中心安装「Container Manager」（即 Docker）。
进入 Container Manager → 项目 → 新建，使用上面 5.1 的
compose.yaml（或注册表搜索louislam/uptime-kuma，标签2）。映射端口
3001，存储设置中把容器/app/data挂载到本地卷（如docker/uptime-kuma）。或通过 SSH 直接执行 5.1/5.2 的 Docker 命令亦可。
开机自启：Container Manager 项目默认随 DSM 启动；计划任务可加开机触发脚本（见第七章）。
Unraid
应用（Apps）→ 社区应用（Community Applications）搜索
Uptime Kuma（通常名uptime-kuma或louislam-uptime-kuma）。安装时设置：容器端口
3001、主机端口自定义、为/app/data配置一个持久路径（如/mnt/user/appdata/uptime-kuma）。勾选「Start on Boot」即可开机自启。
六、配置文件参数全解
Uptime Kuma 绝大多数配置通过 Web 界面完成，没有 YAML/文件式配置文件（这是它与 Gatus 等工具的区别）。但部署层面有几个关键「配置点」必须理解。
6.1 Docker 数据卷（最重要）
6.2 端口映射参数
6.3 容器重启策略
6.4 环境变量（进阶 / 外部数据库）
基础部署通常无需任何环境变量。以下为 v2 外部数据库（MariaDB/MySQL） 相关变量（仅在首次启动前、通过 UI 选择外部数据库或设置环境变量时使用；变量名以官方 Wiki 为准，部署前请核对）：
提示：普通用户保持默认 SQLite 即可，无需设置上表。其余如自定义 CA 可用
NODE_EXTRA_CA_CERTS注入。
6.5 反向代理相关
Uptime Kuma 使用 WebSocket 实时推送数据，反代必须放行 Upgrade 头；若挂子路径，还需在「Settings → Reverse Proxy」中设置 Base URL。详见第八章与第九章。
七、启动 / 后台常驻 / 开机自启 / 改端口 教程
7.1 启动与后台常驻
Docker / Compose：
-d（run）或docker compose up -d即后台运行；--restart=always/unless-stopped保证退出后自动拉起。源码 PM2：
pm2 start server/server.js --name uptime-kuma即后台常驻。
常用运维命令：
# 查看容器日志
docker logs -f uptime-kuma
# 查看容器状态
docker ps | grep uptime-kuma
# 停止 / 启动
docker stop uptime-kuma && docker start uptime-kuma
# PM2 日志
pm2 monit
7.2 改端口（三种做法）
做法 A：docker run 改映射
docker run -d --restart=always -p 8080:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
# 访问 http://<IP>:8080
做法 B：docker compose 改 ports
编辑 compose.yaml：
ports:
- "8080:3001" # 把宿主机端口改为 8080
然后 docker compose up -d。
做法 C：仅本机 + 反代 / SSH 隧道
docker run -d --restart=always -p 127.0.0.1:3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
7.3 开机自启
八、功能实操教程
8.1 首次登录与初始化
浏览器打开
http://<IP>:3001（或你改过的端口）。首次进入会要求创建管理员账号（用户名 + 密码）。请使用强密码并牢记——v2 支持 2FA，建议随后在设置中开启。
进入主控制台，界面即类似第一章的仪表盘截图。
8.2 添加监控项（Monitor）
点击左上角 「+ 新建监控」（Add New Monitor）。
选择监测类型（Type），常用： -
HTTP(s)：填 URL，判断返回 200 即认为在线。 -HTTP(s) Keyword：额外填写期望包含的「关键字」，防止「200 但内容错误」。 -HTTP(s) JSON Query：用 JSONPath 校验返回 JSON 字段，适合 API 健康检查。 -TCP：填host:port，判断端口可达（数据库、邮件服务端口）。 -Ping：ICMP 探测主机存活。 -DNS：检查域名解析记录与 TTL。 -Docker/Push/Steam/WebSocket等按场景选择。设置监测间隔（默认 20 秒，可调大）。
选择通知渠道（见 8.3）与重试/超时参数。
保存后即开始探活，仪表盘实时显示状态与延迟图表。
8.3 设置通知渠道（Notifications）
进入 Settings → Notifications（或监控项内「通知」） → 「+ 新建通知」。
选择渠道类型，例如 Telegram： - 先与
@UptimeKumaBot对话，获取Chat ID； - 填入 Bot Token 与 Chat ID 保存并「测试（Test）」。其他常用：Discord（Webhook URL）、Email（SMTP 账号密码）、Slack、Gotify、Webhook（可中转钉钉/企业微信）。
可在每个监控项里指定「生效通知」，实现不同服务告警发往不同群。
Telegram 通知示例：在「Settings → Notifications → Telegram」填入 Bot Token 与 Chat ID 后保存，即可在监控项中选择该渠道接收告警（官方文档含配图，本机未成功拉取，故以文字说明代替）。
8.4 状态页分享（Status Page）
Dashboard → Status Pages → 新建状态页。
选择要对外展示的监控项分组、设置标题/Logo/域名。
可把状态页映射到独立域名（在反代/DNS 中指向 Uptime Kuma，并在状态页设置域名）。
状态页无需登录即可访问，适合对客户提供可用率公示。
状态页效果截图（官方）：
8.5 反向代理配置（Nginx 示例）
生产环境强烈建议把 Uptime Kuma 放在反代后终止 TLS。关键点：必须支持 WebSocket（Upgrade 头）。
server {
listen 443 ssl;
server_name status.example.com;
# SSL 配置省略...
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
子路径部署（如
https://example.com/uptime）：除上面反代外，还需在 Uptime Kuma「Settings → Reverse Proxy」中设置 Base URL 为/uptime，否则前端资源路径会 404。Caddy / Traefik 同理需放行 WebSocket；Caddy 默认
reverse_proxy已自动处理 Upgrade 头。
九、全套报错故障排查
以下为高频问题（覆盖题目要求：端口占用、容器退出、数据卷权限、通知失败、反代 WS、内存不足等，共 10 条）。
通用排查顺序：
docker ps看状态 →docker logs uptime-kuma看错误 → 检查端口/磁盘/权限 → 查官方 Wiki 与 GitHub Issues。
十、升级 / 回滚 / 卸载 教程
10.1 自动升级（Watchtower）
适合「始终跟进最新稳定版」的个人用户：
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower \
--cleanup uptime-kuma
注意：Watchtower 会自动拉取最新标签并重建容器。v1→v2 这类大版本跳跃有数据迁移风险，不建议用 Watchtower 跨大版本，应手动按 Wiki 迁移。
10.2 手动升级（推荐，可控）
# 1. 先备份数据（停机最安全）
docker stop uptime-kuma
sudo tar czf uk-backup-$(date +%F).tar.gz -C /path/to/data .
# 2. 拉取最新镜像并重建
docker pull louislam/uptime-kuma:2
docker rm -f uptime-kuma
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
10.3 回滚（回退版本）
Uptime Kuma 镜像支持版本标签，回滚只需指定旧标签重建（确保已有兼容备份）：
docker rm -f uptime-kuma
# 回退到指定版本（示例标签，请按实际可用标签调整）
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1
⚠️ v2 的数据结构与 v1 不兼容；跨大版本回滚前必须恢复对应版本的数据库备份，否则可能损坏数据。生产环境「先备份、再升级、可回退」。
10.4 卸载与数据清理
# 停止并删除容器
docker stop uptime-kuma && docker rm uptime-kuma
# 删除命名卷（数据一并清除，不可恢复！）
docker volume rm uptime-kuma
# 若是宿主机目录挂载，手动删除目录
# rm -rf /path/to/uptime-kuma/data
# 卸载 Watchtower（若使用）
docker rm -f watchtower
卸载即永久删除所有监控配置与历史，请确认已导出/备份所需数据（设置中可导出配置 JSON）。
十一、商用许可与合规风险提示
11.1 许可证：MIT，可商用
Uptime Kuma 采用 MIT License，允许商业使用、修改、再分发，仅要求保留版权与许可声明，无 Copyleft 传染、无需开源你的私有改动、无功能限制。你可以在公司内部、对客户提供的付费服务背后使用它。
11.2 商用注意事项
保留许可声明：再分发（如打包进产品）时需附带 MIT 原文与版权声明。
商标：MIT 不授予「Uptime Kuma」名称/Logo 的商标使用权，对外宣传注意避免误导为官方。
无担保：MIT 明确「按原样提供，不提供担保」，生产关键链路请自行评估与加固。
11.3 监控他人的合规边界（重要）
监控你自己拥有/授权的资产（自有服务器、域名、API）完全合规。
监控第三方公网服务（如探测竞品网站是否在线）一般属于正常可达性探测，但高频、大并发探测可能被视为骚扰或违反对方服务条款（ToS），建议控制频率、遵守
robots/ToS。切勿用于：
未经授权扫描/探测他人内网、端口或设备（可能触犯《网络安全法》及类似法规，构成非法侵入）；
分布式高频探活对他人服务造成拒绝服务（DoS）影响；
在他人不知情下监控其私有系统。
数据合规：若状态页/通知中包含客户名称、IP 等个人信息，注意遵循相关隐私保护法规（如 GDPR/个保法），最小化展示。
11.4 运维责任提示
Uptime Kuma 是社区开源项目，无商业 SLA。用于业务关键监控时，建议：① 监控实例本身独立部署并外部心跳保活；② 定期备份 /app/data；③ 启用 2FA 与反代 TLS；④ 重要告警配置多通道冗余（如同时 Telegram + 邮件），避免单点通知失败导致漏报。
本文所有截图均来自 Uptime Kuma 官方 README 引用的官方演示图，命令与参数以官方仓库当前（master）文档为准。部署前请再次核对官方 Wiki 与镜像标签的最新说明。