Обслуживание¶

Часть работы делается в панели (разделы Обслуживание и Инструменты, только админ), часть - командой trafmate на сервере. Команда ставится установщиком в /usr/local/bin/trafmate и работает с каталогом /opt/trafmate.

В панели¶

Диагностика¶

Раздел Обслуживание -> Диагностика. Первой строкой - самодиагностика: агент проверяет установку раз в минуту, панель показывает итог («Всё в порядке» / «Есть замечания» / «Требует внимания») и перечень замечаний. Если агента на сервере нет, проверить вручную - trafmate monitor.

Что проверяется: подняты ли все контейнеры, заполненность диска (предупреждение с 80%, тревога с 90%), отставание очередей, возраст последнего бэкапа и то, уезжает ли он с машины, состояние лицензии.

Ниже на той же странице: статус сервисов (PostgreSQL / ClickHouse / Redis), очереди (необработано / всего в потоке), ресурсы сервера (память, диск, загрузка CPU, аптайм) и данные (размер БД, объём ClickHouse, память Redis, число кликов, активных кампаний и доменов).

Очистка статистики¶

Раздел Обслуживание -> Очистка статистики. Сверху - сколько места занимает каждая таблица.

Срок хранения - «Хранить статистику N дней». Применение выставляет TTL на таблицы статистики, дальше ClickHouse удаляет устаревшее сам.
Очистка партиций - удалить данные старше выбранной даты. Сначала обязательный предпросмотр (сколько строк и сколько места удалится и в каких партициях), потом подтверждение.

Архив¶

Раздел Обслуживание -> Архив. Удаление в трекере не окончательное: кампании, потоки, лендинги, офферы, источники трафика, партнёрские сети и пользователи после удаления попадают в архив.

Что это значит на практике:

Из раздачи трафика удалённое выпадает сразу - движок читает только активные сущности, ждать ничего не нужно.
Из списков оно пропадает, но лежит в архиве и восстанавливается кнопкой «Восстановить». Возвращается в состоянии «активна» - если нужно поднять её позже, остановите переключателем.
Файлы лендингов и офферов при удалении не трогаются. Иначе восстановленный лендинг оказался бы пустой папкой, то есть восстановление было бы обманом. Файлы сносит только окончательная чистка.
Срок хранения - 90 дней (настройка archive_ttl). Столбец «Срок вышел» показывает, сколько записей уже пережило срок и уйдёт ближайшей чисткой.
Окончательная чистка - кнопка «Очистить архив». Удаляет пережившее срок вместе с файлами; после неё восстановить нечем.

Домены в архив НЕ попадают: имя домена уникально, и архивная запись не дала бы завести его заново - «удалил» перестало бы работать.

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

Гео-базы¶

Раздел Обслуживание -> Гео-базы. Страна, регион, город и провайдер определяются локальными базами в формате .mmdb. Устаревшая база - это неверное гео во всей статистике и в гео-фильтрах потоков, поэтому раздел первым делом показывает возраст каждой базы: «устарела на 400 дней» видно сразу, дата обновления - нет.

Две базы:

База городов (City) - страна, регион, город;
База провайдеров (ASN) - провайдер и признак «трафик из дата-центра», по которому работает детект ботов.

Обновление: скачайте свежий .mmdb (GeoLite2 от MaxMind или бесплатная DB-IP lite) и загрузите в разделе. Файл применяется без перезапуска - приём трафика не прерывается.

Две защиты, о которых стоит знать:

формат проверяется до подмены рабочего файла. MaxMind при неверном ключе отдаёт не базу, а html-страницу с ошибкой; без проверки она заменила бы рабочую базу, и трекер остался бы без гео;
не открылась - остаёмся на прежней. Если новый файл битый или недокачан, движок сообщает причину, а гео продолжает работать на старой базе.

Обновлять раз в месяц-два достаточно.

Журнал действий¶

Раздел Обслуживание -> Журнал действий: все мутации в панели. По каждой записи - время, пользователь, действие (Создание / Изменение / Удаление), объект (раздел и ID), IP-адрес, клиент (браузер или инструмент из User-Agent) и код ответа.

Журнал фильтруется по разделу и действию (выпадающие списки над таблицей). Хранится 30 дней (настройка audit_log_ttl), дальше старые записи удаляются сами.

