Router Systems zh - FrankoonG/hy2scale GitHub Wiki

🌐 English | 中文 | 한국어

路由器系统

HY2 SCALE 支持在带有 Docker 的路由器系统上运行，包括使用自定义或精简 Linux 内核的设备。这些环境通常有非标准的 netfilter 模块或受限的 iptables，HY2 SCALE 通过兼容模式自动处理。

在路由器系统上部署

推荐：非 Host 网络

docker run -d --name hy2scale \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

注意： 无需 --privileged。NET_ADMIN + NET_RAW 权限即可。

与标准 Linux 的主要差异

方面 标准 Linux 路由器系统
网络模式 --network host Bridge 网络 + 静态 IP
iptables 正常工作 可能不可用（自定义内核模块）
L2TP 模式 iptables DNAT TUN 捕获 + gvisor netstack
IKEv2 模式 iptables DNAT xfrm bridge + AF_PACKET
路由规则 iptables DNAT 不可用
权限 NET_ADMIN NET_ADMIN + NET_RAW
TUN 设备 自动创建 需要 --device /dev/net/tun

Compat 模式工作原理

自动检测

HY2 SCALE 使用 testIptablesAvailable() 自动检测受限环境：

testIptablesAvailable()
├── true  → 标准路径 (iptables DNAT + 透明代理)
└── false → 兼容路径 (TUN/xfrm + gvisor netstack)

该函数测试 iptables-legacy -t nat -L -n 是否成功。在使用自定义内核的路由器系统上可能失败，原因包括：

  • 内核包含标准 iptables 无法识别的专有 netfilter target
  • 标准 iptables 二进制无法解析这些自定义 target

无需手动配置 — Compat 模式会自动激活。在标准 Linux 上，兼容代码不会执行。

L2TP 兼容模式

标准 L2TP 使用 iptables 将 PPP 流量 DNAT 到透明代理。在 Compat 模式下替换为：

PPP 客户端
  ↓ (L2TP/IPsec 隧道)
xl2tpd + pppd (从地址池分配 IP)
  ↓
策略路由: ip rule from 192.168.25.0/24 lookup TABLE_Y
  ↓
内核 TUN 接口 (hy2cap0)
  ↓
gvisor netstack (TCP/UDP 转发器)
  ↓
通过 Mesh 进行出口路由
  1. 策略路由 将 PPP 子网流量导向路由表
  2. 路由表将流量发送到 内核 TUN 设备 (hy2cap0)
  3. gvisor netstack 从 TUN 读取数据包并提供 TCP/UDP 处理
  4. TCP/UDP 转发器将连接映射到用户并应用出口路由

IKEv2 兼容模式

标准 IKEv2 使用 iptables 将 xfrm 接口流量 DNAT。在 Compat 模式下替换为：

IKEv2 客户端
  ↓ (IKE + ESP 隧道, UDP 500+4500)
strongSwan (创建 xfrm 接口: ikec0, ikec1, ...)
  ↓
AF_PACKET 原始套接字捕获解封装的数据包
  ↓ (过滤 PACKET_OUTGOING 以避免回环)
gvisor netstack (TCP/UDP 转发器)
  ↓
通过 Mesh 进行出口路由
  ↓
响应: 原始 IP 套接字 → xfrm 接口 → 内核 ESP 封装
  1. strongSwan 为每个隧道创建 xfrm 接口 (if_id_in/out = %unique)
  2. AF_PACKET (SOCK_RAW) 从 xfrm 接口捕获解封装的数据包
  3. 过滤 PACKET_OUTGOING 数据包以防止捕获回环
  4. gvisor netstack 处理 TCP/UDP 并应用出口路由
  5. 响应通过 xfrm 接口注入回去进行 ESP 封装

该方法 完全绕过 FORWARD 链，FORWARD 链在非 Host 容器网络命名空间中是被阻塞的。

MTU 设置

路由器系统部署使用更低的 MTU 值以适应 ESP 开销：

协议 标准 MTU 路由器系统 MTU
L2TP 1280 1280
IKEv2 1400 1300

路由器系统上的 IKEv2 MSCHAPv2

IKEv2 MSCHAPv2 模式兼容路由器内置的 IKEv2 客户端：

  1. 在 TLS 页面上传 CA 证书
  2. 在 MSCHAPv2 模式下启用 IKEv2
  3. HY2 SCALE 自动使用 CA 签发服务器证书
  4. 使用 CA 证书和用户凭据配置路由器的 IKEv2 客户端

故障排查

VPN 服务显示为 "Limited"

这表示 iptables 不可用。在路由器系统上这是正常的 — Compat 模式以不同方式处理 VPN 流量。"Limited" 标识表示标准模式的 VPN 功能不可用，但 Compat 模式的等效功能已激活。

L2TP/IKEv2 不工作

  1. 检查权限：确保同时设置了 NET_ADMIN 和 NET_RAW
  2. 检查 TUN 设备：确保传递了 --device /dev/net/tun
  3. 启用调试模式 (DEBUG=true) 并检查日志：
    • iptables available: false — 确认 Compat 模式激活
    • TUN 设备创建消息
    • xfrm 接口创建消息

无法从局域网客户端连接

如果使用 Bridge 网络模式，请确保：

  1. 容器在 Docker 网络上有静态 IP
  2. 路由器有到 Docker 网络的路由
  3. 已配置 VPN 端口的端口转发（500、4500、1701）

调试日志

docker run -d --name hy2scale \
  -e DEBUG=true \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

调试模式日志包括：

  • iptables 检测结果
  • 权限和 Host 网络检查
  • TUN 设备读写操作
  • AF_PACKET 数据包捕获
  • gvisor netstack 转发器连接
  • 策略路由表设置

路由器重启后恢复

路由器重启后，Docker 容器会重启但可能丢失网络配置。请确保：

  1. Docker 网络使用正确的子网重建
  2. 容器使用 --restart unless-stopped
  3. 静态 IP 在 Docker 网络范围内

如果容器在重启后无法启动，使用相同的卷挂载删除并重建容器以保留配置。