Avanzado

cipi api

Cipi puede habilitar opcionalmente una capa REST API en el servidor a través de cipi api <domain>. Está impulsado por el paquete Laravel cipi/api (versión actual 1.20), que expone:

• DESCANSO API — aplicaciones (incluidas Octane crear, .env, auth.json, Artisan, incluido en la lista blanca app run, implementar-config), alias, www redirecciones, implementación, SSL, bases de datos multimotor, registros de aplicaciones, estado del servidor (/api/*)
• MCP servidor — Más de 50 herramientas en /mcp(Transmitible HTTP)
• Cabina de servidor — PHP instalación/cambio, claves SSH, servicios, SMTP, comprobaciones de estado, Lista blanca de IP (API 1.15.0+ / Cipi 5.0.6+)
• Interfaz de usuario arrogante — referencia interactiva en /docs

Requiere PHP 8.2+ y Laravel 12+ en el host del panel. esto es nivel de servidor automatización: distinta de la aplicación por aplicación Cipi Agente paquete (cipi/agent en cada aplicación Laravel).

el cipi/api paquete

En un servidor Cipi normal, nunca instalas el paquete manualmente. cipi api <domain> disposiciones Laravel en /opt/cipi/api, Nginx, SSL, cola de trabajos SQLite y cipi-queue.service. Para referencia o configuraciones personalizadas:

$ composer require cipi/api
$ php artisan vendor:publish --tag=cipi-config
$ php artisan vendor:publish --tag=cipi-assets
$ php artisan migrate
$ php artisan cipi:seed-api-user
$ php artisan cipi:token-create

panel .env usos CIPI_APPS_JSON=/etc/cipi/apps.json (o apps-public.jsonproyección para campos no sensibles). Las habilidades de los tokens se definen en config/cipi.php - enumerarlos con php artisan cipi:token-abilities (lo mismo enumerar como cipi api token create desde Cipi 4.6.3).

Fuente y registro de cambios: github.com/cipi-sh/api (MIT). Envoltorio de cliente: cipi-cli.

Comandos

$ cipi api <domain>           # configure API at root (e.g. api.myhosting.com)
$ cipi api ssl                  # install Let's Encrypt certificate for API domain
$ cipi api token list           # list tokens
$ cipi api token create         # create a new token (choose abilities)
$ cipi api token revoke <id>    # revoke a token
$ cipi api status               # Laravel + cipi-api versions, queue worker, pending jobs, FPM pool
$ cipi api fix-permissions      # repair panel storage/database ownership (www-data)
$ cipi api update               # soft update: composer update on Laravel and API packages
$ cipi api upgrade              # full rebuild with rollback at /opt/cipi/api.old

Solución de problemas del panel API

después cipi self-update, archivos de propiedad raíz en /opt/cipi/api o /opt/cipi/gui puede prevenir PHP-FPM (www-data) de escribir registros o el Base de datos de trabajos SQLite: el navegador muestra una base de datos básica HTTP 500 en /docs o /mcp. Cipi normalmente repara la propiedad automáticamente durante la actualización automática (migración 5.0.13+ reclama la propiedad API/GUI); si los problemas persisten:

$ cipi api fix-permissions   # chown storage, database, bootstrap/cache, .env → www-data
$ cipi api status              # confirm Laravel version, queue worker, pending jobs

cipi api status imprime el Laravel instalado y cipi/api versiones de paquetes, si cipi-queue.service está activo, trabajos asíncronos pendientes en la base de datos SQLite del panel, y estadísticas del grupo PHP-FPM para el vhost API (incluidas las solicitudes lentas cuando se configuran). cipi api update actualiza suavemente el paquete del panel API de Packagist (ya que 5.0.15; la migración elimina las entradas obsoletas del repositorio VCS). cipi api upgrade realiza una reconstrucción completa con reversión en /opt/cipi/api.old. desde 5.0.14–5.0.17, la actualización automática utiliza archivos comprimidos GitHub cronometrados y Packagist dist se instala en lugar de bloquear Composer clones de VCS para los paquetes API y GUI. desde 5.0.18, GUI actualización/actualización evita Composer enlaces simbólicos que rompen PHP-FPM open_basedir (HTTP 500); correr cipi gui fix-permissions o cipi self-update para reparar paneles existentes.

desde v4.7.18 (migraciones 4.7.15–4.7.18), Fallas del panel API en Ubuntu 25.10+ / 26.04 se corrigen de un extremo a otro: sudo-rs rechaza cipi db restore * * comodines (se ignoró todo el archivo sudoers - Me temo que no puedo hacer eso), por lo que la lista blanca utiliza el seguimiento * solamente; abastecimiento common.sh ya no cancela los comandos de solo lectura cuando /etc/cipi se vuelve a montar como de sólo lectura; API open_basedir incluye /usr/local/bin/ para ayudantes de registro; y cipi db list muestra bases de datos vacías y superficies vault/MariaDB errores. correr cipi self-update para aplicar.

Creación de tokens y permisos granulares

Usos de autenticación Santuario. Cada token puede tener uno o más habilidades eso limitar las operaciones permitidas:

• apps-view — leer aplicaciones
• apps-create - crear aplicaciones
• apps-edit — editar aplicaciones (PHP, repositorio, rama, dominio principal desde API 1.9.0+ / Cipi 4.6.2+)
• apps-suspend — suspender y reactivar aplicaciones
• apps-basicauth — habilitar, deshabilitar e inspeccionar HTTP Autenticación básica en aplicaciones (API 1.10.0+)
• apps-env — listar/combinar aplicaciones .env teclas (API 1.14.0+ / Cipi 5.0.3+)
• apps-auth — gestionar Composer compartido auth.json (API 1.14.0+; distinto de apps-basicauth)
• apps-artisan — ejecute Artisan como un trabajo asíncrono (API 1.14.0+)
• apps-run — incluido en la lista blanca no interactivo app run (API 1.14.0+)
• apps-deploy-config — opciones estructuradas de recetas de Deployer (API 1.14.0+)
• php-view — lista de versiones instaladas PHP (API 1.15.0+)
• php-manage — instalar/eliminar PHP, establecer el sistema predeterminado (API 1.15.0+ / 1.17.0+ para PUT /api/php/default)
• ssh-view — enumerar las claves SSH en el cipi usuario (API1.15.0+)
• ssh-manage — agregar/eliminar/cambiar el nombre de las claves SSH (API 1.15.0+)
• services-view — enumerar los servicios del sistema (API 1.15.0+)
• services-manage — reiniciar servicios (API 1.15.0+)
• smtp-view — leer la configuración de notificación SMTP (la contraseña nunca se devolvió; API 1.15.0+)
• smtp-manage — configurar, habilitar, deshabilitar, probar, eliminar SMTP (API 1.15.0+)
• health-view — enumerar los controles de salud (API 1.15.0+)
• health-manage — configurar, desarmar y ejecutar controles de estado por aplicación (API 1.15.0+)
• ip-whitelist-view — leer el panel API / MCP lista de IP permitidas (API 1.15.0+)
• ip-whitelist-manage — editar las entradas de la lista de direcciones IP permitidas (API 1.15.0+)
• apps-delete — eliminar aplicaciones
• deploy-manage — implementar, revertir, desbloquear
• ssl-manage — instalar y administrar certificados SSL
• aliases-view - leer alias
• aliases-create - agregar alias
• aliases-delete - eliminar alias
• www-manage — www/apex contraparte y redirecciones (API 1.12.0+ / Cipi 4.8+)
• dbs-view — listar bases de datos
• dbs-create - crear bases de datos
• dbs-delete — eliminar bases de datos
• dbs-manage — copia de seguridad, restauración, regeneración de contraseña
• status-view — leer la instantánea del estado del servidor (GET /api/status, API 1.11.6+)
• mcp-access — acceder al servidor MCP

Desde Cipi 4.6.3 / API 1.11.7+, cipi api token create lee la lista de habilidades canónicas del paquete API del panel (las mismas entradas que php artisan cipi:token-abilities en el servidor). Migración 4.6.3actualiza los servidores existentes con la lista actualizada (incluidos status-view, apps-suspend, y apps-basicauth).

Puntos finales de descanso

Todos los puntos finales requieren el Authorization: Bearer <token> encabezamiento. Operaciones de escritura (crear, editar, eliminar, implementar, revertir, desbloquear, SSL, alias, www, base de datos) son asíncronos: volver 202 Accepted con un job_id para sondear a través de GET /api/jobs/{id}. Puntos finales de solo lectura como GET /api/dbs, GET /api/dbs/engines, GET /api/status, GET /api/apps/{name}/www, y GET /api/apps/{name}/logs (API 1.11.9+), GET /api/php, GET /api/ssh/keys, GET /api/services, GET /api/smtp, GET /api/health, GET /api/ip-whitelist (API 1.15.0+ / Cipi 5.0.6+) son sincrónicos. POST /api/apps acepta opcional custom (booleano) y docroot (cadena) parámetros para crear aplicaciones personalizadas con despliegue clásico. el repository el campo es requerido para Laravel aplicaciones y opcional para aplicaciones personalizadas: omítalo (o envíelo vacío) para aprovisionar un sitio solo SFTP alineado con Cipi v4.5.1+. Cuando no se establece ningún repositorio, branch es omitido. Desde API 1.12.0+ / Cipi 4.8+, Laravel la creación de la aplicación también acepta opcional engine (mariadb o pgsql) para elegir la base de datos motor. Desde API 1.13.0+ / Cipi 5.0+, Laravel la creación de la aplicación acepta opcional octane (true o "frankenphp") a provisionar Laravel Octane (FrankenPHP); octane es rechazado cuando custom está configurado. La herramienta MCP AppCreate sigue las mismas reglas. Mantenga el API paquete actual con cipi api update / cipi api upgrade entonces validación y OpenAPI coincide con este comportamiento.

POST /api/apps/{name}/suspend desconecta una aplicación cambiando su Nginx vhost por un genérico HTTP 503 página de mantenimiento (HTTPS incluida) sin eliminarla, mientras POST /api/apps/{name}/unsuspend Restaura el vhost normal. Ambos requieren la apps-suspend capacidad y retorno 409 si la aplicación ya está en el objetivo estado. el suspended La bandera sobrevive a la regeneración del vhost y queda expuesta en GET /api/apps y GET /api/apps/{name}. Estos puntos finales requieren el API paquete 1.8.1+ y Cipi 4.5.8+ en el servidor.

PUT /api/apps/{name} acepta una opción domaincampo para cambiar el nombre del dominio principal de la aplicación. Desde API 1.15.0+ / Cipi 5.0.6+, el El punto final solo reenvía campos que difieren de la aplicación actual (evita la no operación webhook o clave de implementación). recreación cuando PHP o rama no cambian). PHP debe estar instalado en el host (422 en caso contrario). El API valida el formato sincrónicamente y devuelve 409si el dominio ya es utilizado por otra aplicación (los alias de la aplicación actual son permitido, por lo que promover un alias a las obras principales). Requiere el paquete API 1.9.0+ y Cipi 4.6.2+. La herramienta MCP AppEdit acepta lo mismo domain parámetro.

GET /api/apps y GET /api/apps/{name} exponer booleano suspended y basic_auth banderas por aplicación (desde apps.json). Desde API 1.12.0+ ellos también exponen engine, www_redirect, y force_https de apps-public.json / apps metadata. Since API 1.13.0+ ellos exponen octane y octane_port para Octane aplicaciones.

HTTP Puntos finales de autenticación básica en /api/apps/{name}/basicauth/* envolver cipi basicauth sincrónicamente: no devuelven un job_id. Habilitar acepta opcional user y password (generado automáticamente cuando se omite; devuelto una vez en la respuesta). Requiere el apps-basicauth habilidad y paquete API 1.10.0+. Esto es distinto de Composer auth.json gestión - ver cipi basicauth.

Puntos finales WWW/Apex en /api/apps/{name}/www/* envolver cipi www (API 1.12.0+ / Cipi 4.8+). GET …/www es sincrónico y regresa primary, apex, www, y redirect. POST …/www/add, …/force-to-root, …/force-from-root, y …/clear son trabajos asincrónicos. Requiere el www-manage habilidad. MCP herramientas: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear.

POST /api/apps/{name}/ssl/force vuelve a aplicar la redirección HTTP → HTTPS sin emitir una nuevo certificado (cipi ssl force). Requiere ssl-manage y API 1.12.0+. Herramienta MCP: SslForce.

GET /api/dbs enumera las bases de datos de forma sincrónica ejecutando sudo cipi db list en el host (igual que el servidor CLI). Consulta opcional engine=mariadb|pgsql filtros por motor (API 1.12.0+ / Cipi 4.8+). GET /api/dbs/engines enumera los motores instalados y el valor predeterminado del servidor (sincronización; MCP DbEngines). Otro /api/dbs/* escribir operaciones Son trabajos asincrónicos y aceptan opcionales. engine al crear, eliminar, realizar copias de seguridad, restaurar, y contraseña. Los comandos de la base de datos requieren Cipi 4.4.17+ en el servidor (cipi db … entradas en la lista blanca de API sudoers); necesidades de soporte multimotor Cipi 4.8+.

POST /api/apps/{name}/webhook/recreate recrea la implementación GitHub/GitLab webhook; cuerpo opcional { "rotate_secret": true } también gira CIPI_WEBHOOK_TOKEN en apps.json y shared/.env. Trabajo asíncrono (app-webhook-recreate; habilidad apps-edit; CLI cipi app webhook recreate [--rotate-secret]; API 1.15.0+ / Cipi 5.0.6+). MCP: AppWebhookRecreate.

PHP gestión (API 1.15.0+ / Cipi 5.0.6+): GET /api/php enumera las versiones instaladas (sincronización; capacidad php-view). POST /api/php/install y DELETE /api/php/{version} instalar o quitar un versión (asincrónica; php-manage). Desde API 1.17.0+, PUT /api/php/default establece el valor predeterminado del sistema PHP sincrónicamente (cuerpo { "version": "8.5" }; envolturas cipi php switch; devoluciones actualizadas GET /api/php carga útil). Las versiones instalables son 8.3, 8.4, 8.5. MCP: PhpList.

motores de base de datos — POST /api/dbs/engines/install y PUT /api/dbs/engines/default (capacidad dbs-manage; API 1.15.0+).

Claves SSH — GET|POST /api/ssh/keys, DELETE /api/ssh/keys/{n} (habilidades ssh-view / ssh-manage; API 1.15.0+).

Servicios — GET /api/services, POST /api/services/{name}/restart (habilidades services-view / services-manage; API 1.15.0+).

SMTP — GET|PUT|DELETE /api/smtp, POST /api/smtp/enable|disable|test (habilidades smtp-view / smtp-manage; la contraseña nunca se devolvió en GET; API 1.15.0+ / Cipi 5.0.6+ no interactivo cipi smtp configure --host=…).

Controles de salud — GET /api/health, GET|PUT|DELETE /api/apps/{name}/health, POST /api/apps/{name}/health/check (habilidades health-view / health-manage; API 1.15.0+).

lista blanca de IP — software intermedio cipi.ip en api/* y /mcp lee /etc/cipi/api-ip-whitelist (archivo faltante o * = permitir todo). Los clientes rechazados obtienen 403 { "error": "IP not allowed", "ip": "…" }. DESCANSO: GET /api/ip-whitelist, PUT /api/ip-whitelist (entries, opcional ensure_client_ip), POST /api/ip-whitelist (ip), DELETE /api/ip-whitelist (ip), POST /api/ip-whitelist/allow-all (habilidades ip-whitelist-view / ip-whitelist-manage; CLI cipi api ip-whitelist; API 1.15.0+ / Cipi 5.0.6+). MCP: IpWhitelistShow.

GET /api/status devuelve el mismo JSON estructurado que cipi status (sistema, recursos, servicios, PHP grupos, recuento de aplicaciones). Desde API 1.11.8+ el punto final prefiere sudo cipi status en el host y recurre a lecturas directas del host cuando sudo es no disponible. Desde API 1.12.1+ el respaldo de lectura del host incluye postgresql cuando la unidad systemd está instalada (que coincide con Cipi 4.8+). Requiere el status-view habilidad (API 1.11.6+). El MCP herramienta ServerStatus devuelve la misma carga útil y solo requiere mcp-access. Desde su computadora portátil, use cipi-cli status para obtener una visión global de todos perfiles de servidor configurados o detalles de un perfil.

GET /api/apps/{name}/logs devuelve instantáneas de registro paginadas y sincrónicas para nginx, PHP-FPM, Laravel (cuando esté presente), registros de trabajo y de implementación: la contraparte REST de cipi app logs y cipi-cli apps logs. Parámetros de consulta: type (predeterminado all), page (predeterminado 1, la mayoría reciente primero), per_page (predeterminado 50, máximo 1000). Requiere el apps-view habilidad y paquete API 1.11.9+. El texto del registro está redactado para secretos comunes (misma política que MCP AppLogs desde API 1.11.5+).

Ejemplos de DESCANSO (curl)

Configure su API URL base y token (de cipi api token create):

exportar CIPI_API_URL="https://api.myserver.com"
exportar CIPI_API_TOKEN="tu-ficha-sanctum"

Listar aplicaciones (sincronización, 200):

curl -sS "${CIPI_API_URL}/api/aplicaciones" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Aceptar: solicitud/json"

Estado del servidor (sincronización, requiere status-view):

curl -sS "${CIPI_API_URL}/api/estado" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}"

Registros de aplicaciones (sincronización, requiere apps-view, API 1.11.9+):

curl -sS "${CIPI_API_URL}/api/apps/myapp/logs?type=deploy&page=1&per_page=50" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Aceptar: solicitud/json"

Crear una aplicación Laravel Octane (asíncrono, API 1.13.0+ / Cipi 5.0+; requiere apps-create):

curl -sS -X POST "${CIPI_API_URL}/api/aplicaciones" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Aceptar: solicitud/json" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{
    "dominio": "tienda.ejemplo.com",
    "repositorio": "git@github.com:you/shop.git",
    "rama": "principal",
    "octane": verdadero,
    "motor": "mariadb"
  }'

enviar "octane": "frankenphp" para el mismo efecto. Omitir octane para clasico PHP-FPM. uso "engine": "pgsql" cuando PostgreSQL está instalado (API 1.12.0+ / Cipi 4.8+).

Aplicación .env (sincronización, API 1.14.0+ / Cipi 5.0.3+; requiere apps-env):

curl -sS "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}"

curl -sS -X PUT "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{"set":{"APP_DEBUG":"false"},"unset":["LEGACY_KEY"]}'

Artisan / ejecución de aplicación (trabajos asíncronos, API 1.14.0+; habilidades apps-artisan / apps-run):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/artisan" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{"comando":"caché:borrar"}'

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/run" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{"command":"composer instalar --no-dev"}'

curl -sS "${CIPI_API_URL}/api/ejecutar comandos" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}"

Encuesta GET /api/jobs/{id} para output / exit_code. Tipos de trabajo: app-artisan, app-run.

Implementar una aplicación (asíncrono, 202 + job_id):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/deploy" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Aceptar: solicitud/json"

# poll until completed
curl -sS "${CIPI_API_URL}/api/trabajos/JOB_ID" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}"

Copia de seguridad de la base de datos (asíncrono, dbs-manage) — devuelve una ruta de respaldo real en el trabajo result, no un volcado anónimo (ver Anonimizador del agente):

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}"

Integración de host (sudoers)

El panel API se ejecuta como www-data y ejecuta Cipi CLI comandos a través de sudo usando /etc/sudoers.d/cipi-api - una lista blanca explícita de cipi subcomandos. Las credenciales de Vault y MariaDB permanecen dentro de Cipi, no en PHP.

• GET /api/dbs - corre sudo cipi db list (sincronización). Requiere Cipi 4.4.17+ (la migración añade cipi db … a sudoers). Sin él: sudo: a terminal is required. Lista de motores múltiples/los motores necesitan Cipi 4.8+ / API 1.12.0+.
• GET /api/status / MCP ServerStatus - preferir sudo cipi status (API 1.11.8+); reserva de lectura del host cuando falla sudo (incluye postgresql desde API 1.12.1+).
• MCP ServiceList — sudo cipi service list
• MCP AppArtisan — sudo cipi app artisan <app> …
• Desde Cipi 5.0.6+ / API 1.15+: php list|install|remove|switch, ssh list|add|remove, service list|restart, status, db install|default|engines, app webhook recreate, smtp status|configure|enable|disable|test|delete, api ip-whitelist (+ args) en la lista blanca de sudoers (migración 5.0.6 crea el archivo de lista blanca de IP predeterminado y lo regenera /etc/sudoers.d/cipi-api en cipi self-update).
• Desde Cipi 5.0.3+ / API 1.14+: app env, app artisan, app run, auth create|edit|show|deletey implementar-config en la lista blanca de sudoers (la migración se regenera /etc/sudoers.d/cipi-api en cipi self-update).
• Trabajos asíncronos: cipi app (incluyendo --octane / --engine), deploy, alias, www, ssl / ssl force, db create|delete|backup|restore|password|engines, etc.

después cipi self-update, correr cipi api fix-permissions si /docs o /mcp devuelve HTTP 500 (consulte la solución de problemas más arriba).

Lista blanca de IP (CLI)

Desde Cipi 5.0.6+, restrinja los clientes del panel API y MCP por IP de origen. Archivo predeterminado /etc/cipi/api-ip-whitelist es * (permitir todo). Una dirección IPv4/IPv6 o CIDR por línea (o separados por comas --ips=).

$ cipi api ip-whitelist show
$ cipi api ip-whitelist add 203.0.113.10
$ cipi api ip-whitelist set --ips=203.0.113.0/24,2001:db8::/32
$ cipi api ip-whitelist allow-all
$ cipi api ip-whitelist show --json

Los equivalentes REST viven bajo /api/ip-whitelist (API 1.15.0+). PUT agrega automáticamente la IP de la persona que llama al ajustar la lista a menos que ensure_client_ip: false.

Arrogancia / OpenAPI

La documentación interactiva está disponible en /docs (Interfaz de usuario arrogante). La especificación OpenAPI es generado a partir de public/api-docs/openapi.json y cubre aplicaciones (incluyendo suspender, reactivar, cambiar el nombre del dominio, autenticación básica, .env, Composer auth.json, Artisan / trabajos de ejecución de aplicaciones, configuración de implementación, registros paginados, redirecciones www, Octane creación y multimotor engine), alias, implementación, SSL (instalar + forzar HTTPS), bases de datos (lista de motores + opcional engine sobre mutaciones), estado del servidor, sondeo de trabajos con estructurado result tipos y esquemas de herramientas MCP. Versión actual del paquete API: 1.20.

MCP servidor

un MCP (Protocolo de contexto modelo) está expuesto en /mcp vía Transmitible HTTP. Desde el paquete API 1.11.1+, una ficha con el mcp-access capacidad es suficiente para todos MCP herramientas: REST por punto final habilidades (apps-view, deploy-manage, apps-basicauth, www-manage, etc.) no están marcados /mcp. El servidor expone Más de 50 herramientas para aplicación, alias, www, base de datos, implementación, SSL, HTTP autenticación básica, gestión del servidor (PHP, SSH, servicios, SMTP, estado, lista blanca de IP), .env / auth.json / app-run / deploy-config, job polling, logs, Artisan, and server monitoring. Write operations that dispatch async jobs return a job_id - encuesta con JobShow (API 1.11.0+). Las acciones de autenticación básicas y las herramientas de solo lectura se ejecutan de forma sincrónica.

• Aplicaciones: AppList, AppShow, AppCreate (opcional engine, octane), AppEdit, AppSuspend, AppUnsuspend, AppDelete, AppDeploy, AppDeployRollback, AppDeployUnlock, AppArtisan (Laravel aplicaciones únicamente; rechaza aplicaciones personalizadas y tinker), AppEnvShow, AppEnvUpdate, AppAuthJson*, AppRun, AppRunCommands, AppDeployConfigShow, AppDeployConfigUpdate, AppWebhookRecreate (API 1.15.0+ / Cipi 5.0.6+; Las herramientas de aplicaciones anteriores requieren API 1.14.0+ / Cipi 5.0.3+)
• Gestión del servidor: PhpList, IpWhitelistShow (API 1.15.0+ / Cipi 5.0.6+)
• HTTP Autenticación básica: AppBasicAuthStatus, AppBasicAuthEnable, AppBasicAuthDisable
• Alias: AliasList, AliasAdd, AliasRemove
• WWW/ápice: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear (API 1.12.0+)
• Bases de datos: DbEngines, DbList, DbCreate, DbDelete, DbBackup, DbRestore, DbPassword (opcional engine en lista/mutaciones; API 1.12.0+)
• SSL: SslInstall, SslForce (API 1.12.0+)
• Trabajos y registros: JobShow (sondear el estado del trabajo asíncrono, analizado resulty CLI salida), AppLogs (registros de aplicaciones recientes por tipo: all, nginx, php, worker, deploy, laravel - igual que cipi app logs; equivalente DESCANSO:GET /api/apps/{name}/logs desde API 1.11.9+), ApiLogShow (registros Laravel recientes para el host del panel API)
• Monitoreo del servidor: ServerStatus (estructurado JSON coincidencia GET /api/status / cipi status), ServiceList (estado de servicio del sistema a través de cipi service list)

Desde Cipi 4.6.3, el paquete del panel API se actualiza suavemente todas las noches a las 04:30 vía /etc/cron.d/cipi-api (cipi api update), entonces MCP y los puntos finales REST se mantienen actualizados sin intervención manual.

Instalación del servidor MCP

El punto final MCP es opcional y se carga solo cuando se instala el paquete MCP requerido. para usarlo de Código VS, Cursor, o Escritorio Claude:

1. Configure el API con cipi api <domain> y cipi api ssl
2. Crea un token con cipi api token create y seleccione al menosmcp-access
3. Agregue el servidor MCP a la configuración de su cliente (ver más abajo)

Cursor

Añadir a ~/.cursor/mcp.json (o Cursor → Configuración → MCP):

{
  "mcpServers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

El cursor se conecta de forma nativa a través de HTTP; no se necesita puente.

Código VS

VS Code (con GitHub Copilot) admite MCP de forma nativa desde 1.102. Añadir a .vscode/mcp.json o correr MCP: Abrir configuración de usuario para una configuración global. uso inputs para solicitar el token una vez y almacenarlo de forma segura:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cipi-token",
      "description": "Cipi API Token",
      "password": true
    }
  ],
  "servers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cipi-token}"
      }
    }
  }
}

Reinicie VS Code después de guardar. uso MCP: Agregar servidor desde la paleta de comandos para un configuración guiada.

Código Claude

Agregue el servidor MCP directamente desde CLI:

$ claude mcp add --transport http cipi-api https://<your-api-domain>/mcp \
    --header "Authorization: Bearer <your-token>"

Escritorio Claude

Claude Desktop requiere el mcp-remoto puente para convertir stdio a HTTP. Añadir a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente ruta de configuración en su sistema operativo:

{
  "mcpServers": {
    "cipi-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-api-domain>/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Instalar mcp-remote una vez con npm install -g mcp-remote.

Reemplazar <your-api-domain> con su dominio API (p. ej. api.myhosting.com) y <your-token> con el token creado en el paso 2.

Módulo WHMCS

un funcionario Módulo de aprovisionamiento WHMCS está disponible en github.com/cipi-sh/whmcs. Une el ciclo de vida de aprovisionamiento de WHMCS con Cipi REST API: automatiza la creación de aplicaciones. eliminación, SSL certificados, implementaciones y cambios de configuración para sus clientes de hosting. Sin Composer dependencias; el módulo es un módulo autónomo.

Requisitos

• WHMCS 8.x (módulo de aprovisionamiento tipo “Servidor”)
• Servidor Cipi con API habilitado: cipi api <domain> y cipi api ssl
• Ficha de Portador del Sanctum con las habilidades requeridas:

Instalación

1. Copiar modules/servers/cipi/ en tu raíz de WHMCS:

   your-whmcs/
   └── modules/
       └── servers/
           └── cipi/
               ├── cipi.php
               └── lib/
                   └── CipiApiClient.php

2. en Administrador de WHMCS → Configuración del sistema → Servidores → Agregar nuevo servidor:
   • Tipo: Cipi (Laravel alojamiento)
   • Nombre de host: API URL base (p. ej. https://api.example.com, no barra diagonal)
   • Contraseña: Token al portador de cipi api token create
   • Seguro: Sí (recomendado: habilita la verificación TLS)
3. Crear un producto de alojamiento vinculado a este servidor y configurar Módulo Configuración:

Tipos de aplicaciones

Ciclo de vida de aprovisionamiento

Suspender / Reactivar requerir Cipi 4.5.8+ (suspender/dessuspender puntos finales), el paquete API 1.8.1+y una ficha con el apps-suspendcapacidad. La suspensión cambia el vhost de la aplicación por una página de mantenimiento genérica HTTP 503; al suspenderlo se restaura.

Botones de administrador

Desde la vista del servicio de administración de WHMCS, los operadores pueden activar acciones con un solo clic:

Auto-SSL en la creación

Habilitar Auto SSL en la configuración del módulo del producto para instalar automáticamente un Cifremos el certificado inmediatamente después del aprovisionamiento. Si la instalación de SSL falla, la aplicación se todavía se creó correctamente y se registra una advertencia.

Cliente API completo

el paquete CipiApiClient cubre toda la superficie Cipi REST API. Incluso si una característica no está conectado a un gancho WHMCS, puede usar el cliente en ganchos o complementos personalizados:

Ampliando el módulo

// Example: add an alias from a WHMCS hook
requerir_una vez ROOTDIR . '/modules/servers/cipi/lib/CipiApiClient.php';

$client = nuevo CipiApiClient('https://api.ejemplo.com', $token);
$client->addAlias('miaplicación', 'alias.ejemplo.com');

// Example: create an extra database
$client->createDatabase('miaplicación_extra');

// Example: backup a database
$client->backupDatabase('miaplicación');

Comportamiento de cara al cliente

El módulo hace no agregue una pestaña del Área del cliente, botones personalizados o estado en vivo desde Cipi. Los clientes ven la vista estándar del servicio WHMCS (dominio, estado, fechas de renovación). Cuando Cipi aprovisiona una aplicación, genera secretos de una sola vez (Contraseña SSH, base de datos contraseña, clave de implementación, webhook URL). REST API no envía automáticamente esos secretos a WHMCS. debe ampliar el módulo, escribir un enlace o entregar credenciales a través de su flujo de trabajo de soporte.

Registro de módulo

Todas las llamadas API se registran a través de logModuleCall()— Crear, finalizar, cambiar paquete, SSL, Implementar, Revertir, Desbloquear e Información de la aplicación. Habilitar Utilidades → Registros → Módulo Iniciar sesión en WHMCS Admin para una visibilidad completa.

cipi sync

Transfiera, replique y realice copias de seguridad de Laravel aplicaciones completas entre Cipi servidores, incluido configuración, volcados de bases de datos, archivos de almacenamiento, claves SSH, trabajadores y crontabs. Cada archivo es cifrado con AES-256-CBC y protegido por una frase de contraseña definida por el usuario, por lo que credenciales y los datos confidenciales están seguros en reposo y durante la transferencia.

Descripción general de los comandos

$ cipi sync export  [app ...] [--with-db] [--with-storage] [--output=<path>] [--passphrase=<secret>]
$ cipi sync import  <archive.tar.gz.enc> [app ...] [--update] [--deploy] [--yes] [--passphrase=<secret>]
$ cipi sync push    [app ...] [--host=IP] [--port=22] [--with-db] [--with-storage] [--import] [--passphrase=<secret>]
$ cipi sync list    <archive.tar.gz.enc> [--passphrase=<secret>]
$ cipi sync pubkey  # display the server's sync public key for inter-server trust
$ cipi sync trust   # add a remote server's public key to cipi's authorized_keys

Cifrado de archivos

Todos los archivos de sincronización son cifrado por defecto con AES-256-CBC. Durante la exportación eres Se le solicitará una frase de contraseña (mínimo 8 caracteres) que proteja el archivo. La misma frase de contraseña es necesario para importarlo o inspeccionarlo. Esto protege las claves SSH, .env archivos, volcados de bases de datos, y credenciales en reposo y durante la transferencia.

# Interactive mode (default) — prompted for passphrase
$ cipi sync export --with-db
#   Enter passphrase to encrypt the archive: ********
#   Confirm passphrase: ********

# Non-interactive mode — for cron jobs and scripts
$ cipi sync export --with-db --passphrase="MyStr0ngP@ss"

Exportar

Empaqueta las configuraciones de la aplicación en un formato cifrado .tar.gz.enc archivo. Opcionalmente incluye base de datos. volcados y archivos de almacenamiento.

# Export all apps (config only)
$ cipi sync export

# Export three specific apps with database + storage
$ cipi sync export shop blog api --with-db --with-storage

# Export to a custom path (non-interactive)
$ cipi sync export --with-db --output=/root/backups/cipi-march.tar.gz --passphrase="MyStr0ngP@ss"

¿Qué va al archivo?

Además de configuraciones globales: apps.json (filtrado a aplicaciones seleccionadas), databases.json, backup.json, api.json.

Importar

Restaura aplicaciones desde un archivo en el servidor actual.

# Import all apps from archive
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc

# Import only two apps from an archive that contains ten
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc shop blog --passphrase="MyStr0ngP@ss"

# Import and deploy code from Git immediately
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --deploy

# Non-interactive (skip all prompts)
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --yes --passphrase="MyStr0ngP@ss"

¿Qué hace la importación para una NUEVA aplicación?

Cuando una aplicación no existe en el servidor de destino, la importación la crea desde cero, equivalente a cipi app create con todas las configuraciones precargadas desde el archivo:

1. usuario de linux — Crea un nuevo usuario con una contraseña aleatoria
2. Directorios — Crea /home/<app>/shared/, logs/, .ssh/, .deployer/
3. Clave de implementación SSH — Restauraciones desde archivo (la misma clave funciona con GitHub/GitLab sin reconfiguración)
4. MariaDB base de datos — Crea base de datos + usuario con un nuevo aleatorio contraseña
5. Datos de la base de datos— Importa el volcado si --with-db fue utilizado durante exportar
6. .env — Copias del archivo, luego sobrescribe DB_PASSWORD, DB_USERNAME, DB_DATABASE, DB_HOST con los valores del nuevo servidor. Todo lo demás (APP_KEY, MAIL_*, REDIS_*, vars personalizados) permanece como está
7. PHP-grupo FPM, Nginx vhost, Supervisor trabajadores, Crontab, Deployer — Completamente configurado a partir de datos de archivo

Controles de seguridad antes de la importación.

La importación ejecuta comprobaciones previas al vuelo antes de tocar nada:

• La aplicación ya existe - bloqueado a menos que --update se pasa
• Conflicto de dominio — bloqueado si otra aplicación ya usa el mismo dominio
• Falta la versión PHP — advertencia (la aplicación se omite; instale la versión primero con cipi php install)

Modo de actualización (--update)

La característica clave para sincronización repetida (por ejemplo, replicación de conmutación por error). sin --update, la importación se niega a tocar aplicaciones que ya existen. con --update, eso actualizaciones aplicaciones existentes y crea los nuevos.

$ cipi sync import /tmp/archive.tar.gz.enc --update --passphrase="MyStr0ngP@ss"

¿Qué hace la actualización para una aplicación existente?

• .env sincronizar — El archivo .env reemplaza al local, pero DB_PASSWORD, DB_USERNAME, DB_DATABASE, y DB_HOST son conservado del servidor local. Todo lo demás (APP_KEY, MAIL_*, REDIS_*, vars personalizados) proviene del fuente.
• Datos de la base de datos — Si el archivo tiene un volcado, elimina todas las tablas (con SET FOREIGN_KEY_CHECKS=0) y reimportaciones. Utiliza credenciales de raíz local.
• Almacenamiento — Si el archivo tiene almacenamiento, lo extrae sobre el directorio existente (nuevo archivos agregados, existentes sobrescritos).
• PHP migración de versión — Si la fuente usa una versión PHP diferente, la actualización migra el grupo FPM, supervisor, crontab, implementador y .env automáticamente.
• Nginx vhost, Supervisor trabajadores, configuración del implementador — Regenerado del archivo datos.
• Implementar — Si --deploy se pasa, corre dep deploy a tirar último código.

¿Qué actualización NO cambia?

• Contraseña de usuario de Linux
• Claves de implementación SSH (conservadas desde la primera importación)
• MariaDB credenciales de usuario (el objetivo conserva las suyas)
• SSL certificados (ejecutar cipi ssl install por separado)

Lista (inspeccionar archivo)

Vea lo que hay dentro de un archivo sin importar nada.

$ cipi sync list /tmp/cipi-sync-aws01-20260306.tar.gz.enc --passphrase="MyStr0ngP@ss"

Cipi Sincronizar archivo
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Cipi v5.0.18
  Exportado 2026-03-06T15:00:00Z
  Fuente aws01 (3.120.xx.xx)
  Base de datos verdadera
  Almacenamiento verdadero
 
  Aplicaciones
  DOMINIO DE APLICACIÓN PHP ALMACENAMIENTO DE BD
  tienda tienda.ejemplo.com 8.4 sí sí
  blog blog.ejemplo.com 8.4 sí sí
  api api.example.com 8.5 sí sí
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Push (exportar + transferir + importar)

Combina exportación, transferencia rsync e importación remota en un solo comando. Se ejecuta enteramente desde el fuente servidor.

# Interactive push — prompted for target IP and passphrase
$ cipi sync push --with-db --with-storage --import

# Non-interactive push (for cron and scripts)
$ cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="MyStr0ngP@ss"

# Push specific apps only
$ cipi sync push shop blog --host=51.195.xx.xx --with-db --import --passphrase="MyStr0ngP@ss"

# Push without auto-import (transfer only — import manually on remote)
$ cipi sync push --host=51.195.xx.xx --with-db --passphrase="MyStr0ngP@ss"

Cómo funciona el empuje

1. Paso 1: Corre cipi sync export localmente (cifra con contraseña)
2. Paso 2: Transfiere el archivo cifrado al destino a través de rsync
3. Paso 3: si --import se pasa, corre cipi sync import --update --yes en el objetivo a través de SSH

Empujar siempre suma --update y --yes al llamar a importar en el control remoto. esto significa: la primera ejecución crea todas las aplicaciones, las ejecuciones posteriores las actualizan incrementalmente. Esto es lo que hace empujar Es seguro ejecutarlo repetidamente a través de cron.

Configuración SSH para envío

El servidor de origen necesita acceso SSH al destino como cipiusuario. Utilice el incorporado Mecanismo de confianza para la autenticación basada en claves y sin contraseña entre Cipi servidores:

# On the SOURCE server — display its sync public key
$ cipi sync pubkey

# On the TARGET server — add the source's public key to cipi's authorized_keys
$ cipi sync trust

Una vez confiado, cipi sync push se conecta como el cipi usuario automáticamente - no se requiere acceso de root.

Escenarios prácticos

Escenario 1: migrar todas las aplicaciones de AWS a OVH

Tienes 20 aplicaciones en AWS. Compraste un OVH VPS y le instalaste Cipi.

# On AWS (source server)
$ cipi sync push --host=51.195.xx.xx --with-db --with-storage --import

En el objetivo de OVH: 20 usuarios de Linux, 20 bases de datos, 20 nginx vhosts, PHP-FPM pools, supervisor configuraciones, crontabs: todos creados automáticamente. Datos de base de datos importados, almacenamiento extraído, .env archivos copiado con las contraseñas de base de datos de OVH, las claves de implementación SSH se conservan (las mismas claves funcionan con GitHub). después importar, instale SSL y actualice DNS:

# On OVH (target server)
$ cipi ssl install shop
$ cipi ssl install blog
# ... then update DNS A records to OVH IP

Escenario 2: replicación de conmutación por error programada (cron)

Cada 6 horas, el Servidor 1 sincroniza todas las aplicaciones con el Servidor 2. Si el Servidor 1 muere, cambie DNS y continúe activo Servidor 2.

# One-time setup on Server 1 — trust Server 2 using cipi sync trust
$ cipi sync pubkey  # copy this key, then run "cipi sync trust" on Server 2
$ echo "YourStr0ngPassphrase!" > /etc/cipi/.sync_passphrase
$ chmod 400 /etc/cipi/.sync_passphrase

# First push (manual, to verify)
$ cipi sync push --host=server2-ip --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)"

# Add to crontab for automatic replication
$ crontab -e

0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-replica.log 2>&1

La ventana de pérdida de datos equivale al intervalo cron (6 horas en este ejemplo). Cuando el Servidor 1 cae: cambiar DNS al Servidor 2, ejecutar cipi ssl install para cada aplicación, y estás en vivo.

Escenario 3: replicar en varios servidores

# Stagger by 30 minutes so exports don't run simultaneously
0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-ovh.log 2>&1
30 */6 * * * /usr/local/bin/cipi sync push --host=164.90.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-do.log 2>&1

Escenario 4: copia de seguridad cifrada diaria (sin transferencia)

0 3 * * * /usr/local/bin/cipi sync export --with-db --with-storage --output=/root/backups/cipi-$(date +\%Y\%m\%d).tar.gz --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/export.log 2>&1

Crea un archivo portátil cifrado todas las noches. Restaurar en cualquier servidor Cipi en cualquier momento con cipi sync import.

Limitaciones

• SSL certificados no están incluidos en el archivo. correr cipi ssl install después de importar en un nuevo servidor.
• La sincronización de la base de datos es un reemplazo completo, no incremental. Cada actualización elimina todas las tablas y reimportaciones.
• La sincronización del almacenamiento es un extracto completo, no rsync incremental. Archivos eliminados en el fuente permanecer en el objetivo.
• Implementar claves son iguales en origen y destino: no GitHub/GitLab reconfiguración necesario.

Bóveda y cifrado

Cipi cifra todos los archivos de configuración en reposo usando AES-256-CBC. El sistema de bóveda proporciona cifrado y descifrado transparente para que los datos confidenciales (contraseñas de bases de datos, API) fichas, claves SSH, .env contenidos: nunca se almacena en texto plano en el disco.

Arquitectura

El sistema se construye en dos capas:

• Bóveda — cifrado transparente de JSON archivos de configuración en el disco (server.json, apps.json, databases.json, backup.json, smtp.json, api.json)
• Cifrado de sincronización — cifrado basado en contraseña de archivos de exportación para mayor seguridad transferencia entre servidores

Cómo funciona la bóveda

Se genera una clave maestra durante la instalación con openssl rand -base64 32 y almacenado en /etc/cipi/.vault_key (chmod 400, sólo raíz). Cada archivo de configuración JSON es cifrado en disco con openssl enc -aes-256-cbc -salt -pbkdf2. Los archivos mantienen el .json extensión: el contenido es simplemente un blob cifrado en lugar de legible JSON.

el vault_read La función detecta automáticamente si un archivo es texto sin formato o está cifrado (hacia atrás). compatibilidad), por lo que los servidores existentes migran sin problemas durante la actualización.

