Развёртывание

​

Обзор архитектуры

  [ AI agent machines ]                  [ Your infrastructure ]

    Python SDK
       |  writes JSONL                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (relational store)   |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (events / analytics) |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (optional) |
                      | Dashboard |           +----------------------+
                      +-----------+

• Server: HTTP-сервис на Rust; получает пакеты событий, записывает их в ClickHouse и поддерживает состояние в PostgreSQL.
• Dashboard: веб-приложение на Next.js; читает и пишет исключительно через API сервера.
• agenteye-collector: развёртывается на машинах агентов, а не на хосте сервера.
• Postgres 15+: ТРЕБУЕТСЯ. (Повышено с 14 в версии с поддержкой нескольких арендаторов; схема членства в организации использует иностранный ключ ON DELETE SET NULL со списком столбцов, что поддерживается только в Postgres 15+. Обновите Postgres перед развёртыванием этой версии.) Хранит состояние OLTP: api_keys, users, sessions, evaluation_jobs (очередь), dashboards, saved_queries, otp_codes, а также таблицы для нескольких арендаторов orgs, org_memberships, org_settings.
• ClickHouse 24+: ТРЕБУЕТСЯ. Хранилище аналитики для каждого полученного события. Engine: ReplacingMergeTree, разбиение по месяцам, упорядочение по (session_id, ts, dedup_key). Сервер подключается через CLICKHOUSE_URL; поставляемая конфигурация deploy/base/clickhouse/ содержит оптимизированную конфигурацию для одного узла. Требование для нескольких арендаторов: поставляемая конфигурация включает управление доступом SQL + users_without_row_policies_can_read_rows=false, позволяя серверу создавать по одному пользователю ClickHouse только для чтения + политику строк для каждой организации (граница изоляции, поддерживаемая engine). Если вы используете собственную конфигурацию ClickHouse, перенесите эти параметры (см. deploy/base/clickhouse/configmap.yaml).
• Redis 7+: опциональный общий кеш + бэкенд ограничения частоты запросов. И сервер, и приборная панель подключаются через REDIS_URL. При отсутствии оба корректно переходят на использование только Postgres. См. Redis (опциональный кеш) ниже.

​

Сервер

​

Получить образ

echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
docker pull ghcr.io/agenteye-enterprise/server:beta-latest

Текущие сборки публикуются под beta-latest; latest присваивается только стабильным релизам. Для продакшена зафиксируйте конкретный тег :v<version>; см. Доступные теги образов.

​

Переменные окружения

​

Запуск

docker run -d --restart unless-stopped \
  --name agenteye-server \
  -e DATABASE_URL="$DATABASE_URL" \
  -e ADMIN_KEY="$ADMIN_KEY" \
  -p 8080:8080 \
  ghcr.io/agenteye-enterprise/server:beta-latest

​

Проверка здоровья

GET /health    # liveness  - всегда {"status":"ok"} после запуска процесса
GET /ready     # readiness - 200 когда Postgres + ClickHouse достижимы, иначе 503

​

Email волшебная ссылка URL

1. Заголовок X-AgentEye-Dashboard-Url: установлено автоматически прокси приборной панели /api/auth/otp/request из её собственного публичного источника. В развёртывании в одном источнике (сервер и приборная панель используют один хост позади одного ingress, который передаёт заголовки прокси), никакая конфигурация не требуется.
2. Переменная окружения DASHBOARD_URL: установите это, если ваша приборная панель достижима на другом источнике, чем тот, который видит конечная точка OTP сервера (разделённые api.example.com / app.example.com), или если ваш ingress не распространяет публичный хост в pod приборной панели (поэтому request.nextUrl.origin иначе разрешит привязку подстановочного знака как 0.0.0.0:3000). Пример: DASHBOARD_URL=https://app.example.com.
3. По умолчанию: https://app.befailproof.ai, используется только если ни один из вышеперечисленных не присутствует.

kubectl set env deployment/server -n agenteye \
  DASHBOARD_URL=https://app.example.com

​

Приборная панель

​

Получить образ

docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Переменные окружения

​

Запуск

docker run -d --restart unless-stopped \
  --name agenteye-dashboard \
  -e AGENTEYE_SERVER_URL="http://your-server-host:8080" \
  -e AGENTEYE_API_KEY="$ADMIN_KEY" \
  -p 3000:3000 \
  ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Телеметрия & конфиденциальность

• Никакие данные агента, сеанса или события никогда не покидают вашу инфраструктуру. Сообщается только использование UI приборной панели. URL страниц удаляют идентификаторы перед отправкой, и операторы идентифицируются только по непрозрачному внутреннему id, никогда по email.
• Телеметрия включена по умолчанию. Чтобы полностью отключить, установите AE_ANALYTICS_DISABLED=1 на контейнере приборной панели и перезагрузитесь.
• Аналитика отправляются на путь приборной панели /ingest, который приборная панель обратный прокси к PostHog (https://us.i.posthog.com). Сохранение запросов от первого лица означает, что блокировщики рекламы браузера их не отбрасывают. Контейнер приборной панели нуждается в исходящем доступе к PostHog; если он заблокирован, телеметрия молча ничего не делает и приборная панель не затронута.

​

ИИ-ассистент (опционально)

​

ClickHouse (требуемое хранилище аналитики)

​

Схема

• agenteye.events: ReplacingMergeTree(ingested_at), разбиение по toYYYYMM(ts), упорядочение по (session_id, ts, dedup_key). Дублирующиеся вставки (повторы сборщика) сворачиваются в одну строку во время слияния; сервер вычисляет детерминированный SHA-256 dedup_key для каждого события, поэтому повторы безопасны.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), разбиение по toYYYYMM(finished_at), упорядочение по (session_id, finished_at, dedup_key). Написано один раз за терминальный результат оценки конвейером evaluator. Та же модель dedup-key, что и events.
• agenteye.agent_sessions: ПРЕДСТАВЛЕНИЕ над agenteye.events, а не физическая таблица. Каждый столбец является производным (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count() и т.д.). Нет upsert за событие и нет отдельной заливки; представление автоматически отражает всё, что находится в events.

​

Конфигурация

• 2 ГиБ запрошено / 4 ГиБ лимит памяти в поставляемом базовом оверлее (размер для маленьких узлов POC/staging); клиенты продакшена должны наложить up — рекомендуемый минимум 2c / 4Gi запрос, 6c / 8Gi лимит. max_server_memory_usage_to_ram_ratio=0.9
• 5 ГиБ mark cache + 8 ГиБ uncompressed cache
• background_pool_size=16, background_merges_mutations_concurrency_ratio=2
• MergeTree: parts_to_throw_insert=3000, parts_to_delay_insert=1500, non_replicated_deduplication_window=1000
• local_io_method=auto (io_uring на поддерживаемых ядрах)
• fsync_metadata=0: допустимо из-за at-least-once inggest + ReplacingMergeTree dedup
• query_log включен с TTL 30 дней; query_thread_log удалён (дорого при высоком QPS)
• max_execution_time=30 для запросов пользователей
• 100 ГиБ PVC в шаблоне StatefulSet (оверлеи клиентов ДОЛЖНЫ переопределить на быстрый класс хранилища SSD для продакшена)

​

Резервные копии

​

Redis (опциональный кеш)

• Сервер кеширует поиски аутентифицированных ключей API, списки /events/environments + /evaluations/environments, rollup /events/latency_aggregate (самый тяжёлый запрос, который приборная панель опрашивает), список /sessions и переключает ограничение частоты запросов OTP с Postgres COUNT(*) на Redis INCR + EXPIRE.
• Приборная панель кеширует результаты validateSession(), поэтому 10-20 аутентифицированных вызовов API, которые типичная загрузка страницы выдаёт, все делят один восходящий проверку сеанса. Она также ограничивает частоту запросов OTP-request и OTP-verify на граница приборной панели.

​

Конфигурация

​

Память + персистентность

​

Когда НЕ развёртывать Redis

