logo

價格

從 Supabase 遷移到 Insforge：教學指南

一個開源工具包，助您無損遷移整個 Supabase 專案——包含使用者、資料庫及檔案。

Kyle ChungKyle Chung

在幾分鐘內從 Supabase 遷移到 Insforge：一份經過生產環境測試的完整指南

你好！既然您決定將專案從 Supabase 遷移到 Insforge，本指南就是為您準備的。資料遷移可能令人望而生畏。您可能會想：如何在不強制使用者重設密碼的情況下遷移所有使用者？如何傳輸每一個檔案並更新所有連結？資料庫結構和那些寶貴的資料又該怎麼辦？

別擔心，我們都為您考慮周全了。

本指南將介紹一個經過生產環境測試的完整遷移工具包，旨在將您的整個 Supabase 專案無縫過渡到一個自託管的 Insforge 執行個體。我們所說的不僅僅是部分資料轉儲，而是一次完整的遷移，它將保留：

  • ✅ 使用者認證（包含密碼！）
  • ✅ 完整的資料庫（結構和資料）
  • ✅ 所有儲存檔案（路徑完全一致）
  • ✅ 外來鍵關聯（透過保留使用者 ID）

該工具包已在真實的生產環境中經過實戰檢驗，成功遷移了 39 位使用者、985 筆資料庫記錄以及超過 1500 個儲存檔案，無任何資料遺失。有關自託管的更多資訊，請查看 Insforge GitHub 儲存庫。

讓我們開始吧。

開始之前：您的遷移前檢查清單

在開始之前，讓我們先設定好環境，確保遷移過程順利。

1. 先決條件

首先，請確保您已具備必要的工具和存取權限：

  • 軟體：
    • Node.js (v20+)
    • PostgreSQL 用戶端 (psql)
  • 存取權限：
    • 您的 Supabase 專案憑證（API 金鑰、資料庫 URL）。
    • 一個擁有管理員 API 金鑰的有效 Insforge 執行個體。

2. 環境設定

現在，讓我們來設定遷移工具本身。

首先，複製該工具包的儲存庫（或下載原始碼）並安裝依賴套件。

# 複製儲存庫 (如適用)
# git clone <https://github.com/InsForge/supabase-to-insforge>

# 安裝依賴套件
npm install

接下來，建立您的環境設定檔。複製範例檔案來建立您自己的 .env 檔案。

cp .env.example .env

現在，打開新建立的 .env 檔案，並填入您決定遷移的 Supabase 專案和新的 Insforge 專案的憑證。

尋找您的 Supabase 憑證

要填寫 .env 檔案，您需要從 Supabase 專案儀表板中獲取三項關鍵資訊。

  1. SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY：
    • 導覽至您的 Supabase 專案。
    • 進入 Project Settings（齒輪圖示）。
    • 點擊 API。
    • 在這裡，您將找到您的專案 URL 和 service_role 金鑰。
  2. SUPABASE_DB_URL（您的連線字串）：
    • 在您的 Supabase 專案儀表板中，點擊頁面頂部的 Connect 按鈕。
    • 一個面板將會開啟，其中包含您的資料庫連線詳細資訊。
    • 從 Direct connection 區塊複製 URI。
    • 重要提示： 您必須將字串中的 [YOUR-PASSWORD] 佔位符替換為您的實際資料庫密碼。如果您忘記了密碼，可以在 Project Settings > Database 中重設。

PSQL String

# ============================================
# Supabase 設定
# ============================================
# 在 Supabase 設定中找到這些憑證
SUPABASE_URL=https://您的專案.supabase.co
SUPABASE_SERVICE_ROLE_KEY=您的_supabase_service_role_key
SUPABASE_DB_URL=postgresql://postgres.xxx:[您的密碼]@...

# ============================================
# Insforge 設定
# ============================================
# 您的 Insforge 執行個體詳情
INSFORGE_API_URL=http://localhost:7130 # 或您的遠端 URL
INSFORGE_API_KEY=您的_insforge_api_key

3. 驗證您的連線

在執行遷移之前，讓我們確保該工具可以連線到兩個資料庫。執行以下指令來測試您的連線：

# 測試 Supabase 連線
psql "$SUPABASE_DB_URL" -c "SELECT version();"

# 測試 Insforge 連線 (根據您的本地/遠端設定進行調整)
psql postgresql://postgres:postgres@localhost:5432/insforge -c "SELECT version();"

# 退出
\\q

如果兩個指令都無誤執行，那麼您就可以開始正式遷移了！

偉大的遷移：步驟指南

遷移過程分為三個邏輯階段。請按順序執行以獲得最佳效果。

階段 1：遷移您的使用者（無需重設密碼！）

這通常是任何遷移中最棘手的部分，但這個工具包讓它變得簡單。我們將遷移所有使用者帳戶，同時保留他們原有的密碼。

步驟 1.1：從 Supabase 匯出使用者

此指令會連線到您的 Supabase 專案，並將 auth.users 資料表中的所有使用者匯出到一個本地 JSON 檔案中。

npm run export:auth

預期輸出：

✅ 已連線到 Supabase PostgreSQL
✅ 已將 39 位使用者匯出到 auth-export.json

這將建立一個名為 auth-export.json 的檔案，其中包含使用者詳情，包括他們的 ID 和加密密碼。

步驟 1.2：將使用者匯入 Insforge

現在，我們將從 auth-export.json 檔案中將使用者匯入到您的 Insforge 執行個體。該腳本會保留原始的使用者 ID（對於外來鍵至關重要）和他們經過 bcrypt 雜湊的密碼。

npm run import:auth

預期輸出：

✅ 已連線到 Insforge API
   URL: <https://your-insforge-instance.insforge.app>

