FurCDN Pages（內測）

FurCDN Pages 讓你把自己的靜態網站（HTML / CSS / JS / 圖片等）放上 FurCDN，並用你自己的網域對外服務。Pages 站點本身沒有公開網址；它是一種新的源站類型（type: "pages"）——你把網域綁到站點，或把既有網域的源站改指到站點，訪客就會經過該網域的叢集、TLS、WAF、快取與計量，機制與一般 CDN 網域完全相同。

一、這是什麼

訪客 → 你的網域（CNAME → 叢集）→ FurCDN 節點（WAF / 快取 / TLS）
                                      └ 源站 type=pages → Pages 站點

Pages 只負責儲存與提供靜態檔案；網域、叢集、SSL、WAF、快取、流量統計與套餐限制全部沿用既有 CDN 網域功能。這代表：

• 你要先有（或新綁）一個網域，Pages 才有對外網址。
• 每個綁定的網域都佔用一個套餐網域額度。
• 流量計入該網域的統計與你的套餐月流量。
• 部署新版本後，平台會自動清除所有綁定該站點網域的快取。

Pages 沒有 SSR、沒有 Functions / Workers、沒有反向代理，也不支援 _redirects / _headers。你在本機 build 出什麼，節點就服務什麼。

二、內測碼與開通

內測期間不開放自助申請。內測碼由管理員於後台批次產生後發放，格式為 PGB-XXXX-XXXX-XXXX。

兌換方式

Dashboard：登入後點側邊欄「Pages」，在輸入框填入內測碼即可。入口對所有使用者可見，未開通時只會看到兌換畫面。

CLI：

furcdn pages beta redeem PGB-XXXX-XXXX-XXXX
furcdn pages beta status

API：POST /api/v1/pages/beta/redeem，詳見開放 API。

兌換成功後會建立使用權（PagesAccess）。規則如下：

• 每個內測碼有使用次數上限，用完為止；過期或停用的碼無法兌換。
• 已開通者再次兌換會直接回成功，不會消耗另一組碼。
• 每使用者、每 IP 每小時最多嘗試 10 次；無效 / 用盡 / 過期 / 停用一律回 pages_beta_invalid。
• 被管理員封禁 Pages 的帳號不可再兌換，所有 Pages API 回 403 pages_banned。
• 未開通時，除了站台概況（供 UI 判斷是否顯示兌換畫面）與兌換端點，其餘 Pages API（含 CLI / GitHub Action / /api/v1）一律回 403 pages_beta_required。
• 未開通時，建立或編輯含 pages 源站的網域也會回 403 pages_beta_required。

三、配額與計費

Pages 的容量免費，流量則跟著綁定的網域走你的 FurCDN 套餐。

容量怎麼算

• 只有目前上線中的 deployment 計入 100MB；非上線的舊版、備用版本不計入。
• 每站最多保留 5 筆 deployment 檔案；超過時自動刪除最舊且非上線中的那筆。上線中的版本不會被自動刪除，也無法手動刪除。
• 部署新版本、或把舊版重新上線（rollback）時，若會讓總容量超過 100MB，API 回 413 pages_quota_exceeded，並附上 usedBytes / limitBytes。

流量、套餐與網域限制

Pages 站點沒有獨立的流量統計，也沒有 Pages 專屬的計費程式碼。綁定後它就是一個普通網域：

• 請求數與位元組走該網域的 TrafficLog / DailyStat，計入你的套餐月流量（bandwidthGbMonth）。
• 沒有有效套餐、套餐過期或當月流量超額時，依既有網域規則停用；月初重置後自動恢復。
• 綁定網域會佔用套餐的 maxDomains；超出時無法再綁定。
• 管理員停用網域（adminDisabled）時，Pages 內容同樣停止服務。
• 站台被停用或帳號被封禁 Pages 時，透過綁定網域存取會回 451（詳見禁止內容與檢舉）。

補救方式與一般網域相同：購買 / 續費 / 升級套餐，或等月初自動重置。詳細計費規則見計費與套餐。

四、綁定自己的網域

Pages 站點沒有預設網址，必須綁定網域才能上線。綁定動作會用既有的「建立網域」流程：檢查網域格式、套餐網域數、可用叢集與實名要求，並建立 origins = [{ type: "pages", pagesSiteId }] 的網域。

Dashboard

CLI

# 查叢集 ID、名稱、CNAME 與是否需要實名
furcdn info clusters

# 綁定網域（--cluster 省略時，TTY 下會列出可選叢集讓你輸入）
furcdn pages bind my-site www.example.com --cluster 3

# 列出站點已綁定的網域
furcdn pages domains my-site

