370 lines
8.2 KiB
Markdown
370 lines
8.2 KiB
Markdown
# 🚀 心願星河 - Supabase 完整建置指南
|
||
|
||
## 📋 目錄
|
||
- [前置準備](#前置準備)
|
||
- [Supabase 項目設置](#supabase-項目設置)
|
||
- [本地環境配置](#本地環境配置)
|
||
- [數據庫建置](#數據庫建置)
|
||
- [存儲服務設置](#存儲服務設置)
|
||
- [安全政策配置](#安全政策配置)
|
||
- [測試驗證](#測試驗證)
|
||
- [數據遷移](#數據遷移)
|
||
- [部署準備](#部署準備)
|
||
- [故障排除](#故障排除)
|
||
|
||
---
|
||
|
||
## 🎯 前置準備
|
||
|
||
### 系統需求
|
||
- Node.js 18+
|
||
- npm 或 yarn
|
||
- 現代瀏覽器
|
||
- Supabase 帳號
|
||
|
||
### 預估時間
|
||
- 初次設置：30-45 分鐘
|
||
- 數據遷移：5-10 分鐘
|
||
- 測試驗證：10-15 分鐘
|
||
|
||
---
|
||
|
||
## 🏗️ Supabase 項目設置
|
||
|
||
### 1. 創建新項目
|
||
1. 前往 [Supabase Dashboard](https://supabase.com/dashboard)
|
||
2. 點擊 **"New Project"**
|
||
3. 填寫項目資訊：
|
||
\`\`\`
|
||
Name: wish-pool-production
|
||
Organization: [選擇你的組織]
|
||
Database Password: [設置強密碼，請記住！]
|
||
Region: [選擇最近的區域，建議 ap-southeast-1]
|
||
\`\`\`
|
||
4. 點擊 **"Create new project"**
|
||
5. 等待 2-3 分鐘完成初始化
|
||
|
||
### 2. 獲取項目配置
|
||
項目創建完成後：
|
||
1. 進入項目 Dashboard
|
||
2. 左側選單 → **Settings** → **API**
|
||
3. 複製以下資訊：
|
||
\`\`\`
|
||
Project URL: https://[your-project-id].supabase.co
|
||
anon public key: eyJ... (很長的字串)
|
||
service_role key: eyJ... (僅在需要管理員功能時使用)
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## ⚙️ 本地環境配置
|
||
|
||
### 1. 安裝依賴
|
||
\`\`\`bash
|
||
# 安裝 Supabase 客戶端
|
||
npm install @supabase/supabase-js
|
||
|
||
# 如果需要圖片處理功能
|
||
npm install sharp
|
||
\`\`\`
|
||
|
||
### 2. 環境變數設置
|
||
1. 複製環境變數範本：
|
||
\`\`\`bash
|
||
cp .env.local.example .env.local
|
||
\`\`\`
|
||
|
||
2. 編輯 `.env.local`：
|
||
\`\`\`env
|
||
# Supabase 配置
|
||
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
|
||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
|
||
|
||
# 可選：管理員功能（謹慎使用）
|
||
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
|
||
|
||
# 應用配置
|
||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||
\`\`\`
|
||
|
||
### 3. 驗證連接
|
||
\`\`\`bash
|
||
# 啟動開發服務器
|
||
npm run dev
|
||
|
||
# 檢查控制台是否有 Supabase 連接錯誤
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 🗄️ 數據庫建置
|
||
|
||
### 執行順序很重要！請按照以下順序執行 SQL 腳本：
|
||
|
||
### 步驟 1: 創建基礎表格
|
||
1. 進入 Supabase Dashboard
|
||
2. 左側選單 → **SQL Editor**
|
||
3. 點擊 **"New Query"**
|
||
4. 複製並執行 `scripts/01-create-tables.sql`
|
||
5. 確認執行成功（無錯誤訊息）
|
||
|
||
### 步驟 2: 創建索引和觸發器
|
||
1. 新建查詢
|
||
2. 複製並執行 `scripts/02-create-indexes.sql`
|
||
3. 確認所有索引創建成功
|
||
|
||
### 步驟 3: 創建視圖和函數
|
||
1. 新建查詢
|
||
2. 複製並執行 `scripts/03-create-views-functions.sql`
|
||
3. 確認視圖和函數創建成功
|
||
|
||
### 步驟 4: 設置存儲服務
|
||
1. 新建查詢
|
||
2. 複製並執行 `scripts/04-setup-storage.sql`
|
||
3. 檢查 Storage → Buckets 是否出現新的桶
|
||
|
||
### 步驟 5: 配置安全政策
|
||
1. 新建查詢
|
||
2. 複製並執行 `scripts/05-setup-rls.sql`
|
||
3. 確認 RLS 政策設置完成
|
||
|
||
---
|
||
|
||
## 📁 存儲服務設置
|
||
|
||
### 存儲桶說明
|
||
- **wish-images**: 主要圖片存儲（5MB 限制）
|
||
- **wish-thumbnails**: 縮圖存儲（1MB 限制）
|
||
|
||
### 支援格式
|
||
- JPEG, JPG, PNG, WebP, GIF
|
||
- 自動壓縮和優化
|
||
- CDN 加速分發
|
||
|
||
### 存儲政策
|
||
- 公開讀取：所有人可查看圖片
|
||
- 限制上傳：防止濫用
|
||
- 自動清理：定期清理孤立圖片
|
||
|
||
---
|
||
|
||
## 🔒 安全政策配置
|
||
|
||
### Row Level Security (RLS)
|
||
所有表格都啟用了 RLS，確保數據安全：
|
||
|
||
#### wishes 表格
|
||
- ✅ 公開困擾案例：所有人可查看
|
||
- ✅ 私密困擾案例：僅統計使用
|
||
- ✅ 插入權限：所有人可提交
|
||
|
||
#### wish_likes 表格
|
||
- ✅ 查看權限：用於統計顯示
|
||
- ✅ 插入權限：所有人可點讚
|
||
- ✅ 防重複：同一用戶不可重複點讚
|
||
|
||
#### user_settings 表格
|
||
- ✅ 個人設定：用戶只能管理自己的設定
|
||
- ✅ 會話隔離：基於 session ID 區分用戶
|
||
|
||
---
|
||
|
||
## 🧪 測試驗證
|
||
|
||
### 1. 數據庫連接測試
|
||
\`\`\`sql
|
||
-- 在 SQL Editor 中執行
|
||
SELECT 'Database connection successful!' as status;
|
||
\`\`\`
|
||
|
||
### 2. 表格結構驗證
|
||
\`\`\`sql
|
||
-- 檢查所有表格是否存在
|
||
SELECT table_name
|
||
FROM information_schema.tables
|
||
WHERE table_schema = 'public'
|
||
ORDER BY table_name;
|
||
\`\`\`
|
||
|
||
### 3. 存儲服務測試
|
||
1. 進入 Storage → wish-images
|
||
2. 嘗試上傳一張測試圖片
|
||
3. 確認可以正常預覽
|
||
|
||
### 4. 功能測試清單
|
||
- [ ] 提交新的困擾案例
|
||
- [ ] 上傳圖片附件
|
||
- [ ] 點讚功能
|
||
- [ ] 查看統計數據
|
||
- [ ] 背景音樂設定保存
|
||
- [ ] 響應式設計正常
|
||
|
||
---
|
||
|
||
## 🔄 數據遷移
|
||
|
||
### 自動遷移流程
|
||
1. 啟動應用程式
|
||
2. 如果檢測到本地數據，會自動顯示遷移對話框
|
||
3. 點擊 **"開始遷移"**
|
||
4. 等待遷移完成
|
||
5. 驗證數據完整性
|
||
|
||
### 手動遷移（如需要）
|
||
\`\`\`javascript
|
||
// 在瀏覽器控制台執行
|
||
console.log('Local wishes:', JSON.parse(localStorage.getItem('wishes') || '[]'));
|
||
console.log('Local likes:', JSON.parse(localStorage.getItem('wishLikes') || '{}'));
|
||
\`\`\`
|
||
|
||
### 遷移後清理
|
||
\`\`\`javascript
|
||
// 確認遷移成功後，清理本地數據
|
||
localStorage.removeItem('wishes');
|
||
localStorage.removeItem('wishLikes');
|
||
localStorage.removeItem('userLikedWishes');
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 🚀 部署準備
|
||
|
||
### 1. 環境變數設置
|
||
在部署平台（Vercel/Netlify）設置：
|
||
\`\`\`
|
||
NEXT_PUBLIC_SUPABASE_URL=your-production-url
|
||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-key
|
||
\`\`\`
|
||
|
||
### 2. 生產環境優化
|
||
\`\`\`sql
|
||
-- 執行生產環境優化
|
||
SELECT optimize_database_performance();
|
||
\`\`\`
|
||
|
||
### 3. 備份設置
|
||
1. 進入 Supabase Dashboard
|
||
2. Settings → Database → Backups
|
||
3. 確認自動備份已啟用
|
||
|
||
---
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 常見問題
|
||
|
||
#### 1. 連接失敗
|
||
**症狀**: `Failed to connect to Supabase`
|
||
**解決方案**:
|
||
- 檢查環境變數是否正確
|
||
- 確認 Supabase 項目狀態正常
|
||
- 檢查網路連接
|
||
|
||
#### 2. RLS 政策錯誤
|
||
**症狀**: `Row Level Security policy violation`
|
||
**解決方案**:
|
||
\`\`\`sql
|
||
-- 檢查 RLS 政策
|
||
SELECT * FROM pg_policies WHERE tablename = 'wishes';
|
||
\`\`\`
|
||
|
||
#### 3. 存儲上傳失敗
|
||
**症狀**: 圖片上傳失敗
|
||
**解決方案**:
|
||
- 檢查檔案大小（<5MB）
|
||
- 確認檔案格式支援
|
||
- 檢查存儲桶政策
|
||
|
||
#### 4. 性能問題
|
||
**症狀**: 查詢速度慢
|
||
**解決方案**:
|
||
\`\`\`sql
|
||
-- 檢查索引使用情況
|
||
EXPLAIN ANALYZE SELECT * FROM wishes_with_likes LIMIT 10;
|
||
\`\`\`
|
||
|
||
### 日誌檢查
|
||
1. Supabase Dashboard → Logs
|
||
2. 查看 Database、API、Storage 日誌
|
||
3. 過濾錯誤和警告訊息
|
||
|
||
### 性能監控
|
||
\`\`\`sql
|
||
-- 檢查數據庫性能
|
||
SELECT * FROM get_performance_stats();
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 📊 維護建議
|
||
|
||
### 定期維護任務
|
||
|
||
#### 每週
|
||
- [ ] 檢查錯誤日誌
|
||
- [ ] 監控存儲使用量
|
||
- [ ] 清理孤立圖片
|
||
|
||
#### 每月
|
||
- [ ] 分析查詢性能
|
||
- [ ] 檢查備份完整性
|
||
- [ ] 更新統計數據
|
||
|
||
#### 每季
|
||
- [ ] 檢查安全政策
|
||
- [ ] 優化數據庫索引
|
||
- [ ] 評估擴展需求
|
||
|
||
### 清理腳本
|
||
\`\`\`sql
|
||
-- 清理 30 天前的孤立圖片
|
||
SELECT cleanup_orphaned_images();
|
||
|
||
-- 更新統計數據
|
||
REFRESH MATERIALIZED VIEW wishes_stats_cache;
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 🎉 完成檢查清單
|
||
|
||
設置完成後，請確認以下項目：
|
||
|
||
### 基礎設置
|
||
- [ ] Supabase 項目創建成功
|
||
- [ ] 環境變數配置正確
|
||
- [ ] 所有 SQL 腳本執行成功
|
||
- [ ] 存儲桶創建完成
|
||
|
||
### 功能測試
|
||
- [ ] 可以提交新困擾案例
|
||
- [ ] 圖片上傳功能正常
|
||
- [ ] 點讚功能運作正常
|
||
- [ ] 統計數據顯示正確
|
||
- [ ] 用戶設定保存成功
|
||
|
||
### 安全檢查
|
||
- [ ] RLS 政策生效
|
||
- [ ] 無法訪問他人私密數據
|
||
- [ ] 存儲權限設置正確
|
||
|
||
### 性能驗證
|
||
- [ ] 頁面載入速度正常
|
||
- [ ] 圖片載入速度快
|
||
- [ ] 查詢響應時間合理
|
||
|
||
---
|
||
|
||
## 📞 支援資源
|
||
|
||
- **Supabase 官方文檔**: https://supabase.com/docs
|
||
- **Next.js 整合指南**: https://supabase.com/docs/guides/getting-started/quickstarts/nextjs
|
||
- **故障排除指南**: https://supabase.com/docs/guides/platform/troubleshooting
|
||
|
||
---
|
||
|
||
**🌟 恭喜！你的心願星河已經成功整合 Supabase！**
|
||
|
||
現在你可以享受雲端數據存儲、圖片管理、實時同步等強大功能。如果遇到任何問題，請參考故障排除章節或聯繫技術支援。
|
||
\`\`\`
|