Verwalten Sie Laravel Apps mit cipi.yml

Von Andrea Pollastri · Letzte Aktualisierung: 7. September 2026 · Kostenlose Lektüre, keine Paywall

Der Status, den eine App auf dem Server erwartet – Aliase, PHP, Worker, Gesundheit, Backups – liegt normalerweise in einem Panel oder im Kopf einer Person. Seit Cipi 5.1 kann es in einem leben cipi.yml im Stammverzeichnis des Repositorys, überprüft im selben Pull-Request wie der davon abhängige Code. Dieser Leitfaden stellt den praktischen Ablauf dar: Generieren, planen, anwenden und dann zustimmen, damit jede Bereitstellung in Einklang gebracht wird.

Warum die Datei neben den Code gehört

Eine Version, die einen Job in der Warteschlange ohne Worker hinzufügt, ist zur Hälfte ausgeliefert. Ein Rollback, das die letzte Woche verlässt upload_max_filesizewird zur Hälfte zurückgerollt. Der Serverstatus befindet sich normalerweise woanders: in einem Panel, einer Wiki-Seite oder in der Erinnerung desjenigen, der die Box eingerichtet hat.

A cipi.yml Wird neben der Laravel-Anwendung festgeschrieben, wird dieser Zustand zum Teil desselben Pull-Requests wie der davon abhängige Code. Die Datei ist deklarativ: Es beschreibt den Endzustand, nicht die Schritte. Cipi liest, was der Server hat, vergleicht es mit der Datei und zeigt Ihnen den Unterschied, bevor Sie etwas anfassen.

Starten Sie vom Live-Server

Sie müssen die Datei nicht von Hand schreiben. Drucken Sie auf einer Cipi 5.1+-Box die aktuelle Konfiguration der App – Aliase, PHP-Version und Pro-App-Einstellungen, zusätzliche Datenbanken, aus Supervisor, Horizon, Reverb zurückgelesene Warteschlangenarbeiter, den Scheduler und die Sicherungsprofile, die die App besitzt – als bereit zum Übertragen Datei:

$ cipi yml generate myapp > cipi.yml
$ cipi yml plan myapp                  # reports nothing to do

Übertragen Sie diese Datei im Repository-Stammverzeichnis. Cipi sucht nach current/cipi.yml, dann current/cipi.yaml, dann shared/cipi.yml – überschreiben mit --file=<path> wenn Sie es woanders aufbewahren.

Bevorzugen Sie eine leere, vollständig kommentierte Vorlage? cipi yml example myapp druckt eine mit Platzhalterdatenbanken und Profilen, die sich bereits im Namespace dieser App befinden, sodass die Vorlage unverändert validiert wird.

Die Befehle, die Sie verwenden werden

$ cipi yml generate myapp
$ cipi yml example myapp
$ cipi yml validate myapp
$ cipi yml plan myapp
$ cipi yml apply myapp [--yes]
$ cipi yml auto myapp on|off|status

Was Sie deklarieren können

Sieben Bereiche. Sie müssen nicht alle deklarieren – nur die Abschnitte, die Sie schreiben, werden abgeglichen.