bind 成功後會輸出網域、CNAME 目標與站點資訊（加 --json 取得機器可讀格式）。非互動環境（CI）必須明確指定 --cluster <id>。

切換叢集與管理網域

綁定後，該網域就是一般網域，可在 儀表板 > 網域管理 > 該網域 > 基本設定 使用既有功能。

切換接入叢集：在「接入叢集」卡片選擇方案允許的叢集（大陸 / 港日）並確認。規則與建立網域相同（可用叢集清單、maxClusters、實名要求）。切換後：

• 由平台管理的 DNS 別名（<domain>.<aliyun zone>）會自動改指向新叢集。若你的 CNAME 是設到這個別名，不需要改 DNS。
• 若你當初直接 CNAME 到舊叢集的 CNAME，請改成新叢集的 CNAME；furcdn domain dns-check <domain> 接受別名或目前叢集的 CNAME。
• 舊、新叢集的快取會一併清除；若啟用 ECH，兩邊的 HTTPS DNS 記錄也會同步。

CLI：

furcdn domain update example.com --cluster 3

API：

PUT /api/domains/123
Content-Type: application/json

{"clusterId": 3}

回 {domain:{id,clusterId,cluster:{id,name,cname},dnsTarget,dnsUpdated,dnsNote?}}。切到同一個叢集是 no-op；DNS 別名更新失敗會回 502 並自動還原原叢集，不會留下半套狀態。

其他既有功能（SSL / 強制 HTTPS / HTTP2、WAF、快取規則、快取刷新、流量統計、刪除網域）都在同一頁管理；刪除網域後，Pages 站點就不再透過該網域服務。

同一個 Pages 站點可以綁定多個網域（每個都佔用一個網域額度）；同一個網域也可以同時有 pages 與 HTTP 源站（例如 Pages 為主、HTTP 備援）。

五、把既有網站源站改指到 Pages

如果網域已經接入 FurCDN（原本回源到自己的伺服器），可以直接把源站改成 Pages 站點，DNS、叢集、SSL、WAF 與快取設定都不用重做。

Dashboard

儀表板 > 網域管理 > 編輯網域 > 源站設定，把來源類型改為「FurCDN Pages 站點」，選擇你的站點後儲存。存檔後建議在網域頁面按「立即刷新快取」。

CLI

# 把 example.com 的主源站改成 Pages 站點 my-site
furcdn domain origin set example.com --pages my-site

# 也可以附加為備援源站（保留原本的 http 主源站）
furcdn domain origin set example.com --pages my-site --backup

--pages 與 --url 互斥；其餘 --weight、--probe 等源站擇優旗標照舊可用。要改回 HTTP 源站，改用 --url 即可。

API

PUT /api/domains/123
Cookie: furcdn_token=...
Content-Type: application/json

{
  "origins": [
    { "type": "pages", "pagesSite": "my-site" }
  ]
}

• 輸入可用 pagesSite（slug，必須是自己的站點）或 pagesSiteId。
• 伺服器會驗證站點歸屬、站點狀態與內測解鎖，並正規化成 { "type": "pages", "url": "pages://<siteId>", "pagesSiteId": <id>, ... }。
• 輸出（API / 節點設定）一律以 pagesSiteId 為準。
• 可以同時保留 HTTP 源站作為備援，例如 Pages 為主、http 為 backup；備援語意與一般源站相同。

六、快速開始

npm install -g @furcdn/cli

# 方式一：互動登入（session）
furcdn login

# 方式二：CI / 腳本用 API key
export FURCDN_API_KEY=fck_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

# 兌換內測碼
furcdn pages beta redeem PGB-XXXX-XXXX-XXXX

# 建立站台（也可在第一次 deploy 時加 --create）
furcdn pages create my-site

# 部署：把 ./dist 的內容打包成 tar.gz 上傳
furcdn pages deploy ./dist --site my-site --create

# 綁定網域（先用 info clusters 查叢集 ID）
furcdn info clusters
furcdn pages bind my-site www.example.com --cluster 3

# 部署到非 production 分支 → 只儲存，不會上線
furcdn pages deploy ./dist --site my-site --branch preview --message "測試新版"

# 列出站台 / 版本 / 已綁網域
furcdn pages list
furcdn pages deployments my-site
furcdn pages domains my-site

# Rollback / promote：把指定版本設為上線版本
furcdn pages activate my-site 42

# 刪除版本 / 刪除站台
furcdn pages rm-deployment my-site 42
furcdn pages delete my-site

# 用量與內測狀態
furcdn pages usage
furcdn pages beta status

name: Deploy Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run build

      - id: pages
        uses: FurCDN/github-action@v1
        with:
          action: pages-deploy
          api-key: ${{ secrets.FURCDN_API_KEY }}
          site: my-site
          dir: dist
          branch: ${{ github.ref_name }}
          message: ${{ github.event.head_commit.message }}
          create-site: 'true'

