WireGuard Manager V2.0 Debian 安装教程

WireGuard Manager V2.0 Debian 安装教程

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

—

一、准备工作

1. 使用 Root 登录服务器

SSH 登录 VPS：

ssh root@你的服务器IP

确认当前用户：

whoami

如果返回：

root

即可继续。

—

二、更新系统

执行：

apt update
apt upgrade -y

—

三、安装依赖

一次性执行：

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

检查 Python：

python3 --version

检查 WireGuard：

wg --version

检查 IP 工具：

ip -V

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

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

—

四、下载 WireGuard Manager V2.0

进入 /opt：

cd /opt

如果之前没有安装过：

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

进入项目目录：

cd /opt/wireguard-manager

查看文件：

ls -la

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

systemd
web
.gitignore
LICENSE
README.md
WireGuard-Manager-V2.0-面板搭建教程.md
wireguard-manager-v2.0.sh

—

五、安装 wgmgr 命令

给主程序增加执行权限：

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

创建全局命令：

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

检查：

which wgmgr

正常应该显示：

/usr/local/bin/wgmgr

测试：

wgmgr help

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

—

六、初始化 WireGuard 服务端

执行：

wgmgr

进入管理菜单。

按照菜单进入：

2. 服务端

然后选择：

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

按照屏幕提示填写参数。

—

七、服务端参数

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

常见情况下需要设置：

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

完成后让程序应用配置。

—

八、检查 WireGuard 是否正常

执行：

wg show

再执行：

ip addr show wg0

如果看到：

wg0

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

继续检查：

systemctl status wg-quick@wg0

如果服务正常，应看到：

active (exited)

或正常运行状态。

—

九、添加第一个客户端

再次执行：

wgmgr

进入：

3. 客户端

然后选择：

1. 添加客户端

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

例如：

iphone

或者：

macbook

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

客户端配置通常位于：

/etc/wireguard-manager/clients/

查看：

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

—

十、查看客户端信息

例如客户端名称为：

iphone

执行：

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

可以查看：

meta.conf
private.key
public.key
client.conf

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

—

十一、导入 WireGuard 客户端

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

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

导入后启动 VPN。

—

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

服务器执行：

wg show

重点查看：

latest handshake
transfer: received
transfer: sent

如果能够看到最近的：

latest handshake

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

—

十三、测试客户端网络

客户端连接 WireGuard 后，测试：

ping 你的服务端VPN地址

例如：

ping 10.66.66.1

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

—

十四、安装 Web 管理面板

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

执行：

wgmgr

进入：

12. Web 面板

选择：

1. 安装

按照程序提示完成安装。

—

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

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

一般有以下几种：

方案一：VPN

推荐。

Web 面板只监听 WireGuard VPN 网络。

适合：

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

优点：

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

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

—

方案二：local

监听：

127.0.0.1

适合：

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

—

方案三：public

监听：

0.0.0.0

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

如果选择此方式，建议：

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

—

十六、设置 Web 面板端口

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

例如：

8443

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

—

十七、创建 Web 管理员账号

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

用户名
密码

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

—

十八、检查 Web 服务

执行：

systemctl status wireguard-manager-web

正常应该看到：

active (running)

再检查 Collector：

systemctl status wireguard-manager-collector

正常应该看到：

active (running)

—

十九、检查 Web 端口

假设 Web 端口设置为：

8443

执行：

ss -lntp | grep 8443

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

—

二十、访问 Web 面板

如果 Web 面板绑定的是 VPN：

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

例如：

http://10.66.66.1:8443

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

—

二十一、检查 Collector 数据

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

查看：

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

手动执行一次采集：

wgmgr collect

然后检查：

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

—

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

执行：

wgmgr health

也可以使用 JSON：

wgmgr health --json

—

二十三、查看流量统计

查看最近 24 小时：

wgmgr traffic --range 24h

查看最近 7 天：

wgmgr traffic --range 7d

查看最近 30 天：

wgmgr traffic --range 30d

—

二十四、查看客户端状态

执行：

wgmgr peer list --json

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

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

客户端状态包括：

online
idle
offline
never
disabled

—

二十五、检查两个 Web 服务

一次性检查：

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

—

二十六、查看 Web 日志

实时查看：

journalctl -u wireguard-manager-web -f

查看 Collector 日志：

journalctl -u wireguard-manager-collector -f

查看最近 100 行：

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

—

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

执行：

systemctl enable wireguard-manager-web
systemctl enable wireguard-manager-collector

同时检查：

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

正常显示：

enabled

—

二十八、最终检查

依次执行：

wg show

systemctl status wg-quick@wg0 --no-pager

systemctl status wireguard-manager-web --no-pager

systemctl status wireguard-manager-collector --no-pager

wgmgr health --json

wgmgr traffic --range 24h

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

—

二十九、日常最常用命令

查看 WireGuard

wg show

进入管理菜单

wgmgr

健康检查

wgmgr health

JSON 健康检查

wgmgr health --json

查看 24 小时流量

wgmgr traffic --range 24h

查看 7 天流量

wgmgr traffic --range 7d

查看客户端

wgmgr peer list --json

手动刷新状态

wgmgr collect

查看 Web 日志

journalctl -u wireguard-manager-web -f

查看 Collector 日志

journalctl -u wireguard-manager-collector -f

—

三十、升级前先备份

升级前建议先创建备份：

wgmgr backup create

查看备份：

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

—

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

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

1. 先备份：

wgmgr backup create

1. 保留原来的：

/etc/wireguard-manager/

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

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

manager.conf
clients/
sites/
keys/
routes/
backups/

1. 重新安装 Web 层：

wgmgr

进入：

12. Web 面板

选择：

1. 安装

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

—

三十二、卸载

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

wgmgr

根据菜单中的：

卸载

执行对应操作。

卸载前建议先备份：

wgmgr backup create

—

三十三、重要目录

WireGuard 配置：

/etc/wireguard/

WireGuard Manager：

/etc/wireguard-manager/

主要配置：

/etc/wireguard-manager/manager.conf

服务端数据：

/etc/wireguard-manager/server/

客户端：

/etc/wireguard-manager/clients/

站点互联：

/etc/wireguard-manager/sites/

备份：

/etc/wireguard-manager/backups/

Web 状态：

/etc/wireguard-manager/state/

管理命令：

/usr/local/bin/wgmgr

项目目录：

/opt/wireguard-manager/

—

三十四、推荐安装顺序

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

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. 完成

—

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

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

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

看到帮助信息后：

wgmgr

然后按照菜单操作：

2 → 服务端 → 1

完成 WireGuard 服务端初始化。

确认 WireGuard 正常后：

12 → Web 面板 → 1

安装 Web 管理面板。

—

三十六、注意事项

1. 不要只下载一个 .sh

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

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

wireguard-manager-v2.0.sh
web/
systemd/

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

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

尤其是：

/etc/wireguard-manager/

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

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

推荐：

wgmgr backup create

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

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

WireGuard VPN
    ↓
Web 管理面板

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

—

三十七、项目地址

GitHub：

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

项目主程序：

wireguard-manager-v2.0.sh

管理命令：

wgmgr