Das Relay über einen Cloudflare Tunnel erreichen

Ein Cloudflare Tunnel gibt deinem Relay eine öffentliche HTTPS-Adresse, ohne eigenen Server und ohne einen Port an deinem Router zu öffnen. OAR kann Cloudflares Programm cloudflared für dich betreiben: Es startet es mit dem Relay, startet es neu, wenn die Verbindung abbricht, und zeigt seinen Zustand im Statuspunkt. Nimm es, wenn du eine Domain bei Cloudflare hast und das Relay vom Handy oder aus einem anderen Netzwerk erreichen willst, oder wenn du HTTPS brauchst, um die Seite als App zu installieren und für Push-Benachrichtigungen.

cloudflared verbindet sich nach außen zu Cloudflare. Das Relay lauscht weiter nur auf diesem Rechner (localhostOnly bleibt true), und Cloudflare leitet Anfragen für deinen Hostnamen über diese Verbindung an den Port des Relays.

Was du brauchst #

• Ein Cloudflare-Konto mit Zero Trust und eine Domain (eine Zone) darin für den öffentlichen Hostnamen.
• cloudflared, installiert auf dem Rechner, auf dem das Relay läuft. OAR liefert es nicht mit und installiert es nicht.
• Einen Tunnel, den du in Cloudflare anlegst. OAR betreibt ihn mit dem Token des Tunnels.

Das Relay startet das Programm, das in cloudflaredTunnel.binary steht, sonst das cloudflared, das es in seinem PATH findet. Installiere es mit:

Unter Windows funktioniert ein .cmd- oder .bat-Starter nicht. OAR startet eine .exe- oder .com-Datei.

Einrichten #

1. Leg in deinem Cloudflare-Zero-Trust-Konto einen Tunnel an. Kopiere sein Token.
2. Gib dem Tunnel einen öffentlichen Hostnamen in deiner Zone, zum Beispiel relay.example.com, und richte ihn auf http://localhost:3333. Hast du port in config.json geändert, nimm diesen Port. Dieses Routing liegt bei Cloudflare, nicht auf deinem Rechner.
3. Füge den Block cloudflaredTunnel mit dem Token in config.json ein (siehe Config-Keys).
4. Starte das Relay mit oar restart neu.

Öffne https://relay.example.com/ in einem Browser. Du meldest dich wie gewohnt mit dem Zugriffstoken an.

Der Config-Block #

{
  "cloudflaredTunnel": {
    "mode": "managed",
    "required": false,
    "token": "<tunnel token>",
    "binary": "cloudflared",
    "extraArgs": []
  }
}

Die alte Form "enabled": true funktioniert weiterhin für mode: "managed". Drei Umgebungsvariablen überschreiben die Datei: COPILOT_CLOUDFLARED_MODE, COPILOT_CLOUDFLARED_TOKEN und COPILOT_CLOUDFLARED_BINARY. Die config.json-Referenz führt die Keys mit den anderen Tunnel-Einstellungen auf, und die Seite Umgebungsvariablen führt die Variablen auf.

Das Relay übergibt das Token an cloudflared als Befehlszeilenargument (cloudflared tunnel run --token <token>), nicht über die Umgebung. Auf einem Rechner mit anderen Benutzern kann das Token daher in der Liste laufender Prozesse auftauchen. Das Log des Relays zeigt es als <redacted>.

Wie er sich verhält #

• Start und Stopp. Das Relay startet cloudflared, wenn es selbst startet, und stoppt es (mit einem Beendigungssignal), wenn es herunterfährt.
• Verbunden. Der Tunnel gilt als verbunden, wenn cloudflared eine registrierte Verbindung meldet, oder ersatzweise, wenn es fünf Sekunden gelaufen ist.
• Abbrüche. Wenn cloudflared endet, startet das Relay es nach einer Wartezeit von etwa 5, 10, 20, 40 und dann 60 Sekunden neu, jeweils mit bis zu 20 Prozent Aufschlag. Die Stufen beginnen von vorn nach einer Verbindung, die länger als 30 Sekunden gehalten hat.
• Falsches Token oder gelöschter Tunnel. Endet cloudflared dreimal hintereinander innerhalb von 10 Sekunden, meldet das Relay den Fehler auth-or-config und versucht es ab dann nur noch etwa einmal pro Minute.
• Kein cloudflared. Das Relay startet wie gewohnt, und der Tunnel bleibt aus. Es sieht jede Minute erneut nach und startet den Tunnel, sobald das Programm da ist. Hast du es in einen Ordner installiert, der nicht im PATH des Relays liegt, starte das Relay neu.