Funciones de bóveda

# Core functions in lib/vault.sh
vault_init          # Generate .vault_key if not present
vault_read <file>   # Decrypt and output JSON to stdout (auto-detect plain/encrypted)
vault_write <file>  # Read JSON from stdin, encrypt and write to disk
vault_seal <file>   # Encrypt an existing plaintext file in-place
vault_get <file> <jq_query>  # Shortcut: vault_read | jq

Proyección pública

Cipi genera un apps-public.json archivo que contiene sólo campos no confidenciales (dominio, alias, PHP versión, rama, repositorio, usuario, marca de tiempo de creación, más suspended y basic_auth banderas). el cipi-api lecturas grupales esta proyección de texto sin formato en lugar del archivo cifrado, manteniendo la clave de la bóveda restringida a la raíz.

Cifrado de archivos de sincronización

cuando corres cipi sync export, las configuraciones se descifran desde la bóveda a un área de preparación, luego, todo el archivo se cifra con su frase de contraseña. Al importar, el archivo se descifra con la frase de contraseña y las configuraciones se vuelven a cifrar con el bóveda del servidor de destino clave.

Notificaciones por correo electrónico

Cipi puede enviar alertas por correo electrónico cuando se produzcan errores de copia de seguridad, fallas de implementación, fallas de trabajo del sistema cron o se producen eventos de autenticación relevantes para la seguridad. La configuración SMTP se almacena cifrada en /etc/cipi/smtp.json e incluido en sincronización exportaciones.

