跳转到内容
danmu_api 图文教程
搜教程里的步骤和配置项 例如 Vercel、Docker、TOKEN、播放器、域名。

常见问题

这个页面整理部署和使用过程中常见的处理方法。

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

问题目录

Section titled “问题目录”

问题 1：Fork Sync 某次自动同步突然失败怎么办？

Section titled “问题 1：Fork Sync 某次自动同步突然失败怎么办？”

适用于 Vercel、Netlify、Cloudflare Workers、EdgeOne Pages、Hugging Face Space 这类从 GitHub fork 自动部署的方式。

目标：先把 fork 手动同步到最新，再重新跑一次 Fork Sync。

这种红叉最常见的原因不是云平台坏了，也不是要重新部署项目，而是上游仓库这次改到了 .github/workflows/*.yml 这类 GitHub Actions 工作流文件。Fork Sync 自动运行时使用的是默认 GITHUB_TOKEN，它通常没有权限直接把上游的 workflow 文件改动写进你的 fork，所以同步会被 GitHub 权限拦截，最后显示红叉。

Fork Sync 自动同步失败原因解释图：上游改了 .github/workflows 下的 yml 文件，默认 GITHUB_TOKEN 无权写入 workflow 文件，导致权限拦截和红叉
简单理解：上游改了工作流 yml，自动同步想写入你的 fork，但默认令牌权限不够，所以被拦住。

处理办法很简单：不要先去翻一堆日志，也不要删项目。直接按下面步骤在 GitHub 网页端点一次 Sync fork，让你本人授权完成同步，然后再手动跑一次 Fork Sync 验证。

如果页面里同时有 Node.js 20 actions are deprecated 这类黄色 warning，先不用管。它是 GitHub Actions 的弃用提醒，不是这次红叉的直接失败原因。

第 1 步：回到 Code 页，点 Sync fork

Section titled “第 1 步：回到 Code 页，点 Sync fork”

先回到自己 fork 出来的 danmu_api 仓库首页处理同步。

  1. 点顶部 Code
  2. 确认页面提示 This branch is ... behind huangxd-/danmu_api:main
  3. 点右侧 Sync fork
GitHub 仓库 Code 页面提示 fork 落后上游并显示 Sync fork 按钮的截图，已圈出 Code、落后提示和 Sync fork
按图里顺序点：先进 Code，看到落后提示后点右侧 Sync fork。

这一步建议在电脑网页端操作。手机端 GitHub 页面经常折叠按钮，容易找不到 Sync fork。

第 2 步：在弹窗里点 Update branch

Section titled “第 2 步：在弹窗里点 Update branch”

点 Sync fork 后，会弹出 This branch is out-of-date 提示。

  1. 确认弹窗里写的是从 upstream repository 同步提交
  2. 不用点 Compare
  3. 直接点绿色的 Update branch
GitHub Sync fork 后弹出的 This branch is out-of-date 对话框截图，已圈出 Update branch 按钮
这里点绿色的 Update branch，不要点左边的 Compare。

第 3 步：确认仓库已经同步完成

Section titled “第 3 步：确认仓库已经同步完成”

点完 Update branch 后，页面会回到仓库首页。再点一次 Sync fork，如果看到 This branch is not behind the upstream ... No new commits to fetch，说明 fork 已经同步到最新。

GitHub Sync fork 后提示 This branch is not behind the upstream 的截图，已圈出 up to date 提示
看到这个绿色提示，就说明网页端同步已经完成。

如果一开始就看不到 Update branch，而是直接看到这个绿色提示，说明当前 fork 本来就是最新的，可以直接继续下一步。

第 4 步：回到 Fork Sync，手动再跑一次

Section titled “第 4 步：回到 Fork Sync，手动再跑一次”

网页端同步完成后，回到 Actions → Fork Sync。

  1. 点右侧 Run workflow
  2. 分支保持 main
  3. 再点绿色的 Run workflow
  4. 等它跑完
GitHub Fork Sync 工作流运行页面截图，显示 Run workflow 入口
手动跑一次是为了确认刚才的同步问题已经解决，不用等下一次定时任务。

第 5 步：看结果

Section titled “第 5 步：看结果”

如果新的 Fork Sync 记录变成绿色对勾，就说明自动同步工作流恢复正常了。后面 GitHub fork 有新提交时，云平台会按自己的规则重新构建部署。

如果还是红叉，继续点进新的失败记录 → Sync with Upstream job，把日志里第一段红色报错完整复制出来，再按报错处理。常见情况：

  1. Sync fork 按钮没有出现：通常说明 fork 已经是最新的，直接手动 Run workflow 验证即可。
  2. 日志提示有冲突：需要先在 GitHub 网页端或本地解决冲突，再重新运行 Fork Sync。
  3. 日志提示权限或 token 问题：检查仓库 Settings → Actions → General 里的 workflow 权限，不要删除仓库，也不要重新部署云平台项目。

处理这个问题时，不需要点左侧那个已经禁用的 Build and Push Docker Image to Docker Hub 工作流，也不需要删除云平台项目。先把 fork 同步恢复，再让平台重新构建即可。

问题 2：Build Docker / Hugging Face 工作流一直红叉怎么办？

Section titled “问题 2：Build Docker / Hugging Face 工作流一直红叉怎么办？”

目标：看懂这两个可选工作流分别是做什么的。Hugging Face 同步现在默认不会启用，只有配置 ENABLE_HF_SYNC=true 才会运行。

第 1 步：先分清这两个工作流

Section titled “第 1 步：先分清这两个工作流”

左侧常见的两个可选工作流是：

  1. Build and Push Docker Image to Docker Hub：用于把仓库代码构建成 Docker 镜像并推送到 Docker Hub，主要是给想维护自己 Docker 镜像的人用。
  2. Sync to Hugging Face Space：把仓库代码同步到 Hugging Face Space。
GitHub Actions 左侧两个可选工作流 Build and Push Docker Image to Docker Hub 和 Sync to Hugging Face Space 的截图，已圈出两个工作流
图里 1 是 Docker Hub 镜像构建工作流，图里 2 是 Hugging Face Space 同步工作流。

如果当前只是用 Vercel、Netlify、Cloudflare Workers、EdgeOne Pages 部署，这两个工作流通常用不到。Docker Hub 工作流一般是上游升级镜像或用户想构建自己的 Docker 镜像时才需要；Hugging Face 工作流只有在你要同步到 Hugging Face Space 时才需要。

第 2 步：Hugging Face 同步默认关闭

Section titled “第 2 步：Hugging Face 同步默认关闭”

新版上游已经加了开关：没有配置 ENABLE_HF_SYNC=true 时，sync_hf.yml 会默认跳过同步，不会真正推送到 Hugging Face Space。

如果正在用 Hugging Face Space，就去 GitHub 仓库 Variables 里配置：

ENABLE_HF_SYNC=true
HF_USERNAME=你的 Hugging Face 用户名
HF_SPACE_NAME=你的 Space 名称

同时在 Secrets 里配置：

HF_TOKEN=你的 Hugging Face Token

具体填写步骤看：Hugging Face Space 部署教程第 10 步。

第 3 步：Docker Hub 工作流不用时再禁用

Section titled “第 3 步：Docker Hub 工作流不用时再禁用”

如果不用 Docker Hub 镜像，才需要点左侧 Build and Push Docker Image to Docker Hub，然后从右上角三点菜单里禁用。

GitHub Actions Docker Hub 工作流页面右上角三点菜单中 Disable workflow 的截图，已圈出工作流、三点菜单和 Disable workflow
只需要禁用 Docker Hub 镜像构建工作流时，按图里 1、2、3 点。

禁用成功后，看 3 个位置：顶部出现 Workflow disabled successfully，左侧对应工作流显示 Disabled，页面里出现 This workflow was disabled manually。

GitHub Actions Docker Hub 工作流禁用成功截图，已圈出顶部成功提示、左侧 Disabled 和禁用提示
Docker Hub 工作流禁用成功后，会看到顶部成功提示和左侧 Disabled。

Fork Sync 不属于这里的两个可选发布工作流。它是用来同步上游更新的；如果还想让 fork 自动跟上游更新，先不要禁用 Fork Sync。

问题 3：部署后播放器加载不出来弹幕怎么办？

Section titled “问题 3：部署后播放器加载不出来弹幕怎么办？”

先不要直接改播放器设置。按下面顺序排查，能最快判断是服务问题、地址问题，还是平台网络问题。

第 1 步：先用部署后自检确认服务能拿到弹幕

Section titled “第 1 步：先用部署后自检确认服务能拿到弹幕”

先打开 部署后自检，在 danmu_api 自带的弹幕测试页里跑一遍自动匹配和手动匹配。

打开部署后自检

部署后自检中自动匹配成功并显示弹幕统计的截图
自动匹配能看到弹幕统计和弹幕列表，说明文件名匹配这条线可用。
部署后自检中手动匹配成功并显示弹幕统计的截图
手动匹配也能看到弹幕统计和弹幕列表，说明服务本身能拿到弹幕。

如果这两步都拿不到弹幕，问题先不在播放器，先按自检页里的提示处理服务地址、TOKEN、平台域名或缓存配置。

如果自检页能拿到弹幕，但播放器里没有弹幕，再继续下面几项。

第 2 步：检查播放器里填的是基础地址

Section titled “第 2 步：检查播放器里填的是基础地址”

播放器里一般填基础地址，不要填完整接口，也不要填管理员入口。

正确示例：

https://你的域名

如果配置了自己的 TOKEN：

https://你的域名/你的TOKEN

不要填：

https://你的域名/api/v2/search/anime?keyword=凡人修仙传

也不要填：

https://你的域名/你的ADMIN_TOKEN

播放器接入步骤看：播放器接入。

第 3 步：Vercel 默认域名可能需要挂梯访问

Section titled “第 3 步：Vercel 默认域名可能需要挂梯访问”

如果是 Vercel 部署，vercel.app 默认域名在当前网络里可能访问不稳定：

  • 页面打不开
  • 页面能打开，但弹幕测试一直匹配不成功
  • 自检偶尔成功，播放器里经常加载失败

这种情况通常需要挂梯访问。如果不想挂梯，建议直接绑定自己的域名，再把播放器里的地址换成新域名。

继续看：云平台绑定域名 · Vercel。

第 4 步：EdgeOne Pages 要补 Upstash

Section titled “第 4 步：EdgeOne Pages 要补 Upstash”

如果是 EdgeOne Pages 部署，弹幕测试或播放器加载时经常失败，先确认已经配置 Upstash：

UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN

EdgeOne 这条线需要共享缓存。不补 Upstash 时，请求落到新的运行环境后，匹配弹幕很容易失败或返回 404。

配置步骤看：

第 5 步：确认播放器当前视频标题能匹配

Section titled “第 5 步：确认播放器当前视频标题能匹配”

服务正常、地址也正确时，播放器仍可能因为视频标题太乱而自动匹配不到。常见情况：

  • 标题里只有数字，没有剧名
  • 标题里带了太多网站名、画质、字幕组信息
  • 当前视频的集数和接口识别到的集数不一致

这时先在播放器里手动选作品和剧集。手动能选到并加载弹幕，就说明服务本身正常，只是自动匹配没识别好。