⚡ 快速上手
用最少的步骤跑通「看完一集 → 自动打格子」的完整流程。
第 1 步：部署运行
选择一种方式启动 Bangumi-syncer，详见 快速开始。
- Docker（推荐）：一行
docker-compose拉起，见 Docker 部署。 - Windows：下载 zip 包，双击
start.bat，见 Windows 部署。 - 群晖 NAS：通过 Container Manager 部署，见 群晖部署。
启动后浏览器访问 http://主机IP:8000，首次登录账号密码均为 admin，请立即修改。
第 2 步：填写 Bangumi 账号
进入 「配置管理」 → Bangumi 账号配置 卡片，点击右上角 「OAuth 授权」 按钮，跳转到 Bangumi 网站登录并授权，完成后自动回到本页并添加账号。授权过程中会自动获取你的用户名、昵称、头像与访问令牌，无需手动填写。
若无法使用 OAuth 授权，也可点击 「手动添加」 自行填写：
- 用户名：Bangumi 个人主页URL
https://bgm.tv/user/xxx最后面的xxx - 访问令牌：点击生成
- 媒体服务器用户名：你在 Plex / Emby / Jellyfin 等媒体库里的登录名
媒体服务器用户名是必须的
媒体服务器用户名是同步与否的关键依据，请不要忘记设置，这关系到是否会触发同步动作。 fongmi 的用户名比较特殊，为设备名，在日志里可以看到相关信息。
完整字段说明见 配置说明。
第 3 步：接入媒体源
选择你使用的播放端，按对应文档配置 Webhook：
| 播放端 | 文档 | Webhook 地址 |
|---|---|---|
| Plex（Tautulli） | 文档 | http://主机IP:8000/Custom |
| Plex Pass 原生 | 文档 | http://主机IP:8000/Plex |
| Emby | 文档 | http://主机IP:8000/Emby |
| Jellyfin | 文档 | http://主机IP:8000/Jellyfin |
| 通用 Webhook | 文档 | http://主机IP:8000/Custom |
| 同步源 | 文档 |
|---|---|
| Trakt 同步 | 文档 |
| 飞牛同步 | 文档 |
| fongmi | 文档 |
更多媒体源移步 接入使用。
第 4 步：验证同步
- 在媒体库中播放完成一集番剧。
- 打开 Bangumi-syncer 的 「日志管理」 页面查看同步记录。
- 前往 Bangumi 个人主页确认观看进度已更新。
标题对不上怎么办
如果媒体库的番剧名称和 Bangumi 条目对不上，可在 「映射管理」 手动指定「标题 → Bangumi 条目 ID」，详见 自定义映射。
想进一步加速与降低 API 依赖？
同步量大、网络不稳定或想降低对 Bangumi 官方 API 的依赖时，可启用 🗄️ Bangumi Archive 离线查询层：把全站数据快照下载到本地，命中后零 API 调用、毫秒级返回；开启后可大幅提升匹配率。