SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

آموزش نصب و راه اندازی Uptime Kuma با Docker

با استفاده از Docker و Uptime Kuma سرورها و وب سایت های خود را مانیتور کنید. یاد بگیرید چگونه با تنظیم هشدارهای Telegram و Email از وضعیت آپتایم سرویس ها مطلع شوید.

آنچه در حال ساخت آن هستید

یک کانتینر کوچک و واحد که سرورها و وب‌سایت‌های دیگر شما را از بیرون زیر نظر می‌گیرد و به محض اینکه یکی از آن‌ها پاسخ‌دهی را متوقف کند، از طریق ایمیل، Telegram، Discord یا یک webhook به شما اطلاع می‌دهد. Uptime Kuma یک پردازش Node است که در این پیکربندی توسط یک فایل SQLite پشتیبانی می‌شود (نسخه 2 می‌تواند روی یک MariaDB داخلی یا خارجی نیز اجرا شود)، بنابراین به‌راحتی در 256 تا 512 مگابایت رم اجرا می‌شود و یک داشبورد زنده، نمودارهای تاریخچه و یک صفحه وضعیت عمومی در اختیار شما قرار می‌دهد. نصب آن شامل یک فایل Compose ده خطی است؛ بخشی که واقعاً اهمیت دارد، محل اجرای آن و تست کردن هشدارهای شما است، زیرا مانیتوری که هرگز ثابت نکرده‌اید می‌تواند به شما پیام برساند، از نبودن مانیتور بدتر است: چرا که به شما حس امنیت کاذب می‌دهد در حالی که عملاً چیزی را پایش نمی‌کند.

اجرای مانیتور در مکانی که قطعی به آن نرسد

این تصمیم، تعیین‌کنندهٔ موفقیت یا شکست کل سیستم است، بنابراین در اولویت قرار دارد. Uptime Kuma را روی همان سروری که قصد نظارت بر آن را دارید، اجرا نکنید. اگر مانیتور روی همان سروری باشد که نظارت می‌کند، دقیقاً همان رویدادی که برایتان اهمیت دارد—یعنی از کار افتادن سرور یا تمام شدن حافظه—مانیتور را نیز از کار می‌اندازد و هیچ هشداری دریافت نخواهید کرد: سکوتِ یک مانیتورِ ازکارافتاده، دقیقاً مشابه وضعیت «همه چیز خوب است» به نظر می‌رسد. حتی زمانی که سرور زنده است نیز یک تلهٔ ظریف‌تر وجود دارد: مانیتوری که به localhost اشاره می‌کند، CPU را با بار کاری (workload) اصلی به اشتراک می‌گذارد؛ بنابراین یک جهش در بار پردازشی باعث می‌شود زمان بررسی مانیتور به پایان برسد (timeout) و وضعیت هدف به down تغییر کند. این یک هشدار کاذب است، در حالی که کاربران واقعی بدون مشکل سرویس دریافت می‌کنند.

بنابراین، Uptime Kuma را روی یک VPS متفاوت از سروری که نظارت می‌کند اجرا کنید؛ در حالت ایده‌آل، از یک ارائه‌دهنده یا منطقهٔ جغرافیایی دیگر استفاده کنید و از طریق اینترنت عمومی و نام دامنه (hostname)، همان‌طور که کاربران به سرویس‌های شما دسترسی دارند، به آن‌ها متصل شوید. یک نمونه (instance) ارزان‌قیمت کافی است و یک VPS کوچک برای مانیتورینگ می‌تواند تمام سرورهای شما را زیر نظر بگیرد. این جداسازی برای برنامه‌های سنگینی که میزبانی می‌کنید اهمیت بیشتری دارد، زیرا چیزی مانند کتابخانهٔ عکس PhotoPrism یا Immich می‌تواند هنگام ایندکس کردن یک واردات جدید، CPU را برای ساعت‌ها درگیر کند و مانیتوری که از همان سخت‌افزار استفاده می‌کند، به اشتباه اعلام کند سرویسی که فقط مشغول است، از دسترس خارج شده است. برای تشخیص از کار افتادن خودِ Kuma، یک push heartbeat از طریق یک cron در جای دیگری تنظیم کنید.

