慈濟年報

問題

慈濟基金會每年出一本年報。舊網站是 Next.js，所有資料都在瀏覽器端經過伺服器代理去抓；草稿預覽用的 ?preview=1 連結任何人都能開，已發布頁面每次造訪都要讀後端。同仁原本就能在後台編輯內容；這次的目標是保留後台、讓公開頁靜態化且省資源，並補上草稿外洩的漏洞。

我做了什麼

一個按年度分頁的公開年報網站（2021–2025 年內容），加上管理後台。已發布的年度在建置時預渲染成靜態 HTML，放在 Cloudflare Pages。另一棵 /preview/{年度} 路由樹在請求時即時渲染草稿，只開放給登入的編輯者。後台是靜態 HTML，沿用既有的 schema 驅動表單產生器，新增欄位只要改 JSON 設定；我把它改接為直連 drust、加上 Google OAuth 登入與圖示選擇器。網站有三層亮／暗色 design token，建置時還會偵測透明背景的 PNG 圖表，讓它們在深色模式下依然看得清楚。

運作方式

1. 編輯者透過 drust 用 Google OAuth 登入，只有白名單內的帳號能進。
2. 後台用編輯者自己的 token 直接寫進 drust，沒有任何伺服器持有高權限金鑰。
3. 草稿在 /preview 下立即可見。middleware 在渲染前先向 drust 驗證 session cookie，任何失敗都導回登入頁，不會送出半點草稿內容。
4. 每次儲存都會觸發 webhook，啟動 GitLab pipeline：建置、3 道建置驗證、部署到 preview，再到正式環境。設計上約 2 分鐘後上線。
5. 每小時一次的排程重建，補上漏掉的 webhook。

關鍵決策

• 公開頁靜態化，預覽頁伺服器渲染。 靜態頁省下每次造訪對後端的讀取與 Worker 呼叫。舊的 ?preview=1 連結任何人都能開，把草稿搬到有門禁的路由，順手補上這個漏洞。
• 後台直接連 drust。 我刪掉了持有 service token 的代理層，並用一道建置關卡加一個單元測試，確保這把 token 永遠不會出現在 src/ 或 dist/。
• 寧可建置失敗，也不讓網站壞掉。 drust 連不上或建置環境變數缺漏時，建置直接報錯停下，不會預渲染出一個空網站；上一版成功的部署繼續在線上。
• 圖片放哪裡由程式決定，不靠 LLM 猜。 2025 年報我用 Python 寫了一條 .docx 匯入管線，每張圖的位置依它在文件中的標題路徑決定，因為先前讓 LLM 猜圖位曾造成相片錯置。LLM 只在單筆記錄內整理文字，若輸出掉圖或掉字，就退回未經 LLM 的版本。

成果

網站已上線，2024 與 2025 年度已發布，2021–2025 年內容都已匯入。2025 年度已發布，但部分內容（年報 PDF、首頁文案、人物照）尚待補編，網站目前也設為 noindex。2026 年 6 月到 9 月由我一人完成。開發全程使用 Claude Code，走「規格 → 計畫 → 測試先行實作 → 審查」的流程，repo 裡留有 13 份設計規格與 11 份實作計畫。