Docker 好项目推荐（第 1 期）：Uptime Kuma —— 自建服务监控面板|个人主页

这是「Docker 好项目」系列的第 1 期。每期挑一个真正能在自己服务器上跑起来、并且能解决具体问题的项目，给出能直接复制的配置。

你的博客、网盘、下载机跑在服务器上，但它们到底有没有挂，通常要等你自己打开网页才发现——或者更糟，等读者告诉你。

Uptime Kuma 就是解决这件事的：一个自托管的可用性监控面板，7×24 盯着你的服务，一挂就立刻推送到你的手机。MIT 协议，开源免费，监控数量不限，一个 1 核 1G 的小机器就能跑。

Uptime Kuma 监控面板

它到底能干什么

先说清楚能力边界，避免装完发现不是自己想要的：

监控类型：HTTP(s)、TCP 端口、Ping、DNS、Push（被动心跳）、Docker 容器状态、MQTT、SNMP、Steam 游戏服务器等
告警渠道：90 多种，常用的 Telegram、Discord、飞书、企业微信、邮件 SMTP、ntfy、Webhook 都支持
状态页：可以生成一个公开的状态页（Status Page）给访客看，也能设成仅自己可见
数据自持：所有数据在你自己的机器上，SQLite 单文件，备份就是复制一个目录

它不做的是：不做性能指标采集、不出 Grafana 那种花哨图表。它就是专注回答一个问题——服务还活着吗。

部署前准备

确认 Docker 和 Compose 插件都在：

docker --version
docker compose version

华为云这类云主机还要注意一点：安全组。后面用到的端口（默认 3001）需要在云控制台的安全组里放行，光在服务器里配没用。

方式一：一行命令跑起来

适合先试试水：

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

方式二：docker-compose（推荐）

正式用一定要写成文件，以后升级、迁移都靠它。

mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma

新建 docker-compose.yml：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

启动：

docker compose up -d
docker compose logs -f uptime-kuma

看到日志里出现 Listening on 3001 就说明起来了。

几个配置项为什么要这么写

这一段是重点，照抄容易、抄错也容易：

配置	说明
`image: ...:2`	不要写 `:latest`。`:2` 会跟随 v2 稳定线，`:latest` 是滚动标签，跨大版本升级会触发数据库迁移，容易出事
`127.0.0.1:3001:3001`	只监听本机回环。Docker 的端口映射走 DNAT，优先级高于服务器防火墙，直接写 `3001:3001` 等于把面板暴露到公网
`./data:/app/data`	监控项、通知配置、状态页、SQLite 数据库全在这里，这是唯一必须备份的东西
`/etc/localtime` + `TZ`	不挂的话容器内是 UTC，告警时间和你看到的对不上，排查问题时很折磨
`healthcheck`	让 Docker 自己能判断容器是否真的健康，配合 Watchtower 之类的自动更新更安全

在 1Panel 里怎么搞

如果你用 1Panel，其实更省事：

应用商店 → 搜索「Uptime Kuma」，有官方应用可以直接装，端口和存储卷会自动配好
想自己控制的话：容器 → 编排 → 创建编排，把上面的 docker-compose.yml 贴进去，填个名称即可
装完在 防火墙 / 安全组 里确认端口状态

首次访问：先建管理员

浏览器打开 http://服务器IP:3001（或你配的域名），第一屏是创建管理员账号的引导。

Uptime Kuma 没有默认账号密码，第一个注册的就是管理员。密码务必设强一点——这个面板能看到你所有服务的内部地址和通知 Token。

万一忘了密码，在服务器上重置：

cd /opt/uptime-kuma
docker compose exec uptime-kuma npm run reset-password

加第一个监控项

进面板后点 Add New Monitor：

Monitor Type：HTTP(s)
Friendly Name：起个自己认得出的名字，比如「博客首页」
URL：https://你的域名
Heartbeat Interval：检查间隔，默认 60 秒；个人站用 120~300 秒就够，别给自己找事
Retries：重试次数，建议设 2~3，避免网络抖动导致误报

保存后主页会出现这张卡片，绿色就是在位。

一定要配通知，否则等于白装

监控不推送告警，就只是块好看的仪表盘。Settings → Notifications → Setup Notification：

Telegram：填 Bot Token 和 Chat ID，30 秒配完，推送最稳
ntfy：不用注册，填个 topic 就能收推送，最省事
SMTP 邮件：465 端口配 Secure = TLS/SSL，或 587 配 STARTTLS，二选一，别混

每个渠道配完记得点 Test 按钮，确认手机真的收到了再往下走。没测试过的通知渠道，是「装了监控但服务挂了一整晚没人知道」的头号原因。

套上域名和 HTTPS

用 1Panel 的话，OpenResty 反代很直接：网站 → 反向代理 → 新建，代理地址填 127.0.0.1:3001，域名填 status.你的域名，然后申请 Let's Encrypt 证书开启 HTTPS。

单独用 Nginx 的话，配置长这样：

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;

        # WebSocket 必须加，否则面板实时刷新不工作
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

WebSocket 那三行不能省。Uptime Kuma 靠 WebSocket 做实时状态更新，漏掉的话面板能打开但数据不刷新，很容易误判成部署失败。

踩坑清单

数据目录别放 NFS 等网络存储。SQLite 需要 POSIX 文件锁，放网络盘会报 SQLITE_BUSY 甚至把库写坏
别把 3001 直接暴露公网。挂个反代 + HTTPS，成本几乎为零
监控间隔别设太短。间隔 20 秒、几十个监控项，小机器会被自己拖慢
升级前先备份 ./data。跨大版本（1.x → 2.x）是单向数据库迁移，回不去
Push 类型适合监控定时任务。脚本跑完往 Kuma 推一个心跳，任务没按时执行就会告警，比查日志快得多

备份

就一句话——定期打包 ./data：

cd /opt/uptime-kuma
tar czf kuma-backup-$(date +%F).tar.gz data/

配合 crontab 或者 1Panel 的计划任务，每周跑一次，丢到对象存储里。

小结

Uptime Kuma 属于那种「装完就后悔没早装」的工具：五分钟部署，之后每次服务出问题你都是第一个知道的，而不是最后一个。

适合：有自建博客 / 网盘 / 下载机、想低成本掌握服务状态的个人用户。
不适合：需要指标采集、性能分析、分布式链路追踪的场景——那是 Prometheus + Grafana 的活。

下期继续聊另一个 Docker 项目。

项目地址：https://github.com/louislam/uptime-kuma
官方文档：https://uptimekuma.org