Uptime Kuma چیست؛ ابزار متن‌باز مانیتورینگ آپتایم سایت با هشدار قطعی

Uptime Kuma چیست؟ راهنمای مانیتورینگ آپتایم سایت با هشدار تلگرام، بله و صفحه وضعیت

ساعت سه بامداد سایت از دسترس خارج می‌شود و تا ساعت نه صبح که اولین مشتری در پشتیبانی پیام می‌دهد، کسی خبر ندارد. شش ساعت قطعی، بدون یک هشدار. Uptime Kuma چیست و چه ربطی به این ماجرا دارد؟ یک ابزار متن‌باز و رایگان است که هر چند ثانیه سایت، API، دیتابیس یا دامنهٔ شما را چک می‌کند و همان لحظه‌ای که چیزی از کار افتاد، در تلگرام، بله یا ایمیل خبرتان می‌کند. خودتان نصبش می‌کنید و داده‌هایش روی سرور خودتان می‌ماند.

در این راهنما می‌بینید Uptime Kuma دقیقاً چه چیزهایی را پایش می‌کند، چطور نصبش کنید، اولین مانیتور و هشدار را چطور بسازید، با Push monitor چطور کرون‌جاب‌ها و بکاپ‌ها را زیر نظر بگیرید و مهم‌تر از همه، این ابزار را کجا اجرا کنید که وقتی سرورتان خوابید، خودش هم همراهش نخوابد.

Uptime Kuma چیست و چه کاری انجام می‌دهد؟

Uptime Kuma یک ابزار مانیتورینگ آپتایم (uptime monitoring) است که لوئیس لام (Louis Lam) آن را با مجوز MIT منتشر کرده است. «Kuma» در ژاپنی یعنی خرس؛ یک خرس کوچک که حواسش به سایت شماست. برنامه با Node.js نوشته شده، یک داشبورد وب دارد و به‌صورت پیش‌فرض روی پورت 3001 بالا می‌آید.

کارش ساده است: برای هر سرویس یک «مانیتور» می‌سازید، مشخص می‌کنید هر چند ثانیه چک شود و اگر جواب نداد یا جواب اشتباه داد، به چه کسی خبر بدهد. Uptime Kuma نتیجهٔ هر بررسی (که به آن heartbeat می‌گوید) را ذخیره می‌کند و از روی آن نمودار زمان پاسخ، درصد آپتایم و تاریخچهٔ قطعی‌ها را نشان می‌دهد.

نسخهٔ ۲ این برنامه در ۲۸ مهر ۱۴۰۴ (اکتبر ۲۰۲۵) منتشر شد و فعلاً نسخه‌های پایدار روی شاخهٔ 2.x عرضه می‌شوند. اگر هنوز نسخهٔ ۱ را اجرا می‌کنید، قبل از ارتقا راهنمای مهاجرت رسمی را بخوانید؛ مهاجرت دیتابیس ممکن است طول بکشد و نباید وسطش متوقف شود.

مانیتورینگ آپتایم دقیقاً چه چیزی را می‌سنجد؟

آپتایم یعنی سهم زمانی که سرویس در دسترس بوده است. عددش خیلی خوش‌ظاهر است، ولی پشتش دقیقه‌های واقعی قطعی خوابیده. جدول زیر نشان می‌دهد هر سطح آپتایم در عمل چقدر قطعی را مجاز می‌کند:

آپتایم قطعی مجاز در ماه قطعی مجاز در سال
۹۹٪ حدود ۷ ساعت و ۲۰ دقیقه حدود ۳ روز و ۱۵ ساعت
۹۹٫۹٪ حدود ۴۴ دقیقه حدود ۸ ساعت و ۴۵ دقیقه
۹۹٫۹۹٪ حدود ۴ دقیقه و ۲۰ ثانیه حدود ۵۳ دقیقه

اما «سایت بالا است» همیشه به معنی «سایت کار می‌کند» نیست. سروری که به جای صفحهٔ اصلی خطای ۵۰۲ برمی‌گرداند هم به پینگ جواب می‌دهد. برای همین مانیتور خوب سه چیز را می‌سنجد: آیا سرویس جواب می‌دهد، آیا جواب درست است (کد وضعیت ۲۰۰ و محتوای مورد انتظار) و چقدر طول کشید تا جواب بدهد. اگر با خطای Bad Gateway درگیر شده‌اید، مقالهٔ رفع خطای ۵۰۲ در Nginx را هم ببینید.

انواع مانیتور در Uptime Kuma