پیش‌نیازها و تعیین ابعاد

  • یک سرور مجازی (VPS) با سیستم‌عامل Ubuntu 24.04 که Docker Engine و افزونه Compose v2 روی آن نصب شده باشد. حتماً از مخزن رسمی apt شرکت Docker استفاده کنید و نه بسته docker.io توزیع که نسخه‌های قدیمی‌تری دارد.
  • مقدار 256 مگابایت رم برای اجرای تعداد کمی مانیتور کافی است؛ 512 مگابایت تا 1 گیگابایت برای ده‌ها مانیتور به همراه reverse proxy مناسب است و مصرف CPU در فواصل بین بررسی‌ها تقریباً صفر است.
  • یک دامنه و یک رکورد DNS A (مثلاً status.example.com که به VPS اشاره می‌کند)، فقط در صورتی که به TLS و یک صفحه وضعیت عمومی نیاز دارید. برای نمونه‌های خصوصی، می‌توانید از DNS صرف‌نظر کرده و از VPN یا SSH tunnel استفاده کنید.
  • دسترسی شبکه خروجی به مقصدی که هشدارها به آن ارسال می‌شوند: SMTP برای سرویس‌دهنده ایمیل شما، یا HTTPS برای Telegram و Discord.

فایل Compose

این محتوا را در /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:

سرویس را بالا بیاورید و اولین بوت را مانیتور کنید:

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

یک شروع موفق، لاگ Listening on 3001 را ثبت می‌کند و سپس ساکت می‌شود. سه مورد در این فایل تعمداً لحاظ شده‌اند.

استفاده از 127.0.0.1:3001:3001، نه 3001:3001. داکر پورت‌ها را با استفاده از قوانین DNAT منتشر می‌کند که پیش از بررسی بسته‌ها توسط ufw ارزیابی می‌شوند. بنابراین، یک 3001:3001 ساده، داشبورد شما را بدون توجه به قوانین ufw در معرض اینترنت عمومی قرار می‌دهد؛ تنها قوانینی که به زنجیره DOCKER-USER خودِ داکر اضافه می‌کنید، می‌توانند آن را فیلتر کنند. اتصال به loopback باعث خصوصی ماندن آن می‌شود و تنها reverse proxy در معرض قرار می‌گیرد. این یعنی فقط خودِ میزبان می‌تواند به 3001 دسترسی داشته باشد: یک نمونهٔ خصوصی بدون پروکسی از تونل SSH که در زیر نشان داده شده استفاده می‌کند، و برای دسترسی به آن از طریق یک VPN شخصی WireGuard، باید پورت را روی آدرس WireGuard سرور (برای مثال 10.8.0.1:3001:3001) به جای 127.0.0.1 منتشر کنید.

یک volume نام‌گذاری‌شده در /app/data. تمام اطلاعاتی که Uptime Kuma به خاطر می‌سپارد، شامل دیتابیس SQLite، مانیتورها، تنظیمات اعلان‌ها و لوگوهای صفحه وضعیت، در آنجا قرار دارد. اگر آن را از دست بدهید، با یک صفحه مدیریت خالی مواجه می‌شوید؛ این تنها چیزی است که باید از آن نسخه پشتیبان تهیه کنید.

ایمیج روی یک تگ اصلی، یعنی :2 قفل شده است. این نسخه، خط پایدار فعلی است؛ پیش از کپی کردن، Docker Hub را برای جدیدترین نسخه اصلی بررسی کنید و هرگز از تگ‌های متغیر مانند latest استفاده نکنید، چرا که پروژه آن را منسوخ می‌داند. جهش به نسخه اصلی بعدی در این ایمیج، یک migration دیتابیس را اجرا می‌کند که باید آگاهانه و با داشتن یک نسخه پشتیبان تازه انجام شود، نه اینکه به‌طور تصادفی در یک pull معمولی رخ دهد.

