Logs Killu
Версия 1Версия 2 · последняя

Все логи.
Один кабинет.

Серверы, архивы и уведомления в Telegram. Разверните у себя — данные останутся у вас.

Скачать комплект ↓
Приватный S3Без DockerМобильный интерфейс
Logs Killu · демо↗
Демонстрационный кабинет: график архивов и состояние серверов
Открыть кабинет →

От сервера до первого архива

Четыре шага. Всё необходимое — в комплекте.

Полная инструкция ↓
  1. Подготовьте VPS и S3

    Чистый Debian 12/13 или Ubuntu 24.04, свой домен и приватный бакет. Для начала — 2 ГБ RAM. Selectel подходит как пример.

    Как настроить хранилище →
  2. Установите коллектор

    Загрузите комплект и контрольную сумму на VPS. Выполните в каталоге загрузки:

    sha256sum -c SHA256SUMS
    tar -xzf log-atlas-starter.tar.gz
    cd log-atlas-starter
    sudo bash install-collector.sh

    Установщик спросит ваш домен, S3-ключи и пароль. Нужны открытые TCP 80 и выбранный HTTPS-порт.

  3. Добавьте сервер в кабинете

    Укажите имя и IP, скопируйте готовую команду и выполните её на ноде. Коллектор и токен уже заполнены. В окне появятся статусы связи и первого архива.

  4. Проверьте архив и Telegram

    Отправьте тестовый архив, скачайте его обратно и сравните SHA-256. Подключите своего бота, задайте пороги и нажмите «Отправить тест».

Серверы, бот и архивы

Попробовать кабинет →

Если нужны подробности

Настройка, ограничения и восстановление.

Хранилище Selectel

В своём проекте Selectel создайте приватный бакет, сервисного пользователя и S3-ключ. Доступ определяется сочетанием роли пользователя и политики бакета. Убедитесь, что разрешены операции записи/чтения объектов и multipart для этого бакета; общий доступ на все ваши проекты не нужен.

Пример параметров, которые заменяются вашими:

S3_ENDPOINT=https://s3.ru-1.storage.selcloud.ru
S3_REGION=ru-1
S3_BUCKET=example-private-log-archive
S3_ACCESS_KEY_ID=REPLACE_WITH_YOUR_ACCESS_KEY
S3_SECRET_ACCESS_KEY=REPLACE_WITH_YOUR_SECRET_KEY

ru-1 — пример пула. Правильный endpoint и регион возьмите из своего проекта. Стартовый комплект использует подпись S3v4 и path-style; при другой настройке бакета задайте S3_ADDRESSING_STYLE=virtual в защищённом runtime.env и проверьте доступ. Не делайте бакет публичным и не добавляйте браузерный CORS ради работы кабинета: браузер обращается к коллектору.

Класс хранения выбирайте по частоте чтения, стоимости запросов, трафика и минимальному сроку хранения. «Холодный» не всегда дешевле для часто читаемых данных. Lifecycle-удаление по умолчанию не включайте.

Официальные источники: S3 API Selectel, доступ к S3, endpoint и ключи после обновления.

Ротация и подключение рабочих логов

Повторите добавление в интерфейсе для каждого своего сервера. Не копируйте один токен на все ноды. Укажите уже существующий каталог закрытых, неизменяемых .gz, .zst или .zip архивов. Имя файла: латиница, цифры, точки, дефисы и подчёркивания; до 160 символов.

Агент просматривает только верхний уровень каталога, пропускает символические ссылки, принимает файлы старше минуты, от 1 байта до 512 МиБ. Он отправляет не более десяти файлов за цикл, хранит локальные квитанции, но никогда не удаляет оригиналы. Пустые, большие или изменившиеся файлы требуют внимания. Для большого потока запланируйте размер ротации и ёмкость диска.

Агент не включает логи в приложении, не монтирует Docker volumes и не меняет logrotate. Если приложение пишет только внутрь контейнера, сначала настройте экспорт по документации приложения в согласованное окно. Не вставляйте универсальную команду пересоздания контейнера на рабочем сервере.

Ротацию настраивайте отдельно: предпочтительно rename + поддерживаемое приложением reopen, затем сжатие завершённого файла. copytruncate имеет окно потери/дублирования и не гарантирует целостность потока. Нельзя считать активный access.log готовым архивом. Даже с выключенным удалением в агенте системный logrotate может удалять старые файлы по своей политике — согласуйте её с очередью и доступным местом.

Если отключить источник в кабинете, токен перестанет приниматься, история останется. Чтобы окончательно остановить локальные запросы, на сервере выполните systemctl disable --now log-atlas-agent.timer. Отключение в кабинете не выключает и не отменяет аренду VPS.

