Seerr Discord 通知配置完全指南：Webhook、角色提及与多语言通知-创锋一号

Seerr Discord 通知配置完全指南：Webhook、角色提及与多语言通知

【免费下载链接】seerrOpen-source media request and discovery manager for Jellyfin, Plex, and Emby.项目地址: https://gitcode.com/GitHub_Trending/je/seerr

Seerr 内置的 Discord 通知代理（Notification Agent）可以将媒体请求、问题反馈与处理状态等事件实时推送到你管理的 Discord 服务器的指定频道，是 Jellyfin / Plex / Emby 家庭媒体栈中最常用的告警渠道之一。本文以官方文档 Discord 通知配置为主线，结合 DiscordAgent 实现与前端设置表单 NotificationsDiscord.tsx 的源码细节，完整讲解每一项配置的语义、底层行为与实战注意事项，读完即可独立完成从创建 Webhook 到按语言、按角色定向推送的整套配置。

Discord 通知代理能做什么

开启 Discord 通知代理后，Seerr 会通过 Discord 的 Incoming Webhook 接口，向目标频道发送包含富媒体卡片（Embed）的推送消息。从通知类型枚举可以看到它覆盖了完整的媒体生命周期与工单流程：

通知类型	位掩码值	触发场景	Discord 卡片颜色
`MEDIA_PENDING`	2	有新的媒体请求等待审批	橙色（`ORANGE`）
`MEDIA_APPROVED`	4	请求已批准，进入下载流程	紫色（`PURPLE`）
`MEDIA_AVAILABLE`	8	媒体已就绪可用	绿色（`GREEN`）
`MEDIA_FAILED`	16	请求处理失败	红色（`RED`）
`TEST_NOTIFICATION`	32	设置页的测试通知	默认紫色
`MEDIA_DECLINED`	64	请求被拒绝	红色（`RED`）
`MEDIA_AUTO_APPROVED`	128	请求自动通过	紫色（`PURPLE`）
`ISSUE_CREATED`/`ISSUE_REOPENED`	256 / 2048	新问题 / 问题重新打开	红色（`RED`）
`ISSUE_COMMENT`	512	问题有新评论	橙色（`ORANGE`）
`ISSUE_RESOLVED`	1024	问题已解决	绿色（`GREEN`）
`MEDIA_AUTO_REQUESTED`	4096	自动请求（如 Plex Watchlist 同步）	默认紫色

每种类型的卡片配色在 buildEmbed 方法中按Notification类型逐一映射，颜色值定义见 EmbedColors 枚举。卡片还会附带“请求人”“请求状态”“上报人”“问题类型”“问题状态”等字段，并在配置了applicationUrl时把标题链接到对应的媒体详情页或问题页，方便直接从 Discord 跳转处理。

前置准备：创建 Discord Webhook

配置的第一步是在 Discord 中创建 Webhook，官方文档给出的路径是：

Server Settings → Integrations → Webhooks

创建一个新的 Webhook 并复制其 URL（形如https://discord.com/api/webhooks/<id>/<token>）。该 URL 就是下面配置中的Webhook URL，Seerr 将用它作为通知的发送端点。

配置项详解

进入 Seerr 的设置 → 通知 → Discord，可以看到以下配置项。前端表单的完整字段与校验逻辑可参考 NotificationsDiscord.tsx，底层数据模型见 NotificationAgentDiscord 接口。

启用代理与通知类型

Enable Agent（启用代理）：总开关。shouldSend()方法要求enabled为真且webhookUrl非空才会真正发送，见 shouldSend 实现。
通知类型选择器：使用位掩码（bitmask）形式保存到types字段，勾选后仅发送对应类型的事件；未勾选任何类型时types为0。默认值为0（不发送任何类型），因此启用代理后务必至少勾选一种类型。
Embed Poster（内嵌海报）：默认开启（embedPoster: true）。开启后通知卡片会在缩略图位置展示媒体海报图，关闭则只保留文字信息。

Webhook URL（必填）

粘贴前面从 Discord 复制的 Webhook URL。前端使用 Yup 校验必须是合法 URL，且启用代理时必填；服务端在shouldSend()中同样把webhookUrl非空作为发送前提。

Notification Role ID（可选）

填写一个 Discord 角色 ID 后，该角色会被包含在 Webhook 消息中，即发送@角色提及。源码实现为：当webhookRoleId通过 Snowflake 校验时，将其以<@&角色ID>形式拼入消息content，同时写入allowed_mentions.roles（见 send 方法）。

注意 ID 格式必须是 Discord Snowflake——纯数字。服务端常量DISCORD_SNOWFLAKE_REGEX定义为^\d{17,20}$（见 discord.ts 常量），前端表单校验为^\d{17,19}$。留空则禁用角色提及。

Bot Username（可选）

覆盖机器人在 Discord 中显示的名称。留空时，Seerr 会回退使用主设置中的applicationTitle（应用标题）作为 Webhook 用户名（见 send 方法），这也是部分用户发现机器人名字与预期不符的原因——只需在这里显式填写即可。

