| # Hugging Face Spaces 部署檢查清單 |
|
|
| ## 部署前檢查 |
|
|
| ### 必要檔案 |
| - [ ] `Dockerfile` - Docker 建置配置 |
| - [ ] `README.md` - Space 配置檔（包含 YAML front matter） |
| - [ ] `.dockerignore` - 排除不需要的檔案 |
| - [ ] `.env.example` - 環境變數範例 |
| - [ ] `DEPLOYMENT.md` - 部署指南 |
|
|
| ### 專案檔案 |
| - [ ] `package.json` - 根目錄 workspace 配置 |
| - [ ] `pnpm-lock.yaml` - 依賴鎖定檔 |
| - [ ] `pnpm-workspace.yaml` - Workspace 配置 |
| - [ ] `tsconfig.base.json` - TypeScript 基礎配置 |
| - [ ] `tsconfig.json` - TypeScript 配置 |
|
|
| ### 後端檔案 |
| - [ ] `artifacts/api-server/` - 完整後端程式碼 |
| - [ ] `artifacts/api-server/src/index.ts` - 已移除背景 token refresh |
| - [ ] `artifacts/api-server/src/lib/localTempStorage.ts` - 本地暫存邏輯 |
|
|
| ### 前端檔案 |
| - [ ] `artifacts/image-gen/` - 完整前端程式碼 |
| - [ ] `artifacts/image-gen/dist/` - 建置後會自動生成 |
|
|
| ### 資料庫檔案 |
| - [ ] `lib/db/` - 資料庫層 |
| - [ ] `lib/db/package.json` - 已更新為 better-sqlite3 |
| - [ ] `lib/db/drizzle.config.ts` - 已改為 SQLite 配置 |
| - [ ] `lib/db/src/index.ts` - 已改為 SQLite 連接 |
|
|
| ### 共享庫 |
| - [ ] `lib/api-client-react/` - React API 客戶端 |
| - [ ] `lib/api-spec/` - OpenAPI 規格 |
| - [ ] `lib/api-zod/` - Zod 驗證 |
|
|
| ## 環境變數設定 |
|
|
| ### 必要變數（在 Space Settings 中設定） |
| - [ ] `JWT_SECRET` - JWT 密鑰（至少 32 字元隨機字串） |
| - [ ] `ENCRYPTION_KEY` - 加密密鑰（必須是 32 字元） |
|
|
| ### 可選變數 |
| - [ ] `DATABASE_URL` - 資料庫路徑（預設：file:/data/sqlite.db） |
| - [ ] `TEMP_STORAGE_PATH` - 暫存路徑（預設：/app/temp-storage） |
| - [ ] `TURNSTILE_SOLVER_URL` - Turnstile 服務 URL（如有） |
|
|
| ## Space 設定 |
|
|
| ### 基本設定 |
| - [ ] Space SDK 選擇 "Docker" |
| - [ ] Space hardware 選擇 "CPU basic"（免費） |
| - [ ] License 設定為 "MIT" |
|
|
| ### Persistent Storage |
| - [ ] 啟用 Persistent Storage |
| - [ ] 掛載路徑設定為 `/data` |
| - [ ] 確認容量足夠（免費版有限制） |
|
|
| ## 建置檢查 |
|
|
| ### Docker 建置 |
| - [ ] Dockerfile 語法正確 |
| - [ ] 所有依賴都能正確安裝 |
| - [ ] 前端建置成功 |
| - [ ] 後端建置成功 |
| - [ ] 暴露端口 7860 |
|
|
| ### 執行時檢查 |
| - [ ] 伺服器能正常啟動 |
| - [ ] 資料庫檔案能正確建立 |
| - [ ] 暫存目錄能正確建立 |
| - [ ] 日誌輸出正常 |
|
|
| ## 功能測試 |
|
|
| ### 基本功能 |
| - [ ] 首頁能正常載入 |
| - [ ] 用戶註冊功能正常 |
| - [ ] 用戶登入功能正常 |
| - [ ] 第一個用戶成為管理員 |
|
|
| ### 管理功能 |
| - [ ] 能進入管理後台 |
| - [ ] 能設定 geminigen.ai 憑證 |
| - [ ] 能查看系統狀態 |
| - [ ] 能管理用戶 |
|
|
| ### 圖像生成 |
| - [ ] 能輸入提示詞 |
| - [ ] 能選擇模型 |
| - [ ] 能選擇風格和比例 |
| - [ ] 能上傳參考圖像 |
| - [ ] 能成功生成圖像 |
| - [ ] 圖像能正常顯示 |
|
|
| ### 影片生成 |
| - [ ] 能輸入提示詞 |
| - [ ] 能選擇模型（Grok-3 / Veo 3.1） |
| - [ ] 能設定進階選項 |
| - [ ] 能上傳參考圖像 |
| - [ ] 能成功生成影片 |
| - [ ] 進度追蹤正常 |
| - [ ] 影片能正常播放 |
|
|
| ### 歷史記錄 |
| - [ ] 圖像歷史能正常顯示 |
| - [ ] 影片歷史能正常顯示 |
| - [ ] 能刪除記錄 |
| - [ ] 私密/公開過濾正常 |
|
|
| ## 效能檢查 |
|
|
| ### 資源使用 |
| - [ ] CPU 使用率合理 |
| - [ ] 記憶體使用率合理 |
| - [ ] 磁碟空間足夠 |
|
|
| ### 回應時間 |
| - [ ] 頁面載入速度可接受 |
| - [ ] API 回應時間合理 |
| - [ ] 圖像生成時間正常 |
| - [ ] 影片生成時間正常 |
|
|
| ## 維護檢查 |
|
|
| ### 自動清理 |
| - [ ] 舊檔案能自動清理（24 小時） |
| - [ ] 清理日誌正常輸出 |
| - [ ] 磁碟空間不會持續增長 |
|
|
| ### 日誌監控 |
| - [ ] 能在 Space Logs 查看日誌 |
| - [ ] 錯誤日誌清晰可讀 |
| - [ ] 無異常錯誤持續出現 |
|
|
| ### 備份 |
| - [ ] 知道如何備份資料庫 |
| - [ ] 知道如何還原資料庫 |
| - [ ] 定期備份計畫已建立 |
|
|
| ## 安全檢查 |
|
|
| ### 憑證安全 |
| - [ ] JWT_SECRET 是隨機生成的 |
| - [ ] ENCRYPTION_KEY 是隨機生成的 |
| - [ ] 不在程式碼中硬編碼敏感資訊 |
| - [ ] .env 檔案已加入 .gitignore |
|
|
| ### 存取控制 |
| - [ ] 管理功能需要管理員權限 |
| - [ ] 私密內容只有擁有者能查看 |
| - [ ] API 端點有適當的認證 |
|
|
| ## 文件檢查 |
|
|
| ### 使用者文件 |
| - [ ] README.md 說明清楚 |
| - [ ] DEPLOYMENT.md 步驟完整 |
| - [ ] .env.example 註解清楚 |
|
|
| ### 開發文件 |
| - [ ] 程式碼註解充足 |
| - [ ] 關鍵邏輯有說明 |
| - [ ] 已知限制有記錄 |
|
|
| ## 部署後驗證 |
|
|
| ### 立即檢查 |
| - [ ] Space 狀態為 "Running" |
| - [ ] 能訪問 Space URL |
| - [ ] 首頁正常顯示 |
| - [ ] 無 JavaScript 錯誤 |
|
|
| ### 24 小時後檢查 |
| - [ ] Space 仍在運行 |
| - [ ] 資料庫資料保存正常 |
| - [ ] 舊檔案已自動清理 |
| - [ ] 無記憶體洩漏 |
|
|
| ### 一週後檢查 |
| - [ ] 長期穩定性良好 |
| - [ ] 磁碟空間使用穩定 |
| - [ ] 無異常錯誤累積 |
| - [ ] 用戶回饋正面 |
|
|
| ## 問題排查 |
|
|
| ### 常見問題 |
| - [ ] 知道如何查看日誌 |
| - [ ] 知道如何重啟 Space |
| - [ ] 知道如何還原資料 |
| - [ ] 知道如何聯繫支援 |
|
|
| ### 緊急處理 |
| - [ ] 有備份還原計畫 |
| - [ ] 有降級方案 |
| - [ ] 有聯繫管道 |
|
|
| ## 完成確認 |
|
|
| - [ ] 所有檢查項目都已完成 |
| - [ ] 所有功能都正常運作 |
| - [ ] 文件都已更新 |
| - [ ] 團隊成員都已知悉 |
|
|
| --- |
|
|
| **部署日期**: _______________ |
| |
| **部署人員**: _______________ |
| |
| **Space URL**: _______________ |
| |
| **備註**: |
| |
