Infraestrutura

cipi php

PHP 8.5 é pré-instalado durante a configuração. Versões adicionais podem ser adicionadas a qualquer momento; desde v4.5.12 Cipi investiga fontes de APT por codinome Ubuntu — normalmente o ondrej/php PPA em 24.04, pacotes.sury.org em 26.04 quando o Launchpad não tem suíte, ou Ubuntu main como um último recurso (co-instalável 8.3–8.5 onde o repositório escolhido o suporta).

$ cipi php list              # list installed versions, status, and system default
$ cipi php install 8.4       # install an additional PHP version (8.3–8.5)
$ cipi php switch 8.4        # set system default (root/cipi, API pool)
$ cipi php remove 8.1        # remove a version, incl. legacy (blocks if default or apps use it)
$ cipi php upgrade           # apply security patches to all installed PHP packages

Atualizações de patches de segurança

Desde v4.7.13, PHP pacotes são excluídos de unattended-upgrades e gerenciado por Cipi. cipi php upgrade corre apt-get update e --only-upgrade em cada instalado php* e libphp* pacote e, em seguida, reinicia os pools PHP-FPM afetados. Quando o SMTP está configurado e pacotes foram atualizados, Cipi envia um e-mail (php_upgrade acionar; desabilitar com cipi notifications disable php_upgrade).

Uma verificação semanal é executada automaticamente em Domingo às 03h30 via root crontab (envolvido por cipi-cron-notify). Registro: /var/log/cipi/php-upgrade.log. Os servidores existentes recebem o cron em cipi self-update (migração 4.7.13).

Padrão do sistema versus PHP específico do aplicativo

O padrão do sistema é a versão PHP usada pelo root e cipi usuários, o pool FPM Cipi API e o trabalhador da fila API. Usar cipi php switch <ver> para mude isso. O comando migra o pool API (e o pool GUI FPM quando instalado), recria soquetes do painel e reinicia o trabalhador API. Desde 5.0.9+, PUT /api/php/default envolve isso através do painel API (php-manage habilidade). Desde 5.0.10–5.0.12, o switch tolera parcial update-alternatives sucesso, remonta raízes somente leitura quando necessário e mantém API/GUI Pools FPM na versão de destino para evitar nginx 502.

DESCANSO: GET /api/php, POST /api/php/install, DELETE /api/php/{version}, PUT /api/php/default (CLI 1.15.0+ / Cipi 5.0.6+). CLI Cipi: cipi php list --json (desde 5.0.6).

Cada aplicativo tem seu próprio Versão PHP (definida em app create ou através cipi app edit --php=). Implantador, Composer, gatilhos de implantação crontab e cipi sync import sempre execute com o PHP configurado do aplicativo - nunca o padrão do sistema.

Para mudar um aplicativo existente para uma versão diferente:

$ cipi app edit myapp --php=8.5

Isso troca a quente a versão PHP com tempo de inatividade zero: atualiza o pool FPM, soquete Nginx, Supervisor trabalhadores, crontab, configuração do Deployer e .env em uma operação atômica.

cipi db

