Auf Cloudflare bereitstellen

Cloudflare Workers bietet eine schnelle, global verteilte Laufzeitumgebung für EmDash. Diese Anleitung zeigt, wie Sie EmDash mit D1 als Datenbank und R2 für die Medienspeicherung bereitstellen.

Voraussetzungen

Ein Cloudflare-Konto
Installierte Wrangler CLI (npm install -g wrangler)
Bei Cloudflare authentifiziert (wrangler login)

Ressourcen erstellen

1. Eine D1-Datenbank erstellen

wrangler d1 create emdash-db

Notieren Sie sich die database_id aus der Ausgabe.

2. Einen R2-Bucket erstellen

wrangler r2 bucket create emdash-media

3. `wrangler.jsonc` erstellen

Erstellen Sie wrangler.jsonc im Stammverzeichnis Ihres Projekts:

{
  "$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, um D1 und R2 zu verwenden:

js title="astro.config.mjs"
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

Generieren und wenden Sie das Datenbankschema an.

1. Das 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 bereitstellen:

wrangler deploy

Ihre Seite ist jetzt live unter https://my-emdash-site.<your-subdomain>.workers.dev.

Lesereplikate

Für global verteilte Seiten aktivieren Sie die D1-Lesereplikation, um Leseanfragen an nahegelegene Replikate zu leiten, anstatt immer die primäre Datenbank zu belasten. Dies reduziert die Latenz für Besucher, die weit von der primären Region entfernt sind, erheblich.

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

Sie müssen die Lesereplikation auch in der D1-Datenbank selbst im Cloudflare-Dashboard oder über die REST-API aktivieren.

Siehe Datenbankoptionen — Read Replicas für Sitzungsmodi und die Funktionsweise der lesezeichenbasierten Konsistenz.

Benutzerdefinierte Domain

Fügen Sie eine benutzerdefinierte Domain im Cloudflare-Dashboard hinzu:

Gehen Sie zu Workers & Pages > Ihren Worker
Klicken Sie auf Custom Domains > Add Custom Domain
Geben Sie Ihre Domain ein und folgen Sie den DNS-Einrichtungsanweisungen

Öffentlicher R2-Zugriff

Um Medien direkt von R2 bereitzustellen (empfohlen für die Leistung):

Gehen Sie im Cloudflare-Dashboard zu R2 > Ihren Bucket
Klicken Sie auf Settings > Public access
Aktivieren Sie den öffentlichen Zugriff und notieren Sie die öffentliche URL
Aktualisieren Sie Ihre Speicherkonfiguration:

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

Cloudflare Access-Authentifizierung

Wenn Ihre Organisation Cloudflare Access verwendet, können Sie es anstelle von Passkeys als Ihren Authentifizierungsanbieter nutzen. Dies bietet SSO mit Ihrem bestehenden Identitätsanbieter.

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 Authentifizierungsleitfaden für alle Konfigurationsoptionen.

Umgebungsvariablen

EmDash benötigt bestimmte Secrets für die Authentifizierung und Vorschaufunktionalität.

Erforderliche Secrets

Variable	Zweck
`EMDASH_AUTH_SECRET`	Signiert Sitzungs-Cookies und Authentifizierungs-Tokens. Erforderlich für die Produktion.
`EMDASH_PREVIEW_SECRET`	Signiert Vorschau-URLs für Entwurfsinhalte. Erforderlich für die Vorschaufunktionalität.

Generieren Sie sichere Secrets:

npx emdash auth secret

Setzen Sie Secrets über Wrangler:

wrangler secret put EMDASH_AUTH_SECRET
wrangler secret put EMDASH_PREVIEW_SECRET

Greifen Sie in Ihrer Konfiguration über import.meta.env oder die Cloudflare env-Bindung auf Umgebungsvariablen zu.

Vorschau-Bereitstellungen

Stellen Sie einen Vorschau-Branch bereit:

wrangler deploy --env preview

Fügen Sie einen Environment-Abschnitt zu wrangler.jsonc hinzu:

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

Fehlerbehebung

”D1-Binding nicht gefunden”

Überprüfen Sie, ob der Bindungsname in wrangler.jsonc mit Ihrer Datenbankkonfiguration übereinstimmt:

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

“R2-Binding nicht gefunden”

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

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

Migrationsfehler

D1-Migrationen werden über Wrangler ausgeführt, nicht zur Laufzeit. Wenn Sie Schemafehler sehen:

Überprüfen Sie, ob Migrationen angewendet wurden: wrangler d1 migrations list emdash-db
Wenden Sie sie bei Bedarf erneut an: wrangler d1 migrations apply emdash-db