Comandos

$ cipi smtp configure      # interactive setup (Gmail, SendGrid, Mailgun, custom)
$ cipi smtp status          # display current notification settings
$ cipi smtp test            # send a verification email
$ cipi smtp enable          # enable notifications
$ cipi smtp disable         # disable without losing settings
$ cipi smtp delete          # remove SMTP configuration entirely

# Non-interactive (v5.0.6+) — panel API, scripts, automation
$ cipi smtp configure --host=smtp.example.com --port=587 --user=… --password=… \
    --from=alerts@example.com --to=ops@example.com --tls=on
$ cipi smtp status --json
$ cipi smtp delete --force

Activadores de notificaciones granulares

desde v4.6.3, puede controlar qué eventos envían correo electrónico cuando se configura SMTP. Todos los desencadenantes son activado de forma predeterminada; los eventos siempre se registran en /var/log/cipi/events.log a pesar de todo.

$ cipi notifications list              # all triggers grouped by category
$ cipi notifications enable <trigger>   # turn one trigger on
$ cipi notifications disable <trigger>  # turn one trigger off
$ cipi notifications enable-all          # re-enable everything
$ cipi notifications disable-all         # mute all email alerts
$ cipi notifications reset               # restore defaults (all on)

Configuración: /etc/cipi/notifications.json. correr cipi notifications list en el servidor para el estado encendido/apagado en vivo. ID de activación para cipi notifications enable|disable <trigger>:

