docs/hf_deployment_guide.md

# Hugging Face Space 部署指南

本指南将详细介绍如何将 QSSS 应用部署到 Hugging Face Space。

## 1. Hugging Face Space 创建步骤

1.  **登录 Hugging Face**: 访问 [Hugging Face 官网](https://huggingface.co/) 并登录您的账户。如果您没有账户，请先注册。
2.  **创建新的 Space**:
    *   点击页面右上角的个人头像，选择 "New Space"。
    *   填写 Space 名称 (例如: `your-username/qsss-app`)。
    *   选择一个许可证 (例如: `MIT License`)。
    *   选择 Space 类型: 推荐选择 `Docker`，因为我们将使用 Docker 容器进行部署。
    *   选择可见性: `Public` (公开) 或 `Private` (私有)，根据您的需求选择。
    *   点击 "Create Space"。
3.  **克隆 Space 仓库**: 创建 Space 后，您将看到一个页面，其中包含克隆仓库的 Git 命令。复制该命令并在本地终端执行，将 Space 仓库克隆到您的本地机器。

    ```bash
    git clone https://huggingface.co/spaces/your-username/your-space-name
    ```

## 2. Docker 容器配置说明 (多阶段构建)

为了优化镜像体积并整合前后端服务，我们采用了多阶段 Dockerfile 构建。这个 `Dockerfile` 将负责构建前端应用、后端应用，并最终将它们以及 Nginx 和 Supervisor 整合到一个轻量级的运行时镜像中。

以下是新的 `Dockerfile` 结构：

```dockerfile
# 阶段1: Node镜像构建前端 (qsss-web)
FROM node:20-alpine AS frontend_builder

WORKDIR /app/qsss-web

# 复制前端依赖文件并安装
COPY qsss-web/package.json qsss-web/package-lock.json ./
RUN npm install --frozen-lockfile

# 复制前端所有代码
COPY qsss-web/ .

# 构建前端应用
RUN npm run build

# 阶段2: Python镜像构建后端
FROM python:3.9-slim-bookworm AS backend_builder

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    build-essential \
    gcc \
    gfortran \
    wget \
    libssl-dev \
    ninja-build \
    libopenblas-dev \
    liblapack-dev \
    pkg-config \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# 安装TA-Lib
RUN mkdir -p /ta-lib-build && cd /ta-lib-build && \
    wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz && \
    tar -xzf ta-lib-0.4.0-src.tar.gz && \
    cd ta-lib/ && \
    ./configure --prefix=/usr && \
    make && \
    make install && \
    # 创建兼容性符号链接解决库名称问题
    ln -s /usr/lib/libta_lib.so /usr/lib/libta-lib.so && \
    ln -s /usr/lib/libta_lib.so.0 /usr/lib/libta-lib.so.0 && \
    ldconfig && \
    cd / && \
    rm -rf /ta-lib-build

# 创建Python虚拟环境
ENV VIRTUAL_ENV=/app/backend_venv
RUN python -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

# 复制后端依赖文件并安装
COPY requirements.txt backend/requirements.txt ./
RUN pip install --no-cache-dir --upgrade pip setuptools wheel && \
    pip install --no-cache-dir \
    Cython==0.29.36 \
    numpy==1.26.4 \
    pythran \
    pybind11 \
    versioneer \
    importlib-metadata==6.0.0 \
    zipp==3.15.0 && \
    pip install --no-cache-dir --no-build-isolation -r requirements.txt && \
    pip install --no-cache-dir --no-build-isolation -r backend/requirements.txt

# 复制后端代码
COPY backend/ backend/

# 阶段3: 运行时镜像整合前后端
FROM debian:bookworm-slim AS final

# 安装Nginx和Supervisor
RUN apt-get update && apt-get install -y \
    nginx \
    supervisor \
    ca-certificates \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# 创建必要的目录
RUN mkdir -p /app/qsss-web/out \
           /app/backend \
           /app/backend_venv \
           /etc/nginx/sites-enabled \
           /var/log/supervisor

# 从前端构建阶段复制前端静态文件
COPY --from=frontend_builder /app/qsss-web/out /app/qsss-web/out

# 从后端构建阶段复制Python虚拟环境
COPY --from=backend_builder /app/backend_venv /app/backend_venv

# 从后端构建阶段复制后端代码
COPY --from=backend_builder /app/backend /app/backend

# 复制Nginx配置
COPY nginx.conf /etc/nginx/sites-enabled/default

# 复制Supervisor配置
COPY supervisord.conf /etc/supervisord.conf

# 设置环境变量
ENV DATABASE_URL=sqlite:///:memory: \
    REDIS_MODE=memory \
    SECRET_KEY=your_secret_key_here \
    ENVIRONMENT=production \
    MEMORY_MODE=true \
    PYTHONPATH=/app/backend:$PYTHONPATH

# 暴露端口
EXPOSE 7860

# 启动命令
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]
```

**Nginx 配置 (`nginx.conf`)**:
Nginx 作为反向代理服务器，负责将外部请求路由到正确的前端或后端服务。

```nginx
events {
    worker_connections 1024;
}

http {
    include mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;

    server {
        listen 80;
        server_name localhost;

        # 前端服务 (Next.js 构建输出)
        location / {
            root /app/qsss-web/out;
            try_files $uri $uri/ /index.html;
        }

        # 后端API服务
        location /api/ {
            proxy_pass http://127.0.0.1:7860/;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}
```

**Supervisor 配置 (`supervisord.conf`)**:
Supervisor 用于管理 Nginx、前端和后端服务的进程，确保它们在容器内同时运行并自动重启。

```ini
[supervisord]
nodaemon=true

[program:nginx]
command=/usr/sbin/nginx -g "daemon off;"
autostart=true
autorestart=true
startretries=3
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:backend]
command=/app/backend_venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 7860
directory=/app/backend
autostart=true
autorestart=true
startretries=3
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:frontend]
command=npm run start --prefix /app/qsss-web
directory=/app/qsss-web
autostart=true
autorestart=true
startretries=3
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
```

**重要提示**:
*   **端口暴露**: 容器内部的 Nginx 监听 80 端口，后端服务监听 7860 端口。Dockerfile 暴露 7860 端口，但 Hugging Face Space 会将外部请求路由到 80 端口，Nginx 会处理这些请求。
*   **Hugging Face Space 兼容性**: 这种单容器多服务部署方式兼容 Hugging Face Space 的单容器部署模型，同时实现了前后端和 Nginx 的整合。

## 3. 部署步骤

1.  **更新项目文件**:
    *   将上述新的 `Dockerfile` 替换您项目根目录下的旧文件。
    *   将 `nginx.conf` 和 `supervisord.conf` 文件放置在您的项目根目录。
    *   确保 `qsss-web/package.json` 中的 `start` 脚本配置正确 (通常为 `next start`)。
2.  **提交并推送**: 将所有更改提交到您的 Git 仓库并推送到 Hugging Face Space 远程仓库。

    ```bash
    git add .
    git commit -m "feat: Update Dockerfile for multi-stage build with Nginx and Supervisor"
    git push
    ```
3.  **Hugging Face Space 自动构建**: Hugging Face Space 会自动检测到您的仓库更新，并根据新的 `Dockerfile` 重新构建和部署您的应用。您可以在 Space 页面查看构建和运行日志。

## 4. 环境变量设置建议

在 Hugging Face Space 中，您可以通过 "Settings" -> "Space secrets" 来设置环境变量。这些变量在您的 Docker 容器中是可用的。

建议设置的环境变量包括：

*   `DATABASE_URL`: 数据库连接字符串 (如果使用外部数据库)。
*   `SECRET_KEY`: 用于 JWT 认证的密钥。
*   `HF_TOKEN`: 如果您的应用需要访问 Hugging Face Hub 上的私有模型或数据集，则需要设置此令牌。
*   其他任何您的应用所需的配置参数。

**示例**:

| 变量名         | 建议值                                   | 说明                                     |
| :------------- | :--------------------------------------- | :--------------------------------------- |
| `SECRET_KEY`   | `your_super_secret_key_here`             | 用于认证和加密，请生成一个强随机字符串。 |
| `DATABASE_URL` | `sqlite:///./sql_app.db` 或您的外部数据库连接 | 数据库连接字符串。                       |
| `HF_TOKEN`     | `hf_YOUR_TOKEN`                          | 访问 Hugging Face Hub 的令牌。           |

## 5. 常见问题排查

*   **应用无法启动**:
    *   检查 `Dockerfile` 中的路径是否正确。
    *   查看 Hugging Face Space 的日志 (Logs 选项卡)，查找错误信息。
    *   确保所有依赖都已正确安装。
    *   检查端口是否正确暴露 (通常是 7860，由 Nginx 代理)。
*   **环境变量未生效**:
    *   确保您在 Hugging Face Space 的 "Settings" -> "Space secrets" 中正确设置了环境变量。
    *   检查您的应用代码是否正确读取了这些环境变量。
*   **内存或 CPU 不足**:
    *   Hugging Face Space 提供不同大小的硬件配置。如果您的应用需要更多资源，请考虑升级 Space 的硬件。
    *   优化您的代码，减少内存和 CPU 使用。
*   **Git LFS 问题**:
    *   如果您的仓库包含大文件 (例如模型权重)，请确保您已正确配置 Git LFS。
    *   在克隆仓库后，运行 `git lfs pull` 来下载大文件。