跳转至

Hugging Face Space 部署指南

手机用户提示

本页截图基于电脑端浏览器。手机浏览器里菜单可能会折叠，按钮位置也可能略有差异；如果某一步找不到入口，先把手机浏览器切换为"桌面版网站"或"电脑端 UA"再继续。

目标

把 danmu_api 部署到 Hugging Face Space，拿到一个能直接访问的 hf.space 地址。

准备工作

开始之前，请确认你已有：

  1. GitHub 账号 — 用于 Fork 仓库
  2. Hugging Face 账号 — 需要验证邮箱
  3. 邮箱 — 用于接收 Hugging Face 验证邮件

第 1 步：先 Fork 上游仓库

打开上游仓库页面：

按顺序操作：

  1. 点击页面右上角的 Fork
  2. 选择你自己的 GitHub 账号
  3. 等页面变成 你的GitHub用户名/danmu_api

Fork 按钮位置

先点 Fork。

确认 Fork 页面

确认 Fork 到你自己的 GitHub 账号下。

第 2 步：注册或登录 Hugging Face

打开 Hugging Face 注册页：

如果还没有账号，按顺序做：

  1. 填 Email Address
  2. 填 Password
  3. 点 Next

已经有账号就点 Log In 登录。

Hugging Face 注册页

先在注册页填邮箱和密码，点 Next 继续。

第 3 步：补充账号资料

点 Next 后，会进入 Complete your profile 页面。按页面提示继续填：

  1. Username 填账号名
  2. Full name 填显示名称
  3. 头像、Twitter、GitHub、LinkedIn、Homepage、AI & ML interests 这些可选项可以先不填
  4. 勾选同意 Terms of Service 和 Code of Conduct
  5. 点 Create Account

填写资料

必填的是账号名、显示名称和底部协议勾选；可选项可以先空着。

第 4 步：看到邮箱验证提示

创建账号后，如果页面顶部出现 Please check your email address for a confirmation link，说明 Hugging Face 已经把验证邮件发到注册邮箱。

这时不要继续创建 Space，先去邮箱完成验证。

邮箱验证提示

看到这条黄色提示，就先去注册邮箱里找 Hugging Face 的确认邮件。

第 5 步：打开邮箱，点击验证链接

打开刚才注册 Hugging Face 用的邮箱，找到主题类似下面这封邮件：

[Hugging Face] Click this link to confirm your email address

进入邮件后，点击正文里的确认链接。链接通常以 https://huggingface.co/email_confirmation/... 开头。

确认邮件

邮件里的确认链接只用于验证当前账号；不要把自己的确认链接发给别人。

第 6 步：回到 Hugging Face，刷新页面

点完邮件里的验证链接后，回到 Hugging Face 页面刷新。

如果页面出现 Your email address has been verified successfully.，或者顶部不再提示验证邮箱，就说明邮箱已经验证成功。

验证成功

看到邮箱验证成功提示后，就可以继续创建 Space。

第 7 步：创建一个新的 Space

登录后打开新建 Space 页面：

下面按页面顺序一项一项填，不用一次看完整张大图。

7.1 填写 Owner、Space name 和 License

Owner 选你自己的账号或组织。Space name 填 danmu_api。Short description 可以先不填。License 随便选一个，例如 mit。

Owner/Space name/License

这一段只填基础信息：账号、Space 名和 License。

7.2 SDK 选 Docker，模板选 Blank

Select the Space SDK 一定选 Docker。下面的 Choose a Docker template 选 Blank。

SDK/模板

这里不要选 Gradio / Static，必须选 Docker，模板用 Blank。

7.3 硬件选免费的 CPU Basic

Space hardware 选免费的 CPU Basic。

硬件选择

先用免费的 CPU Basic 跑通即可。

7.4 打开 Storage Bucket

Storage Bucket 选择 Mount a bucket to this Space。

Storage Bucket

这里要打开 Storage Bucket，后面才能把缓存目录挂进去。

7.5 填写 Bucket name，Bucket visibility 选 Public

Bucket name 填 danmu_api-storage。Bucket visibility 选 Public。

Bucket name 填写注意

这里不要把 Bucket name 填成 .cache。桶名只是 Hugging Face 后台里的存储名称；真正对应程序缓存目录的是下一步的 Mount path=/app/.cache。

Bucket name

前面的账号前缀由 Hugging Face 自动显示，后面名称填 danmu_api-storage；缓存路径下一步再填 /app/.cache。

7.6 Mount path 填 /app/.cache

Mount path 填 /app/.cache，Access mode 选 Read & Write。Space Dev Mode 不开启。

Mount path

/app/.cache 是 danmu_api 运行缓存目录；权限要选可读写。

