pure-genealogy：開源族譜系統，把家族血緣關係化為 2D／3D 視覺化

Facebook Line Messenger Telegram

pure-genealogy 是一個以 Next.js 與 Supabase 為技術骨幹的開源族譜管理系統，由開發者 yunfengsa 在 2026 年 1 月釋出，MIT 授權，原始碼託管於 GitHub。它的核心命題很明確：把家族成員拆解成一張可結構查詢的資料表，再用 2D 樹狀圖、3D 力導向圖與擬物化的「生平冊」介面，把那些原本散在 Excel 與族譜紙本裡的血緣關係，變成可以長期傳承的數位資料。

這篇文章把官方 README、.env.example、family_members.sql 與 GitHub Issues 真實長相整理給你，並標出幾個需要先理解再決定是否投入的設計取捨：它不是純前端 local-first 工具，預設要連 Supabase 雲端；資料表只建模 father_id（父系），母系需要靠 spouse 欄位變通；最後一次 commit 停在 2026 年 1 月 22 日，目前 Docker 部署仍待社群 PR 整合。

開始之前：先把定位看清楚

pure-genealogy 在 README 裡的自我描述是「基於 Next.js 15 與 Supabase 構建的現代化、全中文家族族譜管理系統」。實際對照 package.json，Next.js 15.3.1、@supabase/ssr 與 @supabase/supabase-js 確實是後端依賴，UI 用 shadcn/ui（Radix UI 為底）加 Tailwind CSS，2D 視覺化用 @xyflow/react（React Flow），3D 用 react-force-graph-3d 加 three.js，Rich Text 編輯器是 Slate.js，Excel/CSV 匯入匯出靠 xlsx 套件。

這裡需要先做一個誠實的釐清：它不是純前端 local-first 工具，而是一套自架伺服器應用。Supabase 雖然可以自架（官方有 self-hosted 版本），但 README 預設流程是把你導去 Supabase 雲端開專案、拿 URL 與 anon key。換句話說，家族成員的姓名、生日、居住地這類個資，預設會落到你指定的 Supabase 專案裡，而不是只在你的筆電硬碟上。如果你對「資料不出本機」有硬性要求，可以參考 Scanned Maker 那類純前端工具的設計，或評估自行架設 Supabase 自架版的成本。Supabase 雲端免費方案會把專案閒置後暫停（活躍專案每週至少一次 API 呼叫才不會睡著），這對「偶爾翻一下家族資料」的使用情境是個隱形成本。

另一個要先看的差異是：pure-genealogy 不試圖取代 Gramps 那類研究級譜系軟體的全部功能，而是把焦點放在「中文脈絡下的家族檔案視覺化」，特別是字輩（家族命名傳承的字序規則）與世代標尺的呈現。對本地使用者來說，字輩這個詞可能比中國大陸讀者陌生一些，但在重視宗族傳承的閩南、客家家族裡仍是常見的做法。

家族成員怎麼被建模：一張資料表背後的設計選擇

整個系統的核心其實只有一張 family_members 資料表，定義在 .github/family_members.sql 裡。把它攤開來看會比 README 的功能列表更有資訊量：

頂層結構只有 family_members 一張表，所有成員（無論第幾代）都落在這張表，靠 father_id 自我外鍵串聯血緣邊。沒有獨立的婚姻表、事件表或多代關係表。
id 是 BIGINT GENERATED ALWAYS AS IDENTITY，PostgreSQL 自增，不會因為刪除成員而回收；這對長期經營的家族檔案是好事，但代表匯出 CSV 後 id 欄位不會連續。
索引只建在 father_id 與 name，沒有為 generation、sibling_order 或 birthday 建索引，大型家族的統計視圖可能會明顯變慢。
沒有 Row Level Security（RLS）設定，所有登入使用者都能讀寫全表。要把在世成員欄位鎖起來，得自行加 RLS policy。

具體欄位有十四個：

id、name、generation（世代）、sibling_order（排行）
father_id（父親的外鍵，指向同一張表）、spouse（配偶，純文字欄位）
gender（限「男」或「女」）、is_alive（是否在世）
official_position（官職）、residence_place（居住地）
birthday、death_date、remarks（用 Slate.js Rich Text JSON 存生平）
updated_at 自動更新時間戳

