無需服務器！零成本搭建一個帶後台的個人博客，薅禿Cloudflare所有免費功能

作者：無辣的學習筆記
日期：2026年4月19日 上午12:40
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

利用Cloudflare免費服務搭建全棧博客，零成本實現帶後台的個人網站

整理版摘要

呢篇文章係由項目開發者撰寫，目標係幫新手解決搭建個人博客嘅痛點——WordPress需要伺服器成本，靜態博客又冇方便嘅後台。作者利用Cloudflare嘅R2、D1、KV、Queues等免費服務，結合GitHub Actions或Cloudflare Dashboard，做到完全零成本嘅全棧博客CMS。整體結論係方案功能齊全，維護簡單，而且幾乎用盡Cloudflare嘅免費額度。

文章詳盡列出部署前嘅準備工作，包括Fork倉庫、註冊Cloudflare賬號、創建各類資源（R2、D1、KV、Queues），同埋獲取API令牌同OAuth App。然後提供兩種部署路徑：方案一透過GitHub Actions自動構建，適合想要自動化更新嘅用戶；方案二直接喺Cloudflare Dashboard連接GitHub倉庫，適合想減少外部依賴嘅用戶。兩種方案都需要配置大量環境變量，但官方教程指引清晰。

進階部分包括圖片優化、郵件系統、人機驗證，同埋個性化配置。文章仲提供後續同步上游更新嘅方法同常見問題排查，例如環境變量配置錯誤係最常見嘅問題。呢篇文章適合任何想低成本建立自己博客嘅開發者，尤其係對Cloudflare生態有興趣嘅人。

  • 結論：用Cloudflare免費服務可以搭建完整全棧博客，無需伺服器，成本為零。
  • 方法：透過Fork倉庫、配置Cloudflare資源同環境變量，選擇GitHub Actions或Cloudflare Dashboard部署。
  • 差異：兩種部署方案主要分別在於自動化程度同配置位置，Actions適合自動更新，Dashboard直接管理。
  • 啟發：Cloudflare免費額度非常慷慨，R2、D1、KV、Queues等服務足以支撐一個博客。
  • 可行動點：按文章步驟準備基礎設施，填寫環境變量，部署後可在後台自定義網站。
值得記低
連結 github.com

flare-stack-blog GitHub 倉庫

項目源碼同部署教程

開啟
結構示例

內容片段

內容片段 text 
// 這裏只展示一部分{  "keep_vars": true, // 每次構建不清楚運行時變量  "routes": [{ "pattern": "blog.example.com", "custom_domain": true }],  "d1_databases": [{ "binding": "DB", "database_id": "你的-D1-ID", ... }],  "r2_buckets": [{ "binding": "R2", "bucket_name": "你的-R2-名稱", ... }],  "kv_namespaces": [{ "binding": "KV", "id": "你的-KV-ID", ... }]}
整理重點

點解要用Cloudflare做博客？

新人寫博客第一個門檻就係揀博客系統。

WordPress功能強大但需要伺服器

，而靜態博客如 Hexo 後台裝喺本地唔方便隨時修改。呢個項目基於

Cloudflare生態

，

用盡免費服務

，做到

全棧博客CMS

。

項目作者寫咗好詳細嘅部署教程，更新好頻繁，有問題可以去電報羣直接問。

整理重點

部署前嘅基礎設施清單

無論揀邊種部署方式，都要先

Fork倉庫

、註冊 Cloudflare 賬號（要綁定付款方式先用到 R2 同 Workers AI，但個人博客通常唔會產生費用），同埋將域名 DNS 託管到 Cloudflare。

  1. 1 Fork本倉庫，先有權限配置密鑰同觸發自動部署。
  2. 2 創建Cloudflare資源：R2存儲桶、D1數據庫、KV命名空間、Queues消息隊列（隊列名blog-queue）。
  3. 3 獲取Account ID同Zone ID。
  4. 4 創建API令牌：CDN刷新令牌（必填）同部署令牌（方案一需要）。
  5. 5 創建GitHub OAuth App，記錄Client ID同Secret。

注意：Cloudflare賬號要綁定付款方式先開通R2同Workers AI免費額度。

整理重點

兩種部署方案詳細對比

