EmDash + Cloudflare D1:无服务器数据库架构
EmDash CMS、Cloudflare D1、R2 组成的全栈架构。Binding 配置、seed.json、本地开发详解。
WordPress 已经过时了。有一个为 Edge 设计的现代 CMS 替代方案。EmDash 是一个为 Astro 设计的开源全栈 CMS,结合 Cloudflare D1(SQLite 兼容无服务器 DB)和 R2(对象存储)。本文详解其数据库架构。
1. 架构概览#
EmDash 架构由四大支柱组成:
| 组件 | 角色 |
|---|---|
| Astro | 框架、SSR/SSG、Live Collections |
| EmDash CMS | 管理界面、内容模型、REST API、插件 |
| Cloudflare D1 | 内容、设置、分类、用户、媒体元数据的 SQL DB |
| Cloudflare R2 | 媒体文件(图片、上传)的对象存储 |
2. Cloudflare D1:SQLite 无服务器数据库#
D1 是 Cloudflare 的托管无服务器数据库。SQLite 的 SQL 语义,内置灾难恢复和 Worker/HTTP API 访问。
主要规格#
| 项目 | 详情 |
|---|---|
| 引擎 | SQLite |
| 免费额度 | 每天 500 万次读、10 万次写、最多 5GB |
| 付费方案 | 单 DB 最大 10GB、账户最多 50,000 DB(总计 1TB) |
| Time Travel | 过去 30 天内任意分钟的即时时间点恢复 |
| 全球读副本 | Beta:跨区域读副本 |
为什么选择 D1?#
- SQLite 兼容:现有 SQLite 知识直接可用
- 无服务器:不计空闲费用,只为查询和存储付费
- Edge 分发:Cloudflare 全球网络,低延迟
- EmDash 官方支持:
emdash/db提供d1()适配器
3. Binding 配置:wrangler.jsonc#
D1 和 R2 的 Binding 在 wrangler.jsonc 中配置:
wrangler.jsonc
{
"name": "my-worker",
"compatibility_date": "2026-06-28",
// D1 Database Binding
"d1_databases": [
{
"binding": "DB", // 通过 env.DB 访问
"database_name": "emdash-db", // 人类可读名称
"database_id": "xxxxxxxx-xxxx-xxxx-xxxx" // `wrangler d1 create` 获取的 UUID
}
],
// R2 Bucket Binding
"r2_buckets": [
{
"binding": "MEDIA", // 通过 env.MEDIA 访问
"bucket_name": "emdash-media"
}
]
}jsoncBinding 流程#
[!NOTE]
binding名在代码中用env.DB、env.MEDIA。改名时代码也要同步修改。
4. EmDash DB 适配器#
EmDash 在 astro.config.mjs 中指定 DB 适配器:
astro.config.mjs
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 适配器
}),
],
});js可用适配器:
| 适配器 | 用途 |
|---|---|
d1() | Cloudflare D1(无服务器) |
sqlite() | 本地 SQLite(开发用) |
libsql() | LibSQL/Turso |
postgresql() | PostgreSQL |
5. seed.json:Schema 的真相来源#
seed/seed.json 是 EmDash 站点的引导文档。定义集合、字段、分类、菜单、重定向、小部件区域和站点设置。
seed.json 结构#
seed/seed.json
{
"$schema": "https://emdashcms.com/seed.schema.json",
"version": "1",
"meta": {
"name": "My Blog",
"description": "基于 EmDash + D1 的博客"
},
"settings": {
"title": "My Blog",
"postsPerPage": 10
},
"collections": [
{
"name": "posts",
"fields": [
{ "name": "title", "type": "string" },
{ "name": "body", "type": "portabletext" }
]
}
],
"taxonomies": [],
"menus": [],
"redirects": [],
"widgetAreas": [],
"content": {}
}json应用规则#
| 操作 | 行为 |
|---|---|
| Collections、Settings | upsert — 存在则更新,不存在则创建 |
| Menus、Widgets | replace — 用 seed 完全覆盖 |
| Content entries | skip — slug 存在则跳过 |
应用方式#
# 通过 CLI 应用
npx emdash seed seed/seed.json
# 导出现有 schema
npx emdash export-seed > .emdash/seed.json
# 导出包含 content
npx emdash export-seed --with-content > .emdash/seed.jsonbash[!TIP] seed.json 在数据库为空时”首次请求”自动应用。开发中建议通过 CLI 明确应用更可靠。
6. 本地开发:Miniflare + SQLite#
本地开发使用 Miniflare(Cloudflare 本地模拟器)。
存储路径#
.wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlitetext| 项目 | 说明 |
|---|---|
<hash> | 从 database_id 派生的十六进制哈希 |
| 文件格式 | SQLite 兼容(可用 better-sqlite3 直接连接) |
| 持久性 | wrangler dev 会话间数据保持 |
| 本地/远程 | 用 --local / --remote 标志完全分离 |
本地开发流程#
# 将 seed 应用到本地 D1
npx emdash seed seed/seed.json --local
# 启动开发服务器
wrangler dev
# 查看本地 DB
ls .wrangler/state/v3/d1/miniflare-D1DatabaseObject/bash[!NOTE] 本地 DB 和远程 DB 完全分离。用
--local和--remote区分。
7. 完整数据流#
8. 总结#
| 组件 | 角色 | 文件 |
|---|---|---|
| D1 | 内容 DB | wrangler.jsonc(Binding 配置) |
| R2 | 媒体存储 | wrangler.jsonc(Binding 配置) |
| EmDash | CMS 层 | astro.config.mjs(d1() 适配器) |
| seed.json | Schema 真相来源 | seed/seed.json |
| Miniflare | 本地 DB | .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite |
EmDash + D1 + R2 组合成无服务器、可扩展的 CMS 架构。告别 WordPress 服务器管理,在 Edge 高速分发。