배포

​

아키텍처 개요

  [ 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: Rust HTTP 서비스. 이벤트 배치를 수신하고 ClickHouse에 기록하며 PostgreSQL에서 관계형 상태를 유지합니다.
• Dashboard: Next.js 웹 앱. 서버 API를 통해서만 읽기/쓰기를 수행합니다.
• agenteye-collector: 서버 호스트가 아닌 에이전트 머신에 배포됩니다.
• Postgres 15+: 필수 항목입니다. (멀티테넌트 릴리스에서 14에서 상향; org 멤버십 스키마가 Postgres 15+ 전용인 컬럼 목록 ON DELETE SET NULL 외래 키를 사용합니다. 이 버전 배포 전에 Postgres를 업그레이드하세요.) OLTP 상태를 저장합니다: api_keys, users, sessions, evaluation_jobs(큐), dashboards, saved_queries, otp_codes, 그리고 멀티테넌트 테이블 orgs, org_memberships, org_settings.
• ClickHouse 24+: 필수 항목입니다. 수집된 모든 이벤트의 분석 저장소입니다. 엔진: ReplacingMergeTree, 월별 파티션, (session_id, ts, dedup_key) 순으로 정렬됩니다. 서버는 CLICKHOUSE_URL을 통해 연결합니다. 번들로 제공되는 deploy/base/clickhouse/에는 성능 최적화된 단일 노드 구성이 포함됩니다. 멀티테넌트 요구사항: 번들 구성은 SQL 액세스 관리와 users_without_row_policies_can_read_rows=false를 활성화하여 서버가 조직마다 읽기 전용 ClickHouse 사용자와 행 정책을 생성할 수 있도록 합니다(SQL 에디터 및 AI 에이전트의 엔진 수준 격리 경계). 자체 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    # 활성 상태 - 프로세스가 시작되면 항상 {"status":"ok"}
GET /ready     # 준비 상태 - Postgres + ClickHouse에 연결 가능하면 200, 아니면 503

​

이메일 매직 링크 URL

1. X-AgentEye-Dashboard-Url 헤더: 대시보드의 /api/auth/otp/request 프록시가 자체 공개 오리진에서 자동으로 설정합니다. 동일 오리진 배포(서버와 대시보드가 프록시 헤더를 전달하는 하나의 인그레스 뒤에서 호스트를 공유)에서는 구성이 필요하지 않습니다.
2. DASHBOARD_URL 환경 변수: 대시보드가 서버의 OTP 요청 엔드포인트가 보는 것과 다른 오리진에서 접근 가능하거나(api.example.com / app.example.com 분리), 인그레스가 공개 호스트를 대시보드 파드에 전파하지 않는 경우(그러면 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로만 식별됩니다.
• 텔레메트리는 기본적으로 활성화되어 있습니다. 완전히 끄려면 대시보드 컨테이너에 AE_ANALYTICS_DISABLED=1을 설정하고 재시작하세요.
• 분석은 대시보드의 /ingest 경로로 전송되며, 대시보드가 이를 PostHog(https://us.i.posthog.com)로 역방향 프록시합니다. 요청을 퍼스트파티로 유지하면 브라우저 광고 차단기가 이를 차단하지 않습니다. 대시보드 컨테이너는 PostHog로 아웃바운드 접근이 필요합니다. 차단된 경우 텔레메트리는 조용히 동작하지 않으며 대시보드는 영향을 받지 않습니다.

​

AI 어시스턴트 (선택 사항)

​

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) 순 정렬. 평가자 파이프라인이 최종 평가 결과당 한 번 씁니다. events와 동일한 중복 제거 키 모델.
• agenteye.agent_sessions: 물리적 테이블이 아닌 agenteye.events에 대한 VIEW. 모든 컬럼이 파생됩니다(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 GiB / 제한 4 GiB 메모리(소규모 POC/스테이징 노드에 맞게 크기 조정). 프로덕션 고객은 오버레이를 업사이징해야 합니다. 권장 최소 사양은 요청 2c/4Gi, 제한 6c/8Gi입니다. max_server_memory_usage_to_ram_ratio=0.9
• 5 GiB 마크 캐시 + 8 GiB 비압축 캐시
• 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: 최소 한 번 수집 + ReplacingMergeTree 중복 제거 때문에 허용됨
• 30일 TTL을 가진 query_log 활성화. 높은 QPS에서 비용이 많이 드는 query_thread_log 제거됨
• 사용자 측 쿼리에 대한 max_execution_time=30
• StatefulSet 템플릿에 100 GiB PVC (고객 오버레이는 프로덕션을 위해 빠른 SSD 스토리지 클래스로 재정의해야 함)

​

백업

​

Redis (선택적 캐시)

• 서버는 인증된 API 키 조회, /events/environments + /evaluations/environments 목록, /events/latency_aggregate 롤업(대시보드가 폴링하는 가장 무거운 쿼리), /sessions 목록을 캐시하고, OTP 요청 속도 제한을 Postgres COUNT(*)에서 Redis INCR + EXPIRE로 전환합니다.
• 대시보드는 validateSession() 결과를 캐시하여 일반적인 페이지 로드에서 발생하는 10-20개의 인증된 API 호출이 모두 하나의 업스트림 세션 확인을 공유합니다. 또한 대시보드 엣지에서 OTP 요청 및 확인을 속도 제한합니다.

​

구성

​

메모리 + 지속성

​

Redis를 배포하지 않아야 할 때

• 단일 인스턴스 개발/QA 환경. 서버의 인프로세스 캐시만으로도 복제본별 이점의 대부분을 제공합니다. Redis는 단일 인스턴스 설정에서 필요하지 않은 복제본 간 공유를 추가합니다.
• 추가 서비스 운영 비용이 레이턴시 이점보다 큰 에어갭 설치 환경.

​

Docker Compose (권장)

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

# Use URL-safe passwords (no /, +, or = characters).
# Generate with: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Dashboard authentication
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP for OTP emails (omit to log OTP codes to stdout)
# SMTP_HOST=smtp.yourprovider.com
# SMTP_PORT=587
# SMTP_USERNAME=your-smtp-user
# SMTP_PASSWORD=your-smtp-password
# SMTP_FROM=noreply@yourcompany.com

RUST_LOG=info

docker compose up -d

docker compose down

docker compose down -v

​

운영 설정

​

부트스트랩 작동 방식

• 새 배포의 경우 위에 표시된 대로 환경 변수를 설정하면 기본 org가 첫 번째 부팅 시 읽습니다.
• 나중에 값을 변경하려면 대시보드에 로그인하고 /<org>/settings에서 편집하세요. 변경 사항은 수 초 내에 모든 서버 복제본에 적용됩니다. 재시작이 필요하지 않습니다.
• 시작 로그 라인에 시드된 것과 이미 존재하는 것이 기록되므로 부트스트랩이 적용되었는지 확인할 수 있습니다:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

조직 간 로그인 의미론

• 세션/OTP 유효 기간: 사용자가 속한 org 중 가장 엄격한(가장 짧은) 유효 기간이 적용됩니다.
• 허용된 로그인: 게이트는 모든 org의 허용 목록과 org 멤버십을 OR로 결합합니다. 이메일이 어느 org의 허용 목록에든 허용되거나 이미 어느 org의 멤버이면 OTP를 요청할 수 있습니다.

​

권한

• settings:read: 페이지와 현재 값을 볼 수 있습니다.
• settings:write: 변경 사항을 저장할 수 있습니다.

​

Organizations (멀티테넌시)