Website-Übertragung

Ein Site-Paket ist eine portable Kopie des Inhaltsmodells, der Inhalte, des redaktionellen Verlaufs, der Website-Darstellung, der Einstellungen und der Mediendateien einer EmDash-Website. Importieren Sie ein Site-Paket, um eine Website in ein anderes EmDash-Deployment zu verschieben – auch in eines, das eine andere Datenbank verwendet: SQLite, PostgreSQL oder Cloudflare D1.

Ein Import schreibt in eine neue Website, deren Inhaltsbereich leer ist. EmDash prüft das gesamte Paket, bevor irgendetwas geschrieben wird, führt den Import in kleinen, fortsetzbaren Schritten aus, liest die importierte Website zurück und stellt eine Quittung aus, wenn das Ergebnis mit dem Paket übereinstimmt.

Ein Site-Paket enthält keine Benutzer, Zugangsdaten oder Secrets. Es enthält jedoch jeden Eintrag und jeden Kommentar der Website, einschließlich der E-Mail-Adressen von Autoren und Kommentierenden. Bewahren Sie es mit derselben Sorgfalt auf und versenden Sie es so wie ein Datenbank-Backup.

Die richtige Art der Kopie wählen

Verwenden Sie ein rohes Datenbank-Backup, um ein Deployment nach einem Datenverlust wiederherzustellen. Verwenden Sie ein Site-Paket, um an anderer Stelle eine neue Kopie einer Website zu erstellen.

Was ein Site-Paket enthält

Ein Site-Paket enthält:

• Collections, Felder, Blocktypen mit jeder Version, Taxonomie-Definitionen, Relationsdefinitionen und Byline-Felddefinitionen;
• jeden Inhaltseintrag in jeder Sprache, einschließlich Entwürfen, geplanten Einträgen, Einträgen im Papierkorb, Revisionsverlauf und Übersetzungsgruppen;
• Taxonomie-Begriffe und Begriffszuweisungen, Bylines und Credits, Inhaltsreferenzen und SEO-Datensätze;
• Menüs und Menüeinträge, Widget-Bereiche und Widgets, Sections und Weiterleitungen;
• Kommentare und Kommentarreaktionen, sofern der Export Kommentare nicht ausschließt;
• Medienordner, Medien-Metadaten und die Bytes jeder fertigen Mediendatei; und
• die unten aufgeführten portablen Website-Einstellungen.

Das Paket speichert JSON-Werte, etwa JSON-Felder und Portable Text, mit sortierten Objektschlüsseln. Ein importierter Wert kann seine Schlüssel daher in einer anderen Reihenfolge auflisten als der Ursprung. Ansonsten bleiben die Werte unverändert.

Portable Einstellungen

Nur diese Einstellungen werden exportiert: site:title, site:tagline, site:logo, site:favicon, site:postsPerPage, site:dateFormat, site:timezone, site:social, site:seo, emdash:site_title, emdash:site_tagline und emdash:locale.

Die Ziel-Website behält ihre eigene Website-URL (site:url und emdash:site_url), Website-ID, ihren Einrichtungsstatus und ihre Backup-Einstellungen. Ein Import überschreibt diese niemals.

Der Importplan fragt, ob Titel und Tagline des Ziels beibehalten werden sollen, die der Einrichtungsassistent geschrieben hat, oder ob die Werte des Pakets verwendet werden sollen. Standardmäßig werden die Werte des Pakets verwendet.

Principals

Ein Benutzerkonto wird nie mit einem Paket übertragen. Für jeden Benutzer des Ursprungs, auf den Inhalte, Revisionen, Medien, Bylines oder Kommentare verweisen, enthält das Paket einen Principal: die ID des Benutzers, den Anzeigenamen und die E-Mail-Adresse. Ein Principal hat keine Rolle, kein Passwort, keinen Passkey, keine Sitzung und kein Token.

Während des Imports ordnen Sie jeden Principal einem Benutzer auf der Ziel-Website zu oder lassen ihn unzugeordnet. Siehe Autoren zu Zielbenutzern zuordnen.

Kommentare

Kommentare umfassen Namen und E-Mail-Adresse des Autors, Text, Status, Threading, Zeitstempel und Moderationsmetadaten. Der IP-Adress-Hash und der User-Agent werden nicht exportiert.

