phis-Befehlsübersicht
phis is the operator CLI of @phis/server. It edits the configuration files of one phis root,
writes to the PostgreSQL database that root names, scaffolds and builds Site repositories, and
manages server Add-ons and Site Modules. This file lists every command the dispatcher in
src/cli/phis.mts accepts.
Bei einer Erstinstallation lesen Sie bitte stattdessen
die Datei INSTALL.md; darin werden diese Befehle der Reihe nach ausgeführt.
Ausführen der Befehlszeilenschnittstelle
Der Wrapper ./phis führt dist/phis.mjs aus, sofern diese Datei vorhanden ist, und greift andernfalls auf die TypeScript-Quelldatei zurück.
Sind PHIS_ROOT und PHIS_APP_ROOT nicht gesetzt, legt der Wrapper beide Variablen auf das eigene Verzeichnis des Wrappers fest.
./phis bevorzugt dist/phis.mjs, selbst wenn die Quelldatei neuer ist; führen Sie nach einer Änderung
der CLI den Befehl pnpm build:cli aus oder verwenden Sie pnpm phis.
Im Debian-Paket setzt /usr/bin/phis die Variable PHIS_ROOT=/srv/phis/stages/prod, sofern diese
noch nicht gesetzt ist; dabei handelt es sich um die vom Paket erstellte Stufe und das Stammverzeichnis, das der Server im Produktionsbetrieb verwendet. Geben Sie --root an oder setzen Sie
PHIS_ROOT, um eine andere Stufe zu verwenden.
pnpm phis wird mit dem Paketverzeichnis als Arbeitsverzeichnis ausgeführt; ohne PHIS_ROOT oder
--root greift es daher auf das Verzeichnis config/ des Checkouts selbst zu.
Globale Flags, Ausgabe- und Beendigungscodes
Regeln für die Auswertung von Optionszeichen. Jeder Befehl verfügt über eine festgelegte Liste von Optionszeichen (PHIS_COMMAND_FLAGS in
src/cli/argv.mts), und jedes Optionszeichen nimmt entweder einen Wert an oder ist ein Schalter:
Ein Flag, das einen Wert entgegennimmt, übernimmt das nächste Argument, unabhängig davon, womit dieses beginnt: --password -x1 übergibt
-x1. --name=value funktioniert ebenfalls und ist die übersichtlichere Form für solche Werte.
Eine leere Zeichenkette ist ein Wert: --value "" und --value= übergeben "".
Ein Wert-Flag am Zeilenende führt zu einer Fehlermeldung: --<flag> needs a value.
Ein Schalter (--force, --json, --install, …) nimmt keinen Wert an; --force=yes wird nicht akzeptiert.
Ein Flag, das der Befehl nicht erkennt, wird abgelehnt: phis <command> does not take --<flag>. Dies umfasst
Flags, die zu einem anderen Befehl gehören, z. B. --api-base-url bei reconcile.
Derselbe Name kann je nach Befehl unterschiedliche Bedeutungen haben: site admin --revoke ist ein Schalter, während addon role --revoke
<role>
einen Wert erwartet.
Kurzbefehle: -e --email, -u --public-base-url, -h --hostname, -k --key, -l --locale,
-p --password, -n --name, -d --disabled, -j --json, -r --root. Alle anderen Optionen mit einem einzigen Bindestrich
werden mit der Meldung Unknown flag abgelehnt.
Eine Zeile, die keinem Befehl entspricht, wird an den Dispatcher weitergeleitet, der mit der Meldung Unknown command antwortet.
Ausgabe- und Beendigungscodes:
Bei erfolgreicher Ausführung gibt der Befehl eine für Menschen lesbare Zeile aus – oder JSON bei Verwendung von --json – und beendet den Prozess mit dem Status 0.
Im Fehlerfall wird die Meldung an stderr ausgegeben, zusammen mit einer strukturierten Protokollzeile
({"level":"error","service":"cli","event":"cli.command.failed",...}), und das Programm beendet sich mit dem Status 1. Bei Verwendung von
--json wird über stderr zusätzlich {"ok": false, "error": "<message>"} ausgegeben.
Einige Befehle werden ohne Auslösung eines Fehlers beendet, geben jedoch dennoch den Exit-Code 1 zurück, da sie ein Problem festgestellt haben; diese sind
nachstehend aufgeführt (config validate, schema check, site check, module add|check, addon list|check,
addon job, secret check, media check, maintain, mail drain,
Umgebungsvariablen
Mit dem Befehl update wird die Umgebungsvariable an den Paketmanager übergeben und der Wert NEXT_TELEMETRY_DISABLED=1 hinzugefügt.
Überprüfung der Root-Version
Mit Ausnahme der Befehle help und --version vergleicht jeder Befehl die CLI-Version mit
<root>/config/phis-instance.json ({"formatVersion": 1, "phisVersion": "..."}):
kein Stempel oder eine CLI, die neuer ist als der Stempel: Der Befehl wird ausgeführt und der Stempel wird auf die CLI-Version überschrieben
(eine neuere CLI gibt zunächst folgende Meldung aus: Note: <root> was last operated by phis <old>, this is <new>.);
CLI-Version älter als die angegebene: Der Befehl wird abgelehnt. Verwenden Sie die CLI, die zum Root-Benutzer gehört, oder setzen Sie
PHIS_SKIP_VERSION_CHECK=1.
Der Eintrag wird nur dann geschrieben, wenn das Stammverzeichnis die Datei config/phis-config.json oder
config/phis-runtime.json enthält; ein fehlgeschlagener Schreibvorgang wird ignoriert.
Das Verzeichnis „phis“ und die darin enthaltenen Dateien
Alle Pfade beziehen sich auf das Stammverzeichnis.
Die CLI schreibt die Datei phis-runtime.json über eine temporäre Datei und eine Umbenennung. Ein laufender Server speichert die
zusammengeführte Konfiguration bis zu vier Stunden lang im Cache; starten Sie ihn neu, nachdem Sie einen CLI-Befehl ausgeführt haben, der die Datei
phis-runtime.json ändert (db bootstrap, operator add|passwd|enable|disable|del, site add|del und site
config set|add|del für sites.overrides, secret init-key, auth import-secrets), andernfalls behält der laufende
Server die alten Werte bis zu vier Stunden lang bei.
Was ein Befehl benötigt
Es gibt keine Ausweichlösung von database.migrationUri zu database.uri.
config
phis config
Gibt die zusammengeführte Konfiguration (integrierte Standardwerte, anschließend phis-config.json, dann
phis-runtime.json) als JSON aus. Die Ausgabe enthält Datenbank-URIs, Tokens und Schlüssel; fügen Sie sie
nirgendwo ein.
phis config paths
Gibt den Stammordner sowie die absoluten Pfade der statischen und der Laufzeit-Konfigurationsdateien aus
({root, static, runtime} mit --json).
phis config validate
Analysiert beide Dateien und überprüft die zusammengeführte Konfiguration: Typen von sites.*, platformSuperUsers
(E-Mail-Adresse und passwordHash vorhanden, keine Duplikate), 64-stellige Hex-Schlüssel
(auth.transactionEncryptionKey, secrets.encryptionKey), media, translation (die Quell-
Sprachversionen müssen in translation.supportedLocales enthalten sein), forms.timeouts sowie das Vorhandensein des
nicht mehr verwendeten Feldes auth.secrets. Beendet den Vorgang bei 1, sobald ein Problem auftritt. JSON: {ok, staticError, runtimeError, issues}.
Es wird nicht überprüft, ob die erforderlichen Werte vorhanden sind; ein fehlender database.uri-Eintrag wird von dem
ersten Befehl gemeldet, der diesen benötigt.
db
phis db bootstrap --admin-uri <postgres uri>
Erstellt die Datenbank, auf die diese Installation angewendet wird, sowie die beiden Rollen, denen Teile davon gehören, und schreibt beide
Verbindungszeichenfolgen in die Datei phis-runtime.json. Dies ist der Schritt vor der schema apply-Anwendung und der einzige, der eine
eigene Verbindung benötigt: --admin-uri ist eine Verbindung, die zum Erstellen von Datenbanken und Rollen berechtigt ist, wobei es sich nicht
um eine der beiden zu erstellenden Rollen handelt.
Die Namen werden aus dem Parameter --name abgeleitet, sodass die drei Namen einer Installation erkennbar miteinander in Verbindung stehen:
--name prod ergibt die Datenbank phis_prod, die Serverrolle phis_prod_user und die Migrationsrolle
phis_prod_migrator. Ohne --name lauten sie phis, phis_user und phis_migrator. Die Parameter --database,
--role und --migration-role benennen jeden der drei Namen direkt und werden als eingegeben und nicht als zusammengefasst interpretiert.
Passwörter werden generiert, sofern nicht über --password oder --migration-password eines angegeben wird.
Es gibt zwei Rollen, da die Zuständigkeiten aufgeteilt sind: Die „serving“-Rolle ist für das Core-Schema-phis verantwortlich, die „migration“-Rolle ist für
die Schemata der Server-Add-ons zuständig, und keine der beiden Rollen kann das löschen, was die andere erstellt hat. schema apply gewährt der „migration“-Rolle
die für Add-on-Migrationen erforderlichen Berechtigungen, wobei der Name aus database.migrationUri ausgelesen wird.
Der Befehl „create“ ist idempotent und gibt lediglich zurück, was er vorgefunden hat, anstatt selbst etwas zu erstellen. --force schützt die Konfiguration, nicht
die Datenbank: Bei einer bereits vorhandenen Rolle ist das Passwort bereits festgelegt – es wird kein Passwort zurückgegeben –, sodass ein zweiter
Lauf ohne --force abgelehnt wird, anstatt einem laufenden Server Verbindungszeichenfolgen zu übergeben, die dieser nicht verwendet.
--admin-uri muss einen Host angeben. Eine lokale Socket-Verbindung (postgresql:///postgres?host=...) enthält keinen Host,
und die daraus geschriebenen Verbindungszeichenfolgen müssen so gestaltet sein, dass die CLI sie wieder auswerten kann.
Ist die administrative Verbindung kein Superuser – typischerweise bei einer verwalteten Datenbank –, gewährt sich der Befehl zunächst
selbst das Recht, die Rolle des Servers zu übernehmen, da dies für den Befehl CREATE DATABASE ... OWNER erforderlich ist und
PostgreSQL 16 die Verwaltung einer Rolle von deren Übernahme getrennt hat. Ein Superuser bleibt davon unberührt.
Die Datei enthält zwei Passwörter. Der Befehl ändert weder den Modus noch den Eigentümer der Datei: Bei Ausführung als „root“ gegenüber einer
Remote-Datenbank gehört die Datei „root“, während der Server unter einem anderen Konto läuft. Legen Sie den Modus 0600 fest und setzen Sie den
Eigentümer auf das Konto, unter dem der Server läuft.
Schema
phis schema check
Stellt eine Verbindung zur Datenbank database.uri her und vergleicht die in der Datei scripts/sql/001_create_phis.pgsql deklarierten Tabellen
mit den Tabellen im Schema phis. Zeigt die fehlenden Tabellen an und gibt den Status 1 zurück, falls welche fehlen. Außerdem
listet es die vom Skript erstellten Erweiterungen (pg_trgm) auf, die nicht installiert sind. Nur-Lese-Modus.
phis schema apply
Führt 001_create_phis.pgsql mit database.uri aus. Das Skript ist idempotent (CREATE ... IF NOT
EXISTS), sodass eine Wiederholung unbedenklich ist; es handelt sich um den Schritt, der nach jedem Server-Upgrade ausgeführt werden muss. Es wird bewusst als
„serving“-Rolle ausgeführt: Die Kern-Tabellen gehören zu dieser Rolle. Die Rolle benötigt die Berechtigung zum Anlegen des
Schemas phis und der Erweiterung pg_trgm; andernfalls muss ein Superuser die Erweiterung zuvor anlegen.
Wenn database.migrationUri festgelegt ist, werden der Migrationsrolle zudem die Berechtigungen erteilt, die für Add-on-Migrationen erforderlich sind
(USAGE-Berechtigung für phis-Tabellen, REFERENCES-Berechtigung für die Core-Tabellen, auf die Add-ons verweisen können, Lese-/Schreibberechtigung für die Add-on-
Katalogtabellen sowie einige weitere, eng gefasste Berechtigungen). Zeigt die erstellten Tabellen und den Berechtigungsempfänger an.
phis schema drop [--force]
Zerstörerisch. Ohne die Option --force werden lediglich die zu löschenden Elemente angezeigt, ohne dass Änderungen vorgenommen werden. Mit der Option --force
werden alle in phis.server_addons gespeicherten Add-on-Schemas (mit database.migrationUri, zu der
sie gehören) gelöscht und anschließend DROP SCHEMA phis CASCADE (mit database.uri) ausgeführt. Alle Kerndaten gehen dabei verloren.
Für den Testlauf ist lediglich database.uri erforderlich; für die Option --force ist zusätzlich database.migrationUri erforderlich. Führen Sie phis schema
apply aus,
um ein leeres Schema neu zu erstellen.
Website
Alle site-Befehle benötigen die Datenbank. Site-Schlüssel und Hostnamen werden in Kleinbuchstaben geschrieben. Ein Site-Schlüssel muss dem Muster
[a-z0-9][a-z0-9._-]{0,63} (nach Umwandlung in Kleinbuchstaben) entsprechen – dies ist die Regel für ein Segment einer geheimen Referenz, zu der
der Schlüssel gehört; der Befehl site add lehnt jeden anderen Schlüssel ab.
phis site list [--key <site key>]
Listet Standorte auf (key, enabled, hostname, name), optional einen. Die JSON-Datei enthält alle Spalten, die die
CLI ausliest, sowie die aufgelöste sourceLocale.
phis site add
phis site add --key <site key> --name <site name> --hostname <hostname> --public-base-url <url>
--source-locale <locale> --default-locale <locale> [--available-locales <csv>]
--support-email <email>
Erstellt eine Website.
Jede Sprachversion muss in translation.supportedLocales aufgeführt sein (Standard: ["en"]).
Nebenwirkungen: Schreibt zunächst sites.overrides.<key>.sourceLocale in die Datei phis-runtime.json und fügt anschließend
die Zeile phis.sites (E-Mail-Absender no-reply@<hostname>, Kontaktempfänger = Support-E-Mail-Adresse, ein zufälliges
Formular-Sicherheitskennwort) sowie eine leere Zeile phis.site_auth_config in einer einzigen Transaktion ein. Sollte das Einfügen fehlschlagen,
wird die Laufzeitdatei wiederhergestellt. Der Vorgang wird abgebrochen, wenn für den Schlüssel bereits eine Überschreibung mit einer sourceLocale existiert.
phis site set --key <site key> [--name] [--hostname] [--public-base-url] [--support-email]
Aktualisiert die angegebenen Felder; mindestens eines davon ist erforderlich. Außerdem werden der E-Mail-Absender
(no-reply@<hostname>), der Absendername und der Kontaktempfänger anhand der resultierenden Werte neu geschrieben.
phis site enable|disable --key <site key>
Setzt das Aktivitätskennzeichen der Website.
phis site del --key <site key>
Destruktiv. Löscht die Zeile phis.sites (sowie alle daraus resultierenden Einträge in der Datenbank) und entfernt
sites.overrides.<key> aus der Datei phis-runtime.json. Das Quellverzeichnis der Website,
Release-Artefakte, unter site:<key>:... gespeicherte Geheimnisse sowie die Konfiguration des Webservers und der Dienste bleiben davon unberührt.
Es erfolgt keine Bestätigungsabfrage.
phis site locale add --key <site key> --locale <locale>
Fügt den verfügbaren Sprachumgebungen der Website eine weitere Sprachumgebung hinzu. Die Sprachumgebung muss in
translation.supportedLocales enthalten sein.
phis site admin
phis site admin --site <site key> --email <email> [--password <pw>] [--first-name <n>] [--last-name <n>]
phis site admin --site <site key> --list
phis site admin --site <site key> --email <email> --revoke
Grant (Standard): Weist dem Konto die Administratorrolle auf der Website zu und erstellt das Konto sowie dessen
Mitgliedschaft, sofern die E-Mail-Adresse neu ist. Ein Passwort wird nur für ein Konto festgelegt, das durch diesen Aufruf erstellt wird;
ohne den Parameter --password wird ein zufälliges Passwort vergeben, das niemand kennt, und der Befehl enthält Anweisungen zum Festlegen eines Passworts.
Das Passwort eines bereits bestehenden Kontos wird niemals geändert. Der Befehl kann für mehrere Administratoren ausgeführt werden.
--list: Listet Konten auf, die die Rolle „Admin“ innehaben (E-Mail-Adresse, Benutzer-ID, Rollenkennzeichen, Name, Angabe, ob ein
Passwort festgelegt ist).
--revoke: Entfernt die Rolle „Admin“; das Konto und seine übrigen Rollen bleiben erhalten.
phis site user --site <site key> --email <email> --password <pw> [--overwrite]
Legt das Passwort eines bestehenden Kontos fest, das Mitglied der Site ist. Der Befehl wird abgelehnt, wenn das Konto
bereits über ein Passwort verfügt, es sei denn, die Option --overwrite wird angegeben. Die Anmeldedaten gehören zum Konto, nicht zur
Site, sodass dadurch jede Site geöffnet wird, deren Mitglied das Konto ist; der Befehl gibt an, wie viele dies sind.
phis site check --key <site key> [--url <base url>]
Fragt eine laufende Site ab, welche ihrer Module deaktiviert sind, weil eine Serverfunktion fehlt:
GET <base url>/api/site/module-diagnostics mit dem Header
api.internalToken. Die Basis-URL
ist standardmäßig
http://<host>:<port> der ersten konfigurierten Instanz der Site (siehe
site config). Gibt den Wert
1 zurück, wenn ein Modul deaktiviert ist. Erfordert
api.internalToken und eine erreichbare Site. Führen Sie den Befehl nach Server- oder Site-Updates aus.
phis site config
Die Standorte der Instanzen werden aus der Datei phis-config.json abgeleitet, sofern sie nicht in
sites.overrides.<key> der Datei phis-runtime.json überschrieben werden:
Der Quellpfad ist zugleich der Standardwert für --path, init, reconcile, update und module.
phis site config set source --key <site key> [--source-host <host> --source-port <port> --source-path <path>]
Schreibt sites.overrides.<key>.source in die Datei phis-runtime.json. Alle drei Flags zusammen aktivieren diese Einstellung; kein einziges
deaktiviert sie. Wird von site config nginx --source verwendet, um als Proxy für einen Entwicklungsserver zu fungieren.
phis site config add --key <site key> --instance-host <host> [--instance-port <port>] --instance-path <path>
Fügt eine Instanz zu sites.overrides.<key>.instances hinzu. Sobald eine Instanz dort aufgeführt ist, wird die abgeleitete
Standardinstanz nicht mehr verwendet.
phis site config del --key <site key> --instance-host <host>
Entfernt alle aufgeführten Instanzen auf diesem Host.
phis site config nginx|apache|systemd|docker-compose|runtime --key <site key>
phis site config nginx --key <site key> [--source]
phis site config systemd --key <site key> [--instance <n>]
Gibt einen Konfigurationsausschnitt auf stdout aus. Es wird nichts geschrieben oder installiert. Mit der Option --json befindet sich der
Ausschnitt in der Datei config neben dem Site-Eintrag; die Option runtime --json gibt die strukturierte Zusammenfassung aus.
nginx: Eine Datei für den http-Kontext von nginx (unter Debian: /etc/nginx/sites-available/<key>.conf
, mit einem Symlink aus dem Verzeichnis sites-enabled/ verknüpft, die von nginx.conf innerhalb von http {} eingebunden wird). Sie enthält in folgender Reihenfolge:
map $http_upgrade $phis_site_<key>_connection: upgrade, wenn die Anfrage ein Protokoll-Upgrade
erfordert, andernfalls leer;
upstream phis_site_<key> mit einer server-Zeile für jede Instanz (127.0.0.1:<port> für einen
lokalen Host, andernfalls <host>:<port>), keepalive 64 und keepalive_timeout 4s;
ein serverblock für server_name <hostname> auf Port 80 mit client_max_body_size 2g,
der den location / an den Upstream weiterleitet, mit proxy_http_version 1.1, Host $http_host,
Upgrade $http_upgrade, Connection $phis_site_<key>_connection sowie den Weiterleitungs-Headern
(X-Forwarded-Host $http_host).
keepalive_timeout
bleibt unter dem Keep-Alive-Timeout von Node von 5 s; andernfalls verwendet nginx eine
Verbindung wieder, die Node geschlossen hat, und ein POST
-Aufruf schlägt mit dem Fehler 502
fehl. Host $http_host
behält einen nicht standardmäßigen
Port bei, den das Formular-Relay der Website mit dem Referer
vergleicht. Namen enthalten den Site-Schlüssel (Zeichen,
die keine Buchstaben, Ziffern oder _
sind, werden zu _
), sodass die Dateien mehrerer Sites
gemeinsam eingebunden werden können. Mit der Option --source
ist der Upstream stattdessen die Quell-Überschreibung, und es wird ein Verzeichnis /_next/webpack-hmr
für einen Entwicklungsserver hinzugefügt. Kein TLS.
apache: ein VirtualHost *:80 mit ProxyPass / http://127.0.0.1:<port>/ für die primäre
Instanz (die erste lokale Instanz, andernfalls die erste).
systemd: Eine Unit für eine Instanz, die /usr/bin/node server.js als Benutzer phis im
Instanzpfad ausführt, mit NODE_ENV=production, HOSTNAME=127.0.0.1, PORT=<port>, Restart=always,
sowie einer auskommentierten Einstellung Environment=PHIS_RENDER_CACHE_MB=128 (die prozessspezifische Speicherbegrenzung des Render-Caches
). HOSTNAME bindet die Site an den Loopback-Adressraum, sodass nur der Proxy darauf zugreifen kann. Ohne
--instance gilt die Einheit für die primäre Instanz; --instance <n> wählt die n-te (ab 0) Instanz, wie sie
in der site config runtime-Liste aufgeführt sind, sodass eine Site mit mehreren Instanzen jeweils eine Einheit erhält. Die Einheit verfügt über
kein ExecStop: phis instance drain gilt für Serverinstanzen, und eine Site meldet keine Betriebsbereitschaft.
docker-compose: Ein Dienst-Grundgerüst mit einem Platzhalter-Image.
runtime: the Site row and its resolved source and instance locations.
init, reconcile, update (Site-Scaffold)
phis init <site key> --api-base-url <url> [--path <dir>] [--package-manager pnpm|npm|yarn|bun] [--install]
phis reconcile <site key> [--path <dir>] [--package-manager pnpm|npm|yarn|bun] [--install]
phis update <site key> [--path <dir>] [--package-manager pnpm|npm|yarn|bun]
Die Zeile „Site“ muss vorhanden sein (Befehl: phis site add). Der Site-Schlüssel ist positionsabhängig.
Das Scaffold (Version 3) wird von der Datei src/lib/site-scaffold.mts generiert.
Paketmanager
Ohne die Option --package-manager verwendet init npm, während reconcile und update den site-eigenen
Manager verwenden: den in package.json unter packageManager angegebenen Manager oder andernfalls den Manager, dessen Lockfile die Site enthält
(pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock/bun.lockbb). Eine Site, die weder über eines noch über das andere verfügt
oder Lockfiles mehrerer Manager enthält, wird abgelehnt, bis mit der Option --package-manager ein Manager angegeben wird. Es wird kein Lockfile
gelöscht.
Bei Verwendung von --package-manager wird dieser Manager verwendet, die Sperrdateien der anderen Manager werden gelöscht,
und packageManager wird auf <manager>@<version> gesetzt, sofern ein anderer Manager angegeben wurde.
phis init <site key> --api-base-url <url>
Erstellt ein neues Site-Repository. Schlägt fehl, wenn das Ziel bereits existiert und kein leeres Verzeichnis ist
(
Site target ... already exists; use phis reconcile), wenn
--api-base-url fehlt oder keine
HTTP(S)-URL ist und wenn
api.internalToken im phis-Stammverzeichnis nicht gesetzt ist. Schreibt jede Scaffold-Datei sowie
die Datei
.phis/scaffold-manifest.json (Scaffold-Version, Site-Schlüssel, SHA-256-Hash jeder geschriebenen Datei). Eine Liste der Dateien finden Sie in der Datei
INSTALL.md.
In der Datei config/site-runtime.json werden site.key, site.publicUrl (die öffentliche Basis-URL der Website, andernfalls
https://<hostname>), phis.apiBaseUrl, phis.internalToken (api.internalToken) und
network.internalApiTimeoutMs (8000) gespeichert. Diese Datei wird ausschließlich von init geschrieben.
phis reconcile <site key>
Überträgt ein vorhandenes Site-Repository in das aktuelle Scaffold:
Fehlende kanonische Dateien werden erstellt, Dateien, die Abweichungen aufweisen, werden überschrieben (und repaired).
Änderungen, die an diesen Dateien vorgenommen wurden, gehen verloren.
Im Stammverzeichnis der Website muss sich eine Datei package.json befinden (ansonsten gilt: No Site at ...).
package.json wird durch Hinzufügen und nicht durch Zurücksetzen zusammengeführt: Eine Abhängigkeit (in dependencies oder
devDependencies), ein Skript oder ein Feld auf oberster Ebene, das das Scaffold benötigt und in der Site fehlt, wird mit
dem Wert des Scaffolds hinzugefügt; alles, was die Site bereits enthält, behält den Wert der Site bei, einschließlich Versionsbereiche
wie beispielsweise @phis/ui. Zwei Ausnahmen: engines.node wird auf den Wert des Scaffolds >=24.21.0 gesetzt
(andere engines-Schlüssel bleiben unverändert), und packageManager ändert sich nur bei expliziter Angabe von
--package-manager (siehe oben).
Dateien, die zur Website gehören (PHI_SITE_OWNED_AFTER_INIT), werden, sofern vorhanden, unverändert belassen: .gitignore, die
Modulprojektion src/generated/site-modules.ts, site-modules-client-<area>.ts (eine pro Bereich),
site-modules-authoring-client.ts, site-modules-fonts.ts, site-module-packages.json und
config/site-runtime.json. Eine
fehlende .gitignore- oder Projektionsdatei wird mit ihrem ursprünglichen Inhalt neu erstellt. Eine fehlende
config/site-runtime.json-Datei hingegen nicht: reconcile kennt weder die Serveradresse noch das Token.
Erstellen Sie diese Datei anhand von config/site-runtime.example.json.
Dateien, die vom vorherigen Scaffold (gemäß dem alten Manifest) erstellt wurden und die vom aktuellen Scaffold nicht mehr geschrieben werden, werden
gelöscht, wenn ihr Inhalt unverändert ist (removed), und an Ort und Stelle belassen, wenn die Website sie bearbeitet hat
(kept). Verzeichnisse, die durch eine Entfernung geleert wurden, werden entfernt. Dateien, die der Website gehören, werden auf diese Weise niemals entfernt.
Das Manifest wird neu geschrieben.
Die JSON-Ausgabe listet jede Datei mit der entsprechenden Aktion auf: created, repaired, unchanged, removed und kept.
Überprüfen Sie die als kept gekennzeichneten Einträge manuell; eine beibehaltene Routendatei kann an ihrem neuen Speicherort zu Konflikten führen.
phis update <site key>
reconcile (mit derselben package.json-Regel: Versionen bleiben erhalten), anschließend im Site-Verzeichnis:
install (pnpm install --no-frozen-lockfile, npm install, yarn install, bun install),
run typecheck, run build und anschließend eine Version in .phis/releases/<release id>/ verpacken.
update erhöht die Versionen der Abhängigkeiten nicht; ändern Sie diese zunächst im Site-Verzeichnis (z. B. npm install @phis/ui@<version>),
und führen Sie anschließend update aus.
Die Pressemitteilung:
ist eine Kopie von .next/standalone. Die darin enthaltenen Links werden als Links kopiert, sodass eine Version nicht
von .next/standalone abhängt, das durch den nächsten Build ersetzt wird.
findet die Datei server.js dort, wo Next sie abgelegt hat: am Anfang von .next/standalone für eine Site, die eine eigene
Tracing-Root darstellt, oder verschachtelt unter dem Pfad der Site relativ zur Tracing-Root (eine Site innerhalb eines pnpm-
Arbeitsbereichs: .next/standalone/<site dir>/server.js, wobei sich node_modules ganz oben befindet). Schlägt fehl, wenn
keine vorhanden ist. Bei einem verschachtelten Build startet eine server.js-Datei an der obersten Ebene der Release-Struktur den verschachtelten Build, sodass jeder
Release mit dem Befehl node server.js in seinem Verzeichnis gestartet wird.
ruft .next/static und public/ neben dieser server.js-Datei ab.
enthält keine Datei config/site-runtime.json. Der Dateitracer von Next kopiert die Datei in das Verzeichnis
.next/standalone; dabei werden alle Dateien mit diesem Namen ausgelassen. Stattdessen erhält das App-Verzeichnis
config/site-runtime.json als relativen Verweis auf die Datei „config/site-runtime.json“ im Stammverzeichnis der Website
config/site-runtime.json. Der eigenständige Server wechselt in sein eigenes Verzeichnis, bevor er
die Datei liest; daher liest ein Release-Lauf, bei dem update die Datei erstellt hat, die aktuelle Datei der Site. Ein Release, das
auf einen anderen Host kopiert wird, benötigt die Datei dieses Hosts unter <release>/config/site-runtime.json (ersetzen Sie den Link).
enthält die Datei release.json (releaseId, scaffoldVersion, buildId, appDirectory, createdAt).
update prints a note when the Site root has no config/site-runtime.json. Nothing is deployed or
restarted; the release directory is what an instance path points at. The scaffold's .gitignore
ignores .phis/releases/; a Site created before that entry was added needs it added by hand, because
reconcile does not rewrite .gitignore.
Eine laufende Site liest die Datei config/site-runtime.json einmal pro Prozess; starten Sie die Site nach einer Änderung an dieser Datei neu.
Modul (Website-Module)
Ein Site-Modul ist ein Paket, das der Site-Build über die generierte Projektion
src/generated/site-modules*.ts importiert. Der gewünschte Zustand ist die Datei config/phis-modules.json im phis-Stammverzeichnis.
module-Befehle laden niemals Pakete herunter und führen niemals einen Build durch.
Die Projektion besteht aus folgenden Dateien: site-modules.ts (Server), je eine site-modules-client-<area>.ts-Datei pro
Bereich, site-modules-authoring-client.ts, site-modules-fonts.ts und site-module-packages.json. Die
Namen der installierten Pakete, die in der next.config.ts-Datei des Scaffolds aufgeführt sind, werden in transpilePackages übernommen – ein Paket aus
einem Tarball oder einer Registry wird nur dann kompiliert, wenn es dort aufgeführt ist, und der Bereich ./fonts lädt andernfalls nichts
. Alles, was sich nicht im
gewünschten Zustand befindet, wird aus dem Manifest des jeweiligen Pakets im Verzeichnis node_modules der Website ausgelesen, da kein Befehl
ein Modul ausführt: Die Bereiche in der Datei package.json#phis (modules[].eligibleAreas) werden als Platzierungen in die Server-Datei
geschrieben und legen fest, welche Bereichsdateien die Client-Schnittstelle des Pakets importieren; die exports entscheiden,
ob die „fonts“-Datei ./fonts importiert – dieser Bereich ruft next/font/local auf und wird außerhalb eines
Next-Builds abgebrochen. Ein noch nicht installiertes Paket hat keine der beiden Antworten: Es verbleibt in der Server-Datei, wo
der Build der Site es anhand seines Namens ablehnt, und add sowie sync weisen an, sync auszuführen, sobald es installiert ist.
--path (default: the Site source path as for init) selects the Site repository for every command
except list. Those commands refuse to run when the directory holds no package.json
(No Site at <path>), so a wrong --path does not record a Module for a directory no build reads.
phis module list [--site <site key>]
Listet die installierten Module pro Standort auf (packageName, origin, spec). Liest ausschließlich den gewünschten Status aus.
phis module add --site <site key> --package <@scope/name> [--spec <spec>] [--path <dir>]
Registriert das Modul und schreibt die Projektion neu. Mit --spec (einem Versionsbereich oder workspace:*) wird das
Paket zudem zu den Abhängigkeiten in der Datei package.json der Site hinzugefügt (resolved nach Ursprung); ohne diese Angabe muss das
Paket bereits auflösbar sein (local nach Ursprung). Anschließend wird das installierte Paket überprüft und
es werden etwaige Probleme angezeigt oder der Hinweis not installed yet, falls das Paket vor dem Ausführen des Paketmanagers noch nicht installiert war. Das Programm beendet sich mit dem Status 1, wenn bei der Überprüfung
Probleme festgestellt werden. Als Nächstes: Abhängigkeiten installieren, die Website neu erstellen, das Modul für einen Bereich im
Builder aktivieren. Falls das Paket noch nicht installiert war, führen Sie nach der Installation zusätzlich phis module sync aus:
Die Schriftprojektion wird aus dem installierten Paket gelesen; ohne diesen Befehl bleiben die Schriftarten eines Moduls
aus dem Build ausgeschlossen.
phis module del --site <site key> --package <@scope/name> [--force] [--path <dir>]
Entfernt das Modul aus dem gewünschten Zustand, seine Abhängigkeit aus der Datei package.json und schreibt die
Projektion neu. Der Vorgang wird abgelehnt, wenn Blöcke, die zu diesem Paket gehören, noch auf veröffentlichten Seiten dargestellt werden, und listet
diese nach Bereichen auf; mit dem Parameter --force wird das Modul dennoch entfernt (die Blöcke verbleiben auf ihren Seiten, werden jedoch nicht mehr dargestellt).
Erstellen Sie die Website anschließend neu.
phis module sync --site <site key> [--path <dir>]
Schreibt die Projektion ausgehend vom gewünschten Zustand neu, beispielsweise nach einem Scaffold, einer manuellen Bearbeitung oder der
Installation, die auf ein add folgte. Die installierten Pakete werden erneut eingelesen, sodass eine ./fonts-Grenze, die
mit der Installation eingespielt wurde, hier in site-modules-fonts.ts ankommt. Führen Sie anschließend einen Neuaufbau durch.
phis module check --site <site key> [--package <@scope/name>] [--path <dir>]
Überprüft die installierten Modulpakete im Verzeichnis node_modules der Website anhand des Modulvertrags.
Schlägt fehl, wenn unter dem Pfad keine package.json-Datei vorhanden ist; gibt den Exit-Code 1 zurück, wenn bei einem Paket Probleme auftreten.
Add-on (Server-Add-ons)
Ein Server-Add-on entspricht einem
addon.mjs-Artefakt.
config/phis-addons.json gibt den gewünschten Zustand an, die
Datenbankregistrierung dient als Grundlage für die Verteilung durch den Server, und
reconcile sorgt für die Synchronisierung zwischen beiden.
Die erfasste Release-ID entspricht der Paketversion der CLI. Der Lebenszyklus wird in
ADDON_HOWTO.md beschrieben.
Fehlt die Datei config/phis-addons.json, wird dies als „Keine Add-ons installiert“ interpretiert; das erste addon installiert diese Datei.
phis addon list
Listet installierte Add-ons auf (addonId, enabled, package@version). Einträge, die nicht mehr
mit dieser Version kompatibel sind, werden zuerst aufgeführt; beendet den Prozess mit dem Status 1, sobald solche Einträge vorhanden sind. Nur Dateien.
phis addon check
Überprüft jeden Eintrag: Manifest-Prüfsumme, Vorhandensein des Artefakts und Übereinstimmung mit dessen Prüfsumme; es dürfen keine zwei Add-ons
denselben Dienstanbieter beanspruchen. Meldet Suchanfragen ohne Textindex. Beendet den Vorgang mit dem Status 1, wenn ein
Eintrag nicht gültig ist, und gibt die weitere Vorgehensweise aus (upgrade oder remove). Nur Dateien.
phis addon install --artifact <path>
Importiert das Artefakt einmal, um dessen Manifest zu lesen und zu validieren, kopiert es nach
addons/<scope>/<name>/<version>/addon.mjs und vermerkt es als deaktiviert. Lehnt eine Add-on-ID oder
einen Paketnamen ab, der bereits installiert ist. Nächste Schritte: reconcile, migrate, enable, reconcile.
phis addon upgrade --addon <@scope/name> --artifact <path> [--repackage]
Installiert ein neueres (oder ein Artefakt derselben Version, das sich jedoch in den Bytes unterscheidet) neben dem alten und verweist den
Eintrag neu darauf; der aktivierte Status bleibt erhalten. Eine andere Add-on-ID, eine niedrigere Schemaversion, das
identische Artefakt und einen geänderten Paketnamen werden abgelehnt, sofern nicht --repackage
angegeben wurde. Bis zum nächsten reconcile
(und migrate
, falls die Schemaversion erhöht wurde) gibt das Add-on den Status 503
zurück. Das Zurücksetzen erfolgt durch ein upgrade
mit dem älteren Artefakt.
phis addon migrate [--addon <@scope/name>]
Leitet das Schema eines Add-ons oder aller installierten Add-ons mit
database.migrationUri ab und wendet es an, wobei der servierenden Rolle (dem Benutzer unter database.uri) Zugriff gewährt wird. Unverändert
Add-ons melden sich already at schema version. Eine Wiederholung ist unbedenklich.
phis addon enable|disable --addon <@scope/name>
Änderungen werden nur im gewünschten Zustand enabled. Sie werden erst nach dem Befehl phis addon reconcile wirksam.
phis addon reconcile
Schreibt den gewünschten Zustand für diese Version in die Registrierung, erfasst den aktuellen Status jedes Add-ons
auf den Websites, die es angefordert haben (available oder disabled), und erstellt Gruppen, die in einem Manifest für
Websites deklariert sind, auf denen das Add-on aktiviert ist. Gruppen werden hier niemals deaktiviert. Benötigt die Datenbank.
phis addon remove --addon <@scope/name>
Wird abgelehnt, solange das Add-on aktiviert ist. Löscht alle Installationsverzeichnisse des Add-ons sowie dessen
Eintrag im gewünschten Status. Die Daten bleiben erhalten; siehe purge.
phis addon purge --addon <@scope/name>
Zerstörerisch und irreversibel. Wird ausgeführt, solange das Add-on noch installiert ist. Mit
database.migrationUri wird das Schema des Add-ons gelöscht und jeder Datensatz daraus entfernt (Site-Zuordnungen,
angewandte Migrationen, Katalogzeile, gespeicherte Geheimnisse); die zugehörigen Medienobjekte werden zur Entfernung durch die
betreibende Instanz markiert und anschließend die Objekte aus den Site-spezifischen Speichern gelöscht.
phis addon forget --addon <@scope/name>
Entfernt den Eintrag aus der Datei phis-addons.json, ohne ihn zu validieren, um einen gewünschten Zustand zu erreichen, der nicht mehr
mit dieser Version kompatibel ist. Das Artefakt verbleibt auf der Festplatte. Gilt nur für Dateien.
phis addon site
phis addon site --addon <@scope/name>
phis addon site --addon <@scope/name> --site <site key> --enable [--without-module]
phis addon site --addon <@scope/name> --site <site key> --disable
Ohne --enable/--disable: Listet die Websites auf, für die das Add-on aktiviert ist (Website-ID, angefordert,
Konfigurationsstatus, Gültigkeitsstatus).
--enable: Fordert das Add-on für die Site an, ermittelt den Konfigurationsstatus anhand der angegebenen
Einstellungen und erstellt die darin deklarierten Gruppen. Falls das Add-on über einen Modul-Teil verfügt (mit demselben Paketnamen),
den die Site nicht in der Datei phis-modules.json enthält, wird der Vorgang abgelehnt; führen Sie zunächst phis module add aus und
erstellen Sie die Konfiguration neu, oder übergeben Sie den Parameter --without-module, um nur den Server-Teil zu aktivieren.
--disable: Zieht die Anfrage zurück und löscht die Gruppen des Add-ons auf dieser Website. Die Ausführung wird verweigert, wenn das
Add-on dort nie aktiviert wurde.
phis addon config --addon <@scope/name> --site <site key> [--name <setting> [--value <value>]]
Ohne --name: Listet die deklarierten Einstellungen mit dem gespeicherten Wert oder dem Standardwert auf.
--name with --value: validates and stores the value. An empty value (--value "" or
--value=) is a value and is validated like any other.
--name without --value: clears the stored value, so the declared default applies.
Die Ausführung wird verweigert, wenn das Add-on für die Website nicht aktiviert ist (führen Sie zunächst den Befehl addon site --enable aus).
phis addon role
phis addon role --site <site key> [--addon <@scope/name>]
phis addon role --site <site key> --user <user id>
phis addon role --site <site key> --addon <@scope/name> --user <user id> --grant <role>
phis addon role --site <site key> --addon <@scope/name> --user <user id> --revoke <role>
Ohne --user: Listet die Rollen auf, die jedes installierte Add-on (bzw. das angegebene Add-on) definiert, sowie die Personen, die diese Rollen vergeben dürfen.
Nur --user: Listet die Add-on-Rollen auf, die der Benutzer auf der Website innehat.
--grant/--revoke: Erteilt oder widerruft eine deklarierte Rolle. Der Operator unterliegt nicht der
grantableBy-Regel der Rolle.
phis addon owner --addon <@scope/name> --site <site key> [--from <user id>|none] --to <user id>
Überträgt die Eigentumsrechte an den Zeilen des Add-ons auf dieser Site von einem Konto auf ein anderes. Ohne das Argument --from (oder
mit dem Wert none) werden die Zeilen übertragen, für die niemand die Eigentumsrechte besitzt. Das Ziel muss ein Mitglied der Site sein. Tabellen ohne eine
„Site“-Spalte werden übersprungen und aufgelistet.
phis addon storage
phis addon storage --addon <@scope/name> --site <site key> [--quota-bytes <n>] [--max-objects <n>]
[--unlimited] [--sweep] [--recount]
Zeigt die Speicherauslastung des Add-ons auf der Website an (Bytes und Objekte im Verhältnis zu ihren Obergrenzen) und optional:
Das Festlegen einer Obergrenze wird abgelehnt, wenn das Add-on für die Website nicht aktiviert ist. --sweep wird vor
--recount ausgeführt. Beide greifen direkt auf den Speicher zu; dies funktioniert sowohl für den integrierten lokalen Speicher als auch für Anbieter
aus installierten Add-ons.
phis addon job --addon <@scope/name> --job <job id> --site <site key> --api-base-url <url>
Fordert den laufenden Server auf, einen deklarierten Job für eine Site auszuführen: POST <api base url>/api/v1/addons/jobs
unter Verwendung des internen Tokens. --api-base-url ist erforderlich; dabei handelt es sich um die Adresse des Servers, wie sie von dem Ort aus erreichbar ist, an dem die
CLI ausgeführt wird (Debian-Paket: http://127.0.0.1:5301); es gibt keinen Standardwert. Beendet den Vorgang mit dem Status 1, wenn der Server
die Anfrage ablehnt. Erfordert api.internalToken und einen laufenden Server.
Speicherung (Speicherprofile)
Ein Speicherprofil verknüpft einen Standort mit einem Medien-Speicheranbieter unter Angabe dessen Konfiguration und einer Referenz auf Anmeldedaten.
Der integrierte Anbieter ist der lokale Speicher von Core; weitere Anbieter stammen aus installierten
Add-ons. Siehe
GROUPS_AND_STORAGE.md.
--site wird wie bei jedem anderen Befehl in Kleinbuchstaben geschrieben.
phis storage list --site <site key>
Listet die Profile der Website auf und gibt an, in welches Profil die einzelnen Medienbereiche neue Uploads schreiben.
phis storage add --site <site key> --key <profile key> --provider <provider id> [--config <json|@file>] [--secret-name <name>|--secret-reference <ref>]
Überprüft die Konfiguration anhand der provider-eigenen Factory (für „Local“: rootDir absolut,
storageKeyPrefix relativ), fügt das Profil ein, testet es und schreibt die CORS-Regeln jedes
Profils. --config @file liest JSON aus einer Datei, die relativ zum „phis“-Stammverzeichnis aufgelöst wird. --secret-name
erstellt die Referenz site:<site>:addon:<provider add-on>:<name> (oder ...:core:<name>);
--secret-reference akzeptiert eine vollständige Referenz. Speichern Sie das Geheimnis zunächst mit phis secret set.
phis storage set --site <site key> --key <profile key> [--config <json|@file>] [--replace] [--secret-name|--secret-reference]
Fügt --config in die gespeicherte Konfiguration ein (--replace ersetzt diese), ändert optional den
Verweis auf die Anmeldedaten, führt eine Validierung durch, führt erneut einen Test durch und schreibt die CORS-Regeln neu.
phis storage use --site <site key> --key <profile key>
Legt den Site-Speicherbereich (nicht den Benutzer- oder Gruppen-Speicherbereich) im Profil für neue Uploads fest. Vorhandene Assets verbleiben
an ihrem bisherigen Speicherort. Der Vorgang schlägt fehl, wenn der Site-Speicherbereich noch nicht existiert; er wird erst angelegt, wenn zum ersten Mal Medien
verwendet werden.
phis storage del --site <site key> --key <profile key>
Löscht das Profil. Der Vorgang wird abgelehnt, solange ein Raum oder ein Objekt dieses Profil noch nutzt.
phis storage cors
Schreibt die CORS-Regel jedes externen Speichers aus dem Site-Register (den öffentlichen Basis-URLs der Sites).
Führen Sie diesen Vorgang aus, nachdem Sie die öffentliche Basis-URL einer Site geändert haben.
phis storage probe --site <site key> [--key <profile key>]
Prüft jedes externe Profil (Schreibbarkeit, verifizierte Prüfsummenalgorithmen) und protokolliert das Ergebnis sowie den
Prüfsummenalgorithmus des Profils. Der lokale Anbieter wird nicht geprüft.
Geheimnis
Geheimnisse werden verschlüsselt in phis.server_secrets unter Verwendung von secrets.encryptionKey gespeichert. Ein Verweis lautet
[site:<site key>:](core|addon:<@scope/name>):<name>; Namen bestehen aus Kleinbuchstaben, [a-z0-9._-] und dürfen bis zu
64 Zeichen lang sein.
phis secret init-key
Schreibt einen neuen zufälligen secrets.encryptionKey (Version 1) in die Datei phis-runtime.json. Der Vorgang wird abgebrochen, wenn bereits ein Schlüssel
vorhanden ist, da dessen Ersetzung dazu führt, dass alle gespeicherten Geheimnisse unlesbar werden. Jede Serverinstanz benötigt denselben
Schlüssel.
phis secret set --name <name> [--site <site key>] [--addon <@scope/name>] [--value <value>]
Speichert oder ersetzt ein Geheimnis. Der Wert wird aus stdin eingelesen (ein abschließendes Zeilenendezeichen wird entfernt); stdin darf
kein Terminal sein. Die Option --value funktioniert zwar, es wird jedoch eine Warnung ausgegeben, da der Wert in der Prozessliste und
im Shell-Verlauf sichtbar ist. Ein leeres --value wird nicht akzeptiert.
printf '%s' "$SMTP_PASSWORD" | phis secret set --name smtp-password --site acme
phis secret check --name <name> [--site] [--addon]
configured, missing oder unreadable (gespeichert, aber mit dem aktuellen Schlüssel nicht entschlüsselbar) Ausdrucke
ohne den Wert auszudrucken. Bei unreadablen Ergebnissen wird der Exit-Code 1 zurückgegeben.
phis secret list [--site <site key>] [--addon <@scope/name>]
Listet Referenzen, Schlüsselversionen und Aktualisierungszeitpunkte auf. Niemals Werte.
phis secret del --name <name> [--site] [--addon]
Löscht das Geheimnis.
auth
phis auth restore-preset --site <site key>
Stellt die Benutzeroberfläche für die First-Party-Authentifizierung (@phis/ui/modules/auth) als Authentifizierungsanbieter in den
öffentlichen, App- und Admin-Bereichen der Website wieder her, deaktiviert dort ein Modul eines fremden Authentifizierungsanbieters und löscht
die durch Seitenvoreinstellungen vorgenommenen Überschreibungen der Authentifizierungsseiten. Idempotent; gibt pro Bereich aus, ob sich etwas geändert hat und
welches Modul für „public“/login“ zuständig ist. Verwenden Sie diese Funktion, wenn sich eine Website durch die Auswahl ihres Authentifizierungsmoduls
selbst ausgesperrt hat.
phis auth import-secrets
Verschiebt die nicht mehr verwendete Klartext-auth.secrets-Zuordnung aus der Datei phis-runtime.json in den verschlüsselten Speicher,
schreibt gespeicherte Verweise in die neue Form um und entfernt auth.secrets aus der Datei, sobald alle Daten
importiert wurden. Erfordert secrets.encryptionKey.
Operator
Plattformbetreiber sind die Konten der Betreiber-Benutzeroberfläche (/operator). Sie sind in
platformSuperUsers der Datei phis-runtime.json (argon2-Passwort-Hashes) gespeichert, nicht in der Datenbank. Der Server
speichert diese Datei bis zu vier Stunden lang im Cache: Starten Sie ihn nach jedem operator-Befehl neu, der Änderungen bewirkt,
da sich sonst ein neuer Operator nicht anmelden kann, während ein entfernter oder deaktivierter Operator dies weiterhin kann, bis der Cache
abläuft.
Operator-Sitzungs-Cookies werden ausschließlich mit operator.sessionSecret signiert – und mit nichts anderem, also nicht mit
api.internalToken, über das jede Site-Laufzeitumgebung verfügt.
Die Cookies sind zustandslos; was also eine Sitzung beendet, ist die sessionGeneration des Operators in
platformSuperUsers: Jedes Cookie enthält den Wert, mit dem es signiert wurde, und bei jeder Anfrage wird dieser
mit der Laufzeitdatei abgeglichen. Das Abmelden und der Befehl phis operator passwd erhöhen den Zählwert, wodurch jede Sitzung
des Operators beendet wird – einschließlich eines kopierten Cookies. Die Sitzungen eines entfernten oder deaktivierten Operators enden auf dieselbe
Weise, und zwar bei deren nächster Anfrage.
Passwörter, die über die Befehlszeile eingegeben werden, sind in der Prozessliste und im Shell-Verlauf sichtbar. Ein Passwort,
das mit einem Bindestrich (-) beginnt, wird unverändert weitergegeben (--password -x1 oder --password=-x1).
Medien
Für jedes rootDir eines lokalen Speicherprofils wird das Verzeichnis durchlaufen und es werden Einträge gemeldet, die nicht dem
Eigentümer des Stammverzeichnisses selbst (dem Konto, unter dem der Server läuft) gehören. Beendet das Programm mit dem Status 1, wenn
Funde vorliegen und --fix nicht angegeben wurde. --fix setzt die Eigentumsrechte zurück (chown), wofür ein Benutzer
erforderlich ist, der dazu berechtigt ist, in der Regel root. Fehlende root-Rechte werden gemeldet.
pflegen
phis maintain [--list] [--task <id>] [--dry-run]
Führt begrenzte, idempotente Bereinigungsaufgaben in der unten angegebenen Reihenfolge aus. Mit --list werden diese angezeigt. Aufgaben:
--task führt eine Aufgabe aus, --dry-run gibt eine Meldung aus, ohne etwas zu ändern. Eine fehlgeschlagene Aufgabe wird gemeldet, und die
anderen werden weiterhin ausgeführt; der Exit-Code beträgt 1, wenn eine Aufgabe fehlgeschlagen ist. Die Ausführung über einen Timer ist unbedenklich.
E-Mail
phis mail drain [--limit <rows>] --api-base-url <url>
Versendet die noch ausstehenden Benachrichtigungen aus dem Benachrichtigungs-Ausgang (phis.notification_outbox). Eine Benachrichtigung wird
einmal von der Anfrage versucht, die sie erstellt hat; dieser Befehl dient als Wiederholungsversuch und ist dafür vorgesehen, über einen Timer ausgeführt zu werden. Er
sendet eine Anfrage an <api base url>/api/v1/notifications/drain mit dem internen Token, sodass der Drain im
Serving-Prozess ausgeführt wird, in dem sich die E-Mail-Konfiguration, der Übersetzungscache und der Transport befinden.
--api-base-url is required, the server's address as reached from where the CLI runs (Debian package:
http://127.0.0.1:5301); there is no default. --limit is the number of rows to claim in one run, a positive whole number; the server takes 100
when it is not given and never more than 1000. The command prints how many rows it claimed, sent,
dropped and failed, or the server's JSON answer with --json. It exits 1 when the server refuses or
fails the request. Requires api.internalToken and a running server.
Lizenzen
phis licenses check [--package <directory>]
Überprüft die installierten Produktions- und Entwicklungsabhängigkeiten eines Pakets (Standard: @phis/server
selbst) und meldet nicht zulässige Lizenzen. Ein in der Produktion festgestellter Verstoß, der in
src/cli/licenses.mts
nicht berücksichtigt ist, wirkt blockierend und führt dazu, dass der Befehl mit dem Exit-Code 1
beendet wird. Es ist weder eine phis-Root-Konfiguration
noch die Datenbank erforderlich.
Beispiel
Jeder Serverprozess schreibt eine Heartbeat-Zeile in die Tabelle phis.server_instances (Release-ID, Add-on-Digest,
Bereitschaftsstatus).
phis instance list [--stale-after <seconds>]
Listet Instanzen auf; eine Instanz gilt nur dann als bereit, wenn sie sich innerhalb von --stale-after Sekunden
(Standard: 90) als bereit gemeldet hat. Meldet, wenn mehrere Releases oder Add-on-Sets gleichzeitig bereitgestellt werden, was bedeutet, dass ein
Rollout noch nicht abgeschlossen ist, und beendet in diesem Fall den Prozess mit dem Status 1, sodass ein Bereitstellungsskript darauf warten kann.
phis instance drain [--id <instance id>]
Markiert die Instanz als nicht bereit, sodass ein Load Balancer keine Anfragen mehr an sie weiterleitet; die Zeile bleibt erhalten. Die ID
lautet standardmäßig PHIS_INSTANCE_ID, andernfalls <hostname>:<root>. Führen Sie diesen Befehl aus, bevor Sie einen Serverprozess beenden; die
Debian-Einheit phis@.service führt ihn als ExecStop aus.
phis instance prune [--forget-after <seconds>]
Löscht Zeilen mit Instanzen, die länger als --forget-after Sekunden inaktiv waren (Standardwert: 2592000, 30 Tage).
Häufige Aufgaben
Zahlungsprofile
Core verwaltet Händlerprofile und explizite Verbraucherberechtigungen. Die CLI verwendet ausschließlich installierte Provider-Artefakte;
keine Profildatei kann einen Paketimport auswählen oder einen Anmeldewert bereitstellen.
Vor dem ersten Profil: Wenden Sie das Core-Schema mit dem Befehl
phis schema apply an. Dadurch werden die „Payment“-Tabellen
angelegt; bereits vorhandene Tabellen werden jedoch nicht geändert. Daher müssen in einer Datenbank, in der die Tabelle
phis.addon_event_outbox bereits vor „Payments“ existierte, die neuen Spalten und Einschränkungen dieser Tabelle
manuell hinzugefügt werden, bevor ein „Payment“-Consumer zugelassen wird (
DB.md).
Installieren und aktivieren Sie anschließend das Provider-Add-on, aktivieren Sie es für die Website, die Zahlungen entgegennehmen soll
(`
phis addon site --enable`), und speichern Sie die Anmeldedaten mit `
phis secret set`, wobei Sie den Wert über
die Standard-Eingabe (stdin) statt über die Befehlszeile übergeben.
phis payment profile list --site demo
phis payment profile add --site demo --file /protected/path/stripe-sandbox.json
phis payment profile set --site demo --file /protected/path/stripe-sandbox.json
phis payment profile probe --site demo --key stripe-sandbox --currency CHF
phis payment profile enable --site demo --key stripe-sandbox --currency CHF
phis payment profile retire --site demo --key stripe-sandbox
phis maintain --task payments --dry-run
phis maintain --task payments
Datei hinzufügen/festlegen (nur Referenzen; die darin enthaltenen Richtliniennamen müssen im installierten Consumer-Manifest vorhanden sein):
{
"key": "stripe-sandbox",
"providerKey": "@phis/stripe/stripe",
"mode": "test",
"credentialReferences": {
"apiKey": "site:demo:addon:@phis/stripe:stripe-sandbox-api",
"webhookSecret": "site:demo:addon:@phis/stripe:stripe-sandbox-webhook"
},
"grants": [{
"consumerAddonId": "@example/shop",
"operations": ["read", "create", "complete", "refresh", "capture", "cancel", "refund"],
"merchantActions": {
"capture": { "roles": [], "jobs": [], "events": [] },
"cancel": { "roles": [], "jobs": [], "events": [] },
"refund": { "roles": [], "jobs": [], "events": [] }
}
}]
}
Der Verbraucher muss payments:v1 anfordern und payment.changed deklarieren. Leere Händlerrichtlinien erlauben
nur einem authentifizierten Betreiber oder Site-Administrator innerhalb dieser Verbraucher-/Profilberechtigung. „Add“ ist zunächst deaktiviert;
„Set“ behält den festgelegten Händler/Anbieter/Modus bei, erhöht die Revisionsnummer und deaktiviert die Neuanlage,
bis „reprobed/enabled“ erfolgt ist. Das Ändern von Anbieter, Konto oder Modus erfordert einen neuen Schlüssel. Ausgelaufene Schlüssel werden nicht
wiederverwendet, aber vorhandene Zahlungsnachweise und Abrechnungen bleiben verfügbar. Es wird keine Profil-Löschung oder
finanzielle Bereinigung angeboten. Durch das Entziehen der Berechtigung werden vorhandene Datensätze für diesen Verbraucher ausgeblendet, ohne dass
finanzielle Nachweise gelöscht werden.
Die Probe ist gegenüber dem PSP schreibgeschützt und erfasst Merkmale wie Händleridentität, Modus und Zahlungsmethode; bei einem geänderten
Händler oder Modus schlägt der Vorgang fehl. Aktivieren Sie die Probes erneut und stellen Sie sicher, dass jede bereite Serverinstanz (innerhalb des
bestehenden 90-Sekunden-Bereitheitsfensters) die installierte Provider-Version und die Core-Payment-Funktionen
enthält. Es kann nicht festgestellt werden, ob ein Webhook-Endpunkt erreichbar ist. Konfigurieren Sie das separate
Signaturgeheimnis für den Stripe-Endpunkt und überprüfen Sie die tatsächliche Zustellung von Benachrichtigungen, bevor Sie sich auf die Abwicklung verlassen.
Die Wartungsaufgabe wählt höchstens 100 offene Zahlungen aus, gleicht gespeicherte Fernbefehle ab und
meldet nicht verfügbare bzw. gleichzeitig auftretende Forderungen. Ein Testlauf bewirkt keine Änderungen und führt keine Anrufe beim Anbieter durch. Bei Wiederholungsversuchen
erfolgt weder ein Wechsel des Anbieters oder des Kontos noch die Generierung von Ersatzbefehlen für Finanztransaktionen. Es wird kein Abfrage-Timer hinzugefügt.
