> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Установка Collector > Документация по установке AgentEye Collector. Демон `agenteye-collector` гарантирует, что телеметрия ваших агентов достигает AgentEye без блокирования приложения. Ваш код записывает события в локальный каталог и продолжает работу; collector берет на себя ответственность, загружая каждый файл в течение миллисекунд и сохраняя работоспособность при перезагрузках, сбоях сети и временных ошибках сервера. Неудачные загрузки повторяются с экспоненциальной задержкой, а периодическая восстановительная развёртка повторно ставит в очередь всё, что осталось после сбоя или развёртывания. Результат — надежная доставка с принципом «отправить и забыть»: ваши агенты работают на полной скорости, а collector гарантирует, что события не потеряются в пути. По сути, collector — это лёгкий демон, который отслеживает `$AGENTEYE_HOME/events/` (по умолчанию: `~/.agenteye/events/`) для файлов `.jsonl`, записанных Python SDK, и загружает их на сервер AgentEye. > **Переименовано:** команда collector теперь **`agenteye-collector`** (раньше это был `agenteye`). Краткое имя `agenteye` теперь принадлежит CLI AgentEye. Если вы обновляете существующую установку, см. [enterprise-docs/collector-migration.md](/ru/agenteye/collector-migration). *** ## Предварительные требования * Ваш `AGENTEYE_TOKEN`: GitHub PAT, который вы создаёте сами (см. [enterprise-docs/github-token.md](/ru/agenteye/github-token)) * URL сервера и ключ API collector (см. [enterprise-docs/api-keys.md](/ru/agenteye/api-keys)) *** ## Вариант A: Бинарный файл (рекомендуется) Предварительно собранные статические бинарные файлы доступны для Linux, macOS и Windows (x86\_64 и arm64). Загрузите бинарный файл для вашей платформы прямо из репозитория `agenteye-enterprise/releases` под последний тег релиза `collector/v`. Доступные имена артефактов: | Платформа | Артефакт | | --------------- | --------------------------------------- | | Linux x86\_64 | `agenteye-collector-linux-x86_64` | | Linux arm64 | `agenteye-collector-linux-arm64` | | macOS x86\_64 | `agenteye-collector-darwin-x86_64` | | macOS arm64 | `agenteye-collector-darwin-arm64` | | Windows x86\_64 | `agenteye-collector-windows-x86_64.exe` | | Windows arm64 | `agenteye-collector-windows-arm64.exe` | **Загрузка с помощью CLI `gh`** (замените версию и выберите артефакт для вашей платформы): ```bash theme={null} VERSION=0.0.1-beta.13 GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \ --repo agenteye-enterprise/releases \ --pattern 'agenteye-collector-linux-x86_64' chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` **Или с помощью `curl`:** ```bash theme={null} VERSION=0.0.1-beta.13 ARTIFACT=agenteye-collector-linux-x86_64 curl -fsSL \ -H "Authorization: token $AGENTEYE_TOKEN" \ -L "https://github.com/agenteye-enterprise/releases/releases/download/collector%2Fv${VERSION}/${ARTIFACT}" \ -o agenteye-collector chmod +x agenteye-collector sudo mv agenteye-collector /usr/local/bin/agenteye-collector ``` *** ## Вариант B: Docker ```bash theme={null} echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/collector:beta-latest ``` > Текущие бета-сборки публикуют плавающий тег `:beta-latest`; `:latest` назначается только стабильным релизам. Для повторяемых развёртываний предпочитайте закреплённый тег версии, такой как `:v0.0.1-beta.13`. **Запуск:** ```bash theme={null} docker run -d --restart unless-stopped \ --name agenteye-collector \ -e AGENTEYE_URL=https://ingest.example.com/events \ -e AGENTEYE_KEY="$AGENTEYE_KEY" \ -e AGENTEYE_HOME=/data \ -v "$HOME/.agenteye:/data" \ ghcr.io/agenteye-enterprise/collector:beta-latest \ start ``` Официальный образ запускается от непривилегированного пользователя, поэтому задайте `AGENTEYE_HOME` явно и смонтируйте хостовый буфер к нему. Монтирование тома использует тот же каталог `~/.agenteye/`, в который Python SDK записывает на хосте. Если вы уже установили `AGENTEYE_HOME` в другом месте на хосте, смонтируйте вместо этого этот каталог. *** ## Конфигурация Все параметры можно установить тремя способами (в порядке приоритета): 1. Флаг CLI: `agenteye-collector start --url https://...` 2. Переменная окружения: `AGENTEYE_URL=https://...` 3. Файл конфигурации: `~/.agenteye/config.json` ### Обязательные параметры | Параметр | Флаг CLI | Переменная окружения | Ключ config.json | | ----------- | ------------- | -------------------- | ---------------- | | URL сервера | `--url ` | `AGENTEYE_URL` | `"url"` | | Ключ API | `--key ` | `AGENTEYE_KEY` | `"key"` | ### Опциональные параметры (со значениями по умолчанию) | Параметр | Флаг CLI | Переменная окружения | Ключ config.json | По умолчанию | | ---------------------------------- | ------------------------------ | --------------------------------- | -------------------------- | ------------ | | Макс. одновременных загрузок | `--max-concurrent-uploads ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | Интервал развёртки (сек) | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | Мин. возраст файла развёртки (сек) | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | Макс. файлов в развёртке | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | Макс. попыток загрузки | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | Базовая задержка повтора (мс) | `--retry-base-delay ` | `AGENTEYE_RETRY_BASE_DELAY` | `"retry_base_delay_ms"` | `1000` | ### Параметры mTLS (опционально) Для развёртываний, требующих взаимной TLS (mTLS), collector может представить сертификат клиента во время установления TLS. Если эти параметры не установлены, collector использует стандартный HTTPS. | Параметр | Флаг CLI | Переменная окружения | Ключ config.json | | ------------------------------------ | ------------------- | -------------------- | ---------------- | | Сертификат клиента (PEM) | `--tls-cert ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | Приватный ключ клиента (PEM) | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | Пользовательский сертификат CA (PEM) | `--tls-ca ` | `AGENTEYE_TLS_CA` | `"tls_ca"` | `--tls-cert` и `--tls-key` должны быть установлены вместе. Файлы должны быть в формате PEM. `--tls-ca` независим и требуется только тогда, когда сервер AgentEye представляет TLS-сертификат, который не выдан общедоступным CA (например, самоподписанный издателем `cert-manager` в кластере, когда у вас нет настоящего DNS-домена). Collector добавляет предоставленный CA как дополнительное доверенное якорё; стандартные корни общедоступности остаются доверенными, поэтому существующие развёртывания не затрагиваются. Файл может содержать один PEM-сертификат или полную цепь (несколько объединённых PEM-блоков). **Запуск collector как sidecar в поде приложения?** См. [enterprise-docs/single-pod-deployment.md](/ru/agenteye/single-pod-deployment) для полного паттерна EKS: пакет mTLS, доставляемый через AWS Secrets Manager + Secrets Store CSI Driver + IRSA с автоматической ротацией. При запуске в Kubernetes с паттерном передачи Secret смонтируйте Secret сертификата как том и укажите эти пути на смонтированные файлы: ```yaml theme={null} # Пример: фрагмент Deployment collector volumes: - name: mtls-certs secret: secretName: agenteye-collector-mtls containers: - name: collector env: - name: AGENTEYE_TLS_CERT value: /etc/agenteye/tls/tls.crt - name: AGENTEYE_TLS_KEY value: /etc/agenteye/tls/tls.key # Только если сертификат сервера не выдан общедоступным CA (например, # самоподписанный CA в кластере). Тот же Secret обычно содержит ca.crt # рядом с tls.crt/tls.key. - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### Пример `~/.agenteye/config.json` ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` С mTLS: ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key" } ``` С mTLS плюс пользовательский CA (самоподписанный сервер AgentEye): ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key", "tls_ca": "/etc/agenteye/tls/ca.crt" } ``` Если установлен `AGENTEYE_HOME`, используется этот каталог вместо `~/.agenteye`. *** ## Первоначальная настройка После установки настройте collector с URL сервера и ключом API: ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > Используйте `https` для любого развёртывания, пересекающего ненадёжную сеть, чтобы события не отправлялись в открытом виде. Открытая форма `http://your-server-host:8080/events` подходит только для чисто локального тестирования против сервера на том же хосте. **Протестируйте соединение** (одноразовое полоскание, выход после слива ожидающих событий): ```bash theme={null} agenteye-collector flush ``` `flush` сообщает о прогрессе на stdout. Когда буфер пуст, выводит `No pending files.` и выходит с кодом `0`. В противном случае выводит одну строку на файл (`[UPLOADED] ` или `[FAILED] ()`), затем итоговую сводку `Done: / uploaded, failed.`. Это делает `flush` удобной одноразовой проверкой, что ваш URL, ключ и параметры TLS верны перед запуском демона. *** ## Запуск как демон ### Прямой запуск ```bash theme={null} agenteye-collector start ``` ### Контейнер / Docker Когда collector и приложение используют один контейнер, запустите их под супервизором процессов. Самый простой вариант — `supervisord`; он поставляется в каждом основном дистрибутиве, перезапускает упавшие процессы, перенаправляет сигналы и ждёт корректного завершения. **`Dockerfile`:** ```Dockerfile theme={null} FROM python:3.11-slim RUN apt-get update && apt-get install -y --no-install-recommends supervisor \ && rm -rf /var/lib/apt/lists/* # Получите бинарный файл agenteye-collector из официального образа. # Закрепите конкретный тег (:beta-latest для текущих бета-версий или тег :v); # :latest публикуется только для стабильных релизов. COPY --from=ghcr.io/agenteye-enterprise/collector:beta-latest \ /usr/local/bin/agenteye-collector /usr/local/bin/agenteye-collector COPY supervisord.conf /etc/supervisor/conf.d/agenteye.conf COPY my_agent.py /app/my_agent.py CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"] ``` **`supervisord.conf`:** ```ini theme={null} [supervisord] nodaemon=true user=root [program:agenteye-collector] command=/usr/local/bin/agenteye-collector start autorestart=true stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 [program:app] command=python /app/my_agent.py autorestart=unexpected stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 ``` Почему эти параметры: * `autorestart=true` на agenteye-collector: перезапуск при любом выходе (сбой, паника, OOM). * `autorestart=unexpected` на приложении: перезапуск только при ненулевом выходе, поэтому одноразовый агент, выходящий с 0, не зацикливается. * `stopwaitsecs=30`: дает collector возможность слить ожидающие загрузки при SIGTERM перед тем, как supervisord переключится на SIGKILL. * `stdout_logfile=/dev/stdout`, `*_maxbytes=0`: потоковая передача вывода обоих программ на контейнер stdout; без логфайлов внутри контейнера. Передайте `AGENTEYE_URL` / `AGENTEYE_KEY` (и любые переменные TLS) на `docker run -e` как раньше; supervisord наследует окружение. > **Отдельные контейнеры?** Если вы запускаете collector как собственный контейнер (сервис Docker Compose, sidecar Kubernetes и т.д.), не используйте supervisord; политика перезагрузки runtime контейнера уже выполняет эту работу. См. [enterprise-docs/single-pod-deployment.md](/ru/agenteye/single-pod-deployment) для паттерна EKS sidecar. **Проверка живучести Kubernetes** (применяется независимо от того, работает ли collector отдельно или под supervisord): ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` Работающий демон записывает пульс в `$AGENTEYE_HOME/health.json` каждые 30 секунд. `agenteye-collector health` читает этот файл и выходит с кодом `0` (здоров) только если пульс свежий и задачи загрузки работают нормально; выходит с кодом `1` (болен) если пульс старше 90 секунд (например, демон остановился) или пока наблюдатель и развёртка перезагружаются после непредвиденного выхода. Пульс записывается только командой `start`, поэтому запустите проверку против долгоживущего демона, а не одноразовой команды `flush`. ### systemd (Linux, рекомендуется для production) ```ini theme={null} # /etc/systemd/system/agenteye-collector.service [Unit] Description=AgentEye Collector After=network.target [Service] ExecStart=/usr/local/bin/agenteye-collector start Restart=on-failure RestartSec=5 EnvironmentFile=/etc/agenteye/env [Install] WantedBy=multi-user.target ``` Создайте `/etc/agenteye/env`: ``` AGENTEYE_URL=https://ingest.example.com/events AGENTEYE_KEY=YOUR_COLLECTOR_KEY ``` ```bash theme={null} sudo systemctl daemon-reload sudo systemctl enable --now agenteye-collector sudo systemctl status agenteye-collector ``` ### launchd (macOS) ```xml theme={null} Label ai.befailproof.agenteye-collector ProgramArguments /usr/local/bin/agenteye-collector start EnvironmentVariables AGENTEYE_URL https://ingest.example.com/events AGENTEYE_KEY YOUR_COLLECTOR_KEY RunAtLoad KeepAlive ``` ```bash theme={null} launchctl load ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist ``` *** ## Обновление Collector Collector не обновляется самостоятельно. Для обновления: * **Бинарный файл:** загрузите новый артефакт `agenteye-collector--` из последнего релиза `collector/v` (см. [Вариант A](#вариант-a-бинарный-файл-рекомендуется)), замените `/usr/local/bin/agenteye-collector`, затем перезагрузите сервис (`sudo systemctl restart agenteye-collector`, переза-`launchctl load` или перезагрузите ваш супервизор). * **Docker:** `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (или закреплённый тег `:v`; `:latest` существует только для стабильных релизов) и пересоздайте контейнер. `AGENTEYE_TOKEN` требуется для загрузки новых бинарных файлов/образов из приватного репозитория релизов, но **не** требуется работающему демону. *** ## Подкоманды | Команда | Описание | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agenteye-collector start` | Запустить долгоживущий демон. При запуске он полоскает все события, оставшиеся с предыдущего запуска, затем отслеживает новые файлы и загружает их. Наблюдатель и развёртка автоматически перезагружаются при непредвиденном выходе, и пульс записывается в `health.json` каждые 30 секунд. | | `agenteye-collector flush` | Одноразово: загрузить все ожидающие файлы и выйти. Выводит `No pending files.` если буфер пуст, в противном случае логирует для каждого файла `[UPLOADED]`/`[FAILED]` и итоговую сводку `Done: / uploaded, failed.`. | | `agenteye-collector health` | Прочитать пульс `health.json` демона. Выход `0` если свежий и здоров; выход `1` если пульс устарел (старше 90 сек) или задачи перезагружаются. | *** ## Макет каталога ``` ~/.agenteye/ ├── config.json <- опциональный файл конфигурации ├── events/ <- файлы .jsonl, записанные SDK, подхваченные collector └── failed/ <- файлы, которые не загрузились при всех попытках ``` Файлы в `failed/` не повторяются автоматически. Чтобы вручную переставить их в очередь, переместите их обратно в `events/` и запустите `agenteye-collector flush`.