Node-Rollen und Installation

Diese Rollenanforderungen gelten sowohl für Nodes, die auf Ihren eigenen Servern registriert werden, als auch für über Opfield erstellte VMs.

Die bei der Registrierung gewählte Rolle entscheidet, welche Ressourcen der Host steuern darf, welches Softwareprofil installiert wird und was ein Ausfall des Hosts betrifft. Wählen Sie nach Zuständigkeit, nicht nach den Paketen, die bereits auf der Maschine vorhanden sind.

Klären Sie vor der Registrierung Rolle, Eigentümer des Hosts, Fehlerdomäne, Sensibilität der Daten und wer den Host wiederherstellt. Die Registrierung ist abgeschlossen, wenn eine dauerhafte Node-Identität auf dem vorgesehenen Host installiert ist, nur die erwarteten Fähigkeiten meldet und eine rollenspezifische Abnahmeprüfung mit geringem Risiko besteht, bevor Produktionsressourcen zugewiesen werden.

Details für Betreiber: Voraussetzungen der Profile

Verwenden Sie den generierten Installationsbefehl aus dem Ablauf zum Erstellen eines Nodes. Er enthält begrenztes Registrierungsmaterial und die festgelegte Opfield-Identität.

nginx: erfordert nginx, gegebenenfalls öffentliche Ingress-Ports, Validierung der Konfiguration und Zugriff auf Logs.
Docker: erfordert eine unterstützte Docker Engine und Berechtigungen für die konfigurierten Laufzeitoperationen. Das Installationsprogramm installiert außerdem den Lease-Watchdog opfield-lease-watchdog, einen separaten Dienst, den das Failover der Datenebene auf Nodes benötigt, die Availability-Leases halten. Auf einem Node, der installiert wurde, bevor es den Watchdog gab, installiert ein Docker-Daemon, der als Root mit systemd oder OpenRC läuft, ihn selbst; bei einem Daemon, der mit --user <non-root user> installiert wurde, führen Sie das Docker-Node-Installationsprogramm erneut mit sudo und demselben --user aus, da ein nicht interaktiver Lauf den Daemon-Dienst sonst auf Root umstellt. Jedes verwaltete Disk-Image-Volume belegt ein Loop-Device, und der Daemon installiert einen Boot-Schritt, opfield-volume-images, der diese Volumes mountet, bevor Docker startet.
storage: führt den Docker-Daemon als Root aus und erfordert dedizierten Speicher, Loop-Devices und Mount-Unterstützung; das Installationsprogramm formatiert, mountet, vergrößert und trennt vor der Registrierung ein Test-Image und bricht ab, wenn der Host das nicht kann. Jede verwaltete Datenbank, jedes Mitglied eines Objektspeichers und jedes laufende Backup belegt ein Loop-Device, daher benötigt ein LXC-Gast einen Host, der /dev/loop-control und einen für all diese dimensionierten Pool von Loop-Devices durchreicht. Der Node benötigt ausgehendes HTTPS zu ghcr.io für den Backup-Runner. Das Installationsprogramm installiert außerdem den Lease-Watchdog opfield-lease-watchdog, den Datenbanken und Speicher auf mehreren Servern verwenden. Der frühere Modus databases wird als Alias akzeptiert. Siehe Voraussetzungen für Storage Nodes und Docker Nodes.
builder: erfordert systemd und dedizierte BuildKit/containerd-Kapazität und sollte keinen Docker-Engine-Socket haben. Auf einem Host ohne systemd bricht das Installationsprogramm ab, bevor es etwas installiert oder herunterlädt.
monitoring: stellt die unterstützte Monitoring-Erfassung bereit.
Relay supervisor/worker: erweitert Kapazität und Ausfallsicherheit von Relay mit ausdrücklicher Platzierung.

Prüfen Sie nach der Installation die Fähigkeitsmeldungen, statt anzunehmen, dass Host-Pakete Unterstützung bedeuten. GPU-, Secure-Runtime-, Builder-, Speicher- und Migrationsfunktionen hängen von gemeldeten fehlerfreien Fähigkeiten ab.

Die Rolle wählen

Ingress: terminiert TLS und liefert öffentliche Domains und Routen aus. Er benötigt Validierung der nginx-Konfiguration, Zertifikatsspeicher, Logs und gegebenenfalls öffentliche Ports.
Docker: verwaltet gewöhnliche Anwendungs-Workloads und Docker-Ressourcen. Er benötigt eine unterstützte Docker Engine und die Rechte, die für die gewählten Laufzeitfunktionen erforderlich sind.
Build Worker: führt Git-Builds auf isolierten BuildKit/containerd-Diensten aus. Er muss ausschließlich für Builds verwendet werden und darf dem Builder-Profil keinen gewöhnlichen Docker-Engine-Socket offenlegen.
Storage: betreibt verwaltetes PostgreSQL, Key-Value-Stores und ClickHouse, verwalteten SeaweedFS-Objektspeicher und Datenbank-Backup-Jobs mit dedizierter Speichervorbereitung und einem eingeschränkten Docker-Daemon-Profil. Allgemeine Anwendungscontainer und Builds werden abgelehnt. Nodes, die mit der früheren Rolle Databases registriert wurden, behalten ihre Identität, Registrierung, Konfiguration und Daten; ein Update ihres Daemons aktiviert die Storage-Fähigkeiten ohne erneute Registrierung oder Verlagerung von Daten.
Monitoring: erfasst den unterstützten Zustand und die Metriken des Hosts, ohne Berechtigungen für den Lebenszyklus von Workloads zu erhalten.
Relay: installiert den Relay-Supervisor, kündigt eine erreichbare Adresse an und tritt dem Secure-Link-Relay-Pool bei.

Standardablauf der Registrierung

Öffnen Sie Nodes, wählen Sie Add Node und dann External VM.
Wählen Sie den vorgesehenen Node Type und lesen Sie seine Beschreibung.
Geben Sie einen stabilen, für Operatoren verständlichen Namen ein.
Geben Sie bei Relay die Adresse ein, die beteiligte Nodes über TCP 9443 erreichen können.
Erstellen Sie den ausstehenden Node.
Kopieren Sie den generierten einmaligen Installationsbefehl. Er gehört zu der Opfield-Installation, die ihn anzeigt: Er lädt das Installationsprogramm aus dem Release dieser Installation herunter, führt es erst aus, wenn seine Prüfsumme zum Release passt, und legt den neuesten Daemon derselben Release-Linie fest.
Führen Sie den Befehl auf dem vorgesehenen Linux-Host aus.
Lassen Sie den Ergebnisdialog geöffnet, während der Daemon installiert und registriert wird; er schließt sich automatisch, wenn genau dieser Node online geht.
Öffnen Sie die Node-Details und prüfen Sie Rolle, Hostname, Version, Fähigkeiten, Metriken und Dienstadressen.

Die Aktion Add relay node in den Relay-Einstellungen öffnet denselben Registrierungsablauf mit vorausgewähltem und gesperrtem Relay. Relay-Mitglieder erscheinen erst als bereite Pool-Kapazität, wenn Registrierung und Zustandsmeldung erfolgreich sind.

Vorbereitung des Hosts

Verwenden Sie einen dedizierten Host oder eine dedizierte VM, wann immer die Rolle eine starke Vertrauensgrenze besitzt. Bestätigen Sie vor dem Ausführen des Installationsprogramms DNS, Systemzeit, ausgehende Erreichbarkeit von Relay, Voraussetzungen an Pakete und Laufzeit, persistenten Speicher sowie systemd oder OpenRC. Kopieren Sie keinen Installationsbefehl zwischen ausstehenden Node-Einträgen.

Storage Nodes erfordern die Speicher-Vorabprüfung des Installationsprogramms. Build Worker erfordern dedizierte Ausführungs- und Speicherkapazität. Relay-Nodes erfordern eine erreichbare angekündigte Adresse und sollten in unterschiedlichen Fehlerdomänen platziert werden, wenn der Pool Ausfallsicherheit bieten soll.

Was das Installationsprogramm prüft

Verbindung. Ein Lauf des Installationsprogramms und jeder erneute Lauf auf einem registrierten Node ist nur erfolgreich, wenn der gestartete Daemon unter systemd oder OpenRC läuft und Opfield seine Sitzung angenommen hat. Andernfalls endet er mit einem Fehler, nennt das Daemon-Log und gibt dessen letzte Zeilen aus; er wartet bis zu 90 Sekunden auf die Sitzung. Ein Token, das bereits verwendet wurde oder abgelaufen ist, wird als von Opfield abgelehnt gemeldet. Hosts ohne systemd oder OpenRC erhalten einen abgekoppelten Starter, der einen Neustart nicht übersteht.
Erneuter Lauf des Einrichtungsbefehls. Das erneute Ausführen des eigenen Einrichtungsbefehls eines Nodes mit seinem bereits verwendeten Token behält die Registrierung bei und läuft als erneuter Lauf ohne Token. Ein anderes Token auf einem registrierten Host wird nicht verwendet: Die Docker- und Monitoring-Installationsprogramme brechen mit einem Fehler ab und ändern nichts (auf einem vor 2.11.1 registrierten Node warnen sie und setzen das Update fort), und das nginx-Installationsprogramm registriert sich mit dem neuen Token, behält aber die vorherige Registrierung, wenn Opfield es ablehnt. Um den Host als anderen Node zu registrieren, stoppen Sie den Daemon, verschieben Sie sein Verzeichnis certs und state.json beiseite und führen Sie den neuen Befehl aus.
Antworten. Ohne -y fragt das Installationsprogramm im Terminal nach und bricht ab, wenn es keine Antwort lesen kann, zum Beispiel ohne Terminal oder wenn seine Ausgabe durch tee geleitet wird; eine fehlende Antwort wird nie als Zustimmung gewertet. Das Ablehnen von Proceed with installation? oder das Abbrechen nach der Zusammenfassung endet mit einem Fehler.
Secure Runtime. Eine neue Installation eines Docker Nodes richtet Secure Runtime ein, wenn der Host es unterstützt. Auf einem Host ohne Unterstützung oder wenn die Einrichtung fehlschlägt, warnt das Installationsprogramm mit dem Grund und fährt fort, und der Node meldet denselben Grund in seinen Fähigkeiten. Mit --secure-runtime schlägt die Installation stattdessen fehl; das Flag installiert Secure Runtime auch auf einer bestehenden Installation. In einer bestehenden /etc/docker/daemon.json fügt die Einrichtung nur runtimes.runsc hinzu, nachdem sie das Original einmal als daemon.json.opfield-backup gesichert hat; jeder andere Schlüssel bleibt unverändert.
Daemon-Version. Ohne --version installiert ein Installationsprogramm das neueste stabile Daemon-Release, aber ein erneuter Lauf installiert nie einen älteren Daemon als den installierten, zum Beispiel auf einem Node, der ein neueres Pre-Release ausführt. Es gibt dann die installierte Version und das Release aus, auf das latest verweist, und behält die installierte Version. Um das ältere Release zu installieren, nennen Sie es mit --version (OPFIELD_NODE_DAEMON_VERSION bei den Daemon-Installationsprogrammen). Dies gilt für die Installationsprogramme von Docker, Build Worker, Storage, nginx, Monitoring und Relay.
Backups. Wenn die Monitoring-, nginx- und Docker-Installationsprogramme eine Datei ersetzen, etwa die Daemon-Binärdatei oder eine nginx-Konfiguration, behalten sie nur das neueste Backup davon (<file>.backup.<timestamp>).

Einen Daemon ohne Root ausführen

Die Monitoring-, Docker- (Profil docker), nginx- und Relay-Daemons können als bestehender Benutzer ohne Root-Rechte laufen: Übergeben Sie --user <user> an das Monitoring-, Docker- oder nginx-Installationsprogramm oder setzen Sie OPFIELD_RELAY_RUN_USER (und optional OPFIELD_RELAY_RUN_GROUP) für das Relay-Installationsprogramm. Das Installationsprogramm selbst läuft weiterhin mit sudo und bricht ab, bevor es den Host ändert, wenn der Benutzer nicht existiert. Storage Nodes und Build Worker laufen nur als Root.

Benutzer wechseln. Führen Sie das Installationsprogramm des Nodes erneut mit einem anderen --user aus, oder ohne --user, um zu Root zurückzukehren. Der Node behält seine Registrierung und Host-Identität; ein registriertes Relay benötigt für einen solchen erneuten Lauf kein --token. Auf Docker- und nginx-Nodes bereitet das Installationsprogramm alles vor, während der Daemon weiter bedient, und stoppt ihn unmittelbar bevor der neue Prozess startet; der Monitoring-Daemon und der Relay-Supervisor werden zuerst gestoppt. Der Daemon wird gestoppt, bevor eine seiner Dateien den Eigentümer wechselt. Der Wechsel startet den Daemon einmal neu: Verbindungen über seine Datenbank-, Speicher- und Container-Links werden einmal für etwa 1,5 Sekunden getrennt, und Clients verbinden sich erneut, wie bei jedem Neustart eines Daemons. Routenverkehr über Secure Links wartet nur, weil der Daemon eines Docker- oder nginx-Nodes unter systemd seine Link-Sockets an systemd übergibt, das sie über den Wechsel hinweg hält. Auf einem Docker Node, dessen Speicherverbindungen noch Sidecars pro Verbindung von vor 2.11.1 verwenden, erstellt der Wechsel diese Sidecars außerdem neu. Der vorherige Benutzer behält Gruppenmitgliedschaften, die ihm das Installationsprogramm gegeben hat, etwa docker; entfernen Sie sie mit gpasswd -d <user> docker.
Docker. Das Installationsprogramm fügt den Benutzer der Gruppe docker hinzu, was Root auf dem Host gleichkommt. Ohne Root sind Disk-Image-Volumes, das Verschieben von Volume-Daten zwischen Nodes, Container-Loggrößen und die Installation von Secure Runtime aus Opfield nicht verfügbar; um Secure Runtime zu installieren, führen Sie das Installationsprogramm erneut mit demselben --user und --secure-runtime aus (Node Details zeigt den Befehl). Der Lease-Watchdog läuft weiterhin als Root-Dienst.
nginx. nginx muss bereits als derselbe Benutzer mit CAP_NET_BIND_SERVICE laufen, und der Benutzer muss Eigentümer von /etc/nginx, /var/log/nginx und den temporären Verzeichnissen von nginx sein; verwenden Sie --nginx-mode integrate. Am einfachsten ist es, nginx als Benutzer der Distribution (www-data oder nginx) auszuführen und den Daemon als diesen Benutzer zu installieren. Setzen Sie unter OpenRC command_user="<user>:<group>" und capabilities="^cap_net_bind_service" in /etc/conf.d/nginx und pid /run/nginx/nginx.pid; in nginx.conf. Läuft nginx nicht als dieser Benutzer, bricht das Installationsprogramm ab, bevor es etwas ändert, und listet auf, was vorzubereiten ist. Um zu Root zurückzukehren, führen Sie nginx zuerst wieder als Root aus.
Relay. Ein Relay-Port unter 1024 erfordert systemd oder OpenRC; das Installationsprogramm vergibt die Bind-Capability.
Host-Konsole. console.user in der Daemon-Konfiguration führt Konsolensitzungen nur bei einem Root-Daemon als anderer Benutzer aus. Ein Daemon, der als eigener Benutzer läuft, verweigert Konsolensitzungen, solange console.user einen anderen Benutzer nennt (409 NODE_CONSOLE_USER_UNAVAILABLE), und die Node-Seite nennt die Abhilfe: console.user entfernen oder den Daemon als Root ausführen.

Host-Konsole und Dateien ausschalten

Jeder Daemon-Typ liest zwei Schalter für den Host-Zugriff aus seiner Konfigurationsdatei: console.enabled und files.enabled, beide standardmäßig true. Mit console.enabled: false verweigert der Daemon die Host-Konsole, einschließlich einmaliger Befehle vom Assistenten und von MCP; mit files.enabled: false verweigert er den Zugriff auf Host-Dateien. Die Docker-, nginx-, Monitoring- und Relay-Installationsprogramme setzen sie mit --disable-console und --disable-files, und die Einrichtungsdialoge für Nodes bieten die Kontrollkästchen Disable host console und Disable host files, die diese Flags hinzufügen. Nodes, die über einen Hosting-Anbieter bestellt werden, installiert Opfield selbst; schalten Sie die Schalter dort durch Bearbeiten der Konfigurationsdatei aus.

Die Schalter befinden sich nur auf dem Node, daher kann ein Opfield-Administrator sie nicht aus der Ferne wieder einschalten. Um einen zu ändern, bearbeiten Sie die Datei auf dem Node und starten Sie den Daemon neu. Opfield lehnt die deaktivierten Anfragen mit 409 NODE_CONSOLE_DISABLED bzw. 409 NODE_FILES_DISABLED ab. Container-Konsolen und Container-Dateien sind nicht betroffen. Um den Host-Zugriff zu entfernen, deaktivieren Sie beide: Ein Daemon, der als Root läuft und noch Dateien schreiben kann, kann den Host ändern und die Konsole wieder einschalten. Die Node-Seite zeigt eine Warnung, solange die Konsole aus und der Dateizugriff an ist. Für ein Relay auf der Maschine eines anderen verwenden Sie den geschützten Modus.

Alpine-, OpenRC- und LXC-Gäste

Die Installationsprogramme unterstützen OpenRC ebenso wie systemd, auch für Daemons, die als eigener Benutzer laufen. Ein Docker Node benötigt, dass Docker seinen Containern die cgroup-Controller memory, pids und cpu bereitstellt, weil der Secure-Link-Connector und verwaltete Workloads mit Limits laufen. Das Installationsprogramm prüft dies und verweigert die Registrierung des Nodes, wenn ein Controller fehlt; es ändert die cgroup-Einrichtung des Hosts nicht.