Подключение Telegram
  1. Создайте отдельного бота через @BotFather. Отправьте своему боту /start.
  2. Узнайте числовой Chat ID из обновлений своего бота методом getUpdates. Не передавайте токен сторонним ботам. Для группы добавьте туда своего бота, отправьте ему команду и возьмите message.chat.id из ответа.
  3. В Уведомления → Telegram сохраните токен и Chat ID. Пустое поле токена при следующем сохранении сохраняет прежний ключ.
  4. Нажмите Отправить тест. Успех означает подтверждение Telegram, а не только сохранённую настройку. Ошибка показывается в кабинете и журнале.
  5. Установите пороги и включите переключатель. По умолчанию: нет отчёта 15 минут, очередь больше 1 ГиБ, свободно меньше 2 ГиБ. Ошибки отправки можно включать отдельно.

Коллектор проверяет состояние раз в минуту. Новое состояние вызывает одно сообщение; неизменное не повторяется. Восстановление вызывает отдельное сообщение. При сбое отправки повтор идёт с увеличением интервала до 15 минут. Доставка может повториться при сбое процесса после ответа Telegram, но до записи квитанции: это не гарантия exactly-once. Не больше десяти успешных уведомлений за один цикл. Отключённые источники пропускаются.

Новый источник получает время на установку агента, равное порогу отсутствия связи. Старый отчёт не используется для вывода о текущей очереди или диске. Сам коллектор не способен сообщить о собственном полном отключении — для этого нужен внешний мониторинг.

Токен хранится в /var/lib/log-atlas/telegram.json с правами 0600 и не возвращается через API. Включите файл в защищённый бэкап. Удалить подключение удаляет токен и выключает отправку. В публичном демо поля секретов отключены и сообщения не отправляются.

Подключение логов бота

В разделе Бот → Подключить бота создайте источник типа «Бот». Укажите каталог закрытых логов в archive_dir и, при необходимости, отдельный каталог готовых резервных копий в backup_dir. Агент отправит файлы с разными типами. Каталоги должны существовать; активные файлы и символические ссылки не принимаются.

{
  "collector": "https://logs.example.com",
  "token": "REPLACE_WITH_YOUR_SOURCE_TOKEN",
  "archive_dir": "/var/spool/example-bot/logs",
  "backup_dir": "/var/backups/example-bot"
}

Источник хранит тот же ID и токен при правке IP. В разделе бота есть фильтр источника, вкладки логов и резервных копий, дата последней копии и скачивание. Для gzip-логов доступен просмотр начала файла: до 128 КиБ распакованного текста при чтении не более 1 МиБ сжатых данных. Резервные копии и zstd/zip доступны только для скачивания.

Комплект не создаёт дампы БД, не перезапускает бота и не перенастраивает его logger. Подготовьте закрытые журналы и согласованные резервные копии штатными средствами своего приложения. Активную SQLite-базу нельзя просто gzip-ить: используйте SQLite Backup API; для других БД — их средства резервного копирования. Успешная загрузка копии не заменяет проверку восстановления.

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

Диагностика проблем
Симптом Что проверить
Домен не открывается / нет сертификата A/AAAA, публичный DNS, порты 80 и HTTPS, журнал Caddy, отсутствие лишнего проксирования нестандартного порта
502 log-atlas.service, loopback 8787, runtime.env, права каталога состояния
403 на входе Точное совпадение PUBLIC_ORIGIN со схемой, доменом и портом в браузере
429 при входе Лимит восемь попыток за 15 минут; за reverse proxy в комплекте он общий, поскольку клиентом приложения является Caddy
Источник ждёт агента Токен, DNS, HTTPS, путь конфигурации, запуск таймера; пустой каталог всё равно должен дать heartbeat
401 у агента Источник отключён или токен был заменён; скачайте новую конфигурацию при смене
413 Размер отдельного архива превышает 512 МиБ или лимит reverse proxy
422 Имя/расширение файла, изменившийся архив, неверный SHA-256 или Content-Length
503 при отправке S3 endpoint/ключи/права, сеть, журнал; квитанция не создаётся, файл остаётся для повтора
507 Коллектору не хватает временного места: нужен размер архива плюс резерв 1 ГиБ; проверьте диск, не удаляйте неподтверждённые данные
Очередь растёт Скорость сети/диска/S3, лимиты цикла, размер и частота ротации; не скрывайте это зелёным статусом

Для диагностики не публикуйте токены, runtime.env, содержимое приватных логов и подписанные S3-ссылки. Настройте своего Telegram-бота в разделе уведомлений и проверьте тестовую доставку.

