Cipi Agent

Installieren des Cipi-Agenten

Cipi Agent (cipi/agent auf Packagist) ist der offizielle Laravel-Begleiter für Cipi. Es verbindet Ihre Anwendung und das Server-Kontrollfeld mit:

• Durch Webhook ausgelöste Bereitstellungen von GitHub und GitLab
• Gesundheitsüberwachung (App, Datenbank, Cache, Warteschlange, Bereitstellungs-Commit)
• Eine In-App MCP Server für KI-Assistenten (Cursor, VS Code, Claude Desktop)
• Eine DSGVO-orientierte Datenbank-Anonymisierer

Auf einem von Cipi verwalteten Server, cipi app create spritzt das Notwendige ein .env Variablen automatisch. Gesundheitsprüfung und MCP können auf jedem Laravel-Host funktionieren; Vollständige Bereitstellung und Protokollierung Der Zugriff erfordert eine von Cipi verwaltete Umgebung.

Anforderungen

$ composer require cipi/agent

Der Dienstanbieter erkennt automatisch – nein config/app.php Veränderung ist nötig. Nach der Installation, verpflichten und pushen; Cipi stellt das Update in der nächsten Version bereit.

Optional – veröffentlichen Sie die Konfigurationsdatei (nicht Cipi oder benutzerdefinierte Standardeinstellungen):

$ php artisan vendor:publish --tag=cipi-config
$ php artisan cipi:status   # verify config and DB connectivity

Artisan Befehle

Webhook – Automatische Bereitstellung

Der Agent macht einen POST-Endpunkt verfügbar unter /cipi/webhook. Wenn Ihr Git-Anbieter einen Push sendet Bei diesem Ereignis überprüft der Agent die Signatur und schreibt eine .deploy-trigger Flag-Datei. Ein cron Der Job wird jede Minute ausgeführt, wenn der App-Benutzer diese Datei erkennt, sie entfernt und den Deployer im ausführt Hintergrund.

Dieses Design bedeutet, dass die webhook-Antwort sofort erfolgt (kein HTTP-Timeout beim Warten auf die Bereitstellung). vollständig) und Deployer wird mit den richtigen Benutzerberechtigungen ausgeführt – nein sudo erforderlich.

Konfigurieren Sie Ihren Git-Anbieter

Der zu verwendende Token wird in gespeichert .env als CIPI_WEBHOOK_TOKEN. Das können Sie auch jederzeit abrufen mit:

$ cipi deploy myapp --webhook

Zweigfilterung

Standardmäßig löst jeder Push eine Bereitstellung aus. Um Bereitstellungen auf einen bestimmten Zweig zu beschränken, fügen Sie dies zu Ihrem hinzu .env:

CIPI_DEPLOY_BRANCH=main

Pushs an einen anderen Zweig erhalten eine skipped Es erfolgt keine Reaktion und keine Bereitstellung ausgelöst.

Gesundheitscheck

Der Agent stellt außerdem einen GET-Endpunkt bereit unter /cipi/health das gibt eine JSON-Nutzlast mit zurück den Status der App, der Datenbank, des Caches, der Warteschlange und des aktuell bereitgestellten Git-Commit-Hashs. Nützlich für externe Überwachungsdienste wie UptimeRobot. Geschützt durch die CIPI_HEALTH_TOKEN Inhabertoken – generieren Sie eines mit php artisan cipi:generate-token health.

$ curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
    https://yourdomain.com/cipi/health

{
  „Status“: „gesund“,
  „app_user“: „meine App“,
  „php“: "8.5",
  „laravel“: "12.0.0",
  „Umwelt“: „Produktion“,
  „Schecks“: {
    „App“:      { „ok“: wahr, „Version“: "2.1.0", „Debuggen“: falsch },
    „Datenbank“: { „ok“: wahr, „Datenbank“: „myapp_prod“ },
    „Cache“:    { „ok“: wahr },
    „Warteschlange“:    { „ok“: wahr, „pending_jobs“: 0 },
    „bereitstellen“:   { „ok“: wahr, „verpflichten“: „a1b2c3d4…“, „short_commit“: „a1b2c3d“ }
  },
  „Zeitstempel“: „2026-06-10T14:22:01.000000Z“
}

