База знаний F3 Cloud

Русский

English
Deutsch
Español

Русский

English
Deutsch
Español

Uptime Kuma – мониторинг сайтов и серверов на VPS

Как установить Uptime Kuma на VPS и следить, что сайты и серверы работают. Установка в Docker, SSH-туннель к панели, создание администратора, мониторы HTTP, TCP и ping, повторные попытки, публичная страница статуса, уведомления (на примере Telegram и Webhook), резервные копии и обновление. Проверено на Debian 12 с Uptime Kuma 2.5.6.

Uptime Kuma – это бесплатная программа с открытым кодом, которая следит за тем, что ваши сайты и серверы работают. Каждую минуту она заходит на сайт, пробует открыть порт, пингует адрес, и если что-то перестало отвечать, вы узнаёте об этом сразу, а не от клиентов. Кроме проверок Kuma рисует графики доступности, хранит историю сбоев и умеет публиковать страницу статуса, на которой посетители видят, всё ли в порядке. В этой статье мы установим Uptime Kuma на VPS в Docker, создадим администратора, добавим мониторы разных типов, нарочно устроим сбой, опубликуем страницу статуса и разберём уведомления, резервные копии и обновление. Все шаги мы повторили на тестовом сервере с Debian 12, версия Uptime Kuma на момент проверки 2.5.6.

Как устроен Uptime Kuma ​

Uptime Kuma – это одна программа на Node.js с веб-интерфейсом. На сервере она работает как обычный процесс, который по расписанию выполняет проверки, и каждая проверка устроена очень просто. Для сайта это HTTP-запрос, для порта попытка установить TCP-соединение, для ping обычный эхо-запрос. У проверки только два исхода, ответ получен или нет, и к ним добавляется время отклика. Каждый результат Kuma записывает в базу данных как отдельную точку, а из этих точек складываются цветные полоски на панели, проценты доступности и график времени ответа. Подряд идущие неудачные точки образуют сбой, начало и конец которого попадают в журнал событий.

Из такого устройства следуют два практических вывода. Первый, Kuma видит ваш сервис так, как видит его сервер, на котором она стоит, а не так, как видят клиенты. Если Kuma работает на том же сервере, что и сайт, то при падении сервера замолчит и сам мониторинг, поэтому для настоящих проектов её лучше ставить на отдельный недорогой VPS. В нашей проверке мы для наглядности следили и за самим сервером, и за сайтом из контейнера. Второй вывод касается Docker. Контейнер живёт в собственной сети, и адрес 127.0.0.1 внутри него означает сам контейнер, а не сервер. Поэтому порты сервера Kuma должна проверять по особому имени, которое мы добавим в настройки в шаге 1. Мы сами наступили на эти грабли, проверяя порт SSH, подробности в разделе с вопросами в конце статьи.

Одна неудачная проверка не всегда означает настоящую аварию, ведь сайт мог не ответить из-за случайного сбоя в сети. Для этого у каждого монитора есть настройка Попыток. Пока попытки не исчерпаны, Kuma рисует неудачную проверку оранжевой полоской и ничего не отправляет, и только если ответа нет и после всех повторов, помечает сервис как недоступный и рассылает уведомления. В Uptime Kuma 2 для новых мониторов стоит 0 попыток, то есть сбой объявляется сразу после первой неудачной проверки. Мы покажем разницу в шаге 6. Все данные Kuma, от учётной записи до истории проверок, лежат в одной папке data на сервере, и по умолчанию история проверок хранится 180 дней. Благодаря этому программу легко обновлять и копировать.

Почему в образе указана цифра 2

Разработчики рекомендуют образ с тегом 2, который всегда указывает на последнюю версию второй ветки. Старый тег latest помечен в их документации как устаревший и по-прежнему указывает на первую версию, поэтому его лучше не использовать.

