Triển khai blog tĩnh trên Cloudflare Workers

Từ Astro đến Workers static assets: các lệnh thật, bảng so sánh ba cách triển khai, và năm lỗi mình đã gặp.

Ảnh bìa minh hoạ triển khai blog tĩnh trên Cloudflare Workers
Ảnh bìa minh hoạ triển khai blog tĩnh trên Cloudflare Workers

Triển khai blog tĩnh trên Cloudflare Workers

Bài này là bản ghi lại những gì mình làm để đưa một blog Astro lên Workers, kèm các lệnh thật và những chỗ đã làm sai. Giả định bạn đã có tài khoản Cloudflare và một domain trỏ về đó.

Chuẩn bị

Mình dùng Node 20, Astro 5 và Wrangler 4. Không cần Docker, không cần VPS. Toàn bộ hạ tầng nằm trong một tài khoản Cloudflare, và gói miễn phí là đủ cho lưu lượng của một blog cá nhân.

# tạo project Astro mới, chọn "Empty" khi được hỏi
npm create astro@latest notice-web
cd notice-web

# thêm adapter/asset support cho Workers
npm install --save-dev wrangler@4
npx wrangler login

Sau khi đăng nhập, Wrangler lưu token vào máy. Nếu bạn làm trên CI thì dùng CLOUDFLARE_API_TOKEN thay vì đăng nhập tương tác.

Cấu trúc thư mục

Mình giữ mọi thứ trong một repo, hai thư mục:

vistaverde_autopost/
├── cms/                # SonicJS: API soạn bài, D1, R2
│   ├── src/
│   └── wrangler.toml
├── web/                # Astro: build tĩnh
│   ├── src/pages/
│   └── wrangler.toml
└── .secrets/           # không commit

Việc tách repo theo vai trò giúp mỗi bên có wrangler.toml riêng và deploy độc lập. CMS deploy khi schema đổi, web deploy khi nội dung đổi. Hai pipeline không giẫm chân nhau.

Build và deploy

Astro mặc định build ra dist/. Với Workers static assets, bạn chỉ cần trỏ Wrangler vào thư mục đó:

# web/wrangler.toml
name = "notice-web"
compatibility_date = "2026-01-15"

[assets]
directory = "./dist"
not_found_handling = "404-page"

Còn đây là lệnh build và deploy thật mình chạy:

cd web
npm run build          # astro build → dist/
npx wrangler deploy    # upload dist/ + assets manifest

Lần deploy đầu tiên mất khoảng 40 giây vì phải upload toàn bộ ảnh. Những lần sau chỉ upload phần thay đổi, thường dưới 10 giây. Nếu bạn thấy lần nào cũng 40 giây, kiểm tra xem có đang đặt assets.directory sai chỗ khiến Wrangler hash lại toàn bộ hay không.

Lấy nội dung từ CMS lúc build

Web không gọi API lúc người đọc truy cập. Nó gọi một lần lúc build:

// web/src/lib/posts.ts
const CMS = import.meta.env.PUBLIC_CMS_URL ?? 'https://cms.vistaverde.top';

export async function getPosts() {
  const res = await fetch(`${CMS}/api/post?limit=100`);
  if (!res.ok) throw new Error(`CMS responded ${res.status}`);
  const { data } = await res.json();
  return data.filter((p: any) => p.status === 'published');
}

Điểm cần nhớ: /api/post chỉ trả về bài đã xuất bản, nên bộ lọc status ở trên chỉ để chắc chắn. Bài nháp không bao giờ lọt ra bản public, đó là hành vi đúng.

So sánh các lựa chọn

Mình đã chạy thử cả ba kiểu trong cùng một tháng. Bảng dưới là số đo thực tế với khoảng 500 lượt xem mỗi ngày.

Tiêu chí Workers static assets Cloudflare Pages VPS + Nginx
Chi phí/tháng 0 USD 0 USD ~5 USD
Thời gian deploy 8–40 giây 30–90 giây 1–3 phút
Cấu hình một tệp TOML dashboard + git systemd, TLS, firewall
Cache edge có, mặc định có phải tự dựng
Rollback wrangler rollback chọn deployment tự viết script
Phù hợp với blog, docs, landing site có build phức tạp app cần tiến trình nền

Với một blog chỉ có HTML và ảnh, cột đầu tiên là lựa chọn ít việc nhất. Mình vẫn giữ một VPS cho những việc khác, nhưng không đặt blog ở đó nữa.

Nếu bạn phải SSH vào máy chủ để sửa một bài viết, kiến trúc của bạn đang sai. Nội dung nên đi qua API hoặc git, không đi qua terminal.

Những chỗ dễ sai

Đây là danh sách mình ước có ai đưa trước khi bắt đầu:

  1. Quên compatibility_date. Wrangler sẽ cảnh báo, nhưng vẫn deploy. Đặt một ngày cố định và nâng theo quý.
  2. Cache quá dài ở API. Nếu CMS cache 5 phút, bạn sửa bài xong phải đợi. Notice để TTL 5 giây cho API và cache vĩnh viễn cho file tĩnh.
  3. Slug trùng. API trả 409 khi slug đã tồn tại. Script seed của mình lưu id vào một tệp trạng thái để lần chạy sau là update, không phải create.
  4. Upload sai MIME. R2 không tự đoán. Gửi text/markdown cho tệp .md, nếu không trình duyệt sẽ tải xuống thay vì hiển thị.
  5. Quên bài nháp. Bài nháp không có trong danh sách public. Muốn xem trước phải gọi /api/post/:id bằng token admin, hoặc dựng route preview riêng.

Một mẹo nhỏ về ảnh

Ảnh bìa mình để SVG 1200×630, nặng dưới 4 KB. Vì là SVG nên nó sắc nét trên mọi màn hình và không cần pipeline resize. Nhược điểm là không dùng được cho thẻ og:image trên một số nền tảng, nên khi cần chia sẻ mình xuất thêm PNG.

# kiểm tra nhanh một URL sau khi deploy
curl -sI https://notice.vistaverde.top/ | head -5

Kết quả mong đợi là HTTP/2 200 kèm cf-cache-status: HIT ở lần gọi thứ hai. Nếu luôn là MISS, kiểm tra header Cache-Control của asset.

Tổng kết

Tổng thời gian dựng hệ thống này, tính cả phần CMS, là khoảng hai buổi tối. Phần khó không phải deploy mà là giữ cho nội dung đủ tốt để đáng deploy. Bài tiếp theo nói về phần đó: cách mình soạn thảo với AI mà vẫn giữ được giọng của mình.

Tham khảo