Octans-局域网媒体服务端UDP发现

本文主要记录家庭媒体服务与 NAS 在局域网内的「自动发现」机制：Jellyfin / Emby 官方 App 的主路径是什么、它和 DLNA / mDNS 有何区别、典型家庭拓扑下会踩哪些坑，以及只做「打开 App 看到本网段服务器列表」时的最小可行集。

自托管媒体客户端常见两条入门路径：用户手填 http(s)://host:port，或打开 App 就列出「家里那台」。后者看起来像魔法，实现上往往是 固定端口上的自定义 UDP 探测，而不是完整的「网络邻居」协议栈。

结论摘要

家庭媒体服务端的 App 侧局域网发现，主流做法是：

客户端向本网段广播一句约定好的 probe 文本。
服务端匹配后以 JSON（或等价结构）单播回地址、实例 ID 与名称。
客户端展示列表，用户选择后再走 HTTP(S) 业务 API。

该路径原理简单、实现量小。在 同一子网、防火墙放行、无客户端隔离 的家庭有线 / 普通 Wi-Fi 下成功率很高；跨子网、Docker bridge、VPN / 反代边界、访客网隔离和移动端后台会明显拉低成功率。

NAS 则多采用 厂商专用 UDP 工具端口，再叠加 mDNS、SSDP/UPnP、WS-Discovery、NetBIOS 等，以适配系统「网络邻居」。若目标只是「App 找到媒体服务」，不必上完整 NAS / DLNA 栈。

Jellyfin / Emby：自定义 UDP 7359

两端都把 本机 App 发现 定在 UDP 7359（文档侧描述为不可配置），与 HTTP 业务口（常见 8096 / 8920）并列。

能力	端口 / 协议	是否 App 主发现路径
本地 App 服务器发现	UDP 7359 自定义 probe	是
HTTP / HTTPS API	TCP 8096 / 8920 等	否（发现之后再用）
DLNA / SSDP	UDP 1900	否（旁路）

交互时序

客户端                                      服务端
  |                                            |
  |  UDP 广播 → 255.255.255.255:7359            |
  |  payload: "who is JellyfinServer?"         |
  |  (或 "who is EmbyServer?" 等)              |
  | -----------------------------------------> |
  |                                            | 匹配 probe
  |  UDP 单播 ← JSON { Address, Id, Name, ... }|
  | <----------------------------------------- |
  |  用户选择 → HTTP(S) 业务 API               |

Jellyfin 侧（源码 + 文档事实）：

服务端绑定 7359；probe 忽略大小写包含 who is JellyfinServer? 时应答。
响应里可带 Address / Id / Name 等；多网卡 / 反代 / 容器映射时可用发布 URL 配置修正「对外地址」。
官方 Networking 文档强调：自动发现 仅限本子网，不应当作对外网暴露入口。

Emby 侧同样绑定 7359，响应 who is EmbyServer? 以及历史兼容串 who is MediaBrowserServer_v2?。社区与文档确认主路径是自定义 UDP，不是以 mDNS 为主。

不要和 DLNA 混为一谈

Jellyfin 的 SSDP / UPnP（DLNA）走 UDP 1900，面向 DLNA 渲染器 / 控制器。那是另一条产品能力。

工程含义：

做「官方 App 找服务器」→ 对齐 7359 类自定义 UDP 即可。
做「电视当 DLNA 设备刷到库」→ 才需要 SSDP / UPnP，部署与防火墙更重。

NAS 常见做法

产品	厂商专用发现（公开端口级）	系统级通告	报文规范完整度
Jellyfin	UDP 7359 文本 + JSON	DLNA/SSDP 可选	高（开源）
Emby	UDP 7359 文本 + JSON	另有 DLNA 等	中
QNAP	UDP 8097（Qfinder 等）	UPnP、Bonjour 可开关	低（端口公开，报文未公开）
Synology	UDP 9999/9998/9997（Assistant 等）	SSDP、WSD 等	低
TrueNAS	材料侧无对等闭源 Finder	mDNS + NetBIOS + WSD	中

NAS 往往 并行多条通道：自家工具秒找设备用专用 UDP；出现在 OS「网络」邻居里用标准通告协议。App 绑定媒体服务时，通常只需要对齐自家协议，不必复刻 Windows 资源管理器那一套。

三类「自动发现」

类型	机制	代表
自定义 UDP 广播 / 探测	约定端口 + probe + JSON/二进制应答	Jellyfin / Emby、Qfinder、Assistant
SSDP / UPnP	多播 `239.255.255.250:1900`	DLNA、部分 NAS 邻居
mDNS / DNS-SD、WSD、NetBIOS	系统服务通告	Bonjour、Windows 网络发现

「打开手机就能看见服务器」在媒体库产品里，绝大多数属于第一类。

家庭拓扑下的成功率边界

场景	粗判
同一二层 / 同一子网，有线或普通 Wi-Fi	高
主机防火墙未放行 UDP 7359（或厂商端口）	失败或列表为空
客户端隔离（AP isolation / 访客网）	广播到不了服务端
Docker bridge 未映射 UDP、未设正确 published URL	发现成功但 Address 不可达，或根本收不到
跨 VLAN / 三层路由	广播不跨路由；需中继或手填
VPN / 反代仅暴露 HTTPS	发现通常无意义；应手填公网入口
Android Doze / 后台	发现应在前台短窗口完成；依赖多播锁等细节

实现最小集时建议同时给出：

探测结果列表（实例 ID、名称、候选 base URL）
HTTP 可达性探测（列表里点选前做一次 health / public info）
手填 fallback（永远不要只留自动发现一条路）

最小可行方案（产品视角）

若目标只是「App 打开后看到局域网内服务端列表」：

UDP probe/response（固定端口 + 短文本/JSON）
  + 可达 base URL
  + 用户选择后走既有登录 / 绑定

不必默认上完整 DLNA、mDNS 或 NAS 厂商 Finder 协议。可选增强（多网卡 published URL、IPv6、HTTPS 证书信任提示）可以后加，但不应和「探测主路径」绑死。

参考与边界

Jellyfin Networking / AutoDiscovery 文档与 AutoDiscoveryHost 等开源实现
Emby / MediaBrowser UDP 发现端口与社区说明
QNAP / Synology / TrueNAS 公开端口与服务发现说明
本文不展开具体产品 API 字段定稿；实现细节以各项目正式文档为准

结论摘要#

Jellyfin / Emby：自定义 UDP 7359#

交互时序#

不要和 DLNA 混为一谈#

NAS 常见做法#

三类「自动发现」#

家庭拓扑下的成功率边界#

最小可行方案（产品视角）#

相关阅读#

参考与边界#