wg-easy 完全安装指南

一、什么是 wg-easy？

wg-easy（WireGuard Easy）是一个开源的、基于 Web 的 WireGuard VPN 管理面板。它通过图形化界面简化了 WireGuard 的配置和管理，让用户无需记忆命令行即可完成 VPN 服务器的搭建和日常运维。

核心优势：

• 纯 Web 界面操作，无需 SSH 登录服务器即可管理 VPN
• 一键创建/删除 VPN 客户端
• 支持二维码扫码配置，手机端配置无需手动编辑文件
• 实时查看客户端连接状态和流量统计
• 所有配置持久化存储，容器重启不丢失

架构说明：wg-easy 以 Docker 容器方式运行，通过挂载宿主机的 /lib/modules 目录来调用 WireGuard 内核模块，并利用 NET_ADMIN 和 SYS_MODULE 权限执行网络管理命令。

二、准备工作

2.1 系统要求

项目	要求
操作系统	Ubuntu 20.04 / 22.04 / 24.04（推荐）
架构	x86_64 / ARM64
内存	最低 1GB，推荐 2GB
公网 IP	必须有（供客户端连接）

2.2 软件依赖

• Docker：20.10 及以上版本
• Docker Compose：v2 版本（或 Docker Compose 插件）

2.3 网络端口

端口	协议	用途	是否必须开放
51820	UDP	WireGuard VPN 连接端口	必须
51821	TCP	wg-easy Web 管理界面	必须

⚠️ 重要：51820 必须是 UDP 协议，不是 TCP。如果使用云服务器，请在安全组/防火墙中正确配置协议类型。

2.4 域名（可选但推荐）

虽然 wg-easy 可以通过 http://服务器IP:51821 直接访问，但推荐配置一个独立域名并通过 HTTPS 访问，原因：

• 浏览器逐渐限制非 HTTPS 环境下的功能
• 密码传输更安全
• 避免浏览器缓存导致的界面异常

需要添加的 DNS 记录（以 wg.example.com 为例）：

记录类型	主机记录	记录值
A	wg	你的服务器公网 IP

完成后 wg.example.com 指向你的服务器。

三、安装步骤

3.1 更新系统

sudo apt update && sudo apt upgrade -y

3.2 安装 Docker

使用官方一键安装脚本：

curl -fsSL https://get.docker.com | sudo sh

将当前用户加入 docker 组（避免每次执行 docker 命令都需要 sudo）：

sudo usermod -aG docker $USER

执行完该命令后，必须退出 SSH 重新登录，或者执行 newgrp docker 使权限生效。

验证 Docker 安装成功：

docker --version
docker compose version

预期输出示例：

Docker version 27.0.3
Docker Compose version v2.28.1

3.3 加载 WireGuard 内核模块

WireGuard 在 Linux 5.6+ 内核中已内置，但需要手动加载模块：

# 加载模块
sudo modprobe wireguard

# 验证模块已加载
lsmod | grep wireguard

预期输出包含 wireguard 相关信息。

设置开机自动加载：

echo "wireguard" | sudo tee -a /etc/modules-load.d/wireguard.conf

3.4 开启 IP 转发（VPN 必需）

echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

验证配置生效：

sysctl net.ipv4.ip_forward

应返回 net.ipv4.ip_forward = 1。

3.5 创建安装目录

mkdir -p ~/wg-easy && cd ~/wg-easy

3.6 创建 docker-compose.yml

使用 Docker Compose 部署是最推荐的安装方式，便于管理和持久化。

nano docker-compose.yml

粘贴以下内容：

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - WG_HOST=你的域名或IP        # 改为你的公网 IP 或域名，如 wg.example.com
      - LANG=zh_CN                   # 中文界面
    volumes:
      - ./wireguard_data:/etc/wireguard
      - /lib/modules:/lib/modules:ro   # v15 必须挂载
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

配置说明：

参数	说明
WG_HOST	VPN 服务器的公网地址（IP 或域名），客户端通过此地址连接
LANG=zh_CN	将 Web 界面设置为中文
./wireguard_data:/etc/wireguard	持久化存储 VPN 配置和数据库
/lib/modules:/lib/modules:ro	挂载宿主机内核模块（v15 版本必需）
cap_add: NET_ADMIN, SYS_MODULE	授予容器管理网络和内核模块的权限
net.ipv4.ip_forward=1	开启 IP 转发，允许 VPN 客户端访问互联网

v15 版本重要变更：