Reaktionen behalten ihre Anzahl. Der Exporter ersetzt jeden Abstimmenden-Hash durch einen neuen Zufallswert, sodass das Ziel eine Reaktion nicht dem Besucher zuordnen kann, der sie abgegeben hat.

Was ein Site-Paket auslässt

Ein Site-Paket enthält niemals:

• Benutzer, Sitzungen, Passkeys, OAuth-Konten, erlaubte Domains, API-Tokens, OAuth-Clients, Autorisierungscodes oder Gerätecodes;
• Plugin-Speicher, Plugin-Status oder Plugin-Einstellungen, einschließlich Plugin-Secrets;
• andere Einstellungen als die portablen Einstellungen, etwa das Signatur-Secret für Vorschauen;
• Audit-Logs, Ratenbegrenzungen, Bearbeitungssperren, den Status geplanter Aufgaben, das 404-Log oder den Migrationsverlauf;
• Mediennutzungsdatensätze und Suchindizes, die der Import neu aufbaut;
• Speicherschlüssel, Bucket-Namen, Datenbanknamen oder Binding-Namen des Ursprungs; oder
• Medien, die nicht fertig sind, etwa einen unvollständigen Upload.

Medien eines externen Medienanbieters bleiben extern. Das Paket behält die Referenz, aber die Dateien des Anbieters werden nicht kopiert.

Ziel-Website vorbereiten

Importieren Sie in eine Website, die alle folgenden Anforderungen erfüllt. Wenn Inhalte, Sprachen, Upload-Limit oder unterstütztes Format des Ziels nicht zum Paket passen, meldet die Analyse einen Blocker.

• Ein Administratorkonto. Der Import läuft als angemeldeter Administrator oder mit einem API-Token. Legen Sie den Administrator des Ziels während der Einrichtung an.
• Ein Speicher-Backend. Sowohl der Ursprung als auch das Ziel benötigen konfigurierten Speicher. EmDash legt die Paketdateien dort zwischen.
• Keine Inhalte. Das Ziel darf keine Einträge (einschließlich Einträgen im Papierkorb), Revisionen, Medien oder Medienordner, Bylines oder Byline-Felder, Kommentare, Weiterleitungen, Begriffszuweisungen, Relationen, SEO-Datensätze, im Admin erstellte Sections oder nach der Einrichtung erstellte Collections oder Blocktypen enthalten. Eine Website, die aus einem beliebigen offiziellen Template eingerichtet wurde, erfüllt diese Voraussetzung. Was die Einrichtung erstellt hat, ist das Einrichtungsgerüst: die per Seed angelegten Collections und Blocktypen, Taxonomie-Definitionen und ihre nicht zugewiesenen Begriffe, Menüs und ihre Einträge, Widget-Bereiche und ihre Widgets sowie Theme-Sections. Der Plan listet das Gerüst auf, und der Import entfernt es, nachdem Sie den Plan bestätigt haben.
• Jede Sprache, die das Paket verwendet. Fügen Sie jede Sprache des Pakets zur i18n-Konfiguration des Ziels hinzu. Eine Website ohne i18n-Konfiguration akzeptiert nur en. Sprachen werden ohne Berücksichtigung der Groß-/Kleinschreibung abgeglichen, und der Import schreibt jede Sprache in der beim Ziel konfigurierten Schreibweise, deklariert als locale_recased.
• Ein ausreichend großes Upload-Limit. Jede Mediendatei muss in die maxUploadSize des Ziels passen, die standardmäßig 50 MiB beträgt.
• Formatversion 1. Das Ziel muss die Formatversion des Pakets und jede erforderliche Funktion unterstützen.

Die folgende Anfrage gibt die unterstützten Formatversionen, Funktionen und Limits zurück. Ihr portableDomain-Objekt meldet, ob die Website einen Import empfangen kann, und falls nicht, warum.

curl https://new.example.com/_emdash/api/admin/transfer/capabilities \
  -H "Authorization: Bearer $EMDASH_TOKEN"

Eine Website exportieren

