Konfiguration als Code

Wo im Admin: System › Settings › Import/Export (/agent/config). Auf dem Server: die Befehle nexcmp config export, plan und apply sowie nexcmp admin <tool>.

Funktion

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

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 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); niemals innerhalb der Datei.

Exportieren, bearbeiten, vorschauen, anwenden

1. Exportieren Sie die aktuelle Konfiguration:

   sudo nexcmp config export -o nexcmp.yaml

   Ohne -o wird das YAML auf dem Bildschirm ausgegeben.

2. Bearbeiten Sie nexcmp.yaml (siehe das Beispiel unten). Behalten Sie version: 1 oben bei.

3. Zeigen Sie eine Vorschau der Änderungen an. Dies ändert nichts:

   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). 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:

   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 <file>	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 <name>	Wenden Sie nur diesen Abschnitt an. Wiederholen Sie die Option für mehrere.
-o <file>	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

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:

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

# 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

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.
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. Beim Ändern von Host, Port oder Sicherheit muss das Passwort erneut eingegeben werden.
telegram	Alarmkanal an/aus, Chat-ID, Bot-Token.	Telegram-Benachrichtigungen.
modules	Optionale Module an/aus (key: true/false).	Nur Schlüssel, die das Panel umschalten lässt. Siehe Modules.
currency	Anzeigewährung und manueller USD-zu-VND-Kurs (0 automatisch, ansonsten 15000 bis 50000).	Bereich Abrechnung. Siehe 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.
quotas	quota_*-Limits.	Siehe 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.
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.
ai_provider	Der Panel-KI-Anbieter, der von der Kunden-KI (AI Chat und AI Agent) verwendet wird.	AI provider.
legal	AGB- und Datenschutztext pro Sprache (en, vi).	Legal pages.

Die Anwendungsreihenfolge entspricht der obigen Reihenfolge: infrastrukturähnliche Elemente vor Tarifen.

Zu beachtende Regeln

• 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

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

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.

Beliebiges Tool über die Befehlszeile ausführen

nexcmp admin führt dieselben Tools wie die KI-Assistenten aus (die Tool-Liste) und gibt JSON aus:

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

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

• Die Datei deckt die obigen Einstellungen ab, jedoch keine Kunden, Server, Rechnungen oder Infrastrukturquellen (CloudStack- und Proxmox-Verbindungen). Verbinden Sie diese über AI Chat 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

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_<NAME>-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.