Configuration as code

Where in the admin: System › Settings › Import/Export (/agent/config). Di server: perintah nexcmp config export, plan, dan apply, serta nexcmp admin <tool>.

Fungsi

Konfigurasi panel Anda (branding, pengaturan umum, email, peringatan Telegram, modul, mata uang, gateway pembayaran, batas, zona, paket, penyedia AI, dan halaman hukum) dapat disimpan sebagai satu file YAML. Anda dapat mengedit filenya sendiri, meminta asisten AI untuk mengeditnya, menyimpannya dalam kontrol versi, dan menerapkannya ke panel yang sama atau panel lainnya. Sebelum ada yang berubah, Anda akan selalu melihat daftar perbedaan. Rahasia tidak pernah ditulis ke dalam file.

Gunakan untuk mengkloning peninjauan ke instalasi kedua, untuk meninjau perubahan sebelum ditayangkan, untuk memulihkan pengaturan setelah terjadi kesalahan, atau untuk membiarkan AI mengusulkan seluruh konfigurasi yang Anda baca sebagai satu dokumen.

Persyaratan

Item	Persyaratan
NexCMP	1.4.0 atau lebih baru.
Baris perintah	Anda adalah root di server panel (gunakan sudo). Perintah ini meminta kunci sementara dari panel (15 menit, semua cakupan) dengan sendirinya. Untuk menggunakan kunci yang lebih terbatas sebagai gantinya, tetapkan NEXCMP_KEY ke admin API key dan simpan melalui sudo, misalnya sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml.
Halaman admin	Masuk ke admin. Halaman ini hanya-baca pada panel demo.
Rahasia	Nilai yang disediakan pada saat penerapan (lihat Secrets); tidak pernah di dalam file.

Ekspor, edit, pratinjau, terapkan

1. Ekspor konfigurasi saat ini:

   sudo nexcmp config export -o nexcmp.yaml

   Tanpa -o, YAML dicetak ke layar.

2. Edit nexcmp.yaml (lihat example di bawah). Tetap simpan version: 1 di atas.

3. Pratinjau apa yang akan berubah. Ini tidak mengubah apa pun:

   sudo nexcmp config plan -f nexcmp.yaml

   Setiap baris menunjukkan bagian, item, bidang, dan old → new. Baris bertanda $ termasuk dalam bagian penagihan (lihat Billing sections). Jika panel sudah cocok dengan file, Anda akan melihat "No changes".

4. Terapkan. Tanpa --yes, perintah ini berupa dry run dan hanya mencetak daftar yang sama:

   sudo nexcmp config apply -f nexcmp.yaml --yes

5. Baca hasilnya: applied, pending (menunggu konfirmasi Anda), skipped, dan errors.

Opsi	Arti
-f <file>	File YAML (diperlukan untuk plan dan apply).
--yes	Terapkan secara nyata. Tanpa itu, apply adalah dry run.
--confirm-billing	Terapkan juga bagian penagihan (payments, currency, plans). Tanpa itu, bagian tersebut akan dilewati.
--section <name>	Terapkan hanya bagian ini. Ulangi opsi ini untuk beberapa bagian.
-o <file>	Dengan export: tulis YAML ke sebuah file.

Kode keluar adalah 0 ketika semuanya berhasil diterapkan atau tidak ada yang berubah, 1 ketika kesalahan dikembalikan, 2 untuk kesalahan penggunaan atau kunci.

Rahasia

File tersebut menyimpan referensi alih-alih rahasia, seperti password: secret://smtp_password. Pada saat penerapan, nilai berasal dari variabel lingkungan bernama NEXCMP_SECRET_ ditambah nama referensi dalam huruf kapital:

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

Jika referensi tidak memiliki nilai, rahasia yang sudah disimpan di panel akan tetap disimpan. Rahasia yang tidak pernah disimpan dan tidak disediakan akan tetap kosong.

Nama referensi	Tujuannya
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

Contoh file

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

Sebuah file dapat berisi bagian mana pun dari subset. Bagian yang Anda lewatkan tidak akan disentuh. File yang lebih besar dari 1 MB, version: 1 yang hilang, nomor versi yang berbeda, atau bagian yang tidak dikenal akan ditolak sebelum ada yang berjalan.

Bagian

Bagian	Yang dikendalikan	Catatan
branding	Nama merek (hingga 60 karakter), warna primer, mata uang tampilan (usd atau vnd), nama penjual.	Logo bukan bagian dari file; gunakan branding page.
settings	Daftar tetap pengaturan umum: 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.	Kunci lainnya diabaikan.
email.smtp	Host SMTP, port, keamanan (starttls, tls, none), pengguna, kata sandi, nama dan alamat pengirim, balas-ke.	SMTP and e-mail templates. Mengubah host, port, atau keamanan memerlukan kata sandi lagi.
telegram	Saluran pemberitahuan aktif atau nonaktif, chat ID, bot token.	Telegram notifications.
modules	Modul opsional aktif atau nonaktif (key: true/false).	Hanya tombol yang diizinkan oleh panel. Lihat Modules.
currency	Mata uang tampilan dan kurs manual USD ke VND (0 otomatis, jika tidak 15000 hingga 50000).	Bagian penagihan. Lihat Currency and exchange rates.
payments	Kredensial stripe, paypal, crypto, bank dan tombol channels (pay_card_enabled, pay_wallets_enabled, pay_alipay_enabled, pay_paypal_enabled, pay_usdt_enabled, pay_sepay_enabled).	Bagian penagihan. Lihat Payment channels.
quotas	Batas quota_*.	Lihat Quotas.
zones	Zona berdasarkan slug (wajib: slug, name, country; opsional city, enabled, is_default).	Zona baru dibuat. Zona yang sudah ada tidak diubah oleh file tersebut. Lihat Zones.
plans	Paket berdasarkan slug (wajib: slug, name, cpu, ram_mb, disk_gb, hourly_usd; opsional cs_offering_id, backend_id, zone_id, enabled, visible, sort, description).	Bagian penagihan. Paket baru dibuat, paket yang sudah ada diperbarui berdasarkan slug. Harga dalam USD per jam. Lihat Plans.
ai_provider	Provider AI panel yang digunakan oleh AI Chat dan AI Agent pelanggan.	AI provider.
legal	Teks syarat dan privasi per bahasa (en, vi).	Legal pages.

Urutan penerapan adalah urutan di atas: item mirip infrastruktur sebelum paket.

Aturan yang perlu diingat

• Idempoten. Menerapkan file yang sama dua kali tidak mengubah apa pun pada kali kedua. plan menampilkan "No changes".
• Tanpa penghapusan. File tidak pernah menghapus zona, paket, atau pengaturan. Menghapus entri dari file membiarkan panel seperti apa adanya.
• Aturan keamanan normal tetap berlaku. Dari baris perintah, setiap perubahan dikirim melalui pemeriksaan yang sama seperti perubahan API: cakupan dan aturan IP. Perubahan yang memerlukan konfirmasi (misalnya tombol tingkat situs) dilaporkan di bawah pending dengan pratinjau alih-alih langsung diterapkan, kecuali Anda meneruskan --confirm-billing, yang mengonfirmasi semuanya.
• Klien AI tidak dapat membuka kunci penagihan. Ketika config_apply dipanggil oleh klien MCP, confirm_billing diabaikan; perubahan uang menunggu persetujuan Anda.
• Periksa sebelum Anda menerapkannya. Skema JSON menjelaskan setiap field. Arahkan editor Anda ke sana, atau berikan ke AI agar menulis YAML yang valid: https://cloud.example.com/v1/admin/agent/config/schema.json (dapat dibaca publik).

Bagian penagihan

payments, currency, dan plans mengubah harga atau jalur uang. nexcmp config apply --yes mengabaikannya kecuali Anda menambahkan --confirm-billing; perubahan tersebut kemudian dicantumkan di bawah skipped ("billing section - pass confirm_billing"). Flag tersebut adalah konfirmasi Anda: dengannya, setiap perubahan penagihan dalam file (dan perubahan lain yang akan meminta konfirmasi) diterapkan tanpa prompt kedua. Jalankan plan terlebih dahulu dan baca setiap baris yang ditandai $.

Ketika file yang sama diterapkan oleh AI (alat config_apply di klien MCP atau AI Chat), flag tersebut diabaikan, dan perubahan uang akan menunggu persetujuan Anda.

Gunakan halaman Import/Export