七、檔案與路由規則

上傳格式

POST body 是原始壓縮檔位元組（不是 multipart）。平台依 magic bytes 判斷格式：

• gzip（1f 8b）→ 視為 tar.gz；
• ZIP（50 4b 03 04）→ 視為 zip；
• 其他 → 400 pages_bad_archive。

解壓時的安全限制：只接受一般檔案（目錄會略過；遇到 symlink / hardlink / 裝置檔直接拒絕）、解壓後總和 ≤ 20MB、檔案數 ≤ 2000、路徑 ≤ 255 字元，且路徑不得包含 ..、絕對路徑、NUL 或反斜線（接受 ./ 前綴）。

根目錄必須有 index.html，否則回 400 pages_no_index。最外層若只有單一共同目錄（例如 dist/），平台不會自動剝除，請在打包時就進入該目錄打包內容。

路徑解析順序

請求 /about 時，依序嘗試：

1. about（若真是一個檔案）
2. about/index.html
3. about.html

都找不到時：

• 有 404.html → 以 HTTP 404 回傳 404.html；
• 否則回平台內建的 404 頁。

其他規則：

• 目錄請求若缺少結尾斜線、但存在 <path>/index.html，回 308 導向 <path>/（保留 query string）。
• 任何路徑區段以 . 開頭一律 404，唯一例外是 .well-known。
• 不支援 _headers 與 _redirects：這兩個檔案不會被解讀，寫了也不會生效。
• 不支援伺服器端程式碼（PHP / Node / Python）、SSR、Functions / Workers、URL rewrite 或反向代理。
• 沒有目錄列表（directory listing）。
• Content-Type 依副檔名決定，文字類別自動加 ; charset=utf-8。

快取與生效時間

Pages 回應的 Cache-Control：

• 每個檔案都帶 ETag；帶 If-None-Match 命中時回 304。支援 HEAD。
• 實際快取行為完全依該網域的快取設定（快取開關、規則、TTL、忽略 query string 等），與一般網域相同。
• 部署、rollback、刪除 deployment、停用站點後，平台會自動清除所有綁定該站點網域的快取，新版立即生效；實際生效時間仍受該網域的快取規則與節點行為影響。
• 檔案與錯誤頁回應附帶 X-Content-Type-Options: nosniff 與 Referrer-Policy: strict-origin-when-cross-origin。

版本、rollback 與刪除

• 每次上傳都是一筆 deployment，各自有 branch、message、檔案數、大小與 SHA-256。
• branch 等於站台 production branch 的部署，成功後自動上線；其他分支只儲存，不會上線。
• 沒有預覽網址。任何已上傳的 deployment 都可以「activate」設為上線版本（rollback / promote）；上線前同樣會檢查 100MB 配額。
• 上線中的 deployment 不可刪除（409）；其餘可刪。
• 每站保留 5 筆，超過時自動刪除最舊且非上線中的版本。
• 站點仍有綁定網域時不可刪除（409 pages_bad_request，訊息會列出網域）；請先在網域管理改回 HTTP 源站或刪除網域。

八、禁止內容與檢舉

Pages 嚴禁下列內容：

• 釣魚 / 憑證竊取：偽造登入頁、假表單、誘導輸入密碼 / OTP / 信用卡 / 助記詞；
• 惡意程式：病毒、木馬、勒索軟體、挖礦腳本、惡意導向；
• 品牌冒用：冒充銀行、支付、雲端、社群平台或任何企業 / 個人；
• 詐騙與違法內容：假投資、假客服、兒少剝削、侵權內容等；
• 濫用平台：檔案分享、串流來源、攻擊跳板、繞過計量。

slug 另有保留字與品牌黑名單，命中時回 400 pages_bad_slug。

停用與封禁

• 站點停用（suspended）：所有綁定該站點的網域回 451，顯示違規停用說明；站點不可再部署（403 pages_site_suspended）。
• 帳號封禁 Pages：該使用者所有站點一併停用，透過綁定網域存取回 451，所有 Pages API 回 403 pages_banned，且不可再兌換內測碼。
• 管理員可隨時下架站點、強制刪除站點或封禁帳號；情節重大或重複違規會直接封禁。強制刪除站點後，仍指向它的網域會回 404，請自行改源站或刪除網域。

檢舉

發現釣魚或惡意 Pages 站台，請到 https://cdn.taipei/report-pages 填寫檢舉（不需登入，需通過人機驗證），或呼叫 POST /api/pages/report。檢舉請填網域或完整網址（Pages 沒有自己的公開網址）：

