Cloudflare Workers
Encaminhe requisições /docs por meio de um Cloudflare Worker até o seu site de documentação Jamdesk. Cobre configuração do Worker, padrões de rota e configuração de cache.
Um Cloudflare Worker intercepta requisições em /docs no seu domínio, reescreve-as para o seu subdomínio Jamdesk e devolve a resposta. Ele roda na borda, sem servidor de origem. Gere o Worker com npx jamdesk deploy-proxy cloudflare ou configure-o manualmente abaixo.
Como funciona
O Worker encaminha as requisições para o seu subdomínio Jamdesk. Ele passa o seu domínio no cabeçalho X-Jamdesk-Forwarded-Host. O Jamdesk lê esse cabeçalho para verificar o domínio e aplicar as suas configurações. É uma configuração única. Alterações posteriores no domínio ou na configuração no painel não exigem atualização do Worker.
Pré-requisitos
- Uma conta Cloudflare com o seu domínio configurado
- Wrangler CLI v3.0+ instalado
- O seu subdomínio Jamdesk (encontrado nas configurações do painel)
- Seu domínio personalizado adicionado ao projeto no painel Jamdesk (o Worker retorna 403 até que o domínio seja registrado e verificado)
- Um registro DNS com proxy (nuvem laranja) no hostname que serve a sua documentação. Workers só rodam em registros com proxy. Um domínio que não hospeda mais nada ainda precisa de um: adicione um registro
AAAAde placeholder apontando para100::e ative o proxy.
Configuração rápida com CLI
Configure o Worker com um único comando:
npx jamdesk deploy-proxy cloudflare
Este comando interativo:
- Verifica se o wrangler 3.0+ está instalado
- Verifica a sua conta Cloudflare e mostra os domínios disponíveis
- Resolve o seu subdomínio Jamdesk a partir do projeto vinculado em
docs.json - Permite selecionar o domínio de destino entre as suas zonas Cloudflare
- Gera todos os arquivos necessários
- Opcionalmente faz o deploy na Cloudflare
Com acesso a várias contas Cloudflare (comum em agências ou equipes), a CLI pede que você escolha uma conta antes da seleção de zona. Escolha a conta que possui o domínio para o qual você está fazendo o deploy. Rotas de Workers só podem ser criadas para domínios da conta selecionada.
Configuração não interativa
Passe as respostas como flags para executar sem prompts, em CI ou em um script:
jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes
--yes gera os arquivos do Worker e para. Nunca faz deploy. A zona é assumida a partir do seu domínio, não confirmada contra a sua conta Cloudflare. Colocar essa configuração no ar continua sendo uma etapa explícita. Finalize com:
cd cloudflare-worker
npx wrangler deploy
--yes não consegue pedir o seu subdomínio. A CLI o lê do projeto vinculado em docs.json. Se esse vínculo estiver ausente, passe --slug (ou execute jamdesk deploy uma vez para adicionar o vínculo). Caso contrário, o comando para em vez de adivinhar.
Se o diretório de saída já existir, --yes para em vez de substituí-lo. Adicione --force para sobrescrever, ou --output-dir para gravar em outro lugar.
| Opção | Descrição |
|---|---|
--slug | Seu subdomínio Jamdesk, o X em X.jamdesk.app (ignora a detecção automática) |
--domain | Domínio de destino (ex.: seusite.com) |
--path | Prefixo de caminho; deve corresponder exatamente ao subcaminho do seu painel (padrão: /docs) |
--output-dir | Diretório de saída (padrão: cloudflare-worker/) |
--skip-deploy | Pula o prompt "fazer deploy agora?" em uma execução interativa (--yes nunca faz deploy) |
--force | Sobrescreve o diretório de saída se ele já existir |
--yes | Responde a todos os prompts com o padrão (modo CI). Nunca faz deploy. Nunca sobrescreve um diretório existente, a menos que combinado com --force |
Ou siga os passos manuais abaixo.
Configuração manual
Etapa 1: criar um Worker
Crie um novo diretório para o seu Worker e inicialize-o:
mkdir docs-proxy && cd docs-proxy
npm init -y
Etapa 2: adicionar o código do Worker
Crie index.js com o seguinte código:
/**
* 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);
},
};Substitua YOUR_SLUG pelo seu subdomínio Jamdesk (ex.: acme se a sua documentação estiver em acme.jamdesk.app).
Se você usar um subcaminho personalizado do painel em vez do padrão /docs, substitua "/docs" pelo seu subcaminho em PROXY_PATHS e na verificação de correspondência exata dentro de shouldProxy(). A flag --path da CLI faz isso ao gerar o arquivo, mas somente sobre um template não modificado. Regenerar sobrescreve quaisquer entradas personalizadas que você tenha adicionado manualmente a PROXY_PATHS. Edite as entradas /docs diretamente se você tiver personalizado este Worker.
O cabeçalho X-Jamdesk-Forwarded-Host é obrigatório. A ausência dele falha silenciosamente. As requisições ainda têm sucesso, mas as páginas são servidas com noindex e links canônicos apontando para YOUR_SLUG.jamdesk.app em vez do seu domínio. Mecanismos de busca nunca indexam sua documentação. Um 403 é o problema oposto: o cabeçalho está presente, mas nomeia um domínio que não está registrado e ativo para este projeto.
Etapa 3: configurar wrangler.toml
Crie wrangler.toml para configurar o seu Worker:
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" },
]Se o seu login na Cloudflare tiver acesso a mais de uma conta, adicione também account_id = "<your account id>". Sem ele, wrangler deploy para em vez de adivinhar em qual conta fazer o deploy. npx wrangler whoami lista os IDs das suas contas.
Adicione uma segunda rota se o seu site também servir tráfego em www.yoursite.com:
routes = [
{ pattern = "yoursite.com/*", zone_name = "yoursite.com" },
{ pattern = "www.yoursite.com/*", zone_name = "yoursite.com" },
]Etapa 4: fazer deploy
Faça o deploy do seu Worker na Cloudflare:
npx wrangler deploy
Etapa 5: verificar
Acesse https://yoursite.com/docs e confirme que a sua documentação carrega.
Solução de problemas
Se você renomeou o seu subcaminho no painel (por exemplo, /docs → /help), mas o PROXY_PATHS do seu Worker ainda lista apenas /docs, as requisições para /help/* nunca chegam ao Jamdesk. Elas caem em fetch(request) e retornam 404 na sua própria origem. /docs/* continua funcionando nesse meio tempo (o Jamdesk serve ambos os prefixos). Isso torna o problema fácil de passar despercebido.
Correção: adicione o seu novo subcaminho a PROXY_PATHS. Execute novamente jamdesk deploy-proxy cloudflare --path <subpath> se o Worker ainda for um template não modificado. Edite o array manualmente se você o tiver personalizado.
O wrangler prefere CLOUDFLARE_API_TOKEN ao seu login OAuth. Ele não consegue iniciar um login OAuth enquanto esse token estiver definido. Este comando precisa de OAuth para listar as zonas da sua conta. Ele para e mostra a localização do token em vez de falhar dentro do wrangler.
O wrangler também lê o .env do diretório em que você executa. O token pode estar definido para o wrangler sem estar no seu shell. Um echo $CLOUDFLARE_API_TOKEN vazio não descarta isso. Verifique também se há um .env no diretório atual.
Correção: conceda ao token account:read e zone:read, depois execute novamente. Ou execute sem o token:
env -u CLOUDFLARE_API_TOKEN jamdesk deploy-proxy cloudflareenv -u não ajuda quando o token vem de um .env. Execute o comando a partir de um diretório sem esse .env, ou mova o arquivo temporariamente durante a execução.
A CLI mostra os seus domínios disponíveis antes da seleção de zona. Se você vir "No domains found":
- Verifique se você está logado na conta Cloudflare correta
- Verifique se o seu domínio está adicionado e ativo no painel da Cloudflare
- Execute a CLI novamente e selecione "No" quando perguntado se deseja continuar com a conta atual para trocar de conta
Se você tiver várias contas Cloudflare:
- Execute
jamdesk deploy-proxy cloudflare - Quando solicitado a selecionar uma conta, escolha aquela que possui o seu domínio
- Selecione "Switch to different login" para um login completamente diferente
- A CLI desconecta você e pede para fazer login com as credenciais corretas
Este erro significa que a zona selecionada não corresponde à sua conta Cloudflare. Possíveis causas:
- Você selecionou uma zona que pertence a outra conta
- A zona foi removida da Cloudflare
Correção: execute a CLI novamente e selecione a zona correta na lista, ou troque para a conta que possui a zona.
Use um padrão de rota catch-all: yoursite.com/* (não apenas yoursite.com/docs*). A função interna shouldProxy() do Worker filtra os caminhos.
Duas causas comuns:
- Worker não está em execução: defina o seu registro DNS como Proxied (nuvem laranja) na Cloudflare. Workers só rodam em registros com proxy.
- Cabeçalho
X-Forwarded-Hostausente: o Worker deve definir este cabeçalho. O Jamdesk precisa dele para gerar URLs corretas dos recursos.
Se você vir "Domain is not authorized to serve this content":
- Verifique se o seu domínio está registrado no painel Jamdesk
- Conclua a verificação de DNS (registro TXT) do seu domínio
- Defina o cabeçalho
X-Jamdesk-Forwarded-Hostno código do seu Worker - Verifique se o seu domínio está mapeado para o projeto correto
O domínio precisa estar verificado antes que o Worker possa servir a documentação.
Workers só rodam em registros DNS com proxy (nuvem laranja). Se o seu registro A estiver como "DNS only" (nuvem cinza), as requisições vão direto para a origem e ignoram o Worker.
Correção: altere o registro A para proxy (nuvem laranja) no DNS da Cloudflare. Qualquer registro com uma rota de Worker precisa estar com proxy, incluindo subdomínios.
O Jamdesk verifica a propriedade lendo diretamente os valores do seu registro DNS. O proxy da Cloudflare (nuvem laranja) mascara esses valores. A verificação não pode ser concluída enquanto ele estiver ativo.
Correção:
- Defina o registro DNS como DNS only (nuvem cinza)
- Aguarde a conclusão da verificação (o status muda para active no painel)
- Volte para Proxied (nuvem laranja) para que o Worker execute
O Jamdesk serve o HTML da documentação com Cache-Control: no-store. A Cloudflare não armazena as páginas na borda (cf-cache-status: BYPASS). Cada requisição renderiza a versão atual. As alterações publicadas aparecem sem atraso de cache.
Os recursos estáticos em /_next/ e /_jd/ (JavaScript, CSS, fontes, imagens) têm cabeçalhos de cache immutable de longa duração. A Cloudflare os armazena na borda. Seus nomes de arquivo têm hash de conteúdo. Cada build gera novas URLs. Nenhuma purga é necessária.
cacheEverything: true permite que a Cloudflare armazene esses recursos estáticos na rota com proxy. Isso não sobrescreve o no-store do HTML. Limpe o cache da borda manualmente com Purge Cache da Cloudflare (Caching → Configuration → Purge Everything).
A CLI exige wrangler 3.0+. Atualize com:
npm install -g wrangler@latest