آموزش نصب Uptime Kuma روی VPS؛ مانیتورینگ سایت و سرور

اگر می‌خواهید قبل از کاربران متوجه قطع‌شدن سایت، API یا یکی از سرویس‌های سرور شوید، Uptime Kuma یکی از ابزارهای متن‌باز و Self-hosted مناسب برای این کار است. با نصب Uptime Kuma روی VPS می‌توانید وضعیت سایت‌ها و سرویس‌های مختلف را از یک داشبورد بررسی کنید و هنگام قطع یا وصل‌شدن آن‌ها اعلان دریافت کنید.

در این آموزش Uptime Kuma را روی یک VPS با Ubuntu 24.04 LTS نصب می‌کنیم. روش اصلی از Docker و Docker Compose استفاده می‌کند و در ادامه پنل را پشت Nginx قرار می‌دهیم تا به‌جای بازگذاشتن مستقیم پورت مدیریتی، از یک زیردامنه و HTTPS استفاده شود.

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

Uptime Kuma یک نرم‌افزار مانیتورینگ متن‌باز و Self-hosted است. Self-hosted یعنی به‌جای سپردن اطلاعات مانیتورینگ به یک سرویس خارجی، نرم‌افزار را روی سرور خودتان اجرا می‌کنید و کنترل پنل و داده‌های آن در اختیار خودتان قرار می‌گیرد.

از مهم‌ترین کاربردهای آن می‌توان به موارد زیر اشاره کرد:

بنابراین Uptime Kuma فقط برای مانیتورکردن یک سایت وردپرسی نیست. می‌توانید یک VPS، وب‌سرویس، API، سرور بازی، پنل سازمانی یا سرویس‌های مختلف زیرساخت خود را از یک نقطه کنترل کنید.

پیش‌نیازهای نصب Uptime Kuma روی VPS

در این آموزش فرض می‌کنیم یک سرور خام در اختیار دارید و هنوز Docker یا Uptime Kuma روی آن نصب نشده است.

برای تعداد محدود Monitor معمولاً نیازی به سرور قدرتمند ندارید، اما اگر صدها سرویس را با فاصله زمانی کوتاه بررسی کنید، مصرف CPU، RAM، شبکه و حجم داده افزایش پیدا می‌کند.

آیا می‌توان Uptime Kuma را روی VPS ایران نصب کرد؟

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

برای مثال اگر هدف اصلی شما بررسی سرویس‌های داخل ایران است، قرارگرفتن سیستم مانیتورینگ در ایران می‌تواند دید مناسبی از وضعیت دسترسی داخلی ارائه دهد. اگر سرویس‌های خارجی را نیز مانیتور می‌کنید، دسترسی شبکه VPS به آن مقصدها را جداگانه بررسی کنید.

مرحله ۱: اتصال به VPS با SSH

تمام فرمان‌های لینوکسی این آموزش روی خود VPS اجرا می‌شوند. ابتدا از رایانه شخصی خود به سرور متصل شوید. در ویندوز می‌توانید PowerShell یا Windows Terminal را باز کنید و فرمان زیر را اجرا کنید:

ssh root@192.0.2.10

آدرس 192.0.2.10 فقط IP نمونه است. آن را با IP واقعی VPS خود جایگزین کنید. اگر با کاربر دیگری وارد می‌شوید، به‌جای root نام همان کاربر را قرار دهید و برای فرمان‌های مدیریتی از sudo استفاده کنید.

مرحله ۲: به‌روزرسانی Ubuntu

بعد از ورود، ابتدا فهرست بسته‌ها را به‌روز و بسته‌های نصب‌شده را ارتقا دهید:

sudo apt update
sudo apt upgrade -y

اگر ارتقا شامل Kernel یا اجزای سیستمی مهم بود و سیستم درخواست Reboot داشت، قبل از ادامه سرور را در زمان مناسب ریبوت کنید و دوباره از طریق SSH وارد شوید.

مرحله ۳: نصب Docker Engine و Docker Compose

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

ابتدا ابزارهای موردنیاز و کلید رسمی مخزن Docker را اضافه کنید:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

حالا مخزن رسمی Docker را به APT اضافه کنید:

sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Docker Engine، Containerd و افزونه Docker Compose را نصب کنید:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

وضعیت Docker را بررسی کنید:

sudo systemctl status docker --no-pager
sudo docker run --rm hello-world
sudo docker compose version

اگر Docker فعال باشد و پیام آزمایشی Hello from Docker! را مشاهده کنید، این مرحله با موفقیت انجام شده است.

مرحله ۴: نصب Uptime Kuma با Docker Compose

برای اینکه فایل‌های سرویس مرتب و قابل مدیریت باشند، یک پوشه جدا می‌سازیم:

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

