部署至 Cloudflare

Cloudflare Workers 為 EmDash 提供快速、全球分散的執行環境。本指南涵蓋使用 D1 作為資料庫和 R2 作為媒體儲存的部署。

前置條件

• 一個 Cloudflare 帳戶
• 已安裝 Wrangler CLI（npm install -g wrangler）
• 已透過 Cloudflare 進行身分驗證（wrangler login）

設定綁定

在專案根目錄建立包含 D1 和 R2 綁定的 wrangler.jsonc。如果資源尚不存在，Wrangler 會在首次部署時自動佈建這兩個資源。

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

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

設定 EmDash

更新您的 Astro 設定以使用 D1 和 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" }),
		}),
	],
});

首次啟動

資料庫遷移會在部署後的第一個請求時自動執行，如果有新內容需要套用，則會在每次後續啟動時執行。

如果資料庫為空（沒有集合）且設定精靈尚未完成，EmDash 也會在首次啟動時套用種子檔案。種子檔案在建置時從 .emdash/seed.json、package.json#emdash.seed 中的路徑或 seed/seed.json 讀取 —— 以首先找到的為準 —— 並內嵌至套件中。如果都不存在，則使用內建的預設種子。針對現有資料庫的後續部署會保持其內容不變。

部署

部署至 Cloudflare Workers：

wrangler deploy

您的網站現在已在 https://my-emdash-site.<your-subdomain>.workers.dev 上線。

讀取副本

對於全球分散的網站，啟用 D1 讀取複製，將讀取查詢路由至附近的副本，而不是總是存取主要資料庫。這顯著降低了遠離主要區域的訪客的延遲。

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

您還需要在 Cloudflare 儀表板或透過 REST API 在 D1 資料庫本身上啟用讀取複製。

有關工作階段模式和基於書籤的一致性工作原理，請參閱資料庫選項 — 讀取副本。

自訂網域

在 Cloudflare 儀表板中新增自訂網域：

1. 前往 Workers & Pages > 您的 worker
2. 點選 Custom Domains > Add Custom Domain
3. 輸入您的網域並依照 DNS 設定說明操作

公開 R2 存取

要直接從 R2 提供媒體服務（建議用於效能）：

1. 在 Cloudflare 儀表板中，前往 R2 > 您的儲存貯體
2. 點選 Settings > Public access
3. 啟用公開存取並記下公開 URL
4. 更新儲存設定：

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

Cloudflare Access 身分驗證

如果您的組織使用 Cloudflare Access，您可以將其用作身分驗證提供者而不是密碼金鑰，透過現有的身分提供者提供單一登入。以下設定啟用它：

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

有關完整設定選項，請參閱身分驗證指南。

環境變數

建議：加密金鑰

EMDASH_ENCRYPTION_KEY 是用於加密靜態外掛程式金鑰（webhook 權杖、Turnstile 金鑰等）的金鑰。金鑰在啟動時進行驗證；一旦啟用，外掛程式金鑰加密就會使用它。在每次部署時設定它，以便在不變更設定的情況下保護金鑰。

金鑰由您提供，永遠不會儲存在資料庫中；只儲存加密的密文。遺失它意味著遺失用它加密的每個金鑰。

使用以下命令產生金鑰並將其儲存為 Worker 金鑰：

npx emdash secrets generate
wrangler secret put EMDASH_ENCRYPTION_KEY

可選：穩定值覆寫

EmDash 會自動產生預覽 HMAC 金鑰和評論者 IP 雜湊鹽，並在首次使用時將它們持久化至資料庫中。下面的環境變數是用於需要自己固定值的情況的覆寫 —— 例如，當單獨處理程序中的預覽 Worker 需要與主網站共享金鑰時。

使用 import.meta.env 或 Cloudflare env 綁定在設定中存取環境變數。

預覽部署

部署預覽分支：

wrangler deploy --env preview

在 wrangler.jsonc 中新增環境區段：

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

疑難排解

”D1 binding not found”

驗證 wrangler.jsonc 中的綁定名稱是否與資料庫設定相符：

// Must match: d1({ binding: "DB" })
"binding": "DB"

“R2 binding not found”

檢查 R2 儲存貯體是否正確綁定：

// Must match: r2({ binding: "MEDIA" })
"binding": "MEDIA"

遷移錯誤

如果您看到結構描述錯誤，請追蹤 Worker 日誌（wrangler tail）並重現錯誤以擷取底層訊息 —— 然後使用該輸出提交問題。