criogaid/wg-resilient repository overview

⁠WG Resilient

使用 WireGuard、udp2raw FakeTCP 和可选 UDPspeeder FEC，在两台 Linux 主机之间建立加密隧道，适用于 UDP 受限或存在丢包的网络。

镜像同时支持服务器和客户端角色，提供 Linux amd64、arm64、arm/v7 架构。默认只路由隧道网段，不修改宿主机默认路由或 DNS，不提供全局 VPN、出口 NAT 或内置代理服务。FakeTCP 不是普通 TCP，不能通过 HTTP 反向代理转发。

源码与完整文档：https://github.com/Criogaid/wg-resilient⁠

⁠运行要求

• 两台内核支持 WireGuard 的 Linux 主机，安装 Docker Engine、Compose v2（支持 up --wait）、Bash 和 tar。
• 服务器具有客户端可访问的公网 IPv4 或解析到 IPv4 的域名；服务器另需 Git。
• 两端可拉取 criogaid/wg-resilient:latest，无需本地编译。
• 允许容器使用 host 网络、NET_ADMIN 和 NET_RAW。接口直接创建在宿主机，默认 wg0 不得已被占用。
• 服务器安全组与防火墙放行 TCP 4096，建议限制客户端来源。有上游 NAT 时需转发该端口；内部 UDP 51820、51821、51822 不应对公网开放。

本镜像面向 Linux 宿主机，不以 Windows 或 macOS Docker Desktop 为部署目标。

⁠快速开始

⁠1. 服务器生成配置

在服务器执行：

git clone https://github.com/Criogaid/wg-resilient.git ~/wg-resilient
cd ~/wg-resilient
bash quickstart.sh

填写服务器公网 IPv4 或域名，不加协议和端口。其余默认值为：FakeTCP 端口 4096、隧道网段 10.66.66.0/24、WireGuard MTU 1280、UDPspeeder 关闭。网段与现有路由冲突时需另选私有网段。

在最后的启动提示输入 y。也可稍后执行：

bash ~/wg-resilient/quickstart-output/server/deploy.sh

向导自动生成两端密钥、预共享密钥、udp2raw 口令及客户端安装包。需要自定义接口名时，以 WG_INTERFACE=wg-link bash quickstart.sh 启动向导。

⁠2. 将安装包传到客户端

使用 SCP 或 SFTP，将服务器的 ~/wg-resilient/quickstart-output/client.tar.gz 传至客户端的 ~/client.tar.gz。例如在服务器执行：

scp ~/wg-resilient/quickstart-output/client.tar.gz user@client-host:~/

替换 SSH 用户和地址。该包包含客户端私钥，只供一台客户端使用；不要公开，也不要传输整个服务器输出目录。

⁠3. 客户端启动

在客户端执行：

umask 077
mkdir ~/wg-client && \
  tar -xzf ~/client.tar.gz -C ~/wg-client && \
  bash ~/wg-client/client/deploy.sh

脚本会拉取镜像并等待容器健康检查。再次启动直接执行 bash ~/wg-client/client/deploy.sh。

⁠4. 验证连接

在客户端执行：

cd ~/wg-client/client
docker compose -p wg-resilient-client -f compose.yml exec wireguard-client wg show

检查近期的 latest handshake，并访问对端实际服务。容器 healthy 仅检查本地接口及进程，不能证明隧道已连通。

默认服务器隧道 IP 为 10.66.66.1，客户端为 10.66.66.2。应用使用 隧道IP:服务端口 连接。服务须监听隧道 IP 或适当的所有地址，并允许隧道防火墙访问；仅监听 127.0.0.1 的服务无法被对端直接访问。

⁠配置

向导部署后，在本机部署目录的 .env 修改参数，再执行 bash deploy.sh。

FEC 以额外带宽换取一定的丢包容忍度，不保证更快。WireGuard MTU 与 UDPspeeder 分片大小属于不同层，需根据实际链路调节。

WireGuard 配置位于部署目录的 config/server/wg0.conf 或 config/client/wg0.conf，以只读方式挂载到容器 /config/wg0.conf。保持服务器 ListenPort = 51820、客户端 Endpoint = 127.0.0.1:51821；不支持 AllowedIPs 中的默认路由 0.0.0.0/0 和 ::/0。

手动使用镜像时，另需设置容器环境变量 ROLE=server 或 ROLE=client、上述配置挂载及 host 网络权限。可通过 UDP2RAW_PASSWORD_FILE 指定容器内的口令文件，优先于 UDP2RAW_PASSWORD；需自行挂载文件。完整 Compose 模板与口令文件示例见配置参考⁠。

⁠运维

在客户端部署目录 ~/wg-client/client 执行：

# 状态与日志
docker compose -p wg-resilient-client -f compose.yml ps
docker compose -p wg-resilient-client -f compose.yml logs --tail 100

# 更新镜像或应用 .env 修改
bash deploy.sh

# 应用 WireGuard 配置修改
docker compose -p wg-resilient-client -f compose.yml restart

# 停止并移除容器
docker compose -p wg-resilient-client -f compose.yml down

服务器使用 ~/wg-resilient/quickstart-output/server，并将项目名改为 wg-resilient-server。正常停止清理本项目创建的接口和防 RST 规则，保留配置与密钥。

latest 会随发布更新。需要可重复部署时，固定 Docker Hub 上已有的版本标签或镜像 digest；升级前备份配置并记录原镜像。修改源代码或 README 不意味着 Docker Hub 镜像已同步更新。

无握手时检查公网地址、端口放行、密钥和口令配套、两端 FEC 开关。已握手但服务不可达时检查服务监听、防火墙和返回路由。客户端域名只在启动时解析，服务器 IP 变化后应重启客户端。

⁠安全与限制

• host 网络容器可以管理宿主机网络，只使用可信镜像和可信 WireGuard 配置，不需要 --privileged 或端口映射。
• 私钥、口令、安装包和日志按敏感数据处理。不要将同一客户端安装包用于多台机器。
• 同一宿主机同一角色默认仅运行一套；更换接口名不能解决内部端口冲突。
• 应用容器保留桥接网络时，需自行处理转发和返回路由。本项目不自动添加出口 NAT。
• 网络是否允许 FakeTCP 取决于实际设备和策略，不承诺穿透所有限制。