HevSocks5Tunnel 安装配置详细教程

HevSocks5Tunnel 是一个高性能、低开销的 tun2socks 实现，采用 C 语言编写，基于 LwIP 轻量级网络协议栈和协程化 IO 调度技术。它支持 Linux、Android、FreeBSD、macOS 和 Windows 平台，能够将系统流量通过 SOCKS5 代理转发。

一、安装方式

HevSocks5Tunnel 支持多种安装方式，你可以根据操作系统选择最适合的方法。

1.1 使用预编译二进制文件（推荐）

从 GitHub Releases 下载对应平台的二进制文件：

bash 复制代码

# Linux/macOS/FreeBSD
# 下载对应架构的二进制文件后
chmod +x hev-socks5-tunnel
sudo mv hev-socks5-tunnel /usr/local/bin/

# 验证安装
hev-socks5-tunnel --version

预编译二进制支持的平台包括：

Linux: x86_64, i686, arm64, arm32, mips64, riscv64 等 28 种架构
macOS: arm64 (Apple Silicon) 和 x86_64 (Intel)，支持通用二进制
FreeBSD: x86_64
Windows: win64（包含 wintun.dll）

1.2 OpenWrt 包管理器安装

对于 OpenWrt 24.10+ 版本，可直接通过 opkg 安装：

bash 复制代码

# 安装
opkg install hev-socks5-tunnel

# 配置文件位置
/etc/config/hev-socks5-tunnel

# 重启服务
/etc/init.d/hev-socks5-tunnel restart

1.3 Docker 部署

使用 Docker 可以快速部署，通过环境变量配置：

XML 复制代码

# docker-compose.yml
version: "3.9"

services:
  tun:
    image: ghcr.io/heiher/hev-socks5-tunnel:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      SOCKS5_ADDR: 192.168.1.100   # SOCKS5 服务器地址
      SOCKS5_PORT: 1080             # SOCKS5 服务器端口
      LOG_LEVEL: warn               # 日志级别

1.4 从源码编译

bash 复制代码

# 克隆仓库（必须使用 --recursive 拉取子模块）
git clone --recursive https://github.com/heiher/hev-socks5-tunnel
cd hev-socks5-tunnel

# 编译
make

# 安装
sudo make install

# 输出文件位置
# 二进制: bin/hev-socks5-tunnel
# 安装后: /usr/local/bin/hev-socks5-tunnel

编译选项说明：

选项	命令	说明
静态链接	`make ENABLE_STATIC=1`	生成完全静态链接的可执行文件
调试构建	`make ENABLE_DEBUG=1`	包含调试符号
详细输出	`make V=1`	显示完整编译命令

二、配置文件

HevSocks5Tunnel 使用 YAML 格式的配置文件。

2.1 基础配置文件

创建配置文件 tunnel.yml：

bash 复制代码

# 隧道接口配置
tunnel:
  name: tun0                    # TUN 设备名称
  mtu: 9000                     # MTU 大小
  ipv4:                         # IPv4 地址配置
    address: 10.0.0.2           # 虚拟网卡 IP
    gateway: 10.0.0.1           # 虚拟网关
    prefix: 30                  # 子网掩码位数
  ipv6:                         # IPv6 地址配置（可选）
    address: 'fc00::2'
    gateway: 'fc00::1'
    prefix: 126

# SOCKS5 代理服务器配置
socks5:
  address: 127.0.0.1            # SOCKS5 服务器地址
  port: 1080                    # SOCKS5 服务器端口
  # username: user              # 可选：认证用户名
  # password: pass              # 可选：认证密码
  udp: 'udp'                    # UDP 模式: 'udp' (UDP-in-UDP) 或 'tcp' (UDP-in-TCP)

# 日志配置
misc:
  log-level: info               # 日志级别: debug, info, warn, error
  # log-file: /var/log/tunnel.log  # 可选：日志文件路径

2.2 配置参数详解

tunnel 部分：

参数	类型	说明	默认值
`tunnel.name`	string	TUN 设备名称	tun0
`tunnel.mtu`	int	MTU 大小	1500
`tunnel.ipv4.address`	string	虚拟网卡 IPv4 地址	198.18.0.1
`tunnel.ipv4.gateway`	string	虚拟网关地址	198.18.0.1
`tunnel.ipv4.prefix`	int	子网掩码位数	30

socks5 部分：

参数	类型	说明	默认值
`socks5.address`	string	SOCKS5 服务器地址	必填
`socks5.port`	int	SOCKS5 服务器端口	1080
`socks5.udp`	string	UDP 模式：`udp` 或 `tcp`	udp
`socks5.username`	string	认证用户名（可选）	-
`socks5.password`	string	认证密码（可选）	-

