⚙️ 设置

本页面介绍系统设置中的各项配置功能。

代理配置

功能说明

为需要访问外部网络的功能配置代理服务器。

配置项

配置项	说明
代理地址	代理服务器地址，如 http://127.0.0.1:7890
代理类型	HTTP / SOCKS5
代理用户名	可选，需要认证时填写
代理密码	可选，需要认证时填写

适用场景

• 访问 TMDB/TVDB 等国外元数据源
• 某些弹幕源需要代理才能访问
• 海外部署时访问国内弹幕源

---

安全设置

功能说明

配置系统的安全相关参数，包括 GitHub Token、访问控制、反向代理信任和会话管理。

GitHub Token 配置

作用：用于访问 GitHub API，主要用于弹幕源资源仓库的更新检查。

配置步骤：

1. 访问 GitHub Token 设置
2. 点击 "Generate new token (classic)"
3. 勾选 public_repo 权限
4. 生成并复制 Token
5. 在设置页面填入 Token

效果：

• 提高 GitHub API 调用限额（未认证：60次/小时 → 认证后：5000次/小时）
• 避免频繁请求被限制
• 确保弹幕源更新检查正常工作

访问IP白名单

功能说明：限制只有特定 IP 地址可以访问系统，增强安全性。

配置项：

配置项	说明
启用 IP 白名单	开启后，只有白名单中的 IP 才能访问系统
IP 地址列表	支持单个 IP 或 CIDR 格式的 IP 段

示例：

• 单个 IP：192.168.1.100
• IP 段：192.168.1.0/24（允许 192.168.1.1 - 192.168.1.254）
• 多个地址：每行一个，支持混合格式

适用场景：

• 仅允许内网访问
• 限制特定客户端访问
• 提高系统安全性

⚠️ 警告：配置错误可能导致自己无法访问系统，请谨慎设置！

受信任反代配置

功能说明：配置受信任的反向代理地址，用于正确识别客户端真实 IP。

为什么需要此配置？

当系统部署在反向代理（如 Nginx、Cloudflare）后面时，系统接收到的 IP 是代理服务器的 IP，而非用户真实 IP。通过配置受信任反代，系统会从 X-Forwarded-For 等 HTTP 头中提取用户真实 IP。

配置项：

配置项	说明
受信任反代 IP 列表	填写反向代理服务器的 IP 地址
X-Forwarded-For 解析	自动从 HTTP 头中提取真实 IP

适用场景：

• 使用 Nginx、Apache 等反向代理时
• 使用 Cloudflare CDN 时
• 需要准确记录用户 IP 用于访问控制时

登录令牌有效期

功能说明：设置用户登录 Token 的有效时长，平衡安全性和便利性。

配置项：

配置项	说明	建议值
Token 有效期	单位为秒	默认：2592000（30天）

常用值参考：

• 1 小时：3600
• 1 天：86400
• 7 天：604800
• 30 天：2592000
• 90 天：7776000

安全建议：

• 个人使用：可设置较长有效期（30-90天）
• 多人使用：建议设置较短有效期（1-7天）
• 公网暴露：建议设置较短有效期并启用 IP 白名单

登录失败锁定处理

v2.7.5 起新增登录暴力破解防护。同一真实客户端 IP 连续登录失败达到上限后，会被临时锁定。

相关配置项：

配置项	默认值	说明
loginMaxFailCount	3	登录失败次数上限。同一 IP 达到此次数后将被临时锁定，设为 0 可禁用暴力破解防护。
loginLockoutMinutes	60	登录锁定时长，单位为分钟。默认即失败 3 次后锁定 1 小时。

配置位置：

进入 Web UI 的 设置 → 参数配置 → 安全设置，调整上述配置项。

触发后的表现

当 IP 被锁定后，登录接口会返回锁定提示，前端会显示类似“登录失败次数过多，请稍后再试”的 429 提示。

• GET：查看当前被锁定的 IP、失败次数和已锁定时间
• DELETE 不带 ip：清除所有 IP 的登录锁定
• DELETE 带 ip：只清除指定 IP 的登录锁定

如果管理员自己也被锁定，可以在服务所在环境使用主项目提供的工具：

python -m src.reset_login_lockout
python -m src.reset_login_lockout --clear
python -m src.reset_login_lockout --clear --ip 192.168.1.100
python -m src.reset_login_lockout --host 127.0.0.1 --port 7768
python -m src.reset_login_lockout --token <JWT Token>

注意

reset_login_lockout.py 是通过 API 操作运行中的内存锁定记录，因此需要 Misaka 服务正在运行。

如果服务已经停止，直接重启服务即可清空当前登录锁定记录。

紧急重置 TOTP / PassKey

正常情况下，已登录用户可以在 Web UI 的 安全设置 中管理 MFA：

