ARM OpenWrt iPhone USB 共享网络 -- 免编译快速安装指南

适用场景：ARM 路由器刷了 ImmortalWrt/OpenWrt mediatek/filogic 固件，想用 iPhone USB 共享网络，但官方源里找不到 kmod-usb-net-ipheth 包。
本文提供预编译模块，3 分钟完成安装，无需自行编译固件。

背景

在 x86 OpenWrt 上，iPhone USB 共享只需 opkg install kmod-usb-net-ipheth 即可。但许多 ARM 平台（如 mediatek/filogic）的 ImmortalWrt 固件仓库中并不包含这个包，opkg 搜索结果为空。

iPhone（iOS 18+）的 USB 网络共享使用的是苹果私有的 ipheth 协议（不是 RNDIS/CDC-ECM），没有这个驱动，插入 iPhone 后不会出现网络接口。

我的是向日葵蒲公英 AX3000 X1Pro，刷了 Cudy TR3000 v1 的 ImmortalWrt 固件，遇到了同样的问题。以下是完整的解决方案，包含预编译模块和一键安装脚本。

适用条件（请先确认！）

预编译模块必须与你的内核版本精确匹配，否则 insmod 会报错。

请 SSH 登录路由器执行以下命令，确认信息一致：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 查看内核版本
uname -r
# 预期输出: 6.6.95

# 查看固件版本
cat /etc/openwrt_release | grep REVISION
# 预期输出: DISTRIB_REVISION='r33397-2806544a5a'

# 查看架构
cat /etc/openwrt_release | grep TARGET
# 预期输出: DISTRIB_TARGET='mediatek/filogic'

cat /etc/openwrt_release | grep ARCH
# 预期输出: DISTRIB_ARCH='aarch64_cortex-a53'

项目	要求
固件	ImmortalWrt 24.10-SNAPSHOT r33397-2806544a5a
内核	6.6.95
架构	aarch64_cortex-a53
平台	mediatek/filogic
设备	Cudy TR3000 v1（ubootmod）或刷同款固件的其他设备

⚠️ 如果你的版本不一致：预编译模块可能无法加载。请跳到文末附录：自行编译部分。

快速安装（3 步搞定）

第 1 步：安装依赖包

SSH 登录路由器，安装 iPhone USB 共享所需的用户空间工具：

1
2
opkg update
opkg install usbmuxd libimobiledevice libimobiledevice-utils usbutils

各包作用：

usbmuxd：USB 守护进程，负责触发 iPhone 的"信任此电脑"对话框
libimobiledevice / libimobiledevice-utils：与 iPhone 通信的库和工具
usbutils：提供 lsusb 命令，用于调试

第 2 步：下载并加载 ipheth 驱动

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 下载预编译的 ipheth.ko
cd /tmp
wget -O ipheth.ko https://www.zhangxiaokun.top/downloads/ipheth-6.6.95-aarch64_cortex-a53.ko
# 如果 wget 不行，可以用 curl：
# curl -L -o /tmp/ipheth.ko https://www.zhangxiaokun.top/downloads/ipheth-6.6.95-aarch64_cortex-a53.ko

# 加载模块
insmod /tmp/ipheth.ko

# 验证
lsmod | grep ipheth
# 应输出: ipheth  12288  0

dmesg | tail -1
# 应输出: usbcore: registered new interface driver ipheth

第 3 步：持久化（重启后自动加载）

1
2
3
4
mkdir -p /lib/modules/6.6.95
cp /tmp/ipheth.ko /lib/modules/6.6.95/
echo -e "usbnet\nipheth" > /etc/modules.d/ipheth
depmod -a

网络和防火墙配置

配置 WAN 接口

iPhone USB 共享作为新的 WAN 接口（ipheth 驱动会创建 eth2 接口）：

1
2
3
4
5
6
7
uci set network.wan_usb=interface
uci set network.wan_usb.proto=dhcp
uci set network.wan_usb.device=eth2
uci set network.wan_usb.peerdns=0
uci set network.wan_usb.delegate=0
uci add_list network.wan_usb.dns=223.6.6.6
uci commit network

加入防火墙 WAN 区域

1
2
3
uci add_list firewall.@zone[1].network=wan_usb
uci commit firewall
/etc/init.d/firewall restart

重启网络服务

1
/etc/init.d/network restart

mwan3 兼容修复（重要！）

如果你的路由器没有安装 mwan3 多 WAN 负载均衡，可以跳过此节。

如果你的路由器使用了 mwan3，它会通过 fwmark 策略路由将 iPhone 的流量错误地路由到旧 WAN，导致 ping 和 curl 都失败（但 DNS 正常）。

