Triển khai

​

Tổng quan kiến trúc

  [ 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: Dịch vụ HTTP Rust; nhận các lô sự kiện, ghi chúng vào ClickHouse và duy trì trạng thái quan hệ trong PostgreSQL.
• Dashboard: Ứng dụng web Next.js; đọc và ghi độc quyền thông qua API máy chủ.
• agenteye-collector: triển khai trên các máy agent, không phải trên máy chủ.
• Postgres 15+: REQUIRED. (Được nâng cấp từ 14 trong bản phát hành đa thuê; lược đồ thành viên tổ chức sử dụng khóa ngoại ON DELETE SET NULL danh sách cột, chỉ có trong Postgres 15+. Nâng cấp Postgres trước khi triển khai phiên bản này.) Lưu trữ trạng thái OLTP: api_keys, users, sessions, evaluation_jobs (hàng đợi), dashboards, saved_queries, otp_codes, cộng với các bảng đa thuê orgs, org_memberships, org_settings.
• ClickHouse 24+: REQUIRED. Kho lưu trữ phân tích cho mỗi sự kiện nhập. Công cụ: ReplacingMergeTree, được phân vùng theo tháng, sắp xếp theo (session_id, ts, dedup_key). Máy chủ kết nối qua CLICKHOUSE_URL; deploy/base/clickhouse/ được đóng gói với một cấu hình nút đơn được điều chỉnh hiệu suất. Yêu cầu đa thuê: cấu hình được đóng gói cho phép quản lý quyền truy cập SQL + users_without_row_policies_can_read_rows=false để máy chủ có thể tạo một người dùng ClickHouse chỉ đọc + chính sách hàng cho mỗi tổ chức (ranh giới cô lập do công cụ thực thi cho trình chỉnh sửa SQL và agent AI). Nếu bạn cung cấp cấu hình ClickHouse của riêng mình, hãy chuyển các cài đặt này (xem deploy/base/clickhouse/configmap.yaml).
• Redis 7+: tùy chọn bộ đệm chung + phía sau giới hạn tốc độ. Máy chủ và bảng điều khiển đều kết nối qua REDIS_URL. Nếu không có, cả hai sẽ giảm thành graceful thành các đường Postgres. Xem Redis (bộ đệm tùy chọn) dưới đây.

​

Server

​

Lấy hình ảnh

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

Các bản dựng hiện tại xuất bản dưới beta-latest; latest chỉ được gán cho các bản phát hành ổn định. Đối với sản xuất, hãy ghim một thẻ phiên bản cụ thể :v<version>; xem Available Image Tags.

​

Biến môi trường

​

Chạy

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

​

Kiểm tra sức khỏe

GET /health    # liveness  - luôn {"status":"ok"} khi quy trình lên
GET /ready     # readiness - 200 khi Postgres + ClickHouse có thể truy cập được, nếu không 503

​

Email magic-link URL

1. Tiêu đề X-AgentEye-Dashboard-Url: đặt tự động bằng proxy /api/auth/otp/request của bảng điều khiển từ gốc công khai của riêng nó. Trong một bản triển khai cùng gốc (máy chủ và bảng điều khiển chia sẻ một máy chủ đằng sau một ingress chuyển tiếp tiêu đề proxy), không cần cấu hình.
2. Biến DASHBOARD_URL env: đặt điều này nếu bảng điều khiển của bạn có thể truy cập được trên một gốc khác so với gốc mà điểm cuối yêu cầu OTP của máy chủ nhìn thấy (chia api.example.com / app.example.com), hoặc nếu ingress của bạn không truyền máy chủ công khai vào pod bảng điều khiển (vì vậy request.nextUrl.origin sẽ khác cách giải quyết một ràng buộc ký tự đại diện như 0.0.0.0:3000). Ví dụ: DASHBOARD_URL=https://app.example.com.
3. Mặc định: https://app.befailproof.ai, được sử dụng chỉ nếu không có cái nào ở trên.

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

​

Bảng điều khiển

​

Lấy hình ảnh

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

​

Biến môi trường

​

Chạy

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

​

Telemetry & privacy

• Dữ liệu agent, phiên hoặc sự kiện không bao giờ rời khỏi cơ sở hạ tầng của bạn. Chỉ sử dụng UI bảng điều khiển được báo cáo. URL trang được loại bỏ các định danh trước khi gửi, và các toán tử được xác định chỉ bằng một id nội bộ opaque, không bao giờ bằng email.
• Telemetry được bật theo mặc định. Để tắt nó hoàn toàn, hãy đặt AE_ANALYTICS_DISABLED=1 trên container bảng điều khiển và khởi động lại.
• Phân tích được gửi tới đường dẫn /ingest của bảng điều khiển, mà bảng điều khiển reverse-proxy tới PostHog (https://us.i.posthog.com). Giữ yêu cầu bên thứ nhất có nghĩa là trình chặn quảng cáo trình duyệt không thả chúng. Container bảng điều khiển cần quyền truy cập gửi đi tới PostHog; nếu nó bị chặn, telemetry im lặng không làm gì và bảng điều khiển không bị ảnh hưởng.

​

Trợ lý AI (tùy chọn)

​

ClickHouse (kho lưu trữ phân tích bắt buộc)

​

Lược đồ

• agenteye.events: ReplacingMergeTree(ingested_at), được phân vùng theo toYYYYMM(ts), sắp xếp theo (session_id, ts, dedup_key). Các bản chèn trùng (bộ sưu tập thử lại) sụp đổ thành một hàng tại thời gian hợp nhất; máy chủ tính toán dedup_key SHA-256 xác định cho mỗi sự kiện để các lần thử lại an toàn.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), được phân vùng theo toYYYYMM(finished_at), sắp xếp theo (session_id, finished_at, dedup_key). Được viết một lần cho mỗi kết quả đánh giá thiết bị đầu cuối bởi đường dẫn đánh giá. Cùng mô hình dedup-key như events.
• agenteye.agent_sessions: một VIEW trên agenteye.events, không phải bảng vật lý. Mỗi cột được dẫn xuất (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count(), v.v.). Không upsert mỗi sự kiện và không backfill riêng; chế độ xem tự phản ánh bất cứ điều gì nằm trong events.

​

Cấu hình

• Bộ nhớ 2 GiB được yêu cầu / giới hạn 4 GiB trong lớp phủ cơ sở được gửi (kích thước phù hợp với các nút POC/staging nhỏ); khách hàng sản xuất nên lớp phủ lên — tầng được đề xuất là yêu cầu 2c / 4Gi, giới hạn 6c / 8Gi. max_server_memory_usage_to_ram_ratio=0.9
• Bộ nhớ cache 5 GiB + bộ đệm không nén 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 trên các nhân được hỗ trợ)
• fsync_metadata=0: chấp nhận được vì nhập ít nhất một lần + dedup ReplacingMergeTree
• query_log được bật với TTL 30 ngày; query_thread_log bị xóa (đắt tiền ở QPS cao)
• max_execution_time=30 cho các truy vấn phía người dùng
• 100 GiB PVC ở mẫu StatefulSet (lớp phủ khách hàng NÊN ghi đè thành lớp lưu trữ SSD nhanh cho sản xuất)

