EmDash + Cloudflare:本地开发中的 SQLite3 和 API
EmDash 如何在本地开发环境中处理 SQLite3 和 API。详解 Miniflare、D1、REST API 端点。
运行 wrangler dev 时,Cloudflare 的 D1 数据库立刻出现在本地。但底层发生了什么?本文深入讲解 EmDash 如何在本地开发环境中处理 SQLite3 和 API。
1. 本地开发概览#
2. Miniflare:本地 D1 模拟器#
运行 wrangler dev 会启动 Miniflare(Cloudflare 的本地模拟器)。
Miniflare 工作原理#
SQLite 文件结构#
.wrangler/
state/
v3/
d1/
miniflare-D1DatabaseObject/
<hash>.sqlite # 数据库文件
<hash>.sqlite-shm # 共享内存(WAL)
<hash>.sqlite-wal # Write-Ahead Logtext| 文件 | 作用 |
|---|---|
<hash>.sqlite | 实际的 SQLite 数据库 |
<hash>.sqlite-shm | WAL 模式的共享内存 |
<hash>.sqlite-wal | 预写日志(并发控制) |
[!NOTE]
<hash>是从database_id派生的 HMAC 十六进制哈希。相同 Binding ID 总是映射到相同哈希。
WAL 模式的优势#
默认使用 WAL(Write-Ahead Logging)模式:
- 读写可以同时进行
- 写入不会阻塞读取
- 与生产环境 D1 使用相同模式
直接访问本地 DB#
用外部工具打开 SQLite 文件:
# SQLite CLI 连接
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite
# Beekeeper Studio、SQLiteFlow 等也可以直接连接bash3. EmDash 的两种 DB 适配器#
EmDash 在 astro.config.mjs 中指定 DB 适配器。本地和生产使用不同的适配器。
本地开发:sqlite() 适配器#
astro.config.mjs(本地开发)
import emdash from "emdash/astro";
import { sqlite } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: sqlite({
url: "file:./data.db", // 本地 SQLite 文件
}),
}),
],
});js生产环境:d1() 适配器#
astro.config.mjs(生产)
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 binding
}),
],
});js对比#
| 项目 | 本地(sqlite()) | 生产(d1()) |
|---|---|---|
| 引擎 | better-sqlite3 | Cloudflare D1 |
| 存储 | data.db 文件 | Cloudflare 基础设施 |
| 事务 | SQLite 标准 | batch() API |
| 并发写入 | 单写入者(SQLite 限制) | Cloudflare 管理 |
| Schema | 共享 | 共享 |
[!TIP] 两个适配器共享 Kysely(SQL 查询构建器)。Schema 和 migrations 在本地和生产之间完全相同。
4. 本地数据流#
5. EmDash REST API 端点#
EmDash 在 Astro Dev Server 的同一端口提供 API。
本地开发 URL#
http://localhost:4321/_emdash/api/ # REST API
http://localhost:4321/_emdash/admin/ # 管理界面text主要 API 端点#
| 类别 | 端点 |
|---|---|
| 内容 CRUD | GET/POST /content/{collection}, GET/PUT/DELETE /content/{collection}/{id} |
| 发布管理 | POST /content/{collection}/{id}/publish, /unpublish, /schedule |
| 媒体 | GET/POST /media, POST /media/upload-url |
| Schema | GET/POST /schema/collections |
| 分类 | GET/POST /taxonomies, GET/POST /taxonomies/{name}/terms |
| 菜单 | GET/POST /menus, GET/PUT/DELETE /menus/{name} |
| 设置 | GET/PUT /settings |
| 搜索 | GET /search, GET /search/suggest, POST /search/rebuild |
认证#
# Bearer token 认证
curl -H "Authorization: Bearer $EMDASH_TOKEN" \
http://localhost:4321/_emdash/api/content/posts
# Session 认证(从管理面板)
# CSRF 保护:需要 X-EmDash-Request: 1 headerbashOpenAPI 规范#
# 获取 API 规范
curl http://localhost:4321/_emdash/api/openapi.jsonbash6. 种子数据应用#
首次启动时,如果数据库为空,会从 seed/seed.json 应用种子数据。
手动应用#
# 应用 seed 到本地 DB
npx emdash seed seed/seed.json --local
# 导出 schema
npx emdash export-seed > .emdash/seed.jsonbash应用流程#
7. 本地 vs 远程:详细对比#
| 项目 | 本地(SQLite) | 远程(D1) |
|---|---|---|
| 引擎 | better-sqlite3 | Cloudflare D1 |
| DB 适配器 | sqlite({ url: "file:./data.db" }) | d1({ binding: "DB" }) |
| 存储适配器 | local({ directory: "./uploads" }) | r2({ binding: "MEDIA" }) |
| 持久化 | .wrangler/state/ 或 data.db | Cloudflare 基础设施 |
| 并发写入 | 单写入者(SQLite 限制) | 管理型,但仍为单写入者 |
| 事务 | SQLite 标准 | batch() API |
| 读副本 | 无 | D1 Sessions API |
| 备份 | 复制 .sqlite 文件 | wrangler d1 export |
8. 开发技巧#
重置数据#
# 删除 SQLite 文件重置
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite-*
# 重启重新创建
wrangler devbash团队共享数据库#
# 持久化到共享目录
wrangler dev --persist-to=./shared-dbbash查看本地 DB#
# 列出表
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite ".tables"
# 查看数据
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite \
"SELECT * FROM posts LIMIT 5;"bash9. 总结#
| 组件 | 本地开发行为 |
|---|---|
| Miniflare | 在 .wrangler/state/ 创建 SQLite3 文件 |
| better-sqlite3 | 连接本地 SQLite 的桥梁 |
| Kysely | SQL 查询构建器(本地/生产共享) |
| EmDash API | 在 /_emdash/api/ 提供 REST API |
| seed.json | 首次启动时引导 schema |
EmDash + Cloudflare 的本地开发环境用 SQLite3 复现 D1 的 SQL 语义。Miniflare 搭建桥梁,让开发者在本地验证生产环境行为。