ساعت سه بامداد سایت از دسترس خارج میشود و تا ساعت نه صبح که اولین مشتری در پشتیبانی پیام میدهد، کسی خبر ندارد. شش ساعت قطعی، بدون یک هشدار. 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؛ سه راه اصلی
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 بزنید. برای یک سایت این تنظیمات نقطهٔ شروع خوبی است:
- نوع مانیتور را HTTP(s) – Keyword بگذارید و آدرس صفحهٔ اصلی را وارد کنید.
- در فیلد Keyword عبارتی بنویسید که فقط در صفحهٔ سالم وجود دارد، مثلاً نام برند در فوتر.
- Heartbeat Interval را ۶۰ ثانیه بگذارید. فاصلهٔ کوتاهتر برای بیشتر سایتها فقط بار اضافه میسازد.
- Retries را روی ۱ یا ۲ بگذارید تا یک قطعی چندثانیهای شبکه هشدار بیدلیل نسازد. در نسخهٔ ۲ مقدار پیشفرض برای مانیتورهای جدید صفر است.
- گزینهٔ 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 چیست را بخوانید.

صفحهٔ وضعیت و زمانبندی تعمیرات
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 در داکر) است. قبل از بکاپ یا ارتقا، کانتینر را متوقف کنید تا فایل دیتابیس در حالت سازگار ذخیره شود.