Dağıtım

​

Mimari Özeti

  [ AI agent makineleri ]                [ Kendi altyapınız ]

    Python SDK
       |  JSONL yazar                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (ilişkisel depo)     |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (etkinlikler / analitikler)|
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (isteğe bağlı)|
                      | Pano      |           +----------------------+
                      +-----------+

• Sunucu: Rust HTTP hizmeti; etkinlik toplamalarını alır, ClickHouse’a yazar ve ilişkisel durumu PostgreSQL’de tutar.
• Pano: Next.js web uygulaması; sunucu API’si aracılığıyla okur ve yazar.
• agenteye-collector: sunucu ana bilgisayarında değil, agent makinelerinde dağıtılır.
• Postgres 15+: GEREKLI. (14’ten çok kiracılı sürümde yükseltildi; org-üyelik şeması ON DELETE SET NULL yabancı anahtarını kullanan bir sütun listesi kullanır ve bu Postgres 15+ gerektirir. Bu sürümü dağıtmadan önce Postgres’i yükseltin.) OLTP durumunu saklar: api_keys, users, sessions, evaluation_jobs (sıra), dashboards, saved_queries, otp_codes ve çok kiracılı tablolar orgs, org_memberships, org_settings.
• ClickHouse 24+: GEREKLI. Her alınan etkinlik için analitik deposu. Motor: ReplacingMergeTree, aya göre bölümlendirilmiş, (session_id, ts, dedup_key) ile sıralanmış. Sunucu CLICKHOUSE_URL aracılığıyla bağlanır; paketlenmiş deploy/base/clickhouse/ performans ayarlı tek düğüm yapılandırması içerir. Çok kiracılı gereksinim: paketlenmiş yapılandırma SQL erişim yönetimini etkinleştirir ve users_without_row_policies_can_read_rows=false ayarını yapar, böylece sunucu kuruluş başına bir salt okunur ClickHouse kullanıcısı ve satır ilkesi oluşturabilir (SQL editörü ve AI ajanı için motor tarafından zorlanmış izolasyon sınırı). Kendi ClickHouse yapılandırmanızı sağlarsanız bu ayarları aktarın (bkz. deploy/base/clickhouse/configmap.yaml).
• Redis 7+: isteğe bağlı paylaşılan önbellek + hız sınırı arka ucu. Sunucu ve pano her ikisi de REDIS_URL aracılığıyla bağlanır. Mevcut değilse, her ikisi de Postgres’e yapılan yollarla incelikle düşer. Aşağıda Redis (isteğe bağlı önbellek) bölümüne bakın.

​

Sunucu

​

Görüntüyü çekin

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

Mevcut yapılar beta-latest altında yayımlanır; latest yalnızca kararlı sürümlere atanır. Üretim için belirli bir :v<version> etiketine sabitle; bkz. Kullanılabilir Resim Etiketleri.

​

Ortam değişkenleri

​

Çalıştırma

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

​

Sağlık kontrolü

GET /health    # canlılık  - işlem başladıktan sonra her zaman {"status":"ok"}
GET /ready     # hazırlık - Postgres + ClickHouse ulaşıldığında 200, aksi takdirde 503

​

E-posta sihirli bağlantı URL’si

1. X-AgentEye-Dashboard-Url başlığı: panonun kendi genel kaynağından /api/auth/otp/request proxy tarafından otomatik olarak ayarlayır. Aynı kaynak dağıtımında (sunucu ve pano bir ön uç ardında bir ana bilgisayarı paylaşır, proxy başlıklarını iletir), hiçbir yapılandırma gerekmez.
2. DASHBOARD_URL ortam değişkeni: panonuz sunucunun OTP istek uç noktasının gördüğü orijinin farklı bir kaynağında erişilebilirse (bölünmüş api.example.com / app.example.com), veya ön ucunuz genel ana bilgisayarı pano pod’una yaymıyorsa (bu nedenle request.nextUrl.origin aksi takdirde 0.0.0.0:3000 gibi joker bir bağlamaya çözecektir) ayarlayın. Örnek: DASHBOARD_URL=https://app.example.com.
3. Varsayılan: https://app.befailproof.ai, yalnızca yukarıdaki her ikisi yoksa kullanılır.

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

