⚙️ 配置说明

在 Web 界面左侧打开 「配置管理」，即可在浏览器里完成本页列出的全部设置。修改后请点击页面下方的 「保存配置」 才会生效（个别项保存后需要重启程序，页面上会有说明）。

配置结构

配置按功能分卡片展示，左侧 TOC 可快速跳转。所有配置项都对应 config.ini 中的某一段，但普通用户无需手写 INI，Web 界面已涵盖全部字段。

同步配置

• 启用 Webhook 认证：打开后，媒体服务器通知本程序的地址里需要带上密钥，更安全，适合能从外网访问到本程序的情况；关闭则不要求密钥，仅适合完全内网、你信任当前网络环境时使用。
• Webhook 认证密钥：开启认证后用来拼在通知地址里的一串字符；可复制，也可刷新为新密钥（刷新后记得在 Plex / Emby / Jellyfin 里把 Webhook 地址改成新的）。页面下方会给出各媒体软件地址的填写示例。
• 剧场版播放开始时将条目标为在看：仅当同步内容为剧场版动画，开启后开始播放剧场版会自动将 Bangumi 条目收藏标为在看。关闭则不会标记在看。
• 剧场版同步后自动将条目也标为看过：仅当同步内容为剧场版动画，且本篇单集格子已成功打上时，是否再把该条目的收藏状态同时也设为「看过」。关闭则只更新单集观看进度、不把整条条目标为看过。（PS.如果你想自己写影评，建议关闭此项）
• TV系列同步后自动将整部番标为看过：仅当同步内容为TV动画，当已看过集数等于或者大于总集数时，自动把已看完的番剧标记为“看过”。默认为关。
• 启用三次元（日剧/电影）支持：默认关闭，程序只匹配 Bangumi 动画条目。开启后，在动画匹配失败时会继续尝试 三次元条目（type=6），可覆盖日剧、真人版、真人电影等。
• 模糊匹配置信度阈值：当匹配相似度低于此阈值时，不直接同步，而是沉淀到「候选确认」页等人工审核，避免低质量匹配误打格子。设为 0 表示关闭此兜底（所有匹配都直接同步），默认值见页面提示。
• 测试同步跳过用户名校验：开启后 /api/test-sync 与 /api/fongmi/debug/sync 等测试接口不再校验 media_server_username / 用户映射，方便未配置用户名时验证匹配与标记。仅对测试来源生效，生产 webhook 路径不受影响。

屏蔽关键词

独立卡片，用于跳过不想同步的番剧。标题包含这里关键词的番剧将不同步（不区分大小写）。

• 点击卡片右上角 「添加关键词」，输入框中填入关键词后回车或点击「添加」即可加入列表。
• 每个关键词以红色标签展示，点击标签右侧的垃圾桶图标可删除。
• 添加和删除即时生效，无需手动点击页面下方的「保存配置」。
• 在「同步记录」页，失败或已忽略的记录旁也有一个盾牌按钮，可一键将该番剧标题加入屏蔽列表。

Bangumi 账号配置

所有 Bangumi 账号统一在此卡片管理。账号通过 OAuth 授权 或 手动添加 两种方式添加，保存后即时生效。

• 仅一个账号时为单用户模式：只同步该账号对应的媒体服务器用户名的观看记录。
• 多个账号时按媒体服务器用户名自动路由：每个账号配置自己的媒体服务器用户名，谁看的就记到谁的 Bangumi。
• 点击账号条目的 「设为激活」 可切换默认账号，用于无法确定归属时的兜底（如放送日历、API 探测等场景）。

添加账号

• OAuth 授权（推荐）：点击卡片右上角 「OAuth 授权」 按钮，会跳转到 Bangumi 网站登录并授权，完成后自动回到本页并添加账号。授权过程中会自动获取你的用户名、昵称、头像与访问令牌，无需手动填写。回调地址由系统按当前访问地址自动派生，无需额外配置。
• 手动添加：点击 「手动添加」 按钮，自行填写用户名与访问令牌（适合已有令牌或无法使用 OAuth 的场景）。访问令牌可在 Bangumi 令牌生成页 获取。

