Описание агента
Инструкции по настройке TI Feeds Agent
- Агент Solar TI Feeds представляет собой программное обеспечение для интеграции с облаком TI Feeds, предназначенное для автоматизации получения различных фидов и их доставки конечному потребителю в различных форматах
- Решение представлено в виде Docker-образа, что обеспечивает простоту развертывания и масштабируемость
- Агент самостоятельно выполняет запросы к серверу, аутентифицируется и выгружает необходимые данные
Функциональные особенности агента
- Возможность настройки работы агента при помощи конфигурационного файла
- Встроенный планировщик, позволяющий настраивать расписание загрузки фидов
- Трансформация и фильтрация полученных данных
- Поддержка различных форматов вывода данных (CSV, TXT, Kafka)
- Возможность интеграций с СЗИ
- Возможность настройки способа получения данных:
- Полная выгрузка всех данных при каждой загрузке
- Загрузка только изменений с предыдущего обновления для экономии ресурсов и оперативного получения новых фидов
Подготовка к установке
Перед началом установки убедитесь, что выполнены следующие требования:
1. Программное обеспечение
- Операционная система: Unix-подобная ОС (Linux или macOS)
- Контейнеризация:
- Docker версии 22 или выше
- Docker Compose версии 2
- Архив с агентом: Скачайте установочный пакет
2. Аппаратные требования (при развертывании на виртуальной машине)
Если вы планируете развернуть агент на виртуальной машине, обеспечьте следующие минимальные характеристики:
- Процессор: 2-4 vCPU
- Оперативная память: 8 ГБ vRAM
- Диск: 50 ГБ HDD
Распаковка архива
- Откройте терминал и перейдите в директорию, где находится архив
- Создайте директорию для агента, выполнив команду:
mkdir -p agent - Распакуйте архив, выполнив команду:
tar -xvf latest.tar.gz -C agent - Перейдите в распакованную директорию:
cd agent
Описание установочных файлов
Установочный комплект включает в себя Docker-образ контейнера и конфигурационные файлы, с помощью которых можно настраивать агента без внесения изменений в программный код:
| Файл | Назначение |
|---|---|
4rays_tic_agent.tar | Docker-образ агента Solar TI Feeds |
docker-compose.yml | Готовый файл оркестрации для запуска контейнера с предопределёнными переменными окружения и монтированием томов |
ReadMe.txt | Краткая инструкция по быстрому запуску и базовой настройке агента |
pkl/internal/agent.pkl | Базовая конфигурация агента описывающая все доступные структуру, типы данных, компоненты (генераторы, трансформеры, sink'и) и возможные значения параметров |
pkl/internal/templates.pkl | Шаблоны конфигурации содержащие предопределённые настройки серверов, расписаний, логирования и метрик для переиспользования в pipeline |
pkl/configs/{PIPELINE_NAME}.pkl | Файлы конфигурации pipeline, определяющие логику обработки данных и параметры запуска агента. Имя файла соответствует названию СЗИ, с которой выполняется интеграция (например, cybertrace_pipeline.pkl) |
Загрузка Docker-образа
Для загрузки Docker-образа выполните следующую команду:
docker load -i "4rays_tic_agent.tar"
Проверка загрузки
Чтобы убедиться, что Docker-образ успешно запустился выполните команду:
docker image list
В выводе должен присутствовать контейнер 4rays/tic/agent с актуальной версией. Если в консоли появилась информация о контейнере соответствующей версии, значит контейнер с агентом успешно загружен.
Конфигурация агента
1. Подготовка конфигурационного файла
- Перейдите в директорию pkl/configs
- Выберите существующий файл конфигурации (например,
base_pipeline.pkl) или создайте новый - Убедитесь, что указаны корректные параметры для запуска:
- JWT-токен для доступа к Solar TI Feeds API
- Адрес и учётные данные интегрируемой СЗИ (например, Cybertrace)
2. Настройка Docker Compose
По умолчанию docker-compose.yml использует конфигурацию pkl/configs/base_pipeline.pkl
Данный файл монтируется как volume в контейнер по пути /configs/config.pkl
Если вы используете другой конфигурационный файл (не base_pipeline.pkl), отредактируйте в docker-compose.yml путь к файлу в секции volumes
3. Модификация логики работы (pipeline)
Если требуется изменить дополнительные параметры или логику обработки данных, отредактируйте pipeline в выбранном файле конфигурации {PIPELINE_NAME}.pkl
4. Переопределение переменных окружения
Базовые параметры для готовых конфигураций задаются в блоке environment файла docker-compose.yml
Переменные окружения
Основные (подключение к Solar TI Feeds)
| Переменная | Назначение |
|---|---|
TIC_AGENT_API_URL | Адрес сервера Solar TI Feeds (по умолчанию https://api.data.rt-solar.ru) |
TIC_AGENT_API_TOKEN | JWT-токен для аутентификации на сервере Solar TI Feeds |
Параметры интеграции с СЗИ
| Переменная | Назначение |
|---|---|
TIC_AGENT_SERVICE_URL | Адрес сервиса СЗИ |
TIC_AGENT_SERVICE_USER | Пользователь для базовой аутентификации |
TIC_AGENT_SERVICE_PASSWORD | Пароль для базовой аутентификации |
TIC_AGENT_SERVICE_TOKEN | Аутентификация по токену |
Прокси-сервер (при необходимости)
Если доступ во внешнюю сеть организован через прокси-сервер, добавьте в docker-compose.yml дополнительные переменные окружения:
environment:
- HTTP_PROXY=http://proxy.example.com:8080
- http_proxy=http://proxy.example.com:8080
- HTTPS_PROXY=http://proxy.example.com:8080
- https_proxy=http://proxy.example.com:8080
При проблемах с доступом можно также указать данные параметры напрямую в файле /etc/systemd/system/docker.service.d/http-proxy
Запуск и проверка функционирования
Для запуска агента необходимо перейти в директорию, в которой был распакован установочный комплект, и ввести в консоли команду для запуска агента:
docker compose up
Для запуска агента в фоновом режиме (как службы) необходимо ввести команду:
docker compose up -d
После запуска контейнера в обычном режиме в консоль будет выводиться служебная информация о работе агента. При запуске в режиме службы для просмотра аналогичной информации необходимо воспользоваться командой:
docker logs {CONTAINER_NAME}
или просмотреть .log файлы, находящиеся в директории ./workdir/logs, если в конфигурационном файле задана запись в лог-файл.
Чтобы посмотреть результаты работы агента, перейдите в поддиректорию ./workdir, находящуюся в директории, из которой был запущен агент. Там размещаются файлы, содержащие результаты работы агента. Если в конфигурационном файле установлены соответствующие значения, то в этой же директории могут быть созданы файл с логами работы агента и файл базы данных SQLite, хранящий в себе состояние работы агента.
Для остановки агента нажмите сочетание клавиш Ctrl+C.
Перезапуск агента
В процессе эксплуатации может возникнуть необходимость в полном перезапуске агента с очисткой его текущего состояния. Это может потребоваться для устранения сбоев в работе, очистки кеша или при изменении конфигурации, требующем обработки всех данных заново.
Процедура полного перезапуска включает в себя остановку агента, удаление файла с его состоянием и последующий запуск.
Удаление файла состояния приведет к тому, что агент при следующем запуске начнет обработку данных с начала, что приведет к повторной загрузке уже полученных ранее данных.
Шаги для полного перезапуска агента:
1. Остановите работающий агент:
- Если агент запущен в интерактивном режиме (через
docker compose up), нажмите сочетание клавиш Ctrl+C - Если агент запущен в режиме службы (через
docker compose up -d), выполните в директории с агентом команду:
$ docker compose down
2. Удалите рабочую директорию агента
Для полного удаления ./workdir выполните команду:
$ rm -rf ./workdir
Команда rm -rf безвозвратно удаляет все файлы и поддиректории. Убедитесь, что путь указан верно и директория не содержит важных данных, которые не подлежат удалению.
3. Запустите агент заново, выполнив команду запуска в нужном режиме
- В интерактивном режиме:
$ docker compose up
- В режиме службы:
$ docker compose up -d
После выполнения этих шагов агент будет запущен с чистым состоянием и начнет процесс выгрузки данных сначала.
Результаты работы агента
Результаты работы агента сохраняются в директории ./workdir (относительно места запуска агента).
Структура директории:
| Путь | Содержимое |
|---|---|
| ./workdir/logs/ | Лог-файлы работы агента (например, agent.log) |
| ./workdir/artifacts/ | Выходные файлы с результатами обработки (CSV, TXT и др.) |
| ./workdir/db/db.sqlite | Файл базы данных SQLite, содержащий кэш и текущее состояние работы агента |
Примечание:
Точные пути могут отличаться в зависимости от настроек в конфигурационных файлах (templates.pkl,base_pipeline.pkl)
Сохранение результатов в формате CSV
Данные могут быть загружены в формате CSV с расширенными возможностями настройки:
- Настройка разделителей (сепараторов) между полями (запятая, точка с запятой, табуляция и др.)
- Настройка символов экранирования для специальных символов и текстовых данных
- Настройка заголовков столбцов (возможность переименования, добавления или удаления)
- Гибкая настройка содержания столбцов с выбором необходимых полей данных
Рисунок 1 – Пример CSV-файла
Рисунок 2 – Пример CSV-файла с настроенными столбцами
Также при сохранении результатов в файл можно выбрать режим записи:
- Перезапись старого файла
- Запись в конец существующего файла
- Запись в новый файл с временной меткой
Рисунок 3 – Примеры файлов в различных режимах записи
Сохранение результатов в виде списка в TXT-файле
Агент позволяет настроить получение данных таким образом, что будет выгружаться только значение индикатора без дополнительной информации для удобного формирование списков (Рисунок 4).
Рисунок 4 – Примеры TXT-файлов, содержащие только значения индикатора
Запись результатов в Kafka
Агент предоставляет возможность записи фидов отдельными сообщениями в Apache Kafka с возможностью выбрать топик, ключ и настроить формат сообщения.
Рисунок 5 – Пример записи фида в виде сообщения в формате Apache Kafka
Контакты технических специалистов
При возникновении вопросов по развёртыванию, настройке или эксплуатации ПО вы можете обратиться к специалистам службы сопровождения Solar TI Feeds по электронной почте:
support.tic@rt-solar.ru