# 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