# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/pt/docs/ · generated 2026-11-02. --- # O que é o NexCMP {#what-is-nexcmp} O NexCMP é um software que você instala no **seu próprio servidor** para transformar infraestrutura em nuvem em um produto que você pode vender. Ele oferece: - um **portal do cliente** onde as pessoas se registram, adicionam crédito, encomendam máquinas virtuais e outros serviços, abrem um console, tiram snapshots e entram em contato com o suporte; - um **painel administrativo** (`/admin`) onde você gerencia clientes, planos, preços, pagamentos, infraestrutura e configurações; - **faturamento**: uma carteira por cliente, cobrança por hora ou mensal, faturas, promoções e cotas de recursos; - **revendedores white-label**: outras marcas que vendem a sua capacidade sob o domínio próprio delas; - uma **API**, uma ferramenta de linha de comando (`cmp`) e um servidor MCP para automação; - recursos opcionais de **AI Chat** (assistente de suporte) e **AI Agent** (gerenciar uma VM em linguagem natural). ## Ao que ele se conecta {#what-it-connects-to} O NexCMP não hospeda máquinas virtuais por si só. Ele controla a plataforma que faz isso. Uma *source* (também chamada de provedor) é um dos seguintes: | Source | Uso típico | Guia | |---|---|---| | Apache CloudStack | Nuvem privada ou pública com zonas, redes, roteadores virtuais e IPs públicos | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) | | Proxmox VE | Servidores avulsos ou clusters que você já opera | [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) | Outros módulos precisam de infraestrutura própria: [bare-metal servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/), [VPN and proxy nodes](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/), [S3 object storage](https://nexcmp.com/pt/docs/infrastructure/s3/), [Kubernetes and Private Cloud](https://nexcmp.com/pt/docs/infrastructure/kubernetes-and-private-cloud/). Veja [Infrastructure requirements](https://nexcmp.com/pt/docs/infrastructure/requirements/) para uma tabela abrangendo todos eles. ## Como ele é construído {#how-it-is-built} O NexCMP é um programa único com dois serviços do systemd em um único servidor Ubuntu: - `nexcmp` — o servidor web: portal do cliente, painel administrativo, API, assistente de configuração; - `nexcmp-vmd` — o worker em segundo plano: tarefas de provisionamento, sincronização com seu CloudStack ou Proxmox, execuções de faturamento. Os dados ficam em `/var/lib/nexcmp` (arquivos e bancos de dados SQLite), a configuração em `/etc/nexcmp` e o programa em `/opt/nexcmp`. Consulte [Architecture](https://nexcmp.com/pt/docs/infrastructure/architecture/) para ver a visão geral completa. ## Próximos passos {#where-to-go-next} 1. Verifique os [requirements](https://nexcmp.com/pt/docs/getting-started/requirements/). 2. Obtenha uma licença — [License and purchase](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/). 3. [Install](https://nexcmp.com/pt/docs/getting-started/installation/) e, em seguida, execute o [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/). 4. Conecte sua plataforma: [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) ou [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). --- # Requisitos para o servidor NexCMP {#requirements-for-the-nexcmp-server} Esta página aborda o servidor que executa o NexCMP. O que seu CloudStack, Proxmox VE ou outra infraestrutura precisa está em [Infrastructure requirements](https://nexcmp.com/pt/docs/infrastructure/requirements/). ## Servidor {#server} | Item | Requisito | Verificado pelo instalador | |---|---|---| | Sistema operacional | Ubuntu **22.04** ou **24.04** | Sim — interrompe com um erro em qualquer outro | | Arquitetura de CPU | x86_64 | Sim | | Memória | 2 GB no mínimo (o instalador recusa menos de cerca de 1.8 GB) | Sim | | Disco livre | 8 GB livres no `/` mínimo | Sim | | Privilégios | root (`sudo`) | Sim | | Pacotes | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — instalados automaticamente | Instalado se estiver faltando | | Com HTTPS | `nginx` e `certbot` — instalados automaticamente, a menos que você passe `--no-nginx` | Instalado se estiver faltando | ::: tip Dimensionamento Uma instalação pequena (algumas centenas de clientes) roda confortavelmente em 2 vCPU / 4 GB de RAM. O uso de disco é dominado pelos bancos de dados SQLite e pelas cópias opcionais de atualização e backup — planeje 20 GB ou mais para produção. ::: ## Rede {#network} | Direção | Porta | Finalidade | |---|---|---| | Entrada | 80/tcp | Validação do Let's Encrypt e redirecionamento para HTTPS | | Entrada | 443/tcp | Portal do cliente, console de administração, API | | Entrada | 3000/tcp | Assistente de configuração na primeira instalação e acesso de emergência apenas — consulte [Installation](https://nexcmp.com/pt/docs/getting-started/installation/#the-panel-port-3000) | | Saída | 443/tcp para `nexcmp.com` | Ativação de licença, verificação diária de licença, atualizações | | Saída | para sua API do CloudStack / API do Proxmox | Provisionamento e sincronização | | Saída | 443/tcp para provedores de pagamento, e-mail e IA que você habilitar | Stripe, PayPal, SMTP, provedor de IA e assim por diante | O servidor precisa de um **endereço IPv4 público** se você quiser que o Let's Encrypt emita um certificado diretamente. Se o domínio estiver proxied pelo Cloudflare, consulte [DNS and Cloudflare](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/). ## DNS - Um **domínio principal** (por exemplo, `cloud.example.com`) — o portal é `https://cloud.example.com/` e o console de administração é `https://cloud.example.com/admin`. - Opcional: `admin.` e `partner.`. Se esses nomes resolverem para o servidor (ou para o Cloudflare), o instalador os adicionará ao certificado. - O domínio deve corresponder ao registrado na sua licença. ## Não obrigatório neste servidor {#not-required-on-this-server} O NexCMP roda como um usuário de serviço comum sem privilégios (`nexcmp`). Ele **não** precisa de root em tempo de execução, Docker, um servidor de banco de dados separado, Redis ou qualquer software de hipervisor. --- # Licença e compra {#license-and-purchase} > **Onde no admin:** System › Admin › License & updates (`/license`) O NexCMP é ativado com uma **chave de licença** que você gerencia em sua [conta NexCMP](https://nexcmp.com/licenses). As edições e os preços atuais estão listados em [nexcmp.com/pricing](https://nexcmp.com/pricing); esta página explica como a licença se comporta após a aquisição. ## Obter uma licença {#get-a-license} 1. Crie uma conta em [nexcmp.com](https://nexcmp.com/register) e verifique seu e-mail. 2. Escolha uma edição: - **NexCMP Free** — para operadores de rede com ASN próprio e sub-rede registrada em nome próprio. Envie uma solicitação em [nexcmp.com/deploy](https://nexcmp.com/deploy) (empresa, ASN, sub-rede, domínio do painel). O e-mail da sua conta deve pertencer ao domínio da empresa listado no registro público (WHOIS) para o ASN ou sub-rede. Cada solicitação é analisada; você recebe um e-mail com a decisão, e a chave de licença só aparece após a aprovação. - **NexCMP Source** — uma atualização única, sem necessidade de ASN. Consulte [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. Abra sua página de licença. Ela exibe a **chave de licença** (formato `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), o **domínio principal** e um comando de instalação pronto. ::: warning Mantenha a chave privada A chave de licença ativa uma instalação. Trate-a como uma senha: não a cole em tickets, chats ou capturas de tela. ::: ## O que uma licença contém {#what-a-license-contains} | Campo | Significado | |---|---| | Domínio principal | O hostname onde seu portal é executado. A chave é vinculada a ele na ativação. | | Domínios de revendedores | Hostnames extras atendidos como portais de marca própria — consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). | | Atualizações até | Data até a qual você recebe **atualizações e correções de bugs**. Uma licença Free começa com **1 ano** a partir do dia em que for aprovada; renove-a por $99 por ano na sua página de licença. Correções de segurança são sempre entregues, mesmo após essa data. | | Status | `active`, ou suspenso / expirado / revogado. | ## Quando o ano gratuito termina {#when-the-free-year-ends} O software **continua funcionando** quando a data de "Atualizações até" passa: clientes, serviços e faturamento não são afetados. Você para de receber novos lançamentos de recursos e atualizações de correção de bugs (correções de segurança ainda chegam). Renove por $99 por ano na sua página de licença em [nexcmp.com/licenses](https://nexcmp.com/licenses) para continuar; a renovação adiciona 12 meses à data de término atual. O NexCMP Free inclui apenas correções de bugs — sem suporte técnico e sem aplicativos. ## O que o NexCMP Source adiciona {#what-nexcmp-source-adds} Uma licença Source é uma atualização única de $1,999 da sua licença: o código-fonte completo, todos os aplicativos NexCMP (Android, iOS, Windows, macOS, Linux, Chrome / Edge / Brave e Firefox) compilados e com a sua marca, e 30 dias úteis com um engenheiro especialista — migração gratuita do VMware, WHMCS ou outro painel, ou uma configuração completa de A a Z. Novos lançamentos de código-fonte estão incluídos por 12 meses; renová-los posteriormente ($99 por ano) é opcional, e o código-fonte baixado é seu para sempre. Consulte os [Source license terms](https://nexcmp.com/legal/source-license/). ## Como a instalação verifica sua licença {#how-the-installation-checks-its-license} - Na instalação, o servidor ativa a chave para o seu domínio e recebe um **token assinado**. - O token é renovado automaticamente a cada **24 horas**. Ele permanece válido por **14 dias**, portanto, uma breve interrupção na internet não causa problemas. - Todas as versões e tokens são verificados com uma assinatura Ed25519 integrada ao programa; um download adulterado é rejeitado. Verifique o estado a qualquer momento no console de administração ou com `sudo nexcmp status`. ## Se a licença não for válida {#if-the-license-is-not-valid} Quando o token expirar, a licença for suspensa ou o domínio não corresponder mais: - **os clientes não podem criar novos serviços** e o console de administração exibe um aviso; - os serviços que já estão em execução, **o faturamento e os clientes existentes não são afetados**; - corrija a causa (reconecte o servidor à Internet, renove em [nexcmp.com/licenses](https://nexcmp.com/licenses)) e clique em **Check now** em Licença e atualizações. ## Mudança para um novo servidor ou domínio {#moving-to-a-new-server-or-domain} Ative no novo servidor com a mesma chave e o domínio registrado (consulte [Installation](https://nexcmp.com/pt/docs/getting-started/installation/)). Para alterar o domínio registrado, faça isso primeiro na sua página de licença em [nexcmp.com/licenses](https://nexcmp.com/licenses) e, em seguida, execute o instalador novamente com o novo `--domain`. --- # Instalar o NexCMP {#install-nexcmp} O instalador é um script único fornecido pelo seu servidor de licenças. Ele verifica a máquina, ativa sua licença, baixa e verifica o programa, instala os serviços e (opcionalmente) configura o nginx com um certificado Let's Encrypt. ## Antes de começar {#before-you-start} - Um servidor que atenda aos [requisitos](https://nexcmp.com/pt/docs/getting-started/requirements/) e acesso root. - Sua **chave de licença** e **domínio principal** obtidos na sua [página de licença](https://nexcmp.com/licenses) — consulte [License and purchase](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/). - Um registro DNS para o domínio — consulte [DNS and Cloudflare](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/). Você também pode instalar primeiro e corrigir o DNS mais tarde; o instalador informa o que está faltando e pode simplesmente ser executado novamente. ## Instalação {#install} 1. Faça login no servidor e torne-se root (ou adicione `sudo` no início). 2. Execute o comando da sua página de licença. Ele se parece com isto: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX \ --domain cloud.example.com \ --email admin@example.com ``` 3. Aguarde as marcas de seleção. Uma instalação limpa leva alguns minutos; a primeira inicialização cria o esquema do banco de dados e pode levar até um minuto em discos lentos. 4. Leia o resumo no final. Ele exibe as URLs do portal e do admin, o **código de configuração** e a próxima etapa. ![O instalador sendo concluído com a URL do portal, URL do admin e código de configuração de uso único](https://nexcmp.com/pt/docs/images/getting-started/installation-01-finish.webp) ## Parâmetros {#parameters} | Parâmetro | Padrão | Significado | |---|---|---| | `--license KEY` | obrigatório na primeira instalação | A chave de licença. | | `--domain NAME` | obrigatório na primeira instalação | Domínio principal. Deve corresponder à licença. `https://` e caminhos finais são removidos. | | `--email ADDRESS` | nenhum | E-mail de contato para avisos de expiração do Let's Encrypt. Sem ele, o certificado é registrado sem e-mail. | | `--port N` | `3000` | Porta local do painel (1–65535). | | `--no-nginx` | desativado | Não instala nem configura o nginx / TLS. Use isto quando executar seu próprio proxy reverso ou quiser avaliar o NexCMP primeiro. | | `--behind-cloudflare` | detectado automaticamente | Força o modo "o domínio é feito por proxy através do Cloudflare". Normalmente detectado a partir do DNS. | | `--channel NAME` | `stable` | Canal de lançamento. | Executar o instalador novamente **sem parâmetros** reutiliza os salvos (`/etc/nexcmp/install.conf`) e atualiza com segurança, mantendo dados, configuração e contas. Isso é exatamente o que `sudo nexcmp update` faz. ## O que o instalador faz {#what-the-installer-does} 1. **Verifica a máquina** — Ubuntu 22.04/24.04, x86_64, pelo menos 2 GB de RAM, 8 GB de disco livre. 2. **Instala os pacotes** necessários (`curl`, `zstd`, `openssl`, `python3`, `openssh-client` …). 3. **Cria o usuário de serviço** `nexcmp` e os diretórios: `/opt/nexcmp` (programa, pertencente ao root, somente leitura para o serviço), `/etc/nexcmp` (configuração), `/var/lib/nexcmp` (dados), `/var/log/nexcmp`. 4. **Ativa a licença** para o domínio e armazena um ID de instância fixo para esta máquina. 5. **Baixa a versão mais recente a que você tem direito**, em seguida verifica seu SHA-256 e sua assinatura Ed25519. Uma versão sem uma assinatura válida é recusada. Ele nunca faz o downgrade de uma versão mais nova em execução. 6. **Escreve a configuração e as unidades systemd** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) e inicia os serviços; aguarda `/healthz` responder. 7. **Configura o nginx e o TLS** (a menos que `--no-nginx`): obtém um certificado Let's Encrypt com o certbot (desafio webroot) para o domínio e para `admin.` / `partner.` quando esses nomes também resolvem. Se o DNS ainda não apontar para este servidor (ou Cloudflare), ele pula esta etapa e avisa. 8. **Exibe um resumo** com URLs e, se nenhum administrador existir ainda, o **código de configuração**. ## A porta do painel (3000) {#the-panel-port-3000} - Durante a primeira instalação, o painel escuta em `0.0.0.0:3000` para que você possa abrir o assistente de configuração em `http://:3000/setup`. - Assim que o assistente terminar **e** o TLS estiver ativo, o painel escuta apenas em `127.0.0.1`; o nginx faz o proxy de `https://` para ele. - Para emergências (nginx quebrado, DNS incorreto), você pode abrir a porta por tempo limitado: `sudo nexcmp open-port 30` (30 minutos, depois ela fecha sozinha) — ou usar um túnel SSH: `ssh -L 3000:127.0.0.1:3000 ` e navegar em `http://127.0.0.1:3000/`. ::: warning HTTP Simples A porta 3000 usa HTTP simples. Use-a apenas para o assistente de configuração em uma rede confiável ou por meio de um túnel SSH. Não a deixe aberta. ::: ## Instalando sem um domínio público (laboratório ou teste) {#installing-without-a-public-domain-lab-or-test} Você pode instalar em uma máquina sem DNS ainda: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` Em seguida, abra o assistente por meio de um túnel SSH (`ssh -L 3000:127.0.0.1:3000 `, navegue em `http://127.0.0.1:3000/setup`). Execute o instalador novamente sem `--no-nginx` assim que o DNS existir. ## Docker e Kubernetes {#docker-and-kubernetes} Não há imagem de contêiner publicada. O instalador (uma instalação nativa via systemd) é o método de instalação suportado. ## Verificar {#verify} ```bash sudo nexcmp status ``` Você deve ver a versão, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` e — até que o assistente seja concluído — o código de configuração. Continue com o [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/). Se algo falhar, consulte [Installation errors](https://nexcmp.com/pt/docs/troubleshooting/installation-errors/). --- # DNS e Cloudflare {#dns-and-cloudflare} O NexCMP precisa de um nome DNS — seu **domínio principal** — e funciona em dois modos. ## Modo A: O DNS aponta diretamente para o servidor {#mode-a-dns-points-straight-at-the-server} 1. Crie um registro **A** `cloud.example.com → ` (e um registro **AAAA** se o servidor tiver IPv6). 2. Opcional, se você os utilizar: `admin.cloud.example.com` e `partner.cloud.example.com` apontando para o mesmo IP. 3. Execute (ou reexecute) o [installer](https://nexcmp.com/pt/docs/getting-started/installation/). Ele verifica que o nome resolve para o IP público do próprio servidor e obtém um certificado Let's Encrypt por meio do desafio HTTP-01 na porta 80. ## Modo B: O domínio é proxied pelo Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} Crie os mesmos registros com a nuvem laranja (**Proxied**). O instalador detecta que o nome resolve apenas para endereços da Cloudflare e muda para o modo Cloudflare: - o nginx ainda escuta nas portas 80/443 no seu servidor; - o IP real do visitante é lido a partir do cabeçalho `CF-Connecting-IP` — **apenas** para conexões vindas das faixas publicadas da Cloudflare, para que não possa ser forjado por mais ninguém; - o certificado é obtido através do Let's Encrypt (a Cloudflare encaminha o desafio para sua origem); se isso ainda não for possível, um **certificado de origem autoassinado** é criado para que o modo "Full" funcione, e uma execução posterior do instalador faz o upgrade para o Let's Encrypt. Você pode forçar este modo com `--behind-cloudflare`. ::: important Definir o modo SSL/TLS na Cloudflare Na Cloudflare, vá em **SSL/TLS › Overview** e selecione **Full (strict)** assim que o instalador reportar um certificado Let's Encrypt. Com um certificado de origem autoassinado, use **Full**. **Flexible** causará loops de redirecionamento. ::: ::: tip Se "Always Use HTTPS" estiver ativado, a Cloudflare envia a solicitação de validação para a porta 443 da sua origem. O instalador lida com isso criando primeiro o certificado autoassinado temporário e, em seguida, tentando novamente o Let's Encrypt. ::: ## Verifique {#check-it} ```bash dig +short cloud.example.com # A record (a Cloudflare address in mode B) curl -I https://cloud.example.com/healthz sudo certbot certificates # certificate name, domains and expiry ``` Os certificados são renovados automaticamente com o timer do certbot. A renovação usa o webroot `/var/www/nexcmp-acme`, portanto a porta 80 deve permanecer acessível (diretamente ou através da Cloudflare). ## Problemas comuns {#common-problems} | Sintoma | Causa | Correção | |---|---|---| | Instalador diz "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" | Registro DNS ausente, incorreto ou não propagado | Corrija o registro, aguarde a propagação e execute o instalador novamente. | | O navegador mostra `ERR_TOO_MANY_REDIRECTS` atrás da Cloudflare | O modo SSL é **Flexible** | Defina **Full (strict)** (ou **Full**). | | Erro 525/526 da Cloudflare | Certificado de origem rejeitado | Use **Full** com um certificado de origem autoassinado, ou **Full (strict)** com o Let's Encrypt. | | Os visitantes mostram todos IPs da Cloudflare nos logs | Não está no modo Cloudflare | Execute o instalador novamente com `--behind-cloudflare`. | Mais informações em [Installation errors](https://nexcmp.com/pt/docs/troubleshooting/installation-errors/). --- # Assistente de configuração {#setup-wizard} > **Onde no admin:** o assistente é uma página independente em `/setup` exibida apenas até que o primeiro administrador exista. Depois disso, as mesmas verificações ficam em System › Admin › Start (`/setup`). O assistente transforma uma instalação limpa em um painel funcional em quatro etapas rápidas. Ele é disponibilizado na porta 3000 (`http://:3000/setup`) ou, quando o TLS já estiver ativo, em `https:///setup`. ::: warning O assistente desaparece após a etapa 3 Assim que o administrador é criado, o assistente é fechado e o código de setup é excluído. Para acessar o painel posteriormente, use o console de administração. ::: ## Etapa 0 — Código de setup {#step-0-—-setup-code} O instalador exibe um **código de setup de uso único** no final. Você pode lê-lo novamente com: ```bash sudo nexcmp status ``` Cole-o em **Setup code** e clique em **Continue**. O código protege o assistente: ninguém que encontre a porta aberta pode criar o administrador sem ele. ![Etapa 0 do assistente de configuração solicitando o código de setup de uso único](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-00-code.webp) ## Etapa 1 — Licença {#step-1-—-license} | Campo | Valor | |---|---| | Chave de licença | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — pré-ativado pelo instalador, portanto, esta etapa normalmente exibe "Activated for cloud.example.com" | | Domínio principal | O domínio registrado na licença | Se o instalador já tiver ativado a licença, o assistente a reconhece e prossegue. Caso contrário, insira a chave e o domínio e clique em **Activate**. Os erros são exibidos em vermelho — consulte [Installation errors](https://nexcmp.com/pt/docs/troubleshooting/installation-errors/). ![Etapa 1 do assistente de configuração mostrando a licença já ativada para o domínio principal](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-01-license.webp) ## Etapa 2 — CloudStack (ou Conectar mais tarde) {#step-2-—-cloudstack-or-connect-later} Você tem duas opções: - **Conectar agora.** Insira a **API URL** (`https://cloudstack.example.com/client/api`), a **API key** e a **Secret key** do CloudStack, clique em **Test connection** e selecione a **Zone**, a **Guest network for customer VMs**, um **Zone display name** e o **Country** de duas letras. Clique em **Save CloudStack**. - **Conectar mais tarde.** Clique em **Connect later**. Todo o resto funciona; você conecta o CloudStack ou o Proxmox VE mais tarde em Infrastructure. Até lá, o painel de saúde lembra você de que nenhuma fonte está conectada. ![Etapa 2 do assistente com os campos de URL da API, chave da API e chave secreta do CloudStack preenchidos com valores de exemplo](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important Use uma conta dedicada do CloudStack Não use a chave de administrador ROOT. Crie um domínio e uma conta dedicados para o NexCMP e use sua chave de API — consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). O assistente verifica se a rede escolhida pertence à zona e à conta dessa chave. ::: ![Após o Test connection: as listas de zonas e redes de convidados, o nome de exibição da zona e os campos de país](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) Se você planeja usar apenas o **Proxmox VE**, escolha **Connect later** e siga [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). ## Etapa 3 — Administrador e marca {#step-3-—-administrator-and-brand} | Campo | Regras | |---|---| | E-mail do admin (login) | Endereço de e-mail válido. Este é o seu nome de usuário de administrador. | | Senha | Pelo menos 12 caracteres, com letras e dígitos. | | Nome da marca | Exibido para seus clientes (padrão "Cloud"). Até 60 caracteres. | | E-mail de suporte | Usa o e-mail do admin por padrão. | ![Etapa 3 do assistente com e-mail do administrador, senha, nome da marca e e-mail de suporte](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-03-admin.webp) Clique em **Finish setup**. O painel é reiniciado (cerca de 1 a 2 segundos) e a página direciona você para o login do admin em `https:///admin/`. Se esse endereço ainda não responder (DNS ou TLS pendente), ele direciona você para `/` no endereço atual. ![O assistente após a conclusão com a mensagem de que o painel está sendo reiniciado](https://nexcmp.com/pt/docs/images/getting-started/setup-wizard-03-done.webp) ## O que o assistente configura para você {#what-the-wizard-sets-up-for-you} - Nome da marca, URL do site (`https://`), URL do admin (`https:///admin`), URL do console (`https:///console`), e-mail de suporte e nome do remetente. - Configurações padrão para os módulos que acompanham o NexCMP: DDoS & BGP, IA e SSH web estão **desativados**; a medição de largura de banda está **ativada**. Consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/). - Se você conectou o CloudStack: o provedor nº 1, sua primeira zona, a rede de convidados e um par de chaves de operações anexado às VMs de clientes para que você possa dar suporte a eles. Próximo: [First login](https://nexcmp.com/pt/docs/getting-started/first-login/). --- # Primeiro login e próximos passos {#first-login-and-next-steps} > **Onde no admin:** a página de login é `/admin`; após o login, a página inicial é Overview › Dashboard. ## Endereços {#addresses} | O quê | URL | |---|---| | Portal do cliente | `https:///` | | Console administrativo | `https:///admin` | | Configuração / emergência por IP | `http://:3000/` (consulte [a porta do painel](https://nexcmp.com/pt/docs/getting-started/installation/#the-panel-port-3000)) | | Verificação de saúde | `https:///healthz` | ## Entrar {#sign-in} 1. Abra `https:///admin`. 2. Insira o e-mail e a senha do administrador que você criou no assistente. 3. Você será direcionado ao **Dashboard**. Um banner no topo aparece se a licença não for válida ou se nenhum source estiver conectado. ![A página de login do admin](https://nexcmp.com/pt/docs/images/getting-started/first-login-01-login.webp) ## Checklist recomendado {#recommended-checklist} Siga estes passos em ordem — cada um aponta para a sua página. | # | Tarefa | Página | |---|---|---| | 1 | Ative a autenticação de dois fatores para sua conta | [Security](https://nexcmp.com/pt/docs/administration/security/) | | 2 | Conecte um source de infraestrutura (se escolheu "Connect later") | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) ou [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) | | 3 | Verifique as zonas e os templates de máquina / lista de SO | [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/), [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/) | | 4 | Revise planos e preços | [Plans](https://nexcmp.com/pt/docs/catalog/plans/) | | 5 | Defina seu logotipo, cores e páginas legais | [Branding](https://nexcmp.com/pt/docs/customers/branding/), [Legal](https://nexcmp.com/pt/docs/customers/legal/) | | 6 | Configure o e-mail de saída e envie um teste | [SMTP and emails](https://nexcmp.com/pt/docs/administration/smtp-and-emails/) | | 7 | Ative pelo menos um canal de pagamento e teste uma recarga | [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/) | | 8 | Decida quais módulos você vende | [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | | 9 | Faça um pedido de teste como cliente e exclua-o | [Ordering](https://nexcmp.com/pt/docs/portal/ordering/) | | 10 | Faça um primeiro backup | [Backup and restore](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/) | ## Crie seu primeiro pedido (teste de fumaça) {#create-your-first-order-smoke-test} 1. Abra o portal do cliente em uma janela anônima e registre uma conta de teste. 2. Adicione crédito (um voucher ou um pagamento de teste). 3. Peça o menor plano na sua zona. 4. Acompanhe-o aparecer no admin em Services › Virtual Machines, abra seu console e depois destrua-o. Se a VM não atingir o estado *running*, abra **Infrastructure › Cloud provider › Sync & errors** e leia o erro. --- # Atualizando o NexCMP {#updating-nexcmp} > **Onde no admin:** System › Admin › License & updates (`/license`) → card *Update*. ## O que você recebe {#what-you-receive} | Tipo de lançamento | Entregue quando | |---|---| | Correção de segurança | **Sempre**, mesmo após a data de "atualizações até" | | Lançamento de recurso | Apenas se foi publicado **em ou antes** da sua data de "atualizações até" | Você pode ver ambas as datas em **License & updates**. Renove a licença em [nexcmp.com/licenses](https://nexcmp.com/licenses). ## Atualizar pelo console do administrador {#update-from-the-admin-console} 1. Abra **System › Admin › License & updates**. 2. No cartão **Update**, clique em **Check for update**. O cartão mostra a versão atual, a versão mais recente que você pode instalar, uma tag *security* quando relevante e o changelog. 3. Clique em **Update to X.Y.Z** e confirme. O programa baixa o lançamento, verifica sua **assinatura SHA-256 e Ed25519**, substitui o binário de forma atômica (mantendo uma cópia `.bak`) e reinicia. Espere cerca de **10 segundos** de tempo de inatividade. 4. Recarregue a página e verifique a versão no canto superior direito de License & updates. ![O cartão Update com a versão em execução e o botão Check for new version](https://nexcmp.com/pt/docs/images/getting-started/updating-01-card.webp) ## Atualizar pela linha de comando {#update-from-the-command-line} ```bash sudo nexcmp update ``` Isso executa o instalador incluído *dentro do lançamento atualmente instalado* (não um script baixado naquele momento) com os parâmetros salvos de `/etc/nexcmp/install.conf`. Ele atualiza o binário, as unidades systemd, os modelos do nginx e o agente de nó, e mantém dados, configuração e contas. ::: tip Nunca faz downgrade Se o servidor oferecer uma versão anterior à que está em execução, o instalador mantém a versão atual. ::: ## Antes de atualizar {#before-you-update} 1. Faça um backup: `sudo nexcmp backup` — consulte [Backup and restore](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/). 2. Leia o changelog no card Update. Para as alterações desde a versão 1.3, consulte as [Notas de versão até a 1.6.1](https://nexcmp.com/pt/docs/getting-started/release-notes/), incluindo a atualização do agente VPN e as regras de preços de Bare Metal. 3. Atualize durante um período de menor movimento; as máquinas virtuais em execução não são afetadas, mas os clientes não poderão usar o portal por alguns segundos. ## Após atualizar {#after-you-update} - Execute `sudo nexcmp status` e confirme se ambos os serviços estão ativos. - Abra o Dashboard do administrador e a página **Needs attention**. - As migrações de banco de dados são executadas automaticamente na primeira inicialização da nova versão. - Se você opera nós VPN, atualize o agente separadamente e verifique as leituras de consumo. A atualização do painel disponibiliza o novo agente, mas não garante que todos os nós remotos já o estejam executando. Consulte [Franquia de dados do nó VPN](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). Se uma atualização falhar, consulte [Update errors](https://nexcmp.com/pt/docs/troubleshooting/update-errors/). --- # Notas de versão {#release-notes} > **Onde encontrar no admin:** System › Admin › License & updates (`/license`), card **Update**. Estas notas cobrem as mudanças após a versão 1.3 até o **NexCMP 1.6.1**. Faça backup antes de atualizar e use a versão disponibilizada no card **Update** da sua instalação. Consulte [Como atualizar o NexCMP](https://nexcmp.com/pt/docs/getting-started/updating/) para ver os comandos e as verificações de assinatura. ## 1.6.1 - **Métricas de Bare Metal:** a **Overview** do cliente exibe blocos de CPU, RAM, atividade de disco e rede com histórico recente. Medições ausentes mostram um traço e o motivo. As leituras de rede exigem um contador de tráfego; elas não são deduzidas do inventário de hardware do iDRAC. - **Planos de exemplo de Bare Metal:** os nomes de exemplo usam `BM-40C-`. Planos de exemplo integrados que você não editou recebem nomes neutros. Planos editados são preservados, e um plano referenciado mantém seu código. Verifique o hardware real do servidor antes de disponibilizar um plano para venda. - **Alterações de plano:** a lista de solicitações no admin faz ordenação no servidor e mantém suas ações visíveis durante a rolagem horizontal. - **Relatar um bug:** o formulário rola mantendo os botões visíveis. O mascaramento de senha preserva o texto de diagnóstico ao redor. - **Carregamento:** recursos da página e dados de uso frequente do admin são carregados mais cedo para reduzir atrasos na navegação. Consulte [Configuração, preços e controles do cliente para Bare Metal](https://nexcmp.com/pt/docs/infrastructure/dedicated/) e [Report a bug](https://nexcmp.com/pt/docs/administration/report-a-bug/). ## 1.6.0 - **Configuração de Bare Metal:** insira as redes iDRAC, o endereço do servidor ISO e o endereço de retorno do painel em **Safety › Management network connection**. Valores de exemplo bloqueiam operações reais até que sejam configurados. - **Hospedagem de ISO:** `sudo nexcmp dedicated-setup-iso` configura o servidor web de ISO da rede de gerenciamento. O instalador pode instalar o console e as ferramentas de ISO com `--baremetal` ou com as opções de ISO. Ferramentas ausentes bloqueiam operações reais com `tools_missing`. - **Preços de Bare Metal:** uma instalação nova ou sem uso começa com preços em USD. Instalações que já possuem dados de preços em VND mantêm o VND e ainda exigem uma cotação USD/VND. A atualização não reinterpreta esses preços existentes como dólares. - **Página do servidor do cliente:** renove antecipadamente, agende uma alteração no ciclo de faturamento, solicite mudança de plano, visualize faturas e acesse o login do SO após a instalação. Novos proprietários não têm acesso à senha do proprietário anterior. - **Perfis de clientes:** oito abas agrupam visão geral, serviços, faturamento, cota, segurança, suporte, afiliados e logs. Os serviços compartilham uma tabela única pesquisável e ordenável. - **Ações de serviço:** bloquear, desbloquear, cancelar sem reembolso ou cancelar com reembolso usam um diálogo comum. Os reembolsos retornam para a carteira ou alocação de crédito original; processadores de pagamento não são reembolsados automaticamente. Consulte [Servidores dedicados](https://nexcmp.com/pt/docs/infrastructure/dedicated/) e [Gerenciando clientes](https://nexcmp.com/pt/docs/customers/managing-customers/). BYOIP e vincular uma sub-rede de cliente a um servidor Bare Metal continuam indisponíveis no NexCMP. ## 1.5.2 O administrador principal pode abrir **Report a bug** ao lado de **Docs** e enviar um ticket para a conta da licença sem precisar de outro login. O envio de diagnósticos é opcional. Equipe, clientes e assistentes de IA não podem enviar relatórios por meio dessa ação. Consulte [Report a bug](https://nexcmp.com/pt/docs/administration/report-a-bug/). ## 1.5.1 - **Uso de VPN:** os nós de agente reportam o tráfego ao painel. Uma assinatura que esgota sua franquia de GB é interrompida; ela volta a ficar disponível após um upgrade de largura de banda ou um novo período. Nós sem relatórios de uso exibem **Not measured** e não são interrompidos com base em GB. - **Agente de VPN:** a versão 1.5.1 tenta reenviar o uso não confirmado, envia o tráfego final no encerramento e fecha conexões abertas quando um endpoint é interrompido. Atualize tanto os agentes remotos quanto o painel. - **Add-ons de VPN descontinuados:** High IP Reputation, High Concurrency e High Priority Network não são mais vendidos. Suas tarifas foram removidas dos valores de renovações futuras de assinaturas existentes; períodos anteriores não são reembolsados. Se um add-on foi excluído do catálogo, verifique o valor de renovação manualmente. - **Rótulos de protocolo:** o proxy HTTP IPv4 é HTTP simples. Os endereços IPv4 não sofrem rotação. A porta 443 do proxy IPv6 atende SOCKS5; não é um endpoint de proxy HTTPS. - **Nova instalação:** a inicialização do banco de dados tenta novamente conflitos transitórios de migração entre o painel e o worker, portanto salvar o primeiro provedor não exige reinicialização. Consulte [Nós de VPN e proxy IPv6](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 **AI Models** é um módulo opcional de gateway e faturamento, desativado por padrão. Adicione fontes de modelos que você opera ou tem autorização para revender, sincronize modelos, defina preços e rotas, ative os modelos e, em seguida, abra as vendas. Não há contas de provedor, modelos ou preços inclusos. Ele é separado do módulo AI Chat e AI Agent. Consulte [AI Models](https://nexcmp.com/pt/docs/infrastructure/ai-models/). ## 1.4.2 A instalação do nó de proxy IPv6 usa o daemon e o script de rede fornecidos no pacote de release. O painel precisa de `sshpass` para a instalação via SSH com senha. O painel executa agendamentos de rotação, e a configuração do nó exclui o endereço de gateway das alocações. O Branding pode definir um nome de exibição personalizado para o serviço de VPN. Consulte [Nós de VPN e proxy IPv6](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **Administração de IA:** AI Chat de administrador, contas pessoais de IA, chaves de API de administrador, o servidor MCP de administrador, conectores OAuth, importação/exportação de configuração e a checklist de configuração estão disponíveis. Consulte [Configure with AI](https://nexcmp.com/pt/docs/configure-with-ai/overview/). - **Licenciamento:** os fluxos de trabalho Free e Source incluem builds oficiais e builds personalizados a partir do código-fonte. Conta, licenciamento, downloads e documentação usam `nexcmp.com`. Consulte [Licenciamento e compra](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/). - **Links de documentação:** **Docs** no painel de administração abre o guia da página atual. - **Moedas:** uma nova instalação segue o idioma do cliente por padrão. USD/VND vem de uma tabela pública de taxas de câmbio ou da sua taxa fixa. Consulte [Moedas e taxas de câmbio](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). - **Zonas de origem mista:** os preços públicos de Cloud Server funcionam quando CloudStack e Proxmox VE compartilham uma zona. Os planos usam sua própria fonte de infraestrutura. - **Preços derivados de ofertas:** o percentual é uma margem sobre o preço de venda. Uma margem de 40% sobre um custo de $60 resulta em $100, antes de qualquer arredondamento. ## Checklist de upgrade {#upgrade-checklist} 1. Faça backup, leia o card **Update**, atualize e execute `sudo nexcmp status`. 2. Atualize os agentes de VPN e confirme se os nós estão reportando o tráfego medido antes de depender do corte por GB. 3. Se estiver usando Bare Metal, verifique os campos da rede de gerenciamento, as ferramentas necessárias, a unidade de preço, os templates e os planos de exemplo antes de abrir as vendas ou iniciar as operações em produção. 4. Abra o perfil de um cliente e verifique sua lista de serviços. Confira o valor e a alocação de pagamento original antes de confirmar um cancelamento com reembolso. 5. Mantenha os módulos opcionais desativados até que a infraestrutura deles esteja pronta. Para o AI Models, verifique um provedor, um modelo com preço definido e uma solicitação de cliente bem-sucedida antes de liberar as vendas. --- # Backup and restore {#backup-and-restore} > **Onde fica no painel:** System › Admin › Backup (`/backup`) aparece apenas quando o módulo DDoS & BGP está ativado; para uma instalação padrão, use a linha de comando abaixo. ## O que é incluído no backup {#what-is-backed-up} `sudo nexcmp backup` cria um arquivo compactado contendo: | Parte | Conteúdo | |---|---| | `data/**/*.db` | Todos os bancos de dados SQLite em `/var/lib/nexcmp`, copiados com a API de backup online do SQLite — consistente mesmo com o painel em execução | | `files.tar` | Todos os outros arquivos em `/var/lib/nexcmp` (arquivos de configuração, uploads de marca, `secrets/`), exceto bancos de dados e a pasta `updates/` | | `etc/` | Uma cópia de `/etc/nexcmp` (configurações do instalador, ID da instância, porta e bind) | ::: warning O arquivo compactado contém suas chaves mestras `secrets/` armazena a chave que criptografa chaves de API, credenciais de pagamento e senhas SMTP armazenadas no banco de dados. O arquivo é criado com permissões `0600`. Armazene-o criptografado e fora do servidor. Sem essas chaves, um banco de dados restaurado não poderá descriptografar seus segredos. ::: ## Criar um backup {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` O comando exibe o caminho do arquivo, por exemplo `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### Agende o backup {#schedule-it} ```bash echo '17 3 * * * root /usr/local/bin/nexcmp backup /var/backups/nexcmp && find /var/backups/nexcmp -name "nexcmp-backup-*" -mtime +14 -delete' | sudo tee /etc/cron.d/nexcmp-backup ``` Copie a pasta para fora da máquina (armazenamento de objetos, NAS, outro servidor). ## Restauração {#restore} Restaure em um servidor onde o NexCMP da **mesma versão (ou mais recente)** esteja instalado. 1. Instale o NexCMP com o [instalador](https://nexcmp.com/pt/docs/getting-started/installation/) usando a mesma licença e domínio, mas **não** execute o assistente de configuração. 2. Pare os serviços: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. Descompacte o arquivo em um diretório temporário: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. Restaure os arquivos: ```bash sudo tar -xf /root/restore/files.tar -C /var/lib/nexcmp sudo cp -a /root/restore/data/. /var/lib/nexcmp/ sudo cp -a /root/restore/etc/. /etc/nexcmp/ sudo chown -R nexcmp:nexcmp /var/lib/nexcmp ``` 5. Inicie os serviços e verifique: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. Entre em `https:///admin` com o administrador do sistema *do qual foi feito o backup*. ::: tip Faça um ensaio Execute os passos 1 a 6 em um servidor reserva uma vez, antes de precisar. Um backup que você nunca restaurou é apenas uma esperança. ::: ## Não incluído {#not-included} - Configuração do nginx e certificados (regenerados pelo instalador; os certificados Let's Encrypt são reemitidos). - Seus servidores CloudStack / Proxmox VE e as máquinas virtuais neles — faça o backup deles com suas próprias ferramentas. --- # Desinstalar o NexCMP {#uninstall-nexcmp} ::: warning Clientes perdem o acesso A desinstalação interrompe o portal e o faturamento. As máquinas virtuais no seu CloudStack ou Proxmox VE continuam rodando, mas nada as gerencia ou fatura. Faça um [backup](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/) primeiro. ::: ## Remover o programa, manter os dados {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` Isso desativa e remove os serviços `nexcmp` e `nexcmp-vmd`, o site e o snippet do nginx, `/opt/nexcmp` e o comando `nexcmp`. Os **dados permanecem** em `/var/lib/nexcmp` e `/etc/nexcmp`, para que uma instalação posterior no mesmo servidor continue de onde você parou. ## Remover tudo {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` Também exclui `/var/lib/nexcmp`, `/etc/nexcmp`, `/var/log/nexcmp` e o usuário do sistema `nexcmp`. Esta ação não pode ser desfeita. ## Após a desinstalação {#after-uninstalling} - Os certificados Let's Encrypt e os pacotes `nginx` / `certbot` são mantidos no lugar. Remova o certificado com `sudo certbot delete --cert-name ` se desejar. - Libere o domínio na sua página de licença em [nexcmp.com/licenses](https://nexcmp.com/licenses) se for ativá-lo em outro lugar. - Exclua a conta dedicada do CloudStack / token de API do Proxmox criado para o NexCMP se você não precisar mais deles. --- # Referência de comando `nexcmp` {#nexcmp-command-reference} O instalador coloca um auxiliar em `/usr/local/bin/nexcmp`. Execute-o no servidor NexCMP. Comandos que alteram o sistema precisam de `sudo`. (A ferramenta voltada ao cliente para a API é um programa diferente, consulte [cmp CLI](https://nexcmp.com/pt/docs/developers/cmp-cli/).) | Comando | Requer root | O que faz | |---|---|---| | `nexcmp status` | Não (mais detalhes com `sudo`) | Versão, estado do serviço (`nexcmp`, `nexcmp-vmd`), `/healthz`, resumo da licença, estado da porta pública, código de instalação se o assistente não estiver concluído | | `nexcmp update` | Sim | Executa o instalador fornecido na versão instalada com os parâmetros salvos — consulte [Atualizando](https://nexcmp.com/pt/docs/getting-started/updating/) | | `nexcmp backup [dir]` | Sim | Backup para `/var/backups/nexcmp` (ou `dir`) — consulte [Backup and restore](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | Sim | Remover serviços e programa; `--purge` também remove os dados — consulte [Uninstall](https://nexcmp.com/pt/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | Sim | **Emergência**: escutar na porta do painel (padrão 3000) em todas as interfaces por 1 a 1440 minutos (padrão 30) e, em seguida, fechar automaticamente | | `nexcmp close-port` | Sim | Fechar a janela de emergência agora | | `nexcmp fix-owner` | Sim | Devolver os arquivos em `/var/lib/nexcmp` pertencentes ao root para o usuário `nexcmp` | ## `nexcmp status` ```text Version : 1.6.1 nexcmp : active nexcmp-vmd : active healthz : ok License : active · domain cloud.example.com · token valid until 2026-11-12 · updates until 2027-10-30 Public port: 127.0.0.1 only (nginx proxy; emergency: sudo nexcmp open-port) ``` Se os arquivos no diretório de dados pertencerem ao root (por exemplo, criados ao executar outro comando do `nexcmp` com `sudo` como root), o `status` exibirá um aviso, pois o usuário do serviço não consegue lê-los — um sintoma típico é a licença exibindo HTTP 421. Corrija com `sudo nexcmp fix-owner`. A mesma correção é executada automaticamente a cada inicialização do serviço. ## Acesso de emergência {#emergency-access} Quando o domínio, o nginx ou o TLS estiverem com problemas, você ainda poderá acessar o painel: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` Mais seguro, sem abrir nada: `ssh -L 3000:127.0.0.1:3000 user@server` e acesse `http://127.0.0.1:3000/`. ## Ambiente {#environment} | Variável | Usado para | |---|---| | `NEXCMP_BASE` | Substituir a URL base do servidor de licenças (padrão `https://nexcmp.com`); apenas para testes | Arquivos e diretórios: programa `/opt/nexcmp`, configuração `/etc/nexcmp`, dados `/var/lib/nexcmp`, logs `/var/log/nexcmp` e `journalctl -u nexcmp -u nexcmp-vmd`. --- # Requisitos de infraestrutura {#infrastructure-requirements} > **Onde encontrar no admin:** Infrastructure (o menu à esquerda) e System › Admin › License & updates (`/license`) para ativar os módulos. Esta página lista o que cada módulo precisa **fora** do servidor NexCMP. Para o próprio servidor (Ubuntu, memória, disco, portas), consulte [Requirements for the NexCMP server](https://nexcmp.com/pt/docs/getting-started/requirements/). Para ativar os módulos, consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/). ## Módulo por módulo {#module-by-module} | Módulo | Infraestrutura mínima | Detalhes | |---|---|---| | **Virtual Machines on CloudStack** | Apache CloudStack 4.23 (testado), KVM, uma zona avançada com uma rede de convidado e um intervalo de IP público; um domínio e uma conta dedicados com uma chave de API (nunca ROOT); pelo menos um template pronto e uma service offering | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) | | **Virtual Machines on Proxmox VE** | Proxmox VE 9.x (verificado na 9.2); um token de API com uma função personalizada; um armazenamento que aceite clones; um bridge; um bloco IPv4 com um gateway; um template cloud-init por SO e por nó | [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) | | **OS templates** | CloudStack: uma máquina de build Linux com libguestfs e um servidor web para a imagem. Proxmox VE: templates de cloud-image com o guest agent | [OS templates](https://nexcmp.com/pt/docs/infrastructure/templates/) | | **Bare metal / Dedicated Server** | Servidores Dell com iDRAC 9 acessível via HTTPS (Redfish) a partir do painel em uma rede de gerenciamento; um servidor HTTP nessa rede que sirva arquivos ISO; pastas ISO graváveis para o serviço do NexCMP | [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/) | | **AI Models** | Uma ou mais fontes de modelos que você tenha autorização para revender, com API compatível com OpenAI ou Anthropic e sua própria chave; HTTPS de saída (porta 443, nome de domínio público) do painel para cada fonte, ou um gateway interno listado em Allowed internal hosts; sem GPU ou hardware especial | [AI Models](https://nexcmp.com/pt/docs/infrastructure/ai-models/) | | **VPN** | Um ou mais hosts Linux (x86_64, systemd, root) com endereços IPv4 públicos na interface ou roteados para ela, HTTPS de saída para o seu painel | [Nós de VPN e proxy](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | Hosts Linux (x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`) com um IPv4 público, portas 80, 443 e 60001-65535 livres e um prefixo IPv6 de /32 a /64 que funcione para o tráfego de saída; acesso SSH com senha para a instalação única | [Nós de VPN e proxy](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | Um cluster Ceph com RADOS Gateway (RGW), um usuário Admin Ops e um endpoint HTTPS público na porta 443 | [S3](https://nexcmp.com/pt/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack com o Kubernetes Service (CKS) ativado, pelo menos uma ISO de versão do Kubernetes e uma oferta de serviço de plano de controle gratuita de exatamente 2 vCPU e 2048 MB | [Kubernetes e Private Cloud](https://nexcmp.com/pt/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack com uma oferta de VPC e uma oferta de rede por plano de largura de banda (além de uma oferta bloqueada de 1 Mbps) | [Kubernetes e Private Cloud](https://nexcmp.com/pt/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack cuja VM de armazenamento secundário consiga acessar a Internet para baixar imagens de clientes (links diretos, sem redirecionamentos); a conta do CloudStack pode registrar templates e ISOs | [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | | **Bandwidth** | Nada extra com a fonte padrão: o uso é lido a partir das estatísticas de VMs do CloudStack. VMs no Proxmox VE não são medidas | [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | Uma API compatível com OpenAI (URL base, modelo e chave) que o servidor do painel possa alcançar. Nenhum software extra nos seus servidores | [AI providers](https://nexcmp.com/pt/docs/ai/ai-providers/) | | **DDoS & BGP** | Um pacote adicional que precisa de um host de roteador de borda com daemons executados como root (BGP, filtragem, estatísticas de fluxo). Ele não faz parte da instalação padrão | [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | | **DDoS Shield** | O add-on DDoS & BGP | [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | | **Web SSH terminal** | Um serviço de proxy SSH separado e uma rota para ele. Ele não faz parte da instalação padrão; o AI Agent não precisa dele | [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | ## Caminhos de rede em resumo {#network-paths-at-a-glance} | De | Para | Porta | Finalidade | |---|---|---|---| | Servidor do painel | Servidor de gerenciamento do CloudStack | 443 ou 8080 (conforme você publicar) | API | | Servidor do painel | Nó do Proxmox VE | 8006/tcp | API e console | | Servidor do painel | Dell iDRAC | 443/tcp (e a porta VNC, padrão 5901) | Redfish e console | | iDRAC | Servidor web de ISOs | a porta HTTP que você escolher (por exemplo 8080) | Mídia virtual | | Servidor do painel | Ceph RGW | 443/tcp | Admin Ops | | Servidor do painel | Nó de proxy IPv6 | Porta SSH inserida | Instalação única | | Nós de VPN e proxy | Painel (via nginx) | 443/tcp | Inscrição, heartbeat, configuração | | Clientes | Nós de VPN e proxy | portas por IP 65001-65535 (VPN); 80, 443, 60001-65535 (proxy IPv6) | O serviço em si | ::: tip Mantenha as redes de gerenciamento privadas Os endereços de gerenciamento do iDRAC e do hipervisor devem estar em uma rede que os clientes não possam alcançar. O NexCMP recusa endereços do iDRAC fora das faixas privadas permitidas por você. ::: ## Checklist antes de vender {#checklist-before-you-sell} 1. A infraestrutura por trás do primeiro serviço está conectada e **Test connection** está verde. 2. Uma zona está pronta para vendas (consulte [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/)): um backend ativo, um plano e um template pronto. 3. Um canal de pagamento está configurado (consulte [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/)). 4. O e-mail funciona (consulte [SMTP and e-mails](https://nexcmp.com/pt/docs/administration/smtp-and-emails/)). 5. Você realizou um pedido de teste e excluiu a VM. --- # Arquitetura {#architecture} > **Onde no admin:** esta é uma página de referência. Os serviços descritos aqui estão visíveis com `sudo nexcmp status`; as conexões são configuradas em Infrastructure e System › Settings. ## A visão geral {#the-picture} ![Arquitetura do NexCMP: os clientes acessam o nginx por DNS e, opcionalmente, pelo Cloudflare; o nginx faz proxy para o painel na porta 3000; o painel e o worker se comunicam com o CloudStack, Proxmox VE, iDRAC, Ceph, gateways de pagamento, SMTP e um provedor de IA; e nós de VPN e proxy IPv6 se comunicam de volta com o painel](https://nexcmp.com/pt/docs/images/infrastructure/architecture.svg) ### O mesmo diagrama em palavras {#the-same-diagram-in-words} 1. Um cliente ou administrador abre o `https://cloud.example.com` (o portal), o `https://cloud.example.com/admin` (o console de administração) ou chama a REST API. O DNS aponta o nome para o seu servidor ou para o Cloudflare, que faz proxy para ele. 2. O **nginx** no servidor do painel escuta nas portas 80 (redirecionamento e renovação de certificado) e 443 (TLS) e encaminha cada requisição para o **panel** em `127.0.0.1:3000`. Após o assistente de instalação, o painel escuta apenas na interface de loopback. 3. O **panel** (`nexcmp.service`) serve o portal do cliente, o console de administração, a REST API, o assistente de instalação e os downloads necessários para os nós (o binário do agente, o script de instalação, a ferramenta de linha de comando `cmp`). Ele também verifica sua licença uma vez por dia. 4. O **worker** (`nexcmp-vmd.service`) escuta em `127.0.0.1:8112`, que é apenas local. Ele executa tudo o que leva tempo ou precisa acontecer de forma agendada: tarefas de provisionamento, sincronização com CloudStack e Proxmox VE, ciclos de faturamento, coleta de largura de banda e conexões do console do navegador. 5. A partir desses dois processos, o NexCMP faz chamadas externas para: **CloudStack** (API de gerenciamento), **Proxmox VE** (API na porta 8006, certificado fixado/pinned), **Dell iDRAC** (Redfish sobre HTTPS na rede de gerenciamento), **Ceph RGW** (S3 e Admin Ops sobre HTTPS), **gateways de pagamento** (Stripe, PayPal, USDT e provedores de transferência bancária, que também chamam suas URLs de webhook), **seu servidor SMTP**, um **provedor de IA** com uma API compatível com OpenAI e, opcionalmente, **Telegram**. 6. **Nós de VPN** executam `cmp-agent`. Cada nó se registra uma vez com um token de uso único, envia um batimento cardíaco a cada 5 segundos via HTTPS para o painel e recebe sua configuração na resposta. **Nós de proxy IPv6** são instalados uma vez pelo painel via SSH e, em seguida, obtêm sua configuração do painel. 7. O estado reside em bancos de dados SQLite e em alguns arquivos em `/var/lib/nexcmp`. As credenciais para CloudStack, Proxmox, S3, iDRAC e o provedor de IA são armazenadas criptografadas (AES-256-GCM) com arquivos de chave mestra na mesma área. ## Serviços e processos {#services-and-processes} | Processo | Executado como | Escuta em | Função | |---|---|---|---| | `nginx` | root (workers `www-data`) | 80, 443 | TLS, redirecionamento, proxy para o painel | | `nexcmp` | `nexcmp` | 3000 (todas as interfaces durante a primeira instalação, depois `127.0.0.1`) | Portal, console de administração, API, assistente, downloads | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | Tarefas, sincronização, faturamento, largura de banda, console | | `nexcmp-update` | root | nenhum | Aplica atualizações solicitadas pelo console de administração (uma unidade de caminho aguarda pela solicitação) | | `cmp-agent` (em nós VPN) | root | as portas do listener VPN | Reporta-se ao painel, executa listeners de proxy em IPv4 públicos | O painel e o worker executam como um usuário comum, sem quaisquer recursos do Linux, com um sistema de arquivos somente leitura, exceto `/var/lib/nexcmp` e `/var/log/nexcmp`. Não precisam de root, Docker, banco de dados separado ou Redis. ## Arquivos e onde eles ficam {#files-and-where-they-are} | Caminho | Conteúdo | |---|---| | `/opt/nexcmp` | O programa: versões, `bin/`, arquivos compartilhados como o construtor de modelos. De propriedade do root, somente leitura para o serviço. | | `/etc/nexcmp` | Configurações do instalador (`install.conf`), porta e vínculo (`nexcmp.env`). | | `/var/lib/nexcmp` | Bancos de dados SQLite, identidade visual enviada, pasta de download do agente, estado da licença, arquivos de chave mestra. Faça backup disso. | | `/var/log/nexcmp` | Logs. | Consulte [Backup and restore](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/). Os arquivos de chave mestra devem ter o backup feito junto com os bancos de dados, caso contrário, um banco de dados restaurado não poderá descriptografar suas credenciais armazenadas. ## Quem se conecta a quem {#who-connects-to-whom} | Direção | Caminho | Porta | Notas | |---|---|---|---| | Cliente para o painel | Internet, DNS, Cloudflare opcional, nginx | 443 | Consulte [DNS and Cloudflare](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/). | | Painel para o servidor de licenças | `nexcmp.com` | 443 | Ativação, verificação diária e atualizações. | | Painel para o CloudStack | API | 443 ou 8080 | O console da VM, largura de banda e recursos de Kubernetes usam o mesmo endpoint. | | Painel para o Proxmox VE | API e console WebSocket | 8006 | Certificado fixado (pinned) por SHA-256. | | Painel para o iDRAC | Redfish | 443, VNC 5901 | Apenas rede de gerenciamento. | | iDRAC para o servidor ISO | HTTP | sua porta | O iDRAC puxa a ISO. | | Painel para o Ceph RGW | Admin Ops | 443 | | | Painel para o SMTP | SMTP | 587 ou 465 | | | Painel para o provedor de IA | HTTPS | 443 | Apenas quando o módulo de IA estiver ativado. | | Gateway de pagamento para o painel | Webhook | 443 | Stripe e PayPal fazem chamadas de retorno (callback). | | Nó para o painel | `cmp-agent` | 443 | Registro, heartbeat, atualização. | | Painel para o nó de proxy IPv6 | SSH | a porta que você digita | Instalação única. | ## Por que isso importa {#why-it-matters} - **Um painel que pode ser acessado é um painel que pode ser atacado.** Mantenha a porta 3000 fechada após concluir o assistente de configuração. O instalador já faz isso quando o TLS está ativo. - **O worker deve estar em execução** para que qualquer recurso seja criado ou cobrado. `sudo nexcmp status` exibe ambos os serviços e a verificação de integridade. - **Planeje os firewalls de saída.** Se o tráfego de saída do servidor do painel for filtrado, libere os destinos na tabela acima. - **O tráfego de gerenciamento fica fora da rota pública.** As conexões com CloudStack, Proxmox VE, iDRAC e Ceph vão direto do servidor do painel para esses sistemas, nunca através do nginx ou Cloudflare. --- # Módulos {#modules} > **Onde no admin:** System › Admin › License & updates (`/license`), no card **Module**. ## O que faz {#what-it-does} Um módulo é um serviço ou recurso que você pode ativar ou desativar por completo. Um módulo que está **desativado** fica oculto no menu administrativo e os clientes não podem comprá-lo; suas rotas de API respondem com `404 module_disabled` quando o módulo for um complemento. Ativar um módulo apenas expõe o recurso: a infraestrutura por trás dele ainda precisa estar conectada (consulte a última coluna). ## Requisitos {#requirements} | Item | Requisito | |---|---| | Conta | Um administrador com acesso de gravação. A equipe somente leitura pode ver as chaves, mas não alterá-las. | | Infraestrutura | Consulte a tabela: cada módulo lista o que precisa. | | Depende de | Alguns módulos precisam de outros (o DDoS Shield precisa de DDoS & BGP). | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não é obrigatório para a chave em si. Conecte a infraestrutura de cada módulo conforme descrito na página vinculada na tabela. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **System › Admin › License & updates** e role até o card **Module**. Ele informa que os módulos desativados ficam ocultos no menu administrativo e não podem ser adquiridos pelos clientes. 2. Use a chave de um módulo. A página confirma **Saved: reloading menu** e é recarregada, fazendo com que o menu mude imediatamente. ![O card Module em License & updates com uma chave para cada módulo](https://nexcmp.com/pt/docs/images/infrastructure/modules-01-license-modules.webp) ### Os módulos {#the-modules} | Módulo (conforme exibido) | Padrão | O que adiciona | Necessita | Página | |---|---|---|---|---| | **Virtual Machines** | sempre ativado | Catálogo de VMs, pedidos, console, snapshots | CloudStack ou Proxmox VE | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) | | **Bandwidth** | **ativado** | Cotas, complementos, alertas e ações de excedente para VMs, Kubernetes e S3 | Nada extra (estatísticas de VM do CloudStack) | [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/) | | **OS & ISO Images** | desativado | Os clientes registram suas próprias imagens de SO e ISOs, cobradas por GB | CloudStack; acesso à Internet para sua VM de armazenamento secundário | [Requisitos](https://nexcmp.com/pt/docs/infrastructure/requirements/) | | **Kubernetes** | desativado | Clusters Kubernetes (CKS) | CloudStack com CKS habilitado | [Kubernetes e Private Cloud](https://nexcmp.com/pt/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | desativado | VPC com planos de largura de banda dedicada | VPC do CloudStack e ofertas de rede | [Kubernetes e Private Cloud](https://nexcmp.com/pt/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | desativado | Contas S3 em Ceph RGW, pague pelo uso | Ceph RGW e uma zona com o serviço S3 | [S3](https://nexcmp.com/pt/docs/infrastructure/s3/) | | **VPN** | desativado | VPN em seus próprios nós | Nós executando o `cmp-agent` | [Nós de VPN e proxy](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | desativado | Proxy IPv6 em seus próprios nós | Nós de proxy com um prefixo IPv6 | [Nós de VPN e proxy](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | desativado | Servidores Dell via iDRAC: pedidos, instalação de SO, console, energia | iDRAC 9 em uma rede de gerenciamento | [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/) | | **AI Models** | desativado | Um gateway que vende acesso a modelos de IA: uma única chave para vários modelos, preços por modelo, limites de uso, logs e faturamento via carteira | Fontes de modelos fornecidas por você: uma API compatível com OpenAI ou Anthropic com sua própria chave | [AI Models](https://nexcmp.com/pt/docs/infrastructure/ai-models/) | | **AI** | desativado | AI Chat (suporte automatizado) e AI Agent (administração de VM em linguagem natural) | Um provedor compatível com OpenAI | [AI providers](https://nexcmp.com/pt/docs/ai/ai-providers/) | | **DDoS Shield** | desativado | Proteção de IP para clientes; precisa de DDoS & BGP, portanto o botão permanece desativado sem eles | O add-on DDoS & BGP | abaixo | | **DDoS & BGP** | desligado, **add-on** | Console do roteador de borda: BGP, RTBH, XDP, sessões e tráfego de borda | Um host de borda com daemons root | abaixo | ### O que cada botão faz {#which-switch-does-what} - O **Bare Metal** tem duas camadas. O botão do módulo exibe o menu de administração e a API. A venda para clientes é um botão separado com uma confirmação digitada em **Services › Dedicated Server**, e toda gravação no iDRAC é bloqueada até que você ative o **live ops** em **Infrastructure › Bare Metal › Safety**. Consulte [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/). - Para **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** e **Images**, o botão do módulo e o botão de vendas na página do serviço controlam a mesma configuração. - O **AI** também precisa de um provedor configurado em **System › Settings › AI provider**. - O **AI Models** tem duas camadas. O switch do módulo exibe o menu de administração e a API. A venda para clientes é controlada por um switch de venda separado no topo das páginas do AI Models, desativado por padrão. Consulte [AI Models](https://nexcmp.com/pt/docs/infrastructure/ai-models/). ### Módulos lidos na inicialização {#modules-read-at-start-up} Três recursos não são botões comuns. Eles são lidos **uma vez quando os serviços iniciam** e exigem uma infraestrutura que a instalação padrão não inclui. | Recurso | Configuração | Estado | O que é necessário | |---|---|---|---| | DDoS & BGP | `module_ddos` | Exibido como **Add-on package** quando desligado, **Installed** quando ligado. Não há botão no console. | Daemons do roteador de borda (BGP, RTBH, XDP, estatísticas de fluxo) executados como root. O painel é executado como um usuário sem privilégios e não pode executá-los. | | IA | `module_ai` | Um botão normal. As rotas entram em vigor imediatamente; as tarefas em segundo plano do AI Chat (investigação de tickets, respostas agendadas) começam na próxima reinicialização dos serviços. O console indica que a reinicialização é recomendada. | O provedor de AI. | | Terminal SSH web | `feature_ssh_web` | Desligado por padrão, sem botão no console | Um serviço de proxy SSH separado e sua rota. Sem ele, a aba Console do portal exibe apenas VNC. O **AI Agent não precisa dele**: ele executa comandos por meio de uma conexão SSH que o próprio painel estabelece. | Após uma alteração em uma configuração de inicialização, reinicie os serviços: `sudo systemctl restart nexcmp nexcmp-vmd`. ## Verificar {#verify} 1. O item de menu do módulo aparece (ou desaparece) após a recarga. 2. Para um módulo voltado ao cliente, o portal exibe o novo item de menu para um cliente conectado. Um módulo desativado não exibe nada ou "coming soon". ## Limites e observações {#limits-and-notes} - Desativar um módulo não exclui nada. VMs, clusters, contas S3 e assinaturas em execução continuam funcionando e sendo cobrados; os clientes apenas não conseguem criar novos. - As páginas de cotas listam apenas os serviços cujos módulos estão ativados. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | A entrada do menu não apareceu | A página não foi recarregada | Recarregue o console administrativo. | | O interruptor do DDoS Shield está desativado | O DDoS & BGP não está instalado | O DDoS Shield precisa do add-on DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 ou 422) | Você (ou um script) tentou alternar o DDoS & BGP | É um pacote add-on; não há opção de alternar. | | "O DDoS Shield precisa do add-on DDoS & BGP" | O mesmo para o DDoS Shield | Instale o add-on primeiro. | | Uma rota de módulo responde com 404 `module_disabled` | O módulo está desativado | Ative o módulo. | | O AI Chat responde, mas a investigação do ticket nunca começa | O módulo de IA foi ativado sem uma reinicialização | `sudo systemctl restart nexcmp nexcmp-vmd`. | | Equipe com acesso somente leitura não pode salvar | A função deles é somente leitura | Use uma conta de administrador. | --- # Zonas {#zones} > **Onde encontrar no admin:** Infrastructure › Datacenter › Zone (`/infra/zones`). A página de detalhes de uma zona é `/infra/zones/`. ## O que faz {#what-it-does} Uma **zona** é o local que o cliente escolhe ao fazer um pedido: um país e cidade com bandeira, além dos serviços vendidos lá. É um conceito de vendas, separado das zonas, clusters e nós das plataformas por trás dele. Atrás de uma zona, você vincula a **infraestrutura**: uma zona do CloudStack, um cluster Proxmox VE, nós de VPN com intervalos de IPs, um backend S3. A Zona 1 é criada pelo [assistente de configuração](https://nexcmp.com/pt/docs/getting-started/setup-wizard/), com o nome de exibição e o país que você inseriu. Adicione mais zonas quando tiver infraestrutura em mais locais, ou para dar locais próprios a VPN e S3. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Permissões | Uma conta de administrador. Uma função de equipe somente leitura pode visualizar, mas não alterar. | | Infraestrutura | Uma zona não vende nada até que algo seja vinculado a ela (consulte "Which service sells where" abaixo). | | Depende de | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) ou [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) para VMs, [VPN and proxy nodes](https://nexcmp.com/pt/docs/infrastructure/vpn-proxy-nodes/) para VPN, [S3](https://nexcmp.com/pt/docs/infrastructure/s3/) para armazenamento de objetos. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não obrigatório. Uma zona é um registro dentro do NexCMP. ## Conectar no NexCMP {#connect-in-nexcmp} ### Criar uma zona {#create-a-zone} 1. Abra **Infrastructure › Datacenter › Zone** e clique em **Add zone**. 2. Preencha o formulário: | Campo | Valor de exemplo | Notas | |---|---|---| | Country | `United States` | Escolhe a bandeira. | | City | `New York` | Opcional. | | Name (Vietnamese), Name (English) | `New York` | O nome que os clientes veem em cada idioma. | | Slug | `us-new-york` | a-z, 0-9, hífen, 2-32 caracteres. Preenchido automaticamente com o país e a cidade até que você digite o seu próprio. | | Visibility | Public | Zonas **Public** ficam visíveis para todos os clientes; zonas **Hidden** são atribuídas apenas por um administrador. | | Order | `0` | Números menores aparecem primeiro nas listas. | | Serviços vendidos nesta zona | Virtual Machines (VM), VPN, Object Storage (S3) | Marque pelo menos uma. | | Active | On | **Off** oculta a zona dos clientes. | | Padrão | desativado | A zona pré-selecionada para clientes que não escolheram nenhuma. Exatamente uma zona é a padrão. | ![Janela de adição de zona com país, cidade, slug e os serviços marcados](https://nexcmp.com/pt/docs/images/infrastructure/zones-01-add-zone.webp) 3. Clique em **Create zone**. A lista exibe a zona com sua bandeira, proprietário, serviços, estado e contagens de VMs, planos e infraestrutura vinculada. ![Lista de zonas com a zona padrão e uma segunda zona](https://nexcmp.com/pt/docs/images/infrastructure/zones-02-list.webp) ### Verifique o que está vinculado {#look-at-what-is-attached} Clique em uma linha para abrir a zona. A aba **Provider infrastructure** lista cada backend associado com seu provedor, tipo (CloudStack ou Proxmox VE), região, estado e prioridade. A aba **VPN infrastructure** lista os intervalos de VPN e nós da zona, além de fornecer links para o pool de VPN. ![Detalhes da zona com a aba Provider infrastructure](https://nexcmp.com/pt/docs/images/infrastructure/zones-03-detail.webp) ### Onde cada serviço é vendido {#which-service-sells-where} | Service | Como ele entra em uma zona | |---|---| | Virtual Machines on CloudStack | O assistente (ou **Infrastructure › Cloud provider › CloudStack**) conecta o CloudStack à zona 1. | | Virtual Machines on Proxmox VE | Na aba **Clusters** do cluster, clique em **Attach cluster to zone**. O cluster ingressa em uma zona **existente**, normalmente aquela que vende por meio do CloudStack. | | VPN | Um nó de VPN que relata seus intervalos de IP públicos cria (ou entra em) uma zona para seu país e coloca os intervalos no pool de VPN. Você também pode atribuir a zona e o nó de um intervalo em **VPN IP pools**. | | IPv6 Proxy | Um novo nó de proxy IPv6 cria sua zona no estado **off**. Ative a zona aqui para que os clientes possam selecioná-la. | | Object Storage (S3) | Marque o serviço S3 na zona e, em seguida, vincule o backend em **Ceph S3 (RGW)**. | ### Quando uma zona pode vender máquinas virtuais? {#when-can-a-zone-sell-virtual-machines} Um zone exibe a tag **not ready to sell VMs** até que tenha pelo menos um backend ativo e vendável **e** pelo menos um plano visível **e** pelo menos um template pronto nesse backend. O formulário de pedidos do cliente lista apenas os zones que estão prontos. ## Verificar {#verify} 1. O zone aparece na lista como **On**, com a flag correta. 2. A página de detalhes mostra o backend ou os intervalos de VPN esperados. 3. Para VMs: a tag **not ready to sell VMs** desaparece. No portal do cliente, inicie um pedido e verifique se o zone é oferecido. ## Limites e observações {#limits-and-notes} - Nesta versão do NexCMP, os clientes encomendam máquinas virtuais na **zona padrão** (zona 1). Outras zonas são usadas para VPN, Proxy IPv6 e Object Storage, ou para preparar um local antes de ele ter infraestrutura; a nota abaixo da lista de zonas diz o mesmo. - Uma zona só pode ser excluída quando nada estiver vinculado: nenhum backend, VM, plano ou intervalo de VPN. A zona padrão não pode ser excluída; defina outra zona como padrão primeiro. - Zonas pertencentes a um revendedor só podem ser ativadas ou desativadas e ocultadas ou exibidas por você; os outros campos delas ficam bloqueados. - O slug faz parte das referências internas. Escolha-o uma vez. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "O nome da zona é obrigatório" / "Selecione o país" / "Selecione pelo menos 1 serviço" | Um campo obrigatório está vazio | Preencha o nome, escolha o país e marque um serviço. | | "Slug inválido (a-z 0-9 -, 2-32 caracteres)" | O slug tem outros caracteres ou o comprimento incorreto | Use apenas letras minúsculas, dígitos e hífens. | | Tag "não pronta para vender VMs" | Nenhum backend ativo pronto para venda, nenhum plano ou nenhum template pronto nessa zona | Anexe a infraestrutura e, em seguida, adicione um plano e um template. Consulte [Plans](https://nexcmp.com/pt/docs/catalog/plans/) e [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/). | | A exclusão está desativada com "still attached" | A zona possui backends, VMs, planos ou intervalos de VPN | Remova ou mova-os primeiro. | | A exclusão está desativada com "Default zone" | A zona é a padrão | Defina outra zona como padrão. | | Os clientes não veem a zona | Ela está oculta, inativa ou não tem nenhum serviço marcado | Defina Visibility como Public, Active como On e marque o serviço. | | Uma zona S3 está faltando no formulário de backend | O serviço S3 não está marcado na zona | Edite a zona e marque **Object Storage (S3)**. | --- # CloudStack > **Onde no admin:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). A primeira conexão também pode ser feita no [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/), etapa 2. ## O que faz {#what-it-does} O NexCMP vende máquinas virtuais executadas na sua nuvem Apache CloudStack. Ele implanta, inicia, para, redimensiona, tira snapshots e exclui VMs por meio da API do CloudStack, distribui endereços IP públicos da zona, lê o uso para faturamento e largura de banda, e exibe a capacidade e o status no console do administrador. O CloudStack continua sendo a fonte da verdade para os hipervisores; o NexCMP é a vitrine, o faturamento e o portal integrados. Use esta página quando o CloudStack for (ou for ser) sua principal fonte de VMs. Para uma segunda fonte ao lado dela, consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). ## Requisitos {#requirements} | Item | Requisito | |---|---| | Versão do CloudStack | 4.23 é a versão testada. O console da VM precisa da 4.18 ou mais recente, e o escalonamento ao vivo de CPU/RAM de uma VM em execução requer a 4.23 com KVM. | | Tipo de zona | Uma zona com pelo menos uma rede de convidado para as VMs dos clientes e um intervalo de IP público com endereços livres. | | Hipervisor | O KVM é o hipervisor testado. | | Conta | Um **domínio e conta dedicados** criados para o NexCMP. Nunca use a chave de administrador ROOT. | | Acessibilidade da API | O servidor do painel deve alcançar a URL da API do servidor de gerenciamento (`https://cloudstack.example.com/client/api`) via HTTP(S). O console da VM, a largura de banda e os recursos do Kubernetes usam o mesmo endpoint. | | Chave somente leitura opcional | Uma segunda chave somente leitura permite que o console administrativo exiba hosts, armazenamento, VMs de sistema e intervalos de IPs públicos. Não é necessária para vender VMs. | | IP público | Endereços IPv4 públicos gratuitos na zona. O prefixo que o NexCMP pode vender é configurado em Sales IP pools. | | Templates | Pelo menos um template pronto e habilitado para senha e uma oferta de serviço que sua conta possa ver. Consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/). | | Armazenamento | Armazenamento primário para os volumes da conta e, se você vender snapshots ou imagens, armazenamento secundário. | | Depende de | Nenhum. Kubernetes, Private Cloud, Images e Bandwidth dependem desta página. | ::: warning Não use a chave de administrador ROOT Crie um domínio e uma conta dedicados para o NexCMP. Assim, a chave atinge apenas esse domínio, e uma chave vazada não pode afetar o resto da sua nuvem. O assistente de configuração também verifica se a rede escolhida pertence à zona **e** à conta proprietária da chave. ::: ## Preparar a infraestrutura {#prepare-the-infrastructure} Os comandos usam o [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) conectado como administrador do CloudStack. Substitua os nomes de exemplo e os espaços reservados entre colchetes angulares. ### Criar uma conta dedicada e uma chave de API {#create-a-dedicated-account-and-api-key} 1. Crie o domínio que conterá tudo o que pertence ao NexCMP. ```bash cmk create domain name=nexcmp ``` Anote o `id` na saída; ele é usado como `` abaixo. 2. Encontre a função que deseja atribuir à conta. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Função | Quando escolher | |---|---| | **Domain Admin** (recomendado) | Conjunto completo de recursos: VMs, redes, projetos para Kubernetes, VPC, imagens. O alcance para no domínio `nexcmp`. | | Usuário | Apenas ciclo de vida da VM. Um usuário comum não pode excluir permanentemente (expunge) VMs, a menos que a configuração global `allow.user.expunge.recover.vm` seja true; o NexCMP então para a VM e o CloudStack a expunge após `expunge.delay`. | 3. Crie a conta e seu primeiro usuário. Use uma senha longa e aleatória; ela nunca mais será digitada. ```bash cmk create account name=nexcmp-api username=nexcmp-api \ password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \ firstname=NexCMP lastname=API roleid= domainid= ``` 4. Gere o par de chaves de API para o novo usuário. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Copie `apikey` e `secretkey`. Elas são a **API key** e a **Secret key** que você insere no NexCMP. O NexCMP as armazena criptografadas e exibe apenas os últimos quatro caracteres posteriormente. 5. Certifique-se de que o domínio não tenha limites de recursos restritivos (instâncias, volumes, IPs públicos, redes, snapshots, templates, projetos). ```bash cmk list resourcelimits domainid= ``` ### Criar a rede de convidados para VMs de clientes {#create-the-guest-network-for-customer-vms} As VMs de clientes são implantadas em uma rede de convidados que pertence à nova conta. Uma rede isolada com um roteador virtual (VR) e os serviços Static NAT, Firewall e Port Forwarding funciona bem, pois o NexCMP associa um IP público a cada VM com NAT estático. ```bash cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name cmk create network name=customers displaytext=customers zoneid= \ networkofferingid= account=nexcmp-api domainid= ``` Verifique a política de egress padrão da oferta: se for "deny", as VMs dos clientes não terão acesso de saída até que regras de egress do firewall sejam adicionadas. ### Tornar ofertas e templates visíveis {#make-offerings-and-templates-visible} - **Service offerings** e **network offerings** devem ser públicos ou atribuídos ao domínio `nexcmp`; caso contrário, a conta não poderá listá-los ou usá-los. - Registre ou compartilhe pelo menos um template (consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/)). O NexCMP lista os templates que estão prontos e marcados como em destaque. ### Opcional: chave somente leitura para páginas de infraestrutura {#optional-read-only-key-for-infrastructure-pages} As abas **Capacity**, **Host**, **Storage** e **System VM** e a lista de faixas de IP público usam uma segunda chave que precisa apenas de permissão de leitura para seis comandos. Crie uma função limitada em vez de reutilizar uma chave de administrador completa: ```bash cmk create role name=nexcmp-readonly type=Admin # is the id printed above for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do cmk create rolepermission roleid= rule=$api permission=allow done cmk create rolepermission roleid= rule='*' permission=deny ``` Em seguida, crie uma conta com essa função (no domínio ROOT, pois ela lê dados de toda a zona), gere suas chaves como no passo 4 e insira-as como **RO API key** na seção seguinte. ### Verificar o caminho de rede {#check-the-network-path} A partir do servidor do painel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Qualquer resposta HTTP (mesmo 4xx) prova que a porta está acessível. Um tempo limite (timeout) significa um problema de firewall ou de DNS do seu lado. ## Conectar no NexCMP {#connect-in-nexcmp} ### No assistente de configuração {#in-the-setup-wizard} O passo 2 do [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/) solicita os mesmos valores. **Test connection** lista as zonas e redes que a chave consegue ver; escolha a zona e a rede de convidados, um nome de exibição para a zona e o país, depois clique em **Save CloudStack**. O assistente rejeita uma rede que não esteja nessa zona ou que não seja visível para a chave. ![Passo 2 do assistente com a URL da API do CloudStack e as chaves preenchidas, e a zona e a rede escolhidas após Test connection](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Mais tarde, no console do administrador {#later-in-the-admin-console} 1. Abra **Infrastructure › Cloud provider › CloudStack** e escolha a aba **API connection**. 2. Preencha o cartão **Connection**: | Campo | Valor de exemplo | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | Chave de API (acesso de escrita) | `XXXX` (deixe em branco para manter a chave salva) | | Chave secreta | `XXXX` | | Chave de API SO / Chave secreta SO | opcional, da conta somente leitura | | ID da zona | o UUID da sua zona | ![A aba de conexão da API com um endpoint de exemplo e chaves mascaradas](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Clique em **Test connection** antes de salvar. Isso testa as chaves que você digitou, sem salvá-las: a chave de gravação com `listZones` e `listCapabilities`, e a chave somente leitura com `listSystemVms`. 4. Clique em **Save connection**. Mantenha **Enable CloudStack connection** ativado; desativá-lo faz o worker parar todos os jobs do CloudStack, sem perder dados. 5. Abra **Services › Virtual Machines › Policy › Provisioning** para definir a rede de convidados padrão, ofertas personalizadas e o par de chaves padrão para novas VMs. ![Política de VM, aba Provisioning, com o ID de rede padrão](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Abra **Infrastructure › Cloud provider › Sales IP pools** e, em **Configure sales ranges**, defina **Sellable IP range prefixes** (por exemplo `203.0.113.`) e **Excluded IP prefixes** se alguns endereços na zona nunca devem ser vendidos. Deixe o prefixo em branco para permitir todos os endereços livres. ![Pools de IP de vendas com o prefixo comercializável 203.0.113. definido](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### O que o NexCMP lê e escreve {#what-nexcmp-reads-and-writes} | Área | Leituras | Alterações | |---|---|---| | VMs | lista, estados, histórico de uso, endpoint do console | implantar, iniciar, parar, reiniciar, reinstalar, destruir, redimensionar, redefinir senha e chave SSH | | Discos e snapshots | volumes, snapshots de VM, backups | criar, anexar, desanexar, redimensionar, excluir, fazer snapshot, restaurar | | Rede | redes, roteadores, IPs públicos, firewall, encaminhamento de porta, regras de balanceador de carga | associar e liberar IPs públicos, NAT estático, firewall, encaminhamento de porta, regras de saída, redes e ACLs para Cloud Privado | | Catálogo | ofertas de serviço, disco e rede, templates, ISOs, tipos de SO | registrar e excluir templates e ISOs (Imagens), ofertas de serviço ao criar planos personalizados | | Kubernetes | versões suportadas, clusters, configuração | projetos, limites de recursos, redes, clusters (módulo Kubernetes) | | Chave somente leitura | hosts, clusters, pools de armazenamento, VMs de sistema, capacidade, faixas de IP VLAN | nenhuma | ### CPU e RAM em tempo real e largura de banda {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Uma VM em execução pode ser redimensionada sem reinicialização apenas quando o template permitir (escalabilidade dinâmica) e o convidado colocar novos CPUs e RAM online. O NexCMP ativa o Auto Scaling para templates cujo nome termine em `vN` com N igual a 6 ou mais, ou quando você definir manualmente no campo **vCPU/RAM hot-plug** do template. Consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/). - **Origem de largura de banda.** Com as configurações padrão, o NexCMP mede o tráfego a partir das estatísticas de VM do CloudStack (`listVirtualMachinesUsageHistory`, consultadas a cada 5 minutos e somadas por interface de rede da VM). Os números incluem o tráfego entre VMs, portanto podem ser um pouco maiores do que um roteador de borda contabilizaria. Mantenha a coleta de estatísticas de VM do CloudStack ativada; lacunas maiores do que a retenção de estatísticas são ignoradas. Consulte [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/). ## Verificar {#verify} 1. **Test connection** retorna "Write key: OK" com sua zona e a versão do CloudStack. 2. **Infrastructure › Cloud provider › Providers** mostra o provedor como ativo com um horário de teste recente. O painel de integridade do dashboard não exibe mais "CloudStack: not connected". 3. **Sales IP pools** lista endereços livres (atualiza cerca de uma vez por minuto). 4. Peça uma VM pequena no portal do cliente ou no console administrativo e verifique se ela chega ao estado Running, possui um IP público e se você consegue abrir o console. ## Limites e observações {#limits-and-notes} - Um cluster CloudStack pode ser conectado nesta versão do NexCMP. O diálogo **Add cloud provider** consegue testar as chaves de um segundo cluster, mas não pode salvá-lo. - Uma zona do CloudStack está anexada à zona padrão do NexCMP; um CloudStack com várias zonas tem escopo limitado à zona inserida, portanto VMs, IPs e redes de outras zonas são ignorados. - Excluir a rede de convidados no CloudStack faz com que todo novo provisionamento falhe. O console administrativo exibe um aviso em vermelho quando a rede desaparece. - As credenciais nunca saem do servidor. A API retorna apenas os últimos quatro caracteres. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | Chave ou segredo de API incorretos, chave de outro usuário ou problema de relógio no servidor do painel | Gere as chaves novamente com `cmk generate userkeys` e cole ambas. Verifique a hora do servidor do painel. | | Teste: `listZones: …` ou timeout | O servidor do painel não consegue alcançar a URL da API | Verifique o DNS, o firewall e o caminho exato `/client/api`. | | Assistente: "network not found in that zone for this API key" | A rede escolhida pertence a outra conta ou zona | Crie a rede na conta dedicada (consulte acima) e execute **Test connection** novamente. | | Assistente: "pick a zone and a network" | Teste não executado, ou nenhuma zona ou rede selecionada | Clique em **Test connection** e escolha ambas as listas. | | Banner "chave do CloudStack não configurada" | Nenhuma chave salva ainda ("Connect later") | Preencha o cartão Connection, **Save connection** e, em seguida, **Test connection**. | | Banner "CloudStack connection is OFF" | O botão **Enable CloudStack connection** está desativado | Ative-o e salve. | | Chave somente leitura: "unusable …" no teste | Permissão de função ausente ou conta incorreta | Verifique os seis comandos permitidos e se a conta está no domínio ROOT. | | "Zone public IP ranges not measured yet" ou "no public IP ranges declared" | Nenhuma chave somente leitura, ou a zona realmente não possui faixa pública | Adicione a chave somente leitura ou adicione um intervalo de IP público no CloudStack. | | "Pool vazio — aguarde 60 s para a sincronização do vmd" | A lista de IPs é atualizada pelo worker uma vez por minuto | Aguarde um minuto e recarregue. | | "sem IPs livres no intervalo 203.0.113." | Todos os endereços no prefixo comercializável estão em uso | Adicione endereços à zona, amplie o prefixo ou libere IPs não utilizados. | | "Falha ao buscar dados de rede (CloudStack não está respondendo ou chave sem permissões)" | A chave perdeu o acesso ou o CloudStack está fora do ar | Execute **Test connection**; verifique se a conta está ativada. | | "Rede de convidados NÃO existe" | A rede foi excluída no CloudStack | Crie a rede novamente e defina-a como padrão em Provisioning. | --- # Proxmox VE > **Onde no admin:** Infrastructure › Cloud provider › Providers (`/infra/providers`), depois a página do provedor (`/infra/providers/`) com as abas Overview, Clusters, VMs, Servers e Credentials. Os planos são definidos em Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## O que faz {#what-it-does} O NexCMP pode vender máquinas virtuais executadas em um ou mais clusters Proxmox VE, ao lado ou em vez do CloudStack. Uma VM é criada clonando um modelo de OS com clonagem completa, sendo configurada via cloud-init: tamanho, endereço IP de um pool definido por você, senha de root e chave SSH. Os clientes obtêm controle de energia, console, snapshots, reinstalação, redefinição de senha e métricas no portal. Eles nunca veem o cluster, o nó ou o nome da fonte. Use quando você já opera o Proxmox VE, ou para oferecer um segundo pool de VMs com preços diferentes. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Proxmox VE | PVE 9.x. A integração foi verificada na versão 9.2. Requer o conteúdo de armazenamento `import` e a opção de disco `import-from` (PVE 8.2 ou mais recente). | | Rede a partir do painel | HTTPS para a API do cluster, `https://:8006`. Sem caminho, nome de usuário ou consulta. O painel e o worker se conectam; o console do navegador é roteado via proxy pelo painel. | | Conta | Um usuário dedicado do PVE com um **token de API** e uma função personalizada com os privilégios listados abaixo. Nunca use `root@pam`. | | Armazenamento | Um armazenamento para discos de VM que suporte clones (por exemplo, `local-lvm`). Para o construtor de modelos integrado, o armazenamento chamado `local` com os tipos de conteúdo `import` e `snippets`. | | Rede | Uma bridge do Linux (por exemplo, `vmbr0`) que alcance a rede onde os IPs dos clientes residem. Use uma bridge ciente de VLAN se você inserir uma tag de VLAN. | | IPs | Um bloco IPv4 (/16 a /30) roteado para essa bridge, com um gateway. O NexCMP atribui os endereços por conta própria; o Proxmox não possui gerenciamento de IP. | | Templates | Uma VM de modelo cloud-init por SO, em cada nó para o qual você implantar, com o agente de convidado QEMU. | | Zone | Uma zona existente para anexar o cluster. Consulte [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). | | Depende de | Nothing. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Execute os comandos como root em qualquer nó do cluster. ### 1. Criar uma função, um usuário e um token de API com privilégios mínimos {#_1-create-a-least-privilege-role-user-and-api-token} 1. Crie a função. A lista de privilégios é exatamente a utilizada pelo NexCMP; ela não contém nada que edite usuários, definições de armazenamento ou o datacenter. ```bash pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use" ``` `Sys.AccessNetwork` é obrigatório para o download de imagens em nuvem. O PVE 9 não possui o privilégio `VM.Monitor`; não o adicione. 2. Crie o usuário e um token. `--privsep 1` significa que os direitos do token são a **intersecção** entre as permissões do usuário e as permissões do próprio token. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` O comando exibe o token **secret apenas uma vez** (um UUID). Copie-o agora. O ID do token é `nexcmp@pve!api`. 3. Conceda a função **tanto** ao usuário quanto ao token. Esta é a etapa que as pessoas esquecem: com a separação de privilégios, apenas o token recebe erros 403, como `Datastore.Audit`, se o usuário não tiver permissão. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. Teste-o a partir do servidor do painel: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` Um documento JSON com `version` significa que o token funciona. (`-k` serve apenas para esta verificação rápida; o NexCMP fixa o certificado por conta própria, veja abaixo.) ### 2. Verifique a bridge e o armazenamento {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - As VMs de clientes recebem `virtio` interfaces de rede na bridge informada no NexCMP. Se você definir uma VLAN, a bridge deve ter suporte a VLAN (VLAN-aware). - Coloque as VMs de clientes em uma bridge ou VLAN **separada do endereço de gerenciamento do nó**. Se compartilharem uma rede, o conjunto automático de IPs de gerenciamento do firewall do Proxmox abre as portas 22, 8006, 3128, 5900-5999 e 60000-60050 do nó para todas as VMs nessa rede. Se não puder separá-las, adicione uma regra DROP explícita para a sub-rede da VM nessas portas, acima da regra ACCEPT de gerenciamento. ### 3. Notas sobre armazenamento (LVM-thin) {#_3-storage-notes-lvm-thin} - Deixe o **zeroing** (zeragem) do thin-pool no padrão. Desativá-lo (`lvchange -Zn`) pode deixar dados antigos em blocos recém-alocados e corromper as tabelas de partições ou sistemas de arquivos de VMs clonadas. - Discos que reportam "write cache: disabled" podem clonar a apenas alguns MB/s. Verifique com `hdparm -W /dev/sdX` e ative o cache de escrita se o disco tiver proteção contra perda de energia. ### 4. Ative o conteúdo `import` (apenas para o construtor de templates integrado) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} O construtor integrado baixa a imagem de nuvem no armazenamento chamado `local` e cria o template a partir dela. Adicione `import` (e `snippets`) à lista de conteúdos desse armazenamento. Mantenha os tipos que você já usa; `--content` substitui a lista inteira: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### 5. Construir um template de SO a partir de uma imagem de nuvem {#_5-build-an-os-template-from-a-cloud-image} Um template é uma VM cloud-init que o NexCMP clona. Cada um é registrado sob uma **OS key** curta como `ubuntu-24.04` com o id da VM correspondente. Crie um template por SO **em cada nó que receberá VMs**, pois o clone é executado no nó escolhido. **Opção A, recomendada: construa você mesmo.** As imagens de nuvem padrão de Ubuntu e Debian não contêm o guest agent e não permitem login como root, e o NexCMP define a senha de root por meio do cloud-init. Prepare a imagem primeiro: ```bash apt install -y libguestfs-tools wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img virt-customize -a noble.qcow2 --install qemu-guest-agent \ --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \ --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n' ``` Em seguida, crie a VM de template (o ID 9000 é um exemplo; mantenha os IDs de template abaixo do valor `vmid from`, padrão 1000): ```bash qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \ --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0 qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1 qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0 qm template 9000 ``` **Opção B: o construtor integrado.** O card **Create OS template from cloud image** na aba Clusters (veja abaixo) baixa uma imagem qcow2, cria o template e o registra. Ele cria a VM com o cloud-init e a flag do guest agent, mas não altera o conteúdo interno da imagem. Use-o apenas com uma imagem que já permita login como root e execute o guest agent, ou quando você também fornecer um trecho de vendor-data do cloud-init. O guest agent é necessário para **Reset password** e para exibir o endereço IP da VM. ### 6. Conhecer a impressão digital do certificado (opcional) {#_6-know-the-certificate-fingerprint-optional} O NexCMP confia no cluster fixando a impressão digital SHA-256 do seu certificado TLS, portanto, um certificado autoassinado é aceitável. Para ver o valor que o NexCMP vai fixar: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Infrastructure › Cloud provider › Providers** e clique em **Add cloud provider**. Escolha **Proxmox VE** e preencha: | Campo | Valor de exemplo | |---|---| | Name | `Proxmox cluster 1` | | Endpoint | `https://192.0.2.10:8006` | | Token id | `nexcmp@pve!api` | | Token secret | `XXXX` (o UUID exibido na etapa 1) | | Slug | `pve-1` (a-z, 0-9, hífen, 2-32 caracteres) | | Default node | `pve1` (vazio: o nó online com mais RAM livre) | | Armazenamento | `local-lvm` | | Bridge | `vmbr0` | ![Add cloud provider dialog com o Proxmox VE selecionado e valores de exemplo de endpoint, token e armazenamento](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. Clique em **Save & open provider** e informe um motivo quando solicitado. O token é criptografado antes de ser armazenado. 3. Na aba **Overview**, clique em **Test connection**. O primeiro teste bem-sucedido **fixa a impressão digital TLS do cluster**; a partir daí, qualquer certificado diferente será recusado. 4. Abra a aba **Clusters**. O card **Node · storage · bridge** lista o que a API enxerga; o card **Cluster configuration** contém as configurações: | Campo | Significado | |---|---| | Default node | Nó usado para novas VMs. Vazio significa o nó online com mais RAM livre. | | Storage, Bridge, VLAN | Armazenamento de disco, bridge de placa de rede e tag VLAN opcional (0 significa nenhuma). | | CPU type | `host` por padrão. Use `x86-64-v2-AES` quando os nós tiverem gerações de CPU diferentes. | | vmid from | Primeiro ID de VM atribuído às VMs de clientes (padrão 1000). | | Storage ISO, Storage backup | Deixe em branco, a menos que os utilize; vazio significa que os recursos de ISO e backup não são oferecidos. | | Template OS | Um por linha, `os-key=vmid`, por exemplo `ubuntu-24.04=9000`. | | Pinned TLS fingerprint (SHA-256) | Preenchido pelo primeiro teste. Limpe-o e teste novamente após substituir o certificado do cluster. | ![Aba Clusters, card Cluster configuration com exemplo de nó, armazenamento, bridge e lista de templates de SO](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. Opcional: se você usou a Opção B acima, preencha **Create OS template from cloud image** (OS key `ubuntu-24.04`, vmid `9000`, nó `pve1`, a URL da imagem qcow2) e clique em **Create template**. O processo é executado em segundo plano por alguns minutos; o resultado fica no Audit log. ![Card Create OS template from cloud image com uma URL de exemplo de imagem do Ubuntu](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. Clique em **Add pool** em **Cluster IP pool** e crie o pool de onde as VMs obterão endereços IP: | Campo | Valor de exemplo | |---|---| | Name | `customers-1` | | CIDR | `198.51.100.0/24` | | Gateway | `198.51.100.1` (nunca atribuído a uma VM) | | DNS | `1.1.1.1,8.8.8.8` (1 a 4 endereços IPv4) | | Bridge, VLAN | `vmbr0`, `0` | | Already used IPs | um por linha, `ip note`, por exemplo `198.51.100.10 monitoring` | O NexCMP nunca atribui o endereço de rede, o endereço de broadcast, o gateway ou um endereço reservado. Pools do mesmo cluster não podem se sobrepor. Um pool só pode ser excluído quando nenhum de seus endereços estiver em uso. ![Diálogo de adição de pool de IP com um exemplo de /24 e gateway](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. Em **Attach cluster to zone**, escolha a zona e, opcionalmente, um nome de nó, depois clique em **Attach to zone**. O cluster ingressa na zona que já vende VMs, permitindo que uma zona tenha CloudStack e Proxmox juntos. A nova origem **não é vendida por padrão** e não altera o comportamento dos planos existentes. ![Card de anexar cluster à zona com uma zona existente selecionada](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. Abra **Services › Virtual Machines › Plans & pricing** e clique em **Add plan**. Em **Infrastructure source**, escolha o cluster Proxmox e, em seguida, defina CPU, RAM, disco e preço. Um plano do Proxmox não precisa de uma offering do CloudStack. Para vender a mesma configuração a partir de ambas as origens, use **Clone** em um plano e escolha a outra origem. O disco do plano deve ser pelo menos tão grande quanto o disco do template; o Proxmox não pode reduzir um disco. ### Importar uma VM já existente {#import-a-vm-that-already-exists} Abra a aba **Servers** para listar as VMs no cluster. **Import** atribui uma VM existente a uma conta de cliente sem custo: nada é cobrado por horas, tempo desligado ou tráfego. O cliente pode iniciar, desligar, reiniciar e abrir o console, mas não pode excluí-la; apenas um administrador pode. O NexCMP apenas lê do cluster durante a importação. - O cluster deve estar vinculado a uma zona **com o nome do nó** dessa VM (deixe o nó vazio e as importações relatarão que a região não está configurada). - Para tornar uma VM **protected** (parar, reiniciar, reinstalar, restaurar snapshot, destruir e alterar plano são recusados), importe-a pela linha de comando com `--protect`: ```bash sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect ``` ### O que é e o que não é suportado no Proxmox {#what-is-and-is-not-supported-on-proxmox} | Recurso | Proxmox VE | |---|---| | Criar, ligar/desligar/reiniciar, excluir | Sim | | Redimensionar CPU e RAM, expandir o disco | Sim, mas a VM é desligada, alterada e iniciada novamente (sem redimensionamento em tempo de execução) | | Snapshots | Sim, até 5 por VM: criar, listar, restaurar, excluir | | Reinstalar | Sim: a VM é reconstruída a partir do template e mantém seu ID, IP e configurações, com uma nova senha | | Redefinir senha | Sim, através do guest agent | | Console | Sim, um console de navegador com proxy pelo painel | | Métricas | Sim: CPU, memória, rede e disco | | Montagem de ISO, backups, firewall, IPv6, encaminhamento de porta, alteração de IP, volumes extras, Auto Scaling, DDoS Shield, VPC, medição de largura de banda | Não disponível. A página da VM do cliente oculta o que uma fonte não pode fazer. | ## Verificar {#verify} 1. **Test connection** exibe OK e o status do provedor está ativo. 2. **Clusters** lista seus nós como online, com o armazenamento e a bridge. 3. **Cluster IP pool** mostra as contagens de endereços livres, usados e reservados. 4. A chave do SO aparece sob os templates da zona em **Services › Virtual Machines › Template** após o cluster ser conectado. 5. Peça uma VM de teste de um plano que use o cluster. Ela deve obter um endereço do pool, uma senha de root e um console funcional; o pool mostra um endereço usado. ## Limites e observações {#limits-and-notes} ::: tip Zonas de fontes mistas Desde o NexCMP 1.4.0, a tabela de preços pública do Cloud Server também funciona quando o CloudStack e o Proxmox VE compartilham uma zona. Cada plano usa seu próprio **Infrastructure source**. Depois de anexar um cluster, confira a tabela de preços pública e faça um pedido de teste para cada fonte. ::: - Vários clusters Proxmox podem ser adicionados. Cada um é um provedor. - Uma zona oferece uma fonte padrão; um plano com sua própria **Infrastructure source** é implantado exatamente nesse cluster, desde que o cluster esteja ativo e na zona do plano. - Um cluster atrás da mesma zona que o CloudStack mantém seus planos legados no CloudStack. Teste um pedido de ponta a ponta antes do lançamento. - O token de API só pode ser substituído, nunca visualizado. Substitua-o na aba **Credentials**: crie o novo token no Proxmox primeiro, insira-o, execute **Test connection** e, em seguida, revoque o token antigo. - As ações Test, Sync e cluster-info são limitadas a seis chamadas por minuto por administrador. - O NexCMP cobra de seus clientes; o custo de hardware e licença do cluster é seu. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Test: "Key rejected (wrong access key / secret, or revoked)" ou HTTP 401/403 | ID de token ou segredo incorreto, ou a ACL foi concedida apenas ao token | Execute novamente os dois comandos `pveum acl modify` (usuário **e** token) e verifique se o id do token é `user@realm!tokenid`. | | Teste: "Could not connect to the provider" ou "Timed out" | Firewall, host ou porta incorretos | Verifique `https://host:8006` a partir do servidor do painel. | | Teste: "Invalid endpoint or not on the allowlist" | O endpoint possui um caminho, usuário, query ou não é HTTPS | Use exatamente `https://host:8006`. | | "o certificado TLS do cluster NÃO corresponde à impressão digital fixada (pinned fingerprint)" | O certificado do cluster foi substituído | Limpe **Pinned TLS fingerprint** na aba Clusters, salve e execute **Test connection** novamente. | | Slug rejeitado | Não é a-z, 0-9, hífen ou não tem entre 2 e 32 caracteres | Use algo como `pve-1`. | | "Formato do ID do token: user@realm!tokenid e o secret são obrigatórios" | ID do token ou segredo ausente | Insira ambos; o segredo é o UUID exibido quando o token foi criado. | | "Linha de template inválida: …" | Uma linha em **Template OS** não é `key=vmid` | Use letras, dígitos, `.`, `_`, `-` na chave e um vmid de pelo menos 100. | | "Chave do SO: a-z 0-9 . _ - e vmid ≥ 100" | Chave ou ID inválido em **Create template** | Corrija a chave do SO e use um vmid disponível. | | "vmid … already exists" ao criar um template | O vmid já está em uso | Escolha outro ID. | | "a URL aponta para um endereço interno" | A URL da imagem é um IP interno | Use uma URL pública; os nomes são resolvidos pelo Proxmox. | | A tarefa de template falha no download | O armazenamento `local` não possui conteúdo `import` | `pvesm set local --content …,import,snippets`, e tente novamente. Um nome de arquivo deve terminar em `.qcow2`, `.raw`, `.vmdk`, `.ova` ou `.ovf`. | | "cluster has no online nodes" ou "node … is not online" | O nó padrão está offline ou com o nome incorreto | Corrija **Default node** ou deixe-o em branco. | | "a imagem não pertence ao cluster" | O SO do plano não está em **Template OS** | Adicione a chave à lista e salve. | | A implantação aguarda e depois falha na clonagem | A VM de template não está no nó escolhido | Crie o template nesse nó ou defina **Default node** como o nó que o possui. | | O cliente não consegue fazer login como root | A imagem bloqueia o login como root | Recompile o template conforme a Opção A. | | A redefinição de senha não faz nada | Sem guest agent no sistema convidado | Instale e habilite o `qemu-guest-agent` no template. | | "Nome, CIDR e gateway são obrigatórios" | Campo de pool ausente | Preencha todos os três. | | Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" ou "cidr: network address must be …" | Pool sobreposto, gateway incorreto ou um CIDR que não está em um limite de rede | Use uma faixa livre, um gateway dentro dela e um CIDR escrito como o endereço de rede (por exemplo, `198.51.100.0/24`). | | Importação: "a região não está configurada" | O cluster está vinculado sem o nome do nó da VM | Vincule o cluster à zona com o nome do nó. | --- # Templates de OS e ISOs {#os-templates-and-isos} > **Onde no admin:** Services › Virtual Machines › Template (`/vm/templates`). Os templates do Proxmox são listados por cluster em Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## O que faz {#what-it-does} Um template é a imagem de sistema operacional da qual uma nova VM é iniciada. O NexCMP não armazena imagens por conta própria: ele lê o que o CloudStack reporta (templates prontos e em destaque) ou o que você lista para um cluster Proxmox, e permite escolher quais são vendidos, com um nome voltado ao cliente, ícone e usuário de login. Esta página mostra como preparar imagens que funcionam bem com o NexCMP: login por senha, redimensionamento dinâmico de CPU e RAM, arquivo swap e um disco raiz que cresce até o tamanho do plano. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Construtor de templates do CloudStack | Uma máquina Linux com `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` e cerca de 5 GB de disco livre. Não são necessários KVM nem root. Acesso à internet para instalações de pacotes (ou compile com `--offline`). | | Onde fica o construtor | Ele vem incluído em todas as versões em `/opt/nexcmp/releases//share/templates/` no servidor do painel. Você não precisa executá-lo lá: copie a pasta para qualquer máquina Linux. | | Servidor web | Qualquer servidor HTTP(S) que a VM de armazenamento secundário do CloudStack possa alcançar para publicar o arquivo `.qcow2` finalizado. Ele não precisa estar acessível a partir da Internet. | | CloudStack | Uma conta que possa registrar templates, e o ID da sua zona e de um tipo de OS correspondente. Consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/). | | Proxmox VE | VMs de template com cloud-init e o agente convidado QEMU, uma por OS e por nó. Consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). | | Depende de | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) ou [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) conectado primeiro. | ## Preparar a infraestrutura {#prepare-the-infrastructure} ### CloudStack: criar um template {#cloudstack-build-a-template} Imagens base suportadas (a imagem do fornecedor é baixada e seu checksum é verificado antes de qualquer alteração): | Imagem | `--distro` | Usuário de login | |---|---|---| | Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` | | Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` | | Debian 12 | `debian-12` | `debian` | | Rocky Linux 9 | `rocky-9` | `rocky` | Mais distribuições: adicione uma linha a `distros.conf` (URL da imagem, arquivo de checksum, família `deb` ou `rpm`). 1. Copie o construtor para uma máquina de compilação e execute-o: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` Adicione `--panel-url https://cloud.example.com` para incluir um agente opcional de monitoramento no primeiro boot que se registra com o seu painel (somente HTTPS). Sem ele, nenhum agente é adicionado. Outras opções: `--base ` para usar uma imagem que você baixou, `--offline` para ignorar instalações de pacotes. 2. O resultado é `out/ubuntu-24.04-v7.qcow2` e seu `.sha256`. A compilação termina executando `verify-image.sh`, que inspeciona a imagem finalizada como somente leitura e rejeita imagens defeituosas (ela é mantida como `.unverified`). Você pode executá-lo novamente a qualquer momento: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. O que o construtor insere na imagem: | Item | Motivo | |---|---| | `qemu-guest-agent` | O CloudStack pode consultar a VM sobre CPUs e IPs, e colocá-la em espera (quiesce) para snapshots. | | cloud-init com a fonte de dados do CloudStack, `set_passwords` em cada inicialização, login de senha por SSH | A senha gerada é obtida a partir do roteador virtual e **Reset password** funciona. | | Uma regra udev para CPU e RAM adicionadas a quente (hot-added) | vCPUs e RAM adicionadas a quente entram em atividade sozinhas, fazendo com que o dimensionamento em tempo real (live scaling) e o Auto Scaling funcionem. | | Um serviço de arquivo de troca (swap file) | Cria `/swapfile` do menor valor entre 50% da RAM e 4 GiB após o disco crescer. `touch /etc/cmp-swap.disabled` o desativa. | | cloud-init `growpart` e `resizefs` | O pequeno disco raiz cresce para o tamanho de disco do plano na primeira inicialização. | | machine-id vazio, sem chaves de host SSH | Cada VM obtém sua própria identidade. | ::: warning Nomeie o template como ` ` O NexCMP ativa o **Auto Scaling** para templates cujo nome termina em `vN` ou `vN.M` com **N de 6 ou mais** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). O construtor impõe isso para `--version`. Registre o template exatamente com o nome impresso. ::: 3. Publique o arquivo e registre-o no CloudStack. Use o SHA-256 impresso pelo build e registre somente após o arquivo ser totalmente gravado: ```bash cmk list ostypes keyword="Ubuntu 24.04" filter=id,description cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \ url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid= format=QCOW2 hypervisor=KVM \ ostypeid= passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \ requireshvm=true isextractable=false ispublic=true isfeatured=true \ checksum="{SHA-256}" \ details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault ``` - `passwordenabled=true` permite que o CloudStack gere a senha da VM. - `isdynamicallyscalable=true` permite o dimensionamento em tempo real (live scaling). - `host-passthrough` é necessário para as imagens atuais do Rocky e Alma inicializarem; `osdefault` mantém o controlador de disco portátil. 4. Aguarde o template atingir **Download Complete / Ready**. A imagem do fornecedor mantém seu tamanho virtual pequeno (cerca de 3.5 GiB para Ubuntu e Debian, 10 GiB para Rocky). Lembre-se de que o disco de um plano não pode ser menor do que o disco do template. ### Proxmox VE: criar um template {#proxmox-ve-make-a-template} Crie um template de VM cloud-init por SO em cada nó em que você fizer o deploy, com o agente de convidado instalado e o login de root ativado, e registre-o como `os-key=vmid`. Os comandos completos estão em [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). O construtor do CloudStack acima **não** é para o Proxmox: ele configura o cloud-init para a fonte de dados do CloudStack. ### ISOs {#isos} Os clientes montam suas próprias ISOs através do módulo **Images** (CloudStack) ou do módulo de Servidores Dedicados. Eles são separados dos templates de SO nesta página. Consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) e [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/). ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Services › Virtual Machines › Template**. Clique em **Sync now** ou aguarde até 15 minutos. A sincronização adiciona templates prontos e em destaque no CloudStack. ![A página Template listando templates sincronizados com seu estado pronto e coluna de hot-plug de CPU](https://nexcmp.com/pt/docs/images/infrastructure/templates-01-list.webp) 2. Clique em **Edit** em um novo template e defina o que os clientes veem: | Campo | Valor de exemplo | |---|---| | Nome de exibição para clientes | `Ubuntu 24.04 LTS` | | Família do SO | `ubuntu` (ícone e usuário padrão) | | Versão | `24.04` | | Nome de usuário para login | `ubuntu` (Windows: `Administrator`; outros: `root`) | | Ícone | URL da imagem, um caminho ou um nome | | Order | `10` | | Active | On | | Hot-plug de vCPU/RAM (escala em tempo real) | **Auto by name (v6 or later)**, **Yes** ou **No (needs a restart)** | ![Diálogo Edit template com um nome visível ao cliente, família do SO, usuário de login e a opção de hot-plug](https://nexcmp.com/pt/docs/images/infrastructure/templates-02-edit.webp) 3. Ative o template. Um template que o CloudStack não lista mais é ocultado automaticamente (e você é alertado no Telegram se configurado); ele nunca é excluído do NexCMP. ### Substituir um modelo por uma versão mais recente {#replace-a-template-with-a-newer-build} Use **More › Replace with new version** no modelo comercializado. Escolha o novo modelo pronto e atualmente desativado. A entrada comercializada passa a apontar para a nova compilação, mantendo o nome, a ordem e o ícone; a antiga é desativada como opção de retorno (para voltar, use **Replace** na nova entrada). As VMs em execução não são afetadas. Se a nova compilação pertencer a uma família de SO diferente, marque a confirmação primeiro. ## Verificar {#verify} 1. A linha mostra **ready** e, para compilações chamadas `vN` com N igual a 6 ou mais, **CPU hot-plug: supported**. 2. Implante uma VM de teste a partir do modelo e verifique dentro dela: - você pode fazer login com a senha exibida no portal; - `df -h /` exibe o tamanho do disco do plano; - após um redimensionamento dinâmico (**Change plan** sem reinicialização), `nproc` e `free -m` aumentam; - `swapon --show` lista `/swapfile` (discos com menos de swap mais 2 GiB livres são ignorados); - `systemctl is-active qemu-guest-agent` exibe `active`. 3. Se você integrou o agente, a VM aparecerá nos hosts monitorados do painel um minuto após a primeira inicialização. A VM precisa de um IP público próprio: o painel a reconhece pelo IP de origem público. ## Limites e observações {#limits-and-notes} - O construtor é exclusivo para Linux e compila imagens Linux. Outras imagens (por exemplo, Windows) podem ser registradas no CloudStack por outros meios; o NexCMP lista o que o CloudStack reporta. - Apenas o agente amd64 é distribuído; outras arquiteturas ignoram a instalação do agente. - A imagem é verificada com `guestfish`, mas nunca inicializada pelo construtor. Sempre implante uma VM de teste antes de disponibilizar uma nova imagem. - Ignore o agente em uma VM com `touch /etc/cmp-agent.disabled` antes da primeira inicialização. Remova-o mais tarde com `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent` e, em seguida, exclua o agente no console de administração. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `virt-customize` falha ao baixar pacotes | A máquina de compilação não tem rede de saída | Corrija o DNS ou o proxy nessa máquina ou compile com `--offline` em uma imagem base que já possua os pacotes. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | O kernel do host não pode ser lido pelo usuário atual (Ubuntu) | `sudo chmod +r /boot/vmlinuz*` ou execute a compilação como root. | | A soma de verificação difere ou a imagem do fornecedor não existe mais | Os fornecedores movem seus arquivos "latest" | Baixe a imagem você mesmo, verifique-a com o arquivo de soma de verificação do fornecedor e forneça-a com `--base`. | | Rocky: um XFS mais recente não pode ser montado | O kernel do host é muito antigo | Compile em uma máquina com um kernel recente. | | `--version must be v6 or higher` | O nome deve ser `vN` com N igual a 6 ou mais | Use `--version v7`. | | `--panel-url must be a plain https:// URL` | O agente é baixado e executado como root, portanto, HTTP simples é recusado | Use uma URL `https://` sem espaços, aspas ou string de consulta. | | O modelo permanece **not ready** | O CloudStack ainda não concluiu o download | Aguarde **Download Complete**, verifique se a VM de armazenamento secundário consegue alcançar a URL. | | A linha exibe **no-pass** | O modelo foi registrado sem `passwordenabled=true` | Registre-o novamente com essa flag. | | O hot-plug de CPU exibe **unsupported** | O nome não termina em `vN` (N igual a 6 ou mais) | Renomeie o modelo ou defina **vCPU/RAM hot-plug** como **Yes** em Edit se a imagem possuir a regra udev. | | "Empty template list" após a primeira conexão | A sincronização não foi executada | Clique em **Sync now** (requer o worker em execução) ou aguarde o ciclo de 15 minutos. | --- # Servidores dedicados (bare metal) {#dedicated-servers-bare-metal} > **Onde no admin:** Infrastructure › Bare Metal (Servers `/infra/baremetal`, IP Pools, Stock / iDRAC import, Operations, Templates, Customer ISOs, Safety). Planos e assinaturas: Services › Dedicated Server (`/dedicated`). Ative o módulo em System › Admin › License & updates (`/license`). ## O que faz {#what-it-does} O NexCMP gerencia servidores físicos **diretamente pelo iDRAC**, através da API Redfish. Os clientes alugam um servidor inteiro: eles o ligam e desligam, abrem um console no navegador, montam uma ISO ou instalam um sistema operacional a partir de um modelo, e visualizam o hardware e as métricas. Eles nunca veem o endereço, nome de usuário ou senha do iDRAC. Use para revender servidores dedicados dos seus próprios racks. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Hardware | Servidores Dell com **iDRAC 9** e a API Redfish. | | Rede de gerenciamento | **Você fornece.** O servidor do painel deve alcançar cada iDRAC em **HTTPS 443** (e a porta VNC do iDRAC, padrão **5901**, para o console), e cada iDRAC deve alcançar o servidor web de ISO abaixo. O endereço do iDRAC deve ser um **endereço IPv4 em uma faixa privada** (RFC 1918, um prefixo /16 ou menor) listado por você na configuração `dedicated_bmc_cidrs`. Nomes DNS e IPv6 são recusados. O NexCMP não cria essa rede e não pode testá-la para você. | | Conta do iDRAC | Uma conta com privilégio de **Administrator** em cada iDRAC. O NexCMP a utiliza para ler o servidor e enviar os poucos comandos permitidos (energia, mídia virtual, inicialização única, console). Ele nunca cria contas de iDRAC para seus clientes. | | Ferramentas no servidor do painel | `xorriso` e `genisoimage` (criam a ISO de instalação de cada servidor) e `novnc` (a página do console no navegador). Instale-os com `sudo apt-get install -y xorriso genisoimage novnc`, ou deixe o instalador fazer isso: execute-o com `--baremetal`, ou forneça a ele as opções do servidor de ISO; uma atualização também os instala quando o módulo Bare Metal já estiver ativo. Se algum estiver ausente, **Safety** o listará em um aviso vermelho, o **live ops** se recusará a ativar (erro `tools_missing`), e o console e a instalação do SO responderão que uma ferramenta está ausente em vez de falharem depois. | | Servidor web de ISOs | Um servidor **HTTP** simples na rede de gerenciamento que disponibiliza a pasta de ISOs do NexCMP para os iDRACs. Seu endereço é um endereço IPv4 privado e uma porta opcional, por exemplo `http://10.20.0.2:8080`, **sem um caminho**, armazenado em `dedicated_iso_base_url`. Ele deve suportar byte ranges. A pasta é gravada pelo worker do painel, portanto o servidor web normalmente roda no **próprio servidor do painel**, escutando em um endereço que esse servidor possui na rede de gerenciamento. O NexCMP inclui um site do nginx pronto e um comando de etapa única para isso (veja abaixo). | | Pastas de ISO | Uma pasta para arquivos ISO e, dentro dela, `pub` (o que os iDRACs leem) e `server` (ISOs de clientes). O comando de etapa única usa `/srv/nexcmp-iso`; sem ele, os padrões seguem a instalação (configurações `dedicated_iso_lib_dir`, `dedicated_iso_pub_dir`, `dedicated_iso_server_dir`). O worker do NexCMP deve ser capaz de **gravar** nelas. Ele roda com um sistema de arquivos somente leitura, exceto `/var/lib/nexcmp`, portanto uma pasta em outro local precisa de um drop-in do systemd (o comando de etapa única o instala). | | Endereço de retorno | `dedicated_callback_base`, um `https://` que o servidor em instalação pode alcançar e que aponta para o seu painel. | | Armazenamento | Disco livre para a biblioteca de ISOs e para ISOs fornecidas pelo cliente. | | Depende de | O módulo **Bare Metal**, uma zona e os pools de IP dos servidores. | ::: warning Valores de exemplo não são uma configuração Uma nova instalação contém valores de exemplo em `dedicated_bmc_cidrs`, `dedicated_iso_base_url` e `dedicated_callback_base` (uma rede de exemplo privada e `https://example.com`). Eles não são a sua rede. Enquanto qualquer um deles ainda for um valor de exemplo, as páginas do Bare Metal exibirão um aviso vermelho **Management network not configured**, a importação de um iDRAC falhará na verificação da allow-list e o switch de **live ops** se recusará a ativar (erro `config_placeholder`). Defina os três valores em **Infrastructure › Bare Metal › Safety › Management network connection** (veja abaixo). ::: ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. **Coloque cada iDRAC em uma rede de gerenciamento** que os clientes não possam alcançar e atribua a cada um um endereço IPv4 privado fixo. Verifique a API Redfish a partir do servidor do painel: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **Crie uma conta de administrador no iDRAC** para o NexCMP (interface web do iDRAC ou `racadm`). Use uma senha forte e exclusiva. Nunca reutilize a conta embutida do iDRAC. 3. **Publique a pasta ISO para os iDRACs - um comando.** No servidor do painel, como root, com o endereço que esse servidor possui na rede de gerenciamento e na rede iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` `--listen` deve ser um endereço deste servidor (IPv4 privado, porta 8080 se omitida). `--allow` lista a(s) rede(s) iDRAC (CIDRs privados, /16 ou menor, até 8, separados por vírgula); apenas elas podem fazer download, e o comando também as utiliza como `dedicated_bmc_cidrs` quando essa configuração ainda for o valor de exemplo. `--dir /path` escolhe outra pasta de ISO (padrão `/srv/nexcmp-iso`). O comando: - cria a pasta com `pub` e `server` dentro, pertencente ao usuário do serviço NexCMP; - cria o grupo `nexcmp-iso` e adiciona o usuário do nginx a ele, para que o nginx possa ler uma ISO enquanto um iDRAC a tiver montado e ninguém mais possa; - instala o site do nginx `nexcmp-iso` (mantido apenas se `nginx -t` o aceitar; o nginx é instalado se estiver ausente) e um drop-in do systemd `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` para a pasta, `SupplementaryGroups=nexcmp-iso`); - grava as configurações de ISO (`dedicated_iso_base_url`, as três pastas, o grupo) e reinicia o worker do NexCMP. Ele pode ser executado novamente com outros valores, e `sudo nexcmp dedicated-setup-iso --remove` remove o site do nginx e o drop-in (os arquivos ISO permanecem). Ele também pode ser executado no momento da instalação: adicione `--iso-listen`, `--iso-allow` (e `--iso-dir`) ao comando de instalação. O comando **não** cria a rede de gerenciamento e não entra em contato com nenhum iDRAC; se os valores estiverem incorretos, o endereço não estiver neste servidor ou a porta estiver em uso, ele é interrompido com uma mensagem antes de alterar qualquer coisa, e um site do nginx recusado por `nginx -t` não é mantido. 4. **O que o servidor web de ISO disponibiliza.** O site nginx responde a `GET` (e `HEAD`, com byte ranges) para `/pub/.iso` e nada mais: sem listagem de diretório, sem nenhum outro caminho sob a pasta (a biblioteca e `server/` não ficam acessíveis), nenhum outro método e apenas a partir das redes `--allow` (qualquer outra pessoa recebe 403). O NexCMP disponibiliza cada ISO que um iDRAC precisa ler como um arquivo ou link temporário em `pub`; o nginx só segue um link quando o link e seu destino possuem o mesmo proprietário (o usuário do serviço), de modo que links para arquivos do sistema são recusados. Faça o teste a partir de outro host na rede de gerenciamento: ```bash curl -I http://10.20.0.2:8080/ # 403 or 404, never a listing curl -I http://10.20.0.2:8080/pub/ # 403 or 404 ``` Um arquivo de teste em `pub` deve responder a uma requisição `Range` com 206. *Fazendo manualmente:* o site nginx e o drop-in são fornecidos como templates no pacote da release (`share/dedicated/nginx-iso.conf` e `share/dedicated/vmd-iso.conf` sob `/opt/nexcmp/releases//`). Copie-os, substitua os marcadores `__...__` (endereço de escuta, pasta, linhas allow, grupo) e mantenha as regras acima. 5. **Tenha as imagens do SO prontas.** Coloque ISOs de auto-instalação na pasta da biblioteca (consulte **Templates** abaixo). Os clientes também podem adicionar ISOs a partir de um link; elas são baixadas para o servidor, nunca fornecidas ao iDRAC como URL. ## Conectar no NexCMP {#connect-in-nexcmp} ### 1. Ative o módulo {#_1-turn-the-module-on} Em **System › Admin › License & updates**, ative o botão **Bare Metal**. A categoria **Bare Metal** aparece sob Infrastructure. Consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/). ### 2. Configurar a conexão da rede de gerenciamento {#_2-set-the-management-network-connection} Abra **Infrastructure › Bare Metal › Safety**. O card **Management network connection** contém os três valores que definem se tudo funcionará: | Campo | Configuração | O que inserir | |---|---|---| | iDRAC network (CIDR) | `dedicated_bmc_cidrs` | A(s) rede(s) privada(s) dos seus iDRACs, por exemplo `10.20.0.0/24`. Somente CIDRs privados, /16 ou menor, até 8, separados por vírgula. Apenas os iDRACs nessas faixas podem ser importados. | | Servidor ISO para os iDRACs | `dedicated_iso_base_url` | `http://[:port]`, sem caminho: o endereço do servidor web de ISO da seção anterior, por exemplo `http://10.20.0.2:8080`. O comando em etapa única preenche isso para você. | | Panel callback address | `dedicated_callback_base` | `https://`, sem caminho: o endereço que o servidor que está sendo instalado chama para relatar a conclusão. Ele deve ser acessível a partir da rede desse servidor. `example.com`, `localhost` e semelhantes são recusados. | O formulário valida o formato enquanto você digita e o servidor valida novamente ao salvar; um valor incorreto é recusado com o motivo, e o valor armazenado permanece inalterado. Um campo que ainda contém o valor de exemplo padrão traz o rótulo vermelho **Not configured**, e todas as páginas de Bare Metal mostram o aviso em vermelho **Management network not configured** até que os três sejam reais. As alterações são registradas no log de auditoria com a sua justificativa. Salvar o valor de exemplo novamente não conta como configuração, a menos que você mesmo o tenha digitado. ### 3. Verificar a trava de segurança (deixe-a fechada por enquanto) {#_3-check-the-safety-gate-leave-it-closed-for-now} Abra **Infrastructure › Bare Metal › Safety**. O **Live ops** é o switch global para todos os comandos de gravação enviados a um iDRAC (energia, mídia virtual, console e instalação de SO). Ele começa **desativado** e não pode ser ativado enquanto a conexão da rede de gerenciamento acima ainda contiver valores de exemplo (o switch responde `config_placeholder` e indica os campos). As gravações são recusadas na API e novamente dentro do worker, enquanto a leitura de status continua funcionando. Uma segunda trava, **ops_locked**, protege cada servidor: servidores recém-importados ficam sempre bloqueados, mesmo quando o live ops está ativado. ![A página de segurança com o Live ops desativado e a lista de ações bloqueadas](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. Importar servidores {#_4-import-servers} 1. Abra **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. Em **Add one server**, insira o endereço, a conta e a senha do iDRAC, depois clique em **Test connection**. O teste envia apenas comandos de leitura e não salva nada. | Campo | Valor de exemplo | |---|---| | Endereço do iDRAC (URL ou host) | `10.20.0.11` | | Conta | `nexcmp-admin` | | Senha | `XXXX` | | Rótulo | `rack1-01` (vazio: gerado) | | Atribuir um IP de um pool | opcional; escolha o pool de IPs de serviço do servidor | | Incluir na lista de vendas | desativado até que você esteja pronto | ![Importação de estoque e iDRAC com um endereço de exemplo e um teste bem-sucedido de leitura ](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-02-import-server.webp) 3. Clique em **Save to stock**. O NexCMP lê o modelo, CPU, RAM, discos, placas de rede e service tag do iDRAC. O servidor entra no estoque como **bloqueado**. 4. Para vários servidores, use **Bulk import**: um servidor por linha, campos separados por vírgula, ponto e vírgula ou Tab. O **Preview** verifica a lista de permissões, duplicatas do endereço do iDRAC ou da service tag, e lê o hardware (até quatro servidores por vez). ### 5. ISOs de clientes e o endereço web de ISO {#_5-customer-isos-and-the-iso-web-address} Abra **Infrastructure › Bare Metal › Customer ISOs**. - **HTTP address serving ISOs to iDRAC** é `dedicated_iso_base_url`, o mesmo valor do card Safety (editável em qualquer um dos locais). Insira o endereço na rede de gerenciamento do seu servidor web de ISO. - Os **Customer ISO limits** definem o tamanho de uma ISO, o armazenamento total de ISOs, o espaço livre mínimo, o tempo de retenção das ISOs (horas), o tempo máximo de download e o número de downloads simultâneos. ![Customer ISOs com o endereço HTTP para os iDRACs e os limites de ISO](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. Templates de SO {#_6-os-templates} Abra **Infrastructure › Bare Metal › Templates**. Ele lista as ISOs de autoinstalação encontradas na pasta da biblioteca. Clique em **Register** em um arquivo para preencher a família do SO, versão e conta (preenchidos automaticamente a partir do nome do arquivo), e então ative o modelo em **Enable**. Habilitar um modelo não inicia nada: cada instalação ainda passa pelo controle de segurança. **Unregister** apenas remove a linha do modelo, nunca o arquivo. ![Modelos de Bare Metal com uma ISO registrada e uma não registrada](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. Pools de IP {#_7-ip-pools} Abra **Infrastructure › Bare Metal › IP Pools** e adicione os intervalos IPv4 que os servidores recebem como endereços de serviço. Cada servidor obtém um endereço; **Assign an IP from a pool** na importação pega o próximo livre. Os endereços livres são contados por pool. ![Pools de IP de Bare Metal com intervalos de exemplo e contagens de livres](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. Planos e vendas {#_8-plans-and-sale} 1. Abra **Services › Dedicated Server › Plans & pricing**. Edite os quatro planos de exemplo (chamados `BM-40C-` na versão 1.6.1) ou crie os seus próprios: preço, ciclos e a taxa de configuração. **Em uma nova instalação, os preços são inseridos em dólares americanos, com centavos, e a carteira é cobrada exatamente nesse valor: nenhuma taxa de câmbio é necessária.** Uma instalação que já tinha planos precificados em dong vietnamita mantém os dongs e ainda precisa de uma taxa de câmbio em suas configurações (sem ela, os pedidos são recusados com `dedicated_fx_unavailable`). Os planos de exemplo começam com preço 0 e **desativados**: um plano à venda precisa de um preço superior a 0. Verifique cada plano em relação ao hardware que você realmente importar; o nome de um plano de exemplo não detecta nem altera o hardware de um servidor. 2. Abra o servidor (Infrastructure › Bare Metal › the server › **Sales**), **anexe o plano** e ative **Sellable**. 3. Ative as **live ops** (página de Segurança, com a confirmação digitada) e desbloqueie os servidores que deseja operar (a aba **Lock** do servidor, com um motivo que vai para o registro de auditoria). 4. Em **Services › Dedicated Server**, ative as vendas. Isso leva duas etapas: leia as consequências e digite `ENABLE SALES`. Até lá, os clientes não verão nenhuma página de pedido e não serão cobrados. ![Planos de Dedicated Server com a chave de vendas desativada](https://nexcmp.com/pt/docs/images/infrastructure/dedicated-06-plans.webp) ### O que os clientes podem fazer na página do servidor {#what-customers-can-do-on-their-server-page} A página do servidor de um cliente possui dezesseis abas em sete grupos (Overview, Control, Network, Hardware, Billing, Activity, Settings). O grupo **Billing** contém: - **Plan & renewal**: pague de 1 a 24 meses adiantados em uma única etapa; a nova data é calculada a partir da data de renovação atual e a carteira é cobrada uma vez. A renovação automática pode ser ativada ou desativada. - **Billing cycle**: escolha outro ciclo (por exemplo, trimestral); ele passa a valer a partir da **próxima** renovação, e nada é cobrado ou reembolsado agora. - **Change plan**: o cliente pode **solicitar** outro plano. Nada é cobrado pela solicitação. Você aprova ou rejeita em **Services › Dedicated Server › Plan changes**, depois de fazer o upgrade de hardware ou migrar o servidor. Um upgrade aprovado cobra a diferença pelo restante do período que o cliente já pagou; um downgrade não reembolsa nada e se aplica a partir do próximo período. - **Invoices**: todas as faturas daquele servidor (pedido, renovações, upgrades). Em **Plan changes**, ordene as solicitações por ID, data, status, planos ou servidor; a ordenação abrange todo o resultado no servidor. A coluna de ação permanece visível ao rolar horizontalmente em uma tela estreita. No topo de **Overview**, quatro blocos em tempo real mostram **CPU**, **RAM**, **Disk** e **Network**, com um pequeno gráfico das últimas 24 horas. CPU, RAM e Disk são porcentagens de uso da última consulta do iDRAC (Disk é atividade de I/O, não espaço livre); Network é a velocidade atual de entrada e saída mais o total do mês, obtidos do contador de tráfego. Um bloco exibe **—** e um motivo breve quando o servidor está desligado, o iDRAC não pode ser alcançado ou a máquina não informa esse valor; ele nunca exibe um 0 inventado. Essas leituras vêm do Dell iDRAC e, sem um contador de tráfego, o bloco Network permanece em **—**. Os blocos são atualizados a cada minuto enquanto a página estiver aberta, e um clique abre a aba **Hardware** ou **Bandwidth**. No **Overview**, o card **Access** exibe o nome de usuário e a senha do sistema operacional instalado, ocultos por padrão com os botões **Show** e **Copy**. Ele fica disponível após cada instalação, não apenas uma vez, e um novo proprietário do servidor nunca vê a senha de um proprietário anterior. Se a senha do SO for alterada dentro do servidor, o card ainda exibirá aquela definida no momento da instalação. A aba **Bandwidth** só aparece quando um contador de tráfego a alimenta (consulte Limites). Não há a aba **Subnet**: trazer seu próprio prefixo de IP para um servidor alugado não faz parte do NexCMP. ### O que os clientes podem e não podem fazer {#what-customers-can-and-cannot-do} | Os clientes podem | Nunca possível | |---|---| | Ver inventário, integridade, estado de energia e métricas | Ver o endereço, nome de usuário ou senha do iDRAC | | Ligar, desligamento gracioso, reiniciar, forçar desligamento, redefinir | Alterar contas do iDRAC ou configurações de rede do iDRAC | | Abrir um console do navegador (uma sessão por vez) | Alterar BIOS ou RAID, limpar logs, atualizar firmware, redefinir o iDRAC | | Montar uma ISO ou um link de ISO próprio, definir inicialização única, reinstalar o SO a partir de um modelo ativado | Executar chamadas Redfish brutas (as funções não existem no NexCMP) | O NexCMP não cria contas de iDRAC para os clientes: eles usam apenas os controles do portal, e o endereço e o login do iDRAC nunca são exibidos a eles. ## Verificar {#verify} 0. Em **Safety**, o card **Management network connection** não exibe nenhum aviso vermelho e as páginas de Bare Metal não exibem nenhum alerta vermelho. A partir de um host na rede de gerenciamento, `curl -I http:///` não lista arquivos. 1. **Test connection** no formulário de importação retorna o modelo, CPU, RAM e service tag. 2. O servidor aparece em **Servers** com seu hardware. Com as **live ops desativadas**, uma ação de energia é recusada com "Server control is temporarily disabled system-wide". 3. Após ativar as live ops e desbloquear um servidor de teste, desligue e ligue o servidor em **Operations** ou na página do servidor e abra o console. 4. Faça um pedido de teste com um plano de teste: o servidor é atribuído, o SO é instalado e a instalação termina com o servidor reportando-se ao painel. ## Limites e observações {#limits-and-notes} - Cada servidor físico tem no máximo uma assinatura ativa. - Um comando de gravação é enviado apenas quando **ambas** as live ops estão ativadas **e** o bloqueio do servidor está aberto. A verificação é repetida dentro do worker imediatamente antes de cada comando. - O estado **Installing** aguarda o novo SO responder na sua porta (SSH 22, Windows 3389, Proxmox 8006) antes que o pedido seja concluído; uma instalação tem um limite de tempo (`dedicated_install_timeout_min`, padrão de 150 minutos). - A largura de banda para servidores dedicados é contabilizada a partir de um agente contador de tráfego que não faz parte da instalação padrão. Sem ele, nada é registrado, o portal oculta a aba Bandwidth e a API relata `capabilities.bandwidth` como `false`. - As ações de administrador em uma locação (bloquear, desbloquear, cancelar com ou sem reembolso) são as mesmas ações unificadas de qualquer outro serviço, com reembolsos retornados ao saldo de onde foram pagos. - Os servidores não são revendidos entre revendedores: Dedicated é vendido apenas a partir do site principal. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O teste falha com um erro de endereço | O endereço não é um literal IPv4 em `dedicated_bmc_cidrs` (privado, /16 ou menor) ou a porta não é permitida | Use o endereço IPv4 do iDRAC e adicione sua rede em Safety › Management network connection (`dedicated_bmc_cidrs`). Nomes DNS e IPv6 são recusados. | | Aviso vermelho "Management network not configured", ou o switch de live ops responde `config_placeholder` | Um dos itens `dedicated_bmc_cidrs`, `dedicated_iso_base_url` ou `dedicated_callback_base` ainda contém o valor de exemplo padrão | Insira os valores reais em Safety › Management network connection. | | Um campo é recusado ao salvar | Formato incorreto (CIDR não privado ou mais amplo que /16, endereço de ISO diferente de `http://[:port]`, callback diferente de `https://`) ou um endereço de exemplo como `example.com` | Leia a mensagem abaixo do campo; o valor armazenado permanece inalterado. | | `nexcmp dedicated-setup-iso` para antes de alterar qualquer coisa | `--listen` não é um endereço deste servidor, a porta já está em uso ou um valor é inválido | Use o endereço que este servidor possui na rede de gerenciamento, outra porta, ou corrija o valor indicado na mensagem. | | "O certificado TLS do iDRAC difere do certificado fixado - as ações de polling e gravação foram interrompidas" | O certificado do iDRAC foi substituído (novo certificado, iDRAC substituído) | Abra o servidor, aba **Access**, compare as duas impressões digitais e, se a alteração for intencional, clique em **Repin certificate**. | | "O controle de servidores está temporariamente desativado em todo o sistema" | As operações ao vivo estão desativadas | Turn it on in **Safety**. | | "Este servidor está bloqueado para operações" | O bloqueio por servidor está fechado | Abra o bloqueio na aba **Lock** do servidor com um motivo. | | "Outra operação ainda está em execução neste servidor" | Uma operação anterior não foi concluída | Wait; check **Operations**. | | "Outra sessão de console já está aberta neste servidor" | Um console por vez | Feche a outra sessão. | | "O controlador do servidor está temporariamente indisponível" | O iDRAC não responde | Verifique a rede de gerenciamento e o iDRAC. | | A montagem de uma ISO falha com um erro 403 ou 404 do iDRAC | O servidor web não consegue ler o arquivo ou o endereço base está incorreto | Verifique as permissões do servidor web de ISO e o **HTTP address serving ISOs to iDRAC**. | | "Este plano está esgotado no local selecionado" | Nenhum servidor vendível com esse plano na zona | Vincule o plano a um servidor e ative **Sellable**. | | "Nenhum endereço IPv4 disponível para atribuição no momento" | O pool de IPs está vazio | Adicione endereços ao pool. | | "A instalação automática do SO não está disponível no momento" | Install prerequisites missing | Verifique se um modelo está ativado e se as pastas ISO têm permissão de gravação; os clientes ainda podem instalar via ISO e console. | | Installation stalls | O servidor de instalação não consegue alcançar o endereço de retorno de chamada | Verifique `dedicated_callback_base` e se a rede do servidor consegue alcançar seu painel via HTTPS. | --- # Nós de VPN e proxy IPv6 {#vpn-and-ipv6-proxy-nodes} > **Onde encontrar no admin:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`), VPN IP pools (`/vpn/pool`), IPv6 Proxy nodes (`/vpn/proxy6/nodes`). Os serviços em si ficam em Services › VPN e Services › IPv6 Proxy. Ambos os módulos são ativados em System › Admin › License & updates. ## O que faz {#what-it-does} O NexCMP vende acesso a VPN e proxy com saída por **endereços IP que você possui**, em servidores operados por você. Existem dois tipos de nó: - **Nó de VPN.** Um pequeno programa em Go, `cmp-agent`, é executado no seu host Linux. Ele descobre os endereços IPv4 públicos no host, abre um listener SOCKS5, HTTP e UDP em cada endereço vendido e envia o tráfego a partir do **mesmo IP** ao qual o cliente se conectou (saída pelo mesmo IP). Ele envia relatórios ao painel a cada poucos segundos. - **Nó de proxy IPv6.** Um serviço de proxy que fornece aos clientes endereços de um prefixo IPv6 roteado para o host. O painel o instala para você via SSH. Use-os para revender endereços IP limpos nos países onde você possui servidores. ## Requisitos {#requirements} ### Nó de VPN {#vpn-node} | Item | Requisito | |---|---| | Sistema operacional | Uma distribuição Linux com systemd e kernel 4.15 ou mais recente (suporte a free-bind de IPv6). O binário do agente fornecido é apenas para **x86_64** (amd64). | | Privilégios | root, para a instalação. O serviço mantém apenas `CAP_NET_ADMIN`, `CAP_NET_RAW` e `CAP_DAC_READ_SEARCH`. | | Ferramentas | `curl` ou `wget` e `sha256sum` (o instalador recusa-se a continuar sem verificar o arquivo). | | Endereços públicos | Endereços IPv4 públicos atribuídos a uma interface do host (um `/32` cada) **ou** um prefixo roteado para o host que você adiciona como uma sub-rede extra (IPv4 /16 a /32, IPv6 /48 a /128). Intervalos privados, CGNAT e de documentação são ignorados. | | Rede, entrada | Os clientes se conectam a cada IP público vendido nas **portas 65001-65535** (TCP para SOCKS5 e HTTP, UDP para associação UDP). Cada endpoint usa um conjunto de três portas consecutivas. | | Rede, saída | HTTPS (443) para o domínio do seu painel. O agente também consulta seu próprio país em `ip-api.com` (HTTP) e `ipinfo.io` (HTTPS), com limite de 3.5 segundos. | | E-mail | Conexões de saída para a porta 25 são sempre bloqueadas; não há configuração para liberá-la. | | Docker, VPN e interfaces virtuais | Interfaces chamadas `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*` e `tailscale*` não fornecem endereços. | | Depende de | O módulo **VPN**, uma zona (criada automaticamente a partir do país do host) e o painel NexCMP acessível via HTTPS. | ### Nó de proxy IPv6 {#ipv6-proxy-node} | Item | Requisito | |---|---| | Sistema operacional | Linux com systemd em **x86_64**. Os comandos `systemctl`, `nft`, `ip`, `ss`, `sysctl` e `useradd` devem existir; caso contrário, a instalação para e indica o comando ausente. | | Acesso para a instalação | Um endereço IPv4 público (endereços privados, de loopback e CGNAT são recusados), a porta SSH, uma conta com privilégios de root ou `sudo` e a respectiva **senha**. A senha é usada apenas para a instalação e não é armazenada. | | Portas livres | **80, 443 e todas as portas acima de 60000** devem estar livres. O instalador nunca interrompe ou altera serviços que já estejam em execução; ele relata as portas ocupadas e para. | | IPv6 | Um prefixo público entre **/32 e /64** dentro de `2000::/3` que o host pode usar como origem para tráfego de saída, entregue como **roteado** para o host ou **on-link** com proxy NDP (consulte abaixo). | | Rede | Os clientes se conectam ao IPv4 do nó na porta 80 (proxy HTTP), porta 443 (SOCKS5) e portas 60001-65535 (uma porta por IP estático). O nó não possui certificado, portanto não há proxy HTTPS. O tráfego sai apenas via IPv6 e apenas para destinos que possuem um endereço IPv6. O nó obtém sua configuração a partir do painel via HTTPS. | | Software de nó no servidor do painel | O daemon do nó e seu script de rede vêm no pacote de release do NexCMP. O painel os copia de sua pasta de instalação (`/opt/nexcmp/releases//bin`, ou `/opt/nexcmp/bin` em um build customizado) para cada nó durante a instalação. O servidor do painel também precisa de `sshpass` e de um cliente SSH; o instalador adiciona `sshpass`, e em um servidor instalado antes da 1.4.2 você o adiciona com `sudo apt-get install -y sshpass`. | | Depende de | O módulo **IPv6 Proxy** e a URL do painel para a qual os nós retornam chamadas (**IPv6 Proxy › Settings › Panel URL for nodes**, padrão `https://`). | ## Preparar a infraestrutura {#prepare-the-infrastructure} ### Nó de VPN {#vpn-node-1} 1. **Provisione o host** com um Linux compatível e os endereços IPv4 públicos que você deseja vender, configurados na interface de rede ou roteados para o host. 2. **Se você vende um bloco roteado**, planeje inseri-lo como uma **Extra subnet** ao adicionar o nó. O agente instala uma rota `local dev lo` para que o host aceite tráfego para cada endereço no bloco e, em seguida, relata os endereços que encontrar. O agente também lê a tabela de roteamento real do host e nunca vende ou captura um endereço de **gateway**: se o bloco contiver o next-hop de uma das rotas do host (por exemplo, o endereço de roteador de um bloco on-link), o agente instala rotas `local` apenas para as partes do bloco ao redor dele, relata o gateway ao painel, e o painel mantém esse endereço fora do pool e fora de qualquer alocação. Ele remove as rotas instaladas quando a sub-rede extra é alterada ou quando o agente para. 3. **Abra o firewall.** Permita TCP e UDP de entrada **65001-65535** nos endereços públicos e HTTPS de saída para o painel. 4. **Opcional: contadores de bytes por IP.** A contabilização de Conntrack (`net.netfilter.nf_conntrack_acct = 1`) permite que a função de monitoramento conte bytes por IP. O painel pode ativá-la enviando um comando `acct` ao agente, que também grava `/etc/sysctl.d/99-cmp-agent.conf`. A função de VPN em si não precisa disso. 5. **Verifique o painel a partir do nó:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### Nó de proxy IPv6 {#ipv6-proxy-node-1} Um prefixo IPv6 chega ao nó de duas maneiras. O instalador testa ambas com conexões de saída reais e mantém o que funcionar. | Tipo | O que significa | O que você configura | |---|---|---| | **Roteado** | Seu upstream roteia um prefixo (por exemplo, um /48 ou /56) **para o próprio endereço do nó**. Pacotes de saída podem usar qualquer endereço no prefixo como origem, e as respostas retornam ao nó. | Solicite ao seu provedor um prefixo roteado cujo próximo salto seja o nó. Nada mais no nó: o serviço de proxy usa sockets transparentes, uma tabela de roteamento de política fixa e `nft`. | | **On-link** | O /64 fica na mesma LAN que o nó. As respostas funcionam apenas se o nó atender à descoberta de vizinhos para cada endereço em uso (**NDP proxy**). | O serviço define, apenas nessa interface, `net.ipv6.conf..accept_ra=2`, `forwarding=1` e `proxy_ndp=1`, memoriza os valores antigos, restaura-os ao parar e bloqueia o encaminhamento dos endereços do pool para que o nó não se torne um roteador para o pool. | Como a verificação funciona: o nó tenta uma conexão TCP com um endereço IPv6 público (porta 443) a partir de um endereço aleatório do prefixo candidato, em até 6 segundos. Os candidatos são endereços globais em interfaces com prefixo /64 ou mais curto, além de rotas do tipo `local`, `unreachable` ou `blackhole` entre /16 e /64. Um prefixo mais curto que /64 é aceito como **roteado** se um /64 aleatório dentro dele funcionar. ::: warning Não use o mesmo prefixo duas vezes Um prefixo não pode sobrepor o prefixo de outro nó e não pode ser mais amplo do que um prefixo que já pertença ao próprio pool IPv6 do painel. Um /64 **dentro** do pool do painel é permitido. Sobreposições são relatadas como "assign range … (node …)" no resultado da instalação, e o prefixo é ignorado. ::: Restrições que o nó aplica por conta própria: os clientes não podem enviar e-mails (portas 25, 465, 587, 2525) a partir dos endereços do pool, e o tráfego IPv4 próprio do daemon é limitado a respostas, ao painel e ao DNS. ## Conectar no NexCMP {#connect-in-nexcmp} ### Nó de VPN {#vpn-node-2} 1. Em **System › Admin › License & updates**, ative o botão **VPN**. Consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/). ![O cartão do módulo com os botões VPN e IPv6 Proxy](https://nexcmp.com/pt/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. Abra **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. Você tem duas maneiras de adicionar um nó. **a. Instalar via SSH.** Clique em **+ Add server (SSH)** e preencha: | Campo | Valor de exemplo | |---|---| | Endereço IPv4 do servidor | `192.0.2.50` | | Porta SSH | `22` | | Usuário SSH | `root` | | Senha SSH | `XXXX` | | Nome de exibição | `node-ny-1` (vazio: nomeado com base no IP) | | Função do servidor | External VPN / Proxy Node | | Atribuição de zona | Automático por GeoIP (criar/atribuir zona) ou uma zona existente | | Sub-rede extra (opcional) | vazio para escanear automaticamente as interfaces, ou um bloco roteado como `203.0.113.0/24` | | Habilitar para venda após a instalação | ativado para marcar cada endereço detectado como vendível | Clique em **Connect & install**. O painel se conecta via SSH, executa o instalador de linha única no nó com um tíquete de uso único e exibe o nome do nó, a localização GeoIP e os intervalos detectados. ![Diálogo Add Node via SSH com um exemplo de endereço de servidor e função](https://nexcmp.com/pt/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **b. Instalação manual.** Clique em **Generate manual install token**. O comando aparece **uma única vez**; copie-o e execute-o no nó: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` A instalação por token registra a máquina apenas para monitoramento: por segurança, o painel não permite que uma máquina com o token compartilhado atribua a si mesma a função VPN (adicionar `--roles vpn` ao comando não tem efeito). Depois que a máquina aparecer na lista, abra-a e adicione a função **VPN** manualmente. A instalação via SSH (opção a) atribui ao nó a função VPN desde o início. Um novo token cancela o anterior; hosts já registrados continuam funcionando porque utilizam sua própria chave. ![Diálogo do comando de instalação mostrando o comando de token de uso único](https://nexcmp.com/pt/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) O que o instalador faz: ele baixa `cmp-agent-linux-amd64` do seu painel, **verifica seu SHA-256**, instala-o em `/usr/local/bin/cmp-agent`, registra-se com o token, grava `/etc/cmp-agent/agent.json` e inicia o serviço systemd `cmp-agent`. Para removê-lo: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. Após o primeiro heartbeat, o nó aparece na lista. Seu país é detectado por GeoIP (primeiro pela consulta do próprio nó, depois pelo banco de dados do painel); uma **zone** para esse país é criada e tornada pública caso não exista, e os endereços encontrados no host tornam-se intervalos do pool. 4. Abra **Infrastructure › VPN & Proxy nodes › VPN IP pools** para ver os intervalos, sua zona e nó, e para alterar a zona, o nó ou a opção **Sellable** de cada intervalo. **Enable range** permite que novos pedidos usem seus IPs livres; **Disable range** apenas interrompe novas alocações, os IPs já alocados continuam funcionando. ![Pools de IPs de VPN com intervalos relatados por um nó](https://nexcmp.com/pt/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. Abra **Services › VPN**, defina a tabela de preços e ative as vendas. A chave **Sell VPN** em **Subscriptions** é a mesma chave do módulo VPN em License & updates. 6. **Opcional: renomeie o serviço.** Em **Settings › Branding**, **VPN service display name** altera como o serviço de VPN é exibido no menu do cliente, na página de pedidos, na página de detalhes e na lista de deploy (por exemplo, `IPv4 Proxy`, `Datacenter Proxy` ou `Static Residential Proxy`; até 40 caracteres; vazio mantém `VPN`). Isso altera apenas os rótulos: rotas, dados e a API não mudam. ### Nó de proxy IPv6 {#ipv6-proxy-node-2} 1. Em **System › Admin › License & updates**, ative **IPv6 Proxy**. 2. Abra **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** e clique em **Add node (SSH)**. Insira o endereço IPv4 do nó, porta SSH, usuário, senha, um nome opcional e um **Reason** (ele vai para o log de auditoria), depois clique em **Install**. ![Diálogo de adição de nó IPv6 com exemplo de endereço e motivo](https://nexcmp.com/pt/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. Em seguida, o painel executa em ordem: verifica a máquina e as portas, copia o daemon, o script de rede, a unidade de serviço e um arquivo de ambiente específico do nó (um token de nó e uma chave de assinatura de senha), executa a **probe** de prefixos utilizáveis, registra os prefixos no pool, inicia o serviço e aguarda até 90 segundos pelo primeiro relatório. O **Install log** mostra cada etapa. 4. Um novo nó cria sua zona no estado **off** (a partir do GeoIP do IPv4 do nó). Ative a zona em **Infrastructure › Datacenter › Zone** para que os clientes possam escolhê-la. 5. Defina um limite total de **Mbps cap** por nó (de 10 a 100000 por direção). Em **Services › IPv6 Proxy**, defina a lista de preços e ative as vendas. 6. Verifique **IPv6 Proxy › Settings › Panel URL for nodes**. Os nós chamam esse endereço (`https://host`, sem caminho) para obter sua configuração e enviar relatórios. Vazio significa `https://`. Deve ser um host cujo endereço aponte diretamente para o painel, para que o próprio IPv4 do nó o alcance inalterado. ::: tip Cronograma de rotação Os clientes podem definir um intervalo de rotação automática de 30 a 600 segundos. No NexCMP, o painel executa essa programação (e a limpeza horária dos logs de conexão); os nós recebem um novo endereço em cerca de 5 segundos. ::: ### Como um nó se comunica {#how-a-node-reports} | | Nó de VPN (`cmp-agent`) | Nó de proxy IPv6 | |---|---|---| | Registro | Ticket ou token de uso único via HTTPS, depois chave própria | Instalação SSH única, depois token de nó | | Heartbeat | A cada **5 segundos** (10 s para agente apenas de monitoramento); o painel pode definir de 3 a 300 s. Após uma falha, aguarda em incrementos de 5 s até 60 s | O nó envia um relatório a cada 60 segundos aproximadamente e busca a configuração | | Exibido como online | Um heartbeat nos últimos **60 segundos** | **alive** nos últimos **120 segundos**, caso contrário **missed heartbeat** | | Alteração de configuração | Aplicada no próximo heartbeat | Aplicada em cerca de 5 segundos | | Atualizações | O painel pode enviar um comando `upgrade` com a nova versão, URL e SHA-256 | Reinstalar a partir da linha do nó | ### Franquia de dados em um nó VPN {#data-allowance-on-a-vpn-node} A partir do NexCMP **1.5.1**, o agente do nó VPN envia o tráfego transportado a cada heartbeat, e o painel o adiciona ao uso do plano no período atual. O mesmo valor é exibido para o cliente (abas Overview e Bandwidth) e para você (VPN › Subscriptions, coluna Used e na linha do nó). - **Corte.** Quando um plano atinge o limite de GB do período, o painel para de enviar os endpoints desse plano ao agente, de modo que novas conexões são recusadas e as abertas são encerradas. O corte ocorre no intervalo de um heartbeat, portanto o plano pode ultrapassar ligeiramente o limite. Planos com nível Unlimited nunca sofrem cortes. - **Reativação.** O plano volta a ser atendido no intervalo de um heartbeat após o cliente comprar mais largura de banda ou quando o próximo período começar. - **Não medido.** Um nó cujo agente não enviou dados de uso (por exemplo, um agente mais antigo) é exibido como **Not measured**, e seus planos nunca são suspensos devido a GB. - **Atualize o agente.** Use o agente **1.5.1** nos nós. Agentes mais antigos ainda são contabilizados, mas podem perder os bytes de um heartbeat que falhou, de um endpoint interrompido ou de uma reinicialização, e não fecham conexões abertas quando um plano é cortado. Atualize a partir da linha do nó (Reinstall) ou com o comando `upgrade`. - A contagem é feita sobre o payload que passa pelo proxy, portanto é ligeiramente menor (cerca de 1 %) do que os bytes na rede. ### Add-ons de VPN descontinuados {#retired-vpn-add-ons} High IP Reputation, High Concurrency e High Priority Network não são mais oferecidos em novos pedidos. Assinaturas existentes mantêm suas seleções de add-ons, mas os valores de renovação têm as taxas descontinuadas removidas. Não há reembolso de períodos já pagos. O ajuste utiliza o preço de catálogo atual do add-on; se você alterou esse preço ou excluiu o add-on, revise o valor de renovação da assinatura antes da próxima renovação. ## Verificar {#verify} 1. A linha do nó está online. Para um nó VPN, **Agents & external nodes** exibe sua zona, país, função e faixas detectadas. 2. **VPN IP pools** lista as faixas com IPs livres; a página de detalhes da zona exibe a infraestrutura de VPN. 3. Contrate um plano de teste de VPN ou proxy. O cliente recebe um endpoint `ip:port`, um nome de usuário e uma senha; conecte-se por meio deles e verifique se o IP público visível é o IP do nó (por exemplo, `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. Em um nó IPv6, execute no host: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## Limites e observações {#limits-and-notes} - Os hosts Windows podem executar o agente de monitoramento, mas não a função de VPN. - Franquia de dados (GB por período) de um plano VPN: a partir do NexCMP 1.5.1, o painel soma o tráfego informado pelo agente do nó VPN e corta os proxies do plano quando os GB do período se esgotam (consulte "Franquia de dados em um nó VPN" abaixo). Planos IPv6 Proxy não possuem franquia de GB; eles limitam a velocidade em Mbps por plano. - Os endereços IPv4 de um plano VPN não rotacionam. Um cliente relata um IP na lista de bloqueio; você ou o revendedor aprovam a substituição na mesma zona. Apenas o IPv6 Proxy rotaciona. - No máximo 64 faixas são relatadas por pulso de batimento cardíaco. - Um conjunto de endpoints VPN usa três portas por IP vendido. Com as portas 65001-65535, cada IP atende a um número limitado de endpoints (178 conjuntos de portas); o painel ignora conjuntos que já foram usados anteriormente. - A exclusão de um nó de proxy IPv6 só é permitida quando nenhum plano possui um IP nele. Isso remove os intervalos e o token do nó; o software no host não é desinstalado. - É possível revender um intervalo que também abriga suas próprias VMs: a VPN usa apenas as portas 65001-65535, portanto, compartilha o IP com outros serviços. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "falha no registro (token inválido ou servidor inacessível)" | Token incorreto ou já utilizado, ou o painel está inacessível | Gere um novo token ou tente a instalação via SSH novamente. | | "divergência na assinatura do arquivo - STOP" | O agente baixado difere do SHA-256 publicado | Verifique a pasta `/dl/` do painel e certifique-se de que nada reescreva o download no caminho. | | "este instalador é apenas para Linux" / "a arquitetura … ainda não é suportada" | Windows ou uma arquitetura diferente de x86_64 (a versão inclui o agente apenas para x86_64) | Use um host Linux x86_64. | | O nó nunca aparece | O nó não consegue alcançar o painel via HTTPS | Teste `curl https:///install.sh` a partir do nó; verifique o DNS e o firewall. | | O nó aparece com o país incorreto | As consultas de país falharam, portanto, o banco de dados de endereços do painel foi usado | Permita o acesso de saída para `ip-api.com` e `ipinfo.io` ou escolha a zona explicitamente no formulário SSH. | | Nenhum intervalo detectado | Nenhum IPv4 público em uma interface não virtual | Adicione um endereço público ou insira o bloco roteado como **Extra subnet**. | | A VPN funciona, mas o tráfego sai por outro IP | O IP vendido não está atribuído ou roteado para o host | Certifique-se de que o IP está em uma interface ou coberto por `local … dev lo`. | | "o servidor do painel não possui o sshpass" | O host do painel não consegue fazer login nos nós com senha | Execute `sudo apt-get install -y sshpass openssh-client` no servidor do painel e instale o nó novamente. | | "não encontrado no pacote instalado" ao instalar um nó IPv6 | O painel é anterior a 1.4.2, ou uma build personalizada sem os arquivos do nó | Atualize o NexCMP para 1.4.2 ou posterior; para uma build personalizada, use `build.sh`, que agora empacota `brandy-proxy6d` e `brandy-proxy6-net`. | | "SSH: …" no início de uma instalação IPv6 ou "SSH to internal/loopback addresses is not allowed" | Porta, usuário ou senha incorretos, SSH bloqueado ou o endereço é privado | Use o IPv4 público do nó e verifique o acesso manualmente com `ssh -p PORT USER@IP`. | | "arquitetura … não suportada (apenas x86_64)" | O nó não é x86_64 | Use um host x86_64. | | "comando ausente no node: …" | `nft`, `ip`, `ss`, `sysctl`, `systemctl` ou `useradd` não instalado | Instale os pacotes e execute a instalação novamente. | | "portas em uso por outro serviço no node: … — 80, 443, 60001-65535 devem estar livres" | A porta 80, 443 ou uma porta acima de 60000 está ocupada | Mude o outro serviço de lugar; o instalador não o interrompe. | | "nenhum prefixo IPv6 com acesso à Internet encontrado a partir do node (falha na sonda de saída real)" | Nenhum prefixo roteado, proxy NDP impossível ou sem IPv6 de saída | Verifique se o prefixo está roteado para o nó, se a interface tem conectividade IPv6 e se nada filtra o tráfego de saída. | | "todas as faixas detectadas já pertencem a outro node" | O prefixo já está sendo usado por outro nó | Remova-o do outro nó ou escolha outro prefixo. | | A instalação termina com "no initial report received from node" | O serviço iniciou, mas não alcançou o painel em 90 segundos | Verifique a URL do painel fornecida aos nós e o caminho HTTPS do nó até ela; consulte o **Install log**. | | A linha do nó exibe **missed heartbeat** | Sem relatório por 120 segundos | Verifique o serviço no nó, seu relógio e seu caminho para o painel. | | Os clientes não veem nenhuma localização IPv6 | A zona está desativada | Ative a zona em **Zone**. | --- # AI Models {#ai-models} > **Onde encontrar no admin:** System › Admin › License & updates (`/license`) para ativar o módulo. Depois, Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) e Audit (`/ai/audit`). Os clientes usam AI › API no portal do cliente. ## O que faz {#what-it-does} O AI Models é uma camada de gateway e faturamento no seu próprio painel. Seus clientes obtêm chaves de API e chamam **um único endpoint no seu domínio**, no formato compatível com OpenAI ou Anthropic. Você escolhe quais modelos oferecer e o custo de cada um por 1 milhão de tokens. O NexCMP verifica a chave, os limites e a carteira, envia a requisição para um provedor adicionado por você, contabiliza os tokens e debita da carteira pré-paga do cliente. **Você fornece as fontes de modelos.** O NexCMP não inclui nenhum provedor, modelo, endereço padrão ou preço. Ele não fornece modelos, chaves de API, tokens nem contas de provedor. ::: warning Verifique primeiro os termos das suas fontes Muitos provedores de modelos restringem a revenda ou a cessão de acesso a terceiros. Use apenas fontes que você tenha autorização para usar e revender, e siga seus respectivos termos e a legislação aplicável a você. Esta página não constitui assessoria jurídica. ::: O AI Models é um produto separado do **AI Chat and AI Agent** (módulo **AI**, veja [provedores de IA](https://nexcmp.com/pt/docs/ai/ai-providers/)). Os dois módulos não dependem um do outro. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Módulo | **AI Models** ativado em License & updates, Modules. Vem desativado por padrão. | | Provedores | Uma ou mais fontes de modelos que você tenha autorização para revender, cada uma com uma API compatível com OpenAI (`/chat/completions`), uma API compatível com Anthropic (`/messages`) ou ambas. Cada uma precisa de uma URL base e de uma chave de API. | | Rede | O painel deve alcançar cada provedor via **HTTPS na porta 443** em um nome de domínio público. Um provedor em um host interno, em outra porta ou em HTTP simples deve ser listado em **Allowed internal hosts** (configuração `ai_endpoint_allow`). | | Clientes | Uma conta de cliente com endereço de e-mail verificado e saldo na carteira. | | Hardware | Nenhum. O NexCMP apenas encaminha requisições: sem GPU e sem arquivos de modelo. | ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Obtenha uma chave de API de cada fonte de modelos que você usará e anote sua URL base (por exemplo, `https://api.example.com/v1`). 2. Verifique os termos da fonte quanto à revenda. 3. Se uma fonte rodar dentro da sua rede, defina seu endereço, por exemplo `http://10.0.0.5:8000/v1`. Você listará `10.0.0.5:8000` em **Allowed internal hosts**. ## Conectar no NexCMP {#connect-in-nexcmp} ### 1. Ative o módulo {#_1-turn-the-module-on} Abra **System › Admin › License & updates**, localize o card **Module** e ative **AI Models**. O menu é recarregado e **Services › AI Models** é exibido. Enquanto o módulo estiver desativado, as páginas do cliente, as páginas do admin e o gateway respondem com `404 module_disabled`, e nenhum provedor é contatado. ![O card Module com a opção AI Models ativada](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. Adicionar um provedor {#_2-add-a-provider} 1. Abra **AI Models › Providers** e selecione **Add provider**. 2. Insira um **slug** curto, um **nome** (visível apenas para você), o **tipo** (OpenAI-compatible, Anthropic-compatible ou Both), a **URL base** e a **API key**, e uma **prioridade** (um número menor é tentado primeiro). 3. Salve. A chave é armazenada criptografada e apenas os últimos quatro caracteres são exibidos depois. Uma chave só pode ser inserida a partir de uma sessão de administrador conectada. Use **Both** apenas para um gateway que realmente atenda a ambos os formatos. O NexCMP **não** faz conversão entre os dois formatos: um modelo servido por um provedor compatível com OpenAI é acessado em `/ai/v1/chat/completions`, e um servido por um provedor compatível com Anthropic em `/ai/v1/messages`. ![A página Providers listando três provedores de exemplo com tipo, prioridade e status](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. Testar a conexão {#_3-test-the-connection} Selecione **Test connection** no provedor. O NexCMP lê `GET /models` com a chave e informa **ok**, ou o motivo da falha: **auth** (chave incorreta), **blocked**, **billing** ou **unreachable**. Os testes são limitados a 6 por minuto. ### 4. Sincronizar os modelos {#_4-sync-the-models} Selecione **Sync models**. O NexCMP lê a lista de modelos do provedor e adiciona cada novo modelo **desativado e sem preço**. Modelos que o provedor não lista mais são sinalizados. Enquanto o módulo estiver ativo, a lista também é sincronizada automaticamente a cada 6 horas (configuração `ai_models_sync_hours`). ### 5. Definir preços e ativar os modelos {#_5-set-prices-and-switch-models-on} 1. Abra **AI Models › Models**. 2. Para cada modelo que você deseja vender, defina o **preço de venda** em dólares americanos por 1 milhão de tokens: **input**, **cached input** e **output**. 3. Opcionalmente, insira seu **custo** para o modelo. Com isso, **Profit** exibirá a receita versus o custo por dia e por modelo, e um preço de venda abaixo do seu custo mais a margem mínima (configuração `ai_min_margin_pct`, 10 por padrão) será recusado, a menos que você confirme um prejuízo deliberado. **Set price from cost** usa um markup definido por você; não há markup padrão. 4. Ative o modelo. Um modelo sem preço de venda não pode ser ativado. Um preço de entrada em cache deixado em zero é cobrado pelo preço de entrada. ![A página Models com preços de venda de entrada, entrada em cache e saída e as chaves liga/desliga](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-03-models.webp) ### 6. Rotas e failover {#_6-routes-and-failover} Em um modelo, **Routes** lista os provedores que o atendem, em ordem. Adicione um segundo provedor como fallback, defina a ordem e, opcionalmente, informe um nome de modelo diferente para cada provedor (o nome enviado ao provedor pode diferir do nome que você publica). Quando um provedor retorna um erro de servidor, um erro de autorização ou faturamento, modelo ausente ou limite de taxa, o NexCMP tenta a próxima rota. Se uma leitura expirar após a solicitação ser enviada, ela **não** será enviada para outro provedor, para que você não pague duas vezes. Cada provedor é limitado a `ai_provider_rpm` solicitações por minuto (50 por padrão). Se um provedor continuar retornando erros de autorização ou faturamento, o NexCMP alertará o administrador no Telegram quando o Telegram estiver configurado. ### 7. Ativar a chave de vendas {#_7-open-the-sale-switch} No topo das páginas de AI Models, a **chave de vendas** (configuração `feature_ai_models`) fica desativada por padrão. Enquanto estiver desativada, os clientes veem que o serviço ainda não está aberto e a tabela pública de preços o informa como não disponível. Verifique se pelo menos um modelo está ativado, possui um preço de venda e uma rota com chave, e então ative-a. ### O que os clientes podem fazer {#what-customers-can-do} No portal do cliente, **AI › API**: - **Models** mostra seus modelos e preços, a URL base e exemplos de comandos prontos. - **API Keys**: crie, renomeie, rotacione, desative e exclua chaves. O segredo é exibido apenas uma vez; somente o hash é armazenado. Por chave: modelos permitidos, expiração, orçamento flexível (alerta) e orçamento rígido (bloqueia com `402`), solicitações por minuto e tokens por minuto. - **Usage** por modelo, chave e dia, com exportação. - **Logs**: registros de solicitações filtráveis (horário, chave, modelo, tokens, custo, status, latência). **Prompts e respostas não são gravados.** Os logs são mantidos por 90 dias por padrão (`ai_log_retention_days`). - **Settings**: orçamento da conta e o endereço de e-mail para alertas de orçamento. - **Playground**: converse com um modelo, compare modelos lado a lado e copie o código correspondente. ![A página de API Keys do cliente com as URLs base para ambos os formatos de API](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-04-keys.webp) Os endpoints do gateway, no seu domínio: ```text POST /ai/v1/chat/completions OpenAI-compatible POST /ai/v1/messages Anthropic-compatible (also /ai/v1/messages/count_tokens) GET /ai/v1/models model list GET /ai/v1/models/pricing public price list, no key needed ``` ### Carteira e faturamento {#wallet-and-billing} O uso de IA é cobrado na mesma carteira pré-paga que todos os outros serviços. Antes de uma solicitação ir para um provedor, o NexCMP reserva o valor máximo que a solicitação poderia custar; se o saldo estiver abaixo do mínimo (`ai_min_balance_cents`, 20 centavos por padrão) ou for insuficiente, a solicitação será recusada com `402 insufficient_balance` e **nenhum provedor será chamado**. O uso é consolidado por conta e lançado no extrato da carteira a cada hora, com uma varredura a cada 5 minutos; o uso ainda não liquidado já é subtraído do saldo visualizado pelo gateway. Revendedores podem vender AI Models em seu próprio domínio: sua margem ou desconto se aplica ao seu preço de venda e sua carteira de atacado é cobrada pelo preço de atacado. Uma chave de IA por revendedor, ativada por padrão, controla quem pode vender. ## Verificar {#verify} 1. Após a etapa 3, **Test connection** exibe **ok** e a contagem de modelos. 2. Após a etapa 4, os novos modelos são listados, desativados, sem preço. 3. Como um cliente com saldo na carteira, crie uma chave e faça uma chamada para o gateway: ```bash curl https://your-domain/ai/v1/chat/completions \ -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \ -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}' ``` Uma resposta `200` traz a resposta do modelo. **Usage** mostra a solicitação, e **Profit** a exibe se você tiver inserido um custo. 4. Com a carteira zerada, a mesma chamada retorna `402 insufficient_balance`. ## Limites e observações {#limits-and-notes} - O módulo não possui nenhum provedor, modelo ou preço integrado, e nenhuma tabela de preços é lida de um provedor. - Ferramentas executadas do lado do provedor e cobradas por chamada, como busca na web, são rejeitadas porque não podem ser tarifadas. Apenas uma pequena lista de parâmetros de solicitação é repassada. - O uso de tokens é obtido da resposta do provedor; se a resposta não contiver nenhum, o NexCMP faz uma estimativa e marca o registro como estimado. - Erros de um provedor são limpos antes de chegarem ao cliente (nomes, hosts, endereços e o nome do modelo do provedor são removidos). Os clientes nunca veem qual provedor atendeu a uma requisição. - Os clientes acessam o gateway por meio do domínio do seu painel, portanto o TLS desse domínio deve estar funcionando. - O NexCMP não oferece acordo de nível de serviço, fine-tuning ou hospedagem de GPU para este módulo. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa e solução | |---|---| | Todas as páginas de AI Models e o gateway respondem `404 module_disabled` | O módulo está desativado. Ative **AI Models** em License & updates, Modules. | | A adição de um provedor falha com `endpoint_host_not_allowed`, `endpoint_must_be_https` ou `invalid_endpoint_port` | A URL base deve ser HTTPS na porta 443 em um nome de domínio público. Para um host interno, outra porta ou HTTP simples, liste `host:port` em **Allowed internal hosts**. | | `blocked_endpoint` | O endereço é um IP ou o nome resolve para um endereço privado. Liste-o em **Allowed internal hosts** se for isso o que você deseja. | | **Test connection** exibe `auth` | A chave está incorreta ou não possui acesso. Insira a chave novamente. | | Não é possível ativar um modelo (`no_price`) | Defina um preço de venda primeiro. | | Os clientes recebem `503 ai_unavailable` | A opção de venda está desativada ou a opção de AI da revenda está desativada. | | Os clientes recebem `503 upstream_unavailable` | Nenhuma rota ativada com chave atende a esse modelo no formato solicitado. Verifique as rotas do modelo e o tipo de provedor. | | Os clientes recebem `402 insufficient_balance` | O saldo da carteira está abaixo do mínimo ou é insuficiente para a requisição. Solicite que o cliente faça uma recarga. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **Onde encontrar no admin:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). Contas: Services › Object Storage › S3 accounts (`/s3`). Preços: Services › Object Storage › PAYG pricing (`/s3/policy`). Ative o módulo em System › Admin › License & updates. ## O que faz {#what-it-does} Os clientes criam contas S3 no portal e obtêm chaves de acesso. O NexCMP cria e exclui os usuários correspondentes no **seu Ceph RADOS Gateway (RGW)** por meio da API Admin Ops do RGW, lê o uso para faturamento e cobra conforme o uso: armazenamento acima de uma franquia gratuita por GB por mês (cobrado por hora) e tráfego de download por GB. Os uploads são gratuitos. Use-o quando você opera um cluster Ceph com RGW e deseja revender armazenamento de objetos. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Ceph | Um cluster com pelo menos um daemon RGW, com a **Admin Ops API** ativada (a padrão `rgw_enable_apis` inclui `admin`). | | Usuário admin | Um usuário RGW para o NexCMP com as permissões listadas abaixo. Não use um usuário que possua dados de clientes. | | Endpoints | O endpoint S3 que os clientes usam e o endpoint Admin Ops. Ambos são gravados como `https://host` **sem caminho, porta 443 apenas**, e devem resolver para um endereço **público**: endereços de loopback, link-local, multicast, privados e unique-local são recusados. | | Certificado | Um certificado válido para o host do endpoint. | | Log de uso | O log de uso do RGW ativado (`rgw_enable_usage_log = true`), para que a API de uso possa relatar o tráfego. | | Zone | Uma master zone com o serviço **Object Storage (S3)** marcado. Veja [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). | | Armazenamento | Capacidade no Ceph para as cotas que você vende. | | Depende de | O módulo **Object Storage**. O tráfego de download também conta para [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/). | ## Preparar a infraestrutura {#prepare-the-infrastructure} Em um nó de administração do Ceph: 1. Crie o usuário administrador e dê a ele as capacidades Admin Ops necessárias: ```bash radosgw-admin user create --uid=nexcmp-admin --display-name="NexCMP admin" radosgw-admin caps add --uid=nexcmp-admin --caps="users=*;buckets=*;usage=read;metadata=read" radosgw-admin user info --uid=nexcmp-admin ``` Copie `access_key` e `secret_key` da saída. Eles são a **Admin access key** e a **Admin secret key** no NexCMP. 2. Ative o log de uso e reinicie os gateways: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. Coloque os gateways atrás de HTTPS na porta 443 (um proxy reverso ou o TLS próprio do RGW), publique o nome DNS e teste a partir do servidor do painel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` Você deve receber uma resposta XML do S3 (HTTP 200 ou 403), e não um timeout. ## Conectar no NexCMP {#connect-in-nexcmp} 1. **Atribua o serviço S3 a uma zone.** Abra **Infrastructure › Datacenter › Zone**, edite a zone e marque **Object Storage (S3)**. Apenas master zones com o serviço S3 aparecem no formulário do backend. 2. Abra **Infrastructure › Cloud provider › Ceph S3 (RGW)** e clique em **Add backend**: | Campo | Valor de exemplo | |---|---| | Backend name | `Ceph RGW 1` | | Zone | a zone da etapa 1 | | RGW Admin Ops endpoint | `https://s3.example.com` | | Endpoint S3 do cliente | `https://s3.example.com` | | Região de assinatura do S3 | `default` | | Chave de acesso do admin | `XXXX` | | Chave secreta do admin | `XXXX` | | Active | on | | Habilitar vendas (exige teste de conexão prévio) | **off** por enquanto | | Motivo da alteração | `initial setup` | ![Diálogo de S3 do backend com exemplos de endpoints, região e chaves mascaradas](https://nexcmp.com/pt/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. Clique em **OK** (salvar) e depois em **Check** na linha. O NexCMP chama a API Admin Ops com a chave de admin. **Ceph connection successful** e a tag **Verified** indicam que está funcionando. 4. Clique em **Edit**, ative **Enable sales** e salve. O NexCMP recusa-se a abrir as vendas até que uma verificação seja bem-sucedida. 5. Abra **Services › Object Storage › PAYG pricing** e defina os preços: | Campo | Significado | |---|---| | Armazenamento além da camada gratuita (VND/GB/mês) | Preço de armazenamento; cobrado por hora como o preço mensal dividido por 730. | | Download (VND/GB) | Preço para tráfego de saída. | | Upload (VND/GB) | Sempre 0. | | Camada gratuita com VM em execução (GB) | Fixo em 100 GB por conta enquanto o cliente tiver pelo menos uma VM em execução, compartilhado entre suas contas de S3 por tamanho. | | Limite de dívida (VND) | Quanto de uso não pago é permitido. | | Limite de faturamento (VND) | O uso é consolidado em uma fatura assim que ultrapassa este valor. | | Saldo mín. para criar S3 (VND) | Saldo necessário na carteira para criar uma conta. | | Máx. de contas S3 por cliente, cota técnica padrão (GB) | Limites para novas contas. | ![Formulário de preços PAYG do S3](https://nexcmp.com/pt/docs/images/infrastructure/s3-04-pricing.webp) Os preços do S3 são inseridos em VND. Eles são convertidos para exibição e cobrança na carteira à taxa de câmbio vigente; consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). ## Verificar {#verify} 1. **Check** retorna "Ceph connection successful". 2. Como cliente (ou com uma conta de teste), crie uma conta S3. No Ceph, `radosgw-admin user list` exibe um novo usuário, e **S3 accounts** o lista. 3. Crie um bucket com qualquer cliente S3 usando as chaves do cliente contra o endpoint do cliente. Faça o upload de um arquivo. 4. Após o próximo ciclo de faturamento da hora, **S3 accounts** exibe o uso. ## Limites e observações {#limits-and-notes} - Um backend que já possui contas vinculadas mantém sua **zona, endpoint e região**; para alterá-los, crie um novo backend. - Uma zona pode ter seu próprio backend; contas e backends ficam permanentemente vinculados a uma zona. - A camada gratuita e a gratuidade de uploads são regras fixas, não opções. - As chaves são armazenadas criptografadas; o console exibe apenas um campo para "deixar em branco para manter a chave atual". Um par de chaves é sempre inserido em conjunto. - As chaves secretas dos clientes são exibidas uma vez na criação e nunca mais. Uma chave perdida é substituída por rotação. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Endpoint requires HTTPS" | O endpoint usa HTTP simples | Publique HTTPS na porta 443. | | "Porta do endpoint não permitida" | Uma porta diferente de 443 | Use a porta HTTPS padrão. | | "Endereço do endpoint não permitido" | O nome resolve para um endereço privado, de loopback, link-local ou unique-local | Use um endereço público. | | "O endpoint deve conter apenas protocolo e host" | A URL possui um caminho, consulta ou informações de usuário | Use apenas `https://host`. | | "Falha ao resolver o endpoint" | O DNS não resolve a partir do servidor do painel | Corrija o DNS. | | "Failed to connect to Ceph" | Erro de firewall ou TLS | Teste com `curl` a partir do servidor do painel. | | "Ceph returned HTTP 403 AccessDenied" | Chaves incorretas ou permissões ausentes | Verifique as chaves e execute `radosgw-admin caps add` novamente. | | "Invalid Ceph response" | O endpoint não é uma RGW Admin Ops API | Aponte para o RGW e não para uma página web. | | "O teste de conexão deve ser bem-sucedido antes de habilitar as vendas" | Você ativou as vendas antes de um **Check** bem-sucedido | Execute **Check** e, em seguida, ative as vendas. | | "Todas as novas chaves para o endpoint são obrigatórias" | Endpoint alterado sem ambas as chaves | Insira a chave de acesso e a chave secreta juntas. | | "O backend já possui recursos vinculados; crie um novo backend para alterar a zona ou o endpoint" | Existem contas neste backend | Crie um novo backend. | | "Selecione a zona master com serviço S3" | A zona não é uma zona mestre ou não possui o serviço S3 | Marque **Object Storage (S3)** na zona. | | "Invalid region" | A região contém caracteres diferentes de letras, dígitos, `-` e `_` | Use `default` ou o nome do seu zonegroup do RGW. | | "Resumo de uso do Ceph ausente; não faturado" | Log de uso desativado | Ative `rgw_enable_usage_log`. | --- # Kubernetes and Private Cloud {#kubernetes-and-private-cloud} > **Onde no admin:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`), depois Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). Ative ambos os módulos em System › Admin › License & updates. ## O que faz {#what-it-does} - **Kubernetes.** Os clientes criam clusters Kubernetes gerenciados no seu CloudStack com o CloudStack Kubernetes Service (CKS). O plano de controle é gratuito; os clientes pagam pelos nós de **worker**. O NexCMP cria uma rede separada e um IP público para cada cluster, mantendo os clusters de cada cliente isolados. - **Private Cloud.** Os clientes obtêm uma rede privada (uma CloudStack VPC) com um roteador, sub-redes (tiers), regras de firewall (network ACLs) e máquinas virtuais dentro dela. É vendido por **plano de largura de banda** com velocidade dedicada e ilimitada (por exemplo, 50, 100, 500 Mbps, 1 e 3 Gbps). Cada cliente pode ter uma VPC por padrão. Ambos são baseados em [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) e usam sua API através da mesma conexão. ## Requisitos {#requirements} ### Kubernetes {#kubernetes} | Item | Requisito | |---|---| | CloudStack | 4.23 (testado). O CKS deve estar **enabled** (`cloud.kubernetes.service.enabled = true`). | | Conta | Uma conta **Domain Admin** no domínio dedicado, para que o NexCMP possa criar um projeto CloudStack para cada cliente e os limites de recursos dentro dele. Consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | A configuração global do CloudStack deve apontar para a sua API de gerenciamento, acessível a partir das VMs do cluster. O NexCMP exibe o valor e o resultado de uma verificação de endpoint. | | Versões | Pelo menos uma entrada de versão suportada do Kubernetes com sua ISO de binários, no estado **Enabled**. Versões que ultrapassaram o fim de vida útil não podem ser colocadas à venda. | | Oferta de plano de controle | Uma oferta de serviço gratuita com **exatamente 2 vCPU, 2048 MB RAM e um limite de CPU** (`limitcpuuse = true`), visível para a conta. O servidor rejeita qualquer outra coisa com `cp_offering_invalid`. | | Rede | Uma oferta de rede isolada compatível com CKS que esteja habilitada. | | IPs | Endereços IPv4 públicos gratuitos no intervalo comercializável; cada cluster usa um. | | Capacidade | Cada cluster custa de 2 a 4 GB de RAM para o plano de controle e uma pequena VM de roteador. Fique de olho nas abas de capacidade. | ### Private Cloud {#private-cloud} | Item | Requisito | |---|---| | CloudStack | 4.23 (testado) com VPC habilitado. | | Oferta de VPC | Uma oferta de VPC. Uma oferta de pilha dupla (dual-stack) também fornece a cada camada um IPv6 /64. | | Ofertas de rede de camadas | **Uma oferta de rede por plano de largura de banda**, criada para VPC, com a **taxa de rede** (Mbps) igual à do plano, mais uma oferta **bloqueada** de **1 Mbps** que é aplicada quando uma VPC é bloqueada por falta de pagamento. | | Conta | A conta dedicada (Domain Admin recomendado). As redes VPC ficam na conta, não nos projetos. | | IPs | Endereços IPv4 públicos gratuitos (cada VPC usa um para NAT de origem). | | Espaço de endereçamento | Cada VPC recebe um /16 de `10.128.0.0/9`. Mantenha esse intervalo sem uso em suas próprias redes. | | Depende de | CloudStack conectado; o módulo **Private Cloud**. | ## Preparar a infraestrutura {#prepare-the-infrastructure} ### Kubernetes: habilitar CKS e adicionar versões {#kubernetes-enable-cks-and-add-versions} 1. Habilite o serviço e defina o endpoint, em seguida reinicie o servidor de gerenciamento: ```bash cmk update configuration name=cloud.kubernetes.service.enabled value=true cmk update configuration name=endpoint.url value=https://cloudstack.example.com/client/api sudo systemctl restart cloudstack-management ``` `endpoint.url` é chamado de volta pelo controlador do cluster, portanto, deve ser um endereço que as VMs do cluster possam alcançar. 2. Compile uma ISO de binários do Kubernetes para a versão que você deseja vender, com o script `create-kubernetes-binaries-iso.sh` da árvore de código-fonte do CloudStack, hospede-a em um servidor web e registre-a: ```bash cmk add kubernetessupportedversion name="Kubernetes 1.35.0" semanticversion=1.35.0 \ url=https://files.example.com/setup-v1.35.0-calico-amd64.iso zoneid= \ mincpunumber=2 minmemory=2048 cmk list kubernetessupportedversions filter=name,semanticversion,state,isostate ``` Aguarde até que o estado da ISO se torne **Ready** e a versão fique como **Enabled**. 3. Crie a oferta de plano de controle, limitada ao domínio do NexCMP: ```bash cmk create serviceoffering name=K8S-CP-2-2 displaytext="Kubernetes control plane" \ cpunumber=2 cpuspeed=1000 memory=2048 limitcpuuse=true offerha=false domainid= ``` 4. Verifique se uma oferta de rede CKS está habilitada: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: criar as ofertas {#private-cloud-create-the-offerings} Na interface do CloudStack (**Service Offerings › Network Offerings › Add network offering**) ou com `cmk`: 1. Liste o que você tem: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. Use uma oferta de VPC habilitada (dupla pilha se quiser IPv6). Se precisar de uma nova, klone a oferta de VPC padrão do CloudStack e habilite-a. 3. Para **cada** plano de largura de banda que você vende, crie uma oferta de rede **para VPC** (klone a "isolated network offering for VPC networks" padrão) e defina **Network rate (Mb/s)** para a velocidade do plano: `50`, `100`, `500`, `1000`, `3000`. Habilite cada oferta. 4. Crie mais uma oferta com **taxa de rede 1** (`VPC-LOCKED-1M`) para VPCs bloqueadas: os clientes ainda podem acessar seus servidores via SSH, mas a velocidade é limitada. 5. Anote o UUID de cada offering. O NexCMP precisa deles na próxima seção. ::: warning Os offering IDs fornecidos não existem na sua nuvem O formulário do Private Cloud vem pré-preenchido com UUIDs de offering que pertencem a outra instalação do CloudStack. Substitua **cada** um pelos seus próprios, ou o primeiro pedido de VPC falhará. ::: ## Conectar no NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. Abra **Infrastructure › Cloud provider › CloudStack** e escolha a aba **Kubernetes (CKS)**. O card à direita **CKS status on CloudStack (read-only)** mostra `kubernetesserviceenabled`, `endpoint.url` com **Endpoint check**, a offering de rede do CKS, as configurações de `cloud.kubernetes.*` e a lista de ISOs e versões. Clique em **Recheck** após corrigir algo. 2. Em **Sales config**, escolha o **Control plane Offering** (um aviso aparece se não for exatamente 2 vCPU / 2048 MB / CPU cap), defina **Max workers per cluster** (1 a 9: o CKS permite 10 nós incluindo o nó de controle), ative **Enable CKS for this backend** e clique em **Save**. O botão se mantém desativado até que uma offering seja escolhida. ![A aba Kubernetes (CKS) com a offering do plano de controle escolhida e o card de status do CKS](https://nexcmp.com/pt/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. Abra **Services › Kubernetes › Versions** e clique em **Sync from CloudStack**. Ative **Available for new clusters** para as versões que você vende, defina a padrão e, se desejar, uma data de **End of life (EOL)**. 4. Abra **Services › Kubernetes › Policy**. Em **Worker plans**, adicione planos com um **Plan code** (A-Z, 0-9, hífen, até 16 caracteres). Defina **NVMe per worker (GB)**, **Min and max workers** e os limites do cluster (clusters ativos por conta, criações por 24 horas, limite global, operações CKS concorrentes). Em seguida, ative **Sell Kubernetes (CKS)**. Pelo menos um plano deve permanecer à venda. ![Política do Kubernetes com planos de worker e o botão de vendas](https://nexcmp.com/pt/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. Abra **Services › Private Cloud** (Visão geral). No cartão de política, substitua **VPC offering** e **Locked offering tier** pelos seus próprios UUIDs. Verifique os limites (VPCs por conta, camadas, VMs e regras de ACL por VPC, saldo em horas da taxa do plano necessário para criar, alterações de plano por 24 horas, operações concorrentes onde 0 é uma parada de emergência) e os servidores DNS. Clique em **Save** (será solicitado um motivo). ![Visão geral do Private Cloud com os campos de oferta de VPC e oferta bloqueada](https://nexcmp.com/pt/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. Abra **Services › Private Cloud › Plans & pricing**. Para cada plano, clique em **Edit** e defina **VND price per month**, **On sale** e o UUID de **CloudStack tier offering** cuja taxa de rede corresponda aos Mbps do plano. A linha exibe o custo e o lucro no uso total, permitindo ver quais planos estão abaixo do seu custo. ![Diálogo de edição de plano para um plano de largura de banda do Private Cloud](https://nexcmp.com/pt/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. Ative **Sell Private Cloud**. Para testar primeiro, adicione IDs de contas de teste em **Beta accounts**: essas contas podem usar o serviço enquanto o botão de vendas estiver desativado. ## Verificar {#verify} 1. Kubernetes: o cartão de status mostra `kubernetesserviceenabled: true`, uma verificação de endpoint bem-sucedida e uma versão habilitada. Crie um cluster de teste com um worker como cliente; ele deve atingir o estado de execução e `kubectl get nodes` deve exibi-lo como pronto. Exclua-o depois: a rede e o IP retornam ao pool. 2. Private Cloud: crie uma VPC com o menor plano como cliente de teste. A VPC exibe o status ativa, uma camada obtém sua sub-rede, uma VM na camada alcança a Internet através do roteador da VPC, e **Change plan** para um plano maior entra em vigor em cerca de 20 segundos sem derrubar conexões. ## Limites e observações {#limits-and-notes} - Kubernetes: os workers são faturados como VMs aos preços dos planos e contam como VMs nos limites de VM. Um cluster pode ter no máximo 9 workers devido ao limite de CKS de 10 nós. - Kubernetes: o plano de controle, o roteador e o IP público de um cluster são gratuitos para o cliente; você arca com os custos deles. - Private Cloud: todos os planos são **não metrificados**. Os preços no formulário são em dong vietnamita por mês; a coluna de custo usa um preço de referência que não é o seu, portanto, use seus próprios números. - Uma VPC bloqueada é limitada a 1 Mbps, não é faturada e não é excluída automaticamente. - Private Cloud usa um roteador por VPC, e não um par redundante. Se o host dele falhar, o CloudStack o reconstrói em poucos minutos. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `cp_offering_invalid` / "Esta Offering não é 2 vCPU / 2048 MB / limitcpuuse" | A oferta do plano de controle tem outros tamanhos ou nenhum limite de CPU | Crie a oferta conforme a etapa 3 e selecione-a novamente. | | O botão **Enable CKS** está desativado | Nenhuma oferta de plano de controle foi selecionada | Selecione uma primeiro. | | `kubernetesserviceenabled: false` | O CKS está desativado no CloudStack | Ative-o e reinicie o servidor de gerenciamento. | | A verificação do endpoint falhou | `endpoint.url` não é acessível a partir das VMs do cluster | Defina uma URL acessível, reinicie o servidor de gerenciamento e clique em **Recheck**. | | "EOL: não é possível habilitar para venda" | A data de fim de vida útil (EOL) da versão já passou | Registre uma versão mais recente. | | "Sem versões: clique em Sync from CloudStack" | Nenhuma versão do Kubernetes registrada | Registre uma versão e faça a sincronização. | | "O backend do CKS está DESLIGADO: os clientes não podem criar clusters, mesmo se a opção de vendas estiver ativada" | A opção de vendas está ativada, mas o backend do CKS está desligado | Ative o CKS na aba CloudStack. | | "Pelo menos 1 plano deve estar à venda" | O último plano de worker foi removido | Mantenha pelo menos um plano ou desative as vendas do Kubernetes. | | Cluster travado na criação | Capacidade insuficiente ou ISO ausente | Verifique as abas de capacidade e o estado da ISO da versão. | | Uma nova VPC falha na primeira etapa | O ID da offering da VPC ou tier offering não é válido | Substitua cada UUID de offering por um do seu CloudStack. | | "cs_offering_id deve ser um UUID" | Um ID de offering não é um UUID | Cole o id de `cmk list networkofferings`. | | A alteração de plano falhou | A nova tier offering não existe ou a taxa de rede está incorreta | Verifique o UUID da offering e sua taxa de rede. | --- # Planos e preços {#plans-and-pricing} > **Onde no painel administrativo:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`), com as abas Plan, Custom plan, Cycle e Offering CloudStack. Os templates ficam na página separada Services › Virtual Machines › Template (`/vm/templates`). ## O que faz {#what-it-does} Um **plano** é um tamanho que os clientes podem comprar: vCPU, RAM, disco raiz e um preço, em uma zona, de uma única origem (CloudStack ou um cluster Proxmox VE). O cliente escolhe um plano, um sistema operacional e um **ciclo de cobrança** (por hora, mensal ou um prazo pré-pago maior). Os planos são vendidos no portal do cliente, por meio da API e em sites de revendedores. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Source | CloudStack conectado (um plano aponta para um service offering do CloudStack) ou um cluster Proxmox VE anexado à zona. Consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) e [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). | | Zone | Uma zona que vende máquinas virtuais. Consulte [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). | | Templates | Pelo menos um template habilitado e pronto. Consulte [OS templates](https://nexcmp.com/pt/docs/infrastructure/templates/). | | Taxa de câmbio | Apenas se você inserir preços em VND. Consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). | | Permissões | Um administrador; cada alteração de preço exige um motivo. | ## Preparar a infraestrutura {#prepare-the-infrastructure} - **CloudStack:** crie as ofertas de serviço que deseja vender (públicas ou compartilhadas com o domínio NexCMP). Um plano aponta para uma oferta. A aba **Offering CloudStack** lista as ofertas e ofertas de disco diretamente do CloudStack (em cache por 60 segundos). Quando a tabela de planos está vazia, o worker cria seis planos a partir das suas ofertas reais automaticamente. - **Proxmox VE:** nada no Proxmox; um plano carrega sua própria CPU, RAM e disco. O disco não deve ser menor que o disco do template. ## Conectar no NexCMP {#connect-in-nexcmp} ### Como os preços são armazenados {#how-prices-are-stored} O NexCMP armazena cada preço como **micro-dólares por hora** (µ$/hora; 1 µ$ é 1/1,000,000 USD). Você pode digitar o preço na unidade que preferir e o formulário faz a conversão: | Unidade | Notas | |---|---| | USD / hora (6 decimais) | Armazenado como está. | | USD / mês | Dividido pela configuração de horas por mês (730). | | VND / mês | Convertido uma vez na taxa de câmbio atual, depois armazenado em µ$/hora. Aparece apenas quando existe uma taxa. | O formulário mostra o resultado: µ$/hora, USD/hora, o preço mensal e cada ciclo de cobrança. **Preço mensal = preço por hora × 730**; um ciclo mais longo é **preço mensal × meses × (1 − desconto)**. ### Adicionar um plano {#add-a-plan} 1. Abra **Services › Virtual Machines › Plans & pricing** e clique em **Add plan**. 2. Preencha o formulário: | Campo | Valor de exemplo | |---|---| | Nome do plano | `VM-2-4` | | Slug | vazio: gerado a partir do nome | | Zone | sua zona padrão | | Origem da infraestrutura | vazio para CloudStack ou um cluster Proxmox | | Oferta de serviço CloudStack (ao vivo) | escolha uma (exibido apenas para CloudStack) | | CPU (núcleo), RAM (MB), Disco raiz (GB) | `2`, `4096`, `40` | | Oferta de disco | opcional, para um tamanho de raiz personalizado | | Inserir preço por / Preço | `USD / month`, `12` | | Descrição curta | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | Order | `10` | | Active | Ligado: os clientes podem comprar | | Visibility | Visível no catálogo | | Motivo da alteração de preço | `initial price` | 3. Clique em **OK**. O plano aparece na tabela com seu preço por hora e mensal e uma célula para cada ciclo habilitado. ![Tabela de planos com preços por hora, mensais e por ciclo](https://nexcmp.com/pt/docs/images/catalog/plans-02-list.webp) ### Ciclos de cobrança {#billing-cycles} Abra a aba **Cycle** para definir quais ciclos os clientes podem escolher e seus descontos. | Ciclo | Padrão | Notas | |---|---|---| | Por hora | sempre ativado | Cobrado hora a hora. | | Mensal | ligado, 0% | | | 1 ano | ligado, 10% | | | 2 anos | ligado, 15% | | | 3 anos | ligado, 20% | | Você pode renomear um ciclo, alterar o desconto dele (de 0 a 90%) e ativá-lo ou desativá-lo. Uma alteração se aplica a VMs compradas ou renovadas **após** você salvar; VMs em execução mantêm o preço travado. ![Aba de ciclos com descontos por ciclo de faturamento](https://nexcmp.com/pt/docs/images/catalog/plans-03-cycles.webp) ### Definir um plano base e derivar os outros {#set-a-base-plan-and-derive-the-others} **Set base plan + derive other plans** recalcula a tabela inteira a partir de um preço. Escolha o plano base e seu preço, depois mantenha as **current price ratios** entre os planos ou calcule a partir de **component prices** (µ$/hora por vCPU, por GB de RAM e por GB de NVMe, com um desconto de pacote opcional de 0 a 50%). Uma tabela de visualização mostra os preços antigos e novos antes de qualquer gravação. Clique em **Apply** e forneça um motivo. Ao aplicar novos preços: VMs **por hora** em execução recebem um preço **mais baixo** a partir da próxima hora de faturamento, e VMs pré-pagas o recebem na renovação. Se um preço **aumentar**, as VMs em execução mantêm o preço antigo. ### Planos personalizados {#custom-plans} A aba **Custom plan** permite que os clientes escolham seus próprios tamanhos de vCPU, RAM e NVMe. Defina o preço unitário por hora para uma vCPU, um GB de RAM e um GB de NVMe (deixe em vazio para derivar de um desconto percentual), o mínimo, o máximo e o incremento para cada um, e quais ciclos de faturamento se aplicam. Um plano **custom** deve custar mais do que um plano fixo do mesmo tamanho, caso contrário, os clientes ignorariam o plano fixo; a página sinaliza as linhas em que o plano personalizado é mais barato. Ative **Enable custom plans for customers** para vendê-los; desativado exibe "Coming soon" no portal. Cada VM personalizada obtém sua própria linha de plano oculta; essas linhas não podem ser editadas ou excluídas enquanto a VM existir. ### Alterar, ocultar, clonar, excluir {#change-hide-clone-delete} | Ação | O que faz | |---|---| | **Edit** | Altera nome, descrição, ordem, preço, estado ativo e visibilidade. | | **On/Off** | **Off**: os clientes não podem comprar; VMs em execução não são afetadas. | | **Hide / Show** | Um plano oculto não está no catálogo, mas as VMs existentes o mantêm e um administrador pode atribuí-lo. | | **Clone** | Cria um novo plano na mesma zona com uma nova origem, tamanho ou preço, ocultando opcionalmente o antigo. Para vender a mesma configuração do CloudStack e do Proxmox, clone-a e escolha a outra origem. | | **Mover para cima/baixo** | Altera a ordem. | | **Delete** | Remove o plano da venda e da tabela. As VMs que já o utilizam o mantêm. | ::: warning Planos em uso estão travados Assim que um plano possui VMs, sua **zone, offering, CPU, RAM, disk and source** são travadas para que as VMs em execução não sejam alteradas silenciosamente. Use **Clone** para criar a nova configuração; o plano antigo mantém suas VMs. ::: ## Verificar {#verify} 1. O plano aparece na tabela com o preço por hora e mensal esperado. 2. No portal do cliente, inicie um pedido: a zona oferece o plano e os preços do ciclo correspondem à aba **Cycle**. 3. Faça um pedido de teste, verifique a cobrança na carteira em relação ao preço exibido e exclua a VM. ## Limites e observações {#limits-and-notes} - Um plano pertence a **uma** zona e **uma** origem. - Os preços são armazenados em µ$/hora; o preço em VND exibido é derivado e arredondado pelo **VND rounding step** (consulte a página de moeda). A carteira é sempre em USD. - Revendedores obtêm um preço de atacado e varejo derivado do preço de tabela; alterar um preço para um plano existente não copia preços personalizados de revendedor para um clone cuja configuração você alterou. - Os limites mínimo, máximo e de incremento dos planos personalizados são verificados em relação aos limites do próprio CloudStack; um disco máximo acima de `storage.max.volume.size` do CloudStack faz com que as implantações falhem e gerem reembolso. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Nome do plano obrigatório" / "Oferta de serviço obrigatória" | Campo ausente | Preencha o nome; para o CloudStack, escolha uma oferta. | | "CPU/RAM/disco devem ser > 0" | Um tamanho está vazio ou é zero | Insira os três. | | "Preço inválido (µ$/hr deve ser de 1 a 100,000,000)" | O preço está fora do intervalo | Verifique a unidade e o valor. | | "A alteração de preço requer um motivo" | Motivo vazio ao editar | Digite um motivo (3 caracteres ou mais). | | "A oferta "X" é 4c/8192, mas o plano especifica 2c/4096 - O CloudStack fará o provisionamento pela oferta. Salvar?" | Os números do plano diferem dos da oferta | Faça-os corresponder ou confirme para manter o tamanho do CloudStack. | | "Falha ao buscar ofertas do CloudStack" | A conexão está caída ou a chave não tem permissão | Consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/). | | "O modelo não está pronto no CloudStack - a implantação falhará. Ativar mesmo assim?" | Você ativou um modelo inacabado | Aguarde o modelo ficar pronto. | | O plano não pode ser editado ("possui VMs - bloqueado") | As VMs usam o plano | Clone-o. | | O plano não aparece para os clientes | Desativado, oculto ou a zona não está pronta | Verifique **Active**, **Visibility** e a tag da zona. Consulte [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). | | "Selecione pelo menos 1 ciclo de cobrança" | Nenhum ciclo marcado para planos personalizados | Marque pelo menos uma. | | "O desconto do pacote deve ser de 0–50%" | Fora do intervalo | Use de 0 a 50. | | Opção de preço em VND ausente | Nenhuma taxa de câmbio ainda | Atualize a taxa primeiro. | --- # Cotas de largura de banda e add-ons {#bandwidth-quotas-and-add-ons} > **Onde no admin:** Services › Bandwidth: Summary (`/bandwidth`), Add-on (`/bandwidth/addons`) e Quotas, pricing & policy (`/bandwidth/policy`). O seletor do módulo fica em System › Admin › License & updates. ## O que faz {#what-it-does} A largura de banda concede a cada serviço metrificado uma **cota** mensal de tráfego. O NexCMP mede o uso, avisa o cliente em 80% e 100% e, quando a cota é excedida, age de acordo com a sua **política de excesso**. Os clientes podem comprar **add-ons** de terabytes extras usando a carteira; você também pode conceder add-ons gratuitamente. | Service | Cota | |---|---| | Virtual Machines | Por VM por mês (padrão 2048 GB, ou seja, 2 TB) | | Kubernetes | A cota de VM multiplicada pelo número de workers | | Object Storage | Tráfego de download por cliente por mês (padrão 100 GB); além disso, aplica-se o preço normal de pay-as-you-go | | VPN | Mantém a cota do seu plano; atualize a largura de banda na página de VPN | | Private Cloud | **Sem limite** | ## Requisitos {#requirements} | Item | Requisito | |---|---| | Módulo | **Bandwidth** está ativado por padrão. Desative-o em License & updates para ocultá-lo. | | Fonte de medição | Com a fonte padrão, **CloudStack VM statistics**. Mantenha a coleta de estatísticas de VM ativada no CloudStack; a retenção padrão de 720 minutos é suficiente. | | Proxmox VE | As VMs no Proxmox VE **não são medidas**. | | Taxa de câmbio | O preço do complemento é inserido em VND. Consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). | | Depende de | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) para tráfego de VM e Kubernetes, [S3](https://nexcmp.com/pt/docs/infrastructure/s3/) para downloads de armazenamento. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não é necessário além de o CloudStack estar conectado. O NexCMP lê `listVirtualMachinesUsageHistory` para todas as VMs da conta em uma única chamada, a cada 5 minutos, em janelas de no máximo duas horas. Cada amostra cobre um minuto e é **somada**. As amostras são obtidas com três minutos de atraso para que tenham tempo de chegar. Uma lacuna maior que a retenção do CloudStack (cerca de 12 horas) é ignorada e registrada. ::: info O que os números significam O uso é contabilizado na interface de rede de cada VM, portanto inclui o tráfego entre VMs, e não apenas o tráfego para a Internet. Pode ser um pouco maior do que um roteador de borda contabilizaria. ::: ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Services › Bandwidth › Quotas, pricing & policy**. 2. Defina os valores e clique em **Save**; um motivo será solicitado e registrado. O worker aplica a alteração em cerca de 30 segundos. | Campo | Padrão | Significado | |---|---|---| | Habilitar largura de banda (menu do cliente e compra de complementos) | on | A chave para o lado de vendas do módulo. | | VM, GB/mês (Kubernetes = este valor × workers) | 2048 | Cota por VM por período. | | S3, download em GB/mês por cliente | 100 | Além disso, aplica-se o preço padrão de S3 pay-as-you-go. | | Direção da cota (VM, Kubernetes) | In + out | Ou **Outbound only**. | | Preço de +1 TB (VND) | 100,000 | Convertido em centavos à taxa de cotação. | | Máximo por compra (TB) | 50 | | | Política de excedente | suspend | **notify**, **throttle** ou **suspend** (abaixo). | | Aplicar suspensão real a partir de | data de migração + 24 horas | Antes desta data, nada é suspenso; os clientes recebem apenas avisos. | | Limite de taxa de throttling (Mbps) | | Usado apenas pelo throttle. | ![Política de largura de banda: cotas padrão, preço de complementos e política de excedente](https://nexcmp.com/pt/docs/images/catalog/bandwidth-01-policy.webp) ### Políticas de excedente {#overage-policies} | Política | O que acontece quando um serviço ultrapassa 100% | |---|---| | **notify** | O cliente é notificado. Nada mais. | | **throttle** | Como notify por enquanto: o limitador de velocidade não está conectado nesta versão. | | **suspend** (padrão) | A VM, o cluster ou a conta S3 é suspenso até que o cliente compre um complemento ou o próximo período comece. Só é efetivo a partir da data de **suspend-from**. | Os alertas de 80% e 100% (sino e e-mail) são sempre executados, uma vez por limite, período e serviço. Se você desbloquear um serviço que foi suspenso por largura de banda enquanto ele ainda estiver acima da cota, a próxima verificação (dentro de 5 minutos) o suspenderá novamente. Para mantê-lo funcionando, **conceda um complemento**. ### Monitor o uso e conceda complementos {#watch-usage-and-grant-add-ons} Abra **Services › Bandwidth › Summary**. A listagem exibe cada serviço com seu uso no período atual, cota incluindo complementos, cota restante e as marcas de 80% e 100%. Os blocos de KPI mostram o número de serviços, complementos vendidos nos últimos 30 dias e o estado do coletor (em execução, cursor). A tabela **Daily** mostra o período atual dia a dia. ![Resumo de largura de banda com o estado do coletor e o uso por serviço](https://nexcmp.com/pt/docs/images/catalog/bandwidth-02-summary.webp) Para dar margem a um cliente, use **Grant** em um serviço (um complemento de terabytes inteiros sem custo). Abra **Add-on** para ver o histórico de compras e concessões, do mais recente para o mais antigo, com filtro por tipo. ![Histórico de complementos mostrando compras e concessões gratuitas](https://nexcmp.com/pt/docs/images/catalog/bandwidth-03-addons.webp) ### O que os clientes veem {#what-customers-see} O portal do cliente ganha um menu **Bandwidth** com o uso, a cota restante e uma ação **buy +1 TB** paga com a carteira (até o seu limite máximo por compra). Os complementos são válidos para o período atual. ## Verificar {#verify} 1. O coletor em **Summary** está em execução e o seu cursor avança a cada poucos minutos. 2. Uma VM com tráfego mostra uso após cerca de 10 a 15 minutos. 3. Para ver os alertas, reduza a cota da VM para alguns GB em uma instalação de **teste** e gere algum tráfego. Não faça isso em produção: a cota se aplica a todas as VMs. ## Limites e observações {#limits-and-notes} - O uso é contado por período (um mês). Complementos e cotas aplicam-se ao período atual. - "Enforce actual suspend from" protege você contra a suspensão de clientes no momento em que o módulo é ativado pela primeira vez. - A política de limitação apenas envia notificações nesta versão. - Alterar a cota se aplica a todos os sites, incluindo sites de revendedores. Os preços de varejo e atacado dos complementos dos revendedores seguem seus descontos ou margens. - A largura de banda para **Dedicated servers** é um assunto separado; consulte [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O uso permanece em zero para uma VM em execução | O worker está parado, o CloudStack está desconectado ou as estatísticas da VM estão desativadas | Verifique `sudo nexcmp status` e **Test connection** em [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/); ative as estatísticas de VM do CloudStack. | | O uso apresenta falhas | A retenção do CloudStack foi excedida ou o worker ficou inativo por mais de 12 horas | Não recuperável; a lacuna é registrada. | | O uso está um pouco acima do esperado | O tráfego entre VMs e outro tráfego de interface está incluído | Esperado; explique isso aos clientes. | | Um serviço suspenso retorna como suspenso após você desbloqueá-lo | Ele ainda está acima da cota | Conceda um complemento ou aumente a cota. | | Nada é suspenso, embora a política seja **suspend** | A data de início da suspensão está no futuro | Defina-a para o momento atual (a página exibe "ACTIVE" quando em vigor). | | "bw_over_policy deve ser notify, throttle ou suspend" | Política inválida enviada por meio da API | Use um dos três valores. | | As VMs do Proxmox não mostram uso | Elas não são monitoradas | Esperado. | | Os clientes não conseguem comprar complementos | A largura de banda está desativada ou a carteira está vazia | Verifique a chave e a carteira. | --- # Moeda e taxas de câmbio {#currency-and-exchange-rates} > **Onde no admin:** Finance › Payment channels › Exchange rates (`/payments/fx`) para as taxas. System › Settings › Brand (`/settings/branding`) para o botão **Site currency**. ## O que faz {#what-it-does} O NexCMP mantém carteiras e faturas em USD. Os preços dos planos de VM são armazenados em microdólares por hora. As moedas de exibição permitem que os clientes visualizem valores em USD na sua própria moeda a uma taxa publicada; elas não alteram o saldo da carteira. Alguns serviços aceitam preços inseridos em VND, incluindo add-ons de largura de banda, S3, Private Cloud e planos Bare Metal existentes que mantêm a precificação em VND. Transferências bancárias via Sepay são pagas em VND. As taxas são **publicadas por um administrador**. Nada é atualizado automaticamente, portanto as taxas salvas permanecem exatamente como estão até que você pressione o botão de atualização. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Acesso à internet | O servidor do painel precisa conseguir acessar `open.er-api.com` (para USD/VND) e `api.frankfurter.dev` (para as outras moedas) quando você clica em **Update exchange rates**. | | Permissões | Um administrador para alterações; cada alteração solicita um motivo. | | Depende de | Nada. [Plans](https://nexcmp.com/pt/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/), [S3](https://nexcmp.com/pt/docs/infrastructure/s3/) e transferências bancárias em VND usam a taxa. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não obrigatório. Se o seu servidor filtrar o tráfego de saída, permita HTTPS para os dois serviços acima. ## Conectar no NexCMP {#connect-in-nexcmp} ### 1. Escolher a moeda do site {#_1-choose-the-site-currency} Abra **System › Settings › Brand** e defina **Site currency**: | Escolha | O que os clientes veem | |---|---| | **Language-based (auto)** (o padrão em uma nova instalação) | O portal seleciona uma moeda de exibição com base no idioma (tabela abaixo). O cliente pode optar por USD em vez disso. | | **USD** | Preços e saldos apenas em USD. Sem seletor de moeda e sem valores convertidos. | | **VND** | Configuração legada; segue as mesmas regras de exibição com base no idioma do Auto. | Salvar. As páginas do cliente são atualizadas em cerca de um minuto. Quando o site segue o idioma do cliente: | Idioma | Moeda de exibição | |---|---| | Inglês | USD | | Vietnamita | VND | | Chinês (simplificado / tradicional) | CNY / TWD | | Japonês, coreano | JPY, KRW | | Francês, alemão, espanhol, italiano | EUR | | Português, russo | BRL, RUB | | Árabe, híndi | SAR, INR | | Indonésio, tailandês | IDR, THB | Uma moeda cuja taxa não tenha sido publicada não é oferecida: o portal recorre ao USD como padrão. ### 2. Publicar as taxas {#_2-publish-the-rates} 1. Abra **Finance › Payment channels › Exchange rates**. 2. O cartão **Currency by language** lista as 11 moedas de exibição com suas taxas por USD, a origem (Frankfurter) e a hora da última atualização. Clique em **Update exchange rates**. O botão realiza duas ações em uma única etapa: ele lê a tabela do mercado público para **USD/VND** e lê as outras 11 taxas. Ambas são verificadas antes que qualquer uma seja salva. Se uma falhar, nada é alterado e as taxas anteriores permanecem. 3. O card **Active exchange rate** mostra a taxa de USD/VND em vigor, sua tag de origem (mercado público ou fixa), a margem e os valores de referência do mercado com seus timestamps. 4. O cartão **Config** (salve com um motivo): | Campo | Significado | Intervalo | |---|---|---| | Margem (bp, 100 = 1 %) | Adicionado sobre a taxa de referência de mercado. A taxa efetiva é a taxa de referência mais a margem, arredondada para cima. | 0 a 1000 | | Taxa fixa (VND por USD, 0 = seguir mercado) | Uma taxa definida por você. Ela substitui o valor de mercado. | 0 ou 15,000 a 50,000 | | Limite de salto (bp) | Uma nova taxa de mercado que diferir da atual por mais do que isso fica **retida** até que você a confirme. | 50 a 2000 (padrão 500) | | Etapa de arredondamento de VND | Arredonda preços em VND e valores de transferência bancária. | 1, 100, 1,000 (default) ou 10,000 | 5. Se uma nova taxa de mercado variar mais do que o limite definido, o card **Pending exchange rate** será exibido e a taxa **não será aplicada**. Verifique-a em relação à sua referência escolhida e clique em **Apply this rate**. Uma taxa de mercado fora da faixa de 15,000 a 50,000 VND por USD é rejeitada como inconsistente. As atualizações manuais são limitadas a uma solicitação a cada cinco minutos, portanto o botão pode solicitar que você aguarde. 6. A tabela **Exchange rate history** lista cada taxa consultada ou confirmada com seu horário, taxa efetiva, referência de mercado, fonte, se foi aplicada, quem a executou e uma observação (variações retidas são marcadas como **held**). ## Como uma taxa é usada {#how-a-rate-is-used} | Local | Regra | |---|---| | Carteira e faturas | Centavos de USD. A taxa nunca altera um saldo. | | Planos de VM inseridos em VND | Convertidos **uma única vez** à taxa vigente no momento em que você salva, sendo então armazenados em USD. Alterações posteriores na taxa não alteram os preços desses planos de VM. | | Transferência bancária via Sepay | O cliente paga `ceil(USD × rate)`, arredondado para cima conforme a etapa de arredondamento. O Sepay fica **bloqueado** até que exista uma taxa USD/VND. | | Planos Bare Metal | Novas instalações usam USD diretamente. Planos existentes em VND mantêm sua unidade de preço e necessitam de uma taxa no momento da cobrança; consulte [Servidores dedicados](https://nexcmp.com/pt/docs/infrastructure/dedicated/). | | Outros pagamentos internacionais inseridos em VND | Arredondado para o centavo mais próximo. | | Exibição no portal | USD multiplicado pela taxa publicada da moeda de exibição, formatada para o idioma. | ## Verificar {#verify} 1. **Active exchange rate** mostra um valor USD/VND com um horário recente de "fetched". 2. A grade **Currency by language** mostra taxas não vazias. 3. No portal do cliente, altere o idioma para vietnamita (moeda do site em Auto): os preços são exibidos em dong; altere para japonês: iene. Com a moeda do site em USD, apenas dólares são exibidos. 4. Em um formulário de plano (Plans & pricing), a lista **Enter price by** oferece **VND / month**. ## Limites e observações {#limits-and-notes} - Sem atualização automática. Pressione **Update exchange rates** quando quiser novas taxas e defina um lembrete se as taxas forem importantes para você. - A taxa de mercado pública é usada para USD/VND; trata-se de uma taxa de referência, e não de uma cotação bancária de compra ou venda. As outras moedas de exibição vêm do Frankfurter; uma data com mais de 14 dias ou uma tabela incompleta é rejeitada. - A margem e a taxa fixa afetam apenas USD/VND. As 11 moedas de exibição não possuem margem. - Cada idioma de cliente possui uma moeda. Mudar o idioma redefine para a moeda daquele idioma, a menos que o cliente tenha escolhido USD para o mesmo idioma. - Os sites de revendedores seguem as mesmas taxas. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Nova taxa de câmbio diverge além do limite — EM ESPERA, requer confirmação manual" | A variação é maior do que o limite estabelecido | Verifique e clique em **Apply this rate**, ou altere o limite. | | "Servidor rejeitou a nova taxa de câmbio" | O valor de mercado está fora de 15,000 a 50,000 ou está malformado | Aguarde e tente novamente, ou defina uma taxa fixa. | | A atualização solicita que você aguarde antes de tentar novamente | Atualizações muito frequentes | Aguarde e tente novamente. | | "não foi possível buscar a taxa: …" | O servidor do painel não consegue acessar os serviços de taxa | Permita tráfego HTTPS de saída e tente novamente. | | Tag **Sepay blocked** | Nenhuma taxa USD/VND foi publicada ainda | Pressione **Update exchange rates** ou defina uma taxa fixa. | | Uma moeda está faltando no portal | A taxa correspondente está ausente | Pressione **Update exchange rates**. | | Os clientes veem os preços apenas em USD | A moeda do site é USD ou a taxa está ausente | Defina **Site currency** como Auto e publique as taxas. | | "Tabela de taxas de câmbio incompleta; taxas anteriores mantidas" | O Frankfurter retornou menos de 11 moedas | Tente novamente mais tarde; nada foi alterado. | | A opção VND está ausente no formulário do plano | Nenhuma taxa USD/VND | Publique uma taxa primeiro. | --- # Canais de pagamento {#payment-channels} > **Onde encontrar no admin:** Finance › Payment channels (`/payments`). Alternadores e taxas: Finance › Payment channels › Fees & limits (`/payments/fees`). O NexCMP usa uma **carteira pré-paga em USD**. Os clientes adicionam saldo à carteira por meio de um canal de pagamento; cada serviço é pago a partir da carteira. Um canal só é exibido para os clientes quando está **ativado** e **configurado**. ## O que faz {#what-it-does} Os canais de pagamento conectam suas contas de pagamento (Stripe, PayPal, Binance, um banco vietnamita) à carteira do cliente. Um pagamento confirmado se torna exatamente um crédito na carteira — cada crédito é identificado pelo ID de pagamento do gateway, portanto, um webhook repetido nunca poderá adicionar dinheiro duas vezes. Use esta página para ver quais canais estão prontos, como eles se saíram nos últimos 30 dias e quais precisam de atenção. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Endereço HTTPS público | Os gateways enviam webhooks para `https:///v1/billing/...`, portanto, seu painel deve estar acessível a partir da Internet por TLS válido (consulte [DNS and Cloudflare](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/)). | | Contas | Sua própria conta em cada provedor que deseja usar. As credenciais são inseridas no painel administrativo e nunca mais são exibidas (apenas os últimos 4 caracteres). | | Papel de administrador | Uma conta de administrador. | | Dependências | Nenhum. O canal de banco do Vietnã também precisa de uma [exchange rate](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). | ## Os canais {#the-channels} | Canal | O que o cliente vê | Configurado em | Artigo | |---|---|---|---| | Cartão (Stripe) | Formulário de cartão, cartão salvo | Payment channels › Stripe | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | Botões de carteira (Stripe Express Checkout) | Stripe, mais registro de domínio | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | Redirecionamento para o Alipay (cobrado em JPY pela Stripe) | Stripe, mais Fees & limits | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/#alipay) | | PayPal | Botões do PayPal, conta do PayPal salva | Payment channels › PayPal | [PayPal](https://nexcmp.com/pt/docs/billing/paypal/) | | USDT | Endereço de depósito e valor exato | Payment channels › USDT | [USDT](https://nexcmp.com/pt/docs/billing/usdt/) | | Transferência bancária VN | QR code e detalhes da transferência (apenas interface em vietnamita) | Payment channels › VN bank transfer | [Bank transfer (Vietnam)](https://nexcmp.com/pt/docs/billing/bank-transfer-vn/) | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não é necessário. Tudo é configurado no admin; não há nada para instalar no servidor. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels** (`/payments`). A tabela de visão geral lista cada canal com seu estado. 2. Abra a aba própria do canal (**Stripe**, **PayPal**, **USDT**, **VN bank transfer**) e siga o artigo correspondente. Cada aba termina com um botão **Save** e, quando disponível, um botão **Test**. 3. Abra **Fees & limits** (`/payments/fees`), localize o cartão **Payment gateways & fees (wallet top-up)**, ative o canal com a chave correspondente e clique em **Save channels & fees**. ![Visão geral dos canais de pagamento listando os gateways com seus status de ativado, configurado e estatísticas de 30 dias](https://nexcmp.com/pt/docs/images/billing/payment-channels-01-overview.webp) ![Página de taxas e limites com as chaves dos canais e os campos de taxa](https://nexcmp.com/pt/docs/images/billing/payment-channels-02-fees.webp) ### Chaves e taxas (Fees & limits) {#switches-and-fees-fees-limits} | Configuração | Padrão | Significado | |---|---|---| | Cartão (Stripe) | On | Formulário de cartão na tela de depósito. Oculto até que a Stripe tenha uma chave secreta. | | Apple Pay, Google Pay, Link | On | Botões de carteira. Eles aparecem apenas quando o domínio é verificado na Stripe. | | Alipay | Desligado | Requer o Alipay ativado no Dashboard da Stripe. | | PayPal | Desligado | Exibido apenas quando o PayPal está configurado. | | USDT (Binance) | Desligado | A chave fica bloqueada até que o endereço de depósito seja verificado junto à Binance. | | Taxa da Stripe % / fixa (centavos) | 3.6 % e 0 | Usado para mostrar a taxa ao cliente e calcular o valor creditado. Defina com sua tarifa real da Stripe. | | Taxa do PayPal % / fixa | 4.4 % e 30 centavos | O mesmo, para o PayPal. | | Taxa de USDT % | 1 % | O mesmo, para USDT. | | O cliente paga a taxa de recarga | Desligado | **On**: o cliente paga o valor + taxa e a carteira recebe o valor integral. **Off**: a taxa é deduzida e a carteira recebe o valor menos a taxa. | O cliente sempre vê a taxa e o crédito final na carteira antes de pagar. Desativar um canal oculta o botão e o servidor recusa novos pagamentos com `method_disabled` (HTTP 403). ::: tip Limites de recarga Os valores mínimo e máximo por recarga estão na mesma página — consulte [Minimum top-up](https://nexcmp.com/pt/docs/billing/minimum-top-up/). ::: ## Verificar {#verify} 1. Na tabela de visão geral, o canal mostra **Enabled** e **Configured**; a coluna **Last test** é preenchida após clicar em **Test** na aba do canal. 2. Entre no portal como um cliente de teste e abra **Billing › Deposit**. O botão do canal está presente. 3. Faça um pequeno pagamento (consulte o artigo do canal para cartões de teste ou contas de sandbox). O saldo aumenta, uma notificação de **Top-up received** aparece e o pagamento é listado em **Finance › Billing › Top-ups** (`/billing/deposits`). ## Limites e notas {#limits-notes} - **Colunas da visão geral:** *30 days* (número de pagamentos, sucessos, falhas e volume), *Stuck 24h* (pagamentos ainda pendentes após um dia) e *Unmatched* (USDT ou transferências bancárias que chegaram mas não correspondem a nenhum pedido). A linha de KPI adiciona o volume de 30 dias, o número de canais com falha (ativados mas não configurados, ou pagamentos travados) e o total não correspondido. - **Eventos de webhook** estão listados em **Payment channels › Gateway events** (`/payments/events`). O Stripe tem sua própria aba; PayPal e USDT compartilham uma. Um evento com falha pode ser reproduzido — o razão da carteira é idempotente, portanto, reproduzir nunca credita duas vezes. - **Resellers** podem ter seus próprios canais do Stripe, PayPal, USDT e bancários. As linhas deles também aparecem aqui, e o seletor de site no cabeçalho os filtra. Consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). - **Reembolsos:** Pagamentos via Stripe e PayPal podem ser reembolsados a partir da lista de pagamentos; pagamentos em USDT não podem ser reembolsados para a origem (o servidor responde `usdt_no_refund`). - **Modo de manutenção** ainda aceita webhooks de gateway, portanto, um pagamento feito pouco antes da manutenção não é perdido. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Canal ausente na tela de depósito do cliente | Desativado, não configurado ou (banco do VN) a interface não está em vietnamita | Verifique **Fees & limits** e a aba do canal; consulte [Bank transfer (Vietnam)](https://nexcmp.com/pt/docs/billing/bank-transfer-vn/). | | O KPI **Faulty channels** está acima de 0 | Um canal está ativado sem credenciais, ou os pagamentos estão pendentes há mais de 24 horas | Abra a linha e clique em **Configure**; para pagamentos travados, abra **Gateway events** e reproduza. | | O cliente pagou mas o saldo não mudou | O webhook não chegou | Verifique a URL do webhook na aba do canal e, em seguida, reproduza o evento em **Gateway events**. | | O servidor responde `method_disabled` | A chave está desativada | Ative-a em **Fees & limits** e salve. | | A chave do USDT está esmaecida | Endereço de depósito não verificado | Clique em **Test & verify address** na aba do USDT. | --- # Stripe > **Onde no admin:** Finance › Payment channels › Stripe (`/payments/stripe`). Chaves e taxas: Finance › Payment channels › Fees & limits (`/payments/fees`). ## O que faz {#what-it-does} O Stripe aceita pagamentos com cartão para recargas de carteira. Com a mesma conta, você também pode oferecer **Apple Pay**, **Google Pay**, **Link** e **Alipay**, e permitir que os clientes **salvem um cartão** para [recarga automática](https://nexcmp.com/pt/docs/billing/auto-top-up/). Use-o como o canal principal para clientes internacionais. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Conta do Stripe | Uma conta do Stripe que aceite pagamentos em **USD**. O Alipay é cobrado em JPY e precisa ser ativado pelo Stripe na sua conta. | | Chaves | Uma chave secreta (`sk_live_...` ou `sk_test_...`) e uma chave publicável (`pk_live_...` ou `pk_test_...`). O formulário aceita apenas chaves com esses prefixos. | | Rede | Seu painel deve estar acessível via HTTPS a partir da internet (o Stripe chama o webhook) e deve conseguir acessar `api.stripe.com` na porta 443. | | Domínio (apenas carteiras) | O domínio voltado para o cliente precisa atender em `/.well-known/apple-developer-merchantid-domain-association` — o NexCMP faz isso para você. | | Dependências | Nenhum. | ::: info Contas do Stripe compartilhadas O NexCMP processa apenas eventos de webhook para pagamentos criados por ele mesmo, portanto você pode usar uma conta do Stripe que também atenda a outra aplicação. ::: ## Preparar a infraestrutura {#prepare-the-infrastructure} No lado do Stripe: 1. Faça login no [Stripe Dashboard](https://dashboard.stripe.com). Ative ou desative **Test mode** para decidir se você está fazendo um teste ou em produção. Chaves de um modo nunca funcionam no outro. 2. Abra **Developers › API keys**. Copie a **Publishable key**, e revele e copie a **Secret key**. Mantenha a chave secreta em sigilo. 3. (Opcional) Abra **Settings › Payment methods** e ative **Alipay** se desejar oferecê-lo. 4. Você **não** precisa criar o webhook manualmente — o NexCMP pode criá-lo para você (consulte a etapa 5 abaixo). Se preferir fazer isso manualmente, crie um endpoint em **Developers › Webhooks** com a URL e os eventos listados em [Webhook](#webhook). ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. No cartão **API keys**, escolha o **Mode** (`live` ou `test`), cole a **Secret key** e a **Publishable key**. 3. Clique em **Save**. As chaves são gravadas em um arquivo de configuração no servidor que apenas a conta de serviço do NexCMP pode ler. Elas nunca são enviadas de volta ao navegador; depois disso, a página exibe apenas os últimos 4 caracteres. 4. Clique em **Check**. Uma caixa de diálogo informa a conexão, o modo, o saldo disponível e pendente, o ID da conta, se as cobranças estão ativadas, se um webhook existe e se o Alipay está disponível. Uma linha vermelha indica que essa parte precisa de atenção. 5. No cartão **Webhook**, clique em **Create webhook** e confirme. O NexCMP solicita que o Stripe crie o endpoint com todos os eventos necessários e preenche o campo **Webhook signing secret** (`whsec_...`) automaticamente. A URL preenchida previamente no campo é `https:///v1/billing/stripe/webhook`, por exemplo `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Abra **Fees & limits** (`/payments/fees`), mantenha **Card (Stripe)** ativado, defina a porcentagem em **Stripe fee %** e **Stripe fixed fee (cents)** para a sua tarifa real e clique em **Save channels & fees**. Consulte [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Página do Stripe com o modo, a chave secreta e a chave publicável preenchidas com valores de exemplo](https://nexcmp.com/pt/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} O banner vermelho "Missing webhook_secret" permanece até que um segredo de assinatura seja salvo. Sem ele, as recargas pelo Stripe **não são registradas**, mesmo que o Stripe tenha cobrado o valor. | Item | Valor | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | Eventos | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | Assinatura | Cabeçalho Stripe `Stripe-Signature`, HMAC-SHA256, tolerância de 300 segundos. Solicitações com assinatura inválida recebem HTTP 400. | | Idempotência | Cada ID de evento é armazenado uma única vez; uma entrega repetida nunca credita duas vezes. | Se você atualizou a partir de uma versão que registrava menos eventos, clique em **Create webhook** novamente — o endpoint antigo é mantido, portanto exclua-o manualmente no Stripe Dashboard depois. As linhas **24h events** e **Latest event** no cartão Webhook indicam se o Stripe está alcançando o painel. Os eventos individuais são listados em **Payment channels › Gateway events** (`/payments/events`, aba Stripe), onde cada evento pode ser visualizado (**Payload**) ou reproduzido novamente (**Replay**). ### Apple Pay, Google Pay e Link {#apple-pay-google-pay-and-link} 1. No cartão **Wallets (Apple Pay · Google Pay · Link) & Alipay**, o campo **Customer app Domain registered with Stripe** vem preenchido com o nome de host do seu site (por exemplo, `cloud.example.com`). 2. Clique em **Register / verify domain** e confirme. O NexCMP registra o domínio nos domínios de métodos de pagamento do Stripe e solicita que o Stripe o valide. 3. O resultado mostra o status de **Apple Pay**, **Google Pay** e **Link**. O Apple Pay é exibido apenas quando o status é `active`. 4. Em **Fees & limits**, mantenha **Apple Pay · Google Pay · Link** ativado. ![Cartão da carteira mostrando o domínio registrado e os status do Apple Pay, Google Pay e Link](https://nexcmp.com/pt/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay permanece inativo O Apple Pay exige que o arquivo de associação de domínio responda com HTTP 200 no seu domínio público. Se você usar o Cloudflare ou outro proxy na frente, não bloqueie `/.well-known/`. ::: ### Alipay {#alipay} O Alipay é opcional. Ative-o em **Stripe Dashboard › Settings › Payment methods**, clique em **Check** e aguarde até que a caixa de diálogo mostre que o Alipay está disponível. Em seguida, ative **Alipay (Stripe, JPY display)** em **Fees & limits**. Defina **Alipay fee %**, **Alipay fixed fee**, a **¥/USD rate** (50–500) e o **FX spread %** (0–20). Atualize a taxa ¥/USD regularmente; a página avisa quando ela tiver mais de 7 dias. ## Verificar {#verify} 1. No modo de teste, faça login no portal como um cliente de teste, abra **Billing**, clique em **Deposit**, escolha **Card** e pague o valor mínimo com o cartão de teste do Stripe `4242 4242 4242 4242` (qualquer data futura, qualquer CVC). 2. O saldo aumenta em segundos e o pagamento aparece em **Finance › Billing › Top-ups** com o status *Completed*. 3. Abra **Payment channels › Gateway events › Stripe**: você deverá ver `checkout.session.completed` ou `payment_intent.succeeded` com o horário de processamento. 4. De volta à página do Stripe, **24h events** estará acima de 0. Antes de entrar em produção, altere **Mode** para `live`, cole as chaves de produção e clique em **Create webhook** novamente (os webhooks do modo de teste e de produção são separados). ## Limites e notas {#limits-notes} - **Valores e moeda.** As carteiras usam USD. Os pagamentos com cartão, carteira e link são cobrados em USD; o Alipay é exibido ao cliente em JPY e convertido à sua taxa. - **Taxas.** A taxa real do Stripe não é lida de volta automaticamente; a porcentagem de taxa definida por você determina o que o cliente visualiza e o valor creditado na carteira. Escolha **Customer pays top-up fee** em *Fees & limits* para cobrar a taxa adicionalmente. - **Cartões salvos.** Quando o cliente marca a opção *Save card for auto top-up*, o cartão é armazenado no Stripe, e não no seu servidor. Consulte [Saved payment methods](https://nexcmp.com/pt/docs/billing/saved-payment-methods/). - **Reembolsos.** O reembolso para o cartão é um processo em duas etapas: um administrador cria uma solicitação de reembolso para um pagamento concluído (**Finance › Billing › Top-ups**, ação de reembolso no pagamento) e depois a aprova em **Finance › Payouts › Card refunds** (`/billing/payouts`). Os reembolsos do Alipay são assíncronos; uma falha (`refund.failed`) devolve o valor retido para a carteira. - **Disputas.** Em `charge.dispute.created`, o NexCMP bloqueia a conta do cliente, interrompe seus serviços pré-pagos (nada é excluído) e envia um alerta ao administrador. Se você vencer (`charge.dispute.closed`), o valor é creditado de volta à carteira. - **Pagamentos em espera.** Se um webhook nunca chegar, o NexCMP verifica por conta própria os pagamentos que permaneceram pendentes por mais de 10 minutos junto ao Stripe e os conclui. Pagamentos com mais de 7 dias são ignorados. - **Resellers** podem conectar suas próprias contas do Stripe (webhook `https:///v1/billing/stripe/webhook/r/`); consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "A chave secreta deve começar com sk_live_/sk_test_" | Chave incorreta colada | Cole a chave secreta de **Developers › API keys**. | | "A chave secreta não corresponde ao modo live/test" | A modo e a chave divergem | Faça com que **Mode** corresponda ao prefixo da chave. | | "A chave publicável deve começar com pk_" | Wrong key | Use a chave publicável. | | A verificação indica que a conexão falhou | Chave incorreta, chave revogada ou o servidor não consegue alcançar `api.stripe.com` | Cole a chave novamente; teste com `curl -I https://api.stripe.com` a partir do servidor. | | Banner vermelho "Missing webhook_secret" | O segredo de assinatura não está salvo | Clique em **Create webhook** ou cole o segredo `whsec_...` do painel do Stripe e clique em **Save**. | | O pagamento foi debitado, mas o saldo não mudou | Webhook não entregue ou falha na assinatura | Verifique se a URL termina com `/v1/billing/stripe/webhook`, se o segredo corresponde ao endpoint e repita o evento em **Gateway events**. No Stripe, abra o endpoint e verifique as tentativas de entrega (HTTP 400 indica um segredo de assinatura incorreto). | | "Create webhook" fails | A URL não usa HTTPS ou não é alcançável | Use o seu domínio `https://` público. | | Status do Apple Pay inativo | Domain not validated | Clique em **Register / verify domain** novamente após o arquivo de associação de domínio retornar 200. | | Alipay não disponível no diálogo de verificação | Not activated at Stripe | Ative-o no painel do Stripe e clique em **Check**. | | O cliente não vê o formulário de cartão | **Card (Stripe)** está desativado ou falta a chave secreta | Ative-o em **Fees & limits** e salve as chaves. | --- # PayPal > **Onde encontrar no admin:** Finance › Payment channels › PayPal (`/payments/paypal`). O botão de ligar/desligar e as taxas ficam em Finance › Payment channels › Fees & limits (`/payments/fees`). ## O que faz {#what-it-does} Permite que os clientes recarreguem a carteira em USD com o saldo do PayPal, conta bancária ou cartão vinculado ao PayPal. Os clientes também podem permitir que o NexCMP lembre da conta do PayPal para [recargas automáticas](https://nexcmp.com/pt/docs/billing/auto-top-up/). Use junto com [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) para clientes que preferem o PayPal. ## Requisitos {#requirements} | Item | Requisito | |---|---| | PayPal account | Uma conta **Business** do PayPal que possa receber em USD. | | REST app | Um aplicativo REST no Painel de Desenvolvedores do PayPal (**Apps & Credentials**) que forneça um **Client ID** e um **Client secret**. Use a aba **Sandbox** para testes e **Live** para produção. | | Rede | HTTPS acessível pela Internet (o PayPal aciona o webhook) e acesso de saída para `api-m.paypal.com` (live) ou `api-m.sandbox.paypal.com` (sandbox), porta 443. | | Permissões | O aplicativo REST precisa dos recursos de reembolso e webhooks. O diálogo **Check** mostra se ambos os escopos estão presentes. | | Dependências | Nenhum. | ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Entre em [developer.paypal.com](https://developer.paypal.com) com sua conta Business e abra **Apps & Credentials**. 2. Escolha **Sandbox** (testes) ou **Live** e clique em **Create App**. Dê um nome a ele, por exemplo, "NexCMP". 3. Copie o **Client ID** e o **Secret** do aplicativo. 4. Para testes, use **Testing Tools › Sandbox Accounts** para localizar ou criar uma conta de sandbox *Personal* (comprador). 5. Você não precisa criar o webhook por conta própria; o NexCMP o cria com o botão **Create webhook**. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. Em **API keys**, escolha **Mode**: `live` (dinheiro real, `api-m.paypal.com`) ou `sandbox` (`api-m.sandbox.paypal.com`). 3. Cole o **Client ID** (pelo menos 20 caracteres) e o **Client secret**. 4. Clique em **Check**. Isso testa as credenciais digitadas (salvar não é obrigatório) e relata a conexão, o App ID, o modo, se os escopos de reembolso e webhooks estão presentes e por quanto tempo o token dura. 5. Clique em **Save**. 6. No cartão **Webhook**, confirme se a URL é `https:///v1/billing/paypal/webhook` (ela deve ser `https`), clique em **Create webhook** e confirme. O NexCMP solicita que o PayPal crie ou atualize o webhook com 11 eventos e armazena o **Webhook ID** retornado. O botão usa as chaves **salvas** — salve primeiro caso tenha acabado de editá-las. 7. Clique em **Check** novamente: a linha **Webhook** deve exibir "exists, 11 events". 8. Abra **Fees & limits**, ative **PayPal**, defina **PayPal fee %** (padrão 4.4) e **PayPal fixed fee (cents)** (padrão 30) para a sua tarifa e clique em **Save channels & fees**. ![Página do PayPal com o modo sandbox e credenciais de exemplo inseridas](https://nexcmp.com/pt/docs/images/billing/paypal-01-keys.webp) ### Eventos de webhook {#webhook-events} O NexCMP registra estes 11 eventos: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Cada webhook é verificado chamando a API de verificação de assinatura do PayPal, armazenado uma única vez e processado de forma idempotente. O NexCMP nunca confia no valor presente no corpo do webhook: antes de creditar uma captura, ele busca a captura diretamente no PayPal. ## Verificar {#verify} 1. Mantenha **Mode** em `sandbox`. No portal, abra **Billing › Deposit**, escolha **PayPal**, clique em **Continue on PayPal** (ou no botão do PayPal) e faça login com a conta de comprador de sandbox. 2. Aprove o pagamento. Você retornará ao portal, o saldo aumentará e o pagamento aparecerá em **Finance › Billing › Top-ups** como *Completed*. 3. Abra **Payment channels › Gateway events › PayPal & USDT**: o evento `PAYMENT.CAPTURE.COMPLETED` estará listado. 4. Quando tudo estiver funcionando, altere **Mode** para `live`, insira as credenciais de produção, clique em **Save** e, em seguida, em **Create webhook** novamente (os webhooks de sandbox e de produção são separados). ## Limites e notas {#limits-notes} - **Como um pagamento é concluído.** O pedido é criado em USD; após o cliente aprová-lo, o **server** faz a captura (com ID de requisição idempotente) e credita a carteira exatamente uma vez. O webhook e uma rotina de conciliação executada a cada 10 minutos servem como redes de segurança caso o cliente feche o navegador. - **Pedidos pendentes e abandonados.** Um pedido pode permanecer aberto por 12 horas. Um cliente pode ter no máximo 5 pedidos pendentes (o servidor responde `too_many_pending`, HTTP 429). Um pedido que ainda não tenha sido capturado após 24 horas é marcado como falhou. - **Nenhum webhook configurado.** O painel responde HTTP 503 a todos os webhooks do PayPal até que um Webhook ID seja salvo. Capturas feitas pelo portal e a conciliação de 10 minutos ainda creditam a carteira, mas nada relatado pelo PayPal via webhook (disputas, estornos, capturas tardias) é aplicado — clique em **Create webhook**. - **Conta do PayPal salva.** Quando o cliente opta por salvar o PayPal (ou conclui o primeiro depósito, o que ativa a [recarga automática](https://nexcmp.com/pt/docs/billing/auto-top-up/)), o PayPal armazena o token de pagamento em seu cofre. O NexCMP mantém apenas um identificador e o e-mail do PayPal. Consulte [Saved payment methods](https://nexcmp.com/pt/docs/billing/saved-payment-methods/). - **Reembolsos e disputas** são tratados da mesma forma que no Stripe: solicitações de reembolso são aprovadas em **Finance › Payouts › Card refunds**; uma disputa bloqueia a conta do cliente e suspende seus serviços pré-pagos até que você a resolva. - **Taxas.** A taxa do PayPal não é lida de volta; a porcentagem e a taxa fixa configuradas determinam o que o cliente vê e o que é creditado. A tarifa real depende do seu país (o formulário sugere 4.4 % para o Vietnã e 3.49 % para os EUA). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Client ID muito curto" | Menos de 20 caracteres colados | Copie o Client ID completo. | | "A URL do webhook deve ser https" | URL digitada com `http://` | Use o seu domínio `https://` público. | | A verificação relata um erro de conexão | Modo incorreto (chaves de produção em sandbox ou vice-versa), segredo incorreto, sem acesso de saída | Faça corresponder **Mode** ao tipo de chave; teste `curl -I https://api-m.paypal.com` a partir do servidor. | | Escopo de reembolso / webhooks mostra "no" | O aplicativo REST não possui os recursos | Ative os recursos no aplicativo no Painel de Desenvolvedor do PayPal. | | Banner "Chave do PayPal definida, SEM webhook" | ID do webhook ausente | Clique em **Create webhook**. | | "Webhook not found" na Verificação | O webhook foi excluído no PayPal ou pertence a outro aplicativo | Clique em **Create webhook** novamente. | | O cliente recebe a informação de que o PayPal recusou o pagamento | O PayPal rejeitou essa fonte de financiamento | Peça ao cliente para escolher outra fonte de pagamento. | | O cliente vê "Too many pending requests" | 5 pedidos abertos | Aguarde até que expirem ou conclua-os. | | Botão do PayPal ausente | PayPal desativado em **Fees & limits** ou não configurado | Ative-o e salve as credenciais. | --- # USDT (Binance) {#usdt-binance} > **Onde no admin:** Finance › Payment channels › USDT (`/payments/usdt`). Alternar e taxa: Finance › Payment channels › Fees & limits (`/payments/fees`). Depósitos não correspondidos: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## O que faz {#what-it-does} Os clientes enviam USDT para **seu endereço de depósito da Binance**; o NexCMP lê o histórico de depósitos por meio de uma chave de API da Binance **somente leitura** e credita a carteira quando um depósito corresponde a uma solicitação aberta. Não há taxa de processamento de pagamento do seu lado, além do que a Binance cobra, e nenhuma chave privada é armazenada pelo NexCMP. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Conta Binance | Uma conta da Binance verificada com depósitos de USDT habilitados na rede escolhida. | | Chave de API | Uma chave de API da Binance apenas com **Enable Reading** ativado. Os recursos Enable Withdrawals, Internal Transfer e Spot/Margin Trading devem estar **desativados**. | | Restrição de IP | Altamente recomendável: restrinja a chave ao IP de saída do servidor (a caixa de diálogo **Test & verify address** o exibe). | | Rede | HTTPS de saída para `api.binance.com`. Nenhuma porta de entrada é necessária. | | Redes suportadas | `TRX` (Tron, TRC20), `BSC` (BNB Smart Chain, BEP20), `SOL` (Solana), `ETH` (Ethereum, ERC20). A criptomoeda é fixa em USDT. | | Dependências | Nenhum. | ::: warning Escolha a rede uma única vez Os clientes que enviarem pela rede errada perderão os fundos. Escolha a rede com taxas baixas suportada pelas corretoras dos seus clientes (TRX e BSC são as opções habituais) e não a altere com frequência. ::: ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Na Binance, abra **Account › API Management** e crie uma nova chave de API (gerada pelo sistema). Dê a ela um rótulo como "NexCMP". 2. Edite as permissões: deixe marcado apenas **Enable Reading**. Não ative saques, transferências ou negociações. 3. Em **Restrict access to trusted IPs only**, adicione o endereço IP público do seu servidor NexCMP. Se ainda não souber qual é, crie a chave sem a restrição, execute o primeiro teste no NexCMP (ele exibirá o IP de saída) e adicione o IP em seguida. 4. Copie a **API key** e a **Secret key** (a chave secreta é exibida apenas uma vez). 5. Abra **Wallet › Deposit › Crypto**, escolha **USDT** e a **rede** que você vai usar, e copie o **endereço de depósito** (por exemplo, um endereço `T...` em TRX ou `0x...` em BSC/ETH). ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › USDT** (`/payments/usdt`). 2. Em **API key (Binance › API Management)**, cole a **API key** e o **API secret**. Ambos devem ser inseridos juntos. 3. Em **Deposit address**, escolha a **Network** e cole o **endereço de depósito USDT na rede selecionada**. O formato é validado de acordo com a rede (`T` + 33 caracteres para TRX, `0x` + 40 caracteres hexadecimais para BSC e ETH, base58 para SOL). 4. Clique em **Save**. Alterar o endereço ou a rede redefine a verificação e pausa o canal até que você o verifique novamente; a página pedirá confirmação. 5. Clique em **Test & verify address**. (Alterações não salvas são recusadas — a verificação é executada com base na configuração salva.) O diálogo exibe: - permissões da chave (leitura, saques, transferência interna, negociação, restrição de IP) — avisos em vermelho para permissões perigosas; - o IP de saída do servidor (para inserir na Binance); - a rede (depósitos abertos ou fechados, confirmações necessárias, poeira/dust); - o endereço que a Binance emite para essa rede e se ele **coincide** com o seu. 6. Quando o endereço coincidir, o NexCMP registra o horário da verificação. Só então você poderá abrir **Fees & limits**, ativar **USDT (Binance)**, verificar **USDT fee %** (padrão 1) e **USDT request expires after (mins)** (5–180, padrão 30), e clicar em **Save channels & fees**. ## Como um pagamento é correspondido {#how-a-payment-is-matched} 1. O cliente insere um valor em **Billing › Deposit › USDT** e clica em **Get deposit address**. 2. O NexCMP cria uma solicitação e exibe o endereço, a rede e um **valor exato** com seis casas decimais — por exemplo `19.173742`. Os últimos quatro decimais são um nonce aleatório que torna o valor exclusivo para essa solicitação. 3. O cliente deve enviar **exatamente** esse valor nessa rede. Um pagamento que não corresponda (valor arredondado, rede incorreta) não pode ser atribuído automaticamente. 4. A cada 60 segundos, o NexCMP lê os depósitos da Binance das últimas 24 horas. Um depósito correspondente move a solicitação para *confirming* e, assim que a Binance obtém as confirmações necessárias, credita a carteira. Uma solicitação que já recebeu fundos nunca expira enquanto as confirmações estiverem pendentes. 5. Uma solicitação não paga dentro do tempo de expiração (padrão de 30 minutos) é marcada como expirada. ## Verificar {#verify} 1. Depois que o endereço for verificado e o USDT estiver ativado, faça login como um cliente de teste e solicite um pequeno depósito (o valor mínimo de recarga). 2. Envie o valor exato de outra carteira ou corretora. Aguarde alguns minutos. 3. O portal exibe *Transfer seen — confirming*, seguido por *USDT received — balance updated*. 4. A página de USDT exibe um horário recente em **Last poll** e **Unmatched** em 0. ## Limites e notas {#limits-notes} - **Taxa.** 1 USDT = 1.00 USD. A taxa em **USDT fee %** é exibida ao cliente e deduzida ou adicionada ao valor, dependendo de **Customer pays top-up fee**. - **Sem reembolsos.** Os pagamentos em USDT nunca são reembolsados à origem pelo NexCMP (HTTP 409 `usdt_no_refund`). Faça o reembolso manualmente fora do sistema se necessário. - **Limite de pendências.** Um cliente tem um número limitado de solicitações abertas; além disso, o servidor responde com `too_many_pending` (HTTP 429). - **Resellers** podem usar sua própria conta da Binance; consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). - **Se você compartilhar a conta da Binance** com outro sistema, dê a cada sistema uma rede diferente para que dois coletores nunca vejam o mesmo depósito. ### Depósitos não correspondidos {#unmatched-deposits} Um depósito que não corresponde a nenhuma solicitação (valor incorreto, rede incorreta, solicitação expirada) cria um evento `deposit.unmatched` e um alerta de administrador. Abra **Payment channels › Gateway events › PayPal & USDT**, localize o evento, verifique a transação na Binance e clique na ação de atribuição para creditar o cliente correto. O contador **Unmatched** na página de USDT e na visão geral dos canais cai para 0 posteriormente. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "A chave de API e o segredo devem ser inseridos juntos" | Apenas um campo preenchido | Preencha ambos. | | "O endereço não está no formato de rede ..." | O endereço não corresponde à rede selecionada | Copie-o novamente da Binance para a mesma rede. | | "Alterações não salvas — Salve primeiro e depois teste" | O teste é executado nas configurações salvas | Clique em **Save** e, em seguida, teste. | | Aviso "key has Enable Withdrawals" | Permissão excessiva | Remova-a no Gerenciamento de API da Binance. | | Aviso "key not restricted to IP" | `ipRestrict` está desativado | Adicione o IP de saída do servidor mostrado na caixa de diálogo. | | Aviso "key lacks Enable Reading" | Permissão ausente | Ative a Leitura (Enable Reading). | | Aviso "Binance has deposits disabled for USDT on the network" | Rede suspensa | Escolha outra rede ou aguarde. | | "PERIGO: o endereço configurado difere do endereço emitido pela Binance" | Endereço ou rede incorretos | Copie o endereço novamente da Binance para essa rede. | | Alternância de USDT esmaecida em Fees & limits | Endereço não verificado | Execute **Test & verify address** até que corresponda. | | Cliente pagou, nada creditado | Valor arredondado ou rede incorreta | Encontre o evento em Gateway events e atribua-o manualmente. | | Depósito visto, mas aguardando há muito tempo | Confirmações insuficientes ainda | Aguarde; a solicitação não expira durante a confirmação. | --- # Transferência bancária (Vietnã) {#bank-transfer-vietnam} > **Onde no admin:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Taxa de câmbio: Finance › Payment channels › Exchange rates (`/payments/fx`). ## O que faz {#what-it-does} Permite que os clientes recarreguem a carteira em USD por meio de uma transferência bancária normal em dong vietnamita. O NexCMP exibe um código VietQR, os detalhes da conta e um **transfer memo** exclusivo; o [Sepay](https://sepay.vn) monitora sua conta bancária e chama um webhook quando o dinheiro chega, e o NexCMP credita a carteira. Use-o se você vende para clientes no Vietnã. ::: info Mostrado apenas na interface vietnamita A opção de banco do Vietnã é oferecida ao cliente apenas quando o portal é exibido em **Vietnamese**. Clientes em qualquer outro idioma nunca a veem. ::: ## Requisitos {#requirements} | Item | Requisito | |---|---| | Conta bancária | Uma conta bancária vietnamita (ou uma conta virtual Sepay, **VA**) conectada a uma conta Sepay em [my.sepay.vn](https://my.sepay.vn). | | Sepay | Uma conta Sepay com integração de webhook ativada. | | Taxa de câmbio | É preciso que exista uma taxa de câmbio de USD para VND: atualize-a primeiro em **Exchange rates**. Sem uma taxa, o canal responde `fx_unavailable` e os clientes não conseguem iniciar uma transferência. | | Rede | Seu painel deve estar acessível por HTTPS para que o Sepay possa chamar `https:///v1/billing/sepay/webhook`. | | Dependências | [Moeda e taxas de câmbio](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). | ## Preparar a infraestrutura {#prepare-the-infrastructure} No lado do Sepay: 1. Em [my.sepay.vn](https://my.sepay.vn), conecte sua conta bancária (ou crie uma VA) e certifique-se de que as transações apareçam. 2. Defina o **prefixo do memorando** — 2 a 5 letras maiúsculas, por exemplo `PAY`. O NexCMP gera o memorando como o prefixo seguido por 8 dígitos aleatórios (por exemplo `PAY48210937`). O prefixo não deve conter `ORD` e não deve ser usado por nenhum outro sistema que receba dinheiro na mesma conta. 3. Se a sua conta Sepay usar uma *estrutura de código de pagamento*, registre o mesmo prefixo lá para que o Sepay reconheça o memorando. 4. Crie o webhook mais tarde, após a página do NexCMP fornecer a URL e a chave (etapa 7 abaixo). ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › Exchange rates** e clique em **Update exchange rates** se nenhuma taxa tiver sido armazenada. 2. Abra **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. Em **Receiving account**, preencha: | Campo | Exemplo | Regra | |---|---|---| | Banco | `VCB` Vietcombank | Escolha na lista; o BIN é preenchido automaticamente. | | Número da conta | `0123456789` | 4–24 dígitos ou letras maiúsculas. | | Conta virtual (VA — opcional) | | Se definida, os clientes transferem para a VA e o QR code a exibe. | | Nome do titular da conta | `NGUYEN VAN A` | Sem acentos, MAIÚSCULAS, 2–60 caracteres. | | Prefixo do memorando de transferência | `PAY` | 2–5 letras maiúsculas, sem `ORD`. | 4. Em **Webhook authentication**, escolha **Auth method**: **HMAC-SHA256** (recomendado) ou **API key** e insira a **Webhook key / HMAC secret** (8–200 caracteres). Opcionalmente, insira o **userapi token** do Sepay; ele é usado apenas para reconciliar transferências cujo webhook foi perdido. 5. Em **Channel & limits**, defina os limites (padrões entre parênteses): **Min / order** (10,000 VND), **Max / order** (200,000,000 VND), **Order expiry** (120 minutos, 15–1440), **Max pending orders / account** (3, 1–10), **Reconcile every** (10 minutos) e, opcionalmente, **Allowed webhook IPs** (separados por vírgula; vazio significa que o IP é apenas registrado). 6. Clique em **Save**. O banner vermelho "Sepay not configured" desaparece assim que a conta, o nome, o prefixo e a chave forem válidos. 7. Copie a **Webhook URL to paste into my.sepay.vn** (ela exibe `https:///v1/billing/sepay/webhook`) com **Copy**. No Sepay, abra a integração de webhook, cole a URL, escolha o mesmo tipo e chave de autenticação e ative o evento "money in". 8. Clique em **Test connection**. Em seguida, ative **Enable Sepay for clients (main site)** e **Save**. ![Página de transferência bancária VN com a conta de recebimento, o prefixo do memorando e a autenticação de webhook preenchidos com valores de exemplo](https://nexcmp.com/pt/docs/images/billing/bank-transfer-vn-01-config.webp) ![Card de canal e limites com o botão do Sepay ativado e os limites padrão](https://nexcmp.com/pt/docs/images/billing/bank-transfer-vn-02-limits.webp) ### Segurança do webhook {#webhook-security} | Método | O que o Sepay deve enviar | |---|---| | HMAC-SHA256 | Cabeçalho `X-SePay-Signature: sha256=`, calculado sobre `"."`; o carimbo de data/hora pode diferir em no máximo 300 segundos. | | Chave de API | Cabeçalho `Authorization: Apikey `. | Apenas os cabeçalhos são verificados (nunca o corpo ou a query string) e a comparação é de tempo constante. Apenas transferências de entrada (`transferType = in`) para sua conta configurada ou VA são usadas. Cada transação do Sepay é armazenada uma única vez, portanto um webhook retentado nunca credita duas vezes. O NexCMP responde com `200 {"success":true}` mesmo quando ignora deliberadamente uma transação, e HTTP 5xx apenas para erros temporários para que o Sepay retente. ## Como o cliente paga {#how-the-customer-pays} 1. Em **Billing › Deposit** (interface em vietnamita), o cliente escolhe a opção de transferência bancária em VND e um valor, depois clica no botão de criar transferência. 2. O NexCMP converte o valor em USD na taxa armazenada (incluindo a margem e a etapa de arredondamento definidas em **Exchange rates**) e **arredonda o valor em VND para cima** até a etapa de arredondamento. 3. O cliente vê um QR code (VietQR, gerado localmente) com o número da conta, banco, valor e memorando. 4. Após a transferência, o Sepay chama o webhook e o NexCMP credita `floor(VND received × 100 / rate)` centavos. A taxa é fixada quando o pedido é criado; se o dinheiro chegar após o pedido expirar, usa-se a maior entre a taxa fixada e a atual. 5. Os pedidos expiram após **Order expiry**; a reconciliação é executada a cada **Reconcile every** minutos como rede de segurança (requer o token userapi). ## Verificar {#verify} 1. Crie um pedido de teste como cliente na interface em vietnamita. Verifique se o valor, a conta e o memorando estão corretos. 2. Transfira o menor valor permitido com o memorando exato. 3. Em até um minuto, o portal mostra o depósito como concluído e a carteira aumenta; o cartão **State** na página do banco mostra a hora do último webhook. 4. Abra **Finance › Billing › Top-ups** e verifique se o pagamento está listado com o valor em VND recebido. ## Limites e notas {#limits-notes} - **Mínimo.** O valor mínimo em VND que o cliente vê é o maior entre **Min / order** e o valor em VND do [minimum top-up](https://nexcmp.com/pt/docs/billing/minimum-top-up/). - **Pedidos pendentes.** Um cliente pode ter apenas **Max pending orders / account** pedidos em aberto (padrão 3). - **Mesmo memorando duas vezes.** Transferir duas vezes com o mesmo memorando cria um segundo pagamento concluído à taxa atual. - **Sem reembolso automático** para uma conta bancária. - **Taxa.** O canal não possui uma linha de taxa fixa em **Fees & limits**; a margem da taxa é o único ajuste. - **Resellers** podem configurar sua própria conta; a URL do webhook deles termina com `/v1/billing/sepay/webhook/r/`. ### Transferências não correspondidas {#unmatched-transfers} O dinheiro que chegou à conta, mas não traz um memorando válido, aparece em **Unmatched transactions** na parte inferior da página (filtre por *All channel owners* ou *Master*). Verifique a referência bancária com o cliente, clique em **Assign** e selecione a conta. A carteira é creditada à taxa atual. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Banner "Sepay não configurado" | Banco, conta, nome do titular, prefixo ou chave ausentes ou inválidos | Preencha os cartões **Receiving account** e **Webhook authentication**. | | Banner "Taxa USD/VND bloqueada" (`fx_unavailable`) | Nenhuma taxa de câmbio armazenada | **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | Prefixo inválido | Use de 2 a 5 letras maiúsculas sem `ORD`. | | Erro `account_name` | Acentos ou letras minúsculas | Use letras MAIÚSCULAS sem acento, dígitos, espaço, ponto ou hífen. | | `webhook_secret: 8–200 characters` | Chave muito curta | Use pelo menos 8 caracteres imprimíveis. | | O cliente não consegue ver a opção | Não está na interface em vietnamita, desativado ou sem taxa | Verifique o idioma, o interruptor e a taxa. | | Cliente pagou, mas nada foi creditado | O webhook não chegou, memorando alterado, valor incorreto | Verifique o log de webhook do Sepay; a transferência ficará em **Unmatched transactions** se o memorando estiver incorreto. | | O webhook retorna 401 ou 403 | Incompatibilidade no método de autenticação ou na chave | Use o mesmo método e chave no Sepay e no NexCMP. | | O cliente vê "Too many pending requests" | Limite de pedidos pendentes atingido | Eles terminam ou aguardam a expiração. | --- # Recarga mínima {#minimum-top-up} > **Onde no admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), cartão **Wallet & top-up (Billing › Policy)**. ## O que faz {#what-it-does} Cada canal de pagamento rejeita um valor abaixo da **recarga mínima** ou acima da **recarga máxima por transação**. Os padrões são **$10.00** e **$5,000.00**. Use o mínimo para evitar pagamentos minúsculos cujas taxas de gateway superam o valor. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Dependências | Nenhum. | ## Definir os limites {#set-the-limits} 1. Abra **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. No cartão **Wallet & top-up (Billing › Policy)**, edite **Min top-up (USD)** e **Max top-up per transaction (USD)**. 3. Clique em **Save Wallet & top-up**. ![Cartão de carteira e recarga com a recarga mínima de 10.00 e a máxima de 5000.00](https://nexcmp.com/pt/docs/images/billing/minimum-top-up-01-limits.webp) | Configuração | Padrão | Intervalo permitido | Regra | |---|---|---|---| | Min top-up (USD) | $10.00 | $0 a $10,000 | Deve ser menor ou igual ao máximo. | | Recarga máxima por transação (USD) | $5,000.00 | $1 a $1,000,000 | Deve ser pelo menos o mínimo. | Os valores são armazenados em centavos (`min_topup_cents`, `max_topup_cents`). ## Onde os limites se aplicam {#where-the-limits-apply} | Local | Comportamento | |---|---| | Cartão, Apple/Google Pay, Link, Alipay, PayPal, USDT | Valores fora do intervalo são recusados pelo servidor. O portal exibe "Enter an amount between {min} and {max}". | | Transferência bancária VN | O valor em VND deve estar dentro dos limites do Sepay **e** o seu valor em USD (o que a carteira recebe) dentro do mínimo e do máximo. O portal exibe o maior dos dois mínimos em VND. Consulte [Bank transfer (Vietnam)](https://nexcmp.com/pt/docs/billing/bank-transfer-vn/). | | [Automatic top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/) | Cada cobrança automática é de pelo menos o mínimo e no máximo o máximo. No modo fixo, o valor do cliente deve estar entre o mínimo e $1,000. | | Códigos de recarga ([Vouchers](https://nexcmp.com/pt/docs/billing/promotions/)) | Não afetado. | | Crédito / débito do admin | Não afetado. | | Recarga da carteira de revendedor | Um mínimo separado (`rs_topup_min_cents`, padrão $20) em Resellers › Defaults. | ## Limites relacionados {#related-floors} A recarga mínima não é a única regra de saldo. Elas estão em **Services › Virtual Machines › Policy** (`/vm/policy`): | Regra | Padrão | Significado | |---|---|---| | Saldo mínimo (`min_balance_cents`) | $5.00 | O saldo de carteira mínimo que um cliente precisa para criar uma VM. | | Quotas | Desligado | Quando as **Quotas** estão ativadas, a criação de uma VM também requer um saldo que cubra um número de horas dessa VM. Veja [Quotas](https://nexcmp.com/pt/docs/billing/quotas/). | ## Verificar {#verify} 1. No portal, abra **Billing › Deposit** e digite um valor logo abaixo do seu mínimo. O botão de pagamento é desativado e a mensagem de intervalo aparece. 2. Insira o mínimo e confirme que o pagamento é iniciado. ## Limites e notas {#limits-notes} - Uma alteração se aplica a novos pagamentos. Os pedidos já criados mantêm os valores com os quais foram criados. - A dica voltada para o cliente ("Minimum $10.00, maximum $5,000.00") e os botões de valor rápido seguem os novos limites automaticamente. - Se você exibir VND (a página **Exchange rates**), o mínimo é convertido à taxa armazenada apenas para exibição; a carteira e os limites permanecem em USD. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Minimum top-up must be less than or equal to the maximum | Valores cruzados | Diminua o mínimo ou aumente o máximo. | | O cliente não pode pagar um valor pequeno por transferência bancária vietnamita | O mínimo em VND do Sepay ou o mínimo em USD é maior | Diminua **Min / order** na página do banco ou o mínimo em USD. | | Erro de servidor `invalid_argument` em uma recarga | Valor fora do intervalo | Solicite um valor dentro do intervalo exibido. | --- # Saved payment methods {#saved-payment-methods} > **Onde no portal:** Billing › Settings (`/billing?settings=1`). **Onde no admin:** Customers › List › a customer › Overview (`/customers/`), cartão **Payment**, mostra o método salvo e o histórico de recarga automática. ## O que faz {#what-it-does} Um método de pagamento salvo permite que o NexCMP faça cobranças de um cliente **sem a presença dele**, para que seus serviços nunca parem porque a carteira esvaziou. Ele é usado apenas pela [automatic top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/). Existem dois tipos: um **cartão** salvo na Stripe (incluindo cartões usados via Apple Pay, Google Pay ou Link quando a Stripe retorna um cartão reutilizável) e uma **conta PayPal** armazenada no cofre do PayPal. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Canais | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) e/ou [PayPal](https://nexcmp.com/pt/docs/billing/paypal/) configurados e ativados. | | Site | O site principal ou um site de revendedor cujo canal de pagamento é coletado pela plataforma. Um site de revendedor que usa sua própria conta Stripe não pode salvar cartões. | | Cliente | Uma conta de cliente que fez uma recarga com o cartão ou PayPal. | ## Como um método é salvo {#how-a-method-gets-saved} 1. O cliente abre **Billing**, clica em **Deposit** e paga com **Card** ou **PayPal**. 2. O pagamento é criado para que o método possa ser reutilizado posteriormente: a Stripe armazena o cartão junto ao cliente na Stripe (uso fora de sessão), o PayPal armazena um token de cofre. O NexCMP mantém apenas referências (um ID de método de pagamento e ID de cliente da Stripe, ou o ID do cofre do PayPal) e um rótulo de exibição como `visa •••• 4242` ou o e-mail do PayPal. **Os números dos cartões nunca tocam no seu servidor.** 3. Quando o pagamento é concluído, a [automatic top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/) é ativada uma única vez se o cliente nunca tiver escolhido configurações antes. Não há nenhuma caixa de seleção ou mensagem extra na tela. O servidor registra a hora, o endereço IP do cliente e o método como evidência. 4. Na próxima vez, a tela de depósito oferece **Saved card ...** no menu suspenso de cartões e **Saved PayPal ...** para o PayPal. ## Gerenciar e remover {#manage-and-remove} 1. No portal, vá para **Billing** e clique em **Settings**. O painel mostra os métodos salvos (cartão Stripe e/ou PayPal) e as opções de recarga automática. 2. Para remover um cartão, clique em **Remove card** e confirme. O Stripe desvincula o cartão e **o auto top-up é desativado**. 3. Para remover o PayPal, clique em **Remove saved PayPal** e confirme. ### Visão do administrador {#admin-view} Abra o cliente em **Customers › List**. O cartão **Payment** na aba **Overview** exibe os rótulos dos métodos salvos (**Saved cards**), o gateway usado para cobranças automáticas, o registro de consentimento armazenado (hora, IP, método) e as últimas 20 tentativas de cobrança automática com seus status e motivos (**Auto top-up history**). ## Verificar {#verify} 1. Como cliente de teste, deposite o valor mínimo usando o cartão. Após a conclusão do pagamento, abra **Billing › Settings**: o cartão e a chave de auto top-up (ligada) estarão visíveis. 2. Inicie outro depósito: o menu suspenso oferece o cartão salvo. 3. No painel administrativo, o cartão **Payment** do cliente exibe o mesmo rótulo do cartão. ## Limites e notas {#limits-notes} - **Stripe Link e carteiras.** Link, Apple Pay e Google Pay são recursos do Stripe. O NexCMP não armazena nada específico do Link; ele apenas mantém a referência do cartão retornada pelo Stripe. - **PayPal.** Cada recarga do PayPal iniciada pelo cliente requer um clique; o PayPal salvo é usado apenas pelo auto top-up, nunca por outros recursos. - **Sites de revendedores.** Se um revendedor usar sua própria conta do Stripe ou PayPal, os métodos salvos ficam ocultos e o auto top-up fica indisponível para esse site. - **Disputas.** Uma disputa em qualquer pagamento bloqueia a conta e interrompe seus serviços pré-pagos; consulte [Stripe](https://nexcmp.com/pt/docs/billing/stripe/). - **Remover o último método** desativa o auto top-up; o cliente mantém o saldo da carteira. - **Evidência.** O registro de consentimento é gravado pelo servidor (não editável pelo cliente) e é mantido para o tratamento de disputas. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O cliente não vê o botão de configurações nem o cartão salvo | O site usa um canal de pagamento pertencente ao revendedor ou ainda não há pagamento com cartão | Faça uma recarga por cartão ou PayPal através do canal da plataforma. | | "Saved card" ausente após um pagamento via Stripe | O pagamento foi feito com um método que não pode ser reutilizado (por exemplo, Alipay) | Pague novamente usando um cartão. | | PayPal: "ainda não é possível salvar esta conta" | O PayPal não retornou um token de cofre (vault token) | Continue com um pagamento único ou tente outra conta do PayPal. | | O auto top-up parou após a remoção do cartão | Esperado: remover o cartão desativa o recurso | Salve um novo método no próximo depósito. | --- # Auto top-up {#auto-top-up} > **Onde encontrar no admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), card **Wallet & top-up (Billing › Policy)**, section **Auto top-up (Stripe / PayPal)**. **Onde encontrar no portal:** Billing › Settings (`/billing?settings=1`). ## O que faz {#what-it-does} Quando o saldo da carteira de um cliente fica muito baixo, o NexCMP cobra o seu [saved payment method](https://nexcmp.com/pt/docs/billing/saved-payment-methods/) e credita a carteira, para que os serviços em execução não sejam suspensos por falta de fundos. Uma tarefa em segundo plano verifica todos os clientes habilitados **a cada 5 minutos**. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Canal | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) e/ou [PayPal](https://nexcmp.com/pt/docs/billing/paypal/) configurados. | | Método salvo | O cliente possui um cartão ou conta do PayPal salvos. | | Site | Site principal ou site de revendedor cujo canal do Stripe/PayPal é coletado pela plataforma. | | Chave global | **Auto top-up enabled** está ativado (ativado por padrão). | ## Como funciona {#how-it-works} Após a **primeira recarga no Stripe ou PayPal** do cliente, o servidor salva a forma de pagamento e ativa a recarga automática no modo **By usage** — apenas se o próprio cliente nunca tiver configurado a recarga automática. Não há nenhuma caixa de seleção extra na tela de depósito; o servidor registra o horário, o endereço IP e o método como comprovação. Se o cliente desativar a recarga automática mais tarde, ela nunca será reativada automaticamente. | Modo | Gatilho (quando o saldo estiver abaixo de...) | Valor cobrado | |---|---|---| | **By usage** (padrão após a primeira recarga) | o custo das próximas 24 horas de serviços em execução (VMs por hora mais renovações pré-pagas vencidas em 24 horas), mas nunca abaixo de **$5** | o custo de 24 horas arredondado para cima para o dólar inteiro, pelo menos a [minimum top-up](https://nexcmp.com/pt/docs/billing/minimum-top-up/), no máximo a recarga máxima e o limite diário | | **Fixed amount** | o limite próprio do cliente ($1 a $500) | o valor do próprio cliente (do valor mínimo de recarga até $1,000, e superior ao limite) | Sem nenhum serviço em execução no modo **By usage**, nada é cobrado. O saldo comparado com o limite é o **dinheiro real na carteira**. Os créditos de serviço de códigos promocionais são mantidos separadamente e não contam (consulte [Promotions](https://nexcmp.com/pt/docs/billing/promotions/)). A taxa é tratada como uma recarga normal: com **Customer pays top-up fee** ativado, o cartão é cobrado no valor mais a taxa e a carteira recebe o valor total; com ele desativado, a carteira recebe o valor menos a taxa. ## Configurar os limites globais {#configure-the-global-limits} 1. Abra **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. Em **Auto top-up (Stripe / PayPal)**, defina: | Configuração | Padrão | Intervalo | Significado | |---|---|---|---| | Auto top-up enabled | On | ativado ou desativado | Desativado interrompe todas as cobranças em segundo plano imediatamente. | | Limite padrão de recarga automática (USD, fallback do modo fixo) | $5.00 | $0 a $10,000 | Usado apenas como o limite inicial no modo fixo. | | Máximo de recargas automáticas por 24 h por cliente | 3 | 1 a 50 | Conta tentativas bem-sucedidas e pendentes. | | Teto do valor de recarga automática por 24 h por cliente (USD) | $500.00 | $0 a $1,000,000 | Total de cobranças automáticas em um dia contínuo. | 3. Clique em **Save Wallet & top-up**. ![Seção Auto top-up da página Fees and limits com o botão global e limites diários](https://nexcmp.com/pt/docs/images/billing/auto-top-up-01-limits.webp) ## O que o cliente vê {#what-the-customer-sees} 1. No portal, o cliente abre **Billing** e clica em **Settings**. 2. O painel mostra os métodos salvos, o botão de ligar/desligar, o modo (**By usage** ou **Fixed amount**), o uso atual estimado, a próxima cobrança e as **Recent automatic top-ups**. 3. Mudar para **Fixed amount** permite que eles insiram o limite e o valor. Desativar a chave interrompe as cobranças. ![Configurações de faturamento do cliente com recarga automática no modo By usage e as recargas automáticas recentes](https://nexcmp.com/pt/docs/images/billing/auto-top-up-02-portal.webp) ## Verificar {#verify} 1. Como cliente de teste, faça uma primeira recarga com um cartão de teste ([Stripe](https://nexcmp.com/pt/docs/billing/stripe/#verify)). Abra **Billing › Settings**: a recarga automática está ativada. 2. Execute uma pequena VM para que haja uso e reduza o saldo abaixo do limite (por exemplo, com **Customers › customer › Credit / debit**). 3. Em cerca de 5 minutos, uma cobrança é realizada. No cartão **Overview › Payment** do cliente, **Auto top-up history** mostra a tentativa com o status *Done*, e uma notificação de *Top-up received* é enviada. ## Limites e notas {#limits-notes} - **Uma cobrança por queda.** Após uma cobrança, o job aguarda até que o saldo suba novamente acima do limite ou o tempo de espera termine: 1 hora após um sucesso, 24 horas após uma cobrança pendente, 30 minutos após um erro do sistema. - **Limites diários.** Quando qualquer um dos limites diários é atingido, nenhuma cobrança é feita e uma linha *Daily limit reached* é registrada (no máximo uma vez a cada 6 horas). - **Falhas.** Um cartão recusado, cartão expirado ou fundos insuficientes conta como falha no cartão. O job tenta novamente após 1 hora, depois 6 horas, depois 24 horas. **Após 3 falhas consecutivas no cartão, a recarga automática é desativada** e o cliente é notificado (*Auto top-up failed*). Um pagamento que exija a confirmação do cliente (por exemplo, 3-D Secure) não é contado como falha; o cliente é orientado a confirmá-lo. - **Sem cobranças duplicadas.** Cada cobrança é solicitada de forma atômica por queda abaixo do limite e usa uma chave de idempotência no gateway. - **Remover o cartão** desativa a recarga automática. - **Revendedores.** Se um revendedor usar seu próprio canal de pagamento, o cliente não poderá ativar a recarga automática (HTTP 403 `feature_disabled`). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O cliente não consegue ativá-la: "Top up once with a card or PayPal" | Nenhum método salvo | Faça uma primeira recarga com cartão ou PayPal. | | Erro `no_card` (422) | O gateway escolhido não possui método salvo | Escolha o gateway que possui um ou salve um método. | | Erro `invalid_argument` no valor | Modo fixo fora dos intervalos permitidos | Limite de $1 a $500, valor entre a recarga mínima e $1,000, valor superior ao limite. | | Nada é cobrado, embora o saldo esteja baixo | Botão global desligado, nenhum serviço em execução no modo By usage, limite diário atingido ou a cobrança anterior ainda está aguardando | Verifique o botão, o histórico e os limites. | | "N tentativas consecutivas com falha — a recarga automática é desativada após 3" | O cartão continua falhando | O cliente substitui o cartão por um novo depósito. | | Status *Precisa da sua confirmação* | O banco exige 3-D Secure | O cliente conclui uma recarga normal uma vez. | --- # Faturas e razão {#invoices-and-ledger} > **Onde no admin:** Finance › Billing (`/billing`) com as abas Overview, Transactions (`/billing/ledger`), Invoices (`/billing/invoices`), Top-ups (`/billing/deposits`), Payouts (`/billing/payouts`), Vouchers (`/billing/vouchers`) e Reports (`/billing/reports`). **Onde no portal:** Billing (`/billing`). ## O que faz {#what-it-does} Cada valor no NexCMP é armazenado em centavos de USD e registrado uma vez. A ideia principal: o **wallet ledger** é a fonte de verdade para os saldos; faturas, pagamentos de recarga e relatórios são visualizações construídas a partir dele. O registro é **somente anexação** — um erro é corrigido adicionando uma entrada de estorno, nunca editando o histórico. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Detalhes do vendedor | Defina o nome legal, ID fiscal, endereço, e-mail de contato e o prefixo do número da fatura em **System › Settings › General**, aba **Seller & invoicing** (`/settings?tab=seller`), cartão **Seller details (printed on invoices)**. | | Dependências | [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/) para entrada de dinheiro. | ## As peças {#the-pieces} | Aba de admin | O que lista | Uso típico | |---|---|---| | **Overview** | Receita hoje e neste mês, totais do razão por tipo (depósito, cobrança, reembolso, ajuste, voucher), faturas por status, reembolsos pendentes, atalhos, gastos por serviço nos últimos 30 dias | Verificação diária | | **Transactions** | O razão da carteira, uma linha por movimento | Explicar o saldo de um cliente | | **Invoices** | Faturas e uma segunda visualização **Orders** com cada compra de cada serviço | Encontrar um documento, reenviar, marcar como pago | | **Top-ups** | Pagamentos recebidos através dos gateways | Verificar um pagamento, reembolsá-lo | | **Payouts** | Reembolsos de cartão, pagamentos de afiliados, saques de revendedores | Aprovar saída de dinheiro | | **Vouchers** | Códigos de recarga | Ver [Promotions](https://nexcmp.com/pt/docs/billing/promotions/) | | **Reports** | Receita, por serviço, por revendedor | Contabilidade | ### Transactions (ledger) {#transactions-ledger} Colunas: horário, cliente, **tipo**, serviço, valor (com sinal), VM, referência, ator, nota. Filtros: tipo, serviço, ID do cliente, site (quando você tiver revendedores), intervalo de datas e um link de VM. | Tipo | Significado | |---|---| | `deposit` | Recarga de um gateway | | `charge` | Dinheiro retirado por um serviço (pedido, renovação, uso por hora...) | | `refund` | Dinheiro devolvido à carteira | | `adjust` | Crédito ou débito do administrador e também códigos de recarga (referência começando com `vch:`) — a visão geral mostra os vouchers em sua própria linha | Cada linha tem uma referência como `dep:stripe:`; a mesma referência nunca pode ser gravada duas vezes, por isso um webhook repetido não pode creditar duas vezes. Use **Customers › List › customer › Credit / debit** para adicionar um ajuste manual: um motivo é obrigatório, um valor positivo também tenta desbloquear VMs bloqueadas por falta de fundos e a ação é confirmada em duas etapas. ![Aba Transactions exibindo as linhas do razão da carteira com tipo, serviço, valor e referência](https://nexcmp.com/pt/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Invoices {#invoices} Uma fatura é criada automaticamente quando um cliente compra ou renova algo pago com a carteira, ou para uma recarga. Os números parecem com `-<000001>` (por exemplo, `NX202610-000042`); sites de revendedores usam seu próprio prefixo e sequência. Números existentes nunca mudam quando você altera o prefixo. | Campo | Valores | |---|---| | Tipo | Receipt, Renewal, Top-up, Manual, Refund | | Status | Unpaid, Paid, Overdue, Cancelled, Refunded | Ações em uma linha: | Ação | Efeito | |---|---| | **View** / **Print** | Abre a fatura; o portal também pode imprimir ou salvar como PDF. | | **Mark paid** (apenas não paga ou vencida) | Marca como paga **sem movimentar dinheiro da carteira** — use quando o cliente pagou fora do NexCMP. Um motivo é obrigatório. Para uma fatura de renovação, também estende e desbloqueia a VM bloqueada. | | **Cancel** (apenas não paga ou vencida) | Cancela a fatura. Um motivo é obrigatório. | | **Resend** | Envia a fatura por e-mail novamente. | **Create manual invoice** (botão no topo da aba): ID do cliente, 1 a 50 linhas (descrição, quantidade, preço unitário), ID de VM opcional, dias para vencimento opcionais (0 a 365, padrão 7), nota opcional. É criado como não pago; o cliente vê em **Billing › Invoice History**. Faturas não pagas de serviços são **quitadas automaticamente a partir da carteira** assim que houver saldo, portanto a ação do cliente é simplesmente fazer uma recarga. ### Recargas (pagamentos) {#top-ups-payments} Uma linha por tentativa: hora, cliente, **gateway e método**, tipo (recarga ou recarga automática), status (pendente, concluído, falhou, reembolsado, contestado, cancelado), o que o cliente pagou, a taxa, o que foi para a carteira, a referência do gateway e a hora de conclusão. Pagamentos concluídos do Stripe e PayPal têm uma ação de **Refund**. Use as páginas de eventos do Gateway para ver webhooks ([Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/)). ### Pagamentos de saída {#payouts} Três sub-abas: **Card refunds** (aprovar ou rejeitar solicitações de reembolso; a solicitação é criada a partir de um pagamento concluído), **Affiliate payouts** (saques de comissão) e **Reseller withdrawals**. Cada decisão é auditada. ### Reports {#reports} **Revenue** (tendência de 30 dias, mês a mês, principais clientes), **By service** e **By reseller**. ![Aba Reports mostrando KPIs de receita e a tendência de trinta dias](https://nexcmp.com/pt/docs/images/billing/invoices-and-ledger-03-reports.webp) ## O que o cliente vê {#what-the-customer-sees} Em **Billing**, o cliente tem **Balance**, **Deposit**, **Redeem code**, **Settings** (recarga automática) e um histórico com as abas **Invoice History**, **Payment Order**, **Ledger** e **Orders** (cada serviço em uma lista com filtros por serviço e tipo). Cada fatura possui **View**, **Print** e **Save as PDF**; os valores estão em USD, exibidos opcionalmente na moeda de exibição. ## Verificar {#verify} 1. Faça uma pequena recarga como cliente de teste. 2. **Transactions** exibe uma linha `deposit`, **Top-ups** mostra o pagamento como *Completed* e a receita em **Overview** aumenta. 3. Compre algo: uma linha `charge` aparece e **Invoices** exibe uma fatura do tipo *Receipt* ou *Renewal* com os detalhes do vendedor que você configurou. ## Limites e notas {#limits-notes} - **Somente adição.** Não é possível editar ou excluir uma linha do razão; adicione um ajuste com um motivo. - **Moeda.** Os valores são em USD; a moeda de exibição é cosmética (consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/)). - **Reembolso para o cartão** é feito em duas etapas (solicitação e, em seguida, aprovação em Payouts); USDT e transferências bancárias não são reembolsados para a origem. - **Tudo é auditado** em System › Logs › Admin actions com o motivo que você informou. - **Pedidos vs faturas.** O uso por hora não é faturado por hora; a visualização Orders o agrupa por dia para que você ainda possa vê-lo. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O saldo do cliente parece incorreto | Uma cobrança, ajuste ou voucher inesperado | Filtre **Transactions** pelo ID do cliente e leia as referências e notas. | | "A fatura já está paga" (409) | Marcar como paga em uma fatura paga | Nada a fazer. | | Não é possível cancelar uma fatura | Apenas faturas não pagas ou vencidas podem ser canceladas | Para as pagas, use um reembolso ou um ajuste. | | Detalhes do vendedor ausentes nas faturas | Não preenchido | Preencha **Seller details** em System › Settings › General › Seller & invoicing. | | Crédito / débito recusado | O valor é zero ou superior a $100,000 | Use um valor entre 1 cent e $100,000. | | Um pagamento mostra *Pending* por muito tempo | Webhook ausente | Consulte **Gateway events** e reexecute. | --- # Promoções {#promotions} > **Onde encontrar no painel:** Finance › Billing › Vouchers (`/billing/vouchers`). **Onde encontrar no portal:** Billing › Redeem code (também dentro do painel lateral de depósito). ## O que faz {#what-it-does} Um **código de recarga** (voucher) é um segredo de uso único fornecido aos clientes. Dependendo de como você o cria, ele pode: | Tipo | O que o cliente recebe | Para onde o valor vai | |---|---|---| | **Bonus credit** para todos os serviços | Dinheiro adicionado à carteira | Saldo da carteira. Utilizável em qualquer item. | | **Bonus credit** para serviços selecionados | Um crédito de serviço | Um bolso separado que só pode pagar por esses serviços. | | **Discount %** | Uma porcentagem de desconto no primeiro pedido dos serviços selecionados | Nenhum crédito é concedido; o desconto é aplicado no checkout. | Use-os para campanhas, créditos de cortesia, acordos com parceiros ou desconto no primeiro pedido. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Clientes | Os clientes resgatam códigos enquanto estão autenticados no portal (não como convidados). Por padrão, o cliente deve ter um e-mail verificado. | | Códigos em VND | Um código criado em VND é convertido para USD no resgate usando a taxa de câmbio armazenada (consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/)). | ## Criar um lote {#create-a-batch} 1. Abra **Finance › Billing › Vouchers** e clique em **Create vouchers**. 2. Preencha o formulário. Os valores de exemplo estão entre colchetes. | Campo | Notas | |---|---| | Nome do lote | 1 a 80 caracteres (`Spring welcome`). | | Destino | **Main site clients**, **Single reseller's customers** (necessita de uma lista de clientes) ou **Reseller wallet**. | | Usuários elegíveis | **All in target audience** ou **Specified** — um e-mail ou ID de cliente por linha, até 1,000. Para clientes de revenda, deve ser *Specified*. | | 1 código por destino | Com *Specified*, cria um código por cliente listado. | | Tipo de código | **Bonus credit** ou **Discount %**. | | Aplica-se a | Escolha um ou mais serviços; campo vazio = **All services**. | | Moeda, Valor nominal | USD a partir de $1.00 ou VND a partir de 10,000 em múltiplos de 1,000 (apenas crédito de bônus). | | Desconto (%) | 1 a 100 (apenas para Desconto %). | | Teto máximo de desconto (USD) | Obrigatório para Desconto %, a partir de $1.00. É também o valor máximo que você pode perder por resgate. | | Pedido mínimo (USD) | `0` = nenhum. O primeiro pedido deve ser de pelo menos este valor. | | Quantidade de códigos | 1 a 1,000 códigos aleatórios. | | Usos por código | 1 a 100,000. `1` significa uma pessoa por código; aumente o valor para um código compartilhado. | | Máximo de usos por conta | Pelo menos 1. Para Desconto % deve ser `1`. | | Data de início (opcional), Expira | A expiração deve ser após hoje e após o início, no máximo 2 anos à frente. | | Prefixo do código (0–6 caracteres) | Apenas letras; vazio usa o prefixo do site. | | Código personalizado (apenas quando count = 1) | 6 a 32 caracteres A–Z e 0–9. Fácil de compartilhar, mas fácil de adivinhar: mantenha os usos baixos. | | Exigir e-mail verificado | Ativado por padrão. | | Nota interna, Motivo | O motivo é obrigatório e vai para o registro de auditoria. | 3. O formulário mostra a **Exposição máxima** (valor nominal x códigos x usos) para que você saiba o pior cenário. Clique em **Generate codes**. 4. **Copie os códigos agora.** Eles são exibidos apenas uma vez: o NexCMP armazena apenas um hash e os últimos 4 caracteres. Use **Copy all** ou **Download CSV**, marque a confirmação e feche a caixa. ## Como cada tipo se comporta {#how-each-type-behaves} ### Bônus de carteira (nenhum serviço selecionado) {#wallet-bonus-no-service-selected} A carteira recebe um lançamento de **ajuste** (referência `vch:...`). Não é reembolsável para um cartão, não gera comissão de afiliado, não cria fatura e conta como saldo de carteira para cotas. Códigos em VND usam a taxa de câmbio no momento do resgate. ### Crédito de serviço (serviços selecionados) {#service-credit-services-selected} - O crédito fica em um **compartimento separado**, só pode pagar cobranças dos serviços escolhidos (novos pedidos, renovações, taxas por hora ou diárias, upgrades) e é gasto **antes** da carteira. - Não pode ser sacado, transferido ou convertido em dinheiro, e expira com o código. - O razão mostra a cobrança completa mais uma linha de crédito correspondente, de modo que a receita por serviço permaneça correta enquanto a carteira cai apenas pelo que o cliente realmente pagou. - Ele **não** eleva um nível de [quota](https://nexcmp.com/pt/docs/billing/quotas/) e é ignorado pelo [auto top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/). - Se uma cobrança paga com crédito ou desconto for reembolsada, a parte que o código pagou é retida do reembolso da carteira e devolvida ao compartimento de crédito. ### Desconto % {#discount} 1. O cliente insere o código: ele se torna **ativado**. Um código de porcentagem só pode ser usado uma vez por conta. 2. A **primeira cobrança** de um serviço selecionado que não seja uma taxa por hora, e pelo menos o **Pedido mínimo**, recebe o desconto percentual, nunca superior ao **Limite máximo de desconto**. 3. O desconto é recalculado pelo servidor no momento da cobrança; o valor no navegador é ignorado. A linha de resgate é gravada quando o código é realmente usado, com o desconto real. 4. Cobranças de uso por hora nunca utilizam o código. ## O que o cliente faz {#what-the-customer-does} 1. Abra **Billing** no portal e clique em **Redeem code**, ou use **Have a top-up code?** na gaveta de depósito. 2. Digite o código (não diferencia maiúsculas de minúsculas; hífens opcionais) e clique em **Check**. O portal informa o que ele concede, por exemplo *Valid code: +$5.00*, *$5.00 credit for VPN* ou *20% off voucher for Virtual Machines (up to $5.00)*, e *Valid for orders from $10.00*. 3. Clique em **Redeem** e confirme. Cada código pode ser usado uma vez por conta. Os códigos são vinculados ao site: um código de um site é "inválido" em outro, sem nenhum indício de que ele exista em outro lugar. Tentativas incorretas sofrem limitação de taxa (throttling) e, após várias tentativas, a conta é bloqueada por alguns minutos ("N tentativas restantes antes de um bloqueio temporário"). ## Acompanhar e interromper {#track-and-stop} - **Batches** lista cada lote com seu status (*active*, *disabled*, *expired*, *used up*), contagem de resgates e exposição. Abra um lote para ver as abas **Codes** (mascarados) e **Redemptions**, além de **Export CSV**. - **Redemptions** lista cada resgate em todos os lotes; **Reseller quotas** mostra quanto do limite mensal de emissão de cada revendedor foi utilizado; **Settings** ativa ou desativa códigos de revendedores e define o limite mensal padrão. - **Disable batch** interrompe todos os códigos não utilizados; os resgates já efetuados permanecem. Um código individual também pode ser desativado. ## Verificar {#verify} 1. Crie um lote de 1 código: % de desconto 20, limite de $5, pedido mínimo de $10, serviço Virtual Machines. 2. Como cliente de teste, resgate-o. O portal informa que ele está ativado. 3. Peça uma VM que custe pelo menos $10 (ciclo mensal): a fatura exibe o desconto (no máximo $5). 4. No lote, o código exibe 1 resgate com o desconto real. ## Limites e notas {#limits-notes} - Os códigos são vinculados ao **audience** e ao **site** no momento da criação; eles não podem ser movidos posteriormente. - Revendedores podem emitir códigos para seus próprios clientes dentro de um limite de exposição mensal; consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). - Os slides de promoção da barra lateral para clientes (**Marketing › Promo slides**) são um recurso separado e não concedem nenhum desconto. - Como o código em texto simples nunca é armazenado, um lote perdido não pode ser recuperado: desative-o e crie um novo. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Códigos percentuais: um uso por conta" (`percent_one_per_account`) | Usos máx. por conta acima de 1 para % de Desconto | Defina como `1`. | | O formulário diz que o limite é obrigatório | % de Desconto sem limite máximo de desconto (Maximum discount cap) | Insira pelo menos $1.00. | | Clientes não encontrados | Um e-mail ou ID na lista não existe | Corrija a lista (o erro nomeia as entradas desconhecidas). | | Cliente diz "código inválido" | Site incorreto, expirado, desativado, esgotado, não direcionado ao cliente ou e-mail não verificado | Verifique o lote e o cliente. | | O crédito não foi utilizado | A cobrança pertence a outro serviço | O crédito paga apenas os serviços escolhidos no lote. | | Desconto não aplicado | Pedido abaixo do mínimo, cobrança por hora ou o código foi ativado para outro serviço | Faça um primeiro pedido qualificado. | | Cliente bloqueado de resgatar | Muitas tentativas incorretas | Aguarde o término do bloqueio. | --- # Quotas {#quotas} > **Onde no admin:** Services › Virtual Machines › Policy › Quota tab (`/vm/policy?tab=quota`). Por cliente: Customers › List › a customer › Overview (`/customers/`), card **Quota**. **Onde no portal:** Client › Quotas (`/client/quotas`). ## O que faz {#what-it-does} As cotas protegem você contra abusos de novas contas: quanto mais dinheiro real um cliente tiver colocado na carteira, mais recursos ele poderá criar. Existem duas camadas: - **Recursos de VM e Kubernetes**: total de vCPU, RAM e disco, e o número de VMs. Os tiers são seus planos fixos. - **Quotas de serviço**: quantos IPs, clusters, VPCs, GB de armazenamento e assim por diante, em cinco tiers (de L0 a L4) impulsionados pelo dinheiro depositado. As quotas são verificadas **antes** de qualquer cobrança. Uma solicitação acima do limite é recusada com HTTP 403 `quota_exceeded` e uma mensagem informando ao cliente quanto recarregar. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Alternar | **Enable quota** (`quota_enabled`) fica **desativado** por padrão. Nada abaixo se aplica até que você o ative. | | Planos fixos | Pelo menos um plano não personalizado (consulte [Plans](https://nexcmp.com/pt/docs/catalog/plans/)) — os tiers de recursos são seus planos fixos. Sem nenhum plano, apenas a regra de contagem de VMs se aplica. | | Dependências | As linhas de quota de serviço existem apenas para os produtos ativados em sua instalação (VPN, proxy IPv6, Kubernetes, Private Cloud, Images, Object Storage, Dedicated). | ## Como a base é calculada {#how-the-basis-is-calculated} O NexCMP não olha apenas para pagamentos com cartão. A **base** é o **saldo da carteira lançado** do cliente: recargas de gateway, créditos de administrador (**Credit / debit**) e vales de carteira resgatados contam uma vez, através do razão da carteira. Descontos de pedidos e créditos de serviço de códigos promocionais não são dinheiro de carteira e não contam. A maior base que um cliente já alcançou é **mantida** (por site) — gastos ou reembolsos nunca reduzem um tier já desbloqueado. ### Recursos de VM e Kubernetes {#vm-and-kubernetes-resources} 1. Os tiers são os planos fixos do site, ordenados pelo custo de executá-los por 24 horas. 2. Um cliente está no tier mais alto cujo custo em 24 horas não excede sua base. O limite é a vCPU, RAM e o disco desse plano. Um cliente que não pode pagar nem pelo plano mais barato ainda recebe os recursos do plano mais barato. 3. O uso contabilizado no limite é toda VM ativa (incluindo as bloqueadas), volumes de dados adquiridos (mesmo quando desconectados) e workers e planos de controle do Kubernetes (os workers também contam como VMs). 4. **Contagem de VMs:** até **Max VMs at 24h tier** (padrão 2). A partir da próxima VM, o saldo *atual* da carteira do cliente deve cobrir **30 dias (720 horas)** de todas as suas VMs existentes mais a nova, até **Max VMs when meeting 30-day threshold** (padrão 10). 5. **Criar uma VM** também exige um saldo de pelo menos **N horas** dessa VM (**Create VM: balance ≥ N horas**, padrão 2) e o saldo mínimo da plataforma. 6. Reduzir o tamanho de uma VM nunca é bloqueado. Apenas a dimensão que aumenta é verificada, portanto, um cliente que está acima do limite de disco ainda pode adicionar vCPU se o limite de vCPU permitir. ## Configurar {#configure} 1. Abra **Services › Virtual Machines › Policy** e selecione a aba **Quota**. 2. Ative **Enable quota**. 3. Revise os três números (todos editáveis): | Campo | Padrão | Intervalo | |---|---|---| | Create VM: balance ≥ N horas | 2 | 1 a 720 | | Max VMs at 24h tier | 2 | 1 a 100 | | Máx. de VMs ao atingir o limite de 30 dias | 10 | 1 a 1000 (não abaixo do campo anterior) | 4. Em **Tier-based service quotas**, edite a tabela (abaixo). 5. Clique em **Save**. O NexCMP solicitará um **motivo**, que é gravado no log de auditoria junto com os valores antigo e novo. A alteração se aplica a todos os clientes. ![Aba de cotas com o botão de ativação, os limites de VMs e a tabela de cotas de serviço baseadas em níveis](https://nexcmp.com/pt/docs/images/billing/quotas-01-policy.webp) ### Tabela de cotas de serviço {#service-quota-table} A tabela possui cinco níveis. As células de cabeçalho **L0** a **L4** contêm o **limite de depósito em centavos**: os padrões `0, 1000, 5000, 20000, 100000` significam L0 para uma nova conta, L1 a partir de $10, L2 a partir de $50, L3 a partir de $200 e L4 a partir de $1,000. O primeiro limite deve permanecer `0`. Cada linha define a cota de uma chave por nível; **-1 significa ilimitado**. | Chave | Significado | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | IPs de VPN | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | IPs de proxy IPv6 | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | Servidores dedicados | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | Object Storage GB allocated | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | Clusters Kubernetes | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | Nós de trabalho do Kubernetes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | Redes de Cloud Privada | 1 | 2 | 5 | 10 | 30 | | `images.gb` | Armazenamento de imagens personalizadas (GB) | 50 | 100 | 200 | 500 | 2000 | A tabela também lista algumas linhas para produtos que não fazem parte desta versão; deixe-as inalteradas. Uma chave cujo produto está desativado fica oculta e nunca é aplicada. Um valor deve ser `-1` ou estar entre `0` e `10,000,000`. As cotas de serviço seguem a **base de fundos**, assim como os níveis de VM: o maior saldo de carteira alcançado, não o total de pagamentos com cartão. Clientes de revendedores usam os mesmos padrões e o revendedor só pode visualizá-los. ## Substituições por cliente {#per-customer-overrides} 1. Abra **Customers › List**, depois o cliente. Em **Overview** localize o card **Quota**. 2. **Recursos da VM:** clique em **Quota override** e escolha uma das opções - **Por saldo de recarga (remover substituição)** — comportamento padrão; - **Ilimitado (incluindo contagem de VMs)** — remove todos os limites para este cliente; - **um nível de plano** — fixa o teto de recursos nesse plano; a regra de contagem de VMs ainda se aplica. Insira um motivo. Os administradores da plataforma podem definir qualquer nível; uma substituição definida por um revendedor não pode exceder a base retida do cliente. 3. **Serviços:** a tabela em *Service quotas* mostra cada chave com *In use*, o limite efetivo e sua *Source* (nível ou substituição). Clique em **Edit** em uma linha, digite o **New quota** (`-1` = ilimitado, vazio = retorna ao padrão do nível) e um motivo. ![Cartão de cota do cliente com o nível, o uso de recursos e a tabela de cota de serviço com uma substituição](https://nexcmp.com/pt/docs/images/billing/quotas-02-customer.webp) Cada substituição é registrada no log de auditoria com o administrador, o motivo e os valores antes/depois. ## O que o cliente vê {#what-the-customer-sees} **Client › Quotas** (`/client/quotas`) mostra o **nível atual** do cliente, a quantidade usada e total de vCPUs, RAM, disco e contagem de VMs (dividida entre VMs e Kubernetes), o **saldo de carteira elegível**, a **base de recursos retida** (que não diminui quando eles gastam) e quanto falta recarregar para o próximo nível. Um controle deslizante permite que eles escolham um nível de destino e vão direto para a tela de depósito. O cartão **Service Quotas** lista cada serviço com a cota, a quantidade usada, o nível deles (de L0 a L4), quanto mais depositar para o próximo nível e um botão **Request increase** que abre um rascunho de ticket de suporte. Um botão **Quota policy** explica as regras. ![Página Quotas do portal com o nível atual, o uso de recursos e as cotas de serviço](https://nexcmp.com/pt/docs/images/billing/quotas-03-portal.webp) ## Verificar {#verify} 1. Ative **Enable quota** e use um novo cliente de teste com saldo de $0. 2. Tente criar uma VM maior do que o seu plano mais barato. A solicitação é recusada com `quota_exceeded` e a mensagem "Exceeds the resources of tier ... Top up $X more to unlock tier ...". 3. Recarregue o valor exibido. O nível muda imediatamente e a mesma solicitação é concluída com sucesso. 4. Compre IPs de VPN acima do limite de L0: HTTP 403 `quota_exceeded` com `"scope":"service"` e um link para `/client/quotas`. 5. No cartão de cota do cliente, **Source** mostra *tier*; defina uma substituição e veja-a mudar para *override*. ## Limites e notas {#limits-notes} - **Desligado significa desligado.** Com `quota_enabled` desativado, a regra antiga `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) limita novas contas a 2 VMs até que seus depósitos atinjam $10. Quando a cota está ativada, essa regra deixa de se aplicar. - **VMs criadas por administradores não são bloqueadas.** - **Erros falham fechados.** Se o estado da cota não puder ser lido, a solicitação será recusada com `quota_unavailable` em vez de permitida. - Solicitações de **API, CLI e MCP** usam os mesmos manipuladores, portanto, aplicam-se os mesmos limites. - O **crédito de promoção** não eleva um nível (consulte [Promotions](https://nexcmp.com/pt/docs/billing/promotions/)). - **Os limites de nível são em centavos**, não em dólares. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `quota_exceeded`, motivo `resources` | O novo total de vCPU/RAM/disco está acima do nível | Adicione saldo no valor da mensagem ou defina uma substituição. | | `quota_exceeded`, motivo `vm_30d` | Mais do que a contagem de VMs do nível de 24h e a carteira ainda não cobre 30 dias da frota | Adicione saldo no valor exibido. | | `quota_exceeded`, motivo `vm_max` | O limite absoluto de VMs foi atingido | Aumente **Max VMs when meeting 30-day threshold** ou use uma substituição. | | `quota_exceeded`, `scope: service` | Um limite por serviço foi atingido | Aumente o valor da tabela ou substitua essa chave para o cliente. | | `quota_unavailable` | Não foi possível verificar o estado da cota | Tente novamente; verifique o log do servidor se o problema persistir. | | "quota_max_vms_30d must be >= quota_max_vms_24h" ao salvar | Valores invertidos | Faça com que o número de 30 dias seja pelo menos o número de 24 horas. | | O cliente relata que o nível caiu | Ele não cai; compare **Held resource basis** com o custo do plano | Verifique a lista de preços do plano: um aumento no preço do plano pode mover os limites. | --- # Gerenciando clientes {#managing-customers} > **Onde no admin:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) e API keys (`/customers/apikeys`). ## O que faz {#what-it-does} A área de Clientes é onde a equipe de suporte consulta uma conta, visualiza sua carteira, serviços, tickets e histórico de login, além de tomar medidas: bloquear, desbloquear, verificar e-mail, redefinir a senha, adicionar ou remover crédito, personificar, criar uma VM ou fechar a conta. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. Cada ação de gravação solicita um motivo e é registrada no log de auditoria (System › Logs › Admin actions). | | E-mail | E-mails de redefinição de senha e convite exigem uma [SMTP configuration](https://nexcmp.com/pt/docs/administration/smtp-and-emails/) funcional. | ## A lista de clientes {#the-customer-list} Abra **Customers › List**. Os clientes são contas do seu site principal; contas de revendedores também aparecem e podem ser filtradas por site. ![Lista de clientes com os filtros e as colunas de país, origem de indicação, saldo e contagem de VMs](https://nexcmp.com/pt/docs/images/customers/managing-customers-01-list.webp) | Coluna | Significado | |---|---| | **Email** (e nome) | Clique para abrir o cliente. | | **State** | *Active*, *Locked* ou *Deleted*, além de e-mail *verified* ou *unverified*. Passe o mouse sobre uma tag de bloqueio para ler o motivo. | | **Login** | Métodos de login que o cliente possui: senha, Google, GitHub, passkey. | | **Country** | Bandeira e nome derivados do **IP address**: o país do IP de registro ou, quando este for desconhecido, do último IP de login. A dica de ferramenta indica qual foi usado. | | **Referral source** | *Referral* com um link para quem indicou e o código de indicação quando o cliente se registrou através de um link de afiliado; caso contrário, "Not recorded". | | **Balance**, **VMs** | Saldo da carteira (valores negativos em vermelho) e o número de VMs ativas. | | **IP registrado / último** | O IP usado no cadastro e no último login com um país de duas letras. Use para identificar várias contas de um mesmo endereço. | | **Tenant** | O ID de tenant interno do cliente. | | **Created**, **Last login** | Tempos relativos. | | **Site** | Exibido quando você possui revendedores. | **Search** aceita e-mail, nome ou IP. **Filters:** estado (all, active, locked, deleted), método de login (any, Google, GitHub, passkey, no password yet) e site. Os filtros são mantidos na URL, permitindo salvar a lista filtrada nos favoritos ou compartilhá-la com um colega. **A ordenação é global.** Clicar no cabeçalho de *Email*, *State*, *Balance*, *VMs*, *Created* ou *Last login* ordena a base de clientes **inteira** no servidor, e não apenas a página que você está visualizando, e o número da página volta para 1. **A lista é atualizada automaticamente.** Ela é atualizada a cada poucos segundos enquanto você a visualiza (pausando enquanto uma caixa de diálogo estiver aberta ou enquanto você digita), de modo que novos cadastros e alterações de saldo aparecem sem a necessidade de recarregar a página. A página do cliente é atualizada a cada 30 segundos aproximadamente enquanto estiver visível; cada aba carrega seus próprios dados ao ser aberta pela primeira vez. ### Criar um cliente {#create-a-customer} 1. Clique em **Create customer**. 2. Insira o **e-mail**, um **display name** opcional, uma **password** opcional (vazio = o cliente define através do link de convite) e escolha se deseja **send the invitation e-mail**. 3. Confirme. Uma conta criada manualmente conta como verificada quando você envia o convite. ## A página de um cliente {#a-customer-s-page} Clique em uma linha. A página possui oito abas; a aba selecionada é mantida na URL para que você possa salvá-la nos favoritos. As abas são carregadas ao serem abertas pela primeira vez e mantêm seu estado quando você alterna entre elas. | Aba | Conteúdo | |---|---| | **Overview** | Identidade, informações de cadastro e do último login, resumo da carteira e dos serviços | | **Services** | Uma tabela para os serviços do cliente, com filtros de tipo e estado, busca, ordenação no servidor e paginação | | **Billing** | Carteira e crédito, livro-razão, faturas, pagamentos, reembolsos, forma de pagamento salva e recarga automática | | **Quota** | Limites e sobreposições de recursos; consulte [Cotas](https://nexcmp.com/pt/docs/billing/quotas/) | | **Security** | Sessões, autenticação, métodos de login, histórico de login e chaves de API; consulte [Chaves de API](https://nexcmp.com/pt/docs/developers/api-keys/) | | **Support** | Tickets recentes | | **Affiliate** | Status do programa de indicação | | **Log** | Histórico de auditoria e atividade | Botões de ação no cabeçalho (ocultos para contas excluídas): | Botão | O que faz | |---|---| | **Lock account** / **Unlock** | Bloqueia o login e o acesso à API. Opcionalmente, também para todas as VMs (sem excluí-las). Serviços pré-pagos que não são VMs (Kubernetes, Private Cloud, VPN e assim por diante) também são parados. VMs bloqueadas por um administrador devem ser abertas separadamente na página da VM. | | **Verify email** | Marca o e-mail como verificado sem que o cliente precise clicar em um link. | | **Send reset link** | Envia um e-mail com um link de redefinição de senha (válido por 1 hora, uso único). Se o SMTP não estiver configurado, o link será exibido uma vez para que você possa enviá-lo manualmente. Um administrador nunca vê a senha. | | **Impersonate** | Entra como o cliente por uma hora. Consulte [Log in as a customer](https://nexcmp.com/pt/docs/customers/login-as/). | | **Credit / debit** | Adiciona ou remove saldo da carteira por meio de um ajuste no razão. Consulte [Invoices and ledger](https://nexcmp.com/pt/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | Desconecta o cliente em todos os lugares; os tokens de aplicativo deixam de funcionar. | | **Create VM** | Cria uma VM para o cliente. | | **Soft delete** | Encerra a conta. Você deve digitar o e-mail para confirmar. | ### Gerenciar um serviço individual {#manage-an-individual-service} Abra a aba **Services** do cliente, localize um serviço por nome, ID, IP ou configuração e use as ações de linha. As mesmas ações estão disponíveis na própria lista de administração do serviço. A caixa de diálogo oferece apenas ações compatíveis com esse serviço e seu estado atual. | Ação | Efeito | |---|---| | **Lock** | Interrompe o serviço mantendo seus dados. O cliente o visualiza como bloqueado e não pode operá-lo. Fazer uma recarga não remove o bloqueio aplicado por um administrador; a renovação automática fica bloqueada enquanto estiver bloqueado. | | **Unlock** | Reverte o bloqueio do administrador. Não remove bloqueios não relacionados por abuso ou outras proteções. | | **Cancel without refund** | Cancela o serviço sem lançamento de reembolso no ledger. A confirmação avisa que o cancelamento não pode ser desfeito. | | **Cancel and refund** | Mostra os pagamentos originais, a alocação de carteira/crédito, reembolsos anteriores e o valor máximo reembolsável. Revise o valor antes de confirmar. | Insira um motivo para cada ação. O motivo é destinado aos administradores; o cliente recebe um evento de serviço neutro ou uma notificação. O saldo reembolsado da carteira retorna para a carteira, e os créditos ou alocações promocionais retornam aos créditos. Esta ação não devolve valores via Stripe, transferência bancária ou PayPal. Para vários serviços do mesmo tipo, selecione até 50 linhas e escolha uma ação em massa. O resultado lista o sucesso ou a falha de cada linha. Os reembolsos em massa usam o valor sugerido de cada serviço; serviços cujo reembolso sugerido seja zero são ignorados no modo de reembolso e precisam de revisão individual ou cancelamento sem reembolso. DDoS Shield, discos e backups são linhas somente leitura aqui. Add-ons de largura de banda acompanham seu serviço pai. O acesso a AI Models pode ser bloqueado, mas não possui uma assinatura para cancelar. Para bloquear um servidor Bare Metal alugado, atue na assinatura dele em vez do seu pedido. ### Encerrando uma conta (exclusão lógica / soft delete) {#closing-an-account-soft-delete} A conta é definida como *deleted*, bloqueada, suas sessões são revogadas e suas comissões de indicação ainda não pagas são estornadas. As faturas e o razão permanecem para fins contábeis. A ação é recusada enquanto o cliente ainda tiver **qualquer serviço ativo** (VM, Kubernetes, Private Cloud, Dedicated, VPN, proxy IPv6), uma conta S3 ou uso de S3 pendente de pagamento. Exclua esses itens primeiro. ## Solicitações de exclusão {#deletion-requests} Um cliente pode solicitar a exclusão na página da sua conta. As solicitações aparecem em **Customers › Deletion requests** (filtro padrão: pendentes) exibindo o cliente, o motivo, o número de VMs ativas, o saldo e o horário da solicitação. - **Approve deletion** só é possível quando o cliente não tem nenhuma VM ativa. Digite o e-mail para confirmar. A conta passa por exclusão lógica; **o saldo restante da carteira não é reembolsado automaticamente** — crie um reembolso primeiro se houver valores a pagar. - **Reject** exige um motivo. ## Transferências de serviços {#service-transfers} **Customers › Service transfers** lista as solicitações para mover uma **VM ou uma assinatura de VPN** de uma conta para outra **no mesmo site**. - A tela é apenas de leitura e criação: você pode criar uma solicitação em nome de um cliente ou cancelar uma. Deliberadamente, **não** há um botão para aprová-la pelo proprietário ou pelo destinatário. - Fluxo: o proprietário confirma por meio de um link de e-mail de uso único (válido por 30 minutos, com TOTP se ativado), então o destinatário faz login e aceita (o destinatário assume as obrigações de pagamento). Uma solicitação não aceita em até 7 dias expira. - Regras: o serviço deve estar ativo, sem fatura em aberto e sem tarefa em execução; o destinatário deve ser um cliente ativo com e-mail verificado no mesmo site. A transferência de uma VM remove a chave SSH e desativa a renovação automática; a transferência de uma VPN altera as senhas de conexão. - As faturas já emitidas permanecem com o proprietário anterior; o novo proprietário pode ler o histórico de faturamento do serviço com os dados do proprietário anterior ocultos. - Os clientes podem criar suas próprias solicitações em **Transfers** no portal (5 solicitações por hora e 3 abertas por vez). ## Verificar {#verify} 1. Crie um cliente com um e-mail de convite. A nova conta aparece no topo da lista em poucos segundos. 2. Ordenar por **Balance**: a ordem abrange todos os clientes. 3. Bloquear o cliente: a etiqueta de estado muda para *Locked* e o cliente não pode mais fazer login. Desbloqueie-o. ## Limites e notas {#limits-notes} - A coluna de país é uma orientação baseada em IP, não uma prova de residência. Endereços privados ou desconhecidos não fornecem país. - Bloquear uma conta não reembolsa nada e não exclui VMs, a menos que você também escolha interrompê-las. - Desbloquear a conta não desbloqueia VMs que um administrador bloqueou; abra-as separadamente na página da VM. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "O cliente ainda possui serviços ativos... pare/exclua primeiro" | O cliente possui serviços ou uma conta S3 | Remova-os e, em seguida, faça a exclusão lógica. | | A aprovação de exclusão diz "N VMs alive" | Mesmo motivo | Exclua as VMs primeiro. | | Link de redefinição exibido em vez de "e-mail queued" | SMTP não configurado | Configure o e-mail ou envie o link você mesmo. | | Não é possível remover um método de login (`last_login_method`) | É a única forma de o cliente fazer login | Adicione outro método primeiro. | | O bloqueio não interrompe os serviços pré-pagos | Erros de interrupção foram relatados | Leia a mensagem após o bloqueio; o sistema tenta parar automaticamente novamente. | | Uma transferência não pode ser criada | Fatura não paga, tarefa em execução, destinatário em outro site ou não verificado | Corrija a condição e tente novamente. | --- # Fazer login como cliente {#log-in-as-a-customer} > **Onde no admin:** Customers › Customers › List › a customer › header button **Impersonate** (`/customers/`). ## O que faz {#what-it-does} **Impersonate** (entrar como) permite que um administrador de suporte veja o portal exatamente como um cliente o vê, para reproduzir um problema ou ajudar com um pedido. A sessão dura uma hora e é claramente separada de uma sessão normal: qualquer coisa que possa dar acesso duradouro à conta é bloqueada, e cada uso é registrado. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador conectado ao console de administração. | | Cliente | A conta deve estar **active**. Uma conta bloqueada ou excluída responde "account is not active" (HTTP 409). | | Motivo | Um motivo é obrigatório; ele é gravado no log de auditoria. | | Navegador | Permita pop-ups para o endereço do admin: o portal é aberto em uma nova janela. | ## Etapas {#steps} 1. Abra **Customers › List** e clique no cliente. 2. Clique em **Impersonate**. Uma caixa de diálogo explica que o site do cliente é aberto como o cliente por uma hora e que cada ação é auditada. 3. Digite o **reason** (por exemplo, "Ticket 1234 — cannot create VM") e clique em **Open app**. 4. Uma nova janela é aberta no site do cliente e exibe o painel com `?impersonated=1`. Se o navegador bloqueou a janela, permita pop-ups e clique novamente. ![Diálogo Impersonate com o campo de motivo preenchido](https://nexcmp.com/pt/docs/images/customers/login-as-01-dialog.webp) Para o cliente de um revendedor, a janela é aberta no **domínio do próprio revendedor**, pois o link só funciona no site do próprio cliente. ## Como funciona {#how-it-works} 1. A ação do admin cria um **token de uso único** válido por uma hora e grava `customer.login_as` (administrador, IP, motivo, site) no log de auditoria. 2. A nova janela é aberta `https:///v1/portal/impersonate/`. Uma primeira requisição exibe apenas uma página pequena e **não** consome o token (para que o pré-carregamento do navegador não o consuma); a página então confirma com um POST. 3. O POST consome o token. Um segundo uso, ou o uso após uma hora, responde "The impersonation link has expired or was already used". 4. O NexCMP cria uma sessão de cliente que dura **uma hora** (uma sessão normal dura 30 dias), registra uma entrada de login com o método `impersonate` e registra `customer.login_as.used`. 5. O token funciona apenas no site do próprio cliente; em outro host, ele responde 404. ## O que é bloqueado em uma sessão impersonada {#what-is-blocked-in-an-impersonated-session} Qualquer coisa que dê acesso além da hora ou altere a segurança do próprio cliente retorna HTTP 403 `impersonate_forbidden`: | Bloqueado | Motivo | |---|---| | Alterar a senha, TOTP, vincular ou desvincular Google/GitHub, editar chaves de segurança | Credenciais do próprio cliente | | Excluir a conta | Irreversível | | Criar ou editar **API keys** | Acesso de longa duração | | Aprovar um login de CLI, desktop ou MCP (vínculo de dispositivo) | Acesso de longa duração | | Criar acesso Kubernetes, chaves S3, chaves SSH, senhas de root, links de compartilhamento de console, credenciais de VPN ou proxy | Segredos que sobrevivem à sessão | | Resgatar códigos de recarga | Campanhas de dinheiro | | Retirar ou alterar o pagamento de comissão de afiliado | O dinheiro sai do sistema | | Editar chaves de IA, orçamentos ou e-mails de alerta | Configuração do cliente | Todo o resto funciona: você pode ler as páginas, criar ou gerenciar VMs, fazer pedidos e assim por diante. As ações são executadas com a identidade do cliente e gastam o dinheiro do cliente; os registros de auditoria acima mostram que um administrador estava por trás da sessão. ## Verificar {#verify} 1. Impersonate um cliente de teste. O portal é aberto e exibe os dados desse cliente. 2. Tente alterar a senha: você recebe "forbidden" (impersonation). 3. Em **System › Logs › Admin actions**, localize `customer.login_as` com seu nome, o motivo e o site, seguido por `customer.login_as.used`. 4. Feche a janela, reabra o mesmo link: "link expired or already used". ## Limites e notas {#limits-notes} - O limite de uma hora é fixo (3600 segundos). Para continuar, impersonate novamente. - Prefira ler e reproduzir; evite ações que gastem dinheiro, a menos que o cliente tenha pedido. - Revogue a sessão antecipadamente com **Revoke sessions** na página do cliente (isso desconecta o cliente também). - Os revendedores têm a própria impersonação **Sign in to partner console** (60 minutos) em Resellers; consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "A conta não está ativa" | Conta bloqueada ou excluída | Desbloqueie-a primeiro ou visualize a página do cliente. | | O navegador bloqueia a janela | Bloqueador de pop-up | Permita pop-ups para o endereço do admin e tente novamente. | | "O link expirou ou já foi usado" | Limite de uma hora ou reutilização | Impersonate novamente. | | Abre "Not found" | O link foi usado no host errado | Use a janela aberta pela caixa de diálogo; não cole o link em outro lugar. | | Uma ação diz "forbidden" | Bloqueado em sessões impersonadas | Peça para o cliente fazer isso ou use as telas de administração. | --- # Resellers (white-label) {#resellers-white-label} > **Onde no admin:** Customers › Resellers › List (`/resellers`), Domains & SSL (`/resellers/domains`), Permissions & wholesale (`/resellers/entitlements`), Defaults (`/resellers/settings`). Vagas de revendedores: System › Admin › License & updates (`/license`). ## O que faz {#what-it-does} Um **revendedor** obtém uma cópia com marca própria do portal do cliente no **seu próprio domínio**, com seus próprios clientes, carteira, preços e (opcionalmente) canais de pagamento. Eles compram de você a preço de atacado e vendem pelo próprio preço. Os clientes deles nunca veem a sua marca, e o domínio do revendedor nunca pode abrir o seu console administrativo. O revendedor gerencia seu negócio pelo **console de parceiros** em `https://partner.`. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Licença | Uma **vaga de domínio de revendedor** na sua licença para cada domínio de revendedor personalizado. A página de licença exibe `used/max` vagas e um link para comprar mais. Sem uma vaga livre, adicionar um domínio falhará com a mensagem "Out of license reseller domain slots". | | DNS | Cada domínio de revendedor deve apontar para o seu servidor (consulte abaixo). | | Servidor web e TLS | O nome do host deve alcançar o painel do NexCMP por meio do seu proxy reverso com um certificado válido para esse nome. | | E-mail | SMTP configurado para os e-mails de convite e notificação. | | Chave principal | **Reseller settings › General › `rs_enabled`** está ativado por padrão. | ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Defina o endereço público do servidor: seu endereço IPv4 e, se preferir CNAMEs, um nome de host que aponte para ele (por exemplo, `sites.cloud.example.com`). 2. Abra **Customers › Resellers › Defaults** (`/resellers/settings`), no grupo **Domains & SSL**, e defina: | Chave | Significado | |---|---| | `rs_server_ipv4` | O IPv4 público para o qual os registros A dos revendedores devem apontar. | | `rs_cname_target` | O nome de host para o qual os registros CNAME dos revendedores devem apontar. | | `rs_master_hosts` | Nomes de host que pertencem ao seu próprio site principal (não podem ser fornecidos a revendedores). | | `rs_platform_domain` | Domínio pai opcional para **subdomínios da plataforma** (por exemplo, `partners.cloud.example.com` para fornecer `acme.partners.cloud.example.com` aos revendedores). Deixar vazio desativa a opção. | | `rs_sites_stale_minutes` | Minutos antes de o serviço de certificado ser considerado desatualizado (padrão 15). | | `rs_ssl_fail_hours` | Horas de tentativas falhas antes de um erro ser disparado (padrão 48). | ::: warning Verifique estes valores antes de enviar as instruções `rs_server_ipv4`, `rs_cname_target` e `rs_master_hosts` vêm preenchidos com valores de exemplo. Substitua-os pelo seu próprio servidor e domínio **antes** de fornecer as instruções de DNS a um revendedor; caso contrário, as instruções na tela apontarão para o lugar errado. ::: 3. Clique em **Save** (será solicitada uma justificativa). 4. Certifique-se de que seu proxy reverso encaminhe os nomes de host dos revendedores para o painel do NexCMP e sirva um certificado para cada um deles. O instalador configura o nginx e o Let's Encrypt apenas para o domínio principal (e para os nomes `admin.` e `partner.` que resolvem). Se você usar a Cloudflare, faça o proxy do nome de host e use o modo Full SSL. ## Conectar no NexCMP {#connect-in-nexcmp} ### Criar o revendedor {#create-the-reseller} 1. Abra **Customers › Resellers › List** e clique em **New reseller**. O assistente possui 8 etapas e provisiona tudo no final; cada etapa pode ser repetida com segurança. | Etapa | Preencher | |---|---| | **Reseller** | Nome legal ou comercial, **slug** (4 a 31 caracteres de a–z, 0–9 ou `-`, começando com uma letra; também é o prefixo da fatura), nome de contato, e-mail e telefone, idioma padrão, detalhes de faturamento do revendedor (como comprador de recargas de saldo). | | **Console account** | Nome de usuário, e-mail da conta, nome completo; **Send a one-time invite link by e-mail** (válido por 72 horas, recomendado) ou exibir uma senha temporária uma única vez. | | **Brand** | Nome da marca, nome curto, slogans, cores primárias, e-mail e telefone de suporte, nome do vendedor impresso nas faturas dos clientes, logotipos (fundo claro e escuro), ícone quadrado e favicon: PNG, JPEG, WEBP ou ICO de até 256 KB, **sem SVG**. | | **Domains** | O(s) domínio(s) do cliente **também com www**, qual deles é o principal, um **domínio de teste** (sslip.io) e a opção de **dry-run**, ou um subdomínio da plataforma. O assistente exibe **DNS OK / DNS not ready** e os registros a criar. | | **Pricing & wallet** | Desconto de atacado (%), piso de varejo (% da tabela), margem padrão (%), limite de crédito, saldo inicial, alerta de saldo baixo, limites de clientes, VMs e domínios, recursos do site (cadastro de clientes, proteção DDoS, tickets de suporte, plano personalizado, redimensionamento, Auto Scaling). | | **Payment channels** | Quem coleta os pagamentos dos clientes (veja abaixo) e o PayPal próprio e transferência bancária do Vietnã opcionais. | | **Email** | Nome do remetente e Reply-To. O endereço From permanece o endereço da plataforma até que o DKIM seja configurado para o domínio do revendedor. | | **Review** | Verifique tudo e clique em **Provision everything**, ou **Save draft (provision later)**. | 2. O provisionamento continua em segundo plano (a cada 30 segundos). Abra o revendedor para ver o progresso e use **Continue provisioning** ou **Retry** se alguma etapa falhar. ![Novo assistente de revendedor na primeira etapa com valores de exemplo](https://nexcmp.com/pt/docs/images/customers/resellers-01-wizard.webp) ### Apontar o DNS (o revendedor faz isso) {#point-dns-the-reseller-does-this} O revendedor (ou você) cria os registros exibidos na aba **Domains & SSL**: | Registro | Name | Valor | |---|---|---| | TXT (propriedade, apenas na primeira vez) | `_site-verify.` | `sv=` exibido na tela | | A (domínio raiz como `shop.example.net`) | o domínio | seu `rs_server_ipv4` | | CNAME (subdomínio como `cloud.example.net`) | o domínio | seu `rs_cname_target` (ou um registro A para `rs_server_ipv4`) | | CNAME (opcional) | `www.` | seu `rs_cname_target` | Além disso: - Remova qualquer registro **AAAA** (IPv6), a menos que seu servidor responda nesse endereço IPv6. - Desative o proxy da CDN (**off**, nuvem cinza) enquanto o domínio estiver sendo verificado. - Se o domínio tiver registros **CAA**, permita `letsencrypt.org`. O token no registro TXT é diferente para cada domínio; copie-o da tela. O sistema verifica novamente o DNS a cada 5 minutos nas primeiras 48 horas, depois a cada hora, e libera um nome cujo registro TXT ainda esteja ausente após 72 horas. ### Estados do domínio {#domain-states} Em **Customers › Resellers › Domains & SSL** (todos os revendedores) e na aba **Domains & SSL** de um revendedor: | Estado | Significado | |---|---| | `pending_verify` | Aguardando o registro TXT. | | `pending_dns` / `verifying` | Aguardando o A ou CNAME apontar para você. | | `issuing` | Certificado sendo emitido. | | `active` | Atendendo ao site do revendedor. | | `cert_expiring` | Certificado próximo da expiração; renovação esperada. | | `dns_lost` | O DNS parou de apontar para você; após 30 dias, o domínio é removido. | | `error` | Veja o código de erro; **Retry** após corrigir. | | `removing` / `removed` | Sendo removido; o slot de licença é devolvido. | Ações da linha: **Check now**, **Retry**, **Make primary**, **Test mode** (para um domínio de teste), **Remove**. ## Permissões e atacado {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) é uma matriz: uma linha por revendedor, com o **desconto** e a **margem** de atacado e um botão de alternância por serviço (por exemplo, DDoS Shield e VPN). Um botão pode ser editado quando o recurso global da plataforma estiver ativado; caso contrário, a célula é somente leitura e aponta para a configuração. A sub-aba **Top-up codes** define quantos códigos cada revendedor pode emitir por mês (consulte [Promotions](https://nexcmp.com/pt/docs/billing/promotions/)). Regras de preços: - Preço de atacado = preço de tabela x (1 - desconto), podendo ser substituído por plano e por ciclo de cobrança na aba **Wholesale pricing** do revendedor. - O revendedor define os preços de varejo e não pode ficar abaixo do **floor** (percentual da tabela). - A **carteira** do revendedor paga o preço de atacado quando os clientes dele compram. A carteira possui limite de crédito, período de carência e teto de saldo devedor (consulte Defaults). ## Padrões {#defaults} **Customers › Resellers › Defaults** (`/resellers/settings`) são as chaves `rs_*` que se aplicam a todos os revendedores. Cada alteração solicita um motivo e é auditada. | Grupo | Chave | Padrão | Significado | |---|---|---|---| | Geral | `rs_enabled` | 1 | Programa de revendedores ativado. | | | `rs_platform_collect_enabled` | 0 | Permite que a plataforma colete pagamentos de clientes para revendedores. **Ative apenas após revisão jurídica.** | | | `rs_totp_required` | 1 | As contas do console de revendedor devem usar autenticação de dois fatores. | | | `rs_agreement_version` | 1 | Versão do contrato de revenda que eles devem aceitar. | | Preços padrão | `rs_default_discount_bp` | 2000 (20 %) | Desconto de atacado para novos revendedores (pontos-base, de 0 a 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | Margem padrão (de 0 a 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | Piso de varejo (de 0 a 20000). | | | `rs_default_max_domains` | 3 | Domínios permitidos por revendedor. | | Carteira e pagamentos | `rs_grace_hours` | 72 | Carência antes que os serviços dos clientes sejam afetados por uma carteira de revendedor vazia. | | | `rs_overdraft_cap_cents` | 5000 | Saldo devedor permitido na carteira. | | | `rs_retention_days` | 14 | Dias antes que as VMs de um revendedor encerrado sejam destruídas. | | | `rs_payout_hold_days` | 30 | Dias em que uma comissão fica retida antes de poder ser sacada. | | | `rs_payout_min_cents` | 5000 | Menor saque. | | | `rs_topup_min_cents` | 2000 | Menor recarga de carteira por um revendedor. | | Pagamentos e e-mail | `rs_webhook_base` | vazio | URL base pública para webhooks de gateway de revendedor (vazio = usar a URL do site). | | | `rs_mail_from` | vazio | Endereço do remetente para e-mails de revendedores. | | | `rs_invoice_show_processor` | 1 | Exibir o processador de pagamentos nas faturas. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | Se os revendedores podem configurar seu próprio Stripe ou USDT. | ## Quem coleta os pagamentos dos clientes {#who-collects-customer-payments} | Modo | Significado | |---|---| | **O revendedor coleta (canais próprios)** — padrão | O revendedor conecta sua própria conta do Stripe, PayPal, USDT ou conta bancária. Os webhooks deles são `https:///v1/billing//webhook/r/`. Cartões salvos e o recurso [auto top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/) não estão disponíveis para esses sites. | | **A plataforma coleta** | Seus canais são exibidos no site do revendedor. Bloqueado até `rs_platform_collect_enabled = 1`. | | **Misto** | Uma combinação escolhida por canal. | ## O que o revendedor vê {#what-the-reseller-sees} O console de parceiro em `https://partner.` possui Visão geral, Relatórios, Clientes, VMs, Tickets, Pedidos, Pagamentos, Preços, Marca, Landing & legal, Domínios e SSL, E-mail, Carteira e Canais de pagamento. As contas do console possuem a função *reseller* (completa) ou *staff* (somente leitura). Para conferir você mesmo, abra o revendedor e clique em **Sign in to partner console**: você entra por 60 minutos, cada gravação é registrada com seu nome tanto no log do admin quanto no log do revendedor, e as operações financeiras exigem uma segunda confirmação. ## Verificar {#verify} 1. Após o provisionamento, a linha da lista do revendedor exibe *active* e uma coluna **Provisioning** verde. 2. Abra o domínio do revendedor em um navegador: a própria página de login do revendedor aparece com sua marca. `https:///admin` retorna 404. 3. Cadastre um cliente de teste nesse domínio: o cliente aparece em **Customers › List** com o revendedor na coluna **Site**. 4. A página de licença mostra um slot usado a mais. ## Limites e notas {#limits-notes} - Um slot de licença por domínio personalizado ou de teste; subdomínios da plataforma não usam slot. - Suspender um revendedor mantém os dados; **Close reseller** devolve todos os slots de domínio, e a exclusão da VM só é permitida após o período de retenção. - Os clientes dos revendedores aparecem na sua lista de clientes e podem ser acessados por impersonação como qualquer outro (o link abre no domínio do revendedor). - Os revendedores não podem ver nem alterar seus canais de pagamento, padrões de cotas ou outros revendedores. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Out of license reseller domain slots | Todos os slots usados | Libere um slot (remova um domínio) ou compre mais na página de licença. | | Domínio travado em `pending_verify` | Registro TXT ausente | Crie o registro TXT exatamente como mostrado; use **Check now**. | | Domínio travado em `pending_dns` | A/CNAME não aponta para você, um registro AAAA ou o proxy do CDN está ativado | Corrija o DNS, desative o proxy e clique em **Check now**. | | Estado `error` | Consulte o código na linha (por exemplo, CAA bloqueando o Let's Encrypt, limite de taxa) | Corrija e clique em **Retry**. | | O navegador diz que o host é desconhecido ou "421" | O nome do host não está na licença ou não está roteado para o painel | Adicione o domínio por meio do revendedor (consome um slot) e corrija o proxy reverso. | | As instruções mostram um IP ou host incorreto | `rs_server_ipv4` / `rs_cname_target` ainda contêm os valores de exemplo | Defina-os em Defaults. | | O revendedor não pode ativar a cobrança da plataforma | Bloqueado | Defina `rs_platform_collect_enabled` após análise jurídica. | --- # Branding {#branding} > **Onde encontrar no admin:** System › Settings › Brand (`/settings/branding`). Relacionado: System › Settings › General (`/settings`) para URLs e dados do vendedor nas faturas. ## O que faz {#what-it-does} O NexCMP é white-label: o produto não traz nome de fornecedor e tudo o que seus clientes veem é a **sua** marca. As configurações de marca se aplicam às páginas de login e cadastro, ao portal, ao console de administração e aos e-mails. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Arquivos | Logotipos: SVG, PNG, JPEG, WEBP ou ICO, **até 512 KB cada**. | | Dependências | Nenhum. | ## Etapas {#steps} 1. Abra **System › Settings › Brand**. 2. No cartão **Identity**, preencha: | Campo | Notas | |---|---| | **Brand name** (obrigatório) | Até 60 caracteres. Exibido no portal, em e-mails, faturas e páginas legais. | | **Nome do vendedor nas faturas** | Até 120 caracteres. Vazio significa o nome da marca. | | **Brand color** | Uma cor `#rrggbb`; o pequeno botão ao lado do campo a redefine para a cor integrada. | | **Site currency** | **USD**: os preços e saldos são exibidos apenas em USD, sem alternância de moeda. **VND**: também exibe o valor convertido à taxa de câmbio armazenada (consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/)). | 3. Clique em **Save**. 4. No cartão **Logo & favicon**, faça o upload das três imagens — **Logo (light background)**, **Logo (dark background)** e **Favicon** — usando **Upload** (ou **Replace**); **Remove** exclui uma delas. ![Página de marca com os campos de identidade e as três imagens carregadas](https://nexcmp.com/pt/docs/images/customers/branding-01-brand.webp) ### Configurações relacionadas em General {#related-settings-in-general} **System › Settings › General** possui duas abas que completam o cenário: | Aba | Campos | |---|---| | **Branding & URLs** | Nome da marca (e-mail, faturas), idioma padrão (inglês ou vietnamita), **Customer app URL**, **Console URL**, **Admin URL** (link de representação do revendedor) e **Partner console URL** (links de convite, e-mails do revendedor). O assistente de configuração preenche estes campos com `https://`, `https:///admin` e `https:///console`. | | **Seller & invoicing** | Nome da entidade jurídica, CNPJ/ID fiscal, endereço, e-mail de contato e o prefixo do número da fatura. Consulte [Invoices and ledger](https://nexcmp.com/pt/docs/billing/invoices-and-ledger/). | O **From name** dos e-mails é definido em **System › Settings › Email** ([SMTP and e-mails](https://nexcmp.com/pt/docs/administration/smtp-and-emails/)). ## Os arquivos enviados são verificados {#uploaded-files-are-checked} - As imagens rasterizadas são reconhecidas pelo conteúdo (e não pelo nome do arquivo) e medidas. - **Os arquivos SVG são reconstruídos** a partir de uma lista segura de formas. Um arquivo contendo scripts, `foreignObject`, atributos de evento, links externos, `url(...)` apontando para fora, um DOCTYPE ou entidades é **recusado** (`svg_unsafe`). - Um arquivo muito grande é recusado com `asset_too_large`, um tipo incorreto com `asset_type` e dimensões incorretas com `asset_dimensions`. - Os arquivos são servidos a partir do seu próprio domínio com cabeçalhos rígidos de segurança. ## Verificar {#verify} 1. Abra a página de login do portal em uma janela anônima: o logotipo, o nome e a cor são exibidos. 2. Verifique a aba do navegador para o favicon (os navegadores armazenam favicons em cache; recarregue com o cache limpo se ainda vir o antigo). 3. Dispare um e-mail de teste (por exemplo, **Send reset link** para um cliente de teste) e verifique o nome da marca no assunto e no rodapé. ## Limites e notas {#limits-notes} - O logotipo para o fundo escuro é usado quando o cliente ou administrador alterna para o tema escuro. - Os revendedores têm sua própria marca; eles podem enviar PNG, JPEG, WEBP ou ICO de até 256 KB (sem SVG). Consulte [Resellers](https://nexcmp.com/pt/docs/customers/resellers/). - Uma alteração na cor da marca ou no logotipo aparece no próximo carregamento de página; e-mails já enviados não são alterados. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Upload recusado: `svg_unsafe` | O SVG contém scripts, links ou referências externas | Exporte um SVG simples (sem script, sem imagens externas) ou use PNG. | | `asset_too_large` | Arquivo acima de 512 KB | Comprima ou redimensione a imagem. | | `asset_type` | Não é SVG, PNG, JPEG, WEBP ou ICO | Converta o arquivo. | | `invalid_argument: primary` | A cor não é `#rrggbb` | Use um valor hexadecimal de seis dígitos. | | Logotipo antigo ainda visível | Cache do navegador | Recarregue forçadamente; os favicons podem demorar mais. | | Preços exibidos apenas em USD | A moeda do site é USD | Mude para VND e certifique-se de que uma taxa de câmbio esteja armazenada. | --- # Páginas legais {#legal-pages} > **Onde fica no admin:** System › Settings › Legal (`/settings/legal`). **Onde os clientes veem:** `https:///terms` e `/privacy`, com links no cadastro e no checkout. ## O que faz {#what-it-does} Sua instalação publica duas páginas: **Terms of Service** e **Privacy Policy**. Até que você escreva as suas próprias, o NexCMP exibe um **texto padrão neutro** que não menciona o fornecedor do software e não promete nenhum serviço específico. Substitua-o por um texto revisado pelo seu advogado antes de começar a vender. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador. | | Conteúdo | Markdown simples, de até **50 KB** por página e idioma. | | Dependências | O nome da marca e os detalhes do vendedor ([Branding](https://nexcmp.com/pt/docs/customers/branding/)) são inseridos no texto padrão. | ## Etapas {#steps} 1. Abra **System › Settings › Legal**. Cada uma das duas páginas possui seu próprio cartão com a tag *Using the default text* ou *Using your text*. 2. Escolha a aba de idioma, **English** ou **Tiếng Việt**. 3. Digite seu texto. Enquanto a caixa estiver vazia, o texto padrão aparecerá esmaecido como um espaço reservado. Para começar a partir dele, clique em **Start from the default text** e edite em seguida. 4. Clique em **Save**. O contador de tamanho exibe `used / 50 KB`. 5. Clique em **View on the customer site** para abrir `/terms` ou `/privacy`. 6. Para voltar ao padrão de um idioma, clique em **Clear, back to default** e salve. ![Configurações legais com o card Termos de Serviço mostrando o texto padrão como ponto de partida](https://nexcmp.com/pt/docs/images/customers/legal-01-terms.webp) ## O que as páginas padrão contêm {#what-the-default-pages-contain} O texto padrão está armazenado no produto como `legal_default.json` e preenchido com o nome da sua marca, nome do vendedor, URL do site e e-mail de contato (de **Seller & invoicing** em System › Settings › General; se nenhum e-mail estiver definido, ele aponta para sua equipe de suporte). | Página | Seções | |---|---| | **Terms of Service** | 1 O serviço · 2 Contas e verificação · 3 Preços e faturamento · 4 Reembolsos · 5 Seus dados · 6 Uso aceitável · 7 Disponibilidade e suporte · 8 Suspensão e encerramento · 9 Responsabilidade · 10 Alterações e lei aplicável (a lei do local de negócios do vendedor) | | **Privacy Policy** | 1 O que coletamos · 2 Por que usamos · 3 Cookies e armazenamento local · 4 Quem mais vê · 5 Retenção · 6 Seus direitos · 7 Contato | ::: warning Não é aconselhamento jurídico O texto padrão é um modelo neutro. Faça-o ser revisado antes de usá-lo com clientes reais, especialmente as seções sobre reembolsos, responsabilidade e lei aplicável. ::: ## Regras do Markdown {#markdown-rules} - Suportado: títulos (`# 1. Title`), parágrafos, listas com marcadores e numeradas, **negrito** e links `[text](https://example.com)`. - Os links devem começar com `http://` ou `https://`. - **HTML puro é recusado** (qualquer ``, ` # Visão geral do portal do cliente {#customer-portal-overview} > **Onde no portal:** `https:///` — os clientes entram em `/login`. Os administradores usam `/admin`; o mesmo login abre ambos quando a conta é de administrador. O portal é o que seus clientes usam todos os dias. Ele é personalizado com seu nome, logotipo e cores ([Branding](https://nexcmp.com/pt/docs/customers/branding/)) e exibe apenas os serviços que você ativou ([Modules](https://nexcmp.com/pt/docs/infrastructure/modules/)). ## O painel {#the-dashboard} Após o login, o **Dashboard** exibe: | Bloco | Significado | |---|---| | Saldo da carteira | Crédito atual e uma estimativa de quantos dias ele dura no ritmo atual de consumo | | Gasto este mês | Cobranças até o momento e uma previsão para o fim do mês | | Máquinas virtuais | Cada VM com status, IP, CPU e RAM, e ações rápidas (Console, Restart) | | Largura de banda | Tráfego de entrada/saída por 1 h, 6 h, 24 h, 7 d, 30 d | | Atividade recente | Últimos eventos na conta | | Início rápido | Uma lista de verificação: criar uma VM, adicionar uma chave SSH, recarregar, ativar a recarga automática, verificar o e-mail | ![O painel do cliente com saldo da carteira, previsão de gastos, uma máquina virtual em execução e a lista de verificação de início rápido](https://nexcmp.com/pt/docs/images/portal/overview-01-dashboard.webp) ## Navegação {#navigation} O menu agrupa os serviços por tipo. Um serviço que você desativou (ou cuja origem não está conectada) não aparece. | Área | Página | |---|---| | Instances | [Virtual machines](https://nexcmp.com/pt/docs/portal/virtual-machines/) e suas páginas de detalhes | | Implantar | [Ordering](https://nexcmp.com/pt/docs/portal/ordering/) — criar um recurso | | Armazenamento | Instantes, backups e volumes quando ativados — [Snapshots](https://nexcmp.com/pt/docs/portal/snapshots/) | | Faturamento | [Wallet and top-ups](https://nexcmp.com/pt/docs/portal/sign-up-and-wallet/), faturas, pedidos, cotas | | Conta | Perfil, login e segurança, preferências, recarga automática | | Suporte | Widget de chat e tickets — [Support](https://nexcmp.com/pt/docs/portal/support/) | | Documentação da API | `/apidoc` — [API](https://nexcmp.com/pt/docs/developers/api/) | ## Conta {#account} **Account** tem quatro abas: **Profile** (nome, e-mail, ID do cliente, solicitação de exclusão de conta), **Sign-in & security** (senha, passkeys, Google/GitHub vinculados), **Preferences** (idioma, moeda de exibição) e **Auto top-up** ([Auto top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/)). Um cliente não pode excluir a conta diretamente: ele clica em **Request account deletion**; após todas as máquinas virtuais serem excluídas, um operador analisa a solicitação (Customers › Deletion requests) e o cliente pode cancelá-la enquanto estiver pendente. ## Idioma e moeda {#language-and-currency} O portal está disponível em 16 idiomas e exibe preços na moeda escolhida pelo idioma; consulte [Currency and exchange rates](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). Os clientes podem alternar ambos em **Preferences**. ## Cotas de clientes {#customer-quotas} **Billing › Quotas** mostra quanto de cada recurso (CPU, memória, armazenamento, IP, VM) o cliente pode usar, com base no que foi pago — consulte [Quotas](https://nexcmp.com/pt/docs/billing/quotas/). --- # Cadastro, carteira e recarga {#sign-up-wallet-and-top-up} > **Onde no portal:** `/register`, `/login`, Billing (`/billing`). ## Criar uma conta {#create-an-account} 1. O cliente abre `https:///register` e insere o e-mail e a senha (pelo menos 10 caracteres com letras e dígitos), ou usa **Google**, **GitHub** ou uma **passkey** quando você os tiver ativado — consulte [Security](https://nexcmp.com/pt/docs/administration/security/#customer-sign-in). 2. Se o captcha estiver ativado, ele o conclui. 3. Um e-mail de verificação é enviado pelo seu [SMTP](https://nexcmp.com/pt/docs/administration/smtp-and-emails/). A verificação é obrigatória antes de criar uma VM quando as configurações de vendas exigirem. ![A página de registro com os campos de e-mail e senha](https://nexcmp.com/pt/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip Sem um SMTP funcionando, os clientes não conseguem verificar o e-mail ou redefinir a senha. Configure o [SMTP](https://nexcmp.com/pt/docs/administration/smtp-and-emails/) primeiro. ::: ## A carteira {#the-wallet} Tudo é pago com o saldo da **carteira** na sua moeda de cobrança. A página **Billing** mostra: | Seção | Significado | |---|---| | Poder de gasto | Saldo mais recargas pendentes | | Cobranças acumuladas | Serviços por hora consumidos no ciclo atual, ainda não liquidados | | Saldo devedor | Qualquer valor devido | | Histórico de cobrança | Abas **Invoice History**, **Payment Order**, **Ledger**, **Orders** | ![A página Billing com o poder de gasto, cobranças acumuladas e as abas de histórico](https://nexcmp.com/pt/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## Adicionar crédito {#add-credit} 1. Clique em **Deposit**. 2. Insira o valor. O mínimo é o seu [minimum top-up](https://nexcmp.com/pt/docs/billing/minimum-top-up/). 3. Escolha um canal de pagamento (cartão, PayPal, USDT ou transferência bancária quando a interface for vietnamita) — os canais são aqueles que você ativou em [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/). 4. Pague. O saldo é atualizado quando o provedor de pagamento confirmar. Cartões salvos, Stripe Link e PayPal podem ser reutilizados e usados para [auto top-up](https://nexcmp.com/pt/docs/billing/auto-top-up/); consulte [Saved payment methods](https://nexcmp.com/pt/docs/billing/saved-payment-methods/). ## Resgatar um código {#redeem-a-code} **Redeem code** adiciona crédito de um voucher emitido por você (Finance › Billing › Vouchers) ou aplica um código promocional — consulte [Promotions](https://nexcmp.com/pt/docs/billing/promotions/). ## Invoices {#invoices} Cada pedido pago gera uma fatura que mostra os detalhes do seu vendedor ([General settings](https://nexcmp.com/pt/docs/administration/general-settings/)). Os clientes a abrem em **Invoice History** e imprimem ou salvam como PDF pelo navegador. ## Cobranças por hora {#hourly-charges} Serviços por hora são cobrados a cada hora em que o recurso existir; os valores se acumulam e uma única hora pode arredondar para $0.00. Quando o saldo não for suficiente, os serviços são suspensos conforme as suas regras de faturamento e o cliente é avisado por e-mail (`low_balance`). --- # Contratar um serviço {#ordering-a-service} > **Onde no portal:** Deploy (`/deploy/vm`). **Onde no admin** você controla o que aparece aqui: Services (planos, preços) e System › Admin › License & updates (módulos). A página de pedido é um formulário único com rolagem e etapas numeradas. Escolher outro serviço na etapa 1 mantém a página e altera as etapas abaixo. ## Etapas {#steps} 1. **Service** — Cloud Servers e os outros serviços que você ativou (Kubernetes, Object Storage, Images, Private Cloud, VPN …). 2. **Location** — a [zone](https://nexcmp.com/pt/docs/infrastructure/zones/). Os preços e o tráfego incluído podem variar conforme a localização. 3. **Plan** — um plano fixo (vCPU, RAM, disco NVMe, preço por hora) ou **Custom** (o cliente escolhe vCPU, RAM e disco; preço por recurso). Os planos vêm de [Plans](https://nexcmp.com/pt/docs/catalog/plans/). 4. **Billing cycle** — **Hourly** ou ciclos pré-pagos mensais/anuais com desconto (por exemplo, 1 ano −10%, 2 anos −15%, 3 anos −20%). 5. **Operating system** — uma lista de templates, **My Images** (os próprios uploads do cliente) e a versão. 6. **Hostname & quantity** — um nome (ou **Randomize**) e a quantidade de servidores. ![A página de pedido exibindo as etapas de serviço, localização e plano](https://nexcmp.com/pt/docs/images/portal/ordering-01-plan.webp) ![As etapas de ciclo de faturamento e sistema operacional da página de pedido](https://nexcmp.com/pt/docs/images/portal/ordering-02-cycle-os.webp) ## Realizando o pedido {#placing-the-order} O sumário exibe o preço. O pedido é debitado da carteira **antes** do provisionamento, após as regras de [quota check](https://nexcmp.com/pt/docs/billing/quotas/) e [minimum balance](https://nexcmp.com/pt/docs/billing/minimum-top-up/). Uma VM geralmente atinge o status *Running* em cerca de um minuto; o cliente visualiza as etapas de deploy na aba **Activity** da VM e recebe o e-mail "VM ready" com a senha inicial (visível uma única vez por 10 minutos). ## O que pode interromper um pedido {#what-can-stop-an-order} | Mensagem / causa | Correção | |---|---| | Saldo insuficiente | Adicionar fundos — [Sign-up, wallet and top-up](https://nexcmp.com/pt/docs/portal/sign-up-and-wallet/) | | Cota excedida | Aumentar a cota — [Quotas](https://nexcmp.com/pt/docs/billing/quotas/) | | E-mail não verificado | O cliente verifica o e-mail | | Nenhum plano para a localização escolhida | Disponibilizar um plano nessa zona — [Plans](https://nexcmp.com/pt/docs/catalog/plans/) | | Licença inválida | Os clientes não podem criar novos serviços — [License](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # Máquinas virtuais {#virtual-machines} > **Onde no portal:** Instances (`/vms`) e a página de uma VM (`/vms/`). **Instances** lista as VMs do cliente com nome, SO, status, IP, especificações e custo. Clique em uma para abrir sua página. ## A página da VM {#the-vm-page} Abas: **Overview**, **Console**, **AI SSH Agent** (quando o módulo de IA está ativado), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**. ![Visão geral de uma máquina virtual com status, especificações, IP, gráfico de banda e registro de ações](https://nexcmp.com/pt/docs/images/portal/virtual-machines-01-overview.webp) ### Ações {#actions} | Ação | Efeito | |---|---| | Console | Abre o console no navegador — [Console](https://nexcmp.com/pt/docs/portal/console/) | | Restart / Stop / Force stop | Controle de energia | | Redefinir senha | Gera uma nova senha, exibida uma única vez | | Reinstalar SO | Reconstrói a partir de um template; os dados são perdidos | | Alterar IP | Substitui o IP público (onde a origem suporta) | | Ativar Auto Scaling | Ajusta CPU/RAM sob carga quando ativado | | Excluir | Destrói a VM; a cobrança por hora é interrompida | ### Informações exibidas {#information-shown} Tempo de atividade, custo deste mês, vCPU/RAM/disco com uso em tempo real, IP público e privado, nome de usuário, gráfico de largura de banda, registro de ações e resumo de faturamento (plano, ciclo, horas, restante). ::: info Os campos dependem da origem A página de uma VM mostra apenas o que sua origem suporta. Por exemplo, uma VM do Proxmox VE não possui redirecionamento de porta ou alteração de IP, e sua lista de SO segue o conjunto de templates do cluster. Consulte a tabela de compatibilidade em [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). ::: ## Aba Billing {#billing-tab} Mostra o plano, ciclo, total de horas, tempo restante e o log de faturamento. VMs por hora acumulam custos até serem excluídas. O cliente pode **switch cycle** para pagar um período mais longo com desconto. ## Para administradores {#for-administrators} A mesma VM fica visível em Services › Virtual Machines no console de administração, onde você pode agir em nome do cliente ou [log in as](https://nexcmp.com/pt/docs/customers/login-as/) ele. --- # Console {#console} > **Onde fica no portal:** a página de uma VM → aba **Console**. **Onde fica no admin:** System › Admin › License & updates → módulos (web SSH). ## O que faz {#what-it-does} A aba **Console** abre uma sessão gráfica (VNC) com a VM diretamente no navegador, mesmo quando a rede interna da VM estiver com problemas. Um terminal **web SSH** está disponível como segunda opção quando o módulo SSH está ativado. ## Requisitos {#requirements} | Item | Console VNC | Web SSH | |---|---|---| | CloudStack | VM de proxy de console (CPVM) acessível pelo painel — consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) | Uma porta SSH acessível na VM | | Proxmox VE | Funciona através do painel (noVNC sobre a API do Proxmox; a impressão digital TLS é fixada) — consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) | O mesmo | | Painel | URL do console definida em [General settings](https://nexcmp.com/pt/docs/administration/general-settings/) | O serviço `ssh-proxy` e a flag do módulo `feature_ssh_web`; desativados por padrão — consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) | Se o módulo web SSH estiver desativado, a aba mostrará apenas **VNC only**. ## Como usar {#use-it} 1. Abra a VM → **Console**. 2. Clique em **Console** (ou **Open in new window**). Um ticket de curta duração é emitido e o console é aberto em `https:///console`. 3. Faça login com o nome de usuário e a senha da VM (visíveis na aba Overview; redefina-os caso os perca). ![A aba Console de uma máquina virtual](https://nexcmp.com/pt/docs/images/portal/console-01-tab.webp) ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Disconnected" imediatamente | O navegador manteve um caminho de console antigo | Limpe os dados do site para o domínio e tente novamente | | Tela preta | A VM está desligada ou inicializando | Inicie a VM e aguarde | | O console não abre no CloudStack | A VM de proxy de console não está em execução ou não está acessível | Verifique as VMs de sistema no CloudStack | | Sem opção de SSH | Módulo Web SSH desativado | Ative-o apenas após a instalação de `ssh-proxy` | --- # Snapshots e backups {#snapshots-and-backups} > **Onde no portal:** Snapshots (`/snapshots`), Agendamentos de snapshot (`/snapshots/schedules`), Backups (`/backups`). Visível apenas quando o recurso está ativado no admin. ## O que faz {#what-it-does} Um snapshot salva o estado do disco de uma VM para que o cliente possa reverter após uma alteração indesejada. Os Snapshots podem ser criados manualmente ou por agendamento. ## Disponibilidade {#availability} | Source | Snapshots | Notas | |---|---|---| | CloudStack | Sim | Snapshots de volume; armazenamento cobrado conforme configurado | | Proxmox VE | Sim | Até **5 por VM**; criar, listar, restaurar e excluir | A entrada do menu aparece apenas quando o recurso de snapshot está ativado e o cliente possui uma VM cuja origem o suporte. ## Como usar {#use-it} 1. Abra **Snapshots**, clique em **Create**, selecione a VM e defina um nome. 2. Aguarde até que o status seja *ready*. 3. Para voltar, escolha **Restore** no snapshot e confirme — a VM retorna a esse estado (e é reiniciada quando necessário). 4. Exclua os snapshots de que não precisa mais. ::: warning A restauração descarta tudo o que foi escrito após o snapshot. VMs protegidas não podem ser restauradas ou destruídas pelo portal. ::: --- # Suporte aos clientes {#support-for-customers} > **Onde no portal:** o balão de chat em todas as páginas, `/chat`, e Tickets de suporte. **Onde no admin:** Customers › Support › Tickets (`/support/tickets`), aba **Settings**. ## Para clientes {#for-customers} - **Balão de chat** (canto inferior de cada página): faça uma pergunta; o [AI Chat](https://nexcmp.com/pt/docs/ai/ai-chat/) responde usando sua documentação e os dados da própria conta do cliente. **Expand** abre a mesma conversa em `/chat`. - **Falar com a equipe**: transfere a conversa para a sua equipe (via seu grupo do Telegram para administradores). - **Botões do Telegram / Zalo**: aparecem apenas após você definir os links nas configurações de suporte. - **Tickets**: para problemas mais longos; as respostas são enviadas por e-mail (`ticket_reply`). ## Para você {#for-you} 1. Abra **Customers › Support › Tickets**; novos tickets e chats aparecem aqui com a conversa. 2. Responda na conversa. O cliente recebe um e-mail através do seu [SMTP](https://nexcmp.com/pt/docs/administration/smtp-and-emails/). 3. Na aba **Settings**, ligue ou desligue o widget de chat, defina o link do Telegram e o link do Zalo (apenas https) e escolha se a IA responde automaticamente — consulte [AI Chat](https://nexcmp.com/pt/docs/ai/ai-chat/). 4. Conecte [Telegram alerts](https://nexcmp.com/pt/docs/administration/telegram-notifications/) para que sua equipe seja notificada sobre novos chats. --- # Provedor de IA {#ai-provider} > **Onde no admin:** System › Settings › AI provider (`/settings/ai`). O interruptor do módulo de IA fica lá e em System › Admin › License & updates (`/license`), cartão **Module**. ## O que faz {#what-it-does} O AI Chat (chat de suporte automático) e o AI Agent (administração de VMs em linguagem natural) não vêm com um modelo integrado. Você escolhe **seu próprio provedor**: qualquer serviço que ofereça uma `chat/completions` API **compatível com OpenAI** — por exemplo, OpenAI, OpenRouter, um gateway LiteLLM ou seu próprio servidor vLLM. O NexCMP armazena o endpoint e a chave de API (criptografados) e os utiliza para todos os recursos de IA. Você paga diretamente ao provedor. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Endpoint | Uma URL base compatível com OpenAI (`https://api.openai.com/v1`, `https://ai.example.com/v1`). O NexCMP adiciona `/chat/completions` a uma URL que termina em `/v1`; para qualquer outra URL, ele adiciona `/v1/chat/completions`; uma URL que já termina em `/chat/completions` é usada como está. | | Modelo | Um modelo compatível com **tool (function) calling** (chamada de ferramentas). Tanto o AI Chat quanto o Agent dependem dele. | | Chave de API | Uma chave para esse endpoint. Prefira uma chave com **limite de gastos** no provedor (por exemplo, uma chave virtual do LiteLLM com um orçamento mensal). | | Rede | O servidor do painel deve alcançar o endpoint via HTTP(S). Uma URL inserida no formulário só tem permissão para apontar para a Internet nas portas 80, 443, 8080 ou 8443; para usar um endereço interno, salve o provedor primeiro e teste em seguida. | | Dependências | O módulo **AI** ativado. Para o Agent, consulte [AI Agent](https://nexcmp.com/pt/docs/ai/ai-agent/#requirements). | ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Inscreva-se no provedor e crie uma chave de API. Se o provedor for compatível com orçamentos ou limites de taxa, defina um limite mensal. 2. Anote a **URL base** e o **nome exato do modelo** (e, opcionalmente, até quatro modelos de fallback). 3. Teste-o a partir do servidor do NexCMP antes de inseri-lo: ```bash curl -s https://ai.example.com/v1/chat/completions \ -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}' ``` Uma resposta JSON com `choices[0].message.content` significa que o endpoint está funcionando. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › AI provider**. 2. No cartão **Module AI**, mude o módulo para **on** (ativado). Até que esteja ativado, os clientes não verão o AI Chat ou o AI Agent no portal. (Você também pode alternar isso em **License & updates**.) 3. No cartão **Connection**, preencha: | Campo | Exemplo | Notas | |---|---|---| | Usar este provedor | on | Requer uma URL base, um modelo e uma chave para ser ativado. | | Nome de exibição | `LiteLLM` | Até 60 caracteres. | | URL base (compatível com OpenAI) | `https://ai.example.com/v1` | `http://` ou `https://`, até 300 caracteres, sem espaços. | | Chave de API do provedor | `sk-XXXX` | Armazenada criptografada; depois, apenas os últimos 4 caracteres são exibidos. Deixe em branco para manter a chave salva. | | Modelo padrão | `gpt-4o-mini` | Letras, dígitos e `- _ . / : @`. | | Modelos de fallback | `gemini-2.5-flash` | Separados por vírgula, até 4. Usados quando o modelo padrão falha. | | Esforço de raciocínio | Padrão (não enviado) | `Minimal`, `Low`, `Medium` ou `High`. Para modelos de raciocínio (Gemini, série o), um nível baixo responde muito mais rápido. Deixe em Padrão para modelos normais. | 4. Clique em **Save** e, em seguida, em **Test connection**. O teste envia uma pergunta curta e exibe `Connected — , ms` ou o erro retornado pelo provedor. ![Página do provedor de IA com o módulo de IA ativado e o formulário de conexão preenchido com valores de exemplo](https://nexcmp.com/pt/docs/images/ai/ai-providers-01-connection.webp) ### O que o salvamento faz {#what-saving-does} - As configurações do provedor são salvas como uma única entrada de configuração e a chave é criptografada com AES-256-GCM, vinculada a esta finalidade, usando a chave mestra da instalação. - As configurações de suporte **Primary model** e **Fallback model** (usadas pelo AI Chat) são definidas automaticamente para o seu modelo padrão e primeiro modelo de fallback. - A alteração é registrada no log de auditoria (endpoint, modelo, se a chave foi alterada — nunca a chave). ## Verificar {#verify} 1. **Test connection** fica verde. 2. Faça login no portal como um cliente de teste: o menu agora oferece **AI Chat** (ou a bolha de chat) e **AI Agent**. 3. Pergunte ao AI Chat "Qual é o meu saldo?". Uma resposta que informe o seu saldo real mostra que o provedor lida com chamadas de ferramentas corretamente. ## Limites e notas {#limits-notes} - **Um único provedor.** O NexCMP usa um único provedor configurado para o Chat, o Agent e a investigação de tickets. Os modelos de fallback oferecem resiliência dentro desse provedor. - **Segurança da chave.** A chave salva é enviada apenas para o endpoint salvo. Se você alterar a URL base, deverá digitar a chave novamente antes de testar. - **Limites por cliente.** O AI Chat é apenas para clientes autenticados, com limites de mensagens por minuto e por chat. O Agente tem um limite diário de chamadas por conta. Veja [AI Chat](https://nexcmp.com/pt/docs/ai/ai-chat/) e [AI Agent](https://nexcmp.com/pt/docs/ai/ai-agent/). - **Privacidade.** As perguntas dos clientes e os dados que a IA lê para esse cliente (somente leitura) são enviados ao seu provedores. Informe isso na sua [política de privacidade](https://nexcmp.com/pt/docs/customers/legal/). - **Controle de custos.** O NexCMP não faz a medição de custos da IA; utilize os recursos de orçamento do provedor. - O módulo pode ser desativado a qualquer momento: os itens de menu da IA desaparecem e as rotas da IA retornam 404 `module_disabled`. Algumas tarefas em segundo plano do AI Chat (investigação de tickets, respostas atrasadas) aplicam a alteração na próxima reinicialização do painel. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `base_url must be an http(s) URL` | Esquema ausente ou espaços | Use `https://host/v1`. | | `api_key is required to enable the provider` | Nenhuma chave armazenada | Insira a chave e salve. | | `base_url and model are required to enable the provider` | Campo vazio | Preencha ambos. | | "Base URL bloqueada: apenas http(s) público, portas 80/443/8080/8443" | Testando um endereço interno não salvo ou outra porta | Salve o provedor primeiro e depois teste. | | `api_key is required (enter the key again when you change the endpoint)` | A Base URL difere da salva | Redigite a chave. | | `model: letters, digits and - _ . / : @` | Caractere inválido | Use o ID de modelo exato do provedor. | | `fallback_models: up to 4 model names` | Muitos itens | Mantenha quatro ou menos. | | O teste falha com 401 | Wrong key | Verifique a chave e o endpoint. | | O teste falha com 404 ou "model not found" | Caminho ou modelo incorreto | Verifique a URL base (`/v1`) e o ID do modelo. | | `Too many tests — wait a minute` (429) | Mais de 10 testes por minuto | Aguarde. | | O portal ainda não exibe o menu de IA | Módulo desativado ou provedor não está "in use" | Ative o módulo e habilite o provedor. | --- # AI Chat {#ai-chat} > **Onde no admin:** Customers › Support › Ticket, aba **AI settings** (`/support/tickets?tab=settings`). Provedor e módulo: System › Settings › AI provider (`/settings/ai`). **Onde no portal:** o botão de chat flutuante e a página `/chat` (modo **Ask AI**). ## O que faz {#what-it-does} O AI Chat responde às perguntas dos clientes a qualquer hora, consulta dados da conta *deles* (saldo, serviços, pagamentos, erros recentes) e pode agir por eles — criar uma VM, alterar um plano — após a confirmação do cliente. Quando o assistente não consegue ajudar, o cliente clica em **Talk to a human**: o chat é enviado para sua equipe no Telegram e, se ninguém responder a tempo, vira um ticket. As mesmas configurações de IA também permitem que o sistema **investigue tickets** para sua equipe. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Módulo e provedor | O módulo **AI** ativado e um [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/) salvo e em uso. Sem um provedor, o assistente informa que não está configurado. | | Clientes | **Apenas clientes conectados.** Em uma instalação do NexCMP não há site público, portanto, um visitante que não esteja conectado recebe a mensagem "Sign in to use AI Chat". | | Canal da equipe (opcional) | Um bot e chat do Telegram para alertas de admin (consulte [Telegram notifications](https://nexcmp.com/pt/docs/administration/telegram-notifications/)). O mesmo canal recebe transferências de atendimento do chat e rascunhos de tickets. | | Dependências | [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/). | ## Preparar a infraestrutura {#prepare-the-infrastructure} Não é necessário além do AI provider. Se quiser transferência para a equipe: 1. Crie um bot do Telegram com o @BotFather e anote o token. 2. Crie um grupo ou use seu chat privado com o bot e anote o ID do chat. 3. Insira ambos em System › Settings › Admin alerts (consulte [Telegram notifications](https://nexcmp.com/pt/docs/administration/telegram-notifications/)). Os recursos de suporte reutilizam esse bot e chat. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Certifique-se de que o módulo de IA esteja ativado e o provedor retorne verde nos testes ([AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/)). 2. Abra **Customers › Support › Ticket** e selecione a aba **AI settings**. A parte superior do cartão esquerdo exibe três tags: *AI provider: configured*, *Telegram: channel present* e *On shift* ou *Off shift*. 3. Cartão esquerdo **AI + Telegram**: | Alternador ou campo | Padrão | Significado | |---|---|---| | A IA investiga tickets automaticamente | On | Para um novo ticket ou mensagem, a IA lê os dados do cliente (somente leitura) e escreve a causa provável e um rascunho de resposta como uma **nota interna**. Ela nunca envia para o cliente. | | Alertas do Telegram para o admin | On | A nota chega no Telegram com os botões Send, Edit e Skip. | | AI auto-reply | Desligado | Envia respostas simples de instruções ou vendas por conta própria quando todas as condições de segurança forem atendidas (confiança de 85% ou mais, sem avisos); enviado após 3 minutos e cancelável no Telegram. | | Categorias permitidas para resposta automática | `how_to`, `sales` | Apenas estas. | | Modelo primário, Modelo de fallback | definido pelo provedor | Normalmente, deixe como salvo pela página do provedor de IA. | | ID de usuário do Telegram autorizado a agir | vazio | Vazio significa o chat do canal de alertas. | 4. Cartão direito **Live chat (customer widget)**: | Campo | Padrão | Significado | |---|---|---| | Enable chat widget | On | A bolha de chat e a página `/chat`. | | Horário de suporte (horário do Vietnã) | `08:00-22:00` | Quando a equipe deve responder no Telegram. Fora desses horários, ou quando nenhum canal do Telegram existir, **Talk to a human** transforma o chat em um ticket imediatamente. | | Espera máxima pela equipe (minutos), depois converter em ticket | 10 | 1 a 240. | | Turnos de IA / dia / cliente | 40 | 1 a 1000. Após o limite, o assistente convida o cliente a falar com um atendente humano. | | Novos chats / hora / IP | 20 | 1 a 1000. | | **Zalo OA link** | vazio | `https://zalo.me/...` Mostra o botão **Chat on Zalo** (com um código QR) no chat. Vazio oculta-o. | | **Telegram link** | vazio | `https://t.me/...` Mostra um botão **Telegram**. Vazio oculta-o. | | Limite diário geral do sistema de turnos de IA, clientes logados | 2000 | | | Limite diário geral do sistema, visitantes | 500 | Pool próprio; não usado enquanto convidados não puderem conversar. | | Limite diário geral do sistema de investigações automáticas de tickets | 200 | | | Caminho do admin (o botão "Open admin" do Telegram) | vazio | Sua URL de administrador, por exemplo `https://cloud.example.com/admin`. | Cada alternador ou campo é salvo assim que você o altera. 5. Na parte inferior, **Reply templates** (título, idioma VI/EN/ZH, texto de até 4,000 caracteres) fornecem respostas prontas à equipe. ![Aba AI settings com os alternadores de IA e Telegram, limites do chat ao vivo e links de atalho](https://nexcmp.com/pt/docs/images/ai/ai-chat-01-settings.webp) ![Página de chat do cliente com o assistente, botões de atalho do Zalo e Telegram e a opção de falar com um atendente humano](https://nexcmp.com/pt/docs/images/ai/ai-chat-02-portal.webp) ## O que o assistente pode e não pode fazer {#what-the-assistant-can-and-cannot-do} - **Leitura:** ele pesquisa em sua base de conhecimento e documentação pública, além de ler os dados do próprio cliente conectado por meio de ferramentas somente leitura. Ele não pode ver outro cliente. - **Act:** ela usa as próprias permissões de API do cliente. Uma leitura (*read*) é executada imediatamente. Qualquer coisa que altere ou custe dinheiro cria um **confirmation card** ("Needs your confirmation", com as tags *Costs money* ou *Delete*); nada acontece até que o cliente clique em **Confirm**. Um chat pode manter no máximo 3 cartões pendentes e uma conta no máximo 10 ações de gravação confirmadas por hora. - **Nunca:** ele não pode abrir consoles, criar tokens de SSH ou console, baixar arquivos de acesso ao Kubernetes, redefinir senhas ou exibir segredos como senhas de proxy ou segredos S3. Os segredos nunca são incluídos no contexto do modelo ou no histórico do chat. - **Segurança:** suas respostas passam por um filtro de saída; o texto do cliente e os resultados das ferramentas são tratados como dados, e não como instruções. - **Aviso de transparência:** o chat exibe "Respondido por um assistente de IA — pode conter imperfeições. Fale com um humano para assuntos críticos." ## Transferência para a equipe {#staff-hand-off} 1. O cliente clica em **Talk to a human** e pode deixar um e-mail. 2. Uma mensagem com a conversa chega ao chat do Telegram da equipe. A equipe responde respondendo a essa mensagem; a resposta aparece no chat do cliente como "[brand] Support". 3. Se ninguém responder dentro do tempo de espera (padrão de 10 minutos), o chat se torna um ticket em **Customers › Support › Ticket**. O mesmo acontece imediatamente fora do horário de suporte ou quando o Telegram não está configurado, e o cliente é avisado de que um ticket foi aberto. 4. Os administradores também veem os chats emandamento na aba **Live chat**. ## Verificar {#verify} 1. Faça login como um cliente de teste, abra o chat e faça uma pergunta sobre os seus serviços. O assistente responderá. 2. Peça para ele criar algo que custe dinheiro: um cartão de confirmação aparecerá e nada será criado até que você clique em **Confirm**. 3. Clique em **Talk to a human**. A mensagem chegará ao seu chat do Telegram (se configurado) ou, após o tempo de espera, um ticket aparecerá. 4. Com os links do Zalo e do Telegram preenchidos, ambos os botões de atalho aparecem no chat. ## Limites e notas {#limits-notes} - **Limites de taxa (por IP):** 20 mensagens por minuto e algumas transferências por hora; **40 mensagens por conversa**. Estes valores são fixos. - **Custo:** cada interação da IA aciona o seu provedor. Reduza **AI turns / day / customer** para limitar os gastos. - **A resposta automática vem desativada por padrão.** Ative-a somente após acompanhar os rascunhos por algum tempo. - **Idiomas:** o assistente responde no idioma do cliente; o vietnamita é detectado a partir do texto. - **Revendedores:** os sites de revendedores usam tickets em vez do widget. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Clientes não conseguem ver o chat | Módulo de IA desativado ou **Enable chat widget** desativado | Ative ambos. | | "Sign in to use AI Chat" | O visitante não está conectado | Comportamento esperado no NexCMP: faça login primeiro. | | O assistente diz que nenhum provedor de IA está configurado | Provedor ausente, não utilizado ou chave ausente | Conclua [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/). | | A IA responde "talk to a human" após algumas perguntas | Limite diário por cliente atingido | Aumente **AI turns / day / customer**. | | Tag do Telegram mostra "no channel" | Bot ou ID do chat não configurados | Configure as [notificações do Telegram](https://nexcmp.com/pt/docs/administration/telegram-notifications/). | | Botão do Zalo ou Telegram ausente | O campo de link está vazio | Preencha o link. | | "Too many requests" no chat | Mais de 20 mensagens por minuto de um IP | Aguarde um minuto. | | Conversa do chat cheia | 40 mensagens atingidas | Inicie uma nova conversa. | --- # AI Agent {#ai-agent} > **Onde no admin:** System › Settings › AI provider (`/settings/ai`) — interruptor do módulo e provedor; System › Admin › License & updates (`/license`) — interruptor do módulo. **Onde no portal:** AI Agent (`/ai/agent`) e a página `/chat/agent`, ou o modo **Agent** dentro do chat. ## O que faz {#what-it-does} O AI Agent se conecta à VM Linux própria de um cliente via SSH e executa tarefas descritas em linguagem natural: "verificar integridade do sistema", "instalar o Docker", "encontrar erros recentes", "liberar espaço em disco". Ele exibe cada comando proposto e sua saída. Comandos somente leitura podem ser executados automaticamente; qualquer alteração no servidor aguarda o cliente pressionar **Run**. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Módulo de IA e provedor | O módulo **AI** ativado e um [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/) funcional. O Agente também precisa de um modelo que suporte chamada de ferramentas. | | `openssh-client` no servidor do painel | O Agente executa comandos com o programa `ssh` próprio do painel (`/usr/bin/ssh`). O instalador instala o `openssh-client`; verifique com `ssh -V`. Sem ele, o Agente relata "ssh client is not installed on the panel server". | | Sem gateway SSH separado | Na instalação padrão, o SSH integrado é usado e o terminal web `ssh-proxy` **não** é necessário. Somente quando o recurso opcional de *web SSH* (`feature_ssh_web`) é habilitado e o serviço `ssh-proxy` é instalado é que o Agente passa pelo `ssh-proxy`. | | Rede | O servidor do painel deve alcançar o IP da VM em sua porta SSH (22 por padrão). Verifique firewalls e grupos de segurança entre o painel e a rede de convidados. | | VM | De propriedade do cliente, **em execução**, não bloqueada, **Linux** (VMs Windows são recusadas), com um endereço IP público ou alcançável. | | Credenciais SSH | O usuário e senha de login da VM armazenados pelo NexCMP (salvos quando a VM foi criada ou sua senha foi redefinida, criptografados), ou a chave de operações do painel se houver uma instalada. Se nenhum dos dois existir, o Agente informará que não pode fazer login. | ## Preparar a infraestrutura {#prepare-the-infrastructure} 1. Verifique o cliente SSH no servidor do painel: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. Verifique se o servidor do painel consegue abrir o SSH para uma VM convidada: ```bash nc -vz 198.51.100.10 22 ``` Substitua o endereço pelo IP de uma VM de teste. Se isso falhar, corrija o roteamento ou o firewall primeiro. 3. Certifique-se de que o convidado permita login por senha para o usuário armazenado pelo NexCMP (algumas imagens em nuvem o desativam) ou que a chave de operações do painel esteja instalada no convidado. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Complete o [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/): módulo ativado, provedor salvo, **Test connection** verde. 2. Nada mais é configurado no lado do admin. O interruptor do módulo faz com que as entradas do **AI Agent** apareçam no portal do cliente. 3. Como cliente: abra o **AI Agent**, escolha um servidor em execução e clique em **Choose server**. A página primeiro testa o SSH com um comando fixo inofensivo (nenhuma chamada de IA é usada) e exibe *SSH connected* ou o motivo da falha. 4. Digite uma tarefa ou escolha um início rápido (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*). ## Como ele executa comandos {#how-it-runs-commands} - **De onde:** o servidor do painel, com o `ssh` client do sistema, um comando não interativo por vez. O destino é sempre o IP da VM **proveniente do banco de dados**, nunca da requisição; apenas a VM própria, em execução e desbloqueada do proprietário pode ser acessada. - **Autenticação:** a senha armazenada é passada por meio de um auxiliar `SSH_ASKPASS` de uso único no ambiente de processo — ela não é gravada em disco nem inserida na linha de comando. As chaves de host não são fixadas (as VMs são reinstaladas com novas chaves). A saída por comando é limitada a 200 KB e cada comando possui um limite de tempo (60 segundos). - **Loop do agente:** a IA propõe comandos e lê as saídas; um turno termina após no máximo **10 etapas**. - **Modos:** | Modo | Comportamento | |---|---| | **Confirm** | Cada comando aguarda por **Run**. | | **Auto** | Apenas comandos que passam por uma lista de permissões estrita somente leitura são executados sozinhos (por exemplo `df -h`, `ps`, `journalctl`). Qualquer outra coisa, e qualquer coisa que o analisador não possa analisar com certeza (variáveis, substituição de comando, redirecionamentos para arquivos), aguarda por **Run**. | - **Rótulos de risco:** comandos que sobrescrevem ou excluem arquivos, gravam em discos, alteram contas ou chaves SSH, enviam dados para um servidor externo, abrem conexões de rede brutas, executam código ofuscado, baixam e executam um script, desligam ou reiniciam a máquina, ou alcançam outros servidores sempre mostram **Needs confirmation**, mesmo no modo Auto. - **Saída não confiável:** a saída do comando é mostrada ao modelo como dados não confiáveis; as instruções contidas nela não são seguidas. ## Verificar {#verify} 1. Escolha uma VM de teste em execução. A página exibe *SSH connected*. 2. Peça "Check CPU, RAM and disk". No modo Auto, os comandos somente leitura são executados e a resposta os resume. 3. Peça "Install Nginx". O comando de instalação aparece com **Run** e **Skip**; nada é executado até que você pressione **Run**. 4. O contador na parte superior mostra o número de chamadas de IA usadas hoje (por exemplo `3/300`). ## Limites e notas {#limits-notes} - **Limite diário:** 300 chamadas de IA por cliente por dia (UTC); ele é redefinido às 00:00 UTC. Quando esgotado, o Agente responde "Daily AI quota reached". - **Concorrência:** no máximo 2 execuções do Agente por cliente ao mesmo tempo; uma sessão executa um turno de cada vez. - **Sessões:** até 100 mensagens por sessão, 4,000 caracteres por mensagem. Uma sessão pertence a uma VM; se a VM for excluída ou transferida, a sessão antiga torna-se somente leitura. - **VM bloqueada ou parada, ou Windows:** a VM é exibida como *Locked*, *Stopped*, *Windows* ou *No address* e não pode ser escolhida. - **Personificação:** um administrador personificando um cliente não pode usar os recursos de credencial do Agente (consulte [Log in as a customer](https://nexcmp.com/pt/docs/customers/login-as/)). - **Responsabilidade:** o Agente pode cometer erros. O portal instrui os clientes a revisarem os comandos antes de executá-los. Informe aos clientes em seus termos que eles são responsáveis pelos comandos que aprovam. - Desativar o módulo de IA remove as entradas do Agente e as rotas respondem com 404 `module_disabled`. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "o cliente ssh não está instalado no servidor do painel (apt install openssh-client)" | Sem o binário `ssh` | `sudo apt-get install -y openssh-client`. | | "O Agent não conseguiu fazer login" / `ssh: no saved credentials for this VM` | Sem senha armazenada e sem chave de operações | Redefina a senha da VM no portal para que ela seja salva novamente ou instale a chave de operações. | | "O servidor não respondeu a tempo" | Firewall, SSH não escutando, VM ocupada | Teste `nc -vz 22` a partir do servidor do painel; inicie `sshd` na VM. | | "Não foi possível acessar o SSH neste servidor" | Roteamento ou grupo de segurança | Permita que o servidor do painel alcance a VM na porta 22. | | "VM não está em execução" / "Proibido" | VM parada, bloqueada, excluída ou que não pertence ao cliente | Inicie-a, desbloqueie-a ou escolha outra. | | "Não disponível: N (parada, bloqueada ou Windows)" | Motivos listados acima | A VM deve ser Linux e estar em execução. | | "O gateway SSH está temporariamente indisponível" | Recurso de SSH Web ativado, mas o `ssh-proxy` está fora do ar | Inicie o `ssh-proxy` ou desative o recurso de SSH Web para usar o SSH integrado. | | "A IA está demorando muito para responder (mais de 90 segundos)" | Provedor lento | Use um modelo mais rápido ou um **Reasoning effort** menor. | | "Cota diária de IA atingida" | 300 chamadas usadas | Aguarde até 00:00 UTC. | | "Esta sessão ainda está em execução" | Outro turno em andamento | Aguarde ou pressione **Stop**. | --- # REST API > **Onde no portal:** Referência da API em `https:///apidoc` (pública) e chaves de API em `/api-keys`. **Onde no admin:** Customers › API keys (`/customers/apikeys`) lista as chaves criadas pelos clientes. ## O que faz {#what-it-does} Todas as ações que um cliente pode realizar no portal — listar e controlar VMs, ler faturas, gerenciar chaves SSH, Kubernetes, armazenamento e tickets de suporte — estão disponíveis por meio de uma API REST versionada em `https:///v1/`. Os clientes a chamam de scripts e CI com uma **API key** com escopo definido. A mesma API alimenta a [`cmp` command-line tool](https://nexcmp.com/pt/docs/developers/cmp-cli/) e o [MCP server](https://nexcmp.com/pt/docs/developers/mcp/), e a referência é gerada a partir da instalação em execução, listando sempre exatamente os recursos que você ativou. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Endereço HTTPS público | A API é servida no seu domínio principal (e no domínio próprio de cada revendedor). | | Uma chave de API | Criada pelo cliente no portal; consulte [API keys](https://nexcmp.com/pt/docs/developers/api-keys/). | | Dependências | Nenhum. Os endpoints de um módulo que você não ativou (por exemplo, Kubernetes ou Object Storage) ficam ocultos na referência e são recusados. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada para instalar. Se houver um proxy reverso na frente do NexCMP, encaminhe `/v1/`, `/mcp`, `/cli/` e `/apidoc` para o painel (a configuração do nginx do instalador já faz isso). ## Conectar no NexCMP {#connect-in-nexcmp} ### A referência interativa {#the-interactive-reference} Abra `https://cloud.example.com/apidoc` (substitua o host pelo seu domínio; os clientes de um revendedor veem a referência no domínio do revendedor, com o nome dele). Ela possui documentação de endpoints com exemplos de solicitação e resposta em curl, `cmp` CLI, JavaScript, Python e Go, uma caixa de pesquisa (Ctrl ou Cmd + K) e um painel **Try it**. O Try it envia solicitações apenas para o mesmo site, com uma chave colada pelo visitante (mantida na sessão do navegador); ele é somente leitura por padrão, e chamadas de gravação ou pagas exigem um comando extra e confirmação. ### Downloads e documentos legíveis por máquina {#downloads-and-machine-readable-documents} Todos são públicos, não exigem chave e são gerados por site: | URL | Conteúdo | |---|---| | `/apidoc` | Referência interativa. | | `/v1/public/openapi.json` | Documento OpenAPI 3.1. | | `/v1/public/openapi.yaml` | O mesmo, em YAML. | | `/v1/public/postman.json` | Coleção do Postman. | | `/v1/public/insomnia.json` | Exportação do Insomnia. | | `/v1/public/api.md` | A referência como um único arquivo Markdown. | | `/v1/public/api-catalog` | JSON leve: marca, URL base, prefixo de chave, cada escopo e cada endpoint com método, caminho, escopo e se ele precisa de um `Idempotency-Key`. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` No Postman, escolha **Import › Link** e cole `https://cloud.example.com/v1/public/postman.json`. A página de referência também oferece clientes de API em arquivo único para JavaScript e Python. ### Autenticação {#authentication} Envie a chave no cabeçalho `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - As chaves de cliente começam com `vk_`. As chaves são **vinculadas ao site**: uma chave criada em `cloud.example.com` não funciona no domínio de um revendedor. - Tokens de sessão do navegador (`pt_...`) são apenas para o portal; use uma chave para automação. - Os **escopos** da chave decidem o que ela pode chamar; um escopo ausente responde com HTTP 403 `scope_required`. Consulte [API keys](https://nexcmp.com/pt/docs/developers/api-keys/). - Verifique uma chave com `GET /v1/apikeys/self`: ele retorna o nome da chave chamadora, escopos, validade e o limite restante de taxa (qualquer chave pode chamá-lo). ### Exemplos {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` Obtenha os campos exatos de requisição de cada operação em `/apidoc`. ### Erros {#errors} Cada erro é um JSON com um `code` estável e uma `message` legível por humanos: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | `code` Típico | Significado | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Chave ausente ou desconhecida, revogada, expirada, IP do chamador fora da lista de permissões da chave, chave de outro site ou chaves de API desativadas. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | A chave não tem o escopo; o endpoint não está disponível para chaves; a conta está bloqueada; uma [quota](https://nexcmp.com/pt/docs/billing/quotas/) foi atingida; ação não permitida em uma sessão impersonada. | | 404 | `not_found` | Não encontrado — também retornado para recursos que pertencem a outra pessoa. | | 422 | `invalid_argument` | Erro de validação (campo nomeado na resposta). | | 429 | `rate_limited` | Muitas solicitações; aguarde por `Retry-After`. | | 503 | `maintenance` | O modo de manutenção está ativado: leituras funcionam, gravações são recusadas. | ### Limites de taxa {#rate-limits} | Limite | Padrão | |---|---| | Por chave | 120 requisições por minuto | | Por conta (todas as chaves juntas) | 300 requisições por minuto | Cada resposta carrega `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; um 429 adiciona `Retry-After`. ### Idempotência {#idempotency} Comandos que custam dinheiro ou não podem ser repetidos (criar, alterar plano, comprar, excluir ...) **exigem** um cabeçalho `Idempotency-Key` (qualquer string de até 200 caracteres; um UUID funciona bem). Envie a mesma chave novamente após um tempo limite e o servidor retornará o resultado **original** (com `Idempotency-Replayed: 1`) em vez de repetir a operação. Reutilizar uma chave para um comando diferente responde com 422; uma requisição ainda emandamento responde com 409/`Retry-After`. Sem o cabeçalho, uma chamada paga é recusada. ## Verificar {#verify} 1. Crie uma chave com o escopo `vm:read` no portal (**API keys › Create key**). 2. Execute: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Você obtém o HTTP 200 e os cabeçalhos de limite de taxa. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` lista as VMs da conta. No portal, a coluna **Last used** da chave e o **Key usage log** mostram as chamadas. ## Limites e notas {#limits-notes} - **Nunca disponíveis para uma chave:** recarregar, sacar, alterar cartões ou recarga automática, alterar senha, e-mail ou 2FA, excluir a conta, criar, editar ou revogar outras chaves. Essas ações exigem uma sessão de navegador iniciada. - **Módulos ocultos:** a referência e o documento OpenAPI listam apenas os recursos habilitados naquele site. - **Tamanho de resposta e paginação:** os endpoints de listagem são paginados (`page`, `per_page`); leia o documento OpenAPI para cada endpoint. - **Tempo e dinheiro:** os valores monetários estão em centavos de USD, a menos que o nome do campo diga o contrário. - **Admin API:** o console de administração tem sua própria página **System › Admin › API** e chaves de administrador (`ofw_...`) para a administração; elas são separadas da API de clientes descrita aqui. - **Controle de versão:** o prefixo de caminho `/v1` é estável; novos campos podem ser adicionados às respostas. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | 401 em uma chave nova | Chave de outro domínio, expirada ou digitada com espaços | Crie a chave no domínio que você chama; verifique o cabeçalho `Authorization: Bearer vk_...`. | | 403 `scope_required` | Escopo ausente | Edite a chave no portal e adicione o escopo. | | 401 `key_ip_denied` ou `site_mismatch` | Chave restrita a outros IPs ("allowed IPs") ou criada em outro domínio | Adicione o IP do seu servidor aos IPs permitidos da chave ou chame o domínio onde a chave foi criada. | | 404 em uma VM existente | A VM pertence a outra conta | Use uma chave do proprietário. | | 400/422 solicitando `Idempotency-Key` | Operação paga sem o cabeçalho | Adicione `Idempotency-Key: `. | | 429 | Acima do limite | Aguarde; use `Retry-After`. | | `/apidoc` mostra menos do que o esperado | Módulo desativado | Ative o módulo em License & updates. | --- # Chaves de API e escopos {#api-keys-and-scopes} > **Onde no portal:** API keys (`/api-keys`). **Onde no admin:** Customers › Customers › API keys (`/customers/apikeys`). ## O que faz {#what-it-does} Uma **API key** permite que um script, job de CI, a [`cmp` CLI](https://nexcmp.com/pt/docs/developers/cmp-cli/) ou um assistente de IA ([MCP](https://nexcmp.com/pt/docs/developers/mcp/)) chame a [REST API](https://nexcmp.com/pt/docs/developers/api/) em nome de um cliente, apenas com as permissões (**escopos**) concedidas. As chaves de cliente começam com `vk_`. Elas podem ler e gerenciar serviços, mas **nunca** podem mexer com dinheiro ou com a própria conta. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Cliente | Uma sessão autenticada no portal (uma chave não pode criar ou editar outras chaves, e um administrador personificando um cliente também não pode). | | Alternar | As chaves de API vêm ativadas por padrão. Se forem desativadas, as chamadas retornam 401 `api_keys_disabled`. | | Dependências | Os escopos de um produto aparecem apenas quando esse produto está ativado no site. | ## Criar uma chave (cliente) {#create-a-key-customer} 1. Entre no portal e abra **API keys**. 2. Clique em **Create key**. 3. Preencha o formulário: | Campo | Regra | |---|---| | **Key name** | Obrigatório, até 60 caracteres ("deploy server", "backup script"). | | **O que esta chave pode fazer** | Marque os escopos necessários — pelo menos um. Uma chave somente leitura não deve receber nenhum escopo de gravação. Tenha cuidado com escopos que custam dinheiro ou excluem dados. | | **Expiry** | Nunca, 30 dias, 90 dias ou 1 ano (a API aceita de 1 a 3650 dias). | | **Permitir chamadas apenas destes IPs** | Um IP ou intervalo CIDR por linha, até 20 (IPv4 ou IPv6). Vazio significa qualquer IP. Fixe o IP do seu servidor sempre que puder. | 4. Confirme o formulário. A chave é exibida **uma única vez** em uma janela "Key created — shown ONCE". Copie-a e clique em **I saved the key**. Apenas um hash SHA-256 é armazenado, portanto nem mesmo um administrador pode lê-la novamente; se você perdê-la, revoque-a e crie uma nova. 5. O portal também exibe um comando `curl` pronto para testar a chave. Uma chave se parece com `vk_` seguida por uma longa string aleatória. A lista exibe apenas os primeiros caracteres (por exemplo, `vk_a1b2c3d4`), os escopos, a validade, o último uso, a contagem de solicitações e o status (*Active*, *Expired*, *Revoked*). ### Edit, revoke, audit {#edit-revoke-audit} - **Edit** altera o nome, os escopos, os IPs permitidos e a validade. Não é permitido durante uma sessão personificada. - **Revoke** interrompe a chave imediatamente e não pode ser desfeito. A linha é mantida para que o log de uso continue disponível. - **Key usage log** mostra comandos de gravação e cada erro dos últimos 60 dias: horário, requisição, chave, resultado e IP de origem. - Uma conta pode ter no máximo **10 chaves ativas** por padrão. - Chaves criadas por meio do CLI ou login MCP aparecem em **Connected apps & devices** e podem ser revogadas lá. ## Escopos {#scopes} Os nomes dos escopos têm a forma `area:action`. Quais deles são oferecidos depende dos produtos que você ativou. | Escopo | Permite | |---|---| | `catalog:read` | Ler planos e o catálogo. | | `vm:read` | Ler VMs, métricas e faturas de VMs. | | `vm:write` | Ações de energia, pequenas alterações, firewall, snapshots rápidos. | | `vm:create` | **Criar VMs (gera custos).** | | `vm:plan` | **Alterar plano ou redimensionar (gera custos).** | | `vm:destroy` | **Excluir VMs.** | | `vm:restore` | **Restaurar uma VM a partir de um snapshot (sobrescreve o disco).** | | `vm:console` | Abrir tickets do console VNC. | | `sshkey:read`, `sshkey:write` | Ler, adicionar e remover chaves SSH. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volumes de dados (criar e ampliar geram custos; destruir perde dados). | | `backup:read`, `backup:write`, `backup:restore` | Backups (restaurar sobrescreve o disco). | | `billing:read` | Carteira, faturas, histórico de pagamentos — **somente leitura**. | | `bandwidth:buy` | **Comprar um complemento de largura de banda (gera custos).** | | `account:read`, `account:write` | Perfil, visão geral, atividade, notificações; `account:write` apenas marca as notificações como lidas. | | `apikey:read` | Listar as chaves da conta e o log de uso (não pode criar, editar ou revogar). | | `apikey:self` | Implícito em todas as chaves: inspecionar a chave chamadora (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | Tickets de suporte. | | `aff:read`, `transfer:read` | Programa de afiliados e transferências de serviços — somente leitura. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (criar e escalar geram custos; o kubeconfig é cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. | | `image:read`, `image:write` | Imagens de SO e ISO (o armazenamento é cobrado por hora). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (o segredo S3 é exibido apenas uma vez). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN e proxy IPv6 (os detalhes de conexão incluem senhas de proxy). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Servidores dedicados (criar pedidos a partir da carteira; destruir reinstala o SO). | | `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, apenas quando esse módulo estiver ativado. | Uma chamada fora dos escopos da chave retorna **403 `scope_required`**; um caminho que nenhuma chave pode chamar retorna **403 `endpoint_not_public`**. ### O que uma chave nunca pode fazer {#what-a-key-can-never-do} Nenhum escopo abre: adicionar ou retirar dinheiro, alterar cartões ou recarga automática, alterar a senha, o e-mail ou a 2FA, excluir a conta, criar, editar ou revogar outras chaves. Estas ações sempre exigem um navegador conectado. Mesmo uma chave vazada não pode tocar no dinheiro ou na conta do cliente. ## Regras nas quais você pode confiar {#rules-you-can-rely-on} | Regra | Detalhe | |---|---| | Vinculada ao site | Uma chave funciona apenas no site (domínio) onde foi criada. | | Limites de taxa | Por chave e por conta: 120 e 300 requisições por minuto por padrão. | | Idempotência | Operações que custam dinheiro ou não podem ser repetidas exigem um cabeçalho `Idempotency-Key`. | | Quotas | Uma chave está sujeita às mesmas [quotas](https://nexcmp.com/pt/docs/billing/quotas/) do cliente. | | Conta bloqueada | As chaves de um cliente bloqueado param de funcionar (403 `account_blocked`). | | Auditoria | A revogação por um administrador é registrada no log de auditoria administrativa. | ## Visualização do administrador {#administrator-view} 1. Abra **Customers › API keys** (`/customers/apikeys`). A tabela mostra o nome da chave e os primeiros caracteres, proprietário, escopos, status, último uso (horário, contagem de solicitações, IP) e validade. 2. Filtre por site se você tiver revendedores. Pesquise por nome, ID ou início da chave. 3. Clique em **Revoke** para interromper uma chave ativa ou em **Log** para ver seu uso. 4. Os administradores **visualizam e revogam** chaves, mas não podem ler nem criá-las para os clientes. ![Lista de chaves de API de clientes do administrador com escopos, status, último uso e o botão Revoke](https://nexcmp.com/pt/docs/images/developers/api-keys-02-admin.webp) ## Verificar {#verify} 1. Crie uma chave apenas com o escopo `vm:read`. 2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` retorna a lista de VMs. 3. `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` responde com 403 `scope_required`. 4. Revogue a chave; a primeira chamada agora responde com 401 `key_revoked`. ## Limites e notas {#limits-notes} - A chave nunca mais é exibida. Trate-a como uma senha e armazene-a em um gerenciador de segredos ou segredo de CI. - Prefira uma chave por script, escopos mínimos, validade curta e uma lista de permissão de IPs; faça a rotação criando uma nova chave e revogando a antiga. - Chaves de login de dispositivos (CLI, MCP) têm validade padrão de 90 dias. - Recursos excluídos ou transferidos não são afetados pela revogação de uma chave. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Erro `too_many_keys` (422) | O limite de chaves ativas (10 por padrão) foi atingido | Revogue uma chave antiga. | | Erro `invalid_argument`: nenhum escopo escolhido | Nenhum escopo marcado | Marque pelo menos um escopo. | | Erro `invalid_argument` em IPs permitidos | Uma entrada não é um IP ou intervalo, possui comprimento de prefixo incorreto ou mais de 20 entradas | Um IP ou CIDR por linha, por exemplo `203.0.113.0/24`. | | A criação é recusada durante a impersonação | `impersonate_forbidden` | Peça ao cliente para criar a chave. | | 401 `key_expired` | Data de validade ultrapassada | Crie uma nova chave. | | 401 `key_ip_denied` | IP do chamador não está na lista de permissões | Adicione o IP ou limpe a lista. | | 401 `api_keys_disabled` | Recurso desativado | Consulte o seu administrador (configuração `api_keys_enabled`). | --- # ferramenta de linha de comando `cmp` {#cmp-command-line-tool} > **Onde no portal:** os comandos de instalação estão na referência da API (`https:///apidoc`, seção Command-line interface). Aprovação de um login: `https:///link`. Dispositivos conectados: API keys (`/api-keys`) › Connected apps & devices. ## O que faz {#what-it-does} `cmp` é um pequeno programa de linha de comando para seus clientes (e para você) que transforma **cada operação de API em um comando**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Ele é compilado a partir do documento OpenAPI da **sua** instalação no momento do lançamento, portanto, os comandos correspondem aos recursos que você ativou. É um único binário estático para Linux, macOS e Windows (amd64 e arm64) sem necessidade de instalação adicional. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Servidor | Nada extra. Os pacotes de lançamento estão dentro da versão do NexCMP e são servidos pelo painel em `https:///cli/`. | | Máquina do cliente | Linux, macOS ou Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) é necessário apenas para verificar a assinatura. | | Credenciais | Um login de navegador com um código de uso único ou uma [API key](https://nexcmp.com/pt/docs/developers/api-keys/). | | Rede | HTTPS para o seu painel. A CLI recusa o envio de uma chave por `http://` puro, exceto para `localhost`. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada. O painel serve esses arquivos de `/cli/` (sem necessidade de build ou upload): | Arquivo | Finalidade | |---|---| | `install.sh`, `install.ps1` | Instaladores para Linux/macOS e Windows; eles contêm o endereço do seu painel. | | `latest.json` | Versão atual, lista de arquivos, tamanhos, sha256. | | `v/cmp___.tar.gz` ou `.zip` | Os programas: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Somas de verificação (checksums) e sua assinatura ed25519. | | `cmp-cli.pub` | A chave pública de lançamento. | ## Instalação (cliente) {#install-customer} macOS e Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` O instalador escolhe o pacote para o SO e CPU, baixa `SHA256SUMS` e sua assinatura, verifica a assinatura com a chave embutida no script, verifica o hash do pacote e instala `cmp` em `/usr/local/bin` (como root) ou `~/.local/bin`; no Windows, em `%LOCALAPPDATA%\cmp\bin` (adicionado ao `PATH` do usuário). Se uma verificação falhar, nada é instalado. | Variável | Significado | |---|---| | `CMP_VERSION` | Instalar esta versão em vez da mais recente. | | `CMP_INSTALL_DIR` | Pasta de instalação. | | `CMP_REQUIRE_SIGNATURE` | `1` = abortar quando a assinatura não puder ser verificada. | | `CMP_BASE_URL` | Base de download (para mirrors). | Download manual e verificação: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Seção de referência da API com o comando cmp install para macOS e Linux](https://nexcmp.com/pt/docs/images/developers/cmp-cli-01-install.webp) ## Fazer login {#log-in} ```bash cmp login ``` 1. A CLI exibe um **código** de uso único e um link (`https://cloud.example.com/link?code=WDJB-MJHT`), abre o navegador e aguarda. 2. No navegador, faça login no portal, verifique o nome do cliente, dispositivo, IP e país, marque as permissões (scopes) e escolha o tempo de vida da chave (padrão de 90 dias). Permissões que geram custos ou excluem dados vêm desmarcadas por padrão. Clique em aprovar. 3. A CLI recebe **sua própria chave**, separada das chaves criadas manualmente pelo cliente, e a armazena em `~/.config/cmp/config.json` (modo `0600`; `%APPDATA%\cmp` no Windows). Ela aparece em **API keys › Connected apps & devices** e pode ser revogada lá. O código expira após 10 minutos. A aprovação exige uma sessão real autenticada no portal com um e-mail verificado — não outra chave nem uma sessão impersonada. Flags úteis: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Para CI ou servidores sem navegador, use uma chave do portal: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Uso de comandos {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - Parâmetros de caminho são argumentos posicionais; parâmetros de query e campos de corpo tornam-se flags em kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` ou `--data -` envia um corpo JSON completo; as flags sobrescrevem seus campos. - `cmp help vm firewall add` (ou `--help`) mostra os detalhes de qualquer comando. ```bash cmp catalog plans cmp vm list --state active --per-page 50 cmp vm get 3f2a1c9e-0000-4000-8000-000000000000 cmp vm start 3f2a1c9e-0000-4000-8000-000000000000 cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24 cmp billing wallet cmp api GET /v1/vm --query page=2 # raw call to any endpoint ``` Comandos nativos: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Tudo o mais vem do documento da API. Flags globais: | Flag | Significado | |---|---| | `-o, --output json\|table\|yaml` | Formato. Padrão `table` em um terminal e `json` quando redirecionado. | | `--profile`, `--api-url` | Qual login salvo e qual site. | | `-y, --yes` | Ignorar confirmação para comandos destrutivos ou pagos. | | `--idempotency-key ` | Escolher a chave para um comando pago. | | `--retry ` | Em HTTP 429, aguardar por `Retry-After` e tentar novamente até n vezes. | | `--timeout ` | Segundos para aguardar os headers de resposta (padrão 60). | | `--debug` | Mostrar a troca HTTP em stderr, com chaves mascaradas. | Comandos que **cobram da carteira ou excluem dados** pedem confirmação e, se pagos, enviam um `Idempotency-Key` gerado automaticamente (impresso em stderr, para que você possa tentar novamente com segurança usando `--idempotency-key`). Sem um terminal, eles recusam a execução, a menos que `--yes` seja fornecido. ### Códigos de saída {#exit-codes} | Código | Significado | |---|---| | 0 | Sucesso | | 1 | Outro erro (rede, HTTP 4xx/5xx não listado) | | 2 | Erro de uso | | 3 | Não autorizado (401/403) | | 4 | Não encontrado (404) | | 5 | Limite de requisições excedido (429) | | 6 | Confirmação necessária ou recusada | | 130 | Interrompido | ### Perfis e ambiente {#profiles-and-environment} `cmp config` lista os perfis; `cmp config use ` alterna entre eles; os clientes de um revendedor usam o próprio domínio: `cmp login --api-url https://shop.example.net --profile shop`. Precedência: flag, ambiente, arquivo de configuração. Variáveis: `CMP_TOKEN`, `CMP_PROFILE`, `CMP_API_URL`, `CMP_OUTPUT`, `CMP_CONFIG_DIR`, `CMP_ALLOW_HTTP`, `CMP_UPDATE_URL`. GitHub Actions: ```yaml - name: Install cmp run: | curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" - name: List running VMs env: CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname' ``` Conclusão do shell: `cmp completion bash|zsh|fish|powershell`. ## Atualização e desinstalação {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` baixa `latest.json`, `SHA256SUMS` e a assinatura, verifica a assinatura com a chave pública **embutida no binário em execução**, verifica o hash do pacote e só então se substitui. Um downgrade requer `--force`. Quando você atualiza o NexCMP, o painel disponibiliza a versão da CLI que acompanha a nova versão. Para desinstalar, exclua o binário `cmp` e o diretório de configuração (`cmp config path` mostra o caminho). Revogue a chave em **API keys** caso a máquina seja perdida. ## Verificar {#verify} 1. `cmp version` exibe a versão e a versão do documento da API. 2. `cmp login`, aprove no navegador e, em seguida, `cmp whoami` exibe o perfil e a URL do seu painel. 3. `cmp vm list` retorna suas VMs; `cmp vm list -o json | jq .` exibe o JSON bruto. ## Limites e notas {#limits-notes} - A lista de comandos depende da sua compilação: os pacotes são gerados a partir do documento OpenAPI da sua instalação no momento da criação da release, portanto, um produto desativado na sua versão não possui comando correspondente. Use `cmp api` para um caminho que a CLI desconhece. - A CLI está sob a licença MIT. - Cada pacote é assinado com uma chave ed25519; a chave de assinatura está fixada (pinned) no instalador e no binário, não sendo buscada no momento da atualização. - As chaves possuem limites por chave e por conta (consulte [REST API](https://nexcmp.com/pt/docs/developers/api/#rate-limits)). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `curl .../cli/install.sh` retorna 404 | A release no servidor não possui pasta CLI ou o host não está na licença | Verifique `https:///cli/latest.json` e o domínio; atualize o NexCMP. | | "assinatura não pôde ser verificada" | `ssh-keygen` ausente ou desatualizado | Instale o OpenSSH 8.0+ ou defina `CMP_REQUIRE_SIGNATURE=0` apenas se aceitar o risco. | | `cmp login` indica que o código expirou | 10 minutos se passaram | Execute `cmp login` novamente. | | Código de saída 3 | A chave não possui um escopo, expirou ou foi revogada | `cmp whoami`; crie ou re-aprove com mais escopos. | | Código de saída 6 em um script | Comando pago ou destrutivo sem um terminal | Adicione `--yes` (e o seu próprio `--idempotency-key`). | | "recusa-se a enviar uma chave por http" | URL de API HTTP simples (sem TLS) | Use `https://` ou `CMP_ALLOW_HTTP=1` apenas para laboratório. | | O navegador abre o site incorreto | `--api-url` não definido para um revendedor | `cmp login --api-url https://`. | --- # Servidor MCP {#mcp-server} > **Onde no portal:** API reference › Tools (`https:///apidoc`) mostra o endpoint e trechos para clientes; as chaves são criadas em API keys (`/api-keys`). Não há configuração no admin: o endpoint faz parte do painel. ## O que faz {#what-it-does} O **Model Context Protocol (MCP)** permite que um assistente de IA chame ferramentas. O NexCMP disponibiliza um endpoint MCP em `https:///mcp`. Cada operação da API pública se torna uma **ferramenta** (`vm_list`, `vm_start`, `billing_wallet`, ...), permitindo que um cliente pergunte ao assistente "quais das minhas VMs estão rodando?" ou "desligue a VM de staging". O assistente atua exclusivamente com a chave de API e as permissões do próprio cliente. ::: tip Configurando o próprio NexCMP com IA? Esta página é o endpoint MCP do **cliente** (`/mcp`). Para permitir que um assistente de IA configure seu próprio painel como administrador, consulte [Configure with AI](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, chaves de admin `ak_`). ::: ## Requisitos {#requirements} | Item | Requisito | |---|---| | Servidor | Nada para instalar: o endpoint é servido pelo painel e acessível onde quer que o painel esteja. O seu proxy reverso deve encaminhar `/mcp` para o painel. | | Cliente | Uma [API key](https://nexcmp.com/pt/docs/developers/api-keys/) (`vk_...`) com os escopos que o assistente precisa. | | Cliente | Um cliente MCP que suporte o transporte **Streamable HTTP** e um cabeçalho customizado `Authorization`: Claude Code, Claude Desktop (através da ponte `mcp-remote`), Cursor, VS Code com o modo de agente do Copilot e similares. | | Versões de protocolo | 2025-11-25, 2025-06-18 e 2025-03-26. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada, além de garantir que `https:///mcp` não seja bloqueado por um firewall ou regra de proxy. Um cliente MCP baseado em navegador de outra origem é recusado a menos que essa origem seja permitida; clientes de linha de comando e de desktop não enviam cabeçalho `Origin` e funcionam normalmente. ## Conectar (lado do cliente) {#connect-customer-side} 1. Crie uma API key no portal (**API keys › Create key**) apenas com os escopos que você deseja que o assistente use, com uma curta validade e, se possível, restrição de IP. 2. Adicione o servidor ao seu cliente. Substitua `cloud.example.com` e a chave. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` ou `.cursor/mcp.json`; defina `CLOUD_API_KEY` no ambiente a partir do qual o Cursor é iniciado): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (requer Node.js 18+; `claude_desktop_config.json`), através da ponte `mcp-remote`: ```json { "mcpServers": { "cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"], "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" } } } } ``` Escreva o cabeçalho sem espaço após os dois-pontos e coloque o valor inteiro na variável de ambiente, conforme acima. 3. Reinicie o cliente e peça para ele listar suas ferramentas. Verifique a conexão sem um cliente: ```bash curl -s https://cloud.example.com/mcp \ -H "Authorization: Bearer vk_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Como funciona {#how-it-works} | Item | Detalhe | |---|---| | Endpoint | `POST /mcp` com uma mensagem JSON-RPC 2.0; a resposta é `application/json`. `GET /mcp` responde 405 (sem fluxo de servidor para cliente); `DELETE /mcp` encerra a sessão. | | Autenticação | Apenas `Authorization: Bearer vk_...` (tokens de sessão, cookies e chaves de admin são recusados com 401 e um cabeçalho `WWW-Authenticate: Bearer`). | | Sessão | `Mcp-Session-Id` é emitido por `initialize`, vinculado a essa chave, válido por 24 horas; no máximo 16 sessões por chave. | | Ferramentas | Uma por operação de API pública visível para a chave. O nome da ferramenta é o comando CLI com `_` em vez de espaços e traços (`vm firewall add` vira `vm_firewall_add`) e equivale ao `operationId` da OpenAPI. Uma ferramenta é listada apenas quando a chave possui o escopo dela e o módulo está ativado. | | Capacidades | Apenas ferramentas (sem recursos ou prompts). | | Tamanho | Corpo da requisição de até 1 MB; texto de resultado de ferramenta de até cerca de 100 KB (o excedente é cortado com uma observação); uma chamada leva no máximo 55 segundos. | ### Regras de segurança {#safety-rules} - **Mesmo portão do REST.** Cada `tools/call` passa pelo pipeline de requisições próprio do painel: escopo, site, restrição de IP, limite de taxa, idempotência, verificações de propriedade (404 para recursos de terceiros) e cotas se aplicam. O MCP não pode conceder nada que a chave não possua. - **Confirmação.** Ferramentas que cobram, excluem ou retornam credenciais (tickets de console, kubeconfig, segredos S3 ou SSH, redefinições de senha, novas chaves) exigem o argumento `confirm: true`. A descrição da ferramenta instrui o assistente a repassá-lo apenas após a aprovação do usuário, de modo que uma instrução oculta em uma página da web ou log não possa acioná-la por conta própria. - **Idempotência.** Ferramentas pagas aceitam `idempotency_key`; se omitido, uma chave estável é derivada do nome da ferramenta e dos argumentos, para que uma nova tentativa idêntica não possa cobrar duas vezes. - **Não expostos como ferramentas:** endpoints de streaming (o chat do AI Agent), tickets únicos de SSH ou WebSocket de console, downloads binários e os endpoints do aplicativo VPN (`/v1/ext/*`). - **Nunca possível:** a API nunca permite recargas, alterações de senha, exclusão da conta ou criação de chaves, portanto nenhum assistente pode realizá-las. ### Limites {#limits} | Limite | Padrão | |---|---| | Chamadas de ferramenta por chave | 60 por minuto | | Requisições MCP por chave | 240 por minuto | | Mais os limites normais de chave e conta | Consulte [REST API](https://nexcmp.com/pt/docs/developers/api/#rate-limits) | Acima do limite, o endpoint responde com HTTP 429 com um erro JSON-RPC e `Retry-After`. ## Verificar {#verify} 1. O comando `curl` acima retorna um resultado JSON-RPC com uma lista `tools`. Apenas as ferramentas que correspondem aos escopos da chave aparecem. 2. No seu cliente, pergunte "list my VMs": o assistente chama `vm_list` e exibe o resultado. 3. No portal, o horário de **Last used** da chave é atualizado, e as chamadas de gravação aparecem no **Key usage log**. ## Limites e notas {#limits-notes} - **Login pelo navegador (OAuth).** A página de referência também descreve a autenticação pelo navegador para clientes que oferecem suporte ao OAuth do MCP. Em uma instalação do NexCMP, o método suportado e testado é a chave de API (ou `cmp login` para o CLI). - **Sites de revendedores** não exibem a seção MCP; os clientes deles usam o domínio do revendedor para a API. - **Menor privilégio.** Crie uma chave dedicada por assistente com escopos de leitura primeiro; adicione escopos de gravação apenas quando necessário. - Revogue a chave em **API keys** para cortar o acesso do assistente imediatamente. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | 401 com `WWW-Authenticate: Bearer` | Sem chave, chave incorreta ou token de sessão | Envie `Authorization: Bearer vk_...`. | | 403 sobre `Origin` | Uma página de navegador em outra origem | Use um cliente de desktop ou CLI; ou peça ao administrador para permitir a origem (`mcp_allowed_origins`). | | 404 em uma requisição com `Mcp-Session-Id` | A sessão pertence a outra chave ou expirou | Execute `initialize` novamente. | | 405 em `GET /mcp` | Esperado: o servidor não possui fluxo de eventos | Use apenas POST (os clientes fazem isso automaticamente). | | A lista de ferramentas é curta | Escopos de chave ou módulos | Adicione escopos à chave; habilite o módulo. | | A ferramenta responde que precisa de `confirm: true` | Ferramenta paga, de exclusão ou sensível | O assistente deve definir `confirm` após a sua aprovação. | | 429 | Limite de taxa do MCP ou da chave | Aguarde `Retry-After`. | | O cliente não consegue se conectar com um cabeçalho | Cliente sem suporte a cabeçalho personalizado | Use a ponte `mcp-remote`. | --- # Configurar com IA {#configure-with-ai} > **Onde no admin:** AI Chat (`/agent`) e System › Settings › API & AI agents (`/agent/keys`). Tudo nestes páginas é exclusivo para administradores. ## O que faz {#what-it-does} A partir do NexCMP 1.4.0, você pode pedir a um assistente de IA que configure o painel para você: conectar o Proxmox VE ou CloudStack, criar uma zona, montar uma tabela de planos com base em seus custos, configurar e-mail, pagamentos e identidade visual, localizar um cliente ou exportar toda a configuração. O assistente opera por meio de um conjunto fixo de **ferramentas administrativas**. Ele nunca obtém acesso ao shell, nunca lê arquivos no servidor e nunca visualiza senhas ou chaves de API armazenadas. Use-o quando quiser uma configuração inicial em minutos em vez de navegar por dezenas de páginas, ou quando gerenciar várias instalações e quiser manter a configuração delas em um arquivo. ## Três maneiras de usar {#three-ways-to-use-it} | Forma | Quem fala com a IA | Onde é executado | Comece aqui | |---|---|---|---| | **AI Chat no admin** | Você, no painel administrativo do NexCMP | A fonte de IA escolhida: uma chave de API da OpenAI, Anthropic, Gemini ou OpenRouter, o provedor de IA próprio do seu painel ou uma CLI de IA oficial na qual você fez login | [AI Chat no admin](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/) | | **Seu próprio cliente de IA via MCP** | Você, no Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai ou ChatGPT | No seu computador ou no aplicativo do fornecedor, conectado ao seu painel em `https://cloud.example.com/mcp/admin` | [Connect an AI client](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/) | | **Configuração como código** | Você ou um script | Um arquivo YAML e o comando `nexcmp config` no servidor (ou na página Import/Export) | [Configuration as code](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/) | Todos os três chamam as mesmas ferramentas e passam pela mesma camada de segurança, permitindo combiná-los: rascunhar uma configuração com um assistente, exportá-la como YAML, revisá-la no editor e aplicá-la posteriormente. ## Modelo de segurança {#safety-model} | Regra | O que isso significa para você | |---|---| | **Escopos** | Uma chave ou conexão é limitada aos escopos marcados por você (`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`). Sem um escopo, a chamada é recusada. Consulte [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | Todas as chaves e conexões expiram: de 1 a 90 dias para as chaves criadas por você, sendo 30 dias o padrão. Os tokens de acesso OAuth duram uma hora. | | **Restrição de IP e limite de taxa** | Uma chave pode ser limitada a intervalos de IPs e a um número de chamadas por minuto (120 por padrão). | | **Confirmação em duas etapas** | Ações que movimentam dinheiro, excluem dados, alteram credenciais de pagamento ou modificam a segurança de login exibem uma prévia primeiro e não executam nada até que você aprove. No AI Chat, cada alteração é um cartão de confirmação acionado por você. | | **O que as chaves nunca podem fazer** | Criar administradores, alterar o 2FA, criar ou revogar chaves, entrar como cliente, realizar backup, restaurar ou atualizar o painel, entre ações similares. Essas tarefas exigem sua presença no painel administrativo. | | **Registro de atividades** | Cada chamada, permitida ou recusada, é registrada com a chave, o cliente, a ferramenta, o IP e o resultado. Consulte System › Settings › API & AI agents › Activity. | | **Dados confidenciais nunca são retornados** | Senhas, chaves de API e tokens podem ser definidos, mas nunca lidos de volta. As respostas que a IA vê os mostram mascarados. | | **Instalações de demonstração são somente leitura** | Em um painel de demonstração, toda gravação é recusada com `demo_read_only`. | ::: important O que a IA pode ler Com `admin:read`, um assistente pode ler nomes de clientes, endereços de e-mail, saldos e registros de faturamento. Quando você usa uma fonte de IA que roda em um fornecedor (OpenAI, Anthropic, Google, OpenRouter), esses dados são enviados a esse fornecedor para responder à sua pergunta. Dê a um assistente o menor conjunto de escopos de que ele precisa e escolha uma fonte em cuja segurança com esses dados você confia. ::: ## Início rápido {#quick-start} 1. Faça login no admin e abra **AI Chat**. Se nenhuma fonte de IA estiver conectada ainda, abra **System › Settings › AI accounts** e conecte uma (consulte [AI accounts and subscriptions](https://nexcmp.com/pt/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. Digite "Check my setup progress" e pressione Enter. O assistente lê o [Setup progress checklist](https://nexcmp.com/pt/docs/configure-with-ai/setup-checklist/) e informa o que falta. 3. Peça para ele fazer a próxima etapa. Revise cada cartão de confirmação e pressione **Confirm** para aplicá-lo. Para uma primeira olhada no que perguntar, consulte [Example prompts](https://nexcmp.com/pt/docs/configure-with-ai/example-prompts/). ![Página do AI Chat com uma conversa, um resultado de ferramenta e um cartão de confirmação](https://nexcmp.com/pt/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## Limites e notas {#limits-notes} - **Demonstração e somente leitura.** As páginas ficam visíveis em um painel de demonstração, mas nada pode ser salvo nele. - **Sem shell.** O assistente só pode chamar as ferramentas administrativas listadas em [Connect an AI client](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/#tools). Ele não pode executar comandos no servidor. - **Módulos de rede e roteamento** (BGP, XDP, interfaces, NAT e similares) são somente leitura para a IA, e áreas sensíveis como contas de administrador, backups e atualizações ficam totalmente fechadas para chaves. - **Preços** em USD: preços de planos em dólares por hora, saldos em centavos. - **Custo.** As respostas da IA são pagas à fonte de IA que você conectar (uso de API ou sua própria assinatura). No AI Chat, você pode definir um limite diário de gastos. Para o modelo de licenciamento do NexCMP, consulte https://nexcmp.com/pricing. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | AI Chat diz que nenhuma fonte de IA está conectada | Nenhuma fonte configurada para sua conta de administrador | Abra System › Settings › AI accounts e conecte uma. | | Um assistente responde `insufficient_scope` | A chave ou conexão não tem o escopo para essa ferramenta | Crie uma chave com o escopo necessário ou reconecte e marque-a na tela de consentimento. Consulte [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#errors). | | Cada alteração exibe um cartão de confirmação | Comportamento esperado no AI Chat | Pressione **Confirm** para aplicar ou **Reject** para cancelar. | | Gravações falham com `demo_read_only` | O painel está no modo de demonstração | Use uma instalação que não seja de demonstração. | --- # AI Chat no admin {#ai-chat-in-the-admin} > **Onde fica no admin:** AI Chat (`/agent`, sua própria entrada de menu) e o botão flutuante **Ask AI** em cada página do admin. As fontes de resposta são configuradas em System › Settings › AI accounts (`/agent/accounts`). ## O que faz {#what-it-does} O AI Chat é um assistente integrado ao admin. Você descreve o que deseja ("conectar meu cluster Proxmox", "configurar e-mail"), o assistente lê o estado atual com as ferramentas administrativas, propõe alterações e exibe cada uma como um **cartão de confirmação**. Nada é aplicado até que você pressione **Confirm**. O painel **Ask AI** é o mesmo chat em um painel lateral estreito, para que você possa fazer perguntas enquanto visualiza uma página. Botões como **Do it for me** (no [Setup progress checklist](https://nexcmp.com/pt/docs/configure-with-ai/setup-checklist/) e em listas vazias) o abrem com uma pergunta pronta. Não é o [AI Chat](https://nexcmp.com/pt/docs/ai/ai-chat/) e o [AI Agent](https://nexcmp.com/pt/docs/ai/ai-agent/) voltados para o cliente, que atendem aos seus clientes. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador conectado. Os chats, chaves e preferências pertencem à sua conta de administrador; outros administradores não os veem. | | Uma fonte de respostas | Pelo menos uma conectada: uma chave de API, um login, o próprio provedor de IA do painel ou uma CLI de IA na qual você fez login. Consulte [AI accounts and subscriptions](https://nexcmp.com/pt/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | Demo | Em um painel de demonstração, você pode ler chats antigos, mas não enviar mensagens. | ## Escolha de onde vêm as respostas {#choose-where-answers-come-from} Escolha a fonte no seletor abaixo da entrada (ele lista as fontes que você conectou). O caminho **System › Settings › AI accounts** também permite definir uma fonte padrão, um modelo padrão e o limite diário. | Source | Como você o conecta | Notas | |---|---|---| | OpenAI (modelos ChatGPT) | Cole uma chave de API de platform.openai.com | Cobrado pela OpenAI por uso. | | Anthropic (Claude) | Cole uma chave de API de console.anthropic.com | Cobrado pela Anthropic por uso. | | Google Gemini | Cole uma chave de API de aistudio.google.com ou use **Sign in with Google** | O login com o Google precisa de um cliente OAuth que **você** cria no seu próprio projeto do Google Cloud. | | OpenRouter | Cole uma chave ou **Sign in with OpenRouter** | Uma conta para vários modelos. | | Provedor de IA do painel | Já definido em System › Settings › AI provider | O mesmo provedor que o AI Chat dos seus clientes usa. [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/). | | Assinatura do Claude, ChatGPT ou Gemini | CLI oficial instalada e com sessão iniciada no servidor do painel | Consulte [AI accounts and subscriptions](https://nexcmp.com/pt/docs/configure-with-ai/ai-accounts-and-subscriptions/). | As chaves coladas são armazenadas criptografadas apenas para a sua conta de administrador. Elas nunca são exibidas novamente e outro administrador não pode descriptografá-las. ## Use o chat {#use-the-chat} 1. Abra o **AI Chat** (ou clique em **Ask AI**). 2. Clique em **New chat** ou abra um chat anterior na lista à esquerda. 3. Digite sua solicitação e pressione Enter (Shift+Enter inicia uma nova linha). Você pode anexar imagens ou arquivos de texto (até 4 por mensagem, 3 MB cada) para mostrar um erro ou colar um documento. 4. Observe a resposta ser gerada em tempo real. Cada ferramenta que o assistente chama aparece como um cartão recolhível com o nome da ferramenta, seus argumentos e um resultado curto. 5. Pressione **Stop** para cancelar uma resposta em execução. Apenas uma resposta é executada por vez por administrador. ![AI Chat com a lista de conversas, uma resposta contendo cartões de ferramentas e a entrada com o seletor de fonte e o campo Secret](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) Ocorrem até 10 rodadas de ferramentas por mensagem. O assistente lembra das últimas 30 mensagens do chat. Os resultados das ferramentas são passados para o modelo marcados como dados, não como instruções. ## Cartões de confirmação {#confirmation-cards} No AI Chat, **cada alteração é um cartão**, não apenas ações financeiras. O assistente propõe; você decide. Um cartão mostra: - Um título que diz por que ele precisa de atenção, por exemplo "altera o saldo de um cliente". - A chamada: método e caminho. - Uma tabela com os campos que sofrem alteração: o valor atual e o novo. Valores secretos aparecem como `••••`. - Uma contagem regressiva (os cartões expiram após 5 minutos). - **Confirm** e **Reject**. **Confirm** faz com que o próprio painel aplique a alteração e, em seguida, informa ao assistente o que aconteceu. O assistente não pode pressionar o botão, não pode aprovar por meio da API e é instruído a nunca afirmar que uma alteração foi aplicada antes de ser confirmada. Se você recarregar a página, os cartões que ainda forem válidos reaparecem. Eles também aparecem no topo de **System › Settings › API & AI agents** em "Waiting for your confirmation". ![Cartão de confirmação mostrando a alteração de saldo, a contagem regressiva e os botões Confirm e Reject](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Secrets {#secrets} Senhas e chaves de API não devem passar pelo texto do chat. Use o campo **Secret** (ícone de cadeado) ao lado da entrada: 1. Clique no ícone de cadeado e insira um **nome** (letras, dígitos e sublinhado, por exemplo `smtp_password`) e o **valor**. 2. Na sua mensagem, faça referência ao nome: "use o secret smtp_password como a senha SMTP". 3. O assistente vê apenas um espaço reservado que representa o secret, escrito assim: ```text {{secret:smtp_password}} ``` O painel o substitui pelo valor real no momento em que executa a ferramenta. O valor não é salvo no histórico do chat e não é enviado para a origem de IA. Se você colar por engano algo que pareça uma chave na mensagem, o painel a move para o mesmo armazenamento protegido e a oculta no histórico, mas trate isso como uma rede de segurança, não como um método. Os segredos permanecem apenas na memória do painel, durante a conversa em que foram inseridos e por até uma hora após a última mensagem; uma reinicialização do painel também os limpa. Insira-os novamente se o assistente solicitar. Definir um secret também requer a permissão `secrets:write` para a sessão de chat (consulte abaixo). ## Permissões do chat {#permissions-of-the-chat} Cada mensagem é executada com uma chave temporária que existe durante a duração da resposta (no máximo 15 minutos), funciona apenas a partir do servidor do painel e só pode ser usada por meio dos cartões de confirmação. Seus escopos são aqueles marcados em **System › Settings › AI accounts › Chat session permissions**. `admin:read` está sempre ativado. Todos os escopos, exceto `secrets:write`, vêm ativados por padrão; marque `secrets:write` se quiser que o assistente possa definir senhas e chaves (por meio do campo Secret). Em um painel de demonstração, o chat é somente leitura. ## Limite diário de gastos {#daily-spending-cap} O AI Chat soma o custo estimado das respostas das origens de API. O limite padrão é **5 USD por administrador por dia**. Defina outro valor (0 significa sem limite) em **AI accounts › Defaults for AI Chat**. A página exibe "used today". Quando o limite é atingido, o chat recusa novas mensagens (`daily_cap`) até o dia seguinte ou até que você aumente o limite. Origens que são assinaturas de CLI de IA não são contabilizadas, pois são cobradas pela sua assinatura. ## Verificar {#verify} 1. Em **AI accounts**, clique em **Test** na origem. Ela responde com o nome do modelo e o tempo em milissegundos. 2. No AI Chat, pergunte "Check my setup progress". A resposta lista as etapas da [checklist](https://nexcmp.com/pt/docs/configure-with-ai/setup-checklist/) e um cartão de ferramenta (`setup_checklist`) aparece. 3. Peça uma pequena alteração, por exemplo "Set the brand name to Example Cloud". Um cartão de confirmação é exibido; pressione **Confirm** e verifique a página de Branding. 4. **API & AI agents › Activity** lista as chamadas com o canal `chat`. ## Limites e notas {#limits-notes} - O assistente não possui shell e não pode ler arquivos no servidor. Ele apenas chama as [admin tools](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/#tools). - Alterações que as chaves nunca podem fazer ([list](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)) também não podem ser feitas pelo AI Chat. - Verifique o trabalho do modelo. Um cartão de confirmação mostra exatamente o que será enviado; leia-o atentamente, especialmente os preços e valores. - As respostas da API são cobradas pelo fornecedor de IA. O limite é uma estimativa; defina um limite de gastos também no fornecedor. - Uma resposta de CLI para após 5 minutos. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | "Limite de gastos de IA de hoje atingido" (`daily_cap`) | Você atingiu o limite diário | Aumente-o nas contas de IA ou aguarde até amanhã. | | "Outra resposta ainda está em execução - aguarde ou pressione Parar" (`busy`) | Uma resposta por vez por administrador | Pressione **Stop** ou aguarde. | | A origem não aparece no seletor | Ela não está conectada ou (no Claude CLI) o botão "I understand" está desativado | Conecte-a nas contas de IA. | | "isto não se parece com uma chave de API" | A chave colada contém espaços ou é muito longa | Cole apenas a chave. | | O teste falhou | Chave incorreta, sem crédito ou o provedor está fora do ar | Verifique a chave e a cobrança no provedor. | | O assistente diz que não pode fazer algo | A sessão de chat não tem o escopo ou a ação não é permitida para a IA | Marque o escopo nas contas de IA ou faça isso no painel administrativo. | | Um cartão indica que expirou | Mais de 5 minutos se passaram | Peça ao assistente para propor a alteração novamente. | | A origem CLI relata "usage limit" ou "not logged in" | Seu limite de assinatura ou sessão | Entre novamente ou aguarde; consulte [AI accounts and subscriptions](https://nexcmp.com/pt/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # Contas e assinaturas de IA {#ai-accounts-and-subscriptions} > **Onde no admin:** System › Settings › AI accounts (`/agent/accounts`), abas **Accounts** e **Use your own AI subscription**. O terminal opcional é o AI Console (`/agent/console`), que aparece em AI Chat apenas quando está ativado. ## O que faz {#what-it-does} O AI Chat precisa de algo para responder. Esta página permite que vocêp conecte essa origem para sua conta de administrador: - **Origens de API**: OpenAI, Anthropic (Claude), Google Gemini e OpenRouter, com uma chave de API ou login. - **O provedor de IA do painel**, se você já configurou um em System › Settings › AI provider. - **Sua própria assinatura de IA** (Claude, ChatGPT, Gemini) por meio da **ferramenta de linha de comando oficial** do provedor, seja no servidor do painel ou no seu próprio computador. Tudo o que você conecta pertence à sua conta de administrador. As chaves e os tokens são armazenados criptografados exclusivamente para você; outro administrador não pode usá-los. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Um administrador conectado. Em um painel de demonstração, nada pode ser conectado ou removido. | | Origens de API | Uma conta e uma chave de API no provedor (o cartão possui um link **Get API key** que abre a página do provedor). | | CLI no servidor do painel | AI Console ativado (consulte abaixo), HTTPS de saída do servidor para o provedor, para `nodejs.org` e para o registro npm, e **2 GB de RAM ou mais** (uma CLI precisa de cerca de 1 GB livre durante a execução; o instalador avisa se houver menos de 2 GB). O Node.js 20 ou mais recente é usado se presente; caso contrário, o instalador baixa o Node.js 22 com verificação de soma de verificação. | | CLI no seu computador | Node.js 20 ou mais recente para instalar a CLI e sua própria assinatura. | ## Conectar uma origem de API {#connect-an-api-source} 1. Abra **System › Settings › AI accounts** e permaneça em **Accounts**. 2. No cartão da fonte, clique em **Connect**. A página de chaves do fornecedor é aberta em uma nova aba; crie uma chave nela. 3. Cole a chave no campo e salve. O cartão exibe o estado conectado com os últimos quatro caracteres. 4. Escolha o **default model** se quiser outro, depois clique em **Test**. Um bom resultado aparece como "Connected - example-model, 850 ms". ![Página de contas de IA com os cartões de fonte de API, um cartão do OpenAI conectado e o cartão do provedor Panel AI](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | Alternativa de login | |---|---| | OpenRouter | **Sign in with OpenRouter** abre o OpenRouter em uma janela pop-up ou aba; aprove e você retornará a esta página conectado. | | Google Gemini | **Sign in with Google** aparece após você salvar, em **Set up Google sign-in (optional)** no cartão, um cliente OAuth criado no **seu próprio** projeto do Google Cloud (com ID de cliente terminando em `.apps.googleusercontent.com`, além do seu segredo). O NexCMP não inclui nenhum cliente Google compartilhado. | | Provedor de IA do painel | Usa o fornecedor já configurado em System › Settings › AI provider ([AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/)). Nada para colar. | Para desconectar uma fonte, clique em **Remove** no cartão dela. Isso exclui a chave armazenada para sua conta. ### Padrões, limite diário e permissões {#defaults-daily-cap-and-permissions} Na parte inferior da aba **Accounts**, **Defaults for AI Chat** possui três configurações: | Configuração | Significado | |---|---| | Fonte e modelo padrão | O que novas conversas usam. Você ainda pode alterar a fonte por mensagem. | | Limite de gastos diário (USD, 0 = sem limite) | Padrão 5. A página mostra "used today". Consulte [AI Chat in the admin](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | Permissões de sessão de chat | Os escopos que o assistente pode usar. `admin:read` está sempre ativado; `secrets:write` está desativado por padrão. Consulte [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#scopes). | Clique em **Save defaults**. ## Use sua própria assinatura de IA {#use-your-own-ai-subscription} Você pode gerenciar o NexCMP com um plano Claude, ChatGPT ou Gemini que você já paga, sem precisar de uma chave de API separada. Há duas maneiras. ### Maneira 1 (recomendada): a CLI no seu próprio computador {#way-1-recommended-the-cli-on-your-own-computer} Você usa a ferramenta do próprio fornecedor no seu computador e faz login com sua conta da maneira habitual do fornecedor. O NexCMP recebe apenas chamadas MCP assinadas com uma chave de curta duração. Abra **AI accounts › Use your own AI subscription**; ela exibe três etapas por ferramenta. 1. Clique em **Create a 7-day key** e escolha o nível: **Read only** (`admin:read`) ou **Read + configuration** (`admin:read`, `catalog:write`, `infra:write`, `settings:write`). Os comandos abaixo passam a conter a chave real. 2. Instale a CLI e faça login. A chave é exibida apenas nesta página e apenas uma vez. | Ferramenta | Instalação | Entrar | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | execute `claude`, depois `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | execute `gemini`, escolha "Login with Google" | 3. Conecte-a ao seu painel com um comando ou um bloco, copiado da página: ```bash # Claude Code claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` ```toml # Codex CLI: ~/.codex/config.toml, then: export NEXCMP_KEY=ak_XXXX [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` ```json // Gemini CLI: ~/.gemini/settings.json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` 4. Inicie a ferramenta e pergunte, por exemplo, "what is left to set up in nexcmp?". Todos os detalhes da conexão MCP estão em [Connect an AI client](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/). A mesma aba exibe a URL para os conectores do **claude.ai** e **ChatGPT**, que fazem login com OAuth e não precisam de chave: [OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/). ![Aba Usar sua própria assinatura de IA com o botão de chave de 7 dias e os comandos de instalação, login e conexão para três CLIs](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### Caminho 2: a CLI no servidor do painel (botões Install / Login) {#way-2-the-cli-on-the-panel-server-install-login-buttons} Os cartões em "Subscription through a CLI (Claude, ChatGPT, Gemini)" permitem que o NexCMP instale a CLI oficial no servidor do painel e abra seu próprio fluxo de login, para que o **AI Chat** possa responder com a sua assinatura. **Como é isolado.** As CLIs são executadas em um processo separado (`nexcmp-ai.service`) como seu próprio usuário do sistema `nexcmp-ai`, sem sudo, sem acesso aos dados e pastas de configuração do NexCMP e com limite de memória. Para cada mensagem do AI Chat, a CLI é iniciada permitindo apenas as ferramentas MCP do NexCMP (ferramentas de shell e arquivos estão desativadas) e uma chave que funciona apenas a partir do servidor. O NexCMP não lê nem copia o login da CLI: a CLI o mantém em uma pasta privada para a sua conta de administrador. Não há nada para ativar: o painel configura o usuário e o serviço `nexcmp-ai` quando é instalado ou atualizado para a versão 1.4.0, portanto os cartões estão prontos para uso. **Instalar e fazer login (por administrador):** 1. No cartão da CLI, clique em **Login**. Se a CLI ainda não estiver instalada, o painel a instala primeiro: uma barra de progresso e um log curto mostram o download (Node.js, se necessário, e depois a CLI). Um aviso aparece quando o servidor tem menos de 2 GB de RAM. 2. O cartão mostra o que a CLI solicita: - **Codex CLI**: clique em **Open the sign-in page** e digite o código de uso único exibido no cartão. (O login de dispositivo da OpenAI deve estar ativado nas configurações de segurança do seu ChatGPT.) - **Claude Code e Gemini CLI**: clique em **Open the sign-in page**, faça login e cole o código de verificação exibido pela página do fornecedor em **Paste the verification code here**, depois clique em **Send code**. 3. O cartão muda para "Signed in" com a conta e a versão. Um login não concluído em 10 minutos é cancelado; clique em **Login** novamente. 4. No **AI Chat**, a fonte agora aparece no seletor (por exemplo, "ChatGPT (via Codex CLI)"). 5. **Sign out** remove o login da CLI da sua conta. Para o Claude, o cartão possui um botão alternador extra, **I understand and accept the vendor's terms for using a subscription this way**, desativado por padrão. A fonte não é oferecida no AI Chat até que ele esteja ativado. ![Cartões de assinatura de CLI com Install e Login, um código de uso único no cartão do Codex e o botão de alternância I understand no cartão do Claude](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### Termos dos fornecedores de IA {#terms-of-the-ai-vendors} Fazer login com uma assinatura de consumidor é regido pelos termos de cada fornecedor, que mudam. As notas abaixo são um resumo do que os fornecedores publicam a partir de outubro de 2026, não constituem aconselhamento jurídico nem uma declaração em nome do fornecedor. Leia as páginas atuais antes de ativar esta opção. | Fornecedor | O que a página do fornecedor cobre | Source | |---|---|---| | Anthropic (Claude) | Fazer login no Claude Code não modificado com o seu próprio plano é coberto. O uso de uma assinatura por meio de outros produtos, ou ter um produto coletando ou repassando o login, é tratado de forma diferente, e os limites do plano pressupõem o uso individual comum. É por isso que o cartão do Claude traz um aviso e o botão **I understand**, e por que o Caminho 1 é a escolha mais limpa. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | O Codex oferece suporte a login com uma conta do ChatGPT ou uma chave de API. A OpenAI recomenda chaves de API para automação e diz para não expor o Codex em ambientes não confiáveis ou públicos. Use o cartão apenas para você mesmo. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | Suporta Login com o Google, uma chave de API e o Vertex AI; os termos dependem de como você faz login, e as cotas do seu plano se aplicam. | https://geminicli.com/docs/get-started/authentication | Se você quiser evitar totalmente a questão, use uma fonte de **API key** ou o Caminho 1 no seu próprio computador. ## AI Console {#ai-console} O AI Console é uma página de terminal opcional para executar uma das CLIs conectadas no servidor do painel. Ele vem **desativado por padrão**. - Ative ou desative e gerencie as CLIs no servidor: ```bash sudo nexcmp ai-console enable # turn on (also creates the nexcmp-ai user and service) sudo nexcmp ai-console disable # turn off sudo nexcmp ai-console status # runner, console state and installed CLIs sudo nexcmp ai-console install claude # or codex, or gemini ``` `status` exibe se o socket do executor de IA está pronto, se o AI Console está ativado ou desativado e, para cada CLI, "installed" ou "not installed". `sudo nexcmp status` também exibe "AI runner: active". - Uma vez ativado, a aba **AI Console** aparece em AI Chat. Escolha uma CLI conectada, insira novamente sua senha de administrador (e seu código 2FA, se o utilizar) e abra uma sessão. Um banner lembra que os comandos aqui só podem gerenciar o NexCMP por meio de suas ferramentas MCP; ferramentas de shell e de arquivos estão desativadas. - Instalações de demonstração nunca criam o usuário `nexcmp-ai`. ![Tela inicial do AI Console com o seletor de CLI, campo de senha e o banner de aviso exclusivo para MCP](https://nexcmp.com/pt/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## Verificar {#verify} 1. **Test** em uma fonte de API retorna o nome do modelo. 2. No card da CLI, o estado exibe "Signed in" junto com a conta. 3. No servidor: `sudo nexcmp ai-console status` lista a CLI como instalada e `systemctl is-active nexcmp-ai` exibe `active`. 4. No AI Chat, escolha a fonte, pergunte "Check my setup progress" e um card de ferramenta aparecerá. ## Limites e notas {#limits-notes} - Uma resposta de CLI é limitada a 5 minutos e a uma resposta por vez por administrador. O limite diário não contabiliza as respostas de CLI. - Cada alteração feita a partir de uma fonte de CLI continua gerando um card de confirmação no AI Chat; a CLI não pode aplicar alterações sozinha. - Os planos de assinatura possuem seus próprios limites de uso. Quando o fornecedor informa "usage limit" ou "not logged in", o chat exibe essa mensagem. - A remoção de uma fonte não exclui as conversas. - Mantenha o servidor atualizado: as CLIs são instaladas a partir dos pacotes públicos dos fornecedores no momento em que você clica em Install. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O login está desativado e o card exibe "AI tools are not ready on the server yet" | O serviço `nexcmp-ai` não está em execução | Atualize o painel para a versão mais recente e verifique `sudo nexcmp status`. Na demonstração somente leitura, isso é esperado. | | "Ferramentas de IA ainda não estão instaladas neste servidor" | O serviço `nexcmp-ai` não está em execução (painel mais antigo ou painel de demonstração) | Atualize o painel e execute `sudo nexcmp ai-console install claude` (ou `codex`, `gemini`). | | Aviso sobre RAM abaixo de 2 GB | O servidor é pequeno | A instalação pode ser lenta ou falhar; adicione memória ou use o Caminho 1. | | "Node.js download checksum mismatch" ou "download failed" | O servidor não consegue acessar nodejs.org ou um proxy alterou o download | Permita tráfego HTTPS de saída e tente novamente. | | A instalação termina com um erro | O npm não pôde instalar o pacote | Leia o log no card, verifique o acesso de saída ao registro do npm e tente novamente. | | O login termina com um erro ou esgota o tempo limite | A janela de 10 minutos expirou ou o código estava incorreto | Clique em **Login** novamente e conclua o processo mais rápido. | | A fonte do Claude está ausente no AI Chat | A chave **I understand** está desativada ou a CLI não está conectada | Ative a chave após ler a página do fornecedor e, em seguida, faça login. | | "Sign in with Google" está ausente no Gemini | Nenhum cliente OAuth do Google foi salvo ainda | Crie o cliente no seu próprio projeto do Google Cloud e salve-o em **Set up Google sign-in (optional)** no card, ou cole uma chave de API. | | "Sign in with OpenRouter" retorna um erro | Você cancelou ou o pop-up foi bloqueado | Permita pop-ups e tente novamente. | | A resposta da CLI diz "usage limit" | A cota do plano foi esgotada | Aguarde ou altere a fonte. | --- # Admin API keys {#admin-api-keys} > **Onde no admin:** System › Settings › API & AI agents (`/agent/keys`), aba **API keys**. A mesma página possui as abas **Connect an AI**, **Connected apps** e **Activity**. ## O que faz {#what-it-does} Uma chave de API de admin (com prefixo `ak_`) permite que um cliente de IA ou script gerencie seu painel com exatamente as permissões concedidas. Ela funciona na API de admin em `/v1/admin/` e no endpoint do MCP de admin `/mcp/admin`. Não funciona em nenhum outro lugar. ::: info Não é o mesmo que as chaves de cliente Os clientes criam chaves que começam com `vk_` no portal do cliente ([API keys and scopes](https://nexcmp.com/pt/docs/developers/api-keys/)). Elas alcançam apenas a API de cliente e `/mcp`. Uma chave `ak_` é recusada na API de cliente, e uma chave `vk_` é recusada na API de admin. ::: ## Requisitos {#requirements} | Item | Requisito | |---|---| | Função | Você deve estar conectado como admin. Chaves não podem criar outras chaves. | | Demo | Em um painel de demonstração, a página é somente leitura: nenhuma chave pode ser criada ou revogada. | | Acessibilidade | O cliente deve alcançar `https://cloud.example.com/mcp/admin` ou `/v1/admin/...` no seu painel (verifique seu firewall se usar restrições de IP). | ## Criar uma chave {#create-a-key} 1. Abra **System › Settings › API & AI agents** e permaneça na aba **API keys**. 2. Clique em **Create new key**. 3. Preencha o formulário: | Campo | Regras | |---|---| | Name | Até 60 caracteres, por exemplo "Claude Code no meu notebook". | | Escopos | Marque pelo menos uma. Consulte [Scopes](#scopes). Comece apenas com `admin:read`. | | Validade | 1, 7, 30, 60 ou 90 dias. Padrão 30. Máximo 90. Não é possível criar uma chave sem validade. | | Intervalos de IP (opcional) | Um endereço IPv4 ou IPv6 ou CIDR por linha, por exemplo `203.0.113.0/24` ou `2001:db8::/48`. No máximo 32. Deixe em branco para permitir qualquer IP. | | Chamadas por minuto | 1 a 6000. Padrão 120. | 4. Clique em **Create key**. Uma caixa exibe a chave uma única vez, por exemplo `ak_XXXX`. **Copie agora**: o NexCMP armazena apenas um hash e nunca mais poderá exibi-la. 5. Clique em **I have saved the key**. Abra a aba **Connect an AI** para obter comandos prontos para colar que já contêm a chave que você acabou de criar (apenas nesta página, até recarregá-la). ![Caixa de diálogo de nova chave com nome, caixas de seleção de escopo, validade e intervalo de IP preenchidos](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Caixa de diálogo exibindo a nova chave uma vez com um botão Copiar e um aviso](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Escopos {#scopes} Uma chave só pode usar as ferramentas e endpoints permitidos pelos seus escopos. Escopos de escrita não incluem acesso de leitura: uma chave que precisa ler e escrever também precisa de `admin:read`. | Escopo | O que ela permite | |---|---| | `admin:read` | Lê configurações, catálogo, clientes, faturamento e logs. Segredos nunca são retornados. | | `catalog:write` | Planos, modelos de SO, cotas, códigos de desconto. | | `infra:write` | Fontes de infraestrutura (CloudStack, Proxmox), zonas, servidores. | | `billing:write` | Gateways de pagamento, moeda, faturas, saldos. Ações financeiras exigem confirmação. | | `customers:write` | Clientes e revendedores. | | `settings:write` | Configurações gerais, identidade visual, e-mail, páginas legais, módulos, notificações. | | `ai:write` | O provedor de IA e os recursos de IA. | | `secrets:write` | Grava senhas e chaves de API. Elas podem ser definidas, mas nunca lidas novamente. | ::: tip Definir um segredo exige dois escopos Qualquer chamada que transporte uma senha, chave de API ou valor de token (uma senha SMTP, uma chave de pagamento, um token de bot do Telegram, uma chave de provedor de IA, credenciais do CloudStack ou Proxmox) precisa de `secrets:write` **e** o escopo da área (por exemplo, `settings:write` para SMTP). Se preferir digitar os segredos você mesmo, deixe `secrets:write` desativado e insira-os no painel administrativo. ::: ## Revogar uma chave {#revoke-a-key} 1. Encontre a chave na tabela (status **Active**, **Expired** ou **Revoked**; **Last used** mostra a hora e o cliente). 2. Clique em **Revoke** e confirme. A chave para de funcionar imediatamente. A revogação é permanente; crie uma nova chave se precisar de outra. ## O que uma chave nunca pode fazer {#what-a-key-can-never-do} Uma chave nunca pode alcançar estas áreas, independentemente de seus escopos. Elas exigem que você esteja conectado como administrador. - Criar ou alterar usuários administradores, 2FA e segurança de login, sessões de admin e os tokens de API do admin. - Criar, listar ou revogar chaves de admin, conexões OAuth e contas de IA, ou usar o AI Console. - Fazer backup ou restaurar o painel, atualizá-lo ou alterar sua licença. - Entrar como cliente ou revendedor, abrir o console de um cliente, ler credenciais de VM ou kubeconfig, definir chaves SSH, ou enviar ou redefinir senhas. - Alterar módulos de rede e roteamento (BGP, FRR, RTBH, XDP, interfaces, rotas estáticas e de política, NAT) ou agentes externos e integração de portal. Estes são somente leitura. - Alterar configurações como `demo_*`, `admin_*`, listas de hosts, passkey, reautenticação e segredos de captcha. Tudo o que não estiver coberto por uma regra é fechado por padrão para gravações e legível com `admin:read` para leituras. ### Ações que exigem sua confirmação {#actions-that-need-your-confirmation} Elas só são concluídas após você aprovar uma pré-visualização (consulte [Two-step confirmation](#two-step-confirmation)): - Alterar o saldo de um cliente ou a carteira de um revendedor, desembolsar dinheiro, registros de cobrança, a taxa de câmbio. - Alterar preços (preços de planos, criação em massa de planos, preços de imagens e armazenamento) e criar códigos de desconto ou de saldo. - Salvar credenciais de gateway de pagamento ou a conexão com o CloudStack. - Excluir qualquer coisa, bloquear ou excluir um cliente, alterar os limites de um cliente, suspender ou fechar um revendedor. - Agir em servidores de clientes ou criar um servidor pago para um cliente. - Alterar chaves de todo o site, configurações de segurança de login ou configurações de pagamento por meio das configurações gerais. ## Confirmação em duas etapas {#two-step-confirmation} Quando uma chamada exige confirmação, nada muda ainda. A resposta é HTTP **428** com `confirm_required`, um `confirm_token`, um `preview` (método, caminho, motivo, os novos valores e, quando disponíveis, os valores atuais) e `expires_in: 300`. 1. O cliente mostra a pré-visualização para você. 2. Após você aprovar, ele repete a **mesma** requisição (mesmo método, caminho e corpo) com o cabeçalho `X-Confirm-Token: `. As ferramentas de MCP aceitam o argumento `confirm_token` em vez disso. 3. O token funciona uma vez e expira após 5 minutos. Chaves criadas dentro do painel para o AI Chat só podem ser confirmadas na tela: a resposta diz `confirm_in: "ui"` e um cartão de confirmação aparece no painel administrativo. A IA não pode aprová-lo. ## Regras de limite de taxa e IP {#rate-limit-and-ip-rules} - Acima do limite por minuto, uma chamada retorna `rate_limited` (HTTP 429) com `Retry-After: 60`. - Com intervalos de IP definidos, chamadas de qualquer outro endereço retornam `ip_not_allowed` (HTTP 403). ## Activity log {#activity-log} A aba **Activity** lista todas as chamadas feitas com uma chave, da mais recente para a mais antiga: horário, chave, cliente, modo de envio (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), método e caminho, ferramenta, status HTTP, IP e os detalhes (mascarados). Você pode pesquisar por caminho, ferramenta ou nome da chave, exibir apenas erros (HTTP 400 ou superior) ou apenas chamadas aguardando confirmação (428 ou superior), e limitar o período para a última hora, 24 horas ou 7 dias. NexCMP mantém as 200,000 entradas mais recentes. As alterações feitas por meio de uma chave também aparecem em Logs › Admin actions sob o nome `ak:/`. ![Aba Activity listando chamadas com status, cliente, ferramenta e IP](https://nexcmp.com/pt/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verificar {#verify} Teste uma chave somente leitura de qualquer máquina que esteja dentro do intervalo de IPs: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Você obtém uma lista JSON das ferramentas permitidas pelos seus escopos. Execute uma: ```bash curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" -d '{}' ``` O horário de **Last used** da chave é atualizado e a chamada aparece em **Activity**. A lista completa de ferramentas e uma descrição OpenAPI (`/v1/admin/openapi.json`) estão descritas em [Connect an AI client](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/). ## Erros {#errors} Os erros são em JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Significado | Correção | |---|---|---|---| | 401 | `invalid_key` | A chave está ausente, malformada ou desconhecida. Também retornado quando uma chave `ak_` é usada em um caminho que não é de administração. | Verifique a chave; use-a apenas em `/v1/admin/` e `/mcp/admin`. | | 401 | `key_expired` | A validade da chave expirou. | Crie uma nova chave. | | 401 | `key_revoked` | A chave foi revogada. | Crie uma nova chave. | | 403 | `ip_not_allowed` | O IP do chamador está fora dos intervalos de IP da chave. | Faça a chamada a partir de um IP permitido ou crie uma chave com o intervalo correto. | | 403 | `local_only_key` | Uma chave criada para AI Chat ou para a CLI do servidor foi usada de outra máquina. | Essas chaves funcionam apenas no próprio servidor do painel. | | 403 | `insufficient_scope` | A chave não possui um escopo; a resposta inclui `required_scope`. | Crie uma chave com esse escopo. | | 403 | `forbidden_for_keys` | O endpoint, ou a configuração que você tentou alterar, está fechado para chaves. | Faça isso na administração. | | 403 | `demo_read_only` | O painel está no modo de demonstração e a chamada realiza gravações. | Use um painel que não esteja em modo de demonstração. | | 403 | `confirm_in_ui` | Esta ação deve ser confirmada na tela na administração. | Aprove o cartão de confirmação. | | 428 | `confirm_required` | Uma prévia está pronta; nada foi alterado. Inclui `confirm_token`. | Exiba a prévia e repita com `X-Confirm-Token`. | | 409 | `confirm_expired` | O token tem mais de 5 minutos. | Envie a solicitação novamente para obter uma nova prévia. | | 409 | `confirm_mismatch` | O token pertence a uma solicitação diferente (método, caminho ou corpo diferem). | Repita exatamente a mesma solicitação. | | 409 | `confirm_invalid` | Token desconhecido ou já utilizado. | Envie a solicitação novamente para obter uma nova prévia. | | 429 | `rate_limited` | Muitas chamadas neste minuto. | Aguarde `Retry-After`. | | 400 | `invalid_path` | O caminho contém sequências proibidas. | Use um caminho simples. | | 413 | `too_large` | O corpo tem mais de 10 MB. | Envie menos dados. | | 400 | `invalid_argument` | Um argumento de ferramenta está ausente, é desconhecido ou tem o tipo incorreto; a mensagem o identifica. | Corrija o argumento. | ## Limites e notas {#limits-notes} - Mantenha as chaves de curta duração e escopo restrito. Prefira uma chave por cliente para poder revogar uma única chave. - Uma chave é tão poderosa quanto seus escopos. `secrets:write` mais `billing:write` é a combinação mais sensível; ações financeiras ainda param em uma prévia. - Chaves criadas automaticamente (para o AI Chat, a CLI do servidor) duram apenas alguns minutos e funcionam somente a partir do servidor do painel. - Para cortar o acesso de um cliente de IA imediatamente, revogue sua chave. As conexões OAuth são revogadas na aba **Connected apps** ([OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/)). --- # Conectar um cliente de IA (MCP) {#connect-an-ai-client-mcp} > **Onde encontrar no admin:** System › Settings › API & AI agents (`/agent/keys`), a aba **Connect an AI** mostra a URL do endpoint e um trecho pronto para copiar para cada cliente, preenchido com uma chave que você acabou de criar. ## O que faz {#what-it-does} O **Model Context Protocol (MCP)** permite que um cliente de IA chame ferramentas. Seu painel hospeda um servidor MCP de administração em `https://cloud.example.com/mcp/admin`. Conecte sua própria ferramenta de IA a ele e pergunte em linguagem natural: "o que falta configurar?", "adicione meu cluster Proxmox", "crie planos com margem de 40%". O cliente chama as ferramentas de administração abaixo; o painel verifica os escopos, pede sua confirmação antes de qualquer ação de risco e registra cada chamada. ::: info Dois endpoints MCP `/mcp` é o endpoint de **clientes** (chaves de API de clientes, `vk_`; consulte [MCP server](https://nexcmp.com/pt/docs/developers/mcp/)). `/mcp/admin` é o endpoint de **administração** descrito aqui (chaves de administrador `ak_` ou OAuth). Os dois nunca se misturam: as ferramentas de administração não ficam visíveis em `/mcp`, e `/mcp/admin` aceita apenas chaves de administrador. ::: ## Requisitos {#requirements} | Item | Requisito | |---|---| | Endpoint | `https://cloud.example.com/mcp/admin` no domínio do seu próprio painel. Copie a URL exata na aba **Connect an AI**. A mesma página lista uma URL local (`http://127.0.0.1:/mcp/admin`) para ferramentas executadas no próprio servidor. | | Credenciais | Uma [admin API key](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/) (`ak_...`) com os escopos desejados, **ou** login OAuth para conectores web ([OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/)). | | Cliente | Qualquer cliente MCP que suporte o transporte **Streamable HTTP** e um cabeçalho customizado `Authorization`. Versões de protocolo 2025-11-25, 2025-06-18 e 2025-03-26. | | Rede | Se você colocar seu próprio proxy reverso na frente do painel, ele deverá repassar `/mcp/admin`. Os conectores web (claude.ai, ChatGPT) se conectam a partir dos servidores do fornecedor, portanto a URL deve estar acessível pela internet. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada para instalar no servidor. Se você restringir a chave por IP, certifique-se de que o endereço de onde seu cliente se conecta está no intervalo. Teste a acessibilidade primeiro: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` Uma resposta `401` com um cabeçalho `WWW-Authenticate: Bearer ... resource_metadata=...` significa que o endpoint está ativo e requer credenciais. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Crie uma chave: **System › Settings › API & AI agents › API keys › New key**. Para um primeiro teste, use apenas `admin:read`; adicione escopos de gravação quando precisar. Veja [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/). 2. Abra a aba **Connect an AI**. Enquanto a caixa de diálogo "key created" estiver visível, cada trecho abaixo já contém sua chave real. Caso contrário, ele exibirá o espaço reservado `ak_YOUR_KEY`. 3. Copie o trecho para o seu cliente e execute-o ou cole-o conforme descrito a seguir. ![Aba Connect an AI com a URL MCP e um cartão com botão de cópia por cliente](https://nexcmp.com/pt/docs/images/configure-with-ai/mcp-admin-01-connect.webp) ### Claude Code {#claude-code} ```bash claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` Em seguida, inicie o `claude` e pergunte "list the tools from nexcmp" ou "what is left to set up?". Verificado em 30/10/2026 com o Claude Code 2.1: `claude mcp add --transport http …` grava no servidor (adicione `-s project` para mantê-lo no `.mcp.json` do projeto — o Claude Code pede sua aprovação para servidores de projetos na primeira vez). Para scripts, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` é executado sem o prompt de aprovação e permite que o Claude use apenas as ferramentas do painel. ### Claude Desktop {#claude-desktop} Requer Node.js 18 ou mais recente. Adicione isto a `claude_desktop_config.json` (ele usa a ponte `mcp-remote`) e reinicie o Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` Se o seu sistema corromper o espaço no argumento do cabeçalho, coloque o valor inteiro em uma variável de ambiente, exatamente como para o endpoint de cliente: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` com `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (conector customizado) {#claude-ai-custom-connector} Nenhuma chave necessária: ele faz login com OAuth. No claude.ai, abra as configurações de conectores, adicione um conector customizado, cole `https://cloud.example.com/mcp/admin`, faça login com sua conta de administrador do NexCMP e escolha as permissões na tela de consentimento. Detalhes: [OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (modo de desenvolvedor) {#chatgpt-developer-mode} Nenhuma chave necessária. No ChatGPT, ative o modo de desenvolvedor, adicione um conector MCP com a URL `https://cloud.example.com/mcp/admin`, escolha OAuth e faça login com sua conta de administrador do NexCMP. Detalhes: [OAuth connectors](https://nexcmp.com/pt/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Adicionar a `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` Em seguida, exporte a chave no shell que inicia o Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip Não interativo `codex exec` Em `codex exec` (scripts, CI), o Codex não pede confirmação antes de chamar ferramentas e pula ferramentas que alteram dados. Adicione `default_tools_approval_mode = "approve"` sob `[mcp_servers.nexcmp]` para permitir que ele as chame; o painel ainda retorna uma prévia e pede confirmação para ações de dinheiro, segurança e exclusão. Verificado com o Codex CLI 0.166 em 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Adicionar a `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` O Gemini CLI desativa servidores MCP em pastas nas quais não confia. Inicie-o em uma pasta confiável (ou confie na pasta quando solicitado) e verifique com `gemini mcp list` — ele exibe `nexcmp … Connected`. Você pode manter a chave fora do arquivo com `"Authorization": "Bearer $NEXCMP_KEY"`. Verificado com o Gemini CLI 0.66 em 30/10/2026. ### Cursor {#cursor} Adicionar a `~/.cursor/mcp.json` (ou `.cursor/mcp.json` em um projeto): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip Mantenha a chave fora dos arquivos de configuração Onde o cliente suporta, leia a chave de uma variável de ambiente em vez de gravá-la no arquivo: o Codex faz isso por padrão (`bearer_token_env_var`), e o Cursor aceita `"Bearer ${env:NEXCMP_KEY}"`. Nunca faça commit de um arquivo que contenha uma chave. ::: ### OpenAI Agents SDK (Python) {#openai-agents-sdk-python} ```python from agents.mcp import MCPServerStreamableHttp nexcmp = MCPServerStreamableHttp( params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp", ) ``` Uma execução completa (verificada com `openai-agents` 0.24 em 30/10/2026 — uma ferramenta de leitura, seguida por uma alteração de saldo que retornou a prévia de confirmação e foi aplicada na segunda chamada com `confirm_token`): ```python import asyncio from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def main(): async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp: agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp], instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.") result = await Runner.run(agent, "Run system_health and summarise it in one line.") print(result.final_output) asyncio.run(main()) ``` ### OpenAI Responses API {#openai-responses-api} Passe o servidor como uma ferramenta do tipo `mcp`. Mantenha `require_approval` ativado em `always` para que seu programa pergunte antes de cada chamada: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### Qualquer outra coisa (HTTP simples) {#anything-else-plain-http} Um cliente sem MCP pode chamar as mesmas ferramentas via HTTP. `GET /v1/admin/agent/tools` as lista, `POST /v1/admin/agent/tools/` executa uma com um corpo JSON de argumentos e `GET /v1/admin/openapi.json` retorna uma descrição OpenAPI 3.1 (cada ferramenta é uma operação). Todas exigem `Authorization: Bearer ak_...`. ## Verificar {#verify} 1. Sem um cliente, liste as ferramentas: ```bash curl -s https://cloud.example.com/mcp/admin \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` A resposta é um resultado JSON-RPC com as ferramentas que seus escopos permitem. 2. No seu cliente, pergunte "run system_health". Ele retorna alertas, a integridade da infraestrutura conectada, pagamentos, e-mail, IA e o estado da licença. 3. Abra **API & AI agents › Activity**: as chamadas são listadas com o nome do cliente e `mcp`. 4. No servidor, `sudo nexcmp status` imprime uma linha "MCP admin" que diz `ready` quando o endpoint responde (HTTP 401 sem uma chave é o estado saudável). ## Ferramentas {#tools} O servidor oferece 58 ferramentas. Um cliente vê apenas as ferramentas permitidas pelos escopos da sua chave: ferramentas de leitura precisam de `admin:read`, ferramentas de gravação precisam de seu próprio escopo. Ferramentas de gravação também recebem um argumento opcional `confirm_token` (consulte [Confirmation](#confirmation-confirm-token)). Os argumentos são validados contra o esquema de cada ferramenta: argumentos desconhecidos ou digitados incorretamente são rejeitados com uma mensagem que os identifica. Os preços estão em USD: preços de planos em dólares por hora (`hourly_usd`), saldos em centavos. Segredos podem ser definidos, mas nunca são retornados. ### Visão geral e logs {#overview-and-logs} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `system_health` | Alertas que exigem atenção, integridade da infraestrutura, pagamentos, e-mail, IA, licença e status de atualização. | `admin:read` | Não | Não | | `setup_checklist` | O que está configurado e o que falta: licença, infraestrutura, zona, modelos de SO, planos, pagamentos, e-mail, identidade visual, termos legais, pedido de teste. | `admin:read` | Não | Não | | `license_status` | Status da licença e se existe uma versão mais recente do NexCMP. | `admin:read` | Não | Não | | `audit_search` | Pesquisar no log de auditoria do administrador e no log de chaves de API. | `admin:read` | Não | Não | ### Configurações, identidade visual, termos legais, módulos {#settings-branding-legal-modules} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `settings_get` | Ler configurações gerais (`keys` filtra; um `*` no final corresponde a um prefixo). | `admin:read` | Não | Não | | `settings_update` | Alterar configurações gerais a partir de um objeto `values` plano. Apenas chaves listadas por `settings_get` são aceitas. | `settings:write` | Sim | Quando uma chave afeta pagamentos, segurança de login, chaves globais do site ou preços | | `branding_get` | Nome da marca, cor, moeda de exibição, nome do vendedor, URLs do logotipo e do favicon. | `admin:read` | Não | Não | | `branding_update` | Definir nome da marca (até 60 caracteres), cor (`#rrggbb`), moeda de exibição (`usd` ou `vnd`) e nome do vendedor. | `settings:write` | Sim | Não | | `branding_logo_set` | Faça o upload de um logotipo claro ou escuro ou de um favicon a partir de uma URL https ou base64 (PNG, JPEG, WEBP, ICO ou SVG, até 512 KB). | `settings:write` | Sim | Não | | `legal_get` | Termos de serviço e política de privacidade (em inglês e vietnamita) e os padrões neutros. | `admin:read` | Não | Não | | `legal_update` | Defina o texto dos termos e da privacidade (markdown simples, sem HTML, até 50 KB cada). Uma string vazia restaura o padrão. | `settings:write` | Sim | Não | | `modules_get` | Quais módulos opcionais estão ativados e quais podem ser alternados. | `admin:read` | Não | Não | | `module_set` | Ative ou desative um módulo opcional (`key` deve ser um de `settable`). | `settings:write` | Sim | Não | ### E-mail e alertas {#email-and-alerts} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `smtp_get` | Configurações de e-mail de envio (senha mascarada) e status da fila. | `admin:read` | Não | Não | | `smtp_configure` | Configure o servidor SMTP. A alteração de host, porta ou segurança exige a senha novamente. | `settings:write` (+ `secrets:write` para a senha) | Sim | Não | | `smtp_test` | Envie um e-mail de teste real com as configurações salvas. | `settings:write` | Envia um e-mail | Não | | `telegram_get` | Canais de notificação do administrador (IDs de chat; tokens de bot nunca são retornados). | `admin:read` | Não | Não | | `telegram_configure` | Adicione ou atualize o canal de alerta do Telegram (token do bot e ID do chat) e ative ou desative os alertas de administrador. | `settings:write` (+ `secrets:write` para o token) | Sim | Não | | `telegram_test` | Envie uma mensagem de teste para o canal do Telegram. | `settings:write` | Envia uma mensagem | Não | ### Pagamentos e moeda {#payments-and-currency} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `payments_get` | Status de Stripe, PayPal, criptomoeda (USDT) e transferência bancária, além de canais ativados e taxas. | `admin:read` | Não | Não | | `payment_configure` | Defina as credenciais de um gateway (`stripe`, `paypal`, `crypto` ou `bank`). | `billing:write` (+ `secrets:write`) | Sim | Sempre | | `payment_test` | Verifique as credenciais salvas de um gateway com o provedor. | `billing:write` | Não | Não | | `currency_get` | Moeda de exibição e a taxa de USD para VND (automática ou manual). | `admin:read` | Não | Não | | `currency_set` | Defina a moeda de exibição e/ou uma taxa manual (0 significa automático, caso contrário, de 15000 a 50000). | `billing:write` | Sim | Quando você altera a taxa manual | ### Infraestrutura e zonas {#infrastructure-and-zones} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `cloudstack_get` | Endpoint, zona e IDs de rede do CloudStack salvos (chaves mascaradas). | `admin:read` | Não | Não | | `cloudstack_test` | Teste um endpoint com uma chave de API e segredo sem salvar; lista as zonas. | `infra:write` (+ `secrets:write`, porque você passa as chaves) | Não | Não | | `cloudstack_connect` | Salve a conexão com o CloudStack. | `infra:write` (+ `secrets:write`) | Sim | Sempre | | `proxmox_list` | Clusters do Proxmox VE adicionados como origens, com status de saúde. | `admin:read` | Não | Não | | `proxmox_add` | Adicione um cluster do Proxmox VE com um token de API (`user@realm!tokenid`) e seu segredo. | `infra:write` (+ `secrets:write`) | Sim | Não | | `proxmox_test` | Conecte-se a um cluster por ID; o primeiro sucesso fixa seu certificado TLS. | `infra:write` | Sim | Não | | `proxmox_attach_zone` | Venda um cluster Proxmox em uma zona existente, opcionalmente com um nó como região. | `infra:write` | Sim | Não | | `zones_list` | Zonas (localizações) que os clientes podem escolher. | `admin:read` | Não | Não | | `zone_create` | Crie uma zona. | `infra:write` | Sim | Não | ### Catálogo e planos {#catalog-and-plans} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `templates_list` | Modelos de SO que os clientes podem instalar. | `admin:read` | Não | Não | | `templates_sync` | Importe modelos de SO do CloudStack. | `catalog:write` | Sim | Não | | `template_update` | Ative ou oculte um modelo, renomeie-o, defina o usuário de login ou a ordem. | `catalog:write` | Sim | Não | | `offerings_list` | Ofertas de serviço do CloudStack (CPU, memória, disco raiz) para criar planos. | `admin:read` | Não | Não | | `plans_list` | Planos com preço por hora e por mês, tamanho, zona e quantos servidores os utilizam. | `admin:read` | Não | Não | | `plan_create` | Crie um plano. Preço como `hourly_usd`. Os planos do CloudStack precisam de `cs_offering_id`; os planos do Proxmox precisam de `backend_id`. | `catalog:write` | Sim | Não | | `plan_update` | Renomeie, exiba ou oculte, ative ou desative, ou reprecifique um plano. Alterações de tamanho em um plano em uso exigem uma cópia. | `catalog:write` | Sim | Quando o preço muda | | `plans_from_offerings` | Gere uma tabela de planos iniciais a partir de ofertas (ou tamanhos do Proxmox) usando seu custo e uma porcentagem de margem. Retorna uma prévia; chame novamente com `apply=true` para criar os planos. | `catalog:write` | Com `apply=true` | Sempre na aplicação | | `quota_defaults_get` | Limites padrão de clientes. | `admin:read` | Não | Não | | `quota_defaults_set` | Alterar configurações de `quota_*`. | `catalog:write` | Sim | Não | | `coupons_list` | Lotes de códigos de desconto e brinde. | `admin:read` | Não | Não | | `coupon_create` | Criar um lote de códigos: tipo `money` (valor nominal em centavos de USD) ou `percent` (1 a 100, com desconto máximo). | `catalog:write` | Sim | Sempre | ### Clientes e revendedores {#customers-and-resellers} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `customers_search` | Localizar clientes por e-mail, nome ou IP. | `admin:read` | Não | Não | | `customer_get` | A conta, o saldo, os servidores e o faturamento recente de um cliente. | `admin:read` | Não | Não | | `customer_adjust_balance` | Adicionar (positivo) ou remover (negativo) crédito em centavos de USD. Um motivo é obrigatório. | `billing:write` | Sim | Sempre | | `customer_block` | Bloquear um cliente, opcionalmente parando seus servidores. Um motivo é obrigatório. | `customers:write` | Sim | Sempre | | `customer_unblock` | Desbloquear um cliente. | `customers:write` | Sim | Não | | `resellers_list` | Revendedores com carteira e status. | `admin:read` | Não | Não | | `reseller_get` | O site, a carteira, os usuários e os gateways de um revendedor. | `admin:read` | Não | Não | ### Provedor de IA {#ai-provider} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `ai_provider_get` | O provedor compatível com OpenAI usado pelo AI Chat e pelo AI Agent do cliente (chave mascarada). | `admin:read` | Não | Não | | `ai_provider_set` | Definir o provedor: URL base, modelo, chave de API, modelos de fallback, esforço de raciocínio, ativado. | `ai:write` (+ `secrets:write` para a chave) | Sim | Não | | `ai_provider_test` | Fazer uma pergunta ao provedor salvo para verificar se funciona. | `ai:write` | Não | Não | ### Arquivos de configuração {#configuration-files} | Ferramenta | O que faz | Escopo | Altera dados | Pede confirmação | |---|---|---|---|---| | `config_export` | Exportar a configuração como YAML (segredos se tornam referências `secret://`). | `admin:read` | Não | Não | | `config_plan` | Comparar uma configuração YAML com o painel ativo e listar o que mudaria. | `admin:read` | Não | Não | | `config_apply` | Aplicar uma seção de configuração YAML por seção. Cada alteração segue o escopo normal e as regras de confirmação. | `admin:read` + o escopo de cada alteração | Sim | Por alteração | Consulte [Configuration as code](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/) para ver o formato do arquivo. ## Prompts {#prompts} O servidor também oferece três prompts prontos que os clientes podem exibir como atalhos: | Prompt | Argumento | O que pede para a IA fazer | |---|---|---| | `initial-setup` | nenhum | Chamar `setup_checklist`, explicar cada etapa aberta em uma frase, pedir as informações necessárias, executar a etapa com a ferramenta correspondente, pré-visualizar alterações de dinheiro ou segurança e concluir com `system_health`. | | `add-proxmox` | `endpoint` (opcional, `https://host:8006`) | Pedir o token de API, depois `proxmox_add`, `proxmox_test`, ferramentas de zona e `proxmox_attach_zone`; então propor planos com `plans_from_offerings` e aguardar sua aprovação. | | `launch-pricing` | `margin_pct` (opcional, padrão 40) | Pedir seu custo mensal por vCPU, por GB de RAM e por GB de disco, mostrar uma tabela de visualização com custo, preço por mês e preço por hora, e criar os planos após sua aprovação. | ## Confirmação (`confirm_token`) {#confirmation-confirm-token} Ações que movimentam dinheiro, excluem dados, alteram credenciais de pagamento ou segurança de login são de duas etapas: 1. A primeira chamada não altera nada. O resultado da ferramenta começa com "CONFIRMATION REQUIRED" e inclui uma **prévia** (o que será chamado, por que é confiden_cial, os novos valores e os atuais) e um `confirm_token`. 2. O cliente deve mostrar a prévia a você. Somente após sua aprovação ele chama a mesma ferramenta novamente com os mesmos argumentos mais `confirm_token`. 3. O token funciona uma vez, apenas para essa solicitação exata, e expira após 5 minutos. As instruções do servidor dizem à IA para tratar os resultados de ferramentas como dados, nunca como instruções, e jamais repetir uma chamada com um token que você não aprovou. Você é a salvaguarda: leia a prévia. ::: warning Não aprove automaticamente Alguns clientes podem aprovar cada chamada de ferramenta automaticamente. Para ferramentas de gravação, mantenha a aprovação por chamada ativada ou use uma chave somente leitura, para que um plano incorreto da IA não chegue ao seu painel sem ser visto. ::: ## Como funciona {#how-it-works} | Item | Detalhe | |---|---| | Transporte | `POST /mcp/admin` com uma mensagem JSON-RPC 2.0; a resposta é `application/json`. Até 20 mensagens em lote. `GET /mcp/admin` responde 405 (sem fluxo no servidor); `DELETE /mcp/admin` encerra uma sessão. | | Autenticação | `Authorization: Bearer ak_...` (uma chave manual ou um token de acesso OAuth). Credenciais ausentes ou incorretas retornam 401 com `WWW-Authenticate: Bearer ... resource_metadata=...`, o que permite que clientes OAuth iniciem o login por conta própria. | | Sessões | `Mcp-Session-Id` é emitido por `initialize`, vinculado a essa chave e válido por 24 horas. | | Capacidades | Ferramentas e prompts. Sem recursos. | | Tamanho | Corpo da requisição de até 1 MB; o resultado de uma ferramenta é cortado após cerca de 100 KB. | | Origem | Uma requisição contendo um cabeçalho `Origin` de outro site é recusada (`origin_not_allowed`). Clientes de linha de comando e desktop não enviam nenhum. | | Mesmo portão que a REST | Cada chamada de ferramenta é reenviada através do pipeline de requisições do próprio painel com sua chave, portanto, escopos, intervalos de IP, limite de taxa, confirmação e o log de atividades se aplicam exatamente como nas chamadas diretas de API. | ## Limites e notas {#limits-notes} - Uma ferramenta que você não consegue ver é um escopo que você não concedeu. Adicione o escopo a uma nova chave. - Definir uma senha ou chave de API por meio de um cliente de IA significa que o segredo passa por essa IA. Se preferir, deixe `secrets:write` desativado e insira os segredos você mesmo no admin, ou use o campo **Secret** do AI Chat ([AI Chat in the admin](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/#secrets)) ou referências `secret://` ([Configuration as code](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/#secrets)). - Os clientes não compartilham sessões: cada conexão começa com `initialize`. - Revogue a chave em **API & AI agents** para cortar o acesso de um cliente de IA imediatamente. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | 401 `invalid_key` | Chave incorreta, truncada ou que não seja de admin (por exemplo, uma chave `vk_`) | Use uma chave `ak_`. | | 401 `key_expired` ou `key_revoked` | A chave esgotou ou foi revogada | Crie uma nova chave. | | 403 `ip_not_allowed` | Seu IP está fora dos intervalos de IP da chave | Conecte-se a partir de um IP permitido. | | 403 `origin_not_allowed` | Uma página de navegador em outra origem chamou o endpoint | Use um cliente de desktop ou CLI. | | 404 em uma requisição com `Mcp-Session-Id` | A sessão pertence a outra chave ou expirou | Envie `initialize` novamente. | | 400 unsupported `MCP-Protocol-Version` | O cliente usa uma versão que o servidor desconhece | Atualize o cliente; suportados: 2025-11-25, 2025-06-18, 2025-03-26. | | A lista de ferramentas é curta | Escopos da chave | Crie uma chave com mais escopos. | | `insufficient_scope` em uma chamada | Uma ferramenta precisa de um segundo escopo, por exemplo `secrets:write` | Adicione o escopo a uma nova chave. | | 429 `rate_limited` | Mais chamadas por minuto do que a chave permite | Aguarde por `Retry-After` ou aumente o limite em uma nova chave. | | claude.ai ou ChatGPT não conseguem se conectar | A URL não é alcançável a partir da internet, ou um proxy bloqueia `/mcp/admin` ou `/oauth-admin/` | Verifique o DNS, o TLS e o proxy reverso. | Para todos os códigos de erro, consulte [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#errors). --- # Conectores claude.ai e ChatGPT {#claude-ai-and-chatgpt-connectors} > **Onde no admin:** System › Settings › API & AI agents (`/agent/keys`), aba **Connected apps**. A tela de consentimento é aberta em `/agent/consent` quando um conector solicita acesso (ela não fica no menu). ## O que faz {#what-it-does} Aplicativos de IA na web não podem ler uma chave do seu disco. Eles se conectam com **OAuth**: você adiciona a URL de MCP do painel, o aplicativo o direciona para o seu próprio admin para fazer login, você escolhe o que o aplicativo pode fazer e por quanto tempo, e o aplicativo recebe tokens de curta duração. Nenhuma chave é copiada ou colada. Você pode cortar o acesso do aplicativo a qualquer momento. Use isto para conectores personalizados do claude.ai, conectores em modo de desenvolvedor do ChatGPT e qualquer outro cliente MCP que ofereça suporte a OAuth com registro dinâmico de clientes. Ferramentas de linha de comando podem usar o mesmo fluxo, mas uma [chave de API de admin](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/) é mais simples para elas. ## Requisitos {#requirements} | Item | Requisito | |---|---| | URL | `https://cloud.example.com/mcp/admin`, acessível pela internet (os servidores do fornecedor se conectam a ele). | | Proxy reverso | Se você colocar seu próprio proxy na frente do painel, ele deverá encaminhar os caminhos `/mcp/admin`, `/oauth-admin/` e `/.well-known/` para o painel. | | Você | Logado no admin do NexCMP **no mesmo navegador** que você usa para a tela de consentimento. | | Cliente | Suporta MCP sobre HTTP streamable, OAuth 2.1 com PKCE (S256) e registro dinâmico de clientes. | ## Conectar {#connect} 1. No aplicativo de IA, adicione um conector MCP personalizado e cole `https://cloud.example.com/mcp/admin`. No claude.ai, isso fica nas configurações de conectores (adicionar conector personalizado); no ChatGPT, fica no modo de desenvolvedor (adicionar um conector MCP, autenticação OAuth). 2. Escolha **Sign in** (ou "Connect") no aplicativo. Seu navegador abre a tela de consentimento do admin do NexCMP. Se você não estiver logado, faça login primeiro; a tela continuará em seguida. 3. Leia o cartão: "**Example AI app** wants to manage this NexCMP admin" (o nome do aplicativo que está solicitando), junto com o endereço para o qual você será enviado de volta. 4. Marque os escopos a serem concedidos. Os que o aplicativo solicitou já vêm marcados; se ele não solicitou nenhum, apenas `admin:read` estará marcado. Consulte [Scopes](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#scopes). 5. Escolha quanto tempo a conexão dura: **7**, **30** ou **90** dias (padrão 30). 6. Clique em **Allow**. O navegador retorna ao aplicativo, que agora está conectado. Clique em **Deny** para recusar. ![Tela de consentimento solicitando permissão para um aplicativo de IA, com caixas de seleção de escopo, escolha de duração e botões Allow e Deny](https://nexcmp.com/pt/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important Escolha os escopos como faria para uma chave Conceda o menor conjunto que realize a tarefa. Dinheiro, ações de exclusão e de segurança ainda param em uma prévia e precisam da sua aprovação, mas uma conexão com `settings:write` ainda pode alterar sua identidade visual e seu e-mail. ::: ## Gerenciar e revogar {#manage-and-revoke} Abra **System › Settings › API & AI agents › Connected apps**. A tabela lista cada aplicativo que você conectou: aplicativo, escopos, quando se conectou, quando expira e quando foi usado pela última vez. Para cortar o acesso de um aplicativo, clique em **Revoke** e confirme. Os tokens dele deixam de funcionar imediatamente; o aplicativo precisará passar pela tela de consentimento novamente para se reconectar. ![Aba Connected apps listando um aplicativo de IA com seus escopos, expiração e um botão Revoke](https://nexcmp.com/pt/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## Como o fluxo funciona {#how-the-flow-works} | Etapa | Detalhe | |---|---| | Descoberta | O aplicativo lê `/.well-known/oauth-protected-resource/mcp/admin` e depois `/.well-known/oauth-authorization-server/oauth-admin`. O emissor é `https://cloud.example.com/oauth-admin`. | | Registro | O aplicativo se registra (`POST /oauth-admin/register`, RFC 7591). Apenas clientes públicos são suportados (sem segredo de cliente). O endereço de redirecionamento deve ser `https`, ou `http` no mesmo computador (loopback). | | Autorização | `GET /oauth-admin/authorize` com o método PKCE `S256`. Um parâmetro `resource`, quando enviado, deve ser a URL `/mcp/admin` deste painel. A solicitação é válida por 10 minutos e está vinculada ao navegador que a iniciou. | | Consentimento | Você escolhe os escopos e a duração (acima). O código de autorização é válido por 60 segundos e funciona uma vez. | | Tokens | `POST /oauth-admin/token` retorna um **access token** (um `ak_o...` chave, válido por 1 hora ou até o término da conexão, o que ocorrer primeiro) e um **refresh token** (`akr_...`). Cada atualização retorna um novo refresh token; o antigo deixa de funcionar. A conexão termina após os dias escolhidos. | | Revogação | **Revoke** em Aplicativos conectados, ou o aplicativo chama `POST /oauth-admin/revoke` (RFC 7009). | O access token se comporta como uma chave de administrador com os escopos que você concedeu: mesmas regras de escopo, confirmação, limite de taxa e log de atividades. Suas chamadas aparecem na aba **Activity**. ## Verificar {#verify} 1. No aplicativo, pergunte "run system_health" (ou "what tools do you have?"). O aplicativo lista as ferramentas que seus escopos permitem ([a lista de ferramentas](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/#tools)). 2. Abra **Connected apps**: **Last used** é atualizado. 3. Abra **Activity**: as chamadas são listadas com o nome do aplicativo e `mcp`. ## Limites e notas {#limits-notes} - Se o aplicativo pedir novamente para fazer login após uma hora, isso é normal quando um cliente não atualiza; reconecte. - Um refresh token usado duas vezes é tratado como roubado: toda a conexão é revogada. Reconecte a partir do aplicativo. - Um código de autorização usado duas vezes é rejeitado (`invalid_grant`) e os tokens já emitidos a partir dele são revogados. - O acesso OAuth nunca concede mais do que as regras de escopo permitem: [o que uma chave nunca pode fazer](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) também se aplica aos aplicativos conectados. - Os fornecedores alteram seus menus e o que suportam. Se o aplicativo de um fornecedor não oferecer conectores personalizados no seu plano, use uma [admin API key](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/) com um cliente de desktop ou de linha de comando em vez disso. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | A tela de consentimento diz "Wrong browser" | A solicitação foi iniciada em um navegador diferente daquele em que você está conectado | Inicie a conexão novamente a partir do aplicativo de IA no mesmo navegador. | | A tela de consentimento diz que a solicitação expirou ou está ausente | Mais de 10 minutos se passaram ou o link foi aberto duas vezes | Inicie a conexão novamente a partir do aplicativo de IA. | | Página "Unknown client" ou "redirect address does not match" | O registro do aplicativo está desatualizado ou ele usa um endereço de redirecionamento que não registrou | Remova o conector no aplicativo e adicione-o novamente. | | `invalid_target` | O `resource` enviado não é a URL `/mcp/admin` deste painel | Use a URL exata exibida na aba **Connect an AI**. | | `invalid_request` sobre PKCE | O cliente não envia `code_challenge_method=S256` | Use um cliente que suporte OAuth 2.1 com PKCE. | | O aplicativo se conecta, mas uma chamada retorna `insufficient_scope` | Você não marcou esse escopo | Revogue a conexão e conecte-se novamente com o escopo marcado. | | O aplicativo não consegue alcançar a URL | DNS, TLS ou o proxy reverso bloqueiam `/mcp/admin`, `/oauth-admin/` ou `/.well-known/` | Verifique as regras do proxy. | --- # 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. | --- # Exemplos de prompts {#example-prompts} > **Onde encontrar no painel:** AI Chat (`/agent`) ou o botão flutuante **Ask AI** em qualquer página administrativa. Os mesmos prompts funcionam em qualquer cliente de IA conectado via [MCP](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/). ## O que faz {#what-it-does} Estes prompts mostram como perguntar. Cada um lista o que o assistente faz nos bastidores, os escopos necessários (para um cliente externo ou uma chave) e onde sua aprovação é solicitada. Substitua os valores de exemplo pelos seus. ::: tip Nunca digite um segredo no texto do chat Para senhas, chaves de API e tokens, use o campo **Secret** ao lado da entrada do AI Chat ([details](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/#secrets)). A IA vê apenas um espaço reservado que representa o segredo, e não o valor. Com um cliente de IA externo, o segredo passa por esse cliente, portanto, prefira inseri-lo no painel administrativo. ::: ## Verifique onde você está {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` O assistente chama `setup_checklist` e `system_health` (escopo `admin:read`) e responde com base no estado real. Consulte [Setup progress checklist](https://nexcmp.com/pt/docs/configure-with-ai/setup-checklist/). ## Primeira configuração {#first-setup} ```text Help me finish the initial setup. Go through the checklist, explain each open step in one sentence, ask me for what you need, and show me every change before it is applied. ``` Isso é o mesmo que o prompt do MCP `initial-setup`. Requer `admin:read` mais os escopos das etapas aceitas. Espere um cartão de confirmação para cada alteração no AI Chat. ## Adicionar um cluster Proxmox VE {#add-a-proxmox-ve-cluster} ```text I want to sell servers from my Proxmox VE cluster at https://pve.example.com:8006. Add it, test the connection, create a zone called "New York" in the US, attach the cluster to it, and then propose starter plans. ``` O que acontece: 1. O assistente solicita o ID do token de API (`user@realm!tokenid`) e seu segredo. Coloque o segredo no campo **Secret**. Crie um token limitado primeiro: [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). 2. Ele chama `proxmox_add`, `proxmox_test`, `zone_create` e `proxmox_attach_zone`. 3. Ele propõe planos com `plans_from_offerings` e aguarda sua aprovação (consulte o próximo exemplo). Escopos: `infra:write`, `secrets:write`, `catalog:write`, `admin:read`. ## Criar uma tabela de planos com margem de 40% {#create-a-plan-table-with-a-40-margin} ```text Suggest a starter plan table from my CloudStack offerings. My costs are $4 per vCPU per month, $2 per GB of RAM per month and $0.08 per GB of disk per month. Use a 40% margin, show me the table with cost, price per month and price per hour, and create the plans only after I approve. ``` O assistente chama `plans_from_offerings` com `margin_pct` 40 e seus custos. Margem é a parcela do preço de venda que corresponde ao lucro: a 40%, um plano que custa $60 para você é vendido por $100. A primeira chamada retorna apenas uma prévia. Quando você aprova, ela chama a ferramenta novamente com `apply=true`, o que cria os planos em uma única etapa e solicita uma confirmação, pois há preços envolvidos. Para o Proxmox, ela usa `backend_id` e uma lista de tamanhos padrão (1, 2, 2 e 4 vCPUs). Escopos: `catalog:write`, `admin:read`. Consulte [Plans](https://nexcmp.com/pt/docs/catalog/plans/). ![Resposta do AI Chat mostrando uma tabela de prévia dos planos com custo, preço mensal e preço por hora](https://nexcmp.com/pt/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## Configurar e-mail e enviar uma mensagem de teste {#configure-email-and-send-a-test-message} ```text Configure outgoing email with smtp.example.com, port 587, STARTTLS, user "mailer@example.com", sender name "Example Cloud", sender address "no-reply@example.com". Use my Secret field for the password "smtp_password". Then send a test email to admin@example.com. ``` O assistente chama `smtp_get`, `smtp_configure` e `smtp_test` e informa se a mensagem foi aceita. Escopos: `settings:write`, `secrets:write`. Consulte [SMTP and e-mail templates](https://nexcmp.com/pt/docs/administration/smtp-and-emails/). ## Configurar o Stripe {#set-up-stripe} ```text Set up Stripe in test mode. My publishable key is pk_test_XXXX. Use the secret key and the webhook secret from my Secret field (names stripe_secret_key and stripe_webhook_secret). Then test the credentials and tell me which webhook URL I must add in Stripe. ``` `payment_configure` é sempre uma ação em duas etapas: você visualiza uma prévia com os valores secretos mascarados e a aprova. Em seguida, `payment_test` verifica as credenciais com o Stripe. Escopos: `billing:write`, `secrets:write`. Alterne para o modo de produção apenas após um pagamento de teste. Consulte [Stripe](https://nexcmp.com/pt/docs/billing/stripe/). ## Ativar alertas do Telegram {#turn-on-telegram-alerts} ```text Add my Telegram chat 123456789 for admin alerts. The bot token is in my Secret field as telegram_bot_token. Send a test message. ``` O assistente chama `telegram_configure` e `telegram_test`. Escopos: `settings:write`, `secrets:write`. Consulte [Telegram notifications](https://nexcmp.com/pt/docs/administration/telegram-notifications/). ## Encontrar um cliente e adicionar crédito {#find-a-customer-and-add-credit} ```text Find the customer with e-mail customer@example.com, show me their balance and servers, and add $10.00 of credit because of the outage on Monday. ``` O assistente chama `customers_search` e `customer_get` (somente leitura), e depois `customer_adjust_balance` com `delta_cents` 1000 e um motivo. Isso **sempre** requer sua aprovação: o cartão de confirmação diz "changes a customer balance" e mostra o valor e o motivo que serão registrados no log de auditoria. Escopos: `admin:read`, `billing:write`. ## Exportar minha configuração {#export-my-configuration} ```text Export my whole configuration as YAML. Do not include secrets. Then tell me which settings differ from a typical new installation. ``` O assistente chama `config_export`. Os segredos são substituídos por referências `secret://`. Salve o resultado como `nexcmp.yaml` e mantenha-o no controle de versão. Consulte [Configuration as code](https://nexcmp.com/pt/docs/configure-with-ai/config-as-code/). Escopo: `admin:read`. ## Escrever bons prompts {#write-good-prompts} - Forneça o objetivo e os fatos: nomes, preços, endereços de e-mail. Não cole segredos. - Peça uma prévia primeiro para qualquer coisa que custe dinheiro ou exclua dados. - Peça ao assistente para "ler o valor atual antes de alterá-lo". As instruções integradas já dizem isso. - Se uma resposta parecer incorreta, pergunte "qual ferramenta você chamou e com quais argumentos?". Os cartões de ferramenta no AI Chat mostram ambos. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O assistente diz que não tem ferramenta para algo | O escopo para essa ferramenta não foi concedido ou a ação está fechada para a IA | Verifique [Admin API keys](https://nexcmp.com/pt/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) ou faça isso no painel admin. | | Ele pede para você colar uma senha | O modelo ignorou as instruções | Recuse; use o campo Secret ou insira o valor no painel admin. | | Nada muda após "fazer isso" | As alterações estão aguardando sua confirmação | Role até o cartão de confirmação e pressione **Confirm**. | | Planos foram criados a um preço que você não esperava | Os custos ou a margem no prompt estavam incorretos | Edite os planos na página Plans ou peça ao assistente para precificá-los novamente; alterações de preço exigem confirmação. | --- # Checklist de progresso de configuração {#setup-progress-checklist} > **Onde no admin:** Overview › Dashboard (`/`), o cartão **Setup progress** no topo. Listas vazias em Plans, Customers, Zones, Payments e Infrastructure mostram a mesma ajuda. ## O que faz {#what-it-does} Uma nova instalação precisa de dez itens antes que o primeiro cliente possa fazer um pedido e pagar. O cartão **Setup progress** verifica esses itens para você a partir da configuração real, mostra quantos estão concluídos, nomeia o **próximo passo** e fornece links para a página onde você o realiza. Se você tiver uma fonte de IA conectada, **Do it for me** abre o [AI assistant](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/) com uma pergunta pronta para essa etapa. O assistente (e qualquer cliente de IA via [MCP](https://nexcmp.com/pt/docs/configure-with-ai/mcp-admin/)) pode ler a mesma lista com a ferramenta `setup_checklist`. ## As dez etapas {#the-ten-steps} | # | Etapa | Conta como concluído quando | Onde você faz isso | |---|---|---|---| | 1 | Licença ativa | A licença é ativada para o seu domínio | System › Admin › License & updates (`/license`). Veja [License and purchase](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/). | | 2 | Conectar uma fonte de infraestrutura | O CloudStack está conectado ou pelo menos um cluster Proxmox VE foi adicionado | Infrastructure › Cloud provider › Providers (`/infra/providers`). Veja [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) e [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). | | 3 | Criar uma zona | Pelo menos uma zona existe | Infrastructure › Datacenter › Zone (`/infra/zones`). Veja [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). | | 4 | Modelos de SO | Pelo menos um modelo está habilitado | Services › Virtual Machines › Plans & pricing, aba Templates (`/vm/catalog?tab=templates`). Veja [OS templates](https://nexcmp.com/pt/docs/infrastructure/templates/). | | 5 | Criar planos | Pelo menos um plano está habilitado | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). Veja [Plans and pricing](https://nexcmp.com/pt/docs/catalog/plans/). | | 6 | Configurar pagamentos | Stripe, PayPal, criptomoeda ou transferência bancária está configurado | Finance › Payment channels (`/payments`). Veja [Payment channels](https://nexcmp.com/pt/docs/billing/payment-channels/). | | 7 | Email (SMTP) | O e-mail de saída está configurado | System › Settings › Email (`/settings/email`). Veja [SMTP and e-mail templates](https://nexcmp.com/pt/docs/administration/smtp-and-emails/). | | 8 | Branding | Um logotipo foi enviado ou o nome da marca foi alterado em relação ao padrão | System › Settings › Brand (`/settings/branding`). Veja [Branding](https://nexcmp.com/pt/docs/customers/branding/). | | 9 | Termos e privacidade | Pelo menos um texto legal está preenchido | System › Settings › Legal (`/settings/legal`). Veja [Legal pages](https://nexcmp.com/pt/docs/customers/legal/). | | 10 | Fazer um pedido de teste | Existe pelo menos um pedido | Faça um pedido como cliente no portal do cliente para verificar se tudo funciona de ponta a ponta; o cartão leva à página Billing (`/billing`). | O cartão exibe `done/total` (por exemplo, 6/10), uma barra de progresso, a próxima etapa com **Open** e, quando uma fonte de IA está conectada, **Do it for me**. Clique em uma etapa para ir para a página dela. Ao lado de uma etapa, um pequeno link abre a página de documentação correspondente; algumas etapas também exibem um detalhe como "2 zone(s)". ![Cartão de progresso de configuração na Visão Geral com três de dez etapas concluídas e os botões Open e Do it for me](https://nexcmp.com/pt/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## Como usar {#use-it} 1. Abra a Visão Geral. O cartão fica na parte superior. Use a seta para recolhê-lo; o painel lembra sua escolha no navegador. 2. Clique em **Open** para ir para a página da próxima etapa ou clique em **Do it for me**. 3. Com **Do it for me**, o assistente abre com uma solicitação como "Sugerir uma tabela de planos iniciais a partir das minhas ofertas com margem de 40%, mostrar a prévia antes de criar." Responda às perguntas dele, revise e **Confirm** cada cartão. Veja [AI Chat in the admin](https://nexcmp.com/pt/docs/configure-with-ai/ai-chat-in-admin/). 4. Quando todas as dez etapas forem concluídas, o cartão desaparece. ### Listas vazias {#empty-lists} Quando Plans, Customers, Zones, Payments ou Infrastructure estiver vazio, a página exibe um bloco **Next step** com uma explicação, um botão para a ação, **Do it for me** e um link para a documentação, para que você nunca se depare com uma tabela em branco. ![Página Plans vazia com uma explicação da próxima etapa e o botão Do it for me](https://nexcmp.com/pt/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## Pedir com suas próprias palavras {#ask-for-it-in-your-own-words} Você não precisa do cartão. No AI Chat ou em qualquer cliente de IA conectado, você pode perguntar: ```text Check my setup progress and take me through the open steps, one at a time. ``` Este também é o prompt do MCP `initial-setup`. O assistente chama `setup_checklist`, explica por que cada etapa aberta é importante, solicita as informações necessárias e usa a ferramenta correspondente. Escopos necessários: `admin:read` para ler a lista, além do escopo da etapa que você deseja concluir. Veja [Example prompts](https://nexcmp.com/pt/docs/configure-with-ai/example-prompts/). ## Verificar {#verify} 1. Após concluir uma etapa, a contagem do cartão aumenta na próxima vez que a Visão Geral for carregada. 2. No assistente, `setup_checklist` retorna os mesmos números, com `done: true` na etapa concluída. ## Limites e notas {#limits-notes} - As verificações avaliam o que está salvo, e não se está funcionando. Um gateway configurado conta como concluído mesmo se o teste falhar. Use os botões **Test** em cada página e a ferramenta `system_health` para resolver problemas. - O cartão é apenas para administradores. - **Do it for me** precisa de uma fonte de IA conectada em System › Settings › AI accounts; sem ela, apenas **Open** é exibido. - As dez etapas são as mesmas para todas as instalações; uma etapa que você não planeja usar (por exemplo, pagamentos em uma nuvem privada) ainda conta como aberta. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O cartão está ausente | Todas as dez etapas foram concluídas ou o cartão não pôde ser carregado | Recarregue a Visão Geral. Pergunte `setup_checklist` no AI Chat para ver o estado. | | Uma etapa permanece aberta após você tê-la concluído | O salvamento não foi concluído ou a condição ainda não foi atendida (por exemplo, um modelo existe mas está desativado) | Abra a página da etapa e verifique a tabela acima. | | A identidade visual permanece aberta após a alteração do logotipo | A identidade visual é contada quando existe um logotipo ou o nome da marca é diferente do padrão "NexCMP" | Envie um logotipo ou defina seu próprio nome. | | **Do it for me** não faz nada | Nenhuma fonte de IA conectada ou painel de demonstração | Conecte uma fonte em contas de IA. | --- # SMTP e modelos de e-mail {#smtp-and-e-mail-templates} > **Onde no admin:** System › Settings › Email (`/settings/email`) — abas **SMTP** e **Email templates**. Log de entrega: Overview › Support › Sent emails (`/support/emails`). ## O que faz {#what-it-does} O NexCMP envia e-mails para verificação de cadastro, redefinição de senha, "VM ready" (com a senha inicial), faturas, saldo baixo, renovações, recargas, respostas de suporte e muito mais. Todos passam por **uma conta SMTP fornecida por você**. As mensagens e modelos existem em 16 idiomas; o idioma do cliente é utilizado. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Servidor SMTP | Host, porta e credenciais de qualquer provedor (seu próprio servidor, Brevo, Amazon SES, Mailgun, Google Workspace …) | | Rede | TCP de saída do servidor NexCMP para o host e a porta SMTP (587 STARTTLS, 465 TLS ou 25) | | Dominio do remetente | Um domínio controlado por você, com **SPF e DKIM** publicados para o provedor e um registro DMARC | | Permissão | A conta SMTP deve ter permissão para enviar como o endereço **From** | ::: warning Entregabilidade E-mails como "VM ready" contêm senhas. Se o SPF/DKIM/DMARC do domínio do remetente não corresponder ao provedor SMTP, eles cairão no spam. A página lembra você disso. ::: ## Preparar o provedor de e-mail {#prepare-the-e-mail-provider} 1. No painel do seu provedor, adicione e verifique seu domínio de envio (por exemplo, `example.com`). 2. Publique os registros DNS SPF, DKIM e DMARC exibidos pelo provedor. 3. Crie um usuário SMTP (ou chave API-SMTP) e anote o host, a porta, o nome de usuário e a senha. ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › Email**, aba **SMTP**. 2. Preencha o formulário: | Campo | Exemplo | Notas | |---|---|---| | Host | `smtp.example.net` | Servidor SMTP | | Porta | `587` | | | Segurança | STARTTLS (587) | Escolha o modo exigido pelo seu provedor | | Nome de usuário | `smtp-user` | | | Senha | (oculto) | Somente gravação: a página mostra apenas se um foi definido | | E-mail de remetente | `no-reply@example.com` | Deve ser autorizado no provedor | | Nome de remetente | `Example Cloud` | Usa o nome da sua marca por padrão | | Responder para (opcional) | `support@example.com` | Para onde vão as respostas dos clientes | ![A aba SMTP de Settings, Email com host, porta, segurança, nome de usuário, campos de remetente e o botão Send test](https://nexcmp.com/pt/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. Clique em **Save**, depois em **Send test** e insira seu próprio endereço. As configurações são armazenadas em um arquivo com acesso restrito (`smtp.json`, permissão 0600) e apenas o worker em segundo plano `nexcmp-vmd` envia e-mails; o serviço web apenas os enfileira. ## Verificar {#verify} - A mensagem de teste chega à caixa de entrada (verifique também o spam). Na origem da mensagem, confirme `dkim=pass` e `spf=pass`. - Abra **Support › Sent emails**: cada mensagem tem um status (enfileirada, enviada, com falha) e o resultado da entrega. Mensagens com falha são reenviadas até 3 vezes. - Cadastre um cliente de teste no portal e confirme se o e-mail de verificação chega. ## Editar modelos de e-mail {#edit-e-mail-templates} A aba **Email templates** lista cada modelo por chave, com os idiomas em que ele existe (por exemplo, `verify_email`, `reset_password`, `vm_ready`, `invoice_paid`, `low_balance`, `topup_received`, `ticket_reply`, `scale_up` …). 1. Clique em um modelo e escolha um idioma. 2. Edite o assunto e o corpo. Os espaços reservados são preenchidos quando uma mensagem é enfileirada. 3. Salve. A alteração é aplicada **imediatamente** às mensagens enfileiradas posteriormente. ![A aba Email templates listando as chaves dos modelos e seus idiomas](https://nexcmp.com/pt/docs/images/administration/smtp-and-emails-02-templates.webp) ## Limites e observações {#limits-and-notes} - Uma conta SMTP por instalação. Os clientes dos revendedores recebem e-mail pela mesma conta, a menos que o revendedor esteja configurado de outra forma. - Aplicam-se os limites de envio do provedor; o NexCMP não faz limitador de taxa além de tentar novamente. - Sem SMTP o painel funciona, mas a verificação de cadastro e a redefinição de senha não podem ser concluídas pelos clientes. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | O e-mail de teste nunca chega | Credenciais incorretas, porta bloqueada, remetente não autorizado | Verifique `journalctl -u nexcmp-vmd` para ver o erro SMTP; tente a porta 587 com STARTTLS; verifique o endereço From no provedor. | | As mensagens vão para o spam | SPF/DKIM/DMARC ausentes ou desalinhados | Publique os registros do provedor e envie a partir desse domínio. | | "failed" em Sent emails | O provedor rejeitou a mensagem | Abra a linha para ver a resposta do provedor. | | O campo de senha parece vazio após salvar | Por design (somente gravação) | O rótulo exibe "current: set" assim que uma senha é armazenada. | --- # Telegram e alertas de administrador {#telegram-and-admin-alerts} > **Onde no admin:** System › Settings › Admin alerts (`/settings/alerts`). Atalhos de suporte: Customers › Support › Tickets (`/support/tickets`), aba **Settings**. ## O que faz {#what-it-does} O NexCMP avisa **você** — o operador — quando algo precisa de atenção e quando um cliente se cadastra ou um depósito é creditado. Os alertas vão para um ou mais **canais**: Telegram, webhook ou e-mail. Os eventos enviados para os canais de administrador incluem: falha de implantação, VM ausente, rede caída, IPs livres abaixo de 30, item prestes a expirar (aviso de 1 hora), disputa no Stripe, worker inativo, RAM do cluster acima do limite, novo cadastro de cliente e depósitos creditados. Os eventos de clientes são enfileirados de forma durável e tentados novamente com atraso crescente (de 30 segundos a 1 hora) até que o Telegram os aceita. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Telegram | Um bot criado com **@BotFather** (token) e o **chat ID** do grupo ou usuário que deve receber as mensagens | | Rede | HTTPS de saída para `api.telegram.org` | | Webhook (alternativo) | Um endpoint HTTPS que aceita o payload do alerta | ## Preparar o Telegram {#prepare-telegram} 1. No Telegram, abra **@BotFather**, envie `/newbot`, escolha um nome e copie o **bot token** (`123456789:AA...`). 2. Crie um grupo, adicione o bot a ele e envie qualquer mensagem. 3. Encontre o **chat ID**: abra `https://api.telegram.org/bot/getUpdates` em um navegador e leia `chat.id` (os IDs de grupo começam com `-`). ## Conectar no NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › Admin alerts**. 2. Em **Add channel**, escolha **Type: Telegram**, defina **Destination** como o chat ID e **Secret (bot token)** como o token. Clique em **Add**. 3. Certifique-se de que a opção **Send admin Telegram (VM module)** esteja ativada; a linha *VM module status (read-only)* mostra "on". ![A página de alertas de administração com o formulário Add channel configurado para Telegram](https://nexcmp.com/pt/docs/images/administration/telegram-notifications-01-channel.webp) ## Verificar {#verify} O canal aparece em **Configured channels**. Dispare um evento (por exemplo, registre um cliente de teste) e a mensagem chegará ao grupo. Se nenhum canal estiver configurado, a página avisará "Without a channel, attacks will go unnoticed" e, no log, os eventos do Telegram serão registrados apenas localmente. ## Atalhos de suporte para clientes {#support-shortcuts-for-customers} O widget de suporte ao cliente pode exibir botões do **Telegram** e **Zalo**. Eles ficam ocultos até serem configurados nas configurações de suporte: insira um link `https://t.me/...` para o Telegram e o link ou QR do Zalo. Apenas links `https://` são aceitos. O chat de suporte também pode notificar seu grupo do Telegram com a pergunta e uma resposta preliminar — consulte [AI Chat](https://nexcmp.com/pt/docs/ai/ai-chat/). ## Limites e observações {#limits-and-notes} - O token do bot é armazenado com o canal e nunca mais é exibido. - Os eventos do Telegram usam o primeiro canal do Telegram ativado que possui um destino e um token. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | Nenhuma mensagem chega | Chat ID incorreto, bot não está no grupo ou o bot nunca recebeu mensagens | Verifique novamente o ID com `getUpdates`; envie uma mensagem para o bot ou grupo primeiro. | | Funciona por um tempo e depois para | Token revogado no BotFather | Crie um novo token e atualize o canal. | | `Telegram: no channel` nos logs | Nenhum canal do Telegram ativado | Adicione um conforme descrito acima. | --- # Log de auditoria e atividade {#audit-log-and-activity} > **Onde encontrar no painel admin:** System › Logs › Activity (`/logs`), Admin actions (`/logs/admin`), Console (`/logs/console`), Login (`/logs/logins`), VM events (`/logs/vm-events`); Overview › Support › Sent emails. O NexCMP registra cada ação significativa. Use a página **Activity** como a linha do tempo única e as outras guias para filtrar. ## Guias {#tabs} | Aba | Conteúdo | |---|---| | **Activity** | Linha do tempo unificada em todas as fontes: ações de admin, eventos de VM, logins, afiliados e erros do sistema | | **Admin actions** | O que os administradores alteraram (por exemplo, `customer.block`, `customer.delete`), junto com o IP do administrador | | **Console** | Inícios de sessão no console de administração e requisições do sistema, como uma solicitação de atualização | | **Login** | Entradas e falhas de login de clientes | | **VM events** | Etapas de implantação, criação, senha, exclusão e outros eventos do ciclo de vida por máquina virtual | ## Lendo uma linha {#reading-a-row} Colunas: **Time**, **Source**, **Level**, **Actor** (quem), **Target**, **Services**, **Action** (código do evento como `customer.delete`) e **Details**. Clique em **Open** para ver o registro completo. ![A página de Atividade com filtros de origem, site e serviço acima da linha do tempo](https://nexcmp.com/pt/docs/images/administration/audit-log-01-activity.webp) ## Filtrar e pesquisar {#filter-and-search} 1. Selecione uma **source**, **site** e **service** nos menus suspensos. 2. Defina um intervalo de **From date** / **To date**. 3. Digite um código de evento (por exemplo, `customer.block` ou `destroy`) na caixa de pesquisa — a pesquisa de atividade corresponde ao código do evento. ## Retenção e exportações {#retention-and-exports} Os registros ficam nos bancos de dados do NexCMP em `/var/lib/nexcmp` e são incluídos em [backups](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/). A retenção depende do log: tentativas de login de clientes com mais de 180 dias e logs de requisições de chaves de API de clientes com mais de 60 dias são removidos. A auditoria de chaves de API de admin mantém até cerca de 200,000 registros recentes. Esses limites não implicam a mesma retenção para a linha do tempo de atividade unificada. ## Usos comuns {#common-uses} | Pergunta | Onde procurar | |---|---| | Quem suspendeu este cliente? | Ações de admin, pesquise por `customer.block` | | Por que uma VM desapareceu? | Eventos de VM, filtre pelo ID da VM; também em Atividade | | O cliente recebeu o e-mail? | Overview › Support › Sent emails | | Quando a última atualização foi solicitada? | Guia Console | --- # Segurança {#security} > **Onde encontrar no admin:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`). ## Console administrativo {#admin-console} ### Autenticação de dois fatores (TOTP) {#two-factor-authentication-totp} O console é acessível a partir da Internet, portanto, ative o TOTP. 1. Abra **System › Admin › Console security**. 2. Em **Two-factor authentication (TOTP)**, clique em **Start setup**. 3. Escaneie o código QR com o Google Authenticator, Authy, 1Password ou Bitwarden e insira o código de 6 dígitos. ### Intervalos de IP permitidos para o console {#allowed-console-ip-ranges} Em **Allowed console IP ranges**, insira um IP ou CIDR (IPv4 ou IPv6) por linha. **Campo vazio significa qualquer lugar.** Fora desse intervalo, tanto o login quanto a API de admin serão bloqueados. ::: warning Não fique sem acesso A página exibe seu IP atual e exige que a nova lista o inclua. Use **+ Add my IP**. Se você perder o acesso mesmo assim, utilize o [emergency access](https://nexcmp.com/pt/docs/getting-started/cli-reference/#emergency-access) a partir do servidor. ::: ### Alterar senha {#change-password} Preencha **Current password**, **New password** e **Confirm new password**. Use uma senha longa e exclusiva (12 caracteres ou mais; o assistente de instalação exige 12 para o primeiro administrador). ### Contas e funções de administradores {#administrator-accounts-and-roles} Abra **System › Admin › Admin users** e use **+ Create account**. | Função | Acesso | |---|---| | `admin` | Acesso total à API de admin | | `staff` | Apenas leitura em todo o sistema | | `user` | Visualização somente leitura dos recursos de um cliente | A conta root é a criada no [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/). Ações de linha: **Edit**, **Reset PW**, **Key**, **Delete**. As senhas são armazenadas como hashes com salt; alterar ou bloquear uma conta encerra suas sessões imediatamente. ## Login de clientes {#customer-sign-in} Abra **System › Settings › Customer logins**. | Configuração | O que faz | |---|---| | **Google sign-in** | Ative e insira o ID de cliente OAuth e o segredo. Copie a **Callback URL** exibida na página para *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. Use **Test configuration**. | | **GitHub login** | O mesmo, com *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **Passkey** | Login por impressão digital, PIN ou chave de hardware; ativado por padrão. As passkeys são vinculadas ao domínio; cada domínio de revendedor funciona de forma independente. Insira um domínio antigo em *Legacy passkey Domain* após um rebranding para que os clientes recebam uma dica útil | | **Reautenticar ao adicionar métodos de login** | Solicitar a senha novamente antes de adicionar uma passkey ou vincular o Google/GitHub (desativado por padrão) | | **Captcha** | Cloudflare Turnstile ou Google reCAPTCHA no cadastro: ative, escolha o provedor, insira a chave do site e a chave secreta | | **Block e-mail domains** | Um domínio por linha (máx. 2000). Endereços correspondentes são rejeitados no cadastro com `email_domain_blocked` | ![A página de login do cliente mostrando o login do Google com sua URL de callback](https://nexcmp.com/pt/docs/images/administration/security-01-customer-logins.webp) ### Built-in policies {#built-in-policies} | Política | Valor | |---|---| | Customer password | Pelo menos 10 caracteres, letras e dígitos | | Customer session | 30 dias; sessões de "fazer login como cliente" duram 1 hora | | E-mail verification | Obrigatório antes de criar uma VM quando *require e-mail verified* estiver ativado nas configurações de vendas | | Anti-carding | Contas com saldo inferior à recarga mínima só podem criar um número limitado de VMs | ## Server hardening {#server-hardening} - A porta 3000 é fechada após a configuração e o TLS; consulte [Installation](https://nexcmp.com/pt/docs/getting-started/installation/#the-panel-port-3000). - O serviço é executado como o usuário não privilegiado `nexcmp` com uma sandbox do systemd restrita. - Chaves de API, credenciais de pagamento e senhas SMTP são armazenadas de forma criptografada; a chave mestre está em `/var/lib/nexcmp/secrets` — proteja [backups](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/). - As versões são verificadas com SHA-256 e uma assinatura Ed25519 antes da instalação. --- # Configurações gerais {#general-settings} > **Where in the admin:** System › Settings › General (`/settings`). As alterações entram em vigor imediatamente (cache de 30 segundos). A página tem três seções. ## Branding & URLs {#branding-urls} | Campo | Finalidade | |---|---| | Nome da marca (e-mail, faturas) | Exibido em e-mails e faturas. O logotipo e as cores estão em [Branding](https://nexcmp.com/pt/docs/customers/branding/) | | Default language | Idioma para novos visitantes | | Customer app URL | Endereço público do portal, por exemplo `https://cloud.example.com` | | Console URL | Endereço do serviço de console da VM | | Admin URL | Link usado quando você faz "log in as" no cliente de um revendedor | | Partner console URL | Usado em links de convite, e-mails de revendedores e no redirecionamento após uma recarga | O assistente preenche estes campos com base no seu domínio; altere-os apenas se mover o portal. ## Vendedor e faturamento {#seller-invoicing} Impresso em todas as faturas: | Campo | Exemplo | |---|---| | Nome da entidade jurídica | Example Cloud Ltd | | CNPJ/ID fiscal | `TAX-000000` | | Endereço | 1 Example Street, New York | | E-mail de contato | `billing@example.com` | | Prefixo do número da fatura | `INV` (1–8 caracteres, A–Z e 0–9) | As faturas existentes mantêm os detalhes do vendedor e o número com que foram emitidas; as alterações afetam apenas **novas** faturas. ## Manutenção e região {#maintenance-region} Ative **Customer app MAINTENANCE** para exibir um banner e **bloquear todas as ações de gravação dos clientes** enquanto o console de administração continua funcionando. Insira a **Maintenance message** que os clientes verão. Use isso durante atualizações da sua infraestrutura. ![A página de configurações gerais com nome da marca, idioma padrão e campos de URL](https://nexcmp.com/pt/docs/images/administration/general-settings-01-general.webp) ## Outras páginas de configurações {#other-settings-pages} | Página | Guia | |---|---| | Brand | [Branding](https://nexcmp.com/pt/docs/customers/branding/) | | Legal | [Legal](https://nexcmp.com/pt/docs/customers/legal/) | | Customer logins | [Security](https://nexcmp.com/pt/docs/administration/security/) | | Email | [SMTP e modelos de e-mail](https://nexcmp.com/pt/docs/administration/smtp-and-emails/) | | Admin alerts | [Telegram e alertas de administrador](https://nexcmp.com/pt/docs/administration/telegram-notifications/) | | Provedor de IA | [AI providers](https://nexcmp.com/pt/docs/ai/ai-providers/) | --- # Reportar um bug {#report-a-bug} > **Onde no admin:** Top bar › **Report a bug** (ao lado de Docs; exibido apenas para o administrador principal). Encontrou uma falha no NexCMP? Clique em **Report a bug**, descreva o problema e envie. O relatório chega à equipe NexCMP como um ticket na conta da sua licença em uma única etapa — sem precisar fazer login em outro lugar nem copiar arquivos de log manualmente. Todos os planos podem usar: o NexCMP Free inclui correções de bugs, assim como o NexCMP Source. ::: info Relatórios de bug não são solicitações de suporte O NexCMP Free não inclui suporte técnico; portanto, use este formulário para falhas no software. Ajuda com configuração e migrações fazem parte do [NexCMP Source](https://nexcmp.com/pricing). ::: ## Requisitos {#requirements} | Item | Requisitos | |---|---| | Versão | NexCMP 1.5.2 ou superior | | Quem pode enviar | A conta de administrador principal. Contas de equipe (somente leitura), consoles de revenda, clientes e a demo somente leitura não podem enviar | | Licença | Uma licença ativada (Free ou Source) que não esteja suspensa | | Rede | O servidor precisa alcançar `https://nexcmp.com` via HTTPS (o mesmo endereço usado para verificação de licença e atualizações) | ## Enviar um relatório {#send-a-report} 1. Clique em **Report a bug** na barra superior. No celular, abra o menu e escolha **Report a bug**. 2. Insira um **Subject** curto. 3. Em **What happened**, descreva o que você fez, o que viu e o que esperava. 4. Opcionalmente, liste os **Steps to reproduce**. 5. Escolha o **Impact**: **Blocking** (você não consegue trabalhar), **Major** (um recurso principal está quebrado) ou **Minor** (um problema pequeno ou cosmético). 6. Mantenha **Attach diagnostics** ativado (recomendado) e leia o quadro **What will be sent**. 7. Clique em **Send report**. Na versão 1.6.1, o corpo do formulário rola enquanto os botões de ação permanecem visíveis, inclusive no celular. Valores de senha após `password:` ou `password=` são mascarados sem remover o restante do relatório. Revise seu texto antes de enviar e omita dados de clientes e credenciais. ![A caixa de diálogo Report a bug com título, descrição, impacto e a lista do que será enviado](https://nexcmp.com/pt/docs/images/administration/report-a-bug-01-dialog.webp) Quando o relatório é aceito, a caixa de diálogo exibe o número do ticket e um link. As respostas, caso a equipe envie alguma, vão para o endereço de e-mail da sua conta de licença em nexcmp.com, e o ticket também é listado em **Support** quando você faz login como titular da licença. ## O que é enviado {#what-is-sent} O quadro **What will be sent** mostra exatamente o seguinte antes de clicar em Send: | Enviado | Detalhes | |---|---| | Seu texto | Título, descrição, etapas e impacto | | Versão, plano, domínio | Sua versão do NexCMP, Free ou Source, e o domínio da instalação | | Página atual | A página em que você está no admin, sem nada após `?` ou `#` | | Navegador | O texto de user-agent do seu navegador (nome, versão e sistema operacional), limitado a 200 caracteres | | Erros recentes | Até os últimos 5 erros nesta aba do navegador. Para erros de script, apenas a mensagem; para requisições com falha, apenas o método, o caminho e o código de status | Você pode desativar **Attach diagnostics**; nesse caso, apenas o seu texto, a versão, o plano e o domínio serão enviados. ## O que nunca é enviado {#what-is-never-sent} - Senhas, tokens, cookies e chaves de API. Qualquer item no seu texto ou em uma mensagem de erro que se pareça com um deles é mascarado (exibido como `***` ou `[redacted]`) no seu servidor antes do envio. - O conteúdo de requisições e respostas — requisições com falha são registradas apenas como método, caminho e status. - Dados dos seus clientes (nomes, e-mails, pedidos, faturas) e seus endereços IP. - O endereço IP do seu navegador e qualquer arquivo do seu servidor. Como em toda verificação de licença, o servidor de licenças vê o endereço IP a partir do qual o seu servidor se conecta. O ticket é vinculado à sua instalação pelo token de licença que o servidor já possui, portanto a versão, o domínio e a instalação são definidos pelo servidor e não podem ser alterados pelo navegador. ## Limites {#limits} | Limite | Valor | |---|---| | Assunto | 150 caracteres | | Descrição e etapas | 8 KB somados | | Reports | 5 por hora e 20 por dia para toda a instalação | O envio do mesmo relatório duas vezes (por exemplo, após um erro de rede) não cria um segundo ticket. ## Resolução de problemas {#troubleshooting} | Mensagem | Causa | Correção | |---|---|---| | Ative sua licença primeiro | A instalação não possui uma licença ativada | Abra **License & updates** e ative, depois envie novamente | | Não foi possível acessar o servidor de licenças | O servidor não consegue acessar `nexcmp.com` | Verifique o HTTPS e DNS de saída no servidor e clique em **Send report** novamente — seu texto será mantido | | Muitos relatórios de bug desta instalação | Você atingiu 5 por hora ou 20 por dia | Aguarde e tente novamente; em vez disso, adicione novas informações ao ticket aberto | | Esta licença está suspensa | A licença está suspensa ou foi reembolsada | Consulte [Licença e compra](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/) | | Esta instalação foi revogada | A instalação foi revogada no portal de licenças | Ative-a novamente em **License & updates** | | Não foi possível atualizar o token de licença | O servidor não conseguiu renovar seu token de licença | Abra **License & updates**, clique em **Refresh** e envie novamente | | Nenhum botão Report a bug | Você está conectado com uma conta de equipe, revendedor ou cliente, ou na demo somente leitura | Faça login como o administrador principal | ::: tip Para o assistente de IA e chaves de API O assistente no admin e as chaves de API de admin não podem enviar relatórios de bug em seu nome: o botão requer uma pessoa conectada como o administrador principal. ::: --- # Erros de instalação {#installation-errors} O instalador para no primeiro problema fatal e exibe uma linha vermelha começando com `✗`. Corrija a causa e **execute o mesmo comando novamente** — o instalador pode ser repetido com segurança. Linhas informativas começam com `•`, etapas bem-sucedidas com `✓`. ## Verificações da máquina {#machine-checks} | Mensagem | Causa | Correção | |---|---|---| | `must be run as root (sudo)` | Não executando como root | Prefixe o comando com `sudo` ou execute como root. | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | Outra distribuição ou versão | Use um servidor Ubuntu 22.04 ou 24.04. | | `only x86_64 is supported` | ARM ou outra CPU | Use um servidor x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | Pouca memória | Adicione RAM. | | `requires ≥ 8 GB free disk space on / (… GB available)` | Sistema de arquivos raiz quase cheio | Libere espaço ou aumente `/`. | | `missing --license` / `missing --domain` | Primeira instalação sem esses parâmetros | Passe ambos — veja [Installation](https://nexcmp.com/pt/docs/getting-started/installation/#parameters). | | `unknown argument: …` | Erro de digitação em um parâmetro | Verifique a ortografia; execute com `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | O gerenciador de pacotes está bloqueado | Aguarde alguns minutos (uma instalação limpa do Ubuntu executa atualizações automáticas após a inicialização) e execute novamente. | | `… is a symlink — aborting` | `/opt/nexcmp` ou `/etc/nexcmp` é um link simbólico | Substitua-o por um diretório real — o instalador recusa links simbólicos por motivos de segurança. | ## Ativação de licença {#license-activation} | Mensagem | Causa | Correção | |---|---|---| | `cannot connect to https://nexcmp.com` | Sem HTTPS de saída para o servidor de licenças | Verifique o DNS, o firewall e o proxy no servidor: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | O servidor de licenças rejeitou a chave | Leia a mensagem: chave incorreta, domínio incompatível com a licença, licença suspensa ou revogada. Verifique a página de licenças em [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | A licença não possui uma versão para download | Entre em contato com as vendas; consulte [Support](https://nexcmp.com/pt/docs/troubleshooting/support/). | ## Download e verificação {#download-and-verification} | Mensagem | Causa | Correção | |---|---|---| | `failed to download release X` | Problema de rede durante o download | Execute novamente. | | `sha256 mismatch (… ≠ …)` | O arquivo chegou danificado ou foi alterado | Execute novamente; se o problema persistir, um proxy pode estar reescrevendo os downloads — tente a partir de outra rede. | | `release X is unsigned — refusing to install` | O servidor não forneceu nenhuma assinatura | Nunca ignore; entre em contato com o suporte. | | `INVALID SIGNATURE for version X — aborting` | A assinatura Ed25519 não pôde ser verificada | Não **instale**. Entre em contato com o suporte — isso significa que o arquivo não é uma versão oficial. | | `openssl failed to read public key` | OpenSSL muito antigo ou corrompido | Atualize o pacote `openssl`. | | `invalid version: …` | Dados inesperados do servidor | Execute novamente; entre em contato com o suporte se o problema persistir. | ## Inicialização do serviço {#service-start} | Mensagem | Causa | Correção | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | O painel não respondeu a `/healthz` dentro de 3 minutos | Leia o journal. Causas comuns: a porta (padrão 3000) já está em uso (`ss -ltnp | grep 3000`) — reinstale com `--port`; arquivos pertencentes ao usuário root em `/var/lib/nexcmp` — execute `sudo nexcmp fix-owner`. | ## nginx e TLS {#nginx-and-tls} | Mensagem | Causa | Correção | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | O registro A/AAAA está ausente ou incorreto | Consulte [DNS and Cloudflare](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/) e execute novamente. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | A validação do Let's Encrypt falhou (porta 80 bloqueada, DNS não propagado, limite de taxa) | Abra a porta 80, aguarde a propagação do DNS e execute novamente. Verifique `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | Falha temporária na renovação | Inofensivo; execute novamente mais tarde. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Outro site do nginx entra em conflito (mesmo `server_name`, configurações duplicadas) | Execute `sudo nginx -t` e corrija o conflito, depois execute novamente. | | `apt-get could not install nginx` / `certbot`, ou `E: Failed to fetch … 404 Not Found` | Gerenciador de pacotes bloqueado ou índice de pacotes do servidor desatualizado (comum em imagens de modelo que não são atualizadas há algum tempo) | Execute `sudo apt-get update`, aguarde a conclusão de qualquer outro processo apt e execute o instalador novamente. | | `openssl could not create the self-signed certificate` | Problema no OpenSSL | Atualize `openssl`; execute novamente. | ## Após a instalação {#after-installation} | Sintoma | Causa | Correção | |---|---|---| | O navegador não consegue abrir `https://` | DNS ou TLS não prontos | `sudo nexcmp status`; use o [acesso de emergência](https://nexcmp.com/pt/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | Modo SSL do Cloudflare **Flexible** | Defina **Full (strict)** — [details](https://nexcmp.com/pt/docs/getting-started/dns-and-cloudflare/). | | O assistente diz que o "setup code" está incorreto | Erro de digitação ou um código de uma instalação anterior | Execute `sudo nexcmp status` e copie o código atual. | | A licença exibe HTTP 421 | Arquivos em `/var/lib/nexcmp` pertencem ao root | `sudo nexcmp fix-owner`, depois `sudo systemctl restart nexcmp`. | --- # Erros de atualização {#update-errors} > **Onde no admin:** System › Admin › License & updates (`/license`) As atualizações são descritas em [Updating NexCMP](https://nexcmp.com/pt/docs/getting-started/updating/). Quando o cartão de Atualização ou `sudo nexcmp update` relatar um erro: | Mensagem | Causa | Correção | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | Sua data limite de atualizações ("updates until") é anterior à data de lançamento. Correções de segurança ainda são entregues; lançamentos de recursos não | Renove em [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 por ano para o NexCMP Free) e verifique novamente. O software continua funcionando enquanto isso. | | `sha256 mismatch (downloaded …, expected …)` | Download danificado ou alterado | Tente novamente. Se o problema persistir, verifique os proxies no caminho. | | `downgrade/same version rejected: X is not newer than Y` | A versão selecionada não é mais recente do que a em execução | Nada a fazer — você está atualizado. | | `extraction failed / main binary missing` | Arquivo compactado danificado ou disco cheio | Verifique `df -h`; tente novamente. | | `systemctl restart failed` | O serviço não pôde ser reiniciado após a substituição do binário | `journalctl -u nexcmp -n 80`; o binário anterior é mantido como `/opt/nexcmp/bin/nexcmp.bak` — veja a reversão abaixo. | | Erro do servidor ao entrar em contato com o servidor de atualização | Sem rota para `nexcmp.com` ou token de licença expirado | Verifique o HTTPS de saída; clique em **Check now** no cartão de Licença. | ## Reverter {#roll-back} Se uma nova versão apresentar comportamento inadequado: ```bash sudo systemctl stop nexcmp-vmd nexcmp sudo cp /opt/nexcmp/bin/nexcmp.bak /opt/nexcmp/bin/nexcmp echo | sudo tee /opt/nexcmp/VERSION sudo systemctl start nexcmp nexcmp-vmd ``` Se uma migração de banco de dados já tiver ocorrido, restaure também o seu [backup](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/) feito antes da atualização. ## `sudo nexcmp update` diz que não consegue encontrar o instalador {#sudo-nexcmp-update-says-it-cannot-find-the-installer} `nexcmp update` executa o instalador embutido na versão instalada (`/opt/nexcmp/releases//share/install.sh`). Se esse arquivo estiver ausente, execute o comando de instalação da sua página de licença novamente. --- # FAQ {#faq} ## Licenciamento {#licensing} **O que acontece se minha licença expirar ou o servidor perder o acesso à Internet?** O token permanece válido por 14 dias e é renovado diariamente. Após esse período, os clientes não podem criar **novos** serviços; serviços em execução, faturamento e logins continuam funcionando. Consulte [License and purchase](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/). **Continuo recebendo correções de segurança após o término do meu direito de atualização?** Sim — os lançamentos de segurança são sempre entregues; os lançamentos de recursos exigem um direito ativo. **Posso executar o NexCMP em um segundo servidor ou domínio?** Ative-o com a chave e o domínio registrados na licença — consulte [License and purchase](https://nexcmp.com/pt/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## Instalação {#installation} **O NexCMP precisa do Docker, PostgreSQL ou Redis?** Não. É um único programa com bancos de dados SQLite, executado pelo systemd como um usuário sem privilégios. Consulte [Requirements](https://nexcmp.com/pt/docs/getting-started/requirements/). **Posso instalar sem um domínio público?** Sim, use `--no-nginx` e um túnel SSH — consulte [Installation](https://nexcmp.com/pt/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **Por que a porta 3000 está fechada após a configuração?** Por segurança, o painel escuta em `127.0.0.1` assim que o assistente é concluído e o TLS está ativo. Use `sudo nexcmp open-port` para emergências. ## Infraestrutura {#infrastructure} **Posso usar o CloudStack e o Proxmox VE juntos?** Sim. Uma zona pode ter ambos; cada plano escolhe sua origem. Consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) e [Zones](https://nexcmp.com/pt/docs/infrastructure/zones/). **Preciso da chave API ROOT do CloudStack?** Não — e você não deve usá-la. Crie uma conta dedicada — [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/). **Por que algumas abas ou botões não aparecem em uma máquina virtual?** As páginas exibem apenas o que a origem da VM suporta (por exemplo, o Proxmox VE não tem redirecionamento de portas). Consulte a tabela de recursos em [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). ## Operações {#operations} **Como migro o NexCMP para outro servidor?** Faça backup, instale a mesma versão no novo servidor com a mesma licença, restaure — veja [Backup and restore](https://nexcmp.com/pt/docs/getting-started/backup-and-restore/). **Onde ficam os logs?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp` e o console do administrador em System › Logs. Veja [Audit log](https://nexcmp.com/pt/docs/administration/audit-log/). **Posso ver o portal do cliente antes de instalar?** Sim. As páginas de serviços em [nexcmp.com](https://nexcmp.com/platform/) mostram o portal do cliente aba por aba com dados de exemplo; abra *View demo* para o visualizador em tela cheia. Para ver uma instalação real, fale com a equipe de vendas. --- # Suporte {#support} ## Contato {#contact} Não há formulário de contato. Envie um e-mail para **sales@nexcmp.com** — ele cobre licenciamento, renovações, domínios e dúvidas técnicas. Sua página de licença em [nexcmp.com/licenses](https://nexcmp.com/licenses) também aponta para o mesmo endereço. ## Antes de escrever {#before-you-write} 1. Pesquise nestas docs (pressione `/`) e verifique [Installation errors](https://nexcmp.com/pt/docs/troubleshooting/installation-errors/) e [Update errors](https://nexcmp.com/pt/docs/troubleshooting/update-errors/). 2. Colete os fatos abaixo — eles permitem que o suporte responda em uma única mensagem. ## O que incluir {#what-to-include} | Item | Como obter | |---|---| | Versão do NexCMP | `sudo nexcmp status` ou System › Admin › License & updates | | Domínio principal e os últimos 4 caracteres da chave de licença | License & updates (nunca envie a chave completa) | | O que você fez e o que esperava | Passos exatos | | O texto do erro ou uma captura de tela | Oculte dados confidenciais antes de enviar | | Status do serviço | `sudo nexcmp status` | | Linhas recentes de log | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | Infraestrutura | Versão do CloudStack ou Proxmox VE, uma zona ou várias | ::: warning Nunca envie dados confidenciais Não envie chaves de licença, chaves API, senhas, o código de instalação, credenciais de pagamento ou arquivos de backup. Oculte-os em logs e capturas de tela. ::: ## Relatórios de segurança {#security-reports} Se acreditar que encontrou uma vulnerabilidade, envie um e-mail para o mesmo endereço com "Security" no assunto e evite publicar detalhes publicamente até que seja corrigida.