Sublink Cloudflare (n8n)

Node de comunidade para o n8n que gerencia links curtos armazenados no Cloudflare Workers KV via API REST. Ideal para automações que precisam criar, atualizar, consultar ou remover slugs sem sair do fluxo do n8n.

Nome no npm: n8n-nodes-sublink-cloudflare — o n8n só aceita community nodes cujo pacote começa com o prefixo n8n-nodes-.

Provisionamento automático (padrão): com Provisionar infra automaticamente ligado no node, na primeira execução do workflow o node pode: criar/usar o namespace KV sublink-n8n-kv (se o ID estiver vazio nas credenciais), publicar o Worker sublink-redirect-n8n, associar o hostname da Base da URL curta via API de Workers Domains e, quando necessário, criar/ajustar DNS e rota de Worker automaticamente. Ex.: go.seudominio.com.br. O domínio precisa estar na mesma conta Cloudflare.

Importante (segurança): quando a base for o domínio principal (apex), por exemplo https://seudominio.com.br, o node não faz vínculo automático de hostname/rota para evitar interceptar seu site principal. Nesse caso, a configuração de roteamento deve ser manual.

Modo manual: desligue o provisionamento e use a pasta worker/ / worker/README.md.

Requisitos

• n8n com suporte a Community Nodes (self-hosted ou conforme seu plano).
• Conta Cloudflare com:
  • Workers KV — um namespace dedicado aos slugs;
  • API Token com permissão adequada para esse namespace (leitura/escrita conforme o uso).

Instalação

Pelo painel do n8n

1. Abra Settings → Community nodes.
2. Em Install, informe exatamente: n8n-nodes-sublink-cloudflare (sem @versão na primeira tentativa, ou use a versão já publicada no npm).
3. Aceite os avisos de segurança e conclua a instalação.
4. Reinicie o n8n se a sua instalação exigir.

Por CLI (ambiente com acesso ao npm)

Na pasta de dados ou instalação onde o n8n resolve pacotes de comunidade (varia conforme deploy):

npm install n8n-nodes-sublink-cloudflare

Consulte a documentação oficial do n8n sobre community nodes para o seu cenário (Docker, npm global, etc.).

Credenciais e permissões do API Token

Crie uma credencial do tipo Cloudflare KV (encurtador) com um token que permita KV + publicar Workers + roteamento + DNS.

No painel de criação de token da Cloudflare, inclua no mínimo:

• Account permissions
  • Workers KV Storage: Edit
  • Workers Scripts: Edit
  • Workers Routes: Edit
• Zone permissions (na zona do seu domínio)
  • Zone: Read
  • DNS: Edit
  • Workers Routes: Edit (quando aplicável no modelo de permissões da sua conta)

Se sua conta/plano expuser permissões específicas de Workers Domains / Custom Domains, inclua também.

Preencha:

| Campo | Descrição | |--------|-----------| | API Token | Permissões de KV + Workers Scripts + domínios do Worker (ver texto acima). | | Account ID | ID da conta Cloudflare (painel → Workers / visão geral da conta). | | KV Namespace ID | Opcional. Vazio = o node usa/cria o namespace titulado sublink-n8n-kv (com provisionamento ligado). | | Base da URL curta | Ex.: https://go.seudominio.com.br (sem / no final). Monta short_url e, com provisionamento automático, registra esse hostname na Cloudflare. |

Use Test na credencial para validar o token (lista namespaces KV na conta).

Provisionamento automático: quando usar ligado ou desligado

Ligado (recomendado para primeira configuração)

Use ligado quando você quer que o node prepare quase tudo sozinho.

Casos comuns:

• primeiro setup do encurtador;
• novo ambiente (staging/prod);
• time sem rotina manual de Worker/DNS.

Com provisionamento ligado:

• em subdomínio (ex.: go.seudominio.com.br), o node tenta provisionar hostname/rota/DNS automaticamente;
• em domínio principal (ex.: seudominio.com.br), o node publica Worker/KV, mas não aplica vínculo automático de tráfego (passo manual obrigatório).

Desligado (modo manual/controlado)

Use desligado quando sua infraestrutura já está pronta ou quando você quer controle total.

Casos comuns:

• Worker já publicado por Wrangler/CI;
• DNS e rotas geridos por Terraform/IaC;
• ambientes com governança restrita de permissões.

Nesse modo, preencha o KV Namespace ID manualmente e mantenha Worker + rota/DNS fora do node.

Uso no domínio principal (manual obrigatório)

Se você quiser usar links curtos no domínio principal (apex), por segurança faça manualmente:

1. publique/atualize o Worker de redirect;
2. configure rota/custom domain de forma explícita no painel/infra;
3. valide que o seu site principal não será sobrescrito por uma rota /* indevida;
4. só depois execute o node para gravar e ler slugs no KV.

O que acontece por baixo dos panos (provisionamento ligado)

Ao executar o node com provisionamento ligado, ele segue este fluxo:

1. valida credenciais e resolve o Account ID;
2. obtém/cria o namespace KV sublink-n8n-kv (se KV Namespace ID estiver vazio);
3. publica/atualiza o Worker sublink-redirect-n8n com binding do KV;
4. resolve a zona do hostname (quando permitido pelo token);
5. se o hostname for domínio principal (apex), para por segurança após publicar Worker/KV e deixa roteamento manual;
6. para subdomínio, tenta associar o hostname via accounts/.../workers/domains;
7. se a API de domains não estiver disponível (ex.: HTTP 405), faz fallback automático:
   • resolve a zone do hostname;
   • para subdomínio, garante DNS proxied (A/AAAA/CNAME) e cria CNAME se necessário;
   • cria/atualiza rota hostname/* para o Worker em zones/.../workers/routes.

Esse fallback garante compatibilidade entre contas/planos da Cloudflare que respondem diferente para Workers Domains.

Operações do node

O node Cloudflare Link Shortener oferece:

| Operação | Uso | |----------|-----| | Criar | Define slug, URL de destino e se está ativo. | | Atualizar | Altera URL e/ou active; exige slug existente. | | Obter | Lê o registro de um slug. | | Excluir | Remove a chave do KV. | | Listar chaves | Lista slugs com paginação da API; opcionalmente busca os valores (mais requisições). |

Formato no KV (valor)

Cada chave é o slug; o valor é JSON compatível com um Worker de redirect, por exemplo:

{
  "url": "https://exemplo.com/caminho-longo",
  "active": true,
  "created_at": "2026-04-12T10:00:00.000Z",
  "updated_at": "2026-04-12T10:00:00.000Z",
  "clicks": 0
}

Ajuste o seu Worker para ler esse formato e responder 302/301 ou 404 quando active for false.

Desenvolvimento e publicação (mantenedores)

Repositório Git (código-fonte) costuma ficar na pasta do projeto, por exemplo sublink-cloudflare:

cd sublink-cloudflare
npm install
npm run build

• npm run build — compila TypeScript para compiled/ e copia sublink.svg para junto do .node.js.
• Antes de publicar no npm: npm version patch|minor|major e npm publish.

Pacote legado sublink-cloudflare no npm não é reconhecido pelo instalador de community nodes do n8n; use sempre n8n-nodes-sublink-cloudflare.

Repositório e licença

• Código e issues: github.com/hygorfragas/sublink-cloudflare
• Licença: MIT (veja o campo license no package.json).

Links úteis

• Cloudflare — Workers KV
• Cloudflare — API KV namespaces