Uptime Kuma علاوه بر بررسی ساده HTTP، می‌تواند وجود یک کلمه در صفحه را چک کند، یک فیلد مشخص از پاسخ JSON را بخواند یا مستقیم به دیتابیس وصل شود. پرکاربردترین‌ها این‌ها هستند:

نوع مانیتور چه چیزی را بررسی می‌کند مثال کاربرد
HTTP(s) کد وضعیت پاسخ یک آدرس صفحهٔ اصلی سایت یا پنل مدیریت
HTTP(s) – Keyword وجود یا نبود یک عبارت در صفحه اطمینان از اینکه صفحه به‌جای محتوا پیغام خطا نشان نمی‌دهد
HTTP(s) – Json Query مقدار یک فیلد در پاسخ JSON اندپوینت /health که وضعیت دیتابیس و صف را برمی‌گرداند
TCP Port باز بودن یک پورت SMTP، SSH یا پورت دیتابیس
Ping پاسخ سرور به ICMP در دسترس بودن خود سرور یا روتر
DNS مقدار یک رکورد DNS تشخیص تغییر ناخواستهٔ رکورد A یا MX دامنه
Push رسیدن ضربان از طرف خود سرویس کرون‌جاب، اسکریپت بکاپ، ورکر صف
Docker Container وضعیت یک کانتینر روی میزبان داکر کانتینری که بی‌صدا متوقف شده یا مدام ری‌استارت می‌شود
MySQL، PostgreSQL، Redis، MongoDB اتصال واقعی به دیتابیس اطمینان از اینکه دیتابیس اتصال جدید قبول می‌کند

فهرست کامل در نسخهٔ فعلی بلندتر است و مواردی مثل WebSocket، gRPC، MQTT و سرورهای بازی Steam را هم شامل می‌شود. برای بیشتر سایت‌ها ترکیب یک مانیتور HTTP(s) – Keyword روی صفحهٔ اصلی، یک TCP Port روی دیتابیس و یک Push برای بکاپ شبانه کافی است.

 

نحوه کار Uptime Kuma؛ بررسی سایت، API، پورت و DNS و ارسال هشدار به تلگرام، بله، ایمیل و صفحه وضعیت

 

نصب Uptime Kuma؛ سه راه اصلی

Uptime Kuma را می‌توانید با داکر، بدون داکر روی Node.js یا به‌صورت سرویس آماده اجرا کنید. هر سه یک برنامه را بالا می‌آورند؛ فرقشان در کاری است که نگهداری‌اش با شماست.

نصب با Docker

ساده‌ترین راه روی یک سرور لینوکسی که داکر دارد، همان دستوری است که در مخزن رسمی Uptime Kuma در GitHub آمده است:

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

همهٔ تنظیمات، مانیتورها و تاریخچه در مسیر /app/data ذخیره می‌شود، پس این volume را حتماً نگه دارید و از آن بکاپ بگیرید. از نسخهٔ ۲ به بعد، بکاپ همین پوشهٔ داده تنها روش پشتیبان‌گیری پشتیبانی‌شده است. یک هشدار مهم هم از مستندات رسمی: پوشهٔ داده را روی فایل‌سیستم شبکه‌ای مثل NFS نگذارید؛ پشتیبانی نمی‌شود و دیتابیس ممکن است خراب شود. اگر با داکر کار می‌کنید و رابط گرافیکی برای مدیریت کانتینرها می‌خواهید، Portainer را هم ببینید.

نصب بدون داکر با Node.js

روی سرورهایی که نمی‌خواهید داکر نصب کنید، Uptime Kuma مستقیم روی Node.js هم اجرا می‌شود. نسخهٔ ۲ حداقل به Node.js 20.4 نیاز دارد و برای اجرای دائمی در پس‌زمینه از pm2 استفاده می‌کند:

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
pm2 startup && pm2 save

اجرای Uptime Kuma به‌صورت سرویس آماده

اگر حوصلهٔ نگهداری سرور، به‌روزرسانی داکر و تنظیم SSL را ندارید، Uptime Kuma را می‌توانید از بخش برنامه‌های آماده بسازید. در این حالت سرویس روی یک دامنه با SSL بالا می‌آید و فقط باید نام کاربری و رمز مدیر را بسازید. جزئیات این روش در بخش آخر مقاله آمده است.

Uptime Kuma را پشت Nginx و با دامنه اجرا کنید

