stackia · stackia · Sep 3, 2026
diff --git a/docs/en/guide/ai-network-diagnosis.md b/docs/en/guide/ai-network-diagnosis.md
@@ -43,6 +43,7 @@ You can fetch `https://rtp2httpd.com/llms-full.txt` to obtain the complete rtp2h
 - Multicast, RTSP, and HTTP priority: URL parameter `r2h-ifname` > matching `upstream-interface-multicast` / `upstream-interface-rtsp` / `upstream-interface-http` > `upstream-interface` > system routing table.
 - FCC priority: URL parameter `r2h-ifname-fcc` > `r2h-ifname` > `upstream-interface-fcc` > `upstream-interface` > system routing table.
 - An OpenWrt UCI logical interface may be named `wan85`, while the actual kernel device may be `wan.85`, `eth0.85`, or `br-vlan85`. rtp2httpd needs the actual device name shown by `ip link`.
+- Multicast with an 802.1Q VLAN tag does not appear on UDP sockets of the physical parent. Point the upstream interface at an existing VLAN subinterface (such as `eth0.12`); rtp2httpd does not create VLANs and does not strip tags in-process.
 - FreeBSD supports explicit interface selection only for multicast. FCC, RTSP, and HTTP unicast traffic must use the system routing table.
 - Do not ignore `Failed to bind to upstream interface`. After a binding failure, later traffic may continue according to the system routing table and use the wrong path.
 - A playback URL or service definition may contain its own interface parameters even when the global configuration looks correct. Inspect the effective request URL.
@@ -58,7 +59,7 @@ You can fetch `https://rtp2httpd.com/llms-full.txt` to obtain the complete rtp2h
 
 [Meaning of key log messages]
 
-- `Multicast: interface ... does not exist`: the device is absent from the process network namespace. First check for confusion between an OpenWrt logical interface and a kernel device, or different interfaces inside and outside Docker.
+- `Multicast: interface ... does not exist`: the device is absent from the process network namespace. First check for confusion between an OpenWrt logical interface and a kernel device, different interfaces inside and outside Docker, or a configured VLAN subinterface such as `eth0.12` that the system has not created yet.
 - `Failed to bind to upstream interface ...`: possible causes include a wrong interface name, insufficient permissions, unsupported platform behavior, or a container namespace mismatch. It does not necessarily mean the program stopped the later connection attempt.
 - `Multicast: Successfully joined group`: the kernel accepted the membership socket option. It does not prove that an IGMP report left the interface, the upstream accepted membership, media returned, or the firewall admitted it.
 - `Multicast: No data received for 1 seconds, closing connection`: no multicast media was processed during the timeout window. This message and the resulting HTTP 503 are symptoms, not root causes. Extending the timeout alone cannot repair completely absent packet delivery.

diff --git a/docs/en/guide/quick-start.md b/docs/en/guide/quick-start.md
@@ -51,7 +51,7 @@ After installation, find "rtp2httpd" in the "Services" menu of the LuCI manageme
 
 1. **Basic Settings - Enable**: Check to enable rtp2httpd
 2. **Basic Settings - Port**: Default 5140, or customize
-3. **Network & Performance - Upstream Interface**: Set to IPTV network interface
+3. **Network & Performance - Upstream Interface**: Set to IPTV network interface. For 802.1Q tagged multicast, select an existing kernel VLAN subinterface (such as `eth0.12` / `wan.85`), not the physical parent; see [Configuration Reference](/en/reference/configuration).
 
 ### Optional Configuration Items
 

diff --git a/docs/en/reference/configuration.md b/docs/en/reference/configuration.md
@@ -42,6 +42,21 @@ Unix socket listen paths must be absolute and must not contain whitespace. At st
 > In addition to global configuration, you can specify upstream interfaces per request using the `r2h-ifname` and `r2h-ifname-fcc` URL parameters. See [URL Formats](/en/guide/url-formats) for details.
 > [!TIP]
 > On FreeBSD, specifying upstream interfaces is not supported except for multicast.
+> [!NOTE]
+> The upstream interface name must be a kernel device shown by `ip link`. If multicast frames carry an 802.1Q VLAN tag (for example an EPON stick or SFU in full pass-through), do not point rtp2httpd at the physical parent (such as `eth0`), and do not expect the daemon to strip tags. The kernel does not deliver tagged frames to UDP sockets on the parent interface.
+>
+> Create the VLAN subinterface on the system first, then point the upstream interface at that **existing** device:
+>
+> ```bash
+> ip link add link eth0 name eth0.12 type vlan id 12
+> ip link set eth0.12 up
+> ```
+>
+> ```ini
+> upstream-interface-multicast = eth0.12
+> ```
+>
+> The kernel device name is not always `eth0.12`: OpenWrt DSA may use `wan.85`, `eth0.85`, or `br-vlan85`; iKuai VLAN mixed mode may use a virtual line name such as `vwan*`. Writing `eth0.12` in the config does not create the interface. If it is missing, the log reports `Multicast: interface eth0.12 does not exist`.
 
 ### Performance Optimization
 
@@ -188,6 +203,9 @@ upstream-interface = eth0
 # upstream-interface-rtsp = eth2       # RTSP
 # upstream-interface-http = eth3       # HTTP proxy
 #
+# For 802.1Q tagged multicast, use an existing VLAN subinterface, not the physical parent:
+# upstream-interface-multicast = eth0.12
+#
 # Hybrid configuration example: Use eth0 by default, but use faster eth1 for FCC
 # upstream-interface = eth0
 # upstream-interface-fcc = eth1

diff --git a/docs/guide/ai-network-diagnosis.md b/docs/guide/ai-network-diagnosis.md
@@ -43,6 +43,7 @@
 - 组播、RTSP、HTTP 的优先级：URL 参数 `r2h-ifname` > 对应的 `upstream-interface-multicast` / `upstream-interface-rtsp` / `upstream-interface-http` > `upstream-interface` > 系统路由表。
 - FCC 的优先级：URL 参数 `r2h-ifname-fcc` > `r2h-ifname` > `upstream-interface-fcc` > `upstream-interface` > 系统路由表。
 - OpenWrt 的 UCI 逻辑接口名可能是 `wan85`，实际内核设备名却可能是 `wan.85`、`eth0.85` 或 `br-vlan85`。rtp2httpd 需要的是 `ip link` 能看到的实际设备名。
+- 带 802.1Q VLAN tag 的组播不会出现在物理口的 UDP socket 上。必须把上游接口指到已经存在的 VLAN 子接口（如 `eth0.12`）；rtp2httpd 不会创建 VLAN，也不会在进程内剥 tag。
 - FreeBSD 只支持为组播显式指定接口；FCC、RTSP 和 HTTP 单播必须依赖系统路由表。
 - 如果日志出现 `Failed to bind to upstream interface`，不要忽略它。绑定失败后，后续流量可能继续按照系统路由发送，最终走向错误出口。
 - 每个播放 URL 或服务定义里也可能包含接口参数，即使全局设置看起来正确，也要检查实际请求 URL。
@@ -58,7 +59,7 @@
 
 【关键日志含义】
 
-- `Multicast: interface ... does not exist`：进程所在网络命名空间内不存在该设备。优先检查 OpenWrt 逻辑接口与内核设备名是否混淆，以及 Docker 内外看到的接口是否一致。
+- `Multicast: interface ... does not exist`：进程所在网络命名空间内不存在该设备。优先检查 OpenWrt 逻辑接口与内核设备名是否混淆、Docker 内外看到的接口是否一致，以及配置的 `eth0.12` 这类 VLAN 子接口是否已经由系统创建。
 - `Failed to bind to upstream interface ...`：可能是接口名错误、权限不足、平台不支持或容器命名空间不匹配。它不等于程序已停止后续连接。
 - `Multicast: Successfully joined group`：只表示内核接受了加组 socket 选项，不代表 IGMP 报文已经发出、上游接受了成员关系、媒体包已经返回，或防火墙已经放行。
 - `Multicast: No data received for 1 seconds, closing connection`：表示超时窗口内没有处理到组播媒体包。它和随后出现的 HTTP 503 是症状，不是根因。单纯延长超时无法修复完全收不到包的问题。

diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
@@ -52,7 +52,7 @@ uclient-fetch -q -O - https://raw.githubusercontent.com/stackia/rtp2httpd/main/s
 
 1. **基本设置 - 启用**：勾选启用 rtp2httpd
 2. **基本设置 - 端口**：默认 5140，也可以自定义
-3. **网络与性能 - 上游接口**：设置为 IPTV 网络接口
+3. **网络与性能 - 上游接口**：设置为 IPTV 网络接口。若组播带 802.1Q VLAN tag，应选择已经存在的内核 VLAN 子接口（如 `eth0.12` / `wan.85`），而不是物理口；详见 [配置参数详解](../reference/configuration.md)
 
 ### 可选配置项
 

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -42,6 +42,21 @@ Unix socket 监听路径必须是绝对路径，且路径中不能包含空白
 > 除了全局配置外，还可以在每个请求的 URL 中通过 `r2h-ifname` 和 `r2h-ifname-fcc` 参数指定上游接口，详见 [URL 格式说明](../guide/url-formats.md)。
 > [!TIP]
 > FreeBSD 系统下不支持指定除组播外的接口。
+> [!NOTE]
+> 上游接口名必须是 `ip link` 能看到的内核设备名。如果组播帧带 802.1Q VLAN tag（例如 EPON 猫棒 / SFU 全透传），不要把物理口（如 `eth0`）配给 rtp2httpd，也不要指望程序自己剥 tag。内核不会把带 tag 的帧交给物理口上的 UDP socket。
+>
+> 正确做法是先在系统里创建对应的 VLAN 子接口，再把上游接口指到这个**已经存在**的设备：
+>
+> ```bash
+> ip link add link eth0 name eth0.12 type vlan id 12
+> ip link set eth0.12 up
+> ```
+>
+> ```ini
+> upstream-interface-multicast = eth0.12
+> ```
+>
+> 常见内核设备名不一定是 `eth0.12`：OpenWrt DSA 可能是 `wan.85`、`eth0.85` 或 `br-vlan85`；爱快「基于 VLAN 的混合模式」可能是 `vwan*` 一类虚拟线路名。只在配置里写 `eth0.12` 并不会创建该接口；接口不存在时日志会报 `Multicast: interface eth0.12 does not exist`。
 
 ### 性能优化
 
@@ -186,6 +201,9 @@ upstream-interface = eth0
 # upstream-interface-rtsp = eth2       # RTSP
 # upstream-interface-http = eth3       # HTTP 代理
 #
+# 若组播带 802.1Q VLAN tag，填已经存在的 VLAN 子接口，而不是物理口：
+# upstream-interface-multicast = eth0.12
+#
 # 混合配置示例：默认使用 eth0，但 FCC 使用更快的 eth1
 # upstream-interface = eth0
 # upstream-interface-fcc = eth1

diff --git a/ikuai-support/rtp2httpd/app/option.json b/ikuai-support/rtp2httpd/app/option.json
@@ -55,8 +55,8 @@
     "default": "",
     "attrname": "RTP2HTTPD_UPSTREAM_INTERFACE",
     "label": {
-      "en": "Default upstream interface (empty = routing table)",
-      "zh": "默认上游接口（留空按照路由表）"
+      "en": "Default upstream interface (empty = routing table). For tagged multicast use eth0.12, not eth0",
+      "zh": "默认上游接口（留空按照路由表；带 VLAN tag 时填 eth0.12 等已存在的子接口）"
     },
     "required": false,
     "scope": "config",
@@ -68,8 +68,8 @@
     "default": "",
     "attrname": "RTP2HTTPD_UPSTREAM_INTERFACE_MULTICAST",
     "label": {
-      "en": "Multicast upstream interface (overrides default)",
-      "zh": "组播上游接口（覆盖默认）"
+      "en": "Multicast upstream interface (overrides default; use eth0.12 for tagged multicast)",
+      "zh": "组播上游接口（覆盖默认；带 VLAN tag 时填 eth0.12 等已存在的内核设备名）"
     },
     "required": false,
     "scope": "config",