​

Sao lưu

​

Redis (bộ đệm tùy chọn)

• Server lưu vào bộ đệm tra cứu khóa API được xác thực, danh sách /events/environments + /evaluations/environments, kết tập /events/latency_aggregate (truy vấn nặng nhất mà bảng điều khiển thăm dò), danh sách /sessions và chuyển đổi giới hạn tốc độ yêu cầu OTP từ COUNT(*) Postgres thành INCR + EXPIRE Redis.
• Dashboard lưu vào bộ đệm kết quả validateSession() để 10-20 lệnh gọi API được xác thực một tải trang điển hình tất cả chia sẻ một kiểm tra phiên thượng lưu. Nó cũng giới hạn tốc độ yêu cầu OTP và xác minh OTP tại cạnh bảng điều khiển.

​

Cấu hình

​

Bộ nhớ + tính bền vững

​

Khi KHÔNG triển khai Redis

• Dev/QA instance đơn lẻ. Bộ đệm trong quy trình trên máy chủ một mình cung cấp hầu hết lợi ích mỗi bản sao; Redis thêm chia sẻ xuyên bản sao mà thiết lập đơn instance không cần.
• Cài đặt không kết nối trong đó chi phí hoạt động chạy một dịch vụ khác vượt quá lợi thế độ trễ.

​

Docker Compose (được khuyến nghị)

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

# Sử dụng mật khẩu an toàn URL (không /, +, hoặc = ký tự).
# Tạo với: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Xác thực bảng điều khiển
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP cho email OTP (bỏ qua để ghi nhật ký mã OTP vào 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

​

Cài đặt hoạt động

​

Quá trình khởi động hoạt động

• Đối với triển khai mới, hãy đặt biến env như hiển thị ở trên và tổ chức mặc định đọc chúng trên khởi động đầu tiên.
• Để thay đổi giá trị sau đó, hãy đăng nhập vào bảng điều khiển và chỉnh sửa nó dưới /<org>/settings. Thay đổi áp dụng trong vòng vài giây trên tất cả các bản sao máy chủ; không cần khởi động lại.
• Dòng nhật ký khởi động ghi lại những gì đã được hạt giống so với những gì đã có, vì vậy bạn có thể xác nhận rằng khởi động có hiệu lực:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Ngữ nghĩa đăng nhập trên các tổ chức

• Thời lượng phiên / OTP: thời lượng (ngắn nhất) nghiêm ngặt nhất trong những tổ chức mà người dùng thuộc về win.
• Cho phép đăng nhập: cổng ORs mỗi danh sách cho phép của tổ chức với thành viên tổ chức: người dùng có thể yêu cầu OTP nếu bất kỳ danh sách cho phép của tổ chức nào thừa nhận email của họ hoặc họ đã là thành viên của bất kỳ tổ chức nào.

​

Quyền

• settings:read: xem trang và các giá trị hiện tại.
• settings:write: lưu các thay đổi.