Что понадобится ​

  • Сервер с Debian 12, например тариф DE-RZ9-1. Контейнер Uptime Kuma с пятью мониторами занял на нашем сервере около 150 МБ памяти, а скачанный образ около 2,5 ГБ на диске, так что на самый маленький диск его лучше не ставить. Если сервера ещё нет, закажите его по инструкции.
  • Docker и Docker Compose. Если их ещё нет, установите по инструкции. У нас стояли Docker 29.9.2 и Docker Compose 5.6.1.
  • Подключение по SSH, например через Termius. Команды выполняются от имени root.
  • Адрес сайта, за которым вы хотите следить. В примерах мы используем https://example.com.

Шаг 1. Установите Uptime Kuma ​

Создайте папку для Kuma и файл настроек Docker Compose.

bash
mkdir -p /opt/kuma
cd /opt/kuma
nano compose.yaml

Вставьте в файл настройки ниже и сохраните его сочетанием Ctrl + O, затем Enter, а выйдите из редактора сочетанием Ctrl + X.

yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2   # официальный образ, вторая версия
    container_name: uptime-kuma
    restart: unless-stopped         # запуск после сбоя и перезагрузки сервера
    volumes:
      - ./data:/app/data            # все данные Kuma лежат в папке /opt/kuma/data
    ports:
      - "127.0.0.1:3001:3001"       # порт 3001 открыт только на самом сервере
    extra_hosts:
      - "host.docker.internal:host-gateway"   # имя сервера для проверок изнутри контейнера

Файл почти повторяет официальный compose.yaml из репозитория Uptime Kuma, мы добавили в него три вещи.

  • container_name задаёт понятное имя контейнера, которое мы будем использовать в командах.
  • 127.0.0.1: перед портом оставляет панель доступной только с самого сервера. В официальном файле стоит 3001:3001, и тогда порт открыт всем.
  • extra_hosts добавляет внутрь контейнера имя host.docker.internal, которое указывает на сервер. Оно понадобится в шаге 5 для проверки портов сервера.

Запустите Kuma.

bash
docker compose up -d

При первом запуске Docker скачает образ размером около 600 МБ, на нашем сервере это заняло около 20 секунд. Затем Docker создаст сеть и запустит контейнер.

Команда docker compose up -d создаёт сеть kuma_default и запускает контейнер uptime-kuma

Docker создал сеть и запустил контейнер Uptime Kuma

Проверьте состояние командой docker compose ps. Примерно через 20 секунд в столбце STATUS появится пометка (healthy), это значит, что Kuma запустилась и отвечает.

Не открывайте порт 3001 в интернет

Панель Kuma по обычному HTTP передаёт пароль администратора в открытом виде, поэтому мы оставили порт только на 127.0.0.1. Кроме того, Docker публикует порты в обход брандмауэра UFW, подробнее об этой ловушке рассказано в статье про Docker. Мы проверили это на тестовом сервере. Когда мы убрали 127.0.0.1 из строки ports, порт 3001 стал доступен с нашего компьютера, хотя в UFW для него не было правила. А с 127.0.0.1 соединение не устанавливалось, и компьютер просто ждал до тайм-аута.

Шаг 2. Откройте панель через SSH-туннель ​

Раз порт закрыт от интернета, панель открывают через SSH-туннель. Он пробрасывает порт вашего компьютера на порт сервера, поэтому для браузера Kuma выглядит так, будто работает на вашем компьютере.

  1. На своём компьютере откройте новое окно терминала и создайте туннель. Вместо IP-адрес-сервера подставьте адрес вашего VPS.

    bash
    ssh -L 3001:127.0.0.1:3001 root@IP-адрес-сервера

  2. Не закрывая это окно, откройте в браузере адрес http://localhost:3001.

Если порт 3001 на вашем компьютере уже занят, пробросьте другой, например ssh -L 13001:127.0.0.1:3001 root@IP-адрес-сервера, и откройте http://localhost:13001. Именно так мы работали сами.

Шаг 3. Выберите базу данных и создайте администратора ​

При первом открытии Kuma 2 спрашивает, Какую базу данных вы хотите использовать. Интерфейс у нас сразу открылся на русском, так как браузер был русскоязычным, а сменить язык можно в списке Язык на этой же странице. Вариантов три.

  • Embedded MariaDB – ничего настраивать не нужно, образ Docker уже содержит готовую MariaDB.
  • MariaDB/MySQL – подключение к внешней базе. Нужно указать имя хоста, порт, логин, пароль и имя базы.
  • SQLite – простой файл базы данных, который рекомендуется для небольших установок.