Ein Export liest die Website in begrenzten Schritten und schreibt das Paket in den Speicher der Website. Bevor ein Export abgeschlossen wird, validiert der Exporter das fertige Paket auf dieselbe Weise wie ein Import. Wenn während eines Exports ein Schreibvorgang auf der Website erfolgreich ist, beginnt der Exporter von vorn. Das Setzen oder Erneuern einer Bearbeitungssperre für einen Eintrag zählt nicht als Schreibvorgang. Nach drei Versuchen schlägt er mit TRANSFER_EXPORT_CONCURRENT_WRITES fehl.

Die Dateien des Exports bleiben sieben Tage nach seiner Erstellung verfügbar. Danach gibt ein Download TRANSFER_EXPIRED zurück.

Im Admin exportieren

Der Bereich zeigt außerdem den Paket-Digest, die Anzahl der Datensätze jeder Art und die letzten Exporte der Website, jeweils mit eigener Download-Schaltfläche bis zu ihrem Ablauf.

Download package ruft den Export Datei für Datei ab, prüft Größe und SHA-256-Digest jeder Datei anhand des Manifests und erstellt die .emdash-Datei im Browser, sodass dies auf Cloudflare Workers für Websites jeder Größe funktioniert. Wenn eine Datei nicht übereinstimmt, stoppt der Download mit einem Fehler. Chrome, Edge und andere Chromium-basierte Browser schreiben die Datei direkt auf die Festplatte. Andere Browser halten das gesamte Paket im Speicher, bis der Download abgeschlossen ist; bei einem Export von mehr als etwa 500 MB empfiehlt die Seite einen Chromium-basierten Browser oder die CLI.

Download as one file fordert das Archiv stattdessen in einer einzigen Antwort vom Server an. Das eignet sich für kleine Websites. Auf Cloudflare Workers kann eine große Website die Limits einer einzelnen Anfrage überschreiten.

Mit der CLI exportieren

Melden Sie sich bei der Ursprungs-Website an und exportieren Sie sie dann in eine Paketdatei:

npx emdash login --url https://example.com
npx emdash site export --url https://example.com --output site.emdash

Der Befehl führt den Export bis zum Abschluss aus, lädt das Paket Datei für Datei herunter, prüft Größe und Digest jeder Datei und schreibt site.emdash. Fügen Sie --no-comments hinzu, um Kommentare und Reaktionen auszulassen. Wenn der Befehl unterbrochen wird, führen Sie ihn mit denselben Optionen erneut aus, um denselben Export fortzusetzen. Siehe die Referenz zu emdash site export.

Mit der REST-API exportieren

Jeder Aufruf von advance führt einen Schritt aus und gibt nextRequestInMs zurück, die Wartezeit vor dem nächsten Aufruf. Der Export ist abgeschlossen, wenn nextRequestInMs den Wert null hat.

Diese Beispiele verwenden ein persönliches Zugriffstoken mit dem Scope transfer:export. Siehe Token-Scopes.

Eine .emdash-Datei ist ein unkomprimiertes Tar-Archiv mit manifest.json als erstem Eintrag. Das Archiv streamt alle Dateien in einer Antwort. Auf Cloudflare Workers kann eine große Website die Limits einer einzelnen Anfrage überschreiten. Laden Sie in diesem Fall manifest.json von exports/{id}/manifest und jede Datei von exports/{id}/files/{path} herunter. Jede heruntergeladene Datei wird während des Streamings gegen ihren aufgezeichneten Digest geprüft. Wenn sich die gespeicherten Bytes nach dem Export geändert haben, endet der Download mit einem Fehler, statt abgeschlossen zu werden.

Eine Website importieren

Ein Import wird aus einem Paket erstellt, zu einem Plan analysiert und erst ausgeführt, nachdem Sie diesen Plan anhand seines Digests bestätigt haben. Ein Import, dessen Ausführung noch nicht begonnen hat, läuft 24 Stunden nach seiner Erstellung ab.

Admin, CLI und REST-API können jeden Schritt ausführen. Ein KI-Agent kann über die MCP-Tools einen bereits hochgeladenen Import analysieren und starten.

Im Admin importieren

Die Seite bietet außerdem Cancel import vom Upload bis zum Abschluss des Imports sowie Abandon import, nachdem ein Import, der bereits mit dem Schreiben begonnen hat, fehlgeschlagen ist oder abgebrochen wurde. Beide fragen nach einer Bestätigung. Siehe Einen Import abbrechen und Einen unvollständigen Import aufgeben.

Mit der CLI importieren