1. Buka System › Settings › Import/Export.
2. Di bawah Export klik Get current configuration, lalu Download .yaml untuk menyimpan nexcmp.yaml. Rahasia muncul sebagai placeholder.
3. Di bawah Import pilih file, seret ke dalam kotak, atau tempel YAML.
4. Opsional: buka Secrets that come with it (not in the file) dan tambahkan nama serta nilai untuk setiap referensi, misalnya smtp_password.
5. Klik Preview changes. Tabel mengelompokkan perubahan menurut bagian; bagian yang terkait dengan uang membawa tag "Money-related". Hilangkan centang pada bagian yang tidak Anda inginkan.
6. Jika bagian yang berkaitan dengan keuangan tercantum, centang Also apply money-related changes (prices, payment gateways, balances). Tanpa centang tersebut, bagian itu akan dilewati.
7. Klik Apply selected. Hasilnya menunjukkan apa saja yang diterapkan, dilewati, atau gagal. Perubahan yang dikembalikan sebagai menunggu konfirmasi akan muncul sebagai kartu konfirmasi; tekan Confirm pada kartu tersebut.

Tombol JSON Schema di kanan atas akan membuka skema.

Jalankan alat apa pun dari baris perintah

nexcmp admin menjalankan alat yang sama seperti asisten AI (daftar alat) dan mencetak JSON:

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"}}'

Argumen berupa pasangan key=value (nilai dibaca sebagai JSON saat diurai, jika tidak sebagai teks) atau satu objek --json '{...}'. Jika tindakan memerlukan konfirmasi, perintah akan mencetak pratinjau dan berhenti dengan kode keluar 3 serta "Nothing changed". Baca pratinjau tersebut, lalu jalankan kembali perintah yang sama dengan --yes untuk menerapkannya. Saat dijalankan sebagai root, perintah akan mendapatkan kunci 15 menit dengan semua cakupan, sehingga langkah konfirmasi adalah pengaman Anda; dengan NEXCMP_KEY, cakupan kunci Anda sendiri yang akan berlaku.

Verifikasi

1. sudo nexcmp config plan -f nexcmp.yaml tepat setelah apply --yes mencetak "No changes".
2. Di admin, halaman yang Anda ubah akan menampilkan nilai baru, dan Logs › Admin actions mencantumkan perubahan tersebut.
3. Menerapkan file yang sama lagi tidak akan mengubah apa pun.

Batas & catatan

• File ini mencakup pengaturan di atas, bukan pelanggan, server, tagihan, atau sumber infrastruktur (koneksi CloudStack dan Proxmox). Hubungkan komponen tersebut menggunakan AI Chat atau halaman admin.
• Zona dan paket dicocokkan dengan slug. Jangan ganti nama slug di dalam file: slug tersebut akan dibuat sebagai item baru.
• Paket yang sudah digunakan oleh pelanggan tidak dapat diubah ukurannya; buat paket baru sebagai gantinya.
• Jaga kerahasiaan file yang diekspor meskipun tidak berisi data rahasia: file tersebut mencantumkan harga, alamat, dan nama akun Anda.

Pemecahan Masalah

Gejala	Penyebab	Solusi
missing version: 1	File tidak dimulai dengan version: 1	Tambahkan file tersebut.
unsupported version 2	File memiliki nomor versi yang berbeda	Panel ini hanya membaca versi 1.
unknown section 'x' (known: ...)	Kunci tingkat atas salah eja atau tidak didukung	Gunakan bagian di atas.
YAML error: ...	YAML tidak valid (indentasi, tab)	Perbaiki baris yang disebutkan oleh pesan tersebut.
config is larger than 1 MB	File terlalu besar	Pecah file tersebut dan gunakan --section.
no API key: set NEXCMP_KEY=ak_... or run as root on the server	Perintah tidak menemukan kunci	Jalankan dengan sudo, atau ekspor NEXCMP_KEY dan pertahankan melalui sudo.
panel not reachable	Layanan panel tidak berjalan pada port default	Periksa sudo nexcmp status.
Baris penagihan di bawah skipped	Bagian penagihan memerlukan --confirm-billing	Tambahkan tanda (flag) tersebut dan tinjau baris $ terlebih dahulu.
Item di bawah pending	Perubahan memerlukan konfirmasi	Buka API & AI agents, atau hasil Import/Export, lalu tekan Confirm pada kartu tersebut.
Rahasia tidak diperbarui	Tidak ada nilai NEXCMP_SECRET_<NAME> yang ditetapkan, sehingga rahasia yang disimpan tetap dipertahankan	Ekspor variabel tersebut dan terapkan kembali.
Entri di bawah errors dengan HTTP 403 insufficient_scope	Kunci tidak memiliki cakupan (scope) untuk bagian tersebut	Gunakan kunci yang memiliki cakupan tersebut, atau jalankan sebagai root.
Entri di bawah errors dengan HTTP 403 demo_read_only	Panel demo	Terapkan pada instalasi nyata.