Выберите SQLite и нажмите Далее. Это самый простой вариант, его рекомендует сама Kuma для небольших установок, а вся база будет одним файлом в папке data, что упрощает резервное копирование.

Первый запуск Uptime Kuma 2, выбор базы данных, отмечен вариант SQLite

Выбор базы данных при первом запуске

Через несколько секунд Kuma подготовит базу и предложит Создайте аккаунт администратора.

  1. В поле Логин введите имя администратора, например admin.
  2. В полях Пароль и Повторите пароль введите длинный пароль. Лучше сгенерировать его в менеджере паролей.
  3. Нажмите Создать.
Форма создания администратора Uptime Kuma с полями Логин, Пароль и Повторите пароль

Учётная запись администратора

Kuma откроет панель управления. Слева будет список мониторов, пока пустой, а справа Сводка, где считаются мониторы по состояниям, и журнал важных событий.

Пустая панель управления Uptime Kuma, сообщение Без Мониторов, пожалуйста добавить

Панель управления перед добавлением мониторов

Шаг 4. Добавьте первый монитор для сайта ​

Для сайта лучше всего подходит монитор, который проверяет не только код ответа, но и содержимое страницы. Сайт с поломкой нередко продолжает отвечать кодом 200, но вместо страницы показывает пустое место или сообщение об ошибке. Монитор с ключевым словом заметит и это.

  1. Нажмите Новый монитор.
  2. В списке Тип монитора выберите HTTP(s) - Ключевое слово.
  3. В поле Имя введите название, например example.com (ключевое слово).
  4. В поле URL-ссылка укажите адрес сайта, у нас https://example.com.
  5. В поле Ключевое слово введите слово, которое должно быть на странице. У example.com это Example Domain. Регистр букв важен.
  6. Нажмите Сохранить.
Форма нового монитора, тип HTTP(s) - Ключевое слово, адрес https://example.com, слово Example Domain

Монитор с ключевым словом

Через несколько секунд Kuma сделает первую проверку, и монитор станет зелёным со статусом Доступен. У нас сайт ответил за 52 мс, а в журнале появилась запись 200 - OK, keyword is found. Для сайта с HTTPS Kuma сама показывает на этой же странице, через сколько дней истекает сертификат и доменное имя.

Страница монитора example.com со статусом Доступен, временем ответа 52 мс и сроками действия сертификата и домена

Первая проверка прошла, монитор зелёный

В форме есть настройки, которые стоит знать с самого начала.

  • Интервал опроса – как часто Kuma проверяет сайт, по умолчанию 60 секунд.
  • Попыток – сколько раз повторить неудачную проверку, прежде чем объявить сбой. По умолчанию 0.
  • Тайм-аут запроса – сколько секунд ждать ответа, по умолчанию 48.
  • Уведомление об истечении срока действия сертификата – предупреждение, когда сертификат сайта скоро закончится.

Шаг 5. Добавьте мониторы для сервера ​

Теперь проверим сам сервер. Сначала добавим монитор порта SSH, он покажет, что сервер включён и принимает подключения.

  1. Нажмите Новый монитор и выберите тип TCP Port.
  2. В поле Имя введите SSH сервера.
  3. В поле Имя хоста введите host.docker.internal.
  4. В поле Порт введите 22.
  5. Нажмите Сохранить.

Обратите внимание на имя хоста. Адрес 127.0.0.1, который кажется очевидным, внутри контейнера не сработает, он ведёт в сам контейнер, где порта 22 нет. Мы проверили это на себе, монитор для 127.0.0.1:22 сразу стал красным.

Монитор SSH сервера для 127.0.0.1:22 в Uptime Kuma имеет статус Недоступен

Так выглядит монитор, который смотрит на 127.0.0.1 внутри контейнера

После замены имени хоста на host.docker.internal монитор позеленел, и порт ответил за 1 мс. Имя работает, потому что мы добавили extra_hosts в файл Compose в шаге 1. В нашей проверке оно указывало на адрес 172.17.0.1, это адрес сервера внутри сети Docker.

