jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/SUPABASE_SETUP_GUIDE.md

6.1 KiB
Raw Blame History

🗄️ Supabase 環境變數配置指南

📋 配置檢查清單

準備工作

  • 已有 Supabase 帳號和專案
  • 已記住資料庫密碼
  • 瀏覽器已開啟 Supabase Dashboard

🔑 Step 1: 從 Supabase 獲取所需資訊

1.1 登入 Supabase Dashboard

# 開啟瀏覽器前往:
https://app.supabase.com

1.2 選擇或建立專案

  • 如果沒有專案，點擊 "New Project"
  • 專案名稱建議: dramaling-dev
  • 區域選擇: Singapore (Southeast Asia)

1.3 獲取 API 設定資訊

導航: 左側選單 → Settings → API

需要複製的資訊:

1. Project URL: https://[your-project-id].supabase.co
2. anon public: eyJ[...很長的字串...]
3. service_role secret: eyJ[...很長的字串...]

1.4 獲取 JWT Secret

位置: 同頁面下方 JWT Settings

JWT Secret: [your-super-secret-jwt-token-with-at-least-32-characters-long]

1.5 獲取資料庫連接資訊

導航: 左側選單 → Settings → Database

連接參數:

Host: db.[your-project-id].supabase.co
Database: postgres
Port: 5432
User: postgres
Password: [您建立專案時設定的密碼]

🔧 Step 2: 配置後端 (.NET Core)

2.1 編輯後端配置檔案

檔案: backend/DramaLing.Api/appsettings.Development.json

請將以下範本中的 [替換這裡] 替換為實際值:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=db.[your-project-id].supabase.co;Database=postgres;Username=postgres;Password=[your-db-password];Port=5432;SSL Mode=Require;"
  },
  "Supabase": {
    "Url": "https://[your-project-id].supabase.co",
    "ServiceRoleKey": "[your-service-role-key]",
    "JwtSecret": "[your-jwt-secret]"
  },
  "AI": {
    "GeminiApiKey": "[your-gemini-api-key]"
  },
  "Frontend": {
    "Urls": ["http://localhost:3000", "http://localhost:3001"]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.EntityFrameworkCore": "Information",
      "DramaLing.Api": "Debug"
    }
  }
}

2.2 配置範例 (請替換實際值)

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=db.abcdefghij.supabase.co;Database=postgres;Username=postgres;Password=MySecretPassword123;Port=5432;SSL Mode=Require;"
  },
  "Supabase": {
    "Url": "https://abcdefghij.supabase.co",
    "ServiceRoleKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "JwtSecret": "your-super-secret-jwt-token-with-at-least-32-characters-long"
  }
}

🎨 Step 3: 配置前端 (Next.js)

3.1 建立前端環境變數檔案

檔案: frontend/.env.local (新建立)

# 執行以下指令建立檔案:
cp .env.example frontend/.env.local

3.2 編輯前端環境變數

檔案: frontend/.env.local

請將以下範本中的 [替換這裡] 替換為實際值:

# Supabase 前端配置 (認證用)
NEXT_PUBLIC_SUPABASE_URL=https://[your-project-id].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=[your-anon-public-key]

# API 服務配置
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_APP_URL=http://localhost:3001

3.3 前端配置範例 (請替換實際值)

NEXT_PUBLIC_SUPABASE_URL=https://abcdefghij.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_APP_URL=http://localhost:3001

🧪 Step 4: 測試配置

4.1 測試後端資料庫連接

# 重新啟動後端 API
./start-dotnet-api.sh

# 檢查啟動日誌中是否有資料庫連接錯誤
# 如果成功，應該會看到 "Application started" 訊息

4.2 測試 API 端點

# 測試健康檢查
curl http://localhost:5000/health

# 預期回應:
# {"Status":"Healthy","Timestamp":"2025-09-16T..."}

4.3 測試 Swagger API 文檔

# 瀏覽器訪問:
http://localhost:5000/swagger

# 應該看到 4 個控制器:
# - Auth (用戶認證)
# - CardSets (卡組管理)
# - Flashcards (詞卡管理)
# - Stats (統計分析)

4.4 測試前端 Supabase 連接

# 重新啟動前端
./start-frontend.sh

# 瀏覽器訪問前端並檢查 Console:
http://localhost:3001

# 在瀏覽器 Console 中不應該看到 Supabase 連接錯誤

🚨 常見問題和解決方案

❌ 資料庫連接失敗

錯誤: Npgsql.NpgsqlException: Connection refused

解決方案:

  1. 檢查 IP 白名單: Settings → Database → Network Restrictions
  2. 確認密碼正確
  3. 確認 Host 地址正確

❌ JWT 驗證失敗

錯誤: 401 Unauthorized

解決方案:

  1. 確認 JWT Secret 正確複製 (完整字串)
  2. 檢查 Issuer URL 是否正確
  3. 確認前端傳送的令牌格式

❌ CORS 錯誤

錯誤: Access-Control-Allow-Origin

解決方案:

  1. 檢查 Program.cs 中的 CORS 設定
  2. 確認前端 URL 在允許清單中

📝 實際動手步驟

👉 您現在需要做的:

第一步: 開啟 Supabase Dashboard

# 1. 在瀏覽器中開啟:
https://app.supabase.com

# 2. 登入並選擇專案
# 3. 前往 Settings → API 頁面

第二步: 複製 API 資訊

# 將以下資訊準備好 (可以先貼到記事本):
Project URL: https://
Anon Key: eyJ
Service Role Key: eyJ
JWT Secret: your-super-secret
Database Password:

第三步: 通知我配置資訊

# 告訴我您已經取得了資訊，我會幫您配置檔案
# (當然不要貼出真實的密鑰，只要說 "我已經取得了" 即可)

第四步: 我會幫您配置檔案並測試

🎯 配置完成後的效果

✅ 後端功能

  • Entity Framework 可以連接到 Supabase PostgreSQL
  • JWT 認證可以驗證前端的 Supabase 令牌
  • API 可以正確識別登入用戶

✅ 前端功能

  • 可以使用 Supabase Auth 登入
  • 可以呼叫 .NET Core API 並附加認證令牌
  • Dashboard 可以顯示真實的用戶資料

✅ 整體效果

  • 前後端完全整合
  • 用戶可以登入並看到個人化內容
  • 所有 API 都有適當的認證保護

準備好開始了嗎？請先取得 Supabase 的連接資訊！ 🚀