homelab-wireguard-vpn

Homelab WireGuard VPN 介绍

WireGuard 是一种快速、现代的 VPN 协议，适合用于远程访问家庭网络——它比 OpenVPN 配置更简单，速度也优于多数替代方案。

文档说明：所有配置示例展示的是常见做法。在将每条命令应用到系统之前请逐条检查，尤其是 iptables 转发规则和密钥文件权限，并建议在维护窗口内进行变更。

适用场景（何时使用）

在 Raspberry Pi、Linux 主机、pfSense 或路由器上搭建 WireGuard 服务端
生成 WireGuard 密钥对并编写对等端（peer）配置文件
配置从手机或笔记本到家庭网络的远程访问
解释拆分隧道（仅路由家庭流量）与全隧道（路由全部流量）的区别
排查无法建立的 WireGuard 连接
为多个客户端自动化生成对等端配置

工作原理

文档以示意图说明：手机（WireGuard 客户端）通过加密的 UDP 隧道（端口 51820）连接到家庭路由器（WireGuard 服务端，需要公网 IP 或 DDNS），再接入家庭网络（如 192.168.1.0/24、NAS、Pi 等）。每个设备拥有密钥对（公钥 + 私钥）；服务端知道每个客户端的公钥；客户端知道服务端公钥与端点（IP:端口）。流量端到端加密，无需中心服务器或证书颁发机构。

服务端配置（Linux）

包括：安装 WireGuard（sudo apt update && sudo apt install wireguard -y）；生成服务端密钥对并从一开始就设置私钥权限（umask 077，写入 /etc/wireguard/server_private.key 与 server_public.key）；编写服务端配置 /etc/wireguard/wg0.conf，其中 Interface 设置 Address = 10.8.0.1/24（服务端取 .1）、ListenPort = 51820、PrivateKey，PostUp/PostDown 使用限定范围的 iptables 转发规则（仅允许 wg0 进出流量，并配合 conntrack 的 RELATED,ESTABLISHED 以及 MASQUERADE），而非笼统的 FORWARD ACCEPT；为每个客户端添加 [Peer] 并设置 AllowedIPs；配置权限 chmod 600；将 eth0 替换为实际出网接口（可用 ip route show default 查看）；开启 IP 转发（net.ipv4.ip_forward=1，写入 /etc/sysctl.d/99-wireguard.conf 后执行 sysctl --system）；启动并设为开机自启（wg-quick up wg0、systemctl enable wg-quick@wg0）。文档提醒不要将私钥存入版本控制或分享。

客户端配置

每个客户端设备生成独立密钥对；可在客户端生成，或在服务端生成后安全传输私钥（切勿明文传输）。客户端配置文件示例包含 [Interface] 的 PrivateKey、Address = 10.8.0.2/32、可选 DNS = 192.168.1.2（可用于通过隧道使用 Pi-hole 解析）；[Peer] 的 PublicKey（服务端公钥）、Endpoint = your-home-ip.ddns.net:51820（公网 IP 或 DDNS 主机名）、AllowedIPs = 192.168.1.0/24（拆分隧道，仅家庭网络流量）或 AllowedIPs = 0.0.0.0/0, ::/0（全隧道，全部流量走 VPN）；以及 PersistentKeepalive = 25（移动客户端保持 NAT 打洞所必需）。

拆分隧道 vs 全隧道

拆分隧道（AllowedIPs = 192.168.1.0/24）：仅发往家庭网络的流量走 VPN，互联网流量（YouTube、Spotify）直连，移动端性能更好；适合“我只想从任何地方访问我的 NAS 和 Pi”的场景。
全隧道（AllowedIPs = 0.0.0.0/0, ::/0）：所有流量都走家庭互联网连接；可用于借用家庭 DNS/Pi-hole 广告拦截；缺点是家庭上传带宽会成为所有场景的瓶颈。
多子网拆分隧道（最常见的 homelab 用例）：AllowedIPs = 192.168.10.0/24, 192.168.20.0/24, 192.168.30.0/24, 10.8.0.0/24，将所有 VLAN 路由进隧道，互联网流量保持直连。

