# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/es/docs/ · generated 2026-11-02. --- # ¿Qué es NexCMP? {#what-is-nexcmp} NexCMP es un software que instala en **su propio servidor** para convertir la infraestructura cloud en un producto que puede vender. Le ofrece: - un **portal de clientes** donde los usuarios se registran, añaden saldo, solicitan máquinas virtuales y otros servicios, abren una consola, crean Snapshots y contactan con soporte; - una **consola de administración** (`/admin`) donde gestiona clientes, planes, precios, pagos, infraestructura y ajustes; - **facturación**: un monedero por cliente, cobro por horas o mensual, facturas, promociones y cuotas de recursos; - **revendedores de marca blanca**: otras marcas que venden su capacidad bajo su propio dominio; - una **API**, una herramienta de línea de comandos (`cmp`) y un servidor MCP para automatización; - **AI Chat** (asistente de soporte) y **AI Agent** (gestión de una VM en lenguaje natural) opcionales. ## A qué se conecta {#what-it-connects-to} NexCMP no aloja máquinas virtuales por sí mismo; controla la plataforma que lo hace. Un *source* (también llamado proveedor) es uno de los siguientes: | Source | Uso habitual | Guía | |---|---|---| | Apache CloudStack | Nube privada o pública con zonas, redes, routers virtuales e IP públicas | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) | | Proxmox VE | Servidores individuales o clústeres que ya gestiona | [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) | Otros módulos requieren su propia infraestructura: [servidores bare-metal](https://nexcmp.com/es/docs/infrastructure/dedicated/), [nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/), [Object Storage S3](https://nexcmp.com/es/docs/infrastructure/s3/), [Kubernetes y Private Cloud](https://nexcmp.com/es/docs/infrastructure/kubernetes-and-private-cloud/). Consulte [Requisitos de infraestructura](https://nexcmp.com/es/docs/infrastructure/requirements/) para ver una tabla que los incluye a todos. ## Cómo está construido {#how-it-is-built} NexCMP es un único programa con dos servicios de systemd en un servidor Ubuntu: - `nexcmp` — el servidor web: portal de clientes, consola de administración, API, asistente de configuración; - `nexcmp-vmd` — el worker en segundo plano: tareas de aprovisionamiento, sincronización con su CloudStack o Proxmox, ciclos de facturación. Los datos residen en `/var/lib/nexcmp` (bases de datos SQLite y archivos), la configuración en `/etc/nexcmp` y el programa en `/opt/nexcmp`. Consulte [Arquitectura](https://nexcmp.com/es/docs/infrastructure/architecture/) para obtener una visión completa. ## Siguientes pasos {#where-to-go-next} 1. Revise los [requisitos](https://nexcmp.com/es/docs/getting-started/requirements/). 2. Obtenga una licencia — [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/). 3. [Instale](https://nexcmp.com/es/docs/getting-started/installation/) y, a continuación, ejecute el [asistente de configuración](https://nexcmp.com/es/docs/getting-started/setup-wizard/). 4. Conecte su plataforma: [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). --- # Requisitos del servidor NexCMP {#requirements-for-the-nexcmp-server} Esta página cubre el servidor que ejecuta NexCMP. Los requisitos para su CloudStack, Proxmox VE u otra infraestructura se detallan en [Requisitos de infraestructura](https://nexcmp.com/es/docs/infrastructure/requirements/). ## Servidor {#server} | Elemento | Requisito | Comprobado por el instalador | |---|---|---| | Sistema operativo | Ubuntu **22.04** o **24.04** | Sí — se detiene con un error en cualquier otro caso | | Arquitectura de CPU | x86_64 | Sí | | Memoria | 2 GB mínimo (el instalador rechaza menos de aproximadamente 1.8 GB) | Sí | | Espacio libre en disco | 8 GB libres en `/` como mínimo | Sí | | Privilegios | root (`sudo`) | Sí | | Paquetes | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — instalados automáticamente | Se instalan si faltan | | Con HTTPS | `nginx` y `certbot` — instalados automáticamente a menos que pase `--no-nginx` | Se instalan si faltan | ::: tip Dimensionamiento Una instalación pequeña (unos cientos de clientes) funciona cómodamente con 2 vCPU / 4 GB de RAM. El uso de disco está dominado por las bases de datos SQLite y las copias opcionales de actualización y seguridad — prevea 20 GB o más para producción. ::: ## Red {#network} | Dirección | Puerto | Propósito | |---|---|---| | Entrante | 80/tcp | Validación de Let's Encrypt y redirección a HTTPS | | Entrante | 443/tcp | Portal de clientes, consola de administración, API | | Entrante | 3000/tcp | Asistente de configuración en la primera instalación y acceso de emergencia únicamente — consulte [Instalación](https://nexcmp.com/es/docs/getting-started/installation/#the-panel-port-3000) | | Saliente | 443/tcp hacia `nexcmp.com` | Activación de licencia, comprobación diaria de licencia, actualizaciones | | Saliente | hacia su API de CloudStack / API de Proxmox | Aprovisionamiento y sincronización | | Saliente | 443/tcp hacia los proveedores de pago, correo electrónico e IA que habilite | Stripe, PayPal, SMTP, proveedores de IA, entre otros | El servidor necesita una **dirección IPv4 pública** si desea que Let's Encrypt emita un certificado directamente. Si el dominio está bajo proxy de Cloudflare, consulte [DNS y Cloudflare](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/). ## DNS - Un **dominio principal** (por ejemplo `cloud.example.com`) — el portal es `https://cloud.example.com/` y la consola de administración es `https://cloud.example.com/admin`. - Opcional: `admin.` y `partner.`. Si dichos nombres resuelven al servidor (o a Cloudflare), el instalador los añade al certificado. - El dominio debe coincidir con el registrado en su licencia. ## No requerido en este servidor {#not-required-on-this-server} NexCMP se ejecuta como un usuario de servicio común sin privilegios (`nexcmp`). **No** necesita permisos de root en tiempo de ejecución, Docker, un servidor de base de datos independiente, Redis ni ningún software de hipervisor. --- # Licencia y compra {#license-and-purchase} > **Ubicación en el panel de administración:** System › Admin › License & updates (`/license`) NexCMP se activa con una **clave de licencia** que se gestiona desde su [cuenta de NexCMP](https://nexcmp.com/licenses). Las ediciones y los precios actuales figuran en [nexcmp.com/pricing](https://nexcmp.com/pricing); esta página explica el funcionamiento de la licencia una vez adquirida. ## Obtener una licencia {#get-a-license} 1. Cree una cuenta en [nexcmp.com](https://nexcmp.com/register) y verifique su correo electrónico. 2. Elija una edición: - **NexCMP Free**: para operadores de red con ASN propio y una subred registrada a su nombre. Envíe una solicitud en [nexcmp.com/deploy](https://nexcmp.com/deploy) (empresa, ASN, subred, dominio del panel). El correo de su cuenta debe pertenecer al dominio corporativo que figura en el registro público (WHOIS) para el ASN o la subred. Cada solicitud se revisa de forma individual; recibirá un correo cuando se tome una decisión y la clave de licencia solo estará visible tras la aprobación. - **NexCMP Source**: actualización de pago único, sin necesidad de ASN. Consulte [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. Abra la página de su licencia. Allí se muestran la **clave de licencia** (formato `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), el **dominio principal** y un comando de instalación listo para usar. ::: warning Mantenga la clave en privado La clave de licencia activa una instalación. Trátela como una contraseña: no la pegue en tickets, chats ni capturas de pantalla. ::: ## Qué contiene una licencia {#what-a-license-contains} | Campo | Significado | |---|---| | Main domain | El nombre de host en el que se ejecuta su portal. La clave queda vinculada a este al activarse. | | Reseller domains | Nombres de host adicionales servidos como portales de marca blanca; consulte [Revendedores](https://nexcmp.com/es/docs/customers/resellers/). | | Updates until | Fecha límite hasta la cual recibe **actualizaciones y correcciones de errores**. Una licencia Free comienza con **1 año** a partir del día de su aprobación; renuévela por $99 al año desde la página de su licencia. Los parches de seguridad se entregan siempre, incluso después de esta fecha. | | Status | `active`, o suspendida / vencida / revocada. | ## Cuándo termina el año gratuito {#when-the-free-year-ends} El software **sigue funcionando** cuando pasa la fecha de "Updates until": los clientes, los servicios y la facturación no se ven afectados. Deja de recibir nuevas versiones de funciones y correcciones de errores (los parches de seguridad se siguen entregando). Renuévela por $99 al año en la página de su licencia en [nexcmp.com/licenses](https://nexcmp.com/licenses) para continuar; la renovación añade 12 meses a la fecha de finalización actual. NexCMP Free solo incluye correcciones de errores: no incluye soporte técnico ni aplicaciones. ## Qué añade NexCMP Source {#what-nexcmp-source-adds} Una licencia Source es una actualización de pago único de $1,999 para su licencia: el código fuente completo, todas las aplicaciones de NexCMP (Android, iOS, Windows, macOS, Linux, Chrome / Edge / Brave y Firefox) compiladas y personalizadas con su marca, y 30 días laborables con un ingeniero experto: migración gratuita desde VMware, WHMCS u otro panel, o una configuración completa de principio a fin. Se incluyen nuevas versiones del código fuente durante 12 meses; renovarlas posteriormente ($99 al año) es opcional, y el código fuente descargado queda en su propiedad definitiva. Consulte los [términos de la licencia Source](https://nexcmp.com/legal/source-license/). ## Cómo comprueba la instalación su licencia {#how-the-installation-checks-its-license} - Durante la instalación, el servidor activa la clave para su dominio y recibe un **token firmado**. - El token se renueva automáticamente cada **24 horas**. Mantiene su validez durante **14 días**, por lo que una breve interrupción de la conexión a Internet no afecta el servicio. - Todas las versiones y tokens se verifican con una firma Ed25519 integrada en el programa; cualquier descarga alterada se rechaza. Compruebe el estado en cualquier momento en la consola de administración o con `sudo nexcmp status`. ## Si la licencia no es válida {#if-the-license-is-not-valid} Cuando el token caduca, o la licencia se suspende o el dominio ya no coincide: - los clientes **no pueden crear nuevos servicios** y la consola de administración muestra un banner; - los servicios que ya están en ejecución, **la facturación y los clientes existentes no se ven afectados**; - corrija la causa (vuelva a conectar el servidor a Internet, renueve en [nexcmp.com/licenses](https://nexcmp.com/licenses)) y haga clic en **Check now** en License & updates. ## Migración a un nuevo servidor o dominio {#moving-to-a-new-server-or-domain} Active en el nuevo servidor con la misma clave y el dominio registrado (consulte [Instalación](https://nexcmp.com/es/docs/getting-started/installation/)). Para cambiar el dominio registrado, hágalo primero en su página de licencia en [nexcmp.com/licenses](https://nexcmp.com/licenses) y luego vuelva a ejecutar el instalador con el nuevo `--domain`. --- # Instalar NexCMP {#install-nexcmp} El instalador es un único script servido por su servidor de licencias. Comprueba la máquina, activa su licencia, descarga y verifica el programa, instala los servicios y (opcionalmente) configura nginx con un certificado de Let's Encrypt. ## Antes de comenzar {#before-you-start} - Un servidor que cumpla los [requisitos](https://nexcmp.com/es/docs/getting-started/requirements/) y acceso root. - Su **clave de licencia** y **dominio principal** de su [página de licencia](https://nexcmp.com/licenses) — consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/). - Un registro DNS para el dominio — consulte [DNS y Cloudflare](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/). También puede instalar primero y corregir el DNS más tarde; el instalador le indicará qué falta y simplemente puede ejecutarse de nuevo. ## Instalación {#install} 1. Inicie sesión en el servidor y acceda como root (o anteponga `sudo`). 2. Ejecute el comando de su página de licencia. Tiene este aspecto: ```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. Espere a que aparezcan las marcas de verificación. Una instalación limpia tarda unos minutos; el primer inicio crea el esquema de la base de datos y puede tardar hasta un minuto en discos lentos. 4. Lea el resumen al final. Muestra las URL del portal y de administración, el **código de configuración** y el siguiente paso. ![El instalador finalizando con la URL del portal, la URL de administración y el código de configuración de un solo uso](https://nexcmp.com/es/docs/images/getting-started/installation-01-finish.webp) ## Parámetros {#parameters} | Parámetro | Predeterminado | Significado | |---|---|---| | `--license KEY` | obligatorio en la primera instalación | La clave de licencia. | | `--domain NAME` | obligatorio en la primera instalación | Dominio principal. Debe coincidir con la licencia. Se eliminan `https://` y las rutas finales. | | `--email ADDRESS` | ninguno | Correo electrónico de contacto para avisos de caducidad de Let's Encrypt. Sin él, el certificado se registra sin correo electrónico. | | `--port N` | `3000` | Puerto local del panel (1–65535). | | `--no-nginx` | desactivado | No instala ni configura nginx / TLS. Utilice esta opción si ejecuta su propio proxy inverso o desea probar NexCMP primero. | | `--behind-cloudflare` | detectado automáticamente | Fuerza el modo "el dominio pasa por el proxy de Cloudflare". Normalmente se detecta a partir del DNS. | | `--channel NAME` | `stable` | Canal de versiones. | Ejecutar el instalador de nuevo **sin parámetros** reutiliza los guardados (`/etc/nexcmp/install.conf`) y actualiza de forma segura, manteniendo los datos, la configuración y las cuentas. Eso es exactamente lo que hace `sudo nexcmp update`. ## Qué hace el instalador {#what-the-installer-does} 1. **Comprueba la máquina** — Ubuntu 22.04/24.04, x86_64, al menos 2 GB de RAM, 8 GB de disco libre. 2. **Instala los paquetes** necesarios (`curl`, `zstd`, `openssl`, `python3`, `openssh-client` …). 3. **Crea el usuario de servicio** `nexcmp` y los directorios: `/opt/nexcmp` (programa, propiedad de root, solo lectura para el servicio), `/etc/nexcmp` (configuración), `/var/lib/nexcmp` (datos), `/var/log/nexcmp`. 4. **Activa la licencia** para el dominio y almacena un ID de instancia fijo para esta máquina. 5. **Descarga la versión más reciente a la que tiene derecho**, luego verifica su SHA-256 y su firma Ed25519. Se rechaza cualquier versión sin una firma válida. Nunca degrada una versión más reciente en ejecución. 6. **Escribe la configuración y las unidades de systemd** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) e inicia los servicios; espera a que `/healthz` responda. 7. **Configura nginx y TLS** (a menos que `--no-nginx`): obtiene un certificado de Let's Encrypt con certbot (desafío webroot) para el dominio y para `admin.` / `partner.` cuando esos nombres también resuelven. Si el DNS aún no apunta a este servidor (o a Cloudflare), omite este paso y lo notifica. 8. **Muestra un resumen** con las URL y, si aún no existe un administrador, el **setup code**. ## El puerto del panel (3000) {#the-panel-port-3000} - Durante la primera instalación, el panel escucha en `0.0.0.0:3000` para que pueda abrir el asistente de configuración en `http://:3000/setup`. - Una vez finalizado el asistente **y** cuando TLS esté activo, el panel solo escucha en `127.0.0.1`; nginx actúa como proxy de `https://` hacia él. - En caso de emergencia (nginx dañado, DNS incorrecto), puede abrir el puerto durante un tiempo limitado: `sudo nexcmp open-port 30` (30 minutos, luego se cierra automáticamente) — o usar un túnel SSH: `ssh -L 3000:127.0.0.1:3000 ` y navegar a `http://127.0.0.1:3000/`. ::: warning HTTP sin cifrar El puerto 3000 es HTTP sin cifrar. Úselo únicamente para el asistente de configuración en una red de confianza o mediante un túnel SSH. No lo deje abierto. ::: ## Instalación sin un dominio público (laboratorio o pruebas) {#installing-without-a-public-domain-lab-or-test} Puede realizar la instalación en una máquina que aún no tenga DNS: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` A continuación, abra el asistente mediante un túnel SSH (`ssh -L 3000:127.0.0.1:3000 `, acceda a `http://127.0.0.1:3000/setup`). Vuelva a ejecutar el instalador sin `--no-nginx` una vez que exista el DNS. ## Docker y Kubernetes {#docker-and-kubernetes} No existe una imagen de contenedor publicada. El instalador (una instalación nativa de systemd) es el método de instalación admitido. ## Verificación {#verify} ```bash sudo nexcmp status ``` Debería ver la versión, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` y —hasta que finalice el asistente— el setup code. Continúe con el [asistente de configuración](https://nexcmp.com/es/docs/getting-started/setup-wizard/). Si algo falla, consulte [Errores de instalación](https://nexcmp.com/es/docs/troubleshooting/installation-errors/). --- # DNS y Cloudflare {#dns-and-cloudflare} NexCMP necesita un nombre DNS —su **dominio principal**— y funciona en dos modos. ## Modo A: el DNS apunta directamente al servidor {#mode-a-dns-points-straight-at-the-server} 1. Cree un registro **A** `cloud.example.com → ` (y un registro **AAAA** si el servidor tiene IPv6). 2. Opcional, si los utiliza: `admin.cloud.example.com` y `partner.cloud.example.com` apuntando a la misma IP. 3. Ejecute (o vuelva a ejecutar) el [instalador](https://nexcmp.com/es/docs/getting-started/installation/). Este detecta que el nombre resuelve a la propia IP pública del servidor y obtiene un certificado de Let's Encrypt mediante el desafío HTTP-01 en el puerto 80. ## Modo B: el dominio pasa por el proxy de Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} Cree los mismos registros con la nube naranja (**Proxied**). El instalador detecta que el nombre solo resuelve a direcciones de Cloudflare y cambia al modo Cloudflare: - nginx sigue escuchando en los puertos 80/443 de su servidor; - la IP real del visitante se lee del encabezado `CF-Connecting-IP` — **únicamente** para conexiones provenientes de los rangos publicados de Cloudflare, por lo que nadie más puede falsificarla; - el certificado se obtiene a través de Let's Encrypt (Cloudflare reenvía el desafío a su origen); si aún no es posible, se crea un **certificado de origen autofirmado** para que funcione el modo "Full", y una ejecución posterior del instalador actualizará a Let's Encrypt. Puede forzar este modo con `--behind-cloudflare`. ::: important Configurar el modo SSL/TLS en Cloudflare En Cloudflare, vaya a **SSL/TLS › Overview** y seleccione **Full (strict)** una vez que el instalador reporte un certificado de Let's Encrypt. Con un certificado de origen autofirmado, use **Full**. **Flexible** provocará bucles de redirección. ::: ::: tip Si "Always Use HTTPS" está activado, Cloudflare envía la solicitud de validación al puerto 443 de su origen. El instalador gestiona esto creando primero el certificado autofirmado temporal y reintentando luego con Let's Encrypt. ::: ## Comprobación {#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 ``` Los certificados se renuevan automáticamente mediante el temporizador de certbot. La renovación utiliza el webroot `/var/www/nexcmp-acme`, por lo que el puerto 80 debe permanecer accesible (directamente o a través de Cloudflare). ## Problemas comunes {#common-problems} | Síntoma | Causa | Solución | |---|---|---| | El instalador indica "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" | Registro DNS ausente, incorrecto o no propagado | Corrija el registro, espere la propagación y vuelva a ejecutar el instalador. | | El navegador muestra `ERR_TOO_MANY_REDIRECTS` detrás de Cloudflare | El modo SSL es **Flexible** | Establezca **Full (strict)** (o **Full**). | | Error 525/526 de Cloudflare | Certificado de origen rechazado | Use **Full** con un certificado de origen autofirmado, o **Full (strict)** con Let's Encrypt. | | Todos los visitantes muestran IPs de Cloudflare en los registros | No está en modo Cloudflare | Vuelva a ejecutar el instalador con `--behind-cloudflare`. | Más información en [Errores de instalación](https://nexcmp.com/es/docs/troubleshooting/installation-errors/). --- # Asistente de configuración {#setup-wizard} > **Ubicación en el admin:** el asistente es una página independiente en `/setup` que solo se muestra hasta que exista el primer administrador. Posteriormente, las mismas comprobaciones se encuentran en System › Admin › Start (`/setup`). El asistente convierte una instalación nueva en un panel funcional en cuatro breves pasos. Se sirve en el puerto 3000 (`http://:3000/setup`) o, cuando TLS ya está activo, en `https:///setup`. ::: warning El asistente desaparece después del paso 3 Una vez creado el administrador, el asistente se cierra y se elimina el código de configuración. Para acceder al panel posteriormente, use la consola de administración. ::: ## Paso 0 — Setup code {#step-0-—-setup-code} El instalador imprime un **código de configuración de un solo uso** al final. Puede volver a consultarlo con: ```bash sudo nexcmp status ``` Péguelo en **Setup code** y haga clic en **Continue**. El código protege el asistente: nadie que encuentre el puerto abierto podrá crear el administrador sin él. ![Paso 0 del asistente de configuración solicitando el código de configuración de un solo uso](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-00-code.webp) ## Paso 1 — License {#step-1-—-license} | Campo | Valor | |---|---| | License key | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — preactivada por el instalador, por lo que este paso normalmente muestra "Activated for cloud.example.com" | | Main domain | El dominio registrado en la licencia | Si el instalador ya activó la licencia, el asistente la reconoce y continúa. De lo contrario, introduzca la clave y el dominio y haga clic en **Activate**. Los errores se muestran en rojo; consulte [Errores de instalación](https://nexcmp.com/es/docs/troubleshooting/installation-errors/). ![Paso 1 del asistente de configuración que muestra la licencia ya activada para el dominio principal](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-01-license.webp) ## Paso 2 — CloudStack (o Connect later) {#step-2-—-cloudstack-or-connect-later} Tiene dos opciones: - **Conectar ahora.** Introduzca la **API URL** (`https://cloudstack.example.com/client/api`), la **API key** y la **Secret key** de CloudStack, haga clic en **Test connection** y, a continuación, seleccione la **Zone**, la **Guest network for customer VMs**, un **Zone display name** y el **Country** de dos letras. Haga clic en **Save CloudStack**. - **Conectar más tarde.** Haga clic en **Connect later**. Todo lo demás funciona; después puede conectar CloudStack o Proxmox VE en Infrastructure. Hasta entonces, el panel de estado le recordará que no hay ninguna fuente conectada. ![Paso 2 del asistente con los campos API URL, API key y Secret key de CloudStack completados con valores de ejemplo](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important Utilice una cuenta dedicada de CloudStack No utilice la clave de administrador ROOT. Cree un dominio y una cuenta dedicados para NexCMP y utilice su API key; consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). El asistente verifica que la red seleccionada pertenezca a la zona y a la cuenta de dicha clave. ::: ![Tras Test connection: las listas de zona y red de invitados, y los campos de nombre para mostrar de la zona y país](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) Si solo tiene previsto utilizar **Proxmox VE**, elija **Connect later** y siga [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). ## Paso 3 — Administrador y marca {#step-3-—-administrator-and-brand} | Campo | Reglas | |---|---| | Correo del administrador (login) | Dirección de correo electrónico válida. Este es su nombre de usuario administrador. | | Contraseña | Al menos 12 caracteres, con letras y dígitos. | | Nombre de la marca | Se muestra a sus clientes (por defecto "Cloud"). Hasta 60 caracteres. | | Correo de soporte | Por defecto, el correo electrónico del administrador. | ![Paso 3 del asistente con el correo electrónico del administrador, contraseña, nombre de la marca y correo de soporte](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-03-admin.webp) Haga clic en **Finish setup**. El panel se reinicia (aproximadamente 1–2 segundos) y la página le redirige al inicio de sesión de administración en `https:///admin/`. Si esa dirección aún no responde (DNS o TLS pendiente), le redirige en su lugar a `/` en la dirección actual. ![El asistente tras completarse con el mensaje de que el panel se está reiniciando](https://nexcmp.com/es/docs/images/getting-started/setup-wizard-03-done.webp) ## Lo que el asistente configura para usted {#what-the-wizard-sets-up-for-you} - Nombre de la marca, URL del sitio (`https://`), URL de administración (`https:///admin`), URL de la consola (`https:///console`), correo de soporte y nombre del remitente. - Ajustes predeterminados para los módulos incluidos con NexCMP: DDoS & BGP, AI y web SSH están **desactivados**; la medición de ancho de banda está **activada**. Consulte [Módulos](https://nexcmp.com/es/docs/infrastructure/modules/). - Si conectó CloudStack: el proveedor #1, su primera zona, la red de invitados y un par de claves de operaciones que se asocia a las VM de los clientes para que pueda brindarles soporte. Siguiente: [Primer inicio de sesión](https://nexcmp.com/es/docs/getting-started/first-login/). --- # Primer inicio de sesión y próximos pasos {#first-login-and-next-steps} > **Dónde en el panel de administración:** la página de inicio de sesión es `/admin`; tras iniciar sesión, la página de destino es Overview › Dashboard. ## Direcciones {#addresses} | Qué es | URL | |---|---| | Portal de clientes | `https:///` | | Consola de administración | `https:///admin` | | Configuración / emergencia por IP | `http://:3000/` (consulte [el puerto del panel](https://nexcmp.com/es/docs/getting-started/installation/#the-panel-port-3000)) | | Comprobación de estado | `https:///healthz` | ## Iniciar sesión {#sign-in} 1. Abra `https:///admin`. 2. Introduzca el correo electrónico y la contraseña de administrador creados en el asistente. 3. Accederá a **Dashboard**. Aparecerá un aviso en la parte superior si la licencia no es válida o no hay ninguna fuente conectada. ![La página de inicio de sesión de administración](https://nexcmp.com/es/docs/images/getting-started/first-login-01-login.webp) ## Lista de comprobación recomendada {#recommended-checklist} Siga estos pasos en orden; cada uno enlaza a su página correspondiente. | # | Tarea | Página | |---|---|---| | 1 | Activar la autenticación de dos factores para su cuenta | [Security](https://nexcmp.com/es/docs/administration/security/) | | 2 | Conectar una fuente de infraestructura (si eligió «Connect later») | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) | | 3 | Comprobar las zonas y la lista de plantillas de máquinas / sistemas operativos | [Zones](https://nexcmp.com/es/docs/infrastructure/zones/), [Templates](https://nexcmp.com/es/docs/infrastructure/templates/) | | 4 | Revisar planes y precios | [Plans](https://nexcmp.com/es/docs/catalog/plans/) | | 5 | Definir el logotipo, los colores y las páginas legales | [Branding](https://nexcmp.com/es/docs/customers/branding/), [Legal](https://nexcmp.com/es/docs/customers/legal/) | | 6 | Configurar el correo saliente y enviar una prueba | [SMTP and emails](https://nexcmp.com/es/docs/administration/smtp-and-emails/) | | 7 | Habilitar al menos un canal de pago y probar una recarga | [Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/) | | 8 | Decidir qué módulos vender | [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | | 9 | Realizar un pedido de prueba como cliente y eliminarlo | [Ordering](https://nexcmp.com/es/docs/portal/ordering/) | | 10 | Realizar una primera copia de seguridad | [Backup and restore](https://nexcmp.com/es/docs/getting-started/backup-and-restore/) | ## Crear su primer pedido (smoke test) {#create-your-first-order-smoke-test} 1. Abra el portal de clientes en una ventana privada y registre una cuenta de prueba. 2. Añada saldo (un cupón o un pago de prueba). 3. Contrate el plan más pequeño de su zona. 4. Compruebe cómo aparece en el panel de administración en Services › Virtual Machines, abra su consola y luego destrúyala. Si la VM no pasa al estado *running*, abra **Infrastructure › Cloud provider › Sync & errors** y revise el error. --- # Actualización de NexCMP {#updating-nexcmp} > **Dónde en el panel de administración:** System › Admin › License & updates (`/license`) → tarjeta *Update*. ## Qué incluye {#what-you-receive} | Tipo de versión | Cuándo se entrega | |---|---| | Corrección de seguridad | **Siempre**, incluso después de su fecha de "updates until" | | Versión de funciones | Solo si se publicó **en o antes de** su fecha de "updates until" | Puede ver ambas fechas en **License & updates**. Renueve el derecho en [nexcmp.com/licenses](https://nexcmp.com/licenses). ## Actualizar desde la consola de administración {#update-from-the-admin-console} 1. Abra **System › Admin › License & updates**. 2. En la tarjeta **Update**, haga clic en **Check for update**. La tarjeta muestra la versión actual, la versión más reciente que puede instalar, una etiqueta *security* cuando corresponda y el registro de cambios. 3. Haga clic en **Update to X.Y.Z** y confirme. El programa descarga la versión, verifica su **firma SHA-256 y Ed25519**, reemplaza el binario de forma atómica (conservando una copia `.bak`) y se reinicia. El tiempo de inactividad estimado es de unos **10 segundos**. 4. Recargue la página y compruebe la versión en la parte superior derecha de License & updates. ![La tarjeta Update con la versión en ejecución y el botón Check for new version](https://nexcmp.com/es/docs/images/getting-started/updating-01-card.webp) ## Actualizar desde la línea de comandos {#update-from-the-command-line} ```bash sudo nexcmp update ``` Esto ejecuta el instalador incluido *dentro de la versión actualmente instalada* (no un script descargado en ese momento) con los parámetros guardados de `/etc/nexcmp/install.conf`. Actualiza el binario, las unidades de systemd, las plantillas de nginx y el agente de nodo, y conserva los datos, la configuración y las cuentas. ::: tip Nunca degrada la versión Si el servidor ofrece una versión anterior a la que está en ejecución, el instalador mantiene la versión actual. ::: ## Antes de actualizar {#before-you-update} 1. Realice una copia de seguridad: `sudo nexcmp backup` — consulte [Copia de seguridad y restauración](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). 2. Lea el registro de cambios en la tarjeta Update. Para conocer los cambios desde la versión 1.3, consulte las [Notas de la versión hasta 1.6.1](https://nexcmp.com/es/docs/getting-started/release-notes/), incluida la actualización del agente VPN y las reglas de precios de Bare Metal. 3. Actualice durante un período de baja actividad; las máquinas virtuales en ejecución no se modifican, pero los clientes no podrán usar el portal durante unos segundos. ## Después de actualizar {#after-you-update} - Ejecute `sudo nexcmp status` y confirme que ambos servicios estén activos. - Abra el Dashboard de administración y la página **Needs attention**. - Las migraciones de la base de datos se ejecutan automáticamente al iniciar por primera vez la nueva versión. - Si administra nodos VPN, actualice su agente por separado y revise las lecturas de uso. Actualizar el panel pone a disposición el nuevo agente, pero no garantiza que cada nodo remoto ya lo esté ejecutando. Consulte [VPN node data allowance](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). Si una actualización falla, consulte [Errores de actualización](https://nexcmp.com/es/docs/troubleshooting/update-errors/). --- # Notas de la versión {#release-notes} > **Ubicación en el panel:** System › Admin › License & updates (`/license`), tarjeta **Update**. Estas notas cubren los cambios posteriores a la versión 1.3 hasta **NexCMP 1.6.1**. Realice una copia de seguridad antes de actualizar y use la versión que ofrece la tarjeta **Update** de su instalación. Consulte [Actualizar NexCMP](https://nexcmp.com/es/docs/getting-started/updating/) para ver los comandos y las comprobaciones de firma. ## 1.6.1 - **Métricas de Bare Metal:** la pestaña **Overview** del cliente muestra tarjetas de CPU, RAM, actividad de disco y red con historial reciente. Las mediciones no disponibles muestran un guion y el motivo. Las lecturas de red requieren un contador de tráfico; no se deducen del inventario de hardware de iDRAC. - **Planes de muestra de Bare Metal:** los nombres de muestra utilizan `BM-40C-`. Los planes de muestra integrados que no haya editado reciben nombres neutros. Los planes editados se conservan y un plan referenciado mantiene su código. Compruebe el hardware real del servidor antes de poner un plan a la venta. - **Cambios de plan:** la lista de solicitudes de administración se ordena en el servidor y mantiene visibles sus acciones al desplazarse horizontalmente. - **Informar de un error:** el formulario se desplaza manteniendo visibles sus botones. El enmascaramiento de contraseñas conserva el texto de diagnóstico que las rodea. - **Carga:** los recursos de la página y los datos de administración de uso frecuente se cargan antes para reducir las demoras de navegación. Consulte [Bare Metal setup, pricing and customer controls](https://nexcmp.com/es/docs/infrastructure/dedicated/) y [Report a bug](https://nexcmp.com/es/docs/administration/report-a-bug/). ## 1.6.0 - **Configuración de Bare Metal:** introduzca las redes iDRAC, la dirección del servidor ISO y la dirección de retorno del panel en **Safety › Management network connection**. Los valores de ejemplo bloquean las operaciones en producción hasta que se configuren. - **Alojamiento de ISO:** `sudo nexcmp dedicated-setup-iso` configura el servidor web de ISO en la red de administración. El instalador puede instalar la consola y las herramientas de ISO con `--baremetal` o mediante las opciones de ISO. Si faltan herramientas, las operaciones en producción se bloquean con `tools_missing`. - **Precios de Bare Metal:** una instalación nueva o sin usar comienza con precios en USD. Una instalación que ya contenga datos de precios en VND conserva VND y sigue requiriendo una tasa de cambio USD/VND. La actualización no reinterpreta esos precios existentes como dólares. - **Página del servidor para clientes:** renueve por adelantado, programe un cambio de ciclo de facturación, solicite un cambio de plan, consulte facturas y vea el inicio de sesión del SO tras la instalación. Un nuevo propietario no puede ver la contraseña de un propietario anterior. - **Perfiles de cliente:** ocho pestañas agrupan resumen, servicios, facturación, cuotas, seguridad, soporte, afiliados y registros. Los servicios comparten una única tabla con funciones de búsqueda y ordenación. - **Acciones de servicio:** bloquear, desbloquear, cancelar sin reembolso o cancelar con reembolso utilizan un cuadro de diálogo común. Los reembolsos regresan a la billetera o asignación de crédito original; las pasarelas de pago no se reembolsan automáticamente. Consulte [Servidores dedicados](https://nexcmp.com/es/docs/infrastructure/dedicated/) y [Gestión de clientes](https://nexcmp.com/es/docs/customers/managing-customers/). BYOIP y la asignación de una subred de cliente a un servidor Bare Metal siguen sin estar disponibles en NexCMP. ## 1.5.2 El administrador principal puede abrir **Report a bug** junto a **Docs** y enviar un ticket a la cuenta de la licencia sin necesidad de iniciar sesión por separado. Los diagnósticos son opcionales. El personal, los clientes y los asistentes de IA no pueden enviar reportes mediante esta acción. Consulte [Reportar un error](https://nexcmp.com/es/docs/administration/report-a-bug/). ## 1.5.1 - **Uso de VPN:** los nodos agente reportan el tráfico al panel. Una suscripción que agota su cuota de GB se suspende; vuelve a estar disponible tras una ampliación de ancho de banda o un nuevo periodo. Los nodos sin reportes de uso muestran **Not measured** y no se cortan en función de los GB. - **Agente VPN:** la versión 1.5.1 reintenta el uso no confirmado, envía el tráfico final al apagarse y cierra las conexiones abiertas cuando se detiene un endpoint. Actualice tanto los agentes remotos como el panel. - **Complementos VPN retirados:** High IP Reputation, High Concurrency y High Priority Network ya no están a la venta. Sus tarifas se eliminan de los importes de renovación futuros de las suscripciones existentes; los periodos pasados no se reembolsan. Si se eliminó un complemento del catálogo, verifique el importe de renovación manualmente. - **Etiquetas de protocolo:** el proxy HTTP IPv4 es HTTP plano. Las direcciones IPv4 no rotan. El puerto 443 del proxy IPv6 ofrece SOCKS5; no es un endpoint de proxy HTTPS. - **Instalación limpia:** la inicialización de la base de datos reintenta los conflictos transitorios de migración entre el panel y el worker, por lo que guardar el primer proveedor no requiere reiniciar. Consulte [Nodos VPN y proxy IPv6](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 **AI Models** es un módulo opcional de pasarela y facturación, desactivado de forma predeterminada. Añada orígenes de modelos que opere o tenga autorización para revender, sincronice modelos, configure precios y rutas, habilite los modelos y luego abra las ventas. No incluye cuentas de proveedores, modelos ni precios empaquetados. Es independiente del módulo AI Chat y AI Agent. Consulte [Modelos de IA](https://nexcmp.com/es/docs/infrastructure/ai-models/). ## 1.4.2 La instalación de nodos proxy IPv6 utiliza el demonio y el script de red incluidos en el paquete de la versión. El panel necesita `sshpass` para la instalación por SSH basada en contraseña. El panel ejecuta programaciones de rotación y la configuración del nodo excluye la dirección de puerta de enlace de las asignaciones. Mediante la personalización de marca se puede definir un nombre visible personalizado para el servicio VPN. Consulte [Nodos VPN y proxy IPv6](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **Administración con IA:** están disponibles el AI Chat de administración, cuentas personales de IA, claves API de administración, el servidor MCP de administración, conectores OAuth, importación/exportación de configuración y la lista de comprobación de configuración. Consulte [Configurar con IA](https://nexcmp.com/es/docs/configure-with-ai/overview/). - **Licenciamiento:** los flujos de trabajo Free y Source incluyen compilaciones oficiales y compilaciones personalizadas desde el código fuente. La cuenta, el licenciamiento, las descargas y la documentación utilizan `nexcmp.com`. Consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/). - **Enlaces a la documentación:** **Docs** en el panel de administración abre la guía correspondiente a la página actual. - **Monedas:** una nueva instalación sigue el idioma del cliente de forma predeterminada. USD/VND proviene de una tabla pública de tipos de cambio o de su tipo de cambio fijo. Consulte [Moneda y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). - **Zonas de origen mixto:** los precios públicos de Cloud Server funcionan cuando CloudStack y Proxmox VE comparten una zona. Los planes utilizan su propio origen de infraestructura. - **Precios derivados de las ofertas:** el porcentaje es un margen sobre el precio de venta. Un margen del 40% sobre un coste de $60 da como resultado $100, antes de cualquier redondeo. ## Lista de comprobación de actualización {#upgrade-checklist} 1. Haga una copia de seguridad, lea la tarjeta **Update**, actualice y ejecute `sudo nexcmp status`. 2. Actualice los agentes VPN y confirme que los nodos reporten el tráfico medido antes de depender del corte por límite de GB. 3. Si utiliza Bare Metal, compruebe los campos de red de gestión, las herramientas requeridas, la unidad de precio, las plantillas y los planes de muestra antes de abrir las ventas o iniciar operaciones en producción. 4. Abra un perfil de cliente y verifique su lista de servicios. Compruebe el importe y la asignación del pago original antes de confirmar una cancelación con reembolso. 5. Mantenga desactivados los módulos opcionales hasta que su infraestructura esté lista. Para AI Models, verifique un proveedor, un modelo con precio y una solicitud de cliente exitosa antes de abrir las ventas. --- # Copia de seguridad y restauración {#backup-and-restore} > **Ubicación en el admin:** System › Admin › Backup (`/backup`) solo aparece cuando el módulo DDoS & BGP está habilitado; para una instalación estándar, utilice la línea de comandos a continuación. ## Qué incluye la copia de seguridad {#what-is-backed-up} `sudo nexcmp backup` crea un archivo comprimido que contiene: | Parte | Contenido | |---|---| | `data/**/*.db` | Cada base de datos SQLite en `/var/lib/nexcmp`, copiada con la API de copia de seguridad en línea de SQLite — consistente incluso mientras el panel está en ejecución | | `files.tar` | Todos los demás archivos en `/var/lib/nexcmp` (archivos de configuración, archivos subidos de marca, `secrets/`), excepto las bases de datos y la carpeta `updates/` | | `etc/` | Una copia de `/etc/nexcmp` (configuración del instalador, ID de instancia, puerto y bind) | ::: warning El archivo contiene sus claves maestras `secrets/` contiene la clave que cifra las API keys, las credenciales de pago y las contraseñas SMTP almacenadas en la base de datos. El archivo se crea con los permisos `0600`. Guárdelo cifrado y fuera del servidor. Sin estas claves, una base de datos restaurada no puede descifrar sus secretos. ::: ## Realizar una copia de seguridad {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` El comando muestra la ruta del archivo, por ejemplo `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### Programar la copia de seguridad {#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 la carpeta fuera de la máquina (Object Storage, NAS u otro servidor). ## Restaurar {#restore} Restaure en un servidor donde esté instalada la **misma versión (o más reciente)** de NexCMP. 1. Instale NexCMP con el [instalador](https://nexcmp.com/es/docs/getting-started/installation/) usando la misma licencia y dominio, pero **no** ejecute el asistente de configuración. 2. Detenga los servicios: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. Descomprima el archivo en un directorio temporal: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. Vuelva a colocar los archivos: ```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 los servicios y verifique: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. Inicie sesión en `https:///admin` con el administrador del sistema *respaldado*. ::: tip Póngalo a prueba Realice los pasos 1 a 6 en un servidor de prueba antes de necesitarlo. Una copia de seguridad que nunca se ha restaurado es solo una esperanza. ::: ## No incluido {#not-included} - Configuración y certificados de nginx (regenerados por el instalador; los certificados de Let's Encrypt se vuelven a emitir). - Sus servidores CloudStack / Proxmox VE y las máquinas virtuales en ellos; realice copias de seguridad de estos con sus propias herramientas. --- # Desinstalar NexCMP {#uninstall-nexcmp} ::: warning Los clientes perderán el acceso La desinstalación detiene el portal y la facturación. Las máquinas virtuales en CloudStack o Proxmox VE siguen ejecutándose, pero nada las gestiona ni factura. Realice primero una [copia de seguridad](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). ::: ## Eliminar el programa y conservar los datos {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` Esto deshabilita y elimina los servicios `nexcmp` y `nexcmp-vmd`, el sitio y snippet de nginx, `/opt/nexcmp` y el comando `nexcmp`. Los **datos se conservan** en `/var/lib/nexcmp` y `/etc/nexcmp`, por lo que una instalación posterior en el mismo servidor continuará donde lo dejó. ## Eliminar todo {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` Elimina además `/var/lib/nexcmp`, `/etc/nexcmp`, `/var/log/nexcmp` y el usuario del sistema `nexcmp`. Esta acción no se puede deshacer. ## Tras la desinstalación {#after-uninstalling} - Los certificados de Let's Encrypt y los paquetes `nginx` / `certbot` se mantienen. Si lo desea, elimine el certificado con `sudo certbot delete --cert-name `. - Libere el dominio en su página de licencias en [nexcmp.com/licenses](https://nexcmp.com/licenses) si va a activarlo en otro lugar. - Elimine la cuenta dedicada de CloudStack o el token de API de Proxmox creados para NexCMP si ya no los necesita. --- # Referencia del comando `nexcmp` {#nexcmp-command-reference} El instalador ubica un asistente en `/usr/local/bin/nexcmp`. Ejecútelo en el servidor NexCMP. Los comandos que modifican el sistema requieren `sudo`. (La herramienta del cliente para la API es un programa diferente, consulte [cmp CLI](https://nexcmp.com/es/docs/developers/cmp-cli/)). | Comando | Requiere root | Qué hace | |---|---|---| | `nexcmp status` | No (más detalles con `sudo`) | Versión, estado del servicio (`nexcmp`, `nexcmp-vmd`), `/healthz`, resumen de licencia, estado del puerto público, código de configuración si el asistente no ha finalizado | | `nexcmp update` | Sí | Ejecuta el instalador incluido en la versión instalada con los parámetros guardados; consulte [Actualización](https://nexcmp.com/es/docs/getting-started/updating/) | | `nexcmp backup [dir]` | Sí | Copia de seguridad en `/var/backups/nexcmp` (o `dir`) — consulte [Copia de seguridad y restauración](https://nexcmp.com/es/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | Sí | Elimina los servicios y el programa; `--purge` también elimina los datos — consulte [Desinstalación](https://nexcmp.com/es/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | Sí | **Emergencia**: escucha en el puerto del panel (3000 por defecto) en todas las interfaces durante 1–1440 minutos (30 por defecto) y luego se cierra automáticamente | | `nexcmp close-port` | Sí | Cierra la ventana de emergencia ahora | | `nexcmp fix-owner` | Sí | Devuelve los archivos en `/var/lib/nexcmp` que pertenecen a root al usuario `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) ``` Si los archivos del directorio de datos pertenecen a root (por ejemplo, creados al ejecutar otro comando `nexcmp` con `sudo` como root), `status` muestra una advertencia porque el usuario del servicio no puede leerlos; un síntoma típico es que la licencia muestre HTTP 421. Corríjalo con `sudo nexcmp fix-owner`. Esta misma corrección se ejecuta automáticamente en cada inicio del servicio. ## Acceso de emergencia {#emergency-access} Cuando el dominio, nginx o TLS fallen, aún puede acceder al panel: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` Más seguro, sin abrir nada: `ssh -L 3000:127.0.0.1:3000 user@server` y navegue a `http://127.0.0.1:3000/`. ## Entorno {#environment} | Variable | Uso | |---|---| | `NEXCMP_BASE` | Invalida la URL base del servidor de licencias (por defecto `https://nexcmp.com`); solo para pruebas | Archivos y directorios: programa `/opt/nexcmp`, configuración `/etc/nexcmp`, datos `/var/lib/nexcmp`, registros `/var/log/nexcmp` y `journalctl -u nexcmp -u nexcmp-vmd`. --- # Requisitos de infraestructura {#infrastructure-requirements} > **Dónde está en el admin:** Infrastructure (la zona del menú izquierdo) y System › Admin › License & updates (`/license`) para activar módulos. Esta página enumera lo que necesita cada módulo **fuera** del servidor NexCMP. Para el propio servidor (Ubuntu, memoria, disco, puertos), consulte [Requisitos para el servidor NexCMP](https://nexcmp.com/es/docs/getting-started/requirements/). Para activar módulos, consulte [Módulos](https://nexcmp.com/es/docs/infrastructure/modules/). ## Módulo por módulo {#module-by-module} | Módulo | Infraestructura mínima | Detalles | |---|---|---| | **Virtual Machines en CloudStack** | Apache CloudStack 4.23 (probado), KVM, una zona avanzada con una red de invitados y un rango de IP públicas; un dominio y una cuenta dedicados con una clave de API (nunca ROOT); al menos una plantilla lista y una oferta de servicio | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) | | **Virtual Machines en Proxmox VE** | Proxmox VE 9.x (verificado en 9.2); un token de API con un rol personalizado; un almacenamiento con clonación; un bridge; un bloque IPv4 con puerta de enlace; una plantilla cloud-init por SO y por nodo | [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) | | **Plantillas de SO** | CloudStack: una máquina de compilación Linux con libguestfs y un servidor web para la imagen. Proxmox VE: plantillas cloud-image con el agente invitado | [Plantillas de SO](https://nexcmp.com/es/docs/infrastructure/templates/) | | **Bare metal / Servidor dedicado** | Servidores Dell con iDRAC 9 accesibles mediante HTTPS (Redfish) desde el panel en una red de gestión; un servidor HTTP en dicha red que sirva archivos ISO; carpetas ISO con permisos de escritura para el servicio de NexCMP | [Servidores dedicados](https://nexcmp.com/es/docs/infrastructure/dedicated/) | | **AI Models** | Una o más fuentes de modelos que esté autorizado a revender, con una API compatible con OpenAI o Anthropic y su propia clave; HTTPS saliente (puerto 443, nombre de dominio público) desde el panel hacia cada fuente, o una pasarela interna listada en Allowed internal hosts; sin GPU ni hardware especial | [AI Models](https://nexcmp.com/es/docs/infrastructure/ai-models/) | | **VPN** | Uno o más hosts Linux (x86_64, systemd, root) con direcciones IPv4 públicas en la interfaz o enrutadas hacia ella, HTTPS saliente hacia su panel | [Nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | Hosts Linux (x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`) con una IPv4 pública, puertos 80, 443 y 60001-65535 libres, y un prefijo IPv6 de /32 a /64 operativo para tráfico saliente; acceso SSH con contraseña para la instalación inicial | [Nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | Un clúster Ceph con RADOS Gateway (RGW), un usuario de Admin Ops y un endpoint público HTTPS en el puerto 443 | [S3](https://nexcmp.com/es/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack con Kubernetes Service (CKS) habilitado, al menos una ISO de versión de Kubernetes y una oferta de servicio gratuita para el plano de control de exactamente 2 vCPU y 2048 MB | [Kubernetes y Private Cloud](https://nexcmp.com/es/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack con una oferta de VPC y una oferta de red por cada plan de ancho de banda (más una oferta bloqueada de 1 Mbps) | [Kubernetes y Private Cloud](https://nexcmp.com/es/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack cuya VM de almacenamiento secundario pueda acceder a Internet para descargar imágenes de clientes (enlaces directos, sin redirecciones); la cuenta de CloudStack debe poder registrar plantillas e ISO | [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | | **Bandwidth** | Nada adicional con el origen predeterminado: el consumo se lee de las estadísticas de las VM de CloudStack. Las VM en Proxmox VE no se miden | [Bandwidth](https://nexcmp.com/es/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | Una API compatible con OpenAI (URL base, modelo y clave) a la que el servidor del panel pueda acceder. Sin software adicional en sus servidores | [Proveedores de IA](https://nexcmp.com/es/docs/ai/ai-providers/) | | **DDoS & BGP** | Un paquete complementario que requiere un host de router de borde con demonios que se ejecuten como root (BGP, filtrado, estadísticas de flujo). No forma parte de la instalación estándar | [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | | **DDoS Shield** | El complemento DDoS & BGP | [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | | **Terminal SSH web** | Un servicio proxy SSH independiente y una ruta para él. No forma parte de la instalación estándar; AI Agent no lo necesita | [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | ## Rutas de red de un vistazo {#network-paths-at-a-glance} | Origen | Destino | Puerto | Propósito | |---|---|---|---| | Servidor del panel | Servidor de administración de CloudStack | 443 u 8080 (según cómo lo publique) | API | | Servidor del panel | Nodo de Proxmox VE | 8006/tcp | API y consola | | Servidor del panel | Dell iDRAC | 443/tcp (y el puerto VNC, por defecto 5901) | Redfish y consola | | iDRAC | Servidor web de ISO | el puerto HTTP que elija (por ejemplo, 8080) | Medios virtuales | | Servidor del panel | Ceph RGW | 443/tcp | Admin Ops | | Servidor del panel | Nodo proxy IPv6 | Puerto SSH que introduzca | Instalación única | | Nodos VPN y proxy | Panel (a través de nginx) | 443/tcp | Registro, heartbeat, configuración | | Clientes | Nodos VPN y proxy | puertos 65001-65535 por IP (VPN); 80, 443, 60001-65535 (proxy IPv6) | El propio servicio | ::: tip Mantenga privadas las redes de gestión Las direcciones de gestión de iDRAC y de los hipervisores deben estar en una red a la que los clientes no puedan acceder. NexCMP rechaza las direcciones iDRAC fuera de los rangos privados que usted autorice. ::: ## Lista de comprobación antes de vender {#checklist-before-you-sell} 1. La infraestructura detrás del primer servicio está conectada y **Test connection** está en verde. 2. Una zona está lista para vender (consulte [Zones](https://nexcmp.com/es/docs/infrastructure/zones/)): un backend activo, un plan y una plantilla lista. 3. Hay un canal de pago configurado (consulte [Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/)). 4. El correo electrónico funciona (consulte [SMTP and e-mails](https://nexcmp.com/es/docs/administration/smtp-and-emails/)). 5. Ha realizado un pedido de prueba y ha eliminado la VM. --- # Arquitectura {#architecture} > **Ubicación en el panel de administración:** esta es una página de referencia. Los servicios descritos aquí son visibles con `sudo nexcmp status`; las conexiones se configuran en Infrastructure y System › Settings. ## El diagrama {#the-picture} ![Arquitectura de NexCMP: los clientes acceden a nginx mediante DNS y opcionalmente Cloudflare, nginx actúa como proxy hacia el panel en el puerto 3000, el panel y el worker se comunican con CloudStack, Proxmox VE, iDRAC, Ceph, pasarelas de pago, SMTP y un proveedor de IA, y los nodos VPN y de proxy IPv6 se comunican de vuelta con el panel](https://nexcmp.com/es/docs/images/infrastructure/architecture.svg) ### El mismo diagrama explicado {#the-same-diagram-in-words} 1. Un cliente o administrador abre `https://cloud.example.com` (el portal), `https://cloud.example.com/admin` (la consola de administración) o llama a la REST API. El DNS apunta el nombre a su servidor, o a Cloudflare, que actúa como proxy hacia él. 2. **nginx** en el servidor del panel escucha en los puertos 80 (redirección y renovación de certificados) y 443 (TLS) y reenvía cada solicitud al **panel** en `127.0.0.1:3000`. Tras el asistente de configuración inicial, el panel solo escucha en la interfaz loopback. 3. El **panel** (`nexcmp.service`) sirve el portal de clientes, la consola de administración, la REST API, el asistente de configuración inicial y las descargas que necesitan los nodos (el binario del agente, el script de instalación y la herramienta de línea de comandos `cmp`). También comprueba su licencia una vez al día. 4. El **worker** (`nexcmp-vmd.service`) escucha en `127.0.0.1:8112`, que es únicamente local. Ejecuta todo lo que requiere tiempo o debe realizarse de forma programada: tareas de aprovisionamiento, sincronización con CloudStack y Proxmox VE, ciclos de facturación, recopilación de ancho de banda y conexiones de consola en el navegador. 5. Desde estos dos procesos, NexCMP realiza llamadas externas: **CloudStack** (API de gestión), **Proxmox VE** (API en el puerto 8006, certificado fijado), **Dell iDRAC** (Redfish sobre HTTPS en la red de gestión), **Ceph RGW** (S3 y Admin Ops sobre HTTPS), **pasarelas de pago** (Stripe, PayPal, USDT y proveedores de transferencia bancaria, que también llaman a sus URL de webhook), **su servidor SMTP**, un **proveedor de IA** con una API compatible con OpenAI y, opcionalmente, **Telegram**. 6. Los **nodos VPN** ejecutan `cmp-agent`. Cada nodo se registra una vez con un token de un solo uso, luego envía un heartbeat cada 5 segundos por HTTPS al panel y recibe su configuración en la respuesta. Los **nodos de proxy IPv6** son instalados una vez por el panel a través de SSH y luego obtienen su configuración desde el panel. 7. El estado reside en bases de datos SQLite y algunos archivos en `/var/lib/nexcmp`. Las credenciales de CloudStack, Proxmox, S3, iDRAC y el proveedor de IA se almacenan cifradas (AES-256-GCM) con archivos de clave maestra en la misma ubicación. ## Servicios y procesos {#services-and-processes} | Proceso | Se ejecuta como | Escucha en | Función | |---|---|---|---| | `nginx` | root (workers `www-data`) | 80, 443 | TLS, redirección, proxy hacia el panel | | `nexcmp` | `nexcmp` | 3000 (todas las interfaces durante la primera instalación, luego `127.0.0.1`) | Portal, consola de administración, API, asistente, descargas | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | Tareas, sincronización, facturación, ancho de banda, consola | | `nexcmp-update` | root | ninguno | Aplica las actualizaciones que solicita la consola de administración (una unidad path espera la solicitud) | | `cmp-agent` (en nodos VPN) | root | los puertos de escucha VPN | Informa al panel, ejecuta listeners de proxy en IPv4 públicas | El panel y el worker se ejecutan como un usuario común sin ninguna capacidad de Linux, con un sistema de archivos de solo lectura excepto `/var/lib/nexcmp` y `/var/log/nexcmp`. No necesitan root, ni Docker, ni una base de datos independiente ni Redis. ## Archivos y dónde se encuentran {#files-and-where-they-are} | Ruta | Contenido | |---|---| | `/opt/nexcmp` | El programa: versiones, `bin/`, archivos compartidos como el creador de plantillas. Propiedad de root, de solo lectura para el servicio. | | `/etc/nexcmp` | Configuración del instalador (`install.conf`), puerto y bind (`nexcmp.env`). | | `/var/lib/nexcmp` | Bases de datos SQLite, elementos de marca subidos, la carpeta de descarga del agente, el estado de la licencia, los archivos de la clave maestra. Haga una copia de seguridad de esto. | | `/var/log/nexcmp` | Registros. | Consulte [Copia de seguridad y restauración](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). Debe hacer una copia de seguridad de los archivos de la clave maestra junto con las bases de datos; de lo contrario, una base de datos restaurada no podrá descifrar las credenciales almacenadas. ## Quién se conecta con quién {#who-connects-to-whom} | Dirección | Ruta | Puerto | Notas | |---|---|---|---| | Cliente al panel | Internet, DNS, Cloudflare opcional, nginx | 443 | Consulte [DNS y Cloudflare](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/). | | Panel al servidor de licencias | `nexcmp.com` | 443 | Activación, comprobación diaria y actualizaciones. | | Panel a CloudStack | API | 443 u 8080 | La consola de VM, el ancho de banda y las funciones de Kubernetes usan el mismo endpoint. | | Panel a Proxmox VE | API y consola WebSocket | 8006 | Certificado anclado mediante SHA-256. | | Panel a iDRAC | Redfish | 443, VNC 5901 | Solo red de gestión. | | iDRAC al servidor ISO | HTTP | su puerto | El iDRAC descarga la ISO. | | Panel a Ceph RGW | Admin Ops | 443 | | | Panel a SMTP | SMTP | 587 o 465 | | | Panel al proveedor de IA | HTTPS | 443 | Solo cuando el módulo de IA está activo. | | Pasarela de pago al panel | Webhook | 443 | Stripe y PayPal realizan callbacks. | | Nodo al panel | `cmp-agent` | 443 | Registro, heartbeat, actualización. | | Panel al nodo proxy IPv6 | SSH | el puerto que introduzca | Solo para la instalación inicial. | ## Por qué es importante {#why-it-matters} - **Un panel accesible es un panel que puede ser atacado.** Mantenga cerrado el puerto 3000 una vez finalizado el asistente de configuración. El instalador ya lo hace cuando TLS está activo. - **El worker debe estar en ejecución** para que se pueda crear o facturar cualquier elemento. `sudo nexcmp status` muestra ambos servicios y el health check. - **Planifique los firewalls de salida.** Si el tráfico saliente del servidor del panel está filtrado, permita los destinos de la tabla anterior. - **El tráfico de gestión se mantiene fuera de la ruta pública.** Las conexiones a CloudStack, Proxmox VE, iDRAC y Ceph van directamente desde el servidor del panel a dichos sistemas, nunca a través de nginx o Cloudflare. --- # Módulos {#modules} > **Ubicación en el admin:** System › Admin › License & updates (`/license`), la tarjeta **Module**. ## Qué hace {#what-it-does} Un módulo es un servicio o función que se puede activar o desactivar por completo. Un módulo **desactivado** queda oculto en el menú de administración y los clientes no pueden comprarlo; sus rutas de API devuelven `404 module_disabled` si el módulo es un add-on. Activar un módulo solo habilita la función: la infraestructura subyacente aún debe conectarse (consulte la última columna). ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta | Un administrador con permisos de escritura. El personal de solo lectura puede ver los conmutadores pero no modificarlos. | | Infraestructura | Consulte la tabla: cada módulo detalla sus requisitos. | | Depende de | Algunos módulos dependen de otros (DDoS Shield requiere DDoS & BGP). | ## Preparar la infraestructura {#prepare-the-infrastructure} No se requiere para el conmutador en sí. Conecte la infraestructura de cada módulo como se describe en la página vinculada en la tabla. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **System › Admin › License & updates** y desplácese hasta la tarjeta **Module**. Indica que los módulos desactivados quedan ocultos en el menú de administración y los clientes no pueden comprarlos. 2. Utilice el conmutador de un módulo. La página confirma **Saved: reloading menu** y se recarga, actualizando el menú de inmediato. ![La tarjeta Module en License & updates con un conmutador para cada módulo](https://nexcmp.com/es/docs/images/infrastructure/modules-01-license-modules.webp) ### Los módulos {#the-modules} | Módulo (como se muestra) | Predeterminado | Qué añade | Requisitos | Página | |---|---|---|---|---| | **Virtual Machines** | siempre activo | Catálogo de VM, pedidos, consola y Snapshots | CloudStack o Proxmox VE | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) | | **Bandwidth** | **activo** | Cuotas, complementos, alertas y acciones por exceso de uso para VM, Kubernetes y S3 | Nada adicional (estadísticas de VM de CloudStack) | [Bandwidth](https://nexcmp.com/es/docs/catalog/bandwidth/) | | **OS & ISO Images** | desactivado | Los clientes registran sus propias imágenes de SO e ISO, facturadas por GB | CloudStack; acceso a Internet para su VM de almacenamiento secundario | [Requisitos](https://nexcmp.com/es/docs/infrastructure/requirements/) | | **Kubernetes** | desactivado | Clústeres de Kubernetes (CKS) | CloudStack con CKS habilitado | [Kubernetes y Private Cloud](https://nexcmp.com/es/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | desactivado | VPC con planes de ancho de banda dedicado | CloudStack VPC y network offerings | [Kubernetes y Private Cloud](https://nexcmp.com/es/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | desactivado | Cuentas S3 en Ceph RGW, pago por uso | Ceph RGW y una zona con el servicio S3 | [S3](https://nexcmp.com/es/docs/infrastructure/s3/) | | **VPN** | desactivado | VPN en sus propios nodos | Nodos que ejecutan `cmp-agent` | [Nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | desactivado | Proxy IPv6 en sus propios nodos | Nodos proxy con un prefijo IPv6 | [Nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | desactivado | Servidores Dell mediante iDRAC: pedidos, instalación de SO, consola y control de energía | iDRAC 9 en una red de gestión | [Servidores dedicados](https://nexcmp.com/es/docs/infrastructure/dedicated/) | | **AI Models** | desactivado | Una pasarela que vende acceso a modelos de IA: una clave para varios modelos, precios por modelo, límites de uso, registros y facturación mediante monedero | Fuentes de modelos aportadas por usted: una API compatible con OpenAI o Anthropic con su propia clave | [AI Models](https://nexcmp.com/es/docs/infrastructure/ai-models/) | | **AI** | desactivado | AI Chat (soporte automatizado) y AI Agent (administración de VM en lenguaje natural) | Un proveedor compatible con OpenAI | [Proveedores de IA](https://nexcmp.com/es/docs/ai/ai-providers/) | | **DDoS Shield** | desactivado | Protección de IP para clientes; requiere DDoS & BGP, por lo que su conmutador permanece deshabilitado sin este | El complemento DDoS & BGP | más abajo | | **DDoS & BGP** | desactivado, **add-on** | Consola de router perimetral: BGP, RTBH, XDP, sesiones y tráfico perimetral | Un host perimetral con demonios root | más abajo | ### Qué hace cada conmutador {#which-switch-does-what} - **Bare Metal** tiene dos niveles. El conmutador del módulo muestra el menú de administración y la API. La venta a clientes es un conmutador independiente con confirmación escrita en **Services › Dedicated Server**, y cualquier escritura en un iDRAC se bloquea hasta activar **live ops** en **Infrastructure › Bare Metal › Safety**. Consulte [Servidores dedicados](https://nexcmp.com/es/docs/infrastructure/dedicated/). - Para **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** e **Images**, el conmutador del módulo y el conmutador de ventas en la página del servicio actúan sobre el mismo ajuste. - **AI** también requiere un proveedor configurado en **System › Settings › AI provider**. - **AI Models** tiene dos niveles. El interruptor del módulo muestra el menú de administración y la API. La venta a clientes es un interruptor de venta independiente en la parte superior de las páginas de AI Models, desactivado por defecto. Consulte [AI Models](https://nexcmp.com/es/docs/infrastructure/ai-models/). ### Módulos leídos al inicio {#modules-read-at-start-up} Tres características no son conmutadores comunes. Se leen **una sola vez al iniciar los servicios** y requieren una infraestructura que la instalación estándar no incluye. | Característica | Ajuste | Estado | Qué necesita | |---|---|---|---| | DDoS & BGP | `module_ddos` | Se muestra como **Add-on package** cuando está desactivado, **Installed** cuando está activado. No hay ningún conmutador en la consola. | Demonios del router perimetral (BGP, RTBH, XDP, estadísticas de flujo) que se ejecutan como root. El panel se ejecuta como un usuario sin privilegios y no puede ejecutarlos. | | AI | `module_ai` | Un conmutador normal. Las rutas lo aplican de inmediato; las tareas en segundo plano de AI Chat (investigación de tickets, respuestas programadas) se inician en el próximo reinicio de los servicios. La consola indica que se recomienda un reinicio. | El proveedor de AI. | | Terminal Web SSH | `feature_ssh_web` | Desactivado por defecto, sin conmutador en la consola | Un servicio de proxy SSH independiente y su ruta. Sin él, la pestaña Console del portal solo muestra VNC. El **AI Agent no lo necesita**: ejecuta comandos mediante una conexión SSH que el propio panel establece. | Tras modificar un ajuste de inicio, reinicie los servicios: `sudo systemctl restart nexcmp nexcmp-vmd`. ## Verificación {#verify} 1. La entrada de menú del módulo aparece (o desaparece) tras la recarga. 2. En el caso de un módulo orientado al cliente, el portal muestra la nueva entrada de menú para un cliente que haya iniciado sesión. Un módulo desactivado no muestra nada o "coming soon". ## Límites y notas {#limits-and-notes} - Desactivar un módulo no elimina nada. Las VM, clusters, cuentas S3 y suscripciones en ejecución continúan funcionando y facturándose; los clientes simplemente no podrán crear nuevos. - Las páginas de cuotas solo muestran los servicios cuyos módulos están activados. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | La opción de menú no apareció | No se recargó la página | Recargue la consola de administración. | | El interruptor de DDoS Shield está deshabilitado | DDoS & BGP no está instalado | DDoS Shield necesita el complemento DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 o 422) | Usted (o un script) intentó conmutar DDoS & BGP | Es un paquete de complemento; no dispone de interruptor. | | "DDoS Shield requiere el complemento DDoS & BGP" | Lo mismo, para DDoS Shield | Instale primero el complemento. | | Una ruta de módulo responde 404 `module_disabled` | El módulo está desactivado | Active el módulo. | | AI Chat responde pero la investigación de tickets nunca se inicia | El módulo AI se activó sin reiniciar | `sudo systemctl restart nexcmp nexcmp-vmd`. | | El personal de solo lectura no puede guardar | Su rol es de solo lectura | Utilice una cuenta de administrador. | --- # Zonas {#zones} > **Ubicación en administración:** Infrastructure › Datacenter › Zone (`/infra/zones`). La página de detalles de una zona es `/infra/zones/`. ## Qué hace {#what-it-does} Una **zona** es la ubicación que elige un cliente al realizar un pedido: un país y una ciudad con una bandera, además de los servicios que se venden allí. Es un concepto comercial, independiente de las zonas, clústeres y nodos de las plataformas subyacentes. A una zona se le asocia la **infraestructura**: una zona de CloudStack, un clúster de Proxmox VE, nodos VPN con rangos de IP o un backend de S3. La zona 1 es creada por el [asistente de configuración](https://nexcmp.com/es/docs/getting-started/setup-wizard/), con el nombre para mostrar y el país que haya ingresado. Añada más zonas cuando tenga infraestructura en más lugares, o para asignar a VPN y S3 sus propias ubicaciones. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Permisos | Una cuenta de administrador. Un rol de personal de solo lectura puede ver pero no modificar. | | Infraestructura | Una zona no vende nada hasta que se le asocie algo (consulte «Qué servicio se vende en cada lugar» más abajo). | | Depende de | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) para VM, [nodos VPN y proxy](https://nexcmp.com/es/docs/infrastructure/vpn-proxy-nodes/) para VPN, [S3](https://nexcmp.com/es/docs/infrastructure/s3/) para Object Storage. | ## Preparar la infraestructura {#prepare-the-infrastructure} No requerido. Una zona es un registro dentro de NexCMP. ## Conectar en NexCMP {#connect-in-nexcmp} ### Crear una zona {#create-a-zone} 1. Abra **Infrastructure › Datacenter › Zone** y haga clic en **Add zone**. 2. Complete el formulario: | Campo | Valor de ejemplo | Notas | |---|---|---| | País | `United States` | Selecciona la bandera. | | Ciudad | `New York` | Opcional. | | Nombre (vietnamita), Nombre (inglés) | `New York` | El nombre que ven los clientes en cada idioma. | | Slug | `us-new-york` | a-z, 0-9, guion, 2-32 caracteres. Se completa a partir del país y la ciudad hasta que escriba el suyo propio. | | Visibilidad | Público | Las zonas **Public** son visibles para todos los clientes; las zonas **Hidden** solo las asigna un administrador. | | Orden | `0` | Los números menores aparecen primero en las listas. | | Servicios vendidos en esta zona | Máquinas virtuales (VM), VPN, Object Storage (S3) | Marque al menos uno. | | Activo | On | **Off** oculta la zona a los clientes. | | Predeterminado | desactivado | La zona preseleccionada para los clientes que no hayan elegido ninguna. Solo una zona es la predeterminada. | ![Cuadro de diálogo Add zone con país, ciudad, slug y los servicios marcados](https://nexcmp.com/es/docs/images/infrastructure/zones-01-add-zone.webp) 3. Haga clic en **Create zone**. La lista muestra la zona con su bandera, propietario, servicios, estado y el recuento de VM, planes e infraestructura conectada. ![Lista de zonas con la zona predeterminada y una segunda zona](https://nexcmp.com/es/docs/images/infrastructure/zones-02-list.webp) ### Consultar los elementos conectados {#look-at-what-is-attached} Haga clic en una fila para abrir la zona. La pestaña **Provider infrastructure** enumera cada backend conectado con su proveedor, tipo (CloudStack o Proxmox VE), región, estado y prioridad. La pestaña **VPN infrastructure** enumera los rangos de VPN y los nodos de la zona, y enlaza al pool de VPN. ![Detalle de la zona con la pestaña Provider infrastructure](https://nexcmp.com/es/docs/images/infrastructure/zones-03-detail.webp) ### Dónde se vende cada servicio {#which-service-sells-where} | Servicio | Cómo se añade a una zona | |---|---| | Máquinas virtuales en CloudStack | El asistente (o **Infrastructure › Cloud provider › CloudStack**) conecta CloudStack a la zona 1. | | Máquinas virtuales en Proxmox VE | En la pestaña **Clusters** del clúster, use **Attach cluster to zone**. El clúster se une a una zona **existente**, normalmente aquella en la que se vende a través de CloudStack. | | VPN | Un nodo VPN que informa sus rangos de IP públicas crea (o se une a) una zona para su país e incorpora los rangos al pool de VPN. También puede asignar la zona y el nodo de un rango en **VPN IP pools**. | | IPv6 Proxy | Un nuevo nodo de IPv6 Proxy crea su zona en estado **off**. Active la zona aquí para que los clientes puedan seleccionarla. | | Object Storage (S3) | Marque el servicio S3 en la zona y luego conecte el backend en **Ceph S3 (RGW)**. | ### ¿Cuándo puede vender máquinas virtuales una zona? {#when-can-a-zone-sell-virtual-machines} Una zona muestra la etiqueta **not ready to sell VMs** hasta que tenga al menos un backend activo y disponible para la venta, **y** al menos un plan visible, **y** al menos una plantilla lista en dicho backend. El formulario de pedidos del cliente solo muestra las zonas que están listas. ## Verificación {#verify} 1. La zona aparece en la lista como **On**, con la bandera correcta. 2. Su página de detalles muestra el backend o los rangos de VPN esperados. 3. Para las VM: la etiqueta **not ready to sell VMs** desaparece. En el portal del cliente, inicie un pedido y compruebe que se ofrece la zona. ## Límites y notas {#limits-and-notes} - En esta versión de NexCMP, los clientes solicitan máquinas virtuales en la **zona predeterminada** (zona 1). Las demás zonas se utilizan para VPN, IPv6 Proxy y Object Storage, o para preparar una ubicación antes de que disponga de infraestructura; la nota situada bajo la lista de zonas indica lo mismo. - Una zona solo se puede eliminar cuando no tenga nada conectado: ni backends, ni VM, ni planes, ni rangos de VPN. La zona predeterminada no se puede eliminar; primero establezca otra zona como predeterminada. - Usted solo puede activar o desactivar, y ocultar o mostrar, las zonas que pertenecen a un reseller; sus demás campos están bloqueados. - El slug forma parte de las referencias internas. Elíjalo una sola vez. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "El nombre de la zona es obligatorio" / "Seleccione el país" / "Seleccione al menos 1 servicio" | Un campo obligatorio está vacío | Complete el nombre, elija el país y marque un servicio. | | "Slug no válido (a-z 0-9 -, 2-32 caracteres)" | El slug contiene otros caracteres o su longitud es incorrecta | Utilice únicamente letras minúsculas, dígitos y guiones. | | Etiqueta "not ready to sell VMs" | No hay ningún backend comercializable activo, plan ni plantilla lista en esa zona | Adjunte infraestructura y luego agregue un plan y una plantilla. Consulte [Plans](https://nexcmp.com/es/docs/catalog/plans/) y [Templates](https://nexcmp.com/es/docs/infrastructure/templates/). | | Delete está deshabilitado con "still attached" | La zona tiene backends, VM, planes o rangos de VPN | Elimínelos o muévalos primero. | | Delete está deshabilitado con "Default zone" | La zona es la predeterminada | Establezca otra zona como predeterminada. | | Los clientes no ven la zona | Está oculta, inactiva o no tiene ningún servicio marcado | Establezca Visibility en Public, Active en On y marque el servicio. | | Falta una zona S3 en el formulario del backend | El servicio S3 no está marcado en la zona | Edite la zona y marque **Object Storage (S3)**. | --- # CloudStack > **En el panel de administración:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). La primera conexión también puede realizarse en el [setup wizard](https://nexcmp.com/es/docs/getting-started/setup-wizard/), paso 2. ## Qué hace {#what-it-does} NexCMP vende máquinas virtuales que se ejecutan en su nube de Apache CloudStack. Despliega, inicia, detiene, redimensiona, crea Snapshots y elimina VM mediante la API de CloudStack, asigna direcciones IP públicas desde la zona, lee el consumo para facturación y ancho de banda, y muestra capacidad y estado en la consola de administración. CloudStack sigue siendo la fuente de referencia de los hipervisores; NexCMP es la tienda, la facturación y el portal superpuestos. Utilice esta página cuando CloudStack sea (o vaya a ser) su fuente principal de VM. Para configurar una segunda fuente complementaria, consulte [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Versión de CloudStack | 4.23 es la versión probada. La consola de VM requiere 4.18 o posterior, y el escalado en caliente de CPU/RAM de una VM en ejecución requiere 4.23 con KVM. | | Tipo de zona | Una zona con al menos una red de invitados para las VM de los clientes y un rango de IP públicas con direcciones libres. | | Hipervisor | KVM es el hipervisor probado. | | Cuenta | Un **dominio y cuenta dedicados** creados para NexCMP. Nunca utilice la clave de administrador ROOT. | | Accesibilidad de la API | El servidor del panel debe poder comunicarse con la URL de la API del servidor de administración (`https://cloudstack.example.com/client/api`) mediante HTTP(S). La consola de VM, el ancho de banda y las funciones de Kubernetes utilizan este mismo endpoint. | | Clave de solo lectura opcional | Una segunda clave de solo lectura permite que la consola de administración muestre hosts, almacenamiento, VM del sistema y rangos de IP públicas. No es necesaria para vender VM. | | IP pública | Direcciones IPv4 públicas libres en la zona. El prefijo que NexCMP puede vender se configura en Sales IP pools. | | Plantillas | Al menos una plantilla lista y con contraseña habilitada, y un service offering que su cuenta pueda ver. Consulte [Templates](https://nexcmp.com/es/docs/infrastructure/templates/). | | Almacenamiento | Almacenamiento primario para los volúmenes de la cuenta y, si vende snapshots o imágenes, almacenamiento secundario. | | Depende de | Nada. Kubernetes, Private Cloud, Images y Bandwidth dependen de esta página. | ::: warning No use la clave de administrador ROOT Cree un dominio y una cuenta dedicados para NexCMP. De este modo, la clave solo tendrá alcance sobre ese dominio y una clave filtrada no podrá afectar al resto de su cloud. El asistente de configuración también verifica que la red que elija pertenezca a la zona **y** a la cuenta propietaria de la clave. ::: ## Preparar la infraestructura {#prepare-the-infrastructure} Los comandos utilizan [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) con la sesión iniciada como administrador de CloudStack. Reemplace los nombres de ejemplo y los marcadores de posición entre corchetes angulares. ### Crear una cuenta y clave API dedicadas {#create-a-dedicated-account-and-api-key} 1. Cree el dominio que contendrá todo lo que pertenezca a NexCMP. ```bash cmk create domain name=nexcmp ``` Anote el `id` en la salida; se utilizará como `` más adelante. 2. Busque el rol que desea asignar a la cuenta. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Rol | Cuándo elegirlo | |---|---| | **Domain Admin** (recomendado) | Conjunto completo de funciones: VM, redes, proyectos para Kubernetes, VPC, imágenes. Su alcance se limita al dominio `nexcmp`. | | Usuario | Solo el ciclo de vida de las VM. Un usuario estándar no puede purgar VM a menos que la configuración global `allow.user.expunge.recover.vm` sea true; en ese caso, NexCMP detiene la VM y CloudStack la purga después de `expunge.delay`. | 3. Cree la cuenta y su primer usuario. Utilice una contraseña aleatoria larga; no volverá a escribirla. ```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. Genere el par de claves API para el nuevo usuario. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Copie `apikey` y `secretkey`. Son la **API key** y la **Secret key** que debe introducir en NexCMP. NexCMP las almacena cifradas y posteriormente solo muestra los últimos cuatro caracteres. 5. Asegúrese de que el dominio no tenga límites de recursos restrictivos (instances, volúmenes, IP públicas, redes, snapshots, plantillas, proyectos). ```bash cmk list resourcelimits domainid= ``` ### Crear la red de invitados para las VM de los clientes {#create-the-guest-network-for-customer-vms} Las VM de los clientes se despliegan en una red de invitados que pertenece a la nueva cuenta. Una red aislada con un router virtual (VR) y los servicios Static NAT, Firewall y Port Forwarding funciona adecuadamente, ya que NexCMP asocia una IP pública a cada VM mediante 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= ``` Compruebe la directiva de salida predeterminada de la oferta: si es "deny", las VM de los clientes no tendrán acceso saliente hasta que se añadan reglas de salida en el firewall. ### Hacer visibles las ofertas y plantillas {#make-offerings-and-templates-visible} - Las **service offerings** y **network offerings** deben ser públicas o estar asignadas al dominio `nexcmp`; de lo contrario, la cuenta no podrá enumerarlas ni utilizarlas. - Registre o comparta al menos una plantilla (consulte [Templates](https://nexcmp.com/es/docs/infrastructure/templates/)). NexCMP lista las plantillas que están listas y destacadas. ### Opcional: clave de solo lectura para las páginas de infraestructura {#optional-read-only-key-for-infrastructure-pages} Las pestañas **Capacity**, **Host**, **Storage** y **System VM**, así como la lista de rangos de IP públicas, utilizan una segunda clave que solo necesita acceso de lectura a seis comandos. Cree un rol limitado en lugar de reutilizar una clave 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 ``` A continuación, cree una cuenta con ese rol (en el dominio ROOT, ya que lee datos de toda la zona), genere sus claves como en el paso 4 e introdúzcalas como **RO API key** en la siguiente sección. ### Comprobar la ruta de red {#check-the-network-path} Desde el servidor del panel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Cualquier respuesta HTTP (incluso 4xx) confirma que el puerto es accesible. Un tiempo de espera agotado indica un problema de firewall o DNS de su parte. ## Conectar en NexCMP {#connect-in-nexcmp} ### En el asistente de configuración {#in-the-setup-wizard} El paso 2 del [asistente de configuración](https://nexcmp.com/es/docs/getting-started/setup-wizard/) solicita los mismos valores. **Test connection** enumera las zonas y redes visibles para la clave; elija la zona y la red de invitados, un nombre para mostrar para la zona y el país, y luego haga clic en **Save CloudStack**. El asistente rechaza cualquier red que no pertenezca a esa zona o que no sea visible para la clave. ![Paso 2 del asistente con la URL de la API y las claves de CloudStack completadas, y la zona y red seleccionadas tras Test connection](https://nexcmp.com/es/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Más tarde, en la consola de administración {#later-in-the-admin-console} 1. Abra **Infrastructure › Cloud provider › CloudStack** y seleccione la pestaña **API connection**. 2. Complete la sección **Connection**: | Campo | Valor de ejemplo | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | Clave de API (acceso de escritura) | `XXXX` (dejar vacío para conservar la clave guardada) | | Secret key | `XXXX` | | Clave de API de solo lectura / Clave secreta de solo lectura | opcional, de la cuenta de solo lectura | | Zone ID | el UUID de su zona | ![La pestaña API connection con un endpoint de ejemplo y claves enmascaradas](https://nexcmp.com/es/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Haga clic en **Test connection** antes de guardar. Comprueba las claves introducidas sin guardarlas: la clave de escritura con `listZones` y `listCapabilities`, y la clave de solo lectura con `listSystemVms`. 4. Haga clic en **Save connection**. Mantenga activado **Enable CloudStack connection**; desactivarlo hace que el worker detenga todos los trabajos de CloudStack sin perder datos. 5. Abra **Services › Virtual Machines › Policy › Provisioning** para configurar la red de invitados predeterminada, las ofertas personalizadas y el par de claves predeterminado para las nuevas VM. ![VM Policy, pestaña Provisioning, con el ID de red predeterminado](https://nexcmp.com/es/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Abra **Infrastructure › Cloud provider › Sales IP pools** y, en **Configure sales ranges**, configure **Sellable IP range prefixes** (por ejemplo `203.0.113.`) y **Excluded IP prefixes** si algunas direcciones de la zona no deben venderse nunca. Deje el prefijo vacío para permitir todas las direcciones libres. ![Sales IP pools con el prefijo comercializable 203.0.113. configurado](https://nexcmp.com/es/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### Qué lee y escribe NexCMP {#what-nexcmp-reads-and-writes} | Área | Lecturas | Modificaciones | |---|---|---| | VMs | lista, estados, historial de uso, endpoint de consola | desplegar, iniciar, detener, reiniciar, reinstalar, destruir, escalar, restablecer contraseña y clave SSH | | Discos y Snapshots | volúmenes, Snapshots de VM, Backups | crear, adjuntar, desconectar, redimensionar, eliminar, crear snapshot, restaurar | | Redes | redes, routers, IP públicas, firewall, reenvío de puertos, reglas de balanceador de carga | asociar y liberar IP públicas, NAT estático, firewall, reenvío de puertos, reglas de salida, redes y ACL para Private Cloud | | Catálogo | ofertas de servicio, disco y red, plantillas, ISO, tipos de SO | registrar y eliminar plantillas e ISO (Images), ofertas de servicio al crear planes personalizados | | Kubernetes | versiones compatibles, clústeres, configuración | proyectos, límites de recursos, redes, clústeres (módulo Kubernetes) | | Clave de solo lectura | hosts, clústeres, pools de almacenamiento, VM del sistema, capacidad, rangos de IP de VLAN | nada | ### CPU y RAM en tiempo real, y ancho de banda {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Una VM en ejecución solo se puede redimensionar sin reiniciar cuando su plantilla lo permite (escalable dinámicamente) y el sistema invitado activa las nuevas CPU y la nueva RAM. NexCMP activa Auto Scaling para plantillas cuyo nombre termina en `vN` con una N igual o superior a 6, o cuando se configura manualmente en el campo **vCPU/RAM hot-plug** de la plantilla. Consulte [Templates](https://nexcmp.com/es/docs/infrastructure/templates/). - **Bandwidth source.** Con la configuración predeterminada, NexCMP mide el tráfico a partir de las estadísticas de VM de CloudStack (`listVirtualMachinesUsageHistory`, consultadas cada 5 minutos y sumadas por interfaz de red de la VM). Las cifras incluyen el tráfico entre VM, por lo que pueden ser ligeramente superiores a las que contabilizaría un router perimetral. Mantenga habilitada la recopilación de estadísticas de VM de CloudStack; los intervalos superiores a la retención de estadísticas se omiten. Consulte [Bandwidth](https://nexcmp.com/es/docs/catalog/bandwidth/). ## Verificación {#verify} 1. **Test connection** devuelve "Write key: OK" con su zona y la versión de CloudStack. 2. **Infrastructure › Cloud provider › Providers** muestra el proveedor como activo con una hora de prueba reciente. El panel de estado del dashboard ya no muestra "CloudStack: not connected". 3. **Sales IP pools** enumera las direcciones libres (se actualiza aproximadamente una vez por minuto). 4. Solicite una VM pequeña desde el portal de clientes o la consola de administración y compruebe que pase a Running, tenga una IP pública y que pueda abrir la consola. ## Límites y notas {#limits-and-notes} - En esta versión de NexCMP se puede conectar un clúster de CloudStack. El cuadro de diálogo **Add cloud provider** puede probar las claves de un segundo clúster, pero no puede guardarlo. - Se vincula una zona de CloudStack a la zona predeterminada de NexCMP; un entorno de CloudStack con varias zonas se limita a la zona ingresada, por lo que se ignoran las VM, las IP y las redes de otras zonas. - Eliminar la red de invitados en CloudStack hace que falle cada nuevo despliegue. La consola de administración muestra un aviso en rojo cuando desaparece la red. - Las credenciales nunca salen del servidor. La API solo devuelve los últimos cuatro caracteres. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | API key o secret incorrectos, clave de otro usuario o un problema de reloj en el servidor del panel | Genere las claves de nuevo con `cmk generate userkeys` y pegue ambas. Compruebe la hora del servidor del panel. | | Prueba: `listZones: …` o tiempo de espera agotado | El servidor del panel no puede comunicarse con la URL de la API | Compruebe el DNS, el firewall y la ruta exacta de `/client/api`. | | Asistente: "network not found in that zone for this API key" | La red seleccionada pertenece a otra cuenta o zona | Cree la red en la cuenta dedicada (consulte más arriba) y ejecute **Test connection** de nuevo. | | Asistente: "pick a zone and a network" | No se ejecutó la prueba, o no se seleccionó ninguna zona ni red | Haga clic en **Test connection** y seleccione en ambas listas. | | Aviso "CloudStack key not configured" | Aún no se ha guardado ninguna clave ("Connect later") | Complete la tarjeta Connection, haga clic en **Save connection** y luego en **Test connection**. | | Banner "CloudStack connection is OFF" | El interruptor **Enable CloudStack connection** está desactivado | Actívelo y guarde los cambios. | | Clave de solo lectura: "unusable …" en la prueba | Falta de permisos de rol o cuenta incorrecta | Compruebe los seis comandos permitidos y que la cuenta pertenezca al dominio ROOT. | | "Zone public IP ranges not measured yet" o "no public IP ranges declared" | No hay clave de solo lectura o la zona realmente no tiene ningún rango público | Añada la clave de solo lectura o agregue un rango de IP públicas en CloudStack. | | "Pool vacío — espere 60 s para la sincronización de vmd" | El worker actualiza la lista de IP una vez por minuto | Espere un minuto y vuelva a cargar. | | "sin IP libres en el rango 203.0.113." | Todas las direcciones del prefijo comercializable están ocupadas | Añada direcciones a la zona, amplíe el prefijo o libere las IP no utilizadas. | | "Error al obtener los datos de la red (CloudStack no responde o la clave carece de permisos)" | La clave perdió el acceso o CloudStack no está disponible | Ejecute **Test connection**; compruebe que la cuenta esté habilitada. | | "La red de invitados NO existe" | La red se eliminó en CloudStack | Cree la red de nuevo y establézcala como predeterminada en Provisioning. | --- # Proxmox VE > **Ubicación en el panel de administración:** Infrastructure › Cloud provider › Providers (`/infra/providers`), luego la página del proveedor (`/infra/providers/`) con las pestañas Overview, Clusters, VMs, Servers y Credentials. Los planes se configuran en Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## Qué hace {#what-it-does} NexCMP puede vender máquinas virtuales que se ejecutan en uno o varios clústeres de Proxmox VE, junto a CloudStack o en su lugar. Una VM se crea clonando una plantilla de SO mediante full clone y luego se configura a través de cloud-init: tamaño, dirección IP de un pool que usted defina, contraseña de root y clave SSH. Los clientes obtienen control de energía, consola, snapshots, reinstalación, restablecimiento de contraseña y métricas en el portal. Nunca ven el nombre del clúster, del nodo ni del origen. Utilícelo si ya opera con Proxmox VE o para ofrecer un segundo pool de VM con precios diferenciados. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Proxmox VE | PVE 9.x. La integración se verificó en 9.2. Requiere el contenido de storage `import` y la opción de disco `import-from` (PVE 8.2 o posterior). | | Red desde el panel | HTTPS hacia la API del clúster, `https://:8006`. Sin ruta, nombre de usuario ni consulta. Tanto el panel como el worker se conectan; la consola del navegador se redirige a través del panel. | | Cuenta | Un usuario dedicado de PVE con un **token de API** y un rol personalizado con los privilegios indicados a continuación. Nunca utilice `root@pam`. | | Almacenamiento | Un storage para discos de VM compatible con clones (por ejemplo, `local-lvm`). Para el generador de plantillas integrado, el storage denominado `local` con los tipos de contenido `import` y `snippets`. | | Red | Un bridge de Linux (por ejemplo, `vmbr0`) con acceso a la red donde residen las IP de los clientes. Utilice un bridge con soporte para VLAN si introduce una etiqueta VLAN. | | IP | Un bloque IPv4 (/16 a /30) enrutado a dicho bridge, con puerta de enlace. NexCMP asigna las direcciones por sí mismo; Proxmox no dispone de gestión de IP. | | Plantillas | Una VM de plantilla cloud-init por cada SO, en cada nodo en el que realice despliegues, con el agente de invitado QEMU. | | Zona | Una zona existente a la que vincular el clúster. Consulte [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). | | Depende de | Ninguno. | ## Preparar la infraestructura {#prepare-the-infrastructure} Ejecute los comandos como root en cualquier nodo del clúster. ### 1) Crear un rol, usuario y token de API con privilegios mínimos {#_1-create-a-least-privilege-role-user-and-api-token} 1. Cree el rol. La lista de privilegios es exactamente la que utiliza NexCMP; no contiene nada que permita editar usuarios, definiciones de storage ni el 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` es necesario para la descarga de cloud-image. PVE 9 no dispone del privilegio `VM.Monitor`; no lo añada. 2. Cree el usuario y un token. `--privsep 1` significa que los permisos del token son la **intersección** de los permisos del usuario y los del propio token. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` El comando muestra el **secreto del token una sola vez** (un UUID). Cópielo ahora. El ID del token es `nexcmp@pve!api`. 3. Asigne el rol **tanto** al usuario como al token. Este es el paso que suele pasarse por alto: con la separación de privilegios, solo el token recibe errores 403 como `Datastore.Audit` si el usuario no tiene permisos. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. Pruébelo desde el servidor del panel: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` Un documento JSON con un `version` significa que el token funciona. (`-k` es solo para esta comprobación rápida; NexCMP fija el certificado por sí mismo, consulte más abajo). ### 2. Comprobar el bridge y el almacenamiento {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - Las VM de los clientes reciben interfaces de red `virtio` en el bridge que introduzca en NexCMP. Si configura una VLAN, el bridge debe ser VLAN-aware. - Ubique las VM de los clientes en un bridge o VLAN **independiente de la dirección de administración del nodo**. Si comparten red, el conjunto automático de IP de administración del firewall de Proxmox abre los puertos 22, 8006, 3128, 5900-5999 y 60000-60050 del nodo a cada VM de esa red. Si no puede separarlas, añada una regla DROP explícita para la subred de las VM hacia esos puertos por encima de la regla ACCEPT de administración. ### 3. Notas sobre el almacenamiento (LVM-thin) {#_3-storage-notes-lvm-thin} - Mantenga el **zeroing del thin-pool en su valor predeterminado**. Desactivarlo (`lvchange -Zn`) puede dejar datos antiguos en los bloques recién asignados y dañar las tablas de particiones o los sistemas de archivos de las VM clonadas. - Los discos que reportan "write cache: disabled" pueden clonar a solo unos pocos MB/s. Compruébelo con `hdparm -W /dev/sdX` y habilite la caché de escritura si el disco cuenta con protección contra pérdida de energía. ### 4. Habilitar el contenido `import` (solo para el generador de plantillas integrado) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} El generador integrado descarga la imagen cloud en el almacenamiento llamado `local` y crea la plantilla a partir de ella. Añada `import` (y `snippets`) a la lista de contenido de ese almacenamiento. Conserve los tipos que ya utiliza; `--content` reemplaza la lista completa: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### 5. Crear una plantilla de SO a partir de una imagen cloud {#_5-build-an-os-template-from-a-cloud-image} Una plantilla es una VM con cloud-init que NexCMP clona. Cada una se registra bajo una **OS key** corta como `ubuntu-24.04` con su ID de VM. Cree una plantilla por SO **en cada nodo que vaya a recibir VM**, ya que la clonación se ejecuta en el nodo elegido. **Opción A, recomendada: créela usted mismo.** Las imágenes cloud estándar de Ubuntu y Debian no contienen el guest agent y no permiten el inicio de sesión como root, y NexCMP establece la contraseña de root a través de cloud-init. Prepare la imagen primero: ```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' ``` A continuación, cree la VM de plantilla (el ID 9000 es un ejemplo; mantenga los ID de plantilla por debajo del valor de `vmid from`, por defecto 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 ``` **Opción B: el generador integrado.** La tarjeta **Create OS template from cloud image** en la pestaña Clusters (consulte más abajo) descarga una imagen qcow2, compila la plantilla y la registra. Crea la VM con cloud-init y el flag del guest agent, pero no modifica el contenido de la imagen. Utilícela solo con una imagen que ya permita el inicio de sesión de root y ejecute el guest agent, o cuando también proporcione un fragmento vendor-data de cloud-init. El guest agent es necesario para **Reset password** y para mostrar la dirección IP de la VM. ### 6. Conocer la huella digital del certificado (opcional) {#_6-know-the-certificate-fingerprint-optional} NexCMP confía en el clúster fijando la huella digital SHA-256 de su certificado TLS, por lo que un certificado autofirmado es válido. Para ver el valor que fijará NexCMP: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Infrastructure › Cloud provider › Providers** y haga clic en **Add cloud provider**. Elija **Proxmox VE** y complete: | Campo | Valor de ejemplo | |---|---| | Nombre | `Proxmox cluster 1` | | Endpoint | `https://192.0.2.10:8006` | | ID del token | `nexcmp@pve!api` | | Secreto del token | `XXXX` (el UUID mostrado en el paso 1) | | Slug | `pve-1` (a-z, 0-9, guion, 2-32 caracteres) | | Nodo predeterminado | `pve1` (vacío: el nodo online con más RAM libre) | | Almacenamiento | `local-lvm` | | Bridge | `vmbr0` | ![Cuadro de diálogo Add cloud provider con Proxmox VE seleccionado y valores de ejemplo para endpoint, token y storage](https://nexcmp.com/es/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. Haga clic en **Save & open provider** e introduzca un motivo si se le solicita. El token se cifra antes de almacenarse. 3. En la pestaña **Overview**, haga clic en **Test connection**. La primera prueba correcta **fija la huella digital TLS del clúster**; a partir de ese momento se rechazará cualquier certificado diferente. 4. Abra la pestaña **Clusters**. La tarjeta **Node · storage · bridge** muestra lo que detecta la API; la tarjeta **Cluster configuration** contiene los ajustes: | Campo | Significado | |---|---| | Nodo predeterminado | Nodo utilizado para las nuevas VM. Si está vacío, se utilizará el nodo online con más RAM libre. | | Storage, Bridge, VLAN | Almacenamiento en disco, bridge de la NIC y etiqueta VLAN opcional (0 significa ninguna). | | CPU type | `host` de forma predeterminada. Utilice `x86-64-v2-AES` cuando los nodos tengan diferentes generaciones de CPU. | | vmid from | Primer ID de VM asignado a las VM de clientes (por defecto 1000). | | Storage ISO, Storage backup | Déjelo vacío salvo que los utilice; si está vacío, las funciones de ISO y backup no se ofrecerán. | | Template OS | Uno por línea, `os-key=vmid`, por ejemplo `ubuntu-24.04=9000`. | | Pinned TLS fingerprint (SHA-256) | Se completa con la primera prueba. Bórrelo y vuelva a probar después de sustituir el certificado del clúster. | ![Pestaña Clusters, tarjeta Cluster configuration con lista de ejemplo de nodo, storage, bridge y plantillas de SO](https://nexcmp.com/es/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. Opcional: si utilizó la Opción B anterior, complete **Create OS template from cloud image** (clave de SO `ubuntu-24.04`, vmid `9000`, nodo `pve1`, la URL de la imagen qcow2) y haga clic en **Create template**. Se ejecuta en segundo plano durante unos minutos; el resultado se encuentra en el Audit log. ![Tarjeta Create OS template from cloud image con una URL de imagen de Ubuntu de ejemplo](https://nexcmp.com/es/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. Haga clic en **Add pool** dentro de **Cluster IP pool** y cree el pool del cual las VM obtendrán sus direcciones: | Campo | Valor de ejemplo | |---|---| | Nombre | `customers-1` | | CIDR | `198.51.100.0/24` | | Gateway | `198.51.100.1` (nunca se asigna a una VM) | | DNS | `1.1.1.1,8.8.8.8` (de 1 a 4 direcciones IPv4) | | Bridge, VLAN | `vmbr0`, `0` | | Already used IPs | una por línea, `ip note`, por ejemplo `198.51.100.10 monitoring` | NexCMP nunca asigna la dirección de red, la dirección de broadcast, la gateway ni una dirección reservada. Los pools del mismo clúster no pueden solaparse. Solo se puede eliminar un pool cuando ninguna de sus direcciones esté en uso. ![Cuadro de diálogo Add IP pool con un ejemplo de /24 y gateway](https://nexcmp.com/es/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. En **Attach cluster to zone**, elija la zona y, opcionalmente, un nombre de nodo, y luego haga clic en **Attach to zone**. El clúster se une a la zona que ya vende VM, por lo que una misma zona puede combinar CloudStack y Proxmox. El nuevo origen **no se vende por defecto** y no modifica el comportamiento de los planes existentes. ![Tarjeta Attach cluster to zone con una zona existente seleccionada](https://nexcmp.com/es/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. Abra **Services › Virtual Machines › Plans & pricing** y haga clic en **Add plan**. En **Infrastructure source**, elija el clúster de Proxmox y configure CPU, RAM, disco y precio. Un plan de Proxmox no requiere un offering de CloudStack. Para vender la misma configuración desde ambos orígenes, use **Clone** en un plan y elija el otro origen. El disco del plan debe ser al menos tan grande como el de la plantilla; Proxmox no puede reducir el tamaño de un disco. ### Importar una VM ya existente {#import-a-vm-that-already-exists} Abra la pestaña **Servers** para listar las VM del cluster. **Import** asigna una VM existente a la cuenta de un cliente sin costo: no se factura nada por horas, tiempo de apagado ni tráfico. El cliente puede iniciar, detener, reiniciar y abrir la consola, pero no puede eliminarla; solo un administrador puede hacerlo. NexCMP únicamente lee del cluster durante la importación. - El cluster debe estar asociado a una zona **con el nombre del nodo** de esa VM (si deja el nodo vacío, las importaciones informarán que la región no está configurada). - Para hacer que una VM esté **protegida** (se rechazan las acciones de detener, reiniciar, reinstalar, restaurar snapshot, destruir y cambiar de plan), impórtela desde la línea de comandos con `--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 ``` ### Qué es compatible y qué no en Proxmox {#what-is-and-is-not-supported-on-proxmox} | Característica | Proxmox VE | |---|---| | Crear, encender/apagar/reiniciar, eliminar | Sí | | Redimensionar CPU y RAM, ampliar el disco | Sí, pero la VM se detiene, se modifica y se inicia nuevamente (sin redimensionamiento en caliente) | | Snapshots | Sí, hasta 5 por VM: crear, listar, restaurar, eliminar | | Reinstalar | Sí: la VM se reconstruye a partir de la plantilla y conserva su ID, IP y configuración, con una nueva contraseña | | Restablecer contraseña | Sí, a través del guest agent | | Consola | Sí, una consola en el navegador con proxy a través del panel | | Métricas | Sí: CPU, memoria, red y disco | | Montaje de ISO, Backups, firewall, IPv6, reenvío de puertos, cambio de IP, volúmenes adicionales, Auto Scaling, DDoS Shield, VPC, medición de ancho de banda | No disponible. La página de la VM del cliente oculta lo que un origen no puede hacer. | ## Verificación {#verify} 1. **Test connection** muestra OK y el estado del proveedor es activo. 2. **Clusters** lista sus nodos como en línea, con el almacenamiento y el bridge. 3. **Cluster IP pool** muestra las cantidades libres, en uso y retenidas. 4. La clave de SO aparece bajo las plantillas de la zona en **Services › Virtual Machines › Template** tras asociar el cluster. 5. Solicite una VM de prueba a partir de un plan que utilice el cluster. Debería recibir una dirección del pool, una contraseña de root y una consola funcional; el pool mostrará una dirección utilizada. ## Límites y notas {#limits-and-notes} ::: tip Zonas de origen mixto Desde NexCMP 1.4.0, la lista pública de precios de Cloud Server también funciona cuando CloudStack y Proxmox VE comparten una zona. Cada plan utiliza su propio **Infrastructure source**. Tras vincular un clúster, revise la lista de precios pública y realice un pedido de prueba para cada origen. ::: - Se pueden añadir varios clusters de Proxmox. Cada uno es un proveedor. - Una zona ofrece un origen predeterminado; un plan con su propio **Infrastructure source** se despliega exactamente en ese cluster, siempre que el cluster esté activo y en la zona del plan. - Un cluster detrás de la misma zona que CloudStack mantiene sus planes heredados en CloudStack. Pruebe un pedido de extremo a extremo antes del lanzamiento. - El token de la API solo se puede reemplazar, nunca ver. Reemplácelo en la pestaña **Credentials**: cree primero el nuevo token en Proxmox, ingréselo, ejecute **Test connection** y luego revoque el token anterior. - Las acciones Test, Sync y cluster-info están limitadas a seis llamadas por minuto por administrador. - NexCMP factura a sus clientes; el costo de hardware y licencias del cluster corre por su cuenta. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Test: "Key rejected (wrong access key / secret, or revoked)" o HTTP 401/403 | ID de token o secret incorrectos, o la ACL se otorgó únicamente al token | Vuelva a ejecutar los dos comandos `pveum acl modify` (usuario **y** token) y verifique que el token id sea `user@realm!tokenid`. | | Test: "Could not connect to the provider" o "Timed out" | Firewall, host o puerto incorrectos | Verifique `https://host:8006` desde el servidor del panel. | | Prueba: "Endpoint no válido o no está en la lista de permitidos" | El endpoint tiene una ruta, usuario o consulta, o no es HTTPS | Utilice exactamente `https://host:8006`. | | "El certificado TLS del clúster NO coincide con la huella digital fijada" | Se reemplazó el certificado del clúster | Borre **Pinned TLS fingerprint** en la pestaña Clusters, guarde y vuelva a ejecutar **Test connection**. | | Slug rechazado | No contiene a-z, 0-9, guiones, o no tiene entre 2 y 32 caracteres | Utilice algo como `pve-1`. | | "Formato del ID de token: user@realm!tokenid y el secret es obligatorio" | Falta el token id o el secret | Introduzca ambos; el secret es el UUID que se mostró al crear el token. | | "Línea de plantilla no válida: …" | Una línea en **Template OS** no es `key=vmid` | Utilice letras, dígitos, `.`, `_`, `-` en la clave y un vmid de al menos 100. | | "Clave de SO: a-z 0-9 . _ - y vmid ≥ 100" | Clave o id no válidos en **Create template** | Corrija la clave de OS y use un vmid libre. | | "vmid … already exists" al crear una plantilla | El vmid ya está en uso | Elija otro id. | | "la URL apunta a una dirección interna" | La URL de la imagen es una IP interna | Utilice una URL pública; Proxmox se encarga de resolver los nombres. | | La tarea de plantilla falla durante la descarga | El almacenamiento `local` no admite contenido `import` | `pvesm set local --content …,import,snippets` y vuelva a intentarlo. El nombre de archivo debe terminar en `.qcow2`, `.raw`, `.vmdk`, `.ova` o `.ovf`. | | "cluster has no online nodes" o "node … is not online" | El nodo predeterminado está inactivo o mal escrito | Corrija **Default node** o déjelo en blanco. | | "la imagen no pertenece al clúster"" | El OS del plan no está en **Template OS** | Añada la clave a la lista y guarde. | | El despliegue espera y luego falla al clonar | La VM de plantilla no está en el nodo seleccionado | Cree la plantilla en ese nodo o configure **Default node** con el nodo que la contiene. | | El cliente no puede iniciar sesión como root | La imagen bloquea el inicio de sesión de root | Vuelva a generar la plantilla como en la Opción A. | | Restablecer contraseña no produce ningún efecto | No hay guest agent en el huésped | Instale y habilite `qemu-guest-agent` en la plantilla. | | "El nombre, el CIDR y la puerta de enlace son obligatorios" | Falta un campo del pool | Complete los tres. | | Creación del pool: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" o "cidr: network address must be …" | Pool superpuesto, gateway incorrecta o un CIDR que no está en el límite de la red | Utilice un rango libre, una gateway dentro de él y un CIDR expresado como la dirección de red (por ejemplo `198.51.100.0/24`). | | Importación: "region is not set up" | El clúster está vinculado sin el nombre de nodo de la VM | Vincule el clúster a la zona con el nombre de nodo. | --- # Plantillas de SO e ISO {#os-templates-and-isos} > **Ubicación en el panel de administración:** Services › Virtual Machines › Template (`/vm/templates`). Las plantillas de Proxmox se muestran por clúster en Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## Qué hace {#what-it-does} Una plantilla es la imagen del sistema operativo a partir de la cual se inicia una nueva VM. NexCMP no almacena imágenes por sí mismo: lee lo que CloudStack reporta (plantillas destacadas y listas) o lo que usted lista para un clúster de Proxmox, y le permite elegir cuáles se venden, con un nombre visible para el cliente, icono y usuario de inicio de sesión. Esta página muestra cómo preparar imágenes que funcionen de forma óptima con NexCMP: inicio de sesión con contraseña, escalado en caliente de CPU y RAM, archivo swap y un disco raíz que se expande al tamaño del plan. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Generador de plantillas de CloudStack | Una máquina Linux con `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` y unos 5 GB de disco libre. No se requiere KVM ni root. Acceso a Internet para la instalación de paquetes (o compilar con `--offline`). | | Ubicación del generador | Se incluye con cada versión en `/opt/nexcmp/releases//share/templates/` en el servidor del panel. No es necesario ejecutarlo allí: copie la carpeta a cualquier máquina Linux. | | Servidor web | Cualquier servidor HTTP(S) al que pueda acceder la VM de almacenamiento secundario de CloudStack, para publicar el archivo `.qcow2` terminado. No es necesario que sea accesible desde Internet. | | CloudStack | Una cuenta con permisos para registrar plantillas y el ID de su zona y de un tipo de SO coincidente. Consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/). | | Proxmox VE | VMs de plantilla con cloud-init y el agente invitado QEMU, una por SO y por nodo. Consulte [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). | | Depende de | Conectar primero [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). | ## Preparar la infraestructura {#prepare-the-infrastructure} ### CloudStack: crear una plantilla {#cloudstack-build-a-template} Imágenes base compatibles (la imagen del proveedor se descarga y su checksum se verifica antes de realizar cualquier cambio): | Imagen | `--distro` | Usuario de inicio de sesión | |---|---|---| | 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` | Más distribuciones: agregue una línea a `distros.conf` (URL de la imagen, archivo de checksum, familia `deb` o `rpm`). 1. Copie el generador a una máquina de compilación y ejecútelo: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` Agregue `--panel-url https://cloud.example.com` para integrar un agente de monitorización opcional de primer arranque que se registra en su panel (solo HTTPS). Sin él, no se agrega ningún agente. Otras opciones: `--base ` para usar una imagen descargada previamente, `--offline` para omitir la instalación de paquetes. 2. El resultado es `out/ubuntu-24.04-v7.qcow2` y su `.sha256`. La compilación finaliza ejecutando `verify-image.sh`, que inspecciona la imagen final en modo de solo lectura y rechaza una incorrecta (se conserva como `.unverified`). Puede ejecutarlo de nuevo en cualquier momento: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. Lo que el generador incluye en la imagen: | Elemento | Motivo | |---|---| | `qemu-guest-agent` | CloudStack puede consultar a la VM sobre CPU e IP, e inmovilizarla para Snapshots. | | cloud-init con el origen de datos de CloudStack, `set_passwords` en cada arranque, inicio de sesión por contraseña mediante SSH | La contraseña generada se obtiene del router virtual y **Reset password** funciona. | | Una regla de udev para CPU y RAM añadidas en caliente | Las vCPU y la RAM añadidas en caliente se activan automáticamente, por lo que el escalado en vivo y Auto Scaling funcionan. | | Un servicio de archivo swap | Crea `/swapfile` con el menor valor entre el 50% de la RAM y 4 GiB tras la ampliación del disco. `touch /etc/cmp-swap.disabled` lo desactiva. | | cloud-init `growpart` y `resizefs` | El disco raíz pequeño se expande al tamaño de disco del plan en el primer arranque. | | machine-id vacío, sin claves de host SSH | Cada VM obtiene su propia identidad. | ::: warning Nombre la plantilla ` ` NexCMP activa **Auto Scaling** para las plantillas cuyo nombre termina en `vN` o `vN.M` con **N de 6 o más** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). El generador exige esto para `--version`. Registre la plantilla exactamente con el nombre mostrado. ::: 3. Publique el archivo y regístrelo en CloudStack. Use el SHA-256 mostrado en la compilación y regístrelo solo después de que el archivo se haya escrito por completo: ```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 a CloudStack generar la contraseña de la VM. - `isdynamicallyscalable=true` permite el escalado en vivo. - `host-passthrough` es necesario para que arranquen las imágenes actuales de Rocky y Alma; `osdefault` mantiene la portabilidad del controlador de disco. 4. Espere a que la plantilla alcance **Download Complete / Ready**. La imagen del proveedor conserva su tamaño virtual reducido (alrededor de 3.5 GiB para Ubuntu y Debian, 10 GiB para Rocky). Recuerde que el disco de un plan no puede ser menor que el disco de la plantilla. ### Proxmox VE: crear una plantilla {#proxmox-ve-make-a-template} Cree una plantilla de VM con cloud-init por cada SO en cada nodo donde vaya a desplegar, con el guest agent instalado y el inicio de sesión como root habilitado, y regístrela luego como `os-key=vmid`. Los comandos completos están en [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). El generador de CloudStack anterior **no** es para Proxmox: configura cloud-init para el origen de datos de CloudStack. ### ISOs {#isos} Los clientes montan sus propias ISOs a través del módulo **Images** (CloudStack) o del módulo Dedicated Server. Estos son independientes de las plantillas de SO de esta página. Consulte [Módulos](https://nexcmp.com/es/docs/infrastructure/modules/) y [Servidores dedicados](https://nexcmp.com/es/docs/infrastructure/dedicated/). ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Services › Virtual Machines › Template**. Haga clic en **Sync now** o espere hasta 15 minutos. La sincronización añade las plantillas que estén listas y destacadas en CloudStack. ![La página Template con la lista de plantillas sincronizadas, su estado listo y la columna de hot-plug de CPU](https://nexcmp.com/es/docs/images/infrastructure/templates-01-list.webp) 2. Haga clic en **Edit** en una nueva plantilla y configure lo que ven los clientes: | Campo | Valor de ejemplo | |---|---| | Nombre visible para los clientes | `Ubuntu 24.04 LTS` | | Familia de SO | `ubuntu` (icono y usuario predeterminado) | | Versión | `24.04` | | Usuario de inicio de sesión | `ubuntu` (Windows: `Administrator`; otros: `root`) | | Icono | URL de la imagen, una ruta o un nombre | | Orden | `10` | | Activo | On | | Hot-plug de vCPU/RAM (escalado en vivo) | **Auto by name (v6 or later)**, **Yes** o **No (needs a restart)** | ![Cuadro de diálogo Edit template con un nombre visible para el cliente, la familia de SO, el usuario de inicio de sesión y la opción de hot-plug](https://nexcmp.com/es/docs/images/infrastructure/templates-02-edit.webp) 3. Active la plantilla. Las plantillas que CloudStack ya no incluya en la lista se ocultan automáticamente (y recibirá una alerta en Telegram si está configurado); nunca se eliminan de NexCMP. ### Reemplazar una plantilla por una compilación más reciente {#replace-a-template-with-a-newer-build} Utilice **More › Replace with new version** en la plantilla vendida. Seleccione la plantilla nueva, lista y actualmente deshabilitada. La entrada vendida apuntará entonces a la nueva compilación y conservará su nombre, orden e icono; la anterior se deshabilita como vía de retorno (para volver atrás, utilice **Replace** en la nueva entrada). Las VM en ejecución no se modifican. Si la nueva compilación pertenece a una familia de SO distinta, marque primero la confirmación. ## Verificación {#verify} 1. La fila muestra **ready** y, para compilaciones denominadas `vN` con N de 6 o más, **CPU hot-plug: supported**. 2. Despliegue una VM de prueba a partir de la plantilla y compruebe dentro de la VM: - puede iniciar sesión con la contraseña que se muestra en el portal; - `df -h /` muestra el tamaño de disco del plan; - tras un escalado en caliente (**Change plan** sin reinicio), `nproc` y `free -m` aumentan; - `swapon --show` lista `/swapfile` (los discos con menos espacio libre que la swap más 2 GiB lo omiten); - `systemctl is-active qemu-guest-agent` imprime `active`. 3. Si integró el agente en la imagen, la VM aparecerá en los hosts monitorizados del panel un minuto después del primer arranque. La VM necesita una IP pública propia: el panel la reconoce por su IP pública de origen. ## Límites y notas {#limits-and-notes} - El generador solo funciona en Linux y compila imágenes de Linux. Otras imágenes (por ejemplo, Windows) pueden registrarse en CloudStack por otros medios; NexCMP lista lo que CloudStack reporta. - Solo se incluye el agente para amd64; las demás arquitecturas omiten la instalación del agente. - La imagen se verifica con `guestfish`, pero el generador nunca la arranca. Despliegue siempre una VM de prueba antes de vender una nueva imagen. - Omita el agente en una VM con `touch /etc/cmp-agent.disabled` antes del primer arranque. Elimínelo más adelante con `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent` y luego borre el agente en la consola de administración. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `virt-customize` falla al descargar paquetes | La máquina de compilación no tiene red saliente | Corrija el DNS o el proxy en esa máquina, o compile con `--offline` en una imagen base que ya contenga los paquetes. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | El usuario actual no tiene permisos de lectura sobre el kernel del host (Ubuntu) | `sudo chmod +r /boot/vmlinuz*`, o ejecute la compilación como root. | | La suma de comprobación difiere o la imagen del proveedor ya no existe | Los proveedores mueven sus archivos "latest" | Descargue la imagen manualmente, verifíquela con el archivo de sumas de comprobación del proveedor y pásela con `--base`. | | Rocky: no se puede montar un XFS más reciente | El kernel del host es demasiado antiguo | Compile en una máquina con un kernel reciente. | | `--version must be v6 or higher` | El nombre debe ser `vN` con N de 6 o más | Utilice `--version v7`. | | `--panel-url must be a plain https:// URL` | El agente se descarga y ejecuta como root, por lo que se rechaza HTTP sin cifrar | Utilice una URL `https://` sin espacios, comillas ni cadenas de consulta. | | La plantilla permanece en **not ready** | CloudStack no ha finalizado la descarga | Espere a que aparezca **Download Complete** y compruebe que la VM de almacenamiento secundario pueda comunicarse con la URL. | | La fila muestra **no-pass** | La plantilla se registró sin `passwordenabled=true` | Regístrela de nuevo con ese flag. | | CPU hot-plug muestra **unsupported** | El nombre no termina en `vN` (N de 6 o más) | Cambie el nombre de la plantilla o establezca **vCPU/RAM hot-plug** en **Yes** en Edit si la imagen incluye la regla de udev. | | "Empty template list" tras la primera conexión | La sincronización no se ha ejecutado | Haga clic en **Sync now** (requiere que el worker esté en ejecución) o espere al ciclo de 15 minutos. | --- # Servidores dedicados (bare metal) {#dedicated-servers-bare-metal} > **Ubicación en el panel de administración:** Infrastructure › Bare Metal (Servers `/infra/baremetal`, IP Pools, Stock / iDRAC import, Operations, Templates, Customer ISOs, Safety). Planes y suscripciones: Services › Dedicated Server (`/dedicated`). Active el módulo en System › Admin › License & updates (`/license`). ## Qué hace {#what-it-does} NexCMP gestiona servidores físicos **directamente a través de su iDRAC**, mediante la API Redfish. Los clientes alquilan un servidor completo: lo encienden y apagan, abren una consola web, montan una ISO o instalan un sistema operativo desde una plantilla, y consultan el hardware y las métricas. Nunca ven la dirección, el usuario ni la contraseña de iDRAC. Utilícelo para revender servidores dedicados desde sus propios racks. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Hardware | Servidores Dell con **iDRAC 9** y la API Redfish. | | Red de gestión | **Usted lo proporciona.** El servidor del panel debe alcanzar cada iDRAC mediante **HTTPS 443** (y el puerto VNC de iDRAC, por defecto **5901**, para la consola), y cada iDRAC debe alcanzar el servidor web de ISO indicado abajo. La dirección de iDRAC debe ser una **dirección IPv4 en un rango privado** (RFC 1918, con un prefijo /16 o menor) que usted liste en el ajuste `dedicated_bmc_cidrs`. Se rechazan los nombres DNS y las direcciones IPv6. NexCMP no crea esta red ni puede probarla por usted. | | Cuenta de iDRAC | Una cuenta con privilegios de **Administrator** en cada iDRAC. NexCMP la utiliza para leer el servidor y enviar los pocos comandos que se permite a sí mismo (encendido, medios virtuales, arranque único, consola). Nunca crea cuentas de iDRAC para sus clientes. | | Herramientas en el servidor del panel | `xorriso` y `genisoimage` (construyen la ISO de instalación de cada servidor) y `novnc` (la página de la consola en el navegador). Instálelas con `sudo apt-get install -y xorriso genisoimage novnc`, o deje que el instalador lo haga: ejecútelo con `--baremetal` o indíquele las opciones del servidor ISO; una actualización también las instala cuando el módulo Bare Metal ya está activo. Si falta alguna, **Safety** la muestra en un aviso rojo, **live ops** rechaza activarse (error `tools_missing`), y la consola y la instalación del SO responden indicando que falta una herramienta en lugar de fallar más adelante. | | Servidor web de ISO | Un servidor **HTTP** básico en la red de gestión que sirva la carpeta de ISO de NexCMP a los iDRAC. Su dirección es una dirección IPv4 privada y un puerto opcional, por ejemplo `http://10.20.0.2:8080`, **sin ruta**, almacenada en `dedicated_iso_base_url`. Debe admitir rangos de bytes (byte ranges). El worker del panel escribe en la carpeta, por lo que el servidor web normalmente se ejecuta en el **propio servidor del panel**, escuchando en una dirección que dicho servidor tenga en la red de gestión. NexCMP incluye un sitio de nginx listo para usar y un comando de un solo paso para ello (ver más abajo). | | Carpetas de ISO | Una carpeta para archivos ISO y, en su interior, `pub` (lo que leen los iDRAC) e `server` (las ISO de los clientes). El comando de un solo paso utiliza `/srv/nexcmp-iso`; sin él, los valores predeterminados siguen la instalación (ajustes `dedicated_iso_lib_dir`, `dedicated_iso_pub_dir`, `dedicated_iso_server_dir`). El worker de NexCMP debe poder **escribir** en ellas. Se ejecuta con un sistema de archivos de solo lectura excepto `/var/lib/nexcmp`, por lo que una carpeta en otra ubicación requiere un drop-in de systemd (el comando de un solo paso lo instala). | | Dirección de callback | `dedicated_callback_base`, una `https://` a la que el servidor en instalación pueda acceder y que apunte a su panel. | | Almacenamiento | Espacio libre en disco para la biblioteca de ISO y para las ISO proporcionadas por los clientes. | | Depende de | El módulo **Bare Metal**, una zona y los grupos de IP de los servidores. | ::: warning Los valores de ejemplo no son una configuración Una instalación nueva incluye valores de ejemplo en `dedicated_bmc_cidrs`, `dedicated_iso_base_url` y `dedicated_callback_base` (una red de ejemplo privada y `https://example.com`). No corresponden a su red. Mientras cualquiera de ellos siga siendo un valor de ejemplo, las páginas de Bare Metal mostrarán un aviso rojo **Management network not configured**, la importación de un iDRAC fallará la comprobación de la lista de permitidos y el conmutador **live ops** rechazará activarse (error `config_placeholder`). Configure los tres valores en **Infrastructure › Bare Metal › Safety › Management network connection** (ver más abajo). ::: ## Preparar la infraestructura {#prepare-the-infrastructure} 1. **Ubique cada iDRAC en una red de gestión** a la que los clientes no tengan acceso y asígnele una dirección IPv4 privada fija. Compruebe la API Redfish desde el servidor del panel: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **Cree una cuenta de administrador en el iDRAC** para NexCMP (interfaz web de iDRAC o `racadm`). Utilice una contraseña segura y exclusiva. Nunca reutilice la cuenta integrada de iDRAC. 3. **Publicar la carpeta de ISO para los iDRAC: un solo comando.** En el servidor del panel, como root, con la dirección que dicho servidor tiene en la red de gestión y la red de iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` `--listen` debe ser una dirección de este servidor (IPv4 privada, puerto 8080 si se omite). `--allow` enumera la(s) red(es) de iDRAC (CIDR privados, /16 o menor, hasta 8, separados por comas); solo ellos pueden descargar, y el comando también los utiliza como `dedicated_bmc_cidrs` cuando ese ajuste aún contiene el valor de ejemplo. `--dir /path` selecciona otra carpeta de ISO (por defecto `/srv/nexcmp-iso`). El comando: - crea la carpeta con `pub` e `server` en su interior, pertenecientes al usuario del servicio de NexCMP; - crea el grupo `nexcmp-iso` y añade el usuario de nginx a él, para que nginx pueda leer una ISO mientras un iDRAC la tiene montada y nadie más pueda hacerlo; - instala el sitio de nginx `nexcmp-iso` (conservado solo si `nginx -t` lo acepta; nginx se instala si falta) y un drop-in de systemd `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` para la carpeta, `SupplementaryGroups=nexcmp-iso`); - escribe la configuración de ISO (`dedicated_iso_base_url`, las tres carpetas, el grupo) y reinicia el worker de NexCMP. Se puede ejecutar de nuevo con otros valores, y `sudo nexcmp dedicated-setup-iso --remove` retira el sitio de nginx y el drop-in (los archivos ISO se conservan). También se puede ejecutar durante la instalación: agregue `--iso-listen`, `--iso-allow` (y `--iso-dir`) al comando de instalación. El comando **no** crea la red de gestión y no se comunica con ningún iDRAC; si los valores son incorrectos, la dirección no pertenece a este servidor o el puerto está ocupado, se detiene con un mensaje antes de modificar nada, y un sitio de nginx que `nginx -t` rechace no se conservará. 4. **Qué sirve el servidor web de ISO.** El sitio de nginx responde a `GET` (y `HEAD`, con rangos de bytes) para `/pub/.iso` y nada más: sin listado de directorios, sin ninguna otra ruta bajo la carpeta (la biblioteca y `server/` no son accesibles), ningún otro método y solo desde las redes `--allow` (cualquier otro origen recibe un 403). NexCMP expone cada ISO que una iDRAC debe leer como un archivo o un enlace de corta duración en `pub`; nginx solo sigue un enlace cuando el enlace y su destino tienen el mismo propietario (el usuario del servicio), por lo que se rechaza cualquier enlace a un archivo del sistema. Compruébelo desde otro host en la red de administración: ```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 ``` Un archivo de prueba en `pub` debería responder a una solicitud `Range` con 206. *Si prefiere hacerlo manualmente:* el sitio de nginx y el drop-in se incluyen como plantillas en el paquete de la versión (`share/dedicated/nginx-iso.conf` y `share/dedicated/vmd-iso.conf` bajo `/opt/nexcmp/releases//`). Cópielos, reemplace los marcadores `__...__` (dirección de escucha, carpeta, líneas allow, grupo) y mantenga las reglas anteriores. 5. **Tenga listas las imágenes de SO.** Coloque las ISO de autoinstalación en la carpeta de biblioteca (consulte **Templates** más abajo). Los clientes también pueden añadir ISO desde un enlace; estas se descargan en el servidor y nunca se envían al iDRAC como URL. ## Conectar en NexCMP {#connect-in-nexcmp} ### 1. Activar el módulo {#_1-turn-the-module-on} En **System › Admin › License & updates**, active **Bare Metal**. La categoría **Bare Metal** aparecerá en Infrastructure. Consulte [Modules](https://nexcmp.com/es/docs/infrastructure/modules/). ### 2. Configurar la conexión de red de administración {#_2-set-the-management-network-connection} Abra **Infrastructure › Bare Metal › Safety**. La tarjeta **Management network connection** contiene los tres valores que determinan si algo puede funcionar: | Campo | Ajuste | Qué introducir | |---|---|---| | Red de iDRAC (CIDR) | `dedicated_bmc_cidrs` | La(s) red(es) privada(s) de sus iDRAC, por ejemplo `10.20.0.0/24`. Solo CIDR privados, /16 o menores, hasta 8, separados por comas. Solo se pueden importar las iDRAC dentro de estos rangos. | | Servidor ISO para las iDRAC | `dedicated_iso_base_url` | `http://[:port]`, sin ruta: la dirección del servidor web de ISO de la sección anterior, por ejemplo `http://10.20.0.2:8080`. El comando de un solo paso lo completa por usted. | | Dirección de callback del panel | `dedicated_callback_base` | `https://`, sin ruta: la dirección a la que llama el servidor en proceso de instalación para notificar la finalización. Debe ser accesible desde la red de dicho servidor. Se rechazan `example.com`, `localhost` y similares. | El formulario comprueba el formato a medida que escribe y el servidor lo vuelve a comprobar al guardar; se rechaza cualquier valor incorrecto indicando el motivo y el valor almacenado se mantiene como estaba. Un campo que aún contenga el valor de muestra incluido de fábrica muestra la etiqueta roja **Not configured**, y cada página de Bare Metal muestra el aviso rojo **Management network not configured** hasta que los tres sean reales. Los cambios se registran en el registro de auditoría con su motivo. Volver a guardar el valor de muestra no cuenta como configurarlo, a menos que lo haya escrito usted mismo. ### 3. Comprobar la barrera de seguridad (déjela cerrada por ahora) {#_3-check-the-safety-gate-leave-it-closed-for-now} Abra **Infrastructure › Bare Metal › Safety**. **Live ops** es el interruptor global para cada comando de escritura hacia una iDRAC (alimentación, medios virtuales, consola e instalación del SO). Comienza en **off** y no se puede activar mientras la conexión de red de administración anterior aún contenga valores de muestra (el interruptor responde `config_placeholder` e indica los campos). Las escrituras se rechazan en la API y nuevamente dentro del worker, mientras que la lectura de estado sigue funcionando. Un segundo bloqueo, **ops_locked**, protege cada servidor: los servidores recién importados siempre están bloqueados, incluso cuando live ops está activado. ![La página Safety con Live ops desactivado y la lista de acciones bloqueadas](https://nexcmp.com/es/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. Importar servidores {#_4-import-servers} 1. Abra **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. En **Add one server**, introduzca la dirección del iDRAC, la cuenta y la contraseña, y luego haga clic en **Test connection**. La prueba solo envía comandos de lectura y no guarda nada. | Campo | Valor de ejemplo | |---|---| | Dirección iDRAC (URL o host) | `10.20.0.11` | | Cuenta | `nexcmp-admin` | | Contraseña | `XXXX` | | Etiqueta | `rack1-01` (vacío: generado) | | Asignar una IP de un pool | opcional; elija el pool de IP de servicio del servidor | | Incluir en la lista de venta | desactivado hasta que esté listo | ![Stock e importación de iDRAC con una dirección de ejemplo y una prueba exitosa de solo lectura](https://nexcmp.com/es/docs/images/infrastructure/dedicated-02-import-server.webp) 3. Haga clic en **Save to stock**. NexCMP lee el modelo, CPU, RAM, discos, NIC y etiqueta de servicio (service tag) desde el iDRAC. El servidor entra al inventario **bloqueado**. 4. Para varios servidores, utilice **Bulk import**: un servidor por línea, campos separados por coma, punto y coma o Tab. **Preview** comprueba la lista de permitidos, duplicados de la dirección iDRAC o etiqueta de servicio, y lee el hardware (hasta cuatro servidores a la vez). ### 5. ISO de clientes y dirección web de ISO {#_5-customer-isos-and-the-iso-web-address} Abra **Infrastructure › Bare Metal › Customer ISOs**. - **HTTP address serving ISOs to iDRAC** es `dedicated_iso_base_url`, el mismo valor que en la tarjeta Safety (editable en cualquiera de los dos lugares). Introduzca la dirección en la red de administración de su servidor web de ISO. - **Customer ISO limits** define el tamaño de una ISO, el almacenamiento total de ISO, el espacio libre mínimo, el tiempo de retención de las ISO (horas), el tiempo máximo de descarga y el número de descargas simultáneas. ![Customer ISOs con la dirección HTTP para los iDRAC y los límites de ISO](https://nexcmp.com/es/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. Plantillas de SO {#_6-os-templates} Abra **Infrastructure › Bare Metal › Templates**. Muestra las ISO de autoinstalación encontradas en la carpeta de biblioteca. Haga clic en **Register** en un archivo para rellenar la familia de SO, versión y cuenta (rellenados previamente a partir del nombre del archivo), y luego cambie la plantilla a **Enable**. Habilitar una plantilla no inicia nada: cada instalación sigue pasando por la compuerta de seguridad. **Unregister** solo elimina la fila de la plantilla, nunca el archivo. ![Bare Metal Templates con una ISO registrada y una sin registrar](https://nexcmp.com/es/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. Pools de IP {#_7-ip-pools} Abra **Infrastructure › Bare Metal › IP Pools** y añada los rangos IPv4 que los servidores reciben como direcciones de servicio. Cada servidor obtiene una dirección; **Assign an IP from a pool** en la importación toma la siguiente libre. Las direcciones libres se contabilizan por pool. ![Bare Metal IP Pools con rangos de ejemplo y recuentos de direcciones libres](https://nexcmp.com/es/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. Planes y venta {#_8-plans-and-sale} 1. Abra **Services › Dedicated Server › Plans & pricing**. Edite los cuatro planes de muestra (denominados `BM-40C-` en 1.6.1) o cree los suyos propios: precio, ciclos y la tarifa de configuración. **En una instalación nueva, los precios se introducen en dólares estadounidenses, al centavo, y se cobra exactamente eso al monedero: no se necesita tipo de cambio.** Una instalación que ya tenía planes con precios en dong vietnamita conserva el dong y aún necesita un tipo de cambio en su configuración (sin él, los pedidos se rechazan con `dedicated_fx_unavailable`). Los planes de muestra comienzan con un precio de 0 y **disabled**: un plan a la venta necesita un precio superior a 0. Compare cada plan con el hardware que realmente importa; el nombre de un plan de muestra no detecta ni modifica el hardware de un servidor. 2. Abra el servidor (Infrastructure › Bare Metal › the server › **Sales**), **asocie el plan** y active **Sellable**. 3. Active **live ops** (página Safety, con la confirmación escrita) y desbloquee los servidores que desee operar (pestaña **Lock** del servidor, indicando un motivo que se registrará en el registro de auditoría). 4. En **Services › Dedicated Server**, active las ventas. Esto requiere dos pasos: leer las consecuencias y luego escribir `ENABLE SALES`. Hasta entonces, los clientes no verán la página de pedidos ni se les cobrará. ![Planes de Dedicated Server con el interruptor de ventas desactivado](https://nexcmp.com/es/docs/images/infrastructure/dedicated-06-plans.webp) ### Qué pueden hacer los clientes en la página de su servidor {#what-customers-can-do-on-their-server-page} La página del servidor de un cliente tiene dieciséis pestañas en siete grupos (Overview, Control, Network, Hardware, Billing, Activity, Settings). El grupo **Billing** contiene: - **Plan & renewal**: pague de 1 a 24 meses por adelantado en un solo paso; la nueva fecha se calcula a partir de la fecha de renovación actual y se cobra del monedero una sola vez. La renovación automática se puede activar o desactivar. - **Billing cycle**: elija otro ciclo (por ejemplo, trimestral); se aplicará a partir de la **siguiente** renovación y no se cobrará ni reembolsará nada en este momento. - **Change plan**: el cliente puede **solicitar** otro plan. La solicitud no genera ningún cobro. Usted la aprueba o rechaza en **Services › Dedicated Server › Plan changes**, después de haber actualizado el hardware o trasladado el servidor. Una actualización aprobada cobra la diferencia correspondiente al resto del periodo ya pagado por el cliente; una reducción de plan no reembolsa nada y se aplica a partir del siguiente periodo. - **Invoices**: todas las facturas de ese servidor (pedido, renovaciones, ampliaciones). En **Plan changes**, ordene las solicitudes por ID, fecha, estado, planes o servidor; la ordenación abarca todo el resultado en el servidor. La columna de acciones permanece visible al desplazarse horizontalmente en una pantalla estrecha. En la parte superior de **Overview**, cuatro mosaicos en tiempo real muestran **CPU**, **RAM**, **Disco** y **Network**, con un gráfico pequeño de las últimas 24 horas. CPU, RAM y Disco son porcentajes de uso del último sondeo de iDRAC (Disco es actividad de E/S, no espacio libre); Network es la velocidad entrante y saliente actual más el total del mes, obtenidos del contador de tráfico. Un mosaico muestra **—** y un motivo breve cuando el servidor está apagado, no se puede acceder a iDRAC o la máquina no reporta ese valor; nunca muestra un 0 inventado. Estas lecturas provienen de Dell iDRAC y, sin un contador de tráfico, el mosaico Network permanece en **—**. Los mosaicos se actualizan cada minuto mientras la página esté abierta, y al hacer clic se abre la pestaña **Hardware** o **Bandwidth**. En **Overview**, la tarjeta **Access** muestra el nombre de usuario y la contraseña del sistema operativo que instaló, ocultos de forma predeterminada con los botones **Show** y **Copy**. Está disponible tras cada instalación, no solo una vez, y un nuevo propietario del servidor nunca ve la contraseña de un propietario anterior. Si se cambia la contraseña del SO dentro del servidor, la tarjeta seguirá mostrando la establecida durante la instalación. La pestaña **Bandwidth** solo aparece cuando un contador de tráfico le suministra datos (consulte Límites). No hay pestaña **Subnet**: traer su propio prefijo IP a un servidor alquilado no forma parte de NexCMP. ### Qué pueden y qué no pueden hacer los clientes {#what-customers-can-and-cannot-do} | Los clientes pueden | Nunca es posible | |---|---| | Ver el inventario, el estado de salud, el estado de energía y las métricas | Ver la dirección, el nombre de usuario o la contraseña de iDRAC | | Encender, apagado ordenado, reiniciar, forzar apagado, resetear | Modificar cuentas de iDRAC o la configuración de red de iDRAC | | Abrir una consola en el navegador (una sola sesión a la vez) | Modificar la BIOS o RAID, borrar registros, actualizar firmware, reiniciar la iDRAC | | Montar una ISO o un enlace a una ISO propia, configurar el arranque único, reinstalar el SO desde una plantilla habilitada | Ejecutar llamadas Redfish directas (las funciones no existen en NexCMP) | NexCMP no crea cuentas de iDRAC para los clientes: únicamente utilizan los controles del portal, y la dirección y los datos de acceso de iDRAC nunca se les muestran. ## Verificación {#verify} 0. En **Safety**, la tarjeta **Management network connection** no muestra ninguna etiqueta roja y las páginas de Bare Metal no muestran ningún aviso rojo. Desde un host en la red de gestión, `curl -I http:///` no lista archivos. 1. **Test connection** en el formulario de importación devuelve el modelo, la CPU, la RAM y el service tag. 2. El servidor aparece en **Servers** con su hardware. Con **live ops off**, cualquier acción de energía se rechaza con "Server control is temporarily disabled system-wide". 3. Tras activar live ops y desbloquear un servidor de prueba, apague y encienda el servidor desde **Operations** o la página del servidor, y abra la consola. 4. Realice un pedido de prueba con un plan de prueba: se asigna el servidor, se instala el SO y la instalación finaliza cuando el servidor reporta al panel. ## Límites y notas {#limits-and-notes} - Cada servidor físico tiene como máximo una suscripción activa. - Solo se envía un comando de escritura cuando **tanto** live ops está activo **como** el bloqueo del servidor está abierto. La comprobación se repite dentro del worker inmediatamente antes de cada comando. - El estado **Installing** espera a que el nuevo SO responda en su puerto (SSH 22, Windows 3389, Proxmox 8006) antes de que se complete el pedido; una instalación tiene un límite de tiempo (`dedicated_install_timeout_min`, por defecto 150 minutos). - El ancho de banda de los servidores dedicados se contabiliza mediante un agente contador de tráfico que no forma parte de la instalación estándar. Sin él no se registra nada, el portal oculta la pestaña Bandwidth y la API reporta `capabilities.bandwidth` como `false`. - Las acciones de administración sobre un alquiler (bloquear, desbloquear, cancelar con o sin reembolso) son las mismas acciones unificadas que para cualquier otro servicio, y los reembolsos se devuelven al saldo desde el que se pagaron. - Los servidores no se revenden entre revendedores: Dedicated se vende únicamente desde el sitio principal. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | La prueba falla con un error de dirección | La dirección no es un literal IPv4 en `dedicated_bmc_cidrs` (privada, /16 o menor) o el puerto no está permitido | Utilice la dirección IPv4 del iDRAC y agregue su red en Safety › Management network connection (`dedicated_bmc_cidrs`). No se admiten nombres DNS ni IPv6. | | Aviso rojo "Management network not configured", o el conmutador de operaciones en vivo responde `config_placeholder` | Uno de `dedicated_bmc_cidrs`, `dedicated_iso_base_url`, `dedicated_callback_base` aún conserva el valor de ejemplo predeterminado | Introduzca los valores reales en Safety › Management network connection. | | Se rechaza un campo al guardar | Formato incorrecto (CIDR no privado o más amplio que /16, dirección de ISO no `http://[:port]`, callback no `https://`), o una dirección de ejemplo como `example.com` | Lea el mensaje debajo del campo; el valor guardado permanece sin cambios. | | `nexcmp dedicated-setup-iso` se detiene antes de cambiar nada | `--listen` no es una dirección de este servidor, el puerto ya está en uso o un valor no es válido | Utilice la dirección que tiene este servidor en la red de gestión, otro puerto o corrija el valor indicado en el mensaje. | | "El certificado TLS de iDRAC difiere del fijado - las acciones de sondeo y escritura se han detenido" | Se reemplazó el certificado de la iDRAC (nuevo certificado, reemplazo de iDRAC) | Abra el servidor, pestaña **Access**, compare las dos huellas digitales y, si el cambio es intencionado, haga clic en **Repin certificate**. | | "El control del servidor está temporalmente desactivado en todo el sistema" | Live ops está desactivado | Actívelo en **Safety**. | | "Este servidor está bloqueado para operaciones" | El bloqueo individual del servidor está activado | Abra el bloqueo en la pestaña **Lock** del servidor indicando un motivo. | | "Otra operación todavía se está ejecutando en este servidor" | Una operación anterior no ha finalizado | Espere; revise **Operations**. | | "Ya hay otra sesión de consola abierta en este servidor" | Solo una consola a la vez | Cierre la otra sesión. | | "El controlador del servidor no está disponible temporalmente" | El iDRAC no responde | Compruebe la red de gestión y el iDRAC. | | El montaje de una ISO falla con un 403 o 404 desde el iDRAC | El servidor web no puede leer el archivo o la dirección base es incorrecta | Compruebe los permisos del servidor web de ISO y **HTTP address serving ISOs to iDRAC**. | | "Este plan está agotado en la ubicación seleccionada" | No hay ningún servidor vendible con ese plan en la zona | Asigne el plan a un servidor y active **Sellable**. | | "No hay direcciones IPv4 disponibles para asignar en este momento" | El pool de IP está vacío | Añada direcciones al pool. | | "La instalación automática del SO no está disponible en este momento" | Faltan requisitos previos de instalación | Compruebe que haya una plantilla habilitada y que las carpetas de ISO tengan permisos de escritura; los clientes aún pueden instalar mediante ISO y consola. | | La instalación se detiene | El servidor en instalación no puede acceder a la dirección de callback | Compruebe `dedicated_callback_base` y que la red del servidor pueda acceder a su panel mediante HTTPS. | --- # Nodos VPN y proxy IPv6 {#vpn-and-ipv6-proxy-nodes} > **Dónde encontrarlo en el panel de administración:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`), VPN IP pools (`/vpn/pool`), IPv6 Proxy nodes (`/vpn/proxy6/nodes`). Los servicios en sí están en Services › VPN y Services › IPv6 Proxy. Ambos módulos se activan en System › Admin › License & updates. ## Qué hace {#what-it-does} NexCMP vende acceso VPN y proxy con salida desde **direcciones IP de su propiedad**, en servidores que usted opera. Existen dos tipos de nodos: - **Nodo VPN.** Un pequeño programa en Go, `cmp-agent`, se ejecuta en su host Linux. Detecta las direcciones IPv4 públicas del host, abre un listener SOCKS5, HTTP y UDP en cada dirección vendida, y envía el tráfico de salida desde la **misma IP** a la que se conectó el cliente (salida desde la misma IP). Envía reportes al panel cada pocos segundos. - **Nodo proxy IPv6.** Un servicio proxy que proporciona a los clientes direcciones de un prefijo IPv6 que usted enruta hacia el host. El panel lo instala por usted a través de SSH. Utilícelos para revender direcciones IP limpias en los países donde tenga servidores. ## Requisitos {#requirements} ### Nodo VPN {#vpn-node} | Elemento | Requisito | |---|---| | Sistema operativo | Una distribución Linux con systemd y un kernel 4.15 o superior (soporte para free-bind en IPv6). El binario del agente incluido es solo para **x86_64** (amd64). | | Privilegios | root, para la instalación. El servicio solo conserva `CAP_NET_ADMIN`, `CAP_NET_RAW` y `CAP_DAC_READ_SEARCH`. | | Herramientas | `curl` o `wget`, y `sha256sum` (el instalador se niega a continuar sin verificar el archivo). | | Direcciones públicas | Direcciones IPv4 públicas asignadas en una interfaz del host (un `/32` cada una), **o** un prefijo enrutado hacia el host que usted añada como subred adicional (IPv4 /16 a /32, IPv6 /48 a /128). Se ignoran los rangos privados, CGNAT y de documentación. | | Red, entrante | Los clientes se conectan a cada IP pública vendida en los **puertos 65001-65535** (TCP para SOCKS5 y HTTP, UDP para UDP associate). Cada endpoint utiliza un conjunto de tres puertos consecutivos. | | Red, saliente | HTTPS (443) hacia el dominio de su panel. El agente también consulta su propio país en `ip-api.com` (HTTP) y `ipinfo.io` (HTTPS), con un límite de 3.5 segundos. | | Correo | Las conexiones salientes al puerto 25 siempre están bloqueadas; no existe ningún ajuste para abrirlo. | | Docker, VPN e interfaces virtuales | Las interfaces llamadas `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*` y `tailscale*` no aportan direcciones. | | Depende de | El módulo **VPN**, una zona (creada automáticamente a partir del país del host) y el panel de NexCMP accesible a través de HTTPS. | ### Nodo proxy IPv6 {#ipv6-proxy-node} | Elemento | Requisito | |---|---| | Sistema operativo | Linux con systemd en **x86_64**. Los comandos `systemctl`, `nft`, `ip`, `ss`, `sysctl` y `useradd` deben existir; de lo contrario, la instalación se detiene e indica el comando faltante. | | Acceso para la instalación | Una dirección IPv4 pública (se rechazan las direcciones privadas, loopback y CGNAT), el puerto SSH, una cuenta con privilegios de root o `sudo` y su **contraseña**. La contraseña se utiliza únicamente para la instalación y no se almacena. | | Puertos libres | **80, 443 y cada puerto superior a 60000** deben estar libres. El instalador nunca detiene ni modifica servicios que ya se encuentren en ejecución; informa los puertos ocupados y se detiene. | | IPv6 | Un prefijo público entre **/32 y /64** dentro de `2000::/3` que el host pueda utilizar como origen para el tráfico saliente, entregado ya sea **enrutado** hacia el host o bien **on-link** con proxy NDP (véase más abajo). | | Red | Los clientes se conectan a la IPv4 del nodo en el puerto 80 (proxy HTTP), en el puerto 443 (SOCKS5) y en los puertos 60001-65535 (un puerto por IP estática). El nodo no tiene certificado, por lo que no hay proxy HTTPS. El tráfico sale únicamente por IPv6 y solo hacia destinos que cuenten con una dirección IPv6. El nodo obtiene su configuración desde el panel mediante HTTPS. | | Software de nodo en el servidor del panel | El daemon del nodo y su script de red se incluyen en el paquete de versiones de NexCMP. El panel los copia desde su carpeta de instalación (`/opt/nexcmp/releases//bin` o `/opt/nexcmp/bin` en una compilación personalizada) a cada nodo durante la instalación. El servidor del panel también necesita `sshpass` y un cliente SSH; el instalador añade `sshpass`, y en un servidor instalado antes de 1.4.2 se añade con `sudo apt-get install -y sshpass`. | | Depende de | El módulo **IPv6 Proxy** y la URL del panel a la que responden los nodos (**IPv6 Proxy › Settings › Panel URL for nodes**, valor predeterminado `https://`). | ## Preparar la infraestructura {#prepare-the-infrastructure} ### Nodo VPN {#vpn-node-1} 1. **Aprovisione el host** con un Linux compatible y las direcciones IPv4 públicas que desee vender, ya sea configuradas en la interfaz de red o enrutadas hacia el host. 2. **Si vende un bloque enrutado**, prevea ingresarlo como **Extra subnet** al añadir el nodo. El agente instala una ruta `local dev lo` para que el host acepte tráfico para cada dirección del bloque y luego reporta las direcciones que encuentra. El agente también lee la tabla de enrutamiento real del host y nunca vende ni captura una dirección de **puerta de enlace**: si el bloque contiene el siguiente salto de una de las rutas del host (por ejemplo, la dirección del router de un bloque on-link), el agente instala rutas `local` únicamente para las partes del bloque a su alrededor, reporta la puerta de enlace al panel y el panel mantiene esa dirección fuera del pool y de cualquier asignación. Elimina las rutas instaladas cuando la subred adicional cambia o el agente se detiene. 3. **Abra el firewall.** Permita TCP y UDP entrantes en **65001-65535** en las direcciones públicas y HTTPS saliente hacia el panel. 4. **Opcional: contadores de bytes por IP.** El registro de conntrack (`net.netfilter.nf_conntrack_acct = 1`) permite que el rol de monitoreo cuente bytes por IP. El panel puede activarlo enviando al agente un comando `acct`, lo que también escribe `/etc/sysctl.d/99-cmp-agent.conf`. El rol de VPN en sí no lo necesita. 5. **Verifique el panel desde el nodo:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### Nodo proxy IPv6 {#ipv6-proxy-node-1} Un prefijo IPv6 llega al nodo de una de dos formas. El instalador prueba ambas con conexiones salientes reales y conserva la que funciona. | Tipo | Qué significa | Qué configura | |---|---|---| | **Enrutado** | Su proveedor de tránsito enruta un prefijo (por ejemplo, un /48 o /56) **hacia la propia dirección del nodo**. Los paquetes salientes pueden utilizar cualquier dirección del prefijo como origen y las respuestas regresan al nodo. | Solicite a su proveedor un prefijo enrutado cuyo siguiente salto sea el nodo. Nada más en el nodo: el servicio de proxy utiliza sockets transparentes, una tabla fija de enrutamiento por políticas y `nft`. | | **On-link** | El /64 se encuentra en la misma LAN que el nodo. Las respuestas solo funcionan si el nodo responde al descubrimiento de vecinos para cada dirección en uso (**NDP proxy**). | El servicio configura, únicamente en esa interfaz, `net.ipv6.conf..accept_ra=2`, `forwarding=1` y `proxy_ndp=1`, recuerda los valores anteriores, los restaura cuando se detiene y bloquea el reenvío de las direcciones del pool para que el nodo no se convierta en un router para el pool. | Cómo funciona la comprobación: el nodo intenta una conexión TCP a una dirección IPv6 pública (puerto 443) desde una dirección aleatoria del prefijo candidato, en un plazo de 6 segundos. Los candidatos son direcciones globales en interfaces con un prefijo de /64 o más corto, además de rutas de tipo `local`, `unreachable` o `blackhole` entre /16 y /64. Un prefijo más corto que /64 se acepta como **routed** si un /64 aleatorio dentro de él funciona. ::: warning No utilice el mismo prefijo dos veces Un prefijo no puede superponerse con el prefijo de otro nodo ni puede ser más amplio que un prefijo que ya pertenezca al pool de IPv6 del propio panel. Se permite un /64 **dentro** del pool del panel. Las superposiciones se notifican como "assign range … (node …)" en el resultado de la instalación y el prefijo se omite. ::: Restricciones que aplica el propio nodo: los clientes no pueden enviar correo (puertos 25, 465, 587, 2525) desde las direcciones del pool, y el tráfico IPv4 propio del demonio se limita a respuestas y a la comunicación con el panel y DNS. ## Conectar en NexCMP {#connect-in-nexcmp} ### Nodo VPN {#vpn-node-2} 1. En **System › Admin › License & updates**, active **VPN**. Consulte [Modules](https://nexcmp.com/es/docs/infrastructure/modules/). ![Tarjeta Module con los interruptores de VPN e IPv6 Proxy](https://nexcmp.com/es/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. Abra **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. Dispone de dos formas de añadir un nodo. **a. Instalación mediante SSH.** Haga clic en **+ Add server (SSH)** y complete: | Campo | Valor de ejemplo | |---|---| | Dirección IPv4 del servidor | `192.0.2.50` | | Puerto SSH | `22` | | Usuario SSH | `root` | | Contraseña SSH | `XXXX` | | Nombre para mostrar | `node-ny-1` (vacío: nombrado según la IP) | | Rol del servidor | External VPN / Proxy Node | | Asignación de zona | Auto by GeoIP (create / assign Zone), o una zona existente | | Subred adicional (opcional) | vacío para escanear automáticamente las interfaces, o un bloque enrutado como `203.0.113.0/24` | | Habilitar para la venta tras la instalación | activado para marcar cada dirección detectada como disponible para la venta | Haga clic en **Connect & install**. El panel se conecta mediante SSH, ejecuta el instalador de una sola línea en el nodo con un ticket de un solo uso y muestra el nombre del nodo, la ubicación de GeoIP y los rangos detectados. ![Cuadro de diálogo Add Node via SSH con una dirección de servidor y un rol de ejemplo](https://nexcmp.com/es/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **b. Instalación manual.** Haga clic en **Generate manual install token**. El comando aparece **una sola vez**; cópielo y ejecútelo en el nodo: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` La instalación mediante token registra la máquina únicamente para monitorización: por seguridad, el panel no permite que una máquina que posee el token compartido se asigne a sí misma el rol de VPN (añadir `--roles vpn` al comando no tiene efecto). Cuando la máquina aparezca en la lista, ábrala y agregue usted mismo el rol **VPN**. Instalar mediante SSH (opción a) asigna al nodo el rol de VPN desde el principio. Un nuevo token anula el anterior; los hosts que ya se hayan registrado seguirán funcionando porque utilizan su propia clave. ![Cuadro de diálogo del comando de instalación que muestra el comando con el token de un solo uso](https://nexcmp.com/es/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) Qué hace el instalador: descarga `cmp-agent-linux-amd64` desde su panel, **verifica su SHA-256**, lo instala en `/usr/local/bin/cmp-agent`, se registra con el token, escribe `/etc/cmp-agent/agent.json` e inicia el servicio systemd `cmp-agent`. Para eliminarlo: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. Tras el primer heartbeat, el nodo aparece en la lista. Su país se detecta mediante GeoIP (primero la propia consulta del nodo, luego la base de datos del panel); se crea una **zona** para ese país y se hace pública si no existe ninguna, y las direcciones encontradas en el host se convierten en rangos del pool. 4. Abra **Infrastructure › VPN & Proxy nodes › VPN IP pools** para ver los rangos, su zona y su nodo, y para cambiar la zona, el nodo o el interruptor **Sellable** de cada rango. **Enable range** permite que los nuevos pedidos usen sus IP libres; **Disable range** solo detiene nuevas asignaciones, las IP alquiladas siguen funcionando. ![Pools de IP de VPN con rangos notificados por un nodo](https://nexcmp.com/es/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. Abra **Services › VPN**, configure la lista de precios y active las ventas. El interruptor **Sell VPN** en **Subscriptions** es el mismo interruptor que el módulo VPN en License & updates. 6. **Opcional: cambiar el nombre del servicio.** En **Settings › Branding**, **VPN service display name** cambia la forma en que se denomina el servicio VPN en el menú del cliente, la página de pedidos, la página de detalles y la lista de despliegue (por ejemplo `IPv4 Proxy`, `Datacenter Proxy` o `Static Residential Proxy`; hasta 40 caracteres; si se deja vacío, conserva `VPN`). Solo cambia las etiquetas: las rutas, los datos y la API no se modifican. ### Nodo proxy IPv6 {#ipv6-proxy-node-2} 1. En **System › Admin › License & updates**, active **IPv6 Proxy**. 2. Abra **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** y haga clic en **Add node (SSH)**. Introduzca la dirección IPv4 del nodo, el puerto SSH, el usuario, la contraseña, un nombre opcional y un **Reason** (se envía al registro de auditoría), luego haga clic en **Install**. ![Cuadro de diálogo Add IPv6 node con una dirección y un motivo de ejemplo](https://nexcmp.com/es/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. A continuación, el panel realiza en orden lo siguiente: comprueba la máquina y los puertos, copia el demonio, el script de red, la unidad de servicio y un archivo de entorno específico del nodo (un token de nodo y una clave para firmar contraseñas), ejecuta la **probe** de prefijos utilizables, registra los prefijos en el pool, inicia el servicio y espera hasta 90 segundos el primer informe. **Install log** muestra cada paso. 4. Un nuevo nodo crea su zona en estado **off** (a partir del GeoIP de la IPv4 del nodo). Active la zona en **Infrastructure › Datacenter › Zone** para que los clientes puedan elegirla. 5. Establezca un **Mbps cap** total por nodo (de 10 a 100000 por dirección). En **Services › IPv6 Proxy**, configure la lista de precios y active las ventas. 6. Compruebe **IPv6 Proxy › Settings › Panel URL for nodes**. Los nodos llaman a esta dirección (`https://host`, sin ruta) para obtener su configuración y enviar reportes. Dejarlo vacío significa `https://`. Debe ser un host cuya dirección apunte directamente al panel, de modo que la propia IPv4 del nodo llegue a él sin modificaciones. ::: tip Programación de rotación Los clientes pueden configurar un intervalo de rotación automática de 30 a 600 segundos. En NexCMP el panel ejecuta dicha programación (así como la limpieza por horas de los registros de conexión); los nodos adoptan una nueva dirección en unos 5 segundos. ::: ### Cómo reporta un nodo {#how-a-node-reports} | | Nodo VPN (`cmp-agent`) | Nodo proxy IPv6 | |---|---|---| | Inscripción | Ticket o token de un solo uso mediante HTTPS, luego su propia clave | Instalación única por SSH, luego un token de nodo | | Heartbeat | Cada **5 segundos** (10 s para un agente solo de monitorización); el panel puede configurar de 3 a 300 s. Tras un fallo, aumenta la espera en pasos de 5 s hasta 60 s | El nodo envía un reporte aproximadamente cada 60 segundos y obtiene la configuración | | Se muestra como online | Un heartbeat en los últimos **60 segundos** | **alive** en los últimos **120 segundos**; de lo contrario, **missed heartbeat** | | Cambio de configuración | Se aplica en el siguiente heartbeat | Se aplica en aproximadamente 5 segundos | | Actualizaciones | El panel puede enviar un comando `upgrade` con la nueva versión, URL y SHA-256 | Reinstalar desde la fila del nodo | ### Cuota de datos en un nodo VPN {#data-allowance-on-a-vpn-node} A partir de NexCMP **1.5.1**, el agente del nodo VPN envía el tráfico cursado con cada heartbeat, y el panel lo suma al consumo del plan para el período actual. La misma cifra se muestra al cliente (pestañas Overview y Bandwidth) y a usted (VPN › Subscriptions, columna Used y la fila del nodo). - **Corte de servicio.** Cuando un plan ha consumido sus GB correspondientes al período, el panel deja de enviar los endpoints de dicho plan al agente, por lo que se rechazan las conexiones nuevas y se cierran las abiertas. La interrupción se produce en el transcurso de un heartbeat, por lo que un plan puede sobrepasar ligeramente su límite. Los planes con nivel Unlimited nunca se cortan. - **Reanudación.** El servicio del plan se restablece en el transcurso de un heartbeat después de que el cliente adquiera más ancho de banda o cuando comience el siguiente período. - **Not measured.** Un nodo cuyo agente no ha enviado datos de uso (por ejemplo, un agente más antiguo) se muestra como **Not measured** y sus planes nunca se interrumpen por GB. - **Actualice el agente.** Utilice el agente **1.5.1** en los nodos. Los agentes más antiguos aún se contabilizan, pero pueden perder los bytes de un heartbeat fallido, de un endpoint detenido o de un reinicio, y no cierran las conexiones abiertas cuando se corta un plan. Actualice desde la fila del nodo (Reinstall) o con el comando `upgrade`. - El conteo se realiza sobre la carga útil que pasa a través del proxy, por lo que es ligeramente inferior (alrededor del 1 %) a los bytes transmitidos por la red. ### Complementos de VPN retirados {#retired-vpn-add-ons} High IP Reputation, High Concurrency y High Priority Network ya no se ofrecen en nuevos pedidos. Las suscripciones existentes conservan sus selecciones de complementos, pero a sus importes de renovación se les eliminan las tarifas retiradas. No hay reembolsos por periodos ya pagados. El ajuste utiliza el precio de catálogo actual del complemento; si modificó ese precio o eliminó el complemento, revise el importe de renovación de la suscripción antes de su próxima renovación. ## Verificación {#verify} 1. La fila del nodo está online. Para un nodo VPN, **Agents & external nodes** muestra su zona, país, rol y los rangos detectados. 2. **VPN IP pools** lista los rangos con IP libres; la página de detalles de la zona muestra la infraestructura de VPN. 3. Solicite un plan de VPN o proxy de prueba. El cliente obtiene un endpoint `ip:port`, un nombre de usuario y una contraseña; conéctese a través de él y compruebe que la IP pública visible sea la IP del nodo (por ejemplo, `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. En un nodo IPv6, ejecute en el host: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## Límites y notas {#limits-and-notes} - Los hosts con Windows pueden ejecutar el agente de monitorización, pero no el rol de VPN. - Límite de datos (GB por período) de un plan VPN: a partir de NexCMP 1.5.1, el panel suma el tráfico reportado por el agente del nodo VPN y corta los proxies del plan cuando se agotan los GB del período (consulte "Data allowance on a VPN node" más abajo). Los planes IPv6 Proxy no tienen límite de GB; limitan la velocidad en Mbps por plan. - Las direcciones IPv4 de un plan VPN no rotan. Un cliente reporta una IP en lista negra; usted o el revendedor aprueban un reemplazo de la misma zona. Solo IPv6 Proxy rota. - Se notifican como máximo 64 rangos por heartbeat. - Un conjunto de endpoints VPN utiliza tres puertos por IP vendida. Con los puertos 65001-65535 cada IP sirve a un número limitado de endpoints (178 conjuntos de puertos); el panel omite los conjuntos que ya se hayan utilizado. - Solo se permite eliminar un nodo proxy IPv6 cuando ningún plan tiene una IP en él. Esto elimina los rangos y el token del nodo; el software en el host no se desinstala. - Revender un rango que también aloja sus propias VM es posible: la VPN solo utiliza los puertos 65001-65535, por lo que comparte la IP con otros servicios. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "error de registro (token no válido o servidor inaccesible)" | Token incorrecto o ya utilizado, o el panel es inaccesible | Genere un nuevo token o reintente la instalación por SSH. | | "la firma del archivo no coincide - STOP" | El agente descargado difiere del SHA-256 publicado | Compruebe la carpeta `/dl/` del panel y que nada modifique la descarga en tránsito. | | "este instalador es solo para Linux" / "la arquitectura … aún no es compatible" | Windows, o una arquitectura distinta de x86_64 (la versión incluye el agente solo para x86_64) | Utilice un host Linux x86_64. | | El nodo nunca aparece | El nodo no puede comunicarse con el panel mediante HTTPS | Pruebe `curl https:///install.sh` desde el nodo; compruebe el DNS y el firewall. | | El nodo aparece con el país incorrecto | Las búsquedas de país fallaron, por lo que se utilizó la base de datos de direcciones del panel | Permita el acceso saliente a `ip-api.com` y `ipinfo.io`, o seleccione la zona explícitamente en el formulario SSH. | | No se detectaron rangos | No hay IPv4 pública en una interfaz no virtual | Añada una dirección pública o introduzca el bloque enrutado como **Extra subnet**. | | La VPN funciona, pero el tráfico sale por otra IP | La IP vendida no está asignada ni enrutada al host | Asegúrese de que la IP esté en una interfaz o cubierta por `local … dev lo`. | | "el servidor del panel no tiene sshpass" | El host del panel no puede iniciar sesión en los nodos con contraseña | Ejecute `sudo apt-get install -y sshpass openssh-client` en el servidor del panel y luego instale el nodo de nuevo. | | "not found in the installed package" al instalar un nodo IPv6 | El panel es anterior a 1.4.2 o es una compilación personalizada sin los archivos de nodo | Actualice NexCMP a 1.4.2 o posterior; para una compilación personalizada utilice `build.sh`, que ahora empaqueta `brandy-proxy6d` y `brandy-proxy6-net`. | | "SSH: …" al inicio de una instalación IPv6, o "SSH to internal/loopback addresses is not allowed" | Puerto, usuario o contraseña incorrectos, SSH bloqueado o la dirección es privada | Utilice la IPv4 pública del nodo y compruebe el acceso manualmente con `ssh -p PORT USER@IP`. | | "arquitectura … no compatible (solo x86_64)" | El nodo no es x86_64 | Utilice un host x86_64. | | "falta el comando en el nodo: …" | `nft`, `ip`, `ss`, `sysctl`, `systemctl` o `useradd` no están instalados | Instale los paquetes y ejecute de nuevo la instalación. | | "puertos en uso por otro servicio en el nodo: … — 80, 443, 60001-65535 deben estar libres" | El puerto 80, 443 o un puerto superior a 60000 está ocupado | Mueva el otro servicio; el instalador no lo detiene. | | "no se encontró ningún prefijo IPv6 con acceso a Internet desde el nodo (falló la prueba de salida real)" | No hay prefijo enrutado, proxy NDP no disponible o no hay IPv6 saliente | Compruebe que el prefijo esté enrutado al nodo, que la interfaz tenga conectividad IPv6 y que nada filtre el tráfico saliente. | | "todos los rangos detectados ya pertenecen a otro nodo" | El prefijo ya está en uso por otro nodo | Elimínelo del otro nodo o elija otro prefijo. | | La instalación finaliza con "no initial report received from node" | El servicio se inició pero no se comunicó con el panel en 90 segundos | Compruebe la URL del panel asignada a los nodos y la ruta HTTPS del nodo hacia ella; consulte **Install log**. | | La fila del nodo muestra **missed heartbeat** | Sin reportes durante 120 segundos | Compruebe el servicio en el nodo, su reloj y la ruta hacia el panel. | | Los clientes no ven ninguna ubicación IPv6 | La zona está desactivada | Active la zona en **Zone**. | --- # AI Models {#ai-models} > **Dónde está en el panel de administración:** System › Admin › License & updates (`/license`) para activar el módulo. Luego Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) y Audit (`/ai/audit`). Los clientes usan AI › API en el portal del cliente. ## Qué hace {#what-it-does} AI Models es una pasarela y capa de facturación en su propio panel. Sus clientes obtienen claves API y llaman a **un único endpoint en su dominio**, en formato compatible con OpenAI o Anthropic. Usted elige qué modelos ofrecer y el coste de cada uno por cada 1 millón de tokens. NexCMP verifica la clave, los límites y el monedero, envía la solicitud al proveedor que haya añadido, mide los tokens y cobra al monedero prepagado del cliente. **Usted aporta las fuentes de modelos.** NexCMP se entrega sin proveedores, sin modelos, sin direcciones predeterminadas y sin precios. No suministra modelos, claves API, tokens ni cuentas de proveedores. ::: warning Revise primero los términos de sus fuentes Muchas fuentes de modelos restringen la reventa o la cesión de acceso a terceros. Utilice únicamente fuentes que esté autorizado a usar y revender, y cumpla con sus términos y con la legislación aplicable. Esta página no constituye asesoramiento legal. ::: AI Models es un producto independiente de **AI Chat and AI Agent** (módulo **AI**, consulte [proveedores de IA](https://nexcmp.com/es/docs/ai/ai-providers/)). Los dos módulos no dependen el uno del otro. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Módulo | **AI Models** activado en License & updates, Modules. Está desactivado por defecto. | | Proveedores | Una o más fuentes de modelos que esté autorizado a revender, cada una con una API compatible con OpenAI (`/chat/completions`), una API compatible con Anthropic (`/messages`) o ambas. Cada una requiere una URL base y una clave de API. | | Red | El panel debe comunicarse con cada proveedor mediante **HTTPS en el puerto 443** con un nombre de dominio público. Cualquier proveedor en un host interno, otro puerto o HTTP sin cifrar debe estar listado en **Allowed internal hosts** (ajuste `ai_endpoint_allow`). | | Clientes | Una cuenta de cliente con una dirección de correo electrónico verificada y saldo en el monedero. | | Hardware | Ninguno. NexCMP solo reenvía solicitudes: sin GPU ni archivos de modelos. | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Obtenga una clave API de cada fuente de modelos que vaya a utilizar y anote su URL base (por ejemplo, `https://api.example.com/v1`). 2. Revise los términos de la fuente con respecto a la reventa. 3. Si una fuente se ejecuta dentro de su red, defina su dirección, por ejemplo `http://10.0.0.5:8000/v1`. Indicará `10.0.0.5:8000` en **Allowed internal hosts**. ## Conectar en NexCMP {#connect-in-nexcmp} ### 1. Activar el módulo {#_1-turn-the-module-on} Abra **System › Admin › License & updates**, busque la tarjeta **Module** y active **AI Models**. El menú se recarga y aparece **Services › AI Models**. Mientras el módulo esté desactivado, las páginas de clientes, las de administración y la pasarela responderán `404 module_disabled`, y no se contactará a ningún proveedor. ![La tarjeta Module con el interruptor AI Models activado](https://nexcmp.com/es/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. Añadir un proveedor {#_2-add-a-provider} 1. Abra **AI Models › Providers** y seleccione **Add provider**. 2. Introduzca un **slug** corto, un **nombre** (solo visible para usted), el **tipo** (OpenAI-compatible, Anthropic-compatible o Both), la **URL base** y la **API key**, así como una **prioridad** (los números más bajos se prueban primero). 3. Guarde. La clave se almacena cifrada y después solo se muestran sus últimos cuatro caracteres. Solo se puede introducir una clave desde una sesión de administrador iniciada. Utilice **Both** únicamente para una pasarela que realmente admita ambos formatos. NexCMP **no** traduce entre los dos formatos: a un modelo servido por un proveedor OpenAI-compatible se accede en `/ai/v1/chat/completions`, y a uno servido por un proveedor Anthropic-compatible en `/ai/v1/messages`. ![La página Providers que lista tres proveedores de muestra con tipo, prioridad y estado](https://nexcmp.com/es/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. Probar la conexión {#_3-test-the-connection} Seleccione **Test connection** en el proveedor. NexCMP lee `GET /models` con la clave e informa de **ok**, o bien del motivo del fallo: **auth** (clave incorrecta), **blocked**, **billing** o **unreachable**. Las pruebas están limitadas a 6 por minuto. ### 4. Sincronizar los modelos {#_4-sync-the-models} Seleccione **Sync models**. NexCMP lee la lista de modelos del proveedor y añade cada modelo nuevo **desactivado y sin precio**. Si el proveedor ya no lista un modelo, este se marcará. Mientras el módulo esté activo, la lista también se sincroniza automáticamente cada 6 horas (ajuste `ai_models_sync_hours`). ### 5. Establecer precios y activar los modelos {#_5-set-prices-and-switch-models-on} 1. Abra **AI Models › Models**. 2. Para cada modelo que desee vender, establezca el **precio de venta** en dólares estadounidenses por cada 1 millón de tokens: **input**, **cached input** y **output**. 3. Opcionalmente, introduzca su **coste** para el modelo. A continuación, **Profit** muestra los ingresos frente al coste por día y por modelo, y se rechazará cualquier precio de venta inferior a su coste más el margen mínimo (ajuste `ai_min_margin_pct`, 10 por defecto), a menos que confirme una pérdida deliberada. **Set price from cost** aplica el margen comercial que usted elija; no hay un margen por defecto. 4. Active el modelo. No es posible activar un modelo que no tenga precio de venta. Si el precio de cached input se deja en cero, se cobrará al precio de input. ![La página Models con los precios de venta de input, cached input y output, y los interruptores de activación](https://nexcmp.com/es/docs/images/infrastructure/ai-models-03-models.webp) ### 6. Rutas y conmutación por error {#_6-routes-and-failover} En un modelo, **Routes** lista los proveedores que le dan servicio, por orden. Añada un segundo proveedor de respaldo, configure el orden y, opcionalmente, asigne un nombre de modelo diferente para cada proveedor (el nombre enviado al proveedor puede diferir del que usted publica). Cuando un proveedor devuelve un error de servidor, de autorización o de facturación, un modelo no encontrado o un límite de tasa, NexCMP prueba la siguiente ruta. Si una lectura agota el tiempo de espera después de haber enviado la solicitud, **no** se envía a otro proveedor para que no pague dos veces. Cada proveedor está limitado a `ai_provider_rpm` solicitudes por minuto (50 por defecto). Si un proveedor sigue devolviendo errores de autorización o facturación, NexCMP alertará al administrador por Telegram cuando Telegram esté configurado. ### 7. Activar el interruptor de venta {#_7-open-the-sale-switch} En la parte superior de las páginas de AI Models, el **interruptor de venta** (ajuste `feature_ai_models`) está desactivado por defecto. Mientras esté desactivado, los clientes verán que el servicio aún no está abierto y la lista pública de precios informará de que no está disponible. Compruebe que al menos un modelo esté activado, tenga un precio de venta y una ruta con clave, y luego actívelo. ### Qué pueden hacer los clientes {#what-customers-can-do} En el portal del cliente, **AI › API**: - **Models** muestra sus modelos y precios, la URL base y comandos de ejemplo listos para usar. - **API Keys**: cree, renombre, rote, deshabilite y elimine claves. El secreto se muestra una sola vez; solo se almacena un hash. Por clave: modelos permitidos, caducidad, un presupuesto flexible (advierte) y un presupuesto estricto (bloquea con `402`), solicitudes por minuto y tokens por minuto. - **Usage** por modelo, clave y día, con exportación. - **Logs**: registros de solicitudes filtrables (hora, clave, modelo, tokens, coste, estado, latencia). **Los prompts y las respuestas no se registran.** Los registros se conservan 90 días por defecto (`ai_log_retention_days`). - **Settings**: presupuesto de la cuenta y dirección de correo para las alertas de presupuesto. - **Playground**: chatee con un modelo, compare modelos en paralelo y copie el código correspondiente. ![Página API Keys del cliente con las URL base para ambos formatos de API](https://nexcmp.com/es/docs/images/infrastructure/ai-models-04-keys.webp) Endpoints de gateway en su dominio: ```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 ``` ### Monedero y facturación {#wallet-and-billing} El uso de IA se descuenta del mismo monedero prepago que los demás servicios. Antes de enviar una solicitud al proveedor, NexCMP reserva los fondos correspondientes al coste máximo estimado; si el saldo es inferior al mínimo (`ai_min_balance_cents`, 20 centavos por defecto) o resulta insuficiente, la solicitud se rechaza con `402 insufficient_balance` y **no se realiza ninguna llamada al proveedor**. El uso se recopila por cuenta y se liquida en movimientos del monedero cada hora, con un barrido cada 5 minutos; el consumo aún no liquidado ya se deduce del saldo visible para la pasarela. Los resellers pueden comercializar AI Models en su propio dominio: su margen o descuento se aplica sobre su precio de venta y a su monedero mayorista se le cobra el precio mayorista. Un interruptor de IA por reseller, activado por defecto, determina quién puede venderlo. ## Verificación {#verify} 1. Tras el paso 3, **Test connection** muestra **ok** y el número de modelos. 2. Tras el paso 4, los nuevos modelos aparecen listados, desactivados y sin precio. 3. Como cliente con saldo en el monedero, cree una clave y llame al 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"}]}' ``` Una respuesta `200` incluye la contestación del modelo. **Usage** refleja la solicitud, y **Profit** la muestra si introdujo un coste. 4. Con el monedero a cero, la misma llamada devuelve `402 insufficient_balance`. ## Límites y notas {#limits-and-notes} - El módulo no incluye proveedores, modelos ni tarifas predefinidas, y nunca consulta listas de precios del proveedor. - Las herramientas que se ejecutan en el proveedor y se cobran por llamada, como la búsqueda web, se rechazan al no poder medirse su consumo. Solo se reenvía una lista reducida de parámetros de solicitud. - El consumo de tokens se obtiene de la respuesta del proveedor; si esta no lo incluye, NexCMP realiza una estimación y marca el registro como estimado. - Los errores del proveedor se depuran antes de llegar al cliente (se eliminan nombres, hosts, direcciones y el identificador de modelo del proveedor). Los clientes nunca ven qué proveedor atendió la solicitud. - Los clientes acceden al gateway a través del dominio de su panel, por lo que el certificado TLS de dicho dominio debe ser válido. - NexCMP no ofrece acuerdos de nivel de servicio (SLA), fine-tuning ni alojamiento de GPU para este módulo. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa y solución | |---|---| | Todas las páginas de AI Models y el gateway responden con `404 module_disabled` | El módulo está desactivado. Active **AI Models** en License & updates, Modules. | | Error al añadir un proveedor: `endpoint_host_not_allowed`, `endpoint_must_be_https` o `invalid_endpoint_port` | La URL base debe usar HTTPS en el puerto 443 con un nombre de dominio público. Para un host interno, otro puerto o HTTP estándar, incluya `host:port` en **Allowed internal hosts**. | | `blocked_endpoint` | La dirección es una IP o el nombre resuelve a una dirección privada. Inclúyala en **Allowed internal hosts** si ese es el comportamiento deseado. | | **Test connection** devuelve `auth` | La clave es incorrecta o carece de permisos. Vuelva a introducirla. | | No se puede activar un modelo (`no_price`) | Defina primero un precio de venta. | | Los clientes reciben `503 ai_unavailable` | El interruptor de venta está desactivado o el interruptor de IA del reseller está apagado. | | Los clientes reciben `503 upstream_unavailable` | Ninguna ruta habilitada con clave admite ese modelo en el formato solicitado. Revise las rutas del modelo y el tipo de proveedor. | | Los clientes reciben `402 insufficient_balance` | El saldo del monedero está por debajo del mínimo o no cubre la solicitud. Solicite al cliente que realice una recarga. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **En el panel de administración:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). Cuentas: Services › Object Storage › S3 accounts (`/s3`). Precios: Services › Object Storage › PAYG pricing (`/s3/policy`). Active el módulo en System › Admin › License & updates. ## Qué hace {#what-it-does} Los clientes crean cuentas S3 desde el portal y obtienen claves de acceso. NexCMP crea y elimina los usuarios correspondientes en **su Ceph RADOS Gateway (RGW)** mediante la RGW Admin Ops API, lee el uso para la facturación y factura según el modelo de pago por uso: el almacenamiento que supere el nivel gratuito por GB al mes (cobrado por horas) y el tráfico de descarga por GB. Las subidas son gratuitas. Utilícelo si gestiona un clúster Ceph con RGW y desea revender Object Storage. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Ceph | Un clúster con al menos un demonio RGW y la **Admin Ops API** habilitada (el valor predeterminado `rgw_enable_apis` incluye `admin`). | | Usuario administrador | Un usuario RGW para NexCMP con las capacidades que se indican a continuación. No utilice un usuario que contenga datos de clientes. | | Endpoints | El endpoint S3 que utilizan los clientes y el endpoint Admin Ops. Ambos se introducen como `https://host` **sin ruta, solo en el puerto 443**, y deben resolver a una dirección **pública**: se rechazan las direcciones loopback, link-local, multicast, privadas y unique-local. | | Certificado | Un certificado válido para el host del endpoint. | | Registro de uso | Registro de uso de RGW habilitado (`rgw_enable_usage_log = true`) para que la API de uso pueda reportar el tráfico. | | Zona | Una zona maestra con el servicio **Object Storage (S3)** marcado. Consulte [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). | | Almacenamiento | Capacidad en Ceph para las cuotas que comercialice. | | Depende de | El módulo **Object Storage**. El tráfico de descarga también cuenta para [Bandwidth](https://nexcmp.com/es/docs/catalog/bandwidth/). | ## Preparar la infraestructura {#prepare-the-infrastructure} En un nodo de administración de Ceph: 1. Cree el usuario administrador y asígnele las capacidades de Admin Ops que necesita: ```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` y `secret_key` del resultado. Corresponden a **Admin access key** y **Admin secret key** en NexCMP. 2. Active el registro de uso y reinicie los gateways: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. Configure los gateways tras HTTPS en el puerto 443 (un proxy inverso o el propio TLS de RGW), publique el nombre DNS y realice una prueba desde el servidor del panel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` Debería recibir una respuesta XML de S3 (HTTP 200 o 403), no un tiempo de espera agotado. ## Conectar en NexCMP {#connect-in-nexcmp} 1. **Asigne el servicio S3 a una zona.** Abra **Infrastructure › Datacenter › Zone**, edite la zona y marque **Object Storage (S3)**. Solo las zonas maestras con el servicio S3 aparecen en el formulario del backend. 2. Abra **Infrastructure › Cloud provider › Ceph S3 (RGW)** y haga clic en **Add backend**: | Campo | Valor de ejemplo | |---|---| | Nombre del backend | `Ceph RGW 1` | | Zona | la zona del paso 1 | | Endpoint de RGW Admin Ops | `https://s3.example.com` | | Endpoint S3 del cliente | `https://s3.example.com` | | Región de firma S3 | `default` | | Clave de acceso de administrador | `XXXX` | | Clave secreta de administrador | `XXXX` | | Activo | activado | | Enable sales (requiere probar la conexión primero) | **desactivado** por ahora | | Motivo del cambio | `initial setup` | ![Diálogo de backend S3 con endpoints de ejemplo, región y claves enmascaradas](https://nexcmp.com/es/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. Haga clic en **OK** (guardar) y luego en **Check** en la fila. NexCMP llama a la Admin Ops API con la clave de administrador. **Ceph connection successful** y la etiqueta **Verified** indican que funciona. 4. Haga clic en **Edit**, active **Enable sales** y guarde. NexCMP no permitirá abrir las ventas hasta que una comprobación se haya completado con éxito. 5. Abra **Services › Object Storage › PAYG pricing** y establezca los precios: | Campo | Significado | |---|---| | Almacenamiento por encima del nivel gratuito (VND/GB/mes) | Precio del almacenamiento; se factura por hora como el precio mensual dividido entre 730. | | Descarga (VND/GB) | Precio del tráfico saliente. | | Subida (VND/GB) | Siempre 0. | | Nivel gratuito con Running VM (GB) | Fijado en 100 GB por cuenta mientras el cliente tenga al menos una VM en ejecución, compartido entre sus cuentas de S3 por tamaño. | | Límite de deuda (VND) | Cuánto uso impago está permitido. | | Umbral de facturación (VND) | El uso se acumula en una sola factura una vez que supera este importe. | | Saldo mínimo para crear S3 (VND) | Saldo en el monedero necesario para crear una cuenta. | | Máximo de cuentas S3 por cliente, cuota técnica predeterminada (GB) | Límites para nuevas cuentas. | ![Formulario de precios PAYG de S3](https://nexcmp.com/es/docs/images/infrastructure/s3-04-pricing.webp) Los precios de S3 se introducen en VND. Se convierten para su visualización y para los cargos al monedero al tipo de cambio vigente; consulte [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). ## Verificación {#verify} 1. **Check** devuelve "Ceph connection successful". 2. Como cliente (o con una cuenta de prueba), cree una cuenta de S3. En Ceph, `radosgw-admin user list` muestra un nuevo usuario y **S3 accounts** la enumera. 3. Cree un bucket con cualquier cliente de S3 utilizando las claves del cliente con el endpoint de cliente. Suba un archivo. 4. Tras el siguiente ciclo de facturación por hora, **S3 accounts** muestra el uso. ## Límites y notas {#limits-and-notes} - Un backend que ya tiene cuentas asociadas conserva su **zona, endpoint y región**; para cambiarlos, cree un nuevo backend. - Una zona puede tener su propio backend; las cuentas y los backends quedan vinculados a una zona de forma definitiva. - El nivel gratuito y «las subidas son gratuitas» son reglas fijas, no opciones. - Las claves se almacenan cifradas; la consola solo muestra el campo «leave blank to keep the current key». Los pares de claves siempre se introducen juntos. - Las claves secretas de los clientes se muestran una sola vez al crearse, nunca más. Si se pierde una clave, se reemplaza rotándola. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Endpoint requires HTTPS" | El endpoint utiliza HTTP sin cifrar | Publique HTTPS en el puerto 443. | | "Puerto de endpoint no permitido" | Un puerto distinto del 443 | Utilice el puerto HTTPS estándar. | | "Dirección del endpoint no permitida" | El nombre se resuelve en una dirección privada, loopback, link-local o unique-local | Utilice una dirección pública. | | "El endpoint solo debe contener el protocolo y el host" | La URL contiene una ruta, consulta o información de usuario | Utilice únicamente `https://host`. | | "Error al resolver el endpoint" | El DNS no resuelve desde el servidor del panel | Corrija el DNS. | | "Error al conectar con Ceph" | Error de firewall o TLS | Pruebe con `curl` desde el servidor del panel. | | "Ceph devolvió HTTP 403 AccessDenied" | Claves incorrectas o falta de capabilities | Compruebe las claves y vuelva a ejecutar `radosgw-admin caps add`. | | "Respuesta de Ceph no válida" | El endpoint no es una API de Admin Ops de RGW | Apúntelo al RGW, no a una página web. | | "La prueba de conexión debe completarse con éxito antes de habilitar las ventas" | Activó las ventas antes de un **Check** exitoso | Ejecute **Check** y luego habilite las ventas. | | "Se requieren todas las claves nuevas para el endpoint" | Se cambió el endpoint sin proporcionar ambas claves | Introduzca la clave de acceso y la clave secreta juntas. | | "El backend ya tiene recursos asociados; cree un nuevo backend para cambiar la zona o el endpoint" | Existen cuentas en este backend | Cree un nuevo backend. | | "Seleccione la zona maestra con servicio S3" | La zona no es una zona maestra o no tiene el servicio S3 | Marque **Object Storage (S3)** en la zona. | | "Región no válida" | La región contiene caracteres distintos de letras, dígitos, `-` y `_` | Utilice `default` o el nombre de su zonegroup de RGW. | | "Falta el resumen de uso de Ceph; no facturado" | Registro de uso deshabilitado | Habilite `rgw_enable_usage_log`. | --- # Kubernetes y Private Cloud {#kubernetes-and-private-cloud} > **En el panel de administración:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`), luego Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). Active ambos módulos en System › Admin › License & updates. ## Qué hace {#what-it-does} - **Kubernetes.** Los clientes crean clústeres gestionados de Kubernetes en su CloudStack con CloudStack Kubernetes Service (CKS). El plano de control es gratuito; los clientes pagan por los nodos **worker**. NexCMP crea una red y una IP pública independientes para cada clúster y mantiene separados los clústeres de cada cliente. - **Private Cloud.** Los clientes obtienen una red privada (una VPC de CloudStack) con un router, subredes (tiers), reglas de firewall (network ACLs) y máquinas virtuales en su interior. Se comercializa por **plan de ancho de banda** con velocidad dedicada e ilimitada (por ejemplo 50, 100, 500 Mbps, 1 y 3 Gbps). Cada cliente puede tener una VPC de forma predeterminada. Ambos se basan en [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) y utilizan su API a través de la misma conexión. ## Requisitos {#requirements} ### Kubernetes {#kubernetes} | Elemento | Requisito | |---|---| | CloudStack | 4.23 (probado). CKS debe estar **habilitado** (`cloud.kubernetes.service.enabled = true`). | | Cuenta | Una cuenta **Domain Admin** en el dominio dedicado, para que NexCMP pueda crear un proyecto de CloudStack para cada cliente y límites de recursos dentro de él. Consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | El parámetro global de CloudStack debe apuntar a su API de administración, accesible desde las VM del clúster. NexCMP muestra el valor y el resultado de una comprobación del endpoint. | | Versiones | Al menos una entrada de versión admitida de Kubernetes con su ISO de binarios, en estado **Enabled**. Las versiones que han alcanzado el final de su vida útil no se pueden poner a la venta. | | Oferta de plano de control | Una oferta de servicio gratuita con **exactamente 2 vCPU, 2048 MB de RAM y un límite de CPU** (`limitcpuuse = true`), visible para la cuenta. El servidor rechaza cualquier otra cosa con `cp_offering_invalid`. | | Red | Una oferta de red aislada compatible con CKS que esté habilitada. | | IP | Direcciones IPv4 públicas libres en el rango comercializable; cada clúster utiliza una. | | Capacidad | Cada clúster le cuesta entre 2 y 4 GB de RAM para el plano de control y una pequeña VM de enrutador. Supervise las pestañas de capacidad. | ### Private Cloud {#private-cloud} | Elemento | Requisito | |---|---| | CloudStack | 4.23 (probado) con VPC habilitado. | | Oferta de VPC | Una oferta de VPC. Una oferta dual-stack proporciona a cada nivel un /64 de IPv6 también. | | Ofertas de red de nivel | **Una oferta de red por plan de ancho de banda**, creada para VPC, con la **tasa de red** (Mbps) igual a la del plan, más una oferta **bloqueada** de **1 Mbps** que se aplica cuando un VPC se bloquea por falta de pago. | | Cuenta | La cuenta dedicada (se recomienda Domain Admin). Las redes VPC permanecen en la cuenta, no en proyectos. | | IP | Direcciones IPv4 públicas libres (cada VPC utiliza una para source NAT). | | Espacio de direcciones | Cada VPC recibe un /16 de `10.128.0.0/9`. Mantenga ese rango sin usar en sus propias redes. | | Depende de | CloudStack conectado; el módulo **Private Cloud**. | ## Preparar la infraestructura {#prepare-the-infrastructure} ### Kubernetes: habilitar CKS y añadir versiones {#kubernetes-enable-cks-and-add-versions} 1. Habilite el servicio y configure el endpoint, luego reinicie el servidor de administración: ```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 ``` El controlador del clúster invoca `endpoint.url`, por lo que debe ser una dirección accesible para las VM del clúster. 2. Cree una ISO de binarios de Kubernetes para la versión que desea vender con el script `create-kubernetes-binaries-iso.sh` del árbol de código fuente de CloudStack, alójela en un servidor web y regístrela: ```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 ``` Espere a que el estado de la ISO sea **Ready** y a que la versión esté **Enabled**. 3. Cree la oferta de plano de control, limitada al dominio de 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. Compruebe que una oferta de red CKS esté habilitada: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: crear las ofertas {#private-cloud-create-the-offerings} En la interfaz de usuario de CloudStack (**Service Offerings › Network Offerings › Add network offering**) o con `cmk`: 1. Enumere lo que tiene: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. Utilice una oferta de VPC habilitada (dual-stack si desea IPv6). Si necesita una nueva, clone la oferta de VPC predeterminada de CloudStack y habilítela. 3. Para **cada** plan de ancho de banda que venda, cree una oferta de red **para VPC** (clone la "isolated network offering for VPC networks" predeterminada) y establezca **Network rate (Mb/s)** a la velocidad del plan: `50`, `100`, `500`, `1000`, `3000`. Habilite cada oferta. 4. Cree una oferta más con **network rate 1** (`VPC-LOCKED-1M`) para VPC bloqueados: los clientes aún podrán acceder a sus servidores mediante SSH, pero la velocidad estará limitada. 5. Anote el UUID de cada offering. NexCMP los necesita en la siguiente sección. ::: warning Los ID de offering incluidos no existen en su cloud El formulario de Private Cloud viene precargado con UUID de offering que pertenecen a otra instalación de CloudStack. Reemplace **cada uno** con los suyos propios, o el primer pedido de VPC fallará. ::: ## Conectar en NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. Abra **Infrastructure › Cloud provider › CloudStack** y seleccione la pestaña **Kubernetes (CKS)**. La tarjeta de la derecha **CKS status on CloudStack (read-only)** muestra `kubernetesserviceenabled`, `endpoint.url` con **Endpoint check**, el network offering de CKS, la configuración de `cloud.kubernetes.*` y la lista de ISO y versiones. Haga clic en **Recheck** después de corregir cualquier elemento. 2. En **Sales config**, seleccione el **Control plane Offering** (aparecerá una advertencia si no tiene exactamente 2 vCPU / 2048 MB / CPU cap), defina **Max workers per cluster** (de 1 a 9: CKS permite 10 nodos incluyendo el nodo de control), active **Enable CKS for this backend** y haga clic en **Save**. El interruptor permanecerá deshabilitado hasta que se seleccione un offering. ![La pestaña Kubernetes (CKS) con el offering de control plane seleccionado y la tarjeta de estado de CKS](https://nexcmp.com/es/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. Abra **Services › Kubernetes › Versions** y haga clic en **Sync from CloudStack**. Active **Available for new clusters** para las versiones que comercialice, defina la predeterminada y, si lo desea, una fecha de **End of life (EOL)**. 4. Abra **Services › Kubernetes › Policy**. En **Worker plans**, agregue planes con un **Plan code** (A-Z, 0-9, guion, hasta 16 caracteres). Configure **NVMe per worker (GB)**, **Min and max workers** y los límites del clúster (clústeres activos por cuenta, creaciones por 24 horas, límite global, operaciones concurrentes de CKS). Luego, active **Sell Kubernetes (CKS)**. Debe permanecer a la venta al menos un plan. ![Política de Kubernetes con los planes de worker y el interruptor de ventas](https://nexcmp.com/es/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. Abra **Services › Private Cloud** (Overview). En la tarjeta de política, reemplace **VPC offering** y **Locked offering tier** con sus propios UUID. Verifique los límites (VPC por cuenta, tiers, VM y reglas ACL por VPC, saldo en horas de tarifa del plan requerido para la creación, cambios de plan por 24 horas, operaciones concurrentes donde 0 es una parada de emergencia) y los servidores DNS. Haga clic en **Save** (se solicitará un motivo). ![Vista general de Private Cloud con los campos de VPC offering y locked offering](https://nexcmp.com/es/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. Abra **Services › Private Cloud › Plans & pricing**. Para cada plan, haga clic en **Edit** y configure **VND price per month**, **On sale** y el UUID de **CloudStack tier offering** cuya tasa de red equivalga a los Mbps del plan. La fila muestra el costo y la ganancia a uso completo, lo que le permite identificar qué planes están por debajo de su costo. ![Diálogo de edición de plan para un plan de ancho de banda de Private Cloud](https://nexcmp.com/es/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. Active **Sell Private Cloud**. Para probarlo primero, agregue los ID de las cuentas de prueba a **Beta accounts**: esas cuentas podrán usar el servicio mientras el interruptor de ventas esté desactivado. ## Verificación {#verify} 1. Kubernetes: la tarjeta de estado muestra `kubernetesserviceenabled: true`, una verificación de endpoint correcta y una versión habilitada. Cree un clúster de prueba con un worker como cliente; debería pasar al estado running y `kubectl get nodes` debería mostrarlo listo. Elimínelo después: la red y la IP volverán al grupo. 2. Private Cloud: cree una VPC con el plan más pequeño como cliente de prueba. La VPC se muestra activa, un tier obtiene su subred, una VM en el tier accede a Internet a través del router de la VPC y **Change plan** a un plan superior surte efecto en unos 20 segundos sin interrumpir las conexiones. ## Límites y notas {#limits-and-notes} - Kubernetes: los workers se facturan como VM a los precios del plan y cuentan como VM en los límites de VM. Un clúster puede tener como máximo 9 workers debido al límite de 10 nodos de CKS. - Kubernetes: el control plane, el router y la IP pública de un clúster son gratuitos para el cliente; usted asume su costo. - Private Cloud: todos los planes son **unmetered**. Los precios en el formulario están en dong vietnamitas por mes; la columna de costo utiliza un precio de referencia que no es el suyo, así que utilice sus propios números. - Una VPC bloqueada está limitada a 1 Mbps, no se factura y no se elimina automáticamente. - Private Cloud utiliza un router por VPC, no un par redundante. Si su host falla, CloudStack lo reconstruye en unos minutos. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `cp_offering_invalid` / "Esta oferta no es 2 vCPU / 2048 MB / limitcpuuse" | El offering del plano de control tiene otros tamaños o no tiene límite de CPU | Cree el offering como en el paso 3 y selecciónelo de nuevo. | | El interruptor **Enable CKS** está desactivado | No se ha seleccionado ningún offering para el plano de control | Seleccione uno primero. | | `kubernetesserviceenabled: false` | CKS está desactivado en CloudStack | Actívelo y reinicie el management server. | | Falla la comprobación del endpoint | `endpoint.url` no es accesible desde las VM del clúster | Configure una URL accesible, reinicie el management server y haga clic en **Recheck**. | | "EOL: no se puede habilitar para la venta" | La fecha de fin de vida útil de la versión ya ha pasado | Registre una versión más reciente. | | "Sin versiones: haga clic en Sync from CloudStack" | No hay ninguna versión de Kubernetes registrada | Registre una versión y sincronice. | | "El backend de CKS está en OFF: los clientes no pueden crear clústeres aunque el indicador de venta esté habilitado" | El interruptor de venta está activado pero el backend de CKS está desactivado | Active CKS en la pestaña CloudStack. | | "Al menos 1 plan debe estar a la venta" | Se ha eliminado el último plan de worker | Mantenga al menos un plan o desactive la venta de Kubernetes. | | El clúster se queda bloqueado al crearse | Capacidad insuficiente o falta una ISO | Compruebe las pestañas de capacidad y el estado de la ISO de la versión. | | Una nueva VPC falla en el primer paso | El ID del VPC offering o del tier offering no es válido | Sustituya cada UUID de offering por uno de su CloudStack. | | "cs_offering_id debe ser un UUID" | El ID de un offering no es un UUID | Pegue el ID desde `cmk list networkofferings`. | | Falla el cambio de plan | El nuevo tier offering no existe o la tasa de red es incorrecta | Compruebe el UUID del offering y su tasa de red. | --- # Planes y precios {#plans-and-pricing} > **Ubicación en el panel de administración:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`), con las pestañas Plan, Custom plan, Cycle y Offering CloudStack. Las plantillas están en la página independiente Services › Virtual Machines › Template (`/vm/templates`). ## Qué hace {#what-it-does} Un **plan** es un tamaño que los clientes pueden contratar: vCPU, RAM, disco raíz y un precio, en una zona y desde un origen (CloudStack o un clúster de Proxmox VE). El cliente elige un plan, un sistema operativo y un **ciclo de facturación** (por horas, mensual o un plazo prepagado mayor). Los planes se venden en el portal del cliente, mediante la API y en los sitios de revendedores. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Source | CloudStack conectado (un plan apunta a un service offering de CloudStack) o un clúster de Proxmox VE vinculado a la zona. Consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) y [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). | | Zona | Una zona que comercialice máquinas virtuales. Consulte [Zones](https://nexcmp.com/es/docs/infrastructure/zones/). | | Plantillas | Al menos una plantilla habilitada y lista. Consulte [OS templates](https://nexcmp.com/es/docs/infrastructure/templates/). | | Tipo de cambio | Solo si introduce precios en VND. Consulte [Currency and exchange rates](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). | | Permisos | Un administrador; cada cambio de precio requiere un motivo. | ## Preparar la infraestructura {#prepare-the-infrastructure} - **CloudStack:** cree las ofertas de servicio que desee vender (públicas o compartidas con el dominio de NexCMP). Un plan apunta a una oferta. La pestaña **Offering CloudStack** enumera las ofertas y ofertas de disco en vivo desde CloudStack (almacenadas en caché durante 60 segundos). Cuando la tabla de planes está vacía, el worker crea automáticamente seis planes a partir de sus ofertas reales. - **Proxmox VE:** nada en Proxmox; un plan incluye su propia CPU, RAM y disco. El disco no debe ser menor que el disco de la plantilla. ## Conectar en NexCMP {#connect-in-nexcmp} ### Cómo se almacenan los precios {#how-prices-are-stored} NexCMP almacena cada precio como **microdólares por hora** (µ$/hora; 1 µ$ equivale a 1/1,000,000 USD). Puede introducir el precio en la unidad que prefiera y el formulario lo convertirá: | Unidad | Notas | |---|---| | USD / hora (6 decimales) | Se almacena tal cual. | | USD / mes | Se divide por el ajuste de horas por mes (730). | | VND / mes | Se convierte una vez según el tipo de cambio actual y luego se guarda en µ$/hora. Solo aparece cuando existe un tipo de cambio. | El formulario muestra el resultado: µ$/hora, USD/hora, el precio mensual y cada ciclo de facturación. **Precio mensual = precio por hora × 730**; un ciclo más largo es **precio mensual × meses × (1 − descuento)**. ### Añadir un plan {#add-a-plan} 1. Abra **Services › Virtual Machines › Plans & pricing** y haga clic en **Add plan**. 2. Complete el formulario: | Campo | Valor de ejemplo | |---|---| | Nombre del plan | `VM-2-4` | | Slug | vacío: generado a partir del nombre | | Zona | su zona predeterminada | | Origen de infraestructura | vacío para CloudStack o un clúster de Proxmox | | Oferta de servicio de CloudStack (en vivo) | elija una (solo se muestra para CloudStack) | | CPU (núcleo), RAM (MB), disco raíz (GB) | `2`, `4096`, `40` | | Oferta de disco | opcional, para un tamaño de raíz personalizado | | Introducir precio por / Precio | `USD / month`, `12` | | Descripción breve | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | Orden | `10` | | Activo | Activado: los clientes pueden comprar | | Visibilidad | Visible en el catálogo | | Motivo del cambio de precio | `initial price` | 3. Haga clic en **OK**. El plan aparece en la tabla con su precio por hora y mensual, y una celda para cada ciclo habilitado. ![Tabla de planes con precios por hora, mensuales y por ciclo](https://nexcmp.com/es/docs/images/catalog/plans-02-list.webp) ### Ciclos de facturación {#billing-cycles} Abra la pestaña **Cycle** para configurar los ciclos que los clientes pueden elegir y sus descuentos. | Ciclo | Predeterminado | Notas | |---|---|---| | Por hora | siempre activo | Se cobra hora por hora. | | Mensual | activado, 0% | | | 1 año | activado, 10% | | | 2 años | activado, 15% | | | 3 años | activado, 20% | | Puede cambiar el nombre de un ciclo, modificar su descuento (0 a 90%) y activarlo o desactivarlo. El cambio se aplica a las VM compradas o renovadas **después** de guardar; las VM en ejecución conservan su precio bloqueado. ![Pestaña Cycle con descuentos por ciclo de facturación](https://nexcmp.com/es/docs/images/catalog/plans-03-cycles.webp) ### Definir un plan base y derivar los demás {#set-a-base-plan-and-derive-the-others} **Set base plan + derive other plans** recalcula toda la tabla a partir de un único precio. Elija el plan base y su precio, y luego mantenga las **relaciones de precios actuales** entre planes o calcúlelas a partir de los **precios de componentes** (µ$/hora por vCPU, por GB de RAM y por GB de NVMe, con un descuento opcional por paquete del 0 al 50%). Una tabla de vista previa muestra los precios anteriores y nuevos antes de guardar cualquier cambio. Haga clic en **Apply** e indique un motivo. Al aplicar nuevos precios: las VM **por horas** en ejecución reciben un precio **más bajo** a partir de la siguiente hora de facturación, y las VM prepagadas lo reciben en la renovación. Si un precio **aumenta**, las VM en ejecución conservan su precio anterior. ### Planes personalizados {#custom-plans} La pestaña **Custom plan** permite a los clientes elegir su propio tamaño de vCPU, RAM y NVMe. Defina el precio unitario por hora para una vCPU, un GB de RAM y un GB de NVMe (déjelo vacío para derivarlo a partir de un porcentaje de descuento), los valores mínimo, máximo y de incremento para cada uno, y qué ciclos de facturación aplican. Un plan **personalizado** debería costar más que un plan fijo del mismo tamaño; de lo contrario, los clientes ignorarían el plan fijo. La página marca las filas donde el personalizado resulta más económico. Active **Enable custom plans for customers** para venderlos; al desactivarlo se muestra "Coming soon" en el portal. Cada VM personalizada obtiene su propia fila de plan oculta; dichas filas no se pueden editar ni eliminar mientras la VM exista. ### Modificar, ocultar, clonar, eliminar {#change-hide-clone-delete} | Acción | Qué hace | |---|---| | **Edit** | Modifica el nombre, la descripción, el orden, el precio, el estado activo y la visibilidad. | | **On/Off** | **Off**: los clientes no pueden comprar; las VM en ejecución no se ven afectadas. | | **Hide / Show** | Un plan oculto no aparece en el catálogo, pero las VM existentes lo conservan y un administrador puede asignarlo. | | **Clone** | Crea un nuevo plan en la misma zona con un nuevo origen, tamaño o precio, con la opción de ocultar el anterior. Para vender la misma configuración desde CloudStack y Proxmox, clónelo y elija el otro origen. | | **Move up/down** | Cambia el orden. | | **Delete** | Elimina el plan de la venta y de la tabla. Las VM que ya lo utilizan lo conservan. | ::: warning Los planes en uso están bloqueados Una vez que un plan tiene VM, sus campos **zone, offering, CPU, RAM, disk and source** se bloquean para que las VM en ejecución no se modifiquen de forma silenciosa. Utilice **Clone** para crear la nueva configuración; el plan anterior conserva sus VM. ::: ## Verificación {#verify} 1. El plan aparece en la tabla con el precio por hora y mensual esperado. 2. En el portal de clientes, inicie un pedido: la zona ofrece el plan y los precios del ciclo coinciden con la pestaña **Cycle**. 3. Realice un pedido de prueba, verifique el cargo en el monedero con respecto al precio mostrado y elimine la VM. ## Límites y notas {#limits-and-notes} - Un plan pertenece a **una** zona y a **un** origen. - Los precios se almacenan en µ$/hora; el precio en VND mostrado se deriva y redondea mediante el **VND rounding step** (consulte la página de divisas). El monedero siempre está en USD. - Los revendedores obtienen un precio mayorista y minorista derivado del precio de lista; cambiar un precio para un plan existente no copia los precios personalizados de revendedor a un clon cuya configuración haya modificado. - Los límites mínimo, máximo y de incremento de los planes personalizados se comparan con los límites propios de CloudStack; un disco máximo superior al de CloudStack `storage.max.volume.size` hace que los despliegues fallen y se reembolsen. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Nombre del plan requerido" / "Oferta de servicio requerida" | Campo faltante | Complete el nombre; para CloudStack elija un offering. | | "CPU/RAM/disco debe ser > 0" | Un tamaño está vacío o es cero | Ingrese los tres. | | "Precio no válido (µ$/hr debe ser 1 … 100,000,000)" | El precio está fuera de rango | Verifique la unidad y el importe. | | "El cambio de precio requiere un motivo" | El motivo está vacío al editar | Escriba un motivo (3 caracteres o más). | | "El offering \"X\" es 4c/8192 pero el plan especifica 2c/4096 - CloudStack aprovisionará según el offering. ¿Guardar?" | Los valores del plan difieren de los del offering | Haga que coincidan o confirme para conservar el tamaño de CloudStack. | | "No se pudieron obtener los offerings de CloudStack" | La conexión está caída o la clave no tiene permisos | Consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/). | | "La plantilla no está lista en CloudStack - el despliegue fallará. ¿Habilitar de todos modos?" | Habilitó una plantilla incompleta | Espere a que la plantilla esté lista. | | No se puede editar el plan ("tiene VM: bloqueado") | Hay VM que usan el plan | Clónelo. | | El plan no se muestra a los clientes | Desactivado, oculto o la zona no está lista | Verifique **Active**, **Visibility** y la etiqueta de zona. Consulte [Zones](https://nexcmp.com/es/docs/infrastructure/zones/). | | "Seleccione al menos 1 ciclo de facturación" | No se marcó ningún ciclo para los planes personalizados | Marque al menos uno. | | "El descuento por paquete debe ser de 0–50%" | Fuera de rango | Use de 0 a 50. | | Falta la opción de precio en VND | Aún no hay tipo de cambio | Actualice el tipo de cambio primero. | --- # Cuotas de ancho de banda y add-ons {#bandwidth-quotas-and-add-ons} > **Ubicación en el panel de administración:** Services › Bandwidth: Summary (`/bandwidth`), Add-on (`/bandwidth/addons`) y Quotas, pricing & policy (`/bandwidth/policy`). El interruptor del módulo está en System › Admin › License & updates. ## Qué hace {#what-it-does} Bandwidth asigna a cada servicio medido una **cuota** de tráfico mensual. NexCMP mide el uso, avisa al cliente al 80% y al 100% y, cuando se supera la cuota, actúa según su **política de exceso**. Los clientes pueden comprar **add-ons** de terabytes adicionales desde su billetera; usted también puede otorgar add-ons de forma gratuita. | Servicio | Cuota | |---|---| | Máquinas virtuales | Por VM al mes (por defecto 2048 GB, es decir, 2 TB) | | Kubernetes | La cuota de la VM multiplicada por el número de workers | | Object Storage | Tráfico de descarga por cliente al mes (por defecto 100 GB); a partir de ahí se aplica el precio normal de pago por uso | | VPN | Conserva la cuota de su plan; amplíe el ancho de banda en la página de VPN | | Private Cloud | **No medido** | ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Módulo | **Bandwidth** está activado de forma predeterminada. Desactívelo en License & updates para ocultarlo. | | Fuente de medición | Con la fuente predeterminada, **CloudStack VM statistics**. Mantenga habilitada la recopilación de estadísticas de VM en CloudStack; la retención predeterminada de 720 minutos es suficiente. | | Proxmox VE | Las VM en Proxmox VE **no se miden**. | | Tipo de cambio | El precio del add-on se introduce en VND. Consulte [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). | | Depende de | [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) para el tráfico de VM y Kubernetes, [S3](https://nexcmp.com/es/docs/infrastructure/s3/) para descargas de almacenamiento. | ## Preparar la infraestructura {#prepare-the-infrastructure} No se requiere nada más allá de tener CloudStack conectado. NexCMP lee `listVirtualMachinesUsageHistory` para todas las VM de la cuenta en una sola llamada, cada 5 minutos, en ventanas de como máximo dos horas. Cada muestra cubre un minuto y se **suma**. Las muestras se toman con tres minutos de desfase para que tengan tiempo de llegar. Cualquier intervalo superior a la retención de CloudStack (aproximadamente 12 horas) se omite y se registra. ::: info Qué significan los números El consumo se mide en la interfaz de red de cada VM, por lo que incluye el tráfico entre VM y no solo el tráfico hacia Internet. Puede ser algo mayor que lo que contabilizaría un router de borde. ::: ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Services › Bandwidth › Quotas, pricing & policy**. 2. Establezca los valores y haga clic en **Save**; se solicitará un motivo y se registrará. El worker aplica el cambio en unos 30 segundos. | Campo | Predeterminado | Significado | |---|---|---| | Habilitar Bandwidth (menú del cliente y compra de add-ons) | activado | El interruptor para la parte comercial del módulo. | | VM, GB/mes (Kubernetes = este valor × workers) | 2048 | Cuota por VM por período. | | S3, GB de descarga/mes por cliente | 100 | A partir de este límite, se aplica el pago por uso habitual de S3. | | Dirección de la cuota (VM, Kubernetes) | In + out | O **Outbound only**. | | Precio de +1 TB (VND) | 100,000 | Convertido a centavos al tipo de cambio de la cotización. | | Máximo por compra (TB) | 50 | | | Política de exceso | suspend | **notify**, **throttle** o **suspend** (a continuación). | | Aplicar suspensión efectiva desde | fecha de migración + 24 horas | Antes de esta fecha no se suspende nada; a los clientes solo se les advierte. | | Límite de velocidad de throttle (Mbps) | | Solo se utiliza con throttle. | ![Política de ancho de banda: cuotas predeterminadas, precio de add-on y política de exceso](https://nexcmp.com/es/docs/images/catalog/bandwidth-01-policy.webp) ### Políticas de exceso {#overage-policies} | Política | Qué ocurre cuando un servicio supera el 100% | |---|---| | **notify** | Se notifica al cliente. Nada más. | | **throttle** | Igual que notify por ahora: el limitador de velocidad no está conectado en esta versión. | | **suspend** (predeterminado) | La VM, el clúster o la cuenta de S3 se suspenden hasta que el cliente compre un add-on o comience el siguiente período. Solo es efectivo a partir de la fecha **suspend-from**. | Las alertas del 80% y 100% (campana y correo electrónico) siempre se ejecutan, una vez por umbral, período y servicio. Si desbloquea un servicio que se suspendió por ancho de banda mientras aún supera la cuota, la siguiente comprobación (en un plazo de 5 minutos) lo suspenderá de nuevo. Para mantenerlo en ejecución, **asigne un add-on**. ### Supervisar el uso y otorgar add-ons {#watch-usage-and-grant-add-ons} Abra **Services › Bandwidth › Summary**. Muestra cada servicio con su consumo en el periodo actual, la cuota incluidos los add-ons, la cuota restante y las marcas del 80% y 100%. Las tarjetas de KPI muestran la cantidad de servicios, los add-ons vendidos en los últimos 30 días y el estado del recolector (running, cursor). La tabla **Daily** muestra el periodo actual día por día. ![Bandwidth Summary con el estado del recolector y el consumo por servicio](https://nexcmp.com/es/docs/images/catalog/bandwidth-02-summary.webp) Para dar margen a un cliente, utilice **Grant** en un servicio (un add-on de terabytes enteros sin cargo). Abra **Add-on** para ver el historial de compras y asignaciones, ordenado por las más recientes, con un filtro por tipo. ![Historial de Add-on que muestra compras y asignaciones gratuitas](https://nexcmp.com/es/docs/images/catalog/bandwidth-03-addons.webp) ### Lo que ven los clientes {#what-customers-see} El portal del cliente incluye un menú **Bandwidth** con el consumo, la cuota restante y la opción **buy +1 TB** pagada desde el saldo (hasta su límite máximo por compra). Los add-ons son válidos para el periodo actual. ## Verificación {#verify} 1. El recolector en **Summary** está en ejecución y su cursor avanza cada pocos minutos. 2. Una máquina virtual con tráfico muestra consumo después de unos 10 a 15 minutos. 3. Para ver las alertas, reduzca la cuota de la VM a unos pocos GB en una instalación de **prueba** y genere tráfico. No haga esto en producción: la cuota se aplica a todas las VM. ## Límites y notas {#limits-and-notes} - El consumo se contabiliza por periodo (un mes). Los add-ons y las cuotas se aplican al periodo actual. - "Enforce actual suspend from" evita suspender clientes en el instante en que se habilita el módulo por primera vez. - La política de limitación de ancho de banda (throttle) solo envía notificaciones en esta versión. - Modificar la cuota se aplica a todos los sitios, incluidos los de revendedores. Los precios minoristas y mayoristas de los add-ons para revendedores se ajustan según su descuento o margen. - El ancho de banda para **Dedicated servers** se gestiona de forma independiente; consulte [Dedicated servers](https://nexcmp.com/es/docs/infrastructure/dedicated/). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El consumo permanece en cero para una VM en ejecución | El worker está detenido, CloudStack está desconectado o las estadísticas de VM están deshabilitadas | Compruebe `sudo nexcmp status` y **Test connection** en [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/); habilite las estadísticas de VM en CloudStack. | | El registro de consumo presenta vacíos | Se excedió la retención de CloudStack o el worker estuvo inactivo durante más de unas 12 horas | No recuperable; el intervalo queda registrado. | | El consumo es ligeramente superior al esperado | Se incluye el tráfico entre VM y el tráfico de otras interfaces | Comportamiento esperado; explíqueselo a los clientes. | | Un servicio suspendido vuelve a suspenderse tras desbloquearlo | Aún supera la cuota permitida | Otorgue un add-on o aumente la cuota. | | No se suspende nada aunque la política sea **suspend** | La fecha a partir de la cual suspender está en el futuro | Establézcala en la fecha actual (la página muestra "ACTIVE" cuando está vigente). | | "bw_over_policy debe ser notify, throttle o suspend" | Se envió una política no válida a través de la API | Utilice uno de los tres valores. | | Las VM de Proxmox no muestran consumo | No están sujetas a medición | Comportamiento esperado. | | Los clientes no pueden comprar add-ons | El ancho de banda está desactivado o el saldo es insuficiente | Compruebe el interruptor y el saldo. | --- # Moneda y tipos de cambio {#currency-and-exchange-rates} > **Ubicación en el panel de administración:** Finance › Payment channels › Exchange rates (`/payments/fx`) para las tasas. System › Settings › Brand (`/settings/branding`) para el selector **Site currency**. ## Qué hace {#what-it-does} NexCMP mantiene las billeteras y las facturas en USD. Los precios de los planes de VM se almacenan como microdólares por hora. Las monedas de visualización permiten a los clientes consultar los importes en USD en su propia moneda según una tasa publicada; no modifican el saldo de la billetera. Algunos servicios aceptan precios introducidos en VND, incluidos los complementos de ancho de banda, S3, Private Cloud y los planes existentes de Bare Metal que conservan los precios en VND. Las transferencias bancarias a través de Sepay se pagan en VND. Las tasas las **publica un administrador**. Nada se actualiza automáticamente, por lo que las tasas guardadas permanecen exactamente como están hasta que pulsa el botón de actualización. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Acceso a internet | El servidor del panel debe poder conectarse con `open.er-api.com` (para USD/VND) y `api.frankfurter.dev` (para las demás monedas) cuando pulse **Update exchange rates**. | | Permisos | Un administrador para realizar cambios; cada cambio solicita un motivo. | | Depende de | Ninguno. [Plans](https://nexcmp.com/es/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/es/docs/catalog/bandwidth/), [S3](https://nexcmp.com/es/docs/infrastructure/s3/) y las transferencias bancarias en VND utilizan la tasa. | ## Preparar la infraestructura {#prepare-the-infrastructure} No requerido. Si su servidor filtra el tráfico saliente, permita HTTPS hacia los dos servicios anteriores. ## Conectar en NexCMP {#connect-in-nexcmp} ### 1. Elegir la moneda del sitio {#_1-choose-the-site-currency} Abra **System › Settings › Brand** y configure **Site currency**: | Opción | Lo que ven los clientes | |---|---| | **Basado en el idioma (auto)** (el valor predeterminado en una nueva instalación) | El portal selecciona una moneda de visualización según el idioma (tabla a continuación). El cliente puede elegir USD en su lugar. | | **USD** | Precios y saldos únicamente en USD. Sin selector de moneda ni importes convertidos. | | **VND** | Ajuste heredado; sigue las mismas reglas de visualización basadas en el idioma que Auto. | Guarde los cambios. Las páginas de los clientes se actualizan en aproximadamente un minuto. Cuando el sitio sigue el idioma del cliente: | Idioma | Moneda de visualización | |---|---| | Inglés | USD | | Vietnamita | VND | | Chino (simplificado / tradicional) | CNY / TWD | | Japonés, coreano | JPY, KRW | | Francés, alemán, español, italiano | EUR | | Portugués, ruso | BRL, RUB | | Árabe, hindi | SAR, INR | | Indonesio, tailandés | IDR, THB | Una moneda cuya tasa no haya sido publicada no se ofrecerá: el portal recurrirá a USD. ### 2. Publicar las tasas {#_2-publish-the-rates} 1. Abra **Finance › Payment channels › Exchange rates**. 2. La tarjeta **Currency by language** enumera las 11 monedas de visualización con su tasa por USD, el origen (Frankfurter) y la hora de la última actualización. Haga clic en **Update exchange rates**. El botón realiza dos acciones en un solo paso: lee la tabla de mercado pública para **USD/VND** y lee los otros 11 tipos. Ambos se verifican antes de guardar cualquiera de ellos. Si uno falla, no se modifica nada y se mantienen los tipos anteriores. 3. La tarjeta **Active exchange rate** muestra el tipo de cambio USD/VND vigente, su etiqueta de origen (mercado público o fijo), el margen y las cifras de referencia del mercado con sus marcas de tiempo. 4. La tarjeta **Config** (guardar con un motivo): | Campo | Significado | Rango | |---|---|---| | Margen (bp, 100 = 1 %) | Se añade a la tasa de referencia del mercado. La tasa efectiva es la tasa de referencia más el margen, redondeada hacia arriba. | 0 a 1000 | | Tasa fija (VND por USD, 0 = seguir el mercado) | Un tipo de cambio establecido por usted. Sustituye a la cifra del mercado. | 0 o 15,000 a 50,000 | | Umbral de salto (bp) | Un nuevo tipo de cambio de mercado que difiera del actual en más de este valor queda **retenido** hasta que usted lo confirme. | 50 a 2000 (predeterminado: 500) | | Paso de redondeo de VND | Redondea los precios en VND y los importes de transferencias bancarias. | 1, 100, 1,000 (predeterminado) o 10,000 | 5. Si un nuevo tipo de cambio de mercado supera el umbral, aparece la tarjeta **Pending exchange rate** y el tipo **no se aplica**. Compárelo con la referencia elegida y haga clic en **Apply this rate**. Una tasa de mercado fuera de 15,000 a 50,000 VND por USD se rechaza por considerarse no razonable. Las actualizaciones manuales están limitadas a una solicitud cada cinco minutos, por lo que el botón puede pedirle que espere. 6. La tabla **Exchange rate history** enumera cada tipo de cambio obtenido o confirmado con su hora, tipo efectivo, referencia de mercado, origen, si se aplicó, quién lo hizo y una nota (las variaciones retenidas se marcan como **held**). ## Cómo se utiliza una tasa {#how-a-rate-is-used} | Lugar | Regla | |---|---| | Wallet y facturas | Centavos de USD. La tasa nunca modifica un saldo. | | Planes de VM introducidos en VND | Se convierten **una sola vez** al tipo de cambio vigente al guardar y luego se almacenan en USD. Los cambios posteriores de tipo de cambio no vuelven a cotizar esos planes de VM. | | Transferencia bancaria mediante Sepay | El cliente paga `ceil(USD × rate)`, redondeado hacia arriba al paso de redondeo. Sepay está **bloqueado** hasta que exista una tasa USD/VND. | | Planes Bare Metal | Las nuevas instalaciones utilizan USD directamente. Los planes existentes en VND conservan su unidad de precio y requieren un tipo de cambio al cobrar; consulte [Dedicated servers](https://nexcmp.com/es/docs/infrastructure/dedicated/). | | Otros pagos internacionales introducidos en VND | Redondeado al centavo más cercano. | | Visualización en el portal | USD multiplicado por la tasa publicada de la moneda de visualización, con el formato correspondiente al idioma. | ## Verificación {#verify} 1. **Active exchange rate** muestra un valor USD/VND con una hora de obtención reciente. 2. La cuadrícula **Currency by language** muestra tasas no vacías. 3. En el portal del cliente, cambie el idioma a vietnamita (con la moneda del sitio en Auto): los precios se mostrarán en dongs; cámbielo a japonés: yenes. Con la moneda del sitio en USD, solo se muestran dólares. 4. En un formulario de plan (Plans & pricing), la lista **Enter price by** ofrece **VND / month**. ## Límites y notas {#limits-and-notes} - Sin actualización automática. Pulse **Update exchange rates** cuando desee nuevas tasas y configure un recordatorio si las tasas son importantes para usted. - Se utiliza el tipo de cambio de mercado público para USD/VND; es un tipo de referencia y no una cotización bancaria de compra o venta. Las demás monedas de visualización provienen de Frankfurter; se rechaza una fecha de más de 14 días de antigüedad o una tabla incompleta. - El margen y una tasa fija solo afectan a USD/VND. Las 11 monedas de visualización no tienen margen. - Cada idioma de cliente tiene una moneda. Al cambiar de idioma, se restablece la moneda a la de ese idioma, a menos que el cliente haya elegido USD para el mismo idioma. - Los sitios de revendedor siguen las mismas tasas. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "El nuevo tipo de cambio se desvía más allá del umbral - EN ESPERA, requiere confirmación manual" | El salto es mayor que el umbral | Verifique y haga clic en **Apply this rate**, o cambie el umbral. | | "El servidor rechazó el nuevo tipo de cambio" | La cifra de mercado está fuera de 15,000 a 50,000 o tiene un formato incorrecto | Espere y vuelva a intentarlo, o establezca una tasa fija. | | La actualización le pide que espere antes de volver a intentarlo | Actualizaciones demasiado frecuentes | Espere y vuelva a intentarlo. | | "no se pudo obtener la tasa: …" | El servidor del panel no puede comunicarse con los servicios de tasas | Permita el tráfico HTTPS saliente y vuelva a intentarlo. | | Etiqueta **Sepay blocked** | Aún no se ha publicado ninguna tasa USD/VND | Pulse **Update exchange rates** o establezca una tasa fija. | | Falta una moneda en el portal | Falta su tasa | Pulse **Update exchange rates**. | | Los clientes solo ven los precios en USD | La moneda del sitio es USD o falta la tasa | Establezca **Site currency** en Auto y publique los tipos de cambio. | | "Tabla de tasas de Fx incompleta; se conservan las tasas anteriores" | Frankfurter devolvió menos de 11 monedas | Vuelva a intentarlo más tarde; no se modificó nada. | | Falta la opción VND en el formulario del plan | No hay tasa USD/VND | Publique una tasa primero. | --- # Canales de pago {#payment-channels} > **Dónde está en el panel de administración:** Finance › Payment channels (`/payments`). Interruptores y comisiones: Finance › Payment channels › Fees & limits (`/payments/fees`). NexCMP utiliza una **billetera prepagada en USD**. Los clientes añaden fondos a la billetera mediante un canal de pago; luego, cada servicio se paga desde la billetera. Un canal solo se muestra a los clientes cuando está tanto **habilitado** como **configurado**. ## Qué hace {#what-it-does} Los canales de pago conectan sus cuentas de pago (Stripe, PayPal, Binance, un banco vietnamita) con la billetera del cliente. Un pago confirmado se convierte en exactamente un crédito en la billetera; cada crédito se indexa mediante el ID de pago de la pasarela, por lo que un webhook repetido nunca podrá añadir fondos dos veces. Utilice esta página para ver qué canales están listos, cómo funcionaron durante los últimos 30 días y cuáles requieren atención. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Dirección HTTPS pública | Las pasarelas envían webhooks a `https:///v1/billing/...`, por lo que su panel debe ser accesible desde Internet mediante TLS válido (consulte [DNS y Cloudflare](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/)). | | Cuentas | Su propia cuenta con cada proveedor que desee utilizar. Las credenciales se introducen en el panel de administración y no se vuelven a mostrar (solo los últimos 4 caracteres). | | Rol de administrador | Una cuenta de administrador. | | Dependencias | Ninguno. El canal bancario de VN necesita además un [tipo de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). | ## Los canales {#the-channels} | Canal | Lo que ve el cliente | Se configura en | Artículo | |---|---|---|---| | Tarjeta (Stripe) | Formulario de tarjeta, tarjeta guardada | Payment channels › Stripe | [Stripe](https://nexcmp.com/es/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | Botones de billetera (Stripe Express Checkout) | Stripe, más registro de dominio | [Stripe](https://nexcmp.com/es/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | Redirección a Alipay (cobrado en JPY por Stripe) | Stripe, más Fees & limits | [Stripe](https://nexcmp.com/es/docs/billing/stripe/#alipay) | | PayPal | Botones de PayPal, cuenta de PayPal guardada | Payment channels › PayPal | [PayPal](https://nexcmp.com/es/docs/billing/paypal/) | | USDT | Dirección de depósito e importe exacto | Payment channels › USDT | [USDT](https://nexcmp.com/es/docs/billing/usdt/) | | Transferencia bancaria de VN | Código QR y detalles de transferencia (solo en la interfaz en vietnamita) | Payment channels › VN bank transfer | [Transferencia bancaria (Vietnam)](https://nexcmp.com/es/docs/billing/bank-transfer-vn/) | ## Preparar la infraestructura {#prepare-the-infrastructure} No es necesario. Todo se configura en el panel de administración; no hay nada que instalar en el servidor. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels** (`/payments`). La tabla general enumera cada canal con su estado. 2. Abra la pestaña propia del canal (**Stripe**, **PayPal**, **USDT**, **VN bank transfer**) y siga su artículo. Cada pestaña finaliza con un botón **Save** y, donde esté disponible, un botón **Test**. 3. Abra **Fees & limits** (`/payments/fees`), busque la tarjeta **Payment gateways & fees (wallet top-up)**, active el canal con su interruptor y haga clic en **Save channels & fees**. ![Vista general de canales de pago que enumera las pasarelas con su estado habilitado, configurado y estadísticas de 30 días](https://nexcmp.com/es/docs/images/billing/payment-channels-01-overview.webp) ![Página de tarifas y límites con los interruptores de canales y los campos de comisiones](https://nexcmp.com/es/docs/images/billing/payment-channels-02-fees.webp) ### Interruptores y comisiones (Fees & limits) {#switches-and-fees-fees-limits} | Ajuste | Predeterminado | Significado | |---|---|---| | Tarjeta (Stripe) | On | Formulario de tarjeta en la pantalla de depósito. Oculto hasta que Stripe tenga una clave secreta. | | Apple Pay, Google Pay, Link | On | Botones de billetera. Solo aparecen cuando el dominio está verificado en Stripe. | | Alipay | Desactivado | Requiere que Alipay esté activado en el Stripe Dashboard. | | PayPal | Desactivado | Se muestra solo cuando PayPal está configurado. | | USDT (Binance) | Desactivado | El interruptor está bloqueado hasta que la dirección de depósito haya sido verificada con Binance. | | Comisión de Stripe % / fija (centavos) | 3.6 % y 0 | Se utiliza para mostrar la comisión al cliente y calcular el importe acreditado. Establézcalo según su tarifa real de Stripe. | | Comisión de PayPal % / fija | 4.4 % y 30 centavos | Lo mismo, para PayPal. | | Comisión de USDT % | 1 % | Lo mismo, para USDT. | | El cliente paga la comisión de recarga | Desactivado | **On**: el cliente paga el importe + la comisión y el monedero recibe el importe íntegro. **Off**: se descuenta la comisión y el monedero recibe el importe menos la comisión. | El cliente siempre ve la comisión y el crédito final del monedero antes de pagar. Al desactivar un canal, se oculta el botón y el servidor rechaza nuevos pagos con `method_disabled` (HTTP 403). ::: tip Límites de recarga El importe mínimo y máximo por recarga se encuentran en la misma página; consulte [Minimum top-up](https://nexcmp.com/es/docs/billing/minimum-top-up/). ::: ## Verificación {#verify} 1. En la tabla general, el canal muestra **Enabled** y **Configured**; la columna **Last test** se completa tras hacer clic en **Test** en la pestaña del canal. 2. Inicie sesión en el portal como cliente de prueba y abra **Billing › Deposit**. El botón del canal estará visible. 3. Realice un pago pequeño (consulte el artículo del canal para obtener tarjetas de prueba o cuentas sandbox). El saldo aumentará, aparecerá una notificación de **Top-up received** y el pago se listará en **Finance › Billing › Top-ups** (`/billing/deposits`). ## Límites y notas {#limits-notes} - **Columnas del resumen:** *30 days* (número de pagos, operaciones correctas, fallos y volumen), *Stuck 24h* (pagos aún pendientes tras un día) y *Unmatched* (transferencias bancarias o en USDT recibidas que no coinciden con ningún pedido). La fila de KPI añade el volumen a 30 días, el número de canales con errores (habilitados pero no configurados, o con pagos bloqueados) y el total sin asignar. - Los **eventos de webhook** se listan en **Payment channels › Gateway events** (`/payments/events`). Stripe dispone de su propia pestaña; PayPal y USDT comparten una. Si un evento falla, puede reproducirse: el libro mayor del monedero es idempotente, por lo que reintentarlo nunca acredita dos veces. - Los **Resellers** pueden tener sus propios canales de Stripe, PayPal, USDT y cuentas bancarias. Sus filas también aparecen aquí y el selector de sitio de la cabecera permite filtrarlas. Consulte [Resellers](https://nexcmp.com/es/docs/customers/resellers/). - **Reembolsos:** los pagos de Stripe y PayPal pueden reembolsarse desde la lista de pagos; los pagos con USDT no pueden reembolsarse al origen (el servidor responde `usdt_no_refund`). - El **modo de mantenimiento** sigue aceptando los webhooks de las pasarelas, por lo que un pago efectuado justo antes del mantenimiento no se pierde. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Falta el canal en la pantalla de depósito del cliente | Desactivado, no configurado o (banco de VN) la interfaz no está en vietnamita | Compruebe **Fees & limits** y la pestaña del canal; consulte [Bank transfer (Vietnam)](https://nexcmp.com/es/docs/billing/bank-transfer-vn/). | | El KPI **Faulty channels** es superior a 0 | Un canal está habilitado sin credenciales o hay pagos pendientes durante más de 24 horas | Abra la fila y haga clic en **Configure**; para pagos bloqueados, abra **Gateway events** y vuelva a reproducirlos. | | El cliente pagó pero el saldo no cambió | El webhook no llegó | Compruebe la URL del webhook en la pestaña del canal y luego reproduzca el evento en **Gateway events**. | | El servidor responde `method_disabled` | El interruptor está desactivado | Actívelo en **Fees & limits** y guarde los cambios. | | El interruptor de USDT aparece atenuado | Dirección de depósito no verificada | Haga clic en **Test & verify address** en la pestaña de USDT. | --- # Stripe > **Ubicación en el panel de administración:** Finance › Payment channels › Stripe (`/payments/stripe`). Interruptores y comisiones: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Qué hace {#what-it-does} Stripe procesa pagos con tarjeta para recargas de saldo. Con la misma cuenta también puede ofrecer **Apple Pay**, **Google Pay**, **Link** y **Alipay**, y permitir a los clientes **guardar una tarjeta** para [recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/). Utilícelo como el canal principal para clientes internacionales. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta de Stripe | Una cuenta de Stripe que pueda aceptar pagos en **USD**. Alipay se cobra en JPY y debe ser activado por Stripe para su cuenta. | | Claves | Una clave secreta (`sk_live_...` o `sk_test_...`) y una clave publicable (`pk_live_...` o `pk_test_...`). El formulario solo acepta claves con estos prefijos. | | Red | Su panel debe ser accesible mediante HTTPS desde Internet (Stripe llama al webhook) y debe tener acceso a `api.stripe.com` en el puerto 443. | | Dominio (solo billeteras) | El dominio accesible para los clientes debe servir `/.well-known/apple-developer-merchantid-domain-association` — NexCMP lo hace por usted. | | Dependencias | Ninguno. | ::: info Cuentas compartidas de Stripe NexCMP solo procesa eventos de webhook para pagos creados por él mismo, por lo que puede usar una cuenta de Stripe que también dé servicio a otra aplicación. ::: ## Preparar la infraestructura {#prepare-the-infrastructure} En el lado de Stripe: 1. Inicie sesión en el [Stripe Dashboard](https://dashboard.stripe.com). Active o desactive el **Test mode** para decidir si va a realizar una prueba o pasar a producción. Las claves de un modo nunca funcionan con el otro. 2. Abra **Developers › API keys**. Copie la **Publishable key** y muestre y copie la **Secret key**. Mantenga la clave secreta en privado. 3. (Opcional) Abra **Settings › Payment methods** y active **Alipay** si desea ofrecerlo. 4. **No** es necesario crear el webhook manualmente; NexCMP puede crearlo por usted (consulte el paso 5 a continuación). Si prefiere hacerlo manualmente, cree un endpoint en **Developers › Webhooks** con la URL y los eventos indicados en [Webhook](#webhook). ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. En la tarjeta **API keys** elija el **Mode** (`live` o `test`), pegue la **Secret key** y la **Publishable key**. 3. Haga clic en **Save**. Las claves se guardan en un archivo de configuración en el servidor que solo la cuenta de servicio de NexCMP puede leer. Nunca se devuelven al navegador; posteriormente, la página solo muestra los últimos 4 caracteres. 4. Haga clic en **Check**. Un cuadro de diálogo informa sobre la conexión, el modo, el saldo disponible y pendiente, el ID de cuenta, si los cobros están habilitados, si existe un webhook y si Alipay está disponible. Una línea roja indica que esa parte requiere atención. 5. En la tarjeta **Webhook** haga clic en **Create webhook** y confirme. NexCMP solicita a Stripe que cree el endpoint con todos los eventos requeridos y completa **Webhook signing secret** (`whsec_...`) automáticamente. La URL precargada en el campo es `https:///v1/billing/stripe/webhook`, por ejemplo `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Abra **Fees & limits** (`/payments/fees`), mantenga activado **Card (Stripe)**, configure **Stripe fee %** y **Stripe fixed fee (cents)** con su tarifa real y haga clic en **Save channels & fees**. Consulte [Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Página de Stripe con el modo, la clave secreta y la clave publicable completados con valores de ejemplo](https://nexcmp.com/es/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} El banner rojo "Missing webhook_secret" permanecerá visible hasta que se guarde un signing secret. Sin él, las recargas de Stripe **no se registrarán**, aunque Stripe haya cobrado el dinero. | Elemento | 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` | | Firma | Encabezado `Stripe-Signature` de Stripe, HMAC-SHA256, 300 segundos de tolerancia. Las solicitudes con una firma no válida reciben HTTP 400. | | Idempotencia | Cada ID de evento se almacena una sola vez; un reenvío nunca acreditará dos veces. | Si actualizó desde una versión que registraba menos eventos, haga clic de nuevo en **Create webhook**; el endpoint anterior se conserva, por lo que deberá eliminarlo manualmente en el Stripe Dashboard después. Las filas **24h events** y **Latest event** de la tarjeta Webhook indican si Stripe se está comunicando con el panel. Los eventos individuales se enumeran en **Payment channels › Gateway events** (`/payments/events`, pestaña Stripe), donde cada evento puede visualizarse (**Payload**) o reintentarse (**Replay**). ### Apple Pay, Google Pay y Link {#apple-pay-google-pay-and-link} 1. En la tarjeta **Wallets (Apple Pay · Google Pay · Link) & Alipay**, el campo **Customer app Domain registered with Stripe** se completa automáticamente con el nombre de host de su sitio (por ejemplo, `cloud.example.com`). 2. Haga clic en **Register / verify domain** y confirme. NexCMP registra el dominio en los dominios de métodos de pago de Stripe y solicita a Stripe que lo valide. 3. El resultado muestra el estado de **Apple Pay**, **Google Pay** y **Link**. Apple Pay solo se muestra cuando el estado es `active`. 4. En **Fees & limits**, mantenga activado **Apple Pay · Google Pay · Link**. ![Tarjeta Wallet que muestra el dominio registrado y los estados de Apple Pay, Google Pay y Link](https://nexcmp.com/es/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay permanece inactivo Apple Pay necesita que el archivo de asociación de dominio responda HTTP 200 en su dominio público. Si coloca Cloudflare u otro proxy delante, no bloquee `/.well-known/`. ::: ### Alipay {#alipay} Alipay es opcional. Actívelo en **Stripe Dashboard › Settings › Payment methods**, haga clic en **Check** y espere hasta que el cuadro de diálogo muestre que Alipay está disponible; luego active **Alipay (Stripe, JPY display)** en **Fees & limits**. Configure **Alipay fee %**, **Alipay fixed fee**, la tasa **¥/USD rate** (50–500) y el margen **FX spread %** (0–20). Actualice la tasa ¥/USD periódicamente; la página advierte si tiene más de 7 días. ## Verificación {#verify} 1. En modo de prueba, inicie sesión en el portal como cliente de prueba, abra **Billing**, haga clic en **Deposit**, seleccione **Card** y pague el mínimo con la tarjeta de prueba de Stripe `4242 4242 4242 4242` (cualquier fecha futura, cualquier CVC). 2. El saldo aumenta en cuestión de segundos y el pago aparece en **Finance › Billing › Top-ups** con el estado *Completed*. 3. Abra **Payment channels › Gateway events › Stripe**: debería ver `checkout.session.completed` o `payment_intent.succeeded` con una hora de procesamiento. 4. De vuelta en la página de Stripe, **24h events** es superior a 0. Antes de pasar a producción, cambie **Mode** a `live`, pegue las claves de producción y haga clic en **Create webhook** nuevamente (los webhooks de los modos test y live son independientes). ## Límites y notas {#limits-notes} - **Importes y moneda.** Los monederos están en USD. Los pagos con tarjeta, monedero digital y Link se cobran en USD; Alipay se muestra al cliente en JPY y se convierte según su tasa. - **Comisiones.** La comisión real de Stripe no se vuelve a leer automáticamente; el porcentaje de comisión que configure determina lo que ve el cliente y lo que se acredita en el monedero. Seleccione **Customer pays top-up fee** en *Fees & limits* para cobrar la comisión adicionalmente. - **Tarjetas guardadas.** Cuando el cliente marca *Save card for auto top-up*, la tarjeta se almacena en Stripe, no en su servidor. Consulte [Saved payment methods](https://nexcmp.com/es/docs/billing/saved-payment-methods/). - **Reembolsos.** El reembolso a la tarjeta es un proceso de dos pasos: un administrador crea una solicitud de reembolso para un pago completado (**Finance › Billing › Top-ups**, acción de reembolso en el pago) y luego la aprueba en **Finance › Payouts › Card refunds** (`/billing/payouts`). Los reembolsos de Alipay son asíncronos; si uno falla (`refund.failed`), se devuelve el importe retenido al monedero. - **Disputas.** Ante `charge.dispute.created`, NexCMP bloquea la cuenta del cliente, detiene sus servicios prepagos (no se elimina nada) y envía una alerta al administrador. Si usted gana (`charge.dispute.closed`), el importe se vuelve a acreditar en el monedero. - **Pagos en espera.** Si un webhook nunca llega, NexCMP verifica por sí mismo en Stripe los pagos que hayan permanecido pendientes durante más de 10 minutos y los completa. Los pagos con más de 7 días de antigüedad se ignoran. - Los **Resellers** pueden conectar su propia cuenta de Stripe (webhook `https:///v1/billing/stripe/webhook/r/`); consulte [Resellers](https://nexcmp.com/es/docs/customers/resellers/). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "La clave secreta debe comenzar con sk_live_/sk_test_" | Se pegó una clave incorrecta | Pegue la clave secreta desde **Developers › API keys**. | | "La clave secreta no coincide con el modo live/test" | El modo y la clave no coinciden | Haga que el **Mode** coincida con el prefijo de la clave. | | "La clave publicable debe comenzar con pk_" | Clave incorrecta | Utilice la clave publicable. | | La comprobación indica que la conexión falló | Clave incorrecta, clave revocada o el servidor no puede comunicarse con `api.stripe.com` | Vuelva a pegar la clave; pruebe con `curl -I https://api.stripe.com` desde el servidor. | | Banner rojo "Missing webhook_secret" | El secreto de firma no está guardado | Haga clic en **Create webhook** o pegue el secreto `whsec_...` desde el Stripe Dashboard y pulse **Save**. | | Se cobró el dinero pero el saldo no cambió | Webhook no entregado o firma incorrecta | Compruebe que la URL termine en `/v1/billing/stripe/webhook`, que el secreto coincida con el endpoint y reenvíe el evento en **Gateway events**. En Stripe, abra el endpoint y revise los intentos de entrega (HTTP 400 indica un secreto de firma incorrecto). | | Falla "Create webhook" | La URL no es HTTPS o no es accesible | Utilice su dominio público `https://`. | | El estado de Apple Pay no está activo | Dominio no validado | Haga clic nuevamente en **Register / verify domain** después de que el archivo de asociación de dominio responda 200. | | Alipay no está disponible en el cuadro de diálogo Check | No está activado en Stripe | Actívelo en el Stripe Dashboard y luego haga clic en **Check**. | | El cliente no ve el formulario de tarjeta | **Card (Stripe)** está desactivado o no hay clave secreta | Actívelo en **Fees & limits** y guarde las claves. | --- # PayPal > **Ubicación en el panel:** Finance › Payment channels › PayPal (`/payments/paypal`). El interruptor de activación y las comisiones están en Finance › Payment channels › Fees & limits (`/payments/fees`). ## Qué hace {#what-it-does} Permite a los clientes recargar su monedero en USD con su saldo de PayPal, cuenta bancaria o tarjeta vinculada a PayPal. Los clientes también pueden permitir que NexCMP recuerde su cuenta de PayPal para [recargas automáticas](https://nexcmp.com/es/docs/billing/auto-top-up/). Utilícelo junto con [Stripe](https://nexcmp.com/es/docs/billing/stripe/) para aquellos clientes que prefieran PayPal. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta de PayPal | Una cuenta PayPal **Business** que pueda recibir USD. | | App REST | Una app REST en el PayPal Developer Dashboard (**Apps & Credentials**) que proporcione un **Client ID** y un **Client secret**. Utilice la pestaña **Sandbox** para pruebas y **Live** para producción. | | Red | HTTPS accesible desde Internet (PayPal invoca el webhook) y acceso saliente a `api-m.paypal.com` (live) o `api-m.sandbox.paypal.com` (sandbox), puerto 443. | | Permisos | La app REST necesita los permisos de reembolsos y webhooks. El cuadro de diálogo **Check** muestra si ambos ámbitos están presentes. | | Dependencias | Ninguno. | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Inicie sesión en [developer.paypal.com](https://developer.paypal.com) con su cuenta Business y abra **Apps & Credentials**. 2. Seleccione **Sandbox** (pruebas) o **Live** y luego haga clic en **Create App**. Asígnele un nombre como, por ejemplo, "NexCMP". 3. Copie el **Client ID** y el **Secret** de la app. 4. Para realizar pruebas, utilice **Testing Tools › Sandbox Accounts** para buscar o crear una cuenta de sandbox *Personal* (comprador). 5. No es necesario que cree el webhook usted mismo; NexCMP lo crea con el botón **Create webhook**. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. En **API keys**, elija **Mode**: `live` (dinero real, `api-m.paypal.com`) o `sandbox` (`api-m.sandbox.paypal.com`). 3. Pegue el **Client ID** (al menos 20 caracteres) y el **Client secret**. 4. Haga clic en **Check**. Comprueba las credenciales introducidas (no es necesario guardar) e informa sobre la conexión, el App ID, el modo, si los permisos de reembolso y webhooks están presentes y la duración del token. 5. Haga clic en **Save**. 6. En la tarjeta **Webhook**, confirme que la URL sea `https:///v1/billing/paypal/webhook` (debe ser `https`), luego haga clic en **Create webhook** y confirme. NexCMP solicita a PayPal crear o actualizar el webhook con 11 eventos y almacena el **Webhook ID** devuelto. El botón utiliza las claves **guardadas** — guarde primero si acaba de editarlas. 7. Haga clic en **Check** de nuevo: la fila **Webhook** debe indicar "exists, 11 events". 8. Abra **Fees & limits**, active **PayPal**, configure **PayPal fee %** (predeterminado 4.4) y **PayPal fixed fee (cents)** (predeterminado 30) según su tarifa y haga clic en **Save channels & fees**. ![Página de PayPal con el modo sandbox y credenciales de ejemplo introducidas](https://nexcmp.com/es/docs/images/billing/paypal-01-keys.webp) ### Eventos de webhook {#webhook-events} NexCMP registra estos 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 se verifica llamando a la API de verificación de firma de PayPal, se almacena una vez y se procesa de forma idempotente. NexCMP nunca confía en el importe del cuerpo del webhook: antes de acreditar una captura, la consulta directamente en PayPal. ## Verificación {#verify} 1. Mantenga **Mode** en `sandbox`. En el portal, abra **Billing › Deposit**, elija **PayPal**, haga clic en **Continue on PayPal** (o en el botón de PayPal) e inicie sesión con la cuenta de comprador de sandbox. 2. Apruebe el pago. Regresará al portal, el saldo aumentará y el pago aparecerá en **Finance › Billing › Top-ups** como *Completed*. 3. Abra **Payment channels › Gateway events › PayPal & USDT**: el evento `PAYMENT.CAPTURE.COMPLETED` aparecerá listado. 4. Cuando todo funcione, cambie **Mode** a `live`, introduzca las credenciales reales, haga clic en **Save** y luego en **Create webhook** de nuevo (los webhooks de sandbox y producción son independientes). ## Límites y notas {#limits-notes} - **Cómo se completa un pago.** La orden se crea en USD; una vez que el cliente la aprueba, el **servidor** la captura (con un ID de solicitud idempotente) y acredita el saldo exactamente una vez. El webhook y una tarea de conciliación que se ejecuta cada 10 minutos actúan como red de seguridad si el cliente cierra el navegador. - **Órdenes pendientes y abandonadas.** Una orden puede permanecer abierta durante 12 horas. Un cliente puede tener como máximo 5 órdenes pendientes (el servidor responde `too_many_pending`, HTTP 429). Una orden que siga sin capturarse tras 24 horas se marca como fallida. - **Sin webhook configurado.** El panel responde HTTP 503 a cada webhook de PayPal hasta que se guarde un Webhook ID. Las capturas realizadas a través del portal y la conciliación cada 10 minutos siguen acreditando el saldo, pero nada de lo que PayPal notifique por webhook (disputas, reversiones, capturas tardías) se aplicará — haga clic en **Create webhook**. - **Cuenta de PayPal guardada.** Cuando el cliente elige guardar PayPal (o completa el primer depósito, lo que activa [automatic top-up](https://nexcmp.com/es/docs/billing/auto-top-up/)), PayPal almacena el token de pago en su bóveda. NexCMP solo conserva un identificador y el correo electrónico de PayPal. Consulte [Saved payment methods](https://nexcmp.com/es/docs/billing/saved-payment-methods/). - **Los reembolsos y las disputas** se gestionan como en Stripe: las solicitudes de reembolso se aprueban en **Finance › Payouts › Card refunds**; una disputa bloquea la cuenta del cliente y suspende sus servicios prepago hasta que usted la resuelva. - **Comisiones.** La comisión de PayPal no se consulta automáticamente; el porcentaje y la comisión fija que configure determinan lo que ve el cliente y lo que se le acredita. La tarifa real depende de su país (el formulario sugiere un 4.4 % para Vietnam y un 3.49 % para EE. UU.). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Client ID demasiado corto" | Se pegaron menos de 20 caracteres | Copie el Client ID completo. | | "La URL del webhook debe ser https" | URL introducida con `http://` | Utilice su dominio público `https://`. | | Check reporta un error de conexión | Modo incorrecto (claves live en sandbox o viceversa), secret erróneo o sin acceso saliente | Haga coincidir **Mode** con el tipo de clave; pruebe `curl -I https://api-m.paypal.com` desde el servidor. | | El scope refund / webhooks muestra "no" | La aplicación REST carece de estas funciones | Habilite las funciones en la aplicación dentro del PayPal Developer Dashboard. | | Banner "Clave de PayPal configurada, SIN webhook" | Falta el Webhook ID | Haga clic en **Create webhook**. | | "Webhook not found" en Check | El webhook se eliminó en PayPal o pertenece a otra aplicación | Haga clic de nuevo en **Create webhook**. | | El cliente recibe el aviso de que PayPal rechazó el pago | PayPal rechazó esa fuente de fondos | Pida al cliente que elija otra fuente de pago. | | El cliente ve "Too many pending requests" | 5 órdenes abiertas | Espere a que caduquen o complételas. | | No aparece el botón de PayPal | PayPal está desactivado en **Fees & limits** o no está configurado | Actívelo y guarde las credenciales. | --- # USDT (Binance) {#usdt-binance} > **Ubicación en el admin:** Finance › Payment channels › USDT (`/payments/usdt`). Activación y comisión: Finance › Payment channels › Fees & limits (`/payments/fees`). Depósitos no coincidentes: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## Qué hace {#what-it-does} Los clientes envían USDT a **su dirección de depósito de Binance**; NexCMP lee el historial de depósitos mediante una API key de Binance de **solo lectura** y acredita el saldo cuando un depósito coincide con una solicitud abierta. Por su parte, no hay comisiones de pasarela de pago salvo las que cobra Binance, y NexCMP nunca almacena claves privadas. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta de Binance | Una cuenta verificada de Binance con depósitos de USDT habilitados en la red que elija. | | API key | Una API key de Binance con **Enable Reading** únicamente. Enable Withdrawals, Internal Transfer y Spot/Margin Trading deben estar **desactivados**. | | Restricción de IP | Muy recomendado: restrinja la clave a la IP saliente del servidor (el cuadro de diálogo **Test & verify address** la muestra). | | Red | HTTPS saliente hacia `api.binance.com`. No se necesita ningún puerto entrante. | | Redes compatibles | `TRX` (Tron, TRC20), `BSC` (BNB Smart Chain, BEP20), `SOL` (Solana), `ETH` (Ethereum, ERC20). La moneda está fijada en USDT. | | Dependencias | Ninguno. | ::: warning Elija la red una sola vez Los clientes que envían fondos por la red equivocada los pierden. Elija una red con tarifas bajas y compatible con los exchanges de sus clientes (TRX y BSC suelen ser las opciones habituales) y evite cambiarla con frecuencia. ::: ## Preparar la infraestructura {#prepare-the-infrastructure} 1. En Binance, abra **Account › API Management** y cree una nueva API key (generada por el sistema). Asígnele una etiqueta como "NexCMP". 2. Edite los permisos: deje marcada únicamente la opción **Enable Reading**. No habilite retiros, transferencias ni trading. 3. En **Restrict access to trusted IPs only**, añada la dirección IP pública de su servidor NexCMP. Si aún no la conoce, cree la clave sin la restricción, ejecute la primera prueba en NexCMP (mostrará la IP saliente) y luego añada la IP. 4. Copie la **API key** y la **Secret key** (el secreto solo se muestra una vez). 5. Abra **Wallet › Deposit › Crypto**, elija **USDT** y la **red** que utilizará, y copie la **dirección de depósito** (por ejemplo, una dirección `T...` en TRX o `0x...` en BSC/ETH). ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › USDT** (`/payments/usdt`). 2. En **API key (Binance › API Management)**, pegue la **API key** y el **API secret**. Ambos deben introducirse juntos. 3. En **Deposit address**, elija la **Network** y pegue la **dirección de depósito de USDT en la red seleccionada**. El formato se valida según la red (`T` + 33 caracteres para TRX, `0x` + 40 caracteres hexadecimales para BSC y ETH, base58 para SOL). 4. Haga clic en **Save**. Cambiar la dirección o la red restablece la verificación y pausa el canal hasta que vuelva a verificarlo; la página le pedirá confirmación. 5. Haga clic en **Test & verify address**. (Los cambios no guardados se rechazan; la comprobación se ejecuta sobre la configuración guardada). El cuadro de diálogo muestra: - los permisos de la clave (lectura, retiros, transferencias internas, trading, restricción de IP), con advertencias en rojo para permisos peligrosos; - la IP saliente del servidor (para introducirla en Binance); - la red (depósitos abiertos o cerrados, confirmaciones requeridas, dust); - la dirección que Binance asigna a esa red y si **coincide** con la suya. 6. Cuando la dirección coincide, NexCMP registra la hora de verificación. Solo entonces podrá abrir **Fees & limits**, activar **USDT (Binance)**, revisar **USDT fee %** (por defecto 1) y **USDT request expires after (mins)** (5–180, por defecto 30), y hacer clic en **Save channels & fees**. ## Cómo se concilia un pago {#how-a-payment-is-matched} 1. El cliente introduce un importe en **Billing › Deposit › USDT** y hace clic en **Get deposit address**. 2. NexCMP crea una solicitud y muestra la dirección, la red y un **importe exacto** con seis decimales (por ejemplo, `19.173742`). Los últimos cuatro decimales son un nonce aleatorio que hace que el importe sea único para esa solicitud. 3. El cliente debe enviar **exactamente** ese importe en esa red. Un pago que no coincida (importe redondeado, red incorrecta) no se puede asignar automáticamente. 4. Cada 60 segundos, NexCMP consulta los depósitos de Binance de las últimas 24 horas. Un depósito coincidente cambia la solicitud a *confirming* y, una vez que Binance alcanza las confirmaciones necesarias, acredita el saldo. Una solicitud que ha recibido fondos nunca caduca mientras las confirmaciones estén pendientes. 5. Una solicitud no pagada dentro del tiempo de expiración (por defecto 30 minutos) se marca como caducada. ## Verificación {#verify} 1. Una vez verificada la dirección y activado USDT, inicie sesión como cliente de prueba y solicite un depósito pequeño (la recarga mínima). 2. Envíe el importe exacto desde otra billetera o exchange. Espere unos minutos. 3. El portal muestra *Transfer seen — confirming* y luego *USDT received — balance updated*. 4. La página de USDT muestra una hora reciente de **Last poll** y **Unmatched** en 0. ## Límites y notas {#limits-notes} - **Tasa.** 1 USDT = 1.00 USD. La comisión en **USDT fee %** se muestra al cliente y se deduce del importe o se añade a él según el ajuste de **Customer pays top-up fee**. - **Sin reembolsos.** NexCMP nunca reembolsa pagos en USDT al origen (HTTP 409 `usdt_no_refund`). Reembolse manualmente fuera del sistema si es necesario. - **Límite de pendientes.** El cliente tiene un límite de solicitudes abiertas; si lo supera, el servidor responde `too_many_pending` (HTTP 429). - Los **Resellers** pueden usar su propia cuenta de Binance; consulte [Resellers](https://nexcmp.com/es/docs/customers/resellers/). - **Si comparte la cuenta de Binance** con otro sistema, asigne a cada sistema una red diferente para que dos procesos de sondeo nunca vean el mismo depósito. ### Depósitos sin coincidencia {#unmatched-deposits} Un depósito que no coincida con ninguna solicitud (importe incorrecto, red incorrecta, solicitud vencida) crea un evento `deposit.unmatched` y una alerta de administración. Abra **Payment channels › Gateway events › PayPal & USDT**, busque el evento, verifique la transacción en Binance y haga clic en la acción de asignación para acreditar al cliente correcto. El contador **Unmatched** en la página de USDT y en la vista general de canales pasará a 0 después. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "La API key y el secret deben introducirse juntos" | Solo se completó un campo | Complete ambos. | | "La dirección no tiene el formato de la red ..." | La dirección no coincide con la red seleccionada | Cópiela de nuevo desde Binance para la misma red. | | "Cambios sin guardar — Guarde primero y luego pruebe" | La prueba se ejecuta con la configuración guardada | Haga clic en **Save** y luego pruebe. | | Advertencia "la clave tiene Enable Withdrawals" | Permiso excesivo | Elimínelo en Binance API Management. | | Advertencia "la clave no está restringida a IP" | `ipRestrict` está desactivado | Añada la IP de salida del servidor que se muestra en el cuadro de diálogo. | | Advertencia "la clave no tiene Enable Reading" | Falta el permiso | Habilite Enable Reading. | | Advertencia "Binance tiene los depósitos deshabilitados para USDT en la red" | Red suspendida | Elija otra red o espere. | | "PELIGRO: la dirección configurada difiere de la dirección que emite Binance" | Dirección o red incorrecta | Copie de nuevo la dirección desde Binance para esa red. | | Interruptor de USDT atenuado en Fees & limits | Dirección no verificada | Ejecute **Test & verify address** hasta que coincida. | | El cliente pagó, no se acreditó nada | Importe redondeado o red incorrecta | Busque el evento en Gateway events y asígnelo manualmente. | | Depósito detectado pero en espera durante mucho tiempo | Aún no hay suficientes confirmaciones | Espere; la solicitud no caduca mientras se confirma. | --- # Transferencia bancaria (Vietnam) {#bank-transfer-vietnam} > **Ubicación en administración:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Tipo de cambio: Finance › Payment channels › Exchange rates (`/payments/fx`). ## Qué hace {#what-it-does} Permite a los clientes recargar el monedero en USD mediante una transferencia bancaria normal en dongs vietnamitas. NexCMP muestra un código VietQR, los datos de la cuenta y un **memo de transferencia** único; [Sepay](https://sepay.vn) supervisa su cuenta bancaria y llama a un webhook cuando llega el dinero, y NexCMP acredita el saldo en el monedero. Utilícelo si vende a clientes en Vietnam. ::: info Se muestra solo en la interfaz en vietnamita La opción de VN bank solo se ofrece al cliente cuando el portal se muestra en **Vietnamese**. Los clientes en cualquier otro idioma nunca la ven. ::: ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta bancaria | Una cuenta bancaria vietnamita (o una cuenta virtual de Sepay, **VA**) conectada a una cuenta de Sepay en [my.sepay.vn](https://my.sepay.vn). | | Sepay | Una cuenta de Sepay con la integración de webhook habilitada. | | Tipo de cambio | Debe existir un tipo de cambio de USD a VND: actualícelo primero en **Exchange rates**. Sin un tipo de cambio, el canal responde `fx_unavailable` y los clientes no pueden iniciar una transferencia. | | Red | Su panel debe ser accesible mediante HTTPS para que Sepay pueda llamar a `https:///v1/billing/sepay/webhook`. | | Dependencias | [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). | ## Preparar la infraestructura {#prepare-the-infrastructure} En el lado de Sepay: 1. En [my.sepay.vn](https://my.sepay.vn), conecte su cuenta bancaria (o cree una VA) y asegúrese de que aparezcan las transacciones. 2. Defina el **prefijo del memo**: de 2 a 5 letras mayúsculas, por ejemplo `PAY`. NexCMP genera el memo como el prefijo seguido de 8 dígitos aleatorios (por ejemplo `PAY48210937`). El prefijo no debe contener `ORD` y no debe ser utilizado por ningún otro sistema que reciba dinero en la misma cuenta. 3. Si su cuenta de Sepay utiliza una *estructura de códigos de pago*, registre allí el mismo prefijo para que Sepay reconozca el memo. 4. Cree el webhook más tarde, después de que la página de NexCMP le haya proporcionado la URL y la clave (paso 7 a continuación). ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › Exchange rates** y haga clic en **Update exchange rates** si no se ha guardado ningún tipo de cambio. 2. Abra **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. En **Receiving account**, complete: | Campo | Ejemplo | Regla | |---|---|---| | Banco | `VCB` Vietcombank | Seleccione de la lista; el BIN se completa automáticamente. | | Número de cuenta | `0123456789` | De 4 a 24 dígitos o letras mayúsculas. | | Cuenta virtual (VA: opcional) | | Si se define, los clientes transfieren a la VA y el QR la muestra. | | Nombre del titular de la cuenta | `NGUYEN VAN A` | Sin acentos, MAYÚSCULAS, de 2 a 60 caracteres. | | Prefijo del memo de transferencia | `PAY` | De 2 a 5 letras mayúsculas, sin `ORD`. | 4. En **Webhook authentication**, elija **Auth method**: **HMAC-SHA256** (recomendado) o **API key**, e introduzca la **Webhook key / HMAC secret** (8–200 caracteres). De forma opcional, introduzca el **userapi token** de Sepay; solo se utiliza para conciliar transferencias cuyo webhook se haya perdido. 5. En **Channel & limits**, establezca los límites (valores por defecto entre paréntesis): **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) y, opcionalmente, **Allowed webhook IPs** (separadas por comas; en blanco significa que la IP solo se registra). 6. Haga clic en **Save**. El banner rojo «Sepay not configured» desaparecerá una vez que la cuenta, el nombre, el prefijo y la clave sean válidos. 7. Copie la **URL del webhook para pegar en my.sepay.vn** (muestra `https:///v1/billing/sepay/webhook`) con **Copy**. En SePay abra la integración de webhook, pegue la URL, elija el mismo tipo de autenticación y clave, y active el evento "money in". 8. Haga clic en **Test connection**. Luego active **Enable Sepay for clients (main site)** y haga clic en **Save**. ![Página de VN bank transfer con la cuenta receptora, el prefijo del memo y la autenticación de webhook completados con valores de ejemplo](https://nexcmp.com/es/docs/images/billing/bank-transfer-vn-01-config.webp) ![Tarjeta de canal y límites con el interruptor de Sepay activado y los límites predeterminados](https://nexcmp.com/es/docs/images/billing/bank-transfer-vn-02-limits.webp) ### Seguridad del webhook {#webhook-security} | Método | Qué debe enviar Sepay | |---|---| | HMAC-SHA256 | Encabezado `X-SePay-Signature: sha256=`, calculado sobre `"."`; la marca de tiempo puede diferir en 300 segundos como máximo. | | API key | Encabezado `Authorization: Apikey `. | Solo se comprueban los encabezados (nunca el cuerpo ni la cadena de consulta) y la comparación se realiza en tiempo constante. Solo se utilizan las transferencias entrantes (`transferType = in`) a su cuenta configurada o VA. Cada transacción de Sepay se almacena una sola vez, por lo que un webhook reintentado nunca acredita dos veces. NexCMP responde `200 {"success":true}` incluso cuando ignora deliberadamente una transacción, y HTTP 5xx solo ante errores temporales para que Sepay vuelva a intentarlo. ## Cómo paga el cliente {#how-the-customer-pays} 1. En **Billing › Deposit** (interfaz en vietnamita), el cliente elige la opción de transferencia bancaria VN y un importe, y luego hace clic en el botón para crear la transferencia. 2. NexCMP convierte el importe en USD al tipo de cambio almacenado (incluidos el margen y el paso de redondeo configurados en **Exchange rates**) y **redondea el importe en VND hacia arriba** según el paso de redondeo. 3. El cliente ve un código QR (VietQR, generado localmente) con el número de cuenta, el banco, el importe y el memo. 4. Tras la transferencia, Sepay llama al webhook y NexCMP acredita `floor(VND received × 100 / rate)` centavos. El tipo de cambio se fija al crear el pedido; si el dinero llega después de que el pedido haya caducado, se utiliza el mayor entre el tipo de cambio fijado y el actual. 5. Los pedidos caducan transcurrido el tiempo de **Order expiry**; la conciliación se ejecuta cada **Reconcile every** minutos como red de seguridad (requiere el token de userapi). ## Verificación {#verify} 1. Cree un pedido de prueba como cliente en la interfaz en vietnamita. Compruebe que el importe, la cuenta y el memo sean correctos. 2. Transfiera el importe mínimo permitido con el memo exacto. 3. En cuestión de un minuto, el portal muestra el depósito como completado y el saldo del monedero aumenta; la tarjeta **State** de la página del banco muestra la hora del último webhook. 4. Abra **Finance › Billing › Top-ups** y compruebe que el pago aparezca en la lista con el importe recibido en VND. ## Límites y notas {#limits-notes} - **Mínimo.** El mínimo en VND que ve un cliente es el mayor entre **Min / order** y el valor en VND de la [recarga mínima](https://nexcmp.com/es/docs/billing/minimum-top-up/). - **Pedidos pendientes.** Un cliente solo puede tener **Max pending orders / account** pedidos abiertos (por defecto, 3). - **Mismo memo dos veces.** Transferir dos veces con el mismo memo crea un segundo pago completado al tipo de cambio actual. - **Sin reembolso automático** a una cuenta bancaria. - **Comisión.** El canal no dispone de una línea de comisión fija en **Fees & limits**; el margen del tipo de cambio es el único ajuste. - **Resellers** pueden configurar su propia cuenta; su URL de webhook termina en `/v1/billing/sepay/webhook/r/`. ### Transferencias no coincidentes {#unmatched-transfers} El dinero que llega a la cuenta pero no incluye un memo válido aparece en **Unmatched transactions** en la parte inferior de la página (filtre por *All channel owners* o *Master*). Compruebe la referencia bancaria con el cliente, haga clic en **Assign** y seleccione la cuenta. El monedero se acredita al tipo de cambio actual. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Banner "Sepay no configurado" | Falta o no es válido el banco, la cuenta, el nombre del titular, el prefijo o la clave | Complete las tarjetas **Receiving account** y **Webhook authentication**. | | Banner "Tipo de cambio USD/VND bloqueado" (`fx_unavailable`) | No hay ningún tipo de cambio almacenado | **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | Prefijo no válido | Utilice de 2 a 5 letras mayúsculas sin `ORD`. | | Error `account_name` | Acentos o minúsculas | Utilice letras MAYÚSCULAS sin acento, dígitos, espacio, punto o guion. | | `webhook_secret: 8–200 characters` | Clave demasiado corta | Utilice al menos 8 caracteres imprimibles. | | El cliente no puede ver la opción | No está en la interfaz en vietnamita, interruptor apagado o sin tasa de cambio | Compruebe el idioma, el interruptor y la tasa de cambio. | | El cliente pagó pero no se acreditó nada | El webhook no llegó, el memo cambió o el importe es incorrecto | Compruebe el registro de webhooks de Sepay; la transferencia aparecerá en **Unmatched transactions** si el memo era incorrecto. | | El webhook devuelve 401 o 403 | Discrepancia en el método de autenticación o la clave | Use el mismo método y clave en Sepay y NexCMP. | | El cliente ve "Too many pending requests" | Se alcanzó el límite de pedidos pendientes | Deben completarse o esperar a que expiren. | --- # Recarga mínima {#minimum-top-up} > **Ubicación en el panel de administración:** Finance › Payment channels › Fees & limits (`/payments/fees`), tarjeta **Wallet & top-up (Billing › Policy)**. ## Qué hace {#what-it-does} Cada canal de pago rechaza cualquier importe inferior a la **recarga mínima** o superior a la **recarga máxima por transacción**. Los valores predeterminados son **$10.00** y **$5,000.00**. Utilice el mínimo para evitar pagos diminutos cuyas comisiones de pasarela superen su valor. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Dependencias | Ninguno. | ## Establecer los límites {#set-the-limits} 1. Abra **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. En la tarjeta **Wallet & top-up (Billing › Policy)**, edite **Min top-up (USD)** y **Max top-up per transaction (USD)**. 3. Haga clic en **Save Wallet & top-up**. ![Tarjeta Wallet & top-up con la recarga mínima de 10.00 y la máxima de 5000.00](https://nexcmp.com/es/docs/images/billing/minimum-top-up-01-limits.webp) | Ajuste | Predeterminado | Rango permitido | Regla | |---|---|---|---| | Min top-up (USD) | $10.00 | De $0 a $10,000 | Debe ser menor o igual que el máximo. | | Recarga máxima por transacción (USD) | $5,000.00 | De $1 a $1,000,000 | Debe ser al menos el mínimo. | Los valores se almacenan en centavos (`min_topup_cents`, `max_topup_cents`). ## Dónde se aplican los límites {#where-the-limits-apply} | Lugar | Comportamiento | |---|---| | Card, Apple/Google Pay, Link, Alipay, PayPal, USDT | El servidor rechaza los importes fuera del rango. El portal muestra "Enter an amount between {min} and {max}". | | Transferencia bancaria de VN | El importe en VND debe estar dentro de los límites de Sepay **y** su valor en USD (lo que recibe el monedero) dentro del mínimo y el máximo. El portal muestra el mayor de los dos mínimos en VND. Consulte [Transferencia bancaria (Vietnam)](https://nexcmp.com/es/docs/billing/bank-transfer-vn/). | | [Recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/) | Cada cargo automático es como mínimo el importe mínimo y como máximo el máximo. En modo fijo, el importe del cliente debe estar entre el mínimo y $1,000. | | Códigos de recarga ([Vouchers](https://nexcmp.com/es/docs/billing/promotions/)) | No se ve afectado. | | Crédito / débito de administrador | No se ve afectado. | | Recarga de saldo del revendedor | Un mínimo independiente (`rs_topup_min_cents`, predeterminado $20) en Resellers › Defaults. | ## Límites mínimos relacionados {#related-floors} La recarga mínima no es la única regla de saldo. Estas se encuentran en **Services › Virtual Machines › Policy** (`/vm/policy`): | Regla | Predeterminado | Significado | |---|---|---| | Saldo mínimo (`min_balance_cents`) | $5.00 | El saldo mínimo en el monedero que necesita un cliente para crear una VM. | | Cuotas | Desactivado | Cuando **Quotas** está activado, para crear una VM también se necesita un saldo que cubra una cantidad de horas de esa VM. Consulte [Quotas](https://nexcmp.com/es/docs/billing/quotas/). | ## Verificación {#verify} 1. En el portal, abra **Billing › Deposit** e introduzca un importe justo por debajo de su mínimo. El botón de pago queda deshabilitado y aparece el mensaje de rango. 2. Introduzca el importe mínimo y confirme que el pago comience. ## Límites y notas {#limits-notes} - Los cambios se aplican a los nuevos pagos. Los pedidos ya creados conservan los importes con los que se generaron. - La indicación visible para el cliente ("Minimum $10.00, maximum $5,000.00") y los botones de importe rápido se ajustan automáticamente a los nuevos límites. - Si muestra VND (la página **Exchange rates**), el mínimo se convierte a la tasa guardada solo a efectos de visualización; el monedero y los límites permanecen en USD. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "La recarga mínima debe ser menor o igual que la máxima" | Valores invertidos | Reduzca el mínimo o aumente el máximo. | | El cliente no puede pagar un importe pequeño mediante transferencia bancaria VN | El mínimo en VND de SePay o el mínimo en USD es superior | Reduzca **Min / order** en la página del banco o el mínimo en USD. | | Error del servidor `invalid_argument` en una recarga | Importe fuera del rango | Solicite un importe dentro del rango mostrado. | --- # Métodos de pago guardados {#saved-payment-methods} > **Ubicación en el portal:** Billing › Settings (`/billing?settings=1`). **Ubicación en el admin:** Customers › List › a customer › Overview (`/customers/`), tarjeta **Payment**, muestra el método guardado y el historial de recargas automáticas. ## Qué hace {#what-it-does} Un método de pago guardado permite a NexCMP cobrar a un cliente **sin que esté presente**, de modo que sus servicios nunca se interrumpan por falta de saldo en el monedero. Se utiliza únicamente para la [recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/). Existen dos tipos: una **tarjeta** guardada en Stripe (incluidas las tarjetas utilizadas mediante Apple Pay, Google Pay o Link cuando Stripe devuelve una tarjeta reutilizable) y una **cuenta de PayPal** guardada en el vault de PayPal. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Canales | [Stripe](https://nexcmp.com/es/docs/billing/stripe/) y/o [PayPal](https://nexcmp.com/es/docs/billing/paypal/) configurados y habilitados. | | Sitio | El sitio principal, o un sitio de revendedor cuyo canal de pago es cobrado por la plataforma. Un sitio de revendedor que utiliza su propia cuenta de Stripe no puede guardar tarjetas. | | Cliente | Una cuenta de cliente que haya realizado una recarga con tarjeta o PayPal. | ## Cómo se guarda un método {#how-a-method-gets-saved} 1. El cliente abre **Billing**, hace clic en **Deposit** y paga con **Card** o **PayPal**. 2. El pago se crea de modo que el método pueda reutilizarse más adelante: Stripe guarda la tarjeta asociada al cliente en Stripe (uso off-session) y PayPal almacena un token del vault. NexCMP solo conserva referencias (un ID de método de pago y un ID de cliente de Stripe, o el vault ID de PayPal) y una etiqueta visible como `visa •••• 4242` o el correo electrónico de PayPal. **Los números de tarjeta nunca tocan su servidor.** 3. Al completarse el pago, la [recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/) se activa una vez si el cliente no había definido su configuración previamente. No hay ninguna casilla adicional ni mensaje en pantalla. El servidor registra la hora, la dirección IP del cliente y el método como constancia. 4. La próxima vez, la pantalla de depósito ofrecerá **Saved card ...** en el desplegable de tarjetas y **Saved PayPal ...** para PayPal. ## Administrar y eliminar {#manage-and-remove} 1. En el portal, vaya a **Billing** y haga clic en **Settings**. El panel muestra los métodos guardados (tarjeta de Stripe y/o PayPal) y las opciones de recarga automática. 2. Para eliminar una tarjeta, haga clic en **Remove card** y confirme. Stripe desvincula la tarjeta y **se desactiva la recarga automática**. 3. Para eliminar PayPal, haga clic en **Remove saved PayPal** y confirme. ### Vista de administración {#admin-view} Abra el cliente en **Customers › List**. La tarjeta **Payment** de la pestaña **Overview** muestra las etiquetas del método guardado (**Saved cards**), la pasarela utilizada para los cargos automáticos, el registro de consentimiento almacenado (hora, IP, método) y los últimos 20 intentos de cargo automático con su estado y motivo (**Auto top-up history**). ## Verificación {#verify} 1. Como cliente de prueba, deposite el mínimo con tarjeta. Una vez completado el pago, abra **Billing › Settings**: la tarjeta y el interruptor de recarga automática (activado) serán visibles. 2. Inicie otro depósito: el menú desplegable ofrecerá la tarjeta guardada. 3. En la administración, la tarjeta **Payment** del cliente muestra la misma etiqueta de tarjeta. ## Límites y notas {#limits-notes} - **Stripe Link y wallets.** Link, Apple Pay y Google Pay son funciones de Stripe. NexCMP no almacena nada específico de Link; solo conserva la referencia de la tarjeta devuelta por Stripe. - **PayPal.** Cada recarga por PayPal iniciada por el cliente requiere un clic; el PayPal guardado solo se utiliza para la recarga automática, nunca para otras funciones. - **Sitios de revendedores.** Si un revendedor utiliza su propia cuenta de Stripe o PayPal, los métodos guardados se ocultan y la recarga automática no está disponible para ese sitio. - **Disputas.** Una disputa en cualquier pago bloquea la cuenta y detiene sus servicios prepagados; consulte [Stripe](https://nexcmp.com/es/docs/billing/stripe/). - **Eliminar el último método** desactiva la recarga automática; el cliente conserva el saldo del monedero. - **Evidencia.** El registro de consentimiento lo genera el servidor (no es editable por el cliente) y se conserva para la gestión de disputas. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El cliente no ve el botón Settings ni la tarjeta guardada | El sitio utiliza un canal de pago propio del revendedor o aún no se ha realizado ningún pago con tarjeta | Realice una recarga con tarjeta o PayPal a través del canal de la plataforma. | | Falta "Saved card" tras un pago con Stripe | El pago se realizó con un método que no se puede reutilizar (por ejemplo, Alipay) | Pague de nuevo con tarjeta. | | PayPal: "no se puede guardar esta cuenta todavía" | PayPal no devolvió un token de vault | Continúe con un pago único o pruebe con otra cuenta de PayPal. | | La recarga automática se detuvo tras eliminar la tarjeta | Comportamiento esperado: eliminar la tarjeta la desactiva | Guarde un nuevo método con el siguiente depósito. | --- # Recarga automática {#auto-top-up} > **En la administración:** Finance › Payment channels › Fees & limits (`/payments/fees`), tarjeta **Wallet & top-up (Billing › Policy)**, sección **Auto top-up (Stripe / PayPal)**. **En el portal:** Billing › Settings (`/billing?settings=1`). ## Qué hace {#what-it-does} Cuando el saldo del monedero de un cliente es demasiado bajo, NexCMP realiza un cargo en su [método de pago guardado](https://nexcmp.com/es/docs/billing/saved-payment-methods/) y abona el saldo en el monedero, evitando que los servicios activos se suspendan por falta de fondos. Una tarea en segundo plano revisa a todos los clientes habilitados **cada 5 minutos**. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Canal | [Stripe](https://nexcmp.com/es/docs/billing/stripe/) y/o [PayPal](https://nexcmp.com/es/docs/billing/paypal/) configurados. | | Método guardado | El cliente tiene una tarjeta o cuenta de PayPal guardada. | | Sitio | Sitio principal, o sitio de revendedor cuyo canal de Stripe/PayPal es recaudado por la plataforma. | | Interruptor global | **Auto top-up enabled** está activado (activado por defecto). | ## Cómo funciona {#how-it-works} Tras la **primera recarga con Stripe o PayPal** de un cliente, el servidor guarda el método de pago y activa la recarga automática en modo **By usage**, únicamente si dicho cliente nunca la configuró por sí mismo. No hay ninguna casilla adicional en la pantalla de depósito; el servidor registra la fecha y hora, la dirección IP y el método como prueba. Si el cliente desactiva la recarga automática más adelante, nunca se volverá a activar por sí sola. | Modo | Activador (cuando el saldo es inferior a...) | Importe cobrado | |---|---|---| | **By usage** (predeterminado tras la primera recarga) | el coste de las próximas 24 horas de servicios en ejecución (VM por horas más renovaciones prepagadas que vencen en 24 horas), pero nunca inferior a **$5** | el coste de 24 horas redondeado al alza al dólar entero, como mínimo la [recarga mínima](https://nexcmp.com/es/docs/billing/minimum-top-up/), como máximo la recarga máxima y el límite diario | | **Fixed amount** | el umbral configurado por el cliente ($1 a $500) | el importe configurado por el cliente (desde la recarga mínima hasta $1,000, y mayor que el umbral) | Si no hay ningún servicio en ejecución en el modo **By usage**, no se cobra nada. El saldo comparado con el umbral es el **dinero real en el monedero**. Los créditos de servicio procedentes de códigos promocionales se guardan por separado y no cuentan (consulte [Promotions](https://nexcmp.com/es/docs/billing/promotions/)). La comisión se gestiona como en una recarga normal: con **Customer pays top-up fee** activado, se cobra en la tarjeta el importe más la comisión y el monedero recibe el importe íntegro; con esta opción desactivada, el monedero recibe el importe menos la comisión. ## Configurar los límites globales {#configure-the-global-limits} 1. Abra **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. En **Auto top-up (Stripe / PayPal)** configure: | Ajuste | Predeterminado | Rango | Significado | |---|---|---|---| | Auto top-up enabled | On | activado o desactivado | Off detiene inmediatamente todos los cobros en segundo plano. | | Umbral predeterminado de recarga automática (USD, respaldo en modo fijo) | $5.00 | De $0 a $10,000 | Se utiliza únicamente como umbral inicial en el modo fijo. | | Máximo de recargas automáticas cada 24 h por cliente | 3 | 1 a 50 | Contabiliza los intentos correctos y pendientes. | | Límite de importe de recarga automática cada 24 h por cliente (USD) | $500.00 | $0 a $1,000,000 | Total de cobros automáticos en un período móvil de 24 horas. | 3. Haga clic en **Save Wallet & top-up**. ![Sección Auto top-up de la página Fees and limits con el interruptor global y los límites diarios](https://nexcmp.com/es/docs/images/billing/auto-top-up-01-limits.webp) ## Lo que ve el cliente {#what-the-customer-sees} 1. En el portal, el cliente abre **Billing** y hace clic en **Settings**. 2. El panel muestra los métodos guardados, el interruptor de activación, el modo (**By usage** o **Fixed amount**), el consumo actual estimado y el próximo cobro, y **Recent automatic top-ups**. 3. Cambiar a **Fixed amount** les permite introducir el umbral y el importe. Desactivar el interruptor detiene los cobros. ![Ajustes de facturación del cliente con recarga automática en modo By usage y las recargas automáticas recientes](https://nexcmp.com/es/docs/images/billing/auto-top-up-02-portal.webp) ## Verificación {#verify} 1. Como cliente de prueba, realice una primera recarga con una tarjeta de prueba ([Stripe](https://nexcmp.com/es/docs/billing/stripe/#verify)). Abra **Billing › Settings**: la recarga automática estará activada. 2. Ejecute una pequeña VM para que haya consumo y reduzca el saldo por debajo del umbral (por ejemplo, con **Customers › customer › Credit / debit**). 3. En un plazo aproximado de 5 minutos se realiza un cobro. En la tarjeta **Overview › Payment** del cliente, **Auto top-up history** muestra el intento con el estado *Done* y se envía una notificación *Top-up received*. ## Límites y notas {#limits-notes} - **Un cargo por cada caída.** Tras un cargo, la tarea espera hasta que el saldo vuelva a superar el umbral o finalice el tiempo de espera: 1 hora tras un éxito, 24 horas tras un cargo pendiente y 30 minutos tras un error del sistema. - **Límites diarios.** Al alcanzar cualquiera de los límites diarios, no se realiza ningún cargo y se registra una línea *Daily limit reached* (como máximo una vez cada 6 horas). - **Fallos.** Una tarjeta rechazada, caducada o con fondos insuficientes cuenta como un fallo de tarjeta. La tarea reintenta tras 1 hora, luego 6 horas y luego 24 horas. **Tras 3 fallos consecutivos de tarjeta, la recarga automática se desactiva** y se notifica al cliente (*Auto top-up failed*). Un pago que requiere la confirmación del cliente (por ejemplo, 3-D Secure) no se considera un fallo; se le indica al cliente que lo confirme. - **Sin cargos dobles.** Cada cargo se procesa de forma atómica por cada caída por debajo del umbral y utiliza una clave de idempotencia en la pasarela. - **Eliminar la tarjeta** desactiva la recarga automática. - **Revendedores.** Si un revendedor utiliza su propio canal de pago, el cliente no puede activar la recarga automática (HTTP 403 `feature_disabled`). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El cliente no puede activarlo: "Top up once with a card or PayPal" | No hay ningún método guardado | Realice primero una recarga con tarjeta o PayPal. | | Error `no_card` (422) | La pasarela elegida no tiene ningún método guardado | Elija la pasarela que lo tenga o guarde un método. | | Error `invalid_argument` en el importe | Modo fijo fuera de los rangos permitidos | Umbral de $1–$500, importe entre la recarga mínima y $1,000, importe superior al umbral. | | No se cobra nada aunque el saldo sea bajo | Interruptor global desactivado, no hay servicios en ejecución en el modo By usage, se alcanzó el límite diario o el cargo anterior sigue en espera | Compruebe el interruptor, el historial y los límites. | | "N intentos fallidos consecutivos — la recarga automática se desactiva tras 3" | La tarjeta sigue fallando | El cliente sustituye la tarjeta mediante un nuevo depósito. | | Estado *Needs your confirmation* | El banco requiere 3-D Secure | El cliente completa una recarga normal una vez. | --- # Facturas y libro mayor {#invoices-and-ledger} > **Ubicación en el panel de administración:** Finance › Billing (`/billing`) con las pestañas Overview, Transactions (`/billing/ledger`), Invoices (`/billing/invoices`), Top-ups (`/billing/deposits`), Payouts (`/billing/payouts`), Vouchers (`/billing/vouchers`) y Reports (`/billing/reports`). **Ubicación en el portal:** Billing (`/billing`). ## Qué hace {#what-it-does} Cada importe en NexCMP se almacena en centavos de USD y se registra una sola vez. La idea clave: el **libro mayor del monedero** es la fuente única de verdad para los saldos; las facturas, los pagos de recargas y los informes son vistas generadas a partir de él. El libro mayor es **de solo adición**: los errores se corrigen añadiendo un asiento de contrapartida, nunca editando el historial. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Datos del vendedor | Configure la razón social, el NIF/CIF, la dirección, el correo de contacto y el prefijo de numeración de facturas en **System › Settings › General**, pestaña **Seller & invoicing** (`/settings?tab=seller`), tarjeta **Seller details (printed on invoices)**. | | Dependencias | [Canales de pago](https://nexcmp.com/es/docs/billing/payment-channels/) para las entradas de dinero. | ## Los componentes {#the-pieces} | Pestaña de administración | Qué muestra | Uso habitual | |---|---|---| | **Overview** | Ingresos de hoy y de este mes, totales del libro mayor por tipo (depósito, cargo, reembolso, ajuste, cupón), facturas por estado, reembolsos pendientes, accesos directos, gasto por servicio en los últimos 30 días | Revisión diaria | | **Transactions** | El libro mayor del monedero, una línea por movimiento | Explicar el saldo de un cliente | | **Invoices** | Facturas y una segunda vista **Orders** con cada compra de cada servicio | Buscar un documento, reenviar, marcar como pagada | | **Top-ups** | Pagos recibidos a través de las pasarelas | Verificar un pago, reembolsarlo | | **Liquidaciones** | Reembolsos con tarjeta, pagos a afiliados, retiros de revendedores | Aprobar salidas de fondos | | **Cupones** | Códigos de recarga | Consulte [Promotions](https://nexcmp.com/es/docs/billing/promotions/) | | **Informes** | Ingresos, por servicio, por revendedor | Contabilidad | ### Transacciones (libro mayor) {#transactions-ledger} Columnas: hora, cliente, **tipo**, servicio, importe (con signo), VM, referencia, actor, nota. Filtros: tipo, servicio, ID de cliente, sitio (cuando tiene revendedores), rango de fechas y un enlace a la VM. | Tipo | Significado | |---|---| | `deposit` | Recarga desde una pasarela | | `charge` | Dinero cobrado por un servicio (pedido, renovación, uso por horas...) | | `refund` | Dinero devuelto al monedero | | `adjust` | Crédito o débito del administrador, y también códigos de recarga (referencia que empieza por `vch:`) — la vista general muestra los cupones en su propia línea | Cada fila tiene una referencia como `dep:stripe:`; la misma referencia nunca puede escribirse dos veces, por lo que un webhook repetido no puede acreditar dos veces. Utilice **Customers › List › customer › Credit / debit** para añadir un ajuste manual: el motivo es obligatorio, un importe positivo también intenta desbloquear las VM bloqueadas por falta de fondos y la acción se confirma en dos pasos. ![Pestaña Transactions que muestra las filas del libro mayor del monedero con tipo, servicio, importe y referencia](https://nexcmp.com/es/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Facturas {#invoices} Se crea una factura automáticamente cuando un cliente compra o renueva algo pagado desde el monedero, o por una recarga. Los números tienen el formato `-<000001>` (por ejemplo, `NX202610-000042`); los sitios de revendedor utilizan su propio prefijo y secuencia. Los números existentes nunca cambian cuando se modifica el prefijo. | Campo | Valores | |---|---| | Tipo | Recibo, Renovación, Recarga, Manual, Reembolso | | Status | Impagada, Pagada, Vencida, Cancelada, Reembolsada | Acciones en una fila: | Acción | Efecto | |---|---| | **View** / **Print** | Abre la factura; el portal también permite imprimir o guardar como PDF. | | **Marcar como pagada** (solo impagadas o vencidas) | La marca como pagada **sin mover dinero del monedero**: utilícelo cuando el cliente le haya pagado fuera de NexCMP. Se requiere un motivo. Para una factura de renovación, también amplía y desbloquea la VM bloqueada. | | **Cancelar** (solo impagadas o vencidas) | Cancela la factura. Se requiere un motivo. | | **Reenviar** | Vuelve a enviar la factura por correo electrónico. | **Create manual invoice** (botón en la parte superior de la pestaña): ID de cliente, de 1 a 50 líneas (descripción, cantidad, precio unitario), VM ID opcional, días para el vencimiento opcionales (0 a 365, por defecto 7), nota opcional. Se crea como no pagada; el cliente la visualiza en **Billing › Invoice History**. Las facturas pendientes de servicios se **liquidan automáticamente desde el monedero** en cuanto hay fondos, por lo que la acción del cliente consiste simplemente en recargar. ### Recargas (pagos) {#top-ups-payments} Una fila por intento: fecha y hora, cliente, **pasarela y método**, tipo (recarga o recarga automática), estado (pending, completed, failed, refunded, disputed, canceled), lo que pagó el cliente, la comisión, lo acreditado al monedero, la referencia de la pasarela y la fecha y hora de finalización. Los pagos completados mediante Stripe y PayPal disponen de una acción **Refund**. Utilice las páginas de eventos de pasarela para consultar los webhooks ([Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/)). ### Liquidaciones {#payouts} Tres subpestañas: **Card refunds** (aprobar o rechazar solicitudes de reembolso; la solicitud se genera a partir de un pago completado), **Affiliate payouts** (retiros de comisiones) y **Reseller withdrawals**. Cada decisión queda auditada. ### Informes {#reports} **Revenue** (tendencia a 30 días, mes a mes, principales clientes), **By service** y **By reseller**. ![Pestaña Reports que muestra los KPI de ingresos y la tendencia a treinta días](https://nexcmp.com/es/docs/images/billing/invoices-and-ledger-03-reports.webp) ## Lo que ve el cliente {#what-the-customer-sees} En **Billing** el cliente dispone de **Balance**, **Deposit**, **Redeem code**, **Settings** (recarga automática) y un historial con las pestañas **Invoice History**, **Payment Order**, **Ledger** y **Orders** (todos los servicios en una sola lista con filtros por servicio y tipo). Cada factura cuenta con **View**, **Print** y **Save as PDF**; los importes están en USD, mostrados opcionalmente en la moneda de visualización. ## Verificación {#verify} 1. Realice una pequeña recarga como cliente de prueba. 2. **Transactions** muestra una línea `deposit`, **Top-ups** muestra el pago como *Completed* y los ingresos en **Overview** aumentan. 3. Compre algo: aparece una línea `charge` y **Invoices** muestra una factura de tipo *Receipt* o *Renewal* con los datos del vendedor que haya configurado. ## Límites y notas {#limits-notes} - **Append-only.** No es posible editar ni eliminar una línea del libro contable; añada un ajuste indicando el motivo. - **Moneda.** Los importes están en USD; la moneda de visualización es meramente informativa (consulte [Moneda y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/)). - **El reembolso a tarjeta** consta de dos pasos (solicitud y posterior aprobación en Payouts); USDT y las transferencias bancarias no se reembolsan al origen. - **Todo queda auditado** en System › Logs › Admin actions con el motivo indicado. - **Orders frente a facturas.** El uso por horas no se factura por hora; la vista Orders lo agrupa por día para que pueda consultarlo. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El saldo del cliente parece incorrecto | Un cargo, ajuste o cupón imprevisto | Filtre **Transactions** por el ID de cliente y revise las referencias y notas. | | "La factura ya está pagada" (409) | Marcar como pagada una factura que ya está pagada | No requiere ninguna acción. | | No se puede cancelar una factura | Solo se pueden cancelar facturas impagas o vencidas | Para las facturas pagadas, utilice un reembolso o un ajuste. | | Faltan los datos del vendedor en las facturas | No se han completado | Complete **Seller details** en System › Settings › General › Seller & invoicing. | | Crédito / débito rechazado | El importe es cero o superior a $100,000 | Utilice un importe entre 1 centavo y $100,000. | | Un pago permanece en *Pending* durante mucho tiempo | Falta el webhook | Consulte **Gateway events** y reprodúzcalo. | --- # Promociones {#promotions} > **En el panel de administración:** Finance › Billing › Vouchers (`/billing/vouchers`). **En el portal:** Billing › Redeem code (también dentro del panel Deposit). ## Qué hace {#what-it-does} Un **código de recarga** (voucher) es una clave secreta de un solo uso que se entrega a los clientes. Según cómo se configure, permite: | Tipo | Qué recibe el cliente | Dónde se aplica el saldo | |---|---|---| | **Bonus credit** para todos los servicios | Dinero añadido a la billetera | Saldo de la billetera. Utilizable para cualquier servicio. | | **Bonus credit** para los servicios seleccionados | Crédito para servicios | Un saldo independiente que solo permite pagar dichos servicios. | | **Discount %** | Porcentaje de descuento en el primer pedido de los servicios seleccionados | No se acredita nada; el descuento se aplica al tramitar el pago. | Úselos para campañas, créditos de compensación, acuerdos con socios o descuentos de primer pedido. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Clientes | Los clientes canjean los códigos con la sesión iniciada en el portal (no como invitados). Por defecto, el cliente debe tener un correo electrónico verificado. | | Códigos en VND | Un código creado en VND se convierte a USD al canjearlo según el tipo de cambio registrado (consulte [Monedas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/)). | ## Crear un lote {#create-a-batch} 1. Abra **Finance › Billing › Vouchers** y haga clic en **Create vouchers**. 2. Complete el formulario. Los valores de ejemplo figuran entre corchetes. | Campo | Notas | |---|---| | Nombre del lote | 1–80 caracteres (`Spring welcome`). | | Destinatario | **Clientes del sitio principal**, **Clientes de un solo revendedor** (requiere una lista de clientes) o **Billetera del revendedor**. | | Usuarios aptos | **All in target audience** o **Specified** — un correo electrónico o ID de cliente por línea, hasta 1,000. Para los clientes de un revendedor debe ser *Specified*. | | 1 código por destinatario | Con *Especificados*, crea un código por cada cliente listado. | | Tipo de código | **Bonus credit** o **Discount %**. | | Se aplica a | Seleccione uno o más servicios; vacío = **Todos los servicios**. | | Moneda, valor nominal | USD a partir de $1.00, o VND a partir de 10,000 en múltiplos de 1,000 (solo crédito de bonificación). | | Descuento (%) | De 1 a 100 (solo Discount %). | | Tope máximo de descuento (USD) | Obligatorio para Discount %, a partir de $1.00. Es también lo máximo que puede perder por cada canje. | | Pedido mínimo (USD) | `0` = ninguno. El primer pedido debe ser de al menos este importe. | | Cantidad de códigos | De 1 a 1,000 códigos aleatorios. | | Usos por código | De 1 a 100,000. `1` significa una persona por código; auméntelo para un código compartido. | | Usos máximos por cuenta | Al menos 1. Para Discount % debe ser `1`. | | Hora de inicio (opcional), Vencimiento | El vencimiento debe ser posterior a hoy y posterior al inicio, como máximo 2 años en el futuro. | | Prefijo del código (0–6 caracteres) | Solo letras; si se deja vacío, se utiliza el prefijo del sitio. | | Código personalizado (solo cuando count = 1) | De 6 a 32 caracteres A–Z y 0–9. Fácil de compartir pero fácil de adivinar: mantenga los usos bajos. | | Requerir correo electrónico verificado | Activado por defecto. | | Nota interna, Motivo | El motivo es obligatorio y se registra en el log de auditoría. | 3. El formulario muestra la **Exposición máxima** (valor nominal x códigos x usos) para que conozca el peor escenario posible. Haga clic en **Generate codes**. 4. **Copie los códigos ahora.** Se muestran solo una vez: NexCMP almacena únicamente un hash y los últimos 4 caracteres. Utilice **Copy all** o **Descargar CSV**, marque la confirmación y cierre el cuadro. ## Comportamiento de cada tipo {#how-each-type-behaves} ### Bono de billetera (sin servicio seleccionado) {#wallet-bonus-no-service-selected} Se acredita en la billetera una entrada de **ajuste** (referencia `vch:...`). No es reembolsable a una tarjeta, no genera comisiones de afiliados, no crea facturas y cuenta como saldo de billetera para las cuotas. Los códigos en VND utilizan el tipo de cambio al momento del canje. ### Crédito de servicio (servicios seleccionados) {#service-credit-services-selected} - El crédito se mantiene en un **bolsillo separado**, solo puede pagar cargos de los servicios seleccionados (nuevos pedidos, renovaciones, tarifas horarias o diarias, mejoras) y se consume **antes** que la billetera. - No se puede retirar, transferir ni convertir en dinero, y vence junto con el código. - El libro mayor muestra el cargo completo más una línea de crédito correspondiente, de modo que los ingresos por servicio se mantienen correctos mientras que la billetera solo disminuye según lo que el cliente realmente pagó. - **No** eleva el nivel de [cuota](https://nexcmp.com/es/docs/billing/quotas/) y la [recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/) lo ignora. - Si se reembolsa un cargo pagado con crédito o con descuento, la parte que cubrió el código se descuenta del reembolso de la billetera y se devuelve al bolsillo de crédito. ### Discount % {#discount} 1. El cliente ingresa el código y este queda **activado**. Un código de porcentaje solo se puede usar una vez por cuenta. 2. El **primer cargo** de un servicio seleccionado que no sea una tarifa por hora, y que alcance al menos el **Pedido mínimo**, recibe el porcentaje de descuento, sin superar nunca el **Límite máximo de descuento**. 3. El servidor recalcula el descuento en el momento del cobro; el importe mostrado en el navegador se ignora. La fila de canje se registra cuando el código se utiliza efectivamente, con el descuento real. 4. Los cargos por uso por hora nunca utilizan el código. ## Qué hace el cliente {#what-the-customer-does} 1. Abra **Billing** en el portal y haga clic en **Redeem code**, o utilice **¿Tiene un código de recarga?** en el panel Deposit. 2. Escriba el código (no distingue mayúsculas de minúsculas; guiones opcionales) y haga clic en **Check**. El portal indica lo que otorga, por ejemplo *Código válido: +$5.00*, *Crédito de $5.00 para VPN* o *Cupón de 20% de descuento para Virtual Machines (hasta $5.00)* y *Válido para pedidos a partir de $10.00*. 3. Haga clic en **Redeem** y confirme. Cada código se puede utilizar una sola vez por cuenta. Los códigos están vinculados al sitio: un código de un sitio es «no válido» en otro, sin indicar si existe en otra parte. Los intentos erróneos se limitan y, tras varios, la cuenta se bloquea durante unos minutos («Quedan N intentos antes de un bloqueo temporal»). ## Seguimiento y desactivación {#track-and-stop} - **Batches** muestra cada lote con su estado (*active*, *disabled*, *expired*, *used up*), el número de canjes y la exposición. Abra un lote para ver las pestañas **Codes** (enmascarados) y **Redemptions**, y **Export CSV**. - **Redemptions** lista cada canje entre todos los lotes; **Reseller quotas** muestra cuánto del límite mensual de emisión de cada revendedor se ha utilizado; **Settings** activa o desactiva los códigos de revendedor y define el límite mensual predeterminado. - **Disable batch** detiene todos los códigos no utilizados; los canjes ya realizados se conservan. También se puede desactivar un código individual. ## Verificación {#verify} 1. Cree un lote de 1 código: Discount % 20, límite $5, pedido mínimo $10, servicio Virtual Machines. 2. Canjéelo con una cuenta de cliente de prueba. El portal indicará que está activado. 3. Solicite una VM que cueste al menos $10 (ciclo mensual): la factura mostrará el descuento (como máximo $5). 4. En el lote, el código mostrará 1 canje con el descuento real aplicado. ## Límites y notas {#limits-notes} - Los códigos quedan vinculados a la **audiencia** y al **sitio** en el momento de su creación; no se pueden mover posteriormente. - Los revendedores pueden emitir códigos a sus propios clientes dentro de un límite de exposición mensual; consulte [Resellers](https://nexcmp.com/es/docs/customers/resellers/). - Los banners promocionales de la barra lateral para clientes (**Marketing › Promo slides**) son una función independiente y no otorgan ningún descuento. - Dado que el código en texto plano nunca se almacena, un lote perdido no se puede recuperar: desactívelo y cree uno nuevo. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Códigos de porcentaje: un solo uso por cuenta" (`percent_one_per_account`) | Max uses per account superior a 1 para Discount % | Establézcalo en `1`. | | El formulario indica que el límite es obligatorio | Discount % sin Maximum discount cap | Introduzca al menos $1.00. | | Clientes no encontrados | Un correo electrónico o ID de la lista no existe | Corrija la lista (el error indica las entradas desconocidas). | | El cliente indica «código no válido» | Sitio incorrecto, caducado, desactivado, agotado, cliente no destinatario o correo electrónico no verificado | Compruebe el lote y el cliente. | | El crédito no se utilizó | El cargo corresponde a otro servicio | El crédito solo cubre los servicios seleccionados en el lote. | | Descuento no aplicado | Pedido inferior al mínimo, cargo por horas o código activado para otro servicio | Realice un primer pedido que cumpla las condiciones. | | Cliente bloqueado para canjear | Demasiados intentos erróneos | Espere a que expire el bloqueo temporal. | --- # Cuotas {#quotas} > **Ubicación en el admin:** Services › Virtual Machines › Policy › Quota tab (`/vm/policy?tab=quota`). Por cliente: Customers › List › a customer › Overview (`/customers/`), tarjeta **Quota**. **Ubicación en el portal:** Client › Quotas (`/client/quotas`). ## Qué hace {#what-it-does} Las cuotas protegen contra abusos de cuentas nuevas: cuanto más saldo real haya ingresado un cliente en su cuenta, más recursos podrá crear. Hay dos niveles: - **Recursos de VM y Kubernetes**: total de vCPU, RAM y disco, y el número de VM. Los niveles son sus planes fijos. - **Cuotas de servicio**: cantidad de IP, clústeres, VPC, GB de almacenamiento, etcétera, en cinco niveles (L0 a L4) determinados por el dinero depositado. Las cuotas se comprueban **antes** de realizar cualquier cargo. Toda solicitud que supere el límite se rechaza con HTTP 403 `quota_exceeded` y un mensaje que indica al cliente cuánto debe recargar. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Interruptor | **Enable quota** (`quota_enabled`) está **desactivado** por defecto. Nada de lo indicado a continuación se aplicará hasta que lo active. | | Planes fijos | Al menos un plan no personalizado (consulte [Plans](https://nexcmp.com/es/docs/catalog/plans/)): los niveles de recursos son sus planes fijos. Sin ningún plan, solo se aplica la regla de recuento de VM. | | Dependencias | Las filas de cuotas de servicio solo existen para los productos que estén habilitados en su instalación (VPN, IPv6 proxy, Kubernetes, Private Cloud, Images, Object Storage, Dedicated). | ## Cómo se calcula la base {#how-the-basis-is-calculated} NexCMP no solo considera los pagos con tarjeta. La **base** es el **saldo asentado en el monedero** del cliente: las recargas por pasarela, los créditos de administrador (**Credit / debit**) y los vales de monedero canjeados cuentan una vez a través del libro de contabilidad del monedero. Los descuentos de pedidos y los créditos de servicio derivados de códigos promocionales no son saldo del monedero y no cuentan. La base máxima que un cliente haya alcanzado alguna vez se **mantiene** (por sitio): los gastos o reembolsos nunca rebajan un nivel ya desbloqueado. ### Recursos de VM y Kubernetes {#vm-and-kubernetes-resources} 1. Los niveles son los planes fijos del sitio, ordenados por el costo de ejecutarlos durante 24 horas. 2. El cliente se ubica en el nivel más alto cuyo costo de 24 horas no supere su base. El límite corresponde a la vCPU, RAM y disco de dicho plan. Un cliente que no pueda cubrir ni siquiera el plan más económico seguirá obteniendo los recursos del plan más económico. 3. El uso contabilizado para el límite incluye todas las VM activas (incluidas las bloqueadas), los volúmenes de datos adquiridos (incluso si están desconectados) y los nodos de trabajo y planos de control de Kubernetes (los nodos de trabajo también cuentan como VM). 4. **Recuento de VM:** hasta **Max VMs at 24h tier** (predeterminado: 2). A partir de la siguiente VM, el saldo *actual* del monedero del cliente debe cubrir **30 días (720 horas)** de todas sus VM existentes más la nueva, hasta **Max VMs when meeting 30-day threshold** (predeterminado: 10). 5. **Crear una VM** también requiere un saldo de al menos **N horas** de esa VM (**Create VM: balance ≥ N hours**, predeterminado: 2) y el saldo mínimo de la plataforma. 6. Reducir el tamaño de una VM nunca se bloquea. Solo se comprueba la dimensión que aumenta, por lo que un cliente que supere el límite de disco aún puede añadir vCPU si el límite de vCPU lo permite. ## Configurar {#configure} 1. Abra **Services › Virtual Machines › Policy** y seleccione la pestaña **Quota**. 2. Active **Enable quota**. 3. Revise los tres números (todos editables): | Campo | Predeterminado | Rango | |---|---|---| | Crear VM: saldo ≥ N horas | 2 | 1 a 720 | | Max VMs at 24h tier | 2 | 1 a 100 | | Máximo de VM al cumplir el umbral de 30 días | 10 | 1 a 1000 (no inferior al campo anterior) | 4. En **Tier-based service quotas**, edite la tabla (a continuación). 5. Haga clic en **Save**. NexCMP solicitará un **motivo**, que se registrará en el registro de auditoría junto con los valores anteriores y nuevos. El cambio se aplica a todos los clientes. ![Pestaña Quota con el interruptor de habilitación, los límites de VM y la tabla de cuotas de servicio por niveles](https://nexcmp.com/es/docs/images/billing/quotas-01-policy.webp) ### Tabla de cuotas de servicio {#service-quota-table} La tabla tiene cinco niveles. Las celdas de encabezado **L0** a **L4** contienen el **umbral de depósito en centavos**: los valores predeterminados `0, 1000, 5000, 20000, 100000` corresponden a L0 para una cuenta nueva, L1 a partir de $10, L2 a partir de $50, L3 a partir de $200 y L4 a partir de $1,000. El primer umbral debe permanecer en `0`. Cada fila define la cuota de una clave por nivel; **-1 significa ilimitado**. | Clave | Significado | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | Direcciones IP de VPN | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | Direcciones IP de proxy IPv6 | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | Servidores bare-metal | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | GB asignados de Object Storage | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | Clústeres de Kubernetes | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | Nodos de trabajo de Kubernetes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | Redes de Private Cloud | 1 | 2 | 5 | 10 | 30 | | `images.gb` | GB de almacenamiento de imágenes personalizadas | 50 | 100 | 200 | 500 | 2000 | La tabla también enumera algunas filas de productos que no forman parte de esta versión; déjelas sin cambios. Si el producto de una clave está desactivado, esta se oculta y nunca se aplica. El valor debe ser `-1` o situarse entre `0` y `10,000,000`. Las cuotas de servicio siguen la **base de fondos**, al igual que los niveles de VM: el saldo de monedero más alto alcanzado, no el total de pagos con tarjeta. Los clientes de revendedores utilizan los mismos valores predeterminados y el revendedor solo puede verlos. ## Excepciones por cliente {#per-customer-overrides} 1. Abra **Customers › List**, luego el cliente. En **Overview** busque la tarjeta **Quota**. 2. **Recursos de VM:** haga clic en **Quota override** y elija una de las siguientes opciones: - **By top-up balance (remove override)**: comportamiento predeterminado; - **Unlimited (including VM count)**: elimina cualquier límite para este cliente; - un **nivel de plan**: fija el límite máximo de recursos a ese plan; la regla de cantidad de VM se sigue aplicando. Introduzca un motivo. Los administradores de la plataforma pueden definir cualquier nivel; una excepción establecida por un revendedor no puede superar la base retenida del cliente. 3. **Servicios:** la tabla bajo *Service quotas* muestra cada clave con *In use*, el límite efectivo y su *Source* (nivel o excepción). Haga clic en **Edit** en una fila, escriba la **New quota** (`-1` = ilimitado, vacío = volver al valor predeterminado del nivel) y un motivo. ![Tarjeta Quota del cliente con el nivel, el uso de recursos y la tabla de cuotas de servicio con una excepción](https://nexcmp.com/es/docs/images/billing/quotas-02-customer.webp) Cada excepción se registra en el registro de auditoría con el administrador, el motivo y los valores anteriores y posteriores. ## Lo que ve el cliente {#what-the-customer-sees} **Client › Quotas** (`/client/quotas`) muestra el **nivel actual** del cliente, la cantidad en uso y total de vCPU, RAM, disco y número de VM (desglosado entre VM y Kubernetes), el **saldo de monedero apto**, la **base de recursos retenida** (no disminuye al gastar) y cuánto recargar para alcanzar el siguiente nivel. Un control deslizante permite elegir un nivel objetivo e ir directamente a la pantalla de depósito. La tarjeta **Service Quotas** enumera cada servicio con su cuota, la cantidad utilizada, su nivel (L0 a L4), cuánto más depositar para el siguiente nivel y un botón **Request increase** que abre un borrador de ticket de soporte. Un botón **Quota policy** explica las reglas. ![Página Quotas del portal con el nivel actual, el uso de recursos y las cuotas de servicio](https://nexcmp.com/es/docs/images/billing/quotas-03-portal.webp) ## Verificación {#verify} 1. Active **Enable quota** y utilice un nuevo cliente de prueba con un saldo de $0. 2. Intente crear una VM superior a su plan más económico. La solicitud se rechazará con `quota_exceeded` y el mensaje "Exceeds the resources of tier ... Top up $X more to unlock tier ...". 3. Recargue la cantidad indicada. El nivel cambiará de inmediato y la misma solicitud se completará con éxito. 4. Compre direcciones IP de VPN por encima del límite de L0: HTTP 403 `quota_exceeded` con `"scope":"service"` y un enlace a `/client/quotas`. 5. En la tarjeta Quota del cliente, **Source** muestra *tier*; configure una excepción y compruebe cómo cambia a *override*. ## Límites y notas {#limits-notes} - **Desactivado significa desactivado.** Con `quota_enabled` desactivado, la regla anterior `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) limita las cuentas nuevas a 2 VM hasta que sus depósitos alcancen los $10. Cuando la cuota está activada, dicha regla ya no se aplica. - **Las VM creadas por administradores no se bloquean.** - **Los errores fallan de forma segura.** Si no se puede leer el estado de la cuota, la solicitud se rechaza con `quota_unavailable` en lugar de permitirse. - Las solicitudes de **API, CLI y MCP** utilizan los mismos controladores, por lo que se aplican los mismos límites. - El **crédito de promoción** no aumenta de nivel (consulte [Promociones](https://nexcmp.com/es/docs/billing/promotions/)). - **Los umbrales de nivel son centavos**, no dólares. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `quota_exceeded`, motivo `resources` | El nuevo total de vCPU/RAM/disco supera el nivel | Recargue el importe indicado en el mensaje o establezca una excepción. | | `quota_exceeded`, motivo `vm_30d` | Supera la cantidad de VM del nivel de 24 h y el saldo aún no cubre 30 días de la flota | Recargue el importe mostrado. | | `quota_exceeded`, motivo `vm_max` | Se ha alcanzado el límite absoluto de VM | Aumente **Max VMs when meeting 30-day threshold** o use una excepción. | | `quota_exceeded`, `scope: service` | Se ha alcanzado un límite por servicio | Aumente el valor en la tabla o anule esa clave para el cliente. | | `quota_unavailable` | No se pudo verificar el estado de la cuota | Reintente; consulte el registro del servidor si persiste. | | "quota_max_vms_30d must be >= quota_max_vms_24h" al guardar | Valores invertidos | Haga que el valor de 30 días sea al menos igual al de 24 horas. | | El cliente indica que el nivel se redujo | No se reduce; compare **Held resource basis** con el costo del plan | Consulte la lista de precios del plan: un aumento de precio del plan puede alterar los umbrales. | --- # Gestión de clientes {#managing-customers} > **Ubicación en el panel de administración:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) y API keys (`/customers/apikeys`). ## Qué hace {#what-it-does} El área Customers es donde el personal de soporte busca una cuenta, consulta su saldo, servicios, tickets e historial de inicio de sesión, y realiza acciones sobre ella: bloquear, desbloquear, verificar correo electrónico, restablecer la contraseña, añadir o retirar crédito, suplantar la identidad, crear una VM o cerrar la cuenta. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. Cada acción de escritura solicita un motivo y se registra en el registro de auditoría (System › Logs › Admin actions). | | Correo electrónico | Los correos electrónicos de restablecimiento de contraseña e invitación requieren una [configuración de SMTP](https://nexcmp.com/es/docs/administration/smtp-and-emails/) funcional. | ## La lista de clientes {#the-customer-list} Abra **Customers › List**. Los clientes son cuentas de su sitio principal; las cuentas de revendedores también aparecen y pueden filtrarse por sitio. ![Lista de clientes con los filtros y las columnas de país, fuente de referencia, saldo y recuento de VM](https://nexcmp.com/es/docs/images/customers/managing-customers-01-list.webp) | Columna | Significado | |---|---| | **Email** (y nombre) | Haga clic para abrir el cliente. | | **State** | *Active*, *Locked* o *Deleted*, además de correo electrónico *verified* o *unverified*. Pase el cursor sobre una etiqueta de bloqueo para leer el motivo. | | **Login** | Métodos de inicio de sesión que tiene el cliente: contraseña, Google, GitHub, passkey. | | **Country** | Bandera y nombre obtenidos a partir de la **dirección IP**: el país de la IP de registro o, si se desconoce, de la última IP de inicio de sesión. La descripción emergente indica cuál se utilizó. | | **Referral source** | *Referral* con un enlace al referente y el código de referido cuando el cliente se registró mediante un enlace de afiliado; de lo contrario, «Not recorded». | | **Balance**, **VMs** | Saldo del monedero (valores negativos en rojo) y el número de VM activas. | | **IP de registro / última** | La IP utilizada en el registro y en el último inicio de sesión con el país en dos letras. Utilícela para detectar varias cuentas procedentes de una misma dirección. | | **Tenant** | El ID de tenant interno del cliente. | | **Created**, **Last login** | Tiempos relativos. | | **Site** | Se muestra cuando tiene revendedores. | **Search** acepta correo electrónico, nombre o IP. **Filtros:** estado (todos, activos, bloqueados, eliminados), método de inicio de sesión (cualquiera, Google, GitHub, passkey, aún sin contraseña) y sitio. Los filtros se conservan en la URL, por lo que una lista filtrada puede guardarse en marcadores o compartirse con un colega. **La ordenación es global.** Al hacer clic en el encabezado de *Email*, *State*, *Balance*, *VMs*, *Created* o *Last login*, se ordena **toda** la base de clientes en el servidor, no solo la página que está viendo, y el número de página vuelve a 1. **La lista se actualiza automáticamente.** Se actualiza cada pocos segundos mientras la visualiza (se pausa si hay un diálogo abierto o mientras escribe), de modo que los nuevos registros y cambios de saldo aparecen sin recargar. La página del cliente se actualiza aproximadamente cada 30 segundos mientras está visible; cada pestaña carga sus propios datos cuando se abre por primera vez. ### Crear un cliente {#create-a-customer} 1. Haga clic en **Create customer**. 2. Introduzca el **correo electrónico**, un **nombre para mostrar** opcional, una **contraseña** opcional (en blanco = el cliente la define mediante el enlace de invitación) y elija si desea **enviar el correo electrónico de invitación**. 3. Confirme. Una cuenta creada manualmente se considera verificada al enviar la invitación. ## Página de un cliente {#a-customer-s-page} Haga clic en una fila. La página tiene ocho pestañas; la pestaña seleccionada se conserva en la URL para que pueda guardarla en marcadores. Las pestañas se cargan al abrirse por primera vez y conservan su estado al cambiar a otra. | Pestaña | Contenido | |---|---| | **Overview** | Identidad, información de registro y último inicio de sesión, resumen del monedero y de los servicios | | **Services** | Una tabla para los servicios del cliente, con filtros de tipo y estado, búsqueda, ordenación del lado del servidor y paginación | | **Billing** | Monedero y crédito, libro mayor, facturas, pagos, reembolsos, método de pago guardado y recarga automática | | **Quota** | Límites de recursos y anulaciones; consulte [Quotas](https://nexcmp.com/es/docs/billing/quotas/) | | **Security** | Sesiones, autenticación, métodos de inicio de sesión, historial de inicios de sesión y claves de API; consulte [API keys](https://nexcmp.com/es/docs/developers/api-keys/) | | **Support** | Tickets recientes | | **Affiliate** | Estado del programa de referidos | | **Log** | Historial de auditoría y actividad | Botones de acción en el encabezado (ocultos para cuentas eliminadas): | Botón | Qué hace | |---|---| | **Lock account** / **Unlock** | Bloquea el inicio de sesión y el acceso a la API. Opcionalmente, también detiene todas las VM (sin eliminarlas). Los servicios prepagados que no son VM (Kubernetes, Private Cloud, VPN, etc.) también se detienen. Las VM bloqueadas por un administrador deben abrirse por separado en la página de la VM. | | **Verify email** | Marca el correo electrónico como verificado sin que el cliente tenga que hacer clic en un enlace. | | **Send reset link** | Envía por correo electrónico un enlace para restablecer la contraseña (válido por 1 hora, un solo uso). Si SMTP no está configurado, el enlace se muestra una vez para que pueda enviarlo usted mismo. Un administrador nunca ve la contraseña. | | **Impersonate** | Inicia sesión como el cliente durante una hora. Consulte [Iniciar sesión como cliente](https://nexcmp.com/es/docs/customers/login-as/). | | **Credit / debit** | Añade o retira fondos del monedero mediante un ajuste del libro mayor. Consulte [Facturas y libro mayor](https://nexcmp.com/es/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | Cierra la sesión del cliente en todas partes; los tokens de la aplicación dejan de funcionar. | | **Create VM** | Crea una VM para el cliente. | | **Soft delete** | Cierra la cuenta. Debe escribir el correo electrónico para confirmar. | ### Gestionar un servicio individual {#manage-an-individual-service} Abra la pestaña **Services** del cliente, busque un servicio por nombre, ID, IP o configuración y utilice las acciones de su fila. Las mismas acciones están disponibles en la propia lista de administración del servicio. El diálogo solo ofrece las acciones admitidas por ese servicio y su estado actual. | Acción | Efecto | |---|---| | **Lock** | Detiene el servicio conservando sus datos. El cliente lo ve como bloqueado y no puede operarlo. Realizar una recarga no elimina el bloqueo de un administrador; la renovación automática queda bloqueada mientras permanezca bloqueado. | | **Unlock** | Revierte el bloqueo del administrador. No elimina un bloqueo no relacionado por abuso u otra protección. | | **Cancel without refund** | Cancela el servicio sin un asiento de reembolso en el libro mayor. La confirmación advierte que la cancelación no se puede deshacer. | | **Cancel and refund** | Muestra los pagos originales, su asignación entre monedero y crédito, los reembolsos anteriores y el importe máximo reembolsable. Revise el importe antes de confirmar. | Introduzca un motivo para cada acción. El motivo es para los administradores; el cliente recibe un evento de servicio o una notificación neutral. Los fondos reembolsados vuelven al saldo monedero, y las asignaciones de crédito o promocionales vuelven al crédito. Esta acción no devuelve dinero a través de Stripe, transferencia bancaria o PayPal. Para varios servicios del mismo tipo, seleccione hasta 50 filas y elija una acción masiva. El resultado detalla el éxito o error de cada fila. Los reembolsos masivos utilizan el importe sugerido de cada servicio; los servicios cuyo reembolso sugerido sea cero se omiten en el modo de reembolso y requieren una revisión individual o su cancelación sin reembolso. DDoS Shield, los discos y los backups se muestran aquí como filas de solo lectura. Los complementos de ancho de banda siguen a su servicio principal. El acceso a AI Models se puede bloquear, pero no tiene una suscripción para cancelar. Para bloquear un servidor Bare Metal alquilado, actúe sobre su suscripción en lugar de su pedido. ### Cierre de una cuenta (soft delete) {#closing-an-account-soft-delete} La cuenta pasa a estado *deleted*, se bloquea, se revocan sus sesiones y se revierten las comisiones por referidos que aún no se hayan pagado. Las facturas y el libro mayor se conservan por motivos contables. La acción se deniega mientras el cliente aún tenga **algún servicio activo** (VM, Kubernetes, Private Cloud, Dedicated, VPN, proxy IPv6), una cuenta S3 o uso de S3 pendiente de liquidar. Elimínelos primero. ## Solicitudes de eliminación {#deletion-requests} Un cliente puede solicitar la eliminación desde su página de cuenta. Las solicitudes aparecen en **Customers › Deletion requests** (filtro predeterminado: pendientes) con el cliente, el motivo, el número de VM activas, el saldo y la hora de la solicitud. - **Approve deletion** solo es posible cuando el cliente no tiene ninguna VM activa. Escriba el correo electrónico para confirmar. La cuenta se elimina de forma suave (soft delete); **el saldo restante del monedero no se reembolsa automáticamente** — cree un reembolso primero si corresponde. - **Reject** requiere un motivo. ## Transferencias de servicios {#service-transfers} **Customers › Service transfers** enumera las solicitudes para mover una **VM o suscripción VPN** de una cuenta a otra cuenta **en el mismo sitio**. - La pantalla es de solo lectura y creación: puede crear una solicitud en nombre de un cliente o cancelar una. Deliberadamente **no** hay botón para aprobarla en lugar del propietario o del destinatario. - Flujo: el propietario confirma mediante un enlace de correo electrónico de un solo uso (válido por 30 minutos, con TOTP si está habilitado); a continuación, el destinatario inicia sesión y acepta (el destinatario asume las obligaciones de pago). Una solicitud que no se acepte en un plazo de 7 días caduca. - Reglas: el servicio debe estar activo, sin facturas pendientes de pago y sin tareas en ejecución; el destinatario debe ser un cliente activo con un correo electrónico verificado en el mismo sitio. Una transferencia de VM elimina la clave SSH y desactiva la renovación automática; una transferencia de VPN cambia las contraseñas de conexión. - Las facturas ya emitidas permanecen con el propietario anterior; el nuevo propietario puede consultar el historial de facturación del servicio con los datos del propietario anterior ocultos. - Los clientes pueden crear sus propias solicitudes en **Transfers** en el portal (5 solicitudes por hora y 3 abiertas a la vez). ## Verificación {#verify} 1. Cree un cliente con un correo electrónico de invitación. La nueva cuenta aparece en la parte superior de la lista en pocos segundos. 2. Ordene por **Balance**: el orden abarca a todos los clientes. 3. Bloquee al cliente: la etiqueta de estado cambia a *Locked* y el cliente ya no puede iniciar sesión. Desbloquéelo. ## Límites y notas {#limits-notes} - La columna de país es una guía basada en la IP, no una prueba de residencia. Las direcciones privadas o desconocidas no muestran ningún país. - Bloquear una cuenta no reembolsa nada y no elimina las VM a menos que también decida detenerlas. - Desbloquear la cuenta no desbloquea las VM que un administrador haya bloqueado; actívelas por separado en la página de la VM. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "El cliente aún tiene servicios activos ... detener/eliminar primero" | El cliente tiene servicios o una cuenta S3 | Elimínelos y luego aplique soft delete. | | La aprobación de eliminación indica "N VMs alive" | Mismo motivo | Elimine las VM primero. | | Se muestra el enlace de restablecimiento en lugar de "e-mail queued" | SMTP no configurado | Configure el correo electrónico o envíe el enlace usted mismo. | | No se puede eliminar un método de inicio de sesión (`last_login_method`) | Es la única forma de inicio de sesión del cliente | Añada otro método primero. | | El bloqueo no detiene los servicios prepagados | Se reportaron errores al detener | Lea el mensaje tras el bloqueo; el sistema reintenta la detención automáticamente. | | No se puede crear una transferencia | Factura sin pagar, tarea en ejecución, destinatario en otro sitio o no verificado | Corrija la condición y reintente. | --- # Iniciar sesión como cliente {#log-in-as-a-customer} > **Dónde en el admin:** Customers › Customers › List › a customer › header button **Impersonate** (`/customers/`). ## Qué hace {#what-it-does} **Impersonate** (login-as) permite a un administrador de soporte ver el portal exactamente como lo ve un cliente, para reproducir un problema o ayudar con un pedido. La sesión dura una hora y está claramente separada de una sesión normal: cualquier acción que pueda otorgar acceso duradero a la cuenta se bloquea y cada uso queda registrado. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador con sesión iniciada en la consola de administración. | | Cliente | La cuenta debe estar **activa**. Una cuenta bloqueada o eliminada responde "account is not active" (HTTP 409). | | Motivo | El motivo es obligatorio; se escribe en el registro de auditoría. | | Navegador | Permita ventanas emergentes para la dirección de administración: el portal se abre en una nueva ventana. | ## Pasos {#steps} 1. Abra **Customers › List** y haga clic en el cliente. 2. Haga clic en **Impersonate**. Un cuadro de diálogo explica que el sitio del cliente se abre como el cliente durante una hora y que cada acción se audita. 3. Escriba el **motivo** (por ejemplo, "Ticket 1234 — cannot create VM") y haga clic en **Open app**. 4. Se abre una nueva ventana en el sitio del cliente y muestra el panel con `?impersonated=1`. Si el navegador bloqueó la ventana, permita las ventanas emergentes y haga clic de nuevo. ![Cuadro de diálogo Impersonate con el campo de motivo completado](https://nexcmp.com/es/docs/images/customers/login-as-01-dialog.webp) Para el cliente de un reseller, la ventana se abre en el **dominio propio del reseller**, ya que el enlace solo funciona en el propio sitio del cliente. ## Cómo funciona {#how-it-works} 1. La acción del admin crea un **token de un solo uso** válido por una hora y registra `customer.login_as` (administrador, IP, motivo, sitio) en el registro de auditoría. 2. La nueva ventana abre `https:///v1/portal/impersonate/`. Una primera solicitud solo muestra una página pequeña y **no** consume el token (para que la precarga del navegador no lo agote); luego, la página confirma con un POST. 3. El POST consume el token. Un segundo uso, o el uso tras una hora, responde "The impersonation link has expired or was already used". 4. NexCMP crea una sesión de cliente que dura **una hora** (una sesión normal dura 30 días), registra una entrada de inicio de sesión con el método `impersonate` y registra `customer.login_as.used`. 5. El token solo funciona en el propio sitio del cliente; en otro host responde 404. ## Qué se bloquea en una sesión de suplantación {#what-is-blocked-in-an-impersonated-session} Cualquier acción que otorgue acceso más allá de una hora o modifique la seguridad propia del cliente devuelve HTTP 403 `impersonate_forbidden`: | Bloqueado | Motivo | |---|---| | Cambiar la contraseña, TOTP, vincular o desvincular Google/GitHub, editar passkeys | Credenciales propias del cliente | | Eliminar la cuenta | Irreversible | | Crear o editar **API keys** | Acceso de larga duración | | Aprobar un inicio de sesión de CLI, escritorio o MCP (vínculo de dispositivo) | Acceso de larga duración | | Crear acceso a Kubernetes, S3 keys, SSH keys, contraseñas de root, enlaces para compartir consola, credenciales de VPN o proxy | Secretos que perduran tras la sesión | | Canjear códigos de recarga | Campañas de saldo | | Retirar o modificar el pago de comisiones de afiliados | Salida de dinero del sistema | | Editar claves de IA, presupuestos o correos electrónicos de alerta | Configuración del cliente | Todo lo demás funciona: puede ver las páginas, crear o administrar VMs, realizar pedidos, etc. Las acciones se ejecutan con la identidad del cliente y gastan su dinero; las entradas de auditoría anteriores son las que demuestran que un administrador estuvo detrás de la sesión. ## Verificación {#verify} 1. Suplante a un cliente de prueba. El portal se abre y muestra los datos de ese cliente. 2. Intente cambiar la contraseña: obtendrá "forbidden" (impersonation). 3. En **System › Logs › Admin actions**, busque `customer.login_as` con su nombre, el motivo y el sitio, seguido de `customer.login_as.used`. 4. Cierre la ventana y vuelva a abrir el mismo enlace: "link expired or already used". ## Límites y notas {#limits-notes} - El límite de una hora es fijo (3600 segundos). Para continuar, suplante de nuevo. - Priorice la lectura y la reproducción; evite acciones que gasten dinero salvo que el cliente se lo haya solicitado. - Cierre la sesión antes de tiempo con **Revoke sessions** en la página del cliente (esto también cerrará la sesión del cliente). - Los revendedores disponen de su propia suplantación con **Sign in to partner console** (60 minutos) desde Resellers; consulte [Resellers](https://nexcmp.com/es/docs/customers/resellers/). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "La cuenta no está activa" | Cuenta bloqueada o eliminada | Desbloquéela primero o consulte la página del cliente en su lugar. | | El navegador bloquea la ventana | Bloqueador de ventanas emergentes | Permita las ventanas emergentes para la dirección de administración e inténtelo de nuevo. | | "Enlace caducado o ya utilizado" | Límite de una hora o reutilización | Suplante de nuevo. | | Se abre "Not found" | El enlace se utilizó en el host incorrecto | Utilice la ventana abierta por el diálogo; no pegue el enlace en otro lugar. | | Una acción indica "forbidden" | Bloqueado en sesiones suplantadas | Pídale al cliente que lo haga o utilice las pantallas de administración. | --- # Revendedores (marca blanca) {#resellers-white-label} > **Ubicación en el panel de administración:** Customers › Resellers › List (`/resellers`), Domains & SSL (`/resellers/domains`), Permissions & wholesale (`/resellers/entitlements`), Defaults (`/resellers/settings`). Slots de revendedor: System › Admin › License & updates (`/license`). ## Qué hace {#what-it-does} Un **revendedor** obtiene una copia personalizada con su marca del portal de clientes en **su propio dominio**, con sus propios clientes, billetera, precios y (opcionalmente) canales de pago. Le compra a usted a precio mayorista y vende a su propio precio. Sus clientes nunca ven su marca y el dominio del revendedor nunca puede abrir su consola de administración. El revendedor gestiona su negocio desde la **consola de partners** en `https://partner.`. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Licencia | Un **slot de dominio de revendedor** en su licencia por cada dominio personalizado de revendedor. La página de licencia muestra `used/max` slots y un enlace para comprar más. Sin un slot libre, añadir un dominio falla con «Out of license reseller domain slots». | | DNS | Cada dominio de revendedor debe apuntar a su servidor (consulte más abajo). | | Servidor web y TLS | El nombre de host debe llegar al panel de NexCMP a través de su proxy inverso con un certificado válido para dicho nombre. | | Correo electrónico | SMTP configurado para los correos electrónicos de invitación y notificación. | | Interruptor principal | **Reseller settings › General › `rs_enabled`** está activado por defecto. | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Determine la dirección pública del servidor: su dirección IPv4 y, si prefiere CNAME, un nombre de host que apunte a ella (por ejemplo `sites.cloud.example.com`). 2. Abra **Customers › Resellers › Defaults** (`/resellers/settings`), grupo **Domains & SSL**, y configure: | Clave | Significado | |---|---| | `rs_server_ipv4` | La IPv4 pública a la que deben apuntar los registros A de los revendedores. | | `rs_cname_target` | El nombre de host al que deben apuntar los registros CNAME de los revendedores. | | `rs_master_hosts` | Nombres de host que pertenecen a su propio sitio principal (no se pueden asignar a revendedores). | | `rs_platform_domain` | Dominio principal opcional para **subdominios de la plataforma** (por ejemplo `partners.cloud.example.com` para dar a los revendedores `acme.partners.cloud.example.com`). Dejarlo vacío deshabilita la opción. | | `rs_sites_stale_minutes` | Minutos antes de que el servicio de certificados se considere desactualizado (por defecto 15). | | `rs_ssl_fail_hours` | Horas de intentos fallidos antes de generar un error (por defecto 48). | ::: warning Compruebe estos valores antes de enviar instrucciones `rs_server_ipv4`, `rs_cname_target` y `rs_master_hosts` se proporcionan con valores de ejemplo. Reemplácelos con su propio servidor y dominio **antes** de dar instrucciones de DNS a un revendedor; de lo contrario, las instrucciones en pantalla apuntarán al lugar equivocado. ::: 3. Haga clic en **Save** (se solicita un motivo). 4. Asegúrese de que su proxy inverso reenvíe los nombres de host del revendedor al panel de NexCMP y sirva un certificado para cada uno de ellos. El instalador configura nginx y Let's Encrypt solo para el dominio principal (y los nombres `admin.` y `partner.` que resuelvan). Si utiliza Cloudflare, aplique proxy al nombre de host y utilice el modo Full SSL. ## Conectar en NexCMP {#connect-in-nexcmp} ### Crear el revendedor {#create-the-reseller} 1. Abra **Customers › Resellers › List** y haga clic en **New reseller**. El asistente consta de 8 pasos y aprovisiona todo al final; cada paso se puede reintentar de forma segura. | Paso | Datos a completar | |---|---| | **Reseller** | Nombre legal o comercial, **slug** (4–31 caracteres de a–z, 0–9 o `-`, que comience con una letra; también es el prefijo de factura), nombre de contacto, correo electrónico y teléfono, idioma predeterminado, datos de facturación del revendedor (como comprador de recargas de billetera). | | **Console account** | Nombre de usuario, correo electrónico de la cuenta, nombre completo; **Send a one-time invite link by e-mail** (válido 72 horas, recomendado) o mostrar una contraseña temporal una sola vez. | | **Brand** | Nombre de marca, nombre corto, eslóganes, colores primarios, correo electrónico y teléfono de soporte, nombre del vendedor impreso en las facturas de clientes, logotipos (fondo claro y oscuro), isotipo cuadrado y favicon: PNG, JPEG, WEBP o ICO de hasta 256 KB, **no SVG**. | | **Dominios** | El dominio o dominios del cliente con **también www**, cuál es el principal, un **dominio de prueba** (sslip.io) y la opción **dry-run**, o un subdominio de la plataforma. El asistente muestra **DNS OK / DNS no listo** y los registros que se deben crear. | | **Precios y monedero** | Descuento mayorista (%), precio mínimo minorista (% de lista), margen predeterminado (%), límite de crédito, saldo inicial, alerta de saldo bajo, límites de clientes, VM y dominios, funciones del sitio (registro de clientes, protección DDoS, tickets de soporte, plan personalizado, cambio de tamaño, Auto Scaling). | | **Canales de pago** | Quién cobra los pagos de los clientes (ver más abajo) y, opcionalmente, PayPal propio y transferencia bancaria propia de VN. | | **Email** | Nombre del remitente y Reply-To. La dirección From se mantiene como la dirección de la plataforma hasta que se configure DKIM para el dominio del distribuidor. | | **Revisión** | Revise todo y haga clic en **Provision everything** o en **Guardar borrador (aprovisionar más tarde)**. | 2. El aprovisionamiento continúa en segundo plano (cada 30 segundos). Abra el distribuidor para ver el progreso y use **Continue provisioning** o **Retry** si un paso falló. ![Asistente de nuevo distribuidor en el primer paso con valores de ejemplo](https://nexcmp.com/es/docs/images/customers/resellers-01-wizard.webp) ### Apuntar el DNS (lo realiza el distribuidor) {#point-dns-the-reseller-does-this} El distribuidor (o usted) crea los registros que se muestran en la pestaña **Domains & SSL**: | Registro | Nombre | Valor | |---|---|---| | TXT (propiedad, solo la primera vez) | `_site-verify.` | `sv=` que se muestra en pantalla | | A (dominio raíz como `shop.example.net`) | el dominio | su `rs_server_ipv4` | | CNAME (subdominio como `cloud.example.net`) | el dominio | su `rs_cname_target` (o un registro A a `rs_server_ipv4`) | | CNAME (opcional) | `www.` | su `rs_cname_target` | Además: - Elimine cualquier registro **AAAA** (IPv6) a menos que su servidor responda en esa dirección IPv6. - Desactive el proxy de CDN (**desactivado**, nube gris) mientras se verifica el dominio. - Si el dominio tiene registros **CAA**, permita `letsencrypt.org`. El token del registro TXT es diferente para cada dominio; cópielo de la pantalla. El sistema vuelve a comprobar el DNS cada 5 minutos durante las primeras 48 horas, luego cada hora, y libera cualquier nombre cuyo registro TXT siga faltando después de 72 horas. ### Estados del dominio {#domain-states} En **Customers › Resellers › Domains & SSL** (todos los distribuidores) y en la pestaña **Domains & SSL** de un distribuidor: | Estado | Significado | |---|---| | `pending_verify` | Esperando el registro TXT. | | `pending_dns` / `verifying` | Esperando que el registro A o CNAME apunte a usted. | | `issuing` | Certificado en proceso de emisión. | | `active` | Sirviendo el sitio del distribuidor. | | `cert_expiring` | Certificado próximo a caducar; renovación prevista. | | `dns_lost` | El DNS dejó de apuntar a usted; después de 30 días, el dominio se elimina. | | `error` | Consulte el código de error; use **Retry** tras corregirlo. | | `removing` / `removed` | En proceso de eliminación; se devuelve el espacio de la licencia. | Acciones de fila: **Check now**, **Retry**, **Establecer como principal**, **Test mode** (para un dominio de prueba), **Remove**. ## Permisos y venta mayorista {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) es una matriz: una fila por revendedor, con el **descuento** mayorista y el **margen**, y un conmutador por servicio (por ejemplo, DDoS Shield y VPN). Un conmutador es editable cuando la función a nivel de plataforma está activada; de lo contrario, la celda es de solo lectura y enlaza con la configuración. La subpestaña **Top-up codes** establece cuántos códigos puede emitir cada revendedor al mes (consulte [Promotions](https://nexcmp.com/es/docs/billing/promotions/)). Reglas de precios: - Precio mayorista = precio de lista x (1 - descuento), y se puede anular por plan y por ciclo de facturación en la pestaña **Wholesale pricing** del revendedor. - El revendedor establece los precios minoristas y no puede bajar del **precio mínimo** (porcentaje del precio de lista). - El **wallet** del revendedor paga el precio mayorista cuando sus clientes compran. El wallet tiene un límite de crédito, un período de gracia y un tope de sobregiro (consulte Defaults). ## Valores predeterminados {#defaults} **Customers › Resellers › Defaults** (`/resellers/settings`) son las claves `rs_*` que se aplican a cada revendedor. Cada cambio solicita un motivo y queda auditado. | Grupo | Clave | Predeterminado | Significado | |---|---|---|---| | General | `rs_enabled` | 1 | Programa de revendedores activado. | | | `rs_platform_collect_enabled` | 0 | Permite que la plataforma cobre los pagos de los clientes para los revendedores. **Activar únicamente tras una revisión legal.** | | | `rs_totp_required` | 1 | Las cuentas de la consola del revendedor deben usar autenticación de dos factores. | | | `rs_agreement_version` | 1 | Versión del acuerdo de revendedor que deben aceptar. | | Precios predeterminados | `rs_default_discount_bp` | 2000 (20 %) | Descuento mayorista para nuevos revendedores (puntos básicos, de 0 a 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | Margen predeterminado (de 0 a 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | Precio mínimo minorista (de 0 a 20000). | | | `rs_default_max_domains` | 3 | Dominios permitidos por revendedor. | | Wallet y liquidaciones | `rs_grace_hours` | 72 | Período de gracia antes de que los servicios de los clientes se vean afectados por un wallet de revendedor vacío. | | | `rs_overdraft_cap_cents` | 5000 | Sobregiro permitido en el wallet. | | | `rs_retention_days` | 14 | Días antes de que se destruyan las VM de un revendedor cerrado. | | | `rs_payout_hold_days` | 30 | Días que se retiene una comisión antes de poder retirarla. | | | `rs_payout_min_cents` | 5000 | Retiro mínimo. | | | `rs_topup_min_cents` | 2000 | Recarga mínima de wallet por parte de un revendedor. | | Pagos y correo | `rs_webhook_base` | vacío | URL base pública para los webhooks de pasarela del revendedor (vacío = usar la URL del sitio). | | | `rs_mail_from` | vacío | Dirección de remitente para los correos electrónicos del revendedor. | | | `rs_invoice_show_processor` | 1 | Mostrar el procesador de pagos en las facturas. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | Indica si los revendedores pueden configurar su propio Stripe o USDT. | ## Quién cobra los pagos de los clientes {#who-collects-customer-payments} | Modo | Significado | |---|---| | **El revendedor cobra (canales propios)** — predeterminado | El revendedor conecta su propio Stripe, PayPal, USDT o cuenta bancaria. Sus webhooks son `https:///v1/billing//webhook/r/`. Las tarjetas guardadas y [auto top-up](https://nexcmp.com/es/docs/billing/auto-top-up/) no están disponibles para estos sitios. | | **La plataforma cobra** | Sus canales se muestran en el sitio del revendedor. Bloqueado hasta `rs_platform_collect_enabled = 1`. | | **Mixto** | Una combinación elegida por canal. | ## Qué ve el revendedor {#what-the-reseller-sees} La consola de socios en `https://partner.` incluye Overview, Reports, Customers, VMs, Tickets, Orders, Payments, Prices, Brand, Landing & legal, Domains & SSL, Email, Wallet y Payment channels. Las cuentas de la consola tienen el rol *reseller* (completo) o *staff* (solo lectura). Para comprobarlo usted mismo, abra el revendedor y haga clic en **Sign in to partner console**: accederá durante 60 minutos, cada operación de escritura se registrará con su nombre tanto en el registro de administración como en el del revendedor, y las operaciones monetarias requerirán una segunda confirmación. ## Verificación {#verify} 1. Tras el aprovisionamiento, la fila del revendedor en la lista muestra *active* y una columna **Provisioning** en verde. 2. Abra el dominio del revendedor en un navegador: aparecerá su propia página de inicio de sesión con su marca. `https:///admin` responde 404. 3. Registre un cliente de prueba en ese dominio: el cliente aparecerá en **Customers › List** con el revendedor en la columna **Site**. 4. La página de licencias muestra un slot más en uso. ## Límites y notas {#limits-notes} - Un slot de licencia por dominio personalizado o de prueba; los subdominios de la plataforma no consumen un slot. - Suspender a un revendedor conserva los datos; **Close reseller** libera todos los slots de dominio, y la destrucción de VM solo se permite tras el periodo de retención. - Los clientes del revendedor aparecen en su lista de clientes y se puede iniciar sesión en su nombre igual que con cualquier otro (el enlace se abre en el dominio del revendedor). - Los revendedores no pueden ver ni modificar sus canales de pago, los valores predeterminados de cuotas ni a otros revendedores. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Sin cupos de dominios de revendedor en la licencia" | Todos los slots están en uso | Libere un slot (elimine un dominio) o compre más en la página de licencias. | | Dominio bloqueado en `pending_verify` | Falta el registro TXT | Cree el registro TXT exactamente como se indica; use **Check now**. | | Dominio bloqueado en `pending_dns` | El registro A/CNAME no apunta a usted, hay un registro AAAA o el proxy CDN está activado | Corrija los DNS, desactive el proxy y haga clic en **Check now**. | | Estado `error` | Consulte el código en la fila (por ejemplo, CAA bloqueando Let's Encrypt, límite de tasa) | Corrija el problema y haga clic en **Retry**. | | El navegador indica que el host es desconocido o muestra "421" | El nombre de host no está en la licencia o no está enrutado hacia el panel | Añada el dominio mediante el revendedor (consume un slot) y corrija el proxy inverso. | | Las instrucciones muestran una IP o host incorrecto | `rs_server_ipv4` / `rs_cname_target` aún tienen los valores de ejemplo | Configúrelos en Defaults. | | El revendedor no puede habilitar el cobro a través de la plataforma | Bloqueado | Configure `rs_platform_collect_enabled` tras la revisión legal. | --- # Personalización de marca {#branding} > **Ubicación en el panel de administración:** System › Settings › Brand (`/settings/branding`). Relacionado: System › Settings › General (`/settings`) para las URL y los datos del vendedor impresos en las facturas. ## Qué hace {#what-it-does} NexCMP es de marca blanca: el producto no lleva el nombre del proveedor y todo lo que ven sus clientes es **su** marca. Los ajustes de marca se aplican a las páginas de inicio de sesión y registro, el portal, la consola de administración y los correos electrónicos. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Archivos | Logotipos: SVG, PNG, JPEG, WEBP o ICO, **hasta 512 KB cada uno**. | | Dependencias | Ninguno. | ## Pasos {#steps} 1. Abra **System › Settings › Brand**. 2. En la tarjeta **Identity** complete: | Campo | Notas | |---|---| | **Brand name** (obligatorio) | Hasta 60 caracteres. Se muestra en el portal, correos electrónicos, facturas y páginas legales. | | **Nombre del vendedor en las facturas** | Hasta 120 caracteres. Si se deja en blanco, se utiliza el nombre de la marca. | | **Brand color** | Un color `#rrggbb`; el botón pequeño junto al campo lo restablece al color predeterminado. | | **Site currency** | **USD**: los precios y saldos se muestran solo en USD, sin cambio de divisa. **VND**: también muestra el importe convertido según el tipo de cambio guardado (consulte [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/)). | 3. Haga clic en **Save**. 4. En la tarjeta **Logo & favicon**, suba las tres imágenes —**Logo (light background)**, **Logo (dark background)** y **Favicon**— con **Upload** (o **Replace**); **Remove** elimina una. ![Página Brand con los campos de identidad y las tres imágenes subidas](https://nexcmp.com/es/docs/images/customers/branding-01-brand.webp) ### Ajustes relacionados en General {#related-settings-in-general} **System › Settings › General** cuenta con dos pestañas que completan la configuración: | Pestaña | Campos | |---|---| | **Branding & URLs** | Nombre de marca (correo electrónico, facturas), idioma predeterminado (inglés o vietnamita), **Customer app URL**, **Console URL**, **Admin URL** (enlace de suplantación de revendedor) y **Partner console URL** (enlaces de invitación, correos electrónicos de revendedores). El asistente de configuración completa estos campos con `https://`, `https:///admin` y `https:///console`. | | **Seller & invoicing** | Razón social, NIF/CIF, dirección, correo electrónico de contacto y el prefijo del número de factura. Consulte [Facturas y libro mayor](https://nexcmp.com/es/docs/billing/invoices-and-ledger/). | El **From name** de los correos electrónicos se define en **System › Settings › Email** ([SMTP y correos electrónicos](https://nexcmp.com/es/docs/administration/smtp-and-emails/)). ## Los archivos subidos se verifican {#uploaded-files-are-checked} - Las imágenes de mapa de bits se reconocen por su contenido (no por el nombre de archivo) y se miden. - **Los archivos SVG se reconstruyen** a partir de una lista segura de formas. Si un archivo contiene scripts, `foreignObject`, atributos de eventos, enlaces externos, `url(...)` que apunten al exterior, un DOCTYPE o entidades, se **rechaza** (`svg_unsafe`). - Un archivo demasiado grande se rechaza con `asset_too_large`, un tipo incorrecto con `asset_type` y dimensiones no válidas con `asset_dimensions`. - Los archivos se sirven desde su propio dominio con cabeceras de seguridad estrictas. ## Verificación {#verify} 1. Abra la página de inicio de sesión del portal en una ventana privada: aparecerán el logotipo, el nombre y el color. 2. Compruebe la pestaña del navegador para ver el favicon (los navegadores almacenan en caché los favicons; recargue borrando la caché si sigue viendo el anterior). 3. Envíe un correo electrónico de prueba (por ejemplo, **Send reset link** para un cliente de prueba) y compruebe el nombre de marca en el asunto y el pie de página. ## Límites y notas {#limits-notes} - El logotipo para fondo oscuro se utiliza cuando el cliente o el administrador cambia al tema oscuro. - Los revendedores tienen su propia marca; suben archivos PNG, JPEG, WEBP o ICO de hasta 256 KB (sin SVG). Consulte [Revendedores](https://nexcmp.com/es/docs/customers/resellers/). - Cualquier cambio en el color de la marca o en el logotipo se muestra al recargar la página; los correos electrónicos ya enviados no se modifican. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Subida rechazada: `svg_unsafe` | El archivo SVG contiene scripts, enlaces o referencias externas | Exporte un SVG simple (sin scripts ni imágenes externas) o utilice PNG. | | `asset_too_large` | Archivo superior a 512 KB | Comprima o reduzca el tamaño de la imagen. | | `asset_type` | No es SVG, PNG, JPEG, WEBP ni ICO | Convierta el archivo. | | `invalid_argument: primary` | El color no es `#rrggbb` | Utilice un valor hexadecimal de seis dígitos. | | El logotipo antiguo sigue visible | Caché del navegador | Fuerce la recarga; los favicons pueden tardar más. | | Los precios solo se muestran en USD | La moneda del sitio es USD | Cambie a VND y asegúrese de que haya un tipo de cambio guardado. | --- # Páginas legales {#legal-pages} > **Ubicación en el admin:** System › Settings › Legal (`/settings/legal`). **Dónde los ven los clientes:** `https:///terms` y `/privacy`, vinculados desde el registro y el checkout. ## Qué hace {#what-it-does} Su instalación publica dos páginas: **Terms of Service** y **Privacy Policy**. Hasta que redacte las suyas, NexCMP muestra un **texto neutro predeterminado** que no menciona al proveedor de software ni promete ningún servicio en particular. Sustitúyalo por un texto revisado por su asesor legal antes de empezar a vender. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador. | | Contenido | Markdown sin formato, hasta **50 KB** por página e idioma. | | Dependencias | El nombre de la marca y los datos del vendedor ([Branding](https://nexcmp.com/es/docs/customers/branding/)) se insertan en el texto predeterminado. | ## Pasos {#steps} 1. Abra **System › Settings › Legal**. Cada una de las dos páginas tiene su propia tarjeta con la etiqueta *Using the default text* o *Using your text*. 2. Seleccione la pestaña de idioma, **English** o **Tiếng Việt**. 3. Escriba su texto. Mientras el cuadro esté vacío, el texto predeterminado se mostrará tenue como marcador de posición. Para partir de él, haga clic en **Start from the default text** y luego edítelo. 4. Haga clic en **Save**. El contador de tamaño muestra `used / 50 KB`. 5. Haga clic en **View on the customer site** para abrir `/terms` o `/privacy`. 6. Para volver a la versión predeterminada en un idioma, haga clic en **Clear, back to default** y guarde los cambios. ![Configuración legal con la tarjeta Terms of Service mostrando el texto predeterminado como punto de partida](https://nexcmp.com/es/docs/images/customers/legal-01-terms.webp) ## Qué contienen las páginas predeterminadas {#what-the-default-pages-contain} El texto predeterminado se almacena en el producto como `legal_default.json` y se completa con el nombre de su marca, el nombre del vendedor, la URL del sitio y el correo de contacto (desde **Seller & invoicing** en System › Settings › General; si no se define ningún correo, apunta a su equipo de soporte). | Página | Secciones | |---|---| | **Terms of Service** | 1 El servicio · 2 Cuentas y verificación · 3 Precios y facturación · 4 Reembolsos · 5 Sus datos · 6 Uso aceptable · 7 Disponibilidad y soporte · 8 Suspensión y rescisión · 9 Responsabilidad · 10 Modificaciones y ley aplicable (la legislación del domicilio comercial del vendedor) | | **Privacy Policy** | 1 Qué recopilamos · 2 Para qué lo usamos · 3 Cookies y almacenamiento local · 4 Quién más lo ve · 5 Conservación · 6 Sus derechos · 7 Contacto | ::: warning No constituye asesoramiento legal El texto predeterminado es una plantilla neutra. Solicite su revisión antes de utilizarlo con clientes reales, especialmente las secciones sobre reembolsos, responsabilidad y ley aplicable. ::: ## Reglas de markdown {#markdown-rules} - Compatible con: encabezados (`# 1. Title`), párrafos, listas con viñetas y numeradas, **negrita** y enlaces `[text](https://example.com)`. - Los enlaces deben comenzar con `http://` o `https://`. - **Se rechaza el código HTML sin procesar** (cualquier ``, ` # Información general del portal de clientes {#customer-portal-overview} > **Ubicación en el portal:** `https:///` — los clientes inician sesión en `/login`. Los administradores usan `/admin`; el mismo inicio de sesión abre ambos si la cuenta es de administrador. El portal es lo que sus clientes usan a diario. Lleva su nombre, logotipo y colores ([Branding](https://nexcmp.com/es/docs/customers/branding/)) y solo muestra los servicios que ha activado ([Modules](https://nexcmp.com/es/docs/infrastructure/modules/)). ## El panel de control {#the-dashboard} Tras iniciar sesión, **Dashboard** muestra: | Bloque | Significado | |---|---| | Saldo del monedero | Crédito actual y una estimación de cuántos días durará al ritmo de consumo actual | | Gastado este mes | Cargos acumulados y una previsión para el final del mes | | Máquinas virtuales | Cada VM con estado, IP, CPU y RAM, y acciones rápidas (Console, Restart) | | Ancho de banda | Tráfico entrante/saliente durante 1 h, 6 h, 24 h, 7 d, 30 d | | Actividad reciente | Últimos eventos en la cuenta | | Inicio rápido | Una lista de tareas: crear una VM, añadir una SSH key, recargar saldo, activar la recarga automática y verificar el correo electrónico | ![El panel del cliente con el saldo del monedero, la previsión de gasto, una máquina virtual en ejecución y la lista de inicio rápido](https://nexcmp.com/es/docs/images/portal/overview-01-dashboard.webp) ## Navegación {#navigation} El menú agrupa los servicios por tipo. Un servicio que haya desactivado (o cuyo origen no esté conectado) no se mostrará. | Área | Página | |---|---| | Instances | [Máquinas virtuales](https://nexcmp.com/es/docs/portal/virtual-machines/) y sus páginas de detalles | | Deploy | [Pedidos](https://nexcmp.com/es/docs/portal/ordering/) — crear un recurso | | Almacenamiento | Snapshots, backups y volúmenes si están activados — [Snapshots](https://nexcmp.com/es/docs/portal/snapshots/) | | Billing | [Monedero y recargas](https://nexcmp.com/es/docs/portal/sign-up-and-wallet/), facturas, pedidos, cuotas | | Cuenta | Perfil, inicio de sesión y seguridad, preferencias, recarga automática | | Soporte | Widget de chat y tickets — [Support](https://nexcmp.com/es/docs/portal/support/) | | Documentación de la API | `/apidoc` — [API](https://nexcmp.com/es/docs/developers/api/) | ## Cuenta {#account} **Account** tiene cuatro pestañas: **Profile** (nombre, correo electrónico, ID de cliente, solicitud de eliminación de cuenta), **Sign-in & security** (contraseña, passkeys, Google/GitHub vinculados), **Preferences** (idioma, moneda de visualización) y **Auto top-up** ([Auto top-up](https://nexcmp.com/es/docs/billing/auto-top-up/)). Un cliente no puede eliminar la cuenta directamente: debe pulsar **Request account deletion**; tras eliminar todas las máquinas virtuales, un operador revisa la solicitud (Customers › Deletion requests) y el cliente puede retirarla mientras esté pendiente. ## Idioma y moneda {#language-and-currency} El portal está disponible en 16 idiomas y muestra los precios en una moneda de visualización elegida según el idioma; consulte [Moneda y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). Los clientes pueden cambiar ambos en **Preferences**. ## Cuotas de clientes {#customer-quotas} **Billing › Quotas** muestra qué cantidad de cada recurso (CPU, memoria, almacenamiento, IP, VM) puede utilizar el cliente en función de lo que haya pagado; consulte [Cuotas](https://nexcmp.com/es/docs/billing/quotas/). --- # Registro, billetera y recarga {#sign-up-wallet-and-top-up} > **Dónde está en el portal:** `/register`, `/login`, Billing (`/billing`). ## Crear una cuenta {#create-an-account} 1. El cliente abre `https:///register` e introduce correo electrónico y contraseña (al menos 10 caracteres con letras y dígitos), o utiliza **Google**, **GitHub** o una **passkey** si los ha habilitado; consulte [Seguridad](https://nexcmp.com/es/docs/administration/security/#customer-sign-in). 2. Si el captcha está habilitado, lo completa. 3. Se envía un correo electrónico de verificación a través de su [SMTP](https://nexcmp.com/es/docs/administration/smtp-and-emails/). La verificación es obligatoria antes de crear una VM si la configuración de ventas así lo requiere. ![La página de registro con los campos de correo electrónico y contraseña](https://nexcmp.com/es/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip Sin un SMTP operativo, los clientes no pueden verificar su correo electrónico ni restablecer su contraseña. Configure [SMTP](https://nexcmp.com/es/docs/administration/smtp-and-emails/) primero. ::: ## La billetera {#the-wallet} Todo se paga desde el saldo de la **billetera** en su moneda de facturación. La página **Billing** muestra: | Sección | Significado | |---|---| | Capacidad de gasto | Saldo más recargas pendientes | | Cargos acumulados | Servicios por horas consumidos en el ciclo actual, aún no liquidados | | Saldo pendiente | Cualquier importe adeudado | | Historial de facturación | Pestañas **Invoice History**, **Payment Order**, **Ledger**, **Orders** | ![La página de Billing con la capacidad de gasto, los cargos acumulados y las pestañas de historial](https://nexcmp.com/es/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## Añadir saldo {#add-credit} 1. Haga clic en **Deposit**. 2. Introduzca el importe. El mínimo corresponde a su [recarga mínima](https://nexcmp.com/es/docs/billing/minimum-top-up/). 3. Elija un canal de pago (tarjeta, PayPal, USDT o transferencia bancaria si la interfaz está en vietnamita); los canales son los habilitados en [Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/). 4. Pague. El saldo se actualiza cuando el proveedor de pagos lo confirma. Las tarjetas guardadas, Stripe Link y PayPal pueden reutilizarse y usarse para la [recarga automática](https://nexcmp.com/es/docs/billing/auto-top-up/); consulte [Métodos de pago guardados](https://nexcmp.com/es/docs/billing/saved-payment-methods/). ## Canjear un código {#redeem-a-code} **Redeem code** añade saldo a partir de un cupón emitido por usted (Finance › Billing › Vouchers) o aplica un código promocional — consulte [Promociones](https://nexcmp.com/es/docs/billing/promotions/). ## Facturas {#invoices} Cada pedido pagado genera una factura que muestra sus datos de vendedor ([General settings](https://nexcmp.com/es/docs/administration/general-settings/)). Los clientes pueden abrirla desde **Invoice History** e imprimirla o guardarla como PDF desde el navegador. ## Cargos por hora {#hourly-charges} Los servicios por hora se cobran por cada hora de existencia del recurso; los importes se acumulan y una hora individual puede redondearse a $0.00. Si el saldo no es suficiente, los servicios se suspenden según sus reglas de facturación y se notifica al cliente por correo electrónico (`low_balance`). --- # Contratar un servicio {#ordering-a-service} > **Dónde está en el portal:** Deploy (`/deploy/vm`). **Dónde se controla en la administración:** Services (planes, precios) y System › Admin › License & updates (módulos). La página de pedido es un formulario continuo con pasos numerados. Al seleccionar otro servicio en el paso 1, la página se mantiene y cambian los pasos siguientes. ## Pasos {#steps} 1. **Service** — Cloud Servers y los demás servicios que haya activado (Kubernetes, Object Storage, Images, Private Cloud, VPN …). 2. **Location** — la [zona](https://nexcmp.com/es/docs/infrastructure/zones/). Los precios y el tráfico incluido pueden variar según la ubicación. 3. **Plan** — un plan fijo (vCPU, RAM, disco NVMe, precio por hora) o **Custom** (el cliente elige vCPU, RAM y disco; tarifado por recurso). Los planes se configuran en [Plans](https://nexcmp.com/es/docs/catalog/plans/). 4. **Billing cycle** — **Por hora** o ciclos prepagados mensuales/anuales con descuento (por ejemplo, 1 año −10%, 2 años −15%, 3 años −20%). 5. **Operating system** — lista de plantillas, **My Images** (imágenes subidas por el cliente) y la versión. 6. **Hostname & quantity** — nombre (o **Randomize**) y número de servidores. ![Página de pedido mostrando los pasos de servicio, ubicación y plan](https://nexcmp.com/es/docs/images/portal/ordering-01-plan.webp) ![Pasos de ciclo de facturación y sistema operativo en la página de pedido](https://nexcmp.com/es/docs/images/portal/ordering-02-cycle-os.webp) ## Realizar el pedido {#placing-the-order} El resumen muestra el precio. El pedido se cobra del monedero **antes** del aprovisionamiento, tras la [verificación de cuota](https://nexcmp.com/es/docs/billing/quotas/) y las reglas de [saldo mínimo](https://nexcmp.com/es/docs/billing/minimum-top-up/). Por lo general, una VM pasa a *Running* en un minuto; el cliente ve los pasos de despliegue en la pestaña **Activity** de la VM y recibe el correo "VM ready" con la contraseña inicial (visible una sola vez durante 10 minutos). ## Motivos que pueden impedir un pedido {#what-can-stop-an-order} | Mensaje / causa | Solución | |---|---| | Saldo insuficiente | Recargar saldo — [Registro, monedero y recargas](https://nexcmp.com/es/docs/portal/sign-up-and-wallet/) | | Cuota excedida | Aumentar la cuota — [Cuotas](https://nexcmp.com/es/docs/billing/quotas/) | | Correo electrónico no verificado | El cliente debe verificar el correo electrónico | | No hay ningún plan para la ubicación seleccionada | Habilitar un plan en esa zona — [Plans](https://nexcmp.com/es/docs/catalog/plans/) | | Licencia no válida | Los clientes no pueden crear nuevos servicios — [Licencia](https://nexcmp.com/es/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # Máquinas virtuales {#virtual-machines} > **Dónde está en el portal:** Instances (`/vms`) y la página de una VM (`/vms/`). **Instances** muestra las VM del cliente con nombre, SO, estado, IP, características y coste. Haga clic en una para abrir su página. ## La página de la VM {#the-vm-page} Pestañas: **Overview**, **Console**, **AI SSH Agent** (cuando el módulo de IA está activo), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**. ![Vista general de una máquina virtual con estado, recursos, IP, gráfico de ancho de banda y registro de actividad](https://nexcmp.com/es/docs/images/portal/virtual-machines-01-overview.webp) ### Acciones {#actions} | Acción | Efecto | |---|---| | Consola | Abre la consola en el navegador — [Console](https://nexcmp.com/es/docs/portal/console/) | | Reiniciar / Detener / Forzar parada | Control de energía | | Restablecer contraseña | Genera una nueva contraseña, visible una sola vez | | Reinstalar SO | Reconstruye a partir de una plantilla; los datos se pierden | | Cambiar IP | Reemplaza la IP pública (donde el origen lo admita) | | Habilitar Auto Scaling | Escala CPU/RAM bajo carga cuando está habilitado | | Eliminar | Destruye la VM; la facturación por horas se detiene | ### Información mostrada {#information-shown} Tiempo de actividad, coste de este mes, vCPU/RAM/disco con uso en tiempo real, IP pública y privada, nombre de usuario, gráfico de ancho de banda, registro de acciones y resumen de facturación (plan, ciclo, horas, restante). ::: info Los campos dependen del origen La página de una VM muestra únicamente lo que admite su origen. Por ejemplo, una VM de Proxmox VE no tiene reenvío de puertos ni cambio de IP, y su lista de SO sigue el conjunto de plantillas de su clúster. Consulte la tabla de funcionalidades en [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). ::: ## Pestaña de facturación {#billing-tab} Muestra el plan, el ciclo, el total de horas, el tiempo restante y el registro de facturación. Las VM por horas acumulan costes hasta que se eliminan. El cliente puede **cambiar de ciclo** para pagar por adelantado un período más largo con descuento. ## Para administradores {#for-administrators} La misma VM es visible en Services › Virtual Machines en la consola de administración, donde puede actuar en nombre del cliente o [iniciar sesión como](https://nexcmp.com/es/docs/customers/login-as/) él. --- # Consola {#console} > **Ubicación en el portal:** página de la VM → pestaña **Console**. **Ubicación en la administración:** System › Admin › License & updates → modules (web SSH). ## Qué hace {#what-it-does} La pestaña **Console** abre una sesión gráfica (VNC) con la VM en el navegador, incluso cuando la red interna de la VM no funciona. Dispone de un terminal **web SSH** como segunda opción cuando el módulo SSH está habilitado. ## Requisitos {#requirements} | Elemento | Consola VNC | Web SSH | |---|---|---| | CloudStack | Console proxy VM (CPVM) accesible para el panel — consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) | Un puerto SSH accesible en la VM | | Proxmox VE | Funciona a través del panel (noVNC mediante la API de Proxmox; la huella TLS está fijada) — consulte [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) | Igual | | Panel | URL de la consola configurada en [General settings](https://nexcmp.com/es/docs/administration/general-settings/) | El servicio `ssh-proxy` y el flag de módulo `feature_ssh_web`; desactivado por defecto — consulte [Modules](https://nexcmp.com/es/docs/infrastructure/modules/) | Si el módulo web SSH está desactivado, la pestaña muestra **VNC only**. ## Uso {#use-it} 1. Abra la VM → **Console**. 2. Haga clic en **Console** (o en **Open in new window**). Se emite un ticket de corta duración y la consola se abre en `https:///console`. 3. Inicie sesión con el nombre de usuario y la contraseña de la VM (visibles en la pestaña Overview; restablézcalos si los ha perdido). ![La pestaña Console de una máquina virtual](https://nexcmp.com/es/docs/images/portal/console-01-tab.webp) ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Disconnected" inmediatamente | El navegador conservó una ruta de consola antigua | Borre los datos del sitio para el dominio y vuelva a intentarlo | | Pantalla negra | La VM está detenida o iniciándose | Inicie la VM y espere | | La consola no se abre en CloudStack | La console proxy VM no está en ejecución o no es accesible | Compruebe las VM del sistema en CloudStack | | No hay opción de SSH | Módulo Web SSH desactivado | Actívelo solo después de instalar `ssh-proxy` | --- # Snapshots y Backups {#snapshots-and-backups} > **Dónde está en el portal:** Snapshots (`/snapshots`), Snapshot schedules (`/snapshots/schedules`), Backups (`/backups`). Visible solo cuando la función está habilitada en el admin. ## Qué hace {#what-it-does} Un snapshot guarda el estado del disco de una VM para que el cliente pueda revertir tras un cambio erróneo. Las Snapshots pueden crearse manualmente o de forma programada. ## Disponibilidad {#availability} | Source | Snapshots | Notas | |---|---|---| | CloudStack | Sí | Snapshots de volumen; almacenamiento facturado según la configuración | | Proxmox VE | Sí | Hasta **5 por VM**; crear, listar, restaurar y eliminar | La opción del menú aparece solo cuando la función de Snapshots está activada y el cliente tiene una VM cuyo origen la admite. ## Uso {#use-it} 1. Abra **Snapshots**, haga clic en **Create**, elija la VM y asigne un nombre. 2. Espere hasta que el estado sea *ready*. 3. Para volver atrás, elija **Restore** en el snapshot y confirme — la VM vuelve a ese estado (y se reinicia cuando es necesario). 4. Elimine las Snapshots que ya no necesite. ::: warning Al restaurar se descarta todo lo escrito después del snapshot. Las VM protegidas no se pueden restaurar ni destruir desde el portal. ::: --- # Soporte para clientes {#support-for-customers} > **Dónde está en el portal:** el globo de chat en cada página, `/chat` y Support tickets. **Dónde está en el admin:** Customers › Support › Tickets (`/support/tickets`), pestaña **Settings**. ## Para clientes {#for-customers} - **Globo de chat** (esquina inferior de cada página): haga una pregunta; [AI Chat](https://nexcmp.com/es/docs/ai/ai-chat/) responde utilizando su documentación y los propios datos de la cuenta del cliente. **Expand** abre la misma conversación en `/chat`. - **Talk to staff**: transfiere la conversación a su equipo (a través de su grupo de Telegram de administradores). - **Botones de Telegram / Zalo**: aparecen solo después de configurar los enlaces en los ajustes de soporte. - **Tickets**: para problemas más complejos; las respuestas se envían por correo electrónico (`ticket_reply`). ## Para usted {#for-you} 1. Abra **Customers › Support › Tickets**; los nuevos tickets y chats aparecen aquí con la conversación. 2. Responda en el hilo. Se enviará un correo electrónico al cliente a través de su [SMTP](https://nexcmp.com/es/docs/administration/smtp-and-emails/). 3. En la pestaña **Settings**, active o desactive el widget de chat, configure el enlace de Telegram y el enlace de Zalo (solo https) y elija si la IA responde automáticamente — consulte [AI Chat](https://nexcmp.com/es/docs/ai/ai-chat/). 4. Conecte [Telegram alerts](https://nexcmp.com/es/docs/administration/telegram-notifications/) para que su equipo reciba notificaciones de nuevos chats. --- # Proveedor de IA {#ai-provider} > **Dónde está en el admin:** System › Settings › AI provider (`/settings/ai`). El interruptor del módulo de IA está allí y en System › Admin › License & updates (`/license`), tarjeta **Module**. ## Qué hace {#what-it-does} AI Chat (chat de soporte automático) y AI Agent (administración de VM en lenguaje natural) no incluyen un modelo integrado. Usted elige **su propio proveedor**: cualquier servicio que ofrezca una API `chat/completions` **compatible con OpenAI**, por ejemplo OpenAI, OpenRouter, una pasarela LiteLLM o su propio servidor vLLM. NexCMP almacena el endpoint y la clave de API (cifrados) y los utiliza para cada función de IA. Usted le paga directamente al proveedor. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Endpoint | Una URL base compatible con OpenAI (`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP añade `/chat/completions` a una URL que termina en `/v1`; para cualquier otra URL añade `/v1/chat/completions`; una URL que ya termina en `/chat/completions` se utiliza tal cual. | | Modelo | Un modelo compatible con **tool (function) calling**. Tanto AI Chat como el Agent dependen de ello. | | API key | Una clave para ese endpoint. Se recomienda una clave con un **límite de gasto** en el proveedor (por ejemplo, una clave virtual de LiteLLM con presupuesto mensual). | | Red | El servidor del panel debe poder conectarse al endpoint mediante HTTP(S). Las URL introducidas en el formulario solo pueden apuntar a Internet en los puertos 80, 443, 8080 u 8443; para utilizar una dirección interna, guarde primero el proveedor y luego realice la prueba. | | Dependencias | El módulo **AI** activado. Para el Agent, consulte [AI Agent](https://nexcmp.com/es/docs/ai/ai-agent/#requirements). | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Regístrese con el proveedor y cree una API key. Si el proveedor admite presupuestos o límites de frecuencia, establezca un límite mensual. 2. Anote la **URL base** y el **nombre exacto del modelo** (y, opcionalmente, hasta cuatro modelos de reserva). 3. Pruébelo desde el servidor de NexCMP antes de introducirlo: ```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"}]}' ``` Una respuesta JSON con `choices[0].message.content` indica que el endpoint funciona. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › AI provider**. 2. En la tarjeta **Module AI**, active el módulo (**on**). Mientras no esté activado, los clientes no verán AI Chat ni el AI Agent en el portal. (También puede activarlo en **License & updates**). 3. En la tarjeta **Connection**, complete: | Campo | Ejemplo | Notas | |---|---|---| | Usar este proveedor | activado | Requiere una URL base, un modelo y una clave para poder activarse. | | Nombre para mostrar | `LiteLLM` | Hasta 60 caracteres. | | URL base (compatible con OpenAI) | `https://ai.example.com/v1` | `http://` o `https://`, hasta 300 caracteres, sin espacios. | | API key del proveedor | `sk-XXXX` | Se almacena cifrada; posteriormente solo se muestran los últimos 4 caracteres. Déjela vacía para conservar la clave guardada. | | Modelo predeterminado | `gpt-4o-mini` | Letras, dígitos y `- _ . / : @`. | | Modelos de reserva | `gemini-2.5-flash` | Separados por comas, hasta 4. Se utilizan cuando el modelo predeterminado falla. | | Esfuerzo de razonamiento | Predeterminado (no se envía) | `Minimal`, `Low`, `Medium` o `High`. Para modelos de razonamiento (Gemini, serie o), un nivel bajo responde mucho más rápido. Déjelo en Default para modelos normales. | 4. Haga clic en **Save** y luego en **Test connection**. La prueba envía una pregunta breve y muestra `Connected — , ms` o el error devuelto por el proveedor. ![Página de AI provider con el módulo AI activado y el formulario de conexión completado con valores de ejemplo](https://nexcmp.com/es/docs/images/ai/ai-providers-01-connection.webp) ### Qué ocurre al guardar {#what-saving-does} - La configuración del proveedor se guarda como una entrada de configuración única y la clave se cifra con AES-256-GCM, vinculada a este propósito, utilizando la clave maestra de la instalación. - Los ajustes de soporte **Primary model** y **Fallback model** (utilizados por AI Chat) se configuran automáticamente con su modelo predeterminado y el primer modelo de reserva. - El cambio se registra en el registro de auditoría (endpoint, modelo, si la clave cambió — nunca la clave). ## Verificación {#verify} 1. **Test connection** se muestra en verde. 2. Inicie sesión en el portal como cliente de prueba: el menú ahora ofrece **AI Chat** (o la burbuja de chat) y **AI Agent**. 3. Pregunte a AI Chat "What is my balance?". Una respuesta que indique su saldo real demuestra que el proveedor gestiona las tool calls correctamente. ## Límites y notas {#limits-notes} - **Un solo proveedor.** NexCMP utiliza un único proveedor configurado para Chat, Agent y la investigación de tickets. Los modelos de reserva ofrecen resiliencia dentro de ese proveedor. - **Seguridad de la clave.** La clave guardada se envía únicamente al endpoint guardado. Si cambia la Base URL, debe introducir la clave nuevamente antes de realizar la prueba. - **Límites por cliente.** AI Chat solo está disponible para clientes autenticados, con límites de mensajes por minuto y por chat. El agente tiene un límite diario de llamadas por cuenta. Consulte [AI Chat](https://nexcmp.com/es/docs/ai/ai-chat/) y [AI Agent](https://nexcmp.com/es/docs/ai/ai-agent/). - **Privacidad.** Las preguntas de los clientes y los datos que la IA consulta para ese cliente (solo lectura) se envían a su proveedor. Indíquelo en su [política de privacidad](https://nexcmp.com/es/docs/customers/legal/). - **Control de costos.** NexCMP no tarifica los costos de IA; utilice las funciones de presupuesto del proveedor. - El módulo se puede desactivar en cualquier momento: los elementos de menú de IA desaparecen y las rutas de IA responden 404 `module_disabled`. Algunas tareas en segundo plano de AI Chat (investigación de tickets, respuestas diferidas) aplicarán el cambio en el siguiente reinicio del panel. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `base_url must be an http(s) URL` | Esquema ausente o espacios | Utilice `https://host/v1`. | | `api_key is required to enable the provider` | No hay ninguna clave almacenada | Introduzca la clave y guarde. | | `base_url and model are required to enable the provider` | Campo vacío | Complete ambos. | | "URL base bloqueada: solo http(s) público, puertos 80/443/8080/8443" | Prueba de una dirección interna no guardada u otro puerto | Guarde primero el proveedor y luego realice la prueba. | | `api_key is required (enter the key again when you change the endpoint)` | La Base URL difiere de la guardada | Vuelva a introducir la clave. | | `model: letters, digits and - _ . / : @` | Carácter no válido | Utilice el ID de modelo exacto del proveedor. | | `fallback_models: up to 4 model names` | Demasiados | Mantenga cuatro o menos. | | La prueba falla con 401 | Clave incorrecta | Compruebe la clave y el endpoint. | | La prueba falla con 404 o "model not found" | Ruta o modelo incorrectos | Compruebe la Base URL (`/v1`) y el ID de modelo. | | `Too many tests — wait a minute` (429) | Más de 10 pruebas por minuto | Espere. | | El portal sigue sin mostrar el menú de IA | Módulo desactivado o proveedor no marcado como "in use" | Active el módulo y habilite el proveedor. | --- # AI Chat {#ai-chat} > **En el admin:** Customers › Support › Ticket, pestaña **AI settings** (`/support/tickets?tab=settings`). Proveedor y módulo: System › Settings › AI provider (`/settings/ai`). **En el portal:** el botón flotante de chat y la página `/chat` (modo **Ask AI**). ## Qué hace {#what-it-does} AI Chat responde a las preguntas de los clientes a cualquier hora, consulta los datos de *su propia* cuenta (saldo, servicios, pagos, errores recientes) y puede realizar acciones en su nombre (crear una VM, cambiar de plan) tras la confirmación del cliente. Cuando el asistente no puede ayudar, el cliente hace clic en **Talk to a human**: el chat se transfiere a su equipo en Telegram y, si nadie responde a tiempo, se convierte en un ticket. La misma configuración de IA también permite al sistema **investigar tickets** para su personal. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Módulo y proveedor | El módulo **AI** activado y un [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/) guardado y en uso. Sin un proveedor, el asistente indicará que no está configurado. | | Clientes | **Solo clientes autenticados.** En una instalación de NexCMP no hay sitio público, por lo que un visitante no autenticado verá "Sign in to use AI Chat". | | Canal para el personal (opcional) | Un bot y un chat de Telegram para alertas de administración (consulte [notificaciones de Telegram](https://nexcmp.com/es/docs/administration/telegram-notifications/)). El mismo canal recibe las derivaciones del chat y los borradores de tickets. | | Dependencias | [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/). | ## Preparar la infraestructura {#prepare-the-infrastructure} No se requiere nada más aparte del proveedor de IA. Si desea la derivación al personal: 1. Cree un bot de Telegram con @BotFather y anote el token. 2. Cree un grupo o use su chat privado con el bot y anote el chat ID. 3. Introduzca ambos en System › Settings › Admin alerts (consulte [Telegram notifications](https://nexcmp.com/es/docs/administration/telegram-notifications/)). Las funciones de soporte reutilizan ese bot y chat. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Asegúrese de que el módulo de IA esté activo y que la prueba del proveedor dé resultado verde ([AI provider](https://nexcmp.com/es/docs/ai/ai-providers/)). 2. Abra **Customers › Support › Ticket** y seleccione la pestaña **AI settings**. La parte superior de la tarjeta izquierda muestra tres etiquetas: *AI provider: configured*, *Telegram: channel present* y *On shift* u *Off shift*. 3. Tarjeta izquierda **AI + Telegram**: | Interruptor o campo | Predeterminado | Significado | |---|---|---| | La IA investiga tickets automáticamente | On | Ante un ticket o mensaje nuevo, la IA lee los datos del cliente (solo lectura) y redacta la causa probable y un borrador de respuesta como **nota interna**. Nunca envía nada al cliente. | | Alertas de Telegram al administrador | On | La nota llega a Telegram con los botones Send, Edit y Skip. | | AI auto-reply | Desactivado | Envía respuestas sencillas de guía práctica o ventas por sí misma cuando se cumplen todas las condiciones de seguridad (confianza del 85 % o superior, sin advertencias); se envía tras 3 minutos y se puede cancelar en Telegram. | | Categorías autorizadas para respuesta automática | `how_to`, `sales` | Solo estas. | | Modelo principal, modelo alternativo | definido desde el proveedor | Normalmente déjelo tal como se guardó en la página del proveedor de IA. | | ID de usuario de Telegram autorizado para actuar | vacío | Vacío significa el chat del canal de alertas. | 4. Tarjeta derecha **Live chat (customer widget)**: | Campo | Predeterminado | Significado | |---|---|---| | Enable chat widget | On | La burbuja de chat y la página `/chat`. | | Horario de soporte (hora de Vietnam) | `08:00-22:00` | Horario en que se espera que el personal responda en Telegram. Fuera de estas horas, o cuando no existe canal de Telegram, **Talk to a human** convierte el chat en un ticket de inmediato. | | Espera máxima del personal (minutos), luego convertir a ticket | 10 | 1 a 240. | | Turnos de IA / día / cliente | 40 | 1 a 1000. Tras alcanzar el límite, el asistente invita al cliente a hablar con un humano. | | Nuevos chats / hora / IP | 20 | 1 a 1000. | | **Zalo OA link** | vacío | `https://zalo.me/...` Muestra el botón **Chat on Zalo** (con un código QR) en el chat. Vacío lo oculta. | | **Telegram link** | vacío | `https://t.me/...` Muestra un botón **Telegram**. Vacío lo oculta. | | Límite diario global de turnos de IA, clientes con sesión iniciada | 2000 | | | Límite diario global, invitados | 500 | Fondo propio; no se usa mientras los invitados no puedan chatear. | | Límite diario global de investigaciones automáticas de tickets | 200 | | | Ruta de administración (el botón de Telegram "Open admin") | vacío | Su URL de administración, por ejemplo `https://cloud.example.com/admin`. | Cada interruptor o campo se guarda al modificarlo. 5. En la parte inferior, **Reply templates** (título, idioma VI/EN/ZH, texto de hasta 4,000 caracteres) ofrece al personal respuestas predefinidas. ![Pestaña AI settings con los interruptores de IA y Telegram y los límites y enlaces de acceso rápido del chat en vivo](https://nexcmp.com/es/docs/images/ai/ai-chat-01-settings.webp) ![Página de chat del cliente con el asistente, los botones de acceso rápido a Zalo y Telegram y la opción de hablar con una persona](https://nexcmp.com/es/docs/images/ai/ai-chat-02-portal.webp) ## Qué puede y qué no puede hacer el asistente {#what-the-assistant-can-and-cannot-do} - **Lectura:** busca en su base de conocimiento y en su documentación pública, y lee los datos propios del cliente que ha iniciado sesión mediante herramientas de solo lectura. No puede ver a ningún otro cliente. - **Acción:** utiliza los permisos de API propios del cliente. Las operaciones de *lectura* se ejecutan de inmediato. Cualquier acción que modifique datos o suponga un coste genera una **tarjeta de confirmación** ("Needs your confirmation", con las etiquetas *Costs money* o *Delete*); no ocurre nada hasta que el cliente hace clic en **Confirm**. Un chat puede contener como máximo 3 tarjetas pendientes y una cuenta un máximo de 10 acciones de escritura confirmadas por hora. - **Nunca:** no puede abrir consolas, crear tokens SSH o de consola, descargar archivos de acceso a Kubernetes, restablecer contraseñas ni mostrar secretos como contraseñas de proxy o secretos de S3. Los secretos nunca se incorporan al contexto del modelo ni al historial del chat. - **Seguridad:** sus respuestas pasan por un filtro de salida; el texto del cliente y los resultados de las herramientas se procesan como datos, no como instrucciones. - **Aviso de transparencia:** el chat muestra "Answered by an AI assistant — it may be imperfect. Talk to a human for anything critical." ## Derivación al equipo de soporte {#staff-hand-off} 1. El cliente hace clic en **Talk to a human** y puede indicar una dirección de correo electrónico. 2. Un mensaje con la conversación llega al chat de Telegram del personal. El equipo responde contestando a ese mensaje; la respuesta aparece en el chat del cliente como "[marca] Support". 3. Si nadie responde dentro del tiempo de espera (10 minutos por defecto), el chat se convierte en un ticket en **Customers › Support › Ticket**. Ocurre lo mismo de inmediato fuera del horario de soporte o cuando Telegram no está configurado, y se le notifica al cliente que se ha abierto un ticket. 4. Los administradores también pueden ver los chats en curso en la pestaña **Live chat**. ## Verificación {#verify} 1. Inicie sesión como cliente de prueba, abra el chat y haga una pregunta sobre sus servicios. El asistente responderá. 2. Pídale que cree un elemento que suponga un coste: aparecerá una tarjeta de confirmación y no se creará nada hasta que haga clic en **Confirm**. 3. Haga clic en **Talk to a human**. El mensaje llegará a su chat de Telegram (si está configurado) o, tras el tiempo de espera, se creará un ticket. 4. Al configurar los enlaces de Zalo y Telegram, ambos botones de acceso rápido aparecerán en el chat. ## Límites y notas {#limits-notes} - **Límites de frecuencia (por IP):** 20 mensajes por minuto y unas pocas derivaciones por hora; **40 mensajes por conversación**. Estos límites son fijos. - **Coste:** cada intervención de la IA realiza una llamada a su proveedor. Reduzca **AI turns / day / customer** para limitar el gasto. - **La respuesta automática está desactivada por defecto.** Actívela solo después de haber supervisado los borradores durante un tiempo. - **Idiomas:** el asistente responde en el idioma del cliente; el vietnamita se detecta a partir del texto. - **Revendedores:** los sitios de revendedor utilizan tickets en lugar del widget. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Los clientes no ven el chat | Módulo de IA desactivado, o **Enable chat widget** desactivado | Active ambos. | | "Sign in to use AI Chat" | El visitante no ha iniciado sesión | Comportamiento previsto en NexCMP: inicie sesión primero. | | El asistente indica que no hay ningún proveedor de IA configurado | Falta el proveedor, no está en uso o falta la clave | Configure [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/). | | La IA responde "talk to a human" tras unas pocas preguntas | Se ha alcanzado el límite diario por cliente | Aumente **AI turns / day / customer**. | | La etiqueta de Telegram muestra "no channel" | Bot o chat ID no configurados | Configure las [notificaciones de Telegram](https://nexcmp.com/es/docs/administration/telegram-notifications/). | | Falta el botón de Zalo o Telegram | El campo del enlace está vacío | Complete el enlace. | | "Too many requests" en el chat | Más de 20 mensajes por minuto desde una misma IP | Espere un minuto. | | Conversación del chat llena | Se alcanzó el límite de 40 mensajes | Inicie una nueva conversación. | --- # AI Agent {#ai-agent} > **Dónde está en el admin:** System › Settings › AI provider (`/settings/ai`) — interruptor del módulo y proveedor; System › Admin › License & updates (`/license`) — interruptor del módulo. **Dónde está en el portal:** AI Agent (`/ai/agent`) y la página `/chat/agent`, o el modo **Agent** dentro del chat. ## Qué hace {#what-it-does} El AI Agent se conecta a la VM Linux del cliente mediante SSH y realiza tareas descritas en lenguaje natural: "check system health", "install Docker", "find recent errors", "free up disk space". Muestra cada comando propuesto y su salida. Los comandos de solo lectura pueden ejecutarse automáticamente; cualquier cambio en el servidor espera a que el cliente pulse **Run**. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Módulo y proveedor de AI | El módulo **AI** activado y un [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/) funcional. El Agent también necesita un modelo compatible con tool calling. | | `openssh-client` en el servidor del panel | El Agent ejecuta comandos con el propio programa `ssh` del panel (`/usr/bin/ssh`). El instalador instala `openssh-client`; verifíquelo con `ssh -V`. Sin él, el Agent informa "ssh client is not installed on the panel server". | | Sin gateway SSH independiente | En la instalación predeterminada se utiliza el SSH integrado y **no** se necesita el terminal web `ssh-proxy`. Solo cuando se ha habilitado la función opcional de *web SSH* (`feature_ssh_web`) y se ha instalado el servicio `ssh-proxy`, el Agent pasa a través de `ssh-proxy`. | | Red | El servidor del panel debe poder comunicarse con la IP de la VM en su puerto SSH (22 de forma predeterminada). Compruebe los firewalls y grupos de seguridad entre el panel y la red de invitados. | | VM | Propiedad del cliente, **en ejecución**, no bloqueada, **Linux** (se rechazan las VM Windows), con una dirección IP pública o accesible. | | Credenciales SSH | El usuario y la contraseña de inicio de sesión de la VM almacenados por NexCMP (guardados de forma cifrada cuando se creó la VM o se restableció su contraseña), o la clave de operaciones del panel si hay una instalada. Si ninguno de los dos existe, el Agent indica que no puede iniciar sesión. | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Verifique el cliente SSH en el servidor del panel: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. Compruebe que el servidor del panel pueda conectarse por SSH a una VM invitada: ```bash nc -vz 198.51.100.10 22 ``` Sustituya la dirección por la IP de una VM de prueba. Si esto falla, corrija primero el enrutamiento o el firewall. 3. Asegúrese de que el sistema invitado permita el inicio de sesión por contraseña para el usuario almacenado por NexCMP (algunas imágenes cloud lo deshabilitan) o de que la clave de operaciones del panel esté instalada en el invitado. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Complete [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/): módulo activado, proveedor guardado y **Test connection** en verde. 2. No es necesario configurar nada más en el panel de administración. El interruptor del módulo hace que aparezcan las entradas de **AI Agent** en el portal del cliente. 3. Como cliente: abra **AI Agent**, elija un servidor en ejecución y haga clic en **Choose server**. La página comprueba primero la conexión SSH con un comando fijo inofensivo (sin utilizar llamadas de AI) y muestra *SSH connected* o el motivo por el cual falló. 4. Escriba una tarea o elija un inicio rápido (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*). ## Cómo ejecuta los comandos {#how-it-runs-commands} - **Desde dónde:** el servidor del panel, con el cliente `ssh` del sistema, un comando no interactivo a la vez. El destino siempre es la IP de la VM **desde la base de datos**, nunca desde la solicitud; solo se puede acceder a la VM desbloqueada y en ejecución del propio propietario. - **Autenticación:** la contraseña almacenada se pasa a través de un asistente `SSH_ASKPASS` de un solo uso en el entorno del proceso; no se escribe en el disco ni se coloca en la línea de comandos. Las claves de host no están fijadas (las VM se reinstalan con nuevas claves). La salida por comando está limitada a 200 KB y cada comando tiene un límite de tiempo (60 segundos). - **Bucle del Agent:** la IA propone comandos y lee las salidas; un turno finaliza después de un máximo de **10 pasos**. - **Modos:** | Modo | Comportamiento | |---|---| | **Confirm** | Cada comando espera a **Run**. | | **Auto** | Solo los comandos que superan una estricta lista de permitidos de solo lectura se ejecutan automáticamente (por ejemplo, `df -h`, `ps`, `journalctl`). Cualquier otra cosa, y todo lo que el analizador no pueda analizar con certeza (variables, sustitución de comandos, redirecciones a archivos), espera a **Run**. | - **Etiquetas de riesgo:** los comandos que sobrescriben o eliminan archivos, escriben en discos, modifican cuentas o SSH keys, envían datos a un servidor externo, abren conexiones de red sin procesar, ejecutan código ofuscado, descargan y ejecutan un script, apagan o reinician la máquina, o se comunican con otros servidores siempre muestran **Needs confirmation**, incluso en modo Auto. - **Salida no confiable:** la salida del comando se muestra al modelo como datos no confiables; las instrucciones en su interior no se siguen. ## Verificación {#verify} 1. Elija una VM de prueba en ejecución. La página muestra *SSH connected*. 2. Pregunte "Check CPU, RAM and disk". En modo Auto, los comandos de solo lectura se ejecutan y la respuesta los resume. 3. Pregunte "Install Nginx". El comando de instalación aparece con **Run** y **Skip**; no se ejecuta nada hasta que presione **Run**. 4. El contador en la parte superior muestra el número de llamadas de IA utilizadas hoy (por ejemplo, `3/300`). ## Límites y notas {#limits-notes} - **Límite diario:** 300 llamadas de IA por cliente al día (UTC); se restablece a las 00:00 UTC. Cuando se agota, el Agent responde "Daily AI quota reached". - **Concurrencia:** como máximo 2 ejecuciones del Agent por cliente al mismo tiempo; una sesión ejecuta un turno a la vez. - **Sesiones:** hasta 100 mensajes por sesión, 4,000 caracteres por mensaje. Una sesión pertenece a una VM; si la VM se elimina o se transfiere, la sesión anterior pasa a ser de solo lectura. - **VM bloqueada o detenida, o Windows:** la VM se muestra como *Locked*, *Stopped*, *Windows* o *No address* y no se puede seleccionar. - **Suplantación:** un administrador que suplanta a un cliente no puede usar las funciones de credenciales del Agent (consulte [Log in as a customer](https://nexcmp.com/es/docs/customers/login-as/)). - **Responsabilidad:** el Agent puede cometer errores. El portal indica a los clientes que revisen los comandos antes de ejecutarlos. Indique a los clientes en sus términos que son responsables de los comandos que aprueben. - Desactivar el módulo de IA elimina las entradas del Agent y las rutas responden 404 `module_disabled`. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "el cliente ssh no está instalado en el servidor del panel (apt install openssh-client)" | Falta el binario `ssh` | `sudo apt-get install -y openssh-client`. | | "El agente no pudo iniciar sesión" / `ssh: no saved credentials for this VM` | Sin contraseña almacenada ni clave de operaciones | Restablezca la contraseña de la VM en el portal para que se guarde de nuevo, o instale la clave de operaciones. | | "El servidor no respondió a tiempo" | Firewall, SSH no escucha, VM ocupada | Pruebe `nc -vz 22` desde el servidor del panel; inicie `sshd` en la VM. | | "No se pudo conectar a SSH en este servidor" | Enrutamiento o grupo de seguridad | Permita que el servidor del panel alcance la VM en el puerto 22. | | "La VM no está en ejecución" / "Prohibido" | VM detenida, bloqueada, eliminada o no pertenece al cliente | Iníciela, desbloquéela o elija otra. | | "No disponible: N (detenida, bloqueada o Windows)" | Motivos indicados arriba | La VM debe ser Linux y estar en ejecución. | | "La pasarela SSH no está disponible temporalmente" | Función Web SSH habilitada pero `ssh-proxy` está caído | Inicie `ssh-proxy` o desactive la función Web SSH para usar el SSH integrado. | | "La IA está respondiendo con demasiada lentitud (más de 90 segundos)" | Proveedor lento | Use un modelo más rápido o un **Reasoning effort** menor. | | "Cuota diaria de IA alcanzada" | 300 llamadas utilizadas | Espere hasta las 00:00 UTC. | | "Esta sesión aún está en ejecución" | Otro turno en curso | Espere o pulse **Stop**. | --- # REST API > **Ubicación en el portal:** Referencia de la API en `https:///apidoc` (pública) y claves de API en `/api-keys`. **Ubicación en admin:** Customers › API keys (`/customers/apikeys`) lista las claves creadas por clientes. ## Qué hace {#what-it-does} Cada acción que un cliente puede realizar en el portal —listar y controlar VMs, consultar facturas, gestionar SSH Keys, Kubernetes, almacenamiento y tickets de soporte— está disponible a través de una REST API versionada en `https:///v1/`. Los clientes la invocan desde scripts y CI mediante una **API key** con ámbito definido. La misma API alimenta la [`cmp` herramienta de línea de comandos](https://nexcmp.com/es/docs/developers/cmp-cli/) y el [servidor MCP](https://nexcmp.com/es/docs/developers/mcp/), y la referencia se genera a partir de la instalación en ejecución, por lo que siempre enumera exactamente las funciones que tiene activadas. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Dirección HTTPS pública | La API se sirve en su dominio principal (y en el dominio propio de cada distribuidor). | | Una clave de API | Creada por el cliente en el portal; consulte [API keys](https://nexcmp.com/es/docs/developers/api-keys/). | | Dependencias | Ninguno. Los endpoints de un módulo no habilitado (por ejemplo Kubernetes u Object Storage) se ocultan de la referencia y se rechazan. | ## Preparar la infraestructura {#prepare-the-infrastructure} No hay nada que instalar. Si un proxy inverso está delante de NexCMP, reenvíe `/v1/`, `/mcp`, `/cli/` y `/apidoc` al panel (la configuración de nginx del instalador ya lo hace). ## Conectar en NexCMP {#connect-in-nexcmp} ### La referencia interactiva {#the-interactive-reference} Abra `https://cloud.example.com/apidoc` (sustituya el host por su dominio; los clientes de un distribuidor ven la referencia en el dominio del distribuidor, con su nombre). Incluye documentación de endpoints con ejemplos de solicitud y respuesta en curl, la CLI de `cmp`, JavaScript, Python y Go, un cuadro de búsqueda (Ctrl o Cmd + K) y un panel **Try it**. Try it envía solicitudes únicamente al mismo sitio, con una clave que el visitante pega (guardada en la sesión del navegador); es de solo lectura por defecto, y las llamadas de escritura o de pago requieren un interruptor adicional y confirmación. ### Descargas y documentos legibles por máquina {#downloads-and-machine-readable-documents} Todos son públicos, no requieren clave y se generan por sitio: | URL | Contenido | |---|---| | `/apidoc` | Referencia interactiva. | | `/v1/public/openapi.json` | Documento OpenAPI 3.1. | | `/v1/public/openapi.yaml` | El mismo, en YAML. | | `/v1/public/postman.json` | Colección de Postman. | | `/v1/public/insomnia.json` | Exportación para Insomnia. | | `/v1/public/api.md` | La referencia en un único archivo Markdown. | | `/v1/public/api-catalog` | JSON ligero: marca, URL base, prefijo de clave, cada scope y cada endpoint con método, ruta, scope y si necesita un `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 ``` En Postman elija **Import › Link** y pegue `https://cloud.example.com/v1/public/postman.json`. La página de referencia también ofrece clientes API de un solo archivo para JavaScript y Python. ### Autenticación {#authentication} Envíe la clave en el encabezado `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Las claves de cliente comienzan con `vk_`. Las claves están **vinculadas al sitio**: una clave creada en `cloud.example.com` no funciona en el dominio de un revendedor. - Los tokens de sesión del navegador (`pt_...`) son solo para el portal; use una clave para la automatización. - Los **scopes** de la clave deciden a qué puede llamar; si falta un scope responde HTTP 403 `scope_required`. Consulte [API keys](https://nexcmp.com/es/docs/developers/api-keys/). - Compruebe una clave con `GET /v1/apikeys/self`: devuelve el nombre de la clave que realiza la llamada, los scopes, la expiración y el límite de tasa restante permitido (cualquier clave puede llamarlo). ### Ejemplos {#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 ``` Tome los campos de solicitud exactos de cada operación desde `/apidoc`. ### Errores {#errors} Cada error es un JSON con un `code` estable y un `message` legible para humanos: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | `code` típicos | Significado | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Clave ausente o desconocida, revocada, expirada, IP de origen fuera de la lista de permitidas de la clave, clave de otro sitio o API keys desactivadas. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | La clave carece del scope; el endpoint no está disponible para claves; la cuenta está bloqueada; se alcanzó una [cuota](https://nexcmp.com/es/docs/billing/quotas/); acción no permitida en una sesión personificada. | | 404 | `not_found` | No encontrado — también se devuelve para recursos que pertenecen a otra persona. | | 422 | `invalid_argument` | Error de validación (campo nombrado en la respuesta). | | 429 | `rate_limited` | Demasiadas solicitudes; espere hasta `Retry-After`. | | 503 | `maintenance` | El modo de mantenimiento está activo: las lecturas funcionan, las escrituras se rechazan. | ### Límites de tasa {#rate-limits} | Límite | Predeterminado | |---|---| | Por clave | 120 solicitudes por minuto | | Por cuenta (todas las claves juntas) | 300 solicitudes por minuto | Cada respuesta incluye `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`; un error 429 añade `Retry-After`. ### Idempotencia {#idempotency} Los comandos que conllevan costo o no pueden repetirse (crear, cambiar de plan, comprar, eliminar...) **requieren** un encabezado `Idempotency-Key` (cualquier cadena de hasta 200 caracteres; un UUID funciona bien). Envíe la misma clave de nuevo tras un timeout y el servidor devolverá el resultado **original** (con `Idempotency-Replayed: 1`) en lugar de repetir la operación. Reutilizar una clave para un comando distinto devuelve 422; una solicitud aún en curso devuelve 409/`Retry-After`. Sin el encabezado se rechaza cualquier llamada de pago. ## Verificación {#verify} 1. Cree una clave con el scope `vm:read` en el portal (**API keys › Create key**). 2. Ejecute: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Obtendrá HTTP 200 y los encabezados de límite de tasa. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` lista las VM de la cuenta. En el portal, la columna **Last used** de la clave y el **Key usage log** muestran las llamadas. ## Límites y notas {#limits-notes} - **Nunca disponible para una clave:** recargas, retiros, cambiar tarjetas o recargas automáticas, cambiar contraseña, correo electrónico o 2FA, eliminar la cuenta, crear, editar o revocar otras claves. Estas acciones requieren una sesión iniciada en el navegador. - **Módulos ocultos:** la referencia y el documento OpenAPI solo enumeran las funcionalidades habilitadas en ese sitio. - **Tamaño de respuesta y paginación:** los endpoints de listado están paginados (`page`, `per_page`); consulte el documento OpenAPI de cada endpoint. - **Tiempo y dinero:** los montos están en centavos de USD a menos que el nombre del campo indique lo contrario. - **API de administración:** la consola de administración dispone de su propia página **System › Admin › API** y claves de administrador (`ofw_...`) para la gestión; son independientes de la API de clientes aquí descrita. - **Versionado:** el prefijo de ruta `/v1` es estable; es posible que se añadan nuevos campos a las respuestas. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | 401 en una clave nueva | Clave de otro dominio, vencida o escrita con espacios | Cree la clave en el dominio al que llama; verifique el encabezado `Authorization: Bearer vk_...`. | | 403 `scope_required` | Scope faltante | Edite la clave en el portal y agregue el scope. | | 401 `key_ip_denied` o `site_mismatch` | Clave restringida a otras IP ("allowed IPs") o creada en otro dominio | Agregue la IP de su servidor a las IP permitidas de la clave o llame al dominio donde se creó. | | 404 en una VM existente | La VM pertenece a otra cuenta | Use una clave del propietario. | | 400/422 solicitando `Idempotency-Key` | Operación de pago sin el encabezado | Agregue `Idempotency-Key: `. | | 429 | Límite superado | Reduzca la frecuencia; use `Retry-After`. | | `/apidoc` muestra menos de lo esperado | Módulo desactivado | Active el módulo en License & updates. | --- # Claves de API y scopes {#api-keys-and-scopes} > **Ubicación en el portal:** API keys (`/api-keys`). **Ubicación en admin:** Customers › Customers › API keys (`/customers/apikeys`). ## Qué hace {#what-it-does} Una **API key** permite que un script, un trabajo de CI, la [`cmp` CLI](https://nexcmp.com/es/docs/developers/cmp-cli/) o un asistente de inteligencia artificial ([MCP](https://nexcmp.com/es/docs/developers/mcp/)) llamen a la [REST API](https://nexcmp.com/es/docs/developers/api/) en nombre de un cliente, con solo los permisos (**scopes**) que se le otorgaron. Las claves de cliente comienzan con `vk_`. Pueden leer y administrar servicios, pero **nunca** pueden tocar el dinero ni la cuenta en sí. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cliente | Una sesión iniciada en el portal (una clave no puede crear ni editar otras claves, y un administrador que suplante a un cliente tampoco puede hacerlo). | | Interruptor | Las claves de API están activadas de forma predeterminada. Si se desactivan, las llamadas responden 401 `api_keys_disabled`. | | Dependencias | Los scopes de un producto solo aparecen cuando dicho producto está habilitado en el sitio. | ## Crear una clave (cliente) {#create-a-key-customer} 1. Inicie sesión en el portal y abra **API keys**. 2. Haga clic en **Create key**. 3. Complete el formulario: | Campo | Regla | |---|---| | **Nombre de la clave** | Obligatorio, hasta 60 caracteres ("deploy server", "backup script"). | | **Qué puede hacer esta clave** | Marque los scopes que necesite — al menos uno. Una clave de solo lectura no debe tener scopes de escritura. Tenga cuidado con los scopes que conllevan costos o eliminan datos. | | **Expiry** | Nunca, 30 días, 90 días o 1 año (la API acepta de 1 a 3650 días). | | **Permitir solo llamadas desde estas IP** | Una IP o rango CIDR por línea, hasta 20 (IPv4 o IPv6). En blanco significa cualquier IP. Fije la IP de su servidor siempre que sea posible. | 4. Confirme el formulario. La clave se muestra **una sola vez** en una ventana "Key created — shown ONCE". Cópiela y haga clic en **I saved the key**. Solo se almacena un hash SHA-256, por lo que ni siquiera un administrador puede volver a verla; si la pierde, revóquela y cree una nueva. 5. El portal también muestra un comando `curl` listo para probar la clave. Una clave tiene el aspecto de `vk_` seguido de una cadena aleatoria larga. La lista solo muestra los primeros caracteres (por ejemplo, `vk_a1b2c3d4`), los scopes, el vencimiento, el último uso, el recuento de solicitudes y el estado (*Active*, *Expired*, *Revoked*). ### Editar, revocar, auditar {#edit-revoke-audit} - **Edit** modifica el nombre, los scopes, las IP permitidas y la expiración. No está permitido durante una sesión de suplantación. - **Revoke** desactiva la clave de inmediato y no se puede deshacer. La fila se conserva para que su registro de uso permanezca disponible. - **Key usage log** muestra los comandos de escritura y cada error de los últimos 60 días: hora, solicitud, clave, resultado e IP de origen. - Una cuenta puede tener como máximo **10 claves activas** de forma predeterminada. - Las claves creadas a través del inicio de sesión de CLI o MCP aparecen en **Connected apps & devices** y pueden revocarse allí. ## Scopes {#scopes} Los nombres de los scopes tienen el formato `area:action`. Cuáles se ofrecen depende de los productos que tenga habilitados. | Scope | Permite | |---|---| | `catalog:read` | Leer planes y el catálogo. | | `vm:read` | Leer VM, métricas y facturas de VM. | | `vm:write` | Acciones de energía, cambios menores, firewall, Snapshots rápidos. | | `vm:create` | **Crear VM (tiene coste).** | | `vm:plan` | **Cambiar de plan o redimensionar (tiene coste).** | | `vm:destroy` | **Eliminar VM.** | | `vm:restore` | **Restaurar una VM desde un Snapshot (sobrescribe el disco).** | | `vm:console` | Abrir tickets de consola VNC. | | `sshkey:read`, `sshkey:write` | Leer, añadir y eliminar SSH Keys. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volúmenes de datos (crear y ampliar tiene coste; destruir ocasiona pérdida de datos). | | `backup:read`, `backup:write`, `backup:restore` | Backups (la restauración sobrescribe el disco). | | `billing:read` | Wallet, facturas, historial de pagos — **solo lectura**. | | `bandwidth:buy` | **Comprar un complemento de ancho de banda (tiene coste).** | | `account:read`, `account:write` | Perfil, resumen, actividad, notificaciones; `account:write` solo marca las notificaciones como leídas. | | `apikey:read` | Listar las claves de la cuenta y el registro de uso (no permite crear, editar ni revocar). | | `apikey:self` | Implícito en cada clave: inspeccionar la clave que realiza la llamada (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | Tickets de soporte. | | `aff:read`, `transfer:read` | Programa de afiliados y transferencias de servicios — solo lectura. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (crear y escalar tiene coste; kubeconfig es cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. | | `image:read`, `image:write` | Imágenes de SO e ISO (el almacenamiento se factura por horas). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (el secreto S3 se muestra una sola vez). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN y proxy IPv6 (los detalles de conexión incluyen contraseñas de proxy). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Servidores dedicados (crear realiza pedidos desde la wallet; destruir reinstala el SO). | | `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, solo cuando ese módulo está habilitado. | Una llamada fuera de los scopes de la clave responde **403 `scope_required`**; una ruta a la que ninguna clave puede llamar responde **403 `endpoint_not_public`**. ### Lo que una clave nunca puede hacer {#what-a-key-can-never-do} Ningún scope permite: recargar o retirar fondos, cambiar tarjetas o la recarga automática, cambiar la contraseña, el correo electrónico o 2FA, eliminar la cuenta, ni crear, editar o revocar otras claves. Estas acciones siempre requieren una sesión iniciada en el navegador. Incluso si una clave se filtra, no puede acceder a los fondos ni a la cuenta del cliente. ## Reglas en las que puede confiar {#rules-you-can-rely-on} | Regla | Detalle | |---|---| | Vinculada al sitio | Una clave funciona únicamente en el sitio (dominio) donde se creó. | | Límites de tasa | Por clave y por cuenta: 120 y 300 solicitudes por minuto de forma predeterminada. | | Idempotencia | Las operaciones que tienen coste o no se pueden repetir requieren un encabezado `Idempotency-Key`. | | Cuotas | Una clave está sujeta a las mismas [cuotas](https://nexcmp.com/es/docs/billing/quotas/) que el cliente. | | Cuenta bloqueada | Las claves de un cliente bloqueado dejan de funcionar (403 `account_blocked`). | | Auditoría | La revocación por parte de un administrador se registra en el log de auditoría de administración. | ## Vista de administrador {#administrator-view} 1. Abra **Customers › API keys** (`/customers/apikeys`). La tabla muestra el nombre de la clave y sus primeros caracteres, propietario, scopes, estado, último uso (hora, número de solicitudes, IP) y vencimiento. 2. Filtre por sitio si tiene revendedores. Busque por nombre, ID o inicio de clave. 3. Haga clic en **Revoke** para anular una clave activa, o en **Log** para ver su uso. 4. Los administradores **ven y revocan** claves, pero no pueden leerlas ni crearlas para los clientes. ![Lista de administrador de claves de API de clientes con scopes, estado, último uso y el botón Revoke](https://nexcmp.com/es/docs/images/developers/api-keys-02-admin.webp) ## Verificación {#verify} 1. Cree una clave solo con el scope `vm:read`. 2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` devuelve la lista de VM. 3. `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` responde 403 `scope_required`. 4. Revoque la clave; la primera llamada ahora responde 401 `key_revoked`. ## Límites y notas {#limits-notes} - La clave no se volverá a mostrar. Trátela como una contraseña y guárdela en un gestor de secretos o en un secreto de CI. - Priorice una clave por script, scopes mínimos, una expiración corta y una lista de IP permitidas; rótela creando una clave nueva y revocando la anterior. - Las claves de inicio de sesión de dispositivo (CLI, MCP) vencen por defecto a los 90 días. - Los recursos eliminados o transferidos no se ven afectados al revocar una clave. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Error `too_many_keys` (422) | Se alcanzó el límite de claves activas (10 por defecto) | Revoque una clave antigua. | | Error `invalid_argument`: no se seleccionó ningún scope | Ningún scope marcado | Marque al menos un scope. | | Error `invalid_argument` en IP permitidas | Una entrada no es una IP o rango, longitud de prefijo incorrecta o más de 20 entradas | Una IP o CIDR por línea, por ejemplo `203.0.113.0/24`. | | Se rechaza la creación durante la suplantación | `impersonate_forbidden` | Solicite al cliente que cree la clave. | | 401 `key_expired` | Fecha de vencimiento superada | Cree una nueva clave. | | 401 `key_ip_denied` | La IP de origen no está en la lista de permitidas | Añada la IP o borre la lista. | | 401 `api_keys_disabled` | Función desactivada | Consulte a su administrador (ajuste `api_keys_enabled`). | --- # Herramienta de línea de comandos `cmp` {#cmp-command-line-tool} > **Ubicación en el portal:** los comandos de instalación están en la referencia de la API (`https:///apidoc`, sección Command-line interface). Aprobación de inicio de sesión: `https:///link`. Dispositivos conectados: API keys (`/api-keys`) › Connected apps & devices. ## Qué hace {#what-it-does} `cmp` es un pequeño programa de línea de comandos para sus clientes (y para usted) que convierte **cada operación de la API en un comando**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Se compila a partir del documento OpenAPI de **su** propia instalación en el momento del lanzamiento, por lo que los comandos coinciden con las funciones que tenga habilitadas. Es un único binario estático para Linux, macOS y Windows (amd64 y arm64) sin nada más que instalar. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Servidor | Nada adicional. Los paquetes de distribución están dentro de la versión de NexCMP y el panel los sirve en `https:///cli/`. | | Máquina del cliente | Linux, macOS o Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) solo es necesario para verificar la firma. | | Credenciales | Un inicio de sesión en el navegador con un código de un solo uso o una [API key](https://nexcmp.com/es/docs/developers/api-keys/). | | Red | HTTPS hacia su panel. La CLI rechaza enviar una clave a través de `http://` sin cifrar, excepto a `localhost`. | ## Preparar la infraestructura {#prepare-the-infrastructure} Nada. El panel sirve estos archivos desde `/cli/` (no se requiere compilación ni subida): | Archivo | Propósito | |---|---| | `install.sh`, `install.ps1` | Instaladores para Linux/macOS y Windows; contienen la dirección de su panel. | | `latest.json` | Versión actual, lista de archivos, tamaños, sha256. | | `v/cmp___.tar.gz` o `.zip` | Los programas: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Sumas de verificación y su firma ed25519. | | `cmp-cli.pub` | La clave pública de la versión. | ## Instalación (cliente) {#install-customer} macOS y Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` El instalador selecciona el paquete para el SO y la CPU, descarga `SHA256SUMS` y su firma, verifica la firma con la clave incrustada en el script, comprueba el hash del paquete e instala `cmp` en `/usr/local/bin` (como root) o en `~/.local/bin`; en Windows en `%LOCALAPPDATA%\cmp\bin` (añadido al `PATH` del usuario). Si alguna comprobación falla, no se instala nada. | Variable | Significado | |---|---| | `CMP_VERSION` | Instalar esta versión en lugar de la más reciente. | | `CMP_INSTALL_DIR` | Carpeta de instalación. | | `CMP_REQUIRE_SIGNATURE` | `1` = abortar cuando no se pueda verificar la firma. | | `CMP_BASE_URL` | Base de descarga (para mirrors). | Descarga y verificación manual: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Sección de referencia de la API con el comando cmp install para macOS y Linux](https://nexcmp.com/es/docs/images/developers/cmp-cli-01-install.webp) ## Iniciar sesión {#log-in} ```bash cmp login ``` 1. La CLI muestra un **código** de un solo uso y un enlace (`https://cloud.example.com/link?code=WDJB-MJHT`), abre el navegador y espera. 2. En el navegador, inicie sesión en el portal, compruebe el nombre del cliente, el dispositivo, la IP y el país, marque los permisos (scopes) y elija la duración de la clave (por defecto 90 días). Los permisos que conllevan costes o eliminan datos aparecen desmarcados inicialmente. Haga clic en approve. 3. La CLI recibe **su propia clave**, independiente de las claves creadas manualmente por el cliente, y la guarda en `~/.config/cmp/config.json` (modo `0600`; `%APPDATA%\cmp` en Windows). Aparece en **API keys › Connected apps & devices** y se puede revocar allí. El código caduca a los 10 minutos. La aprobación requiere una sesión real iniciada en el portal con un correo electrónico verificado; no otra clave ni una sesión suplantada. Flags útiles: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Para CI o servidores sin navegador, use una clave del 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] ``` - Los parámetros de ruta son argumentos posicionales; los parámetros de consulta y los campos del cuerpo se convierten en flags en kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` o `--data -` envía un cuerpo JSON completo; los flags anulan sus campos. - `cmp help vm firewall add` (o `--help`) muestra los detalles de cualquier 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 integrados: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Todo lo demás proviene del documento de la API. Flags globales: | Flag | Significado | |---|---| | `-o, --output json\|table\|yaml` | Formato. Por defecto `table` en una terminal y `json` cuando se canaliza. | | `--profile`, `--api-url` | Qué inicio de sesión guardado y qué sitio. | | `-y, --yes` | Omitir la confirmación para comandos destructivos o de pago. | | `--idempotency-key ` | Elegir la clave de un comando de pago. | | `--retry ` | En caso de HTTP 429, esperar `Retry-After` y reintentar hasta n veces. | | `--timeout ` | Segundos de espera para los encabezados de respuesta (por defecto 60). | | `--debug` | Mostrar el intercambio HTTP en stderr, con las claves enmascaradas. | Los comandos que **cargan el monedero o eliminan datos** solicitan confirmación y, si son de pago, envían un `Idempotency-Key` generado automáticamente (impreso en stderr, para que pueda reintentar de forma segura con `--idempotency-key`). Sin un terminal se rechazan a menos que se indique `--yes`. ### Códigos de salida {#exit-codes} | Código | Significado | |---|---| | 0 | Éxito | | 1 | Otro error (red, HTTP 4xx/5xx no listados) | | 2 | Error de uso | | 3 | No autorizado (401/403) | | 4 | No encontrado (404) | | 5 | Límite de solicitudes superado (429) | | 6 | Confirmación requerida o rechazada | | 130 | Interrumpido | ### Perfiles y entorno {#profiles-and-environment} `cmp config` lista los perfiles; `cmp config use ` cambia de perfil; los clientes de un revendedor utilizan su propio dominio: `cmp login --api-url https://shop.example.net --profile shop`. Prioridad: flag, entorno, archivo de configuración. Variables: `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' ``` Autocompletado de shell: `cmp completion bash|zsh|fish|powershell`. ## Actualización y desinstalación {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` descarga `latest.json`, `SHA256SUMS` y la firma, verifica la firma con la clave pública **integrada en el binario en ejecución**, comprueba el hash del paquete y solo entonces se reemplaza a sí mismo. Una degradación requiere `--force`. Al actualizar NexCMP, el panel sirve la versión de la CLI incluida con la nueva versión. Para desinstalar, elimine el binario `cmp` y el directorio de configuración (`cmp config path` lo muestra). Revoque la clave en **API keys** si la máquina se pierde. ## Verificación {#verify} 1. `cmp version` imprime la versión y la versión del documento de la API. 2. `cmp login`, apruebe en el navegador y luego `cmp whoami` muestra el perfil y la URL de su panel. 3. `cmp vm list` devuelve sus VM; `cmp vm list -o json | jq .` muestra el JSON sin procesar. ## Límites y notas {#limits-notes} - La lista de comandos depende de su compilación: los paquetes se generan a partir del documento OpenAPI de su instalación al compilar la versión, por lo que un producto desactivado en su versión no tendrá ningún comando. Utilice `cmp api` para una ruta que la CLI no conozca. - La CLI está bajo la licencia MIT. - Cada paquete está firmado con una clave ed25519; la clave de firma está anclada dentro del instalador y del binario, no se descarga durante la actualización. - Las claves están limitadas por clave y por cuenta (consulte [REST API](https://nexcmp.com/es/docs/developers/api/#rate-limits)). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `curl .../cli/install.sh` devuelve 404 | La versión en el servidor no tiene carpeta CLI o el host no está en la licencia | Compruebe `https:///cli/latest.json` y el dominio; actualice NexCMP. | | "no se pudo verificar la firma" | `ssh-keygen` falta o es demasiado antiguo | Instale OpenSSH 8.0+ o configure `CMP_REQUIRE_SIGNATURE=0` solo si acepta el riesgo. | | `cmp login` indica que el código ha caducado | Han pasado 10 minutos | Ejecute `cmp login` de nuevo. | | Código de salida 3 | La clave carece de un ámbito, ha caducado o está revocada | `cmp whoami`; cree o vuelva a aprobar con más ámbitos. | | Código de salida 6 en un script | Comando de pago o destructivo sin un terminal | Añada `--yes` (y su propio `--idempotency-key`). | | "se niega a enviar una clave por http" | URL de la API en http sin cifrar | Utilice `https://`, o `CMP_ALLOW_HTTP=1` solo para un laboratorio. | | El navegador abre el sitio incorrecto | `--api-url` no está configurado para un revendedor | `cmp login --api-url https://`. | --- # Servidor MCP {#mcp-server} > **Dónde encontrarlo en el portal:** API reference › Tools (`https:///apidoc`) muestra el endpoint y los fragmentos para clientes; las claves se crean en API keys (`/api-keys`). No hay ajustes en el panel de administración: el endpoint forma parte del panel. ## Qué hace {#what-it-does} El **Model Context Protocol (MCP)** permite a un asistente de IA llamar herramientas. NexCMP ofrece un endpoint MCP en `https:///mcp`. Cada operación pública de la API se convierte en una **herramienta** (`vm_list`, `vm_start`, `billing_wallet`...), de modo que un cliente puede preguntar a su asistente «¿cuáles de mis VM están en ejecución?» o «detén la VM de staging». El asistente actúa únicamente con la clave de API y los permisos del cliente. ::: tip ¿Configurar el propio NexCMP con IA? Esta página describe el endpoint MCP para **clientes** (`/mcp`). Para permitir que un asistente de IA configure su propio panel como administrador, consulte [Configurar con IA](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, claves de administrador `ak_`). ::: ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Servidor | No requiere instalación: el endpoint es proporcionado por el panel y es accesible dondequiera que esté el panel. Su proxy inverso debe reenviar `/mcp` al panel. | | Cliente | Una [clave de API](https://nexcmp.com/es/docs/developers/api-keys/) (`vk_...`) con los scopes que necesite el asistente. | | Cliente | Un cliente MCP compatible con el transporte **Streamable HTTP** y una cabecera personalizada `Authorization`: Claude Code, Claude Desktop (mediante el puente `mcp-remote`), Cursor, VS Code con modo agente de Copilot y similares. | | Versiones del protocolo | 2025-11-25, 2025-06-18 y 2025-03-26. | ## Preparar la infraestructura {#prepare-the-infrastructure} Nada, más allá de asegurarse de que `https:///mcp` no esté bloqueado por un firewall o una regla de proxy. Los clientes MCP basados en navegador desde otro origen se rechazan a menos que ese origen esté permitido; los clientes de línea de comandos y de escritorio no envían cabecera `Origin` y funcionan tal cual. ## Conexión (lado del cliente) {#connect-customer-side} 1. Cree una clave de API en el portal (**API keys › Create key**) únicamente con los scopes que desee que use el asistente, una expiración corta y, si es posible, una restricción por IP. 2. Añada el servidor a su cliente. Reemplace `cloud.example.com` y la clave. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` o `.cursor/mcp.json`; defina `CLOUD_API_KEY` en el entorno desde el que se inicia Cursor): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (requiere Node.js 18+; `claude_desktop_config.json`), mediante el puente `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" } } } } ``` Escriba la cabecera sin espacios después de los dos puntos e introduzca el valor completo en la variable de entorno, como se muestra arriba. 3. Reinicie el cliente y pídale que liste sus herramientas. Compruebe la conexión sin un 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"}' ``` ## Cómo funciona {#how-it-works} | Elemento | Detalle | |---|---| | Endpoint | `POST /mcp` con un mensaje JSON-RPC 2.0; la respuesta es `application/json`. `GET /mcp` responde 405 (sin flujo de servidor a cliente); `DELETE /mcp` finaliza la sesión. | | Autenticación | Solo `Authorization: Bearer vk_...` (los tokens de sesión, cookies y claves de administrador se rechazan con 401 y una cabecera `WWW-Authenticate: Bearer`). | | Sesión | `Mcp-Session-Id` es emitido por `initialize`, vinculado a esa clave, válido por 24 horas; máximo 16 sesiones por clave. | | Herramientas | Una por cada operación pública de la API visible para la clave. El nombre de la herramienta es el comando de la CLI con `_` en lugar de espacios y guiones (`vm firewall add` se convierte en `vm_firewall_add`) y coincide con el `operationId` de OpenAPI. Una herramienta solo se muestra si la clave tiene su scope y el módulo está habilitado. | | Capacidades | Solo herramientas (sin resources ni prompts). | | Tamaño | Cuerpo de la solicitud de hasta 1 MB; texto de resultado de la herramienta de hasta aprox. 100 KB (el resto se trunca con una nota); una llamada tarda como máximo 55 segundos. | ### Reglas de seguridad {#safety-rules} - **La misma puerta de enlace que REST.** Cada `tools/call` pasa por la propia canalización de solicitudes del panel: se aplican el alcance, el sitio, la restricción de IP, el límite de frecuencia, la idempotencia, las comprobaciones de propiedad (404 para recursos ajenos) y las cuotas. MCP no puede conceder nada que la clave no posea. - **Confirmación.** Las herramientas con coste económico, de eliminación o que devuelven credenciales (tickets de consola, kubeconfig, secretos de S3 o SSH, restablecimientos de contraseña, nuevas claves) requieren el argumento `confirm: true`. La descripción de la herramienta indica al asistente que solo lo transmita una vez que el usuario lo haya aprobado, de modo que una instrucción oculta en una página web o registro no pueda activarla por sí sola. - **Idempotencia.** Las herramientas de pago aceptan `idempotency_key`; si se omite, se deriva una clave estable a partir del nombre de la herramienta y sus argumentos, de modo que un reintento idéntico no pueda cobrar dos veces. - **No expuestos como herramientas:** endpoints de streaming (el chat de AI Agent), tickets WebSocket de SSH o consola de un solo uso, descargas de binarios y los endpoints de la aplicación VPN (`/v1/ext/*`). - **Nunca posible:** la API nunca permite recargas, cambios de contraseña, eliminar la cuenta o crear claves, por lo que ningún asistente puede realizarlos. ### Límites {#limits} | Límite | Predeterminado | |---|---| | Llamadas a herramientas por clave | 60 por minuto | | Solicitudes MCP por clave | 240 por minuto | | Más los límites habituales de clave y cuenta | Consulte [REST API](https://nexcmp.com/es/docs/developers/api/#rate-limits) | Si se supera el límite, el endpoint responde HTTP 429 con un error JSON-RPC y `Retry-After`. ## Verificación {#verify} 1. El comando `curl` anterior devuelve un resultado JSON-RPC con una lista `tools`. Solo aparecen las herramientas que coinciden con los alcances de la clave. 2. En su cliente pida "list my VMs": el asistente llama a `vm_list` y muestra el resultado. 3. En el portal, la hora de **Last used** de la clave se actualiza y las llamadas de escritura aparecen en **Key usage log**. ## Límites y notas {#limits-notes} - **Inicio de sesión en el navegador (OAuth).** La página de referencia también describe el inicio de sesión a través del navegador para clientes compatibles con MCP OAuth. En una instalación de NexCMP, el método compatible y probado es la clave API (o `cmp login` para la CLI). - **Los sitios de revendedores** no muestran la sección MCP; sus clientes utilizan el dominio del revendedor para la API. - **Mínimo privilegio.** Cree una clave dedicada por asistente, primero con alcances de lectura; añada alcances de escritura solo cuando sea necesario. - Revoque la clave en **API keys** para cortar el acceso del asistente de inmediato. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | 401 con `WWW-Authenticate: Bearer` | Sin clave, clave incorrecta o un token de sesión | Envíe `Authorization: Bearer vk_...`. | | 403 sobre `Origin` | Una página del navegador en otro origen | Utilice un cliente de escritorio o CLI, o solicite a su administrador que permita el origen (`mcp_allowed_origins`). | | 404 en una solicitud con `Mcp-Session-Id` | La sesión pertenece a otra clave o ha caducado | Ejecute `initialize` de nuevo. | | 405 en `GET /mcp` | Esperado: el servidor no tiene flujo de eventos | Utilice solo POST (los clientes lo hacen automáticamente). | | La lista de herramientas es corta | Alcances de la clave o módulos | Añada alcances a la clave; habilite el módulo. | | La herramienta responde que necesita `confirm: true` | Herramienta de pago, de eliminación o confidencial | El asistente debe definir `confirm` después de que usted lo apruebe. | | 429 | Límite de frecuencia de MCP o de la clave | Espere a `Retry-After`. | | El cliente no puede conectarse con un encabezado | Cliente sin compatibilidad con encabezados personalizados | Utilice el puente `mcp-remote`. | --- # Configurar con IA {#configure-with-ai} > **Ubicación en el admin:** AI Chat (`/agent`) y System › Settings › API & AI agents (`/agent/keys`). Todo el contenido de estas páginas es solo para administradores. ## Qué hace {#what-it-does} A partir de NexCMP 1.4.0, puede pedirle a un asistente de IA que configure el panel por usted: conectar Proxmox VE o CloudStack, crear una zona, generar una tabla de planes a partir de sus costos, configurar el correo electrónico, los pagos y la marca, buscar un cliente o exportar la configuración completa. El asistente opera mediante un conjunto fijo de **herramientas de administración**. Nunca obtiene acceso a una shell, nunca lee archivos en el servidor y jamás ve contraseñas ni claves de API almacenadas. Utilícelo cuando desee realizar una configuración inicial en minutos en lugar de navegar por decenas de páginas, o cuando gestione varias instalaciones y prefiera mantener su configuración en un archivo. ## Tres formas de utilizarlo {#three-ways-to-use-it} | Método | Quién interactúa con la IA | Dónde se ejecuta | Comenzar aquí | |---|---|---|---| | **AI Chat en el admin** | Usted, en el admin de NexCMP | El proveedor de IA que elija: una clave de API de OpenAI, Anthropic, Gemini u OpenRouter, el propio proveedor de IA de su panel o una CLI de IA oficial en la que haya iniciado sesión | [AI Chat en el admin](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/) | | **Su propio cliente de IA mediante MCP** | Usted, en Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai o ChatGPT | En su equipo o en la aplicación del proveedor, conectado a su panel en `https://cloud.example.com/mcp/admin` | [Conectar un cliente de IA](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/) | | **Configuración como código** | Usted o un script | Un archivo YAML y el comando `nexcmp config` en el servidor (o la página Import/Export) | [Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/) | Las tres opciones invocan las mismas herramientas y pasan por la misma capa de seguridad, por lo que puede combinarlas: redactar una configuración con un asistente, exportarla como YAML, revisarla en su editor y aplicarla más adelante. ## Modelo de seguridad {#safety-model} | Regla | Qué significa para usted | |---|---| | **Scopes** | Una clave o conexión se limita a los scopes que seleccione (`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`). Sin el scope correspondiente, la llamada se rechaza. Consulte [Admin API keys](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | Cada clave y conexión caduca: entre 1 y 90 días para las claves que cree, 30 días por defecto. Los tokens de acceso OAuth duran una hora. | | **Restricción de IP y límite de peticiones** | Una clave se puede limitar a rangos de IP y a un número de llamadas por minuto (120 por defecto). | | **Confirmación en dos pasos** | Las acciones que mueven dinero, eliminan datos, modifican credenciales de pago o alteran la seguridad de inicio de sesión devuelven primero una vista previa y no hacen nada hasta que usted las apruebe. Dentro de AI Chat, cada cambio es una tarjeta de confirmación que usted mismo debe pulsar. | | **Acciones que las claves nunca pueden realizar** | Crear administradores, modificar 2FA, crear o revocar claves, iniciar sesión como cliente, realizar copias de seguridad, restaurar o actualizar el panel, entre otras. Para estas acciones se requiere su presencia en el panel de administración. | | **Registro de actividad** | Cada llamada, ya sea permitida o denegada, se registra con la clave, el cliente, la herramienta, la IP y el resultado. Consulte System › Settings › API & AI agents › Activity. | | **Los secretos nunca se devuelven** | Las contraseñas, claves API y tokens se pueden configurar, pero nunca volver a leer. Las respuestas que ve la IA los muestran enmascarados. | | **Las instalaciones de demo son de solo lectura** | En un panel de demo, cada escritura se rechaza con `demo_read_only`. | ::: important Qué puede leer la IA Con `admin:read`, un asistente puede leer nombres de clientes, direcciones de correo electrónico, saldos y registros de facturación. Cuando utiliza una fuente de IA que se ejecuta en un proveedor (OpenAI, Anthropic, Google, OpenRouter), esos datos se envían a dicho proveedor para responder a su pregunta. Asigne a un asistente el conjunto mínimo de scopes que necesite y elija una fuente en la que confíe para manejar esos datos. ::: ## Inicio rápido {#quick-start} 1. Inicie sesión en el panel de administración y abra **AI Chat**. Si aún no hay ninguna fuente de IA conectada, abra **System › Settings › AI accounts** y conecte una (consulte [Cuentas de IA y suscripciones](https://nexcmp.com/es/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. Escriba "Check my setup progress" y presione Enter. El asistente leerá [Setup progress checklist](https://nexcmp.com/es/docs/configure-with-ai/setup-checklist/) y le indicará lo que falta. 3. Pídale que realice el siguiente paso. Revise cada tarjeta de confirmación y presione **Confirm** para aplicarlo. Para una primera aproximación sobre qué preguntar, consulte [Ejemplos de prompts](https://nexcmp.com/es/docs/configure-with-ai/example-prompts/). ![Página de AI Chat con una conversación, un resultado de herramienta y una tarjeta de confirmación](https://nexcmp.com/es/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## Límites y notas {#limits-notes} - **Demo y solo lectura.** Las páginas son visibles en un panel de demo, pero allí no se puede guardar nada. - **Sin shell.** El asistente solo puede llamar a las herramientas de administración indicadas en [Conectar un cliente de IA](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/#tools). No puede ejecutar comandos en el servidor. - **Los módulos de red y enrutamiento** (BGP, XDP, interfaces, NAT y similares) son de solo lectura para la IA, y las áreas confidenciales como las cuentas de administrador, las copias de seguridad y las actualizaciones están totalmente cerradas para las claves. - **Los precios** están en USD: los precios de los planes en dólares por hora y los saldos en centavos. - **Costo.** Las respuestas de IA se pagan a la fuente de IA que conecte (uso de API o su propia suscripción). En AI Chat puede definir un límite de gasto diario. Para el modelo de licencia de NexCMP, consulte https://nexcmp.com/pricing. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | AI Chat indica que no hay ninguna fuente de IA conectada | No hay ninguna fuente configurada para su cuenta de administrador | Abra System › Settings › AI accounts y conecte una. | | Un asistente responde `insufficient_scope` | La clave o conexión carece del scope necesario para esa herramienta | Cree una clave con el scope necesario o vuelva a conectarse y márquelo en la pantalla de consentimiento. Consulte [Claves API de administración](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#errors). | | Cada cambio muestra una tarjeta de confirmación | Comportamiento esperado en AI Chat | Presione **Confirm** para aplicar o **Reject** para cancelar. | | Las operaciones de escritura fallan con `demo_read_only` | El panel está en modo demo | Utilice una instalación que no sea de demo. | --- # AI Chat en el admin {#ai-chat-in-the-admin} > **Ubicación en el admin:** AI Chat (`/agent`, su propia opción de menú) y el botón flotante **Ask AI** en cada página del admin. Las fuentes de respuestas se configuran en System › Settings › AI accounts (`/agent/accounts`). ## Qué hace {#what-it-does} AI Chat es un asistente integrado en el panel de administración. Usted describe lo que desea ("connect my Proxmox cluster", "set up email"), el asistente lee el estado actual mediante las herramientas de administración, propone cambios y muestra cada uno como una **tarjeta de confirmación**. No se aplica nada hasta que presione **Confirm**. El panel **Ask AI** es el mismo chat en un panel lateral estrecho, lo que le permite consultar mientras visualiza una página. Botones como **Do it for me** (en [Setup progress checklist](https://nexcmp.com/es/docs/configure-with-ai/setup-checklist/) y en listas vacías) lo abren con una pregunta lista. No es el [AI Chat](https://nexcmp.com/es/docs/ai/ai-chat/) ni el [AI Agent](https://nexcmp.com/es/docs/ai/ai-agent/) orientados al cliente, que atienden a sus clientes. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador con sesión iniciada. Los chats, claves y preferencias pertenecen a su cuenta de administrador; otros administradores no los ven. | | Una fuente de respuestas | Al menos uno conectado: una clave de API, un inicio de sesión, el propio proveedor de IA del panel o una CLI de IA en la que haya iniciado sesión. Consulte [Cuentas y suscripciones de IA](https://nexcmp.com/es/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | Demo | En un panel de demo puede leer chats antiguos, pero no enviar mensajes. | ## Elegir el origen de las respuestas {#choose-where-answers-come-from} Elija la fuente en el selector debajo del campo de entrada (muestra las fuentes que ha conectado). **System › Settings › AI accounts** también le permite configurar una fuente predeterminada, un modelo predeterminado y el límite diario. | Source | Cómo conectarlo | Notas | |---|---|---| | OpenAI (modelos de ChatGPT) | Pegue una clave de API de platform.openai.com | Facturado por OpenAI según el uso. | | Anthropic (Claude) | Pegue una clave de API de console.anthropic.com | Facturado por Anthropic según el uso. | | Google Gemini | Pegue una clave de API de aistudio.google.com o **Sign in with Google** | Iniciar sesión con Google requiere un cliente OAuth que **usted** cree en su propio proyecto de Google Cloud. | | OpenRouter | Pegue una clave o **Sign in with OpenRouter** | Una sola cuenta para múltiples modelos. | | Proveedor de IA del panel | Ya configurado en System › Settings › AI provider | El mismo proveedor que utiliza el AI Chat de sus clientes. [Proveedor de IA](https://nexcmp.com/es/docs/ai/ai-providers/). | | Suscripción a Claude, ChatGPT o Gemini | CLI oficial instalada y con sesión iniciada en el servidor del panel | Consulte [Cuentas y suscripciones de IA](https://nexcmp.com/es/docs/configure-with-ai/ai-accounts-and-subscriptions/). | Las claves que pegue se almacenan cifradas solo para su cuenta de administrador. Nunca se vuelven a mostrar y ningún otro administrador puede descifrarlas. ## Usar el chat {#use-the-chat} 1. Abra **AI Chat** (o haga clic en **Ask AI**). 2. Haga clic en **New chat** o abra uno anterior de la lista de la izquierda. 3. Escriba su solicitud y presione Enter (Shift+Enter inicia una nueva línea). Puede adjuntar imágenes o archivos de texto (hasta 4 por mensaje, 3 MB cada uno) para mostrar un error o pegar un documento. 4. Observe cómo se transmite la respuesta. Cada herramienta que invoca el asistente aparece como una tarjeta plegable con el nombre de la herramienta, sus argumentos y un resultado breve. 5. Presione **Stop** para cancelar una respuesta en curso. Solo se ejecuta una respuesta a la vez por administrador. ![AI Chat con la lista de conversaciones, una respuesta con tarjetas de herramientas y la entrada con selector de fuentes y campo Secret](https://nexcmp.com/es/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) Se realizan hasta 10 rondas de herramientas por mensaje. El asistente recuerda los últimos 30 mensajes del chat. Los resultados de las herramientas se pasan al modelo marcados como datos, no como instrucciones. ## Tarjetas de confirmación {#confirmation-cards} En AI Chat **cada cambio es una tarjeta**, no solo las acciones monetarias. El asistente propone; usted decide. Una tarjeta muestra: - Un título que indica por qué requiere atención, por ejemplo "changes a customer balance". - La llamada: método y ruta. - Una tabla con los campos que cambian: el valor actual y el nuevo. Los valores secretos se muestran como `••••`. - Una cuenta regresiva (las tarjetas caducan tras 5 minutos). - **Confirm** y **Reject**. **Confirm** hace que el propio panel aplique el cambio y luego le indica al asistente qué ocurrió. El asistente no puede presionar el botón, no puede aprobar cambios a través de la API y tiene instrucciones de nunca afirmar que un cambio fue aplicado antes de haber sido confirmado. Si recarga la página, las tarjetas que sigan siendo válidas volverán a aparecer. También se muestran en la parte superior de **System › Settings › API & AI agents** bajo "Waiting for your confirmation". ![Tarjeta de confirmación que muestra el cambio de saldo, la cuenta regresiva y los botones Confirm y Reject](https://nexcmp.com/es/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Secretos {#secrets} Las contraseñas y las claves API no deben enviarse en el texto del chat. Utilice el campo **Secret** (icono de candado) junto al campo de entrada: 1. Haga clic en el icono de candado e introduzca un **nombre** (letras, dígitos y guion bajo, por ejemplo `smtp_password`) y el **valor**. 2. En su mensaje, haga referencia al nombre: "use the secret smtp_password as the SMTP password". 3. El asistente solo ve en todo momento un marcador de posición que representa el secreto, escrito de esta manera: ```text {{secret:smtp_password}} ``` El panel lo reemplaza por el valor real en el momento en que ejecuta la herramienta. El valor no se guarda en el historial del chat ni se envía a la fuente de IA. Si por error pega en el mensaje algo que parece una clave, el panel lo traslada al mismo almacén protegido y lo enmascara en el historial, pero considérelo una red de seguridad y no un método de trabajo. Los secretos solo permanecen en la memoria del panel para la conversación en la que se introdujeron y hasta una hora después de su último mensaje; reiniciar el panel también los borra. Vuelva a introducirlos si el asistente lo solicita. Configurar un secreto también requiere el permiso `secrets:write` para la sesión de chat (véase más abajo). ## Permisos del chat {#permissions-of-the-chat} Cada mensaje se ejecuta con una clave temporal que existe durante la duración de la respuesta (como máximo 15 minutos), funciona únicamente desde el servidor del panel y solo puede utilizarse a través de las tarjetas de confirmación. Sus alcances son los marcados en **System › Settings › AI accounts › Chat session permissions**. `admin:read` siempre está activo. Todos los alcances excepto `secrets:write` están activados por defecto; marque `secrets:write` si desea que el asistente pueda establecer contraseñas y claves (a través del campo Secret). En un panel de demostración, el chat es de solo lectura. ## Límite de gasto diario {#daily-spending-cap} AI Chat suma el costo estimado de las respuestas procedentes de fuentes de API. El límite predeterminado es de **5 USD por administrador al día**. Configure otro importe (0 significa sin límite) en **AI accounts › Defaults for AI Chat**. La página muestra "used today". Cuando se alcanza el límite, el chat rechaza nuevos mensajes (`daily_cap`) hasta el día siguiente o hasta que aumente el límite. Las fuentes que son suscripciones de AI CLI no se contabilizan, ya que se facturan mediante su suscripción. ## Verificación {#verify} 1. En **AI accounts**, haga clic en **Test** en la fuente. Responderá con el nombre del modelo y el tiempo en milisegundos. 2. En AI Chat, pregunte "Check my setup progress". La respuesta enumerará los pasos de la [lista de comprobación](https://nexcmp.com/es/docs/configure-with-ai/setup-checklist/) y aparecerá una tarjeta de herramienta `setup_checklist`. 3. Solicite un cambio pequeño, por ejemplo "Set the brand name to Example Cloud". Aparecerá una tarjeta de confirmación; presione **Confirm** y revise la página Branding. 4. **API & AI agents › Activity** enumera las llamadas con el canal `chat`. ## Límites y notas {#limits-notes} - El asistente no tiene acceso a shell y no puede leer archivos en el servidor. Solo llama a las [herramientas de administración](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/#tools). - Los cambios que las claves nunca pueden realizar ([lista](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)) tampoco pueden hacerse desde AI Chat. - Compruebe el trabajo del modelo. Una tarjeta de confirmación muestra exactamente lo que se enviará; léala, especialmente los precios y los importes. - Las respuestas por API las factura el proveedor de IA. El límite es una estimación; configure también un límite de gasto con el proveedor. - Una respuesta por CLI se detiene transcurridos 5 minutos. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Se ha alcanzado el límite de gasto diario en IA" (`daily_cap`) | Se alcanzó el límite diario | Auméntelo en AI accounts o espere a mañana. | | "Otra respuesta aún se está ejecutando - espere o presione Stop" (`busy`) | Una respuesta a la vez por administrador | Pulse **Stop** o espere. | | La fuente no aparece en el selector | No está conectada o (Claude CLI) la opción "I understand" está desactivada | Conéctela en AI accounts. | | "eso no parece una clave API" | La clave pegada contiene espacios o es demasiado larga | Pegue únicamente la clave. | | La prueba falla | Clave incorrecta, sin crédito o el proveedor no está disponible | Verifique la clave y la facturación en el proveedor. | | El asistente indica que no puede realizar una acción | La sesión de chat no tiene el alcance necesario o la acción está restringida para AI | Marque el alcance en AI accounts o realícelo en el panel de administración. | | Una tarjeta indica que ha caducado | Han pasado más de 5 minutos | Solicite al asistente que vuelva a proponer el cambio. | | La fuente CLI informa de "usage limit" o "not logged in" | Límite de su suscripción o de la sesión | Inicie sesión de nuevo o espere; consulte [Cuentas y suscripciones de AI](https://nexcmp.com/es/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # Cuentas y suscripciones de AI {#ai-accounts-and-subscriptions} > **Dónde encontrarlo en el panel:** System › Settings › AI accounts (`/agent/accounts`), pestañas **Accounts** y **Use your own AI subscription**. La terminal opcional es AI Console (`/agent/console`), que aparece bajo AI Chat solo cuando está activada. ## Qué hace {#what-it-does} AI Chat necesita una fuente para generar respuestas. Esta página le permite conectar dicha fuente para su propia cuenta de administrador: - **Fuentes API**: OpenAI, Anthropic (Claude), Google Gemini y OpenRouter, mediante una clave API o inicio de sesión. - **El proveedor de AI del panel**, si ya configuró uno en System › Settings › AI provider. - **Su propia suscripción de AI** (Claude, ChatGPT, Gemini) a través de la **herramienta oficial de línea de comandos** del proveedor, ya sea en el servidor del panel o en su propio equipo. Todo lo que conecte pertenece a su cuenta de administrador. Las claves y los tokens se almacenan cifrados exclusivamente para usted; ningún otro administrador puede utilizarlos. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Un administrador con la sesión iniciada. En un panel de demostración no se puede conectar ni eliminar nada. | | Fuentes API | Una cuenta y una clave API en el proveedor (la tarjeta incluye un enlace **Get API key** que abre la página del proveedor). | | CLI en el servidor del panel | AI Console activada (consulte más abajo), HTTPS saliente desde el servidor hacia el proveedor, hacia `nodejs.org` y hacia el registro de npm, y **2 GB de RAM o más** (una CLI necesita aproximadamente 1 GB libre mientras se ejecuta; el instalador muestra una advertencia si hay menos de 2 GB). Se utiliza Node.js 20 o posterior si está presente; de lo contrario, el instalador descarga Node.js 22 con verificación de checksum. | | CLI en su equipo | Node.js 20 o posterior para instalar la CLI y su propia suscripción. | ## Conectar una fuente API {#connect-an-api-source} 1. Abra **System › Settings › AI accounts** y permanezca en **Accounts**. 2. En la tarjeta de la fuente, haga clic en **Connect**. La página de claves del proveedor se abrirá en una pestaña nueva; cree una clave allí. 3. Pegue la clave en el campo y guarde. La tarjeta mostrará el estado conectado con los últimos cuatro caracteres. 4. Elija el **modelo predeterminado** si desea uno diferente y, a continuación, haga clic en **Test**. Un resultado correcto se mostrará como "Connected - example-model, 850 ms". ![Página de cuentas de IA con las tarjetas de fuentes de API, una tarjeta de OpenAI conectada y la tarjeta del proveedor Panel AI](https://nexcmp.com/es/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | Alternativa de inicio de sesión | |---|---| | OpenRouter | **Sign in with OpenRouter** abre OpenRouter en una ventana emergente o pestaña; al aprobarlo, regresará a esta página conectado. | | Google Gemini | **Sign in with Google** aparece después de guardar, en **Set up Google sign-in (optional)** dentro de la tarjeta, un cliente OAuth creado en **su propio** proyecto de Google Cloud (ID de cliente que termina en `.apps.googleusercontent.com`, junto con su secreto). NexCMP no incluye ningún cliente de Google compartido. | | Proveedor de IA del panel | Utiliza el proveedor ya configurado en System › Settings › AI provider ([AI provider](https://nexcmp.com/es/docs/ai/ai-providers/)). No es necesario pegar nada. | Para desconectar una fuente, haga clic en **Remove** en su tarjeta. Esto eliminará la clave almacenada para su cuenta. ### Valores predeterminados, límite diario y permisos {#defaults-daily-cap-and-permissions} En la parte inferior de la pestaña **Accounts**, **Defaults for AI Chat** incluye tres ajustes: | Ajuste | Significado | |---|---| | Fuente y modelo predeterminados | Lo que utilizan los chats nuevos. Aún puede cambiar la fuente en cada mensaje. | | Límite de gasto diario (USD, 0 = sin límite) | Valor predeterminado: 5. La página muestra "used today". Consulte [AI Chat in the admin](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | Permisos de la sesión de chat | Los ámbitos que puede utilizar el asistente. `admin:read` está siempre activo; `secrets:write` está desactivado de forma predeterminada. Consulte [Admin API keys](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#scopes). | Haga clic en **Save defaults**. ## Usar su propia suscripción de IA {#use-your-own-ai-subscription} Puede controlar NexCMP con un plan de Claude, ChatGPT o Gemini por el que ya paga, sin necesidad de una clave API independiente. Existen dos formas. ### Método 1 (recomendado): la CLI en su propio equipo {#way-1-recommended-the-cli-on-your-own-computer} Utilice la propia herramienta del proveedor en su propio equipo e inicie sesión con su propia cuenta de la forma habitual del proveedor. NexCMP solo recibe llamadas de MCP firmadas con una clave de corta duración. Abra **AI accounts › Use your own AI subscription**; muestra tres pasos por herramienta. 1. Haga clic en **Create a 7-day key** y elija el nivel: **Read only** (`admin:read`) o **Read + configuration** (`admin:read`, `catalog:write`, `infra:write`, `settings:write`). Los comandos que aparecen a continuación contendrán la clave real. 2. Instale la CLI e inicie sesión. La clave se muestra solo en esta página y una única vez. | Herramienta | Instalación | Iniciar sesión | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | ejecute `claude` y luego `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | ejecute `gemini` y elija "Login with Google" | 3. Conéctelo a su panel con un solo comando o bloque copiado desde la 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 la herramienta y pregunte, por ejemplo, "what is left to set up in nexcmp?". Todos los detalles sobre la conexión MCP se encuentran en [Connect an AI client](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/). La misma pestaña muestra la URL de los conectores de **claude.ai** y **ChatGPT**, que inician sesión con OAuth y no requieren ninguna clave: [OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/). ![Pestaña Use your own AI subscription con el botón de clave de 7 días y los comandos de instalación, inicio de sesión y conexión para tres CLI](https://nexcmp.com/es/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### Método 2: la CLI en el servidor del panel (botones Install / Login) {#way-2-the-cli-on-the-panel-server-install-login-buttons} Las tarjetas bajo "Subscription through a CLI (Claude, ChatGPT, Gemini)" permiten a NexCMP instalar la CLI oficial en el servidor del panel y abrir su propio flujo de inicio de sesión, para que **AI Chat** pueda responder con su suscripción. **Cómo está aislado.** Las CLI se ejecutan en un proceso independiente (`nexcmp-ai.service`) con su propio usuario del sistema `nexcmp-ai`, sin sudo, sin acceso a las carpetas de datos y configuración de NexCMP y con un límite de memoria. Para cada mensaje de AI Chat, la CLI se inicia únicamente con las herramientas MCP de NexCMP permitidas (las herramientas de shell y archivos están desactivadas) y una clave que solo funciona desde el servidor. NexCMP no lee ni copia el inicio de sesión de la CLI: la CLI lo conserva en una carpeta privada para su cuenta de administrador. No hay nada que activar: el panel configura el usuario y servicio `nexcmp-ai` al instalarse o actualizarse a 1.4.0, por lo que las tarjetas están listas para usarse. **Instalación e inicio de sesión (por administrador):** 1. En la tarjeta de la CLI, haga clic en **Login**. Si la CLI aún no está instalada, el panel la instala primero: una barra de progreso y un registro breve muestran la descarga (Node.js si es necesario y luego la CLI). Aparece una advertencia cuando el servidor tiene menos de 2 GB de RAM. 2. La tarjeta muestra lo que solicita la CLI: - **Codex CLI**: haga clic en **Open the sign-in page** e introduzca el código de un solo uso que muestra la tarjeta. (El inicio de sesión de dispositivos de OpenAI debe estar habilitado en los ajustes de seguridad de ChatGPT). - **Claude Code y Gemini CLI**: haga clic en **Open the sign-in page**, inicie sesión y luego pegue el código de verificación que muestra la página del proveedor en **Paste the verification code here** y haga clic en **Send code**. 3. La tarjeta cambia a "Signed in" con la cuenta y la versión. Si el inicio de sesión no se completa en 10 minutos, se cancela; haga clic en **Login** de nuevo. 4. En **AI Chat**, la fuente aparece ahora en el selector (por ejemplo, "ChatGPT (via Codex CLI)"). 5. **Sign out** elimina el inicio de sesión de la CLI para su cuenta. Para Claude, la tarjeta incluye un interruptor adicional, **I understand and accept the vendor's terms for using a subscription this way**, desactivado por defecto. La fuente no se ofrece en AI Chat hasta que esté activado. ![Tarjetas de suscripción de CLI con Install y Login, un código de un solo uso en la tarjeta de Codex y el interruptor I understand en la tarjeta de Claude](https://nexcmp.com/es/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### Términos de los proveedores de IA {#terms-of-the-ai-vendors} El inicio de sesión con una suscripción de consumidor se rige por los términos de cada proveedor, los cuales pueden cambiar. Las notas siguientes son un resumen de lo publicado por los proveedores a fecha de octubre de 2026, no constituyen asesoramiento legal ni una declaración en nombre del proveedor. Lea las páginas actuales antes de activar esta función. | Proveedor | Qué cubre la página del proveedor | Source | |---|---|---| | Anthropic (Claude) | Se contempla el inicio de sesión en Claude Code sin modificar con su propio plan. El uso de una suscripción a través de otros productos, o hacer que un producto recopile o transmita el inicio de sesión, recibe un tratamiento distinto, y los límites del plan asumen un uso individual habitual. Por ello, la tarjeta de Claude incluye una nota y el interruptor **I understand**, y por eso el Método 1 es la opción más limpia. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | Codex permite iniciar sesión con una cuenta de ChatGPT o una clave API. OpenAI recomienda el uso de claves API para la automatización e indica no exponer Codex en entornos públicos o no confiables. Utilice la tarjeta únicamente para usted. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | Admite Sign in with Google, una clave API y Vertex AI; las condiciones dependen del método de inicio de sesión y se aplican las cuotas de su plan. | https://geminicli.com/docs/get-started/authentication | Si desea evitar la pregunta por completo, use una fuente de **API key** o el Método 1 en su propio equipo. ## AI Console {#ai-console} AI Console es una página de terminal opcional para ejecutar una de las CLI con sesión iniciada en el servidor del panel. Está **desactivada de forma predeterminada**. - Actívela o desactívela, y gestione las CLI, en el 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` muestra si el socket de AI runner está listo, si AI Console está habilitada o deshabilitada y, para cada CLI, "installed" o "not installed". `sudo nexcmp status` también muestra "AI runner: active". - Una vez habilitada, aparece una pestaña **AI Console** en AI Chat. Elija una CLI con sesión iniciada, vuelva a introducir su contraseña de administrador (y su código 2FA si lo utiliza) y abra una sesión. Un banner le recordará que los comandos aquí solo pueden gestionar NexCMP mediante sus herramientas de MCP; las herramientas de shell y de archivos están deshabilitadas. - Las instalaciones de demostración nunca crean el usuario `nexcmp-ai`. ![Pantalla de inicio de AI Console con el selector de CLI, el campo de contraseña y el banner de advertencia solo para MCP](https://nexcmp.com/es/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## Verificación {#verify} 1. **Test** en una fuente de API devuelve el nombre del modelo. 2. En la tarjeta de la CLI, el estado muestra "Signed in" con la cuenta. 3. En el servidor: `sudo nexcmp ai-console status` muestra la CLI como instalada y `systemctl is-active nexcmp-ai` imprime `active`. 4. En AI Chat elija la fuente, pregunte "Check my setup progress" y aparecerá una tarjeta de herramienta. ## Límites y notas {#limits-notes} - Las respuestas de la CLI están limitadas a 5 minutos y a una respuesta a la vez por administrador. El límite diario no contabiliza las respuestas de la CLI. - Cada cambio procedente de una fuente de CLI sigue siendo una tarjeta de confirmación en AI Chat; la CLI no puede aplicar cambios por sí misma. - Los planes de suscripción tienen sus propios límites de uso. Cuando el proveedor indica "usage limit" o "not logged in", el chat muestra ese mensaje. - Eliminar una fuente no elimina las conversaciones. - Mantenga el servidor actualizado: las CLI se instalan desde los paquetes públicos de los proveedores en el momento en que hace clic en Install. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | Login está deshabilitado y la tarjeta dice "AI tools are not ready on the server yet" | El servicio `nexcmp-ai` no se está ejecutando | Actualice el panel a la versión más reciente y luego compruebe `sudo nexcmp status`. En la demo de solo lectura, esto es lo esperado. | | "Las herramientas de IA aún no están instaladas en este servidor" | El servicio `nexcmp-ai` no se está ejecutando (panel más antiguo o un panel de demo) | Actualice el panel y luego `sudo nexcmp ai-console install claude` (o `codex`, `gemini`). | | Advertencia sobre RAM inferior a 2 GB | El servidor es pequeño | La instalación puede ser lenta o fallar; añada memoria o use el Método 1. | | "Node.js download checksum mismatch" o "download failed" | El servidor no puede conectarse a nodejs.org, o un proxy alteró la descarga | Permita el tráfico HTTPS saliente y vuelva a intentarlo. | | La instalación finaliza con un error | npm no pudo instalar el paquete | Lea el registro en la tarjeta, compruebe el acceso saliente al registro de npm y vuelva a intentarlo. | | El inicio de sesión finaliza con un error o agota el tiempo de espera | El plazo de 10 minutos venció o el código era incorrecto | Haga clic en **Login** de nuevo y complételo más rápido. | | Falta la fuente de Claude en AI Chat | El interruptor **I understand** está desactivado o la CLI no tiene la sesión iniciada | Active el interruptor después de leer la página del proveedor y luego inicie sesión. | | Falta "Sign in with Google" en Gemini | Aún no se ha guardado ningún cliente OAuth de Google | Cree el cliente en su propio proyecto de Google Cloud y guárdelo en **Set up Google sign-in (optional)** en la tarjeta, o pegue una clave API en su lugar. | | "Sign in with OpenRouter" devuelve un error | Canceló la operación o la ventana emergente fue bloqueada | Permita las ventanas emergentes e inténtelo de nuevo. | | La respuesta de la CLI indica "usage limit" | Se ha agotado la cuota del plan | Espere o cambie de fuente. | --- # Claves API de admin {#admin-api-keys} > **Ubicación en el admin:** System › Settings › API & AI agents (`/agent/keys`), pestaña **API keys**. La misma página incluye las pestañas **Connect an AI**, **Connected apps** y **Activity**. ## Qué hace {#what-it-does} Una clave API de admin (prefijo `ak_`) permite que un cliente de IA o un script gestione su panel con los permisos exactos asignados. Funciona en la API de admin en `/v1/admin/` y en el endpoint MCP de admin `/mcp/admin`. No funciona en ningún otro lugar. ::: info No es lo mismo que las claves de cliente Los clientes crean claves que comienzan con `vk_` en el portal de cliente ([API keys and scopes](https://nexcmp.com/es/docs/developers/api-keys/)). Esas solo acceden a la API de cliente y a `/mcp`. Se rechaza una clave `ak_` en la API de cliente, y se rechaza una clave `vk_` en la API de admin. ::: ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Rol | Debe haber iniciado sesión en el admin. Las claves no pueden crear otras claves. | | Demo | En un panel de demostración, la página es de solo lectura: no se puede crear ni revocar ninguna clave. | | Accesibilidad | El cliente debe alcanzar `https://cloud.example.com/mcp/admin` o `/v1/admin/...` en su panel (compruebe su firewall si utiliza restricciones de IP). | ## Crear una clave {#create-a-key} 1. Abra **System › Settings › API & AI agents** y permanezca en la pestaña **API keys**. 2. Haga clic en **Create new key**. 3. Complete el formulario: | Campo | Reglas | |---|---| | Nombre | Hasta 60 caracteres, por ejemplo "Claude Code en mi portátil". | | Scopes | Marque al menos uno. Consulte [Scopes](#scopes). Empiece solo con `admin:read`. | | Expiración | 1, 7, 30, 60 o 90 días. Predeterminado: 30. Máximo: 90. No se puede crear una clave sin expiración. | | Rangos IP (opcional) | Una dirección IPv4 o IPv6 o CIDR por línea, por ejemplo `203.0.113.0/24` o `2001:db8::/48`. Máximo 32. Déjelo en blanco para permitir cualquier IP. | | Llamadas por minuto | 1 a 6000. Predeterminado: 120. | 4. Haga clic en **Create key**. Un cuadro muestra la clave una sola vez, por ejemplo `ak_XXXX`. **Cópiela ahora**: NexCMP almacena solo un hash y nunca podrá volver a mostrarla. 5. Haga clic en **I have saved the key**. Abra la pestaña **Connect an AI** para obtener comandos listos para pegar que ya contienen la clave recién creada (solo en esta página, hasta que la recargue). ![Diálogo de nueva clave con nombre, casillas de verificación de scope, expiración y rango IP completados](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Diálogo que muestra la nueva clave una sola vez con un botón Copiar y una advertencia](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Scopes {#scopes} Una clave solo puede utilizar las herramientas y endpoints que sus scopes permitan. Los scopes de escritura no incluyen acceso de lectura: una clave que deba leer y escribir también necesita `admin:read`. | Scope | Lo que permite | |---|---| | `admin:read` | Lectura de configuración, catálogo, clientes, facturación y registros. Los secretos nunca se devuelven. | | `catalog:write` | Planes, plantillas de SO, cuotas, códigos de descuento. | | `infra:write` | Fuentes de infraestructura (CloudStack, Proxmox), zonas, servidores. | | `billing:write` | Pasarelas de pago, divisa, facturas, saldos. Las acciones monetarias requieren confirmación. | | `customers:write` | Clientes y revendedores. | | `settings:write` | Configuración general, personalización de marca, correo electrónico, páginas legales, módulos y notificaciones. | | `ai:write` | El proveedor de IA y las funciones de IA. | | `secrets:write` | Escribir contraseñas y claves de API. Se pueden configurar, pero nunca volver a leer. | ::: tip Configurar un secreto requiere dos ámbitos Cualquier llamada que incluya una contraseña, clave de API o valor de token (una contraseña SMTP, una clave de pago, un token de bot de Telegram, una clave de proveedor de IA, credenciales de CloudStack o Proxmox) requiere `secrets:write` **y** el ámbito del área (por ejemplo, `settings:write` para SMTP). Si prefiere escribir los secretos manualmente, desactive `secrets:write` e introdúzcalos en el panel de administración. ::: ## Revocar una clave {#revoke-a-key} 1. Localice la clave en la tabla (estado **Active**, **Expired** o **Revoked**; **Last used** muestra la fecha/hora y el cliente). 2. Haga clic en **Revoke** y confirme. La clave dejará de funcionar de inmediato. La revocación es permanente; cree una nueva clave si vuelve a necesitarla. ## Lo que una clave nunca puede hacer {#what-a-key-can-never-do} Una clave nunca puede acceder a estas áreas, independientemente de sus ámbitos. Requieren haber iniciado sesión en el panel de administración. - Crear o modificar usuarios administradores, 2FA y seguridad de inicio de sesión, sesiones de administración y tokens de API de administración. - Crear, listar o revocar claves de administrador, conexiones OAuth y cuentas de IA, o utilizar la AI Console. - Hacer copias de seguridad o restaurar el panel, actualizarlo o cambiar su licencia. - Iniciar sesión como cliente o revendedor, abrir la consola de un cliente, consultar credenciales de VM o kubeconfig, configurar SSH Keys, o enviar o restablecer contraseñas. - Modificar módulos de red y enrutamiento (BGP, FRR, RTBH, XDP, interfaces, rutas estáticas y de políticas, NAT) o agentes externos e integración del portal. Son de solo lectura. - Modificar parámetros como `demo_*`, `admin_*`, listas de hosts, passkey, reautenticación y secretos de captcha. Todo lo que no esté cubierto por una regla está cerrado de forma predeterminada para escrituras, y se puede consultar con `admin:read` para lecturas. ### Acciones que requieren su confirmación {#actions-that-need-your-confirmation} Estas solo se ejecutan tras aprobar una vista previa (consulte [Confirmación en dos pasos](#two-step-confirmation)): - Modificar el saldo de un cliente o la billetera de un revendedor, realizar pagos, registros de facturación, el tipo de cambio. - Modificar precios (precios de planes, creación masiva de planes, precios de imágenes y almacenamiento) y crear códigos de descuento o de saldo. - Guardar las credenciales de la pasarela de pago o la conexión de CloudStack. - Eliminar cualquier elemento, bloquear o eliminar a un cliente, cambiar los límites de un cliente, suspender o cerrar a un revendedor. - Realizar acciones en los servidores de los clientes o crear un servidor de pago para un cliente. - Modificar conmutadores globales del sitio, ajustes de seguridad de inicio de sesión o ajustes de pago a través de la configuración general. ## Confirmación en dos pasos {#two-step-confirmation} Cuando una llamada requiere confirmación, aún no se modifica nada. La respuesta es HTTP **428** con `confirm_required`, un `confirm_token`, un `preview` (método, ruta, motivo, los nuevos valores y, si están disponibles, los valores actuales) y `expires_in: 300`. 1. El cliente le muestra la vista previa. 2. Tras su aprobación, repite la **misma** solicitud (mismo método, ruta y cuerpo) con el encabezado `X-Confirm-Token: `. Las herramientas de MCP toman el argumento `confirm_token` en su lugar. 3. El token funciona una sola vez y expira transcurridos 5 minutos. Las claves creadas en el panel de administración para AI Chat solo se pueden confirmar en pantalla: la respuesta indica `confirm_in: "ui"` y aparece una tarjeta de confirmación en el panel de administración. La IA no puede aprobarla. ## Límites de frecuencia y reglas de IP {#rate-limit-and-ip-rules} - Al superar el límite por minuto, una llamada devuelve `rate_limited` (HTTP 429) con `Retry-After: 60`. - Si se configuran rangos de IP, las llamadas desde cualquier otra dirección devuelven `ip_not_allowed` (HTTP 403). ## Registro de actividad {#activity-log} La pestaña **Activity** enumera cada llamada realizada con una clave, de la más reciente a la más antigua: hora, clave, cliente, cómo llegó (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), método y ruta, herramienta, estado HTTP, IP y los detalles (enmascarados). Puede buscar por ruta, herramienta o nombre de clave, mostrar solo errores (HTTP 400 y superior) o solo llamadas en espera de confirmación (428 y superior), y limitar el período a la última hora, 24 horas o 7 días. NexCMP conserva las 200,000 entradas más recientes. Los cambios realizados mediante una clave también aparecen en Logs › Admin actions con el nombre `ak:/`. ![Pestaña Activity que muestra las llamadas con estado, cliente, herramienta e IP](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verificación {#verify} Pruebe una clave de solo lectura desde cualquier máquina que esté dentro del rango de IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Obtendrá una lista JSON de las herramientas que permiten sus scopes. Ejecute una: ```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 '{}' ``` La hora en **Last used** de la clave se actualiza y la llamada aparece en **Activity**. La lista completa de herramientas y una descripción de OpenAPI (`/v1/admin/openapi.json`) se detallan en [Conectar un cliente de IA](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/). ## Errores {#errors} Los errores se devuelven en JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Significado | Solución | |---|---|---|---| | 401 | `invalid_key` | La clave falta, es inválida o es desconocida. También se devuelve cuando se utiliza una clave `ak_` en una ruta que no es de administración. | Compruebe la clave; utilícela solo en `/v1/admin/` y `/mcp/admin`. | | 401 | `key_expired` | La clave ha caducado. | Cree una nueva clave. | | 401 | `key_revoked` | La clave fue revocada. | Cree una nueva clave. | | 403 | `ip_not_allowed` | La IP de origen está fuera de los rangos de IP de la clave. | Llame desde una IP permitida o cree una clave con el rango correcto. | | 403 | `local_only_key` | Se utilizó desde otra máquina una clave creada para AI Chat o la CLI del servidor. | Estas claves solo funcionan en el propio servidor del panel. | | 403 | `insufficient_scope` | A la clave le falta un scope; la respuesta incluye `required_scope`. | Cree una clave con ese scope. | | 403 | `forbidden_for_keys` | El endpoint, o la configuración que intentó cambiar, no admite claves. | Hágalo en el admin. | | 403 | `demo_read_only` | El panel está en modo de demostración y la llamada es de escritura. | Utilice un panel que no sea de demostración. | | 403 | `confirm_in_ui` | Esta acción debe confirmarse en pantalla en el admin. | Apruebe la tarjeta de confirmación. | | 428 | `confirm_required` | Hay una vista previa lista; no se aplicó ningún cambio. Incluye `confirm_token`. | Muestre la vista previa y luego repita con `X-Confirm-Token`. | | 409 | `confirm_expired` | El token tiene más de 5 minutos de antigüedad. | Envíe la solicitud de nuevo para obtener una nueva vista previa. | | 409 | `confirm_mismatch` | El token pertenece a una solicitud diferente (el método, la ruta o el cuerpo difieren). | Repita exactamente la misma solicitud. | | 409 | `confirm_invalid` | Token desconocido o ya utilizado. | Envíe la solicitud de nuevo para obtener una nueva vista previa. | | 429 | `rate_limited` | Demasiadas llamadas en este minuto. | Espere a `Retry-After`. | | 400 | `invalid_path` | La ruta contiene secuencias prohibidas. | Utilice una ruta simple. | | 413 | `too_large` | El cuerpo supera los 10 MB. | Envíe menos datos. | | 400 | `invalid_argument` | Falta un argumento de la herramienta, es desconocido o tiene un tipo incorrecto; el mensaje lo especifica. | Corrija el argumento. | ## Límites y notas {#limits-notes} - Mantenga las claves con vigencia corta y permisos limitados. Se recomienda una clave por cliente para poder revocar solo una si es necesario. - Una clave es tan potente como sus scopes. `secrets:write` más `billing:write` es la combinación más delicada; las acciones relacionadas con dinero se detienen siempre en una vista previa. - Las claves creadas automáticamente (para AI Chat o la CLI del servidor) duran solo unos minutos y funcionan únicamente desde el servidor del panel. - Para desconectar de inmediato un cliente de IA, revoque su clave. Las conexiones OAuth se revocan en la pestaña **Connected apps** ([OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/)). --- # Conectar un cliente de IA (MCP) {#connect-an-ai-client-mcp} > **En el panel de administración:** System › Settings › API & AI agents (`/agent/keys`), la pestaña **Connect an AI** muestra la URL del endpoint y un fragmento listo para copiar para cada cliente, con la clave que acaba de crear. ## Qué hace {#what-it-does} El **Model Context Protocol (MCP)** permite que un cliente de IA invoque herramientas. Su panel ofrece un servidor MCP de administración en `https://cloud.example.com/mcp/admin`. Conecte su propia herramienta de IA a él y pregunte en lenguaje natural: "¿qué falta por configurar?", "añadir mi clúster de Proxmox", "crear planes con un 40% de margen". El cliente invoca las herramientas de administración indicadas a continuación; el panel comprueba los scopes, le solicita confirmación antes de cualquier acción de riesgo y registra cada llamada. ::: info Dos endpoints MCP `/mcp` es el endpoint de **clientes** (claves API de clientes, `vk_`; consulte [MCP server](https://nexcmp.com/es/docs/developers/mcp/)). `/mcp/admin` es el endpoint de **administración** descrito aquí (claves de administración `ak_` u OAuth). Ambos nunca se mezclan: las herramientas de administración no son visibles en `/mcp` y `/mcp/admin` solo acepta claves de administración. ::: ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Endpoint | `https://cloud.example.com/mcp/admin` en el propio dominio de su panel. Copie la URL exacta desde la pestaña **Connect an AI**. La misma página indica una URL local (`http://127.0.0.1:/mcp/admin`) para las herramientas que se ejecutan en el propio servidor. | | Credenciales | Una [clave API de administración](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) (`ak_...`) con los scopes deseados, **o** inicio de sesión mediante OAuth para conectores web ([OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/)). | | Cliente | Cualquier cliente MCP compatible con el transporte **Streamable HTTP** y un encabezado `Authorization` personalizado. Versiones de protocolo 2025-11-25, 2025-06-18 y 2025-03-26. | | Red | Si coloca su propio proxy inverso delante del panel, este debe reenviar `/mcp/admin`. Los conectores web (claude.ai, ChatGPT) se conectan desde los servidores del proveedor, por lo que la URL debe ser accesible desde internet. | ## Preparar la infraestructura {#prepare-the-infrastructure} No hay nada que instalar en el servidor. Si restringe la clave por IP, asegúrese de que la dirección desde la que se conecta su cliente esté dentro del rango. Pruebe primero la conectividad: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` Una respuesta de `401` con un encabezado `WWW-Authenticate: Bearer ... resource_metadata=...` indica que el endpoint está activo y solicita credenciales. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Cree una clave: **System › Settings › API & AI agents › API keys › New key**. Para una primera prueba, use solo `admin:read`; agregue scopes de escritura cuando los necesite. Consulte [Admin API keys](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/). 2. Abra la pestaña **Connect an AI**. Mientras el cuadro de diálogo de «clave creada» siga visible, cada fragmento a continuación ya contendrá su clave real. De lo contrario, mostrará el marcador de posición `ak_YOUR_KEY`. 3. Copie el fragmento correspondiente a su cliente y ejecútelo o péguelo como se describe a continuación. ![Pestaña Connect an AI con la URL de MCP y una tarjeta con botón de copia para cada cliente](https://nexcmp.com/es/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" ``` Luego inicie `claude` y pregunte "listar las herramientas de nexcmp" o "¿qué falta por configurar?". Verificado el 30/10/2026 con Claude Code 2.1: `claude mcp add --transport http …` registra el servidor (añada `-s project` para mantenerlo en el `.mcp.json` del proyecto; Claude Code le solicitará aprobar los servidores del proyecto la primera vez). Para scripts, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` se ejecuta sin la solicitud de aprobación y permite que Claude use únicamente las herramientas del panel. ### Claude Desktop {#claude-desktop} Requiere Node.js 18 o posterior. Añada esto a `claude_desktop_config.json` (utiliza el puente `mcp-remote`) y reinicie Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` Si su sistema altera el espacio en el argumento del encabezado, coloque el valor completo en una variable de entorno, exactamente igual que para el endpoint de clientes: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` con `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (conector personalizado) {#claude-ai-custom-connector} No se necesita ninguna clave: inicia sesión con OAuth. En claude.ai abra la configuración de conectores, agregue un conector personalizado, pegue `https://cloud.example.com/mcp/admin`, luego inicie sesión con su cuenta de administrador de NexCMP y elija los permisos en la pantalla de consentimiento. Detalles: [OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (modo desarrollador) {#chatgpt-developer-mode} No se necesita clave. En ChatGPT active el modo desarrollador, agregue un conector MCP con la URL `https://cloud.example.com/mcp/admin`, elija OAuth e inicie sesión con su cuenta de administrador de NexCMP. Detalles: [OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Añada a `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` Luego exporte la clave en el shell que inicia Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip `codex exec` no interactivo En `codex exec` (scripts, CI) Codex no pregunta antes de llamar a las herramientas y omite aquellas que modifican datos. Añada `default_tools_approval_mode = "approve"` bajo `[mcp_servers.nexcmp]` para permitirle ejecutarlas; el panel seguirá devolviendo una vista previa y solicitando confirmación para acciones relacionadas con dinero, seguridad y eliminación. Comprobado con Codex CLI 0.166 el 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Añada a `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` Gemini CLI desactiva los servidores MCP en carpetas en las que no confía. Inícielo en una carpeta de confianza (o confíe en ella cuando lo solicite) y luego compruébelo con `gemini mcp list` — muestra `nexcmp … Connected`. Puede mantener la clave fuera del archivo con `"Authorization": "Bearer $NEXCMP_KEY"`. Comprobado con Gemini CLI 0.66 el 30/10/2026. ### Cursor {#cursor} Añada a `~/.cursor/mcp.json` (o `.cursor/mcp.json` en un proyecto): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip Mantenga la clave fuera de los archivos de configuración Cuando el cliente lo admita, lea la clave desde una variable de entorno en lugar de escribirla en el archivo: Codex lo hace de forma predeterminada (`bearer_token_env_var`) y Cursor admite `"Bearer ${env:NEXCMP_KEY}"`. Nunca haga commit de un archivo que contenga una clave. ::: ### 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", ) ``` Una ejecución completa (comprobada con `openai-agents` 0.24 el 30/10/2026 — una herramienta de lectura, seguida de un cambio de saldo que devolvió la vista previa de confirmación y se aplicó en la segunda llamada con `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} Pase el servidor como una herramienta de tipo `mcp`. Mantenga `require_approval` en `always` para que su programa le solicite confirmación antes de cada llamada: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### Cualquier otra opción (HTTP estándar) {#anything-else-plain-http} Un cliente sin MCP puede llamar a las mismas herramientas a través de HTTP. `GET /v1/admin/agent/tools` las lista, `POST /v1/admin/agent/tools/` ejecuta una con un cuerpo JSON de argumentos y `GET /v1/admin/openapi.json` devuelve una descripción de OpenAPI 3.1 (cada herramienta es una operación). Todas requieren `Authorization: Bearer ak_...`. ## Verificación {#verify} 1. Sin un cliente, liste las herramientas: ```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"}' ``` La respuesta es un resultado JSON-RPC con las herramientas que permiten sus ámbitos. 2. En su cliente, solicite "run system_health". Devuelve alertas, el estado de la infraestructura conectada, pagos, correo electrónico, AI y el estado de la licencia. 3. Abra **API & AI agents › Activity**: las llamadas se listan con el nombre del cliente y `mcp`. 4. En el servidor, `sudo nexcmp status` muestra una línea "MCP admin" que indica `ready` cuando el endpoint responde (HTTP 401 sin clave es el estado correcto). ## Herramientas {#tools} El servidor ofrece 58 herramientas. Un cliente solo ve las herramientas que permiten los ámbitos de su clave: las herramientas de lectura requieren `admin:read`, las de escritura requieren su propio ámbito. Las herramientas de escritura también reciben un argumento opcional `confirm_token` (consulte [Confirmación](#confirmation-confirm-token)). Los argumentos se validan con el esquema de cada herramienta: los argumentos desconocidos o mal escritos se rechazan con un mensaje que los especifica. Los precios están en USD: los precios de los planes en dólares por hora (`hourly_usd`) y los saldos en centavos. Los secretos se pueden configurar, pero nunca se devuelven. ### Resumen y registros {#overview-and-logs} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `system_health` | Alertas que requieren atención, estado de la infraestructura, pagos, correo electrónico, AI, estado de la licencia y de las actualizaciones. | `admin:read` | No | No | | `setup_checklist` | Qué está configurado y qué queda pendiente: licencia, infraestructura, zona, plantillas de SO, planes, pagos, correo electrónico, personalización de marca, avisos legales y pedido de prueba. | `admin:read` | No | No | | `license_status` | Estado de la licencia y comprobación de si existe una versión más reciente de NexCMP. | `admin:read` | No | No | | `audit_search` | Busca en el registro de auditoría de administración y en el registro de claves de API. | `admin:read` | No | No | ### Configuración, marca, legal, módulos {#settings-branding-legal-modules} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `settings_get` | Lee la configuración general (`keys` filtra; un `*` final coincide con un prefijo). | `admin:read` | No | No | | `settings_update` | Modifica la configuración general desde un objeto plano `values`. Solo se aceptan las claves listadas por `settings_get`. | `settings:write` | Sí | Cuando una clave afecta a pagos, seguridad de inicio de sesión, ajustes globales del sitio o precios | | `branding_get` | Nombre de marca, color, moneda de visualización, nombre del vendedor y URL del logotipo y favicon. | `admin:read` | No | No | | `branding_update` | Establece el nombre de marca (hasta 60 caracteres), el color (`#rrggbb`), la moneda de visualización (`usd` o `vnd`) y el nombre del vendedor. | `settings:write` | Sí | No | | `branding_logo_set` | Subir un logotipo claro u oscuro, o un favicon, desde una URL https o base64 (PNG, JPEG, WEBP, ICO o SVG, hasta 512 KB). | `settings:write` | Sí | No | | `legal_get` | Términos de servicio y política de privacidad (inglés y vietnamita) y los valores neutrales predeterminados. | `admin:read` | No | No | | `legal_update` | Definir el texto de términos y privacidad (markdown simple, sin HTML, hasta 50 KB cada uno). Una cadena vacía restaura el valor predeterminado. | `settings:write` | Sí | No | | `modules_get` | Qué módulos opcionales están activados y cuáles se pueden alternar. | `admin:read` | No | No | | `module_set` | Activar o desactivar un módulo opcional (`key` debe ser uno de `settable`). | `settings:write` | Sí | No | ### Correo electrónico y alertas {#email-and-alerts} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `smtp_get` | Configuración del correo saliente (contraseña oculta) y estado de la cola. | `admin:read` | No | No | | `smtp_configure` | Definir el servidor SMTP. Cambiar el host, el puerto o la seguridad requiere ingresar la contraseña de nuevo. | `settings:write` (+ `secrets:write` para la contraseña) | Sí | No | | `smtp_test` | Enviar un correo de prueba real con la configuración guardada. | `settings:write` | Envía un correo | No | | `telegram_get` | Canales de notificación de administración (chat IDs; los tokens del bot nunca se devuelven). | `admin:read` | No | No | | `telegram_configure` | Agregar o actualizar el canal de alertas de Telegram (bot token y chat ID) y activar o desactivar las alertas de administración. | `settings:write` (+ `secrets:write` para el token) | Sí | No | | `telegram_test` | Enviar un mensaje de prueba al canal de Telegram. | `settings:write` | Envía un mensaje | No | ### Pagos y monedas {#payments-and-currency} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `payments_get` | Estado de Stripe, PayPal, cripto (USDT) y transferencia bancaria, además de canales habilitados y comisiones. | `admin:read` | No | No | | `payment_configure` | Configurar las credenciales de una pasarela (`stripe`, `paypal`, `crypto` o `bank`). | `billing:write` (+ `secrets:write`) | Sí | Siempre | | `payment_test` | Verificar con el proveedor las credenciales guardadas de una pasarela. | `billing:write` | No | No | | `currency_get` | Moneda de visualización y tasa de cambio de USD a VND (automática o manual). | `admin:read` | No | No | | `currency_set` | Definir la moneda de visualización o una tasa manual (0 significa automática; de lo contrario, entre 15000 y 50000). | `billing:write` | Sí | Al cambiar la tasa manual | ### Infraestructura y zonas {#infrastructure-and-zones} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `cloudstack_get` | Endpoint de CloudStack guardado, IDs de zona y red (claves ocultas). | `admin:read` | No | No | | `cloudstack_test` | Probar un endpoint con un API key y secret sin guardar; enumera las zonas. | `infra:write` (+ `secrets:write`, ya que transmite las claves) | No | No | | `cloudstack_connect` | Guardar la conexión con CloudStack. | `infra:write` (+ `secrets:write`) | Sí | Siempre | | `proxmox_list` | Clústeres de Proxmox VE agregados como fuentes, junto con su estado de salud. | `admin:read` | No | No | | `proxmox_add` | Agregar un clúster de Proxmox VE con un API token (`user@realm!tokenid`) y su secret. | `infra:write` (+ `secrets:write`) | Sí | No | | `proxmox_test` | Conectar a un clúster por ID; la primera conexión correcta fija su certificado TLS. | `infra:write` | Sí | No | | `proxmox_attach_zone` | Comercializar un clúster de Proxmox en una zona existente, opcionalmente con un nodo como región. | `infra:write` | Sí | No | | `zones_list` | Zonas (ubicaciones) que los clientes pueden elegir. | `admin:read` | No | No | | `zone_create` | Crear una zona. | `infra:write` | Sí | No | ### Catálogo y planes {#catalog-and-plans} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `templates_list` | Plantillas de SO que los clientes pueden instalar. | `admin:read` | No | No | | `templates_sync` | Importar plantillas de SO desde CloudStack. | `catalog:write` | Sí | No | | `template_update` | Habilitar u ocultar una plantilla, cambiarle el nombre, definir el usuario de inicio de sesión o el orden. | `catalog:write` | Sí | No | | `offerings_list` | Ofertas de servicio de CloudStack (CPU, memoria, disco raíz) para crear planes a partir de ellas. | `admin:read` | No | No | | `plans_list` | Planes con precio por hora y por mes, tamaño, zona y cuántos servidores los utilizan. | `admin:read` | No | No | | `plan_create` | Crear un plan. Precio como `hourly_usd`. Los planes de CloudStack requieren `cs_offering_id`; los planes de Proxmox requieren `backend_id`. | `catalog:write` | Sí | No | | `plan_update` | Renombrar, mostrar u ocultar, habilitar o deshabilitar, o cambiar el precio de un plan. Cambiar el tamaño en un plan en uso requiere una copia. | `catalog:write` | Sí | Al cambiar el precio | | `plans_from_offerings` | Crea una tabla de planes iniciales a partir de ofertas (o tamaños de Proxmox) utilizando su costo y un porcentaje de margen. Devuelve una vista previa; llame de nuevo con `apply=true` para crear los planes. | `catalog:write` | Con `apply=true` | Siempre al aplicar | | `quota_defaults_get` | Límites predeterminados de clientes. | `admin:read` | No | No | | `quota_defaults_set` | Cambia la configuración de `quota_*`. | `catalog:write` | Sí | No | | `coupons_list` | Lotes de códigos de descuento y de regalo. | `admin:read` | No | No | | `coupon_create` | Crea un lote de códigos: tipo `money` (valor nominal en centavos de USD) o `percent` (de 1 a 100, con un descuento máximo). | `catalog:write` | Sí | Siempre | ### Clientes y revendedores {#customers-and-resellers} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `customers_search` | Busca clientes por correo electrónico, nombre o IP. | `admin:read` | No | No | | `customer_get` | Cuenta, saldo, servidores y facturación reciente de un cliente. | `admin:read` | No | No | | `customer_adjust_balance` | Añade (positivo) o retira (negativo) crédito en centavos de USD. Se requiere un motivo. | `billing:write` | Sí | Siempre | | `customer_block` | Bloquea a un cliente, deteniendo opcionalmente sus servidores. Se requiere un motivo. | `customers:write` | Sí | Siempre | | `customer_unblock` | Desbloquea a un cliente. | `customers:write` | Sí | No | | `resellers_list` | Revendedores con billetera y estado. | `admin:read` | No | No | | `reseller_get` | Sitio, billetera, usuarios y pasarelas de un revendedor. | `admin:read` | No | No | ### Proveedor de IA {#ai-provider} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `ai_provider_get` | El proveedor compatible con OpenAI utilizado por AI Chat y AI Agent del cliente (clave enmascarada). | `admin:read` | No | No | | `ai_provider_set` | Define el proveedor: URL base, modelo, clave de API, modelos de respaldo, esfuerzo de razonamiento, habilitado. | `ai:write` (+ `secrets:write` para la clave) | Sí | No | | `ai_provider_test` | Hace una pregunta al proveedor guardado para comprobar que funciona. | `ai:write` | No | No | ### Archivos de configuración {#configuration-files} | Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación | |---|---|---|---|---| | `config_export` | Exporta la configuración como YAML (los secretos se convierten en referencias `secret://`). | `admin:read` | No | No | | `config_plan` | Compara una configuración YAML con el panel activo y enumera los cambios. | `admin:read` | No | No | | `config_apply` | Aplica una configuración YAML sección por sección. Cada cambio sigue las reglas normales de alcance y confirmación. | `admin:read` + el alcance de cada cambio | Sí | Por cada cambio | Consulte [Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/) para conocer el formato de archivo. ## Prompts {#prompts} El servidor también ofrece tres prompts predefinidos que los clientes pueden mostrar como accesos directos: | Prompt | Argumento | Qué le pide hacer a la IA | |---|---|---| | `initial-setup` | ninguno | Llama a `setup_checklist`, explica cada paso pendiente en una sola frase, le solicita la información que necesita, ejecuta el paso con la herramienta correspondiente, muestra una vista previa de los cambios de dinero o seguridad y finaliza con `system_health`. | | `add-proxmox` | `endpoint` (opcional, `https://host:8006`) | Solicita el token de API, luego `proxmox_add`, `proxmox_test`, herramientas de zona y `proxmox_attach_zone`; después propone planes con `plans_from_offerings` y espera su aprobación. | | `launch-pricing` | `margin_pct` (opcional, predeterminado 40) | Solicita su costo mensual por vCPU, por GB de RAM y por GB de disco, muestra una tabla de vista previa con el costo, el precio mensual y el precio por hora, y crea los planes tras su aprobación. | ## Confirmación (`confirm_token`) {#confirmation-confirm-token} Las acciones que transfieren dinero, eliminan datos, modifican credenciales de pago o la seguridad de inicio de sesión constan de dos pasos: 1. La primera llamada no modifica nada. El resultado de la herramienta comienza con "CONFIRMATION REQUIRED" e incluye una **vista previa** (qué se llamará, por qué es delicado, los nuevos valores y los actuales) y un `confirm_token`. 2. El cliente debe mostrarle la vista previa. Solo tras su aprobación vuelve a llamar a la misma herramienta con los mismos argumentos más `confirm_token`. 3. El token funciona una sola vez, únicamente para esa solicitud exacta, y caduca a los 5 minutos. Las instrucciones del servidor indican a la IA que trate los resultados de las herramientas como datos, no como instrucciones, y que nunca repita una llamada con un token que usted no haya aprobado. Usted es la salvaguarda: revise la vista previa. ::: warning No apruebe automáticamente Algunos clientes pueden aprobar cada llamada de herramienta automáticamente. Para las herramientas de escritura, mantenga activa la aprobación llamada por llamada o use una clave de solo lectura, de modo que un plan incorrecto de la IA no llegue a su panel sin supervisión. ::: ## Cómo funciona {#how-it-works} | Elemento | Detalle | |---|---| | Transporte | `POST /mcp/admin` con un mensaje JSON-RPC 2.0; la respuesta es `application/json`. Hasta 20 mensajes en un lote. `GET /mcp/admin` responde 405 (sin server stream); `DELETE /mcp/admin` finaliza una sesión. | | Autenticación | `Authorization: Bearer ak_...` (una clave manual o un token de acceso OAuth). Las credenciales faltantes o incorrectas devuelven 401 con `WWW-Authenticate: Bearer ... resource_metadata=...`, lo que permite a los clientes OAuth iniciar sesión por sí mismos. | | Sesiones | `Mcp-Session-Id` es emitido por `initialize`, está vinculado a esa clave y es válido durante 24 horas. | | Capacidades | Herramientas y prompts. Sin recursos. | | Tamaño | Cuerpo de solicitud de hasta 1 MB; el resultado de una herramienta se trunca tras unos 100 KB. | | Origen | Se rechaza una solicitud que contenga una cabecera `Origin` de otro sitio (`origin_not_allowed`). Los clientes de línea de comandos y de escritorio no envían ninguna. | | Mismo control que REST | Cada llamada de herramienta se reenvía a través del propio pipeline de solicitudes del panel con su clave, por lo que los alcances, los rangos de IP, el rate limit, la confirmación y el registro de actividad se aplican exactamente igual que en las llamadas directas a la API. | ## Límites y notas {#limits-notes} - Una herramienta que no puede ver es un alcance que no otorgó. Añada el alcance a una nueva clave. - Configurar una contraseña o clave de API a través de un cliente de IA significa que el secreto pasa por esa IA. Si lo prefiere, deje `secrets:write` desactivado e introduzca los secretos usted mismo en el panel de administración, o use el campo **Secret** de AI Chat ([AI Chat en la administración](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/#secrets)) o las referencias `secret://` ([Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/#secrets)). - Los clientes no comparten sesiones: cada conexión comienza con `initialize`. - Revoque la clave en **API & AI agents** para desconectar de inmediato a un cliente de IA. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | 401 `invalid_key` | Clave incorrecta, truncada o que no es de administrador (por ejemplo, una clave `vk_`) | Use una clave `ak_`. | | 401 `key_expired` o `key_revoked` | La clave expiró o fue revocada | Cree una nueva clave. | | 403 `ip_not_allowed` | Su IP está fuera de los rangos de IP de la clave | Conéctese desde una IP permitida. | | 403 `origin_not_allowed` | Una página del navegador en otro origen llamó al endpoint | Use un cliente de escritorio o CLI. | | 404 en una solicitud con `Mcp-Session-Id` | La sesión pertenece a otra clave o ha expirado | Envíe `initialize` de nuevo. | | 400 unsupported `MCP-Protocol-Version` | El cliente utiliza una versión que el servidor no reconoce | Actualice el cliente; admitidas: 2025-11-25, 2025-06-18, 2025-03-26. | | La lista de herramientas es corta | Alcances de la clave | Cree una clave con más alcances. | | `insufficient_scope` en una llamada | Una herramienta necesita un segundo alcance, por ejemplo `secrets:write` | Añada el alcance a una nueva clave. | | 429 `rate_limited` | Más llamadas por minuto de las que permite la clave | Espere a `Retry-After` o aumente el límite en una nueva clave. | | claude.ai o ChatGPT no pueden conectarse | La URL no es accesible desde internet, o un proxy bloquea `/mcp/admin` o `/oauth-admin/` | Compruebe el DNS, TLS y el proxy inverso. | Para ver todos los códigos de error, consulte [Claves de API de administración](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#errors). --- # Conectores de claude.ai y ChatGPT {#claude-ai-and-chatgpt-connectors} > **Ubicación en el admin:** System › Settings › API & AI agents (`/agent/keys`), pestaña **Connected apps**. La pantalla de consentimiento se abre en `/agent/consent` cuando un conector solicita acceso (no está en el menú). ## Qué hace {#what-it-does} Las aplicaciones web de IA no pueden leer una clave de su disco. Se conectan mediante **OAuth**: usted añade la URL de MCP del panel, la aplicación le redirige a su propio admin para iniciar sesión, usted elige qué puede hacer la app y durante cuánto tiempo, y la aplicación recibe tokens de corta duración. No se copia ni se pega ninguna clave. Puede desconectar la aplicación en cualquier momento. Utilice esto para los conectores personalizados de claude.ai, los conectores en modo desarrollador de ChatGPT y cualquier otro cliente MCP compatible con OAuth y registro dinámico de clientes. Las herramientas de línea de comandos pueden usar el mismo flujo, pero una [clave de API de admin](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) resulta más sencilla para ellas. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | URL | `https://cloud.example.com/mcp/admin`, accesible desde internet (los servidores del proveedor se conectan a ella). | | Proxy inverso | Si coloca su propio proxy delante del panel, debe reenviar `/mcp/admin`, `/oauth-admin/` y las rutas `/.well-known/` al panel. | | Usted | Sesión iniciada en el admin de NexCMP **en el mismo navegador** que utilice para la pantalla de consentimiento. | | Cliente | Compatible con MCP sobre Streamable HTTP, OAuth 2.1 con PKCE (S256) y registro dinámico de clientes. | ## Conectar {#connect} 1. En la aplicación de IA, añada un conector MCP personalizado y pegue `https://cloud.example.com/mcp/admin`. En claude.ai esto se encuentra en los ajustes de conectores (añadir conector personalizado); en ChatGPT está en el modo desarrollador (añadir conector MCP, autenticación OAuth). 2. Elija **Sign in** (o "Connect") en la aplicación. Su navegador abrirá la pantalla de consentimiento del admin de NexCMP. Si no ha iniciado sesión, iníciela primero; la pantalla continuará después. 3. Lea la tarjeta: "**Example AI app** wants to manage this NexCMP admin" (el nombre de la app solicitante), junto con la dirección a la que se le redirigirá. 4. Marque los permisos que desea conceder. Los solicitados por la aplicación aparecen premarcados; si no solicitó ninguno, solo `admin:read` estará marcado. Consulte [Scopes](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#scopes). 5. Elija la duración de la conexión: **7**, **30** o **90** días (por defecto, 30). 6. Haga clic en **Allow**. El navegador regresará a la aplicación, que ahora estará conectada. Haga clic en **Deny** para rechazarla. ![Pantalla de consentimiento que solicita autorizar una app de IA, con casillas de verificación de permisos, selección de duración y botones Allow y Deny](https://nexcmp.com/es/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important Elija los permisos como lo haría para una clave Otorgue el conjunto mínimo necesario para la tarea. Las acciones financieras, de eliminación y de seguridad seguirán deteniéndose en una vista previa y requerirán su aprobación, pero una conexión con `settings:write` aún puede modificar su imagen de marca y correo electrónico. ::: ## Gestionar y revocar {#manage-and-revoke} Abra **System › Settings › API & AI agents › Connected apps**. La tabla enumera cada aplicación que ha conectado: aplicación, permisos, cuándo se conectó, cuándo expira y cuándo se utilizó por última vez. Para revocar el acceso a una aplicación, haga clic en **Revoke** y confirme. Sus tokens dejarán de funcionar de inmediato; la aplicación deberá pasar de nuevo por la pantalla de consentimiento para volver a conectarse. ![Pestaña Connected apps con una app de IA listada, sus permisos, vencimiento y un botón Revoke](https://nexcmp.com/es/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## Cómo funciona el flujo {#how-the-flow-works} | Paso | Detalle | |---|---| | Descubrimiento | La aplicación lee `/.well-known/oauth-protected-resource/mcp/admin` y luego `/.well-known/oauth-authorization-server/oauth-admin`. El emisor es `https://cloud.example.com/oauth-admin`. | | Registro | La aplicación se registra a sí misma (`POST /oauth-admin/register`, RFC 7591). Solo se admiten clientes públicos (sin client secret). La dirección de redirección debe ser `https`, o `http` en el mismo equipo (loopback). | | Autorización | `GET /oauth-admin/authorize` con el método PKCE `S256`. Si se envía el parámetro `resource`, debe ser la URL `/mcp/admin` de este panel. La solicitud es válida durante 10 minutos y está vinculada al navegador que la inició. | | Consentimiento | Usted elige los scopes y la duración (arriba). El código de autorización es válido durante 60 segundos y funciona una sola vez. | | Tokens | `POST /oauth-admin/token` devuelve un **access token** (una clave `ak_o...`, válida durante 1 hora o hasta que finalice la conexión, lo que ocurra antes) y un **refresh token** (`akr_...`). Cada actualización devuelve un nuevo refresh token; el anterior deja de funcionar. La conexión finaliza transcurridos los días elegidos. | | Revocación | **Revoke** en Connected apps, o la aplicación llama a `POST /oauth-admin/revoke` (RFC 7009). | El access token funciona como una clave admin con los scopes otorgados: mismas reglas de scope, confirmación, límite de tasa y registro de actividad. Sus llamadas aparecen en la pestaña **Activity**. ## Verificación {#verify} 1. En la aplicación, solicite "run system_health" (o "what tools do you have?"). La aplicación listará las herramientas permitidas por sus scopes ([la lista de herramientas](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/#tools)). 2. Abra **Connected apps**: **Last used** se actualiza. 3. Abra **Activity**: las llamadas se listan con el nombre de la aplicación y `mcp`. ## Límites y notas {#limits-notes} - Si la aplicación solicita iniciar sesión de nuevo tras una hora, es normal cuando un cliente no actualiza los tokens; vuelva a conectarse. - Un refresh token utilizado dos veces se considera sustraído: se revoca la conexión completa. Vuelva a conectarse desde la aplicación. - Un código de autorización utilizado dos veces se rechaza (`invalid_grant`) y se revocan los tokens emitidos a partir de él. - El acceso OAuth nunca otorga más de lo permitido por las reglas de scopes: [lo que una clave nunca puede hacer](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) también aplica a las aplicaciones conectadas. - Los proveedores cambian sus menús y compatibilidad. Si la aplicación de un proveedor no ofrece conectores personalizados en su plan, utilice en su lugar una [admin API key](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) con un cliente de escritorio o de línea de comandos. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | La pantalla de consentimiento indica "Wrong browser" | La solicitud se inició en un navegador distinto de aquel en el que ha iniciado sesión | Inicie la conexión de nuevo desde la aplicación de IA en el mismo navegador. | | La pantalla de consentimiento indica que la solicitud ha caducado o no existe | Han pasado más de 10 minutos o el enlace se abrió dos veces | Inicie la conexión de nuevo desde la aplicación de IA. | | Página con "Unknown client" o "redirect address does not match" | El registro de la aplicación ha caducado o utiliza una dirección de redirección que no registró | Elimine el conector en la aplicación y agréguelo de nuevo. | | `invalid_target` | El `resource` enviado no es la URL `/mcp/admin` de este panel | Utilice la URL exacta que se muestra en la pestaña **Connect an AI**. | | `invalid_request` sobre PKCE | El cliente no envía `code_challenge_method=S256` | Utilice un cliente compatible con OAuth 2.1 con PKCE. | | La aplicación se conecta pero una llamada devuelve `insufficient_scope` | No seleccionó ese scope | Revoque la conexión y conéctese de nuevo marcando dicho scope. | | La aplicación no puede acceder a la URL | DNS, TLS o el proxy inverso bloquean `/mcp/admin`, `/oauth-admin/` o `/.well-known/` | Compruebe las reglas del proxy. | --- # Configuración como código {#configuration-as-code} > **En el panel de administración:** System › Settings › Import/Export (`/agent/config`). En el servidor: los comandos `nexcmp config export`, `plan` y `apply`, y `nexcmp admin `. ## Qué hace {#what-it-does} La configuración de su panel (marca, ajustes generales, correo electrónico, alertas de Telegram, módulos, moneda, pasarelas de pago, límites, zonas, planes, el proveedor de IA y las páginas legales) se puede guardar como un único archivo YAML. Puede editar el archivo usted mismo, pedirle a un asistente de IA que lo edite, mantenerlo bajo control de versiones y aplicarlo al mismo panel o a otro. Antes de que cambie nada, siempre verá una lista de diferencias. Los secretos nunca se escriben en el archivo. Úselo para clonar una configuración en una segunda instalación, revisar cambios antes de ponerlos en producción, restaurar ajustes tras un error o permitir que una IA proponga una configuración completa que usted pueda revisar como un único documento. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | NexCMP | 1.4.0 o posterior. | | Línea de comandos | Usted es `root` en el servidor del panel (use `sudo`). El comando solicita por sí mismo una clave temporal al panel (15 minutos, todos los ámbitos). Para usar en su lugar una clave más restringida, configure `NEXCMP_KEY` con una [clave de API de administrador](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) y consérvela mediante sudo, por ejemplo `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | Página de administración | Haber iniciado sesión en la administración. La página es de solo lectura en un panel de demostración. | | Secretos | Valores proporcionados al momento de aplicar (consulte [Secretos](#secrets)); nunca dentro del archivo. | ## Exportar, editar, previsualizar, aplicar {#export-edit-preview-apply} 1. Exporte la configuración actual: ```bash sudo nexcmp config export -o nexcmp.yaml ``` Sin `-o`, el YAML se muestra en pantalla. 2. Edite `nexcmp.yaml` (consulte el [ejemplo](#example-file) a continuación). Mantenga `version: 1` en la parte superior. 3. Previsualice qué cambiaría. Esto no modifica nada: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` Cada línea muestra sección, elemento, campo y `old → new`. Las líneas marcadas con `$` pertenecen a secciones de facturación (consulte [Secciones de facturación](#billing-sections)). Si el panel ya coincide con el archivo, verá "No changes". 4. Aplique los cambios. Sin `--yes`, el comando es un **dry run** y solo muestra la misma lista: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. Revise el resultado: `applied`, `pending` (a la espera de su confirmación), `skipped` y `errors`. | Opción | Significado | |---|---| | `-f ` | El archivo YAML (obligatorio para `plan` y `apply`). | | `--yes` | Aplica realmente los cambios. Sin ella, `apply` es un dry run. | | `--confirm-billing` | Aplica también las secciones de facturación (`payments`, `currency`, `plans`). Sin esta opción, se omiten. | | `--section ` | Aplica únicamente esta sección. Repita la opción para varias. | | `-o ` | Con `export`: escribe el YAML en un archivo. | El código de salida es 0 cuando se aplicó todo o no hubo cambios, 1 cuando se devolvió un error y 2 en caso de error de uso o de clave. ### Secretos {#secrets} El archivo contiene referencias en lugar de secretos, como `password: secret://smtp_password`. Al momento de aplicar, el valor se obtiene de una variable de entorno llamada `NEXCMP_SECRET_` más el nombre de la referencia en mayú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 ``` Si una referencia no tiene ningún valor, el secreto ya guardado en el panel se **conserva**. Un secreto que nunca se guardó y no se proporciona permanece vacío. | Nombre de referencia | Dónde se aplica | |---|---| | `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` | ## Archivo de ejemplo {#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). ``` Un archivo puede contener cualquier subconjunto de las secciones. Las secciones que omita no se modificarán. Cualquier archivo que supere 1 MB, no incluya `version: 1`, tenga un número de versión distinto o contenga una sección desconocida será rechazado antes de ejecutar nada. ## Secciones {#sections} | Sección | Qué controla | Notas | |---|---|---| | `branding` | Nombre de la marca (hasta 60 caracteres), color principal, moneda de visualización (`usd` o `vnd`), nombre del vendedor. | Los logotipos no forman parte del archivo; use la [página de marca](https://nexcmp.com/es/docs/customers/branding/). | | `settings` | Una lista fija de ajustes generales: `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`. | Se ignoran las demás claves. | | `email.smtp` | Host SMTP, puerto, seguridad (`starttls`, `tls`, `none`), usuario, contraseña, nombre y dirección del remitente, reply-to. | [SMTP y plantillas de correo electrónico](https://nexcmp.com/es/docs/administration/smtp-and-emails/). Si cambia el host, el puerto o la seguridad, se requerirá de nuevo la contraseña. | | `telegram` | Canal de alertas activado o desactivado, chat id, bot token. | [Notificaciones de Telegram](https://nexcmp.com/es/docs/administration/telegram-notifications/). | | `modules` | Módulos opcionales activados o desactivados (`key: true/false`). | Solo las claves que el panel permite cambiar. Consulte [Módulos](https://nexcmp.com/es/docs/infrastructure/modules/). | | `currency` | Divisa de visualización y tipo de cambio manual de USD a VND (`0` automático; de lo contrario, de 15000 a 50000). | Sección de facturación. Consulte [Divisas y tipos de cambio](https://nexcmp.com/es/docs/catalog/currency-and-exchange-rates/). | | `payments` | Credenciales de `stripe`, `paypal`, `crypto`, `bank` y conmutadores de `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Sección de facturación. Consulte [Canales de pago](https://nexcmp.com/es/docs/billing/payment-channels/). | | `quotas` | Límites de `quota_*`. | Consulte [Cuotas](https://nexcmp.com/es/docs/billing/quotas/). | | `zones` | Zonas por `slug` (obligatorio: `slug`, `name`, `country`; opcional `city`, `enabled`, `is_default`). | Se crean nuevas zonas. Las zonas que ya existen **no se modifican** mediante el archivo. Consulte [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). | | `plans` | Planes por `slug` (obligatorio: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; opcional `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Sección de facturación. Se crean planes nuevos y los existentes se actualizan por slug. Los precios se expresan en USD por hora. Consulte [Planes](https://nexcmp.com/es/docs/catalog/plans/). | | `ai_provider` | El proveedor de IA del panel utilizado por AI Chat y AI Agent de los clientes. | [AI provider](https://nexcmp.com/es/docs/ai/ai-providers/). | | `legal` | Texto de términos y privacidad por idioma (`en`, `vi`). | [Páginas legales](https://nexcmp.com/es/docs/customers/legal/). | El orden de aplicación es el indicado arriba: los elementos relacionados con la infraestructura van antes que los planes. ## Reglas para recordar {#rules-to-remember} - **Idempotente.** Aplicar el mismo archivo dos veces no cambia nada la segunda vez. `plan` muestra "No changes". - **Sin eliminaciones.** El archivo nunca elimina una zona, plan o ajuste. Eliminar una entrada del archivo deja el panel tal como está. - **Las reglas de seguridad habituales siguen vigentes.** Desde la línea de comandos, cada cambio pasa por las mismas comprobaciones que un cambio por API: ámbitos y reglas de IP. Los cambios que requieren confirmación (un interruptor a nivel de todo el sitio, por ejemplo) se notifican bajo `pending` con una vista previa en lugar de aplicarse, a menos que pase `--confirm-billing`, lo que los confirma todos. - **Los clientes de IA no pueden desbloquear la facturación.** Cuando un cliente MCP llama a `config_apply`, `confirm_billing` se ignora; los cambios monetarios quedan a la espera de su confirmación. - **Compruebe antes de aplicar.** El JSON Schema describe cada campo. Apunte su editor hacia él o proporcióneselo a una IA para que genere YAML válido: `https://cloud.example.com/v1/admin/agent/config/schema.json` (legible públicamente). ### Secciones de facturación {#billing-sections} `payments`, `currency` y `plans` modifican precios o flujos de dinero. `nexcmp config apply --yes` los **omite** a menos que añada `--confirm-billing`; en ese caso se enumeran bajo `skipped` ("billing section - pass confirm_billing"). Esta opción es su confirmación: con ella, cada cambio de facturación en el archivo (y cualquier otro cambio que solicite confirmación) se aplica sin una segunda solicitud. Ejecute primero `plan` y lea cada línea marcada con `$`. Cuando una IA aplica el mismo archivo (la herramienta `config_apply` en un cliente MCP o AI Chat), la opción se ignora y, en su lugar, los cambios monetarios quedan a la espera de su aprobación. ## Usar la página Import/Export {#use-the-import-export-page} 1. Abra **System › Settings › Import/Export**. 2. En **Export**, haga clic en **Get current configuration** y luego en **Download .yaml** para guardar `nexcmp.yaml`. Los secretos aparecen como marcadores de posición. 3. En **Import**, elija un archivo, arrástrelo al cuadro o pegue el YAML. 4. Opcional: abra **Secrets that come with it (not in the file)** y añada un nombre y un valor para cada referencia, por ejemplo `smtp_password`. 5. Haga clic en **Preview changes**. La tabla agrupa los cambios por sección; las secciones relacionadas con dinero llevan la etiqueta "Money-related". Desmarque las secciones que no desee. 6. Si se listan secciones relacionadas con dinero, marque **Also apply money-related changes (prices, payment gateways, balances)**. Sin marcar la casilla, se omitirán. 7. Haga clic en **Apply selected**. El resultado muestra lo que se aplicó, se omitió o falló. Los cambios devueltos como pendientes de confirmación aparecen como una tarjeta de confirmación; pulse **Confirm** en ella. El botón **JSON Schema** en la esquina superior derecha abre el esquema. ![Página Import/Export con la tarjeta Export y la tarjeta Import que contiene el YAML exportado](https://nexcmp.com/es/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Tabla de vista previa de cambios agrupados por sección con una etiqueta de facturación y un botón Apply selected](https://nexcmp.com/es/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Ejecutar cualquier herramienta desde la línea de comandos {#run-any-tool-from-the-command-line} `nexcmp admin` ejecuta las mismas herramientas que los asistentes de IA ([la lista de herramientas](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/#tools)) y muestra 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"}}' ``` Los argumentos son pares `key=value` (los valores se interpretan como JSON si es posible; de lo contrario, como texto) o un objeto `--json '{...}'`. Si la acción requiere confirmación, el comando muestra la vista previa y se detiene con el código de salida 3 y "Nothing changed". Revise la vista previa y vuelva a ejecutar el mismo comando con `--yes` para aplicarla. Al ejecutarse como root, el comando obtiene una clave de 15 minutos con todos los ámbitos, por lo que el paso de confirmación es su protección; con `NEXCMP_KEY` se aplican los propios ámbitos de la clave. ## Verificación {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` justo después de un `apply --yes` muestra "No changes". 2. En el panel de administración, las páginas modificadas muestran los nuevos valores y **Logs › Admin actions** lista los cambios. 3. Aplicar de nuevo el mismo archivo no cambia nada. ## Límites y notas {#limits-notes} - El archivo cubre las configuraciones anteriores, no clientes, servidores, facturas ni fuentes de infraestructura (conexiones de CloudStack y Proxmox). Conéctelas con [AI Chat](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/) o desde las páginas de administración. - Las zonas y los planes se vinculan mediante `slug`. No cambie el slug en el archivo: se crearía como un elemento nuevo. - Un plan que los clientes ya están utilizando no puede cambiar de tamaño; cree un nuevo plan en su lugar. - Mantenga la privacidad de los archivos exportados aunque no contengan secretos: enumeran sus precios, direcciones y nombres de cuentas. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | `missing version: 1` | El archivo no comienza con `version: 1` | Agréguelo. | | `unsupported version 2` | El archivo tiene otro número de versión | Este panel solo lee la versión 1. | | `unknown section 'x' (known: ...)` | Una clave de nivel superior mal escrita o no admitida | Utilice las secciones anteriores. | | `YAML error: ...` | YAML no válido (sangría, tabulaciones) | Corrija la línea que indica el mensaje. | | `config is larger than 1 MB` | Archivo demasiado grande | Divídalo y utilice `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | El comando no encontró ninguna clave | Ejecútelo con `sudo` o exporte `NEXCMP_KEY` y consérvelo mediante sudo. | | `panel not reachable` | El servicio del panel no se está ejecutando en el puerto predeterminado | Compruebe `sudo nexcmp status`. | | Líneas de facturación bajo `skipped` | Las secciones de facturación requieren `--confirm-billing` | Añada el flag y revise primero las líneas `$`. | | Elementos bajo `pending` | El cambio requiere confirmación | Abra **API & AI agents** o el resultado de Import/Export y pulse **Confirm** en la tarjeta. | | No se actualizó un secreto | No se definió ningún valor para `NEXCMP_SECRET_`, por lo que se mantuvo el secreto guardado | Exporte la variable y aplique de nuevo. | | Entrada bajo `errors` con HTTP 403 `insufficient_scope` | La clave carece del ámbito de esa sección | Utilice una clave con dicho ámbito o ejecútelo como root. | | Entrada bajo `errors` con HTTP 403 `demo_read_only` | Panel de demostración | Aplíquelo en una instalación real. | --- # Prompts de ejemplo {#example-prompts} > **Dónde encontrarlo en la administración:** AI Chat (`/agent`) o el botón flotante **Ask AI** en cualquier página de administración. Los mismos prompts funcionan en cualquier cliente de IA conectado mediante [MCP](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/). ## Qué hace {#what-it-does} Estos prompts muestran cómo formular las peticiones. Cada uno detalla lo que hace el asistente en segundo plano, los scopes necesarios (para un cliente externo o una clave) y en qué punto se solicita su aprobación. Sustituya los valores de ejemplo por los suyos. ::: tip Nunca introduzca un secreto en el texto del chat Para contraseñas, claves de API y tokens, utilice el campo **Secret** situado junto a la entrada de AI Chat ([detalles](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/#secrets)). La IA solo ve un marcador de posición que representa el secreto, no el valor real. Con un cliente de IA externo, el secreto pasa a través de dicho cliente, por lo que se recomienda introducirlo en la administración. ::: ## Comprobar el estado actual {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` El asistente llama a `setup_checklist` y a `system_health` (scope `admin:read`) y responde a partir del estado real. Consulte la [Lista de comprobación del progreso de la configuración](https://nexcmp.com/es/docs/configure-with-ai/setup-checklist/). ## Configuración inicial {#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. ``` Esto equivale al prompt de MCP `initial-setup`. Requiere `admin:read` más los scopes de los pasos que acepte. Verá una tarjeta de confirmación para cada cambio en AI Chat. ## Añadir un clúster de 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. ``` Qué sucede: 1. El asistente solicita el id del token de API (`user@realm!tokenid`) y su secreto. Introduzca el secreto en el campo **Secret**. Cree primero un token con permisos limitados: [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). 2. Llama a `proxmox_add`, `proxmox_test`, `zone_create` y `proxmox_attach_zone`. 3. Propone planes con `plans_from_offerings` y espera su aprobación (consulte el siguiente ejemplo). Scopes: `infra:write`, `secrets:write`, `catalog:write`, `admin:read`. ## Crear una tabla de planes con un margen del 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. ``` El asistente llama a `plans_from_offerings` con `margin_pct` 40 y sus costos. El margen es el porcentaje del precio de venta que corresponde al beneficio: al 40%, un plan que le cuesta $60 se vende por $100. La primera llamada solo devuelve una vista previa. Al dar su aprobación, vuelve a llamar a la herramienta con `apply=true`, lo que crea los planes en un solo paso y solicita una confirmación porque hay precios involucrados. Para Proxmox utiliza `backend_id` y una lista de tamaños predeterminada (1, 2, 2 y 4 vCPU). Scopes: `catalog:write`, `admin:read`. Consulte [Planes](https://nexcmp.com/es/docs/catalog/plans/). ![Respuesta de AI Chat que muestra una tabla de vista previa de los planes con costo, precio mensual y precio por hora](https://nexcmp.com/es/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## Configurar el correo electrónico y enviar un mensaje de prueba {#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. ``` El asistente llama a `smtp_get`, `smtp_configure` y `smtp_test` y le informa de si el mensaje fue aceptado. Scopes: `settings:write`, `secrets:write`. Consulte [SMTP y plantillas de correo electrónico](https://nexcmp.com/es/docs/administration/smtp-and-emails/). ## Configurar 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` es siempre una acción en dos pasos: verá una vista previa con los valores secretos ocultos y la aprobará. A continuación, `payment_test` comprueba las credenciales con Stripe. Scopes: `billing:write`, `secrets:write`. Cambie al modo de producción solo después de un pago de prueba. Consulte [Stripe](https://nexcmp.com/es/docs/billing/stripe/). ## Activar las alertas de 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. ``` El asistente llama a `telegram_configure` y `telegram_test`. Scopes: `settings:write`, `secrets:write`. Consulte [Notificaciones de Telegram](https://nexcmp.com/es/docs/administration/telegram-notifications/). ## Buscar un cliente y añadir saldo {#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. ``` El asistente llama a `customers_search` y a `customer_get` (solo lectura), y después a `customer_adjust_balance` con `delta_cents` 1000 y un motivo. Esto requiere **siempre** su aprobación: la tarjeta de confirmación indica "changes a customer balance" y muestra el monto y el motivo que se registrarán en el registro de auditoría. Scopes: `admin:read`, `billing:write`. ## Exportar mi configuración {#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. ``` El asistente llama a `config_export`. Los secretos se sustituyen por referencias de `secret://`. Guarde el resultado como `nexcmp.yaml` y manténgalo bajo control de versiones. Consulte [Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/). Scope: `admin:read`. ## Escribir buenos prompts {#write-good-prompts} - Indique el objetivo y los datos concretos: nombres, precios, correos electrónicos. No pegue secretos. - Solicite primero una vista previa para cualquier acción que tenga costo o elimine datos. - Pida al asistente que "lea el valor actual antes de modificarlo". Las instrucciones integradas ya lo indican. - Si una respuesta parece incorrecta, pregunte "¿qué herramienta ejecutó y con qué argumentos?". Las tarjetas de herramientas en AI Chat muestran ambos. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El asistente indica que no tiene una herramienta para esa acción | El alcance para esa herramienta no está concedido o la acción está restringida para la IA | Compruebe [Admin API keys](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) o hágalo directamente en el panel de administración. | | Le solicita que pegue una contraseña | El modelo ignoró las instrucciones | Rechácelo; utilice el campo Secret o introduzca el valor en el panel de administración. | | Nada cambia después de solicitar "hazlo" | Los cambios están esperando su confirmación | Desplácese hasta la tarjeta de confirmación y pulse **Confirm**. | | Los planes se crearon con un precio imprevisto | Los costos o el margen indicados en el prompt eran incorrectos | Edite los planes en la página Plans o pida al asistente que recalcule los precios; los cambios de precio requieren confirmación. | --- # Lista de control de configuración {#setup-progress-checklist} > **Dónde encontrarlo:** Overview › Dashboard (`/`), en la tarjeta **Setup progress** superior. Las listas vacías en Plans, Customers, Zones, Payments e Infrastructure muestran la misma ayuda. ## Qué hace {#what-it-does} Una instalación nueva requiere diez elementos antes de que el primer cliente pueda realizar pedidos y pagos. La tarjeta **Setup progress** los comprueba a partir de la configuración real, muestra cuántos se han completado, indica el **siguiente paso** y enlaza a la página correspondiente. Si tiene conectada una fuente de IA, **Do it for me** abre el [asistente de IA](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/) con una solicitud preparada para ese paso. El asistente (y cualquier cliente de IA mediante [MCP](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/)) puede consultar la misma lista con la herramienta `setup_checklist`. ## Los diez pasos {#the-ten-steps} | # | Paso | Se considera completado cuando | Dónde configurarlo | |---|---|---|---| | 1 | Licencia activa | La licencia está activada para su dominio | System › Admin › License & updates (`/license`). Consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/). | | 2 | Conectar una fuente de infraestructura | CloudStack está conectado o se ha añadido al menos un clúster de Proxmox VE | Infrastructure › Cloud provider › Providers (`/infra/providers`). Consulte [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/) y [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). | | 3 | Crear una zona | Existe al menos una zona | Infrastructure › Datacenter › Zone (`/infra/zones`). Consulte [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). | | 4 | Plantillas de SO | Al menos una plantilla está habilitada | Services › Virtual Machines › Plans & pricing, pestaña Templates (`/vm/catalog?tab=templates`). Consulte [Plantillas de SO](https://nexcmp.com/es/docs/infrastructure/templates/). | | 5 | Crear planes | Al menos un plan está habilitado | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). Consulte [Planes y precios](https://nexcmp.com/es/docs/catalog/plans/). | | 6 | Configurar métodos de pago | Stripe, PayPal, criptomonedas o transferencia bancaria están configurados | Finance › Payment channels (`/payments`). Consulte [Payment channels](https://nexcmp.com/es/docs/billing/payment-channels/). | | 7 | Correo electrónico (SMTP) | El correo electrónico saliente está configurado | System › Settings › Email (`/settings/email`). Consulte [SMTP y plantillas de correo electrónico](https://nexcmp.com/es/docs/administration/smtp-and-emails/). | | 8 | Personalización de marca | Se ha subido un logotipo o se ha modificado el nombre de marca predeterminado | System › Settings › Brand (`/settings/branding`). Consulte [Personalización de marca](https://nexcmp.com/es/docs/customers/branding/). | | 9 | Términos y privacidad | Se ha completado al menos un texto legal | System › Settings › Legal (`/settings/legal`). Consulte [Páginas legales](https://nexcmp.com/es/docs/customers/legal/). | | 10 | Realizar un pedido de prueba | Existe al menos un pedido | Realice un pedido como cliente en el portal de clientes para comprobar que todo funciona de principio a fin; la tarjeta enlaza a la página Billing (`/billing`). | La tarjeta muestra `done/total` (por ejemplo, 6/10), una barra de progreso, el siguiente paso con **Open** y, cuando hay una fuente de IA conectada, **Do it for me**. Haga clic en un paso para ir a su página. Junto a cada paso, un enlace pequeño abre la página de documentación correspondiente; algunos pasos también muestran un detalle como "2 zone(s)". ![Tarjeta de progreso de configuración en Overview con tres de diez pasos completados y los botones Open y Do it for me](https://nexcmp.com/es/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## Uso {#use-it} 1. Abra Overview. La tarjeta se encuentra en la parte superior. Utilice la flecha para plegarla; el panel recordará su elección en el navegador. 2. Haga clic en **Open** para ir a la página del siguiente paso o haga clic en **Do it for me**. 3. Con **Do it for me**, el asistente se abre con una solicitud como «Sugiera una tabla de planes iniciales a partir de mis ofertas con un margen del 40 %, muéstreme la vista previa antes de crearla». Responda a sus preguntas y luego revise y confirme cada tarjeta con **Confirm**. Consulte [AI Chat en el panel de administración](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/). 4. Cuando se completan los diez pasos, la tarjeta desaparece. ### Listas vacías {#empty-lists} Cuando Plans, Customers, Zones, Payments o Infrastructure están vacíos, la página muestra un bloque **Next step** con una explicación, un botón para la acción, **Do it for me** y un enlace a la documentación para no encontrar nunca una tabla vacía. ![Página Plans vacía con una explicación del siguiente paso y el botón Do it for me](https://nexcmp.com/es/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## Pídalo con sus propias palabras {#ask-for-it-in-your-own-words} No necesita la tarjeta. En AI Chat o en cualquier cliente de IA conectado, puede preguntar: ```text Check my setup progress and take me through the open steps, one at a time. ``` Este es también el prompt de MCP `initial-setup`. El asistente llama a `setup_checklist`, explica por qué es importante cada paso pendiente, solicita la información que necesita y utiliza la herramienta correspondiente. Scopes necesarios: `admin:read` para leer la lista, más el scope del paso que desea completar. Consulte [Prompts de ejemplo](https://nexcmp.com/es/docs/configure-with-ai/example-prompts/). ## Verificación {#verify} 1. Después de completar un paso, el recuento de la tarjeta aumentará la próxima vez que se cargue Overview. 2. En el asistente, `setup_checklist` devuelve los mismos números, con `done: true` en el paso finalizado. ## Límites y notas {#limits-notes} - Las comprobaciones revisan lo que está guardado, no si funciona. Una pasarela configurada cuenta como completada incluso si su prueba falla. Utilice los botones **Test** de cada página y la herramienta `system_health` ante cualquier problema. - La tarjeta es solo para administradores. - **Do it for me** requiere una fuente de IA conectada en System › Settings › AI accounts; si no hay ninguna, solo se muestra **Open**. - Los diez pasos son los mismos para cada instalación; un paso que no tenga previsto utilizar (por ejemplo, pagos en una nube privada) seguirá contando como pendiente. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | No aparece la tarjeta | Se han completado los diez pasos o no se pudo cargar la tarjeta | Recargue Overview. Pregunte `setup_checklist` en AI Chat para consultar el estado. | | Un paso sigue pendiente después de haberlo completado | El guardado no se completó o aún no se cumple la condición (por ejemplo, existe una plantilla pero está deshabilitada) | Abra la página del paso y consulte la tabla anterior. | | Branding permanece abierto tras cambiar el logotipo | Branding cuenta cuando existe un logotipo o el nombre de marca difiere del predeterminado "NexCMP" | Suba un logotipo o configure su propio nombre. | | **Do it for me** no hace nada | Ninguna fuente de IA conectada, o es el panel de demostración | Conecte una fuente en cuentas de IA. | --- # SMTP y plantillas de correo {#smtp-and-e-mail-templates} > **Ubicación en el panel de administración:** System › Settings › Email (`/settings/email`) — pestañas **SMTP** y **Email templates**. Registro de entregas: Overview › Support › Sent emails (`/support/emails`). ## Qué hace {#what-it-does} NexCMP envía correos para la verificación de registro, restablecimiento de contraseña, "VM lista" (con la contraseña inicial), facturas, saldo bajo, renovaciones, recargas, respuestas de soporte y más. Todos se envían mediante **una cuenta SMTP que usted proporcione**. Los mensajes y plantillas están disponibles en 16 idiomas; se utiliza el idioma del cliente. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Servidor SMTP | Host, puerto y credenciales de cualquier proveedor (su propio servidor, Brevo, Amazon SES, Mailgun, Google Workspace…) | | Red | Conexión TCP saliente desde el servidor NexCMP hacia el host y puerto SMTP (587 STARTTLS, 465 TLS o 25) | | Dominio de remitente | Un dominio bajo su control, con **SPF y DKIM** publicados para el proveedor y un registro DMARC | | Permisos | La cuenta SMTP debe tener autorización para enviar con la dirección del campo **From** | ::: warning Entregabilidad Los correos electrónicos como "VM lista" contienen contraseñas. Si el SPF/DKIM/DMARC del dominio remitente no coincide con el proveedor SMTP, llegarán a spam. La página se lo recuerda. ::: ## Preparar el proveedor de correo electrónico {#prepare-the-e-mail-provider} 1. En el panel de su proveedor, añada y verifique su dominio de envío (por ejemplo, `example.com`). 2. Publique los registros DNS SPF, DKIM y DMARC que indique el proveedor. 3. Cree un usuario SMTP (o clave API-SMTP) y anote el host, puerto, nombre de usuario y contraseña. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › Email**, pestaña **SMTP**. 2. Complete el formulario: | Campo | Ejemplo | Notas | |---|---|---| | Host | `smtp.example.net` | Servidor SMTP | | Puerto | `587` | | | Security | STARTTLS (587) | Elija el modo que requiera su proveedor | | Username | `smtp-user` | | | Contraseña | (oculto) | Solo escritura: la página solo muestra si hay una configurada | | From email | `no-reply@example.com` | Debe estar autorizada en el proveedor | | From name | `Example Cloud` | Por defecto toma el nombre de su marca | | Reply-To (opcional) | `support@example.com` | Dirección a la que llegan las respuestas del cliente | ![La pestaña SMTP de Settings, Email con campos de host, puerto, seguridad, nombre de usuario, remitente y el botón Send test](https://nexcmp.com/es/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. Haga clic en **Save**, luego en **Send test** e ingrese su propia dirección. La configuración se guarda en un archivo con acceso restringido (`smtp.json`, modo 0600) y solo el worker en segundo plano `nexcmp-vmd` envía correos; el servicio web únicamente los pone en cola. ## Verificación {#verify} - El mensaje de prueba llega a la bandeja de entrada (revise también la carpeta de spam). En el código fuente del mensaje, confirme `dkim=pass` y `spf=pass`. - Abra **Support › Sent emails**: cada mensaje muestra un estado (en cola, enviado, fallido) y el resultado de la entrega. Los mensajes fallidos se reintentan hasta 3 veces. - Registre un cliente de prueba en el portal y confirme que llegue el correo de verificación. ## Editar plantillas de correo {#edit-e-mail-templates} La pestaña **Email templates** muestra cada plantilla por su clave, junto con los idiomas en los que está disponible (por ejemplo, `verify_email`, `reset_password`, `vm_ready`, `invoice_paid`, `low_balance`, `topup_received`, `ticket_reply`, `scale_up`…). 1. Haga clic en una plantilla y seleccione un idioma. 2. Edite el asunto y el cuerpo. Los marcadores de posición se completan cuando se pone en cola un mensaje. 3. Guarde. El cambio se aplica de forma **inmediata** a los mensajes que se pongan en cola a partir de ese momento. ![La pestaña Email templates con la lista de claves de plantilla y sus idiomas](https://nexcmp.com/es/docs/images/administration/smtp-and-emails-02-templates.webp) ## Límites y notas {#limits-and-notes} - Una cuenta SMTP por instalación. Los clientes de los revendedores reciben correos mediante la misma cuenta, a menos que el revendedor esté configurado de otro modo. - Se aplican los límites de envío del proveedor; NexCMP no limita la tasa de envío salvo por los reintentos. - Sin SMTP el panel funciona, pero los clientes no podrán completar la verificación de registro ni el restablecimiento de contraseña. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | El correo de prueba nunca llega | Credenciales incorrectas, puerto bloqueado o remitente no autorizado | Revise `journalctl -u nexcmp-vmd` para ver el error de SMTP; pruebe el puerto 587 con STARTTLS; verifique la dirección From en el proveedor. | | Los mensajes van a spam | SPF/DKIM/DMARC ausentes o desalineados | Publique los registros del proveedor y envíe desde ese dominio. | | "failed" en Sent emails | El proveedor rechazó el mensaje | Abra la fila para ver la respuesta del proveedor. | | El campo de contraseña aparece vacío tras guardar | Por diseño (solo escritura) | La etiqueta muestra "current: set" en cuanto se guarda una contraseña. | --- # Alertas de Telegram y de administración {#telegram-and-admin-alerts} > **Dónde encontrarlo en admin:** System › Settings › Admin alerts (`/settings/alerts`). Accesos rápidos de soporte: Customers › Support › Tickets (`/support/tickets`), pestaña **Settings**. ## Qué hace {#what-it-does} NexCMP le notifica a **usted** —el operador— cuando algo requiere atención, un cliente se registra o se acredita un depósito. Las alertas se envían a uno o más **canales**: Telegram, un webhook o correo electrónico. Los eventos enviados a los canales de administración incluyen: fallos de despliegue, VM faltantes, caídas de red, menos de 30 IP libres, elementos por vencer (aviso de 1 hora), disputas de Stripe, workers caídos, RAM del clúster sobre el umbral, nuevos registros y depósitos acreditados. Los eventos de clientes se ponen en cola de forma persistente y se reintentan con intervalos crecientes (de 30 segundos hasta 1 hora) hasta que Telegram los acepta. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Telegram | Un bot creado con **@BotFather** (token) y el **chat ID** del grupo o usuario que debe recibir los mensajes | | Red | Tráfico HTTPS saliente hacia `api.telegram.org` | | Webhook (alternativa) | Un endpoint HTTPS que acepte el payload de la alerta | ## Preparar Telegram {#prepare-telegram} 1. En Telegram, abra **@BotFather**, envíe `/newbot`, elija un nombre y copie el **bot token** (`123456789:AA...`). 2. Cree un grupo, añada el bot a este y envíe cualquier mensaje. 3. Obtenga el **chat ID**: abra `https://api.telegram.org/bot/getUpdates` en un navegador y lea `chat.id` (los ID de grupo comienzan con `-`). ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **System › Settings › Admin alerts**. 2. En **Add channel**, elija **Type: Telegram**, establezca **Destination** con el chat ID y **Secret (bot token)** con el token. Haga clic en **Add**. 3. Asegúrese de que la opción **Send admin Telegram (VM module)** esté activada; la línea *VM module status (read-only)* muestra "on". ![La página Admin alerts con el formulario Add channel configurado en Telegram](https://nexcmp.com/es/docs/images/administration/telegram-notifications-01-channel.webp) ## Verificación {#verify} El canal aparecerá bajo **Configured channels**. Provoque un evento (por ejemplo, registre un cliente de prueba) y el mensaje llegará al grupo. Si no hay ningún canal configurado, la página advertirá "Without a channel, attacks will go unnoticed" y, en el log, los eventos de Telegram solo se registrarán localmente. ## Accesos directos de soporte para clientes {#support-shortcuts-for-customers} El widget de soporte al cliente puede mostrar botones de **Telegram** y **Zalo**. Permanecen ocultos hasta que se configuran en los ajustes de soporte: introduzca un enlace `https://t.me/...` para Telegram y el enlace o código QR de Zalo. Solo se aceptan enlaces `https://`. El chat de soporte también puede notificar a su grupo de Telegram con la pregunta y un borrador de respuesta; consulte [AI Chat](https://nexcmp.com/es/docs/ai/ai-chat/). ## Límites y notas {#limits-and-notes} - El bot token se almacena con el canal y no se vuelve a mostrar. - Los eventos de Telegram utilizan el primer canal de Telegram habilitado que disponga tanto de destino como de token. ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | No llega ningún mensaje | Chat ID incorrecto, el bot no está en el grupo o nunca se le envió un mensaje | Vuelva a comprobar el ID con `getUpdates`; envíe primero un mensaje al bot o al grupo. | | Funciona durante un tiempo y luego se detiene | Token revocado en BotFather | Cree un nuevo token y actualice el canal. | | `Telegram: no channel` en los logs | Ningún canal de Telegram habilitado | Añada uno como se indicó anteriormente. | --- # Registro de auditoría y actividad {#audit-log-and-activity} > **Dónde encontrarlo en el admin:** System › Logs › Activity (`/logs`), Admin actions (`/logs/admin`), Console (`/logs/console`), Login (`/logs/logins`), VM events (`/logs/vm-events`); Overview › Support › Sent emails. NexCMP registra cada acción relevante. Utilice la página **Activity** como cronología unificada y las demás pestañas para filtrar. ## Pestañas {#tabs} | Pestaña | Contenido | |---|---| | **Activity** | Cronología unificada de todas las fuentes: acciones de admin, eventos de VM, inicios de sesión, afiliados y errores del sistema | | **Admin actions** | Cambios realizados por los administradores (por ejemplo, `customer.block`, `customer.delete`), junto con la IP del administrador | | **Console** | Inicios de sesión en la consola de administración y solicitudes del sistema como una petición de actualización | | **Login** | Inicios de sesión de clientes y accesos fallidos | | **VM events** | Pasos de despliegue, creación, contraseña, destrucción y otros eventos del ciclo de vida por máquina virtual | ## Lectura de una fila {#reading-a-row} Columnas: **Time**, **Source**, **Level**, **Actor** (quién), **Target**, **Services**, **Action** (código de evento como `customer.delete`) y **Details**. Haga clic en **Open** para ver el registro completo. ![La página Activity con los filtros de origen, sitio y servicio sobre la línea de tiempo](https://nexcmp.com/es/docs/images/administration/audit-log-01-activity.webp) ## Filtrar y buscar {#filter-and-search} 1. Seleccione un **source**, **site** y **service** en los menús desplegables. 2. Establezca un rango de **From date** / **To date**. 3. Escriba un código de evento (por ejemplo, `customer.block` o `destroy`) en el cuadro de búsqueda — la búsqueda de actividad busca coincidencias por código de evento. ## Retención y exportaciones {#retention-and-exports} Los registros residen en las bases de datos de NexCMP en `/var/lib/nexcmp` y se incluyen en los [backups](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). La retención depende del registro: los intentos de inicio de sesión de clientes con más de 180 días y los registros de solicitudes con API keys de clientes con más de 60 días se depuran. La auditoría de API keys de administradores conserva hasta unos 200,000 registros recientes. Estos límites no implican la misma retención para el cronograma de actividad unificado. ## Usos habituales {#common-uses} | Pregunta | Dónde buscar | |---|---| | ¿Quién suspendió a este cliente? | Admin actions, busque `customer.block` | | ¿Por qué desapareció una VM? | VM events, filtre por el ID de la VM; también en Activity | | ¿Recibió el cliente el correo electrónico? | Overview › Support › Sent emails | | ¿Cuándo se solicitó la última actualización? | Pestaña Console | --- # Security {#security} > **Ubicación en el admin:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`). ## Consola de administración {#admin-console} ### Autenticación de dos factores (TOTP) {#two-factor-authentication-totp} La consola es accesible desde Internet, así que active TOTP. 1. Abra **System › Admin › Console security**. 2. En **Two-factor authentication (TOTP)**, haga clic en **Start setup**. 3. Escanee el código QR con Google Authenticator, Authy, 1Password o Bitwarden y, a continuación, introduzca el código de 6 dígitos. ### Rangos de IP permitidos para la consola {#allowed-console-ip-ranges} En **Allowed console IP ranges**, introduzca una IP o CIDR (IPv4 o IPv6) por línea. **Dejarlo vacío permite el acceso desde cualquier lugar.** Fuera del rango, se bloquean tanto el inicio de sesión como la admin API. ::: warning Evite perder el acceso La página muestra su IP actual y requiere que la nueva lista la incluya. Utilice **+ Add my IP**. Si a pesar de ello pierde el acceso, utilice el [acceso de emergencia](https://nexcmp.com/es/docs/getting-started/cli-reference/#emergency-access) desde el servidor. ::: ### Cambiar contraseña {#change-password} Complete **Current password**, **New password** y **Confirm new password**. Utilice una contraseña larga y única (de 12 caracteres o más; el asistente de configuración exige 12 para el primer administrador). ### Cuentas y roles de administrador {#administrator-accounts-and-roles} Abra **System › Admin › Admin users** y utilice **+ Create account**. | Rol | Acceso | |---|---| | `admin` | Acceso total a la admin API | | `staff` | Solo lectura en todo el sistema | | `user` | Vista de solo lectura de los recursos de un cliente | La cuenta root es la creada en el [asistente de configuración](https://nexcmp.com/es/docs/getting-started/setup-wizard/). Acciones de fila: **Edit**, **Reset PW**, **Key**, **Delete**. Las contraseñas se almacenan como hashes con salt; modificar o bloquear una cuenta cierra sus sesiones de inmediato. ## Inicio de sesión de clientes {#customer-sign-in} Abra **System › Settings › Customer logins**. | Ajuste | Qué hace | |---|---| | **Google sign-in** | Habilite y luego introduzca el client ID y el secret de OAuth. Copie la **Callback URL** que se muestra en la página en *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. Utilice **Test configuration**. | | **Inicio de sesión con GitHub** | Igual, con *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **Passkey** | Inicio de sesión mediante huella dactilar, PIN o llave de hardware; activado por defecto. Las passkeys están vinculadas al dominio; el dominio de cada revendedor funciona por separado. Introduzca un dominio anterior en *Legacy passkey Domain* tras un cambio de marca para que los clientes reciban una sugerencia útil | | **Reautenticar al añadir métodos de inicio de sesión** | Solicita de nuevo la contraseña antes de añadir una passkey o vincular Google/GitHub (desactivado por defecto) | | **Captcha** | Cloudflare Turnstile o Google reCAPTCHA en el registro: habilite, elija el proveedor e introduzca la site key y la secret key | | **Bloquear dominios de correo electrónico** | Un dominio por línea (máx. 2000). Las direcciones que coincidan se rechazan en el registro con `email_domain_blocked` | ![La página Customer logins que muestra el inicio de sesión con Google y su Callback URL](https://nexcmp.com/es/docs/images/administration/security-01-customer-logins.webp) ### Políticas integradas {#built-in-policies} | Política | Valor | |---|---| | Contraseña del cliente | Al menos 10 caracteres, letras y dígitos | | Sesión del cliente | 30 días; las sesiones de "login as customer" duran 1 hora | | Verificación de correo electrónico | Obligatorio antes de crear una VM cuando *require e-mail verified* está activado en los ajustes de ventas | | Anti-carding | Las cuentas con menos de la recarga mínima solo pueden crear un número limitado de VM | ## Fortalecimiento del servidor {#server-hardening} - El puerto 3000 se cierra tras la configuración y TLS; consulte [Instalación](https://nexcmp.com/es/docs/getting-started/installation/#the-panel-port-3000). - El servicio se ejecuta como el usuario sin privilegios `nexcmp` con un sandbox de systemd restringido. - Las claves de API, las credenciales de pago y las contraseñas SMTP se almacenan cifradas; la clave maestra está en `/var/lib/nexcmp/secrets` — proteja los [backups](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). - Las versiones se verifican con SHA-256 y una firma Ed25519 antes de la instalación. --- # Configuración general {#general-settings} > **Ubicación en el panel de administración:** System › Settings › General (`/settings`). Los cambios surten efecto de inmediato (caché de 30 segundos). La página tiene tres secciones. ## Branding y URL {#branding-urls} | Campo | Propósito | |---|---| | Nombre de marca (correo electrónico, facturas) | Se muestra en correos electrónicos y facturas. El logotipo y los colores se encuentran en [Branding](https://nexcmp.com/es/docs/customers/branding/) | | Idioma predeterminado | Idioma para nuevos visitantes | | URL de la aplicación de clientes | Dirección pública del portal, por ejemplo `https://cloud.example.com` | | URL de la consola | Dirección del servicio de consola de VM | | URL de administración | Enlace utilizado al "iniciar sesión como" cliente de un revendedor | | URL de la consola de partners | Se utiliza en enlaces de invitación, correos electrónicos de revendedores y en la redirección tras una recarga | El asistente los completa a partir de su dominio; cámbielos solo si traslada el portal. ## Vendedor y facturación {#seller-invoicing} Aparece impreso en cada factura: | Campo | Ejemplo | |---|---| | Razón social | Example Cloud Ltd | | Identificación fiscal | `TAX-000000` | | Dirección | 1 Example Street, New York | | Correo electrónico de contacto | `billing@example.com` | | Prefijo del número de factura | `INV` (1–8 caracteres, A–Z y 0–9) | Las facturas emitidas conservan los datos del vendedor y el número con los que se generaron; los cambios solo afectan a las **nuevas** facturas. ## Mantenimiento y región {#maintenance-region} Active **Customer app MAINTENANCE** para mostrar un banner y **bloquear todas las acciones de escritura de los clientes** mientras la consola de administración sigue funcionando. Introduzca el **Maintenance message** que verán los clientes. Utilice esto durante las actualizaciones de su infraestructura. ![Página de configuración General con nombre de marca, idioma predeterminado y campos de URL](https://nexcmp.com/es/docs/images/administration/general-settings-01-general.webp) ## Otras páginas de configuración {#other-settings-pages} | Página | Guía | |---|---| | Brand | [Personalización de marca](https://nexcmp.com/es/docs/customers/branding/) | | Legal | [Legal](https://nexcmp.com/es/docs/customers/legal/) | | Customer logins | [Security](https://nexcmp.com/es/docs/administration/security/) | | Email | [SMTP y plantillas de correo electrónico](https://nexcmp.com/es/docs/administration/smtp-and-emails/) | | Admin alerts | [Telegram y alertas de administración](https://nexcmp.com/es/docs/administration/telegram-notifications/) | | Proveedor de IA | [Proveedores de IA](https://nexcmp.com/es/docs/ai/ai-providers/) | --- # Reportar un error {#report-a-bug} > **Ubicación en el admin:** Top bar › **Report a bug** (junto a Docs; visible solo para el administrador principal). ¿Encontró un defecto en NexCMP? Presione **Report a bug**, describa el problema y envíelo. El reporte llega al equipo de NexCMP como un ticket en su cuenta de licencia en un solo paso — sin necesidad de iniciar sesión en otro lugar ni de copiar archivos de registro a mano. Todos los planes pueden usarlo: NexCMP Free cubre correcciones de errores, al igual que NexCMP Source. ::: info Los reportes de errores no son solicitudes de soporte NexCMP Free no incluye soporte técnico, por lo que debe usar este formulario para defectos en el software. La ayuda con la configuración y las migraciones forman parte de [NexCMP Source](https://nexcmp.com/pricing). ::: ## Requisitos {#requirements} | Elemento | Requisitos | |---|---| | Versión | NexCMP 1.5.2 o posterior | | Quién puede enviar | La cuenta del administrador principal. Las cuentas de personal (solo lectura), las consolas de revendedor, los clientes y la demo de solo lectura no pueden enviar | | Licencia | Una licencia activada (Free o Source) que no esté suspendida | | Red | El servidor debe poder acceder a `https://nexcmp.com` mediante HTTPS (la misma dirección que utiliza para verificar licencias y actualizaciones) | ## Enviar un reporte {#send-a-report} 1. Haga clic en **Report a bug** en la barra superior. En un teléfono, abra el menú y elija **Report a bug**. 2. Introduzca un **Subject** breve. 3. En **What happened**, describa qué hizo, qué vio y qué esperaba. 4. De forma opcional, indique los **pasos para reproducir el problema**. 5. Elija el **Impact**: **Blocking** (no puede trabajar), **Major** (una función principal no funciona) o **Minor** (un problema menor o cosmético). 6. Deje activada la opción **Attach diagnostics** (recomendado) y revise el cuadro **What will be sent**. 7. Haga clic en **Send report**. En 1.6.1 el cuerpo del formulario permite desplazamiento mientras los botones de acción permanecen visibles, incluso en un teléfono. Los valores de contraseña que siguen a `password:` o `password=` se enmascaran sin eliminar el resto del informe. Revise su texto antes de enviarlo y omita credenciales y datos de clientes. ![El cuadro de diálogo Report a bug con el título, la descripción, el impacto y la lista de lo que se enviará](https://nexcmp.com/es/docs/images/administration/report-a-bug-01-dialog.webp) Cuando se acepta el reporte, el cuadro de diálogo muestra el número de ticket y un enlace. Las respuestas, si el equipo envía alguna, se dirigen a la dirección de correo electrónico de su cuenta de licencia en nexcmp.com, y el ticket también aparece en **Support** cuando inicia sesión allí como titular de la licencia. ## Qué se envía {#what-is-sent} El cuadro **What will be sent** muestra exactamente esto antes de hacer clic en Send: | Enviado | Detalles | |---|---| | Su texto | Título, descripción, pasos e impacto | | Versión, plan, dominio | Su versión de NexCMP, Free o Source, y el dominio de la instalación | | Página actual | La página del admin en la que se encuentra, sin nada después de `?` ni de `#` | | Navegador | El texto del user-agent de su navegador (nombre, versión y sistema operativo), truncado a 200 caracteres | | Errores recientes | Hasta los últimos 5 errores en esta pestaña del navegador. En errores de script solo se envía el mensaje; en solicitudes fallidas, únicamente el método, la ruta y el código de estado | Puede desactivar **Attach diagnostics**; en ese caso, solo se enviarán su propio texto y la versión, el plan y el dominio. ## Qué nunca se envía {#what-is-never-sent} - Contraseñas, tokens, cookies y claves de API. Cualquier elemento que parezca uno de ellos en su texto o en un mensaje de error se enmascara (se muestra como `***` o `[redacted]`) en su servidor antes de enviar nada. - El contenido de las solicitudes y respuestas — las solicitudes fallidas solo se registran con método, ruta y estado. - Los datos de sus clientes (nombres, correos electrónicos, pedidos, facturas) y sus direcciones IP. - La dirección IP de su navegador y cualquier archivo de su servidor. Como en cada comprobación de licencia, el servidor de licencias ve la dirección IP desde la que se conecta su servidor. El ticket queda vinculado a su instalación mediante el token de licencia que el servidor ya posee, por lo que la versión, el dominio y la instalación los define el servidor y no pueden modificarse desde el navegador. ## Límites {#limits} | Límite | Valor | |---|---| | Asunto | 150 caracteres | | Descripción más pasos | 8 KB en total | | Informes | 5 por hora y 20 por día para toda la instalación | Enviar el mismo informe dos veces (por ejemplo, tras un error de red) no crea un segundo ticket. ## Resolución de problemas {#troubleshooting} | Mensaje | Causa | Solución | |---|---|---| | Active su licencia primero | La instalación no tiene una licencia activada | Abra **License & updates** y active, luego vuelva a enviar | | No se pudo conectar con el servidor de licencias | El servidor no puede conectarse a `nexcmp.com` | Compruebe el HTTPS y DNS de salida desde el servidor, luego presione **Send report** de nuevo — se conserva su texto | | Demasiados informes de errores desde esta instalación | Ha alcanzado 5 por hora o 20 por día | Espere e inténtelo de nuevo; en su lugar, agregue los nuevos hallazgos al ticket abierto | | Esta licencia está suspendida | La licencia está suspendida o reembolsada | Consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/) | | Esta instalación fue revocada | La instalación se revocó en el portal de licencias | Actívela de nuevo desde **License & updates** | | No se pudo actualizar el token de licencia | El servidor no pudo renovar su token de licencia | Abra **License & updates**, presione **Refresh** y luego vuelva a enviar | | No aparece el botón Report a bug | Ha iniciado sesión con una cuenta de personal, distribuidor o cliente, o en la demo de solo lectura | Inicie sesión como administrador principal | ::: tip Para el asistente de IA y las claves API El asistente en el panel de administración y las claves API de administrador no pueden enviar informes de errores en su nombre: el botón requiere que una persona haya iniciado sesión como administrador principal. ::: --- # Errores de instalación {#installation-errors} El instalador se detiene ante el primer problema fatal y muestra una línea roja que empieza por `✗`. Corrija la causa y **vuelva a ejecutar el mismo comando**; el instalador se puede repetir sin peligro. Las líneas informativas empiezan por `•` y los pasos correctos, por `✓`. ## Comprobaciones de la máquina {#machine-checks} | Mensaje | Causa | Solución | |---|---|---| | `must be run as root (sudo)` | No se ejecuta como root | Anteponga `sudo` al comando o ejecútelo como root. | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | Otra distribución o versión | Utilice un servidor Ubuntu 22.04 o 24.04. | | `only x86_64 is supported` | ARM u otra CPU | Utilice un servidor x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | Memoria insuficiente | Añada RAM. | | `requires ≥ 8 GB free disk space on / (… GB available)` | Sistema de archivos raíz casi lleno | Libere espacio o amplíe `/`. | | `missing --license` / `missing --domain` | Primera instalación sin esos parámetros | Indique ambos; consulte [Instalación](https://nexcmp.com/es/docs/getting-started/installation/#parameters). | | `unknown argument: …` | Error tipográfico en un parámetro | Revise que esté bien escrito; ejecute con `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | El gestor de paquetes está bloqueado | Espere unos minutos (una instalación nueva de Ubuntu ejecuta actualizaciones automáticas tras el arranque) y vuelva a ejecutarlo. | | `… is a symlink — aborting` | `/opt/nexcmp` o `/etc/nexcmp` es un enlace simbólico | Reemplácelo por un directorio real — el instalador rechaza los enlaces simbólicos por seguridad. | ## Activación de la licencia {#license-activation} | Mensaje | Causa | Solución | |---|---|---| | `cannot connect to https://nexcmp.com` | Sin conexión HTTPS saliente hacia el servidor de licencias | Compruebe el DNS, el firewall y el proxy en el servidor: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | El servidor de licencias rechazó la clave | Revise el mensaje: clave incorrecta, el dominio no coincide con la licencia o la licencia está suspendida o revocada. Compruebe la página de licencias en [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | La licencia no tiene una versión descargable | Póngase en contacto con ventas; consulte [Soporte](https://nexcmp.com/es/docs/troubleshooting/support/). | ## Descarga y verificación {#download-and-verification} | Mensaje | Causa | Solución | |---|---|---| | `failed to download release X` | Problema de red durante la descarga | Vuelva a ejecutarlo. | | `sha256 mismatch (… ≠ …)` | El archivo llegó dañado o fue modificado | Vuelva a ejecutarlo; si se repite, es posible que un proxy esté reescribiendo las descargas — pruebe desde otra red. | | `release X is unsigned — refusing to install` | El servidor no proporcionó ninguna firma | Nunca lo omita; póngase en contacto con soporte técnico. | | `INVALID SIGNATURE for version X — aborting` | La firma Ed25519 no se verifica | **No** lo instale. Póngase en contacto con soporte técnico — esto significa que el archivo no es una versión oficial. | | `openssl failed to read public key` | Versión de OpenSSL muy antigua o dañada | Actualice el paquete `openssl`. | | `invalid version: …` | Datos inesperados del servidor | Vuelva a ejecutarlo; póngase en contacto con soporte técnico si el problema persiste. | ## Inicio del servicio {#service-start} | Mensaje | Causa | Solución | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | El panel no respondió a `/healthz` en 3 minutos | Revise el journal. Causas habituales: el puerto (por defecto 3000) ya está en uso (`ss -ltnp | grep 3000`) — vuelva a instalar con `--port`; archivos propiedad de root en `/var/lib/nexcmp` — ejecute `sudo nexcmp fix-owner`. | ## nginx y TLS {#nginx-and-tls} | Mensaje | Causa | Solución | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | El registro A/AAAA falta o es incorrecto | Consulte [DNS y Cloudflare](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/) y vuelva a ejecutarlo. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Falló la validación de Let's Encrypt (puerto 80 bloqueado, DNS no propagado, límite de tasa) | Abra el puerto 80, espere a la propagación del DNS y vuelva a ejecutarlo. Revise `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | Fallo temporal en la renovación | Inofensivo; vuelva a ejecutarlo más tarde. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Otro sitio de nginx entra en conflicto (mismo `server_name`, configuración duplicada) | Ejecute `sudo nginx -t` y corrija el conflicto; luego vuelva a ejecutarlo. | | `apt-get could not install nginx` / `certbot` o `E: Failed to fetch … 404 Not Found` | El gestor de paquetes está bloqueado o el índice de paquetes del servidor está desactualizado (típico en una imagen de plantilla que no se ha actualizado desde hace tiempo) | Ejecute `sudo apt-get update`, espere a que finalice cualquier otro proceso de apt y luego vuelva a ejecutar el instalador. | | `openssl could not create the self-signed certificate` | Problema con OpenSSL | Actualice `openssl` y vuelva a ejecutarlo. | ## Tras la instalación {#after-installation} | Síntoma | Causa | Solución | |---|---|---| | El navegador no puede abrir `https://` | El DNS o TLS no están listos | `sudo nexcmp status`; use el [acceso de emergencia](https://nexcmp.com/es/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | Modo SSL **Flexible** de Cloudflare | Establezca **Full (strict)** — [detalles](https://nexcmp.com/es/docs/getting-started/dns-and-cloudflare/). | | El asistente indica que el «setup code» es incorrecto | Error tipográfico o un código de una instalación anterior | Ejecute `sudo nexcmp status` y copie el código actual. | | La licencia muestra HTTP 421 | Archivos en `/var/lib/nexcmp` propiedad de root | `sudo nexcmp fix-owner` y luego `sudo systemctl restart nexcmp`. | --- # Errores de actualización {#update-errors} > **Ubicación en el panel de administración:** System › Admin › License & updates (`/license`) Las actualizaciones se describen en [Actualización de NexCMP](https://nexcmp.com/es/docs/getting-started/updating/). Cuando la tarjeta Update o `sudo nexcmp update` muestre un error: | Mensaje | Causa | Solución | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | Su fecha «updates until» es anterior a la fecha de lanzamiento. Las correcciones de seguridad se siguen entregando; las versiones de funciones, no | Renueve en [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 al año para NexCMP Free) y vuelva a comprobar. Mientras tanto, el software sigue funcionando. | | `sha256 mismatch (downloaded …, expected …)` | Descarga dañada o alterada | Reinténtelo. Si se repite, revise los proxies en la ruta. | | `downgrade/same version rejected: X is not newer than Y` | La versión seleccionada no es más reciente que la que está en ejecución | No es necesario hacer nada: el sistema está actualizado. | | `extraction failed / main binary missing` | Archivo dañado o disco lleno | Compruebe `df -h`; reinténtelo. | | `systemctl restart failed` | El servicio no pudo reiniciarse tras sustituir el binario | `journalctl -u nexcmp -n 80`; el binario anterior se conserva como `/opt/nexcmp/bin/nexcmp.bak` — consulte cómo revertir más abajo. | | Error del servidor al contactar con el servidor de actualizaciones | No hay ruta hacia `nexcmp.com` o el token de licencia ha caducado | Compruebe el tráfico HTTPS saliente; haga clic en **Check now** en la tarjeta License. | ## Revertir {#roll-back} Si una nueva versión no funciona correctamente: ```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 ``` Si ya se ejecutó una migración de base de datos, restaure también la [copia de seguridad](https://nexcmp.com/es/docs/getting-started/backup-and-restore/) realizada antes de la actualización. ## `sudo nexcmp update` indica que no puede encontrar el instalador {#sudo-nexcmp-update-says-it-cannot-find-the-installer} `nexcmp update` ejecuta el instalador incluido dentro de la versión instalada (`/opt/nexcmp/releases//share/install.sh`). Si falta ese archivo, vuelva a ejecutar el comando de instalación desde su página de licencia. --- # Preguntas frecuentes {#faq} ## Licencias {#licensing} **¿Qué ocurre si mi licencia caduca o el servidor pierde el acceso a Internet?** El token sigue siendo válido durante 14 días y se renueva a diario. Después de eso, los clientes no pueden crear **nuevos** servicios; los servicios en ejecución, la facturación y los inicios de sesión continúan funcionando. Consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/). **¿Sigo recibiendo correcciones de seguridad tras finalizar mis derechos de actualización?** Sí: las versiones de seguridad siempre se entregan; las versiones con nuevas funciones requieren derechos activos. **¿Puedo ejecutar NexCMP en un segundo servidor o dominio?** Actívelo con la clave y el dominio registrados en la licencia; consulte [Licencia y compra](https://nexcmp.com/es/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## Instalación {#installation} **¿Necesita NexCMP Docker, PostgreSQL o Redis?** No. Es un único programa con bases de datos SQLite, ejecutado mediante systemd como usuario sin privilegios. Consulte [Requisitos](https://nexcmp.com/es/docs/getting-started/requirements/). **¿Puedo instalarlo sin un dominio público?** Sí, utilice `--no-nginx` y un túnel SSH; consulte [Instalación](https://nexcmp.com/es/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **¿Por qué está cerrado el puerto 3000 tras la configuración?** Por seguridad, el panel escucha en `127.0.0.1` una vez finalizado el asistente y activado TLS. Utilice `sudo nexcmp open-port` para emergencias. ## Infraestructura {#infrastructure} **¿Puedo utilizar CloudStack y Proxmox VE juntos?** Sí. Una zona puede tener ambos; cada plan elige su origen. Consulte [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/) y [Zonas](https://nexcmp.com/es/docs/infrastructure/zones/). **¿Necesito la clave API de ROOT de CloudStack?** No — y no debería utilizarla. Cree una cuenta dedicada — [CloudStack](https://nexcmp.com/es/docs/infrastructure/cloudstack/). **¿Por qué no aparecen algunas pestañas o botones en una máquina virtual?** Las páginas solo muestran lo que admite el origen de la máquina virtual (por ejemplo, Proxmox VE no tiene reenvío de puertos). Consulte la tabla de funcionalidades en [Proxmox VE](https://nexcmp.com/es/docs/infrastructure/proxmox/). ## Operaciones {#operations} **¿Cómo muevo NexCMP a otro servidor?** Haga una copia de seguridad, instale la misma versión en el nuevo servidor con la misma licencia, restaure — consulte [Copia de seguridad y restauración](https://nexcmp.com/es/docs/getting-started/backup-and-restore/). **¿Dónde están los registros?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp` y la consola de administración en System › Logs. Consulte [Registro de auditoría](https://nexcmp.com/es/docs/administration/audit-log/). **¿Puedo ver el portal del cliente antes de instalar?** Sí. Las páginas de servicios en [nexcmp.com](https://nexcmp.com/platform/) muestran el portal del cliente pestaña por pestaña con datos de ejemplo; abra *View demo* para el visor a pantalla completa. Para ver una instalación real, escriba a ventas. --- # Soporte {#support} ## Contacto {#contact} No hay formulario de contacto. Envíe un correo electrónico a **sales@nexcmp.com** — cubre licencias, renovaciones, dominios y consultas técnicas. Su página de licencias en [nexcmp.com/licenses](https://nexcmp.com/licenses) también enlaza a la misma dirección. ## Antes de escribir {#before-you-write} 1. Busque en esta documentación (presione `/`) y consulte [Errores de instalación](https://nexcmp.com/es/docs/troubleshooting/installation-errors/) y [Errores de actualización](https://nexcmp.com/es/docs/troubleshooting/update-errors/). 2. Recopile los datos que figuran a continuación — permitirán al equipo de soporte responder en un solo mensaje. ## Qué incluir {#what-to-include} | Elemento | Cómo obtenerlo | |---|---| | Versión de NexCMP | `sudo nexcmp status` o System › Admin › License & updates | | Dominio principal y los últimos 4 caracteres de la clave de licencia | License & updates (nunca envíe la clave completa) | | Qué hizo y qué esperaba | Pasos exactos | | El texto del error o una captura de pantalla | Oculte los datos confidenciales antes de enviar | | Estado del servicio | `sudo nexcmp status` | | Líneas de registro recientes | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | Infraestructura | Versión de CloudStack o Proxmox VE, una zona o varias | ::: warning Nunca envíe datos confidenciales No envíe claves de licencia, claves API, contraseñas, el código de configuración, credenciales de pago ni archivos de copia de seguridad. Enmascárelos en registros y capturas de pantalla. ::: ## Reportes de seguridad {#security-reports} Si cree haber encontrado una vulnerabilidad, envíe un correo electrónico a la misma dirección con "Security" en el asunto y evite publicar detalles de forma pública hasta que se haya solucionado.