Jamdesk Documentation logo

Cloudflare Workers

Leiten Sie /docs-Anfragen über einen Cloudflare Worker an Ihre Jamdesk-Dokumentation weiter. Einrichtung, Routenmuster und Caching-Konfiguration.

Ein Cloudflare Worker fängt Anfragen unter /docs auf Ihrer Domain ab, schreibt sie auf Ihre Jamdesk-Subdomain um und gibt die Antwort zurück. Er läuft am Edge ohne Origin-Server. Erstellen Sie den Worker mit npx jamdesk deploy-proxy cloudflare oder richten Sie ihn unten manuell ein.

Funktionsweise

Der Worker leitet Anfragen an Ihre Jamdesk-Subdomain weiter. Dabei übergibt er Ihre Domain im Header X-Jamdesk-Forwarded-Host. Jamdesk liest diesen Header, um die Domain zu verifizieren und die Einstellungen anzuwenden. Es handelt sich um eine einmalige Einrichtung. Spätere Änderungen an Ihrer Domain oder Konfiguration im Dashboard erfordern kein Update des Workers.

Voraussetzungen

  • Ein Cloudflare-Konto mit konfigurierter Domain
  • Wrangler CLI v3.0+ installiert
  • Ihre Jamdesk-Subdomain (zu finden in den Dashboard-Einstellungen)
  • Ihre benutzerdefinierte Domain, hinzugefügt zu Ihrem Projekt im Jamdesk-Dashboard (der Worker gibt einen 403 zurück, bis die Domain registriert und verifiziert ist)
  • Ein proxied (orangefarbener Wolke) DNS-Eintrag für den Hostnamen, der Ihre Dokumentation ausliefert. Worker laufen nur auf proxied Einträgen. Eine Domain, die sonst nichts hostet, benötigt trotzdem einen solchen Eintrag: Legen Sie einen Platzhalter-AAAA-Eintrag an, der auf 100:: zeigt, und setzen Sie ihn auf proxied.

Schnelle Einrichtung mit der CLI

Richten Sie den Worker mit einem Befehl ein:

npx jamdesk deploy-proxy cloudflare

Dieser interaktive Befehl:

  1. Prüft, ob wrangler 3.0+ installiert ist
  2. Verifiziert Ihr Cloudflare-Konto und zeigt verfügbare Domains an
  3. Ermittelt Ihre Jamdesk-Subdomain aus dem in docs.json verknüpften Projekt
  4. Lässt Sie Ihre Ziel-Domain aus Ihren Cloudflare-Zonen auswählen
  5. Erzeugt alle erforderlichen Dateien
  6. Optional: Deployment zu Cloudflare

Bei Zugriff auf mehrere Cloudflare-Konten (häufig bei Agenturen oder Teams) fordert die CLI Sie auf, eines auszuwählen, bevor die Zone gewählt wird. Wählen Sie das Konto, dem die Domain gehört, auf die Sie deployen. Worker-Routen können nur für Domains im ausgewählten Konto erstellt werden.

Nicht interaktive Einrichtung

Übergeben Sie die Antworten als Flags, um ohne Abfragen zu laufen, etwa in CI oder einem Skript:

jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes

--yes erzeugt die Worker-Dateien und stoppt. Es deployt nie. Die Zone wird aus Ihrer Domain abgeleitet, nicht gegen Ihr Cloudflare-Konto geprüft. Die Konfiguration live zu schalten bleibt ein expliziter Schritt. Abschließen mit:

cd cloudflare-worker
npx wrangler deploy

--yes kann Sie nicht nach Ihrer Subdomain fragen. Die CLI liest sie aus dem in docs.json verknüpften Projekt. Fehlt diese Verknüpfung, übergeben Sie --slug (oder führen Sie einmal jamdesk deploy aus, um die Verknüpfung anzulegen). Andernfalls stoppt der Befehl, statt zu raten.

Existiert das Ausgabeverzeichnis bereits, stoppt --yes, statt es zu ersetzen. Fügen Sie --force hinzu, um zu überschreiben, oder --output-dir, um woanders zu schreiben.

OptionBeschreibung
--slugIhre Jamdesk-Subdomain, das X in X.jamdesk.app (überspringt die automatische Erkennung)
--domainZiel-Domain (z. B. yoursite.com)
--pathPfadpräfix; muss exakt mit Ihrem Subpfad im Dashboard übereinstimmen (Standard: /docs)
--output-dirAusgabeverzeichnis (Standard: cloudflare-worker/)
--skip-deployDie Abfrage „jetzt deployen?“ in einem interaktiven Lauf überspringen (--yes deployt nie)
--forceDas Ausgabeverzeichnis überschreiben, falls es bereits existiert
--yesJede Abfrage mit ihrem Standardwert beantworten (CI-Modus). Deployt nie. Überschreibt ein bestehendes Verzeichnis nur zusammen mit --force

Oder folgen Sie den manuellen Schritten unten.

Manuelle Einrichtung

Schritt 1: Worker erstellen

Erstellen Sie ein neues Verzeichnis für Ihren Worker und initialisieren Sie es:

mkdir docs-proxy && cd docs-proxy
npm init -y

Schritt 2: Worker-Code hinzufügen

Erstellen Sie index.js mit folgendem Code:

index.js
/**
 * Jamdesk Documentation Proxy Worker
 *
 * Generated by: jamdesk deploy-proxy cloudflare
 * Proxies /docs/* requests AND their assets to YOUR_SLUG.jamdesk.app
 *
 * Assets under /_jd/* (images, fonts, branding, analytics) must also be proxied
 * since they use absolute paths in the HTML.
 */

const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

// Paths that are always proxied to Jamdesk
const PROXY_PATHS = [
  "/docs",  // Documentation pages
  "/_jd/",  // All Jamdesk assets (images, fonts, branding, analytics)
];

function shouldProxy(pathname) {
  return PROXY_PATHS.some(prefix => {
    // For the docs path, require exact match or prefix with slash (not /docs.json)
    if (prefix === "/docs") {
      return pathname === "/docs" || pathname.startsWith("/docs/");
    }
    return pathname.startsWith(prefix);
  });
}

function proxyToJamdesk(request, url) {
  // Rewrite the request to Jamdesk
  const proxyUrl = new URL(request.url);
  proxyUrl.hostname = JAMDESK_HOST;
  // Pin the scheme: an http:// visitor proxied as http:// gets a 308 from
  // Vercel's edge pointing at JAMDESK_HOST, and redirect:"manual" hands that
  // redirect straight to the browser — bouncing the visitor off this domain.
  proxyUrl.protocol = "https:";
  // Setting .protocol leaves a non-default .port in place, so :8787 (wrangler
  // dev) or Cloudflare's alternate http ports (8080, 8880, 2052…) would follow
  // us to the https upstream and fail there.
  proxyUrl.port = "";

  // Clone headers and add proxy headers
  const headers = new Headers(request.headers);
  headers.set("Host", JAMDESK_HOST);
  headers.set("X-Forwarded-Host", url.hostname);
  headers.set("X-Forwarded-Proto", "https");
  // Custom header for domain verification (Vercel strips standard forwarding headers)
  headers.set("X-Jamdesk-Forwarded-Host", url.hostname);

  // Don't follow redirects — let the browser handle them so the URL updates.
  // Without this, redirects happen internally and the browser URL doesn't change,
  // which causes the sidebar to mis-highlight the active page.
  const proxyRequest = new Request(proxyUrl, {
    method: request.method,
    headers,
    body: request.body,
    redirect: "manual",
  });

  // Cache all content types at Cloudflare edge (CF doesn't cache HTML by default).
  // Cache duration is controlled by upstream Cache-Control headers.
  // Never cache redirects or errors — they must always hit origin.
  return fetch(proxyRequest, {
    cf: {
      cacheEverything: true,
      cacheTtlByStatus: { "300-399": 0, "400-499": 0, "500-599": 0 },
    },
  });
}

export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (shouldProxy(url.pathname)) {
      return proxyToJamdesk(request, url);
    }

    // /_next/ is ambiguous: the customer's root site may itself be a Next.js app
    // serving its own /_next/ assets. Try the origin first and fall back to
    // Jamdesk when the origin doesn't have it (404) or can't answer at all
    // (5xx — a docs-only domain has no real origin, so Cloudflare returns 522).
    // Hashed asset filenames never collide between the two apps.
    if (url.pathname.startsWith("/_next/")) {
      let originResponse;
      try {
        originResponse = await fetch(request);
      } catch (err) {
        // Log rather than swallow: a genuine platform fault and a domain with
        // no origin at all are indistinguishable in `wrangler tail` otherwise.
        console.warn("origin fetch threw, serving from Jamdesk:", err);
        return proxyToJamdesk(request, url);
      }
      if (originResponse.status !== 404 && originResponse.status < 500) {
        return originResponse;
      }
      return proxyToJamdesk(request, url);
    }

    return fetch(request);
  },
};

Ersetzen Sie YOUR_SLUG durch Ihre Jamdesk-Subdomain (z. B. acme, wenn Ihre Dokumentation unter acme.jamdesk.app liegt).

Wenn Sie statt des Standards /docs einen benutzerdefinierten Subpfad aus dem Dashboard verwenden, ersetzen Sie "/docs" durch Ihren Subpfad in PROXY_PATHS und in der exakten Prüfung innerhalb von shouldProxy(). Das --path-Flag der CLI erledigt dies beim Erzeugen der Datei, aber nur gegen eine unveränderte Vorlage. Eine Neugenerierung überschreibt eigene Einträge in PROXY_PATHS. Bearbeiten Sie die /docs-Einträge direkt, wenn Sie diesen Worker angepasst haben.

Der Header X-Jamdesk-Forwarded-Host ist erforderlich. Ein fehlender Header schlägt stillschweigend fehl. Anfragen gelingen weiterhin, aber Seiten werden mit noindex ausgeliefert, und Canonical-Links zeigen auf YOUR_SLUG.jamdesk.app statt auf Ihre Domain. Suchmaschinen indexieren Ihre Dokumentation dann nie. Ein 403 ist das Gegenteil: Der Header ist vorhanden, nennt aber eine Domain, die für dieses Projekt nicht registriert und aktiv ist.

Schritt 3: wrangler.toml konfigurieren

Erstellen Sie wrangler.toml, um Ihren Worker zu konfigurieren:

wrangler.toml
name = "docs-proxy"
main = "index.js"
compatibility_date = "2024-01-01"

# Serve only via the routes below, not on the public <name>.workers.dev URL —
# that URL is a second way into the same proxy and is worth closing.
workers_dev = false

# Single catch-all route; the worker handles path filtering internally
routes = [
  { pattern = "yoursite.com/*", zone_name = "yoursite.com" },
]

Falls Ihr Cloudflare-Login Zugriff auf mehr als ein Konto hat, fügen Sie außerdem account_id = "<your account id>" hinzu. Ohne diesen Eintrag stoppt wrangler deploy, statt zu raten, in welches Konto deployt werden soll. npx wrangler whoami listet Ihre Konto-IDs auf.

Fügen Sie eine zweite Route hinzu, falls Ihre Website auch Traffic auf www.yoursite.com ausliefert:

routes = [
  { pattern = "yoursite.com/*", zone_name = "yoursite.com" },
  { pattern = "www.yoursite.com/*", zone_name = "yoursite.com" },
]

Schritt 4: Bereitstellen

Deployen Sie Ihren Worker zu Cloudflare:

npx wrangler deploy

Schritt 5: Überprüfen

Rufen Sie https://yoursite.com/docs auf und prüfen Sie, ob Ihre Dokumentation lädt.

Fehlerbehebung

Wenn Sie Ihren Subpfad im Dashboard umbenannt haben (etwa /docs → /help), PROXY_PATHS Ihres Workers aber weiterhin nur /docs enthält, erreichen Anfragen an /help/* Jamdesk nie. Sie fallen auf fetch(request) zurück und liefern an Ihrem eigenen Origin ein 404. /docs/* funktioniert in der Zwischenzeit weiter (Jamdesk liefert beide Präfixe aus). Dadurch ist das Problem leicht zu übersehen.

Lösung: Fügen Sie Ihren neuen Subpfad zu PROXY_PATHS hinzu. Führen Sie jamdesk deploy-proxy cloudflare --path <subpath> erneut aus, falls der Worker noch eine unveränderte Vorlage ist. Bearbeiten Sie das Array von Hand, wenn Sie es angepasst haben.

Wrangler bevorzugt CLOUDFLARE_API_TOKEN gegenüber seinem OAuth-Login. Solange dieses Token gesetzt ist, kann er keinen OAuth-Login starten. Dieser Befehl braucht OAuth, um die Zonen Ihres Kontos aufzulisten. Er stoppt und zeigt den Ort des Tokens an, statt innerhalb von wrangler zu scheitern.

Wrangler liest außerdem .env aus dem Verzeichnis, in dem Sie arbeiten. Das Token kann also für wrangler gesetzt sein, ohne in Ihrer Shell zu stehen. Ein leeres echo $CLOUDFLARE_API_TOKEN schließt das nicht aus. Prüfen Sie auch, ob im aktuellen Verzeichnis eine .env liegt.

Lösung: Gewähren Sie dem Token account:read und zone:read und führen Sie den Befehl erneut aus. Oder führen Sie ihn ohne das Token aus:

env -u CLOUDFLARE_API_TOKEN jamdesk deploy-proxy cloudflare

env -u hilft nicht, wenn das Token aus einer .env stammt. Führen Sie den Befehl aus einem Verzeichnis ohne diese .env aus oder verschieben Sie die Datei für den Lauf.

Die CLI zeigt Ihre verfügbaren Domains vor der Zonenauswahl an. Wenn Sie „No domains found“ sehen:

  1. Prüfen Sie, ob Sie beim richtigen Cloudflare-Konto angemeldet sind
  2. Prüfen Sie, ob Ihre Domain im Cloudflare-Dashboard hinzugefügt und aktiv ist
  3. Führen Sie die CLI erneut aus und wählen Sie „No“, wenn Sie gefragt werden, ob Sie mit dem aktuellen Konto fortfahren möchten, um das Konto zu wechseln

Wenn Sie mehrere Cloudflare-Konten haben:

  1. Führen Sie jamdesk deploy-proxy cloudflare aus
  2. Wählen Sie bei der Kontoauswahl das Konto mit Ihrer Domain
  3. Wählen Sie „Switch to different login“ für einen völlig anderen Login
  4. Die CLI meldet Sie ab und fordert Sie auf, sich mit den richtigen Zugangsdaten anzumelden

Dieser Fehler bedeutet, dass die gewählte Zone nicht zu Ihrem Cloudflare-Konto passt. Entweder:

  • Sie haben eine Zone gewählt, die zu einem anderen Konto gehört
  • Die Zone wurde aus Cloudflare entfernt

Lösung: Führen Sie die CLI erneut aus und wählen Sie die richtige Zone aus der Liste oder wechseln Sie zu dem Konto, dem die Zone gehört.

Verwenden Sie ein Catch-All-Routenmuster: yoursite.com/* (nicht nur yoursite.com/docs*). Die interne Funktion shouldProxy() des Workers filtert die Pfade.

Zwei häufige Ursachen:

  1. Worker läuft nicht: Setzen Sie Ihren DNS-Eintrag in Cloudflare auf Proxied (orangefarbene Wolke). Worker laufen nur auf proxied Einträgen.
  2. Fehlender Header X-Forwarded-Host: Der Worker muss diesen Header setzen. Jamdesk benötigt ihn, um korrekte Asset-URLs zu erzeugen.

Wenn Sie „Domain is not authorized to serve this content“ sehen:

  1. Prüfen Sie, ob Ihre Domain im Jamdesk-Dashboard registriert ist
  2. Schließen Sie die DNS-Verifizierung (TXT-Eintrag) für Ihre Domain ab
  3. Setzen Sie den Header X-Jamdesk-Forwarded-Host im Worker-Code
  4. Prüfen Sie, ob Ihre Domain dem richtigen Projekt zugeordnet ist

Die Domain muss verifiziert sein, bevor der Worker Dokumentation ausliefern kann.

Worker laufen nur auf proxied (orangefarbene Wolke) DNS-Einträgen. Ist Ihr A-Eintrag auf „DNS only“ (graue Wolke) gesetzt, gehen Anfragen direkt an den Origin und umgehen den Worker.

Lösung: Stellen Sie den A-Eintrag im Cloudflare-DNS auf proxied (orangefarbene Wolke). Jeder Eintrag mit einer Worker-Route muss proxied sein, Subdomains eingeschlossen.

Jamdesk verifiziert den Besitz, indem es Ihre DNS-Eintragswerte direkt ausliest. Der Proxy von Cloudflare (orangefarbene Wolke) verbirgt diese Werte. Die Verifizierung kann nicht abgeschlossen werden, solange er aktiv ist.

Lösung:

  1. Stellen Sie den DNS-Eintrag auf DNS only (graue Wolke)
  2. Warten Sie, bis die Verifizierung abgeschlossen ist (Status wechselt im Dashboard auf active)
  3. Schalten Sie zurück auf Proxied (orangefarbene Wolke), damit der Worker läuft

Jamdesk liefert Dokumentations-HTML mit Cache-Control: no-store aus. Cloudflare cacht Seiten nicht am Edge (cf-cache-status: BYPASS). Jede Anfrage rendert die aktuelle Version. Veröffentlichte Änderungen erscheinen ohne Cache-Verzögerung.

Statische Assets unter /_next/ und /_jd/ (JavaScript, CSS, Schriften, Bilder) haben langlebige immutable-Cache-Header. Cloudflare cacht sie am Edge. Ihre Dateinamen sind inhaltsgehasht. Jeder Build erzeugt neue URLs. Ein Purge ist nicht erforderlich.

cacheEverything: true erlaubt es Cloudflare, diese statischen Assets auf der proxied Route zu cachen. Es überschreibt nicht das no-store des HTML. Leeren Sie den Edge-Cache manuell über Purge Cache von Cloudflare (Caching → Configuration → Purge Everything).

Die CLI benötigt wrangler 3.0+. Aktualisieren Sie mit:

npm install -g wrangler@latest

Wie geht es weiter?

Nur benutzerdefinierte Domain

Verhindern Sie, dass Ihre Subdomain direkt antwortet

Benutzerdefinierte Domains

DNS verifizieren und Fehler beheben

Subpfad-Hosting

Dokumentation unter /docs ausliefern