Alertas automáticas

Una vez configurado, Cipi envía notificaciones por correo electrónico a:

• Errores de copia de seguridad (S3 fallas de carga, errores de volcado)
• Fallos de implementación (errores del implementador, activadores de reversión)
• Sistema cron fallas en el trabajo (a través del cipi-cron-notify envoltorio)
• Eventos del ciclo de vida de la aplicación: notifica cuando se crea, edita o elimina una aplicación, incluidos nombre de host del servidor, nombre de la aplicación, dominio y versión PHP
• Sudo y su elevación: notifica cuando un usuario se eleva exitosamente a través de sudo o su, incluido quién lo ejecutó, el usuario objetivo (por su), Clave SSH, IP del cliente y TTY
• Inicio de sesión SSH privilegiado: notifica cuando root o cualquier sudoer inicia sesión a través de SSH, incluyendo IP de origen, huella digital de clave SSH y comentario de clave
• Cambios de clave SSH: notifica cuando se agrega, elimina o cambia el nombre de una clave SSH en el cipi usuario, incluido el nombre de host, IP, huella digital, comentario clave, marca de tiempo y recuento de claves restante. Las alertas de cambio de nombre también incluyen el nombre de la clave nueva y antigua.

Cada notificación por correo electrónico incluye un pie de página con la IP del cliente (SSH_CLIENT) y el SSH Nombre de clave utilizado para la autenticación, cuando corresponda. El nombre de la clave se resuelve mediante SSH_USER_AUTH con un auth.log respaldo cuando sea necesario.

