Insights / Artigos técnicos
Como adicionar comentários a um blog Astro usando apenas Cloudflare
Como implementamos comentários em um blog Astro sem serviço externo, usando Cloudflare Pages Functions, D1, Turnstile e configuração Wrangler.
Comentários adicionam estado a um site estático. Por isso, muita gente usa widgets externos.
No Acecore, escolhemos outro caminho: em PR #101, implementamos a função apenas com Cloudflare.
- Astro renderiza a interface.
- Cloudflare Pages Functions expõe
/api/comments. - Cloudflare D1 armazena comentários.
- Cloudflare Turnstile protege o envio.
wrangler.jsoncdefine o bindingCOMMENTS_DB.
O ponto principal é que a área de comentários não vira uma dependência externa dentro da página.
Arquitetura
| Camada | Arquivo ou serviço |
|---|---|
| UI | src/components/BlogComments.astro |
| Artigo | src/views/BlogPostPage.astro |
| API | functions/api/comments.ts |
| Banco | D1 binding COMMENTS_DB |
| Proteção | Cloudflare Turnstile |
| Schema | migrations/0001_create_blog_comments.sql |
A UI lê com GET /api/comments?slug=...&locale=... e envia com POST /api/comments.
A Function valida origin, payload, Turnstile, limites, duplicados e conteúdo bloqueado antes de inserir.
Por que D1
Comentários precisam de consultas por artigo, ordenação por data, soft delete, duplicidade e rate limit por cliente. SQL deixa isso simples.
Os comentários visíveis são deleted_at IS NULL. Para ocultar spam, basta preencher deleted_at, sem apagar fisicamente a linha.
As queries usam prepared statements com bind(), evitando concatenar input de usuário no SQL.
Wrangler e ambientes
COMMENTS_DB fica em wrangler.jsonc e aponta para o único banco D1 acecore-comments.
Assim o nome do binding continua estável, enquanto o dashboard da Cloudflare e o repositório usam o mesmo nome de banco.
Turnstile no servidor
O widget no browser não é suficiente. A Function envia o token para o Cloudflare Siteverify usando TURNSTILE_SECRET_KEY.
Também validamos o hostname retornado, para aceitar apenas domínios esperados e previews autorizadas.
Anti-spam
A primeira versão é restrita:
- sem URLs
- sem emails
- sem HTML
- sem links Markdown
- sem caracteres repetidos em excesso
- sem termos promocionais comuns
- honeypot no formulário
Também há rate limit em memória e rate limit persistente em D1 com client_hash. O hash usa salt; o IP bruto não precisa ser armazenado.
SEO
Comentários são carregados no cliente e a área usa data-pagefind-ignore. Eles não entram no índice como conteúdo principal.
Para um blog corporativo, isso separa conteúdo editorial revisado de interação dos visitantes.
Resumo
Serviços externos de comentários são úteis, mas não obrigatórios.
Se o site já roda em Cloudflare Pages, Pages Functions + D1 + Turnstile + Wrangler formam uma base suficiente para comentários leves, com UI, dados e segurança sob o mesmo modelo operacional.
Referências
Cloudflare Comments
Arquitetura de comentários criada somente com Cloudflare
O Astro renderiza a interface, o Cloudflare Pages Functions forma o limite da API, e D1 e Turnstile são conectados como componentes do Cloudflare.
Colocar a interface no Astro
Posicionar a lista de comentários, o formulário de envio e o widget do Turnstile abaixo do artigo.
Receber em uma Pages Function
`/api/comments` processa GET/POST/OPTIONS e cuida da validação de entrada e do CORS.
Salvar no D1
Usar o binding `COMMENTS_DB` para armazenar comentários, hash e data de criação no D1 compatível com SQLite.
Proteger com Turnstile
Validar o token do Cloudflare Turnstile no servidor e conferir a allowlist de hostname.
Diferenças entre um serviço externo de comentários e uma implementação própria no Cloudflare
Serviço externo de comentários
- A adoção é rápida, mas interface, armazenamento, termos e velocidade ficam a cargo do serviço
- Scripts e iframes externos podem afetar facilmente o carregamento dos artigos
- A interface multilíngue e a unidade com o design do site tendem a sofrer restrições
- Tratamento, exclusão e migração dos comentários dependem da especificação do serviço
Implementação somente com Cloudflare
- Pages Functions, D1 e Turnstile oferecem tanto a API quanto o armazenamento
- HTML e CSS do Astro podem se integrar naturalmente ao design do site
- A configuração do Wrangler alinha o binding D1 ao nome do banco no Cloudflare
- A equipe decide as medidas contra spam, a exclusão e o escopo dos dados pessoais armazenados
Decisões antes da implementação
- Manter os comentários na arquitetura Cloudflare do próprio site, sem confiá-los a um serviço externo
- Usar D1 como armazenamento e Cloudflare Pages Functions como limite da API
- Sempre validar os tokens do Turnstile no servidor
- Rejeitar URLs, e-mails, HTML, links Markdown e expressões promocionais antes do envio
- Alinhar o nome do banco D1 e o binding COMMENTS_DB com a configuração no Cloudflare
Páginas relacionadas
Perguntas frequentes
Por que não usar comentários externos?
Serviços externos são rápidos, mas UI, dados, scripts, moderação e migração ficam dependentes deles. Aqui tudo fica no site e no Cloudflare.
D1 é suficiente?
Para comentários por post_slug, ordenação por data, soft delete, rate limit e duplicados, D1 funciona bem.
Turnstile só no cliente basta?
Não. A Pages Function precisa validar o token no Siteverify antes de gravar no D1.