家教中心老師管理系統 - Cloudflare 伺服器與雲端架構規劃書 (Infrastructure Guide)

本文件詳細規劃本系統採用 Cloudflare 全生態邊緣無伺服器架構 (Serverless Edge Architecture) 的技術選型、元件配置、部署流程與維護指引。此架構具備**「永不休眠」、「大容量免費額度」、「證件儲存零流量費」以及「完全不依賴 GitHub 本機直接部署」**等核心優勢。

1. 系統架構拓撲圖 (Architecture Topology)

flowchart TD
    subgraph ClientLayer["客戶端 (行動裝置 / 桌面端)"]
        AdminBrowser["中心管理員 / 行政秘書 (Web 後台)"]
        TeacherMobile["家教老師 (手機打卡 / 時段設定)"]
        ParentMobile["家長 / 學生 (課堂進度查閱)"]
    end

    subgraph CloudflareEdge["Cloudflare 全球邊緣伺服器 (Global Anycast Edge)"]
        CDN["Cloudflare CDN & SSL
(免費 HTTPS / DDoS 防護)"]
        
        subgraph ServerRuntime["無伺服器運算 (Serverless Compute)"]
            Pages["Cloudflare Pages / Workers
• Next.js / Remix / Astro 全端框架
• SSR 頁面渲染與 RESTful/tRPC API"]
        end

        subgraph StorageLayer["資料與儲存層 (Storage Services)"]
            D1[("Cloudflare D1 (SQL 資料庫)
• 5GB 免費儲存容量
• 永不休眠、邊緣低延遲讀取
• 儲存使用者、排課、簽到、薪資")]
            R2[("Cloudflare R2 (物件儲存)
• 10GB 免費空間、0 流量外網費
• 存放良民證、學歷證書、身分證影本")]
            KV["Cloudflare KV / Secrets
(快取、Session Token 與加密密鑰)"]
        end
    end

    AdminBrowser --> CDN
    TeacherMobile --> CDN
    ParentMobile --> CDN

    CDN --> Pages
    Pages --> D1
    Pages --> R2
    Pages --> KV

2. 雲端核心元件規格與免費額度配置

服務項目	Cloudflare 元件	主要職責	免費額度 (Free Tier)	相比傳統架構優勢
網頁與 API 伺服器	Cloudflare Pages / Workers	託管前端 UI 介面與後端 API 業務邏輯	• 無限請求量 (Pages) • 每日 100,000 次請求 (Workers)	邊緣就近執行，冷啟動低至 0~5ms，免管理 Linux 主機。
關聯式資料庫	Cloudflare D1	儲存核心結構化資料（老師資料、排課、課堂紀錄、薪酬帳務）	• 5 GB 儲存空間 • 每日 5,000,000 行讀取 • 每日 100,000 行寫入	永遠不會休眠（Supabase 7天無活動休眠需 Cron 保活；D1 永久秒開）。
附件證照儲存	Cloudflare R2	存放老師上傳之良民證、畢業證書、身分證掃描檔	• 10 GB 儲存空間 • 每月 1,000,000 次寫入 • 0 元外網流量費 (Zero Egress)	業界唯一無外網流出流量計費，檢閱檔案附件無隱藏成本。
環境機密與快取	Cloudflare Secrets / KV	JWT 密鑰、系統加密 Salt、短效快取	• 免費版支援 Secrets 變數 • KV 每日 10 萬次讀取	原生整合於 Cloudflare 儀表板與 Wrangler CLI。

3. 資料庫設計轉換指引 (PostgreSQL ➔ D1 / SQLite)

專案現存之 database/schema.sql 原以 PostgreSQL 規格撰寫。因 Cloudflare D1 底層採用 SQLite 引擎，在正式落地時請依下列原則進行型別轉換：

型別與語法對應表

規格項目	原 PostgreSQL 設計	Cloudflare D1 (SQLite) 推薦作法	說明
主鍵識別碼	`UUID DEFAULT gen_random_uuid()`	`TEXT PRIMARY KEY`	應用層透過 Web API 原生 `crypto.randomUUID()` 產生。
自增主鍵	`SERIAL PRIMARY KEY`	`INTEGER PRIMARY KEY AUTOINCREMENT`	用於流水號、輔助關聯表。
陣列型別	`VARCHAR(50)[]`	`TEXT` (JSON 陣列) 或關聯表	例如授課方式改以 JSON 字串儲存：`'["IN_PERSON","ONLINE"]'`。
結構化 JSON	`JSONB`	`TEXT`	SQLite 內建完整 JSON 查詢函式（如 `json_extract`）。
時間戳記	`TIMESTAMP WITH TIME ZONE`	`TEXT` (ISO-8601 格式) 或 `INTEGER` (Unix ms)	建議存標準字串：`2026-10-19T06:00:00.000Z`。
金額計算	`NUMERIC(10, 2)`	`REAL` 或 `INTEGER` (存分/整數)	建議時薪與鐘點費以整數或高精準度數值儲存。

推薦 ORM：Drizzle ORM

針對 Cloudflare D1，強烈推薦使用 Drizzle ORM（比傳統 Prisma 更輕量、無冷啟動延遲、原生支援 D1 TypeScript 驅動）：

# 安裝 Drizzle 與 D1 開發依賴
npm install drizzle-orm
npm install -D drizzle-kit

4. 本地開發與免 GitHub 部署流程 (Wrangler CLI)

本系統支援由開發者電腦終端機直接將程式與資料庫推送到 Cloudflare 邊緣網路，全程無須經過 GitHub 儲存庫。

步驟 1：安裝與登入 Wrangler 工具

# 1. 安裝 Cloudflare 官方 CLI 工具
npm install -g wrangler

# 2. 登入 Cloudflare 帳號 (會在瀏覽器彈窗授權一次)
wrangler login

步驟 2：初始化 Cloudflare D1 資料庫

# 建立雲端資料庫實體
wrangler d1 create tutor-db

# 終端機會輸出類似如下設定，請複製至專案 wrangler.toml：
# [[d1_databases]]
# binding = "DB"
# database_name = "tutor-db"
# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

步驟 3：初始化 Cloudflare R2 檔案儲存貯體 (Bucket)

# 建立存放老師證照的 R2 Bucket
wrangler r2 bucket create tutor-documents

步驟 4：執行資料庫遷移 (Migrations)

# 本地開發測試執行
wrangler d1 execute tutor-db --local --file=./database/schema.d1.sql

# 正式上線環境推送
wrangler d1 execute tutor-db --remote --file=./database/schema.d1.sql

步驟 5：一鍵正式部署上線 (Direct Deploy - Bypass GitHub)

# 建置前端與 API 專案
npm run build

# 直接發布至正式環境 (取得 https://tutor-management-system.pages.dev 正式網址)
wrangler pages deploy ./dist --project-name=tutor-management-system

5. 自訂網域名稱與安全防護 (Custom Domain & Security)

預設免費網址：
- 部署完成後，系統會自動分配一組免費的專屬二級網域名稱（如 https://tutor-management-system.pages.dev），內建 SSL 憑證，可立即對外提供老師與行政人員使用。
綁定自訂專用網域：
- 若中心擁有專屬網域（例如 tutor.center.edu.tw 或 tutor.mycenter.com），可在 Cloudflare Pages 後台「Custom Domains」一鍵綁定。
- Cloudflare 會自動簽發並維護免費 SSL/TLS 憑證，並自動開啟 HTTP 強制跳轉 HTTPS。
安全防護設定：
- 透過 Cloudflare WAF（Web 應用程式防火牆）與 DDoS 防護，自動阻擋惡意掃描與暴力破解，確保中心個資安全。