Avançado

cipi api

Cipi pode opcionalmente habilitar uma camada REST API no servidor via cipi api <domain>. É alimentado pelo pacote Laravel cipi/api (versão atual1.20), que expõe:

• DESCANSE API — aplicativos (incluindo Octane criar, .env, auth.json, Artisan, na lista de permissões app run, implantar-config), aliases, www redirecionamentos, implantação, SSL, bancos de dados multimecanismo, logs de aplicativos, status do servidor (/api/*)
• MCP servidor — Mais de 50 ferramentas em /mcp (Transmitivel HTTP)
• Cabine do servidor — PHP instalação/troca, chaves SSH, serviços, SMTP, verificações de integridade, Lista de permissões de IP (API 1.15.0+ / Cipi 5.0.6+)
• IU arrogante — referência interativa em /docs

Requer PHP 8.2+ e Laravel 12+ no host do painel. Isto é nível de servidor automação – diferente da por aplicativo Cipi Agente pacote (cipi/agent em cada aplicativo Laravel).

O cipi/api pacote

Em um servidor Cipi normal você nunca instala o pacote manualmente — cipi api <domain> disposições Laravel em /opt/cipi/api, Nginx, SSL, fila de tarefas SQLite e cipi-queue.service. Para referência ou configurações 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

Painel .env usa CIPI_APPS_JSON=/etc/cipi/apps.json (ou apps-public.json projeção para campos não sensíveis). Habilidades de token são definidas em config/cipi.php - liste-os com php artisan cipi:token-abilities (mesmo listar como cipi api token create desde Cipi 4.6.3).

Fonte e changelog: github.com/cipi-sh/api (MIT). Wrapper do 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

Solução de problemas do painel API

Depois cipi self-update, arquivos de propriedade raiz em /opt/cipi/api ou/opt/cipi/gui pode evitar PHP-FPM (www-data) de gravar logs ou o Banco de dados de tarefas SQLite — o navegador mostra um vazio HTTP 500 ligado /docs ou/mcp. Cipi normalmente repara a propriedade automaticamente durante a autoatualização (migração 5.0.13+recupera a propriedade de API/GUI); se os problemas persistirem:

$ 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 o Laravel instalado e cipi/api versões do pacote, se cipi-queue.service está ativo, trabalhos assíncronos pendentes no banco de dados SQLite do painel, e estatísticas de pool de PHP-FPM para o API vhost (incluindo solicitações lentas quando configuradas). cipi api update atualiza suavemente o pacote panel API do Packagist (desde 5.0.15; a migração descarta entradas obsoletas do repositório VCS). cipi api upgrade executa uma reconstrução completa com reversão em /opt/cipi/api.old. Desde 5.0.14–5.0.17, a autoatualização usa tarballs GitHub cronometrados e Packagist dist instala em vez de bloquear clones Composer VCS para pacotes API e GUI. Desde 5.0.18, GUI upgrade/update evita links simbólicos Composer que quebram PHP-FPM open_basedir (HTTP 500); correr cipi gui fix-permissions oucipi self-update para reparar painéis existentes.

Desde v4.7.18 (migrações 4.7.15–4.7.18), falhas no painel API em Ubuntu 25.10+ / 26.04 são corrigidos de ponta a ponta: sudo-rs rejeita cipi db restore * * curingas (todo o arquivo sudoers foi ignorado - Receio não poder fazer isso), então a lista de permissões usa o final * apenas; fornecimento common.sh não aborta mais comandos somente leitura quando /etc/cipi é remontado somente leitura; API open_basedir inclui /usr/local/bin/ para ajudantes de log; e cipi db list mostra bancos de dados vazios e supera erros de vault/MariaDB. Corre cipi self-update para aplicar.

Criação de token e permissões granulares

Usos de autenticação Santuário. Cada token pode ter um ou mais habilidades isso limitar operações permitidas:

• apps-view - leia aplicativos
• apps-create - criar aplicativos
• apps-edit — editar aplicativos (PHP, repositório, branch, domínio primário desde API 1.9.0+ / Cipi 4.6.2+)
• apps-suspend — suspender e cancelar a suspensão de aplicativos
• apps-basicauth — ativar, desativar e inspecionar HTTP Autenticação básica em aplicativos (API 1.10.0+)
• apps-env - listar/mesclar aplicativo .env teclas (API 1.14.0+ / Cipi 5.0.3+)
• apps-auth — gerenciar Composer compartilhado auth.json (API 1.14.0+; distinto de apps-basicauth)
• apps-artisan — execute Artisan como um trabalho assíncrono (API 1.14.0+)
• apps-run - não interativo na lista de permissões app run (API 1.14.0+)
• apps-deploy-config — opções estruturadas de receitas do Deployer (API 1.14.0+)
• php-view — lista as PHP versões instaladas (API 1.15.0+)
• php-manage — instalar/remover PHP, definir o padrão do sistema (API 1.15.0+ / 1.17.0+ para PUT /api/php/default)
• ssh-view — listar chaves SSH no cipi usuário (API 1.15.0+)
• ssh-manage — adicionar/remover/renomear chaves SSH (API 1.15.0+)
• services-view — listar serviços do sistema (API 1.15.0+)
• services-manage — reiniciar serviços (API 1.15.0+)
• smtp-view — leia as configurações de notificação SMTP (a senha nunca foi retornada; API 1.15.0+)
• smtp-manage — configurar, ativar, desativar, testar, excluir SMTP (API 1.15.0+)
• health-view — listar verificações de integridade (API 1.15.0+)
• health-manage — definir, desativar e executar verificações de integridade por aplicativo (API 1.15.0+)
• ip-whitelist-view — leia o painel API / MCP lista de permissões de IP (API 1.15.0+)
• ip-whitelist-manage — editar entradas da lista de permissões de IP (API 1.15.0+)
• apps-delete - excluir aplicativos
• deploy-manage - implantar, reverter, desbloquear
• ssl-manage — instalar e gerenciar certificados SSL
• aliases-view - leia apelidos
• aliases-create - adicionar apelidos
• aliases-delete - remover apelidos
• www-manage — contraparte www/apex e redirecionamentos (API 1.12.0+ / Cipi 4.8+)
• dbs-view - listar bancos de dados
• dbs-create - criar bancos de dados
• dbs-delete - excluir bancos de dados
• dbs-manage - backup, restauração, regeneração de senha
• status-view — leia o instantâneo do status do servidor (GET /api/status, API 1.11.6+)
• mcp-access — acesse o servidor MCP

Desde Cipi 4.6.3 / API 1.11.7+, cipi api token createlê a lista de habilidades canônicas do pacote painel API (mesmas entradas que php artisan cipi:token-abilities no servidor). Migração 4.6.3 atualiza servidores existentes com a lista atualizada (incluindo status-view, apps-suspende apps-basicauth).

Pontos de extremidade REST

Todos os terminais exigem o Authorization: Bearer <token> cabeçalho. Operações de gravação (criar, editar, excluir, implantar, reverter, desbloquear, SSL, alias, www, banco de dados) são assíncronos: eles retornar 202 Acceptedcom um job_id fazer uma enquete via GET /api/jobs/{id}. Pontos de extremidade somente leitura, como GET /api/dbs, GET /api/dbs/engines, GET /api/status, GET /api/apps/{name}/wwwe 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+) são síncronos. POST /api/apps aceita opcional custom (booleano) e docroot (string) parâmetros para criação aplicativos personalizados com implantação clássica. O repository campo é obrigatório para Laravel aplicativos e opcional para aplicativos personalizados: omita-o (ou envie-o em branco) para provisionar um site somente SFTP alinhado com Cipi v4.5.1+. Quando nenhum repositório está definido, branch é omitido. Desde API 1.12.0+ / Cipi 4.8+, Laravel app create também aceita opcional engine (mariadb ou pgsql) para escolher o banco de dados motor. Desde API 1.13.0+ / Cipi 5.0+, Laravel criação de aplicativo aceita opcional octane (true ou "frankenphp") para provisionar Laravel Octane (FrankenPHP); octane é rejeitado quando custom está definido. A ferramenta MCP AppCreate segue as mesmas regras. Mantenha o API pacote atual com cipi api update / cipi api upgrade então validação e OpenAPI corresponde a esse comportamento.

POST /api/apps/{name}/suspend coloca um aplicativo off-line trocando seu Nginx vhost por um genérico HTTP 503 página de manutenção (HTTPS incluída) sem excluí-la, enquanto POST /api/apps/{name}/unsuspend restaura o vhost normal. Ambos exigem o apps-suspend capacidade e retorno 409 se o aplicativo já estiver no destino estado. O suspended flag sobrevive à regeneração do vhost e é exposto em GET /api/apps e GET /api/apps/{name}. Esses endpoints requerem o API pacote 1.8.1+ e Cipi 4.5.8+ no servidor.

PUT /api/apps/{name} aceita um opcional domain campo para renomear o domínio principal do aplicativo. Desde API 1.15.0+ / Cipi 5.0.6+, o endpoint apenas encaminha campos que diferem do aplicativo atual (evita no-op webhook ou deploy-key recreação quando PHP ou ramo permanecem inalterados). PHP deve ser instalado no host (422 caso contrário). O API valida o formato de forma síncrona e retorna 409 se o domínio já for usado por outro aplicativo (os aliases do aplicativo atual são permitido, promovendo assim um pseudônimo para obras primárias). Requer o pacote API 1.9.0+ e Cipi 4.6.2+. A ferramenta MCP AppEdit aceita o mesmo domain parâmetro.

GET /api/apps e GET /api/apps/{name} expor booleano suspended e basic_auth sinalizações por aplicativo (de apps.json). Desde API 1.12.0+ eles também expõem engine, www_redirecte force_https de apps-public.json / apps metadata. Since API 1.13.0+ eles expõem octane e octane_port para Octane aplicativos.

HTTP Endpoints de autenticação básica em /api/apps/{name}/basicauth/* embrulhar cipi basicauth de forma síncrona - eles não retornam um job_id. Habilitar aceita opcional user e password (gerado automaticamente quando omitido; retornado uma vez em a resposta). Requer o apps-basicauth capacidade e pacote API 1.10.0+. Isso é diferente de Composer auth.json gestão - veja cipi basicauth.

Endpoints WWW/apex em /api/apps/{name}/www/* embrulhar cipi www (API 1.12.0+ / Cipi 4.8+). GET …/www é síncrono e retorna primary, apex, wwwe redirect. POST …/www/add, …/force-to-root, …/force-from-roote …/clear são trabalhos assíncronos. Requer o www-manage habilidade. MCP ferramentas: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear.

POST /api/apps/{name}/ssl/force reaplica o redirecionamento HTTP → HTTPS sem emitir um novo certificado (cipi ssl force). Requer ssl-manage e API 1.12.0+. Ferramenta MCP: SslForce.

GET /api/dbs lista bancos de dados de forma síncrona executando sudo cipi db list no host (igual ao servidor CLI). Consulta opcional engine=mariadb|pgsql filtros por motor (API 1.12.0+ / Cipi 4.8+). GET /api/dbs/engines lista os motores instalados e o padrão do servidor (sincronização; MCP DbEngines). Outro /api/dbs/* operações de gravação são trabalhos assíncronos e aceitam opcionais engine em criar, excluir, fazer backup, restaurar, e senha. Os comandos do banco de dados requerem Cipi 4.4.17+no servidor (cipi db … entradas na lista branca API sudoers); necessidades de suporte multimotor Cipi 4.8+.

POST /api/apps/{name}/webhook/recreate recria o GitHub/GitLab implantar webhook; corpo opcional { "rotate_secret": true } também gira CIPI_WEBHOOK_TOKEN em apps.json e shared/.env. Trabalho assíncrono (app-webhook-recreate; habilidade apps-edit; CLI cipi app webhook recreate [--rotate-secret]; API 1.15.0+ / Cipi 5.0.6+). MCP: AppWebhookRecreate.

PHP gestão (API 1.15.0+ / Cipi 5.0.6+): GET /api/php lista as versões instaladas (sincronização; capacidade php-view). POST /api/php/install e DELETE /api/php/{version} instalar ou remover um versão (assíncrona; php-manage). Desde API 1.17.0+, PUT /api/php/default define o padrão do sistema PHP de forma síncrona (corpo { "version": "8.5" }; embrulhos cipi php switch; retornos atualizados GET /api/php carga útil). Versões instaláveis são 8.3, 8.4, 8.5. MCP: PhpList.

Mecanismos de banco de dados — POST /api/dbs/engines/install e PUT /api/dbs/engines/default (habilidadedbs-manage; API 1.15.0+).

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

Serviços — 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; senha nunca retornada em GET; API 1.15.0+ / Cipi 5.0.6+ não interativo cipi smtp configure --host=…).

Verificações de saúde — 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 de permissões de IP – intermediário cipi.ip ligado api/* e /mcp lê /etc/cipi/api-ip-whitelist (arquivo ausente ou * = permitir tudo). Clientes rejeitados recebem 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 retorna o mesmo JSON estruturado que cipi status (sistema, recursos, serviços, PHP pools, contagem de aplicativos). Desde API 1.11.8+ o ponto final prefere sudo cipi status no host e volta para leituras diretas do host quando sudo é indisponível. Desde API 1.12.1+ o substituto de leitura do host inclui postgresql quando a unidade systemd estiver instalada (correspondente a Cipi 4.8+). Requer o status-view habilidade (API 1.11.6+). O MCP ferramenta ServerStatus retorna a mesma carga útil e requer apenas mcp-access. No seu laptop, use cipi-cli status para uma visão global de todos perfis de servidor configurados ou detalhes de um perfil.

GET /api/apps/{name}/logs retorna instantâneos de log paginados e síncronos para nginx, PHP-FPM, Laravel (quando presente), registros de trabalho e de implantação — a contraparte REST para cipi app logs e cipi-cli apps logs. Parâmetros de consulta: type (padrão all), page (padrão 1, a maioria recente primeiro), per_page (padrão 50, máx. 1000). Requer o apps-view capacidade e pacote API 1.11.9+. O texto do registro é redigido para segredos comuns (mesma política de MCP AppLogs desde API 1.11.5+).

Exemplos REST (curl)

Defina seu URL base e token API (de cipi api token create):

exportar CIPI_API_URL="https://api.myserver.com"
exportar CIPI_API_TOKEN="seu token do santuário"

Listar aplicativos (sincronizar, 200):

curl -sS "${CIPI_API_URL}/api/apps" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Aceitar: aplicação/json"

Status do servidor (sincronizar, requer status-view):

curl -sS "${CIPI_API_URL}/api/status" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}"

Registros de aplicativos (sincronizar, requer apps-view, API 1.11.9+):

curl -sS "${CIPI_API_URL}/api/apps/myapp/logs?type=deploy&page=1&per_page=50" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Aceitar: aplicação/json"

Crie um aplicativo Laravel Octane (assíncrono, API 1.13.0+ / Cipi 5.0+; requer apps-create):

curl -sS -X POST "${CIPI_API_URL}/api/apps" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Aceitar: aplicação/json" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -d '{
    "domínio": "loja.exemplo.com",
    "repositório": "git@github.com:you/shop.git",
    "ramo": "principal",
    "octane": verdadeiro,
    "motor": "mariadb"
  }'

Enviar "octane": "frankenphp" para o mesmo efeito. Omitir octane para clássico PHP-FPM. Usar "engine": "pgsql" quando PostgreSQL estiver instalado (API 1.12.0+ / Cipi 4.8+).

Aplicativo .env (sincronizar, API 1.14.0+ / Cipi 5.0.3+; requer apps-env):

curl -sS "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}"

curl -sS -X PUT "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -d '{"set":{"APP_DEBUG":"false"},"unset":["LEGACY_KEY"]}'

Artisan / execução do aplicativo (trabalhos assíncronos, API 1.14.0+; habilidades apps-artisan / apps-run):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/artisan" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -d '{"comando":"cache:limpar"}'

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/run" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -d '{"comando":"composer instalar --no-dev"}'

curl -sS "${CIPI_API_URL}/api/run-commands" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}"

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

Implantar um aplicativo (assíncrono, 202 + job_id):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/deploy" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Aceitar: aplicação/json"

# poll until completed
curl -sS "${CIPI_API_URL}/api/jobs/JOB_ID" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}"

Backup de banco de dados (assíncrono, dbs-manage) — retorna um caminho de backup real em o trabalho result, não um dump anônimo (veja Anonimizador de agente):

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}"

Integração de host (sudoers)

O painel API funciona como www-data e executa comandos Cipi CLI via sudo usando /etc/sudoers.d/cipi-api - uma lista branca explícita de cipi subcomandos. As credenciais Vault e MariaDB permanecem dentro de Cipi, não em PHP.

• GET /api/dbs - corre sudo cipi db list (sincronizar). Requer Cipi 4.4.17+ (migração adiciona cipi db … para sudoers). Sem isso: sudo: a terminal is required. Lista/motores multi-motores precisam de Cipi 4.8+ / API 1.12.0+.
• GET /api/status / MCP ServerStatus - prefiro sudo cipi status (API 1.11.8+); fallback de leitura de host quando sudo falha (inclui 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) na lista de permissões de sudoers (migração 5.0.6 cria o arquivo de lista branca de IP padrão e regenera /etc/sudoers.d/cipi-api ligado cipi self-update).
• Desde Cipi 5.0.3+ / API 1.14+: app env, app artisan, app run, auth create|edit|show|deletee deploy-config na lista de permissões de sudoers (migração regenera /etc/sudoers.d/cipi-api ligado cipi self-update).
• Trabalhos assíncronos — cipi app (incluindo --octane / --engine), deploy, alias, www, ssl / ssl force, db create|delete|backup|restore|password|engines, etc.

Depois cipi self-update, corra cipi api fix-permissions se /docs ou /mcp retorne HTTP 500 (veja solução de problemas acima).

Lista de permissões de IP (CLI)

Desde Cipi 5.0.6+, restrinja os clientes do painel API e MCP por IP de origem. Arquivo padrão /etc/cipi/api-ip-whitelist é * (permitir tudo). Um endereço IPv4/IPv6 ou CIDR por linha (ou separado por vírgula --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

Equivalentes REST residem em /api/ip-whitelist (API 1.15.0+). PUT adiciona automaticamente o IP do chamador ao restringir a lista, a menos que ensure_client_ip: false.

Arrogância / OpenAPI

A documentação interativa está disponível em /docs (IU do Swagger). A especificação OpenAPI é gerado a partir de public/api-docs/openapi.json e abrange aplicativos (incluindo suspensão, cancelar suspensão, renomear domínio, autenticação básica,.env, Composer auth.json, Artisan / trabalhos de execução de aplicativo, implantação de configuração, logs paginados, redirecionamentos www, Octane criação e multimotor engine), aliases, implantação, SSL (instalar + forçar HTTPS), bancos de dados (lista de motores + opcional engine em mutações), status do servidor, pesquisa de trabalho com estruturado result tipos e esquemas de ferramentas MCP. Versão atual do pacote API: 1.20.

MCP servidor

Um MCP O servidor (Model Context Protocol) é exposto em /mcp através de Transmissível HTTP. Desde o pacote API 1.11.1+, um token com omcp-access habilidade é suficiente para tudo MCP ferramentas — REST por endpoint habilidades (apps-view, deploy-manage, apps-basicauth, www-manage, etc.) não estão marcados /mcp. O servidor expõe Mais de 50 ferramentas para aplicativo, alias, www, banco de dados, implantação, SSL, HTTP Autenticação Básica, gerenciamento de servidores (PHP, SSH, serviços, SMTP, integridade, lista de permissões 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 - enquete com JobShow (API 1.11.0+). Ações básicas de autenticação e ferramentas somente leitura são executadas de forma síncrona.

• Aplicações: AppList, AppShow, AppCreate (opcional engine, octane), AppEdit, AppSuspend, AppUnsuspend, AppDelete, AppDeploy, AppDeployRollback, AppDeployUnlock, AppArtisan (Laravel somente aplicativos; rejeita aplicativos personalizados e tinker), AppEnvShow, AppEnvUpdate, AppAuthJson*, AppRun, AppRunCommands, AppDeployConfigShow, AppDeployConfigUpdate, AppWebhookRecreate (API 1.15.0+ / Cipi 5.0.6+; ferramentas de aplicativos anteriores requerem API 1.14.0+ / Cipi 5.0.3+)
• Gerenciamento de servidor: PhpList, IpWhitelistShow (API 1.15.0+ / Cipi 5.0.6+)
• HTTP Autenticação básica: AppBasicAuthStatus, AppBasicAuthEnable, AppBasicAuthDisable
• Aliases: AliasList, AliasAdd, AliasRemove
• WWW / ápice: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear (API 1.12.0+)
• Bancos de dados: DbEngines, DbList, DbCreate, DbDelete, DbBackup, DbRestore, DbPassword (opcional engine ligado lista/mutações; API 1.12.0+)
• SSL: SslInstall, SslForce (API 1.12.0+)
• Trabalhos e registros: JobShow (pesquisar status do trabalho assíncrono, analisado resulte saída CLI), AppLogs (registros recentes de aplicativos por tipo: all, nginx, php, worker, deploy, laravel - o mesmo que cipi app logs; Equivalente REST: GET /api/apps/{name}/logs desde API 1.11.9+), ApiLogShow (registros Laravel recentes para o host API do painel)
• Monitoramento de servidor: ServerStatus (correspondência JSON estruturada GET /api/status / cipi status), ServiceList (status de serviço do sistema via cipi service list)

Desde Cipi 4.6.3, o pacote do painel API é atualizado suavemente todas as noites às 04:30 através de /etc/cron.d/cipi-api (cipi api update), então MCP e os endpoints REST permanecem atualizados sem intervenção manual.

Instalando o servidor MCP

O endpoint MCP é opcional e carrega somente quando o pacote MCP necessário está instalado. Para usá-lo de Código VS, Cursor, ou Claude Desktop:

1. Configure o API com cipi api <domain> e cipi api ssl
2. Crie um token com cipi api token create e selecione pelo menos mcp-access
3. Adicione o servidor MCP à configuração do seu cliente (veja abaixo)

Cursor

Adicionar a ~/.cursor/mcp.json (ou Cursor → Configurações → MCP):

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

O cursor se conecta nativamente através de HTTP — sem necessidade de ponte.

Código VS

VS Code (com GitHub Copilot) suporta MCP nativamente desde 1.102. Adicionar a .vscode/mcp.json ou correr MCP: Abra a configuração do usuário para uma configuração global. Usar inputs para solicitar o token uma vez e armazená-lo com segurança:

{
  "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 o VS Code após salvar. Usar MCP: Adicionar servidor na paleta de comandos para um configuração guiada.

Código Claude

Adicione o servidor MCP diretamente do CLI:

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

Claude Desktop

Claude Desktop requer o mcp-remoto bridge para converter stdio em HTTP. Adicionar a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou o equivalente caminho de configuração no seu sistema operacional:

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

Instalar mcp-remote uma vez com npm install -g mcp-remote.

Substituir <your-api-domain> com seu domínio API (ex. api.myhosting.com) e <your-token> com o token criado na etapa 2.

Módulo WHMCS

Um oficial Módulo de provisionamento WHMCS está disponível em github.com/cipi-sh/whmcs. Ele une o ciclo de vida de provisionamento WHMCS ao Cipi REST API — automatizando a criação de aplicativos, exclusão, certificados SSL, implantações e alterações de configuração para seus clientes de hospedagem. Sem dependências Composer; o módulo é um drop-in independente.

Requisitos

• WHMCS 8.x (módulo de provisionamento tipo “Servidor”)
• Servidor Cipi com API habilitado: cipi api <domain> e cipi api ssl
• Token de Portador do Santuário com as habilidades necessárias:

Instalação

1. Copiar modules/servers/cipi/ em sua raiz WHMCS:

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

2. Em Administrador WHMCS → Configurações do sistema → Servidores → Adicionar novo servidor:
   • Tipo: Cipi (Laravel hospedagem)
   • Nome do host: API URL base (por exemplo https://api.example.com, não barra final)
   • Senha: Token ao portador de cipi api token create
   • Seguro: Sim (recomendado — permite a verificação TLS)
3. Crie um produto de hospedagem vinculado a este servidor e configure Módulo Configurações:

Tipos de aplicativos

Ciclo de vida de provisionamento

Suspender / Cancelar suspensão exigir Cipi 4.5.8+ (suspender/cancelar a suspensão endpoints), o pacote API 1.8.1+, e um token com o apps-suspend habilidade. A suspensão troca o vhost do aplicativo por uma página de manutenção genérica HTTP 503; sem suspensão o restaura.

Botões de administração

Na visualização do serviço administrativo WHMCS, os operadores podem acionar ações com um clique:

Auto-SSL na criação

Habilitar Automático SSL nas configurações do módulo do produto para instalar automaticamente um Vamos criptografar o certificado logo após o provisionamento. Se a instalação do SSL falhar, o aplicativo será ainda criado com sucesso e um aviso é registrado.

Cliente API completo

O pacote CipiApiClient cobre toda a superfície Cipi REST API. Mesmo que seja uma característica não está conectado a um gancho WHMCS, você pode usar o cliente em ganchos ou complementos personalizados:

Estendendo o módulo

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

$client = novo CipiApiClient('https://api.exemplo.com', $token);
$client->addAlias('meu aplicativo', 'alias.exemplo.com');

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

// Example: backup a database
$client->backupDatabase('meu aplicativo');

Comportamento voltado para o cliente

O módulo faz não adicione uma guia Área do cliente, botões personalizados ou status ao vivo em Cipi. Os clientes veem a visualização padrão do serviço WHMCS (domínio, status, datas de renovação). Quando Cipi provisiona um aplicativo, ele gera segredos únicos (senha SSH, banco de dados senha, chave de implantação, webhook URL). O REST API não envia automaticamente esses segredos para o WHMCS — você deve estender o módulo, escrever um gancho ou entregar credenciais por meio de seu fluxo de trabalho de suporte.

Registro de módulo

Todas as API chamadas são registradas via logModuleCall() — Criar, encerrar, alterar pacote, SSL, Implantar, Reverter, Desbloquear e Informações do aplicativo. Habilitar Utilitários → Logs → Módulo Registro no WHMCS Admin para visibilidade total.

cipi sync

Transfira, replique e faça backup de Laravel aplicativos inteiros entre Cipi servidores — incluindo configuração, dumps de banco de dados, arquivos de armazenamento, chaves SSH, trabalhadores e crontabs. Todo arquivo é criptografado com AES-256-CBC e protegido por uma senha definida pelo usuário, então credenciais e os dados confidenciais estão seguros em repouso e durante a transferência.

Visão geral dos 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

Criptografia de arquivo

Todos os arquivos de sincronização são criptografado por padrão com AES-256-CBC. Durante a exportação você está será solicitada uma senha (mínimo de 8 caracteres) que proteja o arquivo. A mesma senha é necessário importá-lo ou inspecioná-lo. Isso protege as chaves SSH, .env arquivos, despejos de banco de dados, e credenciais em repouso e durante a transferência.

# 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

Empacota configurações de aplicativos em um arquivo criptografado .tar.gz.enc arquivo. Opcionalmente inclui banco de dados dumps e arquivos de armazenamento.

# 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"

O que vai para o arquivo

Além de configurações globais: apps.json (filtrado para aplicativos selecionados), databases.json, backup.json, api.json.

Importar

Restaura aplicativos de um arquivo para o servidor atual.

# 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"

O que a importação faz para um NOVO aplicativo

Quando um aplicativo não existe no servidor de destino, a importação o cria do zero — equivalente a cipi app create com todas as configurações pré-preenchidas do arquivo:

1. Usuário Linux — Cria um novo usuário com uma senha aleatória
2. Diretórios - Cria /home/<app>/shared/, logs/, .ssh/, .deployer/
3. Chave de implantação SSH — Restaura do arquivo (a mesma tecla funciona com GitHub/GitLab sem reconfiguração)
4. MariaDB banco de dados — Cria banco de dados + usuário com um novo aleatório senha
5. Dados do banco de dados— Importa o dump se --with-db foi usado durante exportar
6. .env— Cópias do arquivo, então substitui DB_PASSWORD, DB_USERNAME, DB_DATABASE, DB_HOST com os valores do novo servidor. Todo o resto (APP_KEY, MAIL_*, REDIS_*, vars personalizados) permanece como está
7. Pool de PHP-FPM, Nginx vhost, Supervisor trabalhadores, Crontab, Deployer- Totalmente configurado a partir de dados de arquivo

Verificações de segurança antes da importação

A importação executa verificações pré-voo antes de tocar em qualquer coisa:

• O aplicativo já existe - bloqueado, a menos que --update é passado
• Conflito de domínio — bloqueado se outro aplicativo já usa o mesmo domínio
• Versão PHP ausente — aviso (o aplicativo foi ignorado; instale a versão primeiro com cipi php install)

Modo de atualização (--update)

A principal característica para sincronização repetida (por exemplo, replicação de failover). Sem --update, a importação se recusa a tocar em aplicativos que já existem. Com --update, isso atualizações aplicativos existentes e cria novos.

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

O que a atualização faz para um aplicativo existente

• .env sincronizar - O arquivo .env substitui o local, mas DB_PASSWORD, DB_USERNAME, DB_DATABASEe DB_HOST são preservado do servidor local. Todo o resto (APP_KEY, MAIL_*, REDIS_*, vars personalizados) vem do fonte.
• Dados do banco de dados — Se o arquivo tiver um dump, elimina todas as tabelas (com SET FOREIGN_KEY_CHECKS=0) e reimportações. Usa credenciais raiz locais.
• Armazenamento — Se o arquivo tiver armazenamento, extrai sobre o diretório existente (novo arquivos adicionados, existentes sobrescritos).
• migração de versão PHP — Se a fonte usar uma versão PHP diferente, a atualização migra pool FPM, supervisor, crontab, implantador e .env automaticamente.
• Nginx vhost, Supervisor trabalhadores, configuração do Deployer — Regenerado do arquivo dados.
• Implantar - Se --deploy é passado, corre dep deploy para puxar código mais recente.

Qual atualização NÃO muda

• Senha de usuário Linux
• Chaves de implantação SSH (mantidas desde a primeira importação)
• MariaDB credenciais do usuário (o destino mantém as suas próprias)
• SSL certificados (executar cipi ssl install separadamente)

Lista (inspecionar arquivo)

Veja o que está dentro de um arquivo sem importar nada.

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

Cipi Sincronizar arquivo
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Cipi v5.1.0
  Exportado 2026-03-06T15:00:00Z
  Fonte aws01 (3.120.xx.xx)
  Banco de dados verdadeiro
  Armazenamento verdadeiro
 
  Aplicativos
  DOMÍNIO DO APLICATIVO PHP ARMAZENAMENTO DE BD
  loja shop.example.com 8.4 sim sim
  blog blog.example.com 8.4 sim sim
  api api.example.com 8.5 sim sim
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Push (exportação + transferência + importação)

Combina exportação, transferência rsync e importação remota em um comando. Funciona inteiramente a partir do fonte 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"

Como funciona o push

1. Etapa 1: Corre cipi sync export localmente (criptografa com senha)
2. Etapa 2: Transfere o arquivo criptografado para o destino via rsync
3. Etapa 3: Se --import é passado, corre cipi sync import --update --yes no destino via SSH

Push sempre adiciona --update e --yes ao chamar import no controle remoto. Isto significa: a primeira execução cria todos os aplicativos, as execuções subsequentes os atualizam gradativamente. Isto é o que faz empurrar seguro para executar repetidamente via cron.

Configuração SSH para push

O servidor de origem precisa de acesso SSH ao destino como o cipi usuário. Use o integrado mecanismo de confiança para autenticação sem senha e baseada em chave 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

Uma vez confiável, cipi sync push se conecta como o cipi usuário automaticamente — nenhum acesso root é necessário.

Cenários práticos

Cenário 1: Migrar todas as aplicações da AWS para a OVH

Você tem 20 aplicativos na AWS. Comprou um OVH VPS e instalou Cipi nele.

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

No target OVH: 20 utilizadores Linux, 20 bases de dados, 20 nginx vhosts, pools PHP-FPM, supervisor configs, crontabs – todos criados automaticamente. Dados de banco de dados importados, armazenamento extraído, .env arquivos copiado com as senhas do banco de dados OVH, chaves de implantação SSH preservadas (as mesmas chaves funcionam com GitHub). Depois importar, instale SSL e atualize DNS:

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

Cenário 2: replicação de failover agendada (cron)

A cada 6 horas, o Servidor 1 sincroniza todos os aplicativos com o Servidor 2. Se o Servidor 1 morrer, altere DNS e entre no ar 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

A janela de perda de dados é igual ao intervalo cron (6 horas neste exemplo). Quando o Servidor 1 cair: mude DNS para o Servidor 2, execute cipi ssl install para cada aplicativo e você estará ativo.

Cenário 3: replicar para vários 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

Cenário 4: Backup criptografado diário (sem transferência)

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

Cria um arquivo portátil criptografado todas as noites. Restaure em qualquer servidor Cipi a qualquer momento com cipi sync import.

Limitações

• SSL certificados não estão incluídos no arquivo. Corre cipi ssl install após importar em um novo servidor.
• A sincronização do banco de dados é uma substituição completa, não incremental. Cada atualização elimina todas as tabelas e reimportações.
• A sincronização de armazenamento é uma extração completa, não rsync incremental. Arquivos excluídos no fonte permanecer no alvo.
• Implantar chaves são iguais na origem e no destino — sem GitHub/GitLab reconfiguração necessário.

Cofre e criptografia

Cipi criptografa todos os arquivos de configuração em repouso usando AES-256-CBC. O sistema do cofre fornece criptografia e descriptografia transparentes para que dados confidenciais — senhas de banco de dados, API fichas, Chaves SSH, .env conteúdo — nunca é armazenado em texto simples no disco.

Arquitetura

O sistema é construído em duas camadas:

• Cofre — criptografia transparente de arquivos de configuração JSON no disco (server.json, apps.json, databases.json, backup.json, smtp.json, api.json)
• Sincronizar criptografia — criptografia baseada em senha de arquivos de exportação para segurança transferência entre servidores

Como funciona o Vault

Uma chave mestra é gerada durante a instalação com openssl rand -base64 32 e armazenado em /etc/cipi/.vault_key (chmod 400, somente root). Cada arquivo de configuração JSON é criptografado no disco com openssl enc -aes-256-cbc -salt -pbkdf2. Os arquivos mantêm o .json extensão — o conteúdo é simplesmente um blob criptografado em vez de JSON legível.

O vault_read função detecta automaticamente se um arquivo é de texto simples ou criptografado (backward compatibilidade), para que os servidores existentes migrem perfeitamente durante a atualização.

Funções do cofre

# 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

Projeção pública

Cipi gera um apps-public.json arquivo contendo apenas campos não confidenciais (domínio, aliases, versão PHP, branch, repositório, usuário, carimbo de data e hora de criação, mais suspended e basic_auth bandeiras). O cipi-api leituras em grupo esta projeção de texto simples em vez do arquivo criptografado, mantendo a chave do vault restrita ao root.

Sincronizar criptografia de arquivo

Quando você corre cipi sync export, as configurações são descriptografadas do vault para uma área de teste, então, todo o arquivo é criptografado com sua senha. Na importação, o arquivo é descriptografado com a senha e as configurações são criptografadas novamente com o cofre do servidor de destino chave.

Notificações por e-mail

Cipi pode enviar alertas por e-mail quando ocorrerem erros de backup, falhas de implantação, falhas de trabalho do sistema cron ou ocorrem eventos de autenticação relevantes para a segurança. A configuração SMTP é armazenada criptografada em /etc/cipi/smtp.json e incluído na sincronização exportações.

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

Gatilhos de notificação granulares

Desde v4.6.3, você poderá controlar quais eventos enviam emails quando o SMTP estiver configurado. Todos os gatilhos são ativado por padrão; eventos são sempre registrados /var/log/cipi/events.log sem considerar.

$ 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)

Configuração: /etc/cipi/notifications.json. Corre cipi notifications list no servidor para o estado ligado/desligado ao vivo. IDs de gatilho para cipi notifications enable|disable <trigger>:

v5.1.0 adiciona cinco: backup_stale (um perfil não teve sucesso dentro duas vezes o seu próprio intervalo), ini_set (uma configuração PHP alterada), yml_apply e yml_fail (um projeto cipi.yml foi aplicado ou era inválido), e self_update (Cipi se atualizou — portanto, uma atualização noturna autônoma não chega mais sem uma palavra).

Alertas automáticos

Uma vez configurado, Cipi envia notificações por email em:

• Erros de backup (S3 falhas de upload, erros de dump, arquivo corrompido) e, desde v5.1.0, backups que são simplesmente atrasado (backup_stale)
• Implantar resultados - desde v5.1.0 tanto sucesso efalha, desde CLI e o Git webhook, com o branch, número de lançamento, commit, autor, duração e o veredicto de verificação de saúde pós-implantação no corpo
• Um lançamento que falhoupós-implantação verificação de saúde (deploy_health_fail), incluindo o que é uma reversão automática fiz sobre isso
• Falhas de trabalho do sistema cron (por meio do cipi-cron-notify invólucro)
• Eventos do ciclo de vida do aplicativo — notifica quando um aplicativo é criado, editado ou excluído, incluindo nome de host do servidor, nome do aplicativo, domínio e versão PHP
• Sudo e su elevação — notifica quando qualquer usuário eleva com sucesso via sudo ou su, incluindo quem o executou, usuário alvo (por su), Chave SSH, IP do cliente e TTY
• Login SSH privilegiado — notifica quando root ou qualquer sudoer efetua login via SSH, incluindo IP de origem, impressão digital da chave SSH e comentário principal
• Mudanças na chave SSH — notifica quando uma chave SSH é adicionada, removida ou renomeada no cipi usuário, incluindo nome do host, IP, impressão digital, comentário principal, carimbo de data/hora e contagem de chaves restantes. Os alertas de renomeação também incluem o nome da chave antiga e a nova.

Cada notificação por e-mail inclui um rodapé com o IP do cliente (SSH_CLIENT) e o SSH nome da chave usada para autenticação, quando aplicável. O nome da chave é resolvido via SSH_USER_AUTH com um auth.logsubstituto quando necessário.

Notificações de autenticação de segurança

Cipi integra notificações de autenticação baseadas em PAM via pam_exec.so com ExposeAuthInfo habilitado. Quando o SMTP é configurado, o O sistema envia automaticamente alertas por e-mail sobre estes eventos relevantes para a segurança:

• Sudo e su elevação — acionado quando qualquer usuário é executado com sucesso sudo ou su. A notificação inclui o nome de usuário, usuário alvo (por su), o TTY, a chave SSH, o IP do cliente e o carimbo de data/hora.
• Login SSH privilegiado - acionado quando root ou qualquer usuário no sudo grupo faz login via SSH. A notificação inclui o nome de usuário, IP de origem endereço, impressão digital da chave SSH e comentário da chave (resolvido em /var/log/auth.log correspondência de impressão digital com authorized_keys).
• Mudanças de chave SSH — acionado quando uma chave SSH é adicionada, removida ou renomeado nocipi usuário via cipi ssh add, cipi ssh remove, ou cipi ssh rename. A notificação inclui o nome do host, IP do servidor, impressão digital da chave, comentário da chave, carimbo de data/hora e contagem de chaves restantes. Renomear os alertas também incluem o nome da chave antiga e a nova.
• Eventos do ciclo de vida do aplicativo – acionado quando um aplicativo é criado, editado ou excluído. A notificação inclui o nome do host do servidor, o nome do aplicativo, o domínio e a versão PHP.

As notificações são executadas de forma assíncrona em segundo plano para que nunca atrasem o login ou o comando execução. Se o SMTP não estiver configurado, os ganchos falharão silenciosamente, sem impacto no sistema.

Log de eventos de segurança

Independentemente da configuração do SMTP, todos os eventos de notificação (alterações de chave SSH, ciclo de vida do aplicativo, redefinições de senha, login sudo/su/SSH, falhas cron) são sempre registrados /var/log/cipi/events.log em um formato compacto de uma linha. O log é girado diariamente com Retenção de 1 ano via logrotate.

Cron embalagem

O cipi-cron-notify utilitário envolve os trabalhos cron do sistema e envia uma notificação se o trabalho sai com um código diferente de zero. Isto é útil para monitorar tarefas agendadas críticas.

Retenção de registros (GDPR)

Cipi aplica políticas de rotação automática de logs projetadas para atender ao GDPR e à proteção geral de dados requisitos. Os logs são alternados e excluídos automaticamente, sem necessidade de limpeza manual.

Valkey

Valkey é o armazenamento de dados na memória que Cipi instala como parte da pilha padrão. Desde v4.5.6 Cipi disposições Valkey em vez de redis-server. É excelente em cache, armazenamento de sessão, filas de mensagens, tempo real transmissão e limitação de taxa.

Por que Valkey em vez de Redis

Valkey é o verdadeiramente open-source, licenciado por BSD garfo de Redis, dirigido pelo Fundação Linux. Foi criado em 2024 depois que Redis Inc. relicenciado Redis da licença BSD permissiva ao SSPL/RSALv2 disponível na fonte — uma mudança que não atendia mais a definição open-source. Apoiado pela AWS, Google Cloud, Oracle e uma grande comunidade, Valkey continua a mesma base de código testada em batalha sob uma licença que permanece livre para sempre. Isso o torna perfeito para o MIT de Cipi, filosofia de não dependência de fornecedor, e é fornecido nativamente no repositório Universe do Ubuntu 24.04 (pacotes valkey-server + valkey-tools) – nenhum PPA de terceiros em quem confiar.

Tão importante quanto, Valkey é um substituição imediata: fala exatamente o mesmo RESP protocolo na mesma porta (127.0.0.1:6379), homenageia o mesmo requirepass / bind diretivas e lê o mesmo formato de dados RDB/AOF. Seu aplicativos precisam zero alterações - o phpredis extensão e seu existente REDIS_* .env os valores continuam funcionando exatamente como antes.

Como Cipi implementa isso

• Instalar — setup.sh instala e configura Valkey (/etc/valkey/valkey.conf, serviço valkey-server), vinculado a localhost somente e protegido por senha.
• Gerenciamento de serviços — cipi service … gerencia valkey-server (os nomes redis-server, redise valkey ainda são aceitos como apelidos). É adicionado às atualizações autônomas lista negra, então Cipi gerencia-a em vez de uma atualização automática.
• Credenciais - armazenado sob valkey_user / valkey_password em /etc/cipi/server.json (o legado redis_* as chaves ainda são lidas como um substituto). Host: 127.0.0.1, Porta: 6379.
• Redefinição de senha — cipi reset valkey-password regenera o senha e reinicia o serviço (cipi reset redis-password permanece como um alias).

Migrando de Redis (4.5.6 / 4.5.7)

Os servidores existentes são alterados para Valkey automaticamente em cipi self-update - sem aplicativo .env edição necessária. A migração reutiliza a senha Redis atual (recuperada de server.json ou /etc/redis/redis.conf), força um RDB SAVE e instantâneos dump.rdb/AOF, purges redis-server, instala valkey-server + valkey-tools na mesma porta com o mesmo requirepass / bind, restaura o conjunto de dados e reescreve server.json (redis_* → valkey_*) e as atualizações autônomas lista negra – para que o cache, as sessões e os trabalhos em fila sobrevivam à mudança.

v4.5.7 corrige o nome do pacote para valkey-server (o Ubuntu 24.04 pacote daemon; 4.5.6 inicialmente usado valkey) e faz a migração totalmente independente e seguro. Ele habilita automaticamente o universe componente APT quando a embalagem não for encontrado, executa uma verificação de integridade pós-início (PING → PONG com o senha) e reverte para redis-server - restaurando os salvos senha e o conjunto de dados - se Valkey não puder ser instalado ou não estiver íntegro. O conjunto de dados o snapshot é mantido até que o switch seja verificado e depois limpo. A migração é idempotente: servidores já em Valkey pule.

Laravel integração

Adicione essas variáveis ao seu .env através de cipi app env myapp. Os nomes das variáveis fique REDIS_* - é isso que phpredis e Laravel's redis driver espera e Valkey responde no mesmo soquete:

REDIS_HOST=127.0.0.1
REDIS_SENHA=sua-senha-do-servidor-json
REDIS_PORT=6379

Em seguida, defina os drivers para cada caso de uso:

• Cache — CACHE_STORE=redis
• Sessão — SESSION_DRIVER=redis
• Fila — QUEUE_CONNECTION=redis (então cipi worker restart myapp)
• Transmissão — BROADCAST_CONNECTION=redis

Instale o phpredis Extensão PHP para melhor desempenho ou usepredis/predis como um substituto puro PHP. Ambos conversam com Valkey de forma transparente.

Autoatualização

Cipi pode ser atualizado a partir de GitHub sem afetar nenhum aplicativo, banco de dados ou configuração.

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

Processo de atualização

1. Baixa a versão mais recente de GitHub
2. Faz backup da instalação atual para /opt/cipi.bak.YYYYMMDDHHMMSS/
3. Substitui scripts CLI e lib
4. Executa qualquer pendência scripts de migração em ordem (por exemplo, novas diretivas Nginx, novas pacotes)
5. Atualiza o arquivo de versão

Os scripts de migração residem em lib/migrations/ e são nomeados por versão (por ex. 4.1.0.sh, 5.0.18.sh). Ao atualizar da v4.0.0 para a v4.2.0, Cipi é executado automaticamente 4.1.0.sh e 4.2.0.sh em ordem. Seus aplicativos, bancos de dados e configurações nunca são tocados.

As migrações recentes melhoram a confiabilidade sem alterar os dados do aplicativo: 5.0.6 — arquivo de lista de permissões de IP padrão e API sudoers regenerados; 5.0.9 — cipi php switch em sudoers para PUT /api/php/default; 5.0.13 — recuperar a propriedade de API/GUI após a atualização; 5.0.14–5.0.17 — atualizações de pacotes do painel GitHub/Packagist cronometradas (não mais travadas cipi self-update em clones API/GUI Composer VCS); 5.0.18— reparar Painel GUI após link simbólico/open_basedir HTTP 500 (cipi gui fix-permissions). Corre cipi self-update alcançar 5.1.0.

Migração 5.1.0

O 5.1.0 a migração é a maior da linha 5.x. Em um servidor existente:

• instala o wrapper de implantação automática e redireciona o webhook cron de cada aplicativo;
• preenche o CLI 99-cipi.ini e reescreve os pools FPM para que eles herdem o arquivo para todo o servidor - consulte cipi ini;
• converte a tarefa de backup noturno codificada em um default perfil de backup, transferindo o seu existente --weeks retenção;
• assume o agendamento de backup com o bloco crontab gerenciado;
• afirma o :443 servidor padrão quando nada mais acontece.

Cada passo se transforma em um aviso e continua. Isso importa: no início do 5.1.0, construa um grep que não correspondesse a nada poderia falhar na migração sob set -o pipefail, e uma migração falhada faz cipi self-update recusar a liberação e tentar novamente, falhando novamente, todas as noites.

Quando a atualização em si falha

Até 5.0.x, cipi self-update relatou apenas “Falha no download” - o stderr do git foi descartado, então a única mensagem que explica o que aconteceu (sem DNS, sem HTTPS de saída, faltando filial, um disco cheio, um pacote CA expirado) nunca chegou a ninguém. Desde v5.1.0 o o erro real é impresso, a causa provável é nomeada e o comando para reproduzi-lo manualmente é mostrado. O clone também é executado em um tempo limite de 180 segundos, em vez de poder travar indefinidamente, e um faltando git é relatado como tal. Uma atualização noturna autônoma agora também envia o self_update notificação, para que não chegue mais sem uma palavra.

Por exemplo, o 4.5.5 migração adapta aplicativos existentes com o novo ll='ls -al' alias do shell: anexa o alias a cada aplicativo ~/.bashrc uma vez (somente quando ausente, preservando a propriedade), para que os aplicativos criados antes da versão 4.5.5 sejam obtidos na próxima cipi self-update.

Crons de manutenção automática

Cipi agenda vários trabalhos de nível raiz durante a instalação. Crontabs no nível do aplicativo (agendador, implantação gatilho) são separados - consulte Crontab do usuário.

Domínios curinga

Cipi faz não suporta domínios curinga (*.myapp.com) nativamente. O O bloco é duplo e arquitetônico – não um detalhe de configuração.

Por que os curingas não são suportados

1 — Rejeições de validação de domínio *
Cada domínio passado para cipi alias add (e cipi app create) é validado contra um regex estrito que exige que a string comece com [a-zA-Z0-9]. O asterisco falha imediatamente, antes que nginx ou certbot sejam tocados.

2 — Certbot usa o desafio HTTP-01, que não pode emitir certificados curinga
cipi ssl install chamadas certbot --nginx, que depende do HTTP-01 (ou Desafio TLS-ALPN-01) — colocar um arquivo de verificação no disco e servi-lo pela porta 80. Vamos Encrypt apenas emite certificados curinga por meio do Desafio DNS-01, o que requer acesso programático ao DNS do seu provedor API. Cipi não se integra a nenhum provedor DNS, então mesmo que a validação fosse ignorada, o certbot se recusaria a emitir o certificado curinga.

Alternativa recomendada – certificado Multi-SAN

Se os seus subdomínios forem fixos e enumeráveis (por exemplo api, admin, www, staging), a abordagem correta é adicionar cada um como um explícito alias e deixe Cipi emitir um único certificado SAN cobrindo todos eles:

$ 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's --expand flag (usado internamente por Cipi) adiciona os novos SANs aos existentes certificado sem emitir um novo. A lista SAN não tem limite significativo para uso típico.

Certificado curinga manual (fora de Cipi)

Se você precisar de subdomínios dinâmicos (por exemplo, <tenant>.saas.com), você pode obter um curinga certificado manualmente usando um plugin DNS para certbot e coloque-o no servidor. Cipi não gerencie, renove ou rastreie - você possui inteiramente o ciclo de vida.

# 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"

Após obter o certificado, edite o nginx vhost do aplicativo diretamente (/etc/nginx/sites-available/myapp) para referenciar os caminhos do certificado curinga e adicionar server_name *.myapp.com myapp.com;. Em seguida, recarregue nginx:

$ nginx -t && systemctl reload nginx

Editar configuração Nginx

Para personalizar o vhost Nginx para um aplicativo, edite a configuração do site diretamente. Após as alterações, teste e recarregue Nginx.

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

Desinstalar Cipi

Cipi não fornece um comando de desinstalação integrado. Se você precisar remover completamente Cipi de um servidor, siga os passos abaixo em ordem. Este procedimento remove todos os componentes que Cipi instalações – usuários, serviços, pacotes, configurações e dados.

1 — Pare e remova todos os aplicativos

Para cada aplicativo gerenciado por Cipi, remova seu usuário do sistema, diretório inicial, banco de dados, nginx vhost, PHP-FPM piscina, e supervisor configuração.

# 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 — Remova o usuário e grupos Cipi

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

3 — Remova Cipi binários, bibliotecas e dados

$ 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 — Remova Cipi API (se 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 — Remover Cipi cron trabalhos

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

6 — Remova os arquivos de configuração 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 — Limpar pacotes instalados

Remova todos os pacotes que Cipi foram instalados. Ignore qualquer pacote que você deseja manter para outros fins.

$ 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 — Remover repositórios 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 — Remova Composer e Deployer

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

10 — Remover arquivo de troca

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

11 — Restaure os padrões SSH e PAM

Cipi fortalece o SSH (desativa o login root e a autenticação de senha) e adiciona ganchos PAM. Se você precisar restaurar padrões:

# 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 — Redefinir firewall

$ ufw disable
$ ufw reset