攤開這張 schema，幾個設計選擇值得先思考：

血緣關係只建模 father_id，沒有 mother_id，配偶只用一個純文字欄位。這個模型對父系宗族脈絡自然順手，但對想完整追蹤母系家族、跨姓氏聯姻或收養關係的需求會明顯綁手，只能靠 spouse 字串與 remarks 補充，無法直接做「母系五代關係圖」。這是使用前要先承認的限制。
性別欄位的 CHECK 條件硬編為「男」或「女」，沒有留其他選項。這在統計儀表板的性別比例圖與字輩分析裡會直接影響呈現結果，對當代家族成員的多樣性可能有簡化風險。
remarks 用來存 Slate.js Rich Text JSON，而不是單純長文字。這給生平冊頁面帶來擬物化的書卷排版（毛筆掃過、逐字書寫動畫），但也意味著資料無法直接被其他工具讀取，要靠系統自己的匯出功能。

視覺化：2D 樹狀圖、3D 力導向與生平冊

README 列出的視覺化模組有四個：2D 族譜圖、3D 關係網、統計儀表板、時間軸，再加上「Living Book」生平冊。實際看作者釋出的 app/demo.gif 與 demo 站台（純粹作為設計參考），可以觀察到幾件事：

pure-genealogy 2D 族譜圖與成員列表視圖，可看到上方導航列與左側世代標尺的設計 — pure-genealogy 的 2D 族譜圖與成員列表視圖（截自官方 demo.gif）。導航列從左到右為成員列表、2D 族譜、3D 族譜、時間軸、統計分析、生平冊。

2D 族譜圖（/family-tree/graph 路由）用 React Flow 搭配 Dagre 階層式排版演算法自動佈局，左側標出水墨風格的「世代標尺」，每個節點根據代數深淺漸層（README 稱為松柏綠瀑布式）。點擊節點會觸發兩個方向的高亮路徑：「金線溯源」往祖先方向、「金扇繁衍」往子孫方向，並支援一鍵匯出帶背景與浮水印的高清大圖。

3D 關係網（/family-tree/graph-3d）是這套工具差異化最明顯的部分。它用 react-force-graph-3d 把所有成員丟進一個三維力導向空間，README 標榜的「自動巡遊」會計算任意兩位成員間的最短關係路徑，再讓攝影機自動飛行瀏覽。這個功能對驗證資料錄入邏輯（父子關係倒置、代際斷層）的實用性比視覺炫技更值得提，二維樹狀圖很難直觀看出循環或斷裂。

pure-genealogy 的 3D 力導向關係網視圖，所有家族成員被排進三維空間，以節點與連線呈現血緣關係 — pure-genealogy 的 3D 關係網視圖（截自官方 demo.gif）。每個光點對應一位家族成員，連線表達 father_id 外鍵建立的血緣邊。

統計儀表板（/family-tree/statistics）用 recharts 畫家族人口概覽、性別比例、在世比例、世代增長趨勢、年齡分佈、字輩頻率統計。時間軸（/family-tree/timeline）以橫向軸呈現生卒年分佈。而生平冊（/family-tree/biography-book）是這套系統在「呈現」這一環最用力的設計：擬物化書卷介面，正面展示檔案、背面展示 Slate.js 排版的生平傳記，還有逐字書寫與毛筆掃過的動畫效果。

把它跑起來：四個步驟與兩個要先知道的卡點

README 給的部署流程是典型的 Next.js + Supabase 模板：複製專案、裝依賴、配環境變數、跑 SQL、啟開發伺服器。實際走一遍會遇到幾個需要先有心理準備的地方。

步驟一，clone 與 npm install。git clone https://github.com/yunfengsa/pure-genealogy.git 後，npm install 在多數 Node.js 22 以上環境可直接跑完，但 Issue #3（2026 年 1 月 24 日）回報過依賴安裝錯誤，建議先用最新的 Node.js LTS 再嘗試。

