Cấu hình dưới dạng mã

Vị trí trong admin: System › Settings › Import/Export (/agent/config). Trên máy chủ: các lệnh nexcmp config export, plan và apply, cùng nexcmp admin <tool>.

Chức năng

Cấu hình panel của bạn (branding, cài đặt chung, email, cảnh báo Telegram, module, tiền tệ, cổng thanh toán, giới hạn, zone, gói dịch vụ, nhà cung cấp AI và các trang pháp lý) có thể được lưu thành một file YAML duy nhất. Bạn có thể tự chỉnh sửa file, nhờ trợ lý AI chỉnh sửa, lưu vào hệ thống quản lý phiên bản và áp dụng cho cùng panel đó hoặc panel khác. Trước khi có bất kỳ thay đổi nào, bạn luôn thấy danh sách khác biệt. Secret không bao giờ được ghi vào file.

Hãy dùng tính năng này để sao chép cấu hình sang bản cài đặt thứ hai, xem xét thay đổi trước khi áp dụng thực tế, khôi phục cài đặt sau sự cố hoặc để AI đề xuất toàn bộ cấu hình giúp bạn xem lại trong một tài liệu duy nhất.

Yêu cầu

Hạng mục	Yêu cầu
NexCMP	1.4.0 trở lên.
Dòng lệnh	Bạn là `root` trên máy chủ panel (dùng `sudo`). Lệnh này sẽ tự động yêu cầu panel cấp một key tạm thời (15 phút, tất cả scope). Để dùng một key có phạm vi hẹp hơn, hãy đặt `NEXCMP_KEY` thành một admin API key và giữ nguyên biến qua sudo, ví dụ `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`.
Trang Admin	Đã đăng nhập vào admin. Trang này ở chế độ chỉ đọc trên panel demo.
Bí mật	Giá trị được cung cấp tại thời điểm áp dụng (xem Secrets); không bao giờ nằm trong file.

Xuất, chỉnh sửa, xem trước, áp dụng

Xuất cấu hình hiện tại:
bash
```
sudo nexcmp config export -o nexcmp.yaml
```
Nếu không có -o, nội dung YAML sẽ được in ra màn hình.
Chỉnh sửa nexcmp.yaml (xem ví dụ bên dưới). Giữ version: 1 ở dòng đầu tiên.
Xem trước những thay đổi dự kiến. Lệnh này không thay đổi bất kỳ điều gì:
bash
```
sudo nexcmp config plan -f nexcmp.yaml
```
Mỗi dòng hiển thị section, item, trường và old → new. Các dòng có dấu $ thuộc về các section thanh toán (xem Billing sections). Nếu panel đã khớp với file, bạn sẽ thấy "No changes".
Áp dụng. Nếu không có --yes, lệnh sẽ chạy ở chế độ dry run và chỉ in ra danh sách tương tự:
bash
```
sudo nexcmp config apply -f nexcmp.yaml --yes
```
Đọc kết quả: applied, pending (chờ bạn xác nhận), skipped và errors.

Tùy chọn	Ý nghĩa
`-f <file>`	File YAML (bắt buộc đối với `plan` và `apply`).
`--yes`	Thực sự áp dụng. Nếu không có tùy chọn này, `apply` sẽ là dry run.
`--confirm-billing`	Áp dụng cả các section thanh toán (`payments`, `currency`, `plans`). Nếu không có tùy chọn này, chúng sẽ bị bỏ qua.
`--section <name>`	Chỉ áp dụng section này. Lặp lại tùy chọn nếu muốn áp dụng nhiều section.
`-o <file>`	Khi dùng `export`: ghi nội dung YAML vào file.

Mã thoát (exit code) là 0 khi mọi thứ đã được áp dụng hoặc không có gì thay đổi, 1 khi có lỗi trả về, 2 khi sai cú pháp sử dụng hoặc lỗi key.

Bí mật

File chứa các tham chiếu thay vì secret, ví dụ password: secret://smtp_password. Khi áp dụng, giá trị sẽ được lấy từ biến môi trường có tên NEXCMP_SECRET_ kết hợp với tên tham chiếu viết hoa:

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

Nếu một tham chiếu không có giá trị, secret đã lưu trong panel sẽ được giữ nguyên. Secret chưa từng được lưu và không được cung cấp sẽ để trống.

Tên tham chiếu	Nơi áp dụng
`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`

File mẫu

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

Một file có thể chứa tập hợp con bất kỳ của các section. Section mà bạn bỏ qua sẽ không bị tác động. File lớn hơn 1 MB, thiếu version: 1, phiên bản khác hoặc chứa section không xác định sẽ bị từ chối trước khi có bất kỳ thao tác nào được thực thi.

Các mục

