Skip to content

About

Multi-line WAN aggregation engine for Cudy TR3600 / OpenWrt 25.12 — nftables + iproute2, no kmods, OpenClash coexistence, per-flow balancing + MPTCP roadmap (GPL-2.0)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

多线路带宽聚合 · Cudy TR3600 / OpenWrt 25.12 设计与开发包

仓库:https://github.com/obsidianplusplus/multiline-wan · 版本 v0.2.0 · License: GPL-2.0-only(见 LICENSE / ATTRIBUTIONS.md)

状态:设计 + 可部署代码交付,尚未在路由器上应用(按你的要求"先不实际应用")。 所有部署脚本默认 DRY-RUN(只打印、不执行),只有显式 --apply --yes 才真正改配置;回滚脚本随包提供。 独立评审判定 最终 PASS(初评 PASS-WITH-FIXES → 修复后复核升级 PASS;BLOCKER 0,7 项 MAJOR / 15 项 MINOR 全部修复并复验), 评审报告与修复复核附录见 review/review.md。 2026-10-30 优化轮(已实装):调研 GitHub 生态(mwan3/mwan3-nft 3.x、pbr/mwan4、prometheus-node-exporter-lua、OpenMPTCProuter/glorytun 等)与论文/标准(BFD、RFC 2439 阻尼、ECMP、flowlet、Jain、MPTCP),落地 10 项增强:并行探测+RTT/丢包、惩罚盒/回切抑制、每 WAN 计数器 + mlwan stats/Prometheus、4 种调度器、外部 mark 护栏、自动旁路直连网段、探测目标豁免、nft -j 计数解析、conntrack flush 检测门控、GPL-2.0 许可+归属。详见 docs/optimizations.md。

1. 这个包解决什么问题

让这台 Cudy TR3600(OpenWrt 25.12-SNAPSHOT-CUDY)支持以下入网入口组合,并做多线路调度 + 带宽叠加:

模式 入网入口 保留的有线 LAN 需要牺牲 适合场景
M1 双有线 eth0 + eth1(eth1 改第二 WAN) ❌ 无(LAN 只走 WiFi) 唯一有线 LAN 口 两条独立宽带/上游,走有线最稳
M2 有线+WiFi eth0 + WiFi STA 上行 ✅ 保留 eth1 需关 MLO;一个频段的 AP/信道受限 主宽带 + 手机热点/邻居 WiFi 备份或叠加
M3 三线混合 eth0 + eth1 + WiFi STA ❌ 无 同上 + 有线 LAN 双宽带 + WiFi 备份(下载机/多设备场景)
M4 WiFi 为主/纯 WiFi 一个或两个 radio 的 STA ✅ 视配置 该频段 AP 关闭或受限 无法布线、仅有多个 WiFi 上游
M5 VLAN 逻辑多线 eth0.10 / eth0.20… 或 eth1 trunk ✅ 视配置 上游必须支持 802.1q/VLAN 多拨 上游是光猫多 VLAN、支持多拨的环境

受固件限制,USB 网卡 / USB WiFi / 手机 USB 共享网络不可用(厂商快照缺失 usbnet 内核模块,且官方 kmod 源与内核版本不匹配),物理入口上限就是上面这些。

2. 先说清"带宽聚合"能到什么程度(很重要)

能力 实现方式 效果
多连接/多设备带宽叠加(本期实现) 自研多 WAN 引擎:按"每条连接"加权分流到健康线路(conntrack 粘滞,同一连接不会跳线) 多线程下载、BT、多设备同时上网可以跑满多条线之和;单个 TCP 连接仍然只走一条线
路由器本机应用(如本机 Transmission/BT)参与叠加 仅 balance-proxy 模式(输出链给本机新连接打标);默认 skip 模式只均衡 LAN 转发的直连流量 本机 BT 建议用 balance-proxy + output_exclude 固定代理服务器 IP
真·单流聚合(高阶、可选) MPTCP:内核已启用 MPTCP,但需要一台 支持 MPTCP 的 VPS 做对端(Go 系代理不能用 mptcpize;Go≥1.24 有 GODEBUG=multipathtcp=1 未验证路线) 单条 TCP 连接也能用上多条线的总带宽;代价是需要 VPS、UDP/QUIC 不支持、NAT/MTU 复杂

详见 docs/design.md 与 docs/true-aggregation.md。

2.1 优化轮增强(已实装,借鉴 GitHub/论文)