• Одноэкземплярная разработка/QA. Внутренние кеши на сервере одного доставляют большую часть преимущества за реплику; Redis добавляет кросс-реплику, совместное использование которых одноэкземплярные настройки не нуждаются.
• Air-gapped установки, где эксплуатационная стоимость запуска ещё одного сервиса перевешивает выигрыш задержки.

​

Docker Compose (рекомендуется)

GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \
  --repo agenteye-enterprise/releases \
  --pattern 'docker-compose.yml' \
  --dir ./agenteye
cd agenteye

# Используйте пароли, безопасные для URL (без /, +, или = символов).
# Генерируйте с: openssl rand -hex 24
POSTGRES_PASSWORD=ваш-пароль-бд
ADMIN_KEY=ваш-секрет-администратора

# Аутентификация приборной панели
ADMIN_EMAIL=admin@вашакомпания.com
ALLOWED_EMAILS=*@вашакомпания.com

# SMTP для email OTP (опустите для логирования кодов OTP в stdout)
# SMTP_HOST=smtp.вашпровайдер.com
# SMTP_PORT=587
# SMTP_USERNAME=ваш-smtp-юзер
# SMTP_PASSWORD=ваш-smtp-пароль
# SMTP_FROM=noreply@вашакомпания.com

RUST_LOG=info

docker compose up -d

docker compose down

docker compose down -v

​

Операционные настройки

​

Как работает bootstrap

• Для свежего развёртывания установите переменные окружения, как показано выше, и организация по умолчанию читает их при первой загрузке.
• Чтобы изменить значение позже, войдите на приборную панель и отредактируйте её под /<org>/settings. Изменение применяется в течение секунд на всех репликах сервера; перезагрузка не нужна.
• Строка журнала запуска записывает, что получило заполнение против того, что уже присутствовало, поэтому вы можете подтвердить, что bootstrap сработал:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Семантика входа между организациями

• Время жизни сеанса / OTP: самое строгое (кратчайшее) время жизни среди организаций, которым принадлежит пользователь, выигрывает.
• Допускаемые входы: шлюз ИЛИ каждый список разрешений организации вместе с членством в организации: пользователь может запросить OTP, если список разрешений любой организации допускает их email или они уже являются членом любой организации.

​

Разрешения

• settings:read: видеть страницу и текущие значения.
• settings:write: сохранить изменения.

​

Организации (мультитенантность)

# Docker Compose - exec в работающий сервис сервера:
docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp"
docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin

# Kubernetes - exec в работающее развёртывание сервера:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

Заполнение окна контекста

# предпросмотр (печатает мутацию для каждой организации, ничего не меняет):
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run
# применить:
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window
# docker compose:
docker compose exec server agenteye-backfill-context-window

​

Соображения по продакшену

• Postgres: используйте управляемый сервис Postgres или выделённый экземпляр с регулярными резервными копиями. DATABASE_URL поддерживает все стандартные параметры libpq, включая sslmode=require для зашифрованных соединений.
• TLS: поместите сервер и приборную панель позади обратного прокси (nginx, Caddy, Traefik), который завершает TLS.
• Брандмауэр: порт сервера (по умолчанию 8080) должен быть достижим только с машин сборщика и хоста приборной панели, а не из публичного интернета.
• Ключ администратора: установите ADMIN_KEY на сильный случайный секрет. После bootstrap создавайте выделённые ключи с областью действия для сборщиков и приборной панели, а не используйте ключ администратора везде.
• Теги образов: закрепите версию в ваших манифестах релиза (например, server:v0.0.1-beta.48) в продакшене, а не плавающий тег, чтобы избежать непредусмотренных обновлений. Текущие бета-сборки публикуются под beta-latest; latest присваивается только стабильным релизам.
• Мониторинг здоровья: на Kubernetes проба готовности использует /ready (достижимость Postgres + ClickHouse), пока liveness остаётся на /health. Для fleet-широкого оповещения AgentEye себя на Slack включите opt-in дополнение Robusta; см. enterprise-docs/health-monitoring.md.

​

Доступные теги образов