📦 已載入匯出資料...
⬆️  正在匯入使用者...
   ✅ 已匯入 41/41 個帳戶
✅ 匯入完成！

專業提示： 這個腳本是冪等的，這意味著您可以多次執行它而不會建立重複的使用者。如果發現現有記錄，它只會更新這些記錄。

階段 2：遷移您的資料庫

接下來，我們將遷移您的整個 PostgreSQL 資料庫，包括結構、資料，甚至您的資料列層級安全性（RLS）原則。

步驟 2.1：匯出資料庫結構和資料

此指令使用 pg_dump 為您的 Supabase 公開結構描述建立一個完整的 SQL 備份。

npm run export:db

預期輸出：

✅ 資料庫匯出成功
   檔案: database-export.sql (245 KB)

這將產生一個 database-export.sql 檔案。

步驟 2.2：為 Insforge 轉換 SQL

Supabase 使用了一些特定的函式和擴充套件。此腳本會清理匯出的 SQL 檔案，移除 Supabase 特定的程式碼，更新 RLS 原則（例如，auth.uid() 變為 uid()），並使其與 Insforge 相容。

npm run transform:db

預期輸出：

✅ 已為 Insforge 轉換 SQL
   輸出: database-export.insforge.sql

這將建立一個新的、為 Insforge 準備好的檔案：database-export.insforge.sql。

步驟 2.3：將資料庫匯入 Insforge

最後，讓我們將轉換後的 SQL 檔案匯入到您的 Insforge 專案中。

npm run import:db

預期輸出：

🗄️  正在將資料庫匯入 Insforge...
✅ 資料庫匯入完成！
受影響的資料表: 12
匯入的資料列數: 985

您的資料庫結構和資料現已成功遷移！

階段 3：遷移您的檔案儲存

最後一個階段是將您所有的檔案從 Supabase Storage 移動到 Insforge Storage。這個過程會保留精確的檔案路徑，這對於防止連結失效至關重要。

步驟 3.1：重新建立儲存桶

首先，該腳本將從您的 Supabase 專案中讀取儲存桶列表，並在 Insforge 中建立相同的儲存桶，同時保留它們的公開或私有設定。

npm run create:buckets

預期輸出：

✅ 已連線到 Supabase PostgreSQL
📦 在 Supabase 中找到 4 個儲存桶:
📋 正在建立儲存桶: generated-images (public)... ✅ 建立成功
📋 正在建立儲存桶: raw-product-images (public)... ✅ 建立成功
...
✅ 儲存桶建立完成！

步驟 3.2：從 Supabase 下載所有檔案

此指令會從您所有的 Supabase 儲存桶中下載每一個檔案，並保留原始的目錄結構。

npm run export:storage

預期輸出：

📦 開始從 Supabase 匯出儲存...
⬇️  正在下載檔案...
   [1/1572] generated-images/user123/image.jpg ✅
   ...
   [1572/1572] reference-images/ref5.jpg ✅

✅ 匯出完成！已下載: 1,572 個檔案

所有檔案都將儲存在本地的 storage-downloads/ 目錄中。

步驟 3.3：將所有檔案上傳到 Insforge

現在，我們將所有下載的檔案上傳到 Insforge 中對應的儲存桶。

npm run import:storage

預期輸出：

📦 找到 1572 個待匯入檔案
⬆️  [1/1572] generated-images/user123/scene/image.jpg... ✅ 上傳成功
...
✅ 匯入完成！成功: 1569/1572

步驟 3.4：最後的潤飾 - 更新所有儲存 URL

這是見證奇蹟的時刻。您的資料庫中可能包含數千個指向 Supabase Storage 的 URL。此腳本會連線到您的 Insforge 資料庫，並在所有資料表上執行通用的尋找和取代。它會智慧地將每個 Supabase 儲存 URL 更新為新的 Insforge URL，即使是在複雜的 JSONB 欄位內部。

npm run update:storage-urls

預期輸出：

✅ 已連線到 Insforge API
🔄 通用 URL 取代...
📊 發現:
   - 997 個生成的輸入中包含 Supabase URL
   - 1023 個生成的輸出中包含 Supabase URL
⏳ 正在通用更新所有 URL...
✅ 所有 Supabase 儲存 URL 均已更新！

就這樣！您的整個專案現已遷移完畢。

接下來該做什麼？遷移後步驟

您的資料已遷移，但工作尚未完成。以下是讓您的應用程式在 Insforge 上執行的最後幾個步驟。

  1. 更新應用程式碼： 將您的應用程式用戶端設定指向您的 Insforge 執行個體，而不是 Supabase。有關使用 MCP 重新設定 SDK 的詳細指導，請查看我們的配套部落格文章。

    // 之前 (Supabase)
const supabase = createClient('SUPABASE_URL', 'SUPABASE_ANON_KEY');

// 之後 (Insforge)
const insforge = createClient('您的_INSFORGE_API_URL', '您的_INSFORGE_API_KEY');

  2. 端對端測試： 全面測試您的應用程式。

    • 使用者能用舊密碼登入嗎？
    • 圖片和檔案能正常載入嗎？
    • 所有與資料相關的功能都按預期運作嗎？

  3. 清理工作： 一旦您確認一切正常，就可以刪除暫時的遷移檔案（storage-downloads/、.sql、.json）。

常見問題排查

  • 儲存匯入時出現 File too large 錯誤： 您的檔案超出了 Insforge 執行個體的上傳限制。您可能需要提高限制或手動遷移該檔案。
  • 密碼登入失敗： 仔細檢查 import:auth 腳本是否成功執行。bcrypt 密碼雜湊應該被原樣保留。
  • 連線逾時： 驗證您的 IP 是否已在 Supabase 的網路限制中加入白名單，以及您的 .env 連線字串是否正確。

遷移愉快！🚀

return Blogs