Pflicht-Tunnel #

Mit required: true nimmt das Relay keine Nachrichten aus der Queue, solange der Tunnel nicht verbunden ist. Das gilt auch für die Zeit vor der ersten Verbindung und für ein fehlendes cloudflared oder Token. Nutze es, wenn das Relay nur nützt, wenn du es von außen erreichst. Nachrichten warten in der Queue und laufen, sobald der Tunnel verbunden ist (siehe Turns und die Queue).

Den Zustand sehen #

Das Relay kennt deinen öffentlichen Hostnamen nicht, weil das Routing bei Cloudflare liegt; deshalb zeigt ihn keine dieser Stellen.

Tunnel-Verkehr unterscheiden #

Cloudflare fügt jeder Anfrage, die es weiterleitet, einen Header cf-ray hinzu. Das Relay erkennt daran, ob eine Anfrage durch den Tunnel kam oder auf diesem Rechner gestellt wurde. Sollen auch die Header, die dein eigener Edge hinzufügt, so behandelt werden, trag sie in tunnelMarkerHeaders ein. publicHostnames führt die Hostnamen auf, über die das Relay erreicht wird, und trustProxy legt fest, welchen Proxys das Relay die weitergeleitete Adresse glaubt. Der Standard, "loopback", passt zu cloudflared auf demselben Rechner. Alle drei stehen in der config.json-Referenz.

Ein zweiter Hostname für Previews #

Previews brauchen einen eigenen Hostnamen, damit eine App in der Preview nie ein Anmelde-Cookie mit dem Relay teilt. Füge ihn demselben Tunnel als zweiten öffentlichen Hostnamen hinzu, der auf den Preview-Listener zeigt (standardmäßig http://127.0.0.1:3334). Die Seite zu Previews hat das Ingress-Beispiel und den Block previews. Trag den Hostnamen des Relays in publicHostnames ein.

Cloudflare Access vor dem Relay #

Eine Cloudflare-Access-Anwendung über dem Hostnamen des Relays gilt für jeden Besucher, auch für Betrachter einer geteilten Konversation. Ohne Ausnahme werden sie zur Anmeldung aufgefordert, und der Link funktioniert nicht. Lass /shared/* und /api/shared/* ohne Anmeldung durch.

Leg keine Cloudflare-Cache-Regel für /api/shared/* an. Eine geteilte Seite lädt diese Adresse neu, um der Konversation zu folgen, und eine zwischengespeicherte Antwort würde weiter einen alten Stand zeigen. Das Relay versieht jede API-Antwort mit Cache-Control: no-store und jede Antwort mit CDN-Cache-Control und Cloudflare-CDN-Cache-Control auf no-store. Cloudflare befolgt diese beiden vor einer Cache-Regel in deiner Zone.

Sicherheit #

Ein Tunnel stellt das Relay ins öffentliche Internet. Das Zugriffstoken hält andere draußen. Siehe Das Zugriffstoken und wer das Relay erreicht und Was OAR offenlegt.

Die Session-Worker des Relays verbinden sich über Sockets, die nur auf diesem Rechner laufen. Weil ein öffentlicher Tunnel jeden Pfad weiterleitet, antwortet das Relay mit 403 auf eine Anfrage an diese Pfade, die cf-ray oder einen deiner tunnelMarkerHeaders trägt, und das Log vermerkt das mit [tunnel-guard]. Geteilte Links, die ohne Anmeldung über den Tunnel kommen, sind nicht betroffen.

Fehlerbehebung #