御坂网络弹幕服务

外观

🎬 弹幕API功能配置指南 ​

本文档详细介绍 Web UI 中"弹幕"页面下的所有功能模块和配置项。

Anime 接口 ​

接口说明 ​

本服务兼容 dandanplay API 规范，提供以下核心接口：

接口说明
/api/v2/search/anime搜索动画作品
/api/v2/match匹配文件获取弹幕
/api/v2/comment/{episodeId}获取分集弹幕
/api/v2/related/{episodeId}获取相关弹幕
/api/v2/extcomment获取扩展弹幕

指令输入功能 ​

⚠️ 注意: 指令操作仅在 anime 接口 中支持。具体哪些播放器支持 anime 接口，请查看 客户端配置 - 支持的播放器 中的表格。

在搜索接口中支持特殊指令，用于执行特定操作：

指令输入

💡 提示: 所有指令均支持小写输入，例如 @qlhc 与 @QLHC 效果相同。

指令格式说明
@获取可用指令列表
@QLHC清理缓存
@SXDM刷新最近播放过的某集弹幕
@CXLK查询流控状态
@CXRW查询任务状态（支持按状态和队列筛选）

@ - 获取可用指令列表 ​

使用方式： 在搜索框中输入 @ 并执行，获取可用指令列表。

适用场景：

  • 获取当前可用的指令列表以及指令对应的说明

@QLHC - 清理缓存 ​

使用方式： 在搜索框中输入 @QLHC 并执行，即可清理系统缓存。

适用场景：

  • 缓存数据过多需要清理时
  • 系统响应变慢时
  • 需要刷新缓存数据时

@SXDM - 刷新弹幕 ​

交互流程：

@SXDM 指令支持三种使用方式，通过分步交互来精确选择要刷新的弹幕：

第一步：查看最近播放的番剧列表

在播放器搜索框中输入 @SXDM 并执行，显示最近播放的番剧列表（最多5部），每部番剧会分配一个标签（#A、#B、#C、#D、#E）。

刷新弹幕指令-1

第二步：查看指定番剧的分集列表

输入 @SXDM #A 查看标签为 A 的番剧的分集列表，可以看到每集的缓存状态和弹幕数量。

刷新弹幕指令-2

第三步：刷新指定集数的弹幕

输入 @SXDM #A1 直接刷新标签 A 番剧的第 1 集弹幕，系统会提交刷新任务。

刷新弹幕指令-3

参数格式：

指令格式说明
@SXDM查看最近播放的番剧列表
@SXDM #A查看标签 A 番剧的分集列表
@SXDM #A5刷新标签 A 番剧的第 5 集
@sxdm #a小写也可以

标签说明：

  • 标签范围：#A、#B、#C、#D、#E（对应最近播放的5部番剧）
  • 集数编号：从 1 开始，如 #A1 表示第 1 集，#A10 表示第 10 集

适用场景：

  • 弹幕源更新后需要重新获取弹幕
  • 之前获取的弹幕不完整或有误
  • 想要获取最新的弹幕数据

@CXLK - 查询流控状态 ​

使用方式： 在播放器搜索框中输入 @CXLK 并执行，即可查询当前的流控状态。

查询流控指令

适用场景：

  • 查看当前 API 调用频率限制状态
  • 检查是否触发了流控限制
  • 了解剩余的 API 调用配额

@CXRW - 查询任务状态 ​

使用方式： 在播放器搜索框中输入 @CXRW 并执行，即可查询后台任务状态。支持按状态和队列筛选。

查询进行中的任务

参数格式：

