Hugging Face Spaces 部署指南
本指南說明如何將此專案部署到 Hugging Face Spaces 免費版。
前置準備
- 註冊 Hugging Face 帳號
- 準備 geminigen.ai 帳號憑證
部署步驟
1. 建立 Space
- 前往 https://huggingface.co/new-space
- 填寫資訊：
- Space name: 自訂名稱（例如：ai-image-generator）
- License: MIT
- Select the Space SDK: Docker
- Space hardware: CPU basic (免費)
- 點擊 "Create Space"
2. 上傳專案檔案
方式 A: 使用 Git (推薦)
# 克隆 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 介面
- 在 Space 頁面點擊 "Files" 標籤
- 點擊 "Add file" → "Upload files"
- 上傳所有必要檔案
3. 設定環境變數
在 Space 的 "Settings" 標籤中設定以下環境變數：
必要變數
# JWT 密鑰（請生成隨機字串）
JWT_SECRET=your-random-jwt-secret-key-at-least-32-characters
# 加密密鑰（必須是 32 字元）
ENCRYPTION_KEY=your-32-character-encryption-key
可選變數
# 資料庫路徑（預設值已足夠）
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 (重要)
為了保存資料庫和用戶資料：
- 在 Space Settings 中找到 "Persistent Storage"
- 點擊 "Enable Persistent Storage"
- 設定掛載路徑為
/data
注意: 免費版 Persistent Storage 有容量限制，請定期清理舊檔案。
5. 等待建置完成
Space 會自動開始建置 Docker 映像，這可能需要 10-15 分鐘。
建置完成後，Space 會自動啟動，您可以在 "App" 標籤中看到應用程式。
首次使用
- 訪問您的 Space URL（例如：https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME）
- 點擊右上角「註冊」按鈕
- 第一個註冊的用戶會自動成為管理員
- 登入後，進入「管理後台」
- 設定 geminigen.ai 憑證：
- Password
- 點擊「儲存憑證」
- 開始使用！
常見問題
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 推送更新：
cd YOUR_SPACE_NAME
git pull origin main # 拉取最新變更
# 修改檔案...
git add .
git commit -m "Update application"
git push
Q: 效能不足怎麼辦？
A: 免費版 CPU basic 有限制：
- 考慮升級到付費硬體
- 優化資料庫查詢
- 減少同時處理的請求數
進階配置
使用外部資料庫
如果需要更穩定的資料庫，可以使用外部服務：
- 註冊 Supabase 或 Neon（都有免費額度）
- 建立 PostgreSQL 資料庫
- 修改環境變數：
DATABASE_URL=postgresql://user:pass@host:5432/dbname - 修改
lib/db/drizzle.config.ts和lib/db/src/index.ts改回 PostgreSQL 配置
使用外部儲存
整合 Cloudflare R2 或其他 S3 相容服務：
- 註冊服務並取得憑證
- 修改
artifacts/api-server/src/lib/objectStorage.ts - 設定相關環境變數
監控與維護
查看日誌
在 Space 的 "Logs" 標籤可以查看即時日誌。
重啟 Space
在 Settings 中點擊 "Factory reboot" 可以重啟 Space。
備份資料
定期下載 /data/sqlite.db 進行備份：
# 使用 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
支援
如有問題，請查看：
授權
MIT License