适用于 Debian 10+ / Ubuntu 20.04+
项目地址： https://github.com/plnl/wireguard-manager
本教程以 GitHub 当前 V2.0 项目结构为准，采用“傻瓜式”步骤，尽量直接复制命令即可。

一、准备工作

1. 使用 Root 登录服务器

SSH 登录 VPS：

1
ssh root@你的服务器IP

确认当前用户：

1
whoami

如果返回：

1
root

即可继续。

二、更新系统

执行：

1
2
apt update
apt upgrade -y

三、安装依赖

一次性执行：

1
apt install -y git curl sudo python3 ca-certificates wireguard-tools iproute2 qrencode

检查 Python：

1
python3 --version

检查 WireGuard：

1
wg --version

检查 IP 工具：

1
ip -V

如果都能正常显示版本信息，就可以继续。

qrencode 用于生成 WireGuard 客户端二维码，可选，但建议安装。

四、下载 WireGuard Manager V2.0

进入 /opt：

1
cd /opt

如果之前没有安装过：

1
git clone https://github.com/plnl/wireguard-manager.git

进入项目目录：

1
cd /opt/wireguard-manager

查看文件：

1
ls -la

正常情况下应该能看到类似：

1
2
3
4
5
6
7
systemd
web
.gitignore
LICENSE
README.md
WireGuard-Manager-V2.0-面板搭建教程.md
wireguard-manager-v2.0.sh

五、安装 wgmgr 命令

给主程序增加执行权限：

1
chmod +x /opt/wireguard-manager/wireguard-manager-v2.0.sh

创建全局命令：

1
ln -sf /opt/wireguard-manager/wireguard-manager-v2.0.sh /usr/local/bin/wgmgr

检查：

1
which wgmgr

正常应该显示：

1
/usr/local/bin/wgmgr

测试：

1
wgmgr help

如果能够显示帮助信息，说明程序安装成功。

六、初始化 WireGuard 服务端

执行：

1
wgmgr

进入管理菜单。

按照菜单进入：

1
2. 服务端

然后选择：

1
1. 初始化 / 重新配置服务端

按照屏幕提示填写参数。

七、服务端参数

具体参数以程序实际提示为准。

常见情况下需要设置：

  • WireGuard 接口：wg0
  • VPN 网段
  • 服务端 VPN 地址
  • WireGuard UDP 监听端口
  • DNS
  • IPv4 / IPv6 相关选项

完成后让程序应用配置。

八、检查 WireGuard 是否正常

执行：

1
wg show

再执行：

1
ip addr show wg0

如果看到：

1
wg0

以及对应的 VPN 地址，说明 WireGuard 接口已经创建。

继续检查：

1
systemctl status wg-quick@wg0

如果服务正常，应看到：

1
active (exited)

或正常运行状态。

九、添加第一个客户端

再次执行：

1
wgmgr

进入：

1
3. 客户端

然后选择：

1
1. 添加客户端

按照提示输入客户端名称。

例如：

1
iphone

或者：

1
macbook

完成后，程序会生成客户端配置。

客户端配置通常位于：

1
/etc/wireguard-manager/clients/

查看：

1
ls -la /etc/wireguard-manager/clients/

十、查看客户端信息

例如客户端名称为：

1
iphone

执行：

1
ls -la /etc/wireguard-manager/clients/iphone/

可以查看：

1
2
3
4
meta.conf
private.key
public.key
client.conf

如果安装了 qrencode，还可以使用程序提供的二维码功能导入客户端。

十一、导入 WireGuard 客户端

将生成的客户端配置导入：

  • Windows WireGuard
  • macOS WireGuard
  • iPhone WireGuard
  • Android WireGuard
  • Linux WireGuard

导入后启动 VPN。

十二、检查客户端是否连接

服务器执行：

1
wg show

重点查看：

1
2
3
latest handshake
transfer: received
transfer: sent

如果能够看到最近的：

1
latest handshake

说明客户端已经与服务器建立连接。

十三、测试客户端网络

客户端连接 WireGuard 后，测试：

1
ping 你的服务端VPN地址

例如：

1
ping 10.66.66.1

如果能正常通信，说明基础 WireGuard 已经工作。

十四、安装 Web 管理面板

确认 WireGuard 工作正常后，再安装 Web 面板。

执行：

1
wgmgr