​

Pano

​

Görüntüyü çekin

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

​

Ortam değişkenleri

​

Çalıştırma

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

​

Telemetri & Gizlilik

• Agent, oturum veya etkinlik verileri hiçbir zaman altyapınızdan ayrılmaz. Yalnızca pano UI kullanımı raporlanır. Sayfa URL’leri göndermeden önce tanımlayıcılardan çıkarılır ve operatörler asla e-posta tarafından değil, yalnızca opak bir iç kimliği tarafından tanımlanır.
• Telemetri varsayılan olarak etkindir. Tamamen kapatmak için panonun konteynerinde AE_ANALYTICS_DISABLED=1 ayarlayın ve yeniden başlatın.
• Analitikler panonun kendi /ingest yoluna gönderilir, pano PostHog’a ters proxy yapar (https://us.i.posthog.com). İstekleri birinci taraf olarak tutmak, tarayıcı reklam engelleyicilerin bunları bırakmaması anlamına gelir. Pano konteyneri PostHog’a giden erişime ihtiyaç duyar; engellenmişse telemetri sessizce hiçbir şey yapmaz ve pano etkilenmez.

​

AI Asistanı (isteğe bağlı)

​

ClickHouse (gerekli analitik deposu)

​

Şema

• agenteye.events: ReplacingMergeTree(ingested_at), toYYYYMM(ts) ile bölümlendirilmiş, (session_id, ts, dedup_key) ile sıralanmış. Yinelenen eklenmeler (toplayıcı yeniden denemeleri) birleştirme zamanında tek satıra çöker; sunucu her etkinlik için belirlenimci bir SHA-256 dedup_key hesaplar, böylece yeniden denenmeler güvenlidir.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), toYYYYMM(finished_at) ile bölümlendirilmiş, (session_id, finished_at, dedup_key) ile sıralanmış. Her terminal değerlendirme sonucu için değerlendirici ardışık düzen tarafından bir kez yazılır. events ile aynı dedup-anahtar modeli.
• agenteye.agent_sessions: fiziksel bir tablo değil, agenteye.events üzerindeki bir VIEW. Her sütun türetilmiş (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count(), vb.). Etkinlik başına upsert yok ve ayrı backfill yok; görünüm otomatik olarak events içinde ne varsa yansıtır.

​

Yapılandırma

• 2 GiB istenen / 4 GiB limit bellek paketlenmiş temel ön ek (küçük POC/hazırlık düğümlerine sığmak için boyutlandırılmış); üretim müşterileri ön ek tekrar olmalıdır — önerilen alt sınır 2c / 4Gi istek, 6c / 8Gi sınırıdır. max_server_memory_usage_to_ram_ratio=0.9
• 5 GiB mark önbellek + 8 GiB sıkıştırılmamış önbellek
• 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 (desteklenen çekirdeklerde io_uring)
• fsync_metadata=0: at-least-once alım + ReplacingMergeTree dedup nedeniyle kabul edilebilir
• query_log 30 günlük TTL etkinleştirilmiş; query_thread_log kaldırılmış (yüksek QPS’de pahalı)
• max_execution_time=30 kullanıcı tarafı sorguları için
• StatefulSet şablonunda 100 GiB PVC (müşteri ön ekleri üretim için hızlı SSD depolama sınıfına geçersiz kılmalıdır)

​

Yedeklemeler

​

Redis (isteğe bağlı önbellek)