账号字段说明

• Bangumi 用户名：你在 Bangumi 网站上的用户名。OAuth 授权时自动填充；手动添加时填个人主页 @ 后面的那串字符。
• 访问令牌：用于调用 Bangumi API 的凭证。OAuth 授权时自动获取并定期刷新；手动添加时需自行填写。令牌加密存储在数据库中。
• 媒体服务器用户名：你在 Plex / Emby / Jellyfin 等媒体服务器中的用户名，必须与媒体服务器里显示的一致，这样「谁看的」才能对上「记到谁的 Bangumi」。多个用户名可用英文逗号分隔。
• 观看记录仅自己可见：打开后，同步到 Bangumi 的观看记录仅自己可见，关闭则按 Bangumi 上公开的观看记录处理。
• 令牌过期时间 / 下次刷新：OAuth 授权的账号会展示令牌过期时间，系统会在临近过期时自动刷新，无需干预。
• 断开 OAuth：OAuth 授权的账号可点击「断开」回退为手动模式，保留已填写的访问令牌继续同步，但不再自动刷新。

媒体服务器用户名是必须的

媒体服务器用户名是同步与否的关键依据，请不要忘记设置，这关系到是否会触发同步动作。 fongmi 的用户名比较特殊，为设备名，在日志里可以看到相关信息。

Bangumi OAuth 应用凭证

OAuth 授权所需的应用凭证（Client ID / Client Secret）已内置，开箱即用，普通用户无需关注本卡片。

如需使用自定义应用（例如自己创建的 Bangumi 应用），可在 bgm.tv/dev/app 创建后填写此处覆盖，或通过环境变量 BANGUMI_OAUTH_CLIENT_ID / BANGUMI_OAUTH_CLIENT_SECRET 注入。回调地址由系统自动按当前访问地址派生，无需配置。

Web 认证配置

• 启用 Web 认证：建议能从外网打开管理页时务必开启；关闭后任何人知道地址都能进管理页，仅适合纯内网且你完全信任当前环境。
• 管理员用户名 / 管理员密码：登录管理页用的账号密码。密码框留空再保存表示不修改当前密码，要改密码时输入新密码并保存即可。
• 会话超时时间：登录后多久无操作会自动退出，单位是秒。
• 启用 HTTPS 安全 Cookie：只有当你用 https:// 访问管理页时才建议打开，避免登录状态被不当传输。
• 最大登录尝试次数 / 锁定时间（秒）：同一网络下连续输错密码达到次数后，暂时禁止该来源继续尝试登录，减轻被试密码的风险。

高级配置

• Web 对外路径前缀（子路径反代）：只有当你把本程序挂在网址的子路径下（而不是网站根目录）时才需要填写，且要与你在网关或反向代理里设置的路径一致。默认留空即可。修改此项后需要重启程序才会完全生效，以页面提示为准。
• HTTP 代理：本程序访问外网（例如 Bangumi）时走你本地的代理，网络受限或需要翻墙时填写。可使用 「智能配置」 按环境生成推荐地址，并用其中的连通性测试检查是否填对。
• Bangumi API 反向代理：本程序访问 Bangumi API（主要同步接口）时走你指定的反向代理，网络受限或直连困难时填写。可填入自行搭建或第三方提供的反代链接（用于替代 https://api.bgm.tv），留空则使用默认地址。
• Bangumi Next 反向代理：本程序引导访问 Bangumi Next（鉴权与令牌获取页面）时走你指定的反向代理，网络受限或直连困难时填写（用于替代 https://next.bgm.tv）。留空则使用默认地址。
• Bangumi 图片反向代理：仪表板时间线封面图使用（用于替代 https://lain.bgm.tv），留空则返回 API 原始图片地址。
• SSL 证书验证：一般保持开启。仅当使用代理后出现证书报错、且你确认环境可信时，再考虑关闭（会降低连接校验强度）。
• 调试模式：打开后会打出更多运行细节，方便排查问题；日常使用建议关闭。
• 调度器时区：定时任务（飞牛/fongmi/Trakt）使用的时区，IANA 格式（如 Asia/Shanghai、America/New_York、UTC）。在 config.ini 的 [scheduler] 段 timezone 项配置。Docker 部署也可通过 TZ 环境变量覆盖，优先级：config.ini > TZ 环境变量 > 默认值 Asia/Shanghai。
• 同步记录保留天数：程序每次启动时会自动清理超过指定天数的同步记录，控制数据库体积，避免长期运行后占用过大空间。默认不清理，可在 config.ini 的 [dev] 段 sync_records_retention_days 项修改：填 0 或负数表示永不清理（保留全部历史记录）；调试环境可设为 7–14，生产环境建议 30–90。清理后仪表板的热力图缓存会自动失效并重新加载。