• 启用或关闭 TOTP 两步验证
• 注册、重命名或删除 PassKey
• 注册 PassKey 前需要先启用 TOTP
• 关闭 TOTP 时需要输入当前密码确认

如果因为 TOTP 验证器丢失、PassKey 不可用等原因导致无法登录，可以使用主项目提供的 src/reset_mfa.py 紧急重置工具。

重置指定用户的全部 MFA 配置：

python -m src.reset_mfa admin

这会同时清空：

• TOTP 两步验证配置
• 该用户已注册的所有 PassKey

仅重置 TOTP：

python -m src.reset_mfa admin --totp

仅重置 PassKey：

python -m src.reset_mfa admin --passkey

其中 admin 请替换为实际用户名。重置完成后，该用户可以仅使用密码登录；登录后建议重新绑定 TOTP，再按需注册 PassKey。

Docker 部署时，可以进入容器后执行，也可以直接在容器内运行命令，例如：

docker exec -it misaka_danmu_server python -m src.reset_mfa admin

v2.7.5 MFA 安全增强

v2.7.5 起，TOTP 的 OTP Secret 改为加密存储；PassKey challenge 改为随机 sessionId，避免并发登录或注册时相互覆盖。

访问控制、反代与登录锁定的区别

如果无法访问或无法登录，请先区分下面三种机制：

机制	作用	典型问题
IP 白名单	控制哪些 IP 可以访问或自动登录	当前访问 IP 未加入白名单，导致无法通过白名单访问
受信任反代	决定是否从 X-Forwarded-For / X-Real-IP 识别真实客户端 IP	反代配置不正确时，所有用户可能都被识别为反代服务器 IP
登录失败锁定	同一真实 IP 登录失败过多后临时禁止继续登录	密码输错多次后被锁定，需要等待或由管理员清除

如果你在反向代理后部署，建议正确配置 trustedProxies。否则可能出现：

• 多个用户都被识别为同一个反代 IP
• 某个用户输错密码导致反代 IP 被锁定，影响其他用户登录
• IP 白名单判断不准确

说明：IP 白名单 和 登录失败锁定 是两种不同机制。前者是“允许谁访问”，后者是“同一 IP 失败太多后暂时禁止登录”。

---

识别词配置

功能说明

配置用于识别文件名中影视信息的关键词规则。

配置项

配置项	说明
标题识别规则	用于提取标题的正则表达式
季度识别规则	用于识别季数的规则
集数识别规则	用于识别集数的规则
年份识别规则	用于提取年份的规则

使用场景

• 自定义文件命名规范
• 处理特殊命名格式的文件
• 提高匹配准确率

---

会话管理

功能说明

管理当前登录的会话，查看和控制活跃的登录状态。

功能

功能	说明
查看会话列表	显示所有活跃的登录会话
会话信息	IP地址、设备类型、登录时间
强制下线	手动终止指定会话
清除所有会话	强制所有设备下线

安全建议

• 定期检查会话列表
• 发现异常登录及时强制下线
• 更换密码后建议清除所有会话

---

参数配置

界面配置

用于配置 Web UI 的界面行为和数据管理功能。

分页参数持久化

功能说明：保存页面的分页设置（如每页显示数量），下次访问时自动恢复。

配置项：

配置项	说明
启用分页参数持久化	开启后，系统会记住您在各个页面设置的每页显示数量

适用场景：

• 经常需要查看大量数据时，可以设置较大的每页显示数量并保存
• 不同页面可以保持各自的分页设置
• 提升用户体验，避免每次访问都需要重新调整

数据库备份、还原功能

功能说明：提供数据库的备份和还原功能，保障数据安全。

备份功能：

操作	说明
创建备份	点击"立即备份"按钮，创建当前数据库的完整备份
备份内容	包含所有弹幕数据、条目信息、配置等
备份存储	备份文件保存在系统持久化目录中

还原功能：

操作	说明
选择备份	从备份列表中选择要还原的备份文件
还原数据	点击"还原"按钮，将数据库恢复到备份时的状态
⚠️ 注意	还原操作会覆盖当前数据，请谨慎操作

适用场景：

• 定期备份数据，防止意外数据丢失
• 系统升级或重大配置变更前备份
• 测试新功能前备份，出问题可快速还原
• 迁移数据到新服务器

安全建议：

• 建议定期创建备份（如每周一次）
• 重要操作前务必先备份
• 备份文件可以下载到本地保存
• 还原前确认备份文件的完整性

---

修改密码

1. 鼠标移动到右上角 头像 处
2. 点击 "修改密码"
3. 输入当前密码
4. 输入新密码并确认
5. 点击 "保存"

---

📚 相关文档

• 🎬 元数据源配置 - TMDB/TVDB 配置
• 🎬 弹幕API功能配置 - Token管理等
• ❓ 常见问题 - 故障排除