Mục	Nội dung điều khiển	Ghi chú
`branding`	Tên thương hiệu (tối đa 60 ký tự), màu chủ đạo, đơn vị tiền tệ hiển thị (`usd` hoặc `vnd`), tên người bán.	Logo không nằm trong file; hãy dùng trang thương hiệu.
`settings`	Danh sách cố định các cài đặt chung: `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`.	Các key khác sẽ bị bỏ qua.
`email.smtp`	SMTP host, port, bảo mật (`starttls`, `tls`, `none`), user, password, tên và địa chỉ người gửi, reply-to.	SMTP và mẫu e-mail. Việc thay đổi host, port hoặc bảo mật yêu cầu nhập lại password.
`telegram`	Bật hoặc tắt kênh cảnh báo, chat id, bot token.	Thông báo Telegram.
`modules`	Bật hoặc tắt các module tùy chọn (`key: true/false`).	Chỉ các key mà panel cho phép bật/tắt. Xem Modules.
`currency`	Đơn vị tiền tệ hiển thị và tỷ giá USD sang VND thủ công (`0` tự động, nếu không sẽ từ 15000 đến 50000).	Section billing. Xem Tiền tệ và tỷ giá hối đoái.
`payments`	Thông tin xác thực `stripe`, `paypal`, `crypto`, `bank` và các công tắc `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`).	Section billing. Xem Kênh thanh toán.
`quotas`	Giới hạn `quota_*`.	Xem Quotas.
`zones`	Các zone theo `slug` (bắt buộc: `slug`, `name`, `country`; tùy chọn `city`, `enabled`, `is_default`).	Các zone mới sẽ được tạo. Zone đã tồn tại sẽ không bị thay đổi bởi file. Xem Zones.
`plans`	Các plan theo `slug` (bắt buộc: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; tùy chọn `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`).	Section billing. Các plan mới sẽ được tạo, plan hiện có được cập nhật theo slug. Giá tính theo USD mỗi giờ. Xem Plans.
`ai_provider`	Nhà cung cấp AI của panel được dùng cho AI Chat và AI Agent của khách hàng.	AI provider.
`legal`	Nội dung điều khoản và quyền riêng tư theo từng ngôn ngữ (`en`, `vi`).	Trang pháp lý.

Thứ tự áp dụng tuân theo danh sách trên: các mục hạ tầng trước, plan sau.

Các quy tắc cần nhớ

Idempotent. Áp dụng cùng một file hai lần sẽ không làm thay đổi gì ở lần thứ hai. plan hiển thị "No changes".
Không xóa dữ liệu. File không bao giờ xóa zone, plan hay cài đặt. Xóa một mục khỏi file vẫn sẽ giữ nguyên trạng thái trên panel.
Các quy tắc an toàn thông thường vẫn được áp dụng. Từ dòng lệnh, mỗi thay đổi đều trải qua các bước kiểm tra tương tự như thay đổi qua API: scope và quy tắc IP. Thay đổi cần xác nhận (ví dụ: công tắc ảnh hưởng toàn hệ thống) sẽ được báo cáo dưới pending kèm bản xem trước thay vì được áp dụng ngay, trừ khi bạn truyền --confirm-billing để xác nhận tất cả.
Client AI không thể mở khóa billing. Khi config_apply được gọi bởi client MCP, confirm_billing sẽ bị bỏ qua; các thay đổi liên quan đến tiền bạc sẽ chờ bạn xác nhận.
Kiểm tra trước khi áp dụng. JSON Schema mô tả chi tiết từng trường. Hãy trỏ trình soạn thảo vào schema này hoặc cung cấp cho AI để tạo file YAML hợp lệ: https://cloud.example.com/v1/admin/agent/config/schema.json (cho phép đọc công khai).

Các section billing

payments, currency và plans làm thay đổi giá hoặc luồng tiền. nexcmp config apply --yes bỏ qua các mục này trừ khi bạn thêm --confirm-billing; khi đó chúng được liệt kê dưới skipped ("billing section - pass confirm_billing"). Cờ này đóng vai trò xác nhận: khi có nó, mọi thay đổi billing trong file (và bất kỳ thay đổi nào khác yêu cầu xác nhận) sẽ được áp dụng mà không cần hỏi lại. Hãy chạy plan trước và đọc kỹ từng dòng được đánh dấu $.

Khi tệp tương tự được áp dụng bởi AI (công cụ config_apply trong MCP client hoặc AI Chat), cờ này sẽ bị bỏ qua và các thay đổi liên quan đến tiền sẽ chờ bạn phê duyệt.

Sử dụng trang Import/Export

Mở System › Settings › Import/Export.
Dưới mục Export, nhấp vào Get current configuration, sau đó chọn Download .yaml để lưu nexcmp.yaml. Các secret sẽ hiển thị dưới dạng placeholder.
Dưới mục Import, hãy chọn một tệp, kéo tệp vào khung hoặc dán nội dung YAML.
Tùy chọn: mở Secrets that come with it (not in the file) rồi thêm tên và giá trị cho từng tham chiếu, ví dụ smtp_password.
Nhấp vào Preview changes. Bảng sẽ nhóm các thay đổi theo từng phần; các phần liên quan đến tiền sẽ có nhãn "Money-related". Bỏ chọn những phần bạn không muốn áp dụng.
Nếu có các phần liên quan đến tiền được liệt kê, hãy đánh dấu chọn Also apply money-related changes (prices, payment gateways, balances). Nếu không chọn, các phần này sẽ bị bỏ qua.
Nhấp vào Apply selected. Kết quả sẽ hiển thị những gì đã được áp dụng, bỏ qua hoặc thất bại. Thay đổi nào được trả về ở trạng thái chờ xác nhận sẽ xuất hiện dưới dạng thẻ xác nhận; hãy nhấn Confirm trên thẻ đó.