Тело запроса намеренно не сохраняется: через те же мутации проходят пароли, ключи постбека и токены интеграций, а журнал доступен любому администратору и попадает в резервную копию. IP, клиент и код ответа для разбора «кто и когда это сделал» достаточно, а секретов не содержат.

Гео-профили¶

Готовые наборы стран для быстрой настройки фильтров (USA+CA, Зап. Европа, English, exUSSR, Español и т.д.). Используются в фильтре «Страна».

IP-доступ в админку¶

Раздел Инструменты -> IP-доступ: белый список адресов. Включается настройкой «Доступ к админке по IP». Пустой список = доступ всем (защита от самоблокировки).

Триггеры¶

Раздел Инструменты -> Триггеры: правило условие -> действие. Исполнитель раз в 5 минут считает метрики кампаний за окно (клики, конверсии, доход, расход, ROI) и при выполнении условия применяет действие (например pause_campaign - поставить кампанию на паузу).

Метки, метрики, интеграции¶

Метки - произвольные ярлыки с цветом, привязываются к кампаниям (чипы в карточке).
Метрики отчётов - пользовательские формулы (см. «Отчёты»).
Вебхуки - отправка события (например conversion) POST-запросом с JSON на ваш URL.
Facebook CAPI - отправка конверсий в пиксель Meta серверным запросом. Описание - в разделе «Конверсии и постбеки».

Обновление¶

Обновляется командой на сервере:

trafmate update           # до текущей стабильной версии
trafmate update 1.4.2     # конкретная версия, в том числе откат назад
trafmate version          # что установлено и что есть в канале

Что делает trafmate update по шагам: узнаёт стабильную версию из канала обновлений, снимает дамп конфигурации (страховка), обновляет саму команду trafmate, тянет образы новой версии, применяет миграции, проверяет потолки ресурсов и перезапускает сервисы. Порядок важен: миграции идут до подъёма сервисов, иначе новый воркер писал бы в колонки, которых ещё нет.

Если канал недоступен, обновление не срывается - идёт по уже прописанной версии. Если образы не скачались, версия в конфигурации откатывается обратно.

Рядом с обновлением:

trafmate status              # что запущено
trafmate logs [сервис...]    # логи, Ctrl+C - выход
trafmate restart [сервис...] # перезапуск
trafmate start | stop | down # поднять / остановить / снять контейнеры (данные целы)

Обновление из панели¶

Настройки -> Обновления: текущая версия, состояние и две кнопки - «Проверить обновления» и «Обновить». Перед обновлением снимается дамп БД, панель может ненадолго стать недоступной. Пока идёт проверка или установка, кнопки заблокированы, а состояние обновляется само.

Если на сервере не настроен агент обслуживания, обе кнопки заблокированы с подсказкой обновляться командой trafmate update.

Бэкапы¶

Главное правило: бэкап на том же сервере бэкапом не является. Копия обязана уезжать за пределы машины - иначе она уйдёт вместе с сервером.

Снять и посмотреть¶

trafmate backup          # полный архив: один файл .tar.gz
trafmate backup-config   # быстрый дамп конфигурации (снимается сам перед обновлением)
trafmate backups list    # что есть: архив, размер, версия, кликов, дата

В полный архив попадает всё, что нужно, чтобы поднять установку с нуля: конфигурация Postgres (кампании, потоки, домены, офферы, лендинги, пользователи, настройки), вся статистика ClickHouse, файлы лендингов, снимок Redis (без него конверсии по старым кликам не привязать), буфер отложенных постбеков, .env с секретами установки и сертификаты Caddy. Архив кладётся в /opt/trafmate/backups правами 600 - внутри секреты и приватные ключи.

Статистика выгружается посуточно и при отказе повторяется до пяти раз: на сервере с 3-4 ГБ ОЗУ ClickHouse упирается в общий лимит памяти и месячную партицию не отдаёт вовсе. Поэтому полный бэкап на большой истории идёт долго - это нормально.

Расписание и выгрузка наружу¶

Суточный бэкап включается установщиком по умолчанию: ежедневно в 03:20 (со случайным разбросом до получаса), после бэкапа сразу чистятся старые. Управление:

trafmate backups schedule status     # включено ли, когда был последний, уезжает ли наружу
sudo trafmate backups schedule on          # включить (03:20)
sudo trafmate backups schedule on 02:00    # своё время
sudo trafmate backups schedule off         # выключить

Выгрузка за пределы сервера настраивается в /opt/trafmate/.env и по умолчанию выключена - об этом предупреждает и самодиагностика. Два варианта:

