Quartz 4

cloudflare-deploy

5 min read

Cloudflare 部署步驟 — asurada.suxi.world

目標:把 site/ 經 Cloudflare Pages 部署成 asurada.suxi.world, 前面套 Cloudflare Access,policy 只允許 simon@suxi.world 進。 全程在 Cloudflare dashboard 點完。約 15~20 分鐘。

前提:

  • suxi.world 主網域已在 Cloudflare(同一個帳號)。
  • suxi-learning 已 push 到 github.com/sadwx/suxi-learning。
  • site/ 在 repo 內可本機 build(cd site && npm run build 跑得過)。

Step 1 — Cloudflare Pages 連 GitHub

  1. 開 https://dash.cloudflare.com/ → 左欄 Workers & Pages → Create → 切到 Pages 分頁 → Connect to Git。

  2. 第一次用會要 authorize Cloudflare 讀你的 GitHub。只授權 suxi-learning 這個 repo(不要 all repos)。

  3. 選 repo sadwx/suxi-learning,Begin setup。

  4. Build configurations 填:

    欄位值
    Project namesuxi-learning (這會變成 suxi-learning.pages.dev,等下會綁自訂網域所以不重要)
    Production branchmain
    Framework presetNone
    Build commandnpm install && node sync.mjs && npx quartz build
    Build output directorypublic
    Root directory (advanced)site
    Environment variablesNODE_VERSION = 22

  5. 按 Save and Deploy。第一次 build 約 1~2 分鐘。

  6. Build 完會給你一個 https://suxi-learning.pages.dev。打開應該看到首頁(此時尚無 Access 保護,先確認部署成功)。

build 失敗排查:點該 deployment 看 log。常見問題是 Node 版本 — Cloudflare 預設 NODE_VERSION=18,Quartz 要 22+,確認上面 env var 有設。

Step 2 — 綁自訂網域 asurada.suxi.world

  1. 在剛建好的 Pages project 內 → Custom domains → Set up a custom domain。
  2. 輸入 asurada.suxi.world → Continue。
  3. 既然 suxi.world 在同一 Cloudflare 帳號,Cloudflare 會自動建好 CNAME asurada → suxi-learning.pages.dev,並接管 SSL。Activate domain。
  4. 等 30 秒~2 分鐘 DNS 與 cert 生效。試開 https://asurada.suxi.world,應該看到網站。
  5. 此時整個世界都看得到 — 立刻去下一步把 Access 鎖上。

Step 3 — Cloudflare Access(把網站鎖給只有你)

3a 啟用 Zero Trust(若帳號還沒啟用過)

  1. Dashboard 左欄 Zero Trust。
  2. 第一次點會要你建 team name(隨便取,例如 suxi)。Free plan,不用刷卡。

3b 設定 One-time-PIN(email)做為登入方式

  1. Zero Trust dashboard → Settings → Authentication → Login methods → Add new。
  2. 選 One-time PIN(若未自動啟用)→ Save。
  3. 這個方法不用任何 OAuth 設定。Access 會直接寄 6 位數驗證碼到你信箱。

3c 建 Access Application 保護 asurada.suxi.world

  1. Zero Trust dashboard → Access → Applications → Add an application。

  2. 選 Self-hosted。

  3. Application Configuration:

    欄位值
    Application nameasurada
    Session duration24 hours(或更長,看你想隔多久重登一次)
    Application domainasurada.suxi.world
    Path(留空,代表整站)

    下一步。

  4. Identity providers:勾 One-time PIN。下一步。

  5. Policies(限定誰能進):

    • Policy name: Owner only
    • Action: Allow
    • Session duration: Use application default(繼承上面)
    • Include rule: Emails → 填 simon@suxi.world。
    • (其他規則不加)
    • Save。

  6. 一路 Next → Add application。

3d 驗收

  1. 開無痕視窗(避免 cookie 干擾)→ https://asurada.suxi.world。
  2. 應該跳轉到 Cloudflare Access 登入頁,要你輸入 email。
  3. 填 simon@suxi.world → Send me a code。
  4. 信箱會收到 6 碼驗證碼。填回去 → 過關 → 看到網站。
  5. 用其他 email 試,應該收得到「Access denied」訊息。

Step 4 — 上線後的日常

  • 改 vault 內容 → push → 自動 redeploy:每次 git push origin main,CF Pages 自動 build,1~2 分鐘後 asurada.suxi.world 更新。
  • Build 失敗會 email 你(Pages 預設行為)。
  • 想開 preview branch:git push origin <feature-branch>,Pages 會自動 build 該 branch 的 preview deployment(但 Access 預設只保護 prod 網域,preview 網域是 public — 若敏感請另外加 Access policy)。
  • Build 額度:每月 500 次。你每天 push 10 次也只用 300。

Step 5 — 後續可能想做的事(暫不做)

  • 改 OTP 為 GitHub OAuth:Zero Trust → Authentication → Add IdP → GitHub。比 OTP 快(信任你已登入的 GitHub)。要在 GitHub 開 OAuth App。
  • 手機 widget:讓網站變 PWA(Quartz 有支援)→ 加到主畫面。
  • Backlinks / Graph view:Quartz layout 預設有,可在 quartz.layout.ts 開關。
  • 自訂 favicon / theme 色:quartz.config.ts 的 theme.colors。
  • 加 analytics:不建議。Access 後面 + 自己一個人用,沒有分析意義。

反向操作 — 如果想撤掉部署

  1. Cloudflare Pages → project → Settings → Delete project(會解除 custom domain 綁定)。
  2. Zero Trust → Access → Applications → 刪 asurada application。
  3. DNS:Cloudflare DNS 自動清掉 CNAME(因為 Pages project 沒了)。
  4. (本機)rm -rf site/,改 root .gitignore 拿掉 site/* 那段。

Graph View

Backlinks