Cara guna Uptime Kuma dalam Docker

Apa yang anda bina

Satu kontena kecil tunggal yang memantau pelayan dan laman web anda dari luar. Ia akan memberitahu anda melalui e-mel, Telegram, Discord atau webhook sebaik sahaja sesuatu perkhidmatan gagal bertindak balas. Uptime Kuma ialah satu proses Node yang menggunakan fail SQLite, jadi ia boleh berjalan dengan lancar menggunakan 256-512 MB RAM. Ia menyediakan papan pemuka masa nyata, graf sejarah, dan halaman status awam. Pemasangannya hanyalah fail Compose sepuluh baris; perkara yang paling penting ialah di mana anda menjalankannya dan sama ada amaran anda pernah berjaya diuji, kerana pemantau yang tidak pernah dibuktikan kebolehannya adalah lebih buruk daripada tiada pemantau langsung: ia memberi persepsi selamat sedangkan ia tidak memantau apa-apa.

Jalankan pemantau di lokasi yang tidak terjejas oleh gangguan

Keputusan ini sangat kritikal, jadi ia perlu dilakukan terlebih dahulu. Jangan jalankan Uptime Kuma pada mesin yang sama dengan perkhidmatan yang dipantau. Jika pemantau berada pada pelayan yang sama, kegagalan pelayan tersebut (seperti kehabisan memori) akan menghentikan pemantau juga. Anda tidak akan menerima sebarang amaran kerana pemantau yang mati tidak dapat melaporkan ralat.

Terdapat risiko lain walaupun pelayan masih berfungsi: pemantau yang memantau localhost berkongsi CPU dengan beban kerja tersebut. Lonjakan beban kerja boleh menyebabkan semakan pemantau mengalami timeout dan menukar status sasaran kepada down. Ini adalah amaran palsu sedangkan pengguna sebenar masih boleh mengakses perkhidmatan tersebut.

Oleh itu, jalankan Uptime Kuma pada VPS yang berbeza daripada pelayan yang dipantau. Sebaik-baiknya, gunakan pembekal atau wilayah yang berbeza untuk mengakses perkhidmatan anda melalui internet awam menggunakan hostname, sama seperti pengguna anda. Instance yang murah sudah mencukupi, dan satu VPS pemantauan kecil boleh memantau semua pelayan anda. Untuk memantau jika Kuma sendiri terhenti, tambahkan push heartbeat daripada cron di lokasi lain.

Prasyarat dan saiz

• VPS Ubuntu 24.04 baharu dengan Docker Engine dan plugin Compose v2, dipasang daripada repositori apt Docker sendiri, bukan pakej distro docker.io yang ketinggalan.
• 256 MB RAM memadai untuk beberapa monitor; 512 MB hingga 1 GB adalah selesa untuk puluhan monitor berserta reverse proxy, manakala penggunaan CPU adalah rendah di antara waktu semakan.
• Satu domain dan rekod DNS A (contohnya status.example.com yang menghala ke VPS), hanya jika anda mahukan TLS dan halaman status awam. Pemasangan peribadi boleh mengabaikan DNS dan menggunakan VPN atau terowong SSH.
• Rangkaian keluar ke destinasi amaran: SMTP ke pembekal e-mel anda, atau HTTPS ke Telegram dan Discord.

Fail Compose

Letakkan ini dalam /srv/uptime-kuma/compose.yaml.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data

volumes:
  kuma-data:

Jalankan dan perhatikan proses but pertama:

sudo mkdir -p /srv/uptime-kuma
# save the file above as /srv/uptime-kuma/compose.yaml, then:
cd /srv/uptime-kuma && sudo docker compose up -d
sudo docker compose logs -f uptime-kuma

Permulaan yang betul akan mencatatkan Listening on 3001 dan berhenti menghantar log. Terdapat tiga perkara sengaja dalam fail tersebut.

127.0.0.1:3001:3001, bukan 3001:3001. Docker menerbitkan port dengan peraturan DNAT yang dinilai sebelum ufw melihat paket tersebut, jadi penggunaan 3001:3001 yang kosong akan mendedahkan dashboard anda ke internet awam tanpa mengira firewall anda. Mengikat (binding) ke loopback mengekalkan privasi, dengan hanya reverse proxy yang didedahkan; instans peribadi boleh melangkau proxy dan mengakses 3001 melalui VPN WireGuard hos sendiri sebagai ganti.

Volume bernama pada /app/data. Semua perkara yang diingati oleh Uptime Kuma, pangkalan data SQLite, monitor anda, tetapan notifikasi dan logo halaman status, disimpan di sana. Jika hilang, anda akan bermula dengan skrin admin yang kosong; ini adalah satu-satunya perkara yang wajib anda buat sandaran (backup).

