Workspace

Was der Workspace ist

Der Workspace ist der Dateimanager des Panels für Website-Dateien. Jede Anfrage ist ein asynchroner Job (/api/next/v1/web/sites/{nws_…}/workspace/…, /api/next/v1/jobs/…). Der Job läuft auf dem Web-Node der Website und wird strikt unter der eigenen UID/GID dieser Website ausgeführt.

Panel/Application ──SQL──▶ next_job ◀──SQL── nova-workspace-gateway (Control-Host, Fleet-Adresse:Port)
                                                   ▲ mTLS 1.3, Ed25519, gepinnte Workspace-CA
                                                   │
Web-Node: nova-workspace-node (unprivilegiert) ──Unix-Socket──▶ nova-workspace-broker (root)
          └─ libncp-workspace-v2.so, als Website-UID, unterhalb des Roots aus workspace-roots.json

Umfang in Version 1.0: Auflisten, Herunterladen und Vorschau (Text, Bild, PDF), Abbrechen von Jobs und – optional, siehe unten – Datei-Upload.

Voraussetzungen

• Installationsprofil v26. Das Gateway bindet an fleet_network.listen_address: 127.0.0.1 auf einem Einzelhost, die private Fleet-Adresse, wenn Web-Nodes auf anderen Hosts laufen. Die Fleet-Exposure-Prüfung verweigert die Installation, wenn der Gateway-Port woanders lauscht.
• Release mit nativem Plattform-Bundle (combined schema 2). Produktionshosts kompilieren nichts. Das Bundle ist an Plattform, Commit und den Digest der nativen Quellen in der FILES.sha256 der Application gebunden; jedes andere Bundle wird abgelehnt.
• PHP auf Web-Hosts mit FFI, pcntl, posix, sodium, openssl und pdo_sqlite. Diese Module gehören zu den PHP-Paketen der Distribution, die die Web-Rolle installiert.
• Bildvorschau rendert die Application auf dem Control-Host mit php-gd (Rolle control und kombiniertes Paket-Bundle). Auf einem vorbereiteten Host (expect-provisioned) brauchst du auf dem Control-Host apt-get install php8.x-gd. Separate Web-Nodes brauchen es nicht.
• Die Node-Zeile des Web-Hosts (next_node) muss existieren, siehe unten.

PDF-Vorschau im Browser

Das Panel liest eine PDF-Datei über den Download-Pfad (GET …/workspace/files/{filename}/content, mit derselben Mandantenprüfung, denselben Lese-Jobs und dem Audit-Event workspace.filesystem.download wie ein Download) und zeichnet sie Seite für Seite mit dem mitgelieferten Mozilla pdf.js 6.3.289 (Apache-2.0) in ein Canvas.

• pdf.js wird erst geladen, wenn eine PDF-Vorschau geöffnet wird, und läuft in einem Modul-Worker vom Panel-Origin.
• PDF-JavaScript, XFA-Formulare, Links, Text- und Anmerkungsebenen sind abgeschaltet; nichts wird von fremden Quellen geladen.
• Dateien über 8 MB, Nicht-PDF-Dateien, passwortgeschützte PDFs und Browser, die pdf.js nicht laden können, erhalten einen Hinweis „nur Download“.
• Nicht eingebettete Schriften werden mit einer Systemschrift gezeichnet; JPEG-2000-Bilder und vordefinierte CJK-CMaps werden nicht mitgeliefert und können in der Vorschau fehlen.
• Der Server rendert keine PDFs mehr: GET …/preview?representation=pdf antwortet mit 422 WORKSPACE_PREVIEW_REQUEST_INVALID.

Ghostscript entfernen

Ghostscript ist nicht mehr Teil von Nova. Keine Host-Rolle und kein Paket-Bundle enthält ghostscript oder seine Abhängigkeiten (libgs*, fonts-urw-base35, poppler-data, libjbig2dec0). Ein Host, den eine frühere Version damit eingerichtet hat, behält das Paket: Kein upgrade, accept oder rollback entfernt es, und die Paketquittung führt es weiter unter installed_by_nova. Nachdem das Upgrade akzeptiert ist, kannst du es auf dem Control-Host entfernen, wenn nichts anderes es braucht:

apt-get -s autoremove          # geplante Entfernungen zuerst prüfen
apt-get purge ghostscript && apt-get autoremove --purge

Node-Zeile anlegen

Lege die Node-Zeile ohne Capability-CSV an. <runtime> ist /etc/nova-controlpanel/application-runtime.json:

php /opt/nova-controlpanel/application/current/src/api/bin/nova-node-bootstrap.php bootstrap <runtime> <node_id> <server_ref> <legacy_id>

• node_id = node_ plus 8–59 Zeichen, server_ref = srv_ plus 8–59 Zeichen aus A–Z a–z 0–9 _ - (dieselbe Regel wie für die Node-Zertifikatsidentität). Ein anderer server_ref wird mit NOVA_NODE_BOOTSTRAP_SERVER_REF_INVALID abgelehnt, eine andere node_id mit NOVA_NODE_BOOTSTRAP_ARGUMENTS_INVALID; node-issue erzwingt dieselbe Regel.
• Eine Zeile aus einer älteren Version kann einen kürzeren oder fremden server_ref tragen; node-issue scheitert dann mit NOVA_WORKSPACE_NODE_SERVER_REF_INVALID. Repariere sie einmalig vor der Registrierung:

php …/nova-node-bootstrap.php repair-server-ref <runtime> <node_id> <current_server_ref> <new_server_ref>

Die Reparatur wird auditiert (node.server-ref.repair). Sie wird verweigert, sobald irgendetwas den alten Wert bereits übernommen hat – Workspace-Zugangsdaten, Steuerbefehle, Workspace-Authority-Zustand, Upload oder Job (NOVA_NODE_SERVER_REF_IN_USE). Ein server_ref, der die Regel erfüllt, ist Identität und kann nicht geändert werden (NOVA_NODE_SERVER_REF_ALREADY_VALID).

Workspace-CA anlegen

Einmalig, auf dem Control-Host, als root:

php /opt/nova-controlpanel/application/current/src/api/application/bin/nova-workspace-fabric.php \
    authority-init /root/nova-workspace-pki

Vor der ersten Installation gibt es noch kein installiertes Release; dann führst du dieselbe Datei aus dem vertrauenswürdigen Quellbaum des Releases aus (php <checkout>/src/api/application/bin/nova-workspace-fabric.php authority-init ...). authority-init braucht keine Datenbank.

Der Befehl legt ein neues Verzeichnis mit Modus 0700 an:

• workspace-ca.pem und workspace-ca.key (Ed25519, 10 Jahre)
• gateway.crt und gateway.key (SAN gateway.workspace.nova.invalid, höchstens 825 Tage)
• gateway-root-key

Er gibt die vier Werte workspace_gateway.*_source_file für das Installationsprofil aus. Das Verzeichnis darf nicht unterhalb von /etc/nova-controlpanel liegen und darf noch nicht existieren; der Befehl überschreibt nie eine PKI.

Bestehende Installation. Jede Installation mit Profil v3 oder neuer hat bereits installierte Gateway-Eingaben, auch mit workspace_gateway.enabled=false. Der Installer behält dann den installierten Root-Key (/etc/nova-controlpanel/workspace-gateway/root-key); eine root_key_source_file mit anderem Inhalt wird mit Gateway root key rotation requires a separate migration abgelehnt.

• Übernimm von den Werten, die authority-init ausgibt, nur certificate_source_file, private_key_source_file und node_ca_source_file.
• Lass root_key_source_file auf eine root-eigene Kopie des installierten Root-Keys zeigen (oder auf die Datei aus dem bisherigen Profil), nicht auf den neuen gateway-root-key.
• Zertifikat, privater Schlüssel und Node-CA werden beim nächsten reconfigure/accept ausgetauscht.
• Führe node-issue erst aus, wenn diese Rekonfiguration akzeptiert ist: Es vergleicht die CA der PKI mit der installierten credentials/node-ca.crt (sonst NOVA_WORKSPACE_GATEWAY_TRUST_MISMATCH).
• Eine neue CA macht jeden unter der alten CA registrierten Node ungültig. Registriere diese Nodes neu mit node-issue … --rotate.