方案一用 GitHub Actions 自動部署，適合想要每次 push 自動更新嘅人；方案二直接喺 Cloudflare Dashboard 連接倉庫，適合想減少外部依賴嘅人。

方案一要喺 GitHub 倉庫 Settings -> Secrets and variables -> Actions 新增 Secrets 同 Variables；方案二要喺 Worker 嘅 Settings -> Variables and Secrets 入面分開填寫

構建時變量（VITE_開頭）

同運行時變量。

  • 方案一：GitHub Actions自動化，適合頻繁更新。
  • 方案二：Dashboard直接管理，適合唔想用Action嘅人。
整理重點

進階配置同日常維護

進階配置可以開啓 Cloudflare Images 圖片轉換，每月 5000 次免費；亦可以配置 SMTP 郵件系統（用 Resend 做例子）或者人機驗證 Turnstile。

圖片轉換每月5000次免費，能大幅提升圖片加載速度。

郵件系統支援密碼登錄、驗證碼、評論回覆通知。

個性化配置方面，站點信息可以喺後台改，但主題要改環境變量。更新好簡單：入你 Fork 嘅倉庫，Sync fork -> Update branch，就會自動觸發部署。

由於所有個性化配置抽離到環境變量，直接Sync fork通常唔會有合併衝突。

  1. 1 同步上游：後台提示新版本時，去Fork倉庫Sync fork。
  2. 2 自動部署：方案一GitHub Actions會自動感應；方案二Cloudflare自動檢測。
  3. 3 常見問題：部署成功但打唔開？檢查Console同Worker嘅Live Logs，多數係環境變量問題。

前言

新人寫博客第一個門檻就係揀一個博客系統，例如我而家用WordPress功能強大但需要部署到伺服器上，靜態博客系統如Hexo可以將前端發佈到GitHub pages，但後端裝喺本地唔方便隨時修改。呢個項目係基於Cloudflare生態嘅全棧現代化博客CMS，比較有趣嘅係作者幾乎用曬Cloudflare嘅所有免費服務，功能都好強大。 作者嘅部署教程寫得好詳細，我就直接照搬咗，項目更新好頻繁，有任何問題都可以喺電報羣直接問作者。 項目地址：https://github.com/du2333/flare-stack-blog

項目說明

  1. 預設界面圖片
  2. 作者用嘅fuwari主題圖片
  3. 核心功能圖片
  4. Cloudflare 生態圖片
  5. 核心配置預覽開始之前，先睇嚇呢兩種方式嘅分別：圖片兩種嘅額度都好慷慨，根本用唔完，其中GitHub Actions對於公開倉庫係免費，2000分鐘係對於私有倉庫嘅限制。

第一階段：前期準備（通用）

無論揀邊種部署方式，你都需要先準備好呢啲「基礎設施」。

  1. Fork 本倉庫（必備）呢個係所有部署嘅第一步。㩒倉庫右上角嘅 Fork 掣，將項目源碼複製到你嘅 GitHub 帳號度。圖片

    只有 Fork 咗落自己嘅帳號，你先有權限設定密鑰同觸發自動部署。

  2. 註冊同啓用服務
    • Cloudflare 帳號：注意需要綁定付款方式先可以啓用免費額度充足嘅 R2 同 Workers AI 服務（個人博客通常唔會產生費用）。
    • 域名託管：將你嘅域名 DNS 託管到 Cloudflare，呢個係使用免費 CDN 同自動化部署嘅前提。
  3. 建立 Cloudflare 資源 喺 Cloudflare Dashboard 度建立以下資源並記低佢哋嘅名稱/ID：
    • R2 儲存桶：用嚟儲存圖片同靜態資源（記低儲存桶名稱）。
    • D1 數據庫：用嚟儲存文章同設定（記低 Database ID）。
    • KV 命名空間：用嚟快取（記低 Namespace ID）。
    • Queues 消息隊列：用嚟處理異步任務（隊列名稱係 blog-queue）。
  4. 獲取核心憑證（IDs）你需要以下兩個 ID 貫穿成個部署過程：
    • Account ID：喺域名嘅概覽頁右邊睇。
    • Zone ID：喺域名嘅概覽頁右邊睇。
    • Account Home -> 你嘅域名圖片
  5. 建立 API 令牌（Token）我哋需要賦予部署腳本操作你帳户嘅權限。㩒右上角 頭像 -> 我嘅個人資料 -> API 令牌 -> 建立令牌。A. CDN 刷新令牌（必填）
    • 模板：使用「編輯區域 DNS」模板。
    • 權限：區域 -> 清除快取 -> 清除。
    • 資源：包括 -> 所有區域（或指定域名）。
    • 用途：應用部署後自動強制更新 CDN 快取。圖片B. 部署令牌（僅方案一需要）
    • 模板：使用「編輯 Cloudflare Workers」模板。
    • 權限：添加更多 -> D1 -> 編輯。
    • 資源：包括 -> 所有區域（或指定域名）
    • 用途：允許 GitHub Actions 遠程部署代碼同執行數據庫遷移。圖片
  6. 建立 GitHub OAuth App 為咗實現 GitHub 登入功能：
    1. 前往 GitHub Settings -> Developer Settings -> OAuth Apps -> New OAuth App。
    2. Homepage URL: https://<你的域名>
    3. Authorization callback URL: https://<你的域名>/api/auth/callback/github
    4. 建立後記低 Client ID，並生成一個新嘅 Client Secret。圖片

第二階段：揀部署方案

方案一：GitHub Actions 自動部署

通過 GitHub 嘅伺服器進行構建同分發。

  1. 啓用 Actions 預設情況下，GitHub 為咗安全考慮，唔會喺 Fork 咗嘅倉庫度自動啓用 Actions。需要喺倉庫設定度啓用圖片
  2. 設定倉庫變量 喺 GitHub 倉庫度，入去 Settings -> Secrets and variables -> Actions，點擊 New repository secret 加入以下變量：A. 必填部署變量設定（Secrets - CI/CD）
    • CLOUDFLARE_API_TOKEN：步驟 5 中嘅部署令牌
    • CLOUDFLARE_ACCOUNT_ID：你嘅 Account ID
    • D1_DATABASE_ID：D1 數據庫 ID
    • KV_NAMESPACE_ID：KV 命名空間 ID
    • BUCKET_NAME：R2 桶名稱B. 必填運行時設定（Secrets - 運行時）
    • BETTER_AUTH_SECRET：終端執行 openssl rand -hex 32 生成
    • BETTER_AUTH_URL：應用 URL（例如 https://blog.example.com）
    • ADMIN_EMAIL：管理員電郵
    • GH_CLIENT_ID：GitHub OAuth Client ID
    • GH_CLIENT_SECRET：GitHub OAuth Client Secret
    • CLOUDFLARE_ZONE_ID：你嘅 Zone ID
    • CLOUDFLARE_PURGE_API_TOKEN：步驟 5 中嘅刷新令牌
    • DOMAIN：博客域名（例如 blog.example.com）C. 選填運行時設定
    • PAGEVIEW_SALT：瀏覽量統計嘅訪客匿名化 salt，用嚟增強訪客匿名化，終端執行 openssl rand -hex 16 生成，或者任意 16 位左右嘅字符。
    • GH_TOKEN：用嚟檢查版本更新，由於多個 Workers 共享一個 IP，好大機會導致 GitHub 限流，設定呢個 token 就可以避免限流，去 New Fine-grained Personal Access Token 設定，預設權限就得，過期時間自定義：https://github.com/settings/personal-access-tokens/new
    • UMAMI_SRC：Umami 客戶端埋點代理 URL（例如 https://cloud.umami.is）
    • VITE_UMAMI_WEBSITE_ID：Umami Website ID（客戶端埋點），呢個同時係運行時變量同構建時變量，不過要填 Variables 唔係 Secrets，見下面
  3. 觸發部署 入去 GitHub 倉庫嘅 Actions 標籤頁，啓用並手動執行 Deploy 工作流。之後你每次推送代碼到倉庫，系統都會自動更新博客。

方案二：Cloudflare Dashboard 直接部署

直接喺 Cloudflare Workers 上連接倉庫。

  1. 修改設定檔 喺本地或 GitHub 網頁端將 wrangler.example.jsonc 複製並重新命名為 wrangler.jsonc，取代入面嘅佔位符，唔好自己刪減 binding，除非你知道喺改啲咩