增强 说明 借鉴来源
探测加固 全部上行×目标并行探测;RTT/EWMA(α=0.3)/丢包/投票进入 status/json;默认 3 个跨 AS 目标 + 2/3 共识;boot/换网关 20s grace;失败后 3s 快探(±1s 整数抖动) mwan3 3.7 mwan3track、RFC 5880 BFD
惩罚盒 DOWN +1000 惩罚、120s 半衰衰减、≥2000 抑制(≤600s,到点强制释放)、恢复后 60s 回切 hold-down、物理 ifdown 快速失败 RFC 2439 / RFC 7196、mwan3 score 语义
计数与质量指标 nft 命名 counters(只统计引擎分类流量)+ mlwan stats:每线字节份额/目标份额/误差、Jain permille、CV、RTT/loss/penalty;daemon 每轮原子写 metrics.prom mwan3 计数器/mwan3-lb-test、Jain 1984、Prometheus textfile
调度器 sched=random|rr|hash|source,W=在线权重和、精确区间(3:2→0-2/3-4,无 100 槽取整);ct mark 粘滞仍是主机制 nftables wiki、mwan3 3.7 numgen inc mod W、RFC 2991/2992
外部 mark 护栏 选路前 meta mark != 0 return,绝不覆盖 OpenClash 0x162 / pbr / mihomo routing-mark mwan3 3.7 非破坏 mark 语义
自动旁路 auto_bypass=1:从 ip -4 route 直连前缀生成 @mlwan_connected,pre/out 链跳过(防把 VLAN/VPN 目的地误均衡) mwan3rtmon/populate_connected_set
探测豁免 @mlwan_probes 集合(health_targets+peer/网关)在 pre/out 跳过,避免 ping -I 探测被 balance-proxy 改路自伤 mwan3 track_gateway 经验、papers §B2
统计读取 nft -j JSON + jsonfilter 优先解析 counters(文本回退) nftables 1.1.6、prometheus-node-exporter-lua 模式
conntrack flush flush_conntrack=0 默认,运行时探测能力;本目标内核无 ctnetlink/无工具 → 只告警一次、no-op,不承诺生效 mwan3 flush_conntrack(代码未移植,能力探测)
许可/归属 GPL-2.0-only LICENSE + ATTRIBUTIONS(AGPL 项目仅借鉴思想不抄代码) 调研 §C

2.2 均衡验收方法(来自 papers §B1/B4,避免误判)

  • 真实流量是重尾的:不要用"连接数五五开"验收;用 mlwan stats 看字节份额。
  • 小流数下随机分配方差是常态:2 线 m=10 条新流时份额 CV≈31.6%,m=100 才≈10%;建议 ≥30–50 条新流/窗口再判断(mlwan stats --window N)。
  • 手工示例(mock 60/40KB):wan 60.0% / wan2 40.0%,Jain=961/1000,CV=20.0%,max share error=0.0% 即合格。

3. 目录结构(与仓库实际一致)

multiline-wan/
├── README.md                     # 本文件:总览/边界/上线前须知
├── LICENSE / ATTRIBUTIONS.md     # GPL-2.0 全文;借鉴来源/许可证归属清单
├── docs/
│   ├── device-profile.md         # 路由器实况档案(只读侦察,已核实)
│   ├── design.md                 # 总体设计(数据面/控制面/共存/回滚/测试)
│   ├── optimizations.md          # 优化轮:调研→落地→验证(按收益排序)
│   ├── true-aggregation.md       # MPTCP+VPS 真·单流聚合方案(可选)
│   └── validation-log.md         # 真机 nft -c 等设计验证日志
├── research/
│   ├── research.md               # 关键技术调研(mwan3/OpenClash/MPTCP/WiFi STA)
│   ├── optimizations-github.md   # GitHub 生态调研(可借鉴项目/许可证)
│   └── optimizations-papers.md   # 论文/算法调研(flowlet/ECMP/BFD/MPTCP/Jain)
├── review/review.md              # 独立评审报告(PASS-WITH-FIXES + 发现项/复验)
├── engine/                       # 自研多 WAN 引擎(POSIX sh + nftables + iproute2)
│   ├── mlwan                     # CLI:validate/plan/apply/stop/reload/status/json/doctor/health
│   ├── mlwan-lib.sh              # 配置解析/校验、nft 规则生成、ip rule/路由、OpenClash 闸门
│   ├── mlwan-engine              # 数据面 apply/stop(原子 nft -f)
│   ├── mlwan-health              # 健康监控 daemon(ubus/jsonfilter + ping -I + 滞回)
│   ├── mlwan.init / mlwan-hotplug / mlwan.config
│   └── README.md                 # 引擎架构/配置参考/CLI/排障/限制
├── deploy/                       # 分阶段部署脚本(默认 DRY-RUN)
│   ├── mlwan-deploy              # 总驱动(按阶段顺序执行)
│   ├── preflight.sh              # 只读体检:设备指纹/依赖/空间/冲突
│   ├── deps.sh                   # 依赖检查(不安装任何包)
│   ├── engine.sh                 # 安装/卸载引擎 + 服务控制
│   ├── uplink.sh                 # 双有线/有线+WiFi STA/WiFi-only/VLAN 场景配置
│   ├── openclash.sh              # 共存检查/切换模式/打印(不自动改 OC)
│   ├── rollback.sh               # 回滚(默认 FULL 回最早备份;--latest 只退最近阶段;--to 指定)
│   ├── lib/common.sh
│   └── README.md                 # 分阶段 runbook + 场景示例 + 回滚/排障
├── package/                      # OpenWrt apk 包骨架(将来可刷进固件)
│   ├── Makefile / sync-files.sh / README.md
│   └── files/…                   # 与 engine 同步的目标机 payload
└── tests/                        # mock 环境 + 离线测试(不碰设备)
    ├── run-dryrun.sh             # 65 用例(含优化轮回归/错误路径)
    ├── lib/assert.sh
    ├── mock/_dispatch            # nft/ip/uci/ubus/jsonfilter/ping/… 的 mock
    └── fixtures/…