Бэкапы и замена коллектора
Где Путь
Код коллектора /opt/log-atlas
Настройки и секреты /etc/log-atlas/runtime.env, root-only 0600; /var/lib/log-atlas/telegram.json, 0600
Каталог /var/lib/log-atlas/catalogue.sqlite и WAL/SHM
Агент /usr/local/sbin/log-atlas-agent.py
Конфигурация агента /etc/log-atlas-agent/config.json, root-only 0600
Квитанции агента /var/lib/log-atlas-agent
HTTPS /etc/caddy/Caddyfile

Каталог и runtime.env нужны для восстановления, S3 хранит сами архивы. SQLite копируйте через backup API или при остановленном сервисе; не копируйте только основной файл при активном WAL. Пример согласованной копии:

sudo install -d -m 700 /root/log-atlas-backup
sudo python3 - <<'PY'
import os, sqlite3
os.umask(0o077)
src=sqlite3.connect('/var/lib/log-atlas/catalogue.sqlite')
dst=sqlite3.connect('/root/log-atlas-backup/catalogue.sqlite')
with dst: src.backup(dst)
dst.close(); src.close()
PY
sudo cp -a /etc/log-atlas /root/log-atlas-backup/config
# Если Telegram настроен:
sudo test ! -f /var/lib/log-atlas/telegram.json || sudo cp -a /var/lib/log-atlas/telegram.json /root/log-atlas-backup/

Сохраните защищённую копию вне VPS и проверьте восстановление в отдельном окружении. В стартовом комплекте нет автоматического расписания бэкапов: настройте своё. Копия файлов и успешная загрузка не равны проверенному восстановлению.

При переносе подготовьте новый VPS и тот же бакет, сохраните базу, telegram.json, токены, session secret и домен. Для финальной копии остановите запись на старом коллекторе, перенесите согласованное состояние, переключите DNS/прокси и запустите единственного писателя. Агенты повторят отправки после восстановления связи. При том же домене их URL менять не нужно. S3-архив не требуется копировать ради замены VPS. До завершения проверки сохраняйте старый сервер для отката; не допускайте двух независимых писателей и отката базы поверх новых записей.

Обновление и индикатор диска

Агент1.2 передаёт свободное и полное место файловой системы archive_dir. Индикатор показывает округлённую долю занятого места: менее70% — зелёный, 70–89% — оранжевый, от90% — красный. Если отчёт старше15минут, размера диска нет или он некорректен, цветной индикатор отсутствует. У старых агентов может быть только свободное место; для процента обновите агент. Если копии лежат на другом диске, этот индикатор его не измеряет.

Перед обновлением сделайте согласованную копию базы и настроек. Замените app.py и static, перезапустите сервис по своему плану обслуживания; новые колонки источников и объектов добавятся автоматически. Старые источники получат тип «Сервер», объекты — «Лог». Для бота выберите тип в карточке. Обновите agent.py на своих источниках; рабочие config.json и квитанции сохраняйте.

Возможности и ограничения

Проверены API на тестовом S3-эмуляторе: авторизация, CSRF, создание источника, heartbeat, загрузка/чтение/дедупликация, отказ S3, смена токена, отключение, редактирование IP, Telegram-дедупликация, восстановление и повтор доставки после сбоя; два каталога агента, фильтры логов/копий, ограниченный предпросмотр gzip и полнота данных диска. Интерфейс проверяется в браузере на компьютере и телефоне. Синтаксис установщиков и Python проверен.

Этот выпуск не проверялся с вашим Selectel-проектом и не является гарантией производительности. Чистая установка на всех перечисленных ОС и аварийное восстановление всей системы не сертифицированы. Установщик выполняет S3-проверку уже с вашими реквизитами; обязательно пройдите тест первого архива до подключения рабочей нагрузки. Версии Python-пакетов закреплены в requirements.txt; обновляйте их отдельно с тестами. TLS и размещение секретов включены, но это не независимый аудит безопасности.

Ежедневные отчёты и старый S3

Heartbeat подтверждает связь с агентом. Успешный сбор проверяйте по последнему архиву.

В «Уведомлениях» включите ежедневную сводку, выберите час и часовой пояс. По умолчанию: 09:00 по Москве, данные за вчера. «Отправить тест» проверяет доставку, «Отчёт сейчас» отправляет сводку без повторов за один день.

Старый формат YYYY/MM/DD/source__IP автоматически индексируется каждые пять минут. Другие форматы требуют адаптера. Объекты S3 сохраняются.

Для обновления с резервной копией замените app.py, maintenance.py и static/. Подробная инструкция.