یک نکته مهم: /app/data باید روی فایل‌سیستمی قرار بگیرد که از POSIX file locks پشتیبانی می‌کند. یک Docker volume محلی مناسب است؛ روی NFS، دیتابیس SQLite دچار خرابی می‌شود و با خطاهای SQLITE_BUSY و database disk image is malformed مواجه خواهید شد، بنابراین هرگز از network share استفاده نکنید.

اجرای اولیه: ایجاد حساب کاربری مدیر

از طریق پروکسی خود به آدرس https://status.example.com یا با استفاده از یک تونل SSH به نمونه (instance) متصل شوید: دستور ssh -L 3001:127.0.0.1:3001 user@your-vps را اجرا کرده و http://localhost:3001 را باز کنید. در یک نصب تازه از نسخه v2، اولین صفحه از شما می‌پرسد که از کدام پایگاه داده استفاده کنید؛ گزینه SQLite را انتخاب کنید. این گزینه همه چیز را در volume مربوط به /app/data نگه می‌دارد و همان چیزی است که مراحل پشتیبان‌گیری و عیب‌یابی در ادامه بر اساس آن فرض شده‌اند. سپس فرم تنظیمات برای نام کاربری و رمز عبور مدیر نمایش داده می‌شود؛ هیچ ورود پیش‌فرضی وجود ندارد. یک رمز عبور واقعی انتخاب کنید: این داشبورد به آدرس‌های داخلی و توکن‌های تمام سرویس‌هایی که مانیتور می‌کنید دسترسی دارد. اگر بعداً آن را فراموش کردید، به جای مرورگر، از طریق میزبان (host) آن را بازنشانی کنید:

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

ابتدا کانال‌های اعلان خود را اضافه و تست کنید

پیش از افزودن مانیتورها، هشدارها را تنظیم کنید تا بتوانید هنگام ایجاد هر مانیتور، یک کانال به آن متصل کنید. به مسیر Settings و سپس Notifications و در نهایت Setup Notification بروید و از دکمه Test برای هر کانال استفاده کنید تا مطمئن شوید پیام‌ها ارسال می‌شوند؛ چرا که اعلان تست‌نشده، دومین دلیل رایج برای شکست بی‌سروصدای یک پیکربندی است.

ایمیل (SMTP). میزبان (host)، پورت، نوع رمزنگاری، نام کاربری، رمز عبور، یک آدرس From و یک آدرس To را وارد کنید. ترکیب‌های معمول عبارتند از 465 با تنظیم "Secure" روی TLS/SSL، یا 587 با STARTTLS؛ برخی سرورها نیز STARTTLS را روی 25 ارائه می‌دهند، بنابراین از پورت و حالتی استفاده کنید که ارائه‌دهنده شما مستند کرده است. برای Gmail و اکثر ارائه‌دهندگانی که احراز هویت دو مرحله‌ای دارند، باید یک app password ایجاد کنید؛ رمز عبور عادی حساب کاربری منجر به خطای Error: Invalid login: 535-5.7.8 Username and Password not accepted می‌شود.

تلگرام. به @BotFather پیام دهید، دستور /newbot را ارسال کنید و توکن ربات را کپی کنید. برای دریافت chat ID، یک بار به ربات جدید پیام دهید، https://api.telegram.org/bot<token>/getUpdates را باز کنید و chat.id را از فایل JSON بخوانید. رباتی که هرگز به آن پیام نداده‌اید، دارای getUpdates خالی است و مقصدی برای ارسال پیام ندارد.

دیسکورد (Discord). در کانال مورد نظر، مسیر Edit Channel سپس Integrations سپس Webhooks و در نهایت New Webhook را باز کنید، URL را کپی کرده و آن را به عنوان یک اعلان Discord جای‌گذاری کنید.