Bot Avatar URL（可选）

与用户名同理，可覆盖机器人的头像。该值会原样作为avatar_url传给 Discord Webhook。前端校验必须是合法 URL，允许留空（留空时 Discord 使用 Webhook 默认头像）。

Use Notification Recipient Locale（使用通知接收者语言）

开启后，通知将使用“触发该通知的用户”的显示语言发送——例如提交请求的用户或上报问题的用户。由于 Discord Webhook 是发送到频道而非私信，源码中的处理逻辑是取payload.notifyUser.settings.locale作为buildEmbed的国际化 locale（见 locale 计算）。该选项默认开启（useUserLocale: true）。

Notification Language（通知语言）

当Use Notification Recipient Locale关闭时生效，为发往该频道的所有通知固定一种语言。可选项来自 Seerr 支持的全部界面语言（AvailableLocale，即 server/i18n/locale 下各语言文件对应的语言码），默认值为en。

Thread ID（可选，进阶）

前端表单还提供了一个官方文档之外的隐藏进阶项Thread ID（见 NotificationsDiscord.tsx）：填写 Discord 线程频道 ID 后，通知将发布到该线程而不是 Webhook 所在的普通频道。源码通过给 Webhook URL 追加thread_id查询参数实现（见 send 方法）。留空则发送到 Webhook 关联的默认频道，同样需通过 Snowflake 数字校验。

用户级 Discord ID 与 @提及

官方文档提示：用户可以在个人设置中填写自己的Discord 用户 ID，从而选择是否在相关通知中被 @提及。这依赖两个层面的实现：

数据层：用户设置表新增了discordIds字段（迁移见 AddDiscordIdsColumn 迁移）。
发送层：当代理开启Enable Mentions（启用提及）且用户已在个人设置开启 Discord 通知并填写有效 ID 时，send()会把匹配的用户以<@用户ID>形式加入消息内容，并把去掉了尖括号的纯数字 ID 写入allowed_mentions.users，从而精准控制可被提及的用户范围，避免@everyone式的误打扰（见 send 方法）。

管理员通知场景下，还会遍历所有用户，筛选出已开启该类型 Discord 通知且shouldSendAdminNotification判定应接收的管理员用户一并提及。

发送流程与底层原理

一次完整的 Discord 推送在 DiscordAgent.send() 中按以下顺序执行：

前置过滤：若notifySystem为假，或当前通知类型不在已勾选的types位掩码内，直接跳过。
组装提及：收集用户提及（<@id>）与角色提及（<@&roleId>），并同步构造allowed_mentions。
确定语言：按useUserLocale决定使用接收者语言还是全局通知语言。
处理 URL：若配置了webhookThreadId，向 Webhook URL 追加thread_id参数。
构造载荷：通过axios.post发送username、avatar_url、embeds（由buildEmbed生成）与content（提及文本），其中username未显式配置时回退为应用标题。
失败处理：任何异常都会被记录为Error sending Discord notification，日志中附带错误消息与 Discord 的response.data，便于定位 Webhook 失效、限流或权限问题。

此外，buildEmbed还支持通过payload.extra追加自定义字段，并会为嵌入卡片打上当前时间的timestamp，使频道内的通知具备清晰的时间线。

验证与故障排查

测试通知：设置页底部提供“发送测试通知”按钮，会触发TEST_NOTIFICATION类型推送；前端依次展示“发送中 / 发送成功 / 发送失败”三种 Toast（见 NotificationsDiscord.tsx）。若收不到，可先确认代理已启用、types已勾选且 Webhook URL 有效。
日志排查：推送失败会在 Seerr 后端日志中出现Error sending Discord notification，查看其中的response字段即可区分 Discord 返回的错误码（如 404 表示 Webhook 被删除、403 表示权限不足）。
提及不生效：确认相关用户的 Discord ID 与角色 ID 是 17～20 位的纯数字 Snowflake，且用户在个人设置中已为该通知类型开启 Discord 渠道。

默认配置速查

从 settings 默认值可以看到 Discord 代理的出厂默认状态：

discord: { enabled: false, // 默认关闭，需手动开启 embedPoster: true, // 默认内嵌海报 types: 0, // 默认不勾选任何通知类型 options: { webhookUrl: '', webhookRoleId: '', enableMentions: true, // 默认允许提及 locale: 'en', // 默认通知语言为英文 useUserLocale: true, // 默认优先使用接收者语言 }, }

建议的最小可用配置为：创建 Webhook → 填入Webhook URL→ 开启Enable Agent→ 在通知类型选择器中勾选需要的类型（如媒体可用、请求待审批）→ 点击测试按钮验证。如需定向提醒，再补充Notification Role ID；如需固定统一语言，关闭Use Notification Recipient Locale并设置Notification Language。

企业官网建设流程全解析