Implantar no Cloudflare

O Cloudflare Workers oferece um runtime rápido e distribuído globalmente para o EmDash. Este guia cobre a implantação com D1 como base de dados e R2 para armazenamento de media.

Pré-requisitos

• Uma conta Cloudflare
• Wrangler CLI instalado (npm install -g wrangler)
• Autenticado na Cloudflare (wrangler login)

Criar recursos

1. Criar uma base de dados D1

wrangler d1 create emdash-db

Anote o database_id na saída.

2. Criar um bucket R2

wrangler r2 bucket create emdash-media

3. Criar wrangler.jsonc

Crie wrangler.jsonc na raiz do projeto:

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-emdash-site",
	"compatibility_date": "2025-01-15",
	"compatibility_flags": ["nodejs_compat"],

	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "emdash-db",
			"database_id": "your-database-id",
		},
	],

	"r2_buckets": [
		{
			"binding": "MEDIA",
			"bucket_name": "emdash-media",
		},
	],
}

Configurar o EmDash

Atualize a configuração do Astro para usar D1 e R2:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

Executar migrações

Gere e aplique o esquema da base de dados.

1. Exportar o SQL do esquema

npx emdash init --database ./data.db

2. Aplicar migrações ao D1

wrangler d1 migrations apply emdash-db

Sem ficheiros de migração, aplique o esquema principal diretamente:

wrangler d1 execute emdash-db --file=./node_modules/emdash/migrations/0001_core.sql

Implantar

Implante no Cloudflare Workers:

wrangler deploy

O site fica disponível em https://my-emdash-site.<your-subdomain>.workers.dev.

Réplicas de leitura

Para sites distribuídos globalmente, ative a replicação de leitura do D1 para encaminhar consultas de leitura a réplicas próximas em vez de sempre ao primário. Reduz bastante a latência para visitantes longe da região primária.

emdash({
	database: d1({
		binding: "DB",
		session: "auto",
	}),
	storage: r2({ binding: "MEDIA" }),
}),

Também precisa ativar a replicação de leitura na própria base D1 no painel Cloudflare ou via API REST.

Consulte Opções de base de dados — Réplicas de leitura para modos de sessão e consistência baseada em marcadores.

Domínio personalizado

Adicione um domínio personalizado no painel Cloudflare:

1. Vá a Workers & Pages > o seu worker
2. Clique Custom Domains > Add Custom Domain
3. Introduza o domínio e siga as instruções DNS

Acesso público ao R2

Para servir media diretamente do R2 (recomendado para desempenho):

1. No painel Cloudflare, R2 > o seu bucket
2. Settings > Public access
3. Ative o acesso público e anote o URL público
4. Atualize a configuração de armazenamento:

storage: r2({
  binding: "MEDIA",
  publicUrl: "https://pub-xxx.r2.dev"
}),

Autenticação Cloudflare Access

Se a sua organização usa Cloudflare Access, pode usá-lo como fornecedor de autenticação em vez de passkeys. Oferece SSO com o seu IdP existente.

emdash({
  database: d1({ binding: "DB" }),
  storage: r2({ binding: "MEDIA" }),
  auth: access({
    teamDomain: "myteam.cloudflareaccess.com",
    audience: "your-app-audience-tag",
    roleMapping: {
      "Admins": 50,
      "Editors": 40,
    },
  }),
}),

Veja o guia de autenticação para todas as opções.

Variáveis de ambiente

O EmDash requer certos segredos para autenticação e pré-visualização.

Segredos obrigatórios

Gere segredos seguros:

npx emdash auth secret

Defina segredos com Wrangler:

wrangler secret put EMDASH_AUTH_SECRET
wrangler secret put EMDASH_PREVIEW_SECRET

Aceda às variáveis na configuração com import.meta.env ou o binding env da Cloudflare.

Implementações de pré-visualização

Implante um ramo de pré-visualização:

wrangler deploy --env preview

Adicione uma secção de ambiente a wrangler.jsonc:

{
	"env": {
		"preview": {
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "emdash-db-preview",
					"database_id": "your-preview-db-id",
				},
			],
		},
	},
}

Resolução de problemas

«D1 binding not found»

Verifique se o nome do binding em wrangler.jsonc corresponde à configuração da base de dados:

// Deve corresponder: d1({ binding: "DB" })
"binding": "DB"

«R2 binding not found»

Confirme que o bucket R2 está corretamente ligado:

// Deve corresponder: r2({ binding: "MEDIA" })
"binding": "MEDIA"

Erros de migração

As migrações D1 correm via Wrangler, não em tempo de execução. Se vir erros de esquema:

1. Verifique se as migrações foram aplicadas: wrangler d1 migrations list emdash-db
2. Reaplique se necessário: wrangler d1 migrations apply emdash-db