通知配置

在同步成功、失败或其它情况发生时，通过 Webhook、邮件、企业微信 或 钉钉 提醒你，也可借助本功能扩展其他应用的状态同步能力。详细说明见 通知系统配置。

• 支持 4 类渠道：Webhook（钉钉、Telegram、飞书、Bark、Discord、Slack 等通用 HTTP）、邮件（SMTP）、企业微信群机器人、钉钉群机器人。每类渠道可添加多个实例。
• 渠道配置：在「通知配置」卡片右上角点击「渠道配置」打开模态框，内联编辑各渠道的连接信息（URL/Token/SMTP 等）。
• 通知规则：在「通知配置」卡片中点击「新建配置」创建规则，一个规则 = 「勾选若干触发事件 + 选择若干渠道 + 可选自定义模板」。事件按同步流程、匹配质量、数据源、调度任务、Bangumi API、系统运维六大类分组展示。
• 未创建任何规则时，系统回退到传统模式：每个启用渠道按自身 types 字段订阅事件。
• 配置好后可在渠道配置中点击「测试」试发；同类通知在短时间内会限制连续发送次数（默认 60 秒冷却），避免刷屏。

今日放送提醒

依赖 Bangumi Archive 的 episode.airdate 数据，每日定时查询当天放送的番剧章节并通过通知系统推送。仅在 Archive 启用且已导入数据时生效。配置段为 [notify-airing-today]，对应通知类型 airing_today（归入「调度任务」分类）。

• 启用：总开关，默认开启，但仍需 Archive 启用才会真正执行。
• 定时 Cron：五段式 cron，默认 0 9 * * *（每日 09:00）。保存配置后定时任务会热更新，无需重启。
• 仅我在追：开启后只统计你在 Bangumi 上「在看」的番剧（动画 + 三次元），需配置 Bangumi 账号；获取失败时自动降级为全部放送。

通知订阅

airing_today 默认不会发到任何渠道，需要在「通知配置」的渠道或规则中订阅该事件（在「调度任务」分类下勾选「今日放送提醒」）。

此外，仪表板新增了番剧放送日历卡片（仅在 Archive 启用时显示），可查看未来 7/14/30 天的放送日程，支持「仅我在追」筛选。

Bangumi-data 配置

• 使用 Bangumi-data 匹配：是否启用公共番剧数据帮助把媒体库里的片名对上 Bangumi 条目，对上之后记格更稳，也能减轻反复查询的负担。
• 使用本地缓存：是否把下载的数据存到本机，下次启动优先读本地，加快启动、少占带宽。
• 缓存有效期（天）：本地缓存用多久后认为需要更新；填 0 表示每次启动都尝试更新，一般配置为7天即可。
• 数据源 URL：数据文件的下载地址，一般保持默认即可；若默认地址在你网络下打不开，可换成镜像说明里提供的地址。
• 本地缓存路径：缓存文件保存在哪个路径，一般保持默认即可。

Bangumi Archive 离线查询层

可选的本地归档功能：把 Bangumi 全站数据快照下载到本地 SQLite，启用后同步优先查本地、未命中再回退 API，能显著降低延迟与 API 调用。默认关闭，常态占用约 1.3GB，导入峰值约 2.6GB。详见 🗄️ Bangumi Archive 离线查询层。

• 启用 Archive：总开关。关闭后所有短路查询立即返回 archive_disabled，行为与未接入 archive 完全一致；从「关闭」切到「开启」会自动触发首次导入与索引构建，无需重启程序。
• 定时更新 Cron：五段式 cron，默认每周三 08:00（北京时间）执行，晚于官方 05:00 发布。可在「调试工具」或通过 API 手动触发更新。
• 数据目录：存放双库（a/b 互备）、meta、active 指针的目录，默认 ./data/archive。Docker 部署建议挂载到 /app/data，避免容器重建时数据丢失。
• HTTP 代理：下载 dump zip 时使用的代理。留空则自动继承 [dev] script_proxy，国内用户建议配置。
• 磁盘阈值 (MB)：低于此可用空间时跳过导入，避免磁盘写满。默认 3000。
• SSL 校验：下载时是否校验 SSL 证书，自签名环境可关闭。

Bangumi Replay 待同步队列补发

当 Bangumi API 不可达（网络抖动、DNS 失败、5xx/429 持续返回）时，把写操作（标记在看 / 点单集等）暂存到本地 pending_sync_queue 表，等 API 恢复后由调度器自动批量补发（详见 🔄 Bangumi Replay 待同步队列补发）。

与 Archive 解耦

Replay 与 Archive 已解耦，可独立启停。但完全实现「无网缓存请求 + 自动补发」需要 Archive 配合：Archive 提供读降级（命中本地数据集匹配新条目），Replay 提供写降级（入队待补发）。不开 Archive 时，Replay 仍可独立工作，但仅能在「API 已匹配到 subject_id 后写失败」场景下补发。

• 启用 Replay：总开关，默认启用，与 Archive 互相独立。
• API 不可达 TTL (秒)：标记 API 不可达后的冷却时间，期间所有写操作直接入队不发请求，默认 300 秒（5 分钟）。
• 补发调度 Cron：五段式 cron，默认每 10 分钟扫描一次队列进行补发。队列为空时自动跳过本轮，不发探测请求。
• 批量大小：每轮补发最多处理的任务数量，默认 20。
• 最大重试次数：单条任务重试次数上限，超过后标记为 abandoned 不再重试，默认 50。

立即触发补发

除 cron 定时调度外，入队成功后会自动触发一次立即补发（500ms 防抖），让 API 抖动恢复场景下的补发延迟从「下一个 cron 周期」降到「秒级」。调度器未启动 / 未启用时不影响入队，下一轮 cron 仍会兜底。详见 🔄 Bangumi Replay 待同步队列补发。

飞牛影视

从飞牛的播放记录同步到 Bangumi（仅在使用飞牛并需要此功能时关注）。接入步骤见 飞牛定时同步。

• 启用飞牛同步：关闭时完全不读飞牛数据。首次打开并保存后，只会处理保存之后在飞牛里有更新的观看记录，不会把很久以前的老记录一次性全部推到 Bangumi，关闭并保存会清除这一起点设置。
• 数据库路径：飞牛库里的 trimmedia.db 在本程序能读到的位置（按你安装方式可能是本机路径或容器里的路径），按安装说明挂载或填写即可。
• 视为看完的最低进度 (%)：播到百分之多少就算「看完了」可以记格，飞牛里已标记看完的会当作 100%。
• 飞牛用户：通常填 all 表示不区分飞牛账号；若只想同步某一个飞牛用户，需要其专用标识，可在 「调试工具」 中按页面说明查看后再填。
• 时间范围：在启用同步的前提下，可再限制「只关心最近多久内有更新的记录」，减少无关条目。
• 定时扫描间隔：隔多久自动检查一次飞牛上的观看进度，界面里有默认间隔，不熟悉可保持不动。
• 单次扫描最大条数：每次最多处理多少条候选记录，数字越大单次负担越重，一般保持默认即可。

