代码化配置

后台位置： System › Settings › Import/Export（/agent/config）。在服务器上：命令 nexcmp config export、plan 和 apply，以及 nexcmp admin <tool>。

功能说明

您的面板配置（品牌、常规设置、电子邮件、Telegram警报、模块、货币、支付网关、限制、区域、套餐、AI提供商以及法律页面）可以保存为一个YAML文件。您可以自行编辑该文件、让AI助手协助编辑、将其纳入版本控制，或将其应用到相同或另一个面板中。在任何更改生效之前，您总能看到差异对比列表。敏感信息绝不会写入该文件。

使用它可以将配置克隆到第二个安装实例、在上线前审查更改、在出错后恢复设置，或者让AI生成一个作为完整文档供您阅读的整体配置。

前提条件

项目	要求
NexCMP	1.4.0或更高版本。
命令行	您是面板服务器上的`root`（请使用`sudo`）。该命令会自动向面板请求一个临时密钥（15分钟，所有权限范围）。若要改用权限更窄的密钥，请将`NEXCMP_KEY`设置为一个admin API key并通过sudo保留它，例如`sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`。
管理页面	已登录管理员账号。在演示面板上此页面为只读。
机密	在应用时提供的值（见Secrets）；绝不放在文件内部。

导出、编辑、预览、应用

导出当前配置：
bash
```
sudo nexcmp config export -o nexcmp.yaml
```
不加-o时，YAML将直接打印到屏幕上。
编辑nexcmp.yaml（参见下方的example）。请将version: 1放在顶部。
预览将要产生的更改。这不会做任何修改：
bash
```
sudo nexcmp config plan -f nexcmp.yaml
```
每行显示部分、项目、字段和old → new。标记为$的行属于计费部分（见Billing sections）。如果面板已经与文件匹配，您将看到“No changes”。
应用。不加--yes时，该命令为预演运行（dry run），仅打印相同的列表：
bash
```
sudo nexcmp config apply -f nexcmp.yaml --yes
```
读取结果：applied、pending（等待您的确认）、skipped和errors。

选项	说明
`-f <file>`	YAML文件（`plan`和`apply`所必需）。
`--yes`	真正应用。没有它，`apply`将只是预演运行。
`--confirm-billing`	同时应用计费部分（`payments`、`currency`、`plans`）。没有它这些部分将被跳过。
`--section <name>`	仅应用此部分。若要应用多个部分可重复使用该选项。
`-o <file>`	带有`export`时：将YAML写入文件。

当所有内容应用成功或无更改时退出代码为0，返回错误时为1，用法或密钥错误时为2。

机密

该文件保存的是引用而非密钥，例如 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

如果某个引用没有值，则面板中先前保存的密钥将被保留。从未保存且未提供的密钥将保持为空。

Reference name	Where it goes
`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).

文件可以包含各部分的任意子集。未包含的部分不会被修改。大于 1 MB 的文件、缺失的 version: 1、不同的版本号或未知的部分都会在运行前被拒绝。

部分

板块	What it controls	备注
`branding`	品牌名称（最多 60 个字符）、主色调、显示货币（`usd` 或 `vnd`）、卖家名称。	徽标不属于该文件；请使用 branding page。
`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。更改主机、端口或安全设置需要重新输入密码。
`telegram`	报警通道开启或关闭、chat id、bot token。	Telegram notifications。
`modules`	可选模块开启或关闭（`key: true/false`）。	仅限面板允许切换的键。参见Modules。
`currency`	显示货币和手动USD兑VND汇率（`0`时为自动，否则为15000至50000）。	计费部分。参见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。
`quotas`	`quota_*`限制。	参见Quotas。
`zones`	按`slug`划分的区域（必填：`slug`、`name`、`country`；可选：`city`、`enabled`、`is_default`）。	将创建新区域。已存在的区域文件不会更改。参见Zones。
`plans`	按`slug`划分的套餐（必填：`slug`、`name`、`cpu`、`ram_mb`、`disk_gb`、`hourly_usd`；可选：`cs_offering_id`、`backend_id`、`zone_id`、`enabled`、`visible`、`sort`、`description`）。	计费部分。将创建新套餐，现有套餐将通过slug更新。价格为每小时USD。参见Plans。
`ai_provider`	供客户AI Chat和AI Agent使用的面板AI提供商。	AI provider。
`legal`	各语言的服务条款和隐私文本（`en`、`vi`）。	Legal pages。

应用顺序与上述顺序相同：基础设施类项优先于套餐。

注意事项

幂等。 第二次应用相同文件不会产生任何更改。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（公开可读）。

计费部分

payments、currency和plans会更改价格或资金路径。nexcmp config apply --yes会跳过它们，除非您添加--confirm-billing；它们随后将列在skipped（“billing section - pass confirm_billing”）下。该标志即是您的确认：有了它，文件中的每个计费更改（以及任何其他需要确认的更改）都将直接应用，无需二次提示。请先运行plan并阅读标记为$的每一行。

当AI（MCP客户端或AI Chat中的config_apply工具）应用同一个文件时，该标志将被忽略，资金变动转而等待您的批准。

使用Import/Export页面

打开System › Settings › Import/Export。
在Export下点击Get current configuration，然后点击Download .yaml保存nexcmp.yaml。密钥将显示为占位符。
在Import下选择文件、将其拖入框中或粘贴YAML。
可选：打开Secrets that come with it (not in the file)，为每个引用添加名称和值，例如smtp_password。
点击Preview changes。表格按部分对更改进行分组；与资金相关的部分带有“Money-related”标签。取消勾选您不需要的部分。
如果列出了与资金相关的部分，请勾选同时应用与资金相关的更改（价格、支付网关、余额）。如果不勾选，则会跳过这些部分。
点击Apply selected。结果会显示已应用、已跳过或失败的内容。返回为等待确认的更改会显示为一个确认卡片；请点击其上的Confirm。

右上角的JSON Schema按钮可打开架构。

从命令行运行任意工具

nexcmp admin运行与AI助手相同的工具（the tool list）并输出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读取，否则作为文本读取）或一个--json '{...}'对象。如果操作需要确认，命令将打印预览并以退出码3及“Nothing changed”停止。请阅读预览，然后使用--yes再次运行该命令以应用它。以root身份运行该命令将获得一个具有所有作用域的15分钟密钥，因此确认步骤就是你的安全保障；使用NEXCMP_KEY时则应用密钥自身的作用域。

验证

sudo nexcmp config plan -f nexcmp.yaml在运行apply --yes后会显示 "No changes"。
在管理后台中，你修改过的页面将显示新值，并且Logs › Admin actions会列出这些更改。
再次应用同一个文件不会产生任何更改。

限制与注意事项

该文件涵盖上述设置，不包括客户、服务器、发票或基础设施源（CloudStack和Proxmox连接）。请使用AI Chat或管理后台页面来连接这些内容。
可用区和套餐通过slug进行匹配。请勿在文件中重命名slug：否则它会被创建为一个新项目。
已被客户使用的套餐无法更改其大小；请改为创建一个新套餐。
请妥善保管已导出的文件，即使它们不包含机密信息：它们列出了你的价格、地址和账户名称。

故障排查

症状	原因	解决办法
`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或导入/导出结果，并点击卡片上的Confirm。
机密未更新	未设置`NEXCMP_SECRET_<NAME>`值，因此保留了已保存的机密	导出变量并再次应用。
`errors`下的条目，带有HTTP 403 `insufficient_scope`	密钥缺少该部分的作用域	使用具有该作用域的密钥，或以root身份运行。
`errors`下的条目，带有HTTP 403 `demo_read_only`	演示面板	在真实安装中应用。

代码化配置 ​

功能说明 ​

前提条件 ​

导出、编辑、预览、应用 ​

机密 ​

Example file ​

部分 ​

注意事项 ​

计费部分 ​

使用Import/Export页面 ​

从命令行运行任意工具 ​

验证 ​

限制与注意事项 ​

故障排查 ​