LogVar 弹幕 API

外观

常见问题 ​

使用 LogVar 弹幕 API 过程中遇到问题时，先按目录找到对应场景，再按步骤排查。

问题目录 ​

部署相关 ​

1. Fork Sync 自动同步突然失败 ​

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

直接处理：先在 GitHub 网页端手动同步一次 fork，再手动跑一次 Fork Sync 验证。

为什么会失败

如果上游这次改到了 .github/workflows/*.yml，定时 Fork Sync 使用的默认 GITHUB_TOKEN 可能没有权限写入这些工作流文件，所以会红叉。网页端 Sync fork 使用你的账号权限，通常能直接同步过去。

第 1 步：点 Sync fork ​

进入自己 fork 的 danmu_api 仓库首页，点右侧 Sync fork。

点击 Sync fork

这里只点 Sync fork。

提示

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

第 2 步：点 Update branch ​

弹窗出现后，点绿色 Update branch，不要点 Compare。

点击 Update branch

这里只点绿色的 Update branch。

如果没有 Update branch，而是提示已经是最新，直接继续下一步。

第 3 步：手动运行 Fork Sync ​

进入 Actions → Fork Sync，点右侧 Run workflow，分支保持 main，再点绿色 Run workflow。

手动运行 Fork Sync

先点右上的 Run workflow，再点下拉框里的绿色 Run workflow。

第 4 步：看结果 ​

新的 Fork Sync 记录变成绿色对勾，就说明恢复正常。

如果还是红叉，点进新的失败记录 → Sync with Upstream，把第一段红色报错复制出来。常见原因：

  1. 有冲突：先按 GitHub 提示解决冲突，再重新运行 Fork Sync
  2. 仍然是权限问题：检查仓库 Settings → Actions → General 的 workflow 权限
  3. 看不到 Sync fork：通常说明 fork 已经是最新，直接手动运行 Fork Sync 验证即可

2. Build Docker / Hugging Face 工作流一直红叉 ​

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

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

  1. Build and Push Docker Image to Docker Hub：把仓库代码构建成 Docker 镜像并推送到 Docker Hub，给想维护自己 Docker 镜像的人用
  2. Sync to Hugging Face Space：把仓库代码同步到 Hugging Face Space

两个可选工作流

图里 1 是 Docker Hub 镜像构建工作流，图里 2 是 Hugging Face Space 同步工作流。

如果当前只是用 Vercel、Netlify、Cloudflare Workers、EdgeOne Pages 部署，这两个工作流通常用不到。

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

新版上游已经加了开关：没有配置 ENABLE_HF_SYNC=true 时，sync_hf.yml 会默认跳过同步。

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

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

同时在 Secrets 里配置：

text
HF_TOKEN=你的 Hugging Face Token

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

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

禁用工作流菜单

只需要禁用 Docker Hub 镜像构建工作流时，按图里 1、2、3 点。

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

禁用成功

Docker Hub 工作流禁用成功后，会看到顶部成功提示和左侧 Disabled。

Fork Sync 不属于这里的两个可选发布工作流，先不要禁用 Fork Sync。

3. Docker 容器无法启动 ​

运行 docker compose up -d 后容器立即退出或状态异常。

常见原因及排查：

  1. 端口被占用：

    bash
    # 检查端口占用
netstat -tuln | grep 9321

# 在 docker-compose.yml 里改端口映射
ports:
  - "9322:9321"

  2. 镜像不存在或拉取失败：

    bash
    docker compose pull

  3. 查看容器日志定位问题：

    bash
    docker compose logs danmu-api --tail 50

4. Docker 环境变量修改后不生效 ​

修改 .env 文件后，容器内的配置没有更新。

解决方案：

使用 Docker Compose 部署时，确保 docker-compose.yml 中挂载了配置目录：

yaml
services:
  danmu-api:
    image: logvar/danmu-api:latest
    ports:
      - "9321:9321"
    volumes:
      - ./config:/app/config
      - ./.cache:/app/.cache
    restart: unless-stopped

修改 config/.env 后，正常情况下应用会自动检测并重新加载配置。如果页面还是旧值，手动重启：

bash
docker compose restart danmu-api

5. Docker 挂载目录里没有自动生成 .env ​

Docker 部署后，config 目录里没有看到 .env，通常不是镜像坏了，而是挂载目录没有正常写入。

常见原因：

  1. 挂载目录权限不够：比如 1Panel 面板里新建的文件夹归属用户、权限比较特殊，容器内进程没法在 ./config 里创建文件。
  2. 挂载路径写错了：Compose 里不是 ./config:/app/config，或者面板里填成了另一个目录。
  3. 目录提前建成了文件：宿主机上 config 不是文件夹，或者 .env 被建成了目录。
  4. 容器启动太早失败：目录没有写入成功，容器直接退出，后续也不会再生成配置。

处理步骤：

第 1 步：确认挂载写法 ​

docker-compose.yml 里要有：

yaml
volumes:
  - ./config:/app/config
  - ./.cache:/app/.cache

第 2 步：手动创建目录 ​

在 docker-compose.yml 同级目录执行：

bash
mkdir -p config .cache

第 3 步：修正目录权限 ​

普通 Docker Compose 可以先这样处理：

bash
chmod 755 config .cache

如果是 1Panel 这类面板部署，优先在面板文件管理里把项目目录、config 目录权限改成容器可读写；仍不行再用 SSH 执行：

bash
chmod -R 755 config .cache

不要把整个服务器目录随便改成 777。只在确认权限问题时，临时对当前项目的 config 目录排查。

第 4 步：复制示例配置 ​

如果容器没有自动生成 .env，可以手动复制一份：

bash
cp config/.env.example config/.env

如果当前目录没有 config/.env.example，可以重新拉取项目文件，或者从项目仓库里的 config/.env.example 复制内容新建 config/.env。

第 5 步：重启容器 ​

bash
docker compose down
docker compose up -d

重启后再看：

bash
docker compose logs danmu-api --tail 50

能看到服务正常监听 9321，并且 config/.env 存在，就说明问题解决。

6. Watchtower 自动更新不生效 ​

Watchtower 只能自动拉取并替换 镜像更新后的容器。它不会帮你重新构建 GitHub 源码，也不会修复 Compose 文件里的配置问题。

常见原因：

  1. 用的是本地构建镜像：Compose 里写了 build:，或者容器来自自己手动构建的镜像。Watchtower 不会自动重新 git pull + docker build。
  2. 镜像标签不是会更新的标签：没有使用 logvar/danmu-api:latest，或者用了自己固定版本的镜像。
  3. Docker Hub 镜像还没更新：项目代码更新了，但远端镜像没有新 digest，Watchtower 就没有东西可拉。
  4. Watchtower 没管到这个容器：容器名、label、scope、网络配置不匹配，Watchtower 实际没扫描到 danmu-api。
  5. 容器更新了，但配置没变：旧的 .env、旧挂载目录、旧 Compose 配置还在，看起来像“没更新”。

先确认 Compose 里推荐这样写：

yaml
services:
  danmu-api:
    image: logvar/danmu-api:latest
    container_name: danmu-api
    restart: unless-stopped
    volumes:
      - ./config:/app/config
      - ./.cache:/app/.cache

如果你之前是 build: 方式，想用 Watchtower 自动更新，就改成上面的 image: logvar/danmu-api:latest，然后重新启动：

bash
docker compose pull danmu-api
docker compose up -d danmu-api

检查 Watchtower 是否在跑：

bash
docker ps | grep watchtower

检查它有没有扫描到更新：

bash
docker logs watchtower --tail 100

如果想立刻手动更新一次，不用等 Watchtower：

bash
docker compose pull danmu-api
docker compose up -d danmu-api

如果手动执行上面两行“一下就好了”，说明服务本身没问题，通常是 Watchtower 没拉到新镜像、没管到这个容器，或者你原来用的是本地构建镜像。

如果你坚持使用自己 fork 的源码构建镜像，Watchtower 不是合适工具。要么继续手动重新构建：

bash
git pull
docker compose build --no-cache danmu-api
docker compose up -d danmu-api

要么改成 GitHub Actions 构建并推送自己的镜像，然后让 Watchtower 监控这个远端镜像。

7. Netlify 免费版积分用完了 ​

Netlify 免费版每月 300 积分，每次重新部署扣 15 积分。

解决方案：

  1. 不要零散改变量：Netlify 上修改平台环境变量后，仍然要重新部署才会稳定生效；在前端 UI 里改变量，也需要点一次重新部署，不然新实例不一定读到新配置。
  2. 一次性改完再部署：先把 TOKEN、ADMIN_TOKEN、SOURCE_ORDER、缓存、Cookie 等变量一次性整理好，再统一部署，避免每改一项就消耗一次积分。
  3. 能用 Docker 就优先 Docker：Docker / Node.js 挂载 config/.env 后支持热更新，更适合长期频繁调配置。
  4. 没有服务器再换平台：可以继续用 Netlify，但要控制部署次数；也可以考虑 Vercel、EdgeOne Pages 或 Hugging Face Space，注意这些云平台改变量后通常也需要重新部署或重建。

8. Cloudflare Workers 弹幕获取不全或达到请求上限 ​

Cloudflare Workers 免费版有两个限制会影响 danmu_api：

  1. 每天 10 万次请求。
  2. 单次 Worker 调用最多 50 个外部子请求。

第二个限制更容易踩坑。danmu_api 获取腾讯视频弹幕时，会先获取分片列表，再请求每一个分片；部分腾讯视频弹幕分片会到 90 多个。超过 Workers 免费版子请求上限后，可能表现为弹幕数量明显偏少、后半段弹幕缺失，或者接口请求失败。

解决方案：

  1. 不推荐继续把 Cloudflare Workers 当主力部署：长期使用优先换 Docker。
  2. 没有服务器时换其他云平台：可以考虑 Vercel、Netlify 或 EdgeOne Pages。
  3. 减少重复请求：配置缓存只能减少重复获取，不能解决单集分片数超过上限的问题。
  4. 升级 Workers 付费版：付费版子请求上限更高，但仍不如 Docker 直观稳定。

9. EdgeOne Pages 报 404 ​

部署在 EdgeOne Pages 上，请求任何接口都返回 404。

原因：EdgeOne Pages 必须配置 Upstash Redis。实测不配置 Upstash 时，请求接口会稳定返回 404；补上 Upstash 变量并重新部署后才会正常。

解决步骤：

  1. 注册 Upstash Redis：访问 https://upstash.com/ ，创建 Redis 实例（免费版足够）

  2. 获取连接信息：在 Upstash 控制台获取 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN

  3. 配置环境变量：

    UPSTASH_REDIS_REST_URL=你的Redis URL
UPSTASH_REDIS_REST_TOKEN=你的Redis Token

  4. 重新部署：EdgeOne Pages 改完环境变量后需要重新部署，部署成功后再打开接口测试

10. Vercel 默认域名国内无法访问 ​

Vercel 部署成功，但默认域名（xxx.vercel.app）在国内需要梯子。

解决方案：

方案说明推荐度
绑定自定义域名购买域名后按 域名绑定 教程配置推荐
Docker 部署无网络限制，最稳定最推荐
Cloudflare Workers免费版有子请求上限，腾讯视频等分片多时可能弹幕不全不推荐主力使用

11. 同步成功后版本号还是旧的 ​

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

直接处理：先不要重复 Fork，也不要马上重建项目。先确认“GitHub 代码同步成功”以后，云平台有没有真的重新部署到最新提交。

为什么会这样

Fork Sync 成功只代表 GitHub 上你的 fork 已经同步到上游新代码，不代表 Vercel / Netlify / Cloudflare / EdgeOne / Hugging Face 已经把这次新代码重新部署成功。

最常见原因是：云平台和 GitHub 的绑定掉了、GitHub App 没有仓库权限、平台监听的不是你自己的 fork、生产分支不是 main、自动部署被关闭，或者 Hugging Face 少跑了“同步到 Space”的第二个工作流。

第 1 步：先确认 GitHub fork 真的更新了 ​

进入你自己的 fork 仓库：

text
https://github.com/你的GitHub用户名/danmu_api

确认这 2 件事：

  1. 仓库首页没有提示落后于上游，或者点过 Sync fork 后已经提示最新。
  2. Actions → Fork Sync 最近一次运行是绿色对勾。

如果 Fork Sync 还是红叉，先看：Fork Sync 自动同步突然失败。

第 2 步：去云平台看有没有新的部署记录 ​

Fork Sync 成功后，云平台应该出现一条新的部署 / 构建记录。先按你用的平台检查：

  • Vercel：进入项目 → Deployments，看最新记录是不是 Ready，并确认它对应的是 main 分支的新提交。
  • Netlify：进入项目 → Deploys，看有没有新的成功部署记录。
  • Cloudflare Workers：进入 Workers & Pages → 你的 Worker → Settings → Builds，确认 Git Repository 是你自己的 danmu_api fork，然后看部署记录。
  • EdgeOne Pages：进入 Pages 项目，查看最近一次部署 / 构建记录是否成功。
  • Hugging Face Space：只跑 Fork Sync 不够，还要跑 Sync to Hugging Face Space 工作流；同步成功后 Space 才会重新构建。

如果 GitHub 已经同步成功，但云平台没有出现新的部署记录，基本就是 GitHub 绑定或自动部署链路出了问题，继续看下一步。

第 3 步：检查是不是云平台“掉绑定”或没权限了 ​

云平台通常通过 GitHub App / OAuth 读取你的仓库。如果之前授权过，但后来改过 GitHub 权限、换过账号、删过 App、只授权了部分仓库，就可能出现：GitHub 同步成功，但平台完全没收到新提交。

按平台处理：

  1. Vercel

    • 进入 Vercel 项目 → Settings → Git
    • 确认连接的是 你的GitHub用户名/danmu_api
    • 确认 Production Branch 是 main
    • 如果仓库不对，重新连接自己的 fork
    • 如果没有自动部署，去 Deployments 手动重新部署一次

  2. Netlify

    • 进入项目 → Project configuration → Build & deploy → Continuous deployment → Repository
    • 确认已经 Link 到你自己的 danmu_api fork
    • 如果仓库不对，点 Manage repository，重新 Link
    • 如果 GitHub 授权不完整，去 GitHub 的 Installed GitHub Apps 里给 Netlify App 补上 danmu_api 仓库权限

  3. Cloudflare Workers

    • 进入 Workers & Pages → 你的 Worker → Settings → Builds
    • 确认 Git Repository 是你自己的 fork，不是上游仓库，也不是别的仓库
    • 如果仓库不对，重新连接 / 重新部署自己的 fork
    • 如果自动构建被关了，重新打开对应的自动部署设置

  4. EdgeOne Pages

    • 进入 EdgeOne Pages 项目，确认项目绑定的是你自己的 GitHub fork
    • 确认生产分支是 main
    • 如果没有新的部署记录，优先重新授权 GitHub 或重新导入自己的 fork
    • 重新部署后，再打开当前项目的 Pages 地址测试

  5. Hugging Face Space

    • GitHub 的 Fork Sync 只负责更新你的 GitHub fork
    • 还需要进入 GitHub → Actions → Sync to Hugging Face Space，手动运行一次
    • 同时确认仓库里已经配置：
      text
      ENABLE_HF_SYNC=true
HF_USERNAME=你的 Hugging Face 用户名
HF_SPACE_NAME=你的 Space 名称
    • Secrets 里还要有：
      text
      HF_TOKEN=你的 Hugging Face Token
    • 这个工作流成功后，再回 Hugging Face Space 等状态重新变成 Running

第 4 步：如果云平台部署成功，但页面还是旧版本 ​

这种情况再检查下面几项：

  1. 访问的是旧地址：回云平台项目首页复制当前项目的最新地址；如果绑定过自定义域名，确认域名还指向当前项目，不是旧项目。
  2. 看的是旧部署 / 旧 Preview：Vercel、Netlify 这类平台会保留很多历史部署地址，一定要打开 Production / 当前主域名，不要打开以前保存的 Preview 链接。
  3. 浏览器或 CDN 缓存：电脑端按 Ctrl + F5 强制刷新；手机端换无痕窗口或换浏览器测试；如果用了自定义 CDN，先清一次 CDN 缓存。
  4. 平台部署的提交不是最新提交：在云平台部署详情里看 commit 信息。如果部署详情里的提交还是旧的，说明平台没有拉到 GitHub 最新代码，回到第 3 步检查绑定和权限。
  5. 上游这次没有改版本号：有时上游修了功能，但没有更新显示用的版本号。功能可能已经是新的，只是页面显示的版本号没变，可以用部署记录里的 commit 时间 / commit SHA 判断是否真的部署了新代码。

第 5 步：还是不行时，复制这 3 个信息来排查 ​

如果按上面处理后还是旧版本，请提供：

  1. GitHub Fork Sync 最新一次运行截图
  2. 云平台最新部署记录截图
  3. 云平台部署详情里的 commit 信息，尤其是分支和 commit SHA

只要 GitHub 最新提交和云平台最新部署提交对不上，就说明问题在“云平台没有重新部署”；如果两个提交已经对上，但页面还旧，才继续排查缓存、域名或版本号本身没更新。

功能相关 ​

12. 部署后播放器加载不出来弹幕 ​

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

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

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

自动匹配成功

自动匹配能看到弹幕统计和弹幕列表，说明文件名匹配这条线可用。

手动匹配成功

手动匹配也能看到弹幕统计和弹幕列表，说明服务本身能拿到弹幕。

  • 如果两步都拿不到弹幕，问题先不在播放器，先按自检页里的提示处理服务地址、TOKEN、平台域名或缓存配置
  • 如果自检页能拿到弹幕，但播放器里没有，继续下面几项

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

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

正确示例：

text
https://你的域名

如果配置了自己的 TOKEN：

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

FongMi 影视的弹幕接口要在基础地址后面加 /danmaku：

text
https://你的域名/danmaku

如果改过 TOKEN，FongMi 填：

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

不要填：

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

也不要填管理员地址（ADMIN_TOKEN）。

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

如果是 Vercel 部署，vercel.app 默认域名在国内可能访问不稳定。建议绑定自定义域名或迁移到 Docker 部署。

第 4 步：EdgeOne Pages 优先补 Upstash ​

如果是 EdgeOne Pages 部署，先确认已经配置 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN，并在改完变量后重新部署。不配置 Upstash 时，接口通常会直接 404。

详见 缓存配置。

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

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

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

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

13. 自动匹配有点慢，怎么提升匹配速度 ​

直接处理：先减少 SOURCE_ORDER 里的来源数量，优先保留你常看的官方源；如果官方源在当前部署平台上超时、无返回或弹幕获取失败，再加 360、vod、douban 这类兜底源。

为什么会慢 ​

自动匹配会同时请求多个来源。源越多，请求越多；其中某个源网络慢、超时、被云平台出口 IP 限制，就可能拖慢整体等待时间。

常见情况：

  1. 官方源在国外 IP 下不稳定：Vercel、Netlify、EdgeOne、Hugging Face 这类云平台的出口 IP 通常在国外，请求爱奇艺、腾讯视频、优酷、芒果 TV、哔哩哔哩等官方源时，可能遇到地区限制、风控限制、超时、无返回或弹幕获取失败。
  2. 源配得太多：为了“尽量搜全”把很多源都放进 SOURCE_ORDER，自动匹配时就会等待更多请求。
  3. 某个源单独拖慢整体：只要其中一个源一直等到超时，整体自动匹配就会显得很慢。
  4. 兜底源链路更长：360、vod、douban 这类聚合 / 元数据 / 采集来源覆盖面广，适合作为官方源失败时的兜底，但中间链路更多，不建议一开始全部堆上。

第 1 步：进入源配置并编辑 SOURCE_ORDER ​

打开后台：

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

进入 系统配置 → 源配置，找到 SOURCE_ORDER，点右侧 编辑。

进入源配置并编辑 SOURCE_ORDER

进入系统配置里的源配置，找到 SOURCE_ORDER 后点右侧 编辑。

第 2 步：只保留需要的源 ​

在弹窗里删掉暂时不用、经常超时或当前网络不稳定的源。调整完成后点 保存。

调整 SOURCE_ORDER 后保存

删掉不需要的源，保留常用源后点 保存。

可以先从 2～3 个官方源开始测试，例如只保留自己常看的平台。后台里常见名称是：腾讯视频 tencent、优酷 youku、爱奇艺 iqiyi、芒果 TV imgo、哔哩哔哩 bilibili。

text
tencent,youku,iqiyi

或者：

text
imgo,bilibili

如果这些官方源在你的云平台上经常超时、无返回或弹幕获取失败，再按需加一个兜底源，例如：

text
tencent,iqiyi,360

或者：

text
bilibili,vod,douban

如果某个源一加进去就明显变慢，先去掉它；如果只是偶尔官方源失败，可以保留 1 个兜底源，不建议把所有源都放进来。

第 3 步：按部署方式确认是否需要重新部署 ​

  • Docker / Node.js / Termux：保存后通常会热更新，直接重新测试自动匹配。
  • Vercel / Netlify / EdgeOne：如果页面提示需要重新部署，点顶部 重新部署，等部署成功后再测试。
  • Hugging Face Space：保存变量后通常会自动重建，等 Space 回到 Running 再测试。

注意事项 ​

  1. 想要速度快：源越少越快，优先只保留常看的官方源。
  2. 想要结果全：源多一些更容易搜到，但自动匹配可能变慢。
  3. 官方源失败时再加兜底源：云平台国外 IP 访问爱奇艺、腾讯视频、优酷、芒果 TV、哔哩哔哩等官方源可能不稳定；如果出现超时、无返回或弹幕获取失败，再加 360、vod、douban 这类兜底源。
  4. 不要盲目堆满所有源：兜底源能提高搜到结果的概率，但也可能拉长等待时间。一般保留 1 个兜底源即可，确认需要再继续增加。
  5. 优先解决网络问题：如果你确定只需要某个官方源，但它在当前平台一直超时，换部署地区、加代理或改用 Docker 部署，通常比继续堆更多源更有效。

14. 搜索不到动漫 ​

排查步骤：

  1. 测试 API 是否正常：

    bash
    curl http://你的域名:9321/api/v2/search/anime?keyword=海贼王

  2. 查看日志：

    bash
    # Docker Compose 部署
docker compose logs danmu-api --tail 50

# API 日志接口
curl http://你的域名:9321/api/logs

  3. 检查源配置：

    bash
    # 默认源：douban,360,renren,hanjutv
# 如果常看的平台搜不到，再按需添加 bilibili、tencent、youku、iqiyi、imgo、vod 等
SOURCE_ORDER=douban,360,renren,hanjutv,bilibili,tencent

  4. 检查 Cookie（Bilibili 建议配置）：

    bash
    BILIBILI_COOKIE=你的B站Cookie

    不填 Cookie 也可能搜得到一部分结果；配置 Cookie 主要是提升稳定性、完整性，以及处理登录态、港澳台番剧等场景。

15. 某个剧别人能搜到，我搜不到 ​

如果用的是官方源，先考虑 IP 区域限制，不是接口一定坏了。部分平台会限制国外 IP，导致同一个剧名别人能搜到，你的部署环境搜不到。

常见情况：

  1. 芒果 TV：一些新剧对国外 IP 有限制。
  2. Bilibili：大部分番剧在国外 IP 下搜不到或结果不完整。
  3. 韩小圈 / 韩剧 TV：国外 IP 访问韩小圈链路时可能搜不到，只能用韩剧 TV 极速版链路兜底；国内、海外、挂不挂代理，查到的结果可能不一样。
  4. 爱奇艺：国外 IP 也可能被封锁或返回空结果。

解决办法：先用默认兜底顺序测试；如果还是搜不到，再按需加入 vod 或对应官方源。当前默认顺序是：

bash
SOURCE_ORDER=douban,360,renren,hanjutv

如果主要是官方源区域限制，可以加 vod 做采集站兜底，或把常看的官方源放在前面，例如：

bash
SOURCE_ORDER=douban,360,vod,renren,hanjutv,bilibili,tencent

改完后按部署方式保存生效；云平台需要重新部署或重建。这样很多因为官方源区域限制搜不到的剧，可以通过 douban / 360 / vod 这类兜底来源找到。若主要是 hanjutv 不稳定，可以先把它在 SOURCE_ORDER 里往后放，或临时移除后再测。

16. 多季匹配总是错 / 标题映射不生效 ​

多季剧、别名剧、繁体标题容易出现“搜得到但匹配到第一季 / 匹配到别的剧”的情况。

处理顺序：

  1. 打开 STRICT_TITLE_MATCH，减少“标题里包含关键字就命中”的误匹配。
  2. 片名有别名时，用 TITLE_MAPPING_TABLE 写 原始标题->映射标题，例如 唐朝诡事录->唐朝诡事录之西行。
  3. 原片名是繁体时，打开 ANIME_TITLE_SIMPLIFIED=true。
  4. 搜出来总是预告、花絮、合集时，先打开 ENABLE_ANIME_EPISODE_FILTER；如果是剧名本身带预告、花絮等关键词，再配合 ANIME_TITLE_FILTER。

17. 弹幕与视频不同步 ​

使用 DANMU_OFFSET 环境变量配置时间偏移：

bash
# 格式：剧名:秒数（全剧偏移）
DANMU_OFFSET=海贼王:10

# 格式：剧名/季:秒数（整季偏移）
DANMU_OFFSET=海贼王/S01:15

# 格式：剧名/季/集:秒数（单集偏移）
DANMU_OFFSET=海贼王/S01/E05:20

# 多条偏移（逗号分隔）
DANMU_OFFSET=海贼王:10, 火影/S01:15, 死神/S01/E01:20

# 正数：弹幕延后（向右）
# 负数：弹幕提前（向左）

百分比模式（整集快慢不一致）：

bash
# 格式：剧名@来源%:偏移秒数
DANMU_OFFSET=海贼王@bilibili%:10

# 计算公式：新时间 = 原时间 * (视频时长 + 偏移秒数) / 视频时长

这里冒号后面仍然填“秒数”，不是填 10% 这种百分比。比如 :10 表示按“视频总时长多 10 秒”的比例整体缩放弹幕时间。

18. Bilibili 弹幕获取失败、总是预告或港澳台搜不到 ​

B 站相关问题通常分三类处理。

  1. B 站弹幕少或获取失败：B 站源建议配置 Cookie，不填也可能搜到一部分结果，但稳定性和完整性会差一些。

    • 优先按 浏览器获取 Cookie 在后台扫码获取
    • 扫码失败时，再手动复制 SESSDATA 和 bili_jct
    • 配置 BILIBILI_COOKIE=SESSDATA=xxx; bili_jct=xxx
    • 如果主要处理港澳台番剧，Cookie 里最好带可用的登录态字段；有 access_key 时也可以一起保留

  2. 总是搜到预告、特辑、花絮：先看 ENABLE_ANIME_EPISODE_FILTER 和 ANIME_TITLE_FILTER，过滤掉非正片结果。

  3. 港澳台番剧搜不到或结果不完整：先检查 PROXY_URL 里有没有给 bilibili 单独配反代，例如 bilibili@https://你的反代地址；再补 BILIBILI_COOKIE 提升登录态和搜索稳定性。

Cookie 是敏感信息，截图或发给别人前一定要遮挡。

19. VOD 服务器无法使用或只返回一个站点 ​

如果搜索结果中没有 VOD 数据，先检查默认服务器或自定义 VOD_SERVERS 是否可用。默认 VOD 服务器不止一个，常见有 金蝉、789、听风 等；也可以只保留你确认稳定的站点。

bash
# 粗略检查资源站搜索接口是否可用
curl 'https://zy.jinchancaiji.com/api.php/provide/vod/?ac=detail&wd=海贼王&pg=1'

自定义 VOD 服务器格式：

bash
VOD_SERVERS=我的站点@https://my-site.com

如果配置了多个 VOD 站点，但结果里只返回一个，通常是 VOD_RETURN_MODE=fastest 的正常表现。它只返回第一个成功响应的站点。想返回所有站点结果，就改成：

bash
VOD_RETURN_MODE=all

如果某个站点慢或挂了，先从 VOD_SERVERS 里删掉，或者调整 VOD_REQUEST_TIMEOUT。

20. Renren 源搜得到但取不到 ​

renren 有时能搜到条目，但取弹幕会失败，这通常是源侧变化或风控，不一定是部署错了。

处理顺序：

  1. 先换别的稳定源测试，确认服务本身能正常返回弹幕。
  2. 如果只有少数标题失败，通常是源侧数据或接口问题。
  3. 如果很多标题都失败，先清缓存再测，避免旧结果干扰判断。
  4. 长期不稳定时，把 renren 在 SOURCE_ORDER 里往后放，或临时移除。

高级配置 ​

21. TOKEN 和 ADMIN_TOKEN 怎么区分 ​

TOKEN 是普通 API 口令，播放器、Emby 插件、影视壳都走它。ADMIN_TOKEN 是后台管理口令，只用于 https://你的域名/你的ADMIN_TOKEN。

如果看到 401 Unauthorized，先检查是不是把两个 token 用反了，或者云平台变量还没生效。改完后重新部署或重启，再回到 部署后自检 复测。

22. 429 / Too many requests 怎么处理 ​

429 一般是同一 IP 请求太快触发了限流。默认同一个 IP 1 分钟最多 3 次请求。

这个限制主要针对弹幕获取接口。搜索接口、后台配置接口不按这个规则限流；如果弹幕已经命中缓存，也不会重复计入限流。

处理方法：

  1. 先停几秒再试。
  2. 如果是脚本轮询，先降频。
  3. 想放宽就把 RATE_LIMIT_MAX_REQUESTS 调大；设成 0 表示不限流。

23. AI 匹配不生效 ​

配置了 AI 相关变量，但自动匹配仍使用传统算法。先确认 AI_API_KEY 已配置，并且 AI 连接验证能通过。AI_BASE_URL 和 AI_MODEL 有默认值，使用 OpenAI 官方接口时可以不改；使用第三方 OpenAI 兼容接口时再改成对应地址和模型。

检查必要变量：

bash
AI_API_KEY=你的 API Key  # 必填
AI_BASE_URL=https://api.openai.com/v1  # 可选，默认就是这个
AI_MODEL=gpt-4o  # 可选，默认就是这个

验证 AI 连接：

bash
curl -X POST http://你的域名:9321/api/ai/verify \
  -H "Content-Type: application/json" \
  -d '{"aiBaseUrl":"https://api.openai.com/v1","aiModel":"gpt-4o","aiApiKey":"你的 API Key"}'

支持 OpenAI 兼容接口（如部分国产大模型、代理网关等）。验证失败时，服务会继续使用传统匹配，不会因为 AI 不通就完全不能匹配。

24. Redis 缓存 / 手动选择记忆未生效 ​

如果日志中没有 Redis 相关信息，或者手动选过的弹幕下次又没记住，先检查 Redis 变量。

云平台优先用 Upstash：

bash
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io  # 不含 /set 或 /get 后缀
UPSTASH_REDIS_REST_TOKEN=你的Token

本地 Redis（Node.js / Docker 部署专用）：

bash
LOCAL_REDIS_URL=redis://:password@127.0.0.1:6379/0

REMEMBER_LAST_SELECT=true 默认会记住上次手选结果；如果云平台冷启动后经常丢记忆，就补 Upstash。若不想让历史选择影响后续匹配，就把 REMEMBER_LAST_SELECT 关掉。

Docker / Node.js 部署时，如果已经挂载 ./.cache:/app/.cache，手动选择记忆也会保存在本地缓存里；想跨重启、跨实例更稳定，再考虑本地 Redis 或 Upstash。

EdgeOne 用户

EdgeOne Pages 必须配置 Upstash Redis；不配置时接口会 404。改完 Upstash 变量后，需要重新部署。

25. 环境变量热更新不生效 ​

修改了 .env 文件，但 API 返回的配置没有更新。

各部署方式的热更新支持：

部署方式热更新说明
Node.js 本地支持修改 .env 后自动检测
Docker Compose支持需挂载 ./config:/app/config 目录
云平台不支持本地 .env 热更新在平台环境变量或后台 UI 保存后，通常仍要重新部署 / 重建才会稳定生效

验证是否生效：

bash
curl http://你的域名:9321/api/config

如果是 Docker 部署，还要注意 Compose 里直接写的 environment: 变量优先级更高；这类变量不会因为改 config/.env 自动被覆盖。要么删掉 Compose 里的同名变量，要么改完 Compose 后重启容器。

网络问题 ​

26. 明明绑定了自定义域名，为什么还是无法直连 ​

绑定自定义域名只是在访问地址上换了一个名字，不等于这个域名一定能在当前网络里直连。

常见原因：

  1. 域名本身被墙或被污染：尤其是免费二级域名、三级域名、某些域名商提供的免费子域名，父域名被墙后，你绑定的子域名也会受影响。
  2. 仍然指向被限制的平台：比如自定义域名最后还是 CNAME 到某些默认平台域名，当前网络对这个平台链路不稳定。
  3. DNS 解析没生效或解析到了错误地址：不同运营商、不同地区看到的解析结果可能不一样。
  4. 只在自己设备缓存里异常：浏览器 DNS 缓存、运营商 DNS 缓存、代理规则都可能影响判断。

判断方法：

  1. 关掉代理，用手机流量和家里宽带分别打开自定义域名。
  2. 换一个公共 DNS 再试，比如 223.5.5.5、119.29.29.29。
  3. 用在线 DNS 检测工具看国内多地解析是否一致。
  4. 如果默认平台域名要挂梯，自定义域名也要挂梯，优先怀疑域名或解析链路仍然被限制。

解决步骤：

  1. 换一个不被墙的域名：优先使用自己购买的正式域名，不建议长期使用免费的二级、三级域名。
  2. 换 DNS 托管商后重新解析：例如把域名托管到 Cloudflare 或国内稳定 DNS，再重新添加 CNAME / A 记录。
  3. 确认平台里的自定义域名已生效：平台控制台要显示域名验证通过，证书也要正常。
  4. 等 DNS 缓存过期：刚改解析时，等 10 分钟到几小时再测。
  5. 如果换域名后仍不稳：考虑 Docker 部署到自己的服务器，再用自己的域名解析到服务器；没有服务器时再换 Vercel、Netlify 或 EdgeOne Pages。

简单判断：如果换成另一个干净域名后立刻能直连，原来的问题基本就是旧域名或它的父域名链路被墙 / 被污染。

27. 安卓 App 的局域网地址经常变 ​

这是路由器重新分配了手机的局域网 IP。比如今天是 192.168.1.23，明天可能变成 192.168.1.35，播放器或安卓 App 里填过的地址就会失效。

优先在路由器里给手机做 DHCP 地址保留。这样手机仍然自动联网，但每次都会拿到同一个 IP。

方法一：在路由器里固定手机 IP ​

  1. 让手机先连上家里的 Wi-Fi。
  2. 打开路由器管理页或路由器 App，找 DHCP、地址保留、静态地址分配、Address Reservation 这类入口。
  3. 选择这台手机，给它固定一个 IP，例如 192.168.1.50。
  4. 保存后，让手机断开 Wi-Fi 再重新连接。
  5. 以后安卓 App / 播放器里就固定填这个地址，例如：http://192.168.1.50:9321。

TP-Link Deco App 进入 Address Reservation

不同路由器入口名字不一样，常见位置是 DHCP、LAN、地址保留、静态地址分配。

TP-Link Deco App 点击添加 Address Reservation

进入地址保留后，点右上角添加。

TP-Link Deco App 从设备列表选择手机

能从在线设备里选手机就直接选；不能选时，手动填手机的 MAC 地址和想固定的 IP。

如果路由器按 MAC 地址保留后还是会变，去手机当前 Wi-Fi 的详情里，把隐私 / MAC 地址类型改成 使用设备 MAC。否则安卓可能每次用随机 MAC，路由器就认不出同一台手机。

方法二：在手机 Wi-Fi 里手动填静态 IP ​

没有路由器管理权限时，再用这个办法。

  1. 手机进入 设置 → WLAN / Wi-Fi。
  2. 点当前 Wi-Fi 的详情或修改网络。
  3. 打开 高级选项，把 IP 设置 从 DHCP 改成 静态。
  4. 按当前路由器网段填写：
    • IP 地址：选一个没被占用的地址，例如 192.168.1.50
    • 网关：通常是路由器地址，例如 192.168.1.1
    • 网络前缀长度：通常填 24
    • DNS：可填 223.5.5.5、119.29.29.29，也可以保留原来的 DNS
  5. 保存后，重新打开安卓 App / 播放器，把地址改成新的固定 IP。

Android 当前 Wi-Fi 的网络详情

进入当前 Wi-Fi 的网络详情，找到高级选项或 IP 设置。

Android Wi-Fi 静态 IP 设置页面

把 IP 设置改成静态后，IP、网关、前缀长度、DNS 要填完整。

不要随便把 IP 写成 192.168.1.1，这个通常是路由器自己用的地址。也不要和其它手机、电视、电脑重复。改完如果 Wi-Fi 上不了网，就改回 DHCP，再换一个没被占用的 IP。

参考来源：TP-Link Deco 地址保留说明、Google Nest DHCP IP reservation 说明、荣耀手机静态 IP 说明，以及 Android 静态 IP 设置截图资料。

28. 海外访问慢 ​

在海外访问国内源（B站、腾讯等）速度慢。

配置代理：

bash
# 专用反代（按平台）
PROXY_URL=bahamut@https://proxy.example.com, bilibili@https://bili-proxy.com, animeko@https://animeko-proxy.com

# 万能反代（所有会走反代拼接的请求）
PROXY_URL=@https://universal-proxy.com

# 正向代理（Node.js / Docker 环境，服务会走 5321 代理端口）
PROXY_URL=http://127.0.0.1:1080

代理格式说明：

格式说明
平台@地址仅代理该平台的请求（如 bahamut、bilibili、tmdb、animeko）
@地址万能反代，会拼接所有通过反代函数处理的目标 URL，不等同于系统全局代理
地址（无@）正向代理（Node.js / Docker 环境；云平台不适用）

29. Docker 容器无法访问外网 ​

Docker 容器内请求外部 API 超时。

排查步骤：

  1. 测试容器网络：

    bash
    docker compose exec danmu-api curl -s https://httpbin.org/ip

  2. 使用 host 网络模式（在 docker-compose.yml 中添加）：

    yaml
    services:
  danmu-api:
    image: logvar/danmu-api:latest
    network_mode: host

  3. 配置 DNS（在 docker-compose.yml 中添加）：

    yaml
    services:
  danmu-api:
    image: logvar/danmu-api:latest
    dns:
      - 8.8.8.8
      - 8.8.4.4

如果只是某些国内 / 海外源访问慢或不通，不一定要改 Docker 网络。先按 海外访问慢 配 PROXY_URL，例如给 bilibili、bahamut、tmdb、animeko 单独配置反代，或在本地 Node.js / Docker 环境使用正向代理。

数据相关 ​

30. 我获取的弹幕比别人或者官方平台少 ​

这种情况通常不是播放器问题，而是 数据源返回的弹幕本来就少。

常见原因有两个：

  1. 部分源更新慢：尤其是 360、vod 这类聚合源 / 采集站，更新速度可能落后官方源。新剧、新集刚上线时，采集站能搜到片名，但弹幕数量可能暂时比官方平台少。
  2. 韩剧 TV 的链路兜底问题：韩剧 TV 相关来源通常有两条接口链路：韩小圈链路和极速版链路。网络能同时访问两条链路时，通常可以拿到合并后的弹幕；如果当前部署 IP 请求韩小圈接口返回空，就只能兜底到韩剧 TV 极速版，弹幕数量会少一些。

如果是新剧或刚更新的集数，可以过一段时间再试；如果部署在国外服务器，并且主要看韩剧，弹幕比别人少时优先考虑这个 IP 区域限制原因。

31. 弹幕数量过少/过多 ​

获取的弹幕数量不符合预期。

bash
# 默认不限制弹幕数量
DANMU_LIMIT=0

# 限制最大弹幕数量（等间隔采样，单位是 k，即千）
# 例如 3 表示弹幕超过约 3000 条时，采样到约 3000 条
DANMU_LIMIT=3

32. 弹幕颜色/样式异常 ​

播放器不支持顶部/底部弹幕或彩色弹幕。

bash
# 将顶部和底部弹幕转换为浮动弹幕
CONVERT_TOP_BOTTOM_TO_SCROLL=true

# 转换弹幕颜色为白色
CONVERT_COLOR=white

# 转换为彩色（使用默认颜色池）
CONVERT_COLOR=color

# 自定义颜色池（十进制颜色值）
COLOR_POOL=16777215,16711680,65280,255

33. API 响应慢 ​

搜索或获取弹幕时响应时间长。

优化方案：

  1. 启用缓存：

    bash
    SEARCH_CACHE_MINUTES=3  # 搜索缓存3分钟
COMMENT_CACHE_MINUTES=3  # 弹幕缓存3分钟

  2. 启用 Redis 或挂载 .cache：Redis 和本地 .cache 更适合保存全局状态、手动选择记忆和请求记录；短时间内的搜索缓存、弹幕缓存主要还是当前实例内存缓存。云平台冷启动频繁时，优先补 Upstash Redis。

  3. 减少源数量：

    bash
    # 只启用常用源
SOURCE_ORDER=bilibili,tencent

获取帮助 ​

如果以上问题都无法解决：

  1. 查看日志：curl http://你的域名:9321/api/logs
  2. 提交 Issue：https://github.com/huangxd-/danmu_api/issues
  3. Telegram 群组：https://t.me/logvar_danmu_group
  4. 私信机器人：https://t.me/ddjdd_bot

最后更新:

本项目仅供个人学习与交流，请勿在国内媒体平台宣传。

Copyright © LogVar Danmu API contributors