Hugging Face Space 部署

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

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

先打开：

打开 huangxd-/danmu_api

然后按顺序做：

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

打开 Hugging Face 注册页：

打开 Hugging Face 注册页

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

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

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

点 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

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

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

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

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

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

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

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

登录后打开新建 Space 页面：

打开 New Space

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

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

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

Space hardware 选免费的 CPU Basic。

Storage Bucket 选择 Mount a bucket to this Space。

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

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

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

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

danmu_api 支持把运行缓存写进 .cache。这里把 Hugging Face 的 Storage Bucket 挂到 /app/.cache 后，Hugging Face Space 这条部署线就不需要像需要共享缓存的云平台那样先配 Upstash 才能跑缓存。

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

但不要把它当成跨实例恢复方案：免费版 Space 重启、重建或切换实例后，运行目录可能被清空，缓存会重新生成，不能保证像外部 Redis 那样跨实例保留。

不用删 Space。进入这个 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

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

之前已经生成在临时目录里的缓存不会自动迁过去；挂载完成后，新生成的运行缓存才会写进 /app/.cache。

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

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

把这两个值先记下来：

DEPLOY_PLATFROM_ACCOUNT=账号名
DEPLOY_PLATFROM_PROJECT=Space名

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

打开 Access Tokens 页面：

打开 Hugging Face Tokens

按顺序做：

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

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

按这个路径走：

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

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

HF_TOKEN=*** Hugging Face Token

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

HF_USERNAME=你的 Hugging Face 账号名或组织名
HF_SPACE_NAME=刚才创建的 Space 名
ENABLE_HF_SYNC=true

到这里，HF_TOKEN 放在 Secrets，HF_USERNAME、HF_SPACE_NAME 和 ENABLE_HF_SYNC 放在 Variables。后面的同步工作流会从仓库变量读取账号名、Space 名和开关状态，从 Secret 读取 Token。

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

上面这 4 个仓库变量填好后，再去运行同步工作流。

回到仓库顶部点 Actions。

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

接着按顺序做：

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

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

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

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

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

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

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

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

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

TOKEN=*** 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 当成同步变量。

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

更详细的变量作用和填写位置，见 UI 与环境变量 · Hugging Face Space。

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

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

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

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

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

按需要操作：

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

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

Space 回到 Running 后，不在这里重复写测试细节，直接按 部署后自检 继续检查首页、弹幕测试和管理员入口。

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

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

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

左侧打开 Fork Sync。这个工作流如果以前没启用过，页面会显示 Disabled，要先点右侧 Enable workflow。这一步不能省略，否则后面不会自动同步上游更新。

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

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

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

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

这里的 .cache 只保存运行缓存，不保存环境变量。管理员 UI 里改变量时，Hugging Face Space 仍然会走 Hugging Face API，把变量写回 Space 自己的 Variables and secrets。只有电脑本地 / 普通 Docker 这类 node 部署，前端改变量才会写本地 config/.env。

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

回 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 名大小写不一致，也都会导致推送失败。

检查 Space 里是否已经填了：

DEPLOY_PLATFROM_ACCOUNT
DEPLOY_PLATFROM_PROJECT
DEPLOY_PLATFROM_TOKEN

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

Space 页面是：

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

访问服务时通常是：

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

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

• 播放器接入
• UI 与环境变量 · Hugging Face Space
• 云平台绑定域名 · Hugging Face Space
• 缓存配置

截图来源：Hugging Face 官方页面与文档图片、用户提供的 Hugging Face 注册页、资料填写、邮箱验证、新建 Space、Token、Space Running、Space Settings、Variables and secrets 与管理员 UI 系统配置实际操作截图、GitHub 官方文档图片、GitHub Fork、workflows 目录、README 与 Actions 的实际操作截图、用户提供的 GitHub 仓库变量页面截图。