Skip to main content

Cloudflare Pages 多站點部署指南

本文件說明 GatherTech-Docs 的 Cloudflare Pages 多站點部署架構、設定方式與常見問題。

架構概念​

一個 GitHub Repo 連接多個 Cloudflare Pages Project，每個 Project 用不同的 Build Command 產出不同內容：

觸發機制​

不需要 GitHub Actions，Cloudflare Pages 本身的 Git integration 就是 CI/CD。

內容隔離​

隔離層級機制說明
目錄結構internal/ vs clients/程式碼層級分離
Build Script各 Project 不同 Build Command只打包該站點需要的內容
環境變數INCLUDE_INTERNAL=false客戶 Build 排除 internal
Zero Trust AccessCloudflare Access Policyemail 驗證存取控制

Cloudflare Pages Project 設定​

建立新 Project​

  1. Workers & Pages → Create → Pages → Connect to Git
  2. 選擇 gather-system/gathertech-docs
  3. 設定 Build Configuration

Build Configuration​

內部全站版​

欄位值
Project namegathertech-docs
Production branchmain
Build commandnpx tsx scripts/build-internal.ts
Build output directorydist/internal

客戶站點​

欄位值（以 ProcessVision 為例）
Project namegathertech-docs-jope-pv
Production branchmain
Build commandnpx tsx scripts/build-client.ts --client jope --project process-vision
Build output directorydist/jope-process-vision

Custom Domain 設定​

  1. Pages Project → Custom domains → Set up a custom domain
  2. 輸入子網域（如 docs.gathertech.com.tw）
  3. Cloudflare 自動建立 CNAME DNS 記錄
  4. 等待 SSL 憑證自動簽發

Build Output Directory 注意事項​

Build output directory 必須與 Build Script 的實際輸出路徑一致：

Build Script實際輸出路徑CF Pages 設定
build-internal.tsdist/internaldist/internal
build-client.ts --client jope --project process-visiondist/jope-process-visiondist/jope-process-vision

站點規劃​

現有站點​

CF Pages ProjectBuild CommandDomain存取
gathertech-docsbuild-internal.tsdocs.gathertech.com.tw@gathertech.com.tw
gathertech-docs-jope-pvbuild-client.ts --client jope --project process-visiondocs-jope-pv.gathertech.com.tw指定 email

規劃中站點​

CF Pages ProjectDomain存取
gathertech-docs-jope-plcdocs-jope-plc.gathertech.com.tw指定 email
gathertech-docs-jope-smbdocs-jope-smb.gathertech.com.tw指定 email
gathertech-docs-walton-line1docs-walton-line1.gathertech.com.tw指定 email
gathertech-docs-walton-line3docs-walton-line3.gathertech.com.tw指定 email
gathertech-docs-leyu-inspectiondocs-leyu-inspection.gathertech.com.tw指定 email

Cloudflare Zero Trust Access​

設定流程​

  1. Zero Trust Dashboard → Access controls → Applications
  2. Add an application → Self-hosted
  3. 設定 Application domain 和 Access Policy

Access Policy 設定​

內部站點​

欄位值
Application nameGatherTech Docs - Internal
Application domaindocs.gathertech.com.tw
Policy actionAllow
IncludeEmails ending in @gathertech.com.tw

客戶站點​

欄位值（以 Jope PV 為例）
Application nameGatherTech Docs - Jope ProcessVision
Application domaindocs-jope-pv.gathertech.com.tw
Policy actionAllow
Include指定客戶 email（逐一新增）

認證方式​

  • One-time PIN（Free Plan 預設啟用）
  • 使用者輸入 email → 收到驗證碼 → 輸入驗證碼 → 存取
  • Session 持續時間建議 24 小時

新增客戶站點 SOP​

Step 1：撰寫客戶文件​

gathertech-docs/clients/{client}/{project}/
├── setup/
│   ├── installation.md
│   └── configuration.md
├── operation/
│   ├── dashboard.md
│   └── monitoring.md
├── troubleshooting/
│   └── common-issues.md
└── release-notes/
    └── v1.0.md

Step 2：更新 sites.json​

在 scripts/sites.json 新增站點設定。

Step 3：本機驗證​

# 驗證客戶站點 Build
npx tsx scripts/build-client.ts --client {client} --project {project}

# 驗證內部站點包含新內容
npm run build:internal

# 本機預覽
npm run serve

Step 4：Push 到 main​

所有 CF Pages Project 自動觸發 Build。

Step 5：建立 CF Pages Project​

  1. Workers & Pages → Create → Pages → Connect to Git
  2. 選擇同一個 repo
  3. 設定對應的 Build Command 和 Output Directory
  4. 新增 Custom Domain

Step 6：設定 Zero Trust Access​

  1. Access controls → Applications → Add
  2. 設定客戶 email allow list
  3. 驗證客戶可正常存取

常見問題​

Build output directory not found​

Error: Output directory "build" not found.

原因：CF Pages 設定的 output directory 與 Build Script 實際輸出不一致。 解法：到 Settings → Builds & deployments 修改為正確路徑（如 dist/internal）。

多個 Project 連接同一 Repo​

Cloudflare Pages 支援多個 Project 連接同一個 GitHub Repo。每次 push：

  • 所有連接的 Project 同時觸發 Build
  • 各自用自己的 Build Command
  • 互不影響

Build 失敗不影響其他站點​

一個 Project 的 Build 失敗不會影響其他 Project。各自獨立。

環境變數​

如需在 Build 時傳入環境變數，在 CF Pages Project → Settings → Environment variables 設定。

例如：INCLUDE_INTERNAL=true（內部站點）vs INCLUDE_INTERNAL=false（客戶站點，build-client.ts 已自動設定）。

相關文件​