Der Deploy-Commit wird aus der ersten verfügbaren Quelle aufgelöst:

1. /home/{app_user}/.cipi/deploy.json (Cipi Metadaten bereitstellen)
2. /home/{app_user}/.cipi/last_commit
3. /home/{app_user}/logs/deploy.log
4. .git/HEAD oder git rev-parse HEAD

Authentifizierung

Der Inhabertoken wird in der folgenden Reihenfolge aufgelöst: CIPI_HEALTH_TOKEN (gewidmet), also CIPI_WEBHOOK_TOKEN (zurückgreifen). Deaktivieren Sie den Endpunkt vollständig mit php artisan cipi:service health --disable oder CIPI_HEALTH_CHECK=false.

Überwachung von Integrationen

Der Gesundheitsendpunkt funktioniert mit jedem HTTP-Prüfer, der Bearer-Token unterstützt – z. UptimeRobot, Besserer Stapel, Grafana, oder benutzerdefiniert cron + curl. Umfrage checks.queue.pending_jobs für Warteschlangenrückstauwarnungen.

MCP Server

cipi-Agent Enthält eine integrierte MCP Server (Modellkontextprotokoll) Dadurch wird Ihre Anwendung KI-Assistenten zugänglich gemacht, z Cursor, VS-Code (mit GitHub Copilot) und Claude Desktop. Der Endpunkt implementiert MCP 2024-11-05 über HTTP unter Verwendung von JSON-RPC 2.0 und ist durch die geschützt CIPI_MCP_TOKEN Inhabertoken.

Der Endpunkt MCP ist verfügbar unter POST /cipi/mcp und ist standardmäßig deaktiviert. Zum Aktivieren es:

$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp

Verfügbare Werkzeuge

Der MCP-Server stellt sechs Tools bereit, die ein KI-Assistent namentlich aufrufen kann:

logs Werkzeugparameter

Blockierte Vorgänge (MCP Sicherheit)

• Artisan: serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start
• SQL: DROP, TRUNCATE, GRANT, REVOKE, Datei-E/A – Lese-/Schreibzugriff begrenzt auf 100 Reihen

Einrichtungsanweisungen

Führen Sie das aus cipi:mcp Artisan-Befehl zum Abrufen der Endpunkt-URL und zum Einfügen bereit Konfigurationsausschnitte für Ihren AI-Client:

$ php artisan cipi:mcp

Der Befehl druckt die verfügbaren Tools und die JSON-Konfiguration für Cursor, VS Code und Claude Desktop.

Cursor

Fügen Sie Folgendes hinzu ~/.cursor/mcp.json (oder gehen Sie zu Cursor → Einstellungen → MCP):

{
  „mcpServers“: {
    „cipi-myapp“: {
      „Typ“: „http“,
      „URL“: „https://yourdomain.com/cipi/mcp“,
      „Kopfzeilen“: {
        „Autorisierung“: „Träger YOUR_CIPI_MCP_TOKEN“
      }
    }
  }
}

Ersetzen cipi-myapp mit Ihrem App-Benutzernamen, yourdomain.com mit deinem tatsächliche Domäne und YOUR_CIPI_MCP_TOKEN mit dem Token von Ihrem .env. Der Cursor stellt eine native Verbindung über HTTP her – keine Bridge erforderlich.

VS-Code

VS Code (mit GitHub Copilot) unterstützt MCP nativ seit Version 1.102. Fügen Sie Folgendes hinzu .vscode/mcp.json in Ihrem Projekt (oder run MCP: Benutzerkonfiguration öffnen für ein globales Setup):

{
  „Server“: {
    „cipi-myapp“: {
      „Typ“: „http“,
      „URL“: „https://yourdomain.com/cipi/mcp“,
      „Kopfzeilen“: {
        „Autorisierung“: „Träger YOUR_CIPI_MCP_TOKEN“
      }
    }
  }
}

Ersetzen cipi-myapp, yourdomain.com, und YOUR_CIPI_MCP_TOKEN wie oben. Benutzen MCP: Server hinzufügen aus der Befehlspalette für eine geführte Einrichtung. VS-Code verbindet sich über HTTP – keine Brücke erforderlich.