وب‌هوک عمومی (Generic webhook). برای هر مورد دیگر، مانند وب‌هوک ورودی Slack، یک endpoint سفارشی یا هوک اتوماسیون خانگی، نوع Webhook یک payload با فرمت JSON را به URL ارائه‌شده توسط شما POST می‌کند. همچنین ادغام Apprise که به صورت پیش‌فرض همراه برنامه است، اکثرِ حدود نود سرویس دیگر موجود در لیست را پوشش می‌دهد. اگر ترجیح می‌دهید هیچ شخص ثالثی بین زمان وقوع قطعی و دریافت اعلان روی گوشی شما قرار نگیرد، نوع داخلی ntfy را انتخاب کرده و آن را به یک سرور ntfy که خودتان اجرا می‌کنید متصل کنید؛ این کار اعلان‌ها را از طریق کانالی که از ابتدا تا انتها تحت کنترل شماست، به گوشی شما ارسال می‌کند.

افزودن مانیتورها، یک نوع در هر مرحله

روی Add New Monitor کلیک کنید، یک نوع را انتخاب کرده و Friendly Name، Check Interval (مقدار 60 ثانیه معقول است)، Retries (تعداد شکست‌های متوالی پیش از اعلام وضعیت "down"؛ مقدار 2 یا 3 مناسب است تا یک پکت گم‌شده باعث ارسال هشدار نشود) و اعلان‌هایی که باید ارسال شوند را تنظیم کنید. انواعی که استفاده خواهید کرد عبارتند از:

  • HTTP(s). یک URL کامل. وضعیت "up" به معنای دریافت یک کد وضعیت پذیرفته‌شده است (به‌صورت پیش‌فرض 200-299؛ اگر 301 یا 401 برای شما عادی است، این بازه را در بخش Accepted Status Codes گسترش دهید). این ابزار اصلی شما برای وب‌سایت‌ها و APIها است.
  • HTTP(s) - Keyword. همان درخواست، با این تفاوت که برای وضعیت "up"، وجود یک رشته خاص در بدنه پاسخ نیز الزامی است (یا با فعال کردن Invert، عدم وجود آن). این قابلیت باعث می‌شود اگر سایت در حالی که خطای "Error establishing a database connection" را نمایش می‌دهد، کد 200 OK برگرداند، مانیتور آن را شناسایی کند؛ در حالی که یک چک HTTP ساده آن را سالم تلقی می‌کند. این همچنین چک مناسبی برای فرانت‌اند مرورگری است که با یک بک‌اند مجزا در ارتباط است، مانند یک پوسته فروشگاه ویدیویی Halcyon روی Jellyfin، که صفحه اصلی آن با خوشحالی کد 200 را برمی‌گرداند در حالی که مدیا سرور پشت آن در دسترس نیست.
  • TCP Port. یک اتصال TCP خام به یک میزبان و پورت، برای مواردی که HTTP نیستند: SSH روی پورت 22، Postgres روی 5432، یک سرور SMTP روی 25، یا یک سرور بازی.
  • Ping. اکوی ICMP: روشی کم‌هزینه برای بررسی دسترسی‌پذیری و تأخیر. اما بسیاری از شبکه‌ها و فایروال‌های ابری ICMP را مسدود می‌کنند، بنابراین قرمز شدن مانیتور Ping می‌تواند به معنای "خاموش بودن میزبان" یا "مسدود بودن Ping توسط ارائه‌دهنده" باشد؛ این مورد را با یک مانیتور TCP تأیید کنید.
  • DNS. یک رکورد (A، AAAA، MX، TXT و غیره) را در برابر یک resolver که شما تعیین می‌کنید Resolve می‌کند و می‌تواند پاسخ را تأیید کند، که باعث می‌شود قطعی‌های DNS یا ثبت‌کننده دامنه سریعاً شناسایی شوند.
  • Push. مانیتور از نوع داخل به خارج، که در بخش بعدی به آن پرداخته می‌شود.

نظارت بر یک cron job با استفاده از مانیتور push (heartbeat)

تمام مانیتورهای قبلی از بیرون به سرویس شما دسترسی پیدا می‌کنند. یک مانیتور push برعکس عمل می‌کند: Uptime Kuma منتظر می‌ماند و job شما با آن تماس می‌گیرد تا بگوید «من اجرا شدم». این تنها روش مطمئن برای نظارت بر یک backup یا cron است: یک بررسی HTTP فقط می‌داند که یک URL پاسخ می‌دهد، اما فقط خود job می‌داند که آیا با موفقیت تکمیل شده است یا خیر.

یک مانیتور از نوع Push ایجاد کنید. Uptime Kuma یک URL منحصربه‌فرد مانند زیر تولید می‌کند:

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

Heartbeat Interval را روی بازهٔ زمانی اجرای job، به اضافهٔ کمی زمان اضافه تنظیم کنید. سپس یک خط به انتهای اسکریپت خود اضافه کنید تا فقط در صورت موفقیت اجرا شود:

#!/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="

اگر job با خطا مواجه شود، set -e پیش از رسیدن به دستور curl متوقف می‌شود؛ اگر سرور نیز از دسترس خارج شود، اسکریپت هرگز اجرا نخواهد شد. در هر دو حالت، heartbeat متوقف می‌شود و پس از گذشت بازهٔ زمانی تعیین‌شده (به اضافهٔ تلاش‌های مجدد)، Uptime Kuma وضعیت مانیتور را به down تغییر داده و به شما هشدار می‌دهد. این توکن push را مانند یک راز (secret) نگه دارید: هر کسی که به آن دسترسی داشته باشد می‌تواند یک سیگنال سلامت جعلی ارسال کند.

ساخت یک صفحه وضعیت عمومی

صفحه وضعیت (Status Page) نمایی است که در معرض دید مشتری قرار می‌گیرد: این صفحه نشان می‌دهد کدام سرویس‌ها فعال هستند و تاریخچه اخیر آن‌ها چیست، بدون اینکه داشبورد اصلی شما را فاش کند. به مسیر Status Pages سپس New Status Page بروید، یک نام و یک slug (مسیر عمومی، مانند /status/main) برای آن انتخاب کنید، مانیتورهای مورد نظر خود را به گروه‌هایی مانند "Websites" و "APIs" بکشید (Drag & Drop)، یک لوگو و توضیحات کوتاه اضافه کنید و سپس آن را ذخیره نمایید. شما همچنین می‌توانید این صفحه را به دامنه اختصاصی خود متصل کنید تا status.example.com مستقیماً آن را ارائه دهد.

دو نکته احتیاطی: فقط مانیتورهایی را اضافه کنید که مایل هستید عمومی باشند، زیرا صفحه وضعیت فاش می‌کند که یک سرویس وجود دارد و وضعیت فعال یا غیرفعال بودن آن را نشان می‌دهد؛ همچنین داشبورد اصلی شما پشت لایه احراز هویت باقی می‌ماند، در حالی که صفحه وضعیت عمداً عمومی است و نیازی به احراز هویت ندارد.

قرار دادن آن پشت یک reverse proxy با TLS و توجه به WebSocketها

برای یک نمونه عمومی (public instance)، یک reverse proxy را جلوی کانتینری که به loopback محدود شده قرار دهید تا TLS و نام دامنه را مدیریت کند. نکته‌ای که همه را به دردسر می‌اندازد این است: رابط کاربری Uptime Kuma یک برنامه زنده Socket.IO است، بنابراین پروکسی باید اتصال WebSocket را ارتقا (upgrade) دهد. اگر این کار انجام نشود، صفحه بارگذاری می‌شود اما هرگز متصل نمی‌شود؛ داشبورد روی وضعیت "Connecting..." باقی می‌ماند، ضربان‌های زنده (heartbeats) به‌روز نمی‌شوند و کنسول مرورگر خطای WebSocket connection to 'wss://.../socket.io/...' failed را نشان می‌دهد.

ابتدا nginx و certbot را نصب کنید، سپس vhost مربوطه را بنویسید که درخواست‌ها را به پورت loopback هدایت می‌کند. فعلاً آن را روی پورت 80 قرار دهید تا certbot بعداً TLS را اضافه کند؛ چالش‌ها، زمان‌بندی تمدید و حالت‌های شکست آن در صدور گواهی‌های Let's Encrypt با certbot و nginx پوشش داده شده است.

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

