SSD Nodes Learn
Руководства Matt ConnorАвтор: Matt Connor · Обновлено 2026-07-24

Как установить Uptime Kuma в Docker

Инструкция по развертыванию Uptime Kuma в Docker. Узнайте, почему важно запускать мониторинг на отдельном VPS для надежной проверки сайтов и DNS.

Что вы создаете

Один небольшой контейнер, который проверяет ваши серверы и веб-сайты извне. Он уведомляет вас через email, Telegram, Discord или webhook, как только какой-либо ресурс перестает отвечать. Uptime Kuma — это один процесс Node.js с базой данных SQLite. Приложению достаточно 256-512 MB RAM. Оно предоставляет интерактивную панель управления, графики истории и публичную страницу статуса. Установка выполняется с помощью Compose-файла из десяти строк. Основное значение имеют место запуска и проверка срабатывания уведомлений в тестовом режиме. Монитор, который не прошел проверку на доставку уведомлений, бесполезен: он создает ложное чувство защищенности, когда на самом деле вы ничего не контролируете.

Запускайте монитор там, где сбой не сможет его заблокировать

Это решение определяет успех всей системы, поэтому оно является приоритетным. Не запускайте Uptime Kuma на том же сервере, который вы отслеживаете. Если монитор находится на проверяемом сервере, то критическая ситуация (отказ оборудования или нехватка памяти) одновременно остановит и монитор. В этом случае вы не получите уведомление: отсутствие данных от неработающего монитора выглядит так же, как статус «все в порядке». Существует и более скрытая проблема при работающем сервере: монитор, настроенный на localhost, делит ресурсы CPU с полезной нагрузкой. При скачке нагрузки проверка может завершиться по таймауту, и статус сменится на down. Это вызовет ложную тревогу, хотя реальные пользователи продолжат получать услуги в штатном режиме.

Запускайте Uptime Kuma на другом VPS, отличном от проверяемого сервера. В идеале используйте другого провайдера или другой регион, чтобы доступ к вашим сервисам осуществлялся так же, как у пользователей: через публичный интернет, по hostname. Достаточно использовать дешевый инстанс; одного небольшого VPS хватит для мониторинга всех ваших серверов. Чтобы обнаружить сбой самого Kuma, настройте отправку push heartbeat через cron на другом устройстве.

Предварительные требования и оценка ресурсов

  • Чистый VPS на базе Ubuntu 24.04 с установленными Docker Engine и плагином Compose v2. Устанавливайте их из официального репозитория Docker, а не из пакета docker.io, так как в нем могут быть устаревшие версии.
  • 256 MB RAM достаточно для работы нескольких мониторов. Для работы десятков мониторов вместе с reverse proxy рекомендуется от 512 MB до 1 GB. Нагрузка на CPU минимальна в периоды между проверками.
  • Домен и DNS A запись (например, status.example.com, указывающая на VPS), только если вам необходимы TLS и публичная страница статуса. Для приватного использования можно обойтись без DNS, используя VPN или SSH-туннель.
  • Исходящий сетевой доступ к сервисам отправки уведомлений: 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. Docker создает правила DNAT для публикации портов до того, как пакет будет обработан ufw. Поэтому использование 3001:3001 делает ваш дашборд доступным в публичном интернете, независимо от настроек firewall. Привязка к loopback сохраняет доступ приватным, открывая только обратный прокси; в этом случае можно обойти прокси и подключиться к 3001 через самостоятельно развернутый WireGuard VPN.

Именованный volume по пути /app/data. Все данные Uptime Kuma — база данных SQLite, ваши мониторы, настройки уведомлений и логотипы статус-страниц — хранятся там. При потере этих данных админ-панель будет пустой; это единственный элемент, который необходимо архивировать.

Образ зафиксирован на мажорном теге :2. Это текущая стабильная ветка. Перед копированием проверьте Docker Hub на наличие более новых мажорных версий. Никогда не используйте подвижные теги, такие как latest, так как проект признает их устаревшими. Переход на новую мажорную версию этого образа вызывает одностороннюю миграцию базы данных. Это действие должно быть преднамеренным, а не случайным результатом обычного выполнения команды pull.

Важное замечание: /app/data должен находиться на файловой системе с поддержкой POSIX file locks. Локальный Docker volume подходит; на NFS база данных SQLite повреждается, что приводит к ошибкам SQLITE_BUSY и database disk image is malformed, поэтому никогда не используйте сетевые ресурсы.

Первый запуск: создание учетной записи администратора

Перейдите к инстансу через ваш proxy по адресу https://status.example.com или через SSH-туннель: выполните ssh -L 3001:127.0.0.1:3001 user@your-vps и откройте http://localhost:3001. Первая страница представляет собой форму настройки имени пользователя и пароля администратора; учетные данные по умолчанию отсутствуют. Выберите надежный пароль: этот дашборд имеет доступ к внутренним адресам и токенам всех отслеживаемых объектов. Если вы забудете пароль, сбросьте его на хосте, а не в браузере:

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

Сначала добавьте каналы уведомлений и протестируйте их