Теперь добавим монитор ping, который проверяет, отвечает ли адрес на эхо-запросы.

  1. Нажмите Новый монитор и выберите тип Ping.
  2. В поле Имя введите Ping 1.1.1.1.
  3. В поле Имя хоста введите 1.1.1.1.
  4. Нажмите Сохранить.

Ping до 1.1.1.1 ответил за 6,45 мс. Он полезен, чтобы убедиться, что у сервера есть выход в интернет, или чтобы следить за маршрутизатором и другими устройствами, у которых нет сайта.

В списке типов есть и другие мониторы. Среди них DNS, SMTP, Docker контейнер, Push, а также проверки баз данных MySQL/MariaDB, PostgreSQL, MongoDB и Redis. Принцип у всех один, Kuma по расписанию обращается к сервису и записывает результат.

Шаг 6. Устройте сбой и посмотрите, как он выглядит ​

Мониторы нужны ради тех минут, когда что-то ломается, поэтому проверим, как это выглядит. Начнём с самого простого сбоя, порта, на котором никто не слушает.

  1. Нажмите Новый монитор и выберите тип TCP Port.
  2. В поле Имя введите Закрытый порт 12345.
  3. В полях Имя хоста и Порт укажите host.docker.internal и 12345.
  4. В поле Интервал опроса введите 20, чтобы не ждать минуту.
  5. Нажмите Сохранить.

Через несколько секунд монитор станет красным, а в углу экрана появится красное сообщение. В журнале событий запишется статус Недоступен с текстом Connection failed, а в сводке счётчик Недоступен изменится на 1. Такой монитор никогда не позеленеет, и мы оставим его на панели как пример сбоя.

Панель Uptime Kuma, четыре монитора доступны, один недоступен, внизу журнал событий со сбоями и восстановлениями

Сводка и журнал событий. Красным выделен монитор закрытого порта

Теперь устроим более живой сбой. Запустим на сервере простой сайт в Docker и остановим его. Контейнер нужно поместить в ту же сеть, что и Kuma. Docker Compose создал её сам, а имя сети складывается из названия папки и слова default, у нас это kuma_default.

bash
docker run -d --name kuma-demo-site --network kuma_default --restart unless-stopped nginx:alpine

Добавьте монитор для этого сайта.

  1. Нажмите Новый монитор и выберите тип HTTP(s).
  2. В поле Имя введите Мой сайт.
  3. В поле URL-ссылка введите http://kuma-demo-site. Контейнеры одной сети находят друг друга по имени.
  4. В поле Интервал опроса введите 20.
  5. В поле Попыток введите 2. Рядом появится поле Интервал повтора запроса, оставьте в нём 20.
  6. Нажмите Сохранить.

Остановите сайт и подождите около минуты.

bash
docker stop kuma-demo-site

Kuma не объявляет сбой сразу. Две первые неудачные проверки она рисует оранжевыми полосками, и только третья подряд превращается в красную. У нас статус Недоступен появился примерно через минуту после остановки контейнера, и до этого момента ни одного уведомления не ушло. Теперь запустите сайт снова.

bash
docker start kuma-demo-site

На ближайшей проверке монитор вернулся в Доступен, а в журнале появилась запись о восстановлении. У нас это случилось уже через несколько секунд после запуска контейнера.

Полоска проверок монитора Мой сайт, две оранжевые полоски, одна красная и дальше зелёные

Оранжевые полоски, красный сбой и зелёное восстановление

Текст ошибки зависит от того, как именно сервис перестал отвечать. В двух наших остановках это были connect ECONNREFUSED 172.21.0.3:80 и connect EHOSTUNREACH 172.21.0.3:80.

Шаг 7. Опубликуйте страницу статуса ​

Страница статуса – это публичная страница, на которой посетители видят состояние ваших сервисов без входа в панель. Её удобно показывать клиентам, чтобы они не писали в поддержку при каждом сбое.

  1. В верхнем меню нажмите Страницы статуса, затем Новая страница статуса.
  2. В поле Имя введите название, например Статус сервисов.
  3. В поле Slug введите часть адреса, например main. Страница откроется по адресу /status/main. Slug может состоять только из строчных латинских букв, цифр и дефисов.
  4. Нажмите Далее.

