> ## 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. # Развёртывание > Документация по развёртыванию AgentEye. Это руководство охватывает развёртывание сервера AgentEye и приборной панели в продакшене. *** ## Обзор архитектуры ``` [ 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 (опциональный кеш)** ниже. *** ## Сервер ### Получить образ ```bash theme={null} echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` > Текущие сборки публикуются под `beta-latest`; `latest` присваивается только стабильным релизам. Для продакшена зафиксируйте конкретный тег `:v`; см. [Доступные теги образов](#доступные-теги-образов). ### Переменные окружения | Переменная | Требуется | По умолчанию | Описание | | --------------------------------------------- | ----------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABASE_URL` | Да | нет | Postgres DSN. Строка подключения в стандартном формате libpq со схемой `postgres://`. Поддерживает `?sslmode=require` и другие параметры libpq. Пароль не должен содержать `/`, `+` или `=`; используйте `openssl rand -hex` для генерации безопасных для URL паролей. | | `ADMIN_KEY` | Нет | нет | Начальный ключ API администратора. Обновляется со всеми разрешениями при каждом запуске. Для ротации измените значение и перезагрузитесь. | | `LISTEN_ADDR` | Нет | `0.0.0.0:8080` | TCP-адрес для привязки | | `MAX_BODY_BYTES` | Нет | `134217728` (128 МБ) | Максимальный размер тела запроса | | `ADMIN_EMAIL` | Нет | нет | Email начального пользователя администратора. Обновляется со всеми разрешениями при каждом запуске и помечается защищённым: не может быть отключен или иметь изменены разрешения через приборную панель/API. Для ротации начального администратора измените `ADMIN_EMAIL` и перезагрузитесь; новый email обновляется как защищённый, а предыдущий сохраняет защиту до ручной очистки в БД. | | `ALLOWED_EMAILS` | Нет | нет (все заблокированы) | Список допускаемых адресов email через запятую для создания и входа пользователей. Поддерживает точные адреса (`user@example.com`) и подстановочные знаки домена (`*@example.com`). Если не задано, никакие пользователи не могут быть созданы или войти. **Только при первой загрузке**: заполняет список разрешений организации по умолчанию при первой загрузке; затем страница `//settings` каждой организации является источником истины и изменение этой переменной окружения не имеет эффекта. | | `SMTP_HOST` | Нет | нет | Имя хоста SMTP-сервера для отправки email с OTP. При отсутствии коды OTP логируются в stdout. | | `SMTP_PORT` | Нет | `587` | Порт SMTP-сервера | | `SMTP_USERNAME` | Нет | нет | Имя пользователя для аутентификации SMTP | | `SMTP_PASSWORD` | Нет | нет | Пароль для аутентификации SMTP | | `SMTP_FROM` | Нет | нет | Адрес отправителя для email с OTP | | `SMTP_TLS` | Нет | STARTTLS | STARTTLS используется, если вы явно не отключите это: `false` или `0` отправляют в открытом виде (без TLS); любое другое значение — включая отсутствие — включает STARTTLS. | | `DASHBOARD_URL` | Нет | встроенное значение по умолчанию | Источник приборной панели, используемый для построения как волшебной ссылки OTP, так и волшебных ссылок инцидентов в уведомлениях об оповещениях. При отсутствии возвращается к встроенному значению по умолчанию (и только для OTP — сначала к источнику, производному от приборной панели). Установите это для конфигураций с разделением доменов, чтобы как email, так и ссылки Slack/инцидентов указывали на вашу приборную панель. См. **Email волшебная ссылка URL** ниже; большинству операторов это не требуется. | | `SESSION_TTL_SECS` | Нет | `86400` (24 ч) | Продолжительность сеанса приборной панели в секундах. **Только при первой загрузке**: редактируйте для каждой организации через [`//settings`](#операционные-настройки) после первого развёртывания. | | `OTP_TTL_SECS` | Нет | `600` (10 мин) | Период действительности кода OTP в секундах. **Только при первой загрузке**: редактируйте для каждой организации через [`//settings`](#операционные-настройки) после первого развёртывания. | | `REDIS_URL` | Нет | нет | Опциональный общий кеш + бэкенд ограничения частоты запросов, например `redis://redis:6379/0`. При установке сервер кеширует поиски аутентифицированных ключей API, агрегат `/models` приборной панели, список сеансов и фасет списка окружений; также переводит ограничение частоты запросов OTP с Postgres COUNT на Redis INCR. При отсутствии или недоступности сервер работает без кеша (лимит OTP возвращается на Postgres, каждый другой кеш переходит к источнику истины). См. **Redis (опциональный кеш)** ниже. | | `CLICKHOUSE_URL` | **Да** | нет | Базовый URL экземпляра ClickHouse, например `http://clickhouse:8123`. Сервер применяет свою схему событий к этой БД при каждом запуске и отказывается загружаться, если не может достичь ClickHouse. См. **ClickHouse (требуемое хранилище аналитики)** ниже. | | `CLICKHOUSE_DATABASE` | Нет | `agenteye` | Имя БД (схемы) ClickHouse. Сервер создаёт её при запуске, если она не существует. | | `ORG_CH_SECRET` | Нет (один арендатор) / **Да (несколько организаций)** | значение по умолчанию для разработки | Ключ HMAC, из которого происходит пароль ClickHouse каждой организации для работы с конкретным арендатором. SQL-редактор и `run_query` агента выполняются от имени пользователя ClickHouse, доступного только для чтения организации, чья политика строк обеспечивает изоляцию арендатора в engine. Развёртывания с одним арендатором хорошо загружаются со встроенным значением по умолчанию для разработки; **перед подготовкой второй организации вы ДОЛЖНЫ установить сильное, стабильное значение**, потому что CLI `agenteye-orgctl org create` отказывается работать со встроенным значением по умолчанию для разработки. Его ротация сирот каждого пользователя ClickHouse организации до следующей перезагрузки (при загрузке система автоматически заживляет это). Держите его в тайне и не изменяйте между репликами. Сама подготовка организации доступна только оператору; см. **Организации (мультитенантность)** ниже. | | `DEFAULT_ORG_NAME` | Нет | `Default` | Отображаемое имя, заполняемое встроенной организацией по умолчанию. **Только при первой загрузке** и только пока организация сохраняет своё свежемигрированное универсальное имя, применяется при запуске, затем игнорируется. После переименования организации (`agenteye-orgctl org rename`) переименование авторитетно и эта переменная окружения больше не влияет. | | `DEFAULT_ORG_SLUG` | Нет | `default` | URL-слаг встроенной организации по умолчанию, путь приборной панели, где она находится (`//…`). Та же семантика первой загрузки / только для неиспорченных, что и `DEFAULT_ORG_NAME`. Должен быть 1-40 строчных буквенно-цифровых символов с одиночными внутренними дефисами и не быть [зарезервированным словом](#организации-мультитенантность); недействительное значение игнорируется (организация остаётся `default`). Позволяет установке с одним арендатором представляться как `/acme` вместо `/default` без шага CLI после развёртывания. | | `RUST_LOG` | Нет | `info` | Уровень логирования (`debug`, `warn`, `error`, `agenteye_server=trace`) | | `EVALUATOR_ENDPOINT` | Нет | нет | Базовый URL вашего сервиса evaluator (например `http://evaluator:9000`). При отсутствии весь конвейер оценки является no-op; никакие строки очереди не пишутся, никакие рабочие не работают. См. [Evaluation Suite](/ru/agenteye/evaluation-suite). | | `EVALUATOR_TOKEN` | Нет | нет | Отправляется как `Authorization: Bearer ` к evaluator. **Должно быть равно тому же значению, с которым настроен сервис evaluator.** Опционально только если ваш evaluator настроен без токена. | | `EVALUATOR_WORKERS` | Нет | `2` | Параллелизм: количество рабочих задач на экземпляр сервера, который отправляет оценки. Безопасно работать на нескольких горизонтально масштабируемых серверах. | | `EVALUATOR_CLAIM_BATCH` | Нет | `4` | Максимальное количество оценок, которые один рабочий требует за один цикл. Пакеты отправляются **параллельно**, поэтому общий параллелизм на вашей конечной точке evaluator составляет `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | | `EVALUATOR_POLL_IDLE_SECS` | Нет | `2` | Как долго рабочий спит между попытками отправки, когда нечего делать. | | `EVALUATOR_POLLING_INTERVAL_SECS` | Нет | `10` | Окончательный запасной каданс (секунды) для опросов `GET /evaluate/{id}`, когда evaluator не возвращает `next_poll_secs` для каждого ответа и не объявляет `default_poll_interval_secs` из `GET /config`. | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Нет | `30000` | Тайм-аут за запрос HTTP к evaluator (миллисекунды). | | `EVALUATOR_MAX_ATTEMPTS` | Нет | `5` | После стольких неудачных попыток оценка записывается как терминальная `error` (или `timeout`, если ошибки были тайм-аутами запросов). | | `EVALUATOR_CONFIG_REFRESH_SECS` | Нет | `300` (5 мин) | Как часто сервер переполучает `GET /config` от evaluator. | | `EVALUATOR_MAX_POLL_DURATION_SECS` | Нет | `3600` (1 ч) | Максимальное время существования сеанса в очереди опроса перед тем, как AgentEye завершит его как `timeout`. Защищает от evaluator, который возвращает `pending` бесконечно. | | `ALERT_WORKERS` | Нет | `1` | Параллелизм: количество рабочих задач на экземпляр сервера, который оценивает правила оповещений. См. [Alerts](/ru/agenteye/alerts). | | `ALERT_CLAIM_BATCH` | Нет | `16` | Максимальное количество оповещений, которые один рабочий требует за один цикл. | | `ALERT_POLL_IDLE_SECS` | Нет | `5` | Как долго рабочий оповещений спит, когда очередь пуста. | | `ALERT_REQUEST_TIMEOUT_MS` | Нет | `15000` | Тайм-аут оценки за срабатывание (запросы ClickHouse + исходящий HTTP канала). | | `ALERT_MAX_ATTEMPTS` | Нет | `5` | Последовательные переходящие ошибки перед тем, как оповещение перепланируется с его нормальным каданс вместо экспоненциального отката. | | `AUDIT_WORKERS` | Нет | `1` | Параллелизм: количество рабочих задач на экземпляр сервера, который выполняет аудиты. См. [Audits](/ru/agenteye/audits). | | `AUDIT_CLAIM_BATCH` | Нет | `1` | Максимальное количество просроченных аудитов, которые один рабочий требует за один цикл. Агентское расследование — это один длинный цикл, поэтому значение по умолчанию — 1. | | `AUDIT_POLL_IDLE_SECS` | Нет | `30` | Как долго рабочий аудитов спит, когда нет просроченного аудита. | | `AUDIT_REQUEST_TIMEOUT_MS` | Нет | `30000` | Тайм-аут за запрос политики к ClickHouse (миллисекунды). | | `AUDIT_LLM_TIMEOUT_MS` | Нет | `1440000` | Тайм-аут для вызова агентского расследования к сервису ИИ-ассистента. Полный цикл агента работает минуты; держите это ВЫШЕ `AGENTEYE_AUDIT_TIMEOUT_MS` агента, чтобы агент вернул свои частичные находки перед тем, как сервер сдаст. | | `AUDIT_MAX_ATTEMPTS` | Нет | `5` | Последовательные переходящие ошибки перед тем, как аудит перепланируется с его нормальным каданс вместо экспоненциального отката. | | `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Нет | — | Агентское расследование аудита вызывает сервис ИИ-ассистента `agent`, **повторно используя то же соединение, что и ассистент** — поэтому установите эти два на **сервере** также (поставляемые манифесты/compose делают это). Оба установлены ⇒ аудиты запускают расследование ИИ; либо один не установлен ⇒ аудиты запускают **только политику** (детерминированный SQL проход политики всё ещё работает), независимо от флага `llm_enabled` для каждого аудита. Агент должен также иметь настроенную LLM — см. [assistant.md](/ru/agenteye/assistant). | **Сервис ИИ-ассистента — параметры аудита + песочницы.** Агентское расследование и его Python-песочница в pod настраиваются на **сервисе агента** (не на сервере), все с префиксом `AGENTEYE_AUDIT_*` и все опциональные: | Переменная | По умолчанию | Значение | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Макс ходов агента за расследование. | | `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Настенные часы для одного расследования (20 мин). Должны оставаться **ниже** `AUDIT_LLM_TIMEOUT_MS` сервера. | | `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Одновременные расследования на pod агента (отдельно от бюджета ассистента чата). | | `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Пределы за скрипт для песочницы bubblewrap. | **Требование платформы песочницы.** Песочница кода аудита запускает Python модели внутри клетки bubblewrap, которая нуждается в **пространствах имён пользователей без привилегий**. Pod агента должен позволять флаги `clone()` — установите `seccompProfile: Unconfined` (k8s) или `security_opt: [seccomp:unconfined]` (compose) на агенте. Где ядро узла отключает пространства имён пользователей без привилегий (например, некоторые образы GKE COS), песочница **проверка перед полётом завершается неудачей и аудитор автоматически понижается только до SQL** — нет ошибки, просто `sandbox_available: false` на `/health` агента. ### Запуск Установите `DATABASE_URL` в вашу окружение, затем передайте её в контейнер: ```bash theme={null} 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 ``` Аутентификация не требуется. Используйте `/health` для проб **liveness** и `/ready` для проб **readiness** / балансировщика нагрузки. `/ready` проверяет жёсткие зависимости, без которых сервер не может работать (Postgres + ClickHouse), поэтому сервер, который работает, но не может достичь своей БД, выводится из ротации и отображается как `NotReady`; Redis сообщается, но никогда не вызывает ошибку готовности. На поставляемых манифестах Kubernetes проба готовности уже указывает на `/ready`, а liveness остаётся на `/health`. См. [enterprise-docs/health-monitoring.md](/ru/agenteye/health-monitoring) для полной картины, включая opt-in оповещение об ошибке pod на Slack, собственное для Kubernetes. ### Email волшебная ссылка URL Email логина OTP содержит кнопку одного касания **откройте приборную панель**. Клик по ней приводит пользователя на `/login?token=&email=
`; приборная панель обменивает эту пару на сеанс и перенаправляет в приложение без ручного повторного ввода кода. Сервер разрешает источник приборной панели, используемый для построения ссылки в три уровня: 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`, используется только если ни один из вышеперечисленных не присутствует. Значение заголовка проверяется: принимаются только источники `https://*` и loopback (`http://localhost*`, `http://127.0.0.1*`), а адреса привязки подстановочного знака (`0.0.0.0`, `[::]`) отвергаются даже с схемой `https://`. Всё остальное переходит на уровень 2. Установите его на работающем кластере с одной строчкой; без файла, без перестроения kustomize: ```bash theme={null} kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` Это запускает rollout; новые pod-ы подбирают значение при первом запросе. Обратите внимание, что переопределение живёт только на Deployment; последующее `kustomize build | kubectl apply` для оверлея сотрёт его, если вы не добавите ту же переменную окружения в патч `server-env.yaml` вашего оверлея. *** ## Приборная панель ### Получить образ ```bash theme={null} docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` ### Переменные окружения | Переменная | Требуется | По умолчанию | Описание | | ----------------------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AGENTEYE_SERVER_URL` | Да | нет | Базовый URL сервера, например `http://localhost:8080` | | `AGENTEYE_API_KEY` | Да | нет | Ключ API, который приборная панель использует для аутентификации на сервере. Нужны все разрешения (рекомендуется ключ администратора). | | `AE_LOG_LEVEL` | Нет | `info` | Серверная буквальность логирования: `debug`, `info`, `warn`, `error`. Установите на `debug`, чтобы видеть строки запроса/ответа к вышестоящему и трассировки проверки сеанса при диагностике проблем. | | `AE_LOG_JSON` | Нет | авто | `1` заставляет вывод JSON-per-line; `0` заставляет удобочитаемый вывод. При отсутствии JSON включается автоматически если `NODE_ENV=production`. JSON рекомендуется в продакшене, чтобы логи чистили с `jq` или агрегатором логов. | | `AE_ANALYTICS_DISABLED` | Нет | нет | Установите на `1`/`true`, чтобы отключить анонимную телеметрию использования продукта приборной панели. См. [Телеметрия & конфиденциальность](#телеметрия--конфиденциальность) ниже. | | `REDIS_URL` | Нет | нет | Опциональный общий бэкенд кеша, например `redis://redis:6379/0`. При установке приборная панель кеширует результаты `validateSession()` между репликами и делится fetch кешем Next.js для маршрутов латентности-агрегата / env-list прокси. Ограничения частоты запросов OTP на граничной стороне также используют Redis при наличии (открываются при недоступности Redis; серверная граница это отступление по безопасности). См. **Redis (опциональный кеш)** ниже. | | `AGENTEYE_AGENT_URL` | Нет | нет | Базовый URL опционального сервиса ИИ-ассистента `agent`, например `http://agent:9100`. **Оставьте не установленным, чтобы полностью скрыть ассистента**: никакой пузырь ассистента не появляется на приборной панели. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | | `AGENTEYE_AGENT_TOKEN` | Нет | нет | Общий секрет, который приборная панель представляет сервису `agent`. Должен совпадать с `AGENTEYE_AGENT_TOKEN`, настроенным на агенте. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | ### Запуск ```bash theme={null} 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 ``` ### Телеметрия & конфиденциальность Приборная панель отправляет **анонимную телеметрию использования продукта** в сервис аналитики Exosphere (PostHog): какие страницы приборной панели просматриваются и ряд действий UI, таких как создание ключа API или переоценка сеанса. Этот сигнал использования информирует о том, какие функции получают приоритет. * **Никакие данные агента, сеанса или события никогда не покидают вашу инфраструктуру.** Сообщается только использование UI приборной панели. URL страниц удаляют идентификаторы перед отправкой, и операторы идентифицируются только по непрозрачному внутреннему id, никогда по email. * Телеметрия **включена по умолчанию**. Чтобы полностью отключить, установите `AE_ANALYTICS_DISABLED=1` на контейнере приборной панели и перезагрузитесь. * Аналитика отправляются на путь приборной панели `/ingest`, который приборная панель обратный прокси к PostHog (`https://us.i.posthog.com`). Сохранение запросов от первого лица означает, что блокировщики рекламы браузера их не отбрасывают. **Контейнер приборной панели** нуждается в исходящем доступе к PostHog; если он заблокирован, телеметрия молча ничего не делает и приборная панель не затронута. *** ## ИИ-ассистент (опционально) ИИ-ассистент в приборной панели позволяет вашей команде задавать вопросы о данных своего агента на обычном языке (резюмировать сеансы, черновик SQL для редактора `/queries` и превращать сохранённые запросы в плитки приборной панели) без покидания приборной панели. Он работает как отдельный внутренний контейнер `agent` (на Agents SDK) к которому может достичь только приборная панель, и остаётся **отключённым до тех пор, пока вы не настроите конечную точку LLM**. Чтобы включить, вы установите на сервис `agent` подключение LLM (**Portkey** через `PORTKEY_API_KEY` + слаг каталога моделей `AGENTEYE_AGENT_MODEL=@/`, прямой Anthropic через `ANTHROPIC_API_KEY`, другой шлюз через `ANTHROPIC_BASE_URL` или Bedrock/Vertex), **выделенный** ключ данных и общий `AGENTEYE_AGENT_TOKEN`, совпадающий с приборной панелью. Пользователи приборной панели дополнительно нуждаются в разрешении `agent:use`. Для ключа данных ассистента вы не чеканьте что-нибудь вручную: выберите случайный секрет, установите его как `AGENTEYE_API_KEY` на `agent` **и** как `AGENT_API_KEY` на `server`, и сервер заполняет его при запуске с фиксированным набором разрешений. Его доступ к данным только для чтения (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), и он дополнительно держит области авторства, прошедшие шлюз одобрения (`dashboards:write`, `queries:write`, `queries:run`), поэтому он может черновик и проверить сохранённые запросы и построить плитки приборной панели от имени пользователя; весь SQL всё ещё работает через роль ClickHouse только для чтения организации, поэтому это расширяет то, что ассистент может создать, а не то, какие данные он может достичь. Области фиксированы в коде и не могут быть расширены конфигурацией. Этот ключ защищён; он не может быть отключен или перегенерирован через API, только ротирован путём изменения значения и перезагрузки. Никогда не повторно используйте ключ администратора/приборной панели для этого. Полная настройка, полная ссылка на переменные окружения, опции телеметрии и модель безопасности находятся в **[enterprise-docs/assistant.md](/ru/agenteye/assistant)**. *** ## ClickHouse (требуемое хранилище аналитики) ClickHouse держит приборные панели отзывчивыми при высоких объёмах событий и позволяет редактору SQL `/queries` присоединять события, оценки и сеансы в одном хранилище. Это требуемое канонические хранилище для каждого полученного события, каждого терминального результата оценки и производных агрегатов за сеанс. PostgreSQL держит реляционные / изменяемые таблицы состояния (api\_keys, users, otp\_codes, evaluation\_jobs, dashboards, saved\_queries); аналитическая поверхность живёт в ClickHouse, так что rollup приборной панели и ваши собственные SQL запросы могут сканировать и присоединять её нативно, без кросс-БД круговых путей. Сервер отказывается загружаться без `CLICKHOUSE_URL`. ### Схема Три объекта ClickHouse создаются при запуске сервера, все идемпотентные (`CREATE IF NOT EXISTS`): * **`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`. Для обратной совместимости с сохранёнными запросами, которые ссылаются на `analytics.evaluations` / `analytics.sessions`, сервер также создаёт БД ClickHouse `analytics` с представлениями над таблицами `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` все разрешаются корректно. ### Конфигурация Поставляемые docker-compose и `deploy/base/clickhouse/` содержат сервис ClickHouse, настроенный для рабочей нагрузки AgentEye: * 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 для продакшена) ### Резервные копии Ваш полный набор данных захватывается каждую ночь в один восстанавливаемый архив, поэтому потеря кластера или хранилища восстанавливается. ClickHouse автоматически резервируется ежедневным CronJob `agenteye-backup`, который сбрасывает PostgreSQL и ClickHouse в одном пасс. ClickHouse читается по его HTTP API: `agenteye.events` и `agenteye.evaluations` сбрасываются в родном формате ClickHouse (представления и политики строк переоздаются сервером при запуске, поэтому данные таблицы полная картина) и объединяются с дампом Postgres в один сжатый архив, загруженный в ваше хранилище объектов. Корзина назначения и учётные данные облака настраиваются для каждого оверлея. См. раздел **Backups** в [enterprise-docs/kubernetes-deployment.md](/ru/agenteye/kubernetes-deployment) для конфигурации загрузки и шагов восстановления. *** ## Redis (опциональный кеш) Redis является **опциональным** общим кешем + бэкендом ограничения частоты запросов, используемым сервером и приборной панелью. При развёртывании Redis и установке `REDIS_URL` на обоих сервисах: * **Сервер** кеширует поиски аутентифицированных ключей 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 недоступен.** Каждый вызов кеша возвращает `Err` в течение ограниченного тайм-аута и вызывающий возвращается к источнику истины (Postgres на сервере, восходящий Rust сервер на приборной панели). Ограничение частоты запросов OTP возвращается на путь Postgres `COUNT(*)` на сервере (свойство безопасности сохраняется); граница OTP приборной панели открывается при сбое, пока серверная граница всё ещё удерживается. Redis выключение деградирует задержку, а не правильность. ### Конфигурация Поставляемый пакет docker-compose уже включает сервис Redis и подключает `REDIS_URL=redis://redis:6379/0` в сервер и приборную панель. Чтобы использовать внешний Redis, установите `REDIS_URL` на вашу конечную точку и удалите сервис `redis` из файла compose. ### Память + персистентность Поставляемый образ Redis работает с `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF персистентность означает, что кеш выживает перезагрузки контейнера; `everysec` это правильный баланс долговечности/производительности, потому что потеря последней секунды кеш-записей безвредна. LRU вытеснение ограничивает рост памяти. ### Когда НЕ развёртывать Redis * Одноэкземплярная разработка/QA. Внутренние кеши на сервере одного доставляют большую часть преимущества за реплику; Redis добавляет кросс-реплику, совместное использование которых одноэкземплярные настройки не нуждаются. * Air-gapped установки, где эксплуатационная стоимость запуска ещё одного сервиса перевешивает выигрыш задержки. *** ## Docker Compose (рекомендуется) `docker-compose.yml` доступен в репозитории `agenteye-enterprise/releases`. Он поднимает Postgres, сервер и приборную панель одной командой. ```bash theme={null} GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ --repo agenteye-enterprise/releases \ --pattern 'docker-compose.yml' \ --dir ./agenteye cd agenteye ``` **Переопределить значения по умолчанию через `.env`:** ``` # Используйте пароли, безопасные для 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 ``` ```bash theme={null} docker compose up -d ``` **Остановить (сохраняет объём данных):** ```bash theme={null} docker compose down ``` **Остановить и удалить все данные:** ```bash theme={null} docker compose down -v ``` *** ## Операционные настройки Маленький набор эксплуатационных рычагов, которые раньше были зафиксированы переменными окружения, теперь редактируется для каждой организации со страницы **`//settings`** приборной панели; каждая организация настраивает свою. Изменения вступают в силу в течение секунд, без перезагрузки и без переразвёртывания. | Настройка | Bootstrap переменная окружения | Что это контролирует | | ------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Допускаемые входы | `ALLOWED_EMAILS` | Email (или подстановочные знаки `*@domain.com`) разрешены получать OTP и добавляться как пользователи | | Разрешения пользователя по умолчанию | `DEFAULT_USER_PERMISSIONS` | Токены разрешений через запятую, предварительно выбранные, когда администратор открывает **+ новый пользователь**. Каждый токен должен быть одной из строк, перечисленных под [API key permissions](/ru/agenteye/api-keys). По умолчанию преустановка `standard`: доступ только для чтения плюс повседневные on-call действия (переоценить срабатывание, запустить запросы, подтвердить инциденты, использовать ассистента). | | Время жизни сеанса | `SESSION_TTL_SECS` | Как долго вход на приборную панель остаётся действительным перед повторной аутентификацией. Приборная панель переоценивает вышестоящий сеанс каждые 5 секунд, поэтому обновление разрешения на `//users` вступает в силу при следующем запросе затронутого пользователя без повторного входа. | | Время жизни одноразового кода | `OTP_TTL_SECS` | Как долго OTP / волшебная ссылка остаётся пригодной для использования | | Каналы уведомления оповещений | `ALERTS_ENABLED_CHANNELS` | Список видов каналов через запятую, которые диспетчер оповещений разрешено использовать: `email`, `slack`, `webhook`. Конфигурация для каждого оповещения всё ещё создана на `//alerts/`, но диспетчер фильтрует каждую исходящую доставку через этот набор; отключённый здесь канал сокращает с `skipped_disabled` строкой аудита. Канал `dashboard` (локальная вставка аудита) всегда разрешен. По умолчанию все три. | ### Как работает bootstrap Настройки хранятся для каждой организации в `org_settings`. При первой загрузке сервер заполняет отсутствующие строки организации по умолчанию от соответствующей переменной окружения (или разумное по умолчанию, если переменная окружения не установлена). После этого, **сохранённое значение является источником истины и переменная окружения игнорируется**; изменение переменной окружения при более позднем перезапуске не повлияет на значение живой организации, и дополнительные организации начинают с значений по умолчанию и настраивают свои. Это означает: * Для свежего развёртывания установите переменные окружения, как показано выше, и организация по умолчанию читает их при первой загрузке. * Чтобы изменить значение позже, войдите на приборную панель и отредактируйте её под `//settings`. Изменение применяется в течение секунд на всех репликах сервера; перезагрузка не нужна. * Строка журнала запуска записывает, что получило заполнение против того, что уже присутствовало, поэтому вы можете подтвердить, что bootstrap сработал: ```text theme={null} INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` #### Семантика входа между организациями Сеанс и OTP глобальны пользователю, а не одной организации, поэтому два правила примирения параметров для каждой организации во время входа: * **Время жизни сеанса / OTP**: самое строгое (кратчайшее) время жизни среди организаций, которым принадлежит пользователь, выигрывает. * **Допускаемые входы**: шлюз ИЛИ каждый список разрешений организации вместе с членством в организации: пользователь может запросить OTP, если список разрешений любой организации допускает их email **или** они уже являются членом любой организации. ### Разрешения Доступ к странице `//settings` контролируется двумя разрешениями: * `settings:read`: видеть страницу и текущие значения. * `settings:write`: сохранить изменения. Начальный пользователь администратора (заполняется из `ADMIN_EMAIL`) получает оба автоматически вместе со всеми остальными разрешениями. Предоставьте их другим пользователям из `//users` по мере необходимости. *** ## Организации (мультитенантность) Одно развёртывание может обслуживать несколько изолированных **организаций** (арендаторы); каждая строка данных принадлежит ровно одной организации и изоляция обеспечивается в engine БД. Одноарендаторная установка не нуждается ни в чём здесь; все данные живут во встроенной организации `default`. (Вы можете дать этой организации более дружественное имя и URL-слаг, поэтому она живёт например в `/acme` вместо `/default`, установив `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` перед первой загрузкой или переименовав её в любое время с `agenteye-orgctl org rename`.) **Подготовка арендатора доступна только оператору.** Организации и их членства создаются и управляются CLI **`agenteye-orgctl`**, который поставляется **внутри образа сервера** (рядом с `agenteye-server`) и работает **внутри существующего pod сервера**; там нет **отдельного pod/Job, нет HTTP API и нет кнопки приборной панели**. Он повторно использует `DATABASE_URL` сервера, `CLICKHOUSE_URL` и `ORG_CH_SECRET`. ```bash theme={null} # 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 ``` Доступные команды: `org create | list | rename | delete | purge` и `member add | list | update | remove`, со встроенными наборами разрешений `admin`, `standard` и `read-only`. Добавленные члены получат OTP при первом входе на приборную панель. **Перед созданием второй организации:** установите сильный, стабильный `ORG_CH_SECRET` (команда `org create` отказывается работать со встроенным значением по умолчанию для разработки) и убедитесь, что Postgres **15+**. **Без изменений:** ключи API для каждой организации всё ещё чеканятся в приборной панели/API членами организации; только цикл жизни организации + член перешёл на CLI. Полная справка команд и отработанный пример: **[enterprise-docs/tenant-management.md](/ru/agenteye/tenant-management)**. *** ## Заполнение окна контекста Каждое событие `model_response` показывает **таблетку заполнения контекста** — входные плюс выходные токены в процентах от окна контекста этой модели. Диапазоны: `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) и `reset context` (75–100%). AgentEye автоматически разрешает распространённые ID моделей, поэтому начальная конфигурация не требуется. Каждая модель, которую отправляет организация, появляется под **Settings → model context windows**. Пользователи с `settings:write` могут переопределить его окно или добавить приватную/proxy модель (0–1 000 000 токен); `0` означает неизвестно и подавляет таблетку. Изменения применяются к недавно полученным событиям. Пользователи с `settings:read` могут просмотреть список. Новые события получают заполнение с момента обновления. Чтобы также заполнить **исторические** события (и список для каждой модели) для существующего развёртывания, запустите одноразовую заливку — она поставляется внутри образа сервера (как `agenteye-orgctl`) и работает в существующем pod сервера: ```bash theme={null} # предпросмотр (печатает мутацию для каждой организации, ничего не меняет): 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 ``` Это идемпотентно (безопасно для повторного запуска) и повторно использует `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` из pod. Повторно запустите его после редактирования окон модели, если вы хотите переосчитать существующие события. *** ## Соображения по продакшену * **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](/ru/agenteye/health-monitoring). *** ## Доступные теги образов | Тег | Описание | | ------------- | ------------------------------------------------------------------------------ | | `latest` | Последний стабильный релиз | | `beta-latest` | Последний пред-релиз (бета) | | `v` | Фиксированная версия, например `v0.0.1-beta.48` (рекомендуется для продакшена) |