--- title: 構成のコード化 description: パネル設定をYAMLファイルにエクスポートし、変更をプレビューしてnexcmp configまたはインポート/エクスポートページで適用します。シークレットはファイルに含まれず、JSON Schemaで検証されます。 url: https://nexcmp.com/ja/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # 構成のコード化 {#configuration-as-code} > **管理画面での場所:** System › Settings › Import/Export（`/agent/config`）。サーバー上での操作: コマンド `nexcmp config export`、`plan`、`apply`、および `nexcmp admin `。 ## 動作内容 {#what-it-does} パネルの設定（ブランディング、一般設定、メール、Telegram通知、モジュール、通貨、決済ゲートウェイ、制限、ゾーン、プラン、AIプロバイダー、利用規約などの法的ページ）を1つのYAMLファイルとして保存できます。ファイルを自分で編集したり、AIアシスタントに編集を依頼したり、バージョン管理下で維持したり、同じパネルや別のパネルに適用したりすることができます。変更が適用される前には、必ず差分の一覧が表示されます。機密情報（シークレット）がファイルに書き込まれることはありません。 セットアップを2台目のインストール先にクローンしたり、本番稼働前に変更点を確認したり、誤操作後に設定を復元したり、AIに設定全体を提案させて1つのドキュメントとして確認したりするために使用します。 ## 要件 {#requirements} | 項目 | 要件 | |---|---| | NexCMP | 1.4.0 以降。 | | コマンドライン | パネルサーバーに `root` でログインしています（`sudo` を使用）。コマンドは自動的にパネルに一時キー（15分間、全スコープ）を要求します。代わりに特定の制限されたキーを使用するには、`NEXCMP_KEY` を [admin API key](https://nexcmp.com/ja/docs/configure-with-ai/admin-api-keys/) に設定し、sudo経由で維持します（例: `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`）。 | | 管理画面 | 管理者にサインインしていること。デモパネルではこのページは読み取り専用です。 | | シークレット | 適用時に指定される値（[Secrets](#secrets) を参照）；ファイル内には含まれません。 | ## エクスポート、編集、プレビュー、適用 {#export-edit-preview-apply} 1. 現在の設定をエクスポートします: ```bash sudo nexcmp config export -o nexcmp.yaml ``` `-o` がない場合、YAMLは画面に出力されます。 2. `nexcmp.yaml` を編集します（以下の [example](#example-file) を参照）。先頭に `version: 1` を維持してください。 3. 変更される内容をプレビューします。これによって何も変更されません: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` 各行には、セクション、アイテム、フィールド、および `old → new` が表示されます。`$` とマークされた行は課金セクションに属します（[Billing sections](#billing-sections) を参照）。パネルがすでにファイルと一致している場合は、「No changes」と表示されます。 4. 適用します。`--yes` がない場合、コマンドは **ドライラン** となり、同じ一覧のみが出力されます: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. 結果を読み取ります: `applied`、`pending`（確認待ち）、`skipped`、および `errors`。 | オプション | 意味 | |---|---| | `-f ` | YAMLファイル（`plan` および `apply` に必要）。 | | `--yes` | 実際に適用します。これがない場合、`apply` はドライランになります。 | | `--confirm-billing` | 課金セクション（`payments`、`currency`、`plans`）も適用します。これがない場合、これらはスキップされます。 | | `--section ` | このセクションのみを適用します。複数のセクションに対してオプションを繰り返します。 | | `-o ` | `export` を指定した場合: YAMLをファイルに書き込みます。 | すべてが適用された場合または何も変更されなかった場合の終了コードは0、エラーが返された場合は1、使用法またはキーのエラーの場合は2となります。 ### シークレット {#secrets} ファイルには、機密情報の代わりに `password: secret://smtp_password` などの参照が保持されます。適用時、値は `NEXCMP_SECRET_` という名前の環境変数に大文字の参照名を加えたものから取得されます: ```bash sudo -i read -rs NEXCMP_SECRET_SMTP_PASSWORD && export NEXCMP_SECRET_SMTP_PASSWORD read -rs NEXCMP_SECRET_STRIPE_SECRET_KEY && export NEXCMP_SECRET_STRIPE_SECRET_KEY nexcmp config apply -f nexcmp.yaml --yes --confirm-billing ``` 参照に値がない場合、パネルに既に保存されているシークレットが**保持**されます。一度も保存されておらず、提供もされていないシークレットは空のままになります。 | 参照名 | 格納先 | |---|---| | `smtp_password` | `email.smtp.password` | | `telegram_bot_token` | `telegram.bot_token` | | `stripe_secret_key`, `stripe_webhook_secret` | `payments.stripe` | | `paypal_client_secret` | `payments.paypal.client_secret` | | `binance_api_key`, `binance_api_secret` | `payments.crypto` | | `sepay_api_token`, `sepay_webhook_secret` | `payments.bank` | | `ai_provider_key` | `ai_provider.api_key` | ## ファイルの例 {#example-file} ```yaml # NexCMP configuration. Preview: nexcmp config plan -f nexcmp.yaml version: 1 branding: name: Example Cloud primary: "#1677ff" currency: usd seller_name: Example Cloud LLC settings: brand_name: Example Cloud support_email: support@example.com default_lang: en invoice_prefix: EX company_name: Example Cloud LLC company_address: "1 Example Street, New York, NY" min_topup_cents: 500 email: smtp: host: smtp.example.com port: 587 security: starttls username: mailer@example.com password: secret://smtp_password from_email: no-reply@example.com from_name: Example Cloud reply_to: support@example.com telegram: enabled: true chat_id: "123456789" bot_token: secret://telegram_bot_token modules: s3: true k8s: false currency: site_currency: usd manual_rate_vnd: 0 # 0 = automatic payments: stripe: mode: test publishable_key: pk_test_XXXX secret_key: secret://stripe_secret_key webhook_secret: secret://stripe_webhook_secret bank: bank_code: BANK account_number: "0000000000" account_name: EXAMPLE CLOUD LLC prefix: EX api_token: secret://sepay_api_token channels: pay_card_enabled: true quotas: quota_enabled: true quota_max_vms_24h: 5 quota_max_vms_30d: 30 zones: - slug: new-york name: New York country: US city: New York enabled: true is_default: true plans: - slug: vps-1c-1g name: 1 vCPU, 1 GB RAM, 25 GB cpu: 1 ram_mb: 1024 disk_gb: 25 hourly_usd: 0.0112 cs_offering_id: OFFERING_ID enabled: true visible: true ai_provider: enabled: true name: Example AI base_url: https://api.example.com/v1 model: example-model fallback_models: [example-model-mini] reasoning_effort: low api_key: secret://ai_provider_key legal: terms: en: | # Terms of service Your terms in simple markdown (no HTML). privacy: en: | # Privacy policy Your policy in simple markdown (no HTML). ``` ファイルには任意のセクションのサブセットを含めることができます。省略したセクションは変更されません。1MBを超えるファイル、`version: 1` の欠落、異なるバージョン番号、または不明なセクションがある場合、処理が実行される前に拒否されます。 ## セクション {#sections} | セクション | 制御内容 | 備考 | |---|---|---| | `branding` | ブランド名（60文字まで）、プライマリカラー、表示通貨（`usd` または `vnd`）、販売者名。 | ロゴはファイルに含まれません。[branding page](https://nexcmp.com/ja/docs/customers/branding/) を使用してください。 | | `settings` | 一般設定の固定リスト: `brand_name`、`support_email`、`support_telegram_url`、`default_lang`、`require_email_verified`、`min_topup_cents`、`max_topup_cents`、`invoice_prefix`、`company_name`、`company_address`、`company_tax_id`、`auto_destroy_days`、`low_balance_cents`。 | その他のキーは無視されます。 | | `email.smtp` | SMTPホスト、ポート、セキュリティ（`starttls`、`tls`、`none`）、ユーザー、パスワード、送信者名とアドレス、返信先。 | [SMTP and e-mail templates](https://nexcmp.com/ja/docs/administration/smtp-and-emails/)。ホスト、ポート、またはセキュリティを変更する場合は、パスワードを再度入力する必要があります。 | | `telegram` | アラートチャネルの有効/無効、チャット ID、ボットトークン。 | [Telegram notifications](https://nexcmp.com/ja/docs/administration/telegram-notifications/)。 | | `modules` | オプションモジュールの有効/無効（`key: true/false`）。 | パネルで切り替え可能なキーのみ。[Modules](https://nexcmp.com/ja/docs/infrastructure/modules/)を参照してください。 | | `currency` | 表示通貨と手動の USD/VND レート（`0` は自動、それ以外は 15000 から 50000）。 | 課金セクション。[Currency and exchange rates](https://nexcmp.com/ja/docs/catalog/currency-and-exchange-rates/)を参照してください。 | | `payments` | `stripe`、`paypal`、`crypto`、`bank` の資格情報と `channels` のスイッチ（`pay_card_enabled`、`pay_wallets_enabled`、`pay_alipay_enabled`、`pay_paypal_enabled`、`pay_usdt_enabled`、`pay_sepay_enabled`）。 | 課金セクション。[Payment channels](https://nexcmp.com/ja/docs/billing/payment-channels/)を参照してください。 | | `quotas` | `quota_*` の制限。 | [Quotas](https://nexcmp.com/ja/docs/billing/quotas/)を参照してください。 | | `zones` | `slug` によるゾーン（必須：`slug`、`name`、`country`；任意：`city`、`enabled`、`is_default`）。 | 新しいゾーンが作成されます。既存のゾーンはファイルによって**変更されません**。[Zones](https://nexcmp.com/ja/docs/infrastructure/zones/)を参照してください。 | | `plans` | `slug` によるプラン（必須：`slug`、`name`、`cpu`、`ram_mb`、`disk_gb`、`hourly_usd`；任意：`cs_offering_id`、`backend_id`、`zone_id`、`enabled`、`visible`、`sort`、`description`）。 | 課金セクション。新しいプランが作成され、既存のプランはスラッグによって更新されます。価格は 1 時間あたりの USD です。[Plans](https://nexcmp.com/ja/docs/catalog/plans/)を参照してください。 | | `ai_provider` | カスタマー向けの AI Chat および AI Agent で使用されるパネルの AI プロバイダー。 | [AI provider](https://nexcmp.com/ja/docs/ai/ai-providers/)。 | | `legal` | 言語ごとの利用規約およびプライバシーのテキスト（`en`、`vi`）。 | [Legal pages](https://nexcmp.com/ja/docs/customers/legal/)。 | 適用の順序は上記の通りです。インフラストラクチャ関連の項目がプランの前に処理されます。 ## 覚えておくべきルール {#rules-to-remember} - **べき等性。** 同じファイルを二度適用しても、2 回目は何も変更されません。`plan` に「No changes」と表示されます。 - **削除なし。** このファイルによってゾーン、プラン、設定が削除されることはありません。ファイルからエントリを削除しても、パネルの状態はそのまま維持されます。 - **通常の安全性に関するルールが引き続き適用されます。** コマンドラインからの各変更は、API の変更と同じチェック（スコープや IP ルール）を通過します。確認が必要な変更（サイト全体の設定スイッチなど）は、適用される代わりに `pending` のもとでプレビュー付きで報告されます。ただし `--confirm-billing` を渡した場合は、それらがすべて確認済みとして処理されます。 - **AI クライアントで課金を解除することはできません。** MCP クライアントから `config_apply` が呼び出された場合、`confirm_billing` は無視され、金銭に関する変更はユーザーの承認待ちとなります。 - **適用前に確認する。** JSON Schemaにはすべてのフィールドが記述されています。エディターで参照するか、AI に渡して有効な YAML を作成させてください：`https://cloud.example.com/v1/admin/agent/config/schema.json`（一般公開）。 ### 課金セクション {#billing-sections} `payments`、`currency`、`plans` は価格や金銭のパスを変更します。`nexcmp config apply --yes` は、`--confirm-billing` を追加しない限りこれらを**スキップ**します。スキップされた項目は `skipped`（「billing section - pass confirm_billing」）の下に一覧表示されます。このフラグは確認を意味します。これを指定すると、ファイル内のすべての課金に関する変更（および確認を求めるその他の変更）が、再確認なしで適用されます。最初に `plan` を実行し、`$` とマークされた各行を確認してください。 AI（MCP クライアントまたは AI Chat 内の `config_apply` ツール）によって同じファイルが適用された場合、フラグは無視され、金銭に関する変更はユーザーの承認待ちとなります。 ## Import/Export ページの使用 {#use-the-import-export-page} 1. **System › Settings › Import/Export** を開きます。 2. **Export** で **Get current configuration** をクリックし、**Download .yaml** をクリックして `nexcmp.yaml` を保存します。シークレットはプレとして表示されます。 3. **Import** でファイルを選択するか、ボックスにドラッグするか、YAML を貼り付けます。 4. オプション：**Secrets that come with it (not in the file)** を開き、各参照の名前と値を追加します（例：`smtp_password`）。 5. **Preview changes** をクリックします。テーブルでは変更内容がセクションごとにグループ化され、金銭関連のセクションには「Money-related」タグが付与されます。不要なセクションのチェックを外してください。 6. 金銭関連のセクションがリストされている場合は、**Also apply money-related changes (prices, payment gateways, balances)**にチェックを入れます。チェックを入れないとスキップされます。 7. **Apply selected**をクリックします。結果には、適用されたもの、スキップされたもの、失敗したものが表示されます。確認待ちとして返された変更は確認カードとして表示されるため、その上の**Confirm**を押します。 右上の**JSON Schema**ボタンでスキーマが開きます。 ![ExportカードとエクスポートされたYAMLを保持するImportカードが表示されたImport/Exportページ](https://nexcmp.com/ja/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![課金タグとApply selectedボタンを持つ、セクションごとにグループ化された変更のプレビューテーブル](https://nexcmp.com/ja/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## コマンドラインから任意のツールを実行する {#run-any-tool-from-the-command-line} `nexcmp admin`はAIアシスタントと同じツール（[the tool list](https://nexcmp.com/ja/docs/configure-with-ai/mcp-admin/#tools)）を実行し、JSONを出力します： ```bash sudo nexcmp admin tools # name, scope and title of every tool sudo nexcmp admin system_health sudo nexcmp admin customers_search q=customer@example.com sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}' ``` 引数は`key=value`ペア（値は解析できる場合はJSONとして、それ以外はテキストとして読み込まれます）または1つの`--json '{...}'`オブジェクトです。アクションに確認が必要な場合、コマンドはプレビューを表示し、終了コード3と「Nothing changed」で停止します。プレビューを確認し、`--yes`を指定して同じコマンドをもう一度実行して適用します。rootとして実行すると、コマンドはすべてのスコープを持つ15分間のキーを取得するため、確認ステップが保護機能となります。`NEXCMP_KEY`を指定すると、キー自体のスコープが適用されます。 ## 確認 {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml`の直後の`apply --yes`は「No changes」を出力します。 2. 管理画面では、変更したページに新しい値が表示され、**Logs › Admin actions**に変更がリストされます。 3. 同じファイルを再度適用しても何も変更されません。 ## 制限と注意事項 {#limits-notes} - ファイルが対象とするのは上記の設定であり、顧客、サーバー、請求書、インフラストラクチャソース（CloudStackおよびProxmoxの接続）は対象外です。これらは[AI Chat](https://nexcmp.com/ja/docs/configure-with-ai/ai-chat-in-admin/)または管理画面で接続してください。 - ゾーンとプランは`slug`でマッチングされます。ファイル内のスラッグの名前を変更しないでください。変更すると新しいアイテムとして作成されてしまいます。 - すでに顧客が使用しているプランのサイズを変更することはできません。代わりに新しいプランを作成してください。 - エクスポートされたファイルには機密情報が含まれていない場合でも、価格、住所、アカウント名がリストされているため、非公開に保ってください。 ## トラブルシューティング {#troubleshooting} | 症状 | 原因 | 対処法 | |---|---|---| | `missing version: 1` | ファイルが`version: 1`で始まっていない | 追加してください。 | | `unsupported version 2` | ファイルのバージョン番号が異なっている | このパネルはバージョン1のみを読み取ります。 | | `unknown section 'x' (known: ...)` | スペルミスのある、またはサポートされていないトップレベルキー | 上記のセクションを使用してください。 | | `YAML error: ...` | 無効なYAML（インデント、タブ） | メッセージに示されている行を修正してください。 | | `config is larger than 1 MB` | ファイルが大きすぎます | 分割して`--section`を使用してください。 | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | コマンドがキーを見つけられませんでした | `sudo`を指定して実行するか、`NEXCMP_KEY`をエクスポートしてsudoで保持してください。 | | `panel not reachable` | パネルサービスがデフォルトポートで実行されていません | `sudo nexcmp status`を確認してください。 | | `skipped`の下の課金行 | 課金セクションには`--confirm-billing`が必要です | フラグを追加し、最初に`$`行を確認してください。 | | `pending`の下のアイテム | 変更の確認が必要です | **API & AI agents**を開くか、Import/Exportの結果を開き、カードの**Confirm**を押します。 | | シークレットが更新されませんでした | `NEXCMP_SECRET_`の値が設定されなかったため、保存されたシークレットが維持されました | 変数をエクスポートして再度適用してください。 | | `errors` 下のエントリ、HTTP 403 `insufficient_scope` | キーにそのセクションのスコープがありません | スコープを持つキーを使用するか、rootとして実行してください。 | | `errors` 下のエントリ、HTTP 403 `demo_read_only` | デモパネル | 実際のインストール環境で適用します。 |