症状：ping -I eth2 8.8.8.8 失败，但 nslookup baidu.com 172.20.10.1 正常。

修复：添加 ip rule 让 iPhone 网段的流量绕过 mwan3 的 fwmark 路由：

1
2
# 临时生效
ip rule add from 172.20.10.0/28 lookup main priority 1500

持久化（创建 hotplug 脚本）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cat > /etc/hotplug.d/iface/90-wan_usb-routes << 'EOF'
case "$ACTION" in
    ifup)
        if [ "$INTERFACE" = "wan_usb" ]; then
            ip rule add from 172.20.10.0/28 lookup main priority 1500 2>/dev/null
            logger -t wan_usb "Added ip rule for iPhone USB traffic"
        fi
        ;;
esac
EOF
chmod +x /etc/hotplug.d/iface/90-wan_usb-routes

使用方法

确保 ipheth 模块已加载：lsmod | grep ipheth
确保 usbmuxd 在运行：/etc/init.d/usbmuxd start
将 iPhone 插入路由器 USB 口
iPhone 屏幕弹出 “信任此电脑” → 点击信任
等待 5-10 秒，检查接口：

1
2
3
4
5
ip link show
# 应出现 eth2 接口，状态为 UP

ifstatus wan_usb
# 应显示获取到 IP（通常为 172.20.10.x）

测试连通性：

1
2
ping -c 3 8.8.8.8
# 应 0% 丢包

iPhone 热插拔脚本

如果拔插 iPhone 后接口不自动恢复，可以添加以下热插拔脚本 /etc/hotplug.d/usb/40-usbmuxd：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
cat > /etc/hotplug.d/usb/40-usbmuxd << 'EOF'
case "$ACTION" in
    bind)
        dev=/sys$DEVPATH
        [ ! -f /tmp/iPhone.lock ] && [ -d ${dev}/net ] &&
        {
            readlink ${dev}/driver | grep -q ipheth &&
            {
                sleep 5
                carrier_path=${dev}/net/*/carrier
                carrier=`cat ${carrier_path}`
                [ "${carrier}" = "0" ] &&
                {
                    touch /tmp/iPhone.lock
                    logger -p daemon.error -t iPhone ${carrier_path} = ${carrier}
                    logger -p daemon.error -t iPhone `/usr/bin/usbreset iPhone`
                    /etc/init.d/usbmuxd restart
                    sleep 5 && rm -f /tmp/iPhone.lock &
                }
            }
        }
        ;;
esac
EOF
chmod +x /etc/hotplug.d/usb/40-usbmuxd

故障排查

问题 1：insmod 报错 `module ipheth: .gnu.link_once.this_module section size must match`

原因：内核版本不匹配。ipheth.ko 是为 6.6.95 编译的，你的内核版本不同。

解决：执行 uname -r 确认版本。如果不同，请参考文末附录：自行编译。

问题 2：插入 iPhone 后不弹出"信任此电脑"

原因：usbmuxd 未安装或未运行。

解决：

1
2
3
opkg update
opkg install usbmuxd libimobiledevice libimobiledevice-utils
/etc/init.d/usbmuxd start

验证 iPhone 是否被识别：

1
2
3
4
5
lsusb
# 应显示: Bus 001 Device xxx: ID 05ac:12a8 Apple Inc. iPhone

idevice_id -l
# 应显示 iPhone 序列号

问题 3：eth2 接口出现但状态为 DOWN

1
2
3
4
5
6
# 手动启动接口
ip link set eth2 up
ifup wan_usb

# 检查状态
ifstatus wan_usb

问题 4：ping 失败但 DNS 正常（mwan3 干扰）

症状：nslookup 能解析域名，ping 172.20.10.1 通，但 ping 8.8.8.8 不通。

原因：mwan3 的 fwmark 策略路由将流量错误路由到旧 WAN。

解决：执行 mwan3 兼容修复部分的命令。

验证方法：

1
2
3
4
5
6
7
8
# 查看路由决策
ip route get 8.8.8.8
# 正确: via 172.20.10.1 dev eth2
# 错误: via 192.168.1.1 dev eth0 (走了旧 WAN)

# 查看 ip rule
ip rule show | grep 1500
# 应有: 1500: from 172.20.10.0/28 lookup main

问题 5：防火墙阻止了 eth2 流量

如果重启防火墙后仍无法上网，检查 nftables 规则中 eth2 是否在 WAN 接口列表中：

1
2
nft list chain inet fw4 srcnat | grep eth2
# 应包含: oifname { "eth0", "eth2", ... }

如果没有 eth2，说明防火墙配置未生效，重新执行：

1
2
3
uci add_list firewall.@zone[1].network=wan_usb
uci commit firewall
/etc/init.d/firewall restart

一键安装脚本

如果你不想一步步操作，可以直接运行以下一键脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
#!/bin/sh
set -e

echo "=== 1. 安装依赖包 ==="
opkg update
opkg install usbmuxd libimobiledevice libimobiledevice-utils usbutils

echo "=== 2. 下载 ipheth.ko ==="
cd /tmp
wget -O ipheth.ko https://www.zhangxiaokun.top/downloads/ipheth-6.6.95-aarch64_cortex-a53.ko

echo "=== 3. 加载模块 ==="
insmod /tmp/ipheth.ko
lsmod | grep ipheth || { echo "模块加载失败！请检查内核版本。"; exit 1; }

echo "=== 4. 持久化 ==="
mkdir -p /lib/modules/6.6.95
cp /tmp/ipheth.ko /lib/modules/6.6.95/
echo -e "usbnet\nipheth" > /etc/modules.d/ipheth
depmod -a

echo "=== 5. 配置网络接口 ==="
uci -q set network.wan_usb=interface || true
uci set network.wan_usb.proto=dhcp
uci set network.wan_usb.device=eth2
uci set network.wan_usb.peerdns=0
uci set network.wan_usb.delegate=0
uci add_list network.wan_usb.dns=223.6.6.6
uci commit network

echo "=== 6. 配置防火墙 ==="
existing=$(uci get firewall.@zone[1].network 2>/dev/null)
echo "$existing" | grep -q 'wan_usb' || uci add_list firewall.@zone[1].network=wan_usb
uci commit firewall
/etc/init.d/firewall restart

echo "=== 7. mwan3 兼容（如果安装了 mwan3）==="
if opkg list-installed | grep -q mwan3; then
    ip rule add from 172.20.10.0/28 lookup main priority 1500 2>/dev/null || true
    cat > /etc/hotplug.d/iface/90-wan_usb-routes << 'INNER'
case "$ACTION" in
    ifup)
        if [ "$INTERFACE" = "wan_usb" ]; then
            ip rule add from 172.20.10.0/28 lookup main priority 1500 2>/dev/null
            logger -t wan_usb "Added ip rule for iPhone USB traffic"
        fi
        ;;
esac
INNER
    chmod +x /etc/hotplug.d/iface/90-wan_usb-routes
    echo "mwan3 兼容规则已添加"
fi

echo "=== 8. 热插拔脚本 ==="
cat > /etc/hotplug.d/usb/40-usbmuxd << 'INNER'
case "$ACTION" in
    bind)
        dev=/sys$DEVPATH
        [ ! -f /tmp/iPhone.lock ] && [ -d ${dev}/net ] &&
        {
            readlink ${dev}/driver | grep -q ipheth &&
            {
                sleep 5
                carrier_path=${dev}/net/*/carrier
                carrier=`cat ${carrier_path}`
                [ "${carrier}" = "0" ] &&
                {
                    touch /tmp/iPhone.lock
                    logger -p daemon.error -t iPhone ${carrier_path} = ${carrier}
                    logger -p daemon.error -t iPhone `/usr/bin/usbreset iPhone`
                    /etc/init.d/usbmuxd restart
                    sleep 5 && rm -f /tmp/iPhone.lock &
                }
            }
        }
        ;;
esac
INNER
chmod +x /etc/hotplug.d/usb/40-usbmuxd

echo "=== 9. 重启网络 ==="
/etc/init.d/network restart

echo ""
echo "============================================"
echo "  安装完成！请将 iPhone 插入路由器 USB 口"
echo "  在 iPhone 上点击「信任此电脑」"
echo "  然后执行: ifstatus wan_usb"
echo "============================================"

💡 使用方法：将上面的脚本保存为 install_ipheth.sh，然后 sh install_ipheth.sh 即可。

附录：自行编译（不同固件版本）

如果你的固件版本与本文不同，需要自行编译。以下是简要步骤。

环境要求

一台 Linux 服务器（Ubuntu/Debian，4GB+ 内存）
安装编译依赖：apt install build-essential swig python3-pyelftools

编译步骤

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# 1. 克隆源码
git clone https://github.com/immortalwrt/immortalwrt.git
cd immortalwrt

# 2. 切换到你的固件对应的 commit
#    在路由器上执行: cat /etc/openwrt_release | grep REVISION
#    找到对应的 commit hash
git checkout <你的commit-hash>

# 3. 更新 feeds
./scripts/feeds update -a
./scripts/feeds install -a

# 4. 配置（关键项）
cat > .config << 'EOF'
CONFIG_TARGET_mediatek=y
CONFIG_TARGET_mediatek_filogic=y
CONFIG_TARGET_mediatek_filogic_DEVICE_cudy_tr3000-v1-ubootmod=y
CONFIG_PACKAGE_kmod-usb-net-ipheth=y
CONFIG_PACKAGE_kmod-mediatek_hnat=y
CONFIG_PACKAGE_kmod-ipt-nat=y
CONFIG_PACKAGE_kmod-nf-ipt=y
CONFIG_PACKAGE_kmod-ipt-core=y
CONFIG_PACKAGE_kmod-nf-reject=y
EOF
make defconfig

# 5. 编译
export FORCE_UNSAFE_CONFIGURE=1
make -j$(nproc)

# 6. 编译产物
# .ko 文件:
#   build_dir/target-aarch64_cortex-a53_musl/linux-mediatek_filogic/linux-6.6.95/drivers/net/usb/ipheth.ko
# ipk 包:
#   bin/targets/mediatek/filogic/packages/kmod-usb-net-ipheth_*.ipk

⚠️ 编译常见坑

坑 1：HNAT 依赖导致编译失败

ImmortalWrt 的 mediatek 平台有 HNAT（硬件 NAT）驱动，它依赖 IP_NF_NAT。如果 .config 中没有启用 kmod-ipt-nat 等包，autoconf.h 不会定义 CONFIG_NET_MEDIATEK_HNAT_MODULE，导致 mtk_eth_soc.c 编译时出现大量未定义宏错误。

解决：确保 .config 中同时启用：

CONFIG_PACKAGE_kmod-ipt-nat=y
CONFIG_PACKAGE_kmod-nf-ipt=y
CONFIG_PACKAGE_kmod-ipt-core=y
CONFIG_PACKAGE_kmod-nf-reject=y

坑 2：opkg 安装 ipk 报内核哈希不匹配

opkg 会检查内核编译哈希（如 6.6.95~7d51a94b...），自行编译的哈希与路由器上的不同。

解决：不用 opkg，直接提取 .ko 文件用 insmod 加载。vermagic 匹配即可：

1
2
3
4
# 验证 vermagic
strings ipheth.ko | grep vermagic
# 应输出: vermagic=6.6.95 SMP mod_unload aarch64
# 与路由器的 uname -r 一致即可

坑 3：以 root 编译报错 you should not run configure as root

1
export FORCE_UNSAFE_CONFIGURE=1

总结

步骤	命令
安装依赖	`opkg install usbmuxd libimobiledevice libimobiledevice-utils usbutils`
下载驱动	`wget -O /tmp/ipheth.ko https://www.zhangxiaokun.top/downloads/ipheth-6.6.95-aarch64_cortex-a53.ko>`
加载驱动	`insmod /tmp/ipheth.ko`
持久化	`cp /tmp/ipheth.ko /lib/modules/6.6.95/ && echo -e "usbnet\nipheth" > /etc/modules.d/ipheth`
配置接口	`uci set network.wan_usb=interface ...` (见上文)
配置防火墙	`uci add_list firewall.@zone[1].network=wan_usb` (见上文)
插入 iPhone	信任此电脑 → `ifup wan_usb` → `ping 8.8.8.8`

如果本文对你有帮助，欢迎分享给同样被 iPhone USB 共享困扰的路由器玩家。

环境信息
路由器：向日葵蒲公英 AX3000 X1Pro（刷 Cudy TR3000 v1 固件）
固件：ImmortalWrt 24.10-SNAPSHOT r33397-2806544a5a
内核：6.6.95 (aarch64_cortex-a53, mediatek/filogic)
iPhone：iOS 18.7.7
编译环境：Ubuntu Linux 服务器

背景#

适用条件（请先确认！）#

快速安装（3 步搞定）#

第 1 步：安装依赖包#

第 2 步：下载并加载 ipheth 驱动#

第 3 步：持久化（重启后自动加载）#

网络和防火墙配置#

配置 WAN 接口#

加入防火墙 WAN 区域#

重启网络服务#

mwan3 兼容修复（重要！）#

使用方法#

iPhone 热插拔脚本#

故障排查#

问题 1：insmod 报错 module ipheth: .gnu.link_once.this_module section size must match#

问题 2：插入 iPhone 后不弹出"信任此电脑"#

问题 3：eth2 接口出现但状态为 DOWN#

问题 4：ping 失败但 DNS 正常（mwan3 干扰）#

问题 5：防火墙阻止了 eth2 流量#

一键安装脚本#

附录：自行编译（不同固件版本）#

环境要求#

编译步骤#

⚠️ 编译常见坑#

总结#

背景