Uptime Kuma: Monitoring and Status Pages

Not every service needs a full observability platform. Uptime Kuma answers a narrower question well: is this endpoint answering, how fast, and for how long has it been failing — with a public status page and mobile-friendly notifications included. It monitors HTTP, TCP ports, ping, DNS records and certificates, runs happily in a single container, and stores everything in SQLite. This guide covers a production-shaped deployment with persistent storage, the monitor types worth configuring, notification routing, and the backup procedure that matters because the database is a single file.

Deploy with persistent storage

# docker-compose.yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"       # expose via a reverse proxy, not directly
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro   # only if monitoring containers
    environment:
      - TZ=Asia/Shanghai

docker compose up -d
docker compose logs -f --tail=50
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3001

Bind the port to localhost and put a reverse proxy in front — the application itself expects that, and it keeps the admin password prompt off the public internet. There are two accounts to think about: the admin login for the UI, and the fact that a public status page is unauthenticated by design. Never put internal hostnames or admin URLs on a public page.

Monitor types and sensible intervals

The keyword assertion is the difference between monitoring that catches real outages and monitoring that reports green while the application serves error pages. Check for a string that only appears in a healthy response, or a JSON field value such as "status":"ok".

# a push monitor is just an HTTP call at the end of your job
curl -s "https://uptime.example.com/api/push/<token>?status=up&msg=backup-ok"

Notifications that survive the night

Configure at least two independent channels: one chat channel for the team and one channel that reaches a phone even when the chat service is what broke. Useful specifics:

• Retries and resend: enable "Resend Notification if Down X times" so a flapping service keeps notifying instead of being silenced after one alert.
• Certificate expiry: separate monitors for the certificate, not the HTTP check, with a 14-day warning window.
• Maintenance windows: schedule them before planned work so the status page shows maintenance instead of an outage.
• Notification groups: route database monitors to the DBA channel and edge monitors to the network channel.

Status pages without leaking information

• Group monitors by service, and name groups for customers, not for internal systems ("Payments", not "prod-payments-svc-03").
• Publish a domain you control, with TLS from your existing certificate process — an expired certificate on a status page defeats the point.

Backup, restore and upgrade

# the whole state is in ./data, including kuma.db (SQLite) and TLS material
docker compose stop uptime-kuma
tar czf uptime-kuma-$(date +%F).tar.gz ./data
docker compose start uptime-kuma

# verify the dump before you trust it
tar tzf uptime-kuma-$(date +%F).tar.gz | head
sqlite3 ./data/kuma.db ".tables"

# restore
docker compose down
rm -rf ./data && tar xzf uptime-kuma-2026-09-26.tar.gz
docker compose up -d

Because the database is a single SQLite file, the backup is trivial and the risk of not having one is obvious. Stop the container before copying so the file is consistent, and keep the archive off the host — a backup on the same server as the monitor is not a backup. Also export the monitor configuration: the UI has a settings export that makes rebuilding on a new host fast if the archive is damaged. If you want a belt-and-braces approach, add the archive step to your existing rsync-based backup routine.

Verification checklist

curl -s -o /dev/null -w "kuma http %{http_code}\n" http://127.0.0.1:3001
docker exec uptime-kuma ls -la /app/data | head
docker exec uptime-kuma sqlite3 /app/data/kuma.db "select count(*) from monitor;" 2>/dev/null || \
  echo "sqlite3 not in image - use the UI"
curl -s https://uptime.example.com/status/main | grep -c "Operational"

1. Every monitor shows a green heartbeat and a plausible response time.
2. A deliberately broken monitor (wrong port) turns red within one interval and notifies.
3. The public status page loads over HTTPS with a valid certificate.
4. Backup archive exists, is not empty, and restores into a throwaway container.
5. At least one notification channel has been tested end to end, from a real failure, not a manual click.

When to graduate to something bigger

Uptime Kuma is a service-availability tool, not a telemetry platform. Once you need per-interface graphs, capacity trending or metric-based alerts, run it alongside rather than instead of a real monitoring stack: Netdata for real-time node metrics, LibreNMS for network devices, or Loki for logs. The split is healthy: Uptime Kuma tells you something is down in the first minute, the other tools tell you why.

原文链接：https://github.com/louislam/uptime-kuma/wiki