Claude Desktop

Claude Desktop benötigt das mcp-remote Bridge zum Konvertieren von stdio in HTTP. Fügen Sie die hinzu im Anschluss an ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  „mcpServers“: {
    „cipi-myapp“: {
      „Befehl“: „npx“,
      „Argumente“: [
        „-y“,
        „mcp-remote“,
        „https://yourdomain.com/cipi/mcp“,
        „--header“,
        „Autorisierung: Inhaber YOUR_CIPI_MCP_TOKEN“
      ]
    }
  }
}

Installieren mcp-remote global einmalig mit:

$ npm install -g mcp-remote

Was Sie damit machen können

Sobald die Verbindung hergestellt ist, kann Ihr KI-Assistent auf natürliche Weise mit der von Cipi verwalteten Anwendung interagieren Sprache. Zum Beispiel:

Benutzer:  Is the app healthy? Any pending jobs in the queue?

Claude: Calling health tool...
         Status: healthy — database, cache, and queue all OK.
         Queue: 0 pending jobs.

Benutzer:  Show me the last errors from the log.

Claude: Calling logs tool (lines: 100)...
         Found 2 errors in the last 100 lines:
         [2026-03-04 14:22:01] production.ERROR: Connection refused [...]
         [2026-03-04 14:23:15] production.ERROR: Redis timeout [...]

Benutzer:  Clear the cache and deploy the latest version.

Claude: Calling artisan tool (cache:clear)...
         Cache cleared successfully.
         Calling deploy tool...
         Deploy queued — Deployer will run within 1 minute.

Benutzer:  What's the current migration status?

Claude: Calling artisan tool (migrate:status)...
         All 47 migrations have been run.

Benutzer:  How many users signed up in the last 7 days?

Claude: Calling db_query tool (SELECT COUNT(*) FROM users WHERE created_at >= ...)...
         | count |
         |-------|
         | 23    |

Datenbank-Anonymisierer

cipi-Agententhält einen integrierten Datenbank-Anonymisierer, der bereinigte Kopien davon erstellt Ihre Produktionsdatenbank – ideal für die gemeinsame Nutzung mit Entwicklern, QA-Teams oder Staging-Umgebungen ohne echte Benutzerdaten preiszugeben. Es unterstützt beides MySQL und PostgreSQL, verwendet Faker-basierte Transformationen, die über eine JSON-Datei konfiguriert werden und als ausgeführt werden Hintergrundjob, damit große Datenbanken HTTP-Anfragen nicht blockieren.

Diese Funktion lebt in Ihrem Inneren Laravel-Anwendung (die cipi/agent Paket). Es ist getrennt von der Datenbanksicherung auf Serverebene API, die von bereitgestellt wird cipi api – siehe Agent vs. Cipi API unten.

Anwendungsfälle

• Lokale Entwicklung – Geben Sie jedem Entwickler einen realistischen Datensatz, ohne ihn kopieren zu müssen Produktions-E-Mails, Adressen oder Zahlungshinweise
• Staging-/Vorschauumgebungen – Aktualisieren Sie eine Nicht-Produktionsdatenbank von Produktionsstruktur und -volumen, wobei PII ersetzt wurde
• Qualitätssicherung und Demos – Reproduzieren Sie Fehler, die von relationalen Daten abhängen, ohne DSGVO-Risiko
• Lieferanten- oder Auftragnehmerzugang – Geben Sie einen SQL-Dump frei, wenn eine vollständige VPN + -Produktion erfolgt Der Zugriff ist nicht akzeptabel
• CI-Pipelines – laufen cipi:anonymize auf dem Server oder Trigger POST /cipi/db aus einem sicheren Automatisierungsschritt

Voraussetzungen

Agent vs. Cipi API

Beide Cipi-Komponenten berühren Datenbanken, lösen jedoch unterschiedliche Probleme:

Wie es funktioniert