باز گذاشتن پورت 3001 روی اینترنت ایدهٔ خوبی نیست. بهتر است برنامه فقط روی localhost گوش بدهد (در دستور داکر به‌جای -p 3001:3001 بنویسید -p 127.0.0.1:3001:3001) و Nginx با یک ساب‌دامین مثل status.example.com درخواست‌ها را به آن برساند. داشبورد Uptime Kuma از WebSocket استفاده می‌کند، پس هدرهای Upgrade نباید جا بیفتند. این نمونه بر اساس راهنمای Reverse Proxy در ویکی پروژه است:

server {
    listen 443 ssl http2;
    server_name status.example.com;

    ssl_certificate     /etc/letsencrypt/live/status.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.example.com/privkey.pem;

    location / {
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   Host $host;
        proxy_pass         http://127.0.0.1:3001/;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
    }
}

اگر داشبورد باز شد ولی مدام پیغام قطع اتصال داد، تقریباً همیشه یکی از دو خط Upgrade و Connection جا افتاده است. گواهی این ساب‌دامین را هم مثل بقیهٔ دامنه‌ها خودکار تمدید کنید؛ روشش در مقالهٔ تمدید گواهی SSL آمده است. بعد از اولین ورود، احراز هویت دومرحله‌ای (2FA) را از تنظیمات فعال کنید، چون این داشبورد نقشهٔ کامل سرویس‌های شما را دارد.

اولین مانیتور و هشدار را بسازید

بعد از ساخت حساب مدیر، روی Add New Monitor بزنید. برای یک سایت این تنظیمات نقطهٔ شروع خوبی است:

  1. نوع مانیتور را HTTP(s) – Keyword بگذارید و آدرس صفحهٔ اصلی را وارد کنید.
  2. در فیلد Keyword عبارتی بنویسید که فقط در صفحهٔ سالم وجود دارد، مثلاً نام برند در فوتر.
  3. Heartbeat Interval را ۶۰ ثانیه بگذارید. فاصلهٔ کوتاه‌تر برای بیشتر سایت‌ها فقط بار اضافه می‌سازد.
  4. Retries را روی ۱ یا ۲ بگذارید تا یک قطعی چندثانیه‌ای شبکه هشدار بی‌دلیل نسازد. در نسخهٔ ۲ مقدار پیش‌فرض برای مانیتورهای جدید صفر است.
  5. گزینهٔ Certificate Expiry Notification را روشن کنید تا قبل از منقضی شدن گواهی SSL هم هشدار بگیرید. روزهای هشدار را از Settings و بخش Notifications تعیین می‌کنید.

حالا نوبت هشدار است. Uptime Kuma بیش از ۹۰ سرویس اعلان را پشتیبانی می‌کند. برای کاربران ایرانی سه گزینه کاربردی‌ترند:

کانال هشدار چه چیزی لازم دارد نکته
Telegram توکن ربات از BotFather و Chat ID برای هشدار تیمی، ربات را به یک گروه اضافه کنید
Bale توکن ربات بله و Chat ID از نسخه‌های جدید به‌صورت داخلی پشتیبانی می‌شود و پیام را از API بله می‌فرستد
Email (SMTP) سرور SMTP، نام کاربری و رمز از یک صندوق ایمیل جدا از دامنهٔ پایش‌شده استفاده کنید
Webhook یک آدرس که درخواست POST بگیرد برای وصل کردن به سیستم تیکت، n8n یا ربات اختصاصی

اگر می‌خواهید هشدارها را از مسیر خودتان پردازش کنید، مثلاً فقط قطعی‌های بیشتر از پنج دقیقه را به مدیر بفرستید، Webhook را به یک ربات یا ورک‌فلو وصل کنید. مقاله‌های Webhook چیست و ساخت ربات بله با پایتون برای این کار به دردتان می‌خورند. یک قانون را هم فراموش نکنید: هشدار ایمیلی را روی سرور ایمیلی که روی همان سرور سایت است تنظیم نکنید؛ وقتی سرور قطع شود، ایمیل هشدار هم نمی‌رود.

پایش کرون‌جاب و بکاپ با Push monitor

مانیتورهای معمولی از بیرون به سرویس سر می‌زنند. Push monitor برعکس کار می‌کند: Uptime Kuma منتظر می‌ماند و خود اسکریپت شما باید بعد از هر اجرای موفق یک درخواست به آدرس مخصوص مانیتور بفرستد. اگر در بازهٔ تعیین‌شده چیزی نرسید، وضعیت DOWN می‌شود و هشدار می‌رود.