این فایل را با نام /etc/nginx/sites-available/status.example.com ذخیره کنید؛ دو خط مربوط به WebSocket همان‌هایی هستند که اهمیت دارند:

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;
    }
}

سایت را فعال کنید، پیکربندی را تست کنید و سپس اجازه دهید certbot بلوک را بازنویسی کند تا روی پورت 443 گوش دهد، گواهی را اضافه کند و یک تغییر مسیر (redirect) از HTTP به 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

جفت دستور Upgrade و Connection "upgrade" تمام ماجراست و proxy_read_timeout 3600s مانع از آن می‌شود که nginx سوکت‌های با عمر طولانی را قطع کند؛ certbot هر دو را در بلوک 443 که تولید می‌کند، کپی خواهد کرد. اگر در حال حاضر چندین کانتینر را پشت یک پروکسی اجرا می‌کنید، هدایت آن‌ها از طریق Traefik با TLS خودکار همین کار را با استفاده از برچسب‌های کانتینر انجام می‌دهد و ارتقای WebSocketها را به‌صورت پیش‌فرض مدیریت می‌کند.

روی کل vhost از basic-auth استفاده نکنید، زیرا این کار دسترسی به صفحه وضعیت عمومی و endpoint مربوط به /api/push را نیز مسدود می‌کند. از سیستم ورود داخلی خودِ Uptime Kuma استفاده کنید، اگر سرویس در معرض اینترنت است fail2ban را برای نظارت بر تلاش‌های ناموفق ورود اضافه کنید، و اگر نیازی نیست داشبورد عمومی باشد، پروکسی را حذف کرده و از طریق یک تونل SSH یا یک VPN به آن دسترسی پیدا کنید، به‌طوری که پورت به‌جای loopback، روی آدرس VPN منتشر شود.

نظارت صحیح بر انقضای گواهی

یک مانیتور HTTP(s) می‌تواند پیش از انقضای گواهی TLS به شما هشدار دهد: گزینه Certificate Expiry Notification را فعال کنید تا Uptime Kuma در تعداد روزهای مشخصی پیش از انقضا، هشدار ارسال کند. دو اشتباه باعث می‌شود که این ابزار اطلاعات را اشتباه بخواند. مانیتورینگ را بر اساس hostname انجام دهید، نه IP؛ در غیر این صورت، در درخواستی که فاقد SNI باشد، گواهی پیش‌فرض سرور دریافت می‌شود و شما با Hostname/IP does not match certificate's altnames مواجه خواهید شد. همچنین، گزینه Ignore TLS/SSL Error را در مانیتوری که می‌خواهید هشدارهای انقضا را از آن دریافت کنید، فعال نکنید: این گزینه برای میزبان‌های داخلی با گواهی خودامضا (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT) است، اما باعث می‌شود Uptime Kuma بررسی گواهی را به‌طور کامل، از جمله تاریخ انقضا، متوقف کند.

پشتیبان‌گیری: این یک دایرکتوری است

از آنجایی که همه چیز در /app/data قرار دارد، پشتیبان‌گیری یعنی تهیه یک کپی از آن volume در زمانی که container متوقف شده است؛ این کار باعث می‌شود فایل SQLite در وضعیت منسجم باقی بماند:

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

ابتدا نام واقعی volume را با docker volume ls | grep kuma تأیید کنید، زیرا Compose نام دایرکتوری پروژه را به عنوان پیشوند به آن اضافه می‌کند. سپس فایل tarball را از روی سرور به جای دیگری منتقل کنید، چرا که پشتیبان‌گیری روی همان VPS تنها یک کپی است و نه یک نسخه پشتیبان واقعی. عملیات بازیابی (Restore) برعکس این فرآیند است: stack را متوقف کنید، فایل را در یک volume خالی /app/data استخراج کنید و سپس آن را اجرا نمایید.

ارتقاها

ارتقاها شامل دریافت (pull) یک image جدید هستند:

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