Imej dipaku pada tag utama, :2. Itu adalah barisan stabil semasa; semak Docker Hub untuk versi utama terbaru sebelum menyalinnya, dan jangan sesekali menggunakan tag yang sentiasa berubah seperti latest, yang tidak lagi disokong oleh projek ini. Peralihan versi utama pada imej ini adalah migrasi pangkalan data sehala yang perlu dicetuskan secara sengaja, bukan secara tidak sengaja semasa melakukan pull rutin.

Satu amaran: /app/data mesti berada pada sistem fail dengan kunci fail POSIX. Volume Docker tempatan adalah memadai; pada NFS, pangkalan data SQLite akan rosak dan anda akan mendapat SQLITE_BUSY dan database disk image is malformed, jadi jangan sesekali gunakan perkongsian rangkaian (network share).

Pelaksanaan pertama: cipta akaun admin

Layari instance melalui proxy anda di https://status.example.com, atau melalui terowong SSH: jalankan ssh -L 3001:127.0.0.1:3001 user@your-vps dan buka http://localhost:3001. Halaman pertama ialah borang tetapan untuk nama pengguna dan kata laluan pentadbir; tiada log masuk lalai. Pilih kata laluan yang sebenar: papan pemuka ini dapat melihat alamat dalaman dan token bagi semua perkara yang anda pantau. Lupa kata laluan kemudian? Tetap semula dari hos, bukan dari pelayar:

sudo docker compose exec uptime-kuma npm run reset-password

Tambah saluran pemberitahuan anda terlebih dahulu, dan uji mereka

Tetapkan amaran sebelum menambah pemantau, supaya anda boleh menyertakan saluran semasa mencipta setiap satu. Pergi ke Settings kemudian Notifications kemudian Setup Notification, dan gunakan butang Test pada setiap saluran untuk mengesahkan mesej diterima, kerana pemberitahuan yang tidak diuji adalah punca kedua paling kerap kegagalan sistem berlaku secara senyap.

Email (SMTP). Isi host, port, encryption, username, password, From dan To. Dua kombinasi yang berfungsi ialah 465 dengan "Secure" ditetapkan kepada TLS/SSL, atau 587 dengan STARTTLS. Untuk Gmail dan kebanyakan penyedia dengan pengesahan dua faktor, anda mesti menjana app password; kata laluan akaun biasa akan menghasilkan Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Mesej @BotFather, hantar /newbot, salin bot token. Untuk chat ID anda, mesej bot baharu tersebut sekali, buka https://api.telegram.org/bot<token>/getUpdates, dan baca chat.id daripada JSON. Bot yang tidak pernah anda mesej sebelum ini mempunyai getUpdates yang kosong dan tiada tempat untuk menghantar mesej.

Discord. Di dalam saluran, buka Edit Channel kemudian Integrations kemudian Webhooks kemudian New Webhook, salin URL, dan tampal sebagai pemberitahuan Discord.

Generic webhook. Untuk apa-apa sahaja yang lain, seperti Slack incoming webhook, endpoint tersuai, atau hook automasi rumah, jenis Webhook akan menghantar payload JSON melalui POST ke URL yang anda bekalkan, dan integrasi Apprise yang disertakan merangkumi kebanyakan sembilan puluh-an perkhidmatan lain dalam senarai tersebut.

Tambah monitor, satu demi satu

Klik Add New Monitor, pilih jenis, dan tetapkan Friendly Name, Check Interval (60 saat adalah munasabah), Retries (kegagalan berturut-turut sebelum status "down"; gunakan 2 atau 3 supaya satu paket yang hilang tidak mencetuskan amaran), dan pemberitahuan yang perlu dihantar. Jenis yang akan anda gunakan:

• HTTP(s). URL penuh. Status "up" bermaksud kod status diterima (200-299 secara lalai; lebarkan julat ini di bawah Accepted Status Codes jika 301 atau 401 adalah normal bagi anda). Digunakan secara meluas untuk laman web dan API.
• HTTP(s) - Keyword. Permintaan yang sama, tetapi status "up" juga memerlukan kehadiran rentetan teks dalam kandungan, atau tanpa pilihan Invert. Ini mengesan laman web yang memulangkan 200 OK semasa memaparkan "Error establishing a database connection", yang mana pemeriksaan HTTP biasa akan menganggapnya sebagai sihat.
• TCP Port. Sambungan TCP terus ke hos dan port, untuk perkara yang bukan HTTP: SSH pada 22, Postgres pada 5432, pelayan SMTP pada 25, atau pelayan permainan.
• Ping. ICMP echo: untuk semakan kebolehcapaian dan kependaman yang ringan. Namun, banyak rangkaian dan tembok api awan menyekat ICMP, jadi monitor ping yang berwarna merah boleh bermaksud "hos tergendala" atau "pembekal menyekat ping"; sahkan dengan monitor TCP.
• DNS. Menyelesaikan rekod (A, AAAA, MX, TXT dan sebagainya) terhadap penyelesai yang anda namakan, dan boleh mengesahkan jawapan tersebut, bagi mengesan gangguan pendaftar atau DNS dengan lebih awal.
• Push. Monitor jenis "inside-out", akan dibincangkan selepas ini.

Memantau tugasan cron dengan pemantau push (heartbeat)

Setiap pemantau di atas mengakses perkhidmatan anda dari luar. Pemantau push berfungsi secara terbalik: Uptime Kuma menunggu, dan tugasan anda memanggilnya untuk menyatakan "Saya telah berjalan." Ini adalah satu-satunya cara jujur untuk memantau sandaran atau cron: semakan HTTP hanya tahu URL memberi respons, tetapi hanya tugasan tersebut yang tahu jika ia telah selesai.

Buat pemantau jenis Push. Uptime Kuma akan menjana URL unik seperti:

https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=OK&ping=

Tetapkan Heartbeat Interval mengikut kekerapan tugasan berjalan, ditambah sedikit masa tambahan. Kemudian, tambah satu baris pada bahagian akhir skrip supaya ia hanya dihantar jika berjaya:

#!/usr/bin/env bash
set -euo pipefail
# ... your backup or job runs here; set -e aborts on any failure ...
curl -fsS --retry 3 "https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=backup+ok&ping="

Jika tugasan gagal, set -e akan terhenti sebelum curl dijalankan; jika pelayan terpadam, ia juga tidak akan berjalan. Dalam kedua-dua keadaan, heartbeat akan terhenti, dan sebaik sahaja tempoh interval-tambah-cubaan (retries) tamat, Uptime Kuma akan menukar status pemantau kepada down dan menghantar amaran kepada anda. Anggap token push tersebut sebagai rahsia: sesiapa yang memilikinya boleh memalsukan status sihat.

Bina halaman status awam

Halaman status adalah paparan untuk pelanggan: ia menunjukkan perkhidmatan yang sedang aktif dan sejarah terkini tanpa mendedahkan papan pemuka anda. Pergi ke Status Pages kemudian New Status Page, berikan nama dan slug (laluan awam, seperti /status/main), seret pemantau yang anda mahukan ke dalam kumpulan seperti "Websites" dan "APIs", tambah logo dan deskripsi ringkas, kemudian klik Save. Anda juga boleh menghubungkan halaman tersebut ke domain sendiri supaya status.example.com melayankannya secara terus.

Dua perkara perlu diperhatikan: hanya tambah pemantau yang anda sedia untuk jadikan awam, kerana halaman status mendedahkan kewujudan sesuatu perkhidmatan dan status aktifnya; dan papan pemuka kekal di sebalik log masuk anda manakala halaman status adalah awam secara sengaja dan tidak memerlukan pengesahan.

Letakkan di belakang reverse proxy dengan TLS, dan perhatikan websockets

Untuk instans awam, letakkan reverse proxy di hadapan kontena yang terikat pada loopback untuk TLS dan nama hos. Perincian yang sering menyebabkan ralat: UI Uptime Kuma adalah aplikasi Socket.IO secara langsung, jadi proxy mesti menaik taraf (upgrade) sambungan WebSocket. Jika gagal, halaman akan dimuatkan tetapi tidak pernah bersambung; papan pemuka akan kekal pada status "Connecting...", denyutan jantung (heartbeats) langsung tidak dikemas kini, dan konsol pelayar menunjukkan WebSocket connection to 'wss://.../socket.io/...' failed.

Pasang nginx dan certbot, kemudian tulis vhost yang melakukan proxy ke port loopback. Gunakan port 80 buat masa ini dan biarkan certbot menambah TLS kemudian; cabaran, pemasa pembaharuan dan mod kegagalannya dibincangkan dalam mengeluarkan sijil Let's Encrypt dengan certbot dan nginx.

sudo apt install -y nginx certbot python3-certbot-nginx

Simpan ini sebagai /etc/nginx/sites-available/status.example.com; dua baris WebSocket adalah yang paling penting:

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

    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;
        proxy_read_timeout 3600s;
    }
}