• Aliase — Die deklarierte Liste ersetzt die aktuelle. Ein Alias, den Sie aus der Datei löschen, wird aus Nginx entfernt. Platzhalter wie z*.myapp.com werden akzeptiert. Die primäre Domäne wird hier nie verwaltet.
• PHP und php.ini — Fixieren Sie die App an PHP 8.3, 8.4 oder 8.5 (bereits auf dem Server installiert) und legen Sie Überschreibungen pro App fest: upload_max_filesize, post_max_size, memory_limit und der Rest. Serverweite Werte bleiben erhalten cipi ini set.
• Zusätzliche Datenbanken — über die mit der App erstellte hinaus, am MariaDB oder PostgreSQL. Anmeldeinformationen landen in shared/cipi-databases.env und werden niemals in das Repository zurückgeschrieben. Datenbanken werden erstellt und niemals gelöscht.
• Warteschlangenarbeiter und Horizon – Deklarieren Sie jede Warteschlange mit Prozessanzahl, Versuchen und Zeitüberschreitung, und Supervisor wird entsprechend abgeglichen. Oder einstellen horizon: true und lassen Sie Horizon die Warteschlangen besitzen. Seitdem 5.1.2, horizon: false wird tatsächlich gelesen – vorherfalse wurde wie ein fehlender Schlüssel behandelt.
• Laravel Reverb – seit 5.1.2, reverb: true Gibt der App einen Localhost-Port, ein Supervisor-Programm und einen nginx-Proxy für /app/{key} und /apps/{id}/… auf einer eigenen Domain und generiert REVERB_* Anmeldeinformationen. Nur Laravel Apps. Eine App, die bereits besitzt /app oder /apps kann diese Domain nicht mit Reverb teilen.
• Planer – eine boolesche Umdrehung * * * * * artisan schedule:run ein- oder ausschalten. Keine Crontab-Bearbeitung auf dem nächsten Server.
• Gesundheitscheck – eine HTTP-Prüfung auf einer der eigenen Domänen der App, die alle fünf Minuten und direkt nach jeder Bereitstellung erneut überprüft wird. Optional kann ein fehlerhaftes Release automatisch zurückgesetzt werden – nur der Code-Symlink; Migrationen werden nicht rückgängig gemacht.
• Sicherungsprofile – Pro-App-Profile mit eigenem Umfang, Zeitplan, eigener Aufbewahrung, eigenen Zielen und eigener Verschlüsselung. Namen müssen sein myapp oder myapp-*.

Eine vollständige Datei

Das ist es, was eine Produktions-App normalerweise ausliefert. Sie können das meiste davon generieren; Die Kommentare beziehen sich auf den Pull-Request.

version: 1

app:
  php: "8.5"
  aliases:
    - "www.myapp.com"
    - "*.myapp.com"
  ini:
    upload_max_filesize: 50M
    post_max_size: 60M
    memory_limit: 512M

databases:
  - name: myapp_reporting
  - name: myapp_analytics
    engine: pgsql

workers:
  horizon: false
  reverb: false
  queues:
    - queue: default
      processes: 2
    - queue: emails
      processes: 1
      tries: 5
      timeout: 300

schedule: true

health:
  url: "https://myapp.com/up"
  expect: 200

backup:
  profiles:
    - name: myapp-db
      scope: db
      databases: ["myapp", "myapp_*"]
      exclude_tables: ["*.jobs", "*.telescope_*"]
      every: 30m
      keep: 48
      destinations: [local]
    - name: myapp-nightly
      scope: all
      cron: "0 2 * * *"
      keep_days: 14
      destinations: [s3]
      encrypt: true

Planen, dann bewerben

Es ändert sich nichts, bis man sich das Diff anschaut. cipi yml plan myapp listet alle Aliasnamen, Worker, Datenbanken, Einstellungen und Profile auf, die hinzugefügt, geändert oder entfernt werden. Lesen Sie es so, wie Sie eine Pull-Anfrage lesen.

$ cipi yml validate myapp
$ cipi yml plan myapp
$ cipi yml apply myapp                 # asks for confirmation
$ cipi yml apply myapp --yes           # scripts and CI

Eine Datei, die die Validierung nicht besteht, wird als Ganzes abgelehnt nie teilweise angewendet. Dies ist derselbe Fail-Closed-Pfad, den eine Bereitstellung verwendet, wenn yml auto ist an: E-Mail yml_fail, kein Halbzustand auf der Box.

Eine Woche voller echter Veränderungen

Behandeln Sie die Datei wie Anwendungscode. Bei jedem davon handelt es sich um ein einzeiliges (oder einblockiges) Commit, das überprüft und dann angewendet wird – oder automatisch nach der Veröffentlichung angewendet wird, wenn yml auto ist schon dran.