Melden Sie sich bei der Ziel-Website an und analysieren Sie dann das Paket:

npx emdash login --url https://new.example.com
npx emdash site import site.emdash --url https://new.example.com --analyze

Der Befehl prüft die gesamte Paketdatei lokal, lädt sie hoch, analysiert sie und gibt den Plan mit seinem Plan-Digest aus. Er endet mit dem Code 2, wenn der Plan Blocker enthält. Überprüfen Sie den Plan wie unter Importplan überprüfen beschrieben.

Um die Entscheidungen des Plans zu ändern, führen Sie --analyze erneut mit Entscheidungs-Flags aus. --map-principal ordnet einen Principal, per ID oder E-Mail-Adresse, einem Zielbenutzer per ID oder E-Mail-Adresse oder none zu. --use-target-title und --use-target-tagline behalten Titel und Tagline des Ziels bei:

npx emdash site import site.emdash --url https://new.example.com --analyze \
  --map-principal editor@example.com=editor@example.com \
  --map-principal 01J8ZQ4Y6T2N0D3VJ5R7K9M1PX=none \
  --use-target-title

Führen Sie den überprüften Plan aus, indem Sie seinen Digest übergeben:

npx emdash site import site.emdash --url https://new.example.com \
  --plan sha256:3f1c… --confirm

Der Befehl führt den Import bis zum Abschluss aus und gibt die Quittung aus. Wenn er unterbrochen wird, setzen Sie ihn mit emdash site import resume <operation-id> fort. emdash site import status <operation-id> gibt den Status des Imports aus, und emdash site import receipt <operation-id> gibt die Quittung erneut aus. Siehe die Referenz zu emdash site import.

Mit der REST-API importieren

Der Server arbeitet mit den Dateien innerhalb eines Pakets, nicht mit dem .emdash-Archiv. Entpacken Sie das Archiv zuerst. Es enthält manifest.json, Indexdateien unter index/, Datensatzdateien unter records/ und Mediendateien unter media/. Das Manifest legt Größe und SHA-256-Digest jeder Datei fest, sodass der Paket-Digest das gesamte Paket identifiziert.

Diese Beispiele verwenden ein Token mit den Scopes transfer:analyze und transfer:execute.

Die Ausführung schlägt mit TRANSFER_PACKAGE_DIGEST_MISMATCH oder TRANSFER_PLAN_DIGEST_MISMATCH fehl, wenn einer der Digests vom zwischengespeicherten Paket oder vom aktuellen Plan abweicht. Lesen Sie den aktuellen Plan von imports/{id}/plan, überprüfen Sie ihn erneut und versuchen Sie es mit seinen Digests noch einmal.

Autoren zu Zielbenutzern zuordnen

Die Analyse listet jeden Principal mit seinem Anzeigenamen, seiner E-Mail-Adresse und der Anzahl der Paketdatensätze auf, die auf ihn verweisen. Wenn genau ein Zielbenutzer dieselbe E-Mail-Adresse hat – verglichen ohne Berücksichtigung der Groß-/Kleinschreibung –, schlägt der Plan diesen Benutzer vor und ordnet den Principal standardmäßig ihm zu. Principals ohne Vorschlag beginnen unzugeordnet.

Um eine Zuordnung zu ändern, übergeben Sie --map-principal an emdash site import --analyze oder übermitteln Sie principalMappings an den Analyse-Endpunkt. Jede Zuordnung benennt einen Zielbenutzer oder lässt den Principal unzugeordnet (none in der CLI, null in der API). EmDash wendet jede Zuordnung auf Eintragsautoren, Revisionsautoren, Medien-Uploader, Byline-Benutzerverknüpfungen und Kommentarautoren an.

Die Referenzen eines unzugeordneten Principals werden entfernt. Wenn ein unzugeordneter Autor außerdem eine mit seinem Konto verknüpfte Byline hatte, schreibt der Importer diese Byline explizit jedem Eintrag des Autors gut, der keinen expliziten Byline-Credit hat und dessen Sprache die Byline des Autors besitzt. Der Credit des Autors bleibt daher auf der Seite erhalten.

Zwei Zuordnungen erzeugen einen principal_conflict-Blocker:

• ein Principal mit mehr als einer Byline in derselben Sprache wird einem Benutzer zugeordnet; oder
• zwei Principals, die beide Bylines in derselben Sprache haben, werden demselben Benutzer zugeordnet.

