Auf Cloudflare bereitstellen

Cloudflare Workers bietet eine schnelle, global verteilte Laufzeitumgebung für EmDash. Diese Anleitung beschreibt die Bereitstellung mit D1 als Datenbank und R2 für Medienspeicher.

Voraussetzungen

• Ein Cloudflare-Konto
• Wrangler CLI installiert (npm install -g wrangler)
• Bei Cloudflare angemeldet (wrangler login)

Ressourcen anlegen

1. D1-Datenbank erstellen

wrangler d1 create emdash-db

Notieren Sie die database_id aus der Ausgabe.

2. R2-Bucket erstellen

wrangler r2 bucket create emdash-media

3. wrangler.jsonc erstellen

Legen Sie wrangler.jsonc im Projektstamm an:

{
	"$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",
		},
	],
}

EmDash konfigurieren

Aktualisieren Sie Ihre Astro-Konfiguration für D1 und 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" }),
		}),
	],
});

Migrationen ausführen

Datenbankschema erzeugen und anwenden.

1. Schema-SQL exportieren

npx emdash init --database ./data.db

2. Migrationen auf D1 anwenden

wrangler d1 migrations apply emdash-db

Wenn Sie keine Migrationsdateien haben, wenden Sie das Kernschema direkt an:

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

Bereitstellen

Auf Cloudflare Workers deployen:

wrangler deploy

Ihre Site ist nun unter https://my-emdash-site.<your-subdomain>.workers.dev erreichbar.

Read Replicas

Für global verteilte Sites aktivieren Sie D1 Read Replication, damit Leseanfragen an nahegelegene Replikas statt immer an die primäre Datenbank gehen. Das reduziert die Latenz für Besucher weit entfernt von der Primärregion deutlich.

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

Sie müssen Read Replication außerdem für die D1-Datenbank selbst im Cloudflare-Dashboard oder per REST-API aktivieren.

Siehe Datenbankoptionen — Read Replicas zu Sitzungsmodi und Lesezeichen-basierter Konsistenz.

Eigene Domain

Eigene Domain im Cloudflare-Dashboard hinzufügen:

1. Workers & Pages öffnen > Ihren Worker wählen
2. Custom Domains > Add Custom Domain
3. Domain eingeben und den DNS-Anweisungen folgen

Öffentlicher R2-Zugriff

Um Medien direkt aus R2 auszuliefern (empfohlen für die Performance):

1. Im Cloudflare-Dashboard zu R2 > Ihrem Bucket
2. Settings > Public access
3. Öffentlichen Zugriff aktivieren und die öffentliche URL notieren
4. Speicherkonfiguration aktualisieren:

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

Cloudflare Access Authentication

Wenn Ihre Organisation Cloudflare Access nutzt, können Sie es statt Passkeys als Authentifizierungsanbieter verwenden. So erhalten Sie SSO mit Ihrem bestehenden Identity Provider.

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,
    },
  }),
}),

Siehe den Leitfaden zur Authentifizierung für alle Konfigurationsoptionen.

Umgebungsvariablen

EmDash benötigt bestimmte Secrets für Authentifizierung und Vorschau.

Erforderliche Secrets

Sichere Secrets erzeugen:

npx emdash auth secret

Secrets mit Wrangler setzen:

wrangler secret put EMDASH_AUTH_SECRET
wrangler secret put EMDASH_PREVIEW_SECRET

Auf Umgebungsvariablen in der Konfiguration mit import.meta.env oder der Cloudflare-env-Binding zugreifen.

Preview-Deployments

Preview-Branch bereitstellen:

wrangler deploy --env preview

Einen Umgebungsabschnitt in wrangler.jsonc hinzufügen:

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

Fehlerbehebung

„D1 binding not found“

Prüfen Sie, ob der Binding-Name in wrangler.jsonc zur Datenbankkonfiguration passt:

// Muss übereinstimmen: d1({ binding: "DB" })
"binding": "DB"

„R2 binding not found“

Prüfen Sie, ob der R2-Bucket korrekt gebunden ist:

// Muss übereinstimmen: r2({ binding: "MEDIA" })
"binding": "MEDIA"

Migrationsfehler

D1-Migrationen laufen über Wrangler, nicht zur Laufzeit. Bei Schemafehlern:

1. Prüfen, ob Migrationen angewendet wurden: wrangler d1 migrations list emdash-db
2. Bei Bedarf erneut anwenden: wrangler d1 migrations apply emdash-db