Verwaltung eines Uncloud-Clusters
Referenz für die uc-CLI – eine dezentrale Self-Hosting-Plattform, die Docker-Container, WireGuard-Mesh-Netzwerke und den Caddy-Reverse-Proxy verwendet.
Wann zu aktivieren
Verwenden Sie diese Fähigkeit, wenn Sie mit Uncloud-Clustern arbeiten, insbesondere wenn:
- Sie Maschinen mit
uc machinebootstrappen oder dem Cluster hinzufügen - Sie Dienste aus Compose-Dateien mit
uc deploybereitstellen - Sie HTTP-, HTTPS-, TCP- oder UDP-Ports über Uncloud veröffentlichen
- Sie den Caddy-Ingress mit
x-caddy,x-portsoder--caddyfilekonfigurieren - Sie externe LAN-Geräte über den Cluster-Proxy routen
- Sie Logs, Dienstzustände, Volumes, DNS oder die Platzierung von Maschinen überprüfen
Funktionsweise
Uncloud führt Docker-Dienste auf mehreren über ein WireGuard-Mesh verbundenen Maschinen aus. Jede Maschine ist ein gleichberechtigtes Cluster-Mitglied; Dienste kommunizieren über das Overlay-Netzwerk, und Caddy wird global ausgeführt, um den öffentlichen HTTP/HTTPS-Traffic zu terminieren. Compose-Dateien können Uncloud-Erweiterungen für Ingress, Platzierung und generierte Caddy-Konfiguration nutzen, während die uc-CLI die Image-Verteilung, Planung, Skalierung, Logs und den Cluster-Zustand verwaltet.
Beispiele
uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy
Kernkonzepte
- Keine zentrale Steuerungsebene – alle Maschinen sind gleichberechtigte, über WireGuard verbundene Peers
- Caddy läuft als globaler Dienst auf jeder Maschine; erhält automatisch TLS-Zertifikate von Let's Encrypt
- Overlay-Netzwerk – Dienste kommunizieren standardmäßig über
10.210.0.0/16; DNS ist innerhalb des Meshes verfügbar - Caddyfile wird automatisch generiert – niemals direkt bearbeiten; stattdessen
x-caddy/--caddyfileverwenden
CLI-Kurzreferenz
Maschinen
| Befehl | Zweck |
|---|---|
uc machine init user@host | Erste Maschine / neues Cluster bootstrappen |
uc machine add user@host | Maschine einem bestehenden Cluster hinzufügen |
uc machine ls | Maschinen auflisten |
uc machine update NAME --public-ip IP | Öffentliche IP für Ingress aktualisieren |
uc machine rm NAME | Maschine entfernen |
Wichtige init-Flags: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none
Dienste
| Befehl | Zweck |
|---|---|
uc service ls / uc ls | Dienste auflisten |
uc service run IMAGE | Einzelnen Container-Dienst ausführen |
uc deploy | Aus compose.yaml bereitstellen |
uc deploy --no-build | Bereits gepushte Images ohne Neuerstellung bereitstellen |
uc deploy --recreate | Dienst-Neuerstellung erzwingen |
uc scale DIENST N | Replikatanzahl festlegen |
uc service logs DIENST | Logs anzeigen |
uc service exec DIENST | Shell im Container öffnen |
uc service inspect DIENST | Detaillierte Informationen |
uc service rm DIENST | Dienst entfernen (benannte Volumes bleiben erhalten) |
uc ps | Alle Container im Cluster |
Images
uc image push myapp:latest # Lokales Image auf alle Maschinen pushen
uc image push myapp:latest -m machine1,machine2 # Auf bestimmte Maschinen pushen
uc images # Images im Cluster auflisten
Volumes
uc volume ls # Alle Volumes
uc volume ls -m machine1 # Auf bestimmter Maschine
uc volume create NAME -m MASCHINE
uc volume rm NAME
Caddy
uc caddy config # Aktuelles generiertes Caddyfile anzeigen (schreibgeschützt)
uc caddy deploy # Caddy im Cluster bereitstellen/upgraden
DNS & Kontext
uc dns show # Reservierte *.uncld.dev-Domain anzeigen
uc dns reserve # Neue Domain reservieren
uc ctx ls # Cluster-Kontexte auflisten
uc ctx use prod # Kontext wechseln
Port-Veröffentlichung
HTTP/HTTPS (über Caddy-Reverse-Proxy)
-p [hostname:]container_port[/protokoll]
| Beispiel | Bedeutung |
|---|---|
-p 8080/https | HTTPS mit automatischem dienstname.cluster-domain-Hostnamen |
-p app.example.com:8080/https | HTTPS mit benutzerdefiniertem Hostnamen |
-p 8080/http | Nur HTTP, kein TLS |
TCP/UDP (hostgebunden, umgeht Caddy)
-p [host_ip:]host_port:container_port[/protokoll]@host
| Beispiel | Bedeutung |
|---|---|
-p 5432:5432@host | TCP 5432 auf allen Schnittstellen |
-p 127.0.0.1:5432:5432@host | TCP 5432 nur Loopback |
-p 53:5353/udp@host | UDP |
Compose-Datei-Erweiterungen
Uncloud fügt diese Erweiterungen zu Docker Compose hinzu:
x-ports – Ports mit Domains veröffentlichen
services:
app:
image: app:latest
x-ports:
- example.com:8000/https
- www.example.com:8000/https
- api.example.com:9000/https
x-caddy – Benutzerdefinierte Caddy-Konfiguration für den Dienst
services:
app:
image: app:latest
x-caddy: |
example.com {
redir https://www.example.com{uri} permanent
}
www.example.com {
reverse_proxy {{upstreams 8000}} {
import common_proxy
}
basic_auth /admin/* {
admin $2a$14$...
}
}
Innerhalb von x-caddy verfügbare Vorlagenfunktionen:
{{upstreams [dienst] [port]}}– IPs der fehlerfreien Container{{.Name}}– Dienstname{{.Upstreams}}– Abbildung aller Dienste → IPs
x-machines – Platzierungsbeschränkungen
services:
db:
image: postgres:18
x-machines: db-machine # Name einer einzelnen Maschine
app:
image: app:latest
x-machines:
- machine-1
- machine-2
Vollständiges Beispiel mit mehreren Diensten
services:
api:
build: ./api
x-ports:
- api.example.com:3000/https
environment:
DATABASE_URL: postgres://db:5432/mydb
web:
build: ./web
x-ports:
- example.com:8000/https
- www.example.com:8000/https
environment:
API_URL: http://api:3000
db:
image: postgres:18
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db-data:/var/lib/postgresql/data
x-machines: db-machine
volumes:
db-data:
Routing zu externen (Nicht-Cluster-)Geräten
Um ein externes Gerät (z. B. BMC, NAS, Router-UI) über Caddy verfügbar zu machen, ohne einen echten Container auszuführen:
1. Caddyfile-Snippet erstellen (z. B. ~/geraet.caddyfile):
https://geraet.example.com {
reverse_proxy https://192.168.1.x {
transport http {
tls_insecure_skip_verify # Erforderlich für selbstsignierte BMC-Zertifikate
}
}
log
}
Für unverschlüsselte Upstreams: reverse_proxy http://192.168.1.x:port
2. Als benannten Dienst mit No-Op-Container registrieren:
uc service run \
--name geraet-bmc \
--caddyfile ~/geraet.caddyfile \
registry.k8s.io/pause:3.9
pause ist ein minimaler No-Op-Container – er tut nichts, gibt Uncloud aber einen Diensteintrag, an den das Caddyfile angehängt werden kann.
3. Überprüfen:
uc caddy config # Der Block für geraet.example.com sollte erscheinen
--caddyfilekann nicht mit Nicht-@host-veröffentlichten Ports kombiniert werden.
DNS-Tipp: Ein Wildcard-Eintrag (*.ihredomain.de → cluster-public-ip) stellt sicher, dass jede neue Subdomain sofort funktioniert – kein DNS-Wechsel pro Dienst erforderlich.
Dienst-DNS (Intern)
Dienste im Cluster lösen sich gegenseitig per Name auf:
| DNS-Name | Auflösung |
|---|---|
dienstname | Jeder fehlerfreie Container |
dienstname.internal | Gleich wie oben |
rr.dienstname.internal | Round-Robin |
nearest.dienstname.internal | Zuerst maschinenlokal |
Skalierung & Globale Dienste
uc scale web 5 # 5 Replikate (auf Maschinen verteilt)
uc scale web 1 # Herunterskalieren
services:
caddy:
deploy:
mode: global # Ein Container auf jeder Maschine
Image-Tag-Vorlagen (in compose.yaml)
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-lokal}
| Funktion | Ausgabe |
|---|---|
{{gitsha N}} | Erste N Zeichen des Commit-SHA |
{{gitdate "format"}} | Git-Commit-Datum im Go-Format |
{{date "format"}} | Aktuelles Datum |
Häufige Workflows
Aus dem Quellcode bereitstellen:
uc deploy # Erstellen + Pushen + Bereitstellen
uc build --push && uc deploy --no-build # Getrennte Schritte
Einen Dienst überprüfen:
uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web # Shell öffnen
uc exec web /bin/sh -c "env" # Bestimmten Befehl ausführen
Ausfallfreie Bereitstellungen erfolgen automatisch; Uncloud wartet auf Health Checks, bevor alte Container terminiert werden.
Neuerstellung erzwingen:
uc deploy --recreate
Häufige Fehler
| Fehler | Behebung |
|---|---|
| Das Caddyfile direkt bearbeiten | x-caddy in Compose oder --caddyfile bei uc service run verwenden |
| Einen HTTPS-Upstream mit selbstsigniertem Zertifikat proxen | transport http { tls_insecure_skip_verify } hinzufügen |
uc caddy config zeigt keine benutzerdefinierten Blöcke | Caddy-Admin-Socket nicht erreichbar – uc inspect caddy und uc logs caddy überprüfen |
| Dienst kann vom Container aus keine externe LAN-IP erreichen | Überprüfen, ob der Host des Caddy-Containers eine Route zum Zielnetzwerk hat |
Volumes nach uc service rm verloren | Benannte Volumes bleiben erhalten; nur anonyme Volumes werden automatisch entfernt |