> Полный список статей есть в [llms.txt](https://docs.f3cloud.com/llms.txt). Markdown-версия есть у каждой страницы, достаточно добавить .md к её адресу. Эта страница в Markdown: [https://docs.f3cloud.com/ru/docker/uptime-kuma.md](https://docs.f3cloud.com/ru/docker/uptime-kuma.md).

# 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 ГБ на диске, так что на самый маленький диск его лучше не ставить. Если сервера ещё нет, закажите его по [инструкции](https://docs.f3cloud.com/ru/client-area/order-vps.md).
* **Docker и Docker Compose**. Если их ещё нет, установите по [инструкции](https://docs.f3cloud.com/ru/docker/docker-installation.md). У нас стояли Docker 29.9.2 и Docker Compose 5.6.1.
* **Подключение по SSH**, например через [Termius](https://docs.f3cloud.com/ru/vps/termius-connection.md). Команды выполняются от имени `root`.
* **Адрес сайта**, за которым вы хотите следить. В примерах мы используем `https://example.com`.

***

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

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

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

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

```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 создаст сеть и запустит контейнер.

<figure><img src="https://docs.f3cloud.com/img/kuma-install.png" alt="Команда docker compose up -d создаёт сеть kuma_default и запускает контейнер uptime-kuma"><figcaption><p>Docker создал сеть и запустил контейнер Uptime Kuma</p></figcaption></figure>

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

> **Не открывайте порт 3001 в интернет.**
>
> Панель Kuma по обычному HTTP передаёт пароль администратора в открытом виде, поэтому мы оставили порт только на `127.0.0.1`. Кроме того, Docker публикует порты в обход брандмауэра UFW, подробнее об этой ловушке рассказано в статье про [Docker](https://docs.f3cloud.com/ru/docker/docker-installation.md). Мы проверили это на тестовом сервере. Когда мы убрали `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** и нажмите <kbd>Далее</kbd>. Это самый простой вариант, его рекомендует сама Kuma для небольших установок, а вся база будет одним файлом в папке `data`, что упрощает резервное копирование.

<figure><img src="https://docs.f3cloud.com/img/kuma-setup-db.png" alt="Первый запуск Uptime Kuma 2, выбор базы данных, отмечен вариант SQLite"><figcaption><p>Выбор базы данных при первом запуске</p></figcaption></figure>

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

1. В поле **Логин** введите имя администратора, например `admin`.
2. В полях **Пароль** и **Повторите пароль** введите длинный пароль. Лучше сгенерировать его в менеджере паролей.
3. Нажмите <kbd>Создать</kbd>.

<figure><img src="https://docs.f3cloud.com/img/kuma-setup-admin.png" alt="Форма создания администратора Uptime Kuma с полями Логин, Пароль и Повторите пароль"><figcaption><p>Учётная запись администратора</p></figcaption></figure>

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

<figure><img src="https://docs.f3cloud.com/img/kuma-dashboard-empty.png" alt="Пустая панель управления Uptime Kuma, сообщение Без Мониторов, пожалуйста добавить"><figcaption><p>Панель управления перед добавлением мониторов</p></figcaption></figure>

***

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

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-add-monitor.png" alt="Форма нового монитора, тип HTTP(s) - Ключевое слово, адрес https://example.com, слово Example Domain"><figcaption><p>Монитор с ключевым словом</p></figcaption></figure>

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

<figure><img src="https://docs.f3cloud.com/img/kuma-first-monitor.png" alt="Страница монитора example.com со статусом Доступен, временем ответа 52 мс и сроками действия сертификата и домена"><figcaption><p>Первая проверка прошла, монитор зелёный</p></figcaption></figure>

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

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

***

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

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

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-localhost-down.png" alt="Монитор SSH сервера для 127.0.0.1:22 в Uptime Kuma имеет статус Недоступен"><figcaption><p>Так выглядит монитор, который смотрит на 127.0.0.1 внутри контейнера</p></figcaption></figure>

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

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

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

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

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

***

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

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

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-dashboard.png" alt="Панель Uptime Kuma, четыре монитора доступны, один недоступен, внизу журнал событий со сбоями и восстановлениями"><figcaption><p>Сводка и журнал событий. Красным выделен монитор закрытого порта</p></figcaption></figure>

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

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

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

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

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

```bash
docker stop kuma-demo-site
```

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

```bash
docker start kuma-demo-site
```

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

<figure><img src="https://docs.f3cloud.com/img/kuma-outage-recovery.png" alt="Полоска проверок монитора Мой сайт, две оранжевые полоски, одна красная и дальше зелёные"><figcaption><p>Оранжевые полоски, красный сбой и зелёное восстановление</p></figcaption></figure>

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

***

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

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

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

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

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-status-edit.png" alt="Редактор страницы статуса в Uptime Kuma, слева настройки, справа пять добавленных мониторов"><figcaption><p>Редактор страницы статуса</p></figcaption></figure>

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-status-page.png" alt="Публичная страница статуса, сверху сообщение о плановых работах, ниже заголовок Частичная работа сервисов и пять мониторов"><figcaption><p>Страница статуса глазами посетителя</p></figcaption></figure>

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

Пока 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.** Это основной вариант для работы. Привяжите домен по [инструкции](https://docs.f3cloud.com/ru/vps/domain-to-vps.md), установите [nginx](https://docs.f3cloud.com/ru/web/nginx-installation.md) и получите [бесплатный сертификат](https://docs.f3cloud.com/ru/web/ustanovka-besplatnogo-ssl-sertifikata-lets-encrypt-na-server-s-nginx-ili-apache.md). Kuma работает через WebSocket, поэтому nginx должен передавать ещё два заголовка, `Upgrade` и `Connection`. Готовые примеры настройки есть на странице [Reverse Proxy](https://github.com/louislam/uptime-kuma/wiki/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.

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

<figure><img src="https://docs.f3cloud.com/img/kuma-telegram-form.png" alt="Форма настройки уведомления Telegram в Uptime Kuma с полями токен бота, ID чата, ID цепочки сообщений и URL сервера"><figcaption><p>Форма уведомления Telegram</p></figcaption></figure>

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

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

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

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

Мы проверили, как приходят уведомления, через тип **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
```

<figure><img src="https://docs.f3cloud.com/img/kuma-backup.png" alt="Запуск backup.sh, контейнер uptime-kuma остановлен и запущен, в папке backups лежат архивы kuma"><figcaption><p>Скрипт остановил Kuma, сделал архив и запустил её снова</p></figcaption></figure>

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

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

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

Мы проверили расписание, временно поставив запуск каждую минуту, и за две минуты появилось два новых архива. Подробнее о расписании рассказано в статье про [cron](https://docs.f3cloud.com/ru/linux/cron-linux.md). Копии на том же сервере не спасут, если пропадёт сам сервер, поэтому время от времени забирайте архивы к себе, например командой [rsync](https://docs.f3cloud.com/ru/linux/rsync-linux.md).

### Как восстановить 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`, вторая создаёт контейнер заново.

<figure><img src="https://docs.f3cloud.com/img/kuma-update.png" alt="Команды docker compose pull и docker compose up -d --force-recreate, образ получен, контейнер uptime-kuma запущен"><figcaption><p>Образ обновлён, контейнер создан заново</p></figcaption></figure>

Установленную версию можно посмотреть в панели, в меню профиля, **Настройки**, затем **О программе**. Мы проверили обновление на отдельном экземпляре. Сначала запустили 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`.

***

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

<details>

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

Внутри контейнера адрес `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 пересоздаст контейнер, а данные не пострадают. После этого монитор у нас позеленел.

</details>

<details>

<summary>ERR_CONNECTION_REFUSED при открытии localhost:3001</summary>

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

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

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

</details>

<details>

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

Панель потеряла связь с Kuma. Мы получили такое сообщение, когда остановили контейнер командой `docker compose stop` при открытой панели. После `docker compose start` панель сама переподключилась. Под сообщением Kuma добавляет подсказку «Используете обратный прокси? Проверьте, как настроить его для WebSocket». Если Kuma стоит за nginx, причина обычно в отсутствующих заголовках WebSocket, пример настройки есть в вики Uptime Kuma на странице [Reverse Proxy](https://github.com/louislam/uptime-kuma/wiki/Reverse-Proxy).

</details>

<details>

<summary>Request failed with status code 404</summary>

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

</details>

<details>

<summary>certificate has expired и self-signed certificate</summary>

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

</details>

<details>

<summary>200 - OK, but keyword is not in [...]</summary>

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

</details>

<details>

<summary>getaddrinfo ENOTFOUND имя</summary>

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

</details>

<details>

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

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

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

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

<figure><img src="https://docs.f3cloud.com/img/kuma-reset-password.png" alt="Сброс пароля командой npm run reset-password, найден пользователь admin, пароль сброшен"><figcaption><p>Сброс пароля администратора</p></figcaption></figure>

</details>

<details>

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

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

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

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

</details>

***

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

**Telegram-канал:** [https://t.me/f3cloud_news](https://t.me/f3cloud_news)\
**Официальный сайт:** [https://f3cloud.com](https://f3cloud.com/ru)