Notificaciones de autenticación de seguridad

Cipi integra notificaciones de autenticación basadas en PAM a través de pam_exec.so con ExposeAuthInfo activado. Cuando se configura SMTP, el El sistema envía automáticamente alertas por correo electrónico sobre estos eventos relevantes para la seguridad:

• Sudo y su elevación — se activa cuando cualquier usuario ejecuta con éxito sudo o su. La notificación incluye el nombre de usuario, el usuario objetivo (por su), el TTY, la clave SSH, la IP del cliente y la marca de tiempo.
• Inicio de sesión SSH privilegiado - desencadenado cuando root o cualquier usuario en el sudo El grupo inicia sesión a través de SSH. La notificación incluye el nombre de usuario, IP de origen. dirección, huella digital de clave SSH y comentario clave (resuelto desde /var/log/auth.log comparación de huellas dactilares con authorized_keys).
• Cambios de clave SSH — se activa cuando se agrega, elimina o elimina una clave SSH. renombrado en el cipi usuario a través de cipi ssh add, cipi ssh remove, o cipi ssh rename. La notificación incluye el nombre de host, IP del servidor, huella digital de clave, comentario de clave, marca de tiempo y recuento de claves restantes. Cambiar nombre Las alertas también incluyen el nombre de clave antiguo y nuevo.
• Eventos del ciclo de vida de la aplicación— se activa cuando se crea, edita o elimina una aplicación. La notificación incluye el nombre de host del servidor, el nombre de la aplicación, el dominio y la versión PHP.