Cipi cria um banco de dados dedicado para cada Cipi aplicativo automaticamente durante app create. Cipi (porto 3306) é o padrão nativo; desde v4.8.0 você também pode instalar opcional Laravel (porto 5432) e escolha um mecanismo por banco de dados ou aplicativo. Aplicativos personalizados não obtêm um banco de dados — usar cipi db create --name=<app> se você precisar de um (por exemplo, para WordPress ou outro CMS). Após a configuração, uma URL de conexão pronta para uso é exibida (MariaDB:mariadb+ssh://), combinando credenciais SSH, IP do servidor e informações de banco de dados para GUI clientes como TablePlus, DBeaver ou Sequel Pro.

Motores (v4.8.0+)

$ cipi db install pgsql              # install optional PostgreSQL
$ cipi db uninstall pgsql|mariadb    # remove a non-default engine (destroys data)
$ cipi db default mariadb|pgsql      # server-wide default when --engine is omitted
$ cipi db engines                    # installed engines, ports, and default

Ciclo de vida do banco de dados

$ cipi db create                              # interactive
$ cipi db create --name=analytics             # non-interactive (default engine)
$ cipi db create --name=analytics --engine=pgsql
$ cipi db list [--engine=mariadb|pgsql]       # list databases with sizes
$ cipi db backup myapp [--engine=…]
$ cipi db restore myapp backup.sql.gz [--engine=…]
$ cipi db password myapp [--engine=…]         # regenerate password
$ cipi db delete analytics [--engine=…]

Laravel aplicativos armazenam o mecanismo escolhido nos metadados do aplicativo; backup, sincronização e cipi app reset-db-password siga-o. Usar cipi app create --engine=pgsql (ou o prompt interativo) para provisionar um aplicativo Laravel em PostgreSQL — .env e o URL de conexão correspondem ao mecanismo. Redefinição de senha raiz: cipi reset db-password [--engine=].

cipi alias

Adicione vários domínios ou subdomínios a qualquer aplicativo. Depois de adicionar aliases, execute cipi ssl install provisionar ou renovar o certificado com cobertura SAN para todos domínios. Desdev4.8.0, cipi alias add|remove regenera o vhost e reaplica SSL com certbot install --redirect então HTTPS não é descartado.

$ cipi alias add myapp www.myapp.com
$ cipi alias add myapp myapp.it
$ cipi alias list myapp
$ cipi alias remove myapp myapp.it

Para redirecionamentos canônicos www ↔ apex, prefira cipi www em vez de gerenciar o host homólogo manualmente.

cipi www

Disponível desde v4.8.0. Gerencie aliases www/apex e redirecionamentos 301 canônicos para um aplicativo. Estado vive em apps.json (www_redirect); Nginx emite um sinal dedicado bloco de servidor de redirecionamento (caminho ACME mantido público) que sobrevive à regeneração do vhost. SSL é reaplicado através de certbot install --redirect.

$ cipi www add myapp              # add counterpart host (www ↔ apex)
$ cipi www force-to-root myapp    # 301 www.domain → domain
$ cipi www force-from-root myapp  # 301 domain → www.domain
$ cipi www clear myapp            # clear redirect state
$ cipi www status myapp           # inspect redirect state

force-to-root / force-from-root adicione automaticamente o alias ausente quando necessário.

cipi domains

Disponível desde v4.5.5. Um comando de nível superior que lista cada domínio e alias em tudo aplicativos em uma única tabela — a contrapartida global de o por aplicativo cipi alias list <app>. Ideal para auditar o todo mapeamento de domínio para aplicativo ou localização de um domínio que ainda não possui um certificado.

$ cipi domains   # list all domains and aliases across every app

Cada linha mostra as seguintes colunas:

Um rodapé resume os totais — número de domínios, aplicativos, certificados e aplicativos suspensos — fazendo é fácil auditar todo o mapeamento rapidamente.

cipi ssl

Certbot gerencia certificados Let's Encrypt. Os certificados são renovados automaticamente por meio de um cron semanal. cipi ssl status mostra datas de validade com avisos codificados por cores: verde (>30 dias), amarelo (14–30 dias), vermelho (<14 dias).

$ cipi ssl install myapp   # provision / renew — includes all aliases (SAN)
$ cipi ssl force myapp     # re-apply HTTP→HTTPS redirect (no new issuance)
$ cipi ssl renew            # force renewal of all certificates
$ cipi ssl status           # show all certs with expiry dates

# DNS-01 via Cloudflare (v5.0+) — wildcard certs
$ cipi ssl dns set --provider=cloudflare --token=YOUR_CF_TOKEN
$ cipi ssl install myapp --dns=cloudflare
$ cipi ssl install myapp --dns=cloudflare --wildcard

Desde v4.8.0, cipi ssl force <app> reaplica o HTTP → HTTPS redirecionar para um aplicativo que já possui um certificado Let's Encrypt — sem emitir um novo. cipi ssl install também define force_https em apps.json automaticamente.

Desde v5.0, opcional DNS-01 desafios via Cloudflare substituem o fluxo padrão HTTP-01 quando você precisar de certificados curinga ou não puder expor a porta 80. Configure uma vez com cipi ssl dns set, então passe --dns=cloudflare (e opcionalmente --wildcard) para cipi ssl install.

cipi backup

Faça backup de bancos de dados e armazenamento no Amazon S3 ou em qualquer provedor compatível com S3 (Hetzner Object Storage, Espaços DigitalOcean, Backblaze B2, MinIO, etc.).

Configuração

$ cipi backup configure
# → AWS Access Key ID
# → AWS Secret Access Key
# → Bucket name
# → Region
# → Endpoint URL (leave empty for AWS; required for other providers)

Pontos de extremidade compatíveis com S3

Executando backups

$ cipi backup configure              # configure S3 credentials
$ cipi backup run                    # backup all apps
$ cipi backup run myapp              # backup a single app
$ cipi backup list                   # list all backups
$ cipi backup list myapp             # list backups for one app
$ cipi backup prune myapp --weeks=4  # delete backups older than 4 weeks

Cada backup é carregado para s3://your-bucket/cipi/appname/YYYY-MM-DD_HHMMSS/ e contém:

• db.sql.gz — despejo de banco de dados compactado
• shared.tar.gz - o inteiro shared/ diretório (.env + storage/)

Desde v4.7.14, o teste de backup é padronizado como /var/tmp (disco) em vez de /tmp (geralmente um pequeno tmpfs com suporte de RAM), para que aplicativos grandes não falhem mais no meio do backup quando tmpfs é preenchido. Substituir por tmpdir em backup.json (definido através cipi backup configure) ou o CIPI_BACKUP_TMPDIR variável de ambiente.

Agendando backups automáticos

# Add to root crontab (crontab -e)
0 2 * * * /usr/local/bin/cipi backup run >> /var/log/cipi/backup.log 2>&1

Removendo backups antigos de S3

Os backups se acumulam com o tempo. Usar cipi backup prune para excluir pastas de backup anteriores a N semanas de S3. Execute-o como um trabalho cron junto com o próprio backup.

$ cipi backup prune myapp --weeks=4   # delete backups older than 4 weeks
$ cipi backup prune myapp --weeks=2   # keep only the last 2 weeks

Adicione ambos os comandos ao crontab raiz para serem executados automaticamente:

# root crontab — backup at 02:00, prune at 03:00 (keep 4 weeks)
0 2 * * * /usr/local/bin/cipi backup run myapp >> /var/log/cipi/backup.log 2>&1
0 3 * * * /usr/local/bin/cipi backup prune myapp --weeks=4 >> /var/log/cipi/backup-prune.log 2>&1

Crontab do usuário

Cipi adiciona automaticamente uma entrada crontab para o agendador Laravel quando um aplicativo é criado:

# installed automatically by cipi app create
* * * * * /usr/bin/php8.5 /home/myapp/current/artisan schedule:run >> /dev/null 2>&1

Esta entrada é executada como o myapp Usuário Linux a cada minuto, usando a versão PHP selecionada para o aplicativo. Ele é atualizado automaticamente quando você altera a versão de PHP via cipi app edit myapp --php=X.

Visualizando o crontab atual

# as root — view the app user's crontab
$ crontab -u myapp -l

# or after switching to the app user
$ su - myapp
myapp@server:~$ crontab -l

Adicionando jobs cron personalizados

Você pode adicionar tarefas cron extras ao crontab do usuário do aplicativo. Mude primeiro para o usuário do aplicativo para garantir empregos execute com o contexto de usuário e permissões de arquivo corretos:

$ su - myapp
myapp@server:~$ crontab -e

Entradas de exemplo que você pode adicionar:

# existing Laravel scheduler (do not remove)
* * * * * /usr/bin/php8.5 /home/myapp/current/artisan schedule:run >> /dev/null 2>&1

# nightly database backup at 2 AM
0 2 * * * /usr/local/bin/cipi db backup myapp >> /home/myapp/logs/backup.log 2>&1

# custom script every 15 minutes
*/15 * * * * /home/myapp/current/scripts/sync.sh >> /home/myapp/logs/sync.log 2>&1

Verificando se cron está funcionando

# check system cron log
$ grep CRON /var/log/syslog | grep myapp | tail -20

# check Laravel scheduler execution
$ cipi app artisan myapp schedule:list

cipi schedule

Desde v5.0, gerencie a entrada crontab do agendador Laravel que é executada schedule:run (o próprio crontab já existia; agora é alternável e rastreado em apps.json).

$ cipi schedule on myapp
$ cipi schedule off myapp
$ cipi schedule status myapp

cipi worker & Laravel Horizon

Cada aplicativo recebe um trabalhador padrão Supervisor para o default fila. Você pode adicionar adicionais filas com contagens e tempos limite de processos personalizados.

$ cipi worker add myapp --queue=emails --processes=3
$ cipi worker add myapp --queue=exports --processes=1 --timeout=7200
$ cipi worker list myapp
$ cipi worker edit myapp --queue=default --processes=3
$ cipi worker remove myapp emails
$ cipi worker restart myapp   # restart all workers for the app
$ cipi worker stop myapp      # stop all workers for the app (used during deploys)

# Laravel Horizon (v5.0+) — mutually exclusive with queue:work workers
$ cipi worker horizon enable myapp
$ cipi worker horizon status myapp
$ cipi worker horizon disable myapp

Com Horizon ativado, a implantação é executada horizon:terminate e reinicia trabalhadores através cipi-worker. Você não pode executar o clássico queue:work trabalhadores e Horizon no mesmo aplicativo de uma só vez.

Os trabalhadores são parados antes da troca do link simbólico e reiniciados após cada implantação, evitando Supervisor evite que fique obsoleto artisan caminhos. Supervisor está configurado com autorestart=unexpected então os trabalhadores só reiniciam em saídas inesperadas, não em saídas normais para.

Ajudante do usuário do aplicativo: cipi-worker

Cada usuário do aplicativo pode reiniciar, parar ou verificar trabalhadores sem root – por meio de um auxiliar sudo restrito instalado em /usr/local/bin/cipi-worker:

# run as the app user (SSH or sudo su - myapp)
$ sudo cipi-worker status myapp
$ sudo cipi-worker stop myapp      # used by Deployer before symlink swap
$ sudo cipi-worker restart myapp

Como root, use cipi worker list|restart|stop <app> em vez de. Não há cipi worker status comando de administração - usar cipi worker list ou o usuário do aplicativo ajudante acima.

cipi health

Desde v5.0, configure HTTP verificações de integridade por aplicativo. Um cron é executado a cada 5 minutos; depois 3 falhas consecutivas Cipi notifica através do health_fail acionador (SMTP quando configurado).

$ cipi health set myapp --url=https://myapp.com/up --expect=200
$ cipi health check myapp
$ cipi health list
$ cipi health unset myapp

# Structured output (v5.0.6+) — panel API / scripts
$ cipi health list --json
$ cipi health check myapp --json

DESCANSO: GET /api/health, GET|PUT|DELETE /api/apps/{name}/health, POST /api/apps/{name}/health/check (API 1.15.0+ / Cipi 5.0.6+).

cipi firewall

Cipi instala o UFW com as portas 22, 80 e 443 abertas por padrão. Use os comandos do firewall para gerenciar regras adicionais sem tocar diretamente no UFW.

$ cipi firewall allow 3306                  # open a port
$ cipi firewall allow 3306 --from=10.0.0.5  # allow from specific IP
$ cipi firewall allow 3306 --from=10.0.0.0/24 # allow from subnet
$ cipi firewall deny 8080                   # block a port
$ cipi firewall list                        # show all rules

cipi ban

Inspecione e gerencie banimentos de Fail2ban diretamente do CLI. Cipi configura Fail2ban com progressivo banimento: um banimento básico de 24 horas que dobra a cada reincidência até um limite de 7 dias, com máximo de tentativas reduzido para 3. Um dedicado recidive prisão proíbe reincidentes por 7 dias após 3 proibições dentro de 24 horas.

$ cipi ban list                        # list all banned IPs, grouped by jail
$ cipi ban unban 203.0.113.42           # unban a specific IP from all jails

cipi ban list

Lista todos os IP atualmente banidos pelo Fail2ban, agrupados por prisão (por exemplo, sshd, recidive). Útil para uma rápida verificação de segurança ou antes de cancelar o banimento.

cipi ban unban <IP>

Remove o IP fornecido de tudo Fail2ban prende imediatamente. Útil quando um usuário legítimo ou o CI runner é bloqueado por engano.

cipi service

Verifique e controle os serviços do sistema que alimentam Cipi diretamente do CLI. Nginx usa um estilo elegante recarregar (zero tempo de inatividade) em vez de uma reinicialização completa.

$ cipi service list                    # status of all services
$ cipi service list nginx              # status of a specific service
$ cipi service restart                 # restart all services
$ cipi service restart nginx           # graceful reload (zero downtime)
$ cipi service restart php             # restart all PHP-FPM versions
$ cipi service start fail2ban
$ cipi service stop supervisor         # asks for confirmation

# Structured output (v5.0.6+) — panel API
$ cipi service list --json

DESCANSO: GET /api/services, POST /api/services/{name}/restart (Cipi 1.15.0+ / Cipi 5.0.6+; habilidades services-view / services-manage).

Nomes de serviços suportados: nginx, mariadb, postgresql (apelidos: pgsql, postgres — quando instalado via cipi db install pgsql), valkey-server, supervisor, fail2ban, php<ver>-fpm (por exemplo php8.5-fpm). A palavra-chave php tem como alvo todas as versões PHP-FPM instaladas de uma só vez. Para o back-end do cache, redis-server, redise valkey são aceitos como apelidos de valkey-server.

Valkey — o fork licenciado pelo BSD e compatível com Redis — está incluído na pilha padrão e substitui redis-server desde Cipi 4.5.6. É instalado com uma senha, vinculada a localhost apenas, e suas credenciais (usuário, senha) são salvas em /etc/cipi/server.json e mostrado no final da instalação. valkey-server é adicionado à lista negra de atualizações autônomas - Cipi gerencia isso, então é não é atualizado automaticamente. Veja o Valkey seção para detalhes e a migração automática Redis → Valkey.

cipi ssh — Gerenciamento de chaves SSH

Gerencie as chaves SSH autorizadas para o cipi user — o ponto de entrada SSH do administrador. O cipi usuário (grupo cipi-ssh) usa apenas chave pública; o login root está desabilitado. Usuários do aplicativo (grupo cipi-apps) conecte-se com senha — consulte SSH como o usuário do aplicativo.

Comandos

$ cipi ssh list                 # list all authorized keys with fingerprint, comment, and current-session marker
$ cipi ssh add [key]             # add a new SSH public key (validates format, prevents duplicates)
$ cipi ssh remove [n]            # remove a key by number
$ cipi ssh rename [n] [name]     # change the display name / comment of a key

# Structured output (v5.0.6+) — panel API
$ cipi ssh list --json

DESCANSO: GET|POST /api/ssh/keys, DELETE /api/ssh/keys/{n} (API 1.15.0+ / Cipi 5.0.6+).

Mecanismos de segurança

cipi ssh remove inclui duas salvaguardas para evitar bloqueio:

• Proteção da sessão atual — você não pode remover a chave usada pelo seu SSH ativo sessão.
• Proteção de última chave — você não pode remover a última chave autorizada restante.

Comentários principais

As chaves SSH são armazenadas com seus comentários originais intactos, facilitando a identificação de cada chave pertence. Usar cipi ssh rename para alterar o nome de exibição de qualquer tecla:

# list keys to find the number
$ cipi ssh list

# rename key #2
$ cipi ssh rename 2 "john-macbook"

Notificações por e-mail

Quando o SMTP é configurado, Cipi envia um alerta por e-mail sempre que uma chave é adicionada, removida ou renomeada. A notificação inclui o nome do host do servidor, endereço IP, impressão digital da chave, comentário da chave, carimbo de data/hora, e contagem de chaves restantes. As notificações de renomeação também incluem o nome da chave antiga e a nova.

cipi — Servidor e autoatualização

Comandos de nível superior para status do servidor e autogerenciamento Cipi.

$ cipi status              # CPU, RAM, disk, services, PHP versions, apps
$ cipi version             # show installed Cipi version
$ cipi self-update         # update Cipi to the latest version
$ cipi self-update --check # check for updates without installing

Redefinição de senha e credencial

Cipi fornece comandos para regenerar senhas no nível do servidor. Novas senhas são armazenadas em /etc/cipi/server.json (criptografado via Vault) e exibido na tela. Salve-os imediatamente - eles são mostrados apenas uma vez.

$ cipi reset root-password              # regenerate the root Linux user SSH password
$ cipi reset db-password [--engine=…]   # regenerate root password (default or chosen engine)
$ cipi reset valkey-password           # regenerate the Valkey password and restart the service