第3部 運用と移行
第10章 デプロイと運用
デプロイ、バックアップ、アップデートなど、運用の手順を学ぶ。
読了の目安 約 41 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)
この章で学ぶこと
- 配置先 (Cloudflare Workers / Node.js) の選び方と、それに連動するデータベース・ストレージの組み合わせ
- シークレット (secret) と環境変数の置き場所、ローテーション (rotation) の影響
- ルートキャッシュ (route cache) とオブジェクトキャッシュ (object cache) の役割の違い
- バックアップと復元。特に「EmDash の JSON バックアップでは復元できない」という点
- アップデート、コアマイグレーション (core migration)、スキーマ進化 (schema evolution) の区別
- ドメイン変更、プレビュー環境、監視の実務
- 本番デプロイ前とアップデート時のチェックリスト
基準は EmDash 1.3.1、確認日は 2026-10-29 です。WordPress では「レンタルサーバーに FTP でファイルを置き、プラグインを管理画面から更新する」運用が一般的でした。EmDash はビルドしたアプリケーションをデプロイする形なので、コード、データベース、メディア、鍵の 4 つを別々に管理する発想が必要になります。この章はその整理が目的です。
1. 配置先の選択
なぜ最初に決めるのか
配置先は、使えるデータベース、ストレージ、キャッシュ、スケジューラー、プラグインのサンドボックスまで決めます。後から変えると、これらをまとめて移行することになります。
判断基準
| 観点 | Cloudflare Workers | Node.js |
|---|---|---|
| 標準のデータベース | D1 (テンプレートの既定) | SQLite (最も簡単) |
| 標準のメディア保存先 | R2 バインディング | ローカルディレクトリ、または S3 互換 |
| 定期実行 | Cron Trigger + scheduled ハンドラー |
組み込みスケジューラー (プロセスが動いている間のみ) |
| ルートキャッシュ | cacheCloudflare() (CDN 型) |
memoryCache() (プロセス内) |
| プラグインのサンドボックス | Worker Loader (Workers 有料プラン) | workerd 子プロセス |
| 運用の手間 | サーバー管理が不要 | 永続ディスク、プロセス監視、HTTPS 終端が必要 |
図 10-1 に示すように、配置先を決めるとデータベース、メディア保存先、定期実行、キャッシュ、サンドボックスの構成要素が対になって決まります。
筆者の見解として、すでに Cloudflare のアカウントとドメインがあり、サーバー管理を避けたいなら Workers が素直です。社内の VPS や Docker 環境が前提なら Node.js が向いています。公式資料にこの二択の優劣の記述はないので、上の使い分けは判断の目安です。
Cloudflare Workers へのデプロイ
Cloudflare 用テンプレートには、Worker のエントリーポイントと、名前付きの D1・R2 バインディングが含まれています。wrangler.jsonc の要点は次のとおりです。
{
"main": "./src/worker.ts",
"compatibility_flags": ["nodejs_compat"],
"d1_databases": [{ "binding": "DB", "database_name": "my-emdash-site" }],
"r2_buckets": [{ "binding": "MEDIA", "bucket_name": "my-emdash-media" }],
"worker_loaders": [{ "binding": "LOADER" }],
"triggers": { "crons": ["* * * * *"] }
}
DB、MEDIA、LOADER という名前は EmDash のアダプターと一致させる必要があります。初回の wrangler deploy で、設定した名前の D1 と R2 が無ければ Wrangler が作成し、以後は同じリソースに再接続します。
pnpm build
pnpm wrangler deploy注意点を挙げます。
- Cron Trigger と、
@emdash-cms/cloudflare/workerのscheduledハンドラーの両方が揃わないと、予約公開が行われません。astro devではタイマーで公開されるため、ローカルで動いてもデプロイ後の設定は保証されません。emdash doctorで配線を確認できます (独自の書き方のエントリーポイントでは、動いていても失敗扱いになることがあります)。 - Cron Trigger の新設・変更が反映されるまでに最大 15 分かかることがあります。
- D1 へは 1 リクエストで複数回の往復が発生するため、Targeted Placement で Worker を D1 の近くに置く方法があります。この場合、D1 の読み取りレプリカとは併用しません。
- サンドボックスプラグイン (マーケットプレイス/レジストリ経由、または
sandboxed: []) を使わなければ、sandboxRunnerとLOADERは省略できます。LOADERは Workers 有料プランが前提です。
Node.js へのデプロイ
Node.js 22.23.4 以上が必要です (Astro 7.3 以前なら 22.16.0 で足ります)。アダプターは @astrojs/node の standalone モードです。
npm run build
node ./dist/server/entry.mjs # 既定は http://localhost:4321押さえる点は次のとおりです。
- standalone のエントリーは
.envを自動で読みません。本番ではホスティング側の環境変数に設定します。ローカルで.envを使うならnode --env-file=.env ./dist/server/entry.mjsで起動します。 - リバースプロキシで TLS を終端する場合は、
EMDASH_SITE_URL(またはSITE_URL) に公開 URL を設定します。ビルドする場所とサーバーを動かす場所の両方に必要です。ビルド時に無いと、ローカル保存メディアの画像最適化が効かず、原寸のまま配信されます。 - スケジューラーはプロセスが動いている間だけ動きます。常時 1 プロセス以上を起動しておきます。
- Docker で動かす場合は、公式のサンプルのとおりビルドステージと実行ステージを分け、
dataディレクトリを名前付きボリュームにします。リポジトリ本体のルートにあるDockerfile(モノレポ全体をビルドするもの) とは別物です。 /healthのようなヘルスチェック用エンドポイントは、Astro のルートが応答できることしか示しません。データベース、ストレージ、マイグレーション状態、サンドボックスは別途確認します。
2. データベースの選び方
なぜ重要か
データベースにはコンテンツモデル、エントリー、ユーザー、設定、プラグインのデータが入ります。メディアのバイナリは入りません。環境ごとに別のデータベースを持たせる、という原則も重要です。
選択表
| データベース | 使う場面 | 実行環境 |
|---|---|---|
| SQLite | 永続ディスクを持つ単一の Node.js プロセス | Node.js / ローカル開発 |
| D1 | Cloudflare Workers で Cloudflare の SQL を使う | Workers |
| Hyperdrive | Workers から既存の PostgreSQL に接続する | Workers |
| PostgreSQL | 複数の Node.js プロセスで一つの DB を共有する | Node.js |
| libSQL | Node.js からリモートの SQLite 互換 DB を使う | Node.js |
SQLite の注意点
EmDash は SQLite を WAL (write-ahead logging) モードで開きます。稼働中は emdash.db-wal と emdash.db-shm が隣に作られ、プロセスにはディレクトリへの書き込み権限が必要です。WAL には、まだ本体に反映されていないコミット済みの変更が入ることがあります。NFS や SMB のようなネットワークファイルシステムは避け、ローカルディスクかブロックボリュームに置きます。エフェメラルなファイルシステムでは再起動でデータが消えます。
D1 の読み取りレプリカ
d1({ binding, session, coalesce }) の session は "disabled" (既定)、"auto"、"primary-first" を取ります。"auto" では匿名の訪問者が最寄りのレプリカから読み、ログイン中のユーザーはブックマーク Cookie により自分の書き込みが見えることが保証されます。書き込み系リクエストは常にプライマリから始まります。D1 側でも読み取りレプリケーションを有効にする必要があります。
注意:
session: "auto"または"primary-first"は、global_fetch_strictly_public互換フラグと併用できません。D1 セッション API が使う内部リクエストがブロックされるためです。このフラグが必要ならsessionは"disabled"のままにします。
coalesce (実験的機能) は、同時に発行された読み取りを 1 回の D1 バッチにまとめます。公式資料によれば Cloudflare テンプレートは session と coalesce の両方を有効にしています。
PostgreSQL と Hyperdrive の落とし穴
- EmDash は自分のテーブルを作成・変更するため、接続ロールには稼働期間を通じてスキーマ権限 (
CREATE、テーブルの所有権など) が必要です。スーパーユーザー権限は要りません。 - 接続ロールは変えないでください。オブジェクトは作成したロールの所有になるので、後でロールを入れ替えると、読み書きはできてもマイグレーションが
must be owner of tableで失敗しえます。パスワードの更新だけなら安全です。 - Hyperdrive のクエリキャッシュは既定で有効ですが、プライマリのバインディングでは 無効にする 必要があります。書き込み直後の読み取りが古い結果になり、セットアップが壊れるためです (
--caching-disabled)。匿名の公開読み取りだけをキャッシュ有効のバインディング (cachedBinding) に流す構成も用意されています。 - サンドボックスプラグインは D1 専用で、Hyperdrive 構成では使えません。
3. ストレージの選び方
データベースのバックアップにはメディアのメタデータしか含まれません。実ファイルは別に守ります。
| ストレージ | 使う場面 | 署名付きアップロード |
|---|---|---|
| R2 バインディング | Cloudflare Workers | なし |
| S3 | Node.js で AWS S3、R2 の S3 API、MinIO などを使う | あり |
| ローカル | 永続ボリュームを持つ単一の Node.js サーバー | なし |
- R2 バインディング: アクセスキーが不要です。公開用のカスタムドメインがあれば
publicUrlに設定します。r2.devの開発用 URL はレート制限があり、本番向きではありません。 - S3:
@aws-sdk/client-s3と@aws-sdk/s3-request-presignerを自分でインストールします。入れ忘れるとastro buildが失敗します。未指定の項目はS3_ENDPOINT、S3_BUCKET、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_REGION、S3_PUBLIC_URLから起動時に読み込まれます (Node.js のみ)。Workers の資格情報を Astro の設定に埋め込んではいけません。Vite がサーバーバンドルに含めてしまう恐れがあるためです。 - ローカル:
local({ directory, baseUrl })。baseUrlは通常/_emdash/api/media/fileにします。
セキュリティ: 自動 JSON バックアップは同じストレージの
backups/プレフィックスに保存されます。バケットを公開ドメインに接続すると、このプレフィックスも URL で到達できる恐れがあります。バケットは非公開にして EmDash のメディアルートから配信するか、公開範囲をメディアのオブジェクトに限定してください (EmDash のメディアルート自体はbackups/を返しません)。
どのアダプターも同じ Storage インターフェースを実装しているため、アプリケーションコードを変えずに切り替えられます。HTTP の Range リクエストにも対応しており、Safari の動画再生に必要です。
4. シークレットと環境変数
原則
- Node.js ではホスティングのシークレット管理から
process.envに入れる。Workers ではwrangler secret put <NAME>。 astro.config.mjs、wrangler.jsonc、import.meta.envに秘密値を書かない。import.meta.envはビルド時に置換され、サーバーバンドルに書き込まれる恐れがあります。
一覧
| 種類 | 置き場所 | 失った場合の影響 |
|---|---|---|
EMDASH_ENCRYPTION_KEY |
環境変数 / Worker シークレットのみ (DB に保存されない) | 暗号化されたプラグイン設定が読めなくなる |
| プレビュー用秘密鍵 | DB の options に自動生成 (EMDASH_PREVIEW_SECRET で上書き可) |
発行済みプレビューリンクが無効になるだけ |
| IP ソルト | DB に自動生成 (EMDASH_IP_SALT で上書き可) |
コメントのレート制限の連続性がリセットされる |
| セッション、API トークン | セッションストア / DB (トークンはハッシュのみ) | 失うものなし (再発行できる) |
| OAuth、Turnstile、S3 の資格情報 | 環境変数 | 該当機能が止まる。提供元で再発行する |
| プラグインの秘密設定 | DB (暗号化) | 鍵を戻すか、値を入れ直す |
EMDASH_ENCRYPTION_KEY は npx emdash secrets generate で生成します (emdash_enc_v1_ で始まる形式)。データベースのバックアップにこの鍵は含まれません。 鍵なしで DB を復元すると、暗号化された設定が読めません。別のシークレット管理に必ず控えを取ります。
ローテーションでは、新しい鍵をカンマ区切りの先頭に置き、古い鍵を後ろに残します。
EMDASH_ENCRYPTION_KEY=emdash_enc_v1_<新>,emdash_enc_v1_<旧>
新規保存と再保存は先頭の鍵で暗号化されます。すべてのプラグインシークレットを保存し直し、新しい鍵だけの環境で動作を確認してから古い鍵を外します。EmDash はどの鍵が使われているかを報告しないため、再保存した認証情報は自分で台帳に記録します。
Cloudflare では process.env への反映に nodejs_compat が必要です。compatibility_date が 2025-04-01 以降なら自動で入ります。それより古い日付に固定している場合は nodejs_compat_populate_process_env を追加します。
5. キャッシュ
二種類の役割
| ルートキャッシュ | オブジェクトキャッシュ | |
|---|---|---|
| 何を保存するか | レンダリング済みのレスポンス | クエリ結果 (コンテンツ、設定、メニューなど) |
| ヒット時 | ページの描画が省略される | 描画は毎回走る |
| 設定 | cache.provider と routeRules |
emdash({ objectCache }) |
| Workers | cacheCloudflare() |
kvCache({ binding }) (KV) |
| Node.js | memoryCache() (astro/config) |
memoryCache() (emdash/astro) |
オブジェクトキャッシュは既定で無効です。ルートキャッシュを使っている場合、匿名のレンダリングはオブジェクトキャッシュを使わずデータベースから読みます (無効化後の再生成が古いスナップショットから作られるのを避けるため)。ルートキャッシュが匿名の訪問者を受け持ち、オブジェクトキャッシュは主にログイン中の編集者の表示を速くします。
ルートキャッシュの設定
cache: { provider: cacheCloudflare() },
routeRules: {
"/blog/[slug]": { maxAge: 86_400, swr: 604_800, tags: ["posts", "all"] },
},maxAgeは無効化が失敗した場合の「最悪の古さ」の上限でもあります。- タグにはコレクション名を使います。EmDash は公開・非公開・削除・復元などで
[collection, id]のタグを自動で無効化します。他の名前のタグ (例のall) は自動では無効化されません。非常用の全消去スイッチとして使えます。 - 公開ルートは一つずつ明示的にルールを書きます。ルート直下の rest パラメーター (
/[...slug]) は/_emdash/の管理画面と API にも一致してしまいます。 - 無効化されないもの: 古いリビジョンの復元、著者表記 (byline)、メディアライブラリ、コメントの変更。期限切れか、該当エントリーの再保存で更新されます。
落とし穴
- Cloudflare ではキャッシュヒントがあるだけで保存対象になります。 レイアウトがサイト設定やメニューのヒント (
maxAgeなし) を全ページで設定していると、ルールがなくても Workers Cache の既定 (200 応答で 2 時間) で保存されます。全公開ルートにルールを書き、セッション依存のルートにはヒントを付けません。 - 編集者にも共有キャッシュが返ります。 キャッシュは Worker の前段にあり Cookie では回避できません。既定のサーバー描画ツールバーだと、編集者が匿名版を見ることがあります。ルートキャッシュを使うサイトでは
toolbar: "client"を設定します。 - Cloudflare の purge には上限があります。 Workers Cache の purge は、プランに関係なく Free プランの上限 (アカウントあたり毎分 5 リクエスト、バースト 25) が適用されます。上限を超えると管理画面にエラーが出ず、
maxAgeが切れるまで古いページが残ります。一括編集や同時編集が多いサイトでは、許容できるmaxAgeを選びます。 - Node.js の
memoryCache()はプロセス単位です。 複数インスタンスでは書き込みを受けたプロセスしか無効化されません。再起動で空になり、予約公開は無効化を起こさないため、予約コンテンツを一覧するルートはmaxAgeを短くします。 - デプロイごとに空になります (Cloudflare)。 Worker のバージョンがキャッシュキーに入るためです。
cross_version_cacheで保持できますが、テンプレートの変更が反映されるのは期限切れか無効化の後になります。 - ミドルウェアのリダイレクトは
context.cache?.set(false)でキャッシュ対象から外します。 さもないと、リダイレクトループの原因になりえます。
ブラウザキャッシュは別物です。EmDash のヒントは purge 用のタグであり、Last-Modified は自動では付きません。Cache-Control は no-cache か数分程度の短い値で自分で設定します。
KV を使うオブジェクトキャッシュでは、変更の反映が KV のエッジキャッシュの伝播 (最大約 60 秒) と revalidate (既定 1 秒) の分だけ遅れます。KV 名前空間は npx wrangler kv namespace create CACHE で作ります。複数サイトで一つの名前空間を共有するなら keyPrefix を変えます。
6. バックアップと復元
最重要の事実
注意: EmDash の JSON バックアップ (Settings → Backups) を復元する機能は、管理画面にも API にも CLI にもありません。復旧用には使えません。復旧点には、生のデータベースバックアップかポイントインタイムリカバリを使います。
JSON バックアップはコンテンツ、コレクション定義、メニュー、リビジョンなどを含みますが、ユーザー、パスキー、トークン、プラグインの設定とストレージ、コメント、リダイレクト、メディア本体などを含みません。確認や独自ツール向けです。毎日の自動 JSON バックアップ (保持 1〜30 ファイル) は、Cloudflare では Cron Trigger、Node.js では組み込みスケジューラーで動きます。
復旧点は、データベース、メディア、鍵、アプリケーションの成果物 (artifact) の 4 点を同じ時点で揃えて保管します。
図 10-2 に示すように、JSON バックアップは復旧に使えず、復旧点はデータベース・メディア・鍵・成果物の四つを組にして持ちます。
| データベース | 復旧点 |
|---|---|
| D1 | Time Travel のブックマークを記録。長期保管は SQL ダンプ |
| SQLite / ローカル libSQL | sqlite3 emdash.db ".backup backup.db" + 整合性チェック |
| PostgreSQL | プロバイダーの PITR、または pg_dump --format=custom |
| Hyperdrive | 背後の PostgreSQL に直接接続してバックアップ |
| Turso | PITR で別 DB を作成、または .dump |
D1: Time Travel
npx wrangler d1 time-travel info my-database
npx wrangler d1 time-travel restore my-database --bookmark="<記録したブックマーク>"マイグレーション前にブックマークを記録します。保持期間は Workers Free で 7 日、Paid で 30 日です (Cloudflare の公式ページでも確認済み)。復元は DB を上書きし、実行中のクエリを中断します。復元コマンドは直前の状態のブックマークを出力するので、控えておけば復元自体を取り消せます。Time Travel が戻すのはデータベースだけで、R2 のメディアと EMDASH_ENCRYPTION_KEY は戻りません。
D1: オフサイトの SQL ダンプ
検索を有効にしたコレクションがあると、検索インデックスが FTS5 仮想テーブルになるため、素の wrangler d1 export は失敗します。公式資料の手順では、テーブルを名前で指定してエクスポートし、スキーマ・メディアフォルダー・データ・インデックス/トリガーの 4 ファイルに分けます。検索インデックスは復元後に最初の検索 API 呼び出し (/_emdash/api/search?q=a など) で再構築されます。
D1 は 100,000 バイト以上の SQL 文を拒否します。長い記事やリビジョンがあると SQLITE_TOOBIG で取り込めない場合があるので、作成直後に長さを検査します。その場合、ファイルはオフサイトの完全コピーとしては有効でも D1 には入らないため、D1 の復旧は Time Travel に頼ります。本番 DB にダンプを流してはいけません。空の D1 に取り込んで検証してから、バインディングを切り替えます。
SQLite
オフラインなら書き込むプロセスをすべて止めて、DB ファイルと -wal・-shm を一緒にコピーします。稼働中は sqlite3 emdash.db ".backup file" を使い、PRAGMA integrity_check が ok を返すか確認します。本体ファイルだけをコピーすると、WAL にしか無い変更が失われます。
復旧時は、書き込みプロセスを止め、壊れた DB と WAL/SHM を退避してから、検証済みのバックアップに置き換えます。
メディア
R2 と S3 互換のバケットには、オブジェクト単位のバックアップが別途必要です。
aws s3 sync s3://emdash-media ./emdash-media-backup \
--endpoint-url https://<account-id>.r2.cloudflarestorage.comルーチンのジョブには読み取り専用の資格情報を使い、本番とは別の障害ドメインに保管します。復元は空のバケットに行い、DB とメディアが一緒に検査を通ってから本番を切り替えます。
復元の検証
復元後は、サインイン、公開コンテンツの読み取り、スキーマ、暗号化されたプラグイン設定、書き込み、メディア読み取りを必ず確認します。復旧手順は、実際に空の環境に復元して一度通すまで「バックアップがある」とは言えません。
サイトパッケージ (site package) による複製は、ユーザーやトークン、プラグインデータを復元しないため、復旧点の代わりにはなりません。
7. アップデート手順
三つの変更を区別する
| 種類 | 対象 | 方法 |
|---|---|---|
| EmDash のバージョン更新 | npm パッケージ | npx upgrade-emdash@latest |
| コアマイグレーション | EmDash 内部テーブルなど | 自動 (auto) または emdash migrate |
| スキーマ進化 | 自分のコレクション・フィールド | 管理画面または emdash schema |
バージョン管理
EmDash はセマンティックバージョニングに従います。emdash と @emdash-cms/cloudflare は同じバージョンで同時にリリースされ、後者は一致する emdash を厳密に要求するため、必ず一緒に更新します。プラグインは独自のバージョンを持ちます。EmDash は Astro 6 以降が必要です。
依存のバージョンはロックファイル (npm ci や pnpm install --frozen-lockfile) で固定し、更新後は公開ページだけでなく管理画面も確認します。
手順
npx upgrade-emdash@latest --dry-runで計画を確認します (--to nextなどのnpm の dist-tagは指定できますが、正確なバージョンは指定できません)。npx upgrade-emdash@latestで依存とスキルを更新します。キャレット/チルダの記法は維持されます。マイグレーションは適用されません。.emdash/UPGRADE.mdを開き、作業指示を完了します。更新で追加されるコアマイグレーションの名前と、プロジェクト固有のコマンドが書かれています。- ビルドし、ローカルで起動して管理画面を確認します。
- コアマイグレーションが追加されるなら、起動やデプロイの前に復旧点を確認します。
- デプロイして検証します。
図 10-3 に、この六段階と、混同しやすい三種類の変更の区別を示します。
前提として、更新ツールは emdash 0.35.0 以降を要求します。それ以前のサイトは先に 0.35.0 へ上げます。Yarn Plug'n'Play には対応していません。テンプレートのファイル (レイアウトや astro.config.mjs) は更新されないので、必要なら公式の templates と差分を取って取り込みます。
コアマイグレーション
マイグレーションの既定モードは auto で、最初のリクエストで未適用分が適用されます。確実にしたい場合は、デプロイ前に明示的に流します。
pnpm build
pnpm emdash migrate --status # 対象と未適用分を確認
pnpm emdash migrate # 対象を確認して実行
pnpm wrangler deploy
pnpm emdash migrate --check # 未適用/未知があれば非ゼロ終了- ビルドは
.emdash/migrations.jsonを生成します。.gitignoreに入れ、成果物と一緒に扱います。 - 自動化では
--expected-target-fingerprintが必須です。--statusで確認した対象の指紋を CI の変数に設定します。誤った DB に流す事故を防ぎます。 - D1 は事前に
wrangler d1 createで作成します。emdash migrateは DB を作りません。 - D1 ではマイグレーションロックがあり、CI は同じ DB に対して 1 ジョブずつ直列化します (
concurrencyグループ)。 - Workers の
autoでは、約 5,000 件を超えるコンテンツ行を処理するマイグレーションがあると、適用せず 503 を返します。デプロイ側からemdash migrateで適用します。Node.js と開発サーバーは規模にかかわらず起動時に適用します。 - 実行時モードは
auto/check/manual。checkは未適用があれば 503 を返します。段階的にはautoから始め、ジョブが安定したらcheck、さらに外部チェックを徹底してからmanualに進みます。 - ロックが残った場合 (CI の中断など) は、他のジョブが動いていないことを確認し、
emdash migrate --statusでロック ID を見て--take-over-lock <id>を使います。 - マイグレーションは前進のみです。前のアプリケーションをデプロイし直してもマイグレーションは戻りません。戻す場合は、マイグレーション前のデータベースとアプリケーションを一緒に復元します。
_emdash_migrationsの行を消したりdown()を実行したりしてはいけません。 - D1 の書き込み結果が曖昧なときは、コマンドを再実行せず
--statusで確認します (例外として079_datetime_normalizationは再実行で続きから処理されます)。
スキーマ進化
シードファイルが効くのは初回のブートストラップのみです。デプロイ済みのサイトでシードを書き換えても何も起きません。変更は管理画面の Content Types か emdash schema で行います。
npx emdash login --url https://example.com
npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com- コマンドは冪等ではありません。再実行は失敗しえます。環境ごとに完了した手順を記録します。
- フィールドの削除は列と値を消し、JSON エクスポートでは戻せません。生の DB バックアップを取り、使い捨てのコピーで試してから本番に実行します。
- 変更後は
npx emdash types --url ...で型を再生成します。 - 変更したモデルは
emdash export-seedで.emdash/seed.jsonに書き戻し、コードと一緒にコミットします。export-seedはローカルの SQLite ファイルを読むので、本番が D1 の場合は、オフサイトのダンプ SQL をローカルの DB に読み込んでから--database prod.dbを付けて実行します。エントリーも含めるなら--with-contentを付けます。さもないと、新しいプレビュー環境や災害復旧で古いモデルから始まります。 - 順序: 追加は先にスキーマ、後からコード。削除は先にコード、後からスキーマ。
特定のリリースの注意点として、reference フィールドがリレーション (relation) に結び付く変更があり、結び付かなかったフィールドは入力欄がテキストボックスのままになります。更新後は参照フィールドのあるコレクションでエントリーを開いて確認します。
更新後に壊れたら
ビルドエラーは、飛ばしたバージョンの Breaking エントリーを読みます。プラグインの読み込み失敗は、そのプラグインのリリースノートを読みます。Astro API のエラーは Astro 6 以降へ上げます。前の版に戻すときは、前のパッケージ版を入れ直して再デプロイしますが、マイグレーションは戻らない点に注意してください。
8. ドメイン変更
手順
- 新ドメインを先にサイトへ向けます。HTTPS で応答する必要があります。Cloudflare では Worker の Domains タブでカスタムドメインを追加するか、
wrangler.jsoncのroutesにcustom_domain: trueを設定します。Node.js では DNS と証明書を整えます。 https://<新ドメイン>/_emdash/adminでサインイン画面が見えることを確認します。- Settings > General の Site URL の横にある Change domain で新ドメインを入力し、Check and switch を押します。EmDash は新ドメインの
/_emdash/api/site/domain-proofからワンタイムコードを取得して照合します。管理者のみ操作できます。
落とし穴
- パスキーはそれを作ったアドレスでしか動きません。 旧アドレスでサインインしたまま Continue on … ボタンから新アドレスで再登録します。他のユーザーには、メールが使える環境ならマジックリンクでサインインして追加してもらうか、Email users で案内を一斉送信します (1 サイトで 1 時間に 3 回まで)。
siteUrl、EMDASH_SITE_URL、SITE_URLが設定されていると、メールとプラグイン内のリンクはそちらが優先され、設定の変更と再デプロイが必要です。セットアップ前にこれらが未設定だと、セットアップ時のアドレスがサイトの origin として記録され、パスキーもそのアドレスに結び付きます。本番ドメインでセットアップするか、先にEMDASH_SITE_URLを設定します。- チェックが失敗する典型例は、DNS 未反映、証明書未発行、リダイレクト、Cloudflare Access が前にある場合です。Cloudflare では route ではなくカスタムドメインとして追加してください。route ではチェックが通りません。
- Use … anyway はチェックなしで保存します。ローカル開発やログイン付きのステージング向けです。
- サイトマップは最大 1 時間、
robots.txtは最大 1 日、ブラウザや共有キャッシュに古いものが残ります。旧アドレスは自動では閉じないので、ホスト側のリダイレクトを設定します。旧アドレスを外す前に、全管理者が新アドレスでサインインできることを確かめます。
9. プレビュー環境
「プレビュー」には二つの意味があるので区別します。
(a) コンテンツのプレビュー (下書きの共有)
署名付きの _preview トークン (HMAC-SHA256、有効期限付き) を URL に付けて、下書きを閲覧させる機能です。管理画面の View on site が発行します。既定の有効期間は 1 時間で、getPreviewUrl() の expiresIn で 30m、1d、2w のように指定できます。署名鍵は DB に自動生成されますが、アプリのコードから getPreviewUrl() を使う場合は EMDASH_PREVIEW_SECRET が必要です。トークンは一つのエントリーだけに有効で、別のコレクションやエントリーでは下書きは見えません。公開パスが標準と違うなら EMDASH_PREVIEW_PATH_PATTERN を設定します。
セキュリティ:
EMDASH_PREVIEW_SECRETを知っている人は、任意のコンテンツのプレビュートークンを作れます。漏えいした場合は DB のemdash:preview_secret行を消すか環境変数を変えて再デプロイします。発行済みのリンクが無効になるだけです。_preview付きのレスポンスはルートキャッシュに入りません。
(b) 環境としてのプレビュー (ブランチごとの確認用デプロイ)
Cloudflare では、Worker Previews (ブランチごとの URL。Wrangler 4.135.0 以降) か、名前付き環境 (--env preview) を使います。共通の原則は次のとおりです。
- 本番と別のデータベースとバケットを使う。 プレビューを本番に向けると、マイグレーションや破壊的な操作が本番データに及びます。
- バインディングは継承されません。Worker Previews では
previewsブロックに、名前付き環境ではenv.previewに全部書きます。Worker Previews にはSESSION用の KV 名前空間も必要です。 - セットアップとパスキーのために、プレビュー URL を
EMDASH_SITE_URLで渡します。astro.config.mjsのsiteUrlはすべてのプレビューに焼き込まれてしまうため、使いません。 previewsブロックのリソースはそのブランチ群で共有されます。EmDash を更新したブランチが、他のプレビューも使う DB を移行します。分離するなら、そのブランチ用に D1 を別に作ります。- 空のプレビュー DB にはセットアップウィザードが出ます。 プレビュー URL は公開なので、最初に終えた人が管理者になります。作成直後に自分で終えるか、Cloudflare Access で保護します。
- Cron Trigger は動きません。予約公開、プラグインの定期処理、定期バックアップはプレビューでは実行されません。
- パスキーは登録したホスト名でしか動きません。
スキーマの破壊的変更は、本番の SQL ダンプをプレビュー用 D1 に取り込んだコピーで予行するのが安全です。
10. 監視
EmDash 固有の監視機能は多くありません。資料に出てくる手段を組み合わせます。
| 対象 | 手段 |
|---|---|
| Worker のログ、Cron の実行 | pnpm wrangler tail。"* * * * *" ... - Ok が出ても、公開成功を意味しない。[scheduled] Published N scheduled item(s) を見る |
| 予約公開の遅延 | 管理画面ダッシュボードの Scheduled publishing needs attention (期限を過ぎ、5 分以上スケジューラーが完了していない場合) |
| 配線の静的チェック | emdash doctor (scheduler wiring) |
| マイグレーション状態 | emdash migrate --check / --status |
| Node.js の生存確認 | /health などのエンドポイント (DB やストレージは検証しない) |
| サンドボックス (Node.js) | サーバーログの [emdash:workerd]。60 秒以内に 5 回を超えてクラッシュすると再起動を止めるのでサーバーの再起動が必要 |
| 画像変換 (Cloudflare) | IMAGES バインディングの有無。無いと、内部メディアルート (/_emdash/api/media/file/…) では原寸が配信され (ログには出ない)、バケット URL では変換エンドポイントが 500 で失敗する。無料枠は月 5,000 件の一意な変換 |
筆者の見解として、これらは「確認の手段」であって、アラートの仕組みではありません。外形監視 (公開ページと /_emdash/admin への定期アクセス) と、Cloudflare や Node.js 側の通知は、利用者が別途用意します。外部サービスの選定は未検証です。
WordPress との違い
| 観点 | WordPress | EmDash |
|---|---|---|
| 配布物 | PHP ファイル群 | ビルド成果物 |
| 更新 | 管理画面からワンクリック | npm の依存更新 + 再ビルド + 再デプロイ |
| バックアップ | プラグインで DB + ファイル | DB、メディア、鍵、成果物を別々に保管 |
| 内部 DB の更新 | 管理画面アクセス時に更新 | auto / check / manual を選べ、デプロイ工程に組み込める |
| スケジュール投稿 | WP-Cron (アクセス契機) | Cron Trigger / 常駐スケジューラー |
| キャッシュ | キャッシュプラグイン | Astro のルートキャッシュ + タグ無効化 |
| ステージング | プラグインやホスト依存 | 別の DB・バケットを持つプレビュー環境 |
まとめ
- 配置先でデータベース、ストレージ、キャッシュ、スケジューラー、サンドボックスの選択肢が決まる。
- 環境ごとにデータベースとバケットを分け、秘密値はランタイムのシークレットに置く。
- JSON バックアップは復元できない。復旧点は DB の生バックアップとメディア、鍵、成果物をセットで持つ。
- SQLite は WAL を含めて取る (
.backup)。D1 は Time Travel を使い、ブックマークを記録する。 - ルートキャッシュは公開ルートごとにルールを書き、タグはコレクション名にする。
- 更新は
upgrade-emdash、コアマイグレーション、スキーマ進化の 3 つを区別する。マイグレーションは前進のみ。 - ドメイン変更ではパスキーが引き継がれないため、先に自分のサインイン手段を移す。
チェックリスト
本番デプロイ前
| # | 確認項目 | 確認方法 | 済 |
|---|---|---|---|
| 1 | 本番専用の DB・ストレージを用意し、開発/プレビューと分離している | 設定・バインディングの確認 | |
| 2 | Node.js: DB を永続ボリュームに置いている | マウント、書き込み権限 | |
| 3 | Cloudflare: DB/MEDIA/(LOADER) の名前が設定と一致している |
wrangler.jsonc |
|
| 4 | 秘密値がコードや import.meta.env に入っていない |
wrangler secret put / 環境変数 |
|
| 5 | EMDASH_ENCRYPTION_KEY を別の保管先に控えた |
シークレット管理 | |
| 6 | EMDASH_SITE_URL (または siteUrl) を本番ドメインにし、そこでセットアップする |
パスキーの動作 | |
| 7 | Cron Trigger と scheduled ハンドラーがある (Node.js は常駐プロセス) |
emdash doctor、wrangler tail |
|
| 8 | 公開ルートごとに routeRules を書き、toolbar: "client" を検討した |
キャッシュ動作 | |
| 9 | 公開バケットから backups/ に到達できない |
公開 URL で確認 | |
| 10 | バックアップを取り、復元を一度予行した | 空の環境へ復元 | |
| 11 | 公開ページ、管理画面、メディアのアップロード/取得、予約公開を確認した | 手動確認 | |
| 12 | デプロイ後に emdash migrate --check が成功する (デプロイ前は --status で適用対象を確認する) |
CLI |
アップデート時
| # | 確認項目 | 確認方法 | 済 |
|---|---|---|---|
| 1 | upgrade-emdash --dry-run で計画と changelog を確認 |
CLI | |
| 2 | emdash と @emdash-cms/cloudflare を同時に更新 |
package.json |
|
| 3 | ロックファイルの差分を確認し、問題のある依存は固定した | 差分レビュー | |
| 4 | .emdash/UPGRADE.md の作業を完了し、Breaking を評価した |
ファイル | |
| 5 | 追加マイグレーションがあれば、復旧点 (D1 のブックマーク等) を記録した | 記録 | |
| 6 | ビルドし、ローカルで管理画面を確認した | pnpm build、pnpm dev |
|
| 7 | マイグレーションの扱い (auto か事前適用) を決めた |
emdash migrate --status |
|
| 8 | デプロイ後に emdash migrate --check を実行した |
CLI | |
| 9 | 公開ページ、下書きの公開、メディアのアップロード/取得、予約公開/プラグインを確認した | 手動確認 | |
| 10 | 戻す手順 (DB と成果物をセットで復元) を用意している | 手順書 |
理解度チェック
- EmDash の JSON バックアップを復旧点として使えないのはなぜですか。代わりに何を用意しますか。
- SQLite の
data.dbだけをコピーして戻すと、なぜデータが失われることがありますか。安全な取得方法を二つ挙げてください。 - ルートキャッシュを使うサイトで、
routeRulesのタグにコレクション名を使う理由と、Cloudflare でレイアウトがキャッシュヒントを設定する場合の注意点を説明してください。 - コアマイグレーションを適用した後に前のバージョンをデプロイし直しても元に戻らないのはなぜですか。戻す場合はどうしますか。
- ドメイン変更の後、パスキーでサインインできなくなる理由と、管理者が事前にすべきことは何ですか。
- プレビュー環境を本番のデータベースに向けてはいけない理由を二つ挙げてください。
答え
- 管理画面、API、CLI のいずれにも JSON を復元する機能がなく、ユーザーやプラグイン設定なども含まれないため。DB の生バックアップ (D1 は Time Travel、SQLite は
.backupなど)、メディアのバックアップ、EMDASH_ENCRYPTION_KEY、対応するアプリケーション成果物をセットで用意する。 - WAL にはコミット済みでまだ本体に反映されていない変更が入ることがあるため。
sqlite3 emdash.db ".backup file"を使うか、書き込みプロセスを止めて-wal・-shmも一緒にコピーする。 - EmDash の自動無効化はコレクション名、エントリー ID、
emdash:*のタグに対して働くため、他の名前だと公開してもmaxAgeまで古いままになる。Cloudflare ではmaxAgeのないヒントでも保存可能になり、既定で 2 時間残りうるので、全公開ルートにルールを書き、セッション依存のルートにはヒントを付けない。 - コアマイグレーションは前進のみで、アプリケーションの再デプロイは DB を巻き戻さないため。マイグレーション前の DB とアプリケーションを一緒に復元する (
_emdash_migrationsの行削除やdown()の実行はしない)。 - パスキーは作成したアドレスにのみ有効なため。旧アドレスでサインインしたまま新アドレスでパスキーを登録し、他のユーザーにはメールのマジックリンクか Email users で案内する。旧アドレスを外す前に全管理者が新アドレスでサインインできることを確認する。
- プレビューのマイグレーションや破壊的なスキーマ変更が本番データに及ぶため。また、プレビューは URL が公開されていて Cron も動かないなど本番と挙動が異なり、空の DB ではセットアップウィザードが露出する (本番の DB を共有しない構成でも、プレビュー同士で共有する DB は更新の影響を受ける)。
出典
- Deploy to Cloudflare: https://docs.emdashcms.com/deployment/cloudflare/
- Deploy to Node.js: https://docs.emdashcms.com/deployment/nodejs/
- Choose a database: https://docs.emdashcms.com/deployment/database/
- Choose media storage: https://docs.emdashcms.com/deployment/storage/
- Manage secrets and keys: https://docs.emdashcms.com/deployment/secrets/
- Route Caching: https://docs.emdashcms.com/deployment/route-caching/
- Configure the object cache: https://docs.emdashcms.com/deployment/object-cache/
- Configure the plugin sandbox: https://docs.emdashcms.com/deployment/plugin-sandbox/
- Update EmDash: https://docs.emdashcms.com/deployment/updating/
- Manage core database migrations: https://docs.emdashcms.com/deployment/core-migrations/
- Evolve a deployed site's schema: https://docs.emdashcms.com/deployment/schema-evolution/
- Backups and recovery: https://docs.emdashcms.com/guides/backups/
- Move to a New Domain: https://docs.emdashcms.com/guides/change-domain/
- Preview Mode: https://docs.emdashcms.com/guides/preview/
- Cloudflare D1 Time Travel: https://developers.cloudflare.com/d1/reference/time-travel/
(URL は sources/emdash-docs/ の各 MDX に対応する公式サイトの位置です。)