企业官网建设流程全解析

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用

本指南深入解析 TEN-framework 仓库所依赖的 libwebsockets（lws）第三方库中路由监控子系统的完整设计：它如何通过 netlink 实时感知 Linux 路由表变化，如何在移动网络环境下快速识别“路由不可达”而非等待 TCP 超时，以及如何将路由事件联动到连接清理、DNS 排序、SMD 系统消息与强制门户检测（Captive Portal Detection）。读完本文，你将掌握LWS_WITH_NETLINK编译开关的作用、lws 内部路由表（routing table）与 wsi 的连接绑定关系，以及路由变化触发连接失效判定的完整源码级调用链。

为什么 lws 需要理解路由表

lws（libwebsockets）的核心事件循环是围绕 POSIX socket 构建的，其绝大多数行为都基于 socket 本身能够提供的有限信息。但在移动设备场景下，仅仅依赖 socket 状态远远不够：设备会在 Wi-Fi、蜂窝数据（LTE）等接口之间频繁切换，网络可能瞬间断开又重新恢复。而 POSIX socket 的表现与这种现实完全脱节——只要底层 TCP 连接没有收到错误，socket 会一直保持“已连接”状态，直到 TCP 超时机制介入，而这类超时通常以分钟为单位，对于实时性要求高的 WebSocket / 长连接应用来说几乎是灾难性的。

因此 lws 需要跨出 socket 的边界，主动监控并理解设备的路由表（routing table），并把它与现有连接动态关联起来。路由表和网关正是决定设备能否访问互联网的关键要素，这也是 lws 路由监控子系统的核心动机——源码注释中明确写道："We mainly focus on the routing table / gateways because those are the elements that decide if we can get on to the internet or not."（见 route.c）。

编译开关：Linux 下的 netlink 路由监控

在 Linux 设备上，可以通过编译选项启用基于 netlink 的路由监控：

-DLWS_WITH_NETLINK=1

在 lws 的顶层 CMake 配置中，该选项的定义与默认值如下（见 CMakeLists.txt）：

option(LWS_WITH_NETLINK "Monitor Netlink for Routing Table changes" ON)

即该选项默认开启（ON），并按需置为0关闭。启用后，lws 会在context / pt（per-thread，事件循环线程）启动时抓取一份当前路由表的快照（coldplug），此后根据 netlink 消息对这份快照进行增量维护。

源码层面，netlink 角色的实现位于 ops-netlink.c：

• 每个 context 只允许一个 netlink socket，创建于 pt[0]（we can only have one netlink socket，见 ops-netlink.c）；
• 该 socket 以socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE)方式创建，并订阅RTMGRP_LINK | RTMGRP_IPV4_ROUTE | RTMGRP_IPV4_IFADDR，启用 IPv6 时追加RTMGRP_IPV6_ROUTE | RTMGRP_IPV6_IFADDR（见 ops-netlink.c）；
• 启动早期通过RTM_GETROUTE+NLM_F_REQUEST | NLM_F_DUMP请求内核 dump 全部现有路由（见 ops-netlink.c），这一操作需要CAP_ADMIN或 root 权限，因此 lws 会在降权（dropping privs）之前完成；如果权限不足，仅记录告警并忽略（some systems deny access, just ignore）。

冷插（coldplug）阶段还有一个细节：只要路由表仍在持续填充，lws 会把“冷插完成”的判定定时器反复向后推迟 100ms（sul_nl_coldplug，见 ops-netlink.c），直到消息不再到来。这一点非常关键：若过早判定完成，后续到达的路由响应可能会误杀那些其实仍然可达的进行中连接。

netlink 事件类型与路由表维护

启用后，lws 的处理函数rops_handle_POLLIN_netlink（见 ops-netlink.c）会对内核通过 netlink socket 推送的多种 RTM 消息进行分发处理，一次读取可能包含多条合并消息：

其中RTM_NEWLINK的处理尤其值得注意：Linux 的路由事件（例如由 NetworkManager 在接口 up 时产生的改动）往往不会“体面地”回滚，接口 down 时内核不会为相关路由逐条发送 DELROUTE（源码注释：We don't get individual DELROUTEs for these）。因此 lws 必须自己监控链路 / 接口 down 事件，据此把该接口上的相关路由一并清除，这是原文档明确强调的补洞逻辑（见 ops-netlink.c）。

在解析路由属性时，lws 会提取RTA_SRC（首选源地址）、RTA_DST（目的网络）、RTA_GATEWAY（网关）、RTA_OIF/RTA_IIF（出/入接口索引）、RTA_PRIORITY（路由优先级，注意其为网络字节序，源码中做了手动字节序还原）等字段，存入内部路由对象lws_route_t（见 ops-netlink.c）。此外，RTM_NEWROUTE会过滤掉非RTN_UNICAST/RTN_LOCAL及带RTM_F_CLONED标志的路由“垃圾”，避免 /32 或广播等条目污染内部路由表（见 ops-netlink.c）。

基于路由表的连接判定与主动断开

原文档指出：无论是服务端还是客户端连接，lws 现在都会在 wsi 中保存对端 sockaddr，当路由表变化时，同一 pt 上的所有活跃 wsi 都会被逐一校验对端是否仍然可达。

对应源码验证：