{
  "target": "www.example.com",
  "reason": "phishing",
  "details": "偽造銀行登入頁",
  "email": "optional@example.com"
}

• target 可填網域或 URL；伺服器會取 hostname，並比對出背後是否有 Pages 站點。
• reason 為 phishing / malware / illegal / other。
• details、email 選填；email 只用於必要時聯絡，不會公開。
• 每 IP 每小時最多 5 次。

管理員會依檢舉內容審核並採取停用、刪除或封禁。濫用檢舉管道同樣會被限制。

九、錯誤碼

所有 Pages API 錯誤格式為 { "error": "繁中訊息", "code": "…", … }。

網站本身（訪客看到的）狀態：

十、FAQ

需要自己的網域嗎？

需要。Pages 不提供免費子網域，站點必須綁定你自己的網域才有對外網址。綁定時可選中國大陸或香港 / 日本叢集。

可以綁多個網域嗎？

可以。同一個站點可以綁定多個網域，每個網域都佔用套餐的 maxDomains 額度，並各自沿用該網域的 SSL、WAF 與快取設定。

綁定網域要多久才會生效？

建立網域後依畫面設定 CNAME；DNS 生效後系統會自動申請 SSL。實際時間取決於你的 DNS TTL 與憑證簽發，通常數分鐘到數十分鐘。

可以換叢集嗎？

可以。到 網域管理 > 該網域 > 基本設定 > 接入叢集 切換，或用 furcdn domain update <domain> --cluster <id>。平台管理的 DNS 別名會自動改指向；若你是直接 CNAME 到舊叢集 CNAME，記得改成新叢集的 CNAME（furcdn domain dns-check 會告訴你目前是否正確）。

為什麼沒有預覽網址？

Pages 站點沒有公開 host，所以每筆 deployment 沒有獨立預覽網址。非 production 分支的部署只會儲存，不會上線；需要時用 activate 把它設為上線版本。

既有網站要怎麼改指到 Pages？

在網域管理的源站設定把類型改成「FurCDN Pages 站點」並選擇站點，或用 furcdn domain origin set <domain> --pages <site>。DNS、叢集、SSL 與 WAF 都不用重做；也可以把 Pages 設為備援，保留原本的 HTTP 源站。

流量怎麼算？會另外收費嗎？

不會另外收費。Pages 流量就是綁定網域的流量，計入你的套餐 bandwidthGbMonth；請求數不限。容量（100MB / 人、20MB / 站）免費。

沒有套餐或套餐過期會怎樣？

依既有網域規則停用（與一般網域相同），續費或升級後恢復；月初也會重置超量狀態。

100MB 是每站還是每人？

每人 100MB，計入的是「所有站台上線中 deployment」的檔案大小總和。單站另有 20MB 上限。舊版與未上線版本不計入 100MB，但每站最多保留 5 筆檔案。

為什麼網站回 451？

站點被管理員停用（違規或檢舉成立），或站點擁有者被封禁 Pages。請開工單申訴；確認違規時不會恢復。網域本身仍在，可改回 HTTP 源站。

為什麼網站回 404？

可能是站點尚未部署、沒有上線版本、站點已被刪除，或請求的檔案不存在。先確認站點有 active deployment，且網域的 pages 源站指向正確站點。

刪除站台時說仍有網域綁定？

站點仍有網域使用 pages 源站時不能刪除。請先到網域管理把源站改回 HTTP，或刪除該網域，再刪除站台。

支援自訂網域嗎？

Pages 就是用你自己的網域，沒有平台提供的子網域。網域需先完成 DNS CNAME 與 SSL 簽發。

支援 SPA、SSR 或 API 嗎？

SPA 的靜態產物可以部署，但沒有 rewrite，deep link 需自行輸出對應 HTML（或用 404.html 接手，狀態碼仍為 404）。SSR、Functions、Workers、API 一律不支援。

_headers / _redirects 為什麼沒作用？

Pages 不支援這兩個 Cloudflare Pages 專有檔案。需要自訂回應標頭或轉址，目前只能靠 HTML meta refresh（不建議）或改由前端處理。

部署後多久生效？

部署、rollback、刪除 deployment 或停用站點後，平台會自動清除所有綁定網域的快取。實際生效時間仍依該網域的快取規則與 TTL；必要時可在網域管理手動刷新快取。

刪除站台後流量紀錄會消失嗎？

不會。站台檔案會刪除，但綁定網域的每日流量統計（DailyStat）會保留，當月已產生的流量仍計入套餐。

可以拿 Pages 當圖床或檔案分享嗎？

不行。Pages 是靜態網站託管，不是檔案分享或串流服務；這類用法會被視為濫用並停用。