Ein Zielbenutzer kann nur eine Byline pro Sprache haben. Lassen Sie einen Principal unzugeordnet oder ordnen Sie die Principals verschiedenen Benutzern zu.

Importplan überprüfen

Ein Plan listet auf, was der Import erstellen wird, welche Entscheidungen er anwenden wird, sowie drei Arten von Befunden:

• Blocker verhindern die Ausführung. Die Ausführung gibt TRANSFER_PLAN_BLOCKED zurück, bis der Plan keine mehr enthält. Ändern Sie die Principal-Zuordnungen, um einen principal_conflict aufzulösen. Jeder andere Blocker erfordert eine Änderung am Paket oder am Ziel: Brechen Sie den Import ab, nehmen Sie die Änderung vor und erstellen Sie einen neuen Import.
• Warnungen beschreiben Probleme im Paket, die den Import nicht stoppen. Sie werden in die Quittung übernommen.
• Transformationen sind die exakten, deklarierten Unterschiede zwischen der Quell-Website und der importierten Website. Die Änderungen des Exporters werden zuerst aufgeführt, dann die des Imports. Die Verifizierung wendet die Transformationen des Imports an, wenn sie die importierte Website mit dem Paket vergleicht.

Ein Plan listet höchstens 500 Blocker und Warnungen auf. Eine Warnung issues_truncated meldet, wie viele weitere gefunden wurden.

Blocker

Der Importer schreibt Datensätze direkt, daher wendet die Analyse dieselben Prüfungen an, die die Admin-API beim Speichern dieser Datensätze anwendet. Jeder dieser Werte ist eine value_constraint_violation:

• ein Eintragswert, der nicht in die Spalte seines Feldes passt, ein Pflichtfeld ohne Wert oder ein Wert für ein Feld, das die Collection nicht hat;
• eine Weiterleitung, deren Quelle oder Ziel kein Pfad auf der Website ist, deren Typ nicht unterstützt wird, deren Quellmuster ungültig ist oder deren Ziel einen Parameter verwendet, den die Quelle nicht erfasst;
• eine Byline-Website, die keine http- oder https-URL ist, ein Byline-Feldwert, der nicht zum Typ oder zu den Auswahlmöglichkeiten seines Feldes passt, oder ein Byline-Feld mit mehr Auswahlmöglichkeiten, als eine Website unterstützt;
• ein ungültiges URL-Muster einer Collection;
• ein Blocktyp mit einem reservierten Slug, einem leeren oder mehr als 200 Zeichen langen Label oder Felddefinitionen, die der Blocktyp-Editor ablehnen würde;
• eine kanonische SEO-URL, die weder eine http- oder https-URL noch ein Website-Pfad ist; und
• eine Menüeintrags-URL mit einem Schema, das Menüs nicht erlauben.

Warnungen

Transformationen

Der Exporter deklariert die Änderungen, die er an den Daten der Quell-Website vorgenommen hat. Jede dieser Transformationen enthält eine Datensatzart und eine Anzahl:

Der Import deklariert seine eigenen Änderungen:

Den Import ausführen

Die Ausführung durchläuft diese Phasen in folgender Reihenfolge:

1. Das Ziel reservieren und erneut prüfen, ob es leer ist.
2. Das im Plan aufgeführte Einrichtungsgerüst entfernen.
3. Blocktypen, Collections, Felder, Taxonomie-Definitionen, Relationsdefinitionen und Byline-Felder erstellen.
4. Mediendateien in den Speicher des Ziels kopieren und Mediendatensätze erstellen.
5. Begriffe und Bylines schreiben.
6. Revisionen und Einträge schreiben.
7. Begriffszuweisungen, Byline-Credits, Inhaltsreferenzen und SEO-Datensätze schreiben.
8. Menüs, Widgets, Sections, Weiterleitungen, Kommentare, Reaktionen und Einstellungen schreiben.
9. Suchindizes und Caches neu aufbauen und die Neuindizierung der Mediennutzung einreihen.
10. Das Ergebnis verifizieren.

Jeder advance-Aufruf führt einen begrenzten Schritt aus, der in die Anfragelimits von Cloudflare Workers mit D1 passt. Der Fortschritt wird auf dem Server gespeichert. Eine unterbrochene Anfrage verliert höchstens den laufenden Schritt, und jeder Schreibvorgang ist idempotent, sodass die erneute Ausführung eines Schritts keine Datensätze dupliziert.