// 這裏只展示一部分
{
  "keep_vars": true, // 每次構建不清楚運行時變量
  "routes": [{ "pattern": "blog.example.com", "custom_domain": true }],
  "d1_databases": [{ "binding": "DB", "database_id": "你的-D1-ID", ... }],
  "r2_buckets": [{ "binding": "R2", "bucket_name": "你的-R2-名稱", ... }],
  "kv_namespaces": [{ "binding": "KV", "id": "你的-KV-ID", ... }]
}
  1. 建立並連接工程
    • 喺構建設定中加入 BUN_VERSION: 1.3.5。
    • 加入所有以 VITE_ 開頭嘅前端變量。
    • Framework preset: None
    • Build command: bun run build
    • Deploy command: bun run deploy
    1. 喺 Cloudflare Dashboard 入去 Workers 同 Pages -> 建立 -> 連接到 Git。
    2. 揀你嘅倉庫，並設定構建設定：
    3. 加入環境變量：
  2. 設定運行時變量 部署完成後，入去呢個 Worker 嘅 設定 -> 變量 -> 機密，點擊 加入機密，填入 BETTER_AUTH_SECRET、GITHUB_CLIENT_ID、ADMIN_EMAIL 等敏感設定，具體變量詳情請睇方案一嘅運行時變量表。注意變量名：喺 Cloudflare Dashboard 度，Github 嘅變量名必須使用全稱：
    • GH_CLIENT_ID → GITHUB_CLIENT_ID
    • GH_CLIENT_SECRET → GITHUB_CLIENT_SECRET
    • GH_TOKEN → GITHUB_TOKEN

CDN 快取：方案二由於唔經過 GitHub Actions，唔會自動清除快取。每次部署後，請喺博客後台「設定」頁面手動㩒「清除 CDN 快取」，如果仲未註冊管理員帳號，出現網頁樣式遺失無法導航，去 cloudflare 面板入面清除快取

第三階段：可選進階設定

  1. 圖片優化（Cloudflare Images）喺管理頁為你嘅域名開啓圖片轉換。每月 5000 次免費轉換額度，能夠極大提升博客圖片嘅加載速度。圖片
  2. 郵件系統 支援 SMTP 郵件，以 Resend 為例 註冊 Resend 並綁定域名，推薦綁定子域名。https://resend.com/
    • host: smtp.resend.com
    • port: 465
    • user: resend
    • password: 你的api key
    • 攞到 API Key 之後，填入博客後台嘅「設定」頁面。
    • 開啓後，你嘅博客將支援：密碼登入、驗證碼安全校驗、評論回覆電郵通知。
  3. 人機驗證（Cloudflare Turnstile）去 Cloudflare Turnstile 頁面建立一個 Widget，記低 site key 同 secret key 填寫
    • VITE_TURNSTILE_SITE_KEY 構建時變量，倉庫變量
    • TURNSTILE_SECRET_KEY 運行時變量，倉庫機密 填入重新部署生效

個性化設定

目前除咗主題需要設定環境變量，其他嘅站點資訊都可以喺後台個性化設定板塊自行設定

  • GitHub Actions 部署嘅用戶，需要設定新嘅THEME變量（非機密）
  • Workers Build 部署嘅用戶，需要喺構建時變量度設定（非運行時變量）圖片

第四階段：後續維護同更新

同步上游更新

當管理後台提示有新版本時（或定期檢查 GitHub 倉庫更新），你只需要：

  1. 入去你 Fork 咗嘅倉庫主頁。
  2. 點擊 Sync fork -> Update branch。
  3. 自動部署：
    • 方案一：GitHub Actions 會感應到代碼更新並自動觸發部署。
    • 方案二：Cloudflare 會自動檢測到 GitHub 嘅新提交並開始構建。

關於合併衝突：呢個項目將所有個性化設定都抽離咗去環境變量度，直接同步上游代碼通常唔會產生任何合併衝突。

常見問題

  1. 部署成功，但網頁打唔開，某啲操作報錯？點樣排查問題？ 如果部署過程冇報錯，但訪問時出現錯誤（例如 500 錯誤或白屏），通常按以下步驟排查：
    • 檢查控制枱：按下 F12 打開瀏覽器開發者工具，睇 Console 標籤頁有冇報錯資訊。
    • 睇即時日誌：喺 Cloudflare Dashboard 入去對應嘅 Worker 項目，㩒 Observability（觀測） -> Live。保持呢個頁面打開嘅同時訪問你嘅博客，就可以捕獲即時嘅報錯日誌，通常可以直接睇到係邊個環境變量缺失或設定錯誤。
    • 檢查環境變量：絕大多數打唔開嘅情況都係因為環境變量未正確設定。圖片
  2. 構建時變量 vs 運行時變量有咩分別？ 由於呢個項目係全棧項目，環境變量嘅使用場景有所不同：
    • 構建時變量：喺連接 GitHub 倉庫初期嘅「高級選項」度設定；如果項目已經建立，可以喺 Worker 嘅 Settings -> Build -> Variables 度設定。圖片圖片
    • 構建時變量：由 VITE_ 前綴開頭。呢啲變量會喺項目編譯打包時「硬編碼」入客戶端腳本度。如果呢啲變量設定錯誤，必須重新觸發部署構建先至生效。
    • 運行時變量：伺服器端代碼喺運行時讀取。呢啲變量通常喺服務端執行邏輯度起作用。唔同方案下嘅設定方式：
    • 方案一（GitHub Actions）： 你只需要喺 GitHub 倉庫嘅 Settings -> Secrets and variables -> Actions 度統一設定所有 Secrets 同 Variables。部署流水線會自動處理佢哋嘅歸類。
    • 方案二（Cloudflare Dashboard）：
    • 運行時變量：喺 Worker 嘅 Settings -> Variables and Secrets 度設定。圖片
  3. 點樣設定統計功能？ 系統內置咗瀏覽量統計功能。 此外，你仲可以選擇使用 Umami 進行客戶端埋點統計，只需要設定 UMAMI_SRC 和 VITE_UMAMI_WEBSITE_ID：
UMAMI_SRC=https://cloud.umami.is
VITE_UMAMI_WEBSITE_ID=your-website-id
  1. 發佈咗文章，點解前台唔顯示出嚟？ 只有當你將狀態改成「已發佈」同埋發佈時間早過當前時間嘅情況下，發佈按鈕先會調用後台任務將文章發佈到前台。如果發佈時間喺未來，後台任務就會喺未來時間點執行
  2. 對於已經發佈嘅文章，我想下架佢點算？ 將狀態從「已發佈」改成「草稿」，發佈按鈕就會變成下架按鈕

    部署問題請去Issues（https://github.com/du2333/flare-stack-blog/issues）揾相關問題，或者建立新嘅 Issue

  3. 點樣改善國內嘅訪問速度？ 首先唔理你用咩方式攞優選嘅 IP 定係 CNAME，做好你嘅博客域名嘅 DNS 解析之後，假設你嘅博客域名係blog.example.com，使用路由方式接管 worker 流量，wrangler.jsonc入面可以改成：
{
  "routes": [{ "pattern": "blog.example.com/*", "zone_name": "example.com" }]
}

