跳转至

常见问题

使用 Danmu API 过程中遇到问题？这里汇总了最常见的疑问和解决方案。

问题目录

部署相关

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

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

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

Fork Sync 失败原因
简单理解：上游改了工作流 yml，自动同步想写入你的 fork，但默认令牌权限不够，所以被拦住。

处理办法：不要先去翻日志，也不要删项目。直接按下面步骤操作。

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

  1. 进入自己 fork 的 danmu_api 仓库首页
  2. 点顶部 Code
  3. 确认页面提示 This branch is ... behind huangxd-/danmu_api:main
  4. 点右侧 Sync fork
Code 页面和 Sync fork 按钮
按图里顺序点：先进 Code，看到落后提示后点右侧 Sync fork。

Tip

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

第 2 步：在弹窗里点 Update branch

  1. 确认弹窗里写的是从 upstream repository 同步提交
  2. 不用点 Compare
  3. 直接点绿色的 Update branch
Update branch 弹窗
这里点绿色的 Update branch，不要点左边的 Compare。

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

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

同步完成提示
看到这个绿色提示，就说明网页端同步已经完成。

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

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

  1. 进入 Actions → Fork Sync
  2. 点右侧 Run workflow
  3. 分支保持 main
  4. 点绿色的 Run workflow
  5. 等它跑完
Run workflow
手动跑一次是为了确认刚才的同步问题已经解决，不用等下一次定时任务。

第 5 步：看结果

如果新的 Fork Sync 记录变成绿色对勾，就说明自动同步恢复正常了。

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

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

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 里配置：

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

同时在 Secrets 里配置：

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. 端口被占用： 

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

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

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

    docker compose pull

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

    docker compose logs danmu-api --tail 50

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

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

解决方案：

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

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

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

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 里要有：

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

第 2 步：手动创建目录

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

mkdir -p config .cache

第 3 步：修正目录权限

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

chmod 755 config .cache

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

chmod -R 755 config .cache

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

第 4 步：复制示例配置

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

cp config/.env.example config/.env

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

第 5 步：重启容器

docker compose down
docker compose up -d

重启后再看：

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 里推荐这样写：

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，然后重新启动：

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

检查 Watchtower 是否在跑：

docker ps | grep watchtower

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

docker logs watchtower --tail 100

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

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

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

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

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

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

7. Netlify 免费版积分用完了

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

解决方案：

  1. 使用 UI 配置：配置 DEPLOY_PLATFORM 相关变量后，可在前端 UI 修改环境变量，无需重新部署
  2. 减少重新部署次数：配置好环境变量后一次性部署
  3. 迁移到其他平台：优先考虑 Docker 部署；没有服务器时再看 Vercel、Netlify 或 EdgeOne Pages

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 才能正常工作。

解决步骤：

  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. 重新部署

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

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

解决方案：

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

功能相关

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

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

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

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

自动匹配成功
自动匹配能看到弹幕统计和弹幕列表，说明文件名匹配这条线可用。
手动匹配成功
手动匹配也能看到弹幕统计和弹幕列表，说明服务本身能拿到弹幕。
  • 如果两步都拿不到弹幕，问题先不在播放器，先按自检页里的提示处理服务地址、TOKEN、平台域名或缓存配置
  • 如果自检页能拿到弹幕，但播放器里没有，继续下面几项

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

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

正确示例：

https://你的域名

如果配置了自己的 TOKEN：

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

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

https://你的域名/danmaku

如果改过 TOKEN，FongMi 填：

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

不要填：

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。

详见 缓存配置。

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

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

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

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

12. 搜索不到动漫

排查步骤：

  1. 测试 API 是否正常： 

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

  2. 查看日志： 

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

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

  3. 检查源配置： 

    # 默认源：360,vod,renren,hanjutv
# 可能需要添加 bilibili、tencent 等
SOURCE_ORDER=360,bilibili,vod,renren,hanjutv

  4. 检查 Cookie（Bilibili 需要）： 

    BILIBILI_COOKIE=你的B站Cookie

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

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

常见情况：

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

解决办法：在源配置里加入 360 和 vod 源，并尽量放在前面，让搜索先从聚合源和采集站兜底。例如直接使用默认兜底顺序：

