Configuração como código

Onde no admin: System › Settings › Import/Export (/agent/config). No servidor: os comandos nexcmp config export, plan e apply, e nexcmp admin <tool>.

O que faz

A configuração do seu painel (marca, configurações gerais, e-mail, alertas do Telegram, módulos, moeda, gateways de pagamento, limites, zonas, planos, o provedor de IA e as páginas jurídicas) pode ser salva em um único arquivo YAML. Você pode editar o arquivo você mesmo, pedir a um assistente de IA para editá-lo, mantê-lo em controle de versão e aplicá-lo ao mesmo painel ou a outro. Antes que qualquer alteração seja feita, você sempre verá uma lista de diferenças. Segredos nunca são gravados no arquivo.

Use-o para clonar uma configuração para uma segunda instalação, revisar alterações antes que entrem em produção, restaurar configurações após um erro ou permitir que uma IA proponha uma configuração inteira que você lê como um único documento.

Requisitos

Item	Requisito
NexCMP	1.4.0 ou mais recente.
Linha de comando	Você está root no servidor do painel (use sudo). O comando solicita ao painel uma chave temporária (15 minutos, todos os escopos) automaticamente. Para usar uma chave mais restrita em vez disso, defina NEXCMP_KEY como uma admin API key e mantenha-a através do sudo, por exemplo sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml.
Página de administração	Sessão iniciada como administrador. A página é somente leitura em um painel de demonstração.
Secrets	Valores fornecidos no momento da aplicação (consulte Secrets); nunca dentro do arquivo.

Exportar, editar, visualizar, aplicar

1. Exporte a configuração atual:

   sudo nexcmp config export -o nexcmp.yaml

   Sem -o, o YAML é impresso na tela.

2. Edite nexcmp.yaml (consulte o exemplo abaixo). Mantenha version: 1 no topo.

3. Visualize o que seria alterado. Isso não altera nada:

   sudo nexcmp config plan -f nexcmp.yaml

   Cada linha mostra a seção, o item, o campo e old → new. Linhas marcadas com $ pertencem a seções de faturamento (consulte Billing sections). Se o painel já corresponder ao arquivo, você verá "No changes".

4. Aplicar. Sem --yes, o comando é uma simulação (dry run) e imprime apenas a mesma lista:

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

5. Leia o resultado: applied, pending (aguardando sua confirmação), skipped e errors.

Opção	Significado
-f <file>	O arquivo YAML (obrigatório para plan e apply).
--yes	Realmente aplicar. Sem ela, apply é uma simulação (dry run).
--confirm-billing	Aplicar também as seções de faturamento (payments, currency, plans). Sem isso, elas são ignoradas.
--section <name>	Aplicar apenas esta seção. Repita a opção para várias.
-o <file>	Com export: grava o YAML em um arquivo.

O código de saída é 0 quando tudo foi aplicado ou nada foi alterado, 1 quando um erro foi retornado e 2 para um erro de uso ou de chave.

Secrets

O arquivo armazena referências em vez de segredos, como password: secret://smtp_password. No momento da aplicação, o valor vem de uma variável de ambiente chamada NEXCMP_SECRET_ mais o nome da referência em letras maiúsculas:

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

Se uma referência não tiver valor, o segredo já salvo no painel será mantido. Um segredo que nunca foi salvo e não for fornecido permanecerá vazio.

Nome da referência	Para onde vai
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

Arquivo de exemplo

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

Um arquivo pode conter qualquer subconjunto das seções. Uma seção que você omitir não será modificada. Um arquivo maior que 1 MB, um version: 1 ausente, um número de versão diferente ou uma seção desconhecida é rejeitado antes que qualquer execução ocorra.

Seções

