--- title: Konfiguration als Code description: Exportieren Sie Ihre Panel-Konfiguration in eine YAML-Datei, prüfen Sie die Änderungen und wenden Sie sie an. url: https://nexcmp.com/de/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Konfiguration als Code {#configuration-as-code} > **Wo im Admin:** System › Settings › Import/Export (`/agent/config`). Auf dem Server: die Befehle `nexcmp config export`, `plan` und `apply` sowie `nexcmp admin `. ## Funktion {#what-it-does} Ihre Panel-Konfiguration (Branding, allgemeine Einstellungen, E-Mail, Telegram-Benachrichtigungen, Module, Währung, Zahlungs-Gateways, Limits, Zonen, Tarife, der AI-Anbieter und die rechtlichen Seiten) kann als eine einzige YAML-Datei gespeichert werden. Sie können die Datei selbst bearbeiten, einen AI-Assistenten damit beauftragen, sie in der Versionsverwaltung verwalten und sie auf dasselbe oder ein anderes Panel anwenden. Vor jeder Änderung sehen Sie immer eine Liste der Unterschiede. Passwörter und Geheimnisse werden niemals in die Datei geschrieben. Verwenden Sie dies, um ein Setup auf eine zweite Installation zu klonen, Änderungen vor dem Live-Gang zu überprüfen, Einstellungen nach einem Fehler wiederherzustellen oder ein AI-Modell eine vollständige Konfiguration vorschlagen zu lassen, die Sie wie ein einzelnes Dokument lesen. ## Anforderungen {#requirements} | Komponente | Anforderung | |---|---| | NexCMP | 1.4.0 oder neuer. | | Kommandozeile | Sie sind `root` auf dem Panel-Server (verwenden Sie `sudo`). Der Befehl fordert eigenständig einen temporären Schlüssel (15 Minuten, alle Scopes) vom Panel an. Um stattdessen einen eingeschränkteren Schlüssel zu verwenden, setzen Sie `NEXCMP_KEY` auf einen [admin API key](https://nexcmp.com/de/docs/configure-with-ai/admin-api-keys/) und behalten Sie diesen über sudo bei, zum Beispiel `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | Admin-Seite | Als Administrator angemeldet. Auf einem Demo-Panel ist die Seite schreibgeschützt. | | Secrets | Werte, die zum Zeitpunkt der Anwedung bereitgestellt werden (siehe [Secrets](#secrets)); niemals innerhalb der Datei. | ## Exportieren, bearbeiten, vorschauen, anwenden {#export-edit-preview-apply} 1. Exportieren Sie die aktuelle Konfiguration: ```bash sudo nexcmp config export -o nexcmp.yaml ``` Ohne `-o` wird das YAML auf dem Bildschirm ausgegeben. 2. Bearbeiten Sie `nexcmp.yaml` (siehe das [Beispiel](#example-file) unten). Behalten Sie `version: 1` oben bei. 3. Zeigen Sie eine Vorschau der Änderungen an. Dies ändert nichts: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` Jede Zeile zeigt Bereich, Element, Feld und `old → new`. Zeilen mit der Markierung `$` gehören zu Abrechnungsbereichen (siehe [Billing sections](#billing-sections)). Wenn das Panel bereits der Datei entspricht, wird „No changes“ angezeigt. 4. Anwenden. Ohne `--yes` ist der Befehl ein **Dry Run** (Testlauf) und gibt nur dieselbe Liste aus: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. Lesen Sie das Ergebnis: `applied`, `pending` (wartet auf Ihre Bestätigung), `skipped` und `errors`. | Option | Bedeutung | |---|---| | `-f ` | Die YAML-Datei (erforderlich für `plan` und `apply`). | | `--yes` | Wirklich anwenden. Ohne diese Option ist `apply` ein Testlauf. | | `--confirm-billing` | Wenden Sie auch die Abrechnungsbereiche an (`payments`, `currency`, `plans`). Ohne diese Option werden sie übersprungen. | | `--section ` | Wenden Sie nur diesen Abschnitt an. Wiederholen Sie die Option für mehrere. | | `-o ` | Mit `export`: Schreiben Sie das YAML in eine Datei. | Der Exit-Code ist 0, wenn alles angewendet wurde oder sich nichts geändert hat, 1, wenn ein Fehler zurückgegeben wurde, und 2 bei einem Aufruf- oder Schlüsselfehler. ### Secrets {#secrets} Die Datei enthält Referenzen anstelle von Geheimnissen, wie zum Beispiel `password: secret://smtp_password`. Zum Zeitpunkt der Anwendung stammt der Wert aus einer Umgebungsvariablen namens `NEXCMP_SECRET_` plus dem Referenznamen in Großbuchstaben: ```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 ``` Wenn eine Referenz keinen Wert hat, wird das bereits im Panel gespeicherte Geheimnis **beibehalten**. Ein Geheimnis, das nie gespeichert wurde und nicht übergeben wird, bleibt leer. | Referenzname | Ziel | |---|---| | `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` | ## Beispieldatei {#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). ``` Eine Datei kann eine beliebige Teilmenge der Abschnitte enthalten. Ein ausgelassener Abschnitt wird nicht angetastet. Eine Datei, die größer als 1 MB ist, ein fehlender `version: 1`, eine abweichende Versionsnummer oder ein unbekannter Abschnitt werden abgelehnt, bevor etwas ausgeführt wird. ## Abschnitte {#sections} | Bereich | Funktion | Hinweise | |---|---|---| | `branding` | Markenname (bis zu 60 Zeichen), Primärfarbe, Anzeigewährung (`usd` oder `vnd`), Verkäufername. | Logos sind nicht Teil der Datei; verwenden Sie die [branding page](https://nexcmp.com/de/docs/customers/branding/). | | `settings` | Eine feste Liste allgemeiner Einstellungen: `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`. | Andere Schlüssel werden ignoriert. | | `email.smtp` | SMTP-Host, Port, Sicherheit (`starttls`, `tls`, `none`), Benutzer, Passwort, Absendername und -adresse, Antwortadresse. | [SMTP and e-mail templates](https://nexcmp.com/de/docs/administration/smtp-and-emails/). Beim Ändern von Host, Port oder Sicherheit muss das Passwort erneut eingegeben werden. | | `telegram` | Alarmkanal an/aus, Chat-ID, Bot-Token. | [Telegram-Benachrichtigungen](https://nexcmp.com/de/docs/administration/telegram-notifications/). | | `modules` | Optionale Module an/aus (`key: true/false`). | Nur Schlüssel, die das Panel umschalten lässt. Siehe [Modules](https://nexcmp.com/de/docs/infrastructure/modules/). | | `currency` | Anzeigewährung und manueller USD-zu-VND-Kurs (`0` automatisch, ansonsten 15000 bis 50000). | Bereich Abrechnung. Siehe [Currency and exchange rates](https://nexcmp.com/de/docs/catalog/currency-and-exchange-rates/). | | `payments` | `stripe`-, `paypal`-, `crypto`-, `bank`-Zugangsdaten und `channels`-Schalter (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Bereich Abrechnung. Siehe [Payment channels](https://nexcmp.com/de/docs/billing/payment-channels/). | | `quotas` | `quota_*`-Limits. | Siehe [Quotas](https://nexcmp.com/de/docs/billing/quotas/). | | `zones` | Zonen nach `slug` (erforderlich: `slug`, `name`, `country`; optional `city`, `enabled`, `is_default`). | Neue Zonen werden erstellt. Eine bereits vorhandene Zone wird durch die Datei **nicht verändert**. Siehe [Zones](https://nexcmp.com/de/docs/infrastructure/zones/). | | `plans` | Tarife nach `slug` (erforderlich: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; optional `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Bereich Abrechnung. Neue Tarife werden erstellt, bestehende anhand des Slugs aktualisiert. Preise in USD pro Stunde. Siehe [Plans](https://nexcmp.com/de/docs/catalog/plans/). | | `ai_provider` | Der Panel-KI-Anbieter, der von der Kunden-KI (AI Chat und AI Agent) verwendet wird. | [AI provider](https://nexcmp.com/de/docs/ai/ai-providers/). | | `legal` | AGB- und Datenschutztext pro Sprache (`en`, `vi`). | [Legal pages](https://nexcmp.com/de/docs/customers/legal/). | Die Anwendungsreihenfolge entspricht der obigen Reihenfolge: infrastrukturähnliche Elemente vor Tarifen. ## Zu beachtende Regeln {#rules-to-remember} - **Idempotent.** Das zweimalige Anwenden derselben Datei ändert beim zweiten Mal nichts. `plan` zeigt "No changes". - **Keine Löschungen.** Die Datei entfernt niemals eine Zone, einen Tarif oder eine Einstellung. Das Entfernen eines Eintrags aus der Datei belässt das Panel unverändert. - **Es gelten weiterhin die normalen Sicherheitsregeln.** Über die Befehlszeile wird jede Änderung denselben Prüfungen wie eine API-Änderung unterzogen: Bereiche und IP-Regeln. Eine Änderung, die eine Bestätigung erfordert (z. B. ein weitenweiter Schalter), wird unter `pending` mit einer Vorschau statt der Anwendung gemeldet, es sei denn, Sie übergeben `--confirm-billing`, wodurch alle bestätigt werden. - **KI-Clients können die Abrechnung nicht entsperren.** Wenn `config_apply` von einem MCP-Client aufgerufen wird, wird `confirm_billing` ignoriert; Geldänderungen warten auf Sie. - **Vor der Anwendung prüfen.** Das JSON-Schema beschreibt jedes Feld. Verweisen Sie Ihren Editor darauf oder übergeben Sie es an eine KI, damit sie gültiges YAML schreibt: `https://cloud.example.com/v1/admin/agent/config/schema.json` (öffentlich lesbar). ### Abrechnungsbereiche {#billing-sections} `payments`, `currency` und `plans` ändern Preise oder Geldwege. `nexcmp config apply --yes` **überspringt** diese, es sei denn, Sie fügen `--confirm-billing` hinzu; sie werden dann unter `skipped` ("billing section - pass confirm_billing") aufgeführt. Das Flag ist Ihre Bestätigung: Damit wird jede Abrechnungsänderung in der Datei (und jede andere Änderung, die eine Bestätigung erfordert) ohne erneute Abfrage angewendet. Führen Sie zuerst `plan` aus und lesen Sie jede mit `$` markierte Zeile. Wenn dieselbe Datei von einer KI angewendet wird (dem `config_apply`-Tool in einem MCP-Client oder AI Chat), wird das Flag ignoriert, und Geldänderungen warten stattdessen auf Ihre Genehmigung. ## Verwenden Sie die Import/Export-Seite {#use-the-import-export-page} 1. Öffnen Sie **System › Settings › Import/Export**. 2. Klicken Sie unter **Export** auf **Get current configuration** und dann auf **Download .yaml**, um `nexcmp.yaml` zu speichern. Geheimnisse werden als Platzhalter angezeigt. 3. Wählen Sie unter **Import** eine Datei aus, ziehen Sie sie in das Feld oder fügen Sie das YAML ein. 4. Optional: Öffnen Sie **Secrets that come with it (not in the file)** und fügen Sie einen Namen und Wert für jede Referenz hinzu, z. B. `smtp_password`. 5. Klicken Sie auf **Preview changes**. Die Tabelle gruppiert die Änderungen nach Bereichen; geldbezogene Bereiche tragen das Tag "Money-related". Deaktivieren Sie Bereiche, die Sie nicht wünschen. 6. Wenn finanzbezogene Abschnitte aufgelistet sind, aktivieren Sie **Also apply money-related changes (prices, payment gateways, balances)**. Ohne diesen Haken werden sie übersprungen. 7. Klicken Sie auf **Apply selected**. Das Ergebnis zeigt an, was angewendet, übersprungen oder fehlgeschlagen ist. Eine Änderung, die als auf Bestätigung wartend zurückgegeben wird, erscheint als Bestätigungskarte; klicken Sie dort auf **Confirm**. Die Schaltfläche **JSON Schema** oben rechts öffnet das Schema. ![Import/Export-Seite mit der Export-Karte und der Import-Karte, die exportiertes YAML enthält](https://nexcmp.com/de/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Vorschautabelle der nach Abschnitten gruppierten Änderungen mit einem Abrechnungs-Tag und einer Schaltfläche zum Anwenden der Auswahl](https://nexcmp.com/de/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Beliebiges Tool über die Befehlszeile ausführen {#run-any-tool-from-the-command-line} `nexcmp admin` führt dieselben Tools wie die KI-Assistenten aus ([die Tool-Liste](https://nexcmp.com/de/docs/configure-with-ai/mcp-admin/#tools)) und gibt JSON aus: ```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"}}' ``` Argumente sind `key=value`-Paare (Werte werden als JSON eingelesen, wenn sie parsebar sind, ansonsten als Text) oder ein einzelnes `--json '{...}'`-Objekt. Wenn die Aktion eine Bestätigung erfordert, gibt der Befehl die Vorschau aus und stoppt mit dem Exit-Code 3 und „Nothing changed“. Lesen Sie die Vorschau und führen Sie denselben Befehl dann erneut mit `--yes` aus, um ihn anzuwenden. Wird der Befehl als Root ausgeführt, erhält er einen 15-minütigen Schlüssel mit allen Berechtigungen, sodass der Bestätigungsschritt Ihre Sicherheitsvorkehrung ist; mit `NEXCMP_KEY` gelten die eigenen Berechtigungen des Schlüssels. ## Verifizierung {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` direkt nach einem `apply --yes` gibt „No changes“ aus. 2. Im Admin-Bereich zeigen die geänderten Seiten die neuen Werte an, und **Logs › Admin actions** listet die Änderungen auf. 3. Das erneute Anwenden derselben Datei bewirkt keine Änderungen. ## Limits & Hinweise {#limits-notes} - Die Datei deckt die obigen Einstellungen ab, jedoch keine Kunden, Server, Rechnungen oder Infrastrukturquellen (CloudStack- und Proxmox-Verbindungen). Verbinden Sie diese über [AI Chat](https://nexcmp.com/de/docs/configure-with-ai/ai-chat-in-admin/) oder die Admin-Seiten. - Zonen und Tarife werden über `slug` abgeglichen. Benennen Sie einen Slug in der Datei nicht um: Er würde sonst als neues Element erstellt. - Die Größe eines Tarifs, den Kunden bereits nutzen, kann nicht geändert werden; erstellen Sie stattdessen einen neuen Tarif. - Bewahren Sie exportierte Dateien vertraulich auf, auch wenn sie keine Geheimnisse enthalten: Sie listen Ihre Preise, Adressen und Kontonamen auf. ## Fehlerbehebung {#troubleshooting} | Symptom | Ursache | Behebung | |---|---|---| | `missing version: 1` | Die Datei beginnt nicht mit `version: 1` | Fügen Sie diesen hinzu. | | `unsupported version 2` | Die Datei hat eine andere Versionsnummer | Dieses Panel liest nur Version 1. | | `unknown section 'x' (known: ...)` | Ein falsch geschriebener oder nicht unterstützter Schlüssel auf oberster Ebene | Verwenden Sie die obigen Abschnitte. | | `YAML error: ...` | Ungültiges YAML (Einrückung, Tabs) | Beheben Sie die in der Meldung genannte Zeile. | | `config is larger than 1 MB` | Datei zu groß | Teilen Sie sie auf und verwenden Sie `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | Der Befehl hat keinen Schlüssel gefunden | Führen Sie den Befehl mit `sudo` aus oder exportieren Sie `NEXCMP_KEY` und behalten Sie ihn über sudo bei. | | `panel not reachable` | Der Panel-Dienst läuft nicht auf dem Standardport | Überprüfen Sie `sudo nexcmp status`. | | Abrechnungszeilen unter `skipped` | Abrechnungsabschnitte erfordern `--confirm-billing` | Fügen Sie das Flag hinzu und überprüfen Sie zuerst die `$`-Zeilen. | | Elemente unter `pending` | Die Änderung erfordert eine Bestätigung | Öffnen Sie **API & AI agents** oder das Import/Export-Ergebnis und klicken Sie auf der Karte auf **Confirm**. | | Ein Geheimnis wurde nicht aktualisiert | Es wurde kein `NEXCMP_SECRET_`-Wert festgelegt, sodass das gespeicherte Geheimnis beibehalten wurde | Exportieren Sie die Variable und wenden Sie sie erneut an. | | Eintrag unter `errors` mit HTTP 403 `insufficient_scope` | Dem Schlüssel fehlt der Geltungsbereich dieses Abschnitts | Verwenden Sie einen Schlüssel mit dem entsprechenden Geltungsbereich oder führen Sie ihn als Root aus. | | Eintrag unter `errors` mit HTTP 403 `demo_read_only` | Demo-Panel | Auf einer echten Installation anwenden. |