进入：

1
12. Web 面板

选择：

1
1. 安装

按照程序提示完成安装。

十五、选择 Web 面板绑定方式

安装过程中会要求选择 Web 面板监听方式。

一般有以下几种：

方案一：VPN

推荐。

Web 面板只监听 WireGuard VPN 网络。

适合：

1
2
手机 → WireGuard → Web 面板
电脑 → WireGuard → Web 面板

优点：

  • 不直接暴露公网
  • 安全性更高
  • 适合个人 VPS
  • 不需要公网开放 Web 管理端口

个人使用优先推荐这个方案。

方案二：local

监听：

1
127.0.0.1

适合：

  • SSH 隧道
  • Nginx 反向代理
  • Cloudflare Tunnel
  • 其他反向代理方案

方案三：public

监听：

1
0.0.0.0

表示 Web 面板可以从公网直接访问。

如果选择此方式，建议：

  • 使用 HTTPS
  • 配置反向代理
  • 设置防火墙
  • 不要直接把管理面板裸露在公网

十六、设置 Web 面板端口

按照安装程序提示设置 Web 端口。

例如：

1
8443

如果你选择其他端口，以实际设置的端口为准。

十七、创建 Web 管理员账号

安装过程中按照提示设置：

1
2
用户名
密码

请保存好管理员账号密码。

十八、检查 Web 服务

执行：

1
systemctl status wireguard-manager-web

正常应该看到：

1
active (running)

再检查 Collector：

1
systemctl status wireguard-manager-collector

正常应该看到：

1
active (running)

十九、检查 Web 端口

假设 Web 端口设置为：

1
8443

执行：

1
ss -lntp | grep 8443

如果能够看到监听信息，说明 Web 服务已经监听。

二十、访问 Web 面板

如果 Web 面板绑定的是 VPN：

1
http://你的WireGuard服务端VPN地址:Web端口

例如：

1
http://10.66.66.1:8443

然后输入安装时设置的管理员账号和密码。

二十一、检查 Collector 数据

WireGuard Manager V2.0 的 Web 面板使用状态数据。

查看：

1
ls -la /etc/wireguard-manager/state/

手动执行一次采集：

1
wgmgr collect

然后检查：

1
ls -la /etc/wireguard-manager/state/

二十二、检查系统健康状态

执行：

1
wgmgr health

也可以使用 JSON：

1
wgmgr health --json

二十三、查看流量统计

查看最近 24 小时：

1
wgmgr traffic --range 24h

查看最近 7 天：

1
wgmgr traffic --range 7d

查看最近 30 天：

1
wgmgr traffic --range 30d

二十四、查看客户端状态

执行：

1
wgmgr peer list --json

如果服务器安装了 jq，可以筛选离线客户端：

1
wgmgr peer list --json | jq '.peers[] | select(.status=="offline")'

客户端状态包括：

1
2
3
4
5
online
idle
offline
never
disabled

二十五、检查两个 Web 服务

一次性检查：

1
2
systemctl status wireguard-manager-web --no-pager
systemctl status wireguard-manager-collector --no-pager

二十六、查看 Web 日志

实时查看：

1
journalctl -u wireguard-manager-web -f

查看 Collector 日志：

1
journalctl -u wireguard-manager-collector -f

查看最近 100 行：

1
journalctl -u wireguard-manager-web -n 100 --no-pager

二十七、设置开机自动启动

执行：

1
2
systemctl enable wireguard-manager-web
systemctl enable wireguard-manager-collector

同时检查：

1
2
systemctl is-enabled wireguard-manager-web
systemctl is-enabled wireguard-manager-collector

正常显示：

1
enabled

二十八、最终检查

依次执行：

1
wg show
1
systemctl status wg-quick@wg0 --no-pager
1
systemctl status wireguard-manager-web --no-pager
1
systemctl status wireguard-manager-collector --no-pager
1
wgmgr health --json
1
wgmgr traffic --range 24h

如果以上基本正常，WireGuard Manager V2.0 就安装完成了。

二十九、日常最常用命令

查看 WireGuard

1
wg show

进入管理菜单

1
wgmgr

健康检查

1
wgmgr health

JSON 健康检查

1
wgmgr health --json

查看 24 小时流量

1
wgmgr traffic --range 24h

查看 7 天流量

1
wgmgr traffic --range 7d