Aktifkan tapak, uji konfigurasi, kemudian biarkan certbot menulis semula blok tersebut untuk mendengar pada port 443, masukkan sijil dan tambah penghalaan (redirect) HTTP-ke-HTTPS:

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Pasangan Upgrade dan Connection "upgrade" adalah bahagian yang paling kritikal, dan proxy_read_timeout 3600s menghalang nginx daripada memutuskan sambungan soket yang lama; certbot menyalin kedua-duanya ke dalam blok 443 yang dijana. Jika anda sudah menjalankan beberapa kontena di belakang satu proxy, menghalakan mereka melalui Traefik dengan TLS automatik melakukan perkara yang sama menggunakan label kontena dan menghalarkan naik taraf WebSocket secara lalai.

Jangan gunakan basic-auth pada keseluruhan vhost, kerana itu akan menyekat halaman status awam dan titik akhir /api/push. Kekalkan log masuk terbina dalam Uptime Kuma, tambah fail2ban untuk memantau kegagalan log masuk berulang jika ia terdedah ke internet, dan jika papan pemuka tidak perlu bersifat awam, abaikan proxy dan akses melalui VPN.

Pemantauan tamat tempoh sijil yang betul

Pemantau HTTP(s) juga boleh memberi amaran sebelum sijil TLS tamat tempoh: tandakan Certificate Expiry Notification dan Uptime Kuma akan menghantar amaran mengikut bilangan hari yang ditetapkan. Dua kesilapan menyebabkan ralat pembacaan. Pantau melalui hostname, bukan IP, jika tidak permintaan tanpa SNI akan menerima sijil lalai pelayan dan anda akan melihat Hostname/IP does not match certificate's altnames. Selain itu, jangan tandakan Ignore TLS/SSL Error pada pemantau yang memerlukan amaran tamat tempoh: pilihan itu adalah untuk hos dalaman dengan sijil kendiri (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), tetapi ia akan menghentikan Uptime Kuma daripada memeriksa sijil tersebut sepenuhnya, termasuk tarikh tamat tempoh.

Backups: ia adalah satu direktori

Kerana semua data berada dalam /app/data, sandaran (backup) adalah salinan volum tersebut yang diambil semasa kontena dihentikan, supaya fail SQLite adalah konsisten:

cd /srv/uptime-kuma
sudo docker compose stop
sudo docker run --rm \
  -v uptime-kuma_kuma-data:/data \
  -v /var/backups/kuma:/backup \
  alpine tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .
sudo docker compose start

Sahkan nama sebenar volum dengan docker volume ls | grep kuma terlebih dahulu, kerana Compose menambah awalan nama direktori projek padanya. Kemudian salin fail tarball tersebut ke luar daripada pelayan, kerana sandaran pada VPS yang sama hanyalah salinan, bukan sandaran sebenar. Proses pemulihan adalah sebaliknya: hentikan stack, ekstrak ke dalam volum /app/data yang kosong, kemudian mulakan semula.

Kemas Kini

Kemas kini adalah proses penarikan imej:

cd /srv/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

Kontena baharu akan menjalankan sebarang migrasi pangkalan data pada permulaan pertama; pantau docker compose logs -f. Lakukan sandaran di atas sebelum melakukan penarikan, dan kekal dalam tag utama: peralihan daripada :1 ke :2 adalah migrasi sehala, jadi buat sandaran terlebih dahulu dan semak nota keluaran.

Mod kegagalan, bersama rentetan yang akan anda lihat

Status "down" palsu pada monitor yang menghala ke localhost. Monitor bertukar merah dengan timeout of 48000ms exceeded atau connect ETIMEDOUT, namun perkhidmatan masih menjawab dari komputer riba anda. Jika ia menghala ke hos yang sama dengan Uptime Kuma, lonjakan CPU atau memori telah menghalang semakan tersebut, bukan sasaran. Pindahkan monitor ke VPS berasingan dan halakan ke nama hos awam.

connect ECONNREFUSED 127.0.0.1:443 (atau mana-mana port). Tiada apa yang mendengar pada port tersebut: sama ada perkhidmatan sedang terhenti, atau anda memantau localhost dari dalam kontena, di mana 127.0.0.1 adalah kontena tersebut, bukan pelayan anda. Pantau nama hos awam, bukan loopback.

Invalid login: 535-5.7.8 Username and Password not accepted pada ujian e-mel. Kredential SMTP adalah salah, atau penyedia memerlukan kata laluan khusus aplikasi tetapi anda memberikan kata laluan akaun anda. Jana kata laluan aplikasi dan tampal kata laluan tersebut.

