EmDash + Cloudflare D1: Kiến Trúc Database Serverless
EmDash CMS, Cloudflare D1, R2 kết hợp thành full-stack architecture. Hướng dẫn Binding, seed.json, và phát triển local.
WordPress đã lỗi thời, có giải pháp CMS hiện đại hơn. EmDash là CMS full-stack mã nguồn mở được thiết kế cho Astro, kết hợp Cloudflare D1 (SQLite serverless DB) và R2 (object storage). Bài viết này giải thích kiến trúc database hoàn chỉnh.
1. Tổng Quan Kiến Trúc#
Kiến trúc EmDash gồm 4 trụ cột chính:
| Thành Phần | Vai Trò |
|---|---|
| Astro | Framework, SSR/SSG, Live Collections |
| EmDash CMS | Admin UI, content model, REST API, plugin |
| Cloudflare D1 | SQL DB cho content, settings, taxonomy, user, media metadata |
| Cloudflare R2 | Lưu trữ media files (hình ảnh, uploads) |
2. Cloudflare D1: SQLite Serverless Database#
D1 là managed serverless database của Cloudflare. Semantic SQL của SQLite kết hợp disaster recovery, Worker/HTTP API tích hợp sẵn.
Thông Số Chính#
| Mục | Chi Tiết |
|---|---|
| Engine | SQLite |
| Free Tier | 5M rows read/ngày, 100K rows written/ngày, tối đa 5GB |
| Paid Plan | 1DB tối đa 10GB, account tối đa 50,000DB (tổng 1TB) |
| Time Travel | Point-in-time recovery trong 30 ngày gần nhất |
| Global Read Replica | Beta: read replica cross-region |
Tại Sao Chọn D1?#
- SQLite compatible : Kiến thức SQLite hiện có dùng được ngay
- Serverless : Không tính idle, chỉ tính query và storage
- Edge delivery : Mạng lưới toàn cầu Cloudflare, latency thấp
- EmDash support chính thức :
emdash/dbcung cấpd1()adapter
3. Binding Configuration: wrangler.jsonc#
Binding D1 và R2 cấu hình trong wrangler.jsonc:
{
"name": "my-worker",
"compatibility_date": "2026-06-28",
// D1 Database Binding
"d1_databases": [
{
"binding": "DB", // truy cập qua env.DB
"database_name": "emdash-db", // tên dễ đọc
"database_id": "xxxxxxxx-xxxx-xxxx-xxxx" // UUID từ `wrangler d1 create`
}
],
// R2 Bucket Binding
"r2_buckets": [
{
"binding": "MEDIA", // truy cập qua env.MEDIA
"bucket_name": "emdash-media"
}
]
}jsoncLuồng Binding#
[!NOTE] Tên
bindingdùng trong code làenv.DB,env.MEDIA. Đổi tên thì code cũng phải đổi theo.
4. DB Adapter Của EmDash#
EmDash chỉ định DB adapter trong astro.config.mjs:
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 adapter
}),
],
});jsCác adapter khả dụng:
| Adapter | Dùng Cho |
|---|---|
d1() | Cloudflare D1 (serverless) |
sqlite() | SQLite local (cho development) |
libsql() | LibSQL/Turso |
postgresql() | PostgreSQL |
5. seed.json: Nguồn Sự Thật Cho Schema#
seed/seed.json là document bootstrap cho EmDash site. Định nghĩa collections, fields, taxonomies, menus, redirects, widget areas, site settings.
Cấu Trúc seed.json#
{
"$schema": "https://emdashcms.com/seed.schema.json",
"version": "1",
"meta": {
"name": "My Blog",
"description": "Blog chạy trên 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": {}
}jsonQuy Tắc Áp Dụng#
| Thao Tác | Hành Vi |
|---|---|
| Collections, Settings | upsert — có thì cập nhật, không thì tạo mới |
| Menus, Widgets | replace — ghi đè hoàn toàn bằng seed |
| Content entries | skip — bỏ qua nếu slug đã tồn tại |
Cách Áp Dụng#
# Áp dụng qua CLI
npx emdash seed seed/seed.json
# Export schema hiện tại
npx emdash export-seed > .emdash/seed.json
# Export kèm content
npx emdash export-seed --with-content > .emdash/seed.jsonbash[!TIP] seed.json tự động áp dụng ở “request đầu tiên” khi database trống. Trong development, nên áp dụng rõ ràng qua CLI cho chắc chắn.
6. Phát Triển Local: Miniflare + SQLite#
Phát triển local dùng Miniflare (local simulator của Cloudflare).
Đường Dẫn Lưu Trữ#
.wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlitetext| Mục | Mô Tả |
|---|---|
<hash> | Hash hex bắt nguồn từ database_id |
| Định dạng | SQLite compatible (kết nối trực tiếp bằng better-sqlite3) |
| Persistence | Giữ data giữa các session wrangler dev |
| Local/Remote | Phân tách hoàn toàn với flag --local / --remote |
Luồng Phát Triển Local#
# Áp dụng seed vào D1 local
npx emdash seed seed/seed.json --local
# Start dev server
wrangler dev
# Kiểm tra local DB
ls .wrangler/state/v3/d1/miniflare-D1DatabaseObject/bash[!NOTE] Local DB và remote DB hoàn toàn tách biệt. Dùng
--localvà--remoteđể phân biệt.
7. Luồng Dữ Liệu Toàn Bộ#
8. Tóm Tắt#
| Thành Phần | Vai Trò | File |
|---|---|---|
| D1 | Content DB | wrangler.jsonc (cấu hình Binding) |
| R2 | Media storage | wrangler.jsonc (cấu hình Binding) |
| EmDash | CMS layer | astro.config.mjs (d1() adapter) |
| seed.json | Nguồn sự thật schema | seed/seed.json |
| Miniflare | Local DB | .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite |
Kết hợp EmDash + D1 + R2 tạo kiến trúc CMS serverless scalable. Thoát khỏi quản lý server WordPress, phân phối nhanh trên edge.