7.7 Visibility 选 Public，然后创建 Space

最下面的 Visibility 选 Public，最后点 Create Space。

Create Space

确认是 Public 后，再点 Create Space。

Storage Bucket 说明

danmu_api 支持把运行缓存写进 .cache。把 Hugging Face 的 Storage Bucket 挂到 /app/.cache 后，就不需要像其他云平台那样先配 Upstash 才能跑缓存。

这个挂载只管运行缓存，不改变变量保存方式。后面在管理员 UI 里新增、修改、删除变量时，仍然是通过 Hugging Face API 写到这个 Space 的 Variables and secrets，不是写进 .env，也不是写进 .cache。

7.8 如果创建时忘了打开 Storage Bucket

不用删 Space。进入这个 Space 的 Settings 页面，找到 Storage Buckets，点右侧的 Mount a bucket。

Mount bucket 入口

先在 Space 的 Settings → Storage Buckets 里点 Mount a bucket。

弹窗里选 Create new bucket，再按下面填：

  1. Bucket name 填 danmu_api-storage，不要填 .cache
  2. Bucket visibility 选 Public
  3. Mount path 填 /app/.cache
  4. Access mode 选 Read & Write
  5. 点 Mount bucket

挂载弹窗

弹窗会提示 This will restart your Space.，点 Mount bucket 后 Space 会重启一次。

回到 Storage Buckets 区域后，看到 danmu_api-storage 这一行，并且旁边显示 Read & Write 和 /app/.cache，就说明已经挂好了。

挂载完成

出现 danmu_api-storage、Read & Write、/app/.cache，就是挂载完成。

第 8 步：记下 Space 的账号名和项目名

创建完成后，看浏览器地址。地址一般长这样：

https://huggingface.co/spaces/账号名/Space名

把这两个值先记下来：

DEPLOY_PLATFROM_ACCOUNT=账号名
DEPLOY_PLATFROM_PROJECT=Space名

后面管理员 UI 里要自动改变量、自动重启 Space，就要用到这两个值。

Space 地址

Space 页面地址里的两段，就是后面要填的账号名和 Space 名。

第 9 步：创建 Hugging Face Token

打开 Access Tokens 页面：

按顺序做：

  1. 点 Create new token
  2. 名字填 danmu-api 之类自己能看懂的名字
  3. 权限选 Write，或者 Fine-grained token 里给这个 Space 写入权限
  4. 创建后立刻复制 Token，这个值后面只显示一次

Access Tokens 页面

先进入账号设置里的 Access Tokens 页面。

创建 Token

Token type 选 Write，再填写 Token name，最后点 Create token。

第 10 步：回 GitHub fork，添加 1 个 Secret 和 3 个 Variables

回到你自己 fork 的 danmu_api 仓库，不是上游仓库。

按这个路径走：

你的 fork 仓库 → Settings → Secrets and variables → Actions

Secrets and variables 入口

按图里的顺序点：先点顶部 Settings，再点左侧 Secrets and variables，最后点它下面的 Actions。

先保持在这个页面，不要点左侧其他菜单。页面正文上方有两个页签：Secrets 和 Variables。

先添加 Secret

先停在 Secrets 页签，新建 1 个 Repository secret：

名称 值
HF_TOKEN 你在第 9 步创建的 Hugging Face Token

添加 HF_TOKEN

看图里的 1，先确认在页面正文上方的 Secrets 页签；看 2，点 New repository secret 添加；添加成功后看 3，列表里会出现 HF_TOKEN。

再添加 Variables

添加完 HF_TOKEN 后，左侧菜单不要变，仍然停在 Secrets and variables → Actions。只点页面正文上方的 Variables 页签，然后新建 3 个 Repository variables：

名称 值 说明
HF_USERNAME 你的 Hugging Face 账号名 告诉 Actions 推到哪个账号
HF_SPACE_NAME 你刚才创建的 Space 名 告诉 Actions 推到哪个 Space
ENABLE_HF_SYNC true 开启同步工作流

添加 Variables

看图里的 1，这里点的是页面正文上方的 Variables 页签；看 2，点 New repository variable 添加；同样的位置依次添加 3 个变量。

重要说明

这 4 个值是给 GitHub Actions 同步代码 用的，只填在 GitHub 仓库里，不填到 Hugging Face Space 的运行变量里。

名称 填写位置 用来做什么
HF_TOKEN GitHub 仓库 Secrets 让 GitHub Actions 有权限把代码推送到 Hugging Face Space
HF_USERNAME GitHub 仓库 Variables 告诉 GitHub Actions 要推到哪个 Hugging Face 账号或组织
HF_SPACE_NAME GitHub 仓库 Variables 告诉 GitHub Actions 要推到哪个 Space
ENABLE_HF_SYNC GitHub 仓库 Variables 填 true，开启 sync_hf.yml 同步工作流