Откроется редактор. Слева находятся настройки страницы, справа предварительный вид.

  • Описание и Текст нижнего колонтитула – тексты вверху и внизу страницы. Они поддерживают Markdown.
  • Интервал обновления – как часто страница сама перезагружается, по умолчанию 300 секунд.
  • Тема – светлая, тёмная или как в системе посетителя.
  • Доменные имена – адреса, при заходе на которые показывается именно эта страница, так можно держать несколько страниц на одной Kuma.

Выберите мониторы в списке Добавить монитор и нажмите Сохранить. Мониторы можно разложить по группам кнопкой Добавить Группу. В нашей странице все мониторы оказались в группе Сервисы, и мы добавили туда даже монитор закрытого порта, чтобы показать, как сбой выглядит для посетителей.

Редактор страницы статуса в Uptime Kuma, слева настройки, справа пять добавленных мониторов

Редактор страницы статуса

Посетители видят страницу без кнопок управления. Мы проверили это, открыв её в отдельном окне без входа в Kuma. Если часть мониторов недоступна, вверху автоматически появляется заголовок Частичная работа сервисов.

Если нужно объяснить причину сбоя, нажмите в редакторе Создать инцидент. Впишите Название и Содержание, нажмите Опубликовать, а затем сохраните страницу, и сообщение появится над списком сервисов. Позже его можно изменить, закрыть или удалить, для этого у инцидента есть кнопки Изменить, Закрыть и Удалить.

Публичная страница статуса, сверху сообщение о плановых работах, ниже заголовок Частичная работа сервисов и пять мониторов

Страница статуса глазами посетителя

Как показать страницу посетителям ​

Пока Kuma слушает только 127.0.0.1, страницу видите лишь вы через туннель. Чтобы её увидели другие, есть два пути.

  • Открыть порт напрямую. Замените в compose.yaml строку "127.0.0.1:3001:3001" на "3001:3001" и выполните docker compose up -d. Страница станет доступна по адресу http://IP-адрес-сервера:3001/status/main, но вместе с ней в интернет откроется и окно входа в панель по HTTP без шифрования. Мы проверили, что порт после такой замены открывается.
  • Поставить Kuma за nginx с доменом и HTTPS. Это основной вариант для работы. Привяжите домен по инструкции, установите nginx и получите бесплатный сертификат. Kuma работает через WebSocket, поэтому nginx должен передавать ещё два заголовка, Upgrade и Connection. Готовые примеры настройки есть на странице Reverse Proxy в вики Uptime Kuma. Там же сказано, что для показа разных страниц по доменам прокси должен передавать Kuma заголовок Host или X-Forwarded-Host. Мы эту связку на тестовом сервере не собирали, так как порты 80 и 443 там заняты другим сервисом.

Страница обновляется не мгновенно

По описанию в вики Uptime Kuma, страница статуса кэширует результаты на 5 минут и сама обновляется раз в 5 минут. Поэтому она отстаёт от панели управления, это нормально.

Шаг 8. Настройте уведомления ​

Панель полезна, только когда вы на неё смотрите, а уведомления приходят сами. Kuma умеет отправлять их в десятки сервисов. В списке типов есть Telegram, Discord, Slack, Email (SMTP), Webhook, Apprise и многие другие. Рассмотрим форму на примере Telegram.

Откройте меню профиля в правом верхнем углу, выберите Настройки, затем Уведомления и нажмите Настройка уведомления. В списке Тип уведомления по умолчанию выбран Telegram.

Форма настройки уведомления Telegram в Uptime Kuma с полями токен бота, ID чата, ID цепочки сообщений и URL сервера

Форма уведомления Telegram