Seção	O que controla	Notas
branding	Nome da marca (até 60 caracteres), cor primária, moeda de exibição (usd ou vnd), nome do vendedor.	Logotipos não fazem parte do arquivo; use a branding page.
settings	Uma lista fixa de configurações gerais: 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.	Outras chaves são ignoradas.
email.smtp	Host SMTP, porta, segurança (starttls, tls, none), usuário, senha, nome e endereço do remetente, endereço de resposta (reply-to).	SMTP and e-mail templates. Alterar o host, a porta ou a segurança exige a senha novamente.
telegram	Canal de alerta ligado ou desligado, chat id, token do bot.	Notificações do Telegram.
modules	Módulos opcionais ligados ou desligados (key: true/false).	Apenas as chaves que o painel permite alternar. Veja Modules.
currency	Moeda de exibição e taxa manual de USD para VND (0 automática, caso contrário de 15000 a 50000).	Seção de cobrança. Veja Currency and exchange rates.
payments	Credenciais de stripe, paypal, crypto, bank e chaves channels (pay_card_enabled, pay_wallets_enabled, pay_alipay_enabled, pay_paypal_enabled, pay_usdt_enabled, pay_sepay_enabled).	Seção de cobrança. Veja Payment channels.
quotas	Limites de quota_*.	Veja Quotas.
zones	Zonas por slug (obrigatório: slug, name, country; opcional city, enabled, is_default).	Novas zonas são criadas. Uma zona que já existe não é alterada pelo arquivo. Veja Zones.
plans	Planos por slug (obrigatório: slug, name, cpu, ram_mb, disk_gb, hourly_usd; opcional cs_offering_id, backend_id, zone_id, enabled, visible, sort, description).	Seção de cobrança. Novos planos são criados, os existentes são atualizados por slug. Os preços são em USD por hora. Veja Plans.
ai_provider	O provedor de IA do painel usado pelo AI Chat e AI Agent do cliente.	AI provider.
legal	Texto de termos e privacidade por idioma (en, vi).	Legal pages.

A ordem de aplicação é a ordem acima: itens semelhantes a infraestrutura antes dos planos.

Regras para lembrar

• Idempotente. Aplicar o mesmo arquivo duas vezes não altera nada na segunda vez. plan mostra "No changes".
• Sem exclusões. O arquivo nunca remove uma zona, plano ou configuração. Remover uma entrada do arquivo deixa o painel como está.
• As regras normais de segurança ainda se aplicam. A partir da linha de comando, cada alteração é enviada pelas mesmas verificações de uma alteração de API: escopos e regras de IP. Uma alteração que precisa de confirmação (um comutador global, por exemplo) é relatada em pending com uma prévia em vez de ser aplicada, a menos que você passe --confirm-billing, o que confirma todas elas.
• Os clientes de IA não podem desbloquear o faturamento. Quando config_apply é chamado por um cliente MCP, confirm_billing é ignorado; as alterações de dinheiro aguardam você.
• Verifique antes de aplicar. O JSON Schema descreve cada campo. Aponte seu editor para ele ou forneça-o a uma IA para que ela escreva um YAML válido: https://cloud.example.com/v1/admin/agent/config/schema.json (leitura pública).

Seções de faturamento

payments, currency e plans alteram preços ou caminhos de dinheiro. nexcmp config apply --yes os ignora a menos que você adicione --confirm-billing; eles são então listados em skipped ("billing section - pass confirm_billing"). O sinalizador é a sua confirmação: com ele, cada alteração de faturamento no arquivo (e qualquer outra alteração que exigiria confirmação) é aplicada sem um segundo aviso. Execute plan primeiro e leia cada linha marcada $.

Quando o mesmo arquivo é aplicado por uma IA (a ferramenta config_apply em um cliente MCP ou AI Chat), o sinalizador é ignorado e as alterações de dinheiro aguardam sua aprovação.

Use a página Import/Export

