Мониторинг служб с помощью Uptime Kuma
Установите Uptime Kuma с помощью Docker Compose на Debian или Ubuntu, защитите доступ по HTTPS, создайте мониторы и уведомления, затем управляйте обновлениями и резервными копиями.
На этой странице
Ваши значения
Укажите их один раз, и команды в руководстве обновятся.
Uptime Kuma — это самостоятельно размещаемый инструмент мониторинга. Он регулярно проверяет ваши сайты, порты и службы, хранит историю их доступности и предупреждает вас о сбоях.
К концу этого руководства Uptime Kuma будет работать в Docker, слушать только локальный адрес сервера и отвечать по HTTPS за Caddy с защищённым доступом. Вы создадите первый монитор и уведомление, а также научитесь обновлять экземпляр и создавать его резервные копии.
Заказать сервер
Это руководство подходит для серверов, которыми вы управляете самостоятельно:
Предварительные требования
- Сервер под управлением Debian 12 или 13 либо Ubuntu 22.04 или 24.04
- Доступ по SSH под пользователем с правами
sudo - Docker Engine и Docker Compose, установленные по руководству Установка Docker Engine и Docker Compose
- Caddy, установленный по руководству Caddy как обратный прокси с автоматическим HTTPS
- Запись A для
uptime.ваш-домен.com, указывающая наIP_ВАШЕГО_СЕРВЕРА - Локальный диск для данных: сетевые хранилища, такие как NFS, не поддерживаются
Команды docker предполагают, что ваш пользователь входит в группу docker. В противном случае добавляйте перед ними sudo.
В этом руководстве используется версия 2.5.12 — последняя стабильная версия на момент написания. Актуальную версию можно проверить на странице выпусков Uptime Kuma. Ветка 3 всё ещё находится в стадии бета-тестирования: не используйте её в рабочей среде.
Используемые порты
| Порт | Направление | Назначение | Нужно ли открывать |
|---|---|---|---|
| 80/tcp | Входящий | Сертификат и перенаправление на HTTPS через Caddy | Да |
| 443/tcp | Входящий | Доступ по HTTPS через Caddy | Да |
| 3001/tcp | Локальный | Интерфейс Uptime Kuma на 127.0.0.1 |
Нет |
Сервер также должен иметь исходящий доступ к отслеживаемым службам и вашим службам уведомлений.
Шаг 1: создайте проект Compose
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yamlВставьте эту конфигурацию:
services:
uptime-kuma:
image: louislam/uptime-kuma:2.5.12
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/dataЗапустите контейнер:
docker compose config --quiet
docker compose up -d
docker compose psКонтейнер должен отображаться как запущенный (Up). Его проверка работоспособности может оставаться в состоянии starting в течение первых минут.
Шаг 2: создайте учётную запись через SSH-туннель
Учётную запись администратора создаёт первый посетитель. Поэтому сделайте это до публикации сайта. В терминале на вашем компьютере:
ssh -N -L 3001:127.0.0.1:3001 ВАШ_ПОЛЬЗОВАТЕЛЬ@IP_ВАШЕГО_СЕРВЕРАКоманда остаётся активной и ничего не выводит. Затем откройте http://localhost:3001 и выполните следующие действия:
- Выберите язык.
- Выберите базу данных SQLite, подходящую для установки небольшого масштаба.
- Дождитесь подготовки базы данных.
- Создайте учётную запись администратора с длинным уникальным паролем.
Шаг 3: усильте защиту учётной записи
В разделе Settings (Настройки):
| Раздел | Настройка | Значение |
|---|---|---|
| Security | 2FA Settings | Включите двухфакторную аутентификацию с помощью приложения TOTP |
| Security | Disable Auth | Не включайте этот параметр |
| Reverse Proxy | Trust Proxy | Yes, поскольку служба доступна только через Caddy |
Trust Proxy позволяет отображать настоящий адрес посетителей в журналах. Включайте этот параметр, только если порт 3001 остаётся ограничен адресом 127.0.0.1.
Шаг 4: опубликуйте интерфейс через Caddy
Выберите режим, подходящий для ваших задач.
Доступ только с вашего адреса (рекомендуется)
Интерфейс доступен только с вашего IP-адреса. URL /api/push/ остаются доступными, чтобы ваши запланированные задачи могли отправлять сигналы. Добавьте этот сайт в /etc/caddy/Caddyfile:
uptime.ваш-домен.com {
@push path /api/push/*
@allowed client_ip ВАШ_IP
handle @push {
reverse_proxy 127.0.0.1:3001
}
handle @allowed {
reverse_proxy 127.0.0.1:3001
}
handle {
abort
}
}Если ваш адрес часто меняется, лучше используйте WireGuard или Tailscale.
Публичный доступ со страницей статуса
Страница статуса должна оставаться доступной вашим пользователям. В этом случае страница входа тоже доступна, поэтому двухфакторная аутентификация из шага 3 становится обязательной.
uptime.ваш-домен.com {
reverse_proxy 127.0.0.1:3001
}Применение конфигурации
Caddy самостоятельно передаёт WebSocket-соединения, необходимые Uptime Kuma. Поскольку Caddy установлен на сервере, а не в Docker, на его порты распространяются правила UFW:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyПроверка результата
Туннель можно закрыть сочетанием Ctrl+C. Откройте https://uptime.ваш-домен.com: должна появиться страница входа с действительным сертификатом. На сервере проверьте порт:
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'Вывод должен содержать 127.0.0.1:3001->3001/tcp. С другого компьютера порт 3001 не должен быть открыт:
nmap -Pn -p 3001 IP_ВАШЕГО_СЕРВЕРАПри ограниченном доступе подключение с любого другого адреса должно обрываться.
Шаг 5: добавьте первый монитор
- Нажмите Add New Monitor.
- В поле Monitor Type выберите HTTP(s).
- Заполните Friendly Name, затем укажите отслеживаемый адрес в поле URL, например
https://www.ваш-домен.com. - Настройте Heartbeat Interval (интервал между двумя проверками) и Retries (число повторных попыток перед оповещением).
- Включите Certificate Expiry Notification, чтобы получать предупреждение до истечения срока действия сертификата.
- Нажмите Save.
Наиболее полезные типы мониторов:
| Тип | Назначение |
|---|---|
| HTTP(s) | Сайт или API с проверкой кода ответа |
| HTTP(s) - Keyword | Наличие слова на странице |
| TCP Port | Служба, слушающая порт, например SSH или база данных |
| Ping | Сетевой отклик машины |
| DNS | Разрешение доменного имени |
| Push | Запланированная задача, которая сама сообщает о своём выполнении |
Мониторинг запланированной задачи
Создайте монитор Push и скопируйте его Push URL. Вызывайте его в конце своего скрипта и только в случае успешного выполнения:
/usr/local/bin/my-backup.sh && curl -fsS -m 10 --retry 3 "https://uptime.ваш-домен.com/api/push/ВАШ_ТОКЕН?status=up&msg=OK"Замените ВАШ_ТОКЕН значением из вашего URL. Если в течение заданного времени сигнал не поступит, монитор перейдёт в состояние DOWN. Считайте этот URL секретом.
Шаг 6: настройте уведомления
Откройте Settings > Notifications и нажмите Set Up Notification. Uptime Kuma поддерживает множество служб. В следующем примере используется Telegram:
- В Telegram напишите @BotFather, отправьте
/newbotи скопируйте полученный токен. - Отправьте сообщение своему новому боту.
- В Uptime Kuma выберите Telegram в поле Notification Type.
- Вставьте токен в поле Bot Token.
- Нажмите Auto Get, чтобы заполнить Chat ID.
- Включите Default enabled, чтобы применять уведомление к будущим мониторам, и Apply on all existing monitors для уже существующих.
- Нажмите Test. Если сообщение пришло, нажмите Save.
Для электронной почты выберите Email (SMTP) и укажите параметры, предоставленные вашей почтовой службой, желательно с отдельной учётной записью.
Уведомление работает, только если оно привязано к монитору. Проверьте это в столбце Notifications на странице каждого монитора.
Создание страницы статуса
В разделе Status Pages нажмите New Status Page, выберите имя и адрес, затем добавьте мониторы, которые нужно показывать. Страница станет доступна по адресу /status/vybrannoe-imya. Она рассчитана на публичный доступ, а её данные кэшируются на 5 минут.
При ограниченном доступе из шага 4 она будет видна только с вашего адреса. Чтобы сделать её публичной, используйте второй блок Caddy.
Обновление Uptime Kuma
Сначала сделайте резервную копию каталога data и прочитайте примечания к выпуску. Затем замените тег в compose.yaml и выполните:
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose psОставайтесь на ветке 2, пока не прочитаете руководство по переходу на версию 3. Этот переход изменяет базу данных, и вернуться назад без резервной копии невозможно.
Резервное копирование и восстановление
Резервировать нужно только каталог data и файл compose.yaml. Это способ, поддерживаемый проектом: прежний экспорт в JSON был удалён в версии 2.
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gzАрхив содержит базу данных, учётные записи и токены уведомлений. Скопируйте его за пределы сервера в зашифрованное хранилище.
Чтобы восстановить архив, подставьте вместо ГГГГ-ММ-ДД его дату:
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.old-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-ГГГГ-ММ-ДД.tar.gz
docker compose up -dИспользуйте ту же версию образа, что и при создании резервной копии, или более новую версию той же ветки.
Если что-то пошло не так
Cannot connect to the socket server
Интерфейсу не удаётся установить соединение WebSocket. Убедитесь, что контейнер работает, и просмотрите его журналы:
docker compose ps
docker compose logs --tail=50 uptime-kumaЕсли перед Caddy стоит другой прокси, например Cloudflare, убедитесь, что в нём включены WebSocket и что исходное доменное имя передаётся правильно.
Ошибка 502 при работе с Caddy
Caddy не может подключиться к приложению. Проверьте локальный порт:
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50Монитор показывает DOWN, хотя служба отвечает
Проверка выполняется из контейнера, сеть которого отличается от сети вашего компьютера. Выполните проверку из контейнера, подставив нужный адрес:
docker exec uptime-kuma node -e "fetch('https://www.ваш-домен.com').then(r => console.log(r.status)).catch(console.error)"Убедитесь также, что отслеживаемая служба не блокирует адрес сервера, например брандмауэром или CrowdSec.
Ошибка монитора IPv6
По умолчанию сеть Docker контейнера не использует IPv6. Если служба доступна только по IPv6, добавьте в compose.yaml сеть с IPv6:
services:
uptime-kuma:
networks:
- uptime-kuma-net
networks:
uptime-kuma-net:
enable_ipv6: trueОбъедините эти ключи с существующей службой, затем снова выполните docker compose up -d.
Сигналы Push не приходят
Проверьте URL командой curl -i с машины, на которой выполняется задача. Оборванное соединение обычно означает, что в Caddy отсутствует блок @push. Ответ должен содержать "ok":true.
Уведомления не приходят
Нажмите кнопку Test и прочитайте сообщение об ошибке. Затем убедитесь, что уведомление включено для монитора. При отправке через SMTP уточните хост, порт и имя пользователя у вашей почтовой службы.
Утерян пароль или нет доступа к двухфакторной аутентификации
Выполните подходящую команду и следуйте выведенным инструкциям:
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fadatabase is locked или повреждённая база данных
Убедитесь, что data находится на локальном диске, а не на NFS, и с помощью df -h проверьте, что на диске достаточно места. Если база данных повреждена, восстановите последнюю резервную копию.
port is already allocated
Порт 3001 занят другой службой. Определите её командой sudo ss -ltnp | grep ':3001 '. Чтобы сменить порт, измените только левую часть, например 127.0.0.1:3002:3001, а затем обновите конфигурацию Caddy.