Las notificaciones se ejecutan de forma asincrónica en segundo plano para que nunca retrasen el inicio de sesión o el comando ejecución. Si SMTP no está configurado, los enlaces fallan silenciosamente sin impacto en el sistema.

Registro de eventos de seguridad

Independientemente de la configuración SMTP, todos los eventos de notificación (cambios de clave SSH, ciclo de vida de la aplicación, restablecimientos de contraseña, sudo/su/SSH inicio de sesión, cron fallas) siempre se registran en /var/log/cipi/events.log en un formato compacto de una sola línea. El tronco se rota diariamente con Retención de 1 año a través de logrotate.

Cron envoltorio

el cipi-cron-notify La utilidad envuelve los trabajos del sistema cron y envía una notificación si el trabajo sale con un código distinto de cero. Esto es útil para monitorear tareas críticas programadas.

Retención de registros (GDPR)

Cipi aplica políticas de rotación automática de registros diseñadas para cumplir con el RGPD y la protección general de datos. requisitos. Los registros se rotan y eliminan automáticamente, sin necesidad de limpieza manual.

Valkey

Valkey es el almacén de datos en memoria que Cipi instala como parte de la pila predeterminada. desde v4.5.6 Cipi disposiciones Valkey en lugar de redis-server. Destaca en almacenamiento en caché, almacenamiento de sesiones, colas de mensajes y tiempo real. radiodifusión y limitación de velocidad.