Wichtig: workspace-ca.key ist der einzige private CA-Schlüssel. Kein Installer kopiert ihn, und die Gateway- und Node-Installer lehnen eine *ca*.key unterhalb ihrer Konfigurationsverzeichnisse ab. Bewahre das Verzeichnis auf Wechsel- oder Vault-Speicher auf und binde es nur für authority-init und node-issue ein. Das Gateway-Zertifikat musst du vor seinem Ablauf neu ausstellen.

Auf einem kombinierten Host aktivieren

Gemeint ist die Control Plane mit der Rolle web.

1. Neuinstallation mit workspace_gateway.enabled=false und native_workspace.enabled=false sowie den Eingaben aus dem vorigen Abschnitt; dann kombiniertes install und accept. Die Workspace-Node-Stufe installiert Broker, Root-Mapping-Units und Bibliothek; die Node-Unit bleibt bis zur Registrierung deaktiviert. /etc/nova-controlpanel/workspace-node/workspace-roots.json wird aus /var/lib/nova-controlpanel-agent/web-state/storage.json veröffentlicht; eine Path-Unit aktualisiert sie bei jeder Änderung, ein 5-Minuten-Timer gleicht ab.
2. Rekonfiguration mit neuer Profildatei: workspace_gateway.enabled=true und native_workspace.enabled=true, dann kombiniertes reconfigure und accept.
3. Den Node des Hosts registrieren (alle Befehle als root, siehe unten).
4. Abbrechen von Jobs aktivieren: Rekonfiguration mit native_workspace.job_cancellation_enabled=true, dann accept.

Registrierung, mit FABRIC = /opt/nova-controlpanel/application/current/src/api/application/bin/nova-workspace-fabric.php:

php $FABRIC node-request <node_id> /root/workspace-request.json   # Schlüssel wird einmalig erzeugt, 0640 root:nova-workspace-node
php $FABRIC node-issue /root/nova-workspace-pki /root/workspace-request.json /root/workspace-bundle.json
php $FABRIC node-install /root/workspace-bundle.json            # aktiviert den Node, wartet auf die Authentifizierung
php $FABRIC node-status <node_id>                                 # workspace_policy/workspace_negotiated: true

• node-issue erfasst die Zugangsdaten und setzt die Capability-Policy des Nodes in einer auditierten Transaktion auf den Workspace-Lesesatz. Es lehnt einen Node ab, dessen Policy zu etwas anderem gehört, und ohne --rotate auch zweite Zugangsdaten.
• node-install stellt die vorherigen Dateien und den Dienstzustand wieder her, wenn sich der Node nicht innerhalb von 45 Sekunden authentifiziert.

Einen separaten Web-Node aktivieren

Auf dem Web-Node:

1. Host vorbereiten: nova-host-bootstrap.py --roles web …, den Node Agent mit seiner Fabric-Registrierung (siehe Installation) und das kombinierte Release-Paket auf dem Node bereitstellen (STAGE).
2. Workspace-Node installieren (siehe unten). Installiert wird nur der Application-Code (kein Apache, keine Datenbank); das vorherige Release bleibt als Last-known-good erhalten, dazu kommen Broker, Root-Mapping-Units und Bibliothek. Auf einem Host mit /etc/nova-controlpanel/application-runtime.json verweigert der Installer die Arbeit.
3. Node registrieren: node-request auf dem Web-Node; die Anfragedatei (nur öffentlicher Schlüssel) auf den Control-Host kopieren und dort node-issue ausführen; die Bundle-Datei zurückkopieren (kein privates Material) und auf dem Web-Node node-install ausführen. Das Bundle enthält die Fleet-Adresse des Gateways; node-install schreibt nova-workspace-node.service.d/gateway-address.conf mit genau IPAddressAllow=<gateway address>/32. Alle anderen Adressen bleiben gesperrt.
4. Firewall: Erlaube TCP zum Gateway-Port nur von der Fleet-Adresse des Web-Nodes aus, im Fleet-Netz.