Während eine andere Anfrage einen Schritt ausführt oder eine andere Anfrage die Operation während eines Schritts übernimmt, gibt advance die Operation mit einem kurzen nextRequestInMs zurück. Ein Speicher- oder Datenbankfehler wird wiederholt: Die Operation zeichnet den Fehler auf, und nextRequestInMs wächst mit jedem aufeinanderfolgenden Fehlschlag. Nach wiederholten Fehlschlägen ohne Fortschritt schlägt der Import fehl.

Schreibvorgänge sind während eines Imports blockiert

Vom ersten Ausführungsschritt bis zum Abschluss des Imports lehnt EmDash Schreibanfragen an seine API mit 503 TRANSFER_IMPORT_IN_PROGRESS ab. Das betrifft den Admin, die REST-API, Plugin-Routen, öffentliche Kommentarübermittlungen, geplantes Veröffentlichen und Inhaltsschreibvorgänge von Plugins. Anmeldung, Benutzer- und API-Token-Verwaltung, Bearbeitungssperren für Einträge und die Transfer-API selbst bleiben verfügbar. Leseanfragen werden nicht blockiert.

MCP-Schreibtools, einschließlich Plugin-MCP-Tools, schlagen mit TRANSFER_IMPORT_IN_PROGRESS im üblichen Tool-Fehler fehl. Schreibgeschützte MCP-Tools und die site_*-Transfer-Tools funktionieren weiterhin, sodass ein über MCP gestarteter Import über MCP fortgesetzt, geprüft und abgeschlossen werden kann.

Nach einer Unterbrechung fortsetzen

Die Admin-Seite treibt einen Import nur voran, solange sie geöffnet ist. Um fortzufahren, öffnen Sie Settings → Transfer erneut, führen Sie emdash site import resume <operation-id> aus oder rufen Sie advance für dieselbe Operation erneut auf. Der Server setzt beim letzten abgeschlossenen Schritt fort. Wenn die unterbrochene Anfrage die Operation noch hielt, wartet der nächste Aufruf, bis diese Sperre abläuft, höchstens fünf Minuten.

Ein fehlgeschlagener oder abgebrochener Import kann nicht fortgesetzt werden.

Einen Import abbrechen

Wählen Sie Cancel import unter Settings → Transfer, führen Sie emdash site import cancel <operation-id> aus oder senden Sie POST imports/{id}/cancel. Ein laufender Schritt stoppt nach seinem aktuellen Stapel. Das Abbrechen entfernt keine bereits geschriebenen Datensätze.

Einen unvollständigen Import aufgeben

Ein fehlgeschlagener oder abgebrochener Import, der bereits mit dem Schreiben begonnen hat, blockiert weiterhin Schreibvorgänge, damit die unvollständige Website nicht versehentlich bearbeitet werden kann. Um die Sperre aufzuheben, wählen Sie Abandon import unter Settings → Transfer, führen Sie emdash site import abandon <operation-id> aus oder senden Sie POST imports/{id}/abandon. Beim Aufgeben bleiben die importierten Daten erhalten.

Nach dem Aufgeben ist die Website nicht mehr leer und kann daher keinen weiteren Import empfangen. Importieren Sie stattdessen in eine neu eingerichtete Website.

Ein fehlgeschlagener oder abgebrochener Import, der nie mit dem Schreiben begonnen hat, blockiert keine Schreibvorgänge und muss nicht aufgegeben werden.

Das Ergebnis verifizieren

Die Verifizierung liest jeden importierten Datensatz mit demselben Code zurück, den der Exporter verwendet, wendet die deklarierten Transformationen des Plans auf die Datensätze des Pakets an und vergleicht beides. Außerdem prüft sie die Datensatzanzahl jeder Art und lädt jede importierte Mediendatei erneut herunter, um ihren Digest zu prüfen. Jede Abweichung lässt den Import mit TRANSFER_VERIFICATION_FAILED fehlschlagen. Das errorDetail der Operation listet bis zu 50 der Abweichungen auf.

Ein erfolgreicher Import erzeugt eine Quittung:

{
	"operationId": "01J8ZR2C4S6D8F0G2H4J6K8M0N",
	"packageDigest": "sha256:…",
	"planDigest": "sha256:…",
	"targetSiteId": "01J8ZR0A2B4C6D8E0F2G4H6J8K",
	"originSiteId": "01J1A3C5E7G9J1L3N5Q7S9U1W3",
	"formatVersion": "1",
	"importerEmDashVersion": "0.38.0",
	"completedAt": "2026-09-23T10:15:00.000Z",
	"logicalDigest": "sha256:…",
	"counts": { "entry": 412, "media": 96 },
	"warnings": [],
	"verification": "verified",
	"receiptDigest": "sha256:…"
}

Eine Quittung hält fest, dass die durch targetSiteId identifizierte Ziel-Website zum Zeitpunkt des Abschlusses der Verifizierung genau den Inhalt des durch packageDigest identifizierten Pakets enthielt, nach Anwendung des durch planDigest identifizierten Plans. Der logicalDigest fasst die verifizierten Datensätze zusammen.

receiptDigest ist der SHA-256-Digest des kanonischen JSON der Quittung ohne die Eigenschaft receiptDigest. Er erkennt eine Quittung, die nach ihrer Ausstellung verändert wurde. Eine Quittung ist nicht signiert und beweist daher nicht, welcher Server sie ausgestellt hat. Rufen Sie die Quittung über eine authentifizierte Verbindung vom Ziel ab, wenn das wichtig ist.

Eine Quittung beschreibt die Website zu dem Zeitpunkt, an dem die Verifizierung abgeschlossen wurde. Über spätere Bearbeitungen sagt sie nichts aus.

Zwischen Datenbanken wechseln

Ein Paket hängt nicht von der Datenbank des Ursprungs ab. Exportieren Sie aus SQLite, PostgreSQL oder D1 und importieren Sie in jede davon. Planen Sie die folgenden Unterschiede ein, wenn das Ziel PostgreSQL verwendet:

• PostgreSQL speichert Ganzzahlen mit 32 Bit. Eine Ganzzahl außerhalb dieses Bereichs ist ein integer_out_of_range-Blocker.
• PostgreSQL speichert number-Felder und Medien-Fokuspunkte als 32-Bit-Gleitkommawerte. Werte, die sich ändern, werden als float4_rounded deklariert, und die Verifizierung vergleicht die gerundeten Werte.
• Die Volltextsuche ist nur auf SQLite und D1 verfügbar. Collections mit aktivierter Suche werden mit deaktivierter Suche importiert und als search_unsupported deklariert.

Der Importer schreibt Medien unter neuen Speicherschlüsseln in das Speicher-Backend des Ziels und schreibt Medienreferenzen in Inhalten, Einstellungen und SEO-Datensätzen entsprechend um. Eine Referenz auf eine Mediendatei, die der Ursprung nicht hat, wird unverändert exportiert und als unknown_storage_key deklariert.

Sicherheit

• Behandeln Sie ein Paket als sensibel. Es enthält alle Inhalte, einschließlich Entwürfen und Papierkorb, sowie die E-Mail-Adressen von Autoren und Kommentierenden. Halten Sie es aus öffentlichen Buckets und freigegebenen Ordnern fern und löschen Sie Kopien, die Sie nicht mehr benötigen.
• Behandeln Sie ein Paket als nicht vertrauenswürdige Eingabe. Der Import prüft Pfade, Größen, Digests, Datensatzschemata, Referenzen und Limits, bevor er schreibt. Er führt niemals Code oder SQL aus einem Paket aus und ruft niemals URLs aus einem Paket ab.
• Vergeben Sie Transfer-Zugriff bewusst. Die Übertragung erfordert die Administratorrolle. Ein Token mit dem Scope admin kann jede Transfer-Aktion ausführen; geben Sie dem Token eines Agenten daher nur den Transfer-Scope, den er benötigt.
• Prüfen Sie das Audit-Log. EmDash protokolliert Transfer-Aktionen im Audit-Log der Website: transfer_export_create, transfer_import_create, transfer_import_execute, transfer_import_cancel, transfer_import_abandon, transfer_import_complete, transfer_import_fail, transfer_approval_approve und transfer_approval_deny. Jeder Eintrag nennt den handelnden Benutzer und die Operation oder Genehmigung (Ressourcentyp transfer_operation oder transfer_approval). Seine Details enthalten nur IDs, Digests, Datensatzanzahlen und Fehlercodes, niemals Paketinhalte. Ebenso enthalten die Details von Transfer-Fehlern niemals Paketinhalte.
• Halten Sie den Zwischenspeicher privat. EmDash legt Paketdateien unter dem Präfix transfers/ Ihres Speicher-Buckets ab und weigert sich, dieses Präfix über seine Medienroute auszuliefern. Wenn der Bucket eine öffentliche Domain hat, beschränken Sie sie auf Medien, wie bei Backups. Zwischengespeicherte Dateien werden gelöscht, nachdem eine Operation endet oder abläuft.