SOURCE_ORDER=360,vod,renren,hanjutv

改完后重新部署或在系统配置里保存并重启。这样很多因为官方源区域限制搜不到的剧，可以通过 360 / vod 找到。若主要是 hanjutv 不稳定，可以先把它在 SOURCE_ORDER 里往后放，或临时移除后再测。

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

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

处理顺序：

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

15. 弹幕与视频不同步

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

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

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

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

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

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

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

# 格式：剧名@来源%:百分比
DANMU_OFFSET=海贼王@bilibili%:10

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

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

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

  1. 获取弹幕失败：B站 API 需要 Cookie 认证。
  2. 登录 B站网页版
  3. 打开浏览器开发者工具（F12）
  4. 复制 Cookie 中的 SESSDATA 和 bili_jct

  5. 配置 BILIBILI_COOKIE=SESSDATA=xxx; bili_jct=xxx

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

  7. 港澳台番剧搜不到或结果不完整：先补 BILIBILI_COOKIE，必要时再检查 PROXY_URL 里有没有给 bilibili 单独配反代。

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

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

如果搜索结果中没有 VOD 数据，先检查默认服务器或自定义 VOD_SERVERS 是否可用。

# 检查默认服务器是否可用
curl https://zy.jinchancaiji.com/api.php/provide/vod/?ac=list

自定义 VOD 服务器格式：

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

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

VOD_RETURN_MODE=all

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

18. Renren 源搜得到但取不到

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

处理顺序：

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

高级配置

19. TOKEN 和 ADMIN_TOKEN 怎么区分

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

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

20. 429 / Too many requests 怎么处理

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

处理方法：

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

21. AI 匹配不生效

配置了 AI 相关变量，但自动匹配仍使用传统算法。先确认这三项都已配置；只填其中一项不会启用 AI 匹配。

检查必要变量：

AI_BASE_URL=https://api.openai.com/v1  # 必须
AI_MODEL=gpt-4o  # 必须
AI_API_KEY=sk-xxx  # 必须

验证 AI 连接：

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

支持所有 OpenAI 兼容接口（如 Azure、国产大模型等）。

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

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

云平台优先用 Upstash：

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

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

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

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

EdgeOne 用户

EdgeOne Pages 必须配置 Upstash Redis，否则容易 404 或匹配不稳定。

23. 环境变量热更新不生效

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

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

部署方式 热更新 说明
Node.js 本地 支持 修改 .env 后自动检测
Docker Compose 支持 需挂载 ./config:/app/config 目录
云平台 不支持 需要重新部署或使用 UI 配置

验证是否生效：

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

网络问题

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

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

常见原因：

  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。

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

25. 安卓 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. 按当前路由器网段填写：
  5. IP 地址：选一个没被占用的地址，例如 192.168.1.50
  6. 网关：通常是路由器地址，例如 192.168.1.1
  7. 网络前缀长度：通常填 24
  8. DNS：可填 223.5.5.5、119.29.29.29，也可以保留原来的 DNS
  9. 保存后，重新打开安卓 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 设置截图资料。

26. 海外访问慢

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

配置代理：

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

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

# 正向代理（本地Node.js专用，走5321端口）
PROXY_URL=http://127.0.0.1:1080

代理格式说明：

格式 说明
平台@地址 仅代理该平台的请求（如 bahamut、bilibili、tmdb）
@地址 代理所有请求
地址（无@） 正向代理（仅本地环境）

27. Docker 容器无法访问外网

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

排查步骤：

  1. 测试容器网络： 

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

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

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

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

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

数据相关

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

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

常见原因有两个：

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

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

29. 弹幕数量过少/过多

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

# 限制最大弹幕数量（等间隔采样，单位是 k，即千）
DANMU_LIMIT=3  # 默认约 3000 条

# 设置为 0 表示不限制
DANMU_LIMIT=0

30. 弹幕颜色/样式异常

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

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

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

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

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

31. API 响应慢

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

优化方案：

  1. 启用缓存： 

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

  2. 启用 Redis：使用 Redis 缓存可显著提升性能

  3. 减少源数量： 

    # 只启用常用源
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