1. Abra System › Settings › Import/Export.
2. Em Export clique em Get current configuration e depois em Download .yaml para salvar nexcmp.yaml. Os segredos aparecem como espaços reservados.
3. Em Import escolha um arquivo, arraste-o para a caixa ou cole o YAML.
4. Opcional: abra Secrets that come with it (not in the file) e adicione um nome e um valor para cada referência, por exemplo smtp_password.
5. Clique em Preview changes. A tabela agrupa as alterações por seção; as seções relacionadas a dinheiro carregam a tag "Money-related". Desmarque as seções que você não quer.
6. Se seções relacionadas a dinheiro forem listadas, marque Also apply money-related changes (prices, payment gateways, balances). Sem a marcação, elas são ignoradas.
7. Clique em Apply selected. O resultado mostra o que foi aplicado, ignorado ou falhou. Uma alteração retornada como aguardando confirmação aparece como um cartão de confirmação; clique em Confirm nele.

O botão JSON Schema no canto superior direito abre o esquema.

Executar qualquer ferramenta a partir da linha de comando

nexcmp admin executa as mesmas ferramentas que os assistentes de IA (the tool list) e imprime 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"}}'

Os argumentos são pares key=value (os valores são lidos como JSON quando são analisáveis, caso contrário como texto) ou um objeto --json '{...}'. Se a ação precisar de confirmação, o comando imprime a pré-visualização e para com o código de saída 3 e "Nothing changed". Leia a pré-visualização e execute o mesmo comando novamente com --yes para aplicá-la. Executado como root, o comando obtém uma chave de 15 minutos com todos os escopos, portanto, a etapa de confirmação é sua salvaguarda; com NEXCMP_KEY, aplicam-se os escopos da própria chave.

Verificar

1. sudo nexcmp config plan -f nexcmp.yaml logo após um apply --yes imprime "No changes".
2. No painel administrativo, as páginas que você alterou mostram os novos valores, e Logs › Admin actions lista as alterações.
3. Aplicar o mesmo arquivo novamente não altera nada.

Limites e notas

• O arquivo cobre as configurações acima, não clientes, servidores, faturas ou fontes de infraestrutura (conexões com CloudStack e Proxmox). Conecte-as com AI Chat ou pelas páginas administrativas.
• Zonas e planos são correspondidos por slug. Não renomeie um slug no arquivo: ele seria criado como um novo item.
• Um plano que os clientes já utilizam não pode ter seu tamanho alterado; crie um novo plano.
• Mantenha os arquivos exportados privados, embora não contenham segredos: eles listam seus preços, endereços e nomes de contas.

Resolução de problemas

Sintoma	Causa	Correção
missing version: 1	O arquivo não começa com version: 1	Adicione-o.
unsupported version 2	O arquivo possui outro número de versão	Este painel lê apenas a versão 1.
unknown section 'x' (known: ...)	Uma chave de nível superior com erro de digitação ou não suportada	Use as seções acima.
YAML error: ...	YAML inválido (indentação, tabulações)	Corrija a linha indicada pela mensagem.
config is larger than 1 MB	Arquivo muito grande	Divida-o e use --section.
no API key: set NEXCMP_KEY=ak_... or run as root on the server	O comando não encontrou nenhuma chave	Execute com sudo ou exporte NEXCMP_KEY e mantenha-o com sudo.
panel not reachable	O serviço do painel não está rodando na porta padrão	Verifique sudo nexcmp status.
Linhas de faturamento em skipped	As seções de faturamento precisam de --confirm-billing	Adicione a flag e revise primeiro as linhas $.
Itens em pending	A alteração precisa de confirmação	Abra API & AI agents ou o resultado da importação/exportação e clique em Confirm no cartão.
Um segredo não foi atualizado	Nenhum valor NEXCMP_SECRET_<NAME> foi definido, portanto o segredo salvo foi mantido	Exporte a variável e aplique novamente.
Entrada em errors com HTTP 403 insufficient_scope	A chave carece do escopo dessa seção	Use uma chave com o escopo ou execute como root.
Entrada em errors com HTTP 403 demo_read_only	Painel de demonstração	Aplicar em uma instalação real.