fongmi 局域网同步

从局域网内 fongmi 播放器的实时播放状态同步到 Bangumi（仅在使用 fongmi 及其 fork 并需要此功能时关注）。接入步骤见 fongmi 局域网同步。

• 启用 fongmi 同步：关闭时完全不轮询 fongmi 设备。开启后会按设定频率访问设备的 /media 端点，检测播放进度达标的剧集并提交到 Bangumi。仅支持 fongmi 及其 fork（TV-K、OK影视、WebHomeTV 等），原版 TVBoxOSC 不支持。
• 设备列表：手动指定 fongmi 设备 IP，多个用英文逗号分隔，可带端口号，例如 192.168.1.100 或 192.168.1.100:9979。使用非标端口的设备必须在此填写；留空则依赖下方的自动扫描。
• 自动扫描网段：开启后会扫描下方网段的默认端口 9978，自动发现 fongmi 设备。只有一台设备时建议关闭此项并直接填写设备 IP，更快也更稳定。
• 网段：自动扫描的局域网网段前三段，例如 192.168.1（会扫描 192.168.1.1–192.168.1.254）。Docker 部署需使用 host 网络模式，否则容器无法发现局域网设备。
• 视为看完的最低进度 (%)：播放进度 position / duration 达到该百分比即视为看完并参与同步，默认 80%。直播流不参与判定。
• 定时 Cron：隔多久自动轮询一次 fongmi 设备，默认每 3 分钟 */3 * * * *。保存配置后定时任务会热更新，无需重启。
• 与 Bangumi 账号的对应关系：单用户或多用户模式下，上文「媒体服务器用户名」需填写 fongmi 设备名称（来自 /device 的 name 字段，不是 IP），可在 「调试工具」 的 fongmi 扫描结果或同步日志中查看。

LLM 全局配置

LLM 连接是独立模块，追番总结和调试工具共用。在「配置管理」页面顶部的 LLM 卡片中修改，配置存放在 [llm] section：

• 提供商（provider）：LLM 服务提供商。可选值：openai_compat（默认，兼容 OpenAI / DeepSeek / Ollama 等 OpenAI 接口格式的服务）。后续将支持 anthropic。
• API 地址（api_base）：LLM 服务商的 API 端点，需兼容所选 provider 的接口格式。默认 https://api.openai.com/v1。OpenAI 兼容接口请以 /v1 结尾填写完整地址。
• API 密钥（api_key）：服务商提供的 API Key。加密存储，页面回显为掩码。
• 模型（model）：要调用的模型名称，默认 gpt-4o-mini。请确认所选模型支持 Chat Completions 接口。
• 最大 Token（max_tokens）：单次请求最大输出 token 数，默认 2000。根据模型上下文窗口和总结长度调整。
• 温度（temperature）：生成随机性，0~2 之间，默认 0.7。越低越确定/保守，越高越有创意。
• 超时时间（timeout）：请求超时秒数，默认 60。遇到超时错误可适当调大。
• 调用记录保留（retention_days）：LLM 调用记录（Token 用量、延迟等）在数据库中保留天数，默认 365 天。

配置后可点击「测试连接」按钮验证 LLM 是否可达。

---

AI 追番总结

前提：需要先完成 LLM 全局配置，追番总结依赖 LLM 来生成摘要。

在「配置管理」→「AI 追番总结」卡片中创建和管理总结任务。每个任务对应一个 [summary-{name}] section，全部在 Web 界面操作，无需手动编辑配置文件。

追番总结任务

每个总结任务对应一个 [summary-{name}] section，由 Web 界面自动管理（创建/编辑/删除）。在「配置管理」→「AI 追番总结」卡片中操作：

• 任务名称（name）：唯一标识，也用作 section 后缀。通过 Web 界面创建时自动生成（例：追番总结 1）。

• 启用（enabled）：是否开启该定时任务。

