> ## 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 エージェントマシン ] [ お客様のインフラ ] 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（オプションキャッシュ）** を参照してください。 *** ## サーバー ### イメージの取得 ```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<バージョン>` タグを固定することを推奨します。[利用可能なイメージタグ](#available-image-tags)を参照してください。 ### 環境変数 | 変数 | 必須 | デフォルト | 説明 | | --------------------------------------------- | ------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABASE_URL` | はい | なし | Postgres DSN。スキーム `postgres://` の標準 libpq 接続文字列形式。`?sslmode=require` などの libpq パラメーターをサポート。パスワードに `/`、`+`、`=` を含めないでください。URL セーフなパスワードの生成には `openssl rand -hex` を使用してください。 | | `ADMIN_KEY` | いいえ | なし | ブートストラップ管理者 API キー。起動のたびにすべての権限でアップサートされます。値を変更して再起動することでローテーションできます。 | | `LISTEN_ADDR` | いいえ | `0.0.0.0:8080` | バインドする TCP アドレス | | `MAX_BODY_BYTES` | いいえ | `134217728`（128 MB） | リクエストボディの最大サイズ | | `ADMIN_EMAIL` | いいえ | なし | ブートストラップ管理者ユーザーのメールアドレス。起動のたびにすべての権限でアップサートされ、保護済みとしてマーク（ダッシュボード/API 経由での無効化や権限変更不可）。ブートストラップ管理者をローテーションするには `ADMIN_EMAIL` を変更して再起動してください。新しいメールアドレスが保護済みとしてアップサートされ、以前のものはデータベースで手動クリアされるまで保護が維持されます。 | | `ALLOWED_EMAILS` | いいえ | なし（全て拒否） | ユーザー作成とログインに許可されるメールのカンマ区切りリスト。完全なアドレス（`user@example.com`）とドメインワイルドカード（`*@example.com`）をサポート。未設定の場合、ユーザーの作成とログインはすべて不可。**初回起動時のみのシード**: 初回起動時にデフォルト org のアローリストをシードし、以降は各 org の [`//settings`](#operational-settings) ページが信頼できる情報源となり、この環境変数の変更は無効になります。 | | `SMTP_HOST` | いいえ | なし | OTP メール送信用 SMTP サーバーのホスト名。未設定の場合、OTP コードは stdout にログ出力されます。 | | `SMTP_PORT` | いいえ | `587` | SMTP サーバーポート | | `SMTP_USERNAME` | いいえ | なし | SMTP 認証ユーザー名 | | `SMTP_PASSWORD` | いいえ | なし | SMTP 認証パスワード | | `SMTP_FROM` | いいえ | なし | OTP メールの送信元メールアドレス | | `SMTP_TLS` | いいえ | STARTTLS | 明示的に無効にしない限り STARTTLS が使用されます: `false` または `0` でプレーンテキスト（TLS なし）。それ以外の値（未設定を含む）で STARTTLS が有効になります。 | | `DASHBOARD_URL` | いいえ | 組み込みデフォルト | OTP メールのマジックリンクおよびアラート通知のインシデントマジックリンク生成に使用するダッシュボードのオリジン。未設定の場合、組み込みデフォルトにフォールバック（OTP のみ、まずダッシュボード由来のリクエストオリジンを試みます）。ダッシュボードと API が別ドメインの場合、メールと Slack/インシデントリンクが正しいダッシュボードを指すよう設定してください。下記の **メールマジックリンク URL** を参照。ほとんどのオペレーターは設定不要です。 | | `SESSION_TTL_SECS` | いいえ | `86400`（24 時間） | ダッシュボードセッションの有効期間（秒）。**初回起動時のみのシード**: 初回デプロイ後は [`//settings`](#operational-settings) で org ごとに編集可能。 | | `OTP_TTL_SECS` | いいえ | `600`（10 分） | OTP コードの有効期間（秒）。**初回起動時のみのシード**: 初回デプロイ後は [`//settings`](#operational-settings) で org ごとに編集可能。 | | `REDIS_URL` | いいえ | なし | オプションの共有キャッシュ + レート制限バックエンド（例: `redis://redis:6379/0`）。設定すると、サーバーは認証済み API キーのルックアップ、ダッシュボードの `/models` アグリゲート、セッションリスト、env リストファセットをキャッシュし、OTP リクエストのレート制限を Postgres COUNT から Redis INCR に移行します。未設定または到達不能の場合、サーバーはキャッシュなしで動作します（OTP 制限は Postgres にフォールバック、その他すべてのキャッシュ呼び出しは信頼できる情報源に素通しになります）。下記の **Redis（オプションキャッシュ）** を参照してください。 | | `CLICKHOUSE_URL` | **はい** | なし | ClickHouse インスタンスのベース URL（例: `http://clickhouse:8123`）。サーバーは起動のたびにこのデータベースにイベントスキーマを適用し、ClickHouse に到達できない場合は起動を拒否します。下記の **ClickHouse（必須の分析ストア）** を参照してください。 | | `CLICKHOUSE_DATABASE` | いいえ | `agenteye` | ClickHouse データベース（スキーマ）名。存在しない場合、サーバーが起動時に作成します。 | | `ORG_CH_SECRET` | いいえ（シングルテナント）/ **はい（マルチ org）** | 開発デフォルト | 各組織のテナントごとの ClickHouse パスワードを導出する HMAC キー。SQL エディターと AI エージェントの `run_query` は org 専用の読み取り専用 ClickHouse ユーザーとして実行され、そのロウポリシーがエンジン内でテナント分離を強制します。シングルテナントデプロイは組み込みの開発デフォルトで問題なく起動しますが、**2 番目の org をプロビジョニングする前に強力で安定した値を設定する必要があります**（`agenteye-orgctl org create` CLI は組み込みの開発デフォルトでの実行を拒否します）。ローテーションすると、次回起動時の再プロビジョニング（起動時の調整が自動的に修復）まで、すべての org の ClickHouse ユーザーが孤立します。レプリカ間で秘密かつ不変に保ってください。org のプロビジョニング自体はオペレーター専用です。下記の **組織（マルチテナント）** を参照してください。 | | `DEFAULT_ORG_NAME` | いいえ | `Default` | 組み込みデフォルト org にシードされる表示名。**初回起動時のみ**、かつ org がまだ新規移行後の汎用的なアイデンティティを持っている間のみ、起動時に適用され、以降は無視されます。org を（`agenteye-orgctl org rename` で）リネームすると、その名前が権威ある名前となり、この環境変数はそれ以上効果を持ちません。 | | `DEFAULT_ORG_SLUG` | いいえ | `default` | 組み込みデフォルト org の URL スラッグ（ダッシュボードのパス `//…`）。`DEFAULT_ORG_NAME` と同様に初回起動時のみ/プリスティン状態のみのセマンティクスです。1〜40 文字の小文字英数字（内部ハイフン 1 つまで）で、[予約語](#organizations-multi-tenancy) でないことが必要。無効な値は無視されます（org は `default` のまま）。シングルテナントインストールで、デプロイ後の CLI 手順なしに `/default` の代わりに `/acme` のような表示が可能になります。 | | `RUST_LOG` | いいえ | `info` | ログの詳細度（`debug`、`warn`、`error`、`agenteye_server=trace`） | | `EVALUATOR_ENDPOINT` | いいえ | なし | 評価サービスのベース URL（例: `http://evaluator:9000`）。未設定の場合、評価パイプライン全体は no-op になり、キューの行も書き込まれず、ワーカーも実行されません。[評価スイート](/ja/agenteye/evaluation-suite)を参照してください。 | | `EVALUATOR_TOKEN` | いいえ | なし | 評価サービスへの `Authorization: Bearer ` として送信されます。**評価サービスが設定されている値と同一である必要があります。** 評価サービスがトークンなしで設定されている場合のみオプションです。 | | `EVALUATOR_WORKERS` | いいえ | `2` | 並行数: 評価をディスパッチするサーバーインスタンスごとのワーカータスク数。水平スケールされた複数のサーバーで安全に実行可能。 | | `EVALUATOR_CLAIM_BATCH` | いいえ | `4` | 1 回のティックでシングルワーカーがクレームする評価の最大数。バッチは**並行して**ディスパッチされるため、評価エンドポイントへの合計並行数は `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` になります。 | | `EVALUATOR_POLL_IDLE_SECS` | いいえ | `2` | 保留中のものがない場合に、ワーカーがディスパッチ試行の間にスリープする時間。 | | `EVALUATOR_POLLING_INTERVAL_SECS` | いいえ | `10` | 評価サービスがレスポンスごとの `next_poll_secs` を返さず、`GET /config` の `default_poll_interval_secs` もアドバタイズしない場合の `GET /evaluate/{id}` ポーリングの最終フォールバックサイクル（秒）。 | | `EVALUATOR_REQUEST_TIMEOUT_MS` | いいえ | `30000` | 評価サービスへの HTTP リクエストごとのタイムアウト（ミリ秒）。 | | `EVALUATOR_MAX_ATTEMPTS` | いいえ | `5` | この回数の試行が失敗すると、評価は終端状態 `error`（失敗がリクエストタイムアウトの場合は `timeout`）として記録されます。 | | `EVALUATOR_CONFIG_REFRESH_SECS` | いいえ | `300`（5 分） | サーバーが評価サービスの `GET /config` を再取得する頻度。 | | `EVALUATOR_MAX_POLL_DURATION_SECS` | いいえ | `3600`（1 時間） | セッションがポーリングキューに留まれる最大の実時間。AgentEye がこれを超えると `timeout` として終了します。評価サービスが永久に `pending` を返し続ける場合のガードです。 | | `ALERT_WORKERS` | いいえ | `1` | 並行数: アラートルールを評価するサーバーインスタンスごとのワーカータスク数。[アラート](/ja/agenteye/alerts)を参照してください。 | | `ALERT_CLAIM_BATCH` | いいえ | `16` | 1 回のティックでシングルワーカーがクレームするアラートの最大数。 | | `ALERT_POLL_IDLE_SECS` | いいえ | `5` | キューが空の場合にアラートワーカーがスリープする時間。 | | `ALERT_REQUEST_TIMEOUT_MS` | いいえ | `15000` | トリガー評価ごとのタイムアウト（ClickHouse クエリ + 外部チャンネル HTTP）。 | | `ALERT_MAX_ATTEMPTS` | いいえ | `5` | 通常のサイクルでリスケジュールされる前の連続した一時的障害数（指数バックオフの代わりに）。 | | `AUDIT_WORKERS` | いいえ | `1` | 並行数: 監査を実行するサーバーインスタンスごとのワーカータスク数。[監査](/ja/agenteye/audits)を参照してください。 | | `AUDIT_CLAIM_BATCH` | いいえ | `1` | 1 回のティックでシングルワーカーがクレームする期限到来監査の最大数。エージェント的な調査は長いループのため、デフォルトは 1 です。 | | `AUDIT_POLL_IDLE_SECS` | いいえ | `30` | 監査が期限切れでない場合に監査ワーカーがスリープする時間。 | | `AUDIT_REQUEST_TIMEOUT_MS` | いいえ | `30000` | ClickHouse へのポリシークエリごとのタイムアウト（ミリ秒）。 | | `AUDIT_LLM_TIMEOUT_MS` | いいえ | `1440000` | AI アシスタントサービスへのエージェント的調査コールのタイムアウト。完全なエージェントループは数分かかります。サーバーが諦める前にエージェントが部分的な結果を返せるよう、エージェント自身の `AGENTEYE_AUDIT_TIMEOUT_MS` より**大きな値**に設定してください。 | | `AUDIT_MAX_ATTEMPTS` | いいえ | `5` | 通常のサイクルでリスケジュールされる前の連続した一時的障害数（指数バックオフの代わりに）。 | | `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | いいえ | — | 監査のエージェント的調査は AI アシスタントの `agent` サービスを呼び出し、**アシスタントと同じ接続を再利用します**。そのため、これら 2 つは**サーバーにも設定する必要があります**（バンドルのマニフェスト/compose はそのようになっています）。両方設定 ⇒ 監査は AI 調査を実行し、どちらか未設定 ⇒ 監査は**ポリシーのみ**で実行されます（決定論的な SQL ポリシーパスは引き続き実行されます）。これは監査ごとの `llm_enabled` フラグに関わらず適用されます。エージェントにも LLM の設定が必要です — [assistant.md](/ja/agenteye/assistant) を参照してください。 | **AI アシスタントサービス — 監査 + サンドボックス設定。** エージェント的調査とそのポッド内 Python サンドボックスは、**エージェントサービス**（サーバーではなく）で `AGENTEYE_AUDIT_*` プレフィックスを使用してすべてオプションとしてチューニングされます: | 変数 | デフォルト | 意味 | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- | | `AGENTEYE_AUDIT_MAX_STEPS` | `200` | 調査あたりの最大エージェントターン数。 | | `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | 1 回の調査の実時間（20 分）。サーバーの `AUDIT_LLM_TIMEOUT_MS` より**小さく**保ってください。 | | `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | エージェントポッドあたりの同時調査数（チャットアシスタントの予算とは独立）。 | | `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | bubblewrap サンドボックスのスクリプトごとの制限。 | **サンドボックスのプラットフォーム要件。** 監査コードサンドボックスはモデルの Python を bubblewrap jail 内で実行します。これには**非特権ユーザー名前空間**が必要です。エージェントポッドは `clone()` フラグを許可する必要があります — k8s では `seccompProfile: Unconfined`、compose では `security_opt: [seccomp:unconfined]` をエージェントに設定してください。ノードのカーネルが非特権ユーザー名前空間を無効にしている場合（一部の GKE COS イメージなど）、サンドボックスの**プリフライトが失敗し、オーディターは自動的に SQL のみにデグレードします**。エラーは発生せず、エージェントの `/health` で `sandbox_available: false` として表示されるだけです。 ### 実行 環境変数に `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 # 生存確認 - プロセスが起動すると常に {"status":"ok"} を返す GET /ready # 準備確認 - Postgres + ClickHouse に到達できれば 200、そうでなければ 503 ``` 認証不要です。**liveness** プローブには `/health`、**readiness** / ロードバランサープローブには `/ready` を使用してください。`/ready` はサーバーがサービスを提供するために必須のハード依存関係（Postgres + ClickHouse）をチェックし、実行中でもデータベースに到達できないサーバーはローテーションから外れて `NotReady` として表示されます。Redis は報告されますが、readiness を失敗させることはありません。バンドルの Kubernetes マニフェストでは readiness プローブはすでに `/ready` を指しており、liveness は `/health` のままです。Slack へのオプトイン Kubernetes ネイティブポッド障害アラートを含む詳細については [enterprise-docs/health-monitoring.md](/ja/agenteye/health-monitoring) を参照してください。 ### メールマジックリンク URL OTP ログインメールには**ダッシュボードをワンタップで開く**ボタンが含まれます。クリックすると `/login?token=&email=
` にアクセスし、ダッシュボードがそのペアをセッションに交換してアプリにリダイレクトします。手動でのコード再入力は不要です。サーバーはリンク生成に使用するダッシュボードオリジンを 3 段階で解決します: 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` が使用されます。 ヘッダー値は検証されます。`https://*` およびループバック（`http://localhost*`、`http://127.0.0.1*`）オリジンのみが受け入れられ、`https://` スキームを使用していてもワイルドカードバインドアドレス（`0.0.0.0`、`[::]`）は拒否されます。それ以外はすべて段階 2 にフォールスルーします。 実行中のクラスターに 1 行で設定できます。ファイル編集や kustomize の再ビルドは不要です: ```bash theme={null} kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` これによりロールアウトがトリガーされ、新しいポッドは最初のリクエスト時に値を読み込みます。オーバーライドは 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 行ごとの出力を強制、`0` で人間が読みやすい出力を強制。未設定の場合、`NODE_ENV=production` であれば自動的に JSON が有効になります。本番環境では `jq` やログアグリゲーターで解析しやすいよう JSON を推奨します。 | | `AE_ANALYTICS_DISABLED` | いいえ | なし | `1`/`true` に設定するとダッシュボードの匿名製品利用テレメトリーを無効にします。下記の[テレメトリーとプライバシー](#telemetry--privacy)を参照してください。 | | `REDIS_URL` | いいえ | なし | オプションの共有キャッシュバックエンド（例: `redis://redis:6379/0`）。設定すると、ダッシュボードはレプリカ間で `validateSession()` の結果をキャッシュし、レイテンシーアグリゲート / env リストプロキシルートの Next.js フェッチキャッシュを共有します。Redis が存在する場合、エッジサイドの OTP リクエストと検証のレート制限も Redis を使用します（Redis に到達できない場合はオープンフォールバック。セキュリティのバックストップはサーバーサイドの制限です）。下記の **Redis（オプションキャッシュ）** を参照してください。 | | `AGENTEYE_AGENT_URL` | いいえ | なし | オプションの AI アシスタント `agent` サービスのベース URL（例: `http://agent:9100`）。**未設定のままにするとアシスタントを完全に非表示にします**: ダッシュボードにアシスタントのバブルは表示されません。[enterprise-docs/assistant.md](/ja/agenteye/assistant) を参照してください。 | | `AGENTEYE_AGENT_TOKEN` | いいえ | なし | ダッシュボードが `agent` サービスに提示する共有シークレット。エージェントに設定された `AGENTEYE_AGENT_TOKEN` と一致する必要があります。[enterprise-docs/assistant.md](/ja/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）に**匿名の製品利用分析**を送信します。どのダッシュボードページが表示されたか、API キーの作成やセッションの再評価などのいくつかの UI アクションが含まれます。この利用シグナルは優先すべき機能の判断に使用されます。 * **エージェント、セッション、またはイベントデータがお客様のインフラ外に出ることは一切ありません。** 報告されるのはダッシュボードの UI 利用のみです。ページ URL は送信前に識別子が除去され、オペレーターは不透明な内部 ID でのみ識別され、メールアドレスは使用されません。 * テレメトリーは**デフォルトで有効**です。完全に無効にするには、ダッシュボードコンテナに `AE_ANALYTICS_DISABLED=1` を設定して再起動してください。 * 分析はダッシュボード自身の `/ingest` パスに送信され、ダッシュボードがそれを PostHog（`https://us.i.posthog.com`）にリバースプロキシします。リクエストをファーストパーティとして保つことで、ブラウザの広告ブロッカーによる遮断を防ぎます。**ダッシュボードコンテナ**は PostHog へのアウトバウンドアクセスが必要です。ブロックされている場合、テレメトリーは黙って何もせず、ダッシュボードへの影響はありません。 *** ## AI アシスタント（オプション） ダッシュボード内蔵の AI アシスタントを使用すると、チームがダッシュボードを離れることなく、エージェントデータについて自然言語で質問できます（セッションの要約、`/queries` エディター向けの SQL ドラフト、保存済みクエリのダッシュボードタイルへの変換など）。これは Claude Agent SDK 上で動作する独立した内部 `agent` コンテナとして実行され、ダッシュボードからのみアクセスでき、**LLM エンドポイントを設定するまで無効状態のままです**。 有効にするには、`agent` サービスに LLM 接続（**Portkey** 経由で `PORTKEY_API_KEY` + モデルカタログスラッグ `AGENTEYE_AGENT_MODEL=@/`、直接 Anthropic 経由で `ANTHROPIC_API_KEY`、別のゲートウェイ経由で `ANTHROPIC_BASE_URL`、または Bedrock/Vertex）、**専用**データキー、ダッシュボードと一致する共有 `AGENTEYE_AGENT_TOKEN` を設定します。ダッシュボードユーザーには追加で `agent:use` 権限が必要です。 アシスタントのデータキーは手動で作成する必要はありません。ランダムなシークレットを選択し、`agent` の `AGENTEYE_API_KEY` および `server` の `AGENT_API_KEY` として設定すると、サーバーが起動時に固定された権限セットでシードします。そのデータアクセスは読み取り専用（`events:read`、`evaluations:read`、`dashboards:read`、`queries:read`）で、承認ゲート付きの作成スコープ（`dashboards:write`、`queries:write`、`queries:run`）も保持しているため、保存済みクエリのドラフト・検証やダッシュボードタイルのビルドをユーザーの代わりに行えます。すべての SQL は org の読み取り専用 ClickHouse ロールを通じて実行されるため、これによりアシスタントが作成できる範囲は広がりますが、アクセスできるデータは広がりません。スコープはコードで固定されており、設定で拡大することはできません。このキーは保護されており、API 経由での無効化や再生成はできず、値を変更して再起動することでのみローテーションできます。管理者/ダッシュボードキーを再利用しないでください。 完全なセットアップ手順、環境変数リファレンス、テレメトリーオプション、セキュリティモデルは **[enterprise-docs/assistant.md](/ja/agenteye/assistant)** に記載されています。 *** ## ClickHouse（必須の分析ストア） ClickHouse は高いイベントボリュームでもダッシュボードのレスポンシブさを維持し、`/queries` SQL エディターで単一のストア内でイベント、評価、セッションを結合できるようにします。これは取り込まれたすべてのイベント、すべての終端評価結果、および派生したセッションごとのアグリゲートの必須の正規ストアです。PostgreSQL はリレーショナル/ミュータブルステートテーブル（api\_keys、users、otp\_codes、evaluation\_jobs、dashboards、saved\_queries）を保持し、分析サーフェスは ClickHouse に格納されるため、ダッシュボードのロールアップと独自の SQL クエリがクロスデータベースのラウンドトリップなしにネイティブにスキャン・結合できます。サーバーは `CLICKHOUSE_URL` なしでは起動を拒否します。 ### スキーマ サーバー起動時に 3 つの 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)` 順。評価パイプラインによって終端評価結果ごとに 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` の内容を自動的に反映します。 `analytics.evaluations` / `analytics.sessions` を参照する保存済みクエリとの後方互換性のため、サーバーは `agenteye.*` テーブル上のビューを持つ `analytics` ClickHouse データベースも作成します。`analytics.events`、`analytics.evaluations`、`analytics.agent_sessions`、`analytics.sessions` はすべて正しく解決されます。 ### 設定 バンドルの docker-compose と `deploy/base/clickhouse/` は AgentEye のワークロード向けにチューニングされた ClickHouse サービスを同梱しています: * バンドルのベースオーバーレイでは 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 ストレージクラスへのオーバーライドを推奨） ### バックアップ 完全なデータセットは毎夜単一のリストア可能なアーカイブに取り込まれるため、クラスターやストレージの損失からも復旧できます。ClickHouse は日次の `agenteye-backup` CronJob によって自動バックアップされ、PostgreSQL と ClickHouse の両方を 1 回のパスでダンプします。ClickHouse は HTTP API 経由で読み取られます。`agenteye.events` と `agenteye.evaluations` は ClickHouse ネイティブ形式でダンプされ（ビューとロウポリシーはサーバー起動時に再作成されるため、テーブルデータが完全な情報です）、Postgres ダンプとともに単一の圧縮アーカイブにまとめてオブジェクトストレージにアップロードされます。 アップロード先のバケットとクラウドクレデンシャルはオーバーレイごとに設定します。アップロード設定とリストア手順については [enterprise-docs/kubernetes-deployment.md](/ja/agenteye/kubernetes-deployment) の**バックアップ**セクションを参照してください。 *** ## Redis（オプションキャッシュ） Redis はサーバーとダッシュボードが使用する**オプションの**共有キャッシュ + レート制限バックエンドです。Redis がデプロイされ、両方のサービスに `REDIS_URL` が設定されている場合: * **サーバー** は認証済み API キーのルックアップ、`/events/environments` + `/evaluations/environments` リスト、`/events/latency_aggregate` ロールアップ（ダッシュボードがポーリングする最も重いクエリ）、`/sessions` リストをキャッシュし、OTP リクエストのレート制限を Postgres の `COUNT(*)` から Redis の `INCR + EXPIRE` に切り替えます。 * **ダッシュボード** は `validateSession()` の結果をキャッシュして、典型的なページロードが発行する 10〜20 回の認証済み API 呼び出しが 1 回のアップストリームセッションチェックを共有できるようにします。また、ダッシュボードエッジで OTP リクエストと OTP 検証のレート制限も行います。 **Redis に到達できない場合、両方のサービスは graceful にデグレードします。** すべてのキャッシュ呼び出しは制限されたタイムアウト内で `Err` を返し、呼び出し元は信頼できる情報源（サーバーでは Postgres、ダッシュボードではアップストリームの Rust サーバー）にフォールバックします。OTP レート制限はサーバーの Postgres `COUNT(*)` パスにフォールバックします（セキュリティ特性は維持されます）。ダッシュボードのエッジ OTP 制限はオープンフォールバックになりますが、サーバーサイドの制限は引き続き有効です。Redis のダウンはレイテンシーを低下させますが、正確性には影響しません。 ### 設定 docker-compose バンドルにはすでに Redis サービスが含まれており、`REDIS_URL=redis://redis:6379/0` がサーバーとダッシュボードに配線されています。外部 Redis を使用するには、`REDIS_URL` をエンドポイントに設定し、compose ファイルから `redis` サービスを削除してください。 ### メモリと永続化 バンドルの Redis イメージは `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` で実行されます。AOF 永続化によりコンテナの再起動後もキャッシュが生き残ります。`everysec` は、最後の 1 秒のキャッシュ書き込みが失われても無害なため、適切な耐久性/パフォーマンスのバランスです。LRU 退避によりメモリの増加を抑えます。 ### Redis をデプロイすべきでない場合 * シングルインスタンスの開発/QA 環境。サーバー上のインプロセスキャッシュだけでレプリカごとの利点のほとんどが得られます。Redis はシングルインスタンス設定では不要なクロスレプリカ共有を追加するだけです。 * 別のサービスを運用するコストがレイテンシー改善を上回るエアギャップインストール環境。 *** ## Docker Compose（推奨） `docker-compose.yml` は `agenteye-enterprise/releases` リポジトリで入手できます。1 つのコマンドで 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=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 ``` ```bash theme={null} docker compose up -d ``` **停止（データボリュームを保持）:** ```bash theme={null} docker compose down ``` **停止してすべてのデータを削除:** ```bash theme={null} docker compose down -v ``` *** ## 運用設定 以前は環境変数で固定されていた少数の運用上の設定項目は、ダッシュボードの **`//settings`** ページから組織ごとに編集できるようになりました。各 org が独自の設定を行います。変更は再起動や再デプロイなしで数秒以内に反映されます。 | 設定 | ブートストラップ環境変数 | 制御内容 | | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 許可されたサインイン | `ALLOWED_EMAILS` | OTP の受信とユーザーとしての追加が許可されるメール（または `*@domain.com` ワイルドカード） | | デフォルトユーザー権限 | `DEFAULT_USER_PERMISSIONS` | 管理者が **+ new user** を開いた際に事前選択される権限トークンのカンマ区切りリスト。各トークンは [API キー権限](/ja/agenteye/api-keys) に記載されている文字列のいずれかである必要があります。デフォルトは `standard` プリセット: 読み取り専用アクセスに加え、日常的なオンコールアクション（再評価のトリガー、クエリの実行、インシデントの確認、アシスタントの使用）。 | | セッション有効期間 | `SESSION_TTL_SECS` | 再認証が必要になるまでのダッシュボードログインの有効期間。ダッシュボードは 5 秒ごとにアップストリームセッションを再チェックするため、`//users` での権限更新は影響を受けるユーザーの次のリクエスト時に反映され、再ログインは不要です。 | | ワンタイムコードの有効期間 | `OTP_TTL_SECS` | OTP / マジックリンクが使用可能な期間 | | アラート通知チャンネル | `ALERTS_ENABLED_CHANNELS` | アラートディスパッチャーが使用を許可されるチャンネル種別のカンマ区切りリスト: `email`、`slack`、`webhook`。アラートごとの設定は引き続き `//alerts/` で作成しますが、ディスパッチャーはこのセットを通じてすべての送信配信をフィルタリングし、ここで無効化されたチャンネルは `skipped_disabled` 監査行でショートサーキットされます。`dashboard` チャンネル（ローカル監査挿入）は常に許可されます。デフォルトは 3 つすべてが有効です。 | ### ブートストラップの仕組み 設定は `org_settings` に組織ごとに保存されます。初回起動時、サーバーはデフォルト org の欠落している行を対応する環境変数（または環境変数が未設定の場合は適切なデフォルト）からシードします。その後、**保存された値が信頼できる情報源となり、環境変数は無視されます**。後の再起動で環境変数を変更しても、稼働中の org の値には影響せず、追加の org はデフォルト値から始まり独自に設定します。 つまり: * 新規デプロイの場合は、上記のように環境変数を設定すると、デフォルト org が初回起動時にそれを読み取ります。 * 後で値を変更するには、ダッシュボードにログインして `//settings` で編集してください。変更はすべてのサーバーレプリカに数秒以内に反映されます。再起動は不要です。 * 起動ログ行にシードされた内容と既存のものが記録されるため、ブートストラップが有効になったことを確認できます: ```text theme={null} INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` #### 組織間のサインインセマンティクス セッションと OTP はユーザーに対してグローバルであり、単一の org に限定されません。そのため、サインイン時に 2 つのルールが org ごとの設定を調整します: * **セッション / OTP 有効期間**: ユーザーが所属するすべての org の中で最も厳しい（最短の）有効期間が採用されます。 * **許可されたサインイン**: ゲートは org メンバーシップとともにすべての org のアローリストを OR で組み合わせます。いずれかの org のアローリストがメールを許可している**か**、すでにいずれかの org のメンバーである場合、ユーザーは OTP をリクエストできます。 ### 権限 `//settings` ページへのアクセスは 2 つの権限でゲートされています: * `settings:read`: ページと現在の値を閲覧できます。 * `settings:write`: 変更を保存できます。 ブートストラップ管理者ユーザー（`ADMIN_EMAIL` からシード）は、他のすべての権限とともに両方を自動的に取得します。他のユーザーへの付与は `//users` から必要に応じて行ってください。 *** ## 組織（マルチテナント） 1 つのデプロイメントで複数の分離された**組織**（テナント）を扱えます。すべてのデータ行はちょうど 1 つの org に属し、分離はデータベースエンジンで強制されます。シングルテナントインストールでは何も設定不要で、すべてのデータは組み込みの `default` org に格納されます。（その org に分かりやすい名前と URL スラッグを設定して、`/default` の代わりに `/acme` のようなパスで表示させるには、初回起動前に `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` を設定するか、いつでも `agenteye-orgctl org rename` でリネームできます。） **テナントのプロビジョニングはオペレーター専用です。** 組織とそのメンバーシップは **`agenteye-orgctl`** CLI で作成・管理します。これは**サーバーイメージ内**（`agenteye-server` と並んで）に同梱され、**既存のサーバーポッド内で実行されます**。**別のポッド/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 - 実行中のサーバー Deployment に 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 を受け取ります。 **2 番目の org を作成する前に:** 強力で安定した `ORG_CH_SECRET` を設定してください（`org create` コマンドは組み込みの開発デフォルトでの実行を拒否します）。また Postgres が **15+** であることを確認してください。**変更なし:** org ごとの API キーは引き続きダッシュボード/API で org メンバーによって作成されます。org + メンバーのライフサイクル管理のみが CLI に移動しました。完全なコマンドリファレンスと実例: **[enterprise-docs/tenant-management.md](/ja/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` 権限を持つユーザーはウィンドウをオーバーライドするか、プライベート/プロキシモデルを追加できます（0〜1,000,000 トークン）。`0` は「不明」を意味し、ピルを非表示にします。変更は新たに取り込まれたイベントに適用されます。`settings:read` 権限を持つユーザーはリストを閲覧できます。 アップグレード後の新しいイベントにはその時点から使用率が付与されます。既存のデプロイメントの**過去の**イベント（およびモデルごとのリスト）にも適用するには、一回限りのバックフィルを実行してください。これはサーバーイメージ内（`agenteye-orgctl` と同様）に同梱されており、既存のサーバーポッドで実行されます: ```bash theme={null} # プレビュー（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 ``` 冪等（再実行しても安全）であり、ポッドの `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` を再利用します。モデルウィンドウを編集した後に既存のイベントを再計算したい場合は再実行してください。 *** ## 本番環境での考慮事項 * **Postgres**: マネージド Postgres サービスまたは定期的なバックアップを持つ専用インスタンスを使用してください。`DATABASE_URL` は暗号化接続のための `sslmode=require` を含むすべての標準 libpq パラメーターをサポートします。 * **TLS**: TLS を終端するリバースプロキシ（nginx、Caddy、Traefik）の背後にサーバーとダッシュボードを配置してください。 * \*\*ファ