• Montag – Aliase. Hinzufügen www.myapp.com und *.myapp.com für Multi-Tenant-Subdomains. Denken Sie daran: Die Liste ist maßgeblich. Durch das Löschen eines Alias ​​aus der Datei wird dieser aus Nginx entfernt.
• Dienstag – php.ini. Ein Formular akzeptiert nun Uploads mit einer Größe von 40 MB. Beule upload_max_filesize und post_max_size in app.ini. Serverweite Standardeinstellungen bleiben erhalten cipi ini set.
• Mittwoch – eine neue Warteschlange. Die Veröffentlichung fügt eine hinzu emails Warteschlange. Fügen Sie den Arbeiter mit hinzu processes, tries und timeout. Supervisor stimmt mit der Datei überein. Wenn Sie die App auf Horizon umstellen, stellen Sie ein horizon: true und löschen Sie die Warteschlangenliste.
• Donnerstag – eine zusätzliche Datenbank. Für die Berichterstattung ist ein eigenes MariaDB (bzw engine: pgsql). Nennen Sie es myapp_reporting. Anmeldeinformationen erscheinen in /home/myapp/shared/cipi-databases.env– niemals in Git. Cipi erstellt Datenbanken; Sie werden nicht gelöscht, wenn Sie den Eintrag später löschen.
• Freitag – Gesundheit und Backups. Punkt health.url bei https://myapp.com/up (Es muss eine der eigenen Domänen der App sein). Fügen Sie ein günstiges hinzu myapp-db Profil alle 30 Minuten und eine verschlüsselte nächtliche Kopie auf S3.

Melden Sie sich nach jeder Bereitstellung an

Bereitstellungen ignorieren die Datei, bis Sie etwas anderes sagen. Das ist Absicht: ein erstes Commit voncipi.ymlsollte die Produktion nicht überraschen.

$ cipi yml auto myapp on       # reconcile after every successful deploy
$ cipi yml auto myapp status
$ cipi yml auto myapp off      # back to manual apply

Mit dem gegebenen Opt-in, jeder erfolgreich Die Bereitstellung stimmt ab – von beiden cipi deploy und das Git webhook. Eine Veröffentlichung, die keine trägt cipi.yml ist ein stilles No-Op. Eine Datei, die die Validierung nicht besteht, wird per E-Mail gemeldet (yml_fail) und nie zur Hälfte angewendet. Eine erfolgreiche Abstimmung wird ausgelöst yml_apply.

Was die Datei nicht berührt

• It can only konfiguriereneine App, die bereits existiert – niemals eine erstellen, umbenennen oder löschen.
• Abschnitte, die Sie auslassen, bleiben unverändert. Die einzige bewusste Ausnahme ist die Alias-Liste: Sie ist maßgeblich.
• Die eigene Primärdatenbank und die serverweiten Sicherungsprofile der App bleiben Ihr Eigentum. generate lässt sie absichtlich weg.
• Datenbanken werden erstellt und niemals gelöscht. Durch das Entfernen eines Datenbankeintrags aus der Datei wird die Datenbank nicht gelöscht.
• Kein Feld enthält einen Shell-Befehl oder einen einzuschließenden Pfad. Unbekannte Schlüssel sind Fehler.

Sicher über Git zu akzeptieren

Die Datei kommt aus einem Repository, sodass jeder, der einen Commit durchführen kann, ihren Inhalt kontrolliert. Das Schema ist durchgehend ausfallsicher:

• Datenbanken müssen benannt werden <app> oder <app>_*; Backup-Profile <app> oder <app>-*.
• Die Healthcheck-URL muss in eine der eigenen Domänen der App aufgelöst werden – andernfalls könnte ein Commit den fünfminütigen Prüfer auf eine interne Adresse richten und die Antwort aus den Warn-E-Mails zurücklesen.
• Der Parser implementiert eine kleine Teilmenge von YAML und lehnt Anker, Aliase, Tags, Zusammenführungsschlüssel, Blockskalare und Flusszuordnungen vollständig ab.

Häufig gestellte Fragen

Lesen Sie weiter