کانتینر جدید در اولین اجرا، هرگونه migration دیتابیس را انجام می‌دهد؛ docker compose logs -f را زیر نظر داشته باشید. پیش از pull کردن، از بک‌آپ ذکر شده در بالا استفاده کنید و در محدوده یک major tag باقی بمانید: انتقال از :1 به :2 دیتابیس را migration می‌کند و طبق راهنمای migration پروژه، وقفه در این فرآیند به معنای بازگردانی از بک‌آپ و تلاش مجدد است؛ بنابراین ابتدا بک‌آپ بگیرید و آن راهنما و یادداشت‌های انتشار (release notes) را مطالعه کنید.

حالت‌های شکست و پیام‌های مربوطه

گزارش وضعیت "down" کاذب برای مانیتوری که به localhost اشاره دارد. مانیتور با timeout of 48000ms exceeded یا connect ETIMEDOUT قرمز می‌شود، در حالی که سرویس از روی لپ‌تاپ شما پاسخ می‌دهد. اگر هدف مانیتور همان میزبانی باشد که Uptime Kuma روی آن اجرا شده، یک جهش در مصرف CPU یا حافظه باعث شده که بررسی انجام نشود، نه اینکه سرویس مقصد قطع باشد. مانیتور را به یک VPS مجزا منتقل کنید و نام دامنه عمومی را هدف قرار دهید.

connect ECONNREFUSED 127.0.0.1:443 (یا هر پورت دیگر). هیچ سرویسی روی آن پورت در حال گوش دادن نیست: یا سرویس قطع است، یا شما localhost را از داخل کانتینر مانیتور کرده‌اید، که در آنجا 127.0.0.1 به خودِ کانتینر اشاره دارد، نه سرور شما. نام دامنه عمومی را مانیتور کنید، نه loopback.

Invalid login: 535-5.7.8 Username and Password not accepted در تست ایمیل. اعتبارنامه‌های SMTP اشتباه هستند، یا ارائه‌دهنده سرویس به جای رمز عبور حساب کاربری، نیاز به یک رمز عبور مخصوص برنامه (app-specific password) دارد. یک رمز عبور مخصوص برنامه ایجاد کرده و آن را وارد کنید.

connect ETIMEDOUT یا queryA ETIMEDOUT <host> در تست ایمیل. پورت اشتباه است، یا ارائه‌دهنده سرویس ترافیک خروجی SMTP را مسدود کرده است. تأیید کنید که 465 یا 587 با تنظیمات Secure/STARTTLS مطابقت دارد و با استفاده از nc -vz smtp.example.com 587 از روی میزبان تست کنید. بسیاری از ارائه‌دهندگان، ترافیک خروجی 25 را مسدود می‌کنند و برخی دیگر پورت‌های submission را تا زمانی که درخواست نکنید، باز نمی‌کنند.

self signed certificate یا unable to verify the first certificate در تست ایمیل. سرور SMTP شما گواهی‌نامه‌ای ارائه می‌دهد که Node به آن اعتماد ندارد؛ به جای نادیده گرفتن مشکل، گواهی‌نامه سرور ایمیل را اصلاح کنید.

داشبورد روی وضعیت "Connecting..." گیر کرده و کنسول WebSocket connection ... failed را نشان می‌دهد. Reverse proxy در حال ارتقای (upgrade) اتصال به WebSocket نیست. هدرهای Upgrade و Connection "upgrade" را در nginx اضافه کنید، یا از پروکسی‌هایی استفاده کنید که به‌صورت پیش‌فرض آن‌ها را فوروارد می‌کنند، مانند Traefik یا Caddy. فایل HTML بارگذاری می‌شود چون یک درخواست HTTP GET معمولی است؛ فقط سوکت زنده نیاز به ارتقا دارد.

مانیتور انقضای گواهی‌نامه هشدار نمی‌دهد یا هشدار اشتباه می‌دهد. یا گزینه Ignore TLS/SSL Error تیک خورده است که بررسی گواهی‌نامه را غیرفعال می‌کند، یا مانیتور یک IP را هدف قرار داده و به دلیل نبود SNI، گواهی‌نامه اشتباهی را می‌خواند که منجر به Hostname/IP does not match certificate's altnames می‌شود. تیک گزینه ignore را بردارید و بر اساس نام دامنه مانیتور کنید.

