專案總覽
專案簡介
Eternity 是一個以 Astro + Cloudflare 邊緣運算 為基礎的個人網站 monorepo。包含兩個子應用——主站（作品集）與世界觀文件站——透過 pnpm workspaces 與 Turborepo 管理，完全部署在 Cloudflare Pages 與 Workers 上。
核心理念
邊緣優先架構：所有內容透過 Cloudflare 邊緣網路（D1、R2、KV）供應，確保全球低延遲存取
內容自主權：自建 TipTap 富文字後台編輯器，無需依賴第三方 CMS
世界觀即文件：文件站同時是互動式世界觀體驗，具備區域導航、3D 地圖與環境特效
我的職責
作為本專案唯一開發者，我負責：
系統架構設計
設計包含兩個 Astro 應用、兩個 Cloudflare Worker 與共用套件的 monorepo 結構
規劃兩站的 D1 資料庫架構（層級式頁面、主站內容表、同步日誌）
設計本地與遠端 D1 之間的雙向內容同步管線
核心功能實作
主站：完整作品集網站，包含作品、動態、連結、關於/聯絡頁面，支援 i18n（zh-tw/en）
文件站：六大區域世界觀閱讀器（歷史、回聲、視覺、概念、儲存、傳送門），每區域有專屬 Reader
後台編輯器：基於 TipTap 的三欄式編輯器（目錄列表 | 編輯區 | 屬性檢查器），兩站共用
資產管理：每站獨立 R2 儲存桶，搭配媒體庫、圖片選取器、上傳管線
內容同步：雙向 D1 同步，支援衝突偵測、軟刪除傳播、R2 資產同步
設計系統
實作雙主題系統（主站 Quartz 主題、文件站各區域專屬主題）
建構互動元素：3D 圓餅地圖、傳送門轉場、區域環境氣氛、開機動畫
區域專屬背景特效：文字粒子（歷史）、回聲漣漪（回聲）、光柱（視覺）、數位雨（概念）
核心功能
1. 雙站 Monorepo 架構
apps/root（主站）：Astro 5.x + React + Tailwind，靜態輸出搭配 SSR 管理頁面（port 4320）
apps/uep（文件站）：Astro 4.x + React + MDX，混合 SSR + 靜態輸出（port 4321）
packages/config：共用 ESLint、Prettier、TypeScript、Tailwind 設定
packages/ui：共用 UI 元件
2. Cloudflare 邊緣資料層
D1 資料庫（
eternity-content）：層級式頁面表（parent_id/depth/page_type），加上 5 張主站內容表R2 儲存：兩個隔離桶——
eternity-assets（文件站）與eternity-root-assets（主站）KV 儲存（
VISITOR_STATS）：按頁面追蹤的訪客計數器content-api Worker：完整 CRUD REST API，寫入操作需 JWT 認證
3. 區域式閱讀器系統
六大區域各有專屬 React 閱讀器：HistoryReader、EchoesReader、VisualsReader、ConceptsReader、StorageReader
每個區域有獨特的視覺識別：專屬轉場動畫、背景特效、開機動畫
共用基礎元件：ReaderShell、ZoneStateDisplay、ZonePrevNext、contentVisibility、useZoneRouter
4. TipTap 後台編輯器
三欄式佈局：目錄樹側欄、富文字編輯器、屬性檢查器
依區域/頁面類型分派不同編輯器主體（回聲歌曲、視覺圖庫、概念結構化資料）
整合 R2 的媒體庫、圖片選取對話框、拖放上傳
5. 內容同步管線
pnpm sync——互動模式，顯示差異並逐項確認pnpm sync:push/pnpm sync:pull——批次同步搭配衝突解決R2 資產同步搭配
deleted_assets表追蹤軟刪除支援區域範圍同步：
--area history只同步指定區域
6. 國際化
主站支援
zh-tw（預設）與en，使用路徑策略路由多語內容存放於 D1，透過統一 API 層提供
使用技術
前端
Astro 5.x / 4.x：靜態網站生成搭配混合 SSR
React：互動元件（閱讀器、編輯器、地圖）
Tailwind CSS：原子化樣式搭配自訂設計 token
TipTap：富文字編輯器搭配自訂擴充（對話節點、頁面連結）
MDX：Markdown 搭配嵌入元件用於文件站
後端 / 基礎設施
Cloudflare Workers：邊緣部署 API 伺服器
Cloudflare D1：相容 SQLite 的邊緣資料庫
Cloudflare R2：相容 S3 的物件儲存
Cloudflare KV：鍵值儲存用於訪客統計
Resend API：聯絡表單交易郵件
建構與開發
Turborepo：Monorepo 建構編排
pnpm Workspaces：套件管理搭配 workspace 協定
Vitest：單元與 Worker 整合測試
Playwright：E2E 與壓力測試
GitHub Actions：CI/CD 自動打標與部署
專案狀態
目前版本：v0.9.8-stable
主站：功能完備，含後台編輯器、作品/動態/連結管理、i18n
文件站：六大區域全數實作，各有專屬閱讀器與編輯器
內容 API：正式部署，含 JWT 認證、R2 資產管理、同步端點
測試狀況
單元測試（Vitest）涵蓋前端元件與 Worker 邏輯
E2E 煙霧測試（Playwright）涵蓋關鍵使用者流程
壓力與效能門檻測試
負載測試涵蓋本地與 staging 環境
開發挑戰與成就
1. CMS 遷移：從 Keystatic 到 D1
挑戰：原主站使用 Keystatic（檔案式 CMS），與 Cloudflare 部署產生摩擦，無法支援即時編輯。
解法：完全遷移至 Cloudflare D1 搭配自建 content-api Worker，從零打造完整後台編輯器。
成果：
完全自主的內容管理，無第三方 CMS 依賴
即時編輯搭配即時預覽
開發環境與正式環境之間的雙向同步
2. 區域式閱讀器架構
挑戰：每個文件站區域（歷史、回聲、視覺、概念、儲存）有根本不同的內容模型——散文、音樂、圖庫、結構化資料、收藏品。
解法：為每個區域建構專屬閱讀器，同時抽取共用導航基礎元件（ReaderShell、ZonePrevNext、useZoneRouter）以保持一致性。
成果：
每個區域維持獨特的閱讀體驗
統一的 URL 狀態管理與轉場系統
統一的後台編輯器搭配模式分派
3. 邊緣優先資料架構
挑戰：傳統伺服器渲染網站面臨冷啟動延遲問題。內容需要全球可用且延遲極低。
解法：將整個資料層部署在 Cloudflare 邊緣（D1 + R2 + KV），Worker 在邊緣處理 API 邏輯。
成果：
全球 API 回應時間低於 100ms
主站頁面零成本靜態託管
隔離的 R2 儲存桶防止跨站資產污染
4. 內容同步系統
挑戰：開發需要存取本地 D1，但正式資料在遠端 D1。變更需要雙向流動且不產生衝突。
解法：建構完整同步系統，搭配差異偵測、時間戳衝突解決、軟刪除傳播、R2 資產追蹤。
成果：
互動式同步模式搭配逐項確認
區域範圍同步用於針對性更新
刪除資產追蹤防止已刪除檔案復活
未來規劃
短期目標
歷史內容中的互動嵌入（實體標記、跨區域引用）
浮動互動面板的 Island runtime
中期目標
全站搜尋搭配指令面板（Ctrl+K）
閱讀進度追蹤與章節門控
跨區域音樂播放清單
長期目標
公開測試版發佈（v1.0.0）
區域擴充的外掛生態系
行動裝置優化的閱讀體驗
專案亮點
技術創新
✅ 以 Cloudflare D1/R2/KV 作為唯一資料層的邊緣優先架構
✅ 本地與遠端 D1 之間的雙向內容同步
✅ 搭配共用導航基礎元件的區域式閱讀器系統
設計成就
✅ 沉浸式世界觀文件搭配 3D 地圖與環境特效
✅ 六種獨特區域體驗（文字粒子、回聲漣漪、光柱、數位雨）
✅ 雙設計系統：Quartz（主站）+ 區域專屬主題（文件站）
開發品質
✅ 完整的 monorepo 工具鏈（Turborepo + pnpm workspaces）
✅ 多層測試（單元、Worker 整合、E2E、壓力、負載）
✅ CI/CD 自動打標、回推同步與部署
技術棧：Astro、React、TypeScript、Tailwind CSS、Cloudflare Workers/D1/R2/KV、TipTap、Turborepo Monorepo 結構：2 個應用 + 2 個 Worker + 2 個共用套件 部署：Cloudflare Pages（4 個專案）+ Cloudflare Workers（2 個服務）