使用倉庫內置 GitHub Actions 部署時，唔使手動改 wrangler.jsonc：

  • 默認：custom_domain
  • 設定倉庫變量（非機密） ROUTE=1：自動切換到 routes 路由模式
  • pattern 自動使用 ${DOMAIN}/*
  • zone_name 默認從 DOMAIN 推導；如果有子域單獨託管場景，可以額外設定 ZONE_NAME
圖片

前言

新人寫博客第一個門檻就是挑選一個博客系統，比如我現在用WordPress功能強大但需要部署到服務器上，靜態博客系統如Hexo可以把前端發佈到GitHub pages，但後端裝在本地不方便隨時修改。這個項目是基於Cloudflare生態的全棧現代化博客CMS，比較有意思的是作者幾乎用到了Cloudflare的所有免費服務，功能也很強大。 作者的部署教程寫的非常詳細，我就直接照搬了，項目更新很頻繁，有任何問題都可以在電報羣直接詢問作者。 項目地址：https://github.com/du2333/flare-stack-blog

項目說明

  1. 默認界面圖片
  2. 作者用的fuwari主題圖片
  3. 核心功能圖片
  4. Cloudflare 生態圖片
  5. 核心配置預覽在開始之前，先看看這兩種方式的差異：圖片兩種的額度都挺慷慨的，根本用不完，其中GitHub Actions對於公開倉庫是免費用，2000分鐘是對於私有倉庫的限制。

第一階段：前置準備（通用）

無論選擇哪種部署方式，你都需要先準備好這些「基礎設施」。

  1. Fork 本倉庫 (必備) 這是所有部署的第一步。點擊倉庫右上角的 Fork 按鈕，將項目源碼克隆到你自己的 GitHub 賬號下。圖片

    只有 Fork 到自己的賬號，你才有權配置密鑰和觸發自動部署。

  2. 註冊與啓用服務
    • Cloudflare 賬號：注意需綁定付款方式以啓用免費額度充足的 R2 和 Workers AI 服務（個人博客通常不會產生費用）。
    • 域名託管：將你的域名 DNS 託管到 Cloudflare，這是使用免費 CDN 和自動化部署的前提。
  3. 創建 Cloudflare 資源 在 Cloudflare Dashboard 中創建以下資源並記錄其名稱/ID：
    • R2 存儲桶：用於存儲圖片和靜態資源（記錄存儲桶名稱）。
    • D1 數據庫：用於存儲文章和配置（記錄 Database ID）。
    • KV 命名空間：用於緩存（記錄 Namespace ID）。
    • Queues 消息隊列：用於處理異步任務（隊列名稱為 blog-queue）。
  4. 獲取核心憑證 (IDs) 你需要以下兩個 ID 貫穿整個部署過程：
    • Account ID：域名的概覽頁右側查看。
    • Zone ID：域名的概覽頁右側查看。
    • Account Home -> 你的域名圖片
  5. 創建 API 令牌 (Token) 我們需要賦予部署腳本操作你賬户的權限。點擊右上角 頭像 -> 我的個人資料 -> API 令牌 -> 創建令牌。A. CDN 刷新令牌 (必填)
    • 模板：使用「編輯區域 DNS」模板。
    • 權限：區域 -> 清除緩存 -> 清除。
    • 資源：包括 -> 所有區域（或指定域名）。
    • 用途：應用部署後自動強制更新 CDN 緩存。圖片B. 部署令牌 (僅方案一需要)
    • 模板：使用「編輯 Cloudflare Workers」模板。
    • 權限：添加更多 -> D1 -> 編輯。
    • 資源：包括 -> 所有區域（或指定域名）
    • 用途：允許 GitHub Actions 遠程部署代碼和執行數據庫遷移。圖片
  6. 創建 GitHub OAuth App 為了實現 GitHub 登錄功能：
    1. 前往 GitHub Settings -> Developer Settings -> OAuth Apps -> New OAuth App。
    2. Homepage URL: https://<你的域名>
    3. Authorization callback URL: https://<你的域名>/api/auth/callback/github
    4. 創建後記錄 Client ID，並生成一個新的 Client Secret。圖片

第二階段：選擇部署方案

方案一：GitHub Actions 自動部署

通過 GitHub 的服務器進行構建和分發。

  1. 啓用Actions 默認情況下，GitHub 為了安全考慮，不會在 Fork 的倉庫中自動啓用 Actions。需要在倉庫設置裏啓用圖片
  2. 配置倉庫變量 在 GitHub 倉庫中，進入 Settings -> Secrets and variables -> Actions，點擊 New repository secret 添加以下變量：A. 必填部署變量配置（Secrets - CI/CD）
    • CLOUDFLARE_API_TOKEN：步驟 5中 的部署令牌
    • CLOUDFLARE_ACCOUNT_ID：你的 Account ID
    • D1_DATABASE_ID：D1 數據庫 ID
    • KV_NAMESPACE_ID：KV 命名空間 ID
    • BUCKET_NAME：R2 桶名稱B. 必填運行時配置（Secrets - 運行時）
    • BETTER_AUTH_SECRET：終端運行 openssl rand -hex 32 生成
    • BETTER_AUTH_URL：應用 URL（如 https://blog.example.com）
    • ADMIN_EMAIL：管理員郵箱
    • GH_CLIENT_ID：GitHub OAuth Client ID
    • GH_CLIENT_SECRET：GitHub OAuth Client Secret
    • CLOUDFLARE_ZONE_ID：你的 Zone ID
    • CLOUDFLARE_PURGE_API_TOKEN：步驟 5 中的刷新令牌
    • DOMAIN：博客域名（如 blog.example.com）C. 選填運行時配置
    • PAGEVIEW_SALT：瀏覽量統計的訪客匿名化 salt，用於增強訪客匿名化，終端運行 openssl rand -hex 16 生成，或者任意16位左右的字符。
    • GH_TOKEN：用於檢查版本更新，由於多個Workers共享一個IP，很大概率導致GitHub限流，配置此token就可以避免限流，前往New Fine-grained Personal Access Token設置，默認權限即可，過期時間自定義：https://github.com/settings/personal-access-tokens/new
    • UMAMI_SRC：Umami 客戶端埋點代理 URL（如 https://cloud.umami.is）
    • VITE_UMAMI_WEBSITE_ID：Umami Website ID（客戶端埋點），這個既是運行時變量，也是構建時變量，不過要填Variables不是Secrets，見下
  3. 觸發部署 進入 GitHub 倉庫的 Actions 標籤頁，啓用並手動運行 Deploy 工作流。後續你每次推送代碼到倉庫，系統都會自動更新博客。

方案二：Cloudflare Dashboard 直接部署

直接在 Cloudflare Workers上連接倉庫。

  1. 修改配置文件 在本地或 GitHub 網頁端將 wrangler.example.jsonc 複製並重命名為 wrangler.jsonc，替換其中的佔位符，不要自行刪減 binding，除非你知道在改什麼
// 這裏只展示一部分
{
  "keep_vars": true, // 每次構建不清楚運行時變量
  "routes": [{ "pattern": "blog.example.com", "custom_domain": true }],
  "d1_databases": [{ "binding": "DB", "database_id": "你的-D1-ID", ... }],
  "r2_buckets": [{ "binding": "R2", "bucket_name": "你的-R2-名稱", ... }],
  "kv_namespaces": [{ "binding": "KV", "id": "你的-KV-ID", ... }]
}
  1. 創建並連接工程
    • 在構建配置中添加 BUN_VERSION: 1.3.5。
    • 添加所有以 VITE_ 開頭的前端變量。
    • Framework preset: None
    • Build command: bun run build
    • Deploy command: bun run deploy
    1. 在 Cloudflare Dashboard 進入 Workers 和 Pages -> 創建 -> 連接到 Git。
    2. 選擇你的倉庫，並配置構建設置：
    3. 添加環境變量：
  2. 配置運行時變量 部署完成後，進入該 Worker 的 設置 -> 變量 -> 機密，點擊 添加機密，填入 BETTER_AUTH_SECRET、GITHUB_CLIENT_ID、ADMIN_EMAIL 等敏感配置，具體變量詳見方案一的運行時變量表格。注意變量名：在 Cloudflare Dashboard 中，Github的變量名必須使用全稱：
    • GH_CLIENT_ID → GITHUB_CLIENT_ID
    • GH_CLIENT_SECRET → GITHUB_CLIENT_SECRET
    • GH_TOKEN → GITHUB_TOKEN

CDN 緩存：方案二由於不經過 GitHub Actions，不會自動清除緩存。每次部署後，請在博客後台「設置」頁面手動點擊「清除 CDN 緩存」，如果還沒註冊管理員賬號，出現網頁樣式丟失無法導航，前往cloudflare面板裏清除緩存

第三階段：可選進階配置

  1. 圖片優化 (Cloudflare Images) 在管理頁為你的域名開啓 圖片轉換。每月 5000 次免費轉換額度，能極大提升博客圖片的加載速度。圖片
  2. 郵件系統 支持SMTP郵件，以Resend為例 註冊 Resend 並綁定域名，推薦綁定子域名。https://resend.com/
    • host: smtp.resend.com
    • port: 465
    • user: resend
    • password: 你的api key
    • 獲取 API Key 後，填入博客後台的「設置」頁面。
    • 開啓後，你的博客將支持：密碼登錄、驗證碼安全校驗、評論回覆郵件通知。
  3. 人機驗證 (Cloudflare Turnstile) 前往Cloudflare Turnstile頁面創建一個Widget，記錄site key和secret key 填寫
    • VITE_TURNSTILE_SITE_KEY 構建時變量，倉庫變量
    • TURNSTILE_SECRET_KEY 運行時變量，倉庫機密 填入重新部署生效

個性化配置

目前除了主題需要配置環境變量，其他的站點信息都可以在後台個性化配置板塊自行配置

  • Github Actions部署的用戶，需要設置新的THEME變量（非機密）
  • Workers Build部署的用戶，需要在構建時變量裏設置（非運行時變量）圖片

第四階段：後續維護與更新

同步上游更新

當管理後台提示有新版本時（或定期檢查 GitHub 倉庫更新），你只需：

  1. 進入你 Fork 的倉庫主頁。
  2. 點擊 Sync fork -> Update branch。
  3. 自動部署：
    • 方案一：GitHub Actions 會感應到代碼更新並自動觸發部署。
    • 方案二：Cloudflare 會自動檢測到 GitHub 的新提交併開始構建。

關於合併衝突：該項目將所有個性化配置都抽離到了環境變量中，直接同步上游代碼通常不會產生任何合併衝突。

常見問題

  1. 部署成功，網頁卻打不開，某些操作報錯？如何排查問題？ 如果部署過程沒報錯，但訪問時出現錯誤（如 500 錯誤或白屏），通常按以下步驟排查：
    • 檢查控制枱：按下 F12 打開瀏覽器開發者工具，查看 Console 標籤頁是否有報錯信息。
    • 查看實時日誌：在 Cloudflare Dashboard 進入對應的 Worker 項目，點擊 Observability (觀測) -> Live。保持該頁面打開的同時訪問你的博客，即可捕獲實時的報錯日誌，通常能直接看到是哪個環境變量缺失或配置錯誤。
    • 檢查環境變量：絕大多數打不開的情況都是因為環境變量未正確設置。圖片
  2. 構建時變量 vs 運行時變量有什麼區別？ 由於該項目是全棧項目，環境變量的使用場景有所不同：
    • 構建時變量：在連接 GitHub 倉庫初期的「高級選項」中配置；若項目已創建，可在 Worker 的 Settings -> Build -> Variables 中配置。圖片圖片
    • 構建時變量：由 VITE_ 前綴開頭。這些變量會在項目編譯打包時「硬編碼」進客戶端腳本中。如果這些變量配置錯誤，必須重新觸發部署構建才能生效。
    • 運行時變量：服務器端代碼在運行時讀取。這些變量通常在服務端執行邏輯中起作用。不同方案下的配置方式：
    • 方案一 (GitHub Actions)： 你只需要在 GitHub 倉庫的 Settings -> Secrets and variables -> Actions 中統一配置所有的 Secrets 和 Variables。部署流水線會自動處理它們的歸類。
    • 方案二 (Cloudflare Dashboard)：
    • 運行時變量：在 Worker 的 Settings -> Variables and Secrets 中配置。圖片
  3. 如何配置統計功能？ 系統內置了瀏覽量統計功能。 此外，你還可以選擇使用 Umami 進行客戶端埋點統計，只需設置 UMAMI_SRC 和 VITE_UMAMI_WEBSITE_ID：
UMAMI_SRC=https://cloud.umami.is
VITE_UMAMI_WEBSITE_ID=your-website-id
  1. 發佈了文章，為何前台不顯示出來？ 只有當你把狀態改成"已發佈"以及發佈時間早於當前時間的情況下，發佈按鈕才會調用後台任務把文章發佈到前台 如果發佈時間在未來，則後台任務會在未來時間點執行
  2. 對於已經發布的文章，我想下架它怎麼辦？ 把狀態從"已發佈"改成"草稿"，發佈按鈕就會變成下架按鈕

    部署問題請前往Issues(https://github.com/du2333/flare-stack-blog/issues)尋找相關問題，或者創建新的Issue

  3. 如何改善國內的訪問速度？ 首先不管你以什麼方式獲取優選的ip還是cname，做好你的博客域名的DNS解析之後，假設你的博客域名是blog.example.com，使用路由方式接管worker流量，wrangler.jsonc裏可改成：
{
  "routes": [{ "pattern": "blog.example.com/*", "zone_name": "example.com" }]
}

使用倉庫內置 GitHub Actions 部署時，不必手動改 wrangler.jsonc：

  • 默認：custom_domain
  • 設置倉庫變量（非機密） ROUTE=1：自動切到 routes 路由模式
  • pattern 自動使用 ${DOMAIN}/*
  • zone_name 默認從 DOMAIN 推導；如有子域單獨託管場景，可額外設置 ZONE_NAME
圖片