connect ETIMEDOUT atau queryA ETIMEDOUT <host> pada ujian e-mel. Port salah, atau penyedia menyekat SMTP keluar. Pastikan 465 atau 587 sepadan dengan tetapan Secure/STARTTLS, dan uji dari hos dengan nc -vz smtp.example.com 587. Banyak penyedia menyekat 25 keluar dan sesetengahnya menyekat port penghantaran sehingga anda memohon.

self signed certificate atau unable to verify the first certificate pada ujian e-mel. Pelayan SMTP anda membentangkan sijil yang tidak dipercayai oleh Node; baiki sijil pelayan mel tersebut daripada sekadar menutupinya.

Dashboard tersekat pada "Connecting...", konsol menunjukkan WebSocket connection ... failed. Reverse proxy tidak menaik taraf (upgrade) WebSocket. Tambah pengepala Upgrade dan Connection "upgrade" pada nginx, atau gunakan proxy yang memajukan pengepala tersebut secara lalai seperti Traefik atau Caddy. HTML dimuatkan kerana itu adalah HTTP GET biasa; hanya soket langsung yang memerlukan naik taraf tersebut.

Monitor tamat tempoh sijil tidak pernah memberi amaran, atau memberi amaran secara salah. Sama ada Ignore TLS/SSL Error ditanda, yang melumpuhkan semakan sijil, atau monitor menghala ke IP dan membaca sijil yang salah kerana ketiadaan SNI, menunjukkan Hostname/IP does not match certificate's altnames. Nyah tanda (untick) pilihan ignore, pantau melalui nama hos.

SQLITE_BUSY atau database disk image is malformed dalam log. Volume /app/data berada pada sistem fail tanpa penguncian fail yang betul, biasanya NFS; pindahkannya ke volume Docker tempatan dan pulihkan daripada sandaran.

FAQ

Di manakah saya patut menjalankan pemantau uptime saya?

Pada pelayan yang berbeza daripada pelayan yang dipantau, sebaik-baiknya pembekal atau wilayah lain, yang mengaksesnya melalui hostname melalui internet awam sama seperti pengguna anda. Jika pemantau berkongsi pelayan yang sama dengan sasaran, gangguan yang mematikan pelayan tersebut akan mematikan pemantau juga, dan hos yang terlalu beban akan memberikan amaran "down" walaupun perkhidmatan sebenarnya berfungsi. Sebuah VPS berasingan yang kecil dapat mengelakkan kedua-dua masalah ini.

Bagaimanakah cara untuk mendapatkan amaran pada Telegram atau e-mel?

Tambah saluran di bawah Settings then Notifications, kemudian sambungkannya ke setiap pemantau. Untuk Telegram, cipta bot dengan @BotFather dan baca chat.id daripada https://api.telegram.org/bot<token>/getUpdates; untuk e-mel, gunakan 465 untuk SSL atau 587 untuk STARTTLS dengan kata laluan aplikasi jika pembekal anda menggunakan pengesahan dua faktor. Tekan Test dan sahkan mesej diterima sebelum anda bergantung kepadanya.

Bolehkah Uptime Kuma memantau cron job atau skrip sandaran?

Ya, itu adalah pemantau Push: Uptime Kuma memberikan anda URL dan anda curl ia pada akhir skrip supaya ia hanya berfungsi jika berjaya. Jika tugasan gagal atau pelayan tergendala, isyarat heartbeat tidak akan sampai, dan anda akan menerima amaran selepas tempoh selang masa tamat. Ini adalah satu-satunya cara yang boleh dipercayai untuk mengetahui jika tugasan berjadual benar-benar dijalankan, memandangkan pemeriksaan luaran tidak dapat melihat ke dalam tugasan tersebut.

Uptime Kuma vs Zabbix, yang manakah patut saya jalankan?

Uptime Kuma menjawab "adakah ia berfungsi, dari luar, dan adakah ia memberi amaran kepada saya" dalam masa sepuluh minit dengan penggunaan sumber yang sangat rendah, serta halaman status. Ia tidak mengumpul metrik mendalam seperti trend CPU, memori dan cakera atau ambang had (threshold) bagi seluruh rangkaian; untuk tujuan itu, pelayan pemantauan Zabbix yang lengkap adalah alat berasaskan ejen yang lebih berat, dan ramai orang menjalankan kedua-duanya. Masih belum memutuskan apa yang hendak dijalankan? ringkasan kami tentang apa yang perlu dihoskan sendiri pada 2026 memberikan konteks tentang pemantauan.