sh STAGE/application/src/installer/application/install-nova-workspace-node.sh install STAGE/application / STAGE/payload/native.tar.gz
sh STAGE/application/src/installer/application/install-nova-workspace-node.sh accept  STAGE/application /

Uploads freischalten

Uploads laufen vom Browser zur Application (in Stücken, in einen begrenzten Spool auf dem Control-Host), weiter zum Gateway, in die Node-Sitzung und zum Broker. Der Broker schreibt die Datei auf dem Web-Node als Website-UID. Der Web-Node braucht keinen eingehenden Port über die bestehende Node-Sitzung hinaus.

1. Zuerst die Web-Nodes aktualisieren. Jeder Web-Node, der Uploads annehmen soll, braucht ein Release mit Upload-Unterstützung (update auf einem kombinierten Host, install-nova-workspace-node.sh install … accept auf einem separaten Node). Der aktualisierte Node bietet den Upload-Satz an; das Gateway gewährt aber nur den Lesesatz, solange die Node-Policy read ist.
2. Routen auf dem Control-Host aktivieren: Rekonfiguration mit Installationsprofil v27 (Runtime v26), dann accept (Beispiel unten).
3. Uploads pro Node erlauben (Control-Host, root, siehe unten).

"native_workspace_upload": {
  "enabled": true,
  "max_file_bytes": 1073741824,
  "spool_capacity_bytes": 4294967296
}

• Voraussetzungen: native_workspace.enabled=true, ein aktiviertes Gateway und ein akzeptierter Vorgänger, in dem der Workspace-Leser bereits aktiv war. Aktiviere also zuerst den Leser und akzeptiere, dann die Uploads in einer zweiten Rekonfiguration.
• Der Installer legt den Spool /var/lib/nova-controlpanel/workspace-upload an (nova-controlpanel:nova-workspace-gateway, Modus 2750) und aktiviert nova-workspace-upload-spool-sweeper.timer (alle 10 Minuten).
• Migration 125 ergänzt next_workspace_upload und next_workspace_upload_capacity; sie ist rein additiv.

php $FABRIC node-capabilities <node_id> upload    # auditiert: workspace.node-capabilities.set
php $FABRIC node-status <node_id>                 # upload_policy: true, dann upload_negotiated: true

Eine Policy-Änderung schließt die Sitzung des Nodes; er verbindet sich innerhalb von Sekunden neu und handelt den neuen Satz aus. node-capabilities <node_id> read nimmt die Uploads wieder zurück. Panel und API bieten Uploads nur für Websites an, deren Node upload_negotiated: true meldet. Die Schaltfläche „Dateien hochladen“ erscheint nur, wenn GET …/workspace/uploads für den angemeldeten Benutzer available: true liefert.

Wer hochladen darf: genau die Principals, die die Website ändern dürfen (sites.update) – der Kunde für seine eigenen Websites, ein Reseller für die Websites seiner Kunden, ein Administrator für alle. Die Website-Bindung muss aktiv und write_enabled sein. Das Gateway prüft das vor jedem Node-Befehl erneut.

Prüfen

Control-Host:

• install-nova-application-runtime.sh verify … prüft Gateway, Sweeper, Node-Stufe, Bibliotheks-Digests und Units.
• systemctl status nova-workspace-gateway nova-workspace-job-sweeper.timer
• php $FABRIC node-status <node_id>

Web-Node:

• install-nova-workspace-node.sh verify STAGE/application / (separater Node)
• systemctl status nova-workspace-broker nova-workspace-node nova-workspace-node-roots.path
• /var/lib/nova-controlpanel/workspace-node/authenticated.json nennt die laufende PID und die Zugangsdaten.

Regeln für skriptgesteuerte Prüfungen

Das Panel erledigt all das selbst; die Regeln brauchst du nur für eigene Prüfungen, etwa mit curl.

• Die Sitzung ist das Browser-Cookie NOVA_SESSID einer nativen Anmeldung.
• Jedes POST/PUT braucht Origin: <trusted origin> (genau das trusted_origin der Installation, zum Beispiel https://panel.example:8443) und Sec-Fetch-Site: same-origin; sonst 403 WORKSPACE_UPLOAD_ORIGIN_DENIED (Uploads) oder 422 (Job-Abbruch).
• Content-Type wird exakt verglichen: application/json (ohne ; charset=…) für JSON, application/octet-stream für Upload-Stücke.
• CSRF-Tokens kommen von POST /api/next/v1/native-identity/csrf-tokens mit {"count":1,"scope":"<scope>"} (gleiche Regeln für Origin, Sec-Fetch-Site und Content-Type). Ein Token hat 40 Hex-Zeichen und gilt 5 Minuten für genau eine Anfrage. Den Scope workspace gibt es nur, solange native_workspace_upload.enabled=true gilt.
• Idempotency-Key: 8–200 Zeichen aus A–Z a–z 0–9 . _ : -. Ein Schlüssel ist an seinen Body gebunden; mit anderem Body wird er abgelehnt (JOB_IDEMPOTENCY_CONFLICT, WORKSPACE_UPLOAD_IDEMPOTENCY_CONFLICT).
• JSON-Bodies sind geschlossene Objekte. Die Bodies für Upload-Anlage und Commit müssen genau die dokumentierten Schlüssel in der dokumentierten Reihenfolge enthalten, sonst 422 VALIDATION_REQUEST_INVALID. Lesezugriffe haben keinen Body, Upload-Routen keinen Query-String.

Funktionsprüfung (als Kundensitzung)

1. GET /api/next/v1/web/sites/<nws>/workspace/entries → 202 mit einem Job.
2. GET /api/next/v1/jobs/<job>/result → die Einträge.
3. Download: GET …/workspace/files/<name>/content?relative_path=<folder> → 202 mit einem Job; nach Erfolg mit &job_id=<job> wiederholen (Range wird unterstützt). <name> ist ein einzelner Dateiname, der Ordner gehört in relative_path ("" oder weggelassen für das Website-Root). Vorschau: …/files/<name>/preview?relative_path=<folder>&representation=text|image|pdf, dieselben zwei Schritte.
4. POST /api/next/v1/jobs/<job>/cancel mit X-Nova-CSRF-Token (Scope jobs), Idempotency-Key, Content-Type: application/json und dem Body {"expected_revision":<Revision des Jobs als Ganzzahl>} → 202. Voraussetzung: native_workspace.job_cancellation_enabled=true und sites.update. Der Job endet mit cancelled, auch wenn sein Node offline ist.

Upload-Prüfung (als Kundensitzung)

Jedes POST trägt ein frisches X-Nova-CSRF-Token mit Scope workspace und einen neuen Idempotency-Key.

1. GET …/workspace/uploads → 200 mit upload_availability.available: true (false für einen Benutzer ohne sites.update).
2. POST …/workspace/uploads mit {"name":"a.txt","parent_path":"","size_bytes":N} (genau diese drei Schlüssel in dieser Reihenfolge) → 201 mit upload.upload_id (upl_…), upload.upload_token und upload.chunk_bytes (1 MiB).
3. PUT …/workspace/uploads/<upl>/chunks/<offset> mit höchstens chunk_bytes Bytes, Content-Type: application/octet-stream, X-Nova-Upload-Token: <upload_token> und X-Nova-Chunk-SHA256: <hex dieses Stücks> → 204 mit Upload-Offset. Das Pfadsegment ist der Byte-Offset (0, 1048576, …), keine Stücknummer; ein falscher Offset liefert 409 WORKSPACE_UPLOAD_OFFSET_CONFLICT mit dem Upload-Offset, an dem es weitergeht. Stücke brauchen kein CSRF-Token.
4. POST …/workspace/uploads/<upl>/commit mit {"expected_revision":null,"sha256":"<hex der ganzen Datei>"} (beide Schlüssel, diese Reihenfolge) → 202 mit Upload und Job (Location: /api/next/v1/jobs/<job>). GET …/workspace/uploads/<upl> endet mit committed und revision: "frv_…". Die Datei erscheint in …/workspace/entries, gehört der Website-UID und hat Modus 0644.
5. Derselbe Name noch einmal: Der Commit-Job scheitert mit WORKSPACE_UPLOAD_CONFLICT, GET …/uploads/<upl> zeigt state: "conflict" mit conflict.revision. Um genau diese Datei zu ersetzen, committest du erneut mit {"expected_revision":"<conflict.revision>","sha256":"<hex>"} und neuem Idempotency-Key. POST …/uploads/<upl>/cancel (Body leer oder {}, Content-Type: application/json) behält die vorhandene Datei.
6. Der Job steht unter /jobs; das Audit-Log enthält workspace.upload.create, .commit und .cancel.

Deaktivieren

Hinweis: Eine Runtime mit aktivierten Uploads lässt sich nicht durch eine Runtime unter v26 ersetzen. Schalte die Uploads zuerst ab und akzeptiere.

Rotation und Wiederherstellung

• Gateway-Zertifikat erneuern: php $FABRIC gateway-issue /root/nova-workspace-pki /root/nova-workspace-gateway-<date>. Setze workspace_gateway.certificate_source_file und workspace_gateway.private_key_source_file auf die neuen Dateien, dann reconfigure und accept. Nodes vertrauen weiterhin derselben CA.
• Node-Zertifikat rotieren: node-request, dann node-issue … --rotate, dann node-install. Die alten Zugangsdaten bleiben eine Stunde lang retiring. Eine niedrigere Revision wird nie installiert.
• Node-Schlüssel ersetzen: node-revoke, dann /etc/nova-controlpanel/workspace-node/node.key entfernen und mit --rotate neu registrieren.
• Zurückrollen: Der Application-Installer und install-nova-workspace-node.sh rollback stellen Bibliothek, Units, Links, Quittung und Root-Key exakt wieder her. Registrierungsdateien (transport.json, node.crt, node.key, gateway-ca.pem, das Drop-in) sind Node-Zustand und werden von keinem Installer entfernt. Der Node-Root-Key wird einmal erzeugt und nie rotiert.

Fehlersuche

Grenzen in Version 1.0

• Upload-Durchsatz. Das Gateway leitet 32 KiB pro Node-Befehl weiter, mit je einem Roundtrip. Rechne je nach Latenz mit einigen MB/s pro Node-Sitzung. Uploads zu einem Node teilen sich dessen Sitzung mit Lesezugriffen.
• Commit großer Dateien. Der Broker arbeitet single-threaded. Während er eine große Datei für den Commit hasht, warten andere Workspace-Befehle an diesen Node.
• Stage-Verzeichnis. Jedes Website-Root hat ein Verzeichnis .nova-upload (0700, Website-UID). Der Node blendet es in Listen aus und verweigert Lesezugriffe darunter; über SFTP/FTP ist es sichtbar. Entferne es nicht, solange Uploads laufen.
• Fortsetzen nach Neuladen. Ein neu geladenes Panel setzt einen unterbrochenen Upload nicht selbst fort. Über die API geht das (GET auf den Upload, bei received_bytes weitermachen); andernfalls läuft der Upload nach 6 Stunden Inaktivität ab.
• Panel. Uploads startest du im Dateibrowser der Website (#/websites/<nws>/files, Schaltfläche „Dateien hochladen“). Upload-Jobs erscheinen unter „Dateiaufträge“.