Token-Scopes

Die Übertragung verwendet drei API-Token-Scopes:

Der Scope admin umfasst alle drei, sodass das von emdash login gespeicherte Token jede Übertragung ausführen kann. Jeder Transfer-Scope gewährt nur seine eigenen Aktionen, und nur ein Administrator kann einen solchen ausstellen. Verwenden Sie sie, um einem Token engeren Zugriff als admin zu geben, zum Beispiel einem Agenten, der Pakete analysieren, aber nicht exportieren oder importieren darf. Siehe die Scope-Referenz.

Genehmigungen für Agenten

KI-Agenten steuern Übertragungen über die site_*-MCP-Tools. Die Tools starten Operationen, treiben sie voran und berichten darüber. Sie übertragen niemals Paket-Bytes, daher lädt der Benutzer eines Agenten Exporte herunter und Pakete hoch – mit der CLI oder der REST-API. Jedes Tool erfordert die Admin-Rolle.

Ein MCP-Client, dessen Token weder admin noch den passenden Transfer-Scope hat – etwa ein Agent, dem nur transfer:analyze gewährt wurde –, kann einen Export oder Import nicht allein starten. Sein Aufruf von site_export_start oder site_import_start erstellt eine ausstehende Genehmigungsanfrage und schlägt mit TRANSFER_APPROVAL_REQUIRED und der Genehmigungs-ID fehl. Ein Administrator genehmigt oder lehnt die Anfrage unter Approval requests in Settings → Transfer ab, wo jede ausstehende Anfrage mit ihrem Anfragenden, ihrer Aktion und ihrer Ablaufzeit aufgeführt ist. Die nur mit Sitzung nutzbaren Endpunkte POST /_emdash/api/admin/transfer/approvals/{id}/approve und …/deny tun dasselbe. API-Tokens können keine Anfragen genehmigen. Der Client wiederholt den Aufruf anschließend mit der Genehmigungs-ID. Genehmigungen gelten nur für diese MCP-Tools; die REST-API hat keinen Genehmigungsparameter.

Eine Genehmigung gewährt dem anfragenden Benutzer einen Aufruf, vom selben Token, mit denselben Argumenten. Eine Exportgenehmigung ist an die Exportoptionen gebunden. Eine Importgenehmigung ist an die Operation und beide Digests gebunden, sodass ein geänderter Plan eine neue Genehmigung benötigt. Eine ausstehende Anfrage läuft nach 15 Minuten ab, eine genehmigte 15 Minuten nach der Genehmigung. Der Wiederholungsaufruf, der die Operation startet, verbraucht sie; wenn die Operation nicht startet, kann dieselbe Genehmigung bis zu ihrem Ablauf erneut verwendet werden. Derselbe Benutzer und dasselbe Token können diese eine Operation anschließend ohne den Scope prüfen und vorantreiben.

Gewähren Sie dem Token eines Agenten transfer:export, transfer:execute oder admin nur dann, wenn der Agent Übertragungen ausführen muss, ohne dass eine Person jede einzelne genehmigt.

Limits

Der Endpunkt capabilities meldet die Werte, die die Website durchsetzt.

Für Hosting-Anbieter

Eine Hosting-Steuerungsebene kann die Website eines Kunden allein mit der REST-API in die Produktion verschieben:

Halten Sie das Ziel unerreichbar, bis Schritt 4 erfolgreich ist. EmDash verbirgt eine teilweise importierte Website nicht vor Besuchern.

Fehlerbehebung

Transfer-Fehler verwenden stabile Codes. Der HTTP-Status wird bei jedem Code angegeben.