این دقیقاً همان چیزی است که برای کرون‌جاب‌ها لازم دارید. بکاپی که سه هفته است بی‌صدا شکست می‌خورد، از بیرون هیچ نشانه‌ای ندارد. برای راه‌اندازی، یک مانیتور از نوع Push بسازید، بازهٔ آن را کمی بیشتر از فاصلهٔ اجرای اسکریپت بگذارید (برای بکاپ روزانه، حدود ۲۵ ساعت) و آدرس Push را در انتهای اسکریپت صدا بزنید:

#!/bin/sh
set -e

# nightly database backup
pg_dump -Fc mydb > /backups/mydb-$(date +%F).dump

# report success to Uptime Kuma (runs only if the backup succeeded)
curl -fsS -m 10 "https://status.example.com/api/push/TOKEN?status=up&msg=OK" > /dev/null

به‌خاطر set -e، اگر pg_dump خطا بدهد اسکریپت همان‌جا متوقف می‌شود و ضربانی نمی‌رسد. پارامتر status را می‌توانید down هم بفرستید تا شکست را صریح گزارش کنید، و با msg یک توضیح کوتاه کنار ضربان ثبت کنید. اگر با زمان‌بندی کرون آشنا نیستید، مقالهٔ Cron Job چیست را بخوانید.

 

Push monitor در Uptime Kuma برای پایش کرون جاب و اسکریپت بکاپ؛ نرسیدن ضربان یعنی هشدار

 

صفحهٔ وضعیت و زمان‌بندی تعمیرات

Uptime Kuma می‌تواند یک یا چند صفحهٔ وضعیت (Status Page) عمومی بسازد که مشتری‌ها بدون ورود ببینند کدام سرویس سالم است. هر صفحه را می‌توانید به یک دامنهٔ جدا مثل status.example.com وصل کنید، مانیتورها را در گروه‌هایی مثل «سایت»، «API» و «پرداخت» بچینید و هنگام بروز مشکل یک اطلاعیه (Incident) بالای صفحه بگذارید.

برای کارهای برنامه‌ریزی‌شده مثل ارتقای دیتابیس هم بخش Maintenance را دارید. یک پنجرهٔ زمانی تعریف می‌کنید و مانیتورهای مرتبط در آن بازه به‌جای DOWN، وضعیت تعمیرات نشان می‌دهند. هم هشدار بی‌مورد نمی‌گیرید، هم آمار آپتایم با قطعی برنامه‌ریزی‌شده خراب نمی‌شود.

Uptime Kuma را کجا اجرا کنیم؟

این مهم‌ترین تصمیم کل راه‌اندازی است. اگر Uptime Kuma روی همان سروری باشد که سایت روی آن است، وقتی سرور از دسترس خارج شود، ابزار پایش هم با آن خاموش می‌شود و هیچ هشداری نمی‌رسد. پایش باید از بیرون انجام شود.

برای سرویس‌هایی که کاربرانشان در ایران هستند یک نکتهٔ محلی هم مهم است. اگر Uptime Kuma را در اروپا اجرا کنید و سایت در ایران باشد، هر اختلال در ارتباط بین‌الملل را قطعی سایت گزارش می‌کند، در حالی که کاربران داخلی مشکلی ندارند. برعکسش هم صادق است. چند راه عملی:

  • برای سایتی که مخاطبش داخلی است، Uptime Kuma را در یک دیتاسنتر داخلی دیگر، جدا از سرور اصلی اجرا کنید.
  • اگر هم کاربر داخلی دارید هم خارجی، دو نمونه بالا بیاورید؛ یکی در ایران و یکی در اروپا. اگر فقط یکی هشدار داد، مشکل احتمالاً از مسیر شبکه است، نه از سرور.
  • خود Uptime Kuma را هم از یک جای دیگر پایش کنید؛ حتی یک Push ساده از سرور دیگر کافی است تا اگر ابزار پایش از کار افتاد، بفهمید.

Uptime Kuma یا ابزارهای دیگر؟

Uptime Kuma تنها گزینه نیست. اینکه کدام ابزار مناسب شماست بیشتر به این بستگی دارد که می‌خواهید فقط «بالا یا پایین بودن» را بدانید یا متریک‌های عمیق سرور را هم جمع کنید:

ابزار نوع تنظیمات مناسب برای
Uptime Kuma متن‌باز، روی سرور خودتان رابط وب گرافیکی تیم‌های کوچک و متوسط که پایش آپتایم، هشدار و صفحهٔ وضعیت را یک‌جا می‌خواهند
UptimeRobot و سرویس‌های مشابه سرویس ابری آماده رابط وب، بدون نصب کسی که نمی‌خواهد چیزی نصب کند و با محدودیت‌های پلن رایگان کنار می‌آید
Gatus متن‌باز، روی سرور خودتان فایل پیکربندی YAML تیم‌هایی که تنظیمات پایش را مثل کد در گیت نگه می‌دارند
Prometheus و Grafana متن‌باز، مجموعه‌ای از چند ابزار پیکربندی مفصل و کوئری PromQL پایش عمیق CPU، حافظه، دیتابیس و اپلیکیشن در زیرساخت‌های بزرگ‌تر

خیلی از تیم‌ها دو ابزار را کنار هم دارند: Uptime Kuma برای اینکه بفهمند سایت قطع شده و Grafana برای اینکه بفهمند چرا قطع شده است.

Uptime Kuma در چابکان

در چابکان، سرویس Uptime Kuma از بخش برنامه‌های آماده با چند کلیک ساخته می‌شود. نصب، دامنهٔ پیش‌فرض و SSL با پلتفرم است و شما فقط حساب مدیر را می‌سازید و مانیتورها را اضافه می‌کنید. مراحل تصویری راه‌اندازی در مستندات Uptime Kuma در چابکان آمده است. موقعیت سرویس را هم می‌توانید ایران یا اروپا انتخاب کنید که برای همان پایش از بیرون، که در بخش قبل گفتیم، کاربرد مستقیم دارد.

اگر کنترل کامل می‌خواهید، روی سرور ابری چابکان می‌توانید Uptime Kuma را با داکر و Nginx همین مقاله خودتان راه بیندازید و نگهداری پایهٔ سرور را به دستیار مدیریت سرور بسپارید. سایت یا اپلیکیشنی را هم که پایش می‌کنید می‌توانید روی هاست ابری چابکان نگه دارید. برای انتخاب پلن، جدول پلن‌ها را در صفحهٔ هر سرویس ببینید.

سوالات متداول درباره Uptime Kuma

Uptime Kuma رایگان است؟

بله. Uptime Kuma نرم‌افزار متن‌باز با مجوز MIT است و هزینهٔ لایسنس ندارد. هزینهٔ شما فقط سروری است که آن را روی آن اجرا می‌کنید، یا سرویس آماده‌ای که برایش می‌گیرید.

Uptime Kuma منابع زیادی مصرف می‌کند؟

برای چند ده مانیتور با فاصلهٔ ۶۰ ثانیه، یک سرور یا سرویس کوچک کافی است. چیزی که با زمان بزرگ می‌شود دیتابیس تاریخچهٔ heartbeatهاست. در تنظیمات می‌توانید مدت نگهداری تاریخچه را محدود کنید.

آیا Uptime Kuma هشدار تلگرام و بله می‌فرستد؟

بله، هر دو به‌صورت داخلی پشتیبانی می‌شوند. برای هر کدام یک ربات می‌سازید، توکن و Chat ID را در بخش Notifications وارد می‌کنید و با دکمهٔ Test پیام آزمایشی می‌فرستید.

Uptime Kuma چیست و چه فرقی با Grafana دارد؟

Uptime Kuma از بیرون بررسی می‌کند که سرویس جواب می‌دهد یا نه و در صورت قطعی هشدار می‌دهد. Grafana داشبوردی برای نمایش متریک‌هایی است که ابزارهایی مثل Prometheus از داخل سرور جمع می‌کنند. اولی به سؤال «قطع است؟» جواب می‌دهد و دومی به سؤال «چرا کند یا قطع شد؟».

می‌توانم Uptime Kuma را روی همان سرور سایت نصب کنم؟

از نظر فنی بله، ولی هدف پایش را از بین می‌برد. وقتی سرور از دسترس خارج شود، Uptime Kuma هم خاموش است و هشداری نمی‌فرستد. آن را روی سرور یا سرویس جداگانه اجرا کنید.

چطور از Uptime Kuma بکاپ بگیرم؟

از نسخهٔ ۲، روش پشتیبانی‌شده بکاپ از کل پوشهٔ داده (/app/data در داکر) است. قبل از بکاپ یا ارتقا، کانتینر را متوقف کنید تا فایل دیتابیس در حالت سازگار ذخیره شود.

دیدگاه خود را بنویسید:

آدرس ایمیل شما نمایش داده نخواهد شد.

فوتر سایت