Ctrl K

Cloudflare Pages：PCE 實作進度（private GitHub repo）

Private GitHub 無法使用 GitHub Pages 時，可改由 Cloudflare Pages 托管 docs/（靜態站根目錄＝docs/，與本機 npm run serve:status 相同）。

預設網址（建立專案後）：https://pceguitw-status.pages.dev/html/index.html 根路徑 / 經 index.html 導向總覽。

若 Workers Builds 一直 Authentication error [code: 10000]（推薦改這條）

Workers Builds（Worker 底下的「組建／部署命令」）的建置權杖，常無法讓 wrangler pages deploy 通過認證。請二選一，不要兩邊同時自動部署：

方案甲：GitHub Actions（建議，約 5 分鐘）

  1. Cloudflare 建立 API Token（Create Custom Token）
    • Permissions：Account → Cloudflare Pages → Edit；Account → Account Settings → Read
    • Account resources：Include → 你的 Account
    • 建立後只顯示一次，複製 token
  2. Account ID：Dashboard 首頁右側 Account ID（32 字元）
  3. GitHub repo → Settings → Secrets and variables → Actions → New repository secret
    • CLOUDFLARE_API_TOKEN = 上一步 token
    • CLOUDFLARE_ACCOUNT_ID = Account ID
  4. Cloudflare 端：Worker/Pages 的 Builds 裡清空部署命令或關閉自動建置（避免和 GitHub 搶 deploy、繼續 10000）。
  5. GitHub → Actions → Deploy status docs (Cloudflare Pages) → Run workflow（或 push docs/ 觸發）。
  6. 成功後開 https://pceguitw-status.pages.dev/html/index.html

本機自測 token（token 勿貼給他人）：

export CLOUDFLARE_API_TOKEN='…'
export CLOUDFLARE_ACCOUNT_ID='…'
sh scripts/verify-cloudflare-pages-auth.sh
npm run deploy:status-pages

方案乙：Cloudflare Pages（不是 Worker Builds）Connect Git

Workers & Pages → Create → Pages → Connect to Git（畫面標題要是 Pages，不是 Worker 的 Builds）。

欄位值
Build commandnpm run build:status-html
Build output directorydocs
部署命令無此欄（Pages 會自動上傳 output，不要填 wrangler pages deploy）

路徑 A：Cloudflare Pages Connect Git（細節）

  1. 登入 Cloudflare Dashboard → Workers & Pages → Create → Pages → Connect to Git。
  2. 授權 GitHub，選 repo com.netsuite.pceguitw（private 可連）。
  3. Build settings（與 repo 根目錄 wrangler.toml 一致）：
欄位值
Production branchmaster
Framework presetNone
Build commandnpm run build:status-html
Build output directorydocs
Root directory/（預設）
  1. Environment variables（Build）建議加：NODE_VERSION = 22（或依 .nvmrc）。
  2. Save and Deploy。之後每次 push 到 production branch，Cloudflare 會重建並發佈。

專案名稱：Dashboard 可設為 pceguitw-status，與 wrangler.toml 的 name 一致；若改名，請同步改 scripts/build-module-status-html.js 內的 CLOUDFLARE_PAGES_* URL 並重建 HTML。

Workers Builds 介面（組建／部署命令）

若畫面是 組建命令、部署命令、根目錄、建置權杖：

欄位建議值說明
根目錄/（repo 根）勿填 docs。根目錄＝docs 時，pages deploy docs 會找 docs/docs/，部署必失敗；且 wrangler.toml、.nvmrc 在 repo 根
組建命令npm run build:status-html產生 docs/html/*.html
部署命令npx wrangler pages deploy docs --project-name=pceguitw-status上傳 repo 下的 docs/；勿用 npx wrangler deploy
建置變數見下表僅「建置權杖」常不夠，Wrangler 還要 Account ID
建置權杖pceguitw-status build token 等權限：Account → Cloudflare Pages → Edit（與 Workers 建置若分開，Pages Edit 必開）

建置變數（建議兩項都加）

名稱值
NODE_VERSION22（與 .nvmrc 一致）
CLOUDFLARE_ACCOUNT_IDDashboard 首頁右側 Account ID（32 字元 hex）

建置權杖通常會注入 CLOUDFLARE_API_TOKEN；若 log 出現 Missing account ID 或 Authentication error，多半是缺 Account ID 或 token 權限不足。

簡化（單一組建、部署留空）：若介面允許只跑一段命令，可設組建命令為 npm run deploy:status-pages（內含 build + deploy，見 scripts/cloudflare-pages-deploy.sh），部署命令留空。

首次部署前：Workers & Pages 裡需已有名為 pceguitw-status 的 Pages 專案（Connect Git 建立即可）。專案不存在時，CI 裡 wrangler pages deploy 不會互動建立，會直接失敗。

若有 Build output directory 欄位（舊版 Pages）：根目錄仍為 /，輸出目錄填 docs，部署命令可留空。

部署成功後，在該專案 Deployments → Visit site 複製實際 https://….pages.dev；在成功前，文件中的 pceguitw-status.pages.dev 可能仍是 NXDOMAIN。

路徑 B：GitHub Actions（workflow 細節）

Workflow：.github/workflows/deploy-status-cloudflare-pages.yml push docs/ 或手動 Run workflow；需已設定 Secrets（見上方 方案甲）。workflow 會 verify token 後以 Wrangler** pages deploy docs 上傳（不使用 GitHub Deployments API，避免 403）。

本機手動部署（除錯用）

npm run build:status-html
npx wrangler pages deploy docs --project-name=pceguitw-status

需已 npx wrangler login 或設定 CLOUDFLARE_API_TOKEN。

存取控管（進度頁非公開時）

*.pages.dev 預設為公開 URL。若內容僅限團隊：

  1. Cloudflare Zero Trust → Access：對 pceguitw-status.pages.dev（或自訂網域）加 Application，要求 Email／IdP 登入。
  2. 或綁 自訂網域（僅內部 DNS 可解析），並搭配 Access。

政策允許前，勿將含客戶細節的進度頁設為完全公開。

與 repo 內其他流程

項目說明
npm run build:status-html產生 docs/html/*.html；Cloudflare build 與本機相同
sync-status-html workflowPush 後若 Markdown 與 HTML 不一致，bot 會補 commit（與 Pages 部署可並存）
本機預覽npm run serve:status → http://127.0.0.1:8765/html/index.html

疑難排解

  • Authentication error [code: 10000]（部署階段）：幾乎都是 API Token 權限或 Account ID 問題，不是「打錯專案名」。 ``bash curl -s "https://api.cloudflare.com/client/v4/user/tokens/verify" \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ` "success": true` 表示 token 有效；若仍 10000，改查 Account ID 或 Pages 權限。
    • 到 My Profile → API Tokens，找到 Workers Builds 綁定的那支 token（或 pceguitw-status build token 對應的 Cloudflare token），Edit 權限至少包含：
    • Account → Cloudflare Pages → Edit
    • Account → Account Settings → Read（建議）
    • Account resources：Include → 選 部署 Pages 專案所在的那個 Account（勿選錯帳號）
    • 勿只用「Edit Cloudflare Workers」範本；該範本 沒有 Pages，pages deploy 會 10000（wrangler#1186）。
    • 建置變數必加 CLOUDFLARE_ACCOUNT_ID（與 token 同一 Account 的 ID）。
    • 本機驗證（token 勿貼到 chat）：
    • 若專案是 Workers Builds（Worker） 而非 Pages Connect Git，請改在 Workers & Pages → 你的 Pages 專案 → Connect Git，或確認 deploy 用的 token 已含 Pages Edit。
  • DNS_PROBE_FINISHED_NXDOMAIN / pceguitw-status.pages.dev 無法連線：表示 Cloudflare 尚未成功發佈此專案（或專案名不同）。到 Deployments 看是否 Success；修正部署命令（見上表）後 Retry deployment。以 Dashboard Visit site 的網域為準。
  • Build 成功、Deploy 失敗：(1) 根目錄改回 /，勿用 docs；(2) 加建置變數 CLOUDFLARE_ACCOUNT_ID；(3) log 若 no such file / docs/docs，同上；(4) 若 Project not found，先在 Dashboard 建立 pceguitw-status Pages 專案。
  • 404 on /：確認 output 為 docs（不是 docs/html），根目錄需有 index.html。
  • 圖表／樣式壞掉：確認以 /html/index.html 進入，且 pce-module-status.css、pce-module-status-charts.js 與 assets/ 一併在 repo 內。
  • 連到 .md 變下載：預期行為；完整 Markdown 渲染可之後再加（例如 md 靜態生成器），目前以 HTML 進度頁為主。