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: _______________
備註: