Cloudflare Workers — Configuration du proxy

Un Cloudflare Worker intercepte les requêtes à /docs sur votre domaine, les réécrit vers votre sous-domaine Jamdesk, et retourne la réponse -- entièrement en edge, sans serveur d'origine requis. Vous pouvez générer le Worker automatiquement avec npx jamdesk deploy cloudflare ou le configurer manuellement ci-dessous.

Fonctionnement

Le Worker transfère les requêtes vers votre sous-domaine Jamdesk en transmettant le domaine original dans l'en-tête X-Jamdesk-Forwarded-Host. Jamdesk utilise cet en-tête pour :

Vérifier votre domaine - S'assure que seuls les domaines autorisés peuvent servir vos docs
Appliquer la configuration correcte - Utilise les paramètres de votre domaine depuis le dashboard

Cela signifie que le Worker est une configuration unique. Si vous changez ultérieurement votre domaine personnalisé ou votre configuration dans le dashboard Jamdesk, le Worker n'a pas besoin d'être mis à jour — toutes les décisions de routage sont prises côté serveur.

Prérequis

Un compte Cloudflare avec votre domaine configuré
Wrangler CLI v3.0+ installé
Votre sous-domaine Jamdesk (accessible dans les paramètres du dashboard)

Configuration rapide avec CLI

La méthode la plus rapide pour configurer votre Cloudflare Worker :

npx jamdesk deploy cloudflare

Cette commande interactive va :

Vérifier que wrangler 3.0+ est installé
Vérifier votre compte Cloudflare et afficher les domaines disponibles
Détecter automatiquement votre slug de projet depuis docs.json
Vous permettre de sélectionner votre domaine cible parmi vos zones Cloudflare
Générer tous les fichiers requis
Optionnellement déployer sur Cloudflare

Sélection du compte

Le CLI vérifie que vous êtes connecté au bon compte Cloudflare avant de continuer. Si vous avez accès à plusieurs comptes Cloudflare (courant pour les agences ou équipes), vous serez invité à choisir :

Step 2: Verifying Cloudflare account...
✓ Logged in as: you@example.com
? Select the Cloudflare account to use:
❯ Your Personal Account
  Company Team Account
  [ Switch to different login ]

Après avoir sélectionné un compte, seuls les domaines de ce compte seront disponibles pour la sélection de zone :

✓ Using account: Company Team Account
✓ Domains: 3 available for Workers routing

Assurez-vous de sélectionner le compte Cloudflare qui possède le domaine vers lequel vous souhaitez déployer. Chaque compte a son propre ensemble de domaines, et vous ne pouvez créer des routes Workers que pour les domaines du compte sélectionné.

Déploiement CI/scripts

Pour CI/scripts, utilisez des flags pour ignorer les invites :

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

Option	Description
`--slug`	Slug du projet Jamdesk (ignore la détection automatique)
`--domain`	Domaine cible (ex. : yoursite.com)
`--path`	Préfixe de chemin (défaut : /docs)
`--output-dir`	Répertoire de sortie (défaut : cloudflare-worker/)
`--skip-deploy`	Génère les fichiers uniquement, sans déployer
`--force`	Écrase le répertoire existant
`--yes`	Ignore toutes les invites (mode CI)

Si vous préférez une configuration manuelle, continuez avec les étapes ci-dessous.

Configuration manuelle

Étape 1 : Créer un Worker

Créez un nouveau répertoire pour votre Worker et initialisez-le :

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

Étape 2 : Ajouter le code du Worker

Créez index.js avec le code suivant :

index.js

const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

// Paths to proxy to Jamdesk
const PROXY_PATHS = [
  "/docs",    // Documentation pages
  "/_next/",  // Next.js static assets
  "/_jd/",    // Jamdesk assets (fonts, images, branding, analytics)
];

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

    // Check if this path should be proxied
    const shouldProxy = PROXY_PATHS.some(prefix =>
      path === prefix || path.startsWith(prefix.endsWith("/") ? prefix : prefix + "/")
    );

    if (!shouldProxy) {
      return fetch(request);
    }

    // Rewrite the request to Jamdesk
    const proxyUrl = new URL(request.url);
    proxyUrl.hostname = JAMDESK_HOST;

    // 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");
    // Required for domain verification
    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, "500-599": 0 },
      },
    });
  },
};

Remplacez YOUR_SLUG par votre sous-domaine Jamdesk réel (ex. : acme si vos docs sont à acme.jamdesk.app).

L'en-tête X-Jamdesk-Forwarded-Host est obligatoire. Il permet :

La vérification du domaine (votre domaine doit être enregistré dans le dashboard)
La génération correcte des URL pour les liens et les ressources
La configuration adéquate depuis les paramètres de votre dashboard

Sans cet en-tête, les requêtes seront rejetées avec une erreur 403.

Étape 3 : Configurer wrangler.toml

Créez wrangler.toml pour configurer votre Worker :

wrangler.toml

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

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

Si votre site sert également du trafic sur www.yoursite.com, ajoutez une seconde route afin que le Worker gère les deux :

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

Étape 4 : Déployer

Déployez votre Worker sur Cloudflare :

npx wrangler deploy

Étape 5 : Vérifier

Visitez https://yoursite.com/docs pour confirmer que votre documentation est correctement servie.

Alternative : syntaxe Service Worker

Si vous préférez l'ancienne syntaxe Service Worker (compatible avec les Workers plus anciens) :