SQLITE_BUSY یا database disk image is malformed در لاگ‌ها. حجم /app/data روی یک سیستم فایل بدون قفل‌گذاری فایل (file locking) مناسب قرار دارد، که معمولاً NFS است؛ آن را به یک Docker volume محلی منتقل کرده و از روی نسخه پشتیبان بازیابی کنید.

FAQ

مانیتور آپ‌تایم خود را کجا اجرا کنم؟

روی سروری متفاوت از سرورهایی که مانیتور می‌کند؛ ترجیحاً در یک ارائه‌دهنده یا منطقه جغرافیایی دیگر. مانیتور باید از طریق نام دامنه و از طریق اینترنت عمومی به سرویس‌ها متصل شود، درست همان‌طور که کاربران شما متصل می‌شوند. اگر مانیتور روی همان سروری باشد که هدف قرار داده، قطعی سرور باعث از کار افتادن مانیتور نیز می‌شود و در صورت بارگذاری بیش از حد سرور، مانیتور به اشتباه وضعیت سرویس‌های سالم را "down" گزارش می‌کند. یک VPS کوچک و جداگانه از هر دو مشکل جلوگیری می‌کند.

چگونه اعلان‌ها را در تلگرام یا ایمیل دریافت کنم؟

کانال مورد نظر را در بخش Settings و سپس Notifications اضافه کنید و آن را به هر مانیتور اختصاص دهید. برای تلگرام، یک ربات با استفاده از @BotFather بسازید و chat.id را از https://api.telegram.org/bot<token>/getUpdates بخوانید. برای ایمیل، اگر ارائه‌دهنده شما از احراز هویت دو مرحله‌ای استفاده می‌کند، از 465 برای SSL یا 587 برای STARTTLS به همراه یک app password استفاده کنید. پیش از تکیه بر اعلان‌ها، دکمه Test را بزنید و از دریافت پیام اطمینان حاصل کنید.

آیا Uptime Kuma می‌تواند یک cron job یا اسکریپت پشتیبان‌گیری را مانیتور کند؟

بله، این کار با مانیتور نوع Push انجام می‌شود: Uptime Kuma یک URL به شما می‌دهد و شما باید آن را در انتهای اسکریپت خود curl کنید تا فقط در صورت موفقیت اجرا شود. اگر عملیات با شکست مواجه شود یا سرور از دسترس خارج شود، سیگنال heartbeat هرگز ارسال نمی‌شود و پس از گذشت بازه زمانی تعیین‌شده، به شما هشدار داده می‌شود. این تنها روش مطمئن برای اطلاع از اجرای موفقیت‌آمیز یک عملیات زمان‌بندی‌شده است، زیرا بررسی‌های خارجی نمی‌توانند وضعیت داخلی اسکریپت را مشاهده کنند.

Uptime Kuma در برابر Zabbix؛ کدام را انتخاب کنم؟

Uptime Kuma در عرض 10 دقیقه و با مصرف منابع ناچیز، به این پرسش پاسخ می‌دهد که «آیا سرویس از بیرون در دسترس است و آیا هشدار ارسال شد یا خیر»؛ همچنین قابلیت ارائه یک صفحه وضعیت (status page) را دارد. این ابزار معیارهای عمیقی مانند روند مصرف CPU، حافظه، دیسک یا آستانه‌های کل شبکه را جمع‌آوری نمی‌کند. برای این منظور، یک سرور مانیتورینگ کامل Zabbix ابزاری سنگین‌تر و مبتنی بر agent است و بسیاری از افراد از هر دو به صورت هم‌زمان استفاده می‌کنند. هنوز در مورد انتخاب سرویس‌ها تردید دارید؟ بررسی ما از سرویس‌های مناسب برای self-hosting در سال 2026، مانیتورینگ را در بستر مناسب خود قرار می‌دهد.

#uptime-kuma#monitoring#docker#self-hosting#status-page