• 定时 Cron（cron）：五段式 Cron 表达式，默认 0 21 * * *（每晚 9 点执行）。保存后定时任务会热更新，无需重启。

  常用示例（直接复制 Cron 表达式，配合对应回溯天数）：

  场景	Cron	lookback_days
  每日总结（默认）	0 21 * * *	1
  每周总结（周日 21:00）	0 21 * * 0	7
  每月总结（1 号 21:00）	0 21 1 * *	31
  每季度总结	0 21 1 1,4,7,10 *	92
  年度总结	0 21 1 1 *	365

  季度总结的 92 天回溯已覆盖季番和半年番。如需每次总结半年内容，Cron 保持不变、回溯天数改为 183 即可。

  支持同时创建多个任务（如每日 + 年度），各自独立运行、互不影响。

• 回溯天数（lookback_days）：每次执行时回顾最近几天的观看记录，默认 1 天。调整为与 Cron 周期匹配（如季度总结设为 92）。

• 限定用户（user_name）：只总结特定用户的记录，留空则包含所有用户。

• 自定义提示词（system_prompt）：控制总结的语气、格式、长度等。默认为轻松聊天风格的中文提示词，可根据需要改写。

📋 推荐 Prompt 模板（点击展开，直接复制）

数据洞察型 — 统计观看数据，发掘规律：

你是一个追番数据分析师。用户会给你一段观影记录，请生成一份数据洞察报告：

1. 按观看次数降序排列番剧，标记 TOP 3 热门
2. 统计各用户的观看活跃度（总集数、番剧数）
3. 从记录时间戳推断观看高峰时段（如工作日晚上、周末下午）
4. 从番剧标题推断类型分布（热血/日常/恋爱/奇幻 等），按占比排名
5. 语气轻松但有数据感，控制在 400 字以内

偏好分析型 — 根据片单推断口味，给出推荐：

你是一个懂二次元的追番顾问。用户会给你一段观影记录，请分析用户的口味偏好：

1. 根据番剧名称和风格，归纳用户的观看偏好（如"偏爱战斗番""喜欢治愈日常"）
2. 如果涉及多用户，对比不同用户的喜好差异
3. 根据当前片单，推荐 1-2 部风格相近的番剧（仅推荐，无需查数据）
4. 语气像朋友聊天，控制在 350 字以内

简洁播报型 — 极简进度表，适合高频推送：

你是一个极简追番播报员。用户会给你一段观影记录，请生成一个超简总结：

1. 按番剧分组，只列名称和进度（如"《芙莉莲》S1E10"）
2. 多用户场景下标注每条记录属于谁
3. 总字数不超过 150 字
4. 最后加一句不超过 15 字的俏皮评论

吐槽评论型 — 轻松吐槽风，比默认更活泼：

你是一个毒舌但可爱的追番伙伴。用户会给你一段观影记录，请用吐槽风格生成总结：

1. 按番剧分组描述进度，并对每部番剧加一句简短吐槽（如"终于开始补这部了，全网都在等你"）
2. 如果进度太慢（同部番剧集数增长很少），善意调侃
3. 如果开了很多新坑，提醒"注意肝度"
4. 语气轻松毒舌但不冒犯，控制在 300 字以内

• 最大记录数（max_records）：每次发送给 LLM 的最大观影记录条数，默认 -1（不限制）。季度/年度总结保持 -1 即可，日常总结可设为 200 控制上下文长度。

创建任务后，可在「调试工具」页面手动触发测试。总结结果会通过通知系统发送，对应的通知类型为 watching_summary_{任务名称}，可在 Webhook/邮件配置中勾选。

接下来

配置完成后，按你的播放端接入媒体源：

• Plex：Tautulli / 原生 Webhook
• Emby 通知 / Jellyfin Webhook
• 自定义 Webhook
• Trakt.tv 定时同步 / 飞牛定时同步 / fongmi 局域网同步

标题对不上 Bangumi 条目时，可使用 自定义映射 手动指定。