Configuración como código

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 <tool>.

Qué hace

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

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 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); nunca dentro del archivo.

Exportar, editar, previsualizar, aplicar

1. Exporte la configuración actual:

   sudo nexcmp config export -o nexcmp.yaml

   Sin -o, el YAML se muestra en pantalla.

2. Edite nexcmp.yaml (consulte el ejemplo a continuación). Mantenga version: 1 en la parte superior.

3. Previsualice qué cambiaría. Esto no modifica nada:

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

   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 <file>	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 <name>	Aplica únicamente esta sección. Repita la opción para varias.
-o <file>	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

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:

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

# 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

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.
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. 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.
modules	Módulos opcionales activados o desactivados (key: true/false).	Solo las claves que el panel permite cambiar. Consulte Módulos.
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.
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.
quotas	Límites de quota_*.	Consulte Cuotas.
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.
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.
ai_provider	El proveedor de IA del panel utilizado por AI Chat y AI Agent de los clientes.	AI provider.
legal	Texto de términos y privacidad por idioma (en, vi).	Páginas legales.

El orden de aplicación es el indicado arriba: los elementos relacionados con la infraestructura van antes que los planes.

Reglas para recordar

• 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

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

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.

Ejecutar cualquier herramienta desde la línea de comandos

nexcmp admin ejecuta las mismas herramientas que los asistentes de IA (la lista de herramientas) y muestra JSON:

sudo nexcmp admin tools                       # name, scope and title of every tool
sudo nexcmp admin system_health
sudo nexcmp admin customers_search q=customer@example.com
sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}'

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

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

• El archivo cubre las configuraciones anteriores, no clientes, servidores, facturas ni fuentes de infraestructura (conexiones de CloudStack y Proxmox). Conéctelas con AI Chat 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

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_<NAME>, 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.