# 從 Supabase 遷移到 Insforge：教學指南

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

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

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

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

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

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

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

讓我們開始吧。

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

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

### 1. 先決條件

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

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

### 2. 環境設定

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

首先，複製該工具包的[儲存庫](https://github.com/InsForge/supabase-to-insforge)（或下載原始碼）並安裝依賴套件。

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

# 安裝依賴套件
npm install
```

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

```bash
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](https://cdn.zeabur.com/psqlstring.png)

```
# ============================================
# 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. 驗證您的連線

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

```bash
# 測試 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 檔案中。

```bash
npm run export:auth
```

**預期輸出：**

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

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

### 步驟 1.2：將使用者匯入 Insforge

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

```bash
npm run import:auth
```

**預期輸出：**

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

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

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

### 階段 2：遷移您的資料庫

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

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

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

```bash
npm run export:db
```

**預期輸出：**

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

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

### 步驟 2.2：為 Insforge 轉換 SQL

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

```bash
npm run transform:db
```

**預期輸出：**

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

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

### 步驟 2.3：將資料庫匯入 Insforge

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

```bash
npm run import:db
```

**預期輸出：**

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

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

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

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

### 步驟 3.1：重新建立儲存桶

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

```bash
npm run create:buckets
```

**預期輸出：**

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

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

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

```bash
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 中對應的儲存桶。

```bash
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 欄位內部。

```bash
npm run update:storage-urls
```

**預期輸出：**

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

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

---

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

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

1.  **更新應用程式碼：** 將您的應用程式用戶端設定指向您的 Insforge 執行個體，而不是 Supabase。有關使用 MCP 重新設定 SDK 的詳細指導，請查看我們的[配套部落格文章](https://zeabur.com/blogs/lovable-to-zeabur-insforge)。

    ```jsx
    // 之前 (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` 連線字串是否正確。

遷移愉快！🚀