• Sunucu kimliği doğrulanmış API anahtarı aramaları, /events/environments + /evaluations/environments listeleri, /events/latency_aggregate açılmış (panonun yokladığı en ağır sorgu), /sessions listesi önbelleğe alır ve OTP istek hız sınırlamasını Postgres COUNT(*) adresinden Redis INCR + EXPIRE adresine değiştirir.
• Pano validateSession() sonuçlarını çoğaltmalar arasında önbelleğe alır, böylece tipik sayfa yükü sorunları olan 10-20 authed API çağrısı tüm bir yukarı akış oturumu kontrolü paylaşır. Ayrıca panonun kenarında OTP istek ve OTP doğrulama hız sınırı tutar.

​

Yapılandırma

​

Bellek + kalıcılık

​

Redis dağıtmamak için

• Tek örnek geliştirme/QA. Sunucuda işlem içi önbellekler tek başına çoğu per-çoğaltma avantajını teslim eder; Redis, tek örnek kurulumları gereken çapraz çoğaltma paylaşımını ekler.
• Bir hizmeti daha çalıştırmanın operasyonel maliyeti gecikme kazancından daha ağır olan hava geçitli kurulumlar.

​

Docker Compose (önerilen)

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

# URL-safe parolalar kullanın (/, +, veya = karakterleri yok).
# Oluştur: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Pano kimlik doğrulması
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# OTP e-postaları için SMTP (OTP kodlarını stdout'a kaydetmek için atla)
# 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

​

İşletimsel ayarlar

​

Önyükleme nasıl çalışır

• Yeni bir dağıtım için, ortam değişkenlerini yukarıda gösterildiği gibi ayarlayın ve varsayılan org ilk önyüklemede onları okur.
• Bir değeri daha sonra değiştirmek için panonuya giriş yapın ve /<org>/settings altında düzenleyin. Değişiklik saniyeler içinde tüm sunucu çoğaltmaları arasında etkili olur; yeniden başlatma gerekmez.
• Bir başlangıç günlük satırı ne tohurnlandığını ve ne zaten var olduğunu kaydeder, böylece önyüklemenin etkili olduğunu doğrulayabilirsiniz:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Kuruluşlar arasında oturum açma anlambilimi

• Oturum / OTP yaşam süresi: en katı (en kısa) yaşam süresi kullanıcının ait olduğu org’lar arasında kazanır.
• İzin verilen oturum açmalar: kapı VEYA’lar her org’un izin listesi kuruluş üyeliğiyle: bir kullanıcı herhangi bir org’un izin listesi e-postalarını kabul ederse OTP isteyebilir veya zaten herhangi bir org’un üyeleri.

​

İzinler

• settings:read: sayfayı görmek ve geçerli değerleri.
• settings:write: değişiklikleri kaydet.

​

Kuruluşlar (çok kiracılılık)

# Docker Compose - çalışan sunucu hizmetine 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 - çalışan sunucu Dağıtımı içine exec:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

Bağlam penceresi doldurma

# ön izleme (per-org mutasyonu yazdırır, hiçbir şey değişmez):
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run
# uygula:
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window
# docker compose:
docker compose exec server agenteye-backfill-context-window

​

Üretim Hususları

• Postgres: Yönetilen Postgres hizmetini veya düzenli yedeklemeleri olan ayrılmış bir örneği kullanın. DATABASE_URL sslmode=require dahil olmak üzere tüm standart libpq parametrelerini destekler, şifreli bağlantılar için.
• TLS: Sunucu ve panoyu TLS’yi sonlandıran ters proxy’nin (nginx, Caddy, Traefik) ardına koyun.
• Güvenlik duvarı: Sunucu portu (varsayılan 8080) yalnızca toplayıcı makinelerinden ve pano ana bilgisayarından erişilebilir olmalıdır, genel İnternet’ten değil.
• Yönetici anahtarı: ADMIN_KEY güçlü rastgele gizli ayarlayın. Önyüklemeden sonra, yönetici anahtarını her yerde kullanmak yerine toplayıcılar ve pano için ayrılmış kapsamlı anahtarlar oluştu