1. Eine authentifizierte POST /cipi/db Anfrage (mit einem Empfänger email) Warteschlangen AnonymizeDatabaseJob
2. Der Job wird ausgeführt php artisan cipi:anonymize, die:
   • speichert die Datenbank mit mysqldump oder pg_dump
   • strömt durch INSERT Anweisungen und schreibt nur die in aufgeführten Spalten neu anonymization.json
   • schreibt das Ergebnis nach storage/cipi/anonymized_{jobId}.sql
3. Bei Erfolg sendet Laravel eine E-Mail mit a Zeitlich begrenzte Download-URL (15 Minuten)
4. GET /cipi/db/{token} stellt die Datei bereit – kein Bearer-Token; Die URL selbst ist die Berechtigung
5. Bei einem Fehler wird eine Klartext-Fehler-E-Mail an dieselbe Adresse gesendet

E-Mail-Benachrichtigungen

Der HTTP API gibt die Download-URL nicht in der JSON-Antwort zurück – E-Mail ist die einzige Lieferkanal für POST /cipi/db. Verstehen, wer es erhält und Was konfiguriert werden muss, vermeidet stille Fehler.

Wer erhält die E-Mail?

Genau die Adresse, die Sie im JSON-Body übergeben – sonst nichts:

{ „E-Mail“: „developer@example.com“ }

• Erfolgreich → HTML E-Mail mit dem signierten Download-Link (15 Minuten)
• Fehler → Klartext-E-Mail mit Fehler und Job-ID
• Kein CC, BCC oder Fallback auf den Cipi-Administrator, CIPI_APP_USER, oder eine feste Adresse in .env
• Wer auch immer hält CIPI_ANONYMIZER_TOKEN wählt bei jeder Anfrage den Empfänger aus

Laravel Mail muss funktionieren

Benachrichtigungen verwenden Laravel Mail Fassade und Ihre Anwendung MAIL_* Einstellungen – die gleiche Konfiguration wie beim Zurücksetzen von Passwörtern oder bei Kontaktformularen. Das ist unabhängig von Cipi Server SMTP (cipi smtp configure für Backup/Bereitstellung Warnungen auf dem Host).

Typische Produktion .env Einträge:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@myapp.example.com
MAIL_FROM_NAME="${APP_NAME}"

Schneller Mailtest (als App-Benutzer vor Ihrem ersten Export):