UDP 模式说明：

udp（UDP-in-UDP）：标准 SOCKS5 UDP 转发，适用于大多数场景
tcp（UDP-in-TCP）：将 UDP 封装在 TCP 中传输，适用于受限网络环境

三、运行与路由配置

3.1 基本启动

bash 复制代码

# 启动隧道（需要 root 权限）
sudo hev-socks5-tunnel tunnel.yml

3.2 Linux 策略路由配置

启动隧道后，需要配置路由规则来避免环路并实现流量转发。

第一步：添加 SOCKS5 服务器绕过路由（避免环路）

bash 复制代码

# 假设 SOCKS5 服务器地址为 192.168.1.100，物理网卡为 eth0
# 添加高优先级路由，让 SOCKS5 服务器的流量绕过 TUN 设备
sudo ip route add 192.168.1.100 dev eth0 metric 10
sudo ip -6 route add 2001:db8::1 dev eth0 metric 10   # IPv6 版本

第二步：配置策略路由

bash 复制代码

# 方法一：全局模式（所有流量都走代理）
sudo ip route add default dev tun0 metric 20
sudo ip -6 route add default dev tun0 metric 20

# 方法二：规则模式（指定 UID 的用户走代理）
sudo ip rule add uidrange 1000-1000 lookup 100
sudo ip route add default dev tun0 table 100

3.3 macOS/FreeBSD 路由配置

BSD 系统的路由配置语法不同：

bash 复制代码

# 添加 SOCKS5 服务器绕过路由
sudo route add -net 192.168.1.100/32 10.0.2.2

# 设置默认路由走 TUN 设备
sudo route change -inet default -interface tun0
sudo route change -inet6 default -interface tun0

四、验证与测试

4.1 检查 TUN 设备

bash 复制代码

# 查看 TUN 设备状态
ip addr show tun0

# 预期输出应包含配置的 IP 地址
# 例如: inet 10.0.0.2/30 scope global tun0

4.2 测试连通性

bash 复制代码

# 检查路由是否生效
ip route show

# 测试网络连通性（应通过代理访问）
curl -I https://www.google.com

# 查看当前出口 IP
curl https://ip.sb

4.3 查看日志

如果配置了日志文件，可以查看运行状态：

bash 复制代码

tail -f /var/log/tunnel.log

五、常见问题与解决方案

5.1 权限不足

问题 : open /dev/net/tun: permission denied

解决:

bash 复制代码

# 使用 root 运行，或添加 CAP_NET_ADMIN 权限
sudo hev-socks5-tunnel tunnel.yml

5.2 路由环路

问题: 网络完全不通，流量死循环

解决: 检查 SOCKS5 服务器地址的绕过路由是否正确配置

bash 复制代码

# 确认绕过路由存在且优先级高于默认路由
ip route show | grep "dev eth0"

5.3 UDP 无法转发

问题: UDP 应用（如 DNS、游戏）无法正常工作

解决:

确认 SOCKS5 服务器支持 UDP 转发
尝试切换 UDP 模式：

bash 复制代码

socks5:
  udp: 'tcp'    # 改为 UDP-in-TCP 模式

5.4 内存不足（嵌入式设备）

在内存受限的设备上，可以减少缓冲区大小：

bash 复制代码

misc:
  task-stack-size: 24576        # 任务栈大小（字节）
  tcp-buffer-size: 4096         # TCP 缓冲区大小
  limit-nofile: 1024            # 文件描述符限制

六、高级使用

6.1 作为库集成

HevSocks5Tunnel 可以作为 C 库集成到其他程序中：

cpp 复制代码

#include "hev-main.h"

int main() {
    // 使用配置文件启动
    int result = hev_socks5_tunnel_main("/etc/tunnel.yml", -1);
    
    // 从另一线程停止
    // hev_socks5_tunnel_quit();
    
    return result;
}

6.2 服务端配套

如需完整的 UDP over TCP 支持，服务端可使用 hev-socks5-server。

七、快速参考

常用命令汇总：

操作	命令
启动隧道	`sudo hev-socks5-tunnel config.yml`
添加绕过路由	`sudo ip route add <SOCKS5_IP> dev eth0 metric 10`
全局模式路由	`sudo ip route add default dev tun0 metric 20`
检查 TUN 设备	`ip addr show tun0`
查看路由表	`ip route show`
停止隧道	`pkill hev-socks5-tunnel`

HevSocks5Tunnel 的核心优势在于高性能 和低资源占用。在 RK3399 设备（1Gbps 网卡）上测试显示，其 CPU 使用率远低于同类实现。配置的关键在于正确设置路由规则以避免环路------这是保证隧道正常工作的核心步骤。