Настройте оповещения перед добавлением мониторов. Это позволит прикреплять канал при создании каждого монитора. Перейдите в Settings, затем в Notifications, затем в Setup Notification. Используйте кнопку Test для каждого канала, чтобы подтвердить доставку сообщения. Непротестированное уведомление — вторая по частоте причина скрытых сбоев системы.

Email (SMTP). Заполните поля host, port, encryption, username, password, а также From и To. Рабочие комбинации: 465 с параметром "Secure" в значении TLS/SSL или 587 с использованием STARTTLS. Для Gmail и большинства провайдеров с двухфакторной аутентификацией необходимо создать app password. Обычный пароль от аккаунта вернет ошибку Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Отправьте сообщение @BotFather, отправьте /newbot и скопируйте bot token. Чтобы получить 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 incoming webhook, кастомные эндпоинты или системы автоматизации дома) используйте тип Webhook. Он отправляет JSON-объект методом POST на указанный вами URL. Встроенная интеграция Apprise поддерживает большинство из девяноста других сервисов в списке.

Добавление мониторов по одному

Нажмите Add New Monitor, выберите тип и установите Friendly Name, Check Interval (рекомендуется 60 секунд), Retries (количество последовательных сбоев перед переходом в статус «down»; установите 2 или 3, чтобы один потерянный пакет не вызывал оповещение) и параметры уведомлений. Вам понадобятся следующие типы:

  • HTTP(s). Полный URL. Статус «up» означает получение допустимого кода ответа (по умолчанию 200–299; измените диапазон в поле Accepted Status Codes, если для вас нормальны 301 или 401). Основной инструмент для проверки веб-сайтов и API.
  • HTTP(s) - Keyword. Тот же запрос, но статус «up» также требует наличия определенной строки в теле ответа (если флаг Invert не установлен). Это позволяет обнаружить ситуацию, когда сайт возвращает 200 OK, но отображает текст «Error establishing a database connection», что обычная HTTP-проверка сочтет за рабочий статус.
  • TCP Port. Прямое TCP-соединение с хостом и портом для протоколов, отличных от HTTP: SSH на 22, Postgres на 5432, SMTP-сервер на 25 или игровой сервер.
  • Ping. ICMP echo: проверка доступности и задержки (latency). Многие сети и облачные брандмауэры блокируют ICMP, поэтому красный статус монитора ping может означать как «хост недоступен», так и «провайдер блокирует ping»; в таких случаях используйте TCP-монитор для подтверждения.
  • DNS. Выполняет разрешение записи (A, AAAA, MX, TXT и т. д.) через указанный вами резолвер. Позволяет проверять корректность ответа и своевременно обнаруживать сбои регистратора или DNS-сервиса.
  • Push. Мониторинг по принципу «изнутри наружу» (inside-out), о котором будет сказано далее.

Мониторинг cron-задачи с помощью push-мониторинга (heartbeat)

Все вышеперечисленные методы мониторинга обращаются к вашему сервису извне. Push-мониторинг работает иначе: Uptime Kuma ожидает сигнала, а ваша задача сама отправляет его, подтверждая выполнение. Это единственный надежный способ мониторинга резервного копирования или cron-задач: HTTP-проверка подтверждает только доступность URL, но только сама задача знает, успешно ли она завершилась.

Создайте монитор типа Push. Uptime Kuma сгенерирует уникальный URL вида:

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

Установите параметр Heartbeat Interval равным частоте запуска задачи плюс небольшой запас времени. Затем добавьте одну строку в конец вашего скрипта, чтобы запрос отправлялся только при успешном выполнении:

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

Если задача завершится с ошибкой, set -e прервется до выполнения curl; если сервер выключен, скрипт также не запустится. В обоих случаях отправка heartbeat прекратится. Как только пройдет время, равное интервалу плюс количество попыток (retries), Uptime Kuma переведет статус монитора в состояние down и отправит уведомление. Относитесь к этому push-токену как к секретному значению: любой, кто им владеет, может имитировать успешную работу.

Создание публичной страницы состояния

Страница состояния — это интерфейс для клиентов. Она показывает доступность сервисов и историю их работы, не раскрывая содержимое вашей панели управления. Перейдите в Status Pages, затем выберите New Status Page. Введите имя и slug (публичный путь, например /status/main). Перетащите нужные мониторы в группы, такие как "Websites" или "APIs". Добавьте логотип и краткое описание, затем нажмите Save. Вы также можете привязать страницу к отдельному домену, чтобы status.example.com обслуживал её напрямую.

Два предостережения: добавляйте только те мониторы, информацию о которых вы готовы сделать публичной, так как страница состояния подтверждает факт существования сервиса и его текущий статус; панель управления остается защищенной авторизацией, в то время как страница состояния намеренно является публичной и не требует аутентификации.

Настройте обратный прокси с TLS и учтите websockets