$ php artisan tinker --execute=„Mail::raw('Cipi anonymizer mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

Wenn diese Nachricht nicht ankommt, reparieren Sie zuerst die Mail Laravel – oder verwenden Sie den Pfad CLI (php artisan cipi:anonymize), wodurch die Datei direkt geschrieben und E-Mails übersprungen werden.

Einrichtung – Schritt für Schritt

Führen Sie diese Befehle aus auf dem Server als App-Benutzer (SSH: ssh myapp@your-server oder sudo su - myapp als Wurzel – siehe SSH als App-Benutzer):

1. Installieren Sie den Agenten (falls nicht schon drin composer.json):

$ composer require cipi/agent
# commit, push, deploy — or run on the current release

2. Aktivieren Sie den Dienst und erstellen Sie ein Token:

$ php artisan cipi:service anonymize --enable
$ php artisan cipi:generate-token anonymize

3. Erstellen Sie ein Gerüst für die Konfigurationsdatei:

$ php artisan cipi:init-anonymize

Das schafft /home/{app_user}/.db/anonymization.json (Berechtigungen 0640) aus der integrierten Vorlage. Die Datei lebt außerhalb des Git-Repositorys – das ist es nie mit Ihrem Code bereitgestellt. Benutzen --force um eine bestehende Datei zu überschreiben.

4. Bearbeiten Sie die Konfiguration um Ihren realen Tabellen und sensiblen Spalten zu entsprechen (siehe Konfiguration).

5. Warteschlange und E-Mail überprüfen: Bestätigen Sie, dass der Worker Jobs ausführt und Laravel an den senden kann Adresse, an die Sie weitergeben werden POST /cipi/db (siehe E-Mail-Benachrichtigungen).

$ php artisan cipi:status          # DB connectivity
$ php artisan queue:work --once   # optional: confirm worker can run jobs
# send a test email — must arrive before using POST /cipi/db
$ php artisan tinker --execute=„Mail::raw('Mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

6. Lösen Sie Ihren ersten anonymisierten Export aus über HTTP oder CLI (siehe Beispiele unten).

Konfiguration

Gültige Pfade (das erste Spiel gewinnt):

• /home/{app_user}/.db/anonymization.json — empfohlen
• /home/{app_user}/.cipi/anonymization.json – Alternative

Die Datei JSON verfügt über zwei Schlüssel der obersten Ebene: transformations (erforderlich) und options (optional).

{
  „Transformationen“: {
    „Benutzer“: {
      „Name“: „fakeName“,
      „E-Mail“: „fakeEmail“,
      „Passwort“: „Passwort“,
      „Telefon“: „fakePhoneNumber“,
      „Adresse“: „fakeAddress“
    },
    „Bestellungen“: {
      „customer_notes“: „fakeParagraph“,
      „Versandadresse“: „fakeAddress“
    },
    „support_tickets“: {
      „user_message“: „fakeParagraph“,
      „agent_response“: „fakeParagraph“
    }
  },
  „Optionen“: {
    „hash_algorithm“: „automatisch“,
    „preserve_ids“: wahr,
    „faker_locale“: „en_US“
  }
}

Unter transformations, jeder Schlüssel ist ein Tabellenname. Verschachtelte Schlüssel sind Spaltennamen; Werte sind Transformationstypen (keine rohen Faker-Methodennamen – siehe Tabelle unten). Spalten nicht Die aufgelisteten Daten behalten ihre ursprünglichen Werte bei, sodass Sie personenbezogene Daten anonymisieren können Beibehaltung von Fremdschlüsseln, Enumerationen und Geschäftslogikfeldern.

Unterstützte Transformationen

Optionen

HTTP API – Endpunkte

Wenn der Anonymisierer deaktiviert ist (CIPI_ANONYMIZER=false), Routen kehren zurück 404 — Die Endpunkte sind vollständig ausgeblendet.

Praxisbeispiele (Curl)

Legen Sie die Variablen einmal fest (ersetzen Sie sie durch Ihre App-Domäne und das Token von). .env):

exportieren APP_URL=„https://myapp.example.com“
exportieren CIPI_ANONYMIZER_TOKEN=„Ihr-Token-aus-Umgebung“

1. Stellen Sie einen Anonymisierungsauftrag in die Warteschlange

curl -sS -X POST „${APP_URL}/cipi/db“ \
  -H „Autorisierung: Inhaber ${CIPI_ANONYMIZER_TOKEN}“ \
  -H „Inhaltstyp: application/json“ \
  -H „Akzeptieren: application/json“ \
  -d '{"email": "developer@example.com"}'

Erfolgreiche Antwort (200):

{
  „Status“: „in der Warteschlange“,
  „Nachricht“: „Der Auftrag zur Datenbankanonymisierung wurde in die Warteschlange gestellt. Sobald der Vorgang abgeschlossen ist, erhalten Sie eine E-Mail mit Anweisungen zum Herunterladen.“,
  „E-Mail“: „developer@example.com“
}

Der HTTP-Aufruf kehrt sofort mit zurück status: queued – das geht nicht garantieren, dass die Benachrichtigungs-E-Mail gesendet wurde. Die Verarbeitung kann bei großen Datenbanken (Job Timeout: 1 Stunde). Die Abschlussmeldung geht nur an die email in deinem JSON Körper; wenn Es kommt nichts an, überprüfen Sie storage/logs/laravel.log für Mail-Transportfehler, php artisan queue:failed für einen gescheiterten Job, und das MAIL_* konfiguriert ist (siehe E-Mail-Benachrichtigungen).

2. Laden Sie den Dump herunter (über den E-Mail-Link).

Die Abschluss-E-Mail enthält eine URL wie:

https://myapp.example.com/cipi/db/AbCdEf...?expires=1710000000&signature=...

Speichern Sie es mit Curl (fügen Sie die vollständige URL aus der E-Mail ein – ohne Bearer-Header):

curl -sS -L -o anonymized.sql „PASTE_FULL_SIGNED_URL_FROM_EMAIL“

# Import locally (MySQL example)
mysql -u root -p myapp_local < anonymized.sql

Abgelaufene oder ungültige Links werden zurückgegeben 410 Gone oder 404. Fordern Sie einen neuen Export an mit POST /cipi/db wenn das 15-Minuten-Fenster verstrichen ist.

3. Suchen Sie per E-Mail nach einer Benutzer-ID

Nach der Anonymisierung sind E-Mails gefälscht – aber Benutzer-IDs bleiben gleich. Benutzen Sie dies vor Anonymisierung, um eine bekannte Produktions-E-Mail einer ID zuzuordnen, die Sie später im finden Dump:

curl -sS -X POST „${APP_URL}/cipi/db/user“ \
  -H „Autorisierung: Inhaber ${CIPI_ANONYMIZER_TOKEN}“ \
  -H „Inhaltstyp: application/json“ \
  -d '{"email": "customer@produktion.com"}'

{
  „user_id“: 42,
  „E-Mail“: „customer@produktion.com“,
  „found_at“: „2026-06-10T14:22:01+00:00“
}

Dies fragt das Live ab users Tabelle – nur ausführen, wenn Sie die Produktion berühren dürfen Daten. Es ändert nichts.

4. Fehlerreaktionen (Fehlerbehebung)

CLI – ohne HTTP ausführen

Für Skripte, cron oder einmalige Exporte auf dem Server:

$ php artisan cipi:anonymize \
    /home/myapp/.db/anonymization.json \
    /home/myapp/anonymized_export.sql

Der Befehl gibt drei Schritte aus (Dump → Transformieren → Speichern) und wird bei einem Fehler ungleich Null beendet. Das ist nicht der Fall E-Mail senden – Kopieren Sie die Datei über SCP oder Ihren eigenen sicheren Kanal.

Vergleichscurl: Cipi API Rohsicherung

Als Referenz: a nicht anonymisiert Server-Backup über Cipi API sieht so aus (unterschiedlicher Host, Token und Semantik):

exportieren CIPI_API_URL=„https://api.myserver.com“
exportieren CIPI_API_TOKEN=„sanctum-token-with-dbs-manage“

curl -sS -X POST „${CIPI_API_URL}/api/dbs/myapp_db/backup“ \
  -H „Autorisierung: Inhaber ${CIPI_API_TOKEN}“ \
  -H „Akzeptieren: application/json“

Das kommt zurück 202 mit einem job_id – Umfrage GET /api/jobs/{id} für den Backup-Pfad auf dem Server. Das Archiv enthält echte Produktionsdaten; einschränken entsprechend zugreifen.

Sicherheits- und DSGVO-Tipps

• Speichern CIPI_ANONYMIZER_TOKEN in der Geheimnisverwaltung – jeder, der damit ausgestattet ist, kann Dumps in die Warteschlange stellen und abfragen /cipi/db/user
• Drehen Sie den Token nach einem Teamwechsel: php artisan cipi:generate-token anonymize
• Deaktivieren, wenn es nicht benötigt wird: php artisan cipi:service anonymize --disable (Endpunkte geben 404 zurück)
• Download-Links laufen ab 15 Minuten – Leiten Sie E-Mails sorgfältig weiter
• Dokumentieren Sie, welche Spalten für Ihre DPA-/Datenschutzrichtlinie umgewandelt werden
• Testen Sie den dump: grep auf eine bekannte Produktions-E-Mail – er sollte nicht erscheinen, wenn fakeEmail wurde auf diese Spalte gesetzt

Sicherheit

Cipi Agent verwendet Verteidigung in der Tiefe: Jede Funktion hat ihr eigenes Bearer-Token und kann sein unabhängig voneinander ausgeschaltet werden. Wenn deaktiviert, kehren Routen zurück 404 (versteckt, nicht 403).

Token-Isolation

Webhook Verifizierung

• GitHub — X-Hub-Signature-256 HMAC-SHA256
• GitLab — X-Gitlab-Token Header-Vergleich

Quellcode und Veröffentlichungen: github.com/cipi-sh/agent (MIT).

ENV-Variablen

Diese Variablen werden von Cipi automatisch in die App eingefügt.env während cipi app create. Schalten Sie optionale Funktionen mit um php artisan cipi:service {type} --enable|--disable oder manuell einstellen.