فایل Compose را بسازید:

sudo nano /opt/uptime-kuma/compose.yaml

محتوای زیر را داخل فایل قرار دهید:

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

volumes:
  uptime-kuma-data:

در Nano کلیدهای Ctrl+O و سپس Enter را برای ذخیره بزنید و با Ctrl+X خارج شوید.

همچنین داده‌های Uptime Kuma در Volume محلی uptime-kuma-data نگه‌داری می‌شوند. برای دیتای Uptime Kuma از فایل‌سیستم‌هایی که مشکل File Lock دارند مانند NFS استفاده نکنید؛ مستندات پروژه درباره خطر خرابی دیتابیس در چنین شرایطی هشدار داده‌اند.

حالا Container را اجرا کنید:

cd /opt/uptime-kuma
sudo docker compose up -d

وضعیت Container را ببینید:

sudo docker compose ps

برای آزمایش محلی نیز اجرا کنید:

curl -I http://127.0.0.1:3001

دریافت پاسخ HTTP نشان می‌دهد سرویس روی localhost در دسترس است. چون عمداً پورت 3001 را عمومی نکرده‌ایم، در این معماری نباید انتظار داشته باشید آدرس IP:3001 از اینترنت باز شود.

مرحله ۵: ساخت زیردامنه برای Uptime Kuma

برای دسترسی تمیز و امن، زیردامنه‌ای مانند status.example.com ایجاد کنید. این رکورد باید در سرویس DNS فعال دامنه ساخته شود؛ ممکن است DNS شما در پنل ثبت دامنه، Cloudflare یا سرویس دیگری مدیریت شود.

یک رکورد A با مشخصات زیر بسازید:

پس از انتشار DNS می‌توانید آن را بررسی کنید:

dig +short status.example.com

باید IP VPS خودتان را مشاهده کنید. اگر هنوز IP دیگری نمایش داده می‌شود، قبل از دریافت SSL ادامه ندهید و DNS را بررسی کنید.

مرحله ۶: قرار دادن Uptime Kuma پشت Nginx

Nginx درخواست‌های عمومی را روی پورت‌های 80 و 443 دریافت می‌کند و آن‌ها را به Uptime Kuma روی 127.0.0.1:3001 می‌فرستد.

ابتدا Nginx را نصب کنید:

sudo apt install -y nginx
sudo systemctl enable --now nginx

فایل Virtual Host را ایجاد کنید:

sudo nano /etc/nginx/sites-available/uptime-kuma

محتوای زیر را وارد کنید و status.example.com را با دامنه واقعی خود جایگزین کنید:

server {
    listen 80;
    listen [::]:80;

    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

دو خط مربوط به Upgrade و Connection مهم هستند، زیرا رابط Uptime Kuma از WebSocket استفاده می‌کند.

فایل را فعال کنید:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/uptime-kuma
sudo nginx -t

اگر پیام موفقیت Syntax را مشاهده کردید:

sudo systemctl reload nginx

حالا باید با بازکردن http://status.example.com صفحه Uptime Kuma را مشاهده کنید.

مرحله ۷: فعال‌کردن HTTPS

پنل مانیتورینگ می‌تواند اطلاعات مهمی درباره سرویس‌های شما داشته باشد، بنابراین استفاده عمومی از آن با HTTP توصیه نمی‌شود. برای دامنه یک گواهی TLS معتبر فعال کنید.

اگر Certbot روی سرور شما نصب نیست، روش نصب را مطابق دستورالعمل فعلی Certbot برای Ubuntu/Nginx انتخاب کنید. پس از نصب Certbot و افزونه Nginx، دریافت و نصب گواهی با فرمان زیر انجام می‌شود:

sudo certbot --nginx -d status.example.com

بعد از صدور گواهی، آدرس زیر را در مرورگر باز کنید:

https://status.example.com

برای بررسی مکانیزم تمدید نیز پس از نصب صحیح Certbot می‌توانید از تست Dry Run استفاده کنید:

sudo certbot renew --dry-run

مرحله ۸: ساخت حساب مدیر Uptime Kuma

در اولین ورود، Uptime Kuma از شما می‌خواهد حساب Administrator ایجاد کنید. یک نام کاربری مناسب و رمز عبور طولانی و منحصربه‌فرد انتخاب کنید.

بعد از ورود، از بخش تنظیمات امنیتی قابلیت 2FA را نیز در صورت سازگاری با روش مدیریت خود فعال کنید. Uptime Kuma از احراز هویت دومرحله‌ای پشتیبانی می‌کند.

مرحله ۹: ساخت اولین Monitor

برای مانیتورکردن یک سایت، از داشبورد گزینه افزودن Monitor جدید را انتخاب کنید. برای یک وب‌سایت عادی، نوع HTTP(s) انتخاب مناسبی است.

برای مثال می‌توانید این مقادیر را تنظیم کنید:

پس از ذخیره، Uptime Kuma شروع به ارسال درخواست به مقصد می‌کند. اگر سرویس پاسخ مورد انتظار را بدهد، وضعیت Monitor به حالت Up می‌رود و تاریخچه پاسخ‌ها به‌تدریج ساخته می‌شود.

برای پورت SSH یا سرویس‌های دیگر چه کنیم؟

برای بررسی یک سرویس TCP می‌توانید Monitor از نوع TCP Port بسازید. برای مثال بررسی بازبودن پورت SSH با IP و پورت مربوط انجام می‌شود. Up بودن پورت فقط نشان می‌دهد اتصال TCP برقرار می‌شود؛ این نتیجه لزوماً سلامت کامل برنامه پشت آن پورت را اثبات نمی‌کند.

مرحله ۱۰: تنظیم اعلان قطعی سرویس

مانیتورینگ زمانی ارزش بیشتری پیدا می‌کند که برای دیدن قطعی مجبور نباشید دائماً داشبورد را باز نگه دارید. Uptime Kuma از روش‌های متعددی برای Notification پشتیبانی می‌کند؛ از جمله Telegram، Email از طریق SMTP، Discord، Slack، Gotify، Webhook و سرویس‌های متعدد دیگر.

از بخش Settings → Notifications روش موردنظر را اضافه کنید و قبل از وابسته‌شدن به آن، حتماً گزینه Test را اجرا کنید. سپس Notification ساخته‌شده را به Monitorهای موردنظر متصل کنید.

ساخت Status Page برای کاربران

یکی از قابلیت‌های کاربردی Uptime Kuma ساخت Status Page است. با آن می‌توانید صفحه‌ای بسازید که وضعیت سرویس‌های منتخب را بدون نمایش داشبورد مدیریتی به کاربران نشان دهد.

برای مثال اگر چند سرویس دارید، می‌توانید وضعیت وب‌سایت اصلی، API، پنل مشتریان و سرویس دانلود را در یک صفحه وضعیت نمایش دهید. این صفحه برای اطلاع‌رسانی هنگام اختلال نیز کاربردی است.

امن‌سازی Uptime Kuma روی VPS

بعد از راه‌اندازی، چند نکته امنیتی را جدی بگیرید:

بکاپ گرفتن از Uptime Kuma

در نصب Docker این مقاله، داده‌های برنامه داخل Volume با نام uptime-kuma-data قرار دارند. این داده‌ها شامل تنظیمات و تاریخچه‌ای هستند که نمی‌خواهید هنگام خرابی یا انتقال سرور از دست بروند.

برای داشتن یک بکاپ سازگار، ابتدا Container را متوقف کنید تا هنگام کپی، برنامه در حال نوشتن روی دیتابیس نباشد:

cd /opt/uptime-kuma
sudo docker compose stop

سپس Volume را در یک فایل فشرده ذخیره کنید:

sudo docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/data:ro \
  -v /opt/uptime-kuma:/backup \
  alpine \
  tar -czf /backup/uptime-kuma-backup.tar.gz -C /data .

نام واقعی Volume را قبل از اجرای فرمان با دستور زیر بررسی کنید:

sudo docker volume ls | grep uptime-kuma

اگر نام Volume متفاوت بود، همان نام واقعی را در فرمان بکاپ جایگزین کنید. سپس سرویس را دوباره اجرا کنید:

sudo docker compose start

فایل بکاپ را فقط روی همان VPS نگه ندارید. برای بازیابی واقعی در خرابی کامل سرور، حداقل یک نسخه باید در محل دیگری نگه‌داری شود.

چگونه Uptime Kuma را آپدیت کنیم؟

این مقاله برای بازتولیدپذیری، Image را روی نسخه 2.5.5 Pin کرده است. قبل از ارتقا ابتدا Release Notes نسخه جدید و مسیر ارتقا را بررسی و از داده‌ها بکاپ بگیرید.

پس از انتخاب نسخه جدید، مقدار image در فایل زیر را تغییر دهید:

sudo nano /opt/uptime-kuma/compose.yaml

سپس Image جدید را دریافت و Container را دوباره ایجاد کنید:

cd /opt/uptime-kuma
sudo docker compose pull
sudo docker compose up -d --force-recreate

بعد از ارتقا وضعیت و Log را بررسی کنید:

sudo docker compose ps
sudo docker compose logs --tail=100 uptime-kuma

رفع خطاهای رایج Uptime Kuma

Container اجرا نمی‌شود

ابتدا وضعیت و Log را ببینید:

cd /opt/uptime-kuma
sudo docker compose ps
sudo docker compose logs --tail=200 uptime-kuma

اگر Image دریافت نشده، اتصال Docker به Registry و فضای دیسک را بررسی کنید. اگر خطا مربوط به فایل Compose است، ابتدا ساختار YAML و تورفتگی‌ها را کنترل کنید.

خطای 502 Bad Gateway در Nginx

ابتدا ببینید Uptime Kuma واقعاً روی localhost پاسخ می‌دهد یا نه:

curl -I http://127.0.0.1:3001

اگر این فرمان هم پاسخ نمی‌دهد، مشکل از Uptime Kuma یا Docker است. اگر localhost پاسخ می‌دهد اما دامنه 502 می‌دهد، تنظیمات Nginx و Log آن را بررسی کنید:

sudo nginx -t
sudo tail -n 100 /var/log/nginx/error.log

داشبورد باز می‌شود اما اتصال ناپایدار است

اگر صفحه باز می‌شود ولی رابط Real-time درست کار نمی‌کند، تنظیمات WebSocket در Reverse Proxy را بررسی کنید. وجود هدرهای Upgrade و Connection در تنظیم Nginx برای این سناریو مهم است.

دامنه باز نمی‌شود

ابتدا DNS را بررسی کنید:

dig +short status.example.com

اگر IP درست است، وضعیت Nginx را بررسی کنید:

sudo systemctl status nginx --no-pager
sudo ss -lntp | grep -E ':80|:443'

Uptime Kuma بعد از Reboot بالا می‌آید؟

در فایل Compose از restart: unless-stopped استفاده کرده‌ایم. پس از Reboot، در صورتی که Docker به‌درستی اجرا شود و Container عمداً Stop نشده باشد، Docker آن را دوباره اجرا می‌کند. برای اطمینان بعد از راه‌اندازی سرور بررسی کنید:

sudo docker ps
sudo systemctl status docker --no-pager

سؤالات متداول نصب Uptime Kuma روی VPS

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

بله، Uptime Kuma یک پروژه متن‌باز است. با این حال برای اجرای Self-hosted آن به سرور یا زیرساخت مناسب نیاز دارید و هزینه VPS، دامنه یا سرویس‌های جانبی جداگانه است.

آیا Uptime Kuma روی VPS ایران اجرا می‌شود؟

بله. روی VPS لینوکسی ایران قابل اجرا است. فقط باید بررسی کنید خود VPS به مقصدهایی که قصد مانیتورکردن آن‌ها را دارید دسترسی شبکه دارد.

آیا برای Uptime Kuma حتماً به دامنه نیاز داریم؟

برای اجرای خود برنامه الزام فنی به دامنه ندارید، اما برای استفاده عمومی امن و دسترسی با HTTPS، داشتن دامنه یا زیردامنه روش مناسب‌تری است.

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

بله. می‌توانید Monitorهای متعددی ایجاد کنید. ظرفیت عملی به نوع Monitor، فاصله بررسی‌ها، منابع VPS و حجم داده بستگی دارد؛ بنابراین عدد ثابتی برای همه سرورها وجود ندارد.

چرا پورت 3001 را مستقیماً باز نکردیم؟

چون در معماری این آموزش Nginx نقش Reverse Proxy را دارد. Uptime Kuma فقط روی 127.0.0.1:3001 گوش می‌دهد و کاربران از طریق دامنه و HTTPS وارد می‌شوند. این کار سطح دسترسی مستقیم به سرویس داخلی را کاهش می‌دهد.

Uptime Kuma بهتر است روی همان سرور سایت نصب شود یا سرور جدا؟

برای تست‌های ساده می‌توان آن را روی همان زیرساخت اجرا کرد، اما برای مانیتورینگ جدی بهتر است نقطه مانیتورینگ از سرویس اصلی مستقل باشد. در غیر این صورت خرابی کامل VPS ممکن است هم سایت و هم سامانه‌ای را که باید خرابی آن را گزارش کند از دسترس خارج کند.

چگونه بفهمیم Uptime Kuma بعد از نصب درست کار می‌کند؟

Container باید در خروجی Docker در وضعیت Running باشد، درخواست به 127.0.0.1:3001 پاسخ بگیرد، دامنه از طریق HTTPS باز شود و یک Monitor آزمایشی بتواند وضعیت مقصد را ثبت کند. Notification را نیز جداگانه با قابلیت Test بررسی کنید.

منابع رسمی

🔹 مخزن رسمی Uptime Kuma در GitHub — اطلاعات پروژه، قابلیت‌ها و روش نصب

🔹 Releaseهای رسمی Uptime Kuma — بررسی نسخه‌های جدید و تغییرات قبل از ارتقا

🔹 راهنمای رسمی نصب Docker Engine روی Ubuntu