• 服务端侧，被接纳的 socket 通过getpeername()填充wsi->sa46_peer（见 adopt.c）；客户端侧，连接建立时把排序后的 DNS 解析结果写入wsi->sa46_peer，并把对应路由的peer_route_uidx记录到 wsi（见 connect3.c）；
• 路由删除时，_lws_route_remove会调用_lws_route_pt_close_route_users(pt, robj->uidx)，将peer_route_uidx与删除路由一致的 wsi 以LWS_TO_KILL_ASYNC方式关闭（见 route.c 与 route.c）；
• 全量校验则由_lws_route_pt_close_unroutable遍历pt->fds，对每个 wsi 执行_lws_route_check_wsi：只要“无法为对端找到出站路由”或“本地源地址已消失”二者之一成立，该 wsi 就会被判定为不可路由并关闭（见 route.c）。

原文档给出了两个典型的失效场景，与源码逻辑一一对应：

1. 对端既无匹配的网络路由也无默认网关→ 连接被判定失效并关闭；
2. 移除最高优先级的网关路由→ 所有“没有网络路由精确匹配对端、只能依赖该网关”的连接被关闭。

而不受影响的连接会被保留，例如命中127.0.0.0/8这类未被波及网络路由的连接不会被误杀。这里的核心判断函数是_lws_route_est_outgoing（见 route.c）：遍历路由表，先寻找与目的地址在同一网络的精确路由（命中即返回，如192.168.0.0/24对192.168.0.1），否则在所有网关路由中挑选优先级（priority）最低者作为“预估出站路由”。IPv4/IPv6 混用的兼容性也在代码中有明确注释：IPv4 对 IPv4 网关、IPv4 经::ffff:x:x映射 IPv6 网关均可用，而 IPv6 直连 IPv4 网关不被支持（见 route.c）。

同一预估函数还被复用于DNS 结果排序：客户端在排序多个解析地址时，会调用_lws_route_est_outgoing判断哪个候选地址当前“最可路由”，从而把最优地址排到前面（见 sort-dns.c 与 sort-dns.c）。

值得一提的是路由指纹（uidx）机制：每条路由在加入 lws 内部路由表时都会获得一个唯一递增的uidx（见 route.c），wsi 连接时记录自己“估计使用的路由”的 uidx。这一设计专门应对 wlan → LTE 切换的场景：切换后可能仍存在有效的网关路由，但先前经由 wlan 网关建立的所有 TCP 连接本质上都已失效，通过 uidx 精确匹配即可定向清理，而不会波及使用其他路由的连接（见 route.c 的注释说明）。

与其他子系统的集成：SMD 消息与强制门户检测

路由变化不仅驱动连接清理，还会以系统消息（System Message Distribution，SMD）的方式广播给其他子系统：

1. 任意路由增删：当 SMD 被编译启用（LWS_WITH_SYS_SMD）时，lws 会发出网络类消息{"rt":"add|del"}（路由添加时为add，删除时为del），对应源码见 ops-netlink.c；
2. 涉及网关的路由变化：只要解析到路由属性RTA_GATEWAY就会置位gateway_change，并在消息循环结束后发出{"trigger":"cpdcheck","src":"gw-change"}（见 ops-netlink.c 与 ops-netlink.c）。若系统中同时启用了强制门户检测（Captive Portal Detection，CPD），该消息会触发一轮新的强制门户检测序列。

SMD 侧的定义可以在 smd/README.md 中找到对应说明：LWSSMDCL_NETWORK类别专门承载“captive portal detection requests and results”（见 smd/README.md），其 185 行附近对该消息类别有专门描述，而 210 行左右明确记载了{"trigger":"cpdcheck","src":"gw-change"}的触发语义（见 smd/README.md）。强制门户检测本身的探测步骤通过 Secure Streams Policy 中名为captive_portal_detect的 streamtype 来定义（见 smd/README.md）。

这套联动的业务意义在于：当用户设备从 Wi-Fi 切换到蜂窝网络（或反之）、或网关发生变更时，之前的网络很可能已被替换为需要认证的强制门户（如酒店/机场 Wi-Fi 登录页），lws 通过gw-change消息自动重新发起一次检测，从而让上层应用及时感知“网络是否真正可用”，而不是把连接挂在早已失效的链路上。

小结：一条完整的路由事件处理链路

综合原文档与源码，lws 路由监控子系统在 Linux 上的完整处理链路可以概括为：

1. context 启动 → 创建 netlink socket（需 CAP_ADMIN）→RTM_GETROUTEdump 现有路由完成冷插；
2. 内核持续推送RTM_NEWLINK/NEWADDR/DELADDR/NEWROUTE/DELROUTE/NEWNEIGH等事件；
3. 事件处理器增量维护内部路由表（含接口 down 时的路由兜底清理，并过滤非 unicast/local 及 cloned 路由）；
4. 路由变化触发两类动作：精确清理（按peer_route_uidx关闭受影响的 wsi）与全量校验（_lws_route_pt_close_unroutable逐 wsi 检查对端/源地址可达性）；
5. 通过 SMD 广播{"rt":"add|del"}；若涉及网关，再广播{"trigger":"cpdcheck","src":"gw-change"}触发强制门户重检测。

对于在 TEN-framework 这类面向对话式语音 AI 设备/嵌入式场景的构建中引入 lws 的开发者，理解这套机制有助于判断长连接在弱网、多网卡切换环境下的可靠性边界：只要保持LWS_WITH_NETLINK开启，lws 就能在数秒内感知路由级故障并主动关闭失效连接，避免应用层长时间阻塞在不可达的 socket 上。

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用