查看客户端

1
wgmgr peer list --json

手动刷新状态

1
wgmgr collect

查看 Web 日志

1
journalctl -u wireguard-manager-web -f

查看 Collector 日志

1
journalctl -u wireguard-manager-collector -f

三十、升级前先备份

升级前建议先创建备份：

1
wgmgr backup create

查看备份：

1
ls -lah /etc/wireguard-manager/backups/

三十一、V1.3 升级到 V2.0

如果原来已经使用 WireGuard Manager V1.3：

  1. 先备份：
1
wgmgr backup create
  1. 保留原来的：
1
/etc/wireguard-manager/

  1. 使用 V2.0 项目文件替换程序。

  2. 确认以下数据没有被删除：

1
2
3
4
5
6
manager.conf
clients/
sites/
keys/
routes/
backups/
  1. 重新安装 Web 层：
1
wgmgr

进入：

1
12. Web 面板

选择：

1
1. 安装

V2.0 的 Web 层是在原有管理核心基础上增加的，不需要重新创建原有客户端和站点数据。

三十二、卸载

如果以后需要卸载，可以进入：

1
wgmgr

根据菜单中的：

1
卸载

执行对应操作。

卸载前建议先备份：

1
wgmgr backup create

三十三、重要目录

WireGuard 配置：

1
/etc/wireguard/

WireGuard Manager：

1
/etc/wireguard-manager/

主要配置：

1
/etc/wireguard-manager/manager.conf

服务端数据：

1
/etc/wireguard-manager/server/

客户端：

1
/etc/wireguard-manager/clients/

站点互联：

1
/etc/wireguard-manager/sites/

备份：

1
/etc/wireguard-manager/backups/

Web 状态：

1
/etc/wireguard-manager/state/

管理命令：

1
/usr/local/bin/wgmgr

项目目录：

1
/opt/wireguard-manager/

三十四、推荐安装顺序

如果你是第一次安装，严格按照下面顺序执行：

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
1. SSH 登录 VPS
        ↓
2. 更新系统
        ↓
3. 安装依赖
        ↓
4. 下载 GitHub 项目
        ↓
5. 安装 wgmgr
        ↓
6. 初始化 WireGuard 服务端
        ↓
7. wg show 检查
        ↓
8. 创建客户端
        ↓
9. 客户端连接测试
        ↓
10. 安装 Web 面板
        ↓
11. 设置 Web 绑定方式
        ↓
12. 创建管理员账号
        ↓
13. 检查 Web 服务
        ↓
14. 检查 Collector
        ↓
15. 浏览器登录 Web 面板
        ↓
16. 完成

三十五、一键准备环境命令

如果系统刚安装好，可以直接执行：

1
2
3
4
5
6
7
8
apt update && apt upgrade -y && \
apt install -y git curl sudo python3 ca-certificates wireguard-tools iproute2 qrencode && \
cd /opt && \
git clone https://github.com/plnl/wireguard-manager.git && \
cd /opt/wireguard-manager && \
chmod +x wireguard-manager-v2.0.sh && \
ln -sf /opt/wireguard-manager/wireguard-manager-v2.0.sh /usr/local/bin/wgmgr && \
wgmgr help

看到帮助信息后：

1
wgmgr

然后按照菜单操作：

1
2 → 服务端 → 1

完成 WireGuard 服务端初始化。

确认 WireGuard 正常后：

1
12 → Web 面板 → 1

安装 Web 管理面板。

三十六、注意事项

1. 不要只下载一个 .sh

V2.0 不是只有一个脚本。

必须保持项目目录结构，特别是：

1
2
3
wireguard-manager-v2.0.sh
web/
systemd/

之间的相对位置不能随意改变。

2. 不要随意删除配置目录

尤其是：

1
/etc/wireguard-manager/

里面保存着 Manager 的主要配置、客户端、站点和备份数据。

3. 修改网络配置前先备份

推荐：

1
wgmgr backup create

4. Web 面板优先使用 VPN 方式访问

如果只是自己管理 VPS，推荐：

1
2
3
WireGuard VPN
    ↓
Web 管理面板

而不是直接公网暴露管理面板。

三十七、项目地址

GitHub：

https://github.com/plnl/wireguard-manager

项目主程序：

1
wireguard-manager-v2.0.sh

管理命令：

1
wgmgr