feat: add Hugging Face Spaces Docker deployment

- Multi-stage Dockerfile for frontend + backend
- Automatic model download from Hugging Face Hub
- Nginx reverse proxy on port 7860
- CPU-only deployment (8-12GB RAM)
- Environment detection for API URL configuration

.dockerignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+env/
+venv/
+.venv
+
+# Node - 注意：為了 HF Spaces，我們保留 node_modules
+# node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Docker
+.dockerignore
+docker-compose*.yml
+Dockerfile*
+!Dockerfile.huggingface
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# 上傳和輸出（運行時生成）
+backend/uploads/
+backend/outputs/
+outputs/
+
+# 模型（運行時下載）
+models/
+
+# 環境變數
+.env
+.env.local
+
+# 文檔和腳本
+*.md
+!README-HF.md
+*.sh
+!docker-entrypoint.sh
+
+# 測試
+*.log
+.pytest_cache/
+.coverage

Dockerfile.huggingface

@@ -0,0 +1,113 @@
+# Dockerfile for Hugging Face Spaces
+# 完整的前端 + 後端部署
+
+# Stage 1: 構建前端
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+
+# 複製前端文件
+COPY frontend/package.json frontend/yarn.lock ./
+COPY frontend/node_modules ./node_modules
+COPY frontend/ ./
+
+# 設置 API URL（HF Spaces 使用同一域名）
+ENV VITE_API_URL=/api
+
+# 構建前端
+RUN yarn build
+
+# Stage 2: 後端 + 前端服務
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# 安裝系統依賴
+RUN apt-get update && apt-get install -y \
+    git \
+    wget \
+    curl \
+    build-essential \
+    libsndfile1 \
+    libsndfile1-dev \
+    ffmpeg \
+    sox \
+    libsox-dev \
+    libsox-fmt-all \
+    libavcodec-dev \
+    libavformat-dev \
+    libavutil-dev \
+    libswresample-dev \
+    nginx \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安裝 uv
+RUN pip install --no-cache-dir uv
+
+# 複製後端代碼
+COPY pyproject.toml /app/
+COPY backend /app/backend
+
+# 安裝 Python 依賴
+RUN uv pip install --system --no-cache \
+    torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 \
+    --index-url https://download.pytorch.org/whl/cpu && \
+    uv pip install --system --no-cache \
+    qwen-tts \
+    fastapi \
+    uvicorn[standard] \
+    python-multipart \
+    soundfile \
+    huggingface-hub \
+    tqdm
+
+# 從前端構建階段複製靜態文件
+COPY --from=frontend-builder /app/frontend/dist /app/frontend/dist
+
+# 創建必要目錄
+RUN mkdir -p /app/backend/uploads /app/backend/outputs
+
+# Nginx 配置
+RUN echo 'server { \n\
+    listen 7860; \n\
+    server_name _; \n\
+    \n\
+    # 前端靜態文件 \n\
+    location / { \n\
+        root /app/frontend/dist; \n\
+        try_files $uri $uri/ /index.html; \n\
+    } \n\
+    \n\
+    # API 代理到後端 \n\
+    location /api { \n\
+        proxy_pass http://127.0.0.1:8000; \n\
+        proxy_http_version 1.1; \n\
+        proxy_set_header Upgrade $http_upgrade; \n\
+        proxy_set_header Connection "upgrade"; \n\
+        proxy_set_header Host $host; \n\
+        proxy_set_header X-Real-IP $remote_addr; \n\
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \n\
+        proxy_set_header X-Forwarded-Proto $scheme; \n\
+        proxy_read_timeout 300s; \n\
+    } \n\
+}' > /etc/nginx/sites-available/default
+
+# 環境變數
+ENV PYTHONUNBUFFERED=1
+ENV MODEL_PATH=/app/models/Qwen3-TTS-12Hz-1.7B-Base
+ENV UPLOAD_DIR=/app/backend/uploads
+ENV OUTPUT_DIR=/app/backend/outputs
+ENV USE_CPU=true
+
+# 暴露 HF Spaces 端口
+EXPOSE 7860
+
+# 健康檢查
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
+    CMD curl -f http://localhost:7860/api/status || exit 1
+
+# 啟動腳本
+COPY docker-entrypoint.sh /app/
+RUN chmod +x /app/docker-entrypoint.sh
+
+CMD ["/app/docker-entrypoint.sh"]

README-HF.md

@@ -0,0 +1,64 @@
+---
+title: Qwen3-TTS Voice Clone
+emoji: 🎤
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: apache-2.0
+---
+
+# 🎤 Qwen3-TTS 語音複製
+
+基於 Qwen3-TTS-12Hz-1.7B-Base 的全功能語音複製應用。
+
+## ✨ 功能特色
+
+- 🎯 **3秒快速複製**: 僅需 3-10 秒參考音訊
+- 🌏 **多語言支持**: 中、英、日、韓等 10 種語言
+- 🎨 **高相似度**: 聲音相似度可達 95%
+- 💻 **完整 Web UI**: React 前端 + FastAPI 後端
+- 🚀 **即開即用**: 模型自動下載
+
+## 🚀 使用方法
+
+1. 上傳 3-10 秒的參考音訊（清晰人聲）
+2. 輸入參考音訊的逐字稿
+3. 輸入想要生成的目標文字
+4. 選擇語言
+5. 點擊「複製並生成」
+
+## 📊 效能說明
+
+- **CPU 模式**: 10-20 秒/次
+- **記憶體**: 約 8-12GB
+- **模型大小**: 4.3GB
+
+## 🛠️ 技術棧
+
+- **前端**: React + TypeScript + Tailwind CSS
+- **後端**: FastAPI + Python
+- **模型**: Qwen3-TTS-12Hz-1.7B-Base
+- **部署**: Docker
+
+## 📝 本地運行
+
+```bash
+# Clone 項目
+git clone https://huggingface.co/spaces/你的用戶名/qwen3-tts-clone
+cd qwen3-tts-clone
+
+# 使用 Docker
+docker build -f Dockerfile.huggingface -t qwen3-tts .
+docker run -p 7860:7860 qwen3-tts
+```
+
+訪問: http://localhost:7860
+
+## 🤝 貢獻
+
+基於 [Qwen3-TTS](https://github.com/QwenLM/Qwen3-TTS) by Alibaba Qwen Team
+
+## 📄 授權
+
+Apache 2.0 License

docker-entrypoint.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+set -e
+
+echo "🚀 啟動 Qwen3-TTS 服務..."
+
+# 下載模型（如果不存在）
+if [ ! -d "$MODEL_PATH" ]; then
+    echo "📥 下載模型..."
+    mkdir -p /app/models
+
+    python3 << 'PYTHON'
+from huggingface_hub import snapshot_download
+import os
+
+model_path = os.environ.get('MODEL_PATH', '/app/models/Qwen3-TTS-12Hz-1.7B-Base')
+print(f"下載模型到: {model_path}")
+
+snapshot_download(
+    repo_id="Qwen/Qwen3-TTS-12Hz-1.7B-Base",
+    local_dir=model_path,
+    local_dir_use_symlinks=False,
+)
+print("✅ 模型下載完成")
+PYTHON
+else
+    echo "✅ 模型已存在"
+fi
+
+# 啟動 Nginx（前端）
+echo "🌐 啟動 Nginx（端口 7860）..."
+nginx
+
+# 啟動後端
+echo "🔧 啟動後端 API（端口 8000）..."
+uvicorn backend.main:app --host 127.0.0.1 --port 8000