4. 架构一句话

LAN/WiFi 客户端 ──► fw4(nft) ──► [OpenClash TUN? skb mark 0x162 → utun]
                                    │(未被代理的流量)
                                    ▼
                    nft table inet mlwan(钩子 -140,晚于 OpenClash 的 -150)
                    新连接:ct mark = 加权随机(健康线路)  同连接:粘滞复用
                                    │
              ip rule fwmark 0x100..0x103 → table 100..103 → 各 WAN 的默认路由
                                    │
            eth0(WAN1) │ eth1(WAN2) │ wifi-STA(WAN3) │ vlan(可选)
                                    │
                     健康检查守护进程(ping -I + 阈值/滞回)──► 动态重生成规则

5. 与现有 OpenClash 的关系(必须先读)

路由器目前跑 OpenClash TUN 模式(skb mark 0x162、ip rule pref 1888、table 354 → utun、DNS 全部指向 127.0.0.1#7874)。 多 WAN 引擎不会改动这些规则(跳过 0x162/utun/本地网段/fake-ip,表 354 与 pref 1888 完全不碰),两者叠加有三种模式:

模式 说明 适用
skip(默认,最稳) 只调度 LAN 转发的直连流量(实测 OpenClash 对国内直连会提前 return、不打 0x162)。代理流量仍由 clash 决定出口;路由器本机应用(本机 Transmission/BT、DNS、更新)不参与均衡;外部 skb mark 一律不覆盖 保留代理优先;国内直连/备份流量获得多 WAN 增益
balance-proxy(实验) 额外生成 output 链,给本机发起的新连接(含 clash 出站、本机 BT)打多 WAN 标记;用 output_exclude 固定代理服务器 IP;健康探测目标 @mlwan_probes 被豁免(防 ping -I 自伤) 想让本机应用/代理连接也按连接分散到多条线(单连接仍单线)
bypass-direct(Phase-2 实验,能力有限) 指定 LAN 源"绕开 OpenClash"。实测限制:OpenClash 在 dstnat(-100) 对所有 LAN TCP redirect 到 :7892,本引擎无法阻止 TCP 的 NAT 重定向,该模式实际只对 UDP/ICMP 生效;TCP 需 mihomo 侧 DIRECT/源 bypass + fake-ip DNS 分流 仅作研究/后续 Phase-2,不建议生产使用

两种实验模式上线前必须真机小流量验证(详见 docs/design.md §7、review/review.md §7)。 引擎的安全闸门:balance-proxy/bypass-direct 在检测不到 OpenClash TUN 标记时会拒绝 apply(--force 可覆盖并告警)。

6. 将来上线时的流程(本次不执行)

  1. 维护窗口,记录现状快照(nft list ruleset / ip rule / 配置备份),确认可回滚。
  2. 只读体检:deploy/preflight.sh(板型/内核/nft/iproute2/闪存/mwan3/USB 驱动检查)+ deploy/deps.sh + deploy/openclash.sh check。
  3. 先做回滚演练:写入少量改动(install + uplink)后立即 deploy/rollback.sh list,确认默认 FULL 回滚(最早 pre-deployment 备份)能逐字节恢复全部 /etc/config。--latest 只回退最近阶段;注意它在未加 --keep-files 时仍会移除引擎文件(--to 可指定某份备份)。
  4. 选入口模式:deploy/uplink.sh dual-wired|wired-wifi|wifi-only|vlan …(先 DRY-RUN 看将写入的 uci)。
  5. 安装并启动引擎:deploy/engine.sh install --apply --yes → mlwan apply --apply → mlwan status / mlwan doctor。
  6. 分场景验证:多线程下载 + mlwan stats(字节份额/Jain/CV/份额误差,≥30–50 新流/窗口)+ metrics.prom 采集、断线故障注入(观察快探 ~13–16s 检出、恢复受 failback hold-down 约束)、重启自愈、OpenClash 回归(0x162/1888/354/utun/dnsmasq 未变)。
  7. 需要真·单流聚合再上 VPS + MPTCP 模块(见 docs/true-aggregation.md)。

7. 已知限制与风险(诚实版)

  • 单连接不叠加:L3 负载均衡的物理限制(mwan3 等同样做不到);只有 MPTCP/VPS 路线能突破。
  • 默认 skip 模式不均衡路由器本机流量:本机 Transmission/BT 只有在 balance-proxy 下才参与多线(review F-06 已修正文档)。
  • bypass-direct 对 TCP 无效:OpenClash dstnat 在 -100 把所有 LAN TCP 重定向到 :7892,-140 的 mark 无法阻止;该模式仅 UDP/ICMP 生效(review F-05 已修正文档)。
  • WiFi STA 上行的硬约束:同一 radio 的 AP 与 STA 必须同信道 + 同 Beacon 间隔;Cudy-MLO 必须关闭;DFS 信道受雷达事件影响;2.4G STA 实际速率通常只有几十到一两百 Mbps。
  • eth1 改 WAN 后没有有线 LAN 口(M1/M3),只剩 WiFi AP;恢复需回滚。
  • 本固件不能装 kmod:引擎完全基于 nftables + iproute2 + 用户态脚本;IPv6 多线聚合、TUN 类隧道不在本期范围。
  • 双 NAT 环境:WAN 是 192.168.1.2 接上级 192.168.1.1,多线时各上游的端口映射/UPnP 需在上游单独做。
  • 性能是估算不是实测:双核 Filogic + 2×1G 口,多流合计预期约 1.2–1.7 Gbps(受 CPU/NAT/OpenClash 影响);WiFi STA 另受空口限制。本交付未在设备上部署实测。
  • 旧连接故障切换不会自动迁移(本机无 ctnetlink/conntrack 工具,flush_conntrack 为 no-op),旧流靠超时/应用层恢复。
  • sched=hash/source 是确定性/按设备粘滞模式,公平性不优于 random(papers §B1);生产默认 random 或 rr。
  • mlwan stats 的 nft 计数器在表重载/重启后归零(引擎会标记 reset,Prometheus 抓取间隔应小于重载频率);跨重启历史不保留。
  • 惩罚盒/failback 参数(120s 半衰、2000 抑制、60s 回切)是文献缩放默认值,真实 ISP 抖动下建议按 mlwan status/logread 调优。

8. 交付物审阅建议

  1. 先看 docs/device-profile.md(设备事实)→ docs/design.md(设计与取舍)。
  2. 看 research/research.md(为什么自研而不是 mwan3、OpenClash 集成依据、MPTCP 结论)。
  3. 读 engine/README.md + deploy/README.md,并跑 tests/run-dryrun.sh(本地 mock,不碰路由器)与 sh -n 检查。
  4. 看 docs/optimizations.md(优化轮调研→落地→验证 + 后续路线)。
  5. 最后看 review/review.md(独立评审结论、修复记录与真机上线前验证顺序)。

9. 本次交付的验证证据(摘要)

  • 本地:tests/run-dryrun.sh 69/69 全绿(含优化轮/复核修复 16 个回归用例、错误路径与真机格式 fixture);全部 shell sh -n 通过;package/sync-files.sh --check 通过。
  • 真机只读:优化轮后 4 sched × 4 共存模式 = 16 份生成规则集在目标机 nft -c -f 16/16 通过(nft 1.1.6,含命名计数器、probes/connected 集合、外部 mark 护栏、精确权重 map);25 个交付 shell 文件在目标机 busybox ash -n 25/25 通过;preflight/openclash check 实机 FAIL=0;全程未执行 nft -f(无 -c)、uci commit、service 变更或包安装,路由器配置未被修改。
  • 独立评审:最终 PASS(初评 PASS-WITH-FIXES:0 BLOCKER / 7 MAJOR / 15 MINOR → 修复后复核升级 PASS;优化轮复核 PASS-WITH-FIXES(O-01 MAJOR + 6 MINOR)→ 修复 O-01..O-07 后复核升级 PASS;69/69 用例、真机 18 份规则集 nft -c 全过)。

About

Multi-line WAN aggregation engine for Cudy TR3600 / OpenWrt 25.12 — nftables + iproute2, no kmods, OpenClash coexistence, per-flow balancing + MPTCP roadmap (GPL-2.0)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages