> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/platform-development/onprem-operations.md). # 運用の要点：オフラインインストール、TLS、バックアップ、監視、受け入れ検証 プライベートクラウドとオンプレミス環境の運用保守の要点：オフライン（air-gap）インストール、ドメインと TLS 証明書、バックアップと復元、監視（オプション）、デプロイ後の受入確認についての要点と注意事項 本ページでは、デプロイパッケージで MaiAgent をインストールする際（プライベートクラウドまたはオンプレミス）に、お客様の IT 部門と SI パートナーが計画および日常の運用保守で把握すべき 5 つの事項をまとめています。各項目では要点と間違いやすい点を説明します。実際のコマンドと期待される出力は、デプロイパッケージに付属するインストールマニュアルに記載されています。入手については MaiAgent の担当者にお問い合わせください。 ## オフライン（air-gap）インストール **要点** * **判断基準**：ホストが MaiAgent のダウンロードサイトと Hugging Face に直接接続できない場合は、必ずオフラインインストールを使用します。許可リストのみの通信、proxy 経由の通信、一部の接続先にしか接続できない場合もオフラインに該当します。 * **現地訪問は 1 回で済みます**：訪問前に、インターネット接続可能な作業用コンピューターで、デプロイ設定に従ってデプロイパッケージ、サービスイメージ、モデルの重みをダウンロードし、ファイルごとに checksum を照合します。現地では資材をホストに転送し、問題がないことを確認してからインストールします。 * **資材のサイズ**：検証では、Docker 単一ホストのデフォルト機能は 12 個のイメージで約 8.7 GB、監視とアラートを有効にすると約 9.2 GB でした。ホスト上でモデルを実行する場合、重みの容量は別途必要です。 * **現地への持ち込み方法**：作業用コンピューターをお客様の内部ネットワークに接続して直接コピーするか、USB を使用します。USB は exFAT または NTFS 形式にしてください。バックエンドイメージは 1 ファイルで約 7.5 GB あり、FAT32 には保存できません。 {% hint style="warning" %} **注意事項** * デプロイ設定は現地訪問前に確定してください。機能、バージョン、CPU アーキテクチャを変更すると異なる資材が必要になり、作業用コンピューターで再ダウンロードする必要があります。そのホストのみに関係する設定（ユーザーの接続先アドレスなど）は現地で変更できます。 * Docker 分散構成では、Docker を実行するすべてのホストに資材を配置してください。 * Kubernetes のオフラインインストールには、追加の資材（クラスタコンポーネント、Helm chart、ストレージコンポーネント用のシステムパッケージ）が必要です。ドメインは内部 DNS で設定し、公開 DNS の名前解決に依存するドメインサービスは使用しないでください。 * デプロイ設定にはモデルサービスのキーが含まれ、アップグレード時にも使用します。社内規定に従って暗号化して保管してください。 * Messenger、Instagram、WhatsApp チャネルは、Meta がインターネット経由で MaiAgent の API を呼び出す必要があるため、オフライン環境では使用できません。 {% endhint %} ## ドメインと TLS 証明書 **要点** * **2 種類の接続方法**：IP とポート番号（ドメイン不要）、またはサービスごとに 1 つのドメイン（API、管理画面、会話ページなど）を使用します。Kubernetes は後者のみ対応します。開放するポートは[システム要件：ポート](/tech/ja/platform-development/system-requirements.md#ports)をご覧ください。 * **ユーザーが別のアドレスから接続する場合**（クラウドホストの公開 IP、NAT の外部アドレス、それらを指すドメインなど）、インストール時のサーバーアドレスにはユーザーが実際に接続するアドレスを指定してください。ホストの内部 IP を指定すると、外部から管理画面を開いたり、ファイルをアップロードしたりできません。 * **インストール時に自己署名証明書が自動生成されます**。ブラウザーで初めて開く際にセキュリティ警告が表示されます。お客様の証明書に変更する場合は、公開 CA と企業内 CA のどちらが発行したものでも使用でき、`.pfx` または「証明書ファイル＋秘密鍵」の形式に対応しています。デプロイパッケージの変換ツールは、証明書と秘密鍵の一致、証明書チェーンの完全性、有効期限までの期間を確認します。 * **証明書の変更に再インストールは不要です**。検証では適用中の API 呼び出しがすべて成功し、サービスは中断しませんでした。 {% hint style="warning" %} **注意事項** * 証明書の名前（SAN）には、ユーザーの接続先アドレスを含める必要があります。IP で接続する場合は、その IP を証明書に含めてください。公開 CA は通常、IP を含む証明書を発行しません。 * クラウドおよび多くの NAT 環境では、ホストから自分自身の外部アドレスに接続できず、デプロイ後の受入テストがすべて接続タイムアウトになります。ホストに NAT ルールを追加し、自分自身の外部アドレス宛ての通信を内部アドレスに戻す必要があります。 * 企業内 CA：ルート CA をバックエンドサービスの信頼リストに追加してください。追加しないと、バックエンドが自身の URL に接続する際に検証が失敗します。CA 証明書には Key Usage フィールドが必要です。 * システムは証明書の期限切れを自動通知しません。有効期限の確認を、お客様の既存の監視やスケジュールに組み込んでください。 * バックアップを復元すると、Web サイトの証明書もバックアップ時点のものに戻ります。 * Kubernetes の証明書はクラスタ内に保存されます。企業内 CA が発行した証明書を使用する場合は、事前に MaiAgent にご相談ください。Docker 分散構成と Kubernetes で証明書を変更する前に、MaiAgent の担当者と手順を確認し、実施日時を調整してください。 {% endhint %} ## バックアップと復元 **要点** * デプロイパッケージにはバックアップスクリプトが付属し、データベース、オブジェクトストレージ（アップロードしたファイル）、検索インデックス、キャッシュとメッセージキュー、リバースプロキシ設定、サービス設定（各サービスのパスワードと暗号化キーを含む）を一括でバックアップします。 * デフォルトではホスト上のバックアップディレクトリに保存し、7 日間保持します。ディレクトリと保持日数は変更でき、スケジュール（cron）による定期バックアップも可能です。 * 復元ではサービスを停止し、データを上書きしてから再起動します。この間、システムは利用できません。検証（新規インストールでデータが少ない状態）では、バックアップは約 1 分、復元は約 2.5 分でした。 * アップグレード前には自動でバックアップを作成し、保持対象としてマークします。[バージョンとアップグレード：ロールバックの制限](/tech/ja/platform-development/onprem-versioning-and-upgrades.md#rollback)をご覧ください。 {% hint style="danger" %} **注意事項** * デフォルトのバックアップディレクトリはシステムと同じディスク上にあるため、ホストが故障するとバックアップも失われます。独立したディスクまたはネットワークストレージをバックアップディレクトリとしてマウントしてください。 * サービス設定の暗号化キーを失うと、暗号化済みデータを復号できません。削除や置き換えはしないでください。 * 復元には実行順序の依存関係があります。一部だけではなく、バックアップ全体を復元してください。 * 本番利用前に復元訓練を行うことを推奨します。識別できるデータを作成し、バックアップ、削除、復元を行い、データが戻ることを確認してください。 * Docker 分散構成ではデプロイホストで実行し、各ホストのデータをデプロイホストに集約して保存します。Kubernetes ではコントロールノードで実行します。お客様が用意したクラスタ（インストーラーが作成したものではない場合）では内蔵スクリプトを使用できないため、クラスタの既存のバックアップ機構を使用してください。 * バックアップの失敗では監視アラートが発生しません。定期バックアップの結果を別途確認してください。 {% endhint %} ## 監視（オプション） **要点** * 有効にすると VictoriaMetrics（メトリクス、デフォルト保持期間 30 日）、VictoriaLogs（ログ、デフォルト保持期間 14 日）、Grafana ダッシュボードがデプロイされ、ホスト、コンテナ、データベース、キャッシュ、検索エンジン、オブジェクトストレージ、メッセージキューを監視します。ホストに NVIDIA ドライバーがある場合は、GPU の使用率、メモリ、温度も収集します。 * アラートは別のスイッチで有効にします。有効にすると、内蔵ルール（ホストの CPU、メモリ、ディスク使用量が高すぎる場合など）に従って Email 通知を送信します。現在、通知は Email（SMTP）のみ対応しています。 {% hint style="warning" %} **注意事項** * 現在の監視対象には、アプリケーション層のメトリクス（HTTP エラー率、リクエスト遅延など）、業務メトリクス（会話数など）、外部からのユーザー接続確認、証明書の期限、バックアップの成否は含まれません。外部からの可用性確認には、お客様の既存の外部監視で API の URL を呼び出してください。 * Kubernetes の監視インターフェースには外部ルートがないため、port-forward で接続してください。 * 監視とアラートの導入方法（しきい値、通知先）は、有効にする前に MaiAgent と確認してください。 {% endhint %} ## デプロイ後の受入確認 **要点** * デプロイ設定で自動受入確認を選択すると（有効化を推奨）、インストールの最後に機能受入テスト（deploy-test）が実行され、HTML と JSON のレポートが生成されます。証明書の変更やアップグレード後など、後から単独で再実行することもできます。 * **合格基準**：フェーズ 0（インフラストラクチャ）とフェーズ 1（スモークテスト）はすべて合格する必要があります。フェーズ 2 以降の失敗は、項目ごとに原因を確認してください。スキップされた項目は通常、有効にしていないオプション機能です。スキップや未検証は合格には含まれません。 * デプロイ前に「デプロイ設定確認表」を記入している場合は、確認表とともに生成された照合ツールでシステムの実際の設定を比較し、機能スイッチがすべて確認表どおりであることを確認してください。 | # | 受入確認項目 | 合格条件 | | - | ------------------------- | ------------------------ | | 1 | インストール結果 | 失敗した手順がありません | | 2 | サービスの状態 | すべてのサービスが実行中です | | 3 | 管理画面、会話ページ、システム管理インターフェース | すべて開いてログインできます | | 4 | デフォルトアカウントのパスワード | 変更済みで、初期パスワードではログインできません | | 5 | 機能受入テスト | フェーズ 0、1 がすべて合格しています | | 6 | バックアップ | バックアップスクリプトが正常に実行されます | | 7 | 確認表との照合（確認表を記入した場合） | 不一致の項目がありません | {% hint style="danger" %} **注意事項** * デプロイパッケージで作成されるデフォルト管理者アカウントは、公開されている初期パスワードを使用します。インストール後すぐに変更し、変更するまではユーザーの接続を許可しないでください。 * 受入テスト用アカウントのパスワードを変更した後は、デプロイディレクトリに保存されているものも更新してください。更新しないと、その後の受入テストでログインに失敗します。 * ブラウザー操作のテスト項目には、別途提供される受入テスト用イメージが必要です。ない場合、レポートには未検証と表示されます。 * ホストの再起動後、サービスは自動で起動します。検証では約 1.5 分後にログインできました。 {% endhint %} ## 招待メールと通知メールの送信設定 メンバー管理の Email 招待や有人対応への引き継ぎ通知などのメールは、プラットフォームからお客様の SMTP サーバーを通じて送信されます。デプロイパッケージにメールサーバーは含まれず、インストール時にメール送信の設定も行いません。インストール後、システム管理者が**システム管理インターフェース**（Django 管理サイト）の Email 設定に以下を入力してください。 * **SMTP サーバー**：ホスト、ポート番号、ユーザー名とパスワード、送信元アドレスを指定します。設定していない場合、招待メールは送信されません。 * **登録ページ URL テンプレート**：招待メール内の登録リンクです。管理画面のログイン URL に招待コードのパラメーターを追加し、例えば `https://<後台網址>/login?invitationCode={invitationCode}` と指定します。`{invitationCode}` は該当する招待のコードに置き換えられます。管理画面 URL は、インストール時にユーザーの接続先として指定した管理画面のアドレスです（ドメインと TLS を使用する場合は `https://` を使用します）。未設定の場合、招待メールを送信できません。 {% hint style="info" %} * この 2 項目はデプロイ全体で共有するシステム設定です。組織の管理画面には対応する項目がなく、組織管理者は変更できません。変更する場合はシステム管理者に依頼してください。 * 登録ページ URL テンプレートの変更は、その後に送信されるメールにのみ適用されます。送信済みの招待メールには古いリンクが残るため、必要に応じて管理画面の招待ステータスから再送信してください。 * この設定は、ユーザーマニュアルの[会話プラットフォームの基本設定：カスタムドメイン（CNAME）](https://docs.maiagent.ai/build/channels/basic-settings#custom-domain)とは無関係です。カスタムドメインは会話ページの公開 URL にのみ適用されます。 {% endhint %} ### メール設定と登録ページ URL が必要なメール 下表は、プラットフォームが自動的に送信するシステムメールと、メール設定（上記の SMTP サーバー、または AWS SES）や登録ページ URL テンプレートが未設定の場合のそれぞれの結果をまとめたものです。各メールの送信タイミング、宛先、無効化できるかどうかについては、ユーザーマニュアルの[システム通知とメール](https://docs.maiagent.ai/start/system-emails)をご覧ください。 | システムメール | メール設定の要否 | 登録ページ URL テンプレートの要否 | メール設定がない場合 | | --------------------------------------------------------------- | -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | パスワードリセットメール | 必要 | 不要 | ユーザーがログインページで「パスワードを忘れた場合」を送信するとエラーが表示され、メールは届きません | | 招待メール | 必要 | 必要：未入力の場合、この招待は送信失敗として記録され、「再送信」を押しても失敗します | 招待が送信失敗として記録されます | | パスワード設定メール（メンバーの一括インポート） | 必要 | 不要 | メンバーは作成されますが、一括分のメールはすべて送信されず、送信履歴も残りません | | 有人対応への引き継ぎ通知メール | 必要 | メール内の会話リンクには登録ページ URL テンプレートのアドレスが使われます：未入力の場合、リンクを開けません | メールは送信されません。通知センターの有人対応への引き継ぎ通知は通常どおり発行されます | | コネクタ申請メール | 必要 | 不要 | メールは送信されません。メンバーの申請は通常どおり送信されます | | MCP ツールの再認証が必要 | 必要 | 不要 | メールは送信されず、通知センターの通知のみが発行されます | | 認可が失効したツールをスケジュールがスキップ | 必要 | 不要 | メールは送信されません。スケジュールの実行履歴にはスキップされたツールが通常どおり記録されます | | ポイント残高不足のリマインド、個人クォータの残りわずか／期限切れ間近 | 必要 | 不要 | メールは送信されません。通知センターのリマインドは通常どおり発行されます | | 組織の審査承認／不承認、データの完全削除予定 | 必要 | 不要 | メールは送信されません | | プランと Credits の通知（プラン予約済み、プラン適用開始、今月の Credits 付与、Credits チャージ入金） | 必要 | 不要 | プライベートクラウドとオンプレミスでは既定で無効のため送信されません。有効化した後にメール設定がない場合、各メールは失敗として記録され、設定を修正した後に管理インターフェースの通知履歴から再送信できます | {% hint style="warning" %} * コネクタ申請メール、MCP ツールの再認証メール、認可が失効したツールをスケジュールがスキップしたことを知らせるメールの 3 種類では、メールに記載される管理画面のリンクが現在、常にクラウド版の URL（`admin.maiagent.ai`）を指しています。プライベートクラウドとオンプレミスの受信者は、メール内のリンクをクリックせず、自社の管理画面に直接ログインして、コネクタ管理またはツールのページで対応してください。 * SMTP または AWS SES でメールを送信する場合、招待メールとパスワード設定メールの**件名とメールテンプレート**には既定値がありません。あわせて入力してください。入力しないと、送信されるメールに件名も本文もありません。 {% endhint %} ## ログアウト後に指定 URL へリダイレクト シングルサインオン（SSO）を採用したり、MaiAgent を企業ポータルに埋め込んだりする環境では、管理画面の標準ログインページを通常は使用しないため、ログアウト後にそのページに留まっても移動先がありません。デプロイ設定で「ログアウト後のリダイレクト URL」を指定できます。例えば、企業ポータルのホームページや IdP のログアウトエンドポイントを指定します。 **設定後の動作** * ユーザーによるログアウト、アイドルタイムアウトによるログアウト、未ログイン状態で管理画面リンクを直接開いた場合の 3 つすべてで、ページ全体が指定 URL にリダイレクトされます。 * ページ全体の遷移となり、ブラウザーの戻るボタンを押しても管理画面のログインページには戻りません。 * 未設定の場合は従来の動作を維持し、MaiAgent のログインページに戻ります。 **URL の形式** * `http://`、`https://` で始まる完全な URL、または単一の `/` で始まるサイト内パスを指定できます。 * その他の形式（`javascript:` や `//` で始まる URL など）は無視され、未設定として扱われます。 {% hint style="info" %} これは管理画面フロントエンドのデプロイ設定で、デプロイ内のすべての組織に適用されます。組織の管理画面には対応する項目がありません。インストール時に設定できます。インストール後に追加や変更する場合は、MaiAgent の担当者に適用をご依頼ください。フロントエンドサービスが設定を再読み込みした後に有効になります。各 SSO タイプでのログアウト時の IdP に対する動作は、ユーザーマニュアルの[外部サービスによるログイン：ログアウト時の動作](https://docs.maiagent.ai/org/sso#logout-behavior)をご覧ください。 {% endhint %} ## 関連ページ * [デプロイ形態と機能比較](/tech/ja/platform-development/onprem-deployment-types.md) * [システム要件](/tech/ja/platform-development/system-requirements.md) * [バージョンとアップグレード](/tech/ja/platform-development/onprem-versioning-and-upgrades.md) * [オンプレミスのモデルサービス接続](/tech/ja/platform-development/onprem-model-services.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/ja/platform-development/onprem-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.