В форме такие поля.

  • Имя – название уведомления, по которому вы найдёте его в списках.
  • Токен бота – ключ вашего бота. Его выдаёт бот @BotFather, ссылка на него есть под полем. Токен вводится в скрытом виде, значок глаза показывает его.
  • ID чата – идентификатор чата, группы или канала, куда бот будет писать. Kuma подсказывает, как его узнать. Нужно написать боту сообщение и открыть в браузере адрес https://api.telegram.org/bot<ВАШ ТОКЕН БОТА ЗДЕСЬ>/getUpdates, в ответе будет chat_id.
  • ID цепочки сообщений – необязательное поле для тем форума. Подходит только для супергрупп с темами.
  • URL Сервера – необязательное поле, в нём по умолчанию стоит https://api.telegram.org. Обычно его не меняют.
  • Используйте пользовательский шаблон сообщения – включите, если хотите сами написать текст уведомления.
  • Отправить без звука – сообщения приходят без звукового сигнала.
  • Запретить пересылку/сохранение – Telegram не даст переслать или сохранить сообщения бота.
  • По умолчанию включён – уведомление будет включаться для каждого нового монитора.
  • Применить ко всем существующим мониторам – подключает уведомление ко всем мониторам, которые уже есть.

Кнопка Тест отправляет проверочное сообщение, а Сохранить сохраняет уведомление. Настоящего бота мы для этой статьи не создавали, поэтому форму Telegram только разобрали по полям.

Сохранённое уведомление нужно подключить к мониторам. Откройте монитор, нажмите Изменить и найдите справа блок Уведомления. В нём перечислены все созданные уведомления с переключателями. Включите нужный и нажмите Сохранить. Если вы отметили По умолчанию включён, переключатель в новых мониторах уже будет включён.

Мы проверили, как приходят уведомления, через тип Webhook, который отправляет запрос на любой адрес. За каждую остановку и запуск контейнера с сайтом пришло ровно два сообщения, первое при переходе в Недоступен, второе при восстановлении. Оранжевые проверки с повторами уведомлений не вызвали. Текст уведомления Kuma составляет сама.

text
[Мой сайт] [🔴 Down] connect EHOSTUNREACH 172.21.0.3:80
[Мой сайт] [✅ Up] 200 - OK

Если вы хотите, чтобы Kuma напоминала о затянувшемся сбое, в форме монитора есть поле Повторно отправлять уведомление, если сбой произошёл X раз подряд, по умолчанию повторная отправка отключена.

Плановые работы без лишних уведомлений

В меню профиля есть пункт Техобслуживание. По описанию в вики Uptime Kuma, в окно техобслуживания уведомления для выбранных мониторов не отправляются, а сообщение о работах можно показать на страницах статуса. Заведите такое окно перед тем, как отключать сервис на обновление.

Шаг 9. Настройте резервные копии ​

Всё, что Kuma знает, лежит в папке /opt/kuma/data. Это учётная запись администратора, мониторы, уведомления, страницы статуса и история проверок. В Uptime Kuma 2 убрали старую выгрузку настроек в JSON, и в руководстве по переходу на вторую версию разработчики прямо пишут, что копирование папки data остаётся единственным поддерживаемым способом резервного копирования.

Копировать её нужно аккуратно. Пока Kuma работает, база SQLite хранит свежие изменения в отдельных файлах kuma.db-wal и kuma.db-shm, мы видели их рядом с kuma.db в работающей Kuma. Если скопировать файлы на ходу, копия может оказаться неполной. Поэтому скрипт ниже на несколько секунд останавливает Kuma, архивирует папку и запускает Kuma снова. После остановки в папке остаётся один файл kuma.db.

bash
nano /opt/kuma/backup.sh
bash
#!/bin/sh
# Останавливает Kuma, архивирует папку data и снова запускает Kuma
cd /opt/kuma || exit 1
mkdir -p backups
docker compose stop
tar -czf "backups/kuma-$(date +%F-%H%M).tar.gz" data
docker compose start
# Хранит 7 последних архивов
ls -1t backups/kuma-*.tar.gz | tail -n +8 | xargs -r rm --

Сделайте скрипт исполняемым и запустите его вручную.

bash
chmod +x /opt/kuma/backup.sh
/opt/kuma/backup.sh
ls -lh /opt/kuma/backups
Запуск backup.sh, контейнер uptime-kuma остановлен и запущен, в папке backups лежат архивы kuma

Скрипт остановил Kuma, сделал архив и запустил её снова