Auf einem Alpine-LXC-Gast mit OpenRC gibt die Root-cgroup oft keine Controller weiter, weil jeder Prozess in ihr liegt. Lassen Sie den OpenRC-Dienst cgroups die Prozesse herausverschieben, bevor er die Controller aktiviert: Führen Sie rc-update add cgroups boot aus, fügen Sie Folgendes in /etc/conf.d/cgroups ein und starten Sie den Gast neu.

# Move every process out of the root cgroup so that the cgroups service can pass the controllers down.
start_pre() {
  [ -w /sys/fs/cgroup/cgroup.subtree_control ] || return 0
  mkdir -p /sys/fs/cgroup/init
  for pid in $(cat /sys/fs/cgroup/cgroup.procs); do
    echo "$pid" > /sys/fs/cgroup/init/cgroup.procs 2>/dev/null
  done
  return 0
}

Prüfen Sie dann mit cat /sys/fs/cgroup/cgroup.subtree_control /sys/fs/cgroup/docker/cgroup.controllers: Beide müssen memory, pids und cpu auflisten. Die LXC-Containerkonfiguration auf dem Hypervisor muss dafür nicht geändert werden.

Prüfung und Bereinigung

Die Registrierung ist erst abgeschlossen, wenn der Daemon die erwarteten Fähigkeiten meldet und die erste Momentaufnahme von Inventar und Metriken eintrifft. Schlägt die Installation vor der Registrierung fehl, prüfen Sie die lokalen Dienst- und Installationslogs. Löschen Sie den ausstehenden Eintrag nur, wenn Sie diese Identität aufgeben; ein Token eines gelöschten Nodes darf nicht wiederverwendet werden.

Fehlerbilder bei der Installation

Das nginx-Node-Installationsprogramm kann nach einem fehlgeschlagenen Lauf erneut auf demselben Host ausgeführt werden, und ein erneuter Lauf behält den Nginx-Modus der bestehenden Installation bei. Kann der Befehl den Daemon nicht herunterladen oder starten, prüfen Sie ausgehendes HTTPS, DNS, Systemzeit, Zustand des Paketmanagers, Architektur und verfügbaren Festplattenplatz. Startet der Daemon, die Registrierung wird aber nicht abgeschlossen, prüfen Sie die Erreichbarkeit von Relay, dass das einmalige Token noch nicht verbraucht ist und dass der Befehl für den im Dialog angezeigten ausstehenden Node ausgeführt wurde. Erzeugen Sie nicht mehrere ausstehende Einträge, um deren Befehle wechselweise auszuprobieren.

Ein Node, der sich ohne seine erwartete Fähigkeit registriert, ist für diese Rolle nicht bereit. Prüfen Sie den Rollendienst, Berechtigungen für Socket oder Speicher, erforderliche Kernel-Funktionen und die begrenzten Startlogs des Daemons. Korrigieren Sie die Voraussetzung auf dem Host und lassen Sie die Fähigkeitsmeldung aktualisieren; den Node Type nach der Installation zu ändern, ersetzt nicht die Installation des richtigen Profils.

Wurde der Host mit der falschen Rolle registriert, nehmen Sie diese Identität bewusst außer Betrieb und erstellen Sie einen neuen Node mit der richtigen Rolle. Stellen Sie vor dem Löschen sicher, dass der falschen Identität keine Ressourcen oder Operationen zugewiesen wurden, und deinstallieren Sie ihr Daemon-Material, damit sie sich nicht unerwartet erneut verbinden kann.

Sicherheit nach der Installation

Behandeln Sie den generierten Installationsbefehl als kurzlebige Zugangsberechtigung. Führen Sie ihn nur auf dem vorgesehenen Host aus, fügen Sie ihn nicht in gemeinsame Chats oder dauerhafte Shell-Automatisierung ein und entfernen Sie ihn nach der Registrierung aus betrieblichen Notizen. Das installierte Daemon-Zertifikat wird zur dauerhaften Identität und darf weder auf eine andere Maschine kopiert noch auf zwei aktiven Hosts wiederhergestellt werden.

Beschränken Sie den lokalen Zugriff auf Daemon-Konfiguration, Zertifikatsmaterial, Registry-Zugangsdaten, Datenbankspeicher und rollenspezifische Sockets. Die Registrierung stellt Vertrauen zwischen Opfield und dem Host her; sie härtet keine anderen Dienste des Betriebssystems. Wenden Sie die Host-Basis Ihrer Organisation an und halten Sie die Angriffsfläche der Rolle nicht breiter als ihre dokumentierten Voraussetzungen.