密钥生成与对等端管理

文档提供 Python 脚本示例：generate_keypair() 通过 wg genkey 与 wg pubkey 生成密钥对；generate_preshared_key() 使用 wg genpsk；build_client_config() 按参数拼装客户端配置；build_server_peer_block() 生成服务端 [Peer] 块。并提醒：私钥不要放入源码控制；如使用该脚本，应将密钥材料写入权限为 600 的文件，且绝不记录或打印密钥。

pfSense / OPNsense 中的 WireGuard

pfSense：VPN → WireGuard → Add Tunnel；Interface Keys 选择 Generate（自动创建密钥对）；Listen Port 51820；Interface Address 10.8.0.1/24。
添加 Peer（每个客户端一个）：Public Key 填客户端公钥，Allowed IPs 填 10.8.0.2/32。
分配 WireGuard 接口：Interfaces → Assignments → Add（选择 wg0）；启用接口，无需填 IP（在隧道配置中已设置）。
防火墙规则：WAN 允许 UDP 51820 入站（让客户端能到达服务端）；WireGuard 接口允许到希望可达的 LAN 网络流量。

家庭服务器的 DDNS（动态 DNS）

多数家庭宽带是动态 IP，使用 DDNS 可在 IP 变化后仍保持 VPN 端点可达。文档给出两种方式：

Cloudflare DDNS：将凭据存入 secrets 文件而非内联；给出 docker-compose 中 ddns-updater 使用 env_file 的示例，以及 ddns.env（chmod 600，不提交到 git）中的 zone_id 与 token 设置。
DuckDNS（免费、简单）：在 duckdns.org 注册获取 token 与子域名；将 token 存入 /etc/ddns.env（权限 600），使用一个 root 所有的小脚本（/usr/local/bin/update-duckdns，通过 curl 调用更新接口），并配置 cron 任务每 5 分钟执行一次。

故障排查

使用 sudo wg show 查看状态与最近握手时间；“latest handshake” 为空或很久之前说明隧道未连接。
排查要点：路由器/防火墙是否开放 UDP 端口 51820（sudo ufw status 或检查 pfSense/UniFi 防火墙规则）；客户端配置中的服务端公钥是否正确（sudo wg show wg0 public-key 对比）；服务端是否启用 IP 转发（cat /proc/sys/net/ipv4/ip_forward 应为 1）；客户端 AllowedIPs 是否覆盖目标 IP（若 AllowedIPs = 192.168.1.0/24 而要访问 192.168.3.5，则不会路由）。
查看内核日志 dmesg | grep wireguard；重启方式 sudo wg-quick down wg0 && sudo wg-quick up wg0。

反模式（应当避免）

将私钥存入版本控制或分享（私钥等同于密码，绝不提交到 git）。
在移动端使用 AllowedIPs = 0.0.0.0/0 却不考虑影响（全隧道会让所有移动流量走家庭上传，通常很慢）。
移动客户端未设置 PersistentKeepalive（NAT 后空闲隧道会被断开）。
开放了端口 51820 却忘了服务端 IP 转发（隧道连上但无流量路由，难以排查）。
多个客户端设备共用同一密钥对（每台设备必须使用唯一密钥对，共用会破坏安全模型）。
使用宽泛的 FORWARD ACCEPT iptables 规则（应仅限定到 wg0 接口与方向）。

最佳实践

每个客户端设备生成唯一密钥对，绝不重复使用。
移动端使用拆分隧道（AllowedIPs = 家庭子网）。
所有移动客户端设置 PersistentKeepalive = 25。
若 ISP 分配动态 IP 则使用 DDNS；凭据存入 env 文件而非内联。
使用限定范围的 iptables 转发规则（仅 wg0 入站），而非笼统的 FORWARD ACCEPT。
在客户端配置中将 DNS = 设为 Pi-hole 的 IP，以通过 VPN 获得广告拦截。
定期轮换服务端密钥对，并更新所有客户端配置。

技能介绍