262 lines
6.1 KiB
Markdown
262 lines
6.1 KiB
Markdown
# 🗄️ Supabase 環境變數配置指南
|
|
|
|
## 📋 **配置檢查清單**
|
|
|
|
### 準備工作
|
|
- [ ] 已有 Supabase 帳號和專案
|
|
- [ ] 已記住資料庫密碼
|
|
- [ ] 瀏覽器已開啟 Supabase Dashboard
|
|
|
|
---
|
|
|
|
## 🔑 **Step 1: 從 Supabase 獲取所需資訊**
|
|
|
|
### 1.1 登入 Supabase Dashboard
|
|
```bash
|
|
# 開啟瀏覽器前往:
|
|
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`
|
|
|
|
**請將以下範本中的 `[替換這裡]` 替換為實際值**:
|
|
|
|
```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 配置範例 (請替換實際值)
|
|
```json
|
|
{
|
|
"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` (新建立)
|
|
|
|
```bash
|
|
# 執行以下指令建立檔案:
|
|
cp .env.example frontend/.env.local
|
|
```
|
|
|
|
### 3.2 編輯前端環境變數
|
|
**檔案**: `frontend/.env.local`
|
|
|
|
**請將以下範本中的 `[替換這裡]` 替換為實際值**:
|
|
|
|
```env
|
|
# 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 前端配置範例 (請替換實際值)
|
|
```env
|
|
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 測試後端資料庫連接
|
|
```bash
|
|
# 重新啟動後端 API
|
|
./start-dotnet-api.sh
|
|
|
|
# 檢查啟動日誌中是否有資料庫連接錯誤
|
|
# 如果成功，應該會看到 "Application started" 訊息
|
|
```
|
|
|
|
### 4.2 測試 API 端點
|
|
```bash
|
|
# 測試健康檢查
|
|
curl http://localhost:5000/health
|
|
|
|
# 預期回應:
|
|
# {"Status":"Healthy","Timestamp":"2025-09-16T..."}
|
|
```
|
|
|
|
### 4.3 測試 Swagger API 文檔
|
|
```bash
|
|
# 瀏覽器訪問:
|
|
http://localhost:5000/swagger
|
|
|
|
# 應該看到 4 個控制器:
|
|
# - Auth (用戶認證)
|
|
# - CardSets (卡組管理)
|
|
# - Flashcards (詞卡管理)
|
|
# - Stats (統計分析)
|
|
```
|
|
|
|
### 4.4 測試前端 Supabase 連接
|
|
```bash
|
|
# 重新啟動前端
|
|
./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
|
|
```bash
|
|
# 1. 在瀏覽器中開啟:
|
|
https://app.supabase.com
|
|
|
|
# 2. 登入並選擇專案
|
|
# 3. 前往 Settings → API 頁面
|
|
```
|
|
|
|
**第二步**: 複製 API 資訊
|
|
```bash
|
|
# 將以下資訊準備好 (可以先貼到記事本):
|
|
Project URL: https://
|
|
Anon Key: eyJ
|
|
Service Role Key: eyJ
|
|
JWT Secret: your-super-secret
|
|
Database Password:
|
|
```
|
|
|
|
**第三步**: 通知我配置資訊
|
|
```bash
|
|
# 告訴我您已經取得了資訊，我會幫您配置檔案
|
|
# (當然不要貼出真實的密鑰，只要說 "我已經取得了" 即可)
|
|
```
|
|
|
|
**第四步**: 我會幫您配置檔案並測試
|
|
|
|
---
|
|
|
|
## 🎯 **配置完成後的效果**
|
|
|
|
### ✅ **後端功能**
|
|
- Entity Framework 可以連接到 Supabase PostgreSQL
|
|
- JWT 認證可以驗證前端的 Supabase 令牌
|
|
- API 可以正確識別登入用戶
|
|
|
|
### ✅ **前端功能**
|
|
- 可以使用 Supabase Auth 登入
|
|
- 可以呼叫 .NET Core API 並附加認證令牌
|
|
- Dashboard 可以顯示真實的用戶資料
|
|
|
|
### ✅ **整體效果**
|
|
- 前後端完全整合
|
|
- 用戶可以登入並看到個人化內容
|
|
- 所有 API 都有適當的認證保護
|
|
|
|
**準備好開始了嗎？請先取得 Supabase 的連接資訊！** 🚀 |