Installation von phis
Diese Schritt-für-Schritt-Anleitung führt Sie Schritt für Schritt von einem neuen Linux-Host zu einem lauffähigen
@phis/server mit einer Website. Jeder
Befehl wird in
der Datei CLI.md beschrieben; die Konfigurationsschlüssel sind in
der Datei README.md aufgeführt.
In den Beispielen wird Folgendes verwendet:
Führen Sie phis mit der Option --root /srv/phis/stages/prod aus oder exportieren Sie einmalig PHIS_ROOT=/srv/phis/stages/prod; die
nachstehenden Beispiele gehen davon aus, dass die Variable exportiert ist.
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
1. Voraussetzungen
Node.js 24.21.0
oder höher für den Server, die CLI und jede Site. Frühere Versionen verursachen Speicherlecks
beim React-Flight-Rendering und stoßen unter Last an ihre Speichergrenzen.
@phis/server
deklariert
"engines": {"node": ">=24.21.0"}
; eine generierte Site tut dasselbe; das Debian-Paket hängt von
nodejs (>= 24.21.0)
ab, und die Einrichtungsseite des Servers schlägt bei einer Node-Version unterhalb dieser Grenze bei der Node-Prüfung fehl. Weder Debian 13
(trixie) noch Ubuntu 24.04 (noble) liefern Node 24 in ihrem eigenen Archiv mit; installieren Sie es daher zunächst über
NodeSource
, dessen
nodejs
-Paket diese
Abhängigkeit erfüllt. Ohne dieses Paket bricht
apt install phis
aufgrund der nicht erfüllten Abhängigkeit ab, da das in „noble“ enthaltene
nodejs
die Version 18 hat; auf einem Host, dessen NodeSource-Node älter als 24.21 ist, wird dieser zusammen mit dem Paket aktualisiert, und
Dienste, die bereits auf dem alten Node laufen, behalten diesen bis zu ihrem Neustart bei.
Es gibt keinen Paketmanager für den Server selbst, wenn dieser über das Debian-Paket oder den
Paket-Tarball installiert wird: Der Server und die phis-CLI laufen ausschließlich auf Node. pnpm wird nur benötigt, um den
Server aus dem Quellcode zu kompilieren (die Release-Version wird mit pnpm 11 kompiliert; @phis/server gibt pnpm in devEngines an, weshalb npm
sich weigert, die eigenen Skripte des Repositorys auszuführen).
Ein Paketmanager für jede Site, über den die Befehle
phis init und
phis update im Verzeichnis der Site ausgeführt werden:
Standardmäßig
npm für eine neue Site oder „yarn“, „bun“ oder „pnpm“, falls die Site einen dieser Paketmanager verwendet; siehe
Paketmanager.
PostgreSQL mit der Erweiterung pg_trgm (Debian: Bestandteil des Pakets postgresql
). Da pg_trgm eine vertrauenswürdige Erweiterung ist, kann sie von einer Rolle installiert werden, die über die Berechtigung CREATE für die Datenbank verfügt.
Ein Reverse-Proxy (nginx oder Apache) für TLS und öffentliche Hostnamen.
Ein Systemkonto, unter dem die Dienste ausgeführt werden, z. B. phis, das Eigentümer des „phis“-Stammverzeichnisses, des Stammverzeichnisses für lokale Medien und
der Verzeichnisse der Standortinstanzen ist.
Vom Server aus erreichbarer SMTP-Relay-Server für den ausgehenden Datenverkehr (email.smtp.targets), falls die Websites E-Mails versenden.
Legen Sie die beiden Datenbankrollen und die Datenbank an. Die Rolle „serving“ ist Eigentümerin des Core-Schemas phis; die
Rolle „migration“ ist Eigentümerin der Schemata der Server-Add-ons. Beide benötigen die Berechtigung CREATE für die Datenbank.
phis db bootstrap does this, once the server is installed — step 2 below, after which:
phis db bootstrap --admin-uri postgres://<admin>@<host>:5432/postgres --name prod
Es legt die Tabellen
phis_prod,
phis_prod_user und
phis_prod_migrator an, generiert für jede davon ein Passwort und schreibt
beide Verbindungszeichenfolgen in die Datei
config/phis-runtime.json, sodass die Tabelle in Schritt 2 diese nicht erneut abfragt
(
CLI.md).
--admin-uri ist eine Verbindung, die zum
Anlegen von Datenbanken und Rollen berechtigt ist und einen Host angeben muss; es muss sich dabei nicht um einen Superuser handeln.
Von Hand, entsprechend:
CREATE ROLE phis_prod_user LOGIN PASSWORD '<serving password>';
CREATE ROLE phis_prod_migrator LOGIN PASSWORD '<migration password>';
CREATE DATABASE phis_prod OWNER phis_prod_user;
GRANT CREATE ON DATABASE phis_prod TO phis_prod_migrator;
2. Installieren Sie den Server und konfigurieren Sie das physische Root-Verzeichnis
Aus der Quelle
Das Repository wird als eigenständiges Paket erstellt, so wie es im Release-Workflow vorgesehen ist
(.github/workflows/release.yml). Es enthält weder eine Lockdatei noch eine pnpm-workspace.yaml; seine einzige
Abhängigkeit, @phis/contracts, wird von npm in der in der package.json angegebenen Version bezogen. Es benötigt Node 24.21 oder
höher sowie pnpm 11. Erstellen Sie die vom Release-Workflow generierte Workspace-Datei – diese ermöglicht die nativen Build-Skripte und
befreit die @phis-Pakete von der Mindestveröffentlichungsdauer von pnpm – und installieren Sie anschließend den Server, erstellen Sie ihn und
bündeln Sie die CLI:
git clone https://github.com/phis-dev/phis-server.git && cd phis-server
printf 'allowBuilds:\n argon2: true\n esbuild: true\n sharp: true\n unrs-resolver: true\nminimumReleaseAgeExclude:\n - "@phis/*"\n' > pnpm-workspace.yaml
pnpm install --no-frozen-lockfile
pnpm build # next build
pnpm build:cli # dist/phis.mjs, which ./phis prefers
Führen Sie die Befehlszeilenschnittstelle mit dem Befehl
pnpm phis ... oder
./phis ... aus dem Verzeichnis
phis-server aus
(
CLI.md).
Aus dem Debian-Paket
Das Paket wird im apt-Repository unter apt.phisys.com für Debian 13 (trixie) und Ubuntu
24.04 (noble) auf den Architekturen amd64 und arm64 veröffentlicht. Jede neue Version wird zunächst im testing-Kanal bereitgestellt; der stable-Kanal erhält eine
Version, sobald diese hochgestuft wurde. Fügen Sie das Repository und dessen Signaturschlüssel hinzu und führen Sie anschließend die Installation durch:
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.phisys.com/repo-signing-key.asc \
| sudo gpg --dearmor -o /etc/apt/keyrings/phisys-archive-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/phisys-archive-keyring.gpg] https://apt.phisys.com/testing $(. /etc/os-release && echo "$VERSION_CODENAME") main" \
| sudo tee /etc/apt/sources.list.d/phisys.list
sudo apt update
sudo apt install phis
Jeder GitHub-Release sind dieselben Pakete beigefügt, und zwar im Format
phis_<version>-<revision>+<distribution>_<arch>.deb (beispielsweise phis_0.2.7-1+trixie_amd64.deb),
für einen Host, auf dem die Installation ohne Repository erfolgt (sudo apt install ./phis_<...>.deb). Debian 12
(bookworm) wird nicht unterstützt: Die dortige glibc-Version ist älter als die, auf deren Basis das Paket erstellt wurde.
Das Paket installiert den Server unter
/usr/lib/phis/server, die Befehlszeilenschnittstelle unter
/usr/bin/phis, legt den Benutzer
phis an und erstellt die Stufe
/srv/phis/stages/prod mit einer leeren Datei
config/phis-runtime.json, einem Verweis auf
die im Paket enthaltene Datei
phis-config.json (
/usr/share/phis/phis-config.json) sowie der Datei
.env, die die Einträge
PORT=5301,
HOSTNAME=127.0.0.1 und einen generierten
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY enthält. Der Dienst lautet
phis@prod.service. Die Serveradresse lautet dann
http://127.0.0.1:5301.
/usr/bin/phis arbeitet in
/srv/phis/stages/prod, sofern nicht
--root oder
PHIS_ROOT eine andere Stufe angibt (
CLI.md).
Das Paket legt die Dateien config/phis-runtime.json
und .env
mit den Berechtigungen 0600
an, deren Eigentümer phis:phis
ist, und setzt diese
bei jedem Upgrade erneut, da beide geheime Daten enthalten. Ein normaler Benutzer kann die CLI daher nicht auf der
„stage“-Umgebung ausführen: Führen Sie sie als Dienstkonto aus (sudo -u phis phis ...
) oder als Root. Ein Schreibvorgang als Root behält den
Eigentümer und die Gruppe der Datei bei, sodass der Server sie anschließend weiterhin lesen kann; die CLI legt die Datei mit dem Modus 0600
an, unabhängig davon, wer sie ausführt. Fahren Sie mit der folgenden Konfiguration fort.
Aus dem Paket-Tarball
@phis/server ist nicht auf npm verfügbar; das Debian-Paket stellt die offizielle Version dar (README, „Distribution“). Der Tarball
pnpm package:pack, der erstellt wird, enthält denselben eigenständigen Server, dieselbe Operator-CLI und dieselbe Schemadatei
wie das Debian-Paket, wobei die Laufzeitabhängigkeiten von npm aufgelöst werden, anstatt neben den Dateien kopiert zu werden.
Es wurde noch nicht auf einem echten Host installiert. Was es
nicht enthält, ist die Maschineneinrichtung: kein Dienstkonto, keine Stage, keine Service-Einheit, keine Proxy-Konfiguration und kein
generierter
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY – was für den Produktivbetrieb erforderlich ist und von jeder Instanz einer
Installation gemeinsam genutzt werden muss. Entnehmen Sie diese aus
dem Verzeichnis debian/, sofern die Installation sie benötigt.
npm install -g ./phis-server-<version>.tgz
phis --help # the bin wrapper names the application root the CLI reads
Der Server ist die eigenständige Datei server.js im Paketverzeichnis:
PHIS_ROOT=/srv/phis/stages/prod PORT=5301 HOSTNAME=127.0.0.1 \
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=... \
node "$(npm root -g)/@phis/server/server.js"
npm install gibt eine Warnung aus, dass das Installationsskript von „argon2“ nicht ausgeführt wurde. Dies ist jedoch nicht erforderlich: Beide nativen Pakete
enthalten vorgefertigte Binärdateien, und die Hash-Berechnung sowie die Bildverarbeitung funktionieren mit dem installierten Tarball in seiner aktuellen Form einwandfrei. Fahren Sie
mit der folgenden Konfiguration fort.
Die Phis-Wurzel
Das „phis“-Stammverzeichnis ist das Verzeichnis, aus dem der Server und die CLI den Ordner config/ lesen. Der Server bezieht diesen Wert aus
PHIS_ROOT; in der Produktionsumgebung wird standardmäßig auf /srv/phis/stages/prod zurückgegriffen. Erstellen Sie dieses Verzeichnis, dessen Eigentümer das
Dienstkonto ist:
install -d -o phis -g phis /srv/phis/stages/prod/config
Überprüfen Sie in der Datei phis-config.json mindestens Folgendes:
Legen Sie in der Datei phis-runtime.json die vom Server benötigten Werte fest. Generieren Sie jeden 64-Zeichen-Hexadezimalwert mit dem Befehl
openssl rand -hex 32:
{
"database": {
"uri": "postgresql://phis_prod_user:<serving password>@127.0.0.1:5432/phis_prod",
"migrationUri": "postgresql://phis_prod_migrator:<migration password>@127.0.0.1:5432/phis_prod"
},
"api": {
"internalToken": "<random token>"
},
"auth": {
"transactionEncryptionKey": "<64 hex>"
},
"registration": {
"intentEncryptionKey": "<64 hex>"
}
}
Die Beispieldatei ist in ihrer jetzigen Form gültig, enthält jedoch Platzhalter und lässt die beiden 64-stelligen Hexadezimal-Schlüssel
(auth.transactionEncryptionKey, registration.intentEncryptionKey) außer Acht, da ein Platzhalter an dieser Stelle
nicht gültig wäre; fügen Sie diese wie oben beschrieben hinzu.
Geben Sie anschließend den geheimen Speicherschlüssel ein und überprüfen Sie ihn:
phis secret init-key # writes secrets.encryptionKey; every instance needs the same file
phis config validate
api.internalToken is what Sites authenticate with. The /setup finish step generates one if it is
missing; phis init (step 6) copies it into the Site and refuses to run while it is unset.
operator.sessionSecret signs the operator session cookies and is written by the same finish step, or
by phis operator add; it is deliberately not the internal token, which every Site holds.
In der Produktionsumgebung benötigt der Server zudem die Umgebungsvariable
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
(Base64-Kodierung mit 32 Byte: `
head -c 32 /dev/urandom | base64`) und weigert sich, ohne diese zu starten. Instanzen
einer Installation teilen sich diesen Wert. Weitere Server-Umgebungsvariablen (
PORT,
HOSTNAME,
TRUST_PROXY,
PHIS_INSTANCE_ID) sind in
der Datei README.md beschrieben.
3. Erstellen Sie das Datenbankschema
phis schema apply
phis schema check
apply erstellt das
phis-Schema, dessen Tabellen sowie
pg_trgm als Serving-Rolle und erteilt der
Rolle „migration“ die Berechtigungen, die für Add-on-Migrationen erforderlich sind. Der Befehl ist idempotent und wird nach jedem Server-Upgrade
erneut ausgeführt (
CLI.md).
4. Starten Sie den Server und legen Sie den ersten Bediener an
Starten Sie den Server mit dem physischen Root-Verzeichnis und einer Loopback-Bindung:
# from source, in the phis-server checkout
PHIS_ROOT=/srv/phis/stages/prod NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=<key> \
pnpm exec next start -H 127.0.0.1 -p 5301
# Debian package
systemctl enable --now phis@prod.service
Der Server wurde mit der Option output: "standalone" erstellt, sodass next start eine Warnung ausgibt, dass er
mit dieser Einstellung nicht funktioniert, und die Verwendung der Datei „standaloneserver.js“ empfiehlt. Das Debian-Paket führt die Datei „standalone
server.js“ aus (siehe debian/rules für die Dateien, die es aus dem Verzeichnis .next/standalone übernimmt).
Bevor ein Serverprozess beendet wird, entzieht phis instance drain dessen Bereitschaftsstatus; die Debian-Unit führt
diesen Vorgang in ExecStop durch.
Legen Sie den ersten Plattformbetreiber an, das Konto der Betreiber-Benutzeroberfläche unter /operator:
phis operator add --email ops@example.com --password '<password>' --name 'Operations'
Der Server speichert die Konfiguration bis zu vier Stunden lang im Cache: Starten Sie ihn nach diesem Befehl neu, da sich der neue
Operator andernfalls noch nicht anmelden kann. Dasselbe gilt für jeden nachfolgenden CLI-Befehl, der die Datei
phis-runtime.json ändert (andere operator-Befehle, site add, site config set|add|del, secret
init-key
), sowie für die manuelle Bearbeitung der Datei.
Alternative: die Einstellungsseiten
Wenn bootstrap.enabled: true gesetzt ist, stellt der Server /setup bereit, einen geführten Ablauf: Laufzeitprüfungen, erster
Operator (nur solange noch keiner vorhanden ist), Übersetzungsmodus, Datenbankverbindung (schreibt database.uri),
Schema (dasselbe Skript wie bei phis schema apply), eine optionale erste Site und Abschluss, wobei api.internalToken geschrieben wird, falls es fehlt, und
bootstrap.enabled: false in phis-runtime.json gesetzt wird. Die Einrichtungsseiten erfordern keine Anmeldung; solange
bootstrap.enabled auf true gesetzt ist, darf der Server nur für den Operator erreichbar sein (Loopback-Bindung, SSH-
Tunnel). Sie schreiben weder database.migrationUri, secrets.encryptionKey,
auth.transactionEncryptionKey noch registration.intentEncryptionKey; legen Sie diese Werte wie in Schritt 2 fest. Eine dort
erstellte Site erhält weder sites.overrides.<key>.sourceLocale (ihre Quellsprache ist
translation.sourceLocale) noch einen Administrator; fahren Sie in Schritt 5 mit dem phis site admin fort.
5. Eine Website erstellen
phis site add --key acme --name 'ACME' --hostname www.acme.example \
--public-base-url https://www.acme.example \
--source-locale en --default-locale en --available-locales en,de \
--support-email support@acme.example
Dadurch wird die Zeile „Site“ eingefügt und der unveränderliche Eintrag
sites.overrides.acme.sourceLocale
in die Datei
phis-runtime.json
geschrieben; starten Sie den Server neu, damit er die Überschreibung übernimmt. Alle Sprachversionen müssen in
translation.supportedLocales
enthalten sein. Der Schlüssel muss dem Muster
[a-z0-9][a-z0-9._-]{0,63}
entsprechen (
CLI.md
).
Weisen Sie der Website ihren ersten Administrator zu, der sich auf der Website selbst anmeldet:
phis site admin --site acme --email admin@acme.example --password '<password>' \
--first-name Ada --last-name Admin
Without
--password the account gets an unknown random password; set one with
phis site user --site acme --email admin@acme.example --password '<password>' --overwrite
(
CLI.md).
phis site config runtime --key acme shows the Site's derived source path, instance path and port.
6. Errichten Sie ein Gerüst auf der Baustelle
phis init acme --path /opt/phis/sources/acme --api-base-url http://127.0.0.1:5301
Die Zeile „Site“ muss vorhanden sein, und das Ziel darf nicht vorhanden sein oder ein leeres Verzeichnis sein; andernfalls verwenden Sie bitte
phis reconcile.
api.internalToken must be set in the phis root (step 2); init refuses otherwise.
--path defaults to <sites.sourcePathRoot>/<site key>.
--api-base-url is required: the address the Site's server-side code uses to reach
@phis/server, as seen from the host the Site runs on. The Debian package serves on
http://127.0.0.1:5301. Only init writes it into config/site-runtime.json.
--package-manager defaults to npm for a new Site.
Was init ausgibt (Scaffold-Version 3):
config/site-runtime.json, .gitignore and the src/generated/ files belong to the Site after
init: reconcile leaves them as they are.
src/generated/ is ignored by git as well. The projection is what the operator installed, and its
source is the desired state in the phis root (config/phis-modules.json), not the Site's history: a
fresh clone gets the empty files from reconcile and the installed Modules from phis module sync. Every other file is canonical and is overwritten by
reconcile. Put Site-specific code in new files, not in canonical ones.
config/site-runtime.json is ignored by git, so a fresh clone of the Site has none: create it from
config/site-runtime.example.json on every host that builds or runs the Site. reconcile does not
create it.
Die kanonischen Dateien sind schlanke Wrapper: Routen, Proxy- und Area-Hosts greifen auf @phis/ui zu und enthalten keine
eigene CMS-, Medien-, Ländereinstellungs- oder Proxy-Logik. Eine Änderung an diesem gemeinsamen Verhalten wirkt sich auf eine Website aus, indem
@phis/uiaktualisiert und neu kompiliert wird. Das Scaffold enthält keine optionalen Feature-Pakete; Module werden
erst mit phis module add (Schritt 9) hinzugefügt, und reconcile sorgt für deren Beibehaltung.
Führen Sie einen Commit für das Repository durch.
7. Die Website installieren, erstellen und ausführen
phis update acme --path /opt/phis/sources/acme
update reconciles the scaffold, runs the Site's package manager (install, typecheck, build),
and copies the standalone build with .next/static and public/ into
/opt/phis/sources/acme/.phis/releases/<release id>/. The printed release id is the directory name.
Next nests the app inside .next/standalone when the Site is built inside a workspace; update finds
it there and writes a server.js at the top of the release that starts it, so every release starts
the same way. Equivalent by hand: npm install && npm run typecheck && npm run build in the Site
directory, without the release copy.
Die Version enthält keine Kopie von config/site-runtime.json und somit auch kein internes Token. Die Datei
config/site-runtime.json ist ein relativer Verweis auf /opt/phis/sources/acme/config/site-runtime.json,
die die Version beim Start einliest. Eine auf einen anderen Host kopierte Version benötigt anstelle dieses Verweises die eigene Datei
des jeweiligen Hosts.
@phis/ui and the other dependencies must be resolvable by the package manager, from a registry or a
workspace.
Führen Sie die Version über den Instanzpfad aus:
ln -sfn /opt/phis/sources/acme/.phis/releases/<release id> /var/www/phis/sites/acme
cd /var/www/phis/sites/acme
NODE_ENV=production HOSTNAME=127.0.0.1 PORT=52001 node server.js
Der Port lautet sites.basePort + site id (dieser Wert wird mit dem Befehl phis site config runtime --key acme ausgegeben).
Die Website liest die Datei config/site-runtime.json einmal pro Prozess über den Release-Link aus dem Verzeichnis
/opt/phis/sources/acme/config/ ein. Starten Sie die Website nach einer Änderung an der Datei neu; ein neuer Release ist
nicht erforderlich.
Gerenderte Seiten des öffentlichen Bereichs werden im Arbeitsspeicher des Prozesses gespeichert; standardmäßig stehen pro Prozess 128 MB zur Verfügung. Legen Sie
PHIS_RENDER_CACHE_MB fest, um diesen Wert zu ändern und den Arbeitsspeicher des Hosts für alle Site-Prozesse anzupassen (siehe
STATIC_RENDERING.md in @phis/ui). Instanzen nutzen den Cache nicht gemeinsam.
Der Befehl npm start (next start) im Quellverzeichnis dient ebenfalls dem Build, es wird jedoch darauf hingewiesen, dass er
mit der Scaffold-output: "standalone" nicht funktioniert; verwenden Sie in der Produktionsumgebung server.js.
Für die Entwicklung wird npm run dev im Verzeichnis „Site“ ausgeführt, wodurch next dev gestartet wird.
8. Webserver und Serviceeinheiten
phis site config prints snippets; it writes nothing (
CLI.md).
phis site config systemd --key acme > /etc/systemd/system/phis-site-acme.service
phis site config nginx --key acme > /etc/nginx/sites-available/acme.conf
Die systemd-Einheit führt /usr/bin/node server.js als phis im Instanzpfad mit den folgenden Einstellungen aus:
NODE_ENV=production, HOSTNAME=127.0.0.1, PORT=<port> und Restart=always. Die Zeile
#Environment=PHIS_RENDER_CACHE_MB=128 ist auskommentiert; entfernen Sie das Kommentarzeichen und passen Sie den Wert an, falls der Standardwert nicht
passend ist. Überprüfen Sie den Node-Pfad und gehen Sie anschließend wie folgt vor:
systemctl daemon-reload
systemctl enable --now phis-site-acme.service
Eine Site mit mehreren Instanzen (phis site config add
) erhält eine Unit pro Instanz:
phis site config systemd --key acme --instance <n>
, die in phis-site-acme-<n>.service
gespeichert wird und entsprechend der Reihenfolge nummeriert ist, in der
phis site config runtime --key acme
sie auflistet. Eine Site-Unit verfügt über keinen Drain-Schritt; phis instance drain
ist für Server-Instanzen vorgesehen.
Die Nginx-Datei gehört in den http-Kontext von Nginx; dort fügt Debian
sites-enabled/* einbindet. Sie enthält eine map, die Connection nur für Upgrade-Anfragen auf upgrade setzt, einen
upstream für jede Instanz der Site, keepalive 64 und keepalive_timeout 4s, sowie einen server-Block
auf Port 80 für den Hostnamen der Site mit client_max_body_size 2g, proxy_http_version 1.1,
Host $http_host und den Weiterleitungs-Headern. Halten Sie keepalive_timeout beim Bearbeiten unter dem Keep-Alive-Timeout von Node
von 5 s: Andernfalls verwendet nginx Verbindungen wieder, die Node geschlossen hat, und POST-Anfragen schlagen
mit dem Status 502 fehl (die README-Datei von phis-host, Abschnitt „Webserver vor mehreren Instanzen“, enthält die Details
sowie das Apache-Äquivalent). Fügen Sie TLS hinzu (einen listen 443 ssl-Block und Zertifikate), aktivieren Sie es und laden Sie
Nginx neu. Der Proxy der Website leitet /api/auth, /api/site, /api/addons und /api/hooks intern an den
Server weiter, sodass der Server selbst keinen öffentlichen Hostnamen für die Website benötigt.
Machen Sie die Operator-Benutzeroberfläche (/operator) nur für Operatoren zugänglich.
Die gleiche Keep-Alive-Regel gilt für einen Proxy, der vor mehreren Serverinstanzen geschaltet ist. Die Vorlagen, die das
Paket installiert (/usr/share/phis/templates/nginx/phis.conf und .../apache2/phis.conf, die von postinst nach
sites-available/phis.conf kopiert werden), enthalten diese Regel: einen upstream phis-Pool mit den Instanzen, die das
Paket ausführt – phis@prod.service unter 127.0.0.1:5301:5301 und eine auskommentierte Zeile für eine zweite Instanz –
keepalive 64, keepalive_timeout 4s, die Connection-Zuordnung und Host $http_host. Fügen Sie eine weitere
Instanz derselben Stufe als zusätzliche Zeile in diesen Pool ein. Eine weitere Stufe entspricht einer weiteren Installation mit
eigener Datenbank: Weisen Sie ihr einen eigenen upstream- und server-Block zu, niemals eine Zeile in diesem. Die Apache-
Vorlage ist ein balancer://phis mit ttl=4 pro Mitglied, was der gleichen Regel auf dieser Seite entspricht.
Ein Übersetzungsspiegel
Eine Installation, von der andere Installationen globale Übersetzungen abrufen – mit translation.cdnBaseUrl
auf ihrer Seite und cdn+deepl als Modus –, wird anders veröffentlicht als eine Website oder ein Operator-Host. Sie
erfordert die Angabe von api.publicToken und die Aktivierung von translation.allowPublicReads, und ihr Hostname bedient zwei Pfade
und nichts anderes:
server {
listen 443 ssl;
server_name cdn.example.test;
# certificates, HSTS
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
location = /api/v1/tr {
proxy_pass http://127.0.0.1:5301;
}
location = /api/v1/locales {
proxy_pass http://127.0.0.1:5301;
}
location / {
return 404;
}
}
Es handelt sich um exakte Übereinstimmungen, daher ist auch
/api/v1/tr/anything kein Zugang. Der
404-Fehler ist der Kern des Problems: Die
location /-Adresse, die in den oben genannten Vorlagen enthalten ist, würde die Betreiber-Benutzeroberfläche, die Einrichtungsseiten und jede interne
/api/v1-Route unter diesem Hostnamen ebenfalls veröffentlichen. Sie weisen Aufrufer ohne das interne Token zurück, sodass ein
ungefilterter Mirror eher eine öffentliche Schnittstelle als eine Sicherheitslücke darstellt; die Einrichtungsseiten verfügen jedoch über keine eigene Anmeldung. Ein Mirror
wird niemals über die Proxy-Routen einer Site veröffentlicht – diese setzen das interne Token, wodurch jeder
Aufrufer zu einem vertrauenswürdigen wird;
TRANSLATIONS.md, „Wie ein Mirror bereitgestellt wird“, enthält die
Begründung sowie die Vorgaben, die ein davor geschalteter Edge-Cache beachten müsste.
9. Module hinzufügen
Ein Site-Modul ist ein Paket, das im Site-Build enthalten ist.
phis module add --site acme --package @phis/marketplace --spec 0.1.0 --path /opt/phis/sources/acme
phis update acme --path /opt/phis/sources/acme
module add trägt das Modul in die Datei
config/phis-modules.json ein, fügt die Abhängigkeit hinzu, wenn
--spec
angegeben wird, und schreibt die Dateien unter
src/generated/site-modules*.ts neu – einschließlich
site-modules-fonts.ts, in der
die installierten Pakete aufgelistet sind, die
./fonts exportieren, sowie
site-module-packages.json, die von
next.config.ts
ausgelesen wird, damit Next jedes installierte Modulpaket kompiliert. Ein Paket, das vor der Installation hinzugefügt wurde, ist noch nicht
lesbar; führen Sie daher nach der Installation
phis module sync --site acme --path /opt/phis/sources/acme aus, um
die darin enthaltenen Schriftarten zu übernehmen.
update installiert und erstellt eine neue Version;
stellen Sie diese bereit (Schritt 7) und starten Sie den Site-Dienst neu. Aktivieren Sie anschließend das Modul für einen Bereich im Builder.
phis module check --site acme überprüft die installierten Pakete
(
CLI.md).
10. Add-ons hinzufügen
A server Add-on is one addon.mjs artifact, installed once per phis root and activated per Site.
phis addon install --artifact ./dist/addon.mjs
phis addon reconcile
phis addon migrate --addon @acme/status
phis addon enable --addon @acme/status
phis addon reconcile
Falls das Add-on über ein zugehöriges Modul verfügt (mit demselben Paketnamen), fügen Sie dieses zunächst zur Website hinzu (Schritt 9) und
aktivieren Sie anschließend das Add-on für die Website:
phis addon site --addon @acme/status --site acme --enable
phis addon config --addon @acme/status --site acme # list settings
phis addon config --addon @acme/status --site acme --name <setting> --value <value>
Die vom Add-on deklarierten Geheimnisse werden mit dem Befehl
phis secret set --addon @acme/status --site acme --name
<name>
(Wert über stdin) gespeichert. Rollen werden mit dem Befehl
phis addon role
(
CLI.md
) zugewiesen.
Core plant nichts ein. Ein Add-on, das Jobs deklariert (mit dem Befehl
phis addon list --json werden die einzelnen Manifeste angezeigt,
einschließlich der darin enthaltenen
jobs), führt diese nur aus, wenn
phis addon job aufgerufen wird; der Benachrichtigungs-Ausgang wird
nur von
phis mail drain erneut abgefragt, und die Bereinigungsaufgaben von Core werden mit
phis maintain ausgeführt. Auf einem systemd-Host
weisen Sie jedem einen One-Shot-Dienst und einen Timer zu:
SERVER_ADDONS.md enthält
ein Beispiel für einen Job, und dasselbe Paar von Einheiten mit einem anderen `
ExecStart=`-Eintrag bedient die beiden anderen.
11. Spätere Aktualisierung
Server
Installieren Sie die neue Server-Version – sudo apt update && sudo apt install phis aus dem Debian-Paket – oder
laden Sie den Checkout (Schritt 2) aus dem Quellcode herunter und kompilieren Sie ihn neu. Das Debian-Paket startet jede laufende
phis@<stage>-Instanz nach der Installation der neuen Version nacheinander selbst neu; bei der Installation aus dem Quellcode
müssen Sie den unten beschriebenen Neustart selbst durchführen. Anschließend:
phis schema apply
phis addon check
phis addon migrate
phis addon reconcile
Starten Sie die Serverinstanzen von der Quelle aus nacheinander neu (führen Sie zunächst phis instance drain aus). Überprüfen Sie anschließend
phis instance list und führen Sie für jede Site den Befehl phis site check --key acme aus.
Standort
phis update acme --path /opt/phis/sources/acme
update runs reconcile first, which:
schreibt die kanonischen Scaffold-Dateien in das aktuelle Scaffold um (die von der Website vorgenommenen Änderungen gehen dabei verloren);
Fügt der Datei package.json die Elemente hinzu, die das Scaffold benötigt und die in der Site fehlen, wobei alle Versionen, Skripte
und Felder, über die die Site bereits verfügt, beibehalten werden; lediglich engines.node wird auf >=24.21.0 gesetzt. Um auf eine neuere Version von
@phis/ui oder Next umzusteigen, erhöhen Sie die Version in der Site (npm install @phis/ui@<version>) und führen Sie anschließend update aus;
behält die zur Website gehörenden Dateien (PHI_SITE_OWNED_AFTER_INIT: config/site-runtime.json, .gitignore,
src/generated/site-modules*.ts) unverändert bei;
entfernt Dateien, die von einem früheren Scaffold erstellt wurden und vom aktuellen nicht mehr erstellt werden, sofern deren Inhalt
unverändert ist, und meldet bearbeitete Dateien als kept (beibehalten), die Sie manuell verschieben oder löschen;
verwendet den eigenen Paketmanager der Website und löscht keine Sperrdatei, es sei denn, mit --package-manager wird ein
anderer angegeben.
Bei einem Repository, das zuvor unter .phis/releases/ erstellt wurde und Teil der generierten .gitignore-Datei ist, muss diese Zeile
manuell hinzugefügt werden; reconcile schreibt die .gitignore-Datei nicht neu.
Überprüfen Sie die Änderungen (mit dem Befehl phis reconcile acme --json
werden alle Dateien mit der jeweiligen Aktion aufgelistet, und mit git diff
werden diese angezeigt), stellen Sie anschließend die neue Version bereit (Schritt 7) und starten Sie den Site-Dienst neu. Um die
Serveradresse oder das Token einer bestehenden Site zu ändern, bearbeiten Sie die Datei config/site-runtime.json
selbst; reconcile
schreibt diese nicht neu.
