| # Hugging Face Spaces 部署指南 |
|
|
| 本指南說明如何將此專案部署到 Hugging Face Spaces 免費版。 |
|
|
| ## 前置準備 |
|
|
| 1. 註冊 [Hugging Face](https://huggingface.co/) 帳號 |
| 2. 準備 geminigen.ai 帳號憑證 |
|
|
| ## 部署步驟 |
|
|
| ### 1. 建立 Space |
|
|
| 1. 前往 https://huggingface.co/new-space |
| 2. 填寫資訊： |
| - **Space name**: 自訂名稱（例如：ai-image-generator） |
| - **License**: MIT |
| - **Select the Space SDK**: Docker |
| - **Space hardware**: CPU basic (免費) |
| 3. 點擊 "Create Space" |
|
|
| ### 2. 上傳專案檔案 |
|
|
| #### 方式 A: 使用 Git (推薦) |
|
|
| ```bash |
| # 克隆 Space 倉庫 |
| git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME |
| cd YOUR_SPACE_NAME |
| |
| # 複製專案檔案（排除不需要的檔案） |
| cp -r /path/to/project/* . |
| |
| # 確保包含以下關鍵檔案： |
| # - Dockerfile |
| # - README.md (Space 配置) |
| # - artifacts/ |
| # - lib/ |
| # - package.json |
| # - pnpm-lock.yaml |
| # - pnpm-workspace.yaml |
| # - tsconfig.base.json |
| # - tsconfig.json |
| |
| # 提交並推送 |
| git add . |
| git commit -m "Initial deployment" |
| git push |
| ``` |
|
|
| #### 方式 B: 使用 Web 介面 |
|
|
| 1. 在 Space 頁面點擊 "Files" 標籤 |
| 2. 點擊 "Add file" → "Upload files" |
| 3. 上傳所有必要檔案 |
|
|
| ### 3. 設定環境變數 |
|
|
| 在 Space 的 "Settings" 標籤中設定以下環境變數： |
|
|
| #### 必要變數 |
|
|
| ```bash |
| # JWT 密鑰（請生成隨機字串） |
| JWT_SECRET=your-random-jwt-secret-key-at-least-32-characters |
| |
| # 加密密鑰（必須是 32 字元） |
| ENCRYPTION_KEY=your-32-character-encryption-key |
| ``` |
|
|
| #### 可選變數 |
|
|
| ```bash |
| # 資料庫路徑（預設值已足夠） |
| DATABASE_URL=file:/data/sqlite.db |
| |
| # 暫存路徑（預設值已足夠） |
| TEMP_STORAGE_PATH=/app/temp-storage |
| |
| # Turnstile 驗證碼服務（如果有部署） |
| TURNSTILE_SOLVER_URL=https://your-turnstile-solver.vercel.app |
| ``` |
|
|
| ### 4. 啟用 Persistent Storage (重要) |
|
|
| 為了保存資料庫和用戶資料： |
|
|
| 1. 在 Space Settings 中找到 "Persistent Storage" |
| 2. 點擊 "Enable Persistent Storage" |
| 3. 設定掛載路徑為 `/data` |
|
|
| **注意**: 免費版 Persistent Storage 有容量限制，請定期清理舊檔案。 |
|
|
| ### 5. 等待建置完成 |
|
|
| Space 會自動開始建置 Docker 映像，這可能需要 10-15 分鐘。 |
|
|
| 建置完成後，Space 會自動啟動，您可以在 "App" 標籤中看到應用程式。 |
|
|
| ## 首次使用 |
|
|
| 1. 訪問您的 Space URL（例如：https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME） |
| 2. 點擊右上角「註冊」按鈕 |
| 3. 第一個註冊的用戶會自動成為管理員 |
| 4. 登入後，進入「管理後台」 |
| 5. 設定 geminigen.ai 憑證： |
| - Email |
| - Password |
| 6. 點擊「儲存憑證」 |
| 7. 開始使用！ |
| |
| ## 常見問題 |
| |
| ### Q: 建置失敗怎麼辦？ |
| |
| A: 檢查以下項目： |
| - 確認 Dockerfile 格式正確 |
| - 確認所有依賴檔案都已上傳 |
| - 查看 Space 的 "Logs" 標籤了解錯誤訊息 |
| |
| ### Q: 應用程式無法啟動？ |
| |
| A: 檢查： |
| - 環境變數是否正確設定 |
| - Persistent Storage 是否已啟用 |
| - 查看 "Logs" 標籤的錯誤訊息 |
| |
| ### Q: 資料庫資料遺失？ |
| |
| A: 確保： |
| - Persistent Storage 已啟用並掛載到 `/data` |
| - DATABASE_URL 指向 `/data/sqlite.db` |
|
|
| ### Q: 圖片/影片無法顯示？ |
|
|
| A: 本地暫存模式下： |
| - 檔案會在 24 小時後自動清理 |
| - 重啟 Space 會清空暫存 |
| - 這是免費版的限制，如需永久儲存請考慮外部儲存服務 |
|
|
| ### Q: 如何更新應用程式？ |
|
|
| A: 使用 Git 推送更新： |
|
|
| ```bash |
| cd YOUR_SPACE_NAME |
| git pull origin main # 拉取最新變更 |
| # 修改檔案... |
| git add . |
| git commit -m "Update application" |
| git push |
| ``` |
|
|
| ### Q: 效能不足怎麼辦？ |
|
|
| A: 免費版 CPU basic 有限制： |
| - 考慮升級到付費硬體 |
| - 優化資料庫查詢 |
| - 減少同時處理的請求數 |
|
|
| ## 進階配置 |
|
|
| ### 使用外部資料庫 |
|
|
| 如果需要更穩定的資料庫，可以使用外部服務： |
|
|
| 1. 註冊 [Supabase](https://supabase.com/) 或 [Neon](https://neon.tech/)（都有免費額度） |
| 2. 建立 PostgreSQL 資料庫 |
| 3. 修改環境變數： |
| ```bash |
| DATABASE_URL=postgresql://user:pass@host:5432/dbname |
| ``` |
| 4. 修改 `lib/db/drizzle.config.ts` 和 `lib/db/src/index.ts` 改回 PostgreSQL 配置 |
|
|
| ### 使用外部儲存 |
|
|
| 整合 Cloudflare R2 或其他 S3 相容服務： |
|
|
| 1. 註冊服務並取得憑證 |
| 2. 修改 `artifacts/api-server/src/lib/objectStorage.ts` |
| 3. 設定相關環境變數 |
|
|
| ## 監控與維護 |
|
|
| ### 查看日誌 |
|
|
| 在 Space 的 "Logs" 標籤可以查看即時日誌。 |
|
|
| ### 重啟 Space |
|
|
| 在 Settings 中點擊 "Factory reboot" 可以重啟 Space。 |
|
|
| ### 備份資料 |
|
|
| 定期下載 `/data/sqlite.db` 進行備份： |
|
|
| ```bash |
| # 使用 Hugging Face CLI |
| huggingface-cli download spaces/YOUR_USERNAME/YOUR_SPACE_NAME data/sqlite.db --repo-type=space |
| ``` |
|
|
| ## 成本估算 |
|
|
| - **免費版**: CPU basic，適合個人使用或測試 |
| - **付費版**: |
| - CPU upgrade: $0.03/hour |
| - GPU T4: $0.60/hour |
| - Persistent Storage: 免費 50GB |
|
|
| ## 支援 |
|
|
| 如有問題，請查看： |
| - [Hugging Face Spaces 文件](https://huggingface.co/docs/hub/spaces) |
| - [專案 GitHub Issues](https://github.com/your-repo/issues) |
|
|
| ## 授權 |
|
|
| MIT License |
|
|