• 密码不再通过环境变量 PASSWORD 设置，改在首次访问时通过安装向导配置
• 必须挂载 /lib/modules:/lib/modules:ro，否则容器无法正常启动
• 数据存储从 JSON 文件改为 SQLite 数据库

3.7 启动 wg-easy

docker compose up -d

首次启动会自动拉取镜像（约 500MB），等待片刻。

查看运行状态：

docker ps | grep wg-easy

预期输出显示 Up 状态。

查看日志确认无错误：

docker logs wg-easy

正常日志应包含：

Listening on http://0.0.0.0:51821
WireGuard Interface wg0 started successfully.

四、首次访问配置

4.1 访问 Web 界面

浏览器打开 http://你的服务器IP:51821

⚠️ 注意：使用 http 而非 https。如使用域名，需先配置 Nginx 反向代理和 SSL 证书。

4.2 安装向导（Setup Wizard）

v15 版本首次访问不会直接进入登录页面，而是显示安装向导。这是 v15 最重要的变化之一。

在向导中需要设置：

1. 管理员账户：输入邮箱和密码（这是登录凭证，请务必记住）
2. VPN 服务器地址：确认 WG_HOST 配置的地址正确
3. 其他可选配置：DNS 服务器、IP 地址范围等（可使用默认值）

完成向导后，页面自动跳转到登录界面。

4.3 登录

输入向导中设置的密码，进入 wg-easy 主界面。

主界面功能：

• 客户端列表：显示所有已创建的客户端及其连接状态
• 新建客户端：点击 + New Client 创建新的 VPN 用户
• 状态监控：查看客户端最后握手时间、收发数据量

五、配置 Nginx 反向代理（可选）

如果希望通过域名以 HTTPS 方式访问 wg-easy，可以使用 Nginx 反向代理。

5.1 安装 Nginx

sudo apt install -y nginx certbot python3-certbot-nginx

5.2 创建 Nginx 配置

sudo nano /etc/nginx/sites-available/wg

