hev-socks5-tunnel 透明代理网关部署指南

Posted on

hev-socks5-tunnel 透明代理网关部署指南

项目概述

hev-socks5-tunnel 是一个基于 TUN 设备的 SOCKS5 隧道工具，可以将系统级流量透明转发到 SOCKS5 代理服务器。本指南介绍如何将其部署为局域网透明代理网关。

系统架构

  • 网关机器：运行 hev-socks5-tunnel，作为局域网的透明代理网关
  • 局域网客户端：将网关设为默认路由，流量自动经过代理
  • 上游 SOCKS5：实际的代理服务器

核心组件

  • TUN 虚拟网卡：捕获需要代理的流量
  • 策略路由：将局域网流量导向 TUN 设备
  • iptables 规则：管理流量转发
  • fwmark 标记：避免代理流量循环

1. 构建二进制文件

使用 Docker 构建

Dockerfile

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
# ---------- Build stage ----------
FROM debian:bookworm-slim AS builder

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
    git ca-certificates build-essential pkg-config \
 && rm -rf /var/lib/apt/lists/*

# 可通过 --build-arg HEV_REF=v2.13.0 指定版本/标签/提交
ARG HEV_REF=master
WORKDIR /src

RUN git clone --recursive https://github.com/heiher/hev-socks5-tunnel . \
 && git checkout "${HEV_REF}" \
 && git submodule update --init --recursive \
 && make -j"$(nproc)"

# ---------- Runtime stage ----------
FROM debian:bookworm-slim

# 运行时常见依赖（可按需删除）
RUN apt-get update && apt-get install -y --no-install-recommends \
    iproute2 libcap2-bin ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# 拷贝编译产物
COPY --from=builder /src/bin/hev-socks5-tunnel /usr/local/bin/hev-socks5-tunnel

# 可选：暴露配置/数据目录（如需）
# VOLUME ["/etc/hev-socks5-tunnel"]

# 不设置 ENTRYPOINT，便于按需传参；需要时可启用：
# ENTRYPOINT ["/usr/local/bin/hev-socks5-tunnel"]

构建并提取二进制文件

1
2
3
4
docker run -d --name my_tun2socks_container tun2socks:latest sleep infinity
docker cp my_tun2socks_container:/usr/local/bin/hev-socks5-tunnel ./
docker stop my_tun2socks_container
docker rm my_tun2socks_container

2. 配置文件

/etc/hev-socks5-tunnel/config.yml

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
tunnel:
  # 虚拟 TUN 接口
  name: tun0
  mtu: 8500
  multi-queue: true
  # TUN 口地址（内网保留网段，用于与宿主区分）
  ipv4: 198.18.0.1
  ipv6: "fc00::1"
  # 可选：启动/停止时的钩子脚本（如自定义路由）
  post-up-script: /etc/hev-socks5-tunnel/up.sh
  pre-down-script: /etc/hev-socks5-tunnel/down.sh

socks5:
  # 上游 SOCKS5 服务器
  address: 127.0.0.1
  port: 1080
  # UDP 中继模式：udp（原生）或 tcp（UDP-over-TCP 兼容模式）
  udp: "udp"
  # 可选：握手管线化（减少 RTT）
  pipeline: true
  # 可选：认证
  # username: "user"
  # password: "pass"
  # 将连接打上此 fwmark，便于在系统路由中"旁路上游"避免环路
  mark: 438

# 可选：DNS 映射（将域名解析映射到专用网段，降低泄露风险）
#mapdns:
#  address: 198.18.0.2      # 本地映射 DNS 监听地址
#  port: 53
#  network: 240.0.0.0       # 专用映射网段（仅供本机内部映射）
#  netmask: 240.0.0.0
#  cache-size: 10000

# 可选：其他运行参数与日志
# misc:
#   task-stack-size: 86016      # 任务栈大小（字节）
#   tcp-buffer-size: 65536      # TCP 缓冲（字节）
#   connect-timeout: 5000       # 连接超时（毫秒）
#   read-write-timeout: 60000   # 读写超时（毫秒）
#   log-file: stderr            # stdout / stderr / 文件路径
#   log-level: warn             # debug / info / warn / error
#   pid-file: /run/hev-socks5-tunnel.pid
#   limit-nofile: 65535         # （可选）提升文件句柄上限
misc:
  task-stack-size: 86016    # = 20480 + 65536
  tcp-buffer-size: 65536
  connect-timeout: 5000     # ms
  read-write-timeout: 180000
  log-file: stderr
  log-level: warn
# pid-file: /run/hev-socks5-tunnel.pid
  limit-nofile: 65535

配置说明

  • tunnel.ipv4/ipv6：TUN 设备的虚拟 IP，选择不与现有网络冲突的地址段
  • socks5.address/port：上游 SOCKS5 服务器地址，通常是本机运行的代理客户端
  • socks5.mark：重要！用于标记代理流量，防止路由循环
  • misc.limit-nofile：提高文件句柄限制，支持更多并发连接

3. 网络配置脚本

/etc/hev-socks5-tunnel/up.sh（启动时配置）

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
#!/bin/bash
# up.sh — 配置 hev-socks5-tunnel 网关（仅 IPv4，幂等合并版）
set -e

# ===== 基本变量（可通过环境变量覆盖）=====
SELF_IP="${SELF_IP:-192.168.2.42}"
LAN_NET="${LAN_NET:-192.168.2.0/24}"
TUN_IF="${TUN_IF:-tun0}"
TBL_NAME="${TBL_NAME:-tun_socks}"   # /etc/iproute2/rt_tables 中映射到 100
TBL_NUM="${TBL_NUM:-100}"
MARK="${MARK:-438}"

# 自动识别 LAN 接口（可预先导出 LAN_IF 覆盖）
if [ -z "${LAN_IF:-}" ]; then
  LAN_IF="$(ip -o -4 addr show | awk -v ip="${SELF_IP}" '$4 ~ ip"/" {print $2; exit}')"
fi
: "${LAN_IF:?无法识别 LAN 接口，请手动设置 SELF_IP 或 LAN_IF}"
echo "LAN_IF=${LAN_IF} TUN_IF=${TUN_IF} TBL=${TBL_NAME}(${TBL_NUM}) MARK=${MARK}"

# ===== 内核参数 =====
sysctl -w net.ipv4.ip_forward=1 \
         net.ipv4.conf.all.rp_filter=0 \
         net.ipv4.conf.default.rp_filter=0 \
         net.ipv4.conf.all.accept_redirects=0 \
         net.ipv4.conf.default.accept_redirects=0 \
         net.ipv4.conf.all.send_redirects=0 \
         net.ipv4.conf.default.send_redirects=0 >/dev/null

# ===== 路由表映射 =====
grep -qE "^[[:space:]]*${TBL_NUM}[[:space:]]+${TBL_NAME}\$" /etc/iproute2/rt_tables || \
  echo "${TBL_NUM} ${TBL_NAME}" >> /etc/iproute2/rt_tables

# ===== 路由与策略规则 =====
# 100 表（tun_socks）→ tun0
ip route replace default dev "$TUN_IF" table "$TBL_NAME"

# main 表不得出现 “default dev tun0”
ip route del default dev "$TUN_IF" 2>/dev/null || true

# 旁路标记：hev-socks5-tunnel 自身连接 mark=438 走 main
ip rule add fwmark "$MARK" lookup main priority 50 2>/dev/null || true

# 旁路 LAN/本机/容器网段（避免被表100吸走）
ip rule add iif "$LAN_IF" to "${SELF_IP}/32" lookup main priority 900 2>/dev/null || true
ip rule add iif "$LAN_IF" to "$LAN_NET"      lookup main priority 900 2>/dev/null || true
ip rule add iif "$LAN_IF" to 172.17.0.0/16   lookup main priority 900 2>/dev/null || true
ip rule add iif "$LAN_IF" to 172.18.0.0/16   lookup main priority 900 2>/dev/null || true

# LAN 其余流量 → 表100（经 tun0）
ip rule add iif "$LAN_IF" lookup "$TBL_NAME" priority 1000 2>/dev/null || true

# ===== 防火墙（转发放行）=====
iptables -C FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT 2>/dev/null || \
  iptables -I FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -C FORWARD -i "$LAN_IF" -o "$TUN_IF" -j ACCEPT 2>/dev/null || \
  iptables -I FORWARD -i "$LAN_IF" -o "$TUN_IF" -j ACCEPT
iptables -C FORWARD -i "$TUN_IF" -o "$LAN_IF" -j ACCEPT 2>/dev/null || \
  iptables -I FORWARD -i "$TUN_IF" -o "$LAN_IF" -j ACCEPT

echo "配置完成。"

/etc/hev-socks5-tunnel/down.sh（停止时清理）

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
#!/bin/bash
# down.sh — 清理 hev-socks5-tunnel 网关配置（仅 IPv4，等幂）
set -e

# ===== 变量（可通过环境变量覆盖）=====
SELF_IP="${SELF_IP:-192.168.2.42}"
LAN_NET="${LAN_NET:-192.168.2.0/24}"
TUN_IF="${TUN_IF:-tun0}"
TBL_NAME="${TBL_NAME:-tun_socks}"   # 映射到 100
TBL_NUM="${TBL_NUM:-100}"
MARK="${MARK:-438}"

# 自动识别 LAN 接口（亦可预先导出 LAN_IF 覆盖）
if [ -z "${LAN_IF:-}" ]; then
  LAN_IF="$(ip -o -4 addr show | awk -v ip="${SELF_IP}" '$4 ~ ip"/" {print $2; exit}')"
fi
: "${LAN_IF:?无法识别 LAN 接口，请手动设置 SELF_IP 或 LAN_IF}"
echo "清理: LAN_IF=${LAN_IF} TUN_IF=${TUN_IF} TBL=${TBL_NAME}(${TBL_NUM}) MARK=${MARK}"

# ===== 删除策略路由 =====
# 旁路标记
ip rule del fwmark "$MARK" lookup main priority 50 2>/dev/null || true

# 旁路本机/LAN/容器网段
ip rule del iif "$LAN_IF" to "${SELF_IP}/32" lookup main priority 900 2>/dev/null || true
ip rule del iif "$LAN_IF" to "$LAN_NET"      lookup main priority 900 2>/dev/null || true
ip rule del iif "$LAN_IF" to 172.17.0.0/16   lookup main priority 900 2>/dev/null || true
ip rule del iif "$LAN_IF" to 172.18.0.0/16   lookup main priority 900 2>/dev/null || true

# LAN → 代理表
ip rule del iif "$LAN_IF" lookup "$TBL_NAME" priority 1000 2>/dev/null || true
ip rule del iif "$LAN_IF" lookup "$TBL_NUM"  priority 1000 2>/dev/null || true

# ===== 清空代理表路由并移除误设默认路由 =====
ip route flush table "$TBL_NAME" 2>/dev/null || true
ip route flush table "$TBL_NUM"  2>/dev/null || true
ip route del default dev "$TUN_IF" 2>/dev/null || true   # 防止 main 表存在 default dev tun0

# ===== 删除 iptables 规则（与 up.sh 对应）=====
iptables -D FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT 2>/dev/null || true
iptables -D FORWARD -i "$LAN_IF" -o "$TUN_IF" -j ACCEPT 2>/dev/null || true
iptables -D FORWARD -i "$TUN_IF" -o "$LAN_IF" -j ACCEPT 2>/dev/null || true

# ===== 可选：恢复内核参数（按需启用）=====
sysctl -w net.ipv4.ip_forward=0 \
         net.ipv4.conf.all.rp_filter=1 \
         net.ipv4.conf.default.rp_filter=1 >/dev/null || true

echo "已清理 hev-socks5-tunnel 网关配置。"

脚本参数说明

需要根据实际网络环境修改以下参数：

  • LAN_NET：局域网网段（如 192.168.1.0/24）
  • SELF_IP：网关机器的局域网 IP
  • MARK：必须与 config.yml 中的 socks5.mark 一致

4. 部署步骤

4.1 创建目录结构

1
2
3
4
5
6
mkdir /etc/hev-socks5-tunnel
touch /etc/hev-socks5-tunnel/config.yml
cp up.sh down.sh /etc/hev-socks5-tunnel
cp hev-socks5-tunnel /usr/local/bin/hev-socks5-tunnel
chmod 0755 /etc/hev-socks5-tunnel/up.sh
chmod 0755 /etc/hev-socks5-tunnel/down.sh

4.2 创建 systemd 服务

/etc/systemd/system/hev-socks5-tunnel.service

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[Unit]
Description=hev-socks5-tunnel (with policy routing scripts)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/hev-socks5-tunnel /etc/hev-socks5-tunnel/config.yml

Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

4.3 启动服务

1
2
3
systemctl daemon-reload
systemctl enable --now hev-socks5-tunnel
systemctl status hev-socks5-tunnel

5. 客户端配置

在局域网内的客户端设备上，将默认网关改为网关机器的 IP（如 192.168.2.42）。

6. 故障排查

检查服务状态

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 查看服务状态
systemctl status hev-socks5-tunnel

# 查看日志
journalctl -u hev-socks5-tunnel -f

# 检查 TUN 设备
ip link show tun0
ip addr show tun0

# 检查路由规则
ip rule list
ip route show table 100

# 检查 iptables 规则
iptables -t filter -L FORWARD -n -v

# 测试连通性
curl --interface tun0 https://ipinfo.io/ip

# 客户端测试
curl -4s https://ipinfo.io/ip
dig @8.8.8.8 www.google.com +timeout=10 +retry=0

7. 进阶配置

7.3 DNS 防泄露

启用 config.yml 中的 mapdns 功能，或使用独立的 DNS 服务器（如 dnsmasq）。