常见问题
忘记密码怎么办？
如果您忘记了管理员密码，可以通过以下步骤在服务器上重置：
通过 SSH 或其他方式登录到您的服务器
进入您存放
docker-compose.yml的目录执行以下命令来重置指定用户的密码。请将
<username>替换为您要重置密码的用户名（例如admin）使用 Docker 命令：
bashdocker exec <您的容器名称> python -m src.reset_password <username>💡 提示：如果不确定容器名称，可以先运行
docker ps查看正在运行的容器列表。命令执行后，终端会输出一个新的随机密码。请立即使用此密码登录，并在 Web UI 右上角头像处点击"修改密码"更改为您自己的密码
或者进入容器后直接使用 Python 命令：
python -m src.reset_password <username>注意：此命令需要在项目根目录下执行，如果使用了虚拟环境需要先激活。
弹幕库搜索不到内容怎么办？
如果您在弹幕库中搜索不到内容，可能有以下两种情况：
情况一：没有弹幕源
从 v2.1.0 至 v2.1.6 版本，系统没有内置弹幕源，需要您手动添加。如果没有安装任何弹幕源，搜索结果将为空。
解决方案：
- 登录 Web UI → "源管理" → "资源仓库"
- 从资源仓库中安装弹幕源
- 或者上传离线弹幕源包
详细操作请参考：弹幕源管理
情况二：国外VPS的IP地区限制
如果您在国外VPS上部署本项目，可能会遇到搜索不到弹幕或搜索结果很少的问题。
部分弹幕源（如B站、爱奇艺、腾讯视频等）的搜索接口存在IP地区限制，出于版权保护考虑，这些接口可能只对大陆IP开放完整的搜索结果。
解决方案：VPS回家
为了获得完整的搜索体验，建议使用"VPS回家"的方案，即让您的国外VPS通过国内网络进行弹幕搜索。
推荐方案：
- 使用国内中转服务器或代理
- 配置网络路由，让弹幕搜索请求通过国内IP发出
- 使用VPN或隧道技术将流量回传到国内
详细教程： 群友 @wdnmlgbd 提供了完整的解决方案：
数据库文件越来越大怎么办？
随着时间的推移，数据库占用的磁盘空间可能会逐渐增大。这通常由两个原因造成：
- 应用日志: 任务历史、API访问记录等会存储在数据库中。这些日志会由内置的 "数据库维护" 定时任务自动清理（默认保留最近3天）。
- MySQL二进制日志 (Binlog): 这是MySQL用于数据恢复和主从复制的日志，如果不进行管理，它会持续增长。
本项目内置的"数据库维护"任务会尝试自动清理旧的Binlog文件。但由于权限问题，您可能会在日志中看到"Binlog 清理失败"的警告。这是一个正常且可安全忽略的现象。
更多优化建议请参考：MySQL 内存优化
对于PostgreSQL用户: PostgreSQL没有Binlog机制，其WAL日志通常会自动管理，因此空间占用问题没有MySQL那么突出。您只需关注应用日志的自动清理即可。
如何配置 TMDB/TVDB API Key?
TMDB 和 TVDB 是重要的元数据源,用于获取影视作品的详细信息。
快速配置
获取 TMDB API Key:
- 访问 TMDB 官网 注册账号
- 进入 Settings → API → Request an API Key
- 选择 "Developer" 类型并填写申请表单
- 复制 "API Key (v3 auth)"
获取 TVDB API Key:
- 访问 TVDB 官网 注册账号
- 进入 Dashboard → API Keys → Create API Key
- 复制生成的 API Key
在系统中配置:
- 登录 Web UI → "设置" → "搜索源"
- 填写对应的 API Key
- 保存配置
详细教程: 请参考 元数据源配置指南
AI 功能无法使用怎么办?
如果您遇到 AI 功能无法使用的问题,请按以下步骤排查:
1. 检查 AI 配置
- 登录 Web UI → "设置" → "AI 自动匹配"
- 确认已选择 AI 提供商
- 确认已填写正确的 API Key
- 点击 "测试 AI 连接" 验证配置
2. 检查网络连接
- 国外 AI 服务 (OpenAI, Gemini): 需要确保网络能访问对应服务
- 如果在国内,可能需要配置代理
- 在 "设置" → "网络" 中配置全局代理
- 国内 AI 服务 (DeepSeek, SiliconFlow): 通常无需代理
3. 检查 API Key 是否有效
- 访问对应 AI 提供商的官网
- 检查 API Key 是否过期
- 检查账户余额是否充足(DeepSeek, SiliconFlow 支持余额查询)
4. 查看系统日志
- 在 Web UI 中查看 "任务" 页面的日志
- 或使用
docker logs misaka-danmu-server查看容器日志 - 查找 AI 相关的错误信息
5. 常见错误
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
API key is invalid | API Key 错误 | 检查 API Key 是否正确,没有多余空格 |
Connection timeout | 网络无法访问 | 配置代理或更换 AI 提供商 |
Insufficient balance | 余额不足 | 充值账户余额 |
Model not found | 模型名称错误 | 检查模型名称是否正确 |
详细教程: 请参考 AI 功能配置指南
如何启用播放器自动搜索并下载弹幕功能?
如果您希望在播放器中直接搜索弹幕或让系统自动下载弹幕，而不是每次都要在 Web UI 中手动搜索和导入，您需要启用后备系列开关。
什么是后备功能？
后备功能允许系统在本地没有弹幕时，自动从配置的弹幕源搜索和下载弹幕，实现无感知的弹幕获取体验。
需要开启哪些功能？
根据您的使用场景，可以选择以下一种或两种功能：
1. 匹配后备
适用场景：希望播放器自动匹配并下载弹幕，无需手动操作
功能说明：
- 播放器使用文件名自动匹配时，如果本地没有弹幕，系统会自动从弹幕源搜索并导入
- 配合媒体服务器（如 Emby/Jellyfin/Plex）的 Webhook，可实现新媒体入库自动获取弹幕
- 完全自动化，无需用户干预
如何开启：
- 登录 Web UI → "弹幕" → "高级设置"
- 找到 "匹配后备" 配置项
- 勾选 "启用匹配后备"
- 保存配置
详细说明：请参考 弹幕API功能配置 - 匹配后备
2. 后备搜索（推荐）
适用场景：希望在播放器中直接搜索弹幕，返回搜索结果供您选择
功能说明：
- 在播放器的搜索界面输入关键词时，如果本地没有结果，系统会自动从弹幕源搜索
- 返回多个搜索结果，您可以选择最合适的
- 作为匹配后备的补充方案
如何开启：
- 登录 Web UI → "弹幕" → "高级设置"
- 找到 "后备搜索" 配置项
- 勾选 "启用后备搜索"
- 保存配置
详细说明：请参考 弹幕API功能配置 - 后备搜索
增强功能（可选）
开启匹配后备或后备搜索后，您还可以启用以下增强功能：
顺延机制
功能：当选中的弹幕源没有有效分集时，自动尝试下一个候选源，提高导入成功率
开启方式：在 "高级设置" 中勾选 "启用顺延机制"
详细说明：请参考 弹幕API功能配置 - 顺延机制
预下载
功能：播放当前集时，自动在后台下载下一集的弹幕，实现无缝播放体验
开启方式：在 "高级设置" 中勾选 "启用预下载"
详细说明：请参考 弹幕API功能配置 - 预下载
💡 推荐配置
完全自动化体验：
- ✅ 启用匹配后备
- ✅ 启用顺延机制
- ✅ 启用预下载
- ✅ 配合 Webhook 实现新媒体入库自动获取弹幕
手动控制 + 播放器搜索：
- ✅ 启用后备搜索
- ✅ 启用预下载机制
PS：这种功能组合能够在首次搜索第一集之后自动下载后续的集弹幕，更加准确的获取弹幕并且从第二集开始没有等待时间
相关配置
- 弹幕API功能配置 - 高级设置 - 查看所有后备功能的详细说明
- Webhook 配置 - 配置媒体入库自动触发
- 弹幕源管理 - 配置和管理弹幕源
如何自定义弹幕文件存储路径?
默认情况下,弹幕文件存储在 /app/config/danmaku 目录下。如果您想自定义存储路径:
方式 1: Web UI 配置 (推荐)
- 登录 Web UI → "设置" → "弹幕文件路径"
- 启用 "自定义弹幕文件保存路径"
- 配置电影和电视节目的存储路径
- 配置文件命名模板(支持变量:
${title},${season},${episode}等) - 保存配置
方式 2: Docker 挂载
如果您想将弹幕文件存储到宿主机的其他位置:
volumes:
- ./config:/app/config
- /path/to/your/danmaku:/app/config/danmaku # 挂载自定义路径然后在 Web UI 中配置路径为 /app/config/danmaku/...
注意: 确保挂载的目录有正确的读写权限(PUID/PGID 配置)。