diff --git a/openwrt-support/luci-app-rtp2httpd/htdocs/luci-static/resources/view/rtp2httpd.js b/openwrt-support/luci-app-rtp2httpd/htdocs/luci-static/resources/view/rtp2httpd.js
@@ -488,7 +488,7 @@ return view.extend({
       "upstream_interface",
       _("Upstream Interface"),
       _(
-        "Default interface for all upstream traffic (multicast, FCC and RTSP). Leave empty to use routing table."
+        "Default interface for all upstream traffic (multicast, FCC and RTSP). Leave empty to use routing table. For 802.1Q tagged IPTV multicast, select the existing VLAN subinterface (e.g. eth0.12), not the physical parent."
       )
     );
     o.noaliases = true;
@@ -502,7 +502,7 @@ return view.extend({
       "upstream_interface_multicast",
       _("Upstream Multicast Interface"),
       _(
-        "Interface to use for multicast (RTP/UDP) upstream media stream (default: use routing table)"
+        "Interface to use for multicast (RTP/UDP) upstream media stream (default: use routing table). For tagged multicast, use the VLAN subinterface (e.g. eth0.12)."
       )
     );
     o.noaliases = true;

diff --git a/openwrt-support/luci-app-rtp2httpd/po/zh_Hans/rtp2httpd.po b/openwrt-support/luci-app-rtp2httpd/po/zh_Hans/rtp2httpd.po
@@ -68,8 +68,11 @@ msgstr "分别配置组播、FCC 和 RTSP 的接口"
 #: htdocs/luci-static/resources/view/rtp2httpd.js:436
 msgid ""
 "Default interface for all upstream traffic (multicast, FCC and RTSP). Leave "
-"empty to use routing table."
-msgstr "所有上游流量（组播、FCC 和 RTSP）使用的默认接口。留空则使用路由表。"
+"empty to use routing table. For 802.1Q tagged IPTV multicast, select the "
+"existing VLAN subinterface (e.g. eth0.12), not the physical parent."
+msgstr ""
+"所有上游流量（组播、FCC 和 RTSP）使用的默认接口。留空则使用路由表。"
+"组播带 802.1Q VLAN tag 时，请选择已经存在的 VLAN 子接口（如 eth0.12），不要选物理口。"
 
 #: htdocs/luci-static/resources/view/rtp2httpd.js:327
 msgid "Edit the content of /etc/rtp2httpd.conf"
@@ -183,8 +186,10 @@ msgstr "用于 RTSP 单播上游媒体流的接口（默认：使用路由表）
 #: htdocs/luci-static/resources/view/rtp2httpd.js:450
 msgid ""
 "Interface to use for multicast (RTP/UDP) upstream media stream (default: use "
-"routing table)"
-msgstr "用于组播（RTP/UDP）上游媒体流的接口（默认：使用路由表）"
+"routing table). For tagged multicast, use the VLAN subinterface (e.g. eth0.12)."
+msgstr ""
+"用于组播（RTP/UDP）上游媒体流的接口（默认：使用路由表）。"
+"带 VLAN tag 的组播请使用 VLAN 子接口（如 eth0.12）。"
 
 #: htdocs/luci-static/resources/view/rtp2httpd.js:359
 msgid "Listen Addresses"

diff --git a/rtp2httpd.conf b/rtp2httpd.conf
@@ -61,6 +61,9 @@ verbosity = 1
 # Specific interfaces (override upstream-interface when set)
 # Interface for multicast (RTP/UDP) traffic
 ;upstream-interface-multicast = iptv
+# For 802.1Q tagged multicast, use an existing VLAN subinterface
+# (e.g. eth0.12). rtp2httpd does not create VLANs or strip tags.
+;upstream-interface-multicast = eth0.12
 # Interface for FCC unicast traffic
 ;upstream-interface-fcc = iptv
 # Interface for RTSP unicast traffic