# 1) по SSH-ключу
BACKUP_REMOTE=user@backup-host:/путь
BACKUP_REMOTE_KEY=/root/.ssh/id_ed25519     # необязательно

# 2) своя команда: путь к архиву приходит в $1
BACKUP_UPLOAD_CMD=rclone copy "$1" remote:путь

Второй вариант - это и S3 (aws s3 cp "$1" s3://bucket/), и rsync, и что угодно ещё. Уезжает и сам архив, и его манифест. Разово выгрузить уже снятый архив: trafmate backups upload [файл].

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

Проверка бэкапа¶

trafmate backups verify [файл]     # по умолчанию - самый свежий

Проверяет не разворачивая: открывается ли архив, сходятся ли контрольные суммы, на месте ли все суточные куски статистики (по манифесту), сколько в дампе кампаний, офферов, лендингов, потоков и доменов, есть ли лендинги, .env, сертификаты и снимок Redis.

Итог однозначный: «Бэкап пригоден к восстановлению» либо «Бэкап НЕПОЛНЫЙ или повреждён - на него полагаться нельзя». Отсутствие снимка Redis - ошибка, отсутствие сертификатов - предупреждение.

Чистка старых¶

trafmate backups prune          # только показать, что удалилось бы
trafmate backups prune --yes    # применить

По умолчанию хранятся 3 последних полных архива и 10 дампов конфигурации (меняется переменными BACKUP_KEEP_FULL и BACKUP_KEEP_CONFIG в .env). Самый свежий не удаляется никогда.

Восстановление¶

trafmate restore <файл>                  # показать план, ничего не делать
trafmate restore <файл> --yes            # выполнить
trafmate restore <файл> --yes --force    # затереть непустые таблицы статистики
trafmate restore <файл> --yes --no-start # не поднимать сервисы (переезд до переключения DNS)

Порядок такой: проверка архива -> страховочная копия текущего состояния -> остановка admin/traffic/worker -> пересоздание схемы Postgres и загрузка конфигурации -> миграции -> загрузка статистики -> запуск сервисов.

Что важно знать:

Битый архив останавливает всё до того, как что-то тронуто: не читается, нет манифеста или не сошлись контрольные суммы - выход.
Ошибки при загрузке видны. Загрузка идёт с остановкой на первой ошибке, вывод сохраняется, а после загрузки число строк в базе построчно сверяется с дампом. При несовпадении команда падает и оставляет данные как есть - «разбирайтесь до запуска трафика». Раньше вывод глушился, и восстановление рапортовало об успехе на половине базы.
Страховочная копия обязательна. Если снять её не удалось, восстановление отменяется; осознанно пропустить - --no-snapshot (уместно только на пустом приёмнике).
Статистика не затирается молча: если в таблице уже есть строки, кусок пропускается, пока не передан --force.
.env не подменяется. Секреты донора кладутся рядом в .env.from-backup - оттуда можно перенести JWT_SECRET, если нужно, чтобы продолжили работать ссылки на лендинги и выданные до переезда сессии.
После восстановления вход в панель - по учётным записям из бэкапа; пароль, выданный установщиком, больше не подходит.

Сертификаты удалённых доменов¶

Удаление домена в панели снимает и его сертификат: панель ставит задачу агенту обслуживания, тот удаляет каталог сертификата и перезапускает Caddy. Перезапуск здесь не формальность - пока сертификат жив в памяти процесса, удалённый домен продолжает обслуживаться.

Отдельно то же самое чистится суточным таймером (04:40) и руками:

trafmate certificates list          # что лежит, с пометкой «ЛИШНИЙ - домена в базе нет»
trafmate certificates prune         # только показать
trafmate certificates prune --yes   # удалить и перезапустить Caddy

Домен самой установки и имена из Caddyfile не трогаются никогда. Если Postgres не отвечает, уборка отменяется целиком - иначе снесло бы все сертификаты разом.

Если бы этого не делалось, удалённый домен продолжал бы терминировать TLS на вашем IP до истечения сертификата (около 90 дней).

Сброс пароля владельца¶

Если доступ в панель потерян:

trafmate reset-password                                  # логин из .env, пароль сгенерируется
trafmate reset-password owner
trafmate reset-password owner --password 'Секрет123'

Пароль показывается один раз - сохраните его. Существующему пользователю меняется только пароль, учётная запись разблокируется, роль не меняется; если такого логина нет, он создаётся с ролью админа. Все старые сессии при этом гасятся. Минимальная длина пароля - 8 символов.

Доступ поддержки¶

Временный SSH-доступ для поддержки TrafMate, с автозакрытием:

sudo trafmate support-access on        # на 4 часа
sudo trafmate support-access on 8      # на 8 часов (потолок - 24)
sudo trafmate support-access off       # закрыть досрочно
trafmate support-access                # статус

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

Ресурсы: логи и память ClickHouse¶

Обе настройки применяются сами и на новых установках, и на старых - при каждом trafmate update.

Логи контейнеров ротируются: 10 МБ на файл, 3 файла, то есть не больше 30 МБ на сервис. Без этого лог одного сервиса за месяц занимал диск целиком.
ClickHouse ограничен по памяти: серверный потолок - 60% ОЗУ вместо стандартных 90%, кэш меток урезан, число одновременных запросов - 32; на один запрос - 1 ГБ, с уходом на диск при нехватке вместо падения. На машине 3-4 ГБ стандартные настройки роняли и вставку кликов, и выгрузку бэкапа.

Если в каталоге установки уже лежит ваш собственный docker-compose.override.yml, команда его не трогает и говорит об этом - потолки в этом случае нужно перенести руками.

Перенос данных из Keitaro¶

Скрипт deploy/migrate/migrate.py переносит конфигурацию и историю кликов/конверсий с сохранением идентификаторов. Нумерация типов конверсий у нас совпадает с Keitaro, поэтому привезённые статусы не меняют смысл.

Системный лог¶

Раздел Обслуживание -> Диагностика, карточка «Системный лог». Отвечает на вопрос «что вообще происходило на сервере», не заходя на него по ssh:

обновления - когда и на какую версию, и отдельно случай «раскладку сервисов не обновили, потому что docker-compose.yml правили руками»;
бэкапы и восстановления - когда снимался архив, какого размера, когда разворачивался;
гео-базы - когда заменялись и применились ли без перезапуска;
домены - когда домен перестал отвечать и когда снова начал;
очистка статистики и срок хранения - удаление необратимо, и спрашивают об этом уже после того, как данные пропали.

Домены пишутся переходами, а не каждой проверкой: здоровый домен проверяется раз в 6 часов, сломанный - раз в 30 минут, и запись каждого результата залила бы лог одним и тем же фактом.

Переключатель «Только проблемы» оставляет строки с уровнем «Внимание» и «Ошибка» - обычный день состоит из штатных событий, а вопрос задают про необычный.

Это не лог сервисов: вывод контейнеров сюда не попадает, он растёт мегабайтами в час и нужен для другого. И это не «Журнал действий»: там - что делали пользователи панели, здесь - что делала система.

Канал обновлений: stable и beta¶

trafmate channel            # какой канал сейчас и какая в нём версия
trafmate channel beta       # получать свежие версии раньше остальных
trafmate channel stable     # вернуться к проверенным (по умолчанию)

stable - версия, прошедшая полную проверку: релиз ставится на чистую машину с нуля, на ней прогоняется сквозной тест, и только после этого канал переводится. Это умолчание, и менять его не нужно.
beta - та же сборка, но канал переводится до этой проверки. Нужен, чтобы обкатать релиз на настоящей установке с настоящим трафиком. Берите его, только если готовы поймать дефект первым.

Смена канала сама ничего не обновляет - это отдельное решение. Обновиться: trafmate update. Вернуться на конкретную версию можно всегда: trafmate update 1.1.28.

Сколько памяти занимает трекер¶

Основной потребитель памяти под трафиком - Redis, и занимает её индекс кликов для постбеков: по нему конверсия находит свой клик. Один клик - около 450 байт, срок хранения задаётся настройкой «Хранить клик для постбека, дней» (по умолчанию 90).

Кликов в месяц	Память при 90 днях	При 30 днях
100 тыс	~135 МБ	~45 МБ
1 млн	~1.35 ГБ	~450 МБ
5 млн	~6.7 ГБ	~2.2 ГБ

Если сервер небольшой (3-4 ГБ ОЗУ), а трафика много - уменьшайте срок. Цена решения понятная: постбек, пришедший позже срока, будет отклонён как «клик не найден», то есть поздняя конверсия не запишется. Спросите у партнёрской сети, с какой задержкой она подтверждает конверсии, и берите срок с запасом.

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