Nút JSON Schema ở góc trên bên phải sẽ mở schema.

Chạy bất kỳ công cụ nào từ dòng lệnh

nexcmp admin chạy cùng các công cụ như trợ lý AI (danh sách công cụ) và xuất ra 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"}}'

Các đối số là các cặp key=value (giá trị được đọc dưới dạng JSON khi parse được, nếu không sẽ là văn bản) hoặc một đối tượng --json '{...}'. Nếu thao tác cần xác nhận, lệnh sẽ in bản xem trước và dừng lại với mã thoát 3 kèm thông báo "Nothing changed". Hãy đọc bản xem trước, sau đó chạy lại lệnh với --yes để áp dụng. Khi chạy dưới quyền root, lệnh sẽ nhận một khóa 15 phút với đầy đủ phạm vi quyền, vì vậy bước xác nhận là chốt an toàn của bạn; với NEXCMP_KEY, phạm vi quyền riêng của khóa sẽ được áp dụng.

Kiểm tra

sudo nexcmp config plan -f nexcmp.yaml ngay sau apply --yes sẽ in ra "No changes".
Trong trang admin, các trang bạn đã thay đổi sẽ hiển thị giá trị mới, và Logs › Admin actions sẽ liệt kê các thay đổi.
Áp dụng lại cùng một tệp sẽ không thay đổi bất kỳ điều gì.

Hạn mức & lưu ý

Tệp này áp dụng cho các cài đặt ở trên, không bao gồm khách hàng, máy chủ, hóa đơn hay tài nguyên hạ tầng (kết nối CloudStack và Proxmox). Hãy kết nối các mục đó bằng AI Chat hoặc qua các trang admin.
Zone và plan được khớp theo slug. Không đổi tên slug trong tệp: nó sẽ được tạo thành một mục mới.
Không thể thay đổi quy mô của plan mà khách hàng đang sử dụng; thay vào đó hãy tạo một plan mới.
Hãy bảo mật các tệp đã xuất dù chúng không chứa secret: chúng liệt kê giá cả, địa chỉ và tên tài khoản của bạn.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
`missing version: 1`	Tệp không bắt đầu bằng `version: 1`	Thêm vào.
`unsupported version 2`	Tệp có số phiên bản khác	Panel này chỉ đọc phiên bản 1.
`unknown section 'x' (known: ...)`	Khóa top-level bị viết sai chính tả hoặc không được hỗ trợ	Sử dụng các phần ở trên.
`YAML error: ...`	YAML không hợp lệ (thụt lề, ký tự tab)	Sửa dòng được chỉ ra trong thông báo.
`config is larger than 1 MB`	Tệp quá lớn	Chia nhỏ tệp và sử dụng `--section`.
`no API key: set NEXCMP_KEY=ak_... or run as root on the server`	Lệnh không tìm thấy khóa	Chạy bằng `sudo`, hoặc export `NEXCMP_KEY` và giữ biến môi trường đó qua sudo.
`panel not reachable`	Dịch vụ panel không chạy trên cổng mặc định	Kiểm tra `sudo nexcmp status`.
Các dòng billing dưới `skipped`	Các phần billing cần `--confirm-billing`	Thêm cờ này và xem lại các dòng `$` trước.
Các mục dưới `pending`	Thay đổi cần được xác nhận	Mở API & AI agents, hoặc kết quả Import/Export, rồi nhấn Confirm trên thẻ.
Secret không được cập nhật	Không có giá trị `NEXCMP_SECRET_<NAME>` nào được thiết lập, nên secret đã lưu được giữ nguyên	Export biến này và áp dụng lại.
Mục dưới `errors` gặp lỗi HTTP 403 `insufficient_scope`	Key thiếu scope của phần đó	Sử dụng key có scope này, hoặc chạy dưới quyền root.
Mục dưới `errors` gặp lỗi HTTP 403 `demo_read_only`	Panel demo	Áp dụng trên bản cài đặt thực tế.

Cấu hình dưới dạng mã ​

Chức năng ​

Yêu cầu ​

Xuất, chỉnh sửa, xem trước, áp dụng ​

Bí mật ​

File mẫu ​

Các mục ​

Các quy tắc cần nhớ ​

Các section billing ​

Sử dụng trang Import/Export ​

Chạy bất kỳ công cụ nào từ dòng lệnh ​

Kiểm tra ​

Hạn mức & lưu ý ​

Xử lý sự cố ​