Hugging Face Space 部署
适合免费体验和备用入口，会有冷启动；长期主力优先 Docker 部署 或 NAS / 家用网络。手机找不到按钮时切到“桌面版网站”。
适合谁
- 适合：想免费体验、已有 Hugging Face 账号、可以接受冷启动和偶尔重建。
- 不适合：希望长期稳定主力使用、希望国内网络访问更稳、希望维护步骤最少。
- 注意：这条路线需要 GitHub Actions 把代码同步到 Hugging Face Space，比 Vercel / Netlify 多一步。
准备
开始前准备好：
- GitHub 账号。
- Hugging Face 账号，且邮箱已经验证。
- 一份你自己的
danmu_apifork。 - 一个管理员令牌，后面填到
ADMIN_TOKEN。
1. Fork 项目仓库
打开项目仓库：
按顺序操作：
- 点击右上角 Fork。
- 确认 Fork 到你自己的 GitHub 账号。
- 页面变成
你的用户名/danmu_api后再继续。
注意
后面 GitHub Actions 要从你自己的 fork 同步代码，不要直接操作 huangxd- 的上游仓库。
2. 注册或登录 Hugging Face
打开 Hugging Face：
没有账号就注册，有账号就登录。注册时按页面提示填写邮箱、密码、用户名和显示名称。
如果页面提示验证邮箱，先去邮箱点确认链接，验证完成后再继续创建 Space。
3. 创建 Docker Space
登录后打开新建 Space 页面：
基础信息建议这样填：
- Owner：选择你自己的账号或组织。
- Space name：
danmu_api。 - License：可以先选
mit。
SDK 一定选择：
Docker → Blank不要选 Gradio / Static。
硬件先选免费的：
CPU Basic
Storage Bucket 建议打开，用来挂载运行缓存：
Mount a bucket to this Space
Bucket 建议这样填：
- Bucket name：
danmu_api-storage - Bucket visibility：
Public - Mount path：
/app/.cache - Access mode：
Read & Write
最后 Visibility 选 Public，点击 Create Space。
Storage Bucket 说明
Bucket 名不要填 .cache。Bucket 是 Hugging Face 后台里的存储名称，真正挂到程序里的路径是 /app/.cache。
4. 记下 Space 账号名和项目名
创建完成后，看浏览器地址。地址一般是：
https://huggingface.co/spaces/账号名/Space名先记下这两个值：
账号名Space名
后面 GitHub Actions 同步代码、以及系统配置里自动更新变量都会用到。
5. 创建 Hugging Face Token
打开 Access Tokens 页面：
按顺序操作：
- 点击 Create new token。
- 名字填
danmu-api之类自己能看懂的名称。 - 权限选 Write，或 Fine-grained token 里给当前 Space 写入权限。
- 创建后立刻复制 Token；这个值后面只完整显示一次。
6. 配置 GitHub Actions 同步变量
回到你自己 fork 的 danmu_api 仓库，进入：
Settings → Secrets and variables → Actions
先在 Secrets 页签添加一个 Repository secret：
HF_TOKEN：上一步创建的 Hugging Face Token。
再切到 Variables 页签，添加三个 Repository variables：
HF_USERNAME：你的 Hugging Face 账号名。HF_SPACE_NAME：刚才创建的 Space 名。ENABLE_HF_SYNC：填true。
填写位置不要混
这 4 个值只填在 GitHub 仓库 里，用来让 GitHub Actions 把代码推送到 Hugging Face Space。不要填到 Hugging Face Space 的运行变量里。
7. 手动同步一次代码
回到仓库顶部，点击 Actions。
如果这是 fork 仓库第一次使用 Actions，GitHub 可能会提示 workflows 被停用，先按页面提示启用。
然后按顺序操作：
- 左侧打开 Sync to Hugging Face Space。
- 点击 Run workflow。
- 分支保持
main。 - 再点绿色 Run workflow。
任务跑完后，点进这次运行记录。看到绿色成功，就说明代码已经推到 Hugging Face Space。
8. 等 Space 变成 Running
回到刚才创建的 Space，等待 Hugging Face 构建并启动。
看到顶部状态变成 Running，并且页面出现 LogVar 弹幕 API 界面，就说明服务已经跑起来。
如果一直停在 Starting，先打开页面底部日志，确认是构建失败、变量错误，还是平台还没切到 Running。
9. 配置 Space 运行变量
进入这个 Space 的 Settings，往下找到 Variables and secrets。
至少添加这些变量：
ADMIN_TOKEN：管理员令牌，用来进入系统配置。TOKEN：普通访问令牌；不改也可以继续用默认87654321。
如果你想在网页里修改系统配置，还需要继续配置：
DEPLOY_PLATFROM_ACCOUNT：Hugging Face 账号名或组织名。DEPLOY_PLATFROM_PROJECT：Space 名。DEPLOY_PLATFROM_TOKEN：Hugging Face Token。
变量怎么找、怎么填，可以看：UI 与环境变量。
Hugging Face Space 保存变量后通常会自动重启。等状态重新变成 Running 后，再继续验证。
10. 验证服务
Hugging Face Space 的访问地址通常是：
https://账号名-Space名.hf.space/如果 Space 页面给出了实际地址，以页面显示的地址为准。
打开首页
https://账号名-Space名.hf.space/能看到 LogVar 弹幕 API 页面，说明服务已经跑起来。
打开播放器地址
把 TOKEN 换成你设置的值；如果没改过，就是默认的 87654321。
https://账号名-Space名.hf.space/你的TOKEN能看到页面里的配置预览、接口调试等内容，说明播放器地址可用。
打开系统配置
https://账号名-Space名.hf.space/你的ADMIN_TOKEN能进入系统配置，说明管理员令牌可用。
常见问题
Space 一直启动失败
先打开 Space 页面里的日志，确认是构建失败还是启动失败。常见原因是同步任务没成功、变量名拼错、Token 权限不够。
还要不要配置 Upstash Redis
按前面步骤把 Storage Bucket 挂到 /app/.cache 后，Hugging Face Space 可以先不配 Upstash。运行缓存会写进 .cache。
如果你需要跨实例共享缓存，或者发现缓存经常丢失，再考虑外部 Redis / Upstash。
创建时忘了打开 Storage Bucket
不用删 Space。进入 Space 的 Settings → Storage Buckets，点击 Mount a bucket，按下面填写：
- Bucket name：
danmu_api-storage - Bucket visibility：
Public - Mount path：
/app/.cache - Access mode：
Read & Write
看到 danmu_api-storage、Read & Write、/app/.cache，就是挂载完成。
Actions 推送失败
回 GitHub 仓库检查这 4 个值：
Secret: HF_TOKEN
Variable: HF_USERNAME
Variable: HF_SPACE_NAME
Variable: ENABLE_HF_SYNC=trueHF_TOKEN 要放在 Secrets；另外三个要放在 Variables。名字写错、Token 没有写入权限、Space 名大小写不一致，都会导致推送失败。
以后怎么同步上游更新
后续更新一般是两层：
- 先把上游
huangxd-/danmu_api的更新同步到你的 GitHub fork。 - 再运行 Sync to Hugging Face Space，把 fork 里的新代码推到 Hugging Face Space。
更完整的更新说明后续看：更新维护。