На нашем сервере остановка и запуск вместе заняли около 5 секунд, а архив с пятью мониторами весил около 50 КБ. На это время Kuma не делает проверок, так что в графике будет короткий пропуск.

Чтобы копии делались сами, добавьте задание в расписание, например на 4 часа ночи. Файл в папке /etc/cron.d проще, чем редактирование общего расписания.

bash
echo "0 4 * * * root /opt/kuma/backup.sh" > /etc/cron.d/kuma-backup

Мы проверили расписание, временно поставив запуск каждую минуту, и за две минуты появилось два новых архива. Подробнее о расписании рассказано в статье про cron. Копии на том же сервере не спасут, если пропадёт сам сервер, поэтому время от времени забирайте архивы к себе, например командой rsync.

Как восстановить Kuma из копии ​

Остановите Kuma, уберите текущую папку data в сторону и распакуйте архив. Вместо имени архива подставьте нужный файл из папки backups.

bash
cd /opt/kuma
docker compose down
mv data data.old
tar -xzf backups/kuma-2026-10-21-1526.tar.gz
docker compose up -d

Мы проверили восстановление отдельно. Распаковали архив в чистую папку, запустили из него вторую Kuma и вошли тем же логином и паролем. Мониторы с историей проверок, страница статуса с инцидентом и настроенное уведомление оказались на месте.

Шаг 10. Обновите Uptime Kuma ​

Новые версии Kuma выходят регулярно и исправляют ошибки и уязвимости. Например, в описании выпуска 2.5.6 на GitHub есть и исправление ошибки, и обновление зависимостей по безопасности. Обновление в Docker заключается в том, чтобы скачать свежий образ и создать контейнер заново. Данные при этом остаются в папке data и не затрагиваются. Перед обновлением сделайте резервную копию из шага 9.

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

Первая команда скачивает свежий образ для тега 2, вторая создаёт контейнер заново.

Команды docker compose pull и docker compose up -d --force-recreate, образ получен, контейнер uptime-kuma запущен

Образ обновлён, контейнер создан заново

Установленную версию можно посмотреть в панели, в меню профиля, Настройки, затем О программе. Мы проверили обновление на отдельном экземпляре. Сначала запустили Uptime Kuma 2.4.0 с образом louislam/uptime-kuma:2.4.0, создали в ней администратора и монитор, затем заменили тег на 2 и выполнили команды выше. После этого в О программе стояла версия 2.5.6, администратор вошёл со своим паролем, а монитор остался на месте вместе с историей проверок.

Переход с первой версии делайте по руководству

Если у вас уже работает Uptime Kuma 1, не обновляйте её просто сменой тега. В вики разработчиков есть отдельное руководство по переходу на вторую версию. Там сказано сначала сделать копию папки data, а сам переход может идти долго, и его нельзя прерывать. Мы этот переход не проверяли.

Если вам нужна конкретная версия, а не последняя в ветке, укажите её в image, например louislam/uptime-kuma:2.5.6. Так мы запускали Uptime Kuma 2.4.0 в проверке обновления.

Полезные команды ​

bash
docker compose ps                         # состояние контейнера
docker logs uptime-kuma                   # журнал Kuma
docker compose stop                       # остановить Kuma, данные останутся
docker compose start                      # запустить Kuma снова
docker compose pull                       # скачать свежий образ
docker compose up -d --force-recreate     # пересоздать контейнер на новом образе
docker exec -it uptime-kuma npm run reset-password   # сбросить пароль администратора
docker stats --no-stream uptime-kuma      # память и процессор контейнера

Все команды выполняются в папке /opt/kuma.

Частые вопросы ​

Монитор для 127.0.0.1:22 показывает Недоступен и Connection failed

Внутри контейнера адрес 127.0.0.1 означает сам контейнер, а не сервер. Мы проверили это командой изнутри контейнера, и она получила отказ.

bash
docker exec uptime-kuma bash -c "echo > /dev/tcp/127.0.0.1/22"

В ответе будет Connection refused. В поле Имя хоста монитора укажите host.docker.internal. Если вы не добавили extra_hosts в compose.yaml, сделайте это, как в шаге 1, и выполните docker compose up -d. Compose пересоздаст контейнер, а данные не пострадают. После этого монитор у нас позеленел.

ERR_CONNECTION_REFUSED при открытии localhost:3001

Браузер не нашёл ничего на порту вашего компьютера. Проверьте три вещи.

  1. Окно терминала с командой ssh -L должно быть открыто, туннель работает только пока оно открыто.
  2. Порт в адресе должен совпадать с первым портом в команде ssh -L.
  3. Контейнер на сервере должен работать, это показывает команда docker compose ps.

Не получится и открыть панель по адресу http://IP-адрес-сервера:3001. Порт слушает только 127.0.0.1, и у нас такое соединение просто висело до тайм-аута.

Невозможно подключиться к серверу сокетов. [Error: xhr poll error] Переподключение...

Панель потеряла связь с Kuma. Мы получили такое сообщение, когда остановили контейнер командой docker compose stop при открытой панели. После docker compose start панель сама переподключилась. Под сообщением Kuma добавляет подсказку «Используете обратный прокси? Проверьте, как настроить его для WebSocket». Если Kuma стоит за nginx, причина обычно в отсутствующих заголовках WebSocket, пример настройки есть в вики Uptime Kuma на странице Reverse Proxy.

Request failed with status code 404

Сайт ответил, но с кодом, который не входит в разрешённые. По умолчанию успешными считаются коды 200–299. Мы получили эту ошибку, проверяя несуществующую страницу https://example.com/missing. Проверьте адрес в поле URL-ссылка. Если сайт отвечает другим кодом и так задумано, добавьте его в поле Допустимые коды статуса в форме монитора.

certificate has expired и self-signed certificate

У сайта проблема с сертификатом HTTPS. Мы получили certificate has expired на тестовом сайте expired.badssl.com и self-signed certificate на self-signed.badssl.com. Сначала по возможности исправьте сертификат на самом сайте. Если вам нужно следить за сайтом, которому вы доверяете, но сертификат у него намеренно самоподписанный, включите в форме монитора флажок Игнорировать ошибки TLS/SSL для сайтов с HTTPS. После этого монитор с просроченным сертификатом у нас стал показывать 200 - OK.

200 - OK, but keyword is not in [...]

Сайт ответил, но слова из поля Ключевое слово на странице нет. Мы получили эту ошибку, указав Hello world для example.com. Kuma ищет слово с учётом регистра и показывает в квадратных скобках начало страницы, которую получила. Сверьте слово со страницей и поправьте его в форме монитора.

getaddrinfo ENOTFOUND имя

Kuma не смогла превратить имя в адрес. Проверьте, нет ли опечатки в имени. Если вы проверяете контейнер по имени, как kuma-demo-site в шаге 6, убедитесь, что он запущен и подключён к той же сети, что и Kuma. Мы получили эту ошибку для несуществующего домена, а также на копии Kuma, которая работала в другой сети Docker и не видела контейнера kuma-demo-site.

Неверное имя пользователя или пароль. Как сбросить пароль

С этим сообщением мы столкнулись, когда вошли в Kuma со старым паролем после сброса. Если вы забыли пароль, его можно сбросить командой на сервере.

bash
docker exec -it uptime-kuma npm run reset-password

Программа найдёт пользователя, дважды спросит новый пароль и сообщит Password reset successfully.. Пароль при вводе отображается на экране, поэтому делайте это, когда за вами никто не смотрит.

Сброс пароля командой npm run reset-password, найден пользователь admin, пароль сброшен

Сброс пароля администратора

Kuma показывает Недоступен, а сайт в браузере открывается

Kuma проверяет сайт со своего сервера, поэтому ответ может отличаться от того, который видите вы. Разработчики советуют проверить доступность прямо из контейнера. В образе уже есть curl.

bash
docker exec -it uptime-kuma bash
curl -I https://example.com

Если здесь та же ошибка, проблема в сети сервера, файрволе или DNS, а не в самой Kuma.

Наши ресурсы ​

Telegram-канал: https://t.me/f3cloud_news
Официальный сайт: https://f3cloud.com