第 11 步：打开 Actions，启用并手动同步一次

回到仓库顶部点 Actions。

如果这是 fork 仓库第一次使用 Actions，GitHub 可能会先提示 workflows 被停用。按页面提示点启用按钮。

启用 workflows

第一次进入 fork 仓库的 Actions 时，先把 workflows 启用；后面才能手动运行同步到 Hugging Face Space 的工作流。

接着按顺序做：

  1. 左侧打开 Sync to Hugging Face Space
  2. 点右侧 Run workflow
  3. 分支保持 main
  4. 再点绿色 Run workflow

手动运行同步

左侧选中 Sync to Hugging Face Space，右侧点 Run workflow，下拉框里分支保持 main 后再点绿色按钮。

第 12 步：等同步任务变成绿色成功

任务跑完后，点进这次运行记录。看到 Status: Success，并且 sync-to-huggingface 是绿色对勾，就说明 GitHub 已经把代码推到 Hugging Face Space 仓库。

同步成功

这里看到绿色成功后，再回 Hugging Face Space 页面继续。

第 13 步：确认 Space 变成 Running

回到刚才创建的 Space。同步成功后，等待 Hugging Face 构建并启动。

看到顶部状态变成 Running，并且页面出现 LogVar弹幕API 的管理界面，就说明 Space 已经跑起来了。

Space Running

看图里的 1：顶部显示 Running，页面出现 LogVar弹幕API，就可以继续填写运行变量并测试接口。

如果页面一直停在 Starting，先打开底部日志看是构建失败、变量错误，还是服务已经启动但平台还没切到 Running。

第 14 步：进入 Space Settings，填写运行变量

回到 Hugging Face Space 顶部，点页面上方的 Settings。

Settings 入口

点图里的 1：进入这个 Space 自己的 Settings。

进入 Settings 后往下翻，找到 Variables and secrets。这一步是在 Hugging Face Space 里填，和第 10 步的 GitHub 仓库变量不是同一个地方。

运行变量页面

看图里的 1，确认已经在 Variables and secrets；看 2，新增变量点 New variable；看 3，图上这 4 个是 Hugging Face Space 里最少要配置的变量。

最少需要在 Hugging Face Space 里配置这 4 个：

名称 建议放到 用来做什么
DEPLOY_PLATFROM_ACCOUNT Variables 管理员 UI 调 Hugging Face API 时，知道账号或组织名
DEPLOY_PLATFROM_PROJECT Variables 管理员 UI 调 Hugging Face API 时，知道 Space 名
DEPLOY_PLATFROM_TOKEN Secrets 管理员 UI 以后在页面里改环境变量、重启 Space 时使用
ADMIN_TOKEN Secrets 打开 danmu_api 管理员页面用

如果还想给普通接口单独设置访问口令，再额外添加：

TOKEN=87654321

注意变量名拼写

变量名要按项目代码现有拼写填写：DEPLOY_PLATFROM_ACCOUNT、DEPLOY_PLATFROM_PROJECT、DEPLOY_PLATFROM_TOKEN，中间是 PLATFROM，不要改成别的拼写。

HF_TOKEN 与 DEPLOY_PLATFROM_TOKEN 的区别

HF_TOKEN 和 DEPLOY_PLATFROM_TOKEN 可以填同一个 Hugging Face Token 的值，但变量名和填写位置不同：

  • HF_TOKEN 只填在 GitHub 仓库里，给 GitHub Actions 同步代码用
  • DEPLOY_PLATFROM_TOKEN 填在 Hugging Face Space 里，给部署好的 danmu_api 管理员 UI 用

不要把 HF_TOKEN 填到 Hugging Face Space，也不要把 DEPLOY_PLATFROM_TOKEN 填到 GitHub 仓库 Secrets 当成同步变量。

第 15 步：以后直接在管理员页改变量

第 14 步那几个变量配好以后，后面删改变量不要再回 Hugging Face 的 Settings → Variables and secrets 里操作，直接打开 danmu_api 管理员页面：

https://你的Space访问地址/你的ADMIN_TOKEN

如果按前面的默认地址拼，就是：

https://你的账号名-你的Space名.hf.space/你的ADMIN_TOKEN

进入后打开 系统配置，后续新增、编辑、删除变量都在这里做。

系统配置

打开管理员页后进入 系统配置。后续删改变量直接在前端操作，不需要再回 Hugging Face 后台找变量页。

按需要操作：

  • 新增变量：在系统配置里新增一项配置
  • 修改变量：点对应变量右侧的 编辑，改完保存
  • 删除变量：点对应变量右侧的 删除