¿Por qué Valkey en lugar de Redis?

Valkey es el verdaderamente open-source, con licencia BSD tenedor de Redis, dirigido por el Fundación Linux. Se creó en 2024 después de que Redis Inc. volviera a otorgar la licencia a Redis. de la licencia BSD permisiva a la SSPL/RSALv2 disponible en el código fuente, un cambio que ya no se cumplió la definición open-source. Respaldado por AWS, Google Cloud, Oracle y una gran comunidad, Valkey continúa con el mismo código base probado en batalla bajo una licencia que permanecelibre para siempre. Eso lo hace perfecto para el MIT de Cipi, la filosofía de no depender de ningún proveedor, y se envía de forma nativa en el repositorio Universe de Ubuntu 24.04 (paquetes valkey-server + valkey-tools) - no hay PPA de terceros en quien confiar.

Igual de importante es que Valkey es un reemplazo directo: habla exactamente lo mismo RESP protocolo en el mismo puerto (127.0.0.1:6379), honra lo mismo requirepass / bind directivas y lee el mismo formato de datos RDB/AOF. tu las aplicaciones necesitan cero cambios — el phpredis extensión y su existente REDIS_* .env Los valores siguen funcionando exactamente como antes.

Cómo lo implementa Cipi

• Instalar — setup.sh instala y configura Valkey (/etc/valkey/valkey.conf, servicio valkey-server), obligado a localhost únicamente y protegido con contraseña.
• Gestión de servicios — cipi service … gestiona valkey-server (los nombres redis-server, redis, y valkey todavía se aceptan como alias). Se agrega a las actualizaciones desatendidas. lista negra, por lo que Cipi la administra en lugar de una actualización automática.
• Credenciales - almacenado bajo valkey_user / valkey_password en /etc/cipi/server.json (el legado redis_* las claves todavía se leen como alternativa). Anfitrión: 127.0.0.1, Puerto: 6379.
• Restablecer contraseña — cipi reset valkey-password regenera el contraseña y reinicia el servicio (cipi reset redis-password permanece como un alias).

Migrando desde Redis (4.5.6 / 4.5.7)

Los servidores existentes cambian a Valkey automáticamente el cipi self-update — sin aplicación .env Se requiere edición. La migración reutiliza la contraseña actual Redis (recuperada de server.json o /etc/redis/redis.conf), fuerza a un RDB SAVE y instantáneas dump.rdb/AOF, purges redis-server, instala valkey-server + valkey-tools en el mismo puerto con el mismo requirepass / bind, restaura el conjunto de datos y reescribe server.json (redis_* → valkey_*) y las actualizaciones desatendidas lista negra: para que la caché, las sesiones y los trabajos en cola sobrevivan al cambio.

v4.5.7 corrige el nombre del paquete a valkey-server (el Ubuntu 24.04 paquete demonio; 4.5.6 utilizado inicialmente valkey) y hace la migración completamente autónomo y seguro. Autoactiva launiverse APT componente cuando el paquete no se encuentra, ejecuta una verificación de estado posterior al inicio (PING → PONG con el contraseña), y vuelve a redis-server— restaurar tanto los salvados contraseña y el conjunto de datos, si Valkey no se puede instalar o no funciona correctamente. El conjunto de datos La instantánea se conserva hasta que se verifica el cambio y luego se limpia. La migración es idempotente: servidores ya en Valkey sáltatelo.

Laravel integración

Añade estas variables a tu .env vía cipi app env myapp. Los nombres de las variables quedarse REDIS_* - eso es lo que phpredis y Laravel redis El controlador espera y Valkey responde en el mismo socket:

REDIS_HOST=127.0.0.1
REDIS_CONTRASEÑA=su-contraseña-del-servidor-json
REDIS_PORT=6379

Luego configure los controladores para cada caso de uso:

• caché — CACHE_STORE=redis
• Sesión — SESSION_DRIVER=redis
• cola — QUEUE_CONNECTION=redis (entonces cipi worker restart myapp)
• Radiodifusión — BROADCAST_CONNECTION=redis

Instale el phpredis PHP extensión para un mejor rendimiento, o use predis/predis como un respaldo puro-PHP. Ambos hablan con Valkey de forma transparente.

Autoactualización

Cipi puede actualizarse desde GitHub sin afectar ninguna aplicación, base de datos o configuración.

$ cipi self-update --check   # check for a new version
$ cipi self-update           # update to latest

Proceso de actualización

1. Descarga la última versión de GitHub
2. Realiza una copia de seguridad de la instalación actual en /opt/cipi.bak.YYYYMMDDHHMMSS/
3. Reemplaza los scripts CLI y lib
4. Ejecuta cualquier pendiente guiones de migración en orden (por ejemplo, nuevas directivas Nginx, nuevas paquetes)
5. Actualiza el archivo de versión.

Los guiones de migración viven en lib/migrations/ y se nombran por versión (p. ej. 4.1.0.sh, 5.0.18.sh). Al actualizar de v4.0.0 a v4.2.0, Cipi se ejecuta automáticamente 4.1.0.sh y 4.2.0.sh en orden. Sus aplicaciones, bases de datos y configuraciones nunca son tocados.

Reciente 5.0.x Las migraciones mejoran la confiabilidad sin cambiar los datos de la aplicación: 5.0.6 — archivo de lista blanca de IP predeterminado y API sudoers regenerados; 5.0.9 — cipi php switch en sudoers para PUT /api/php/default; 5.0.13 — recuperar la propiedad de API/GUI después de la actualización; 5.0.14–5.0.17 — Actualizaciones programadas del paquete del panel GitHub/Packagist (no más cipi self-update en API/GUI Composer clones VCS);5.0.18 — reparar el Panel GUI después del enlace simbólico/open_basedir HTTP 500 (cipi gui fix-permissions). correr cipi self-update alcanzar 5.0.18.

Por ejemplo, el 4.5.5 migración actualiza las aplicaciones existentes con la nueva ll='ls -al' alias de shell: agrega el alias a cada aplicación ~/.bashrc una vez (solo cuando falta, preservando la propiedad), por lo que las aplicaciones creadas antes de 4.5.5 lo obtienen en la siguiente cipi self-update.

Crones de mantenimiento automático

Cipi programa varios trabajos de nivel raíz durante la instalación. Crontabs a nivel de aplicación (programador, implementación disparador) están separados; consulte crontab de usuario.

Dominios comodín