步驟二，配置 .env.local。.env.example 只列了三個變數：NEXT_PUBLIC_SUPABASE_URL、NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY，以及一個家族姓氏設定 NEXT_PUBLIC_FAMILY_SURNAME，預設值是「劉」的簡體寫法。這個預設值會直接反映在登入頁標題（例如 demo 站顯示「劉氏族譜管理系統」）與整個 UI 的家族代稱，部署前請改成繁體「劉」或你自己的姓氏。

步驟三，建立 Supabase 專案並執行 SQL。到 Supabase 官方雲端（或自架版）建立專案後，把 .github/family_members.sql 貼進 SQL Editor 跑一次，建立主表與索引。這裡需要誠實標示：這套系統的資料主權範圍，取決於你選擇哪種 Supabase。官方雲端的免費方案把資料放在 Supabase 的基礎設施，雖然技術上是你的專案，但營運層與平台層的存取風險仍在；要達到接近完全私有，得自行架設 Supabase 自架版（Docker compose 部署，資源消耗不低）。這條取捨類似我們在巴菲特股東信知識庫那篇文章討論過的「第三方平台 vs 自架基礎設施」邊界。

步驟四，npm run dev。本機跑起來後造訪 http://localhost:3000，會被導到登入頁。README 的 demo 帳號是 [email protected] 與密碼 123456。這組帳號在官方 demo 站（pure-genealogy.onehacker.top）是公開有效的，任何人都能登入看示範資料。這意味著兩件事：你可以馬上體驗系統，但生產環境部署時務必在第一時間刪除測試帳號、改密碼、關閉註冊，否則你的家族資料會門戶洞開。

另一個卡點是 Docker。截至 2026 年 7 月，官方 repo 沒有 Dockerfile 也沒有 docker-compose。Issue #5 與 #8 都在請求 Docker 支援，其中 #8 是一個待審的 PR（renxia 在 2026 年 3 月 20 日提交，加入 Dockerfile 與 GitHub Actions 自動構建映像）。在 PR 合併前，部署流程綁定 Node.js + Supabase 雲端的「官方路徑」，對習慣一鍵 docker compose up 的使用者會是阻力。

和其他選擇的差異

把 pure-genealogy 放在幾個常見家族譜管理選項之間比較，會更容易看出它的位置：

方案	資料落地	視覺化重點	授權與費用	適合脈絡
Excel / Google Sheets	本機或雲端試算表	純欄位，無樹狀圖	商業軟體授權	百人以內的小型家族
MyHeritage / Ancestry	商業平台雲端	家譜樹與歷史檔案比對	訂閱制服務	跨國尋親與歷史紀錄
Gramps（開源桌面）	本機 XML 檔	完整譜系研究工具	GPL，免費	研究級、多關係類型
pure-genealogy	Supabase（預設雲端，可自架）	2D／3D 視覺化與字輩統計	MIT，免費	中文宗族脈絡、強調呈現

pure-genealogy 與常見家族譜管理方案的差異（整理自各方案官方文件，2026 年 7 月）。

從這個比較可以看出，pure-genealogy 的位置不在「研究級譜系工具」（那是 Gramps 的領域），也不在「跨國歷史檔案比對」（那是 MyHeritage 與 Ancestry 的訂閱價值），而是在「中文家族脈絡下，把可視化呈現與字輩世代標示做得相對用心的自架方案」。它的競爭優勢是介面質感與中文在地化，劣勢是父系建模、缺少 Docker 與 GEDCOM 匯入支援。

適合誰、不適合誰

適合：有 Next.js 或 Supabase 經驗、能自己架設資料庫、想完整控制 UI 與資料結構、家族重視字輩傳承的開發者型使用者。
適合：把家族檔案當成長期數位資產經營，願意定期備份與維護的小型家族。
不適合：完全不願碰指令列與資料庫設定、只想安裝即用的桌面軟體使用者，這套需要基本的 DevOps 投入。
不適合：母系家族脈絡完整追蹤需求高、需要表達收養與跨姓氏聯姻關係的使用者，目前 schema 不支援。
不適合：對「資料完全不出本機」有硬性要求的使用者，除非自行架設 Supabase 自架版。

限制與風險清單

專案活躍度：GitHub 顯示最後一次 commit 在 2026 年 1 月 22 日，之後五個月沒有新提交。Issues 仍有持續累積（#10 在 4 月、#8 PR 在 3 月），但維護節奏偏慢。採用前要評估是否能自行 fork 維護。
Supabase 雲端相依：預設部署仰賴 Supabase 官方雲端。NEXT_PUBLIC_SUPABASE_URL 一旦指向某個 Supabase 專案，家族資料就落在那個專案的 PostgreSQL 裡，跨專案搬移需要正確匯出匯入。
預設啟用 Vercel Analytics：app/layout.tsx 引入了 @vercel/analytics，若部署到 Vercel 會自動收集訪客分析資料。在意遙測的使用者需要自行移除這行或改用自架 Supabase + 自架前端 Hosting。
測試帳號公開：README 描述的 [email protected]／123456 在官方 demo 站仍可登入。生產部署第一件事是停用這組帳號、改密碼、關閉開放註冊。
在世成員個資：姓名、生日、居住地、官職欄位都會進資料庫。系統沒有內建的欄位級權限控管，分級顯示需要在應用層自行處理。涉及在世親屬個資的處理可參考我們在 Secure PDF Editor 討論過的「最小揭露」原則。
父系建模限制：family_members 只有 father_id 外鍵，沒有 mother_id，配偶用純文字欄位。母系家族脈絡與收養關係無法直接表達。
中國大陸預設值與簡繁：UI 文案是簡體中文，姓氏預設是「劉」的簡體寫法，字輩欄位統計針對中國大陸命名傳統設計，繁體讀者需要自行繁體化與調整預設值。 fork 專案修改 app/ 目錄下的中文文案是已知可行的路徑，但會增加後續合併官方更新的摩擦。

常見問題

字輩是什麼？本地家族會用到嗎？

字輩是家族為世代命名時預先約定的字序規則，例如「文章華國、詩禮傳家」這類八句或四句的詩。同一代的家族成員名字中會共用同一個字。閩南、客家家族在台灣仍有這個傳統，但都會區年輕一代未必遵循。pure-genealogy 的字輩統計模組對有這個傳統的家族實用，對沒有的家族則只是一個不會被填的欄位。實際上 README 提到的「字輩統計」對應的是 generation 欄位的數值聚合（例如每一代的成員計數），而不是從姓名中自動萃取共用字序；要呈現真正的字輩詩，需要手動在 remarks 或家族介紹區塊補充說明。

支援 GEDCOM 匯入嗎？

不支援。系統的匯入匯出限於 Excel／CSV（透過 xlsx 套件），欄位是針對中文家族脈絡設計，不是國際標準的 GEDCOM 5.5.1 或 GEDCOM 7。如果你已經有 Gramps 或 MyHeritage 的 GEDCOM 檔，需要自行寫腳本轉換成 CSV 才能匯入。

有 Docker 部署嗎？

官方 repo 目前（2026 年 7 月）沒有合併的 Docker 支援。Issue #8 是一個待審 PR，加入 Dockerfile 與 GitHub Actions 自動構建映像，但尚未被維護者合併。在此之前，部署走 Node.js + Supabase 雲端的傳統路徑。

母系家族怎麼辦？

目前資料表的設計無法直接表達母系血緣。可行的變通是利用 spouse 欄位記錄母系祖先、把母系成員也建成獨立的 family_members 記錄（但就無法和父系節點形成外鍵連結），或自行 fork 專案加入 mother_id 欄位與視覺化規則。

自架的成本與回報

pure-genealogy 把「家族血緣」這件本來會隨時間散佚的事，變成一套有結構、可視覺化、長期可查詢的數位資料，前提是你願意承擔自架 Supabase 與持續維護的成本。它的設計選擇（父系建模、預設雲端、預設簡體中文、Docker 缺位）說明它仍在早期階段，適合當作起點而非最終方案。對有 Next.js 開發能力、想為家族留一份可傳承數位檔案的技術型使用者來說，是一個值得 fork、改造、自架的基礎；對只想快速上手的使用者，Excel 或許還是目前摩擦最低的選擇。