--- title: Configuração como código description: Exporte a configuração para YAML, pré-visualize e aplique via CLI ou página de importação/exportação. url: https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Configuração como código {#configuration-as-code} > **Onde no admin:** System › Settings › Import/Export (`/agent/config`). No servidor: os comandos `nexcmp config export`, `plan` e `apply`, e `nexcmp admin `. ## O que faz {#what-it-does} 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 {#requirements} | 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](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/) 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](#secrets)); nunca dentro do arquivo. | ## Exportar, editar, visualizar, aplicar {#export-edit-preview-apply} 1. Exporte a configuração atual: ```bash sudo nexcmp config export -o nexcmp.yaml ``` Sem `-o`, o YAML é impresso na tela. 2. Edite `nexcmp.yaml` (consulte o [exemplo](#example-file) abaixo). Mantenha `version: 1` no topo. 3. Visualize o que seria alterado. Isso não altera nada: ```bash 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](#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: ```bash 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 ` | 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 ` | Aplicar apenas esta seção. Repita a opção para várias. | | `-o ` | 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 {#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: ```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 ``` 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 {#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). ``` 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 {#sections} | 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](https://nexcmp.com/pt/docs/customers/branding/). | | `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](https://nexcmp.com/pt/docs/administration/smtp-and-emails/). 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](https://nexcmp.com/pt/docs/administration/telegram-notifications/). | | `modules` | Módulos opcionais ligados ou desligados (`key: true/false`). | Apenas as chaves que o painel permite alternar. Veja [Modules](https://nexcmp.com/pt/docs/infrastructure/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](https://nexcmp.com/pt/docs/catalog/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](https://nexcmp.com/pt/docs/billing/payment-channels/). | | `quotas` | Limites de `quota_*`. | Veja [Quotas](https://nexcmp.com/pt/docs/billing/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](https://nexcmp.com/pt/docs/infrastructure/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](https://nexcmp.com/pt/docs/catalog/plans/). | | `ai_provider` | O provedor de IA do painel usado pelo AI Chat e AI Agent do cliente. | [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/). | | `legal` | Texto de termos e privacidade por idioma (`en`, `vi`). | [Legal pages](https://nexcmp.com/pt/docs/customers/legal/). | A ordem de aplicação é a ordem acima: itens semelhantes a infraestrutura antes dos planos. ## Regras para lembrar {#rules-to-remember} - **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 {#billing-sections} `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 {#use-the-import-export-page} 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. ![Página de importação/exportação com o cartão Export e o cartão Import contendo o YAML exportado](https://nexcmp.com/pt/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Tabela de pré-visualização de alterações agrupadas por seção com uma tag de faturamento e um botão Apply selected](https://nexcmp.com/pt/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Executar qualquer ferramenta a partir da linha de comando {#run-any-tool-from-the-command-line} `nexcmp admin` executa as mesmas ferramentas que os assistentes de IA ([the tool list](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/#tools)) e imprime 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"}}' ``` 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 {#verify} 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 {#limits-notes} - 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](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/) 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 {#troubleshooting} | 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_` 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. |