server {
    listen 80;
    server_name wg.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wg.example.com;

    # SSL 证书路径（certbot 会自动填写）
    ssl_certificate /etc/letsencrypt/live/wg.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wg.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:51821;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

5.3 启用配置并申请证书

sudo ln -s /etc/nginx/sites-available/wg /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d wg.example.com

完成后访问 https://wg.example.com。

六、环境变量参考

以下是 wg-easy 支持的主要环境变量（v15 版本）：

变量	默认值	说明
WG_HOST	–	必须，服务器公网 IP 或域名
LANG	en	界面语言，zh_CN 为简体中文
PORT	51821	Web 管理界面端口
WG_PORT	51820	WireGuard 服务 UDP 端口
WG_DEFAULT_ADDRESS	10.8.0.x	客户端 IP 地址范围
WG_DEFAULT_DNS	1.1.1.1	客户端 DNS 服务器
WG_ALLOWED_IPS	0.0.0.0/0	允许的 IP 范围
WG_PERSISTENT_KEEPALIVE	0	NAT 穿透心跳间隔（秒）
INSECURE	false	设为 true 允许 HTTP 访问

⚠️ 注意：v15 版本已移除 PASSWORD 和 PASSWORD_HASH 环境变量。密码在首次访问的安装向导中设置。

七、客户端连接

7.1 在 wg-easy 中创建客户端

1. 登录 wg-easy Web 界面
2. 点击 New Client 按钮
3. 输入客户端名称（如 my-laptop）
4. 可选：设置过期时间
5. 点击 Create

创建成功后，客户端卡片出现，提供两种配置方式：

• 二维码：供手机 App 扫描
• 下载配置：下载 .conf 文件供电脑客户端使用

7.2 各平台客户端下载

平台	下载方式
Windows	https://www.wireguard.com/install/
macOS	App Store 搜索 “WireGuard”
Linux	sudo apt install wireguard wireguard-tools
Android	Google Play / F-Droid 搜索 “WireGuard”
iOS	App Store 搜索 “WireGuard”

7.3 导入配置并连接

• 手机：打开 WireGuard App → 点击 + → Scan from QR code → 扫描 wg-easy 界面二维码
• 电脑：打开 WireGuard 客户端 → Import tunnel(s) from file → 选择下载的 .conf 文件 → Activate

7.4 验证连接

在客户端连接成功后，可在 wg-easy Web 界面看到该客户端状态变为 Connected，并显示最后握手时间和流量数据。

服务器端也可通过命令行查看：

sudo wg show

八、防火墙配置

8.1 阿里云/腾讯云等云服务器

在云控制台的安全组中添加入方向规则：

端口	协议	授权对象	说明
51820	UDP	0.0.0.0/0	WireGuard VPN 连接
51821	TCP	0.0.0.0/0	wg-easy Web 界面（如不使用 Nginx 代理）
80	TCP	0.0.0.0/0	HTTP（如有 Nginx）
443	TCP	0.0.0.0/0	HTTPS（如有 Nginx）

⚠️ 特别重要：WireGuard 端口（51820）必须是 UDP 协议，不是 TCP。如果误配为 TCP，客户端将无法连接。

8.2 系统防火墙（如已启用 ufw）

如果系统启用了 ufw：

sudo ufw allow 51820/udp
sudo ufw allow 51821/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload

九、常用管理命令

9.1 容器管理

# 进入 wg-easy 目录
cd ~/wg-easy

# 启动容器
docker compose up -d

# 停止容器
docker compose down

# 重启容器
docker compose restart

# 查看容器状态
docker ps | grep wg-easy

# 查看日志
docker logs wg-easy --tail 50

# 更新镜像
docker compose pull && docker compose up -d

9.2 数据备份与恢复

备份配置：

cd ~/wg-easy
tar -czf wg-easy-backup-$(date +%Y%m%d).tar.gz wireguard_data/

恢复配置：

cd ~/wg-easy
docker compose down
rm -rf wireguard_data
tar -xzf wg-easy-backup-YYYYMMDD.tar.gz
docker compose up -d

wireguard_data 目录包含：

• db.sqlite：客户端、用户等配置的 SQLite 数据库
• wg0.conf：WireGuard 接口配置（自动生成，不要手动编辑）

十、常见问题排查

Q1: 容器反复重启

常见原因：

1. WireGuard 内核模块未加载
2. 缺少 /lib/modules 挂载（v15 必须）
3. 端口被占用

解决：

# 检查内核模块
lsmod | grep wireguard
sudo modprobe wireguard

# 检查端口占用
sudo ss -tulnp | grep -E '51820|51821'

# 查看容器日志
docker logs wg-easy --tail 50

Q2: 无法访问 Web 界面

排查步骤：

# 1. 检查容器是否运行
docker ps | grep wg-easy

# 2. 检查端口监听
sudo ss -tulnp | grep 51821

# 3. 检查防火墙/安全组
# 确保 51821/tcp 已放行

# 4. 在服务器本地测试
curl -I http://127.0.0.1:51821

Q3: VPN 能连接但无法上网

原因：IP 转发未开启

解决：

# 检查状态
sysctl net.ipv4.ip_forward

# 临时开启
sudo sysctl -w net.ipv4.ip_forward=1

# 永久开启
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf

Q4: 忘记管理员密码

v15 版本密码存储在 SQLite 数据库中，重置方法：

cd ~/wg-easy
docker compose down
sudo rm -f ./wireguard_data/db.sqlite
docker compose up -d

重新访问 Web 界面，会再次进入安装向导，可重新设置密码。

Q5: 默认页面找不到 /login 或界面空白

原因：浏览器缓存或 v15 安装向导未完成

解决：

1. 强制刷新：Ctrl + Shift + R
2. 清除浏览器缓存（清除 wg.example.com 或你的 wg-easy 域名的站点数据）
3. 使用无痕模式访问
4. 确认是否已正确完成安装向导

十一、总结

安装流程回顾

步骤	操作	验证方法
1	更新系统	apt update 成功
2	安装 Docker	docker --version
3	加载 WireGuard 内核模块	lsmod | grep wireguard
4	开启 IP 转发	sysctl net.ipv4.ip_forward 返回 1
5	创建 docker-compose.yml	配置正确
6	启动容器	docker ps 显示 Up
7	访问 Web 界面	浏览器打开 IP:51821

关键要点

• 内核模块必须在宿主机加载：sudo modprobe wireguard
• v15 必须挂载 /lib/modules：否则容器无法访问内核模块
• 密码在首次访问时设置：不在环境变量中配置
• 51820 必须是 UDP 协议：云安全组配置时最容易出错的地方
• 独立域名是最简单的部署方式：wg-easy v15 不支持子路径反向代理

端口速查表

端口	协议	用途	必须开放
51820	UDP	VPN 连接	✅ 是
51821	TCP	Web 管理界面	✅ 是
80	TCP	HTTP（证书申请/代理）	如用 Nginx
443	TCP	HTTPS（代理访问）	如用 Nginx