Для публичного экземпляра установите обратный прокси перед контейнером, привязанным к loopback, чтобы обеспечить работу TLS и использование доменного имени. Важная деталь, в которой часто ошибаются: интерфейс Uptime Kuma использует Socket.IO, поэтому прокси должен поддерживать upgrade WebSocket-соединения. Если этого не сделать, страница загрузится, но соединение не установится; на панели управления будет отображаться статус "Connecting...", данные не будут обновляться, а в консоли браузера появится ошибка 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, добавления сертификатов и настройки перенаправления с 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 решает эту задачу с помощью меток (labels) контейнеров и по умолчанию поддерживает WebSocket upgrade.

Не используйте basic-auth для всего vhost, так как это заблокирует доступ к публичной странице статуса и эндпоинту /api/push. Используйте встроенную систему входа Uptime Kuma, добавьте fail2ban для отслеживания повторных неудачных попыток входа, если сервис доступен из интернета. Если панель управления не должна быть публичной, откажитесь от прокси и используйте 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, резервная копия представляет собой копию этого тома, сделанную при остановленном контейнере. Это обеспечивает целостность файла 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

Сначала проверьте фактическое имя тома с помощью docker volume ls | grep kuma, так как Compose добавляет префикс имени директории проекта. Затем скопируйте архив на другой сервер, так как копия на том же VPS не является полноценным резервным копированием. Восстановление выполняется в обратном порядке: остановите стек, извлеките данные в пустой том /app/data и запустите стек.

Обновления

Обновление выполняется путем загрузки нового образа:

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

При первом запуске новый контейнер выполняет миграцию базы данных; следите за docker compose logs -f. Создайте резервную копию, указанную выше, перед загрузкой образа. Придерживайтесь одной мажорной версии: переход с :1 на :2 является односторонним, поэтому сначала сделайте резервную копию и изучите примечания к выпуску.

Режимы сбоев и соответствующие сообщения об ошибках

Ложное состояние "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, либо провайдер требует пароль приложения, а вы используете основной пароль от аккаунта. Сгенерируйте пароль приложения и вставьте его.

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. Обратный прокси не выполняет upgrade протокола до WebSocket. Добавьте заголовки Upgrade и Connection "upgrade" в nginx или используйте прокси, который пересылает их по умолчанию, например Traefik или Caddy. HTML загружается, так как это обычный HTTP GET; upgrade требуется только для WebSocket.

Монитор срока действия сертификата не выдает предупреждение или выдает его ошибочно. Либо установлена галочка Ignore TLS/SSL Error, что отключает проверку сертификата, либо монитор обращается к IP-адресу и считывает неверный сертификат из-за отсутствия SNI, что приводит к ошибке Hostname/IP does not match certificate's altnames. Снимите галочку игнорирования и используйте мониторинг по имени хоста.

SQLITE_BUSY или database disk image is malformed в логах. Том /app/data находится на файловой системе без поддержки блокировки файлов (обычно NFS); перенесите его на локальный Docker volume и восстановите из резервной копии.

FAQ

Где следует запускать мониторинг uptime?

На отдельном сервере от тех, которые вы отслеживаете. В идеале — у другого провайдера или в другом регионе. Доступ к целевым узлам должен осуществляться по hostname через публичный интернет, так же, как это делают ваши пользователи. Если монитор находится на том же сервере, что и целевые объекты, сбой сервера приведет к остановке монитора. Также перегрузка хоста может вызвать ложные уведомления о недоступности исправных сервисов. Использование отдельного маломощного VPS решает обе проблемы.

Как получать уведомления в Telegram или по электронной почте?

Добавьте канал в разделе Settings -> Notifications, затем привяжите его к каждому монитору. Для Telegram создайте бота через @BotFather и получите chat.id из https://api.telegram.org/bot<token>/getUpdates. Для электронной почты используйте 465 для SSL или 587 для STARTTLS с использованием пароля приложения, если ваш провайдер использует двухфакторную аутентификацию. Нажмите Test и убедитесь в доставке сообщения, прежде чем полагаться на этот метод.

Может ли Uptime Kuma отслеживать cron-задачи или скрипты резервного копирования?

Да, для этого используется тип монитора Push. Uptime Kuma предоставляет URL, который необходимо вызвать с помощью curl в конце скрипта; в этом случае уведомление сработает только при успешном завершении. Если задача завершится ошибкой или сервер будет недоступен, сигнал (heartbeat) не поступит, и вы получите уведомление по истечении заданного интервала. Это единственный надежный способ проверить фактический запуск запланированной задачи, так как внешняя проверка не имеет доступа к внутренним процессам системы.

Uptime Kuma против Zabbix: что выбрать?

Uptime Kuma за десять минут с минимальным потреблением ресурсов отвечает на вопросы: «доступен ли сервис извне» и «пришло ли уведомление», а также предоставляет страницу статуса. Она не собирает детальные метрики, такие как динамика загрузки CPU, памяти или диска, и не поддерживает глобальные пороги для всей инфраструктуры. Для этих целей полноценный сервер мониторинга Zabbix является более тяжелым инструментом, работающим через агентов; многие пользователи используют оба решения одновременно. Все еще не определились с выбором? наш обзор программ для self-hosting в 2026 году поможет вам сориентироваться.

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