Cipi hace no Admite dominios comodín (*.myapp.com) de forma nativa. el El bloque es doble y arquitectónico, no un detalle de configuración.

Por qué no se admiten comodines

1 — Rechazos de validación de dominio *
Cada dominio pasado a cipi alias add (y cipi app create) está validado contra una expresión regular estricta que requiere que la cadena comience con [a-zA-Z0-9]. el asterisco falla inmediatamente, antes de que se toque nginx o certbot.

2: Certbot utiliza el desafío HTTP-01, que no puede emitir certificados comodín
cipi ssl install llamadas certbot --nginx, que se basa en HTTP-01 (o TLS-ALPN-01): colocar un archivo de verificación en el disco y entregarlo a través del puerto 80. Vamos a Encrypt solo emite certificados comodín a través del DNS-01 desafío, que requiere acceso programático al API de su DNS proveedor. Cipi no se integra con ningún proveedor DNS, por lo que Incluso si se omitiera la validación, certbot se negaría a emitir el certificado comodín.

Alternativa recomendada: certificado Multi-SAN

Si sus subdominios son fijos y enumerables (p. ej. api, admin, www, staging), el enfoque correcto es agregar cada uno como un explícito alias y permita que Cipi emita un único certificado SAN que los cubra a todos:

$ cipi alias add myapp api.myapp.com
$ cipi alias add myapp admin.myapp.com
$ cipi alias add myapp www.myapp.com
$ cipi ssl install myapp   # single cert, SAN covers all domains

Certbot --expand El indicador (utilizado internamente por Cipi) agrega las nuevas SAN a las existentes certificado sin emitir uno nuevo. La lista SAN no tiene ningún límite significativo para el uso típico.

Certificado comodín manual (fuera de Cipi)

Si necesita subdominios dinámicos (p. ej. <tenant>.saas.com), puedes obtener un comodín certificado manualmente usando un complemento DNS para certbot y colóquelo en el servidor. Cipi no lo hará adminístrelo, renuévelo o realice un seguimiento: usted es dueño del ciclo de vida por completo.

# example with the Cloudflare DNS plugin
$ pip install certbot-dns-cloudflare
$ certbot certonly --dns-cloudflare \
    --dns-cloudflare-credentials /root/.cloudflare.ini \
    -d "*.myapp.com" -d "myapp.com"

Después de obtener el certificado, edite el nginx vhost de la aplicación directamente (/etc/nginx/sites-available/myapp) para hacer referencia a las rutas de los certificados comodín y agregar server_name *.myapp.com myapp.com;. Luego recarga nginx:

$ nginx -t && systemctl reload nginx

Editar configuración Nginx

Para personalizar el vhost Nginx para una aplicación, edite la configuración del sitio directamente. Después de los cambios, pruebe y recargar Nginx.

$ sudo nano /etc/nginx/sites-available/<app>
$ sudo nginx -t && sudo systemctl reload nginx

Desinstalar Cipi

Cipi no proporciona un comando de desinstalación integrado. Si necesita eliminar completamente Cipi de un servidor, sigue los pasos a continuación en orden. Este procedimiento elimina todos los componentes que Cipi instalaciones: usuarios, servicios, paquetes, configuraciones y datos.

1: detener y eliminar todas las aplicaciones

Para cada aplicación administrada por Cipi, elimine su usuario del sistema, directorio de inicio, base de datos, nginx vhost, PHP-FPM piscina, y supervisor configuración.

# List all app users (members of cipi-apps group)
$ grep cipi-apps /etc/group

# For EACH app user, remove everything
$ supervisorctl stop <app_user>:*
$ rm -f /etc/supervisor/conf.d/<app_user>.conf
$ rm -f /etc/nginx/sites-enabled/<app_user>
$ rm -f /etc/nginx/sites-available/<app_user>
$ rm -f /etc/php/*/fpm/pool.d/<app_user>.conf
$ rm -f /etc/sudoers.d/cipi-<app_user>
$ mysql -e "DROP DATABASE IF EXISTS <app_user>; DROP USER IF EXISTS '<app_user>'@'localhost'; DROP USER IF EXISTS '<app_user>'@'127.0.0.1';"
$ userdel -r <app_user>

2 - Eliminar el usuario y los grupos Cipi

$ userdel -r cipi
$ groupdel cipi-ssh 2>/dev/null
$ groupdel cipi-apps 2>/dev/null

3 - Eliminar Cipi archivos binarios, bibliotecas y datos

$ rm -f /usr/local/bin/cipi
$ rm -f /usr/local/bin/cipi-worker
$ rm -f /usr/local/bin/cipi-cron-notify
$ rm -f /usr/local/bin/cipi-auth-notify
$ rm -rf /opt/cipi
$ rm -rf /etc/cipi
$ rm -rf /var/log/cipi

4 — Quitar Cipi API (si está instalado)

$ systemctl stop cipi-queue 2>/dev/null
$ systemctl disable cipi-queue 2>/dev/null
$ rm -f /etc/systemd/system/cipi-queue.service
$ systemctl daemon-reload

5 - Eliminar Cipi cron trabajos

# Edit root crontab and remove all Cipi entries
$ crontab -e
# Remove lines referencing: cipi self-update, certbot renewal, cache cleanup, RAM drop

6 - Eliminar archivos de configuración Cipi

# Sudoers
$ rm -f /etc/sudoers.d/cipi-sudo
$ rm -f /etc/sudoers.d/cipi-api

# Logrotate
$ rm -f /etc/logrotate.d/cipi-app-logs
$ rm -f /etc/logrotate.d/cipi-http-logs
$ rm -f /etc/logrotate.d/cipi-security-logs

# Unattended upgrades
$ rm -f /etc/apt/apt.conf.d/50cipi-unattended-upgrades
$ rm -f /etc/apt/apt.conf.d/20cipi-auto-upgrades

# System profile and MOTD
$ rm -f /etc/profile.d/cipi-env.sh
$ echo "" > /etc/motd

# MariaDB custom config
$ rm -f /etc/mysql/mariadb.conf.d/99-cipi.cnf

# PHP custom config (all versions)
$ rm -f /etc/php/*/fpm/conf.d/99-cipi.ini

# Nginx default page
$ rm -f /etc/nginx/sites-available/default
$ rm -f /etc/nginx/sites-enabled/default

7 - Purgar paquetes instalados

Elimine todos los paquetes que Cipi instaló. Omita cualquier paquete que desee conservar para otros fines.

$ systemctl stop nginx mariadb valkey-server fail2ban supervisor
$ systemctl stop php*-fpm

$ apt purge -y nginx* mariadb-server mariadb-client valkey-server \
    fail2ban supervisor certbot python3-certbot-nginx \
    php8.4* php8.5* nodejs

$ apt autoremove -y
$ apt autoclean

8 - Eliminar repositorios APT

$ add-apt-repository --remove ppa:ondrej/php -y
$ rm -f /etc/apt/sources.list.d/mariadb.list
$ rm -f /etc/apt/sources.list.d/nodesource.list
$ rm -f /etc/apt/keyrings/mariadb-keyring.pgp
$ apt update

9 - Eliminar Composer y el implementador

$ rm -f /usr/local/bin/composer
$ rm -f /usr/local/bin/dep

10 - Eliminar archivo de intercambio

$ swapoff /var/swap.1
$ rm -f /var/swap.1
# Remove the swap entry from /etc/fstab
$ sed -i '/swap\.1/d' /etc/fstab

11 — Restaurar los valores predeterminados de SSH y PAM

Cipi refuerza SSH (deshabilita el inicio de sesión raíz y la autenticación de contraseña) y agrega enlaces PAM. Si necesitas restaurar valores predeterminados:

# Restore sshd_config to allow password auth (if needed)
$ sed -i 's/^PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config
$ sed -i 's/^PermitRootLogin no/PermitRootLogin yes/' /etc/ssh/sshd_config

# Remove Cipi PAM hooks
$ sed -i '/cipi-auth-notify/d' /etc/pam.d/sshd
$ sed -i '/cipi-auth-notify/d' /etc/pam.d/sudo

# Restore sysctl
$ sed -i '/vm.swappiness/d' /etc/sysctl.conf
$ sysctl -p

$ systemctl restart sshd

12 — Restablecer el cortafuegos

$ ufw disable
$ ufw reset