index.js

const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

// Paths to proxy to Jamdesk
const PROXY_PATHS = [
  "/docs",    // Documentation pages
  "/_next/",  // Next.js static assets
  "/_jd/",    // Jamdesk assets (fonts, images, branding, analytics)
];

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const url = new URL(request.url);
  const path = url.pathname;

  // Check if this path should be proxied
  const shouldProxy = PROXY_PATHS.some(prefix =>
    path === prefix || path.startsWith(prefix.endsWith("/") ? prefix : prefix + "/")
  );

  if (!shouldProxy) {
    return fetch(request);
  }

  const proxyUrl = new URL(request.url);
  proxyUrl.hostname = JAMDESK_HOST;

  const headers = new Headers(request.headers);
  headers.set("Host", JAMDESK_HOST);
  headers.set("X-Forwarded-Host", url.hostname);
  headers.set("X-Forwarded-Proto", "https");
  // Required for domain verification
  headers.set("X-Jamdesk-Forwarded-Host", url.hostname);

  // Don't follow redirects — let the browser handle them so the URL updates
  return fetch(new Request(proxyUrl, {
    method: request.method,
    headers,
    body: request.body,
    redirect: "manual",
  }), {
    cf: {
      cacheEverything: true,
      cacheTtlByStatus: { "300-399": 0, "500-599": 0 },
    },
  });
}

Dépannage

Le CLI affiche vos domaines disponibles avant la sélection de zone. Si vous voyez "No domains found" :

Vérifiez que vous êtes connecté au bon compte Cloudflare
Vérifiez que votre domaine est ajouté et actif dans le dashboard Cloudflare
Relancez le CLI et sélectionnez "No" lorsqu'on vous demande de continuer avec le compte actuel pour changer de compte

Si vous avez plusieurs comptes Cloudflare :

Exécutez jamdesk deploy cloudflare
Lorsqu'on vous invite à sélectionner un compte, choisissez celui qui possède votre domaine
Si vous avez besoin d'une connexion entièrement différente, sélectionnez "Switch to different login"
Le CLI vous déconnectera et vous invitera à vous connecter avec les identifiants corrects

Cette erreur signifie que la zone sélectionnée ne correspond pas à votre compte Cloudflare. Soit :

Vous avez sélectionné une zone appartenant à un autre compte
La zone a été supprimée de Cloudflare

Correction : Relancez le CLI et sélectionnez la zone correcte dans la liste, ou basculez vers le compte propriétaire de la zone.

Assurez-vous que votre pattern de route utilise un catch-all : yoursite.com/* (et non pas seulement yoursite.com/docs*). La fonction interne shouldProxy() du Worker gère le filtrage des chemins.

Deux causes courantes :

Worker non actif. Assurez-vous que votre enregistrement DNS est défini sur Proxied (nuage orange) dans Cloudflare. Les Workers ne s'exécutent que sur les enregistrements proxifiés.
En-tête X-Forwarded-Host manquant. Le Worker doit définir cet en-tête pour que Jamdesk génère des URL de ressources correctes.

Si vous voyez "Domain is not authorized to serve this content" :

Vérifiez que votre domaine est enregistré dans le dashboard Jamdesk
Complétez la vérification DNS (enregistrement TXT) pour votre domaine
Assurez-vous que l'en-tête X-Jamdesk-Forwarded-Host est défini dans le code de votre Worker
Vérifiez que votre domaine est associé au bon projet

Le domaine doit être vérifié avant que le Worker puisse servir la documentation.

Les Workers ne s'exécutent que sur les enregistrements DNS proxifiés (nuage orange). Si votre enregistrement A est défini sur "DNS only" (nuage gris), les requêtes vont directement à l'origine et contournent entièrement le Worker.

Correction : Basculez l'enregistrement A en proxifié (nuage orange) dans Cloudflare DNS. Même chose pour les sous-domaines : tout enregistrement avec une route Worker doit être proxifié.

Jamdesk vérifie la propriété en lisant directement les valeurs de vos enregistrements DNS. Le proxy Cloudflare (nuage orange) masque ces valeurs, ce qui empêche la vérification de se terminer.

Correction :

Définissez l'enregistrement DNS sur DNS only (nuage gris)
Attendez que la vérification soit complète (le statut passe à active dans le dashboard)
Rebasculez sur Proxied (nuage orange) pour que le Worker s'exécute

En résumé : nuage gris pour vérifier → nuage orange pour servir.

Le Worker active le cache edge Cloudflare pour tous les types de contenu, y compris le HTML. La durée du cache est contrôlée par les en-têtes de réponse en amont : le HTML est mis en cache pendant 5 minutes, tandis que les ressources statiques comme les images et les polices sont mises en cache beaucoup plus longtemps.

Après un déploiement, le contenu mis à jour apparaîtra dans les 5 minutes sans aucune action requise. Si vous avez besoin de forcer une actualisation immédiate, utilisez la fonctionnalité Purge Cache de Cloudflare dans votre dashboard (Caching → Configuration → Purge Everything).

Le CLI requiert wrangler 3.0+. Mettez à jour avec :

npm install -g wrangler@latest

Et ensuite ?

Vue d'ensemble du déploiement

Comparer les options d'hébergement

Hébergement en sous-chemin

Servir les docs à /docs

Domaines personnalisés

Vérifier DNS et résoudre les problèmes