@CXRW [状态#] [#队列] [状态#队列]

状态标识（放在 # 前面）：

标识说明
a#全部任务
r#进行中（运行中/排队中/已暂停）
c#已完成
f#失败
p#排队中
s#已暂停

队列标识（放在 # 后面）：

标识说明
#d下载队列
#m管理队列
#b后备队列

使用示例：

指令说明
@CXRW查询所有任务
@cxrw r#查询进行中的任务
@CXRW c#查询已完成的任务
@cxrw f#查询失败的任务
@CXRW #d查询下载队列的任务
@cxrw #m查询管理队列的任务
@CXRW #b查询后备队列的任务
@cxrw r#d查询下载队列中进行中的任务
@CXRW c#m查询管理队列中已完成的任务

适用场景：

  • 查看后台正在执行的弹幕下载任务
  • 检查任务执行进度
  • 按状态或队列筛选特定任务
  • 了解系统当前的工作状态

Token管理 ​

功能说明: 管理API访问令牌,用于控制第三方应用对弹幕API的访问权限。

Token管理

创建Token ​

操作步骤:

  1. 打开 Web UI,进入 "弹幕" → "Token管理" 页面
  2. 点击 "创建Token" 按钮
  3. 填写Token信息:
    • Token名称: 用于识别Token的名称(如 "我的播放器")
    • 有效期: 选择Token的有效期(如 30天、90天、永久)
    • 每日调用限制: 设置每日最大调用次数(可选)
  4. 点击 "确认" 创建

Token格式: 系统自动生成20位随机字符串(包含大小写字母和数字)

管理Token ​

功能:

  • 查看Token列表: 显示所有已创建的Token及其状态
  • 复制Token: 点击复制按钮快速复制Token字符串
  • 删除Token: 删除不再使用的Token
  • 查看统计: 查看Token的调用次数和有效期

使用场景:

  • 为不同的播放器客户端分配独立Token
  • 为第三方应用提供API访问权限
  • 限制单个Token的调用频率

弹幕输出控制 ​

功能说明: 调整弹幕API的输出行为,优化客户端性能。

弹幕输出配置

弹幕输出上限 ​

配置项: 弹幕输出上限

说明: 设置弹幕API返回的弹幕最大数量。

配置值:

  • -1: 无限制,返回所有弹幕
  • 正整数: 限制返回的弹幕数量(建议 3000-5000)

工作原理:

  • 当弹幕总数超过限制时,系统会按时间段均匀采样
  • 确保弹幕在整个视频时长中分布均匀
  • 避免客户端因弹幕过多而卡顿

推荐配置:

  • 移动设备: 3000
  • 桌面设备: 5000
  • 高性能设备: 8000 或更高

随机弹幕颜色 ​

配置项: 启用随机弹幕颜色

说明: 开启后,系统会为弹幕随机分配颜色,让弹幕显示更加丰富多彩。

工作原理:

  • 对于原本没有颜色信息的弹幕,系统会随机分配一个颜色
  • 已有颜色的弹幕保持原有颜色不变
  • 颜色从预设的颜色池中随机选取

适用场景:

  • 希望弹幕显示更加多彩
  • 弹幕源提供的弹幕大多为白色,想要增加视觉效果

弹幕输出黑名单 ​

配置项: 弹幕输出黑名单

说明: 配置弹幕输出的黑名单规则,过滤不想显示的弹幕内容。

配置方式:

  • 支持关键词过滤: 包含指定关键词的弹幕将被过滤
  • 支持正则表达式: 使用正则表达式进行更精确的匹配

适用场景:

  • 过滤广告弹幕
  • 过滤剧透内容
  • 过滤不文明用语
  • 过滤特定格式的弹幕

弹幕存储配置 ​

功能说明: 自定义弹幕文件的存储路径和命名规则。

启用自定义路径 ​

配置项: 启用自定义弹幕路径

说明: 开启后,可以自定义弹幕文件的存储位置和命名模板。

电影弹幕配置 ​

配置项:

  • 电影弹幕目录路径: 电影弹幕的存储根目录
  • 电影弹幕文件名模板: 电影弹幕文件的命名规则

默认配置:

目录路径: /app/config/danmaku/movies
文件名模板: ${title}/${episodeId}

支持的变量:

变量说明
${title}原始标题
${titleBase}标准化标题（去除特殊字符）
${season}季数
${season:02d}季数（两位数格式，如 01、02）
${episode}集数
${episode:02d}集数（两位数格式，如 01、02）
${episode:03d}集数（三位数格式，如 001、002）
${year}上映年份
${provider}弹幕源提供商
${animeId}作品ID
${episodeId}分集ID
${sourceId}源ID

电视节目弹幕配置 ​

配置项:

  • 电视弹幕目录路径: 电视节目弹幕的存储根目录
  • 电视弹幕文件名模板: 电视节目弹幕文件的命名规则

默认配置:

目录路径: /app/config/danmaku/tv
文件名模板: ${animeId}/${episodeId}

高级设置 ​

匹配后备 ​

配置项: 启用匹配后备

功能说明: 当播放器使用 /match 接口请求弹幕时,如果本地没有匹配的弹幕,系统会自动从弹幕源搜索并导入。

工作原理:

  1. 播放器发送 /match 请求,包含文件名、文件Hash等信息
  2. 系统检查本地是否已有匹配的弹幕
  3. 如果没有,自动使用配置的弹幕源搜索
  4. 找到匹配后,自动导入弹幕并返回给播放器

适用场景:

  • 希望完全自动化获取弹幕
  • 不想手动在 Web UI 中搜索和导入
  • 配合 Webhook 实现新媒体入库自动获取弹幕

后备搜索 ​

配置项: 启用后备搜索

功能说明: 当播放器使用 /search/anime 接口搜索弹幕时,如果本地没有结果,系统会自动从弹幕源搜索并返回结果。

工作原理:

  1. 播放器发送 /search/anime 请求
  2. 系统先检查本地是否有匹配结果
  3. 如果没有,自动从配置的弹幕源搜索
  4. 返回搜索结果供用户选择

适用场景:

  • 希望在播放器中直接搜索弹幕
  • 作为匹配后备的补充方案

顺延机制 ​

配置项: 启用顺延机制

功能说明: 当选中的弹幕源没有有效分集时(如只有预告片被过滤掉),自动尝试下一个候选源,提高导入成功率。

工作原理:

  1. 系统从搜索结果中选择最佳匹配源
  2. 检查该源是否有有效分集(过滤预告片等无效内容)
  3. 如果没有有效分集,自动尝试下一个候选源
  4. 重复步骤2-3,直到找到有效源或尝试完所有候选源

适用场景:

  • 某些搜索源只有预告片或特典
  • 提高自动导入的成功率
  • 减少手动重试的次数

依赖条件:

  • 需要启用"匹配后备"或"后备搜索"
  • 如果两者都未启用,此选项将被禁用

预下载 ​

配置项: 启用预下载

功能说明: 当播放当前集时,系统会自动在后台下载下一集的弹幕(如果下一集存在且没有弹幕)。

工作原理:

  1. 播放器请求当前集的弹幕(如 S01E01)
  2. 系统检查下一集(S01E02)是否存在
  3. 如果下一集存在但没有弹幕,触发后台下载任务
  4. 下载完成后,用户播放下一集时弹幕已准备就绪

优势:

  • 提升观看体验: 播放下一集时弹幕已准备好
  • 减少等待时间: 无需等待弹幕下载
  • 无感知下载: 后台自动完成,不影响当前播放

依赖条件:

  • 需要启用"匹配后备"或"后备搜索"
  • 如果两者都未启用,此选项将被禁用

匹配后备Token授权 ​

功能说明: 为匹配后备功能配置专用的API Token,用于访问第三方弹幕源。

配置项:

  • Token列表: 添加多个Token,系统会自动轮换使用
  • Token状态: 显示每个Token的可用状态和剩余配额

使用场景:

  • 某些弹幕源需要API Token才能访问
  • 提高API调用限额(多个Token轮换使用)
  • 避免单个Token被限流

匹配后备黑名单 ​

功能说明: 配置匹配后备功能的黑名单,阻止特定作品或源被自动导入。

配置项:

  • 作品黑名单: 阻止特定作品的弹幕被自动导入
  • 源黑名单: 阻止特定弹幕源的内容被自动导入

使用场景:

  • 某些作品的弹幕质量差,不希望自动导入
  • 某些弹幕源经常匹配错误,需要屏蔽
  • 避免导入不需要的内容

常见问题 ​

Q: 匹配后备和后备搜索有什么区别? ​

A:

  • 匹配后备: 播放器使用 /match 接口时触发,自动匹配并导入弹幕
  • 后备搜索: 播放器使用 /search/anime 接口时触发,返回搜索结果供用户选择

Q: 为什么顺延机制和预下载被禁用? ​

A: 这两个功能依赖于"匹配后备"或"后备搜索"。如果两者都未启用,这两个功能将被禁用。

Q: 预下载会影响性能吗? ​

A: 不会。预下载是异步后台任务,不会阻塞当前播放或影响系统性能。

📚 相关文档 ​

基于 AGPL-3.0 许可发布

Copyright © 2025 - 御坂网络弹幕服务