デプロイメント

​

アーキテクチャ概要

  [ AI エージェントマシン ]                  [ お客様のインフラ ]

    Python SDK
       |  JSONL を書き込み                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (リレーショナルストア) |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (イベント / 分析)    |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (オプション) |
                      | 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 のみのパスに graceful にデグレードします。下記の 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<バージョン> タグを固定することを推奨します。利用可能なイメージタグを参照してください。

​

環境変数

​

実行

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 プロキシが独自のパブリックオリジンから自動設定します。同一オリジンのデプロイ（サーバーとダッシュボードが 1 つのイングレスの背後でホストを共有し、プロキシヘッダーを転送している場合）では、設定不要です。
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) 順。評価パイプラインによって終端評価結果ごとに 1 回書き込まれます。events と同じ dedup キーモデルです。
• agenteye.agent_sessions: agenteye.events 上のビュー（物理テーブルではありません）。すべてのカラムは派生（started_at = min(ts)、last_event_at = max(ts)、ended_at = max(event_type='agent_end' の場合 ts、それ以外 NULL)、event_count = count() など）。イベントごとのアップサートや別途バックフィルはなく、ビューは 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: at-least-once インジェスト + ReplacingMergeTree dedup のため許容可能
• query_log は 30 日 TTL で有効。query_thread_log は削除済み（高 QPS でコストが高い）
• ユーザーサイドクエリに 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 呼び出しが 1 回のアップストリームセッションチェックを共有できるようにします。また、ダッシュボードエッジで OTP リクエストと 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

# URL セーフなパスワードを使用してください（/、+、= 文字を含まない）。
# 生成方法: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# ダッシュボード認証
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# OTP メール用 SMTP（省略すると OTP コードが 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: 変更を保存できます。

​

組織（マルチテナント）

# 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 - 実行中のサーバー Deployment に exec で入る:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

コンテキストウィンドウの使用率

# プレビュー（org ごとのミューテーションを表示し、何も変更しない）:
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 は暗号化接続のための sslmode=require を含むすべての標準 libpq パラメーターをサポートします。
• TLS: TLS を終端するリバースプロキシ（nginx、Caddy、Traefik）の背後にサーバーとダッシュボードを配置してください。
• **ファ