自动重新部署

Hugging Face Space 在前端保存或删除变量后，通常会自动触发重新构建/部署，一般不需要再手动点"重新部署"。等 Space 状态重新回到 Running 后，再继续做部署后自检。

第 16 步：测试验证

Space 回到 Running 后：

测试首页

直接访问根路径：

https://你的账号名-你的Space名.hf.space/

测试 API

在浏览器访问搜索接口：

https://你的账号名-你的Space名.hf.space/api/v2/search/anime?keyword=鬼灭之刃&token=87654321

将 87654321 替换为你设置的 TOKEN 值。

如果返回 JSON 数据（包含弹幕搜索结果），说明部署成功。

测试管理员后台

访问 https://你的账号名-你的Space名.hf.space/你的ADMIN_TOKEN，即可进入管理员后台。

第 17 步：以后怎么同步上游更新

Hugging Face Space 这条线后续更新分两层：

  1. Fork Sync 负责把上游 huangxd-/danmu_api 的更新同步到你的 GitHub fork
  2. 你的 fork 有新提交后，.github/workflows/sync_hf.yml 会把代码推到 Hugging Face Space，Space 会重新构建

启用 Fork Sync

回到你自己 fork 的 GitHub 仓库，点顶部 Actions。

进入 Actions

后续同步上游更新时，从你自己的 fork 仓库进入 Actions。

左侧打开 Fork Sync。这个工作流如果以前没启用过，页面会显示 Disabled，要先点右侧 Enable workflow。

启用 Fork Sync

先点左侧 Fork Sync。如果页面显示 Disabled，说明这个自动同步工作流还没启用。

启用成功

点右侧 Enable workflow。看到 Workflow enabled successfully 后，再继续手动运行。

启用后，点 Run workflow 手动跑一次。看到 Success，就说明这个 fork 自动同步工作流可以正常跑。

手动同步成功

手动跑一次 Fork Sync，看到 Success 就可以了。

如果自动同步失败

如果自动同步失败，常见原因是上游改了 workflow 文件，或者自动同步工作流没有权限同步某些受保护文件。这时不用纠结报错，回到 GitHub fork 首页，用网页端 Sync fork → Update branch 手动同步一次；同步完后，再回 Actions 手动跑一次 Sync to Hugging Face Space。

网页端同步

Sync fork 只会在你的 fork 落后上游时出现。

常见问题

1）Space 一直启动失败

先打开 Space 页面里的日志，确认是构建失败还是启动失败。常见原因是变量名拼错、Token 填错、代码还没有同步完成，先按前面的步骤逐项核对。

2）Hugging Face Space 还要不要配 Upstash

按第 7 步把 Storage Bucket 挂到 /app/.cache 后，Hugging Face Space 这条线可以先不配 Upstash。danmu_api 会把运行缓存写进 .cache，比只放内存更适合 Space 运行。

.cache 的作用范围

这里的 .cache 只保存运行缓存，不保存环境变量。管理员 UI 里改变量时，Hugging Face Space 仍然会走 Hugging Face API，把变量写回 Space 自己的 Variables and secrets。

但免费版重启、重建或切换实例后，运行目录可能清空，缓存会重新生成；它不能当成跨实例持久恢复。如果你确实需要跨实例共享缓存，再考虑外部 Redis / Upstash。

3）Actions 推送失败

回 GitHub 仓库检查这 4 个名字是否完全一致：

Secret: HF_TOKEN
Variable: HF_USERNAME
Variable: HF_SPACE_NAME
Variable: ENABLE_HF_SYNC=true

HF_TOKEN 要放在 Secrets；HF_USERNAME、HF_SPACE_NAME 和 ENABLE_HF_SYNC 要放在 Variables。ENABLE_HF_SYNC 必须填 true，否则新版上游的 sync_hf.yml 不会真正执行同步。名字写错、Token 没有写入权限、Space 名大小写不一致，也都会导致推送失败。

4）管理员 UI 里改变量失败

检查 Space 里是否已经填了 DEPLOY_PLATFROM_ACCOUNT、DEPLOY_PLATFROM_PROJECT、DEPLOY_PLATFROM_TOKEN。

注意这里变量名里的 PLATFROM 是项目代码当前使用的拼写，照着写，不要改成 PLATFORM。

5）地址里的账号名和 Space 名怎么拼

Space 页面是：

https://huggingface.co/spaces/账号名/Space名

访问服务时通常是：

https://账号名-Space名.hf.space/

如果 Space 名里有大写字母，测试访问时优先按 Hugging Face 页面给出的实际 hf.space 地址复制。

下一步