对于开发者和小型项目来说，寻找一个免费、简单且强大的应用部署平台一直是个挑战。Hugging Face Spaces 不仅提供机器学习模型的托管，还支持通过 Docker 部署任意 Web 应用，并且完全免费！本教程将手把手教你如何将你的 Docker 应用部署到 HF Spaces，即使你之前从未接触过。

为什么选择 Hugging Face Spaces？

  • 完全免费：提供一定的 CPU 和内存资源，足够个人项目和小型应用使用。
  • 支持 Docker：你可以使用自己的 Dockerfile，构建任何环境，摆脱平台限制。
  • 一键部署：与 GitHub 无缝集成，推送代码即可自动构建和部署。
  • 社区曝光：部署后的应用会获得一个公开链接，易于分享和展示。

前提条件

  1. 一个 Hugging Face 账号。
  2. 本地已安装 Git 和 Docker（用于本地测试和构建镜像）。
  3. 一个准备好要部署的 Web 应用代码（例如 Flask、FastAPI、Node.js 等），并包含 Dockerfile。

部署步骤

第 1 步：创建新的 Space

  1. 登录 Hugging Face，点击右上角头像，选择 **”New Space”**。
  2. 填写 Space 名称（如 my-docker-app）。
  3. 关键选择：
    • Owner: 选择你的用户名或组织。
    • Space SDK: 选择 **”Docker”**。
    • Hardware: 免费选项通常选择 CPU basic。
    • Public/Private: 根据需求选择，免费层要求为 Public。
  4. 点击 **”Create Space”**。

第 2 步：准备你的代码仓库

HF Spaces 会从你的 GitHub 仓库拉取代码。你需要确保仓库结构符合要求：

1
2
3
4
5
your-repo/
├── Dockerfile          # 必须
├── app.py (或你的入口文件) # 示例
├── requirements.txt   # 如果使用 Python
└── ...                # 其他应用文件

一个简单的 Dockerfile 示例（Python Flask）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 使用官方 Python 镜像
FROM python:3.9-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口（HF Spaces 要求暴露 7860 端口，但你的应用可监听 7860 或通过 $PORT 环境变量）
ENV PORT=7860
EXPOSE 7860

# 启动命令
CMD ["python", "app.py"]

app.py 示例：

1
2
3
4
5
6
7
8
9
10
11
12
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello from Docker on Hugging Face Spaces!"

if __name__ == "__main__":
    # 注意：HF 会通过 $PORT 环境变量指定端口，默认 7860
    import os
    port = int(os.environ.get('PORT', 7860))
    app.run(host='0.0.0.0', port=port)

第 3 步：连接 GitHub 并推送代码

  1. 在刚创建的 Space 页面，点击 “Settings” 标签。
  2. 在 “Git repository” 部分，点击 **”Connect a repository”**，选择你的 GitHub 仓库（需提前创建好并包含上述文件）。
  3. 连接后，HF Spaces 会自动触发一次构建。你可以在 “Logs” 标签页实时查看构建和部署过程。
  4. 如果一切顺利，几分钟后，你的应用就会运行在 https://<your-username>-<your-space-name>.hf.space。

第 4 步：验证与调试

  • 访问你的 Space 公开 URL，检查应用是否正常运行。
  • 如果部署失败，返回 “Logs” 查看错误信息。常见问题：
    • Dockerfile 语法错误或基础镜像拉取失败。
    • 应用未监听 PORT 环境变量指定的端口（默认为 7860）。
    • 依赖安装超时（可尝试优化 requirements.txt 或使用国内镜像源）。

高级技巧与注意事项

  • 持久化存储：HF Spaces 的容器是无状态的，每次重启会重置。如需存储数据，需连接外部数据库或对象存储（如 Hugging Face Datasets）。
  • 自定义域名：免费版不支持，但付费方案可绑定自定义域名。
  • 资源限制：免费层有 CPU/内存限制，且应用在闲置一段时间后会自动休眠，再次访问需重新唤醒（约 10-30 秒）。
  • 环境变量：在 Space 的 “Settings” -> “Variables” 中可设置敏感信息（如 API Keys），在代码中通过 os.environ.get('MY_KEY') 读取。

总结

通过 Hugging Face Spaces 的 Docker 支持，你可以几乎零成本地将任何 Web 应用快速部署到公网。其核心流程就是：创建 Space（选 Docker） -> 准备带 Dockerfile 的代码 -> 关联 GitHub 仓库 -> 自动构建。

赶紧试试吧！即使是一个简单的 Flask 应用，也能在几分钟内获得一个可分享的在线链接。如果遇到问题，HF 社区和文档是很好的求助资源。

提示：对于更复杂的应用（如需要 GPU、更大内存），可查看 HF Spaces 的付费方案或考虑其他云平台（如 Vercel, Railway, Fly.io）进行对比。