### Proxies avec des déploiements Vercel [#proxies-avec-des-déploiements-vercel]
Si vous utilisez Cloudflare comme proxy avec des déploiements Vercel, vous devez veiller à une configuration correcte pour éviter les conflits avec la vérification du domain de Vercel et l’émission des certificats SSL.
Une mauvaise configuration du proxy peut empêcher Vercel d’émettre des certificats SSL Let's Encrypt et entraîner des échecs de vérification du domain.
.mintlify.site`, comme illustré dans le script d’exemple, plutôt que de transmettre l’en-tête `Host` de la requête d’origine. Des en-têtes `Host` incorrects entraînent l’échec des requêtes de vérification.
### Configurer le routage [#configurer-le-routage]
Dans votre Dashboard Cloudflare, sélectionnez **Edit Code** et ajoutez le script depuis votre page [Configuration du domaine personnalisé](https://app.mintlify.com/settings/deployment/custom-domain), dans laquelle vos valeurs sont déjà renseignées, ou copiez le script d’exemple suivant. Consultez la [documentation Cloudflare](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) pour plus d'informations sur la modification d'un Worker.
Remplacez `[SUBDOMAIN]` par votre sous-domaine unique, `[YOUR_DOMAIN]` par l'URL de base de votre site, et `/docs` par le sous-chemin souhaité, s'il est différent.
```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// Si la requête concerne un chemin de vérification Vercel, la laisser passer
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// Si la requête concerne le sous-chemin docs, une ressource Mintlify ou un chemin d'API
if (
/^\/docs/.test(urlObject.pathname) ||
/^\/mintlify-assets\//.test(urlObject.pathname) ||
/^\/_mintlify\//.test(urlObject.pathname)
) {
// Alors rediriger via proxy vers Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// Si déploiement sur Vercel, conserver l'IP du client
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
} catch (error) {
// Si aucune action trouvée, exécuter la requête normale
return await fetch(request);
}
}
```
En plus de votre sous-chemin, votre Worker doit proxyfier `/mintlify-assets/*`, qui sert le CSS, le JavaScript et les favicons de votre documentation, ainsi que `/_mintlify/*`, qui gère les requêtes du playground d'API.
Si vous routez le trafic vers votre Worker avec des modèles de route au lieu d'un domaine personnalisé, ajoutez des routes pour `yoursite.com/mintlify-assets/*` et `yoursite.com/_mintlify/*` en plus de la route de votre sous-chemin. Ces chemins doivent partir de la racine de votre domaine, pas de votre sous-chemin.
Le script d'exemple ne proxyfie que le trafic de la documentation. Si vous ajoutez le Worker comme domaine personnalisé, les requêtes en dehors de votre sous-chemin, `/mintlify-assets/*`, `/_mintlify/*` et `/.well-known/*` ne sont pas gérées. Si votre site principal est servi sur le même domaine, limitez le Worker aux chemins de la documentation avec des modèles de route ou routez tout le reste du trafic vers votre site principal comme indiqué dans [Routage personnalisé avec Webflow](#webflow-custom-routing).
Cliquez sur **Deploy** et attendez que les modifications se propagent.
Après avoir déployé vos modifications, votre documentation est généralement accessible à votre sous-chemin en quelques minutes. Si votre configuration inclut des changements DNS, la propagation peut prendre de 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre documentation n’est pas immédiatement accessible, patientez avant d’essayer de résoudre le problème.
### Testez votre Worker [#testez-votre-worker]
Après le déploiement de votre code, testez votre Worker pour vérifier qu’il redirige vers votre documentation Mintlify.
1. Testez en utilisant l’URL d’aperçu du Worker : `your-worker.your-subdomain.workers.dev/docs`
2. Vérifiez que le Worker redirige vers votre documentation Mintlify et votre site web.
### Ajouter un domaine personnalisé [#ajouter-un-domaine-personnalisé]
1. Dans votre [Dashboard Cloudflare](https://dash.cloudflare.com/), accédez à votre Worker.
2. Allez dans **Settings > Domains & Routes > Add > Custom Domain**.
3. Ajoutez votre domaine.
Ajoutez votre domaine avec et sans le préfixe `www.`.
Consultez [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) dans la documentation Cloudflare pour en savoir plus.
### Résoudre les conflits DNS [#résoudre-les-conflits-dns]
Si votre domaine pointe déjà vers un autre service, vous devez supprimer l’enregistrement DNS existant. Votre Cloudflare Worker doit être configuré pour gérer l’ensemble du trafic de votre domaine.
1. Supprimez l’enregistrement DNS existant pour votre domaine. Consultez la section [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) de la documentation Cloudflare pour plus d’informations.
2. Retournez à votre Worker et ajoutez votre domaine personnalisé.
## Routage personnalisé avec Webflow [#routage-personnalisé-avec-webflow]
Si vous utilisez Webflow pour héberger votre site principal et que vous souhaitez servir la documentation Mintlify à `/docs` sur le même domaine, vous devrez configurer un routage personnalisé via Cloudflare Workers pour faire transiter (proxy) tout le trafic non lié à la documentation vers votre site principal.
Configurez votre site principal sur une page d’atterrissage avant de déployer ce Worker, sinon les visiteurs de votre site principal pourraient voir des erreurs.
1. Dans Webflow, configurez une page d’atterrissage pour votre site principal, par exemple `landing.yoursite.com`. C’est la page que les visiteurs voient lorsqu’ils visitent votre site.
2. Déployez votre site principal sur la page d’atterrissage. Cela garantit que votre site principal reste accessible pendant que vous configurez le Worker.
3. Pour éviter les conflits, mettez à jour toutes les URL absolues de votre site principal pour qu’elles soient relatives.
4. Dans Cloudflare, sélectionnez **Edit Code** et ajoutez le script suivant dans le code de votre Worker.
Remplacez
`[SUBDOMAIN]`
par votre sous-domaine unique,
`[YOUR_DOMAIN]`
par l’URL de base de votre site web,
`[LANDING_DOMAIN]`
par l’URL de votre page d’atterrissage, et
`/docs`
par le sous-chemin souhaité si différent.
```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// Si la requête concerne un chemin de vérification Vercel, la laisser passer
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// Si la requête concerne le sous-chemin docs, une ressource Mintlify ou un chemin d'API
if (
/^\/docs/.test(urlObject.pathname) ||
/^\/mintlify-assets\//.test(urlObject.pathname) ||
/^\/_mintlify\//.test(urlObject.pathname)
) {
// Proxy vers Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// En cas de déploiement sur Vercel, préserver l'IP du client
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
// Rediriger tout le reste vers le site principal
const MAIN_SITE_URL = "[LANDING_DOMAIN]";
if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") {
let mainSiteUrl = new URL(request.url);
mainSiteUrl.hostname = MAIN_SITE_URL;
return await fetch(mainSiteUrl, {
method: request.method,
headers: request.headers,
body: request.body
});
}
} catch (error) {
// Si aucune action n'est trouvée, servir la requête normale
return await fetch(request);
}
}
```
5. Sélectionnez **Deploy** et attendez que les modifications se propagent.
Après avoir déployé vos modifications, votre documentation est généralement accessible à votre sous-chemin en quelques minutes. Si votre configuration inclut des changements DNS, la propagation peut prendre de 1 à 4 heures, et dans de rares cas jusqu’à 48 heures. Si votre documentation n’est pas immédiatement accessible, patientez avant d’essayer de résoudre le problème.
## Dépanner le blocage par le pare-feu [#dépanner-le-blocage-par-le-pare-feu]
Si votre site de documentation affiche des erreurs 500 après quelques secondes ou rencontre une navigation lente, le pare-feu de Cloudflare bloque peut-être les requêtes vers les ressources Mintlify.
### Symptômes [#symptômes]
* La page de documentation se charge d'abord, puis plante avec une erreur 500 au bout de 30 à 60 secondes.
* Navigation côté client lente ou défaillante entre les pages.
* Erreurs 403 dans la console du navigateur pour les requêtes vers les chemins `/mintlify-assets/*`.
* Messages de sécurité Cloudflare évoquant des « données malformées » ou des « modèles d'URL suspects ».
### Cause racine [#cause-racine]
Le pare-feu d'applications web (WAF) de Cloudflare et le Bot Fight Mode peuvent considérer les requêtes de ressources Mintlify comme suspectes en raison de :
* La présence de plusieurs symboles `%` dans les paramètres d'URL encodés.
* De longues chaînes de requête avec des caractères spéciaux.
* Des requêtes automatisées provenant d'onglets inactifs.
### Solution [#solution]
Créez une règle de pare-feu Cloudflare pour exclure les ressources Mintlify des contrôles de sécurité.
#### Créer l'exception de pare-feu [#créer-lexception-de-pare-feu]
1. Connectez-vous à votre [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Sélectionnez votre domaine.
3. Accédez à **Security > WAF**.
4. Cliquez sur **Create rule**.
5. Configurez la règle avec ces paramètres :
**Nom de la règle :** Autoriser les ressources Mintlify
**Lorsque les requêtes entrantes correspondent :**
* Field: `Hostname`
* Operator: `equals`
* Value: `docs.yourdomain.com` (remplacez par le domaine réel de votre documentation)
**Et :**
* Field: `URI Path`
* Operator: `starts with`
* Value: `/mintlify-assets/`
**Alors :**
* Action: `Skip`
* Select: `All remaining custom rules`, `Managed rules`, and `Super Bot Fight Mode`
6. Activez **Log** pour suivre les requêtes correspondantes.
7. Cliquez sur **Deploy**.
#### Vérifier la règle [#vérifier-la-règle]
Après le déploiement :
1. Ouvrez votre site de documentation dans un navigateur.
2. Laissez la page inactive pendant 2 à 3 minutes.
3. Naviguez entre les pages.
4. Vérifiez la console du navigateur pour voir s'il y a des erreurs 403.
Si les problèmes persistent, vérifiez la configuration de votre règle :
* Assurez-vous que le nom d'hôte correspond exactement à votre domaine de documentation.
* Confirmez que le chemin URI utilise « starts with » (et non « contains »).
* N'incluez pas de caractères génériques (`*`) dans la valeur du chemin.
* Vérifiez que vous avez activé et déployé la règle.
### Erreurs courantes [#erreurs-courantes]
* Utiliser l'opérateur `contains` avec `/mintlify-assets/*`. Le `*` est interprété comme un caractère littéral, pas comme un caractère générique.
* Utiliser `equals` pour le chemin URI. Cela ne fait correspondre que le chemin exact `/mintlify-assets/` et non les sous-chemins.
* Oublier d'exclure le Bot Fight Mode. Incluez-le explicitement dans l'action d'exclusion.
* Définir un nom d'hôte incorrect. Il doit correspondre à votre domaine de documentation réel.
### Résolution de problèmes supplémentaire [#résolution-de-problèmes-supplémentaire]
Si l'exception du pare-feu ne résout pas le problème :
1. Consultez le journal **Security > Events** de Cloudflare pour identifier les requêtes bloquées.
2. Vérifiez que votre Cloudflare Worker (si vous utilisez un sous-chemin personnalisé) définit l'en-tête `Host` sur votre cible `.mintlify.site` au lieu de transmettre l'en-tête `Host` de la requête d'origine.
3. Réglez temporairement le niveau de sécurité sur « Essentially Off » pour confirmer que Cloudflare est bien en cause.
4. Vérifiez d'éventuelles Page Rules personnalisées susceptibles d'outrepasser l'exception du pare-feu.
### Exemple de configuration fonctionnelle [#exemple-de-configuration-fonctionnelle]
```
Rule: Allow Mintlify assets
Status: Enabled
When incoming requests match:
(http.host eq "docs.yourdomain.com" and starts_with(http.request.uri.path, "/mintlify-assets/"))
Then:
Skip: All remaining custom rules, Managed rules, Super Bot Fight Mode
Log: Enabled
```