Coralesoft/Openwrt-Wireguard-Installer
GitHub: Coralesoft/Openwrt-Wireguard-Installer
一个用于在 OpenWrt 路由器上交互式安装、配置和管理 WireGuard VPN 的自动化脚本套件。
Stars: 17 | Forks: 2
# OpenWrt WireGuard 交互式安装器
一套全面的脚本，用于在 OpenWrt 路由器上自动化 WireGuard VPN 的设置、管理和维护。
## 🚀 功能
- **自动化安装** - 通过交互式提示完成完整的 WireGuard 设置
- **自动安装软件包** - 自动检测并安装缺失的软件包
- **交互式 Peer 管理** - 用户友好的菜单界面，用于管理 peer
- **二维码生成** - 通过二维码即时完成移动设备设置
- **密钥轮换** - 以安全为核心的密钥轮换及备份功能
- **备份与回滚** - 自动备份配置并提供回滚选项
- **系统集成备份** - 将 WireGuard 添加到 OpenWrt 备份配置中
- **彻底卸载** - 包含预览（dry-run）功能的完全卸载工具
## 📦 包含的脚本
| 脚本 | 用途 | 版本 |
|--------|---------|---------|
| `wg-openwrt-installer.sh` | 主安装程序和初始 peer 设置 | 2026.4.2 |
| `wg-peer-manage.sh` | 交互式 peer 管理 | 2026.4.2 |
| `wg-key-rotate.sh` | 用于安全性的密钥轮换 | 2026.4.1 |
| `wg-uninstall.sh` | 彻底移除 WireGuard | 2025.11.2 |
## 🔧 前置条件
### OpenWrt 路由器要求
- OpenWrt 23.05 或更高版本
- 需要互联网连接以下载和安装软件包
- 同时支持 `apk`（OpenWrt 24.10+）和 `opkg`（旧版本）包管理器
### 必需的软件包
安装器会自动检测并提示安装以下软件包：
- `wireguard-tools` - WireGuard 命令行工具
- `kmod-wireguard` - WireGuard 内核模块
- `luci-proto-wireguard` - LuCI Web 界面集成
### 可选软件包
- `qrencode` - 为移动设备生成二维码
**注意：** 你不再需要手动安装软件包！安装器会自动为你处理。
## 📖 快速开始
### 1. 下载脚本
```
cd /root
wget https://raw.githubusercontent.com/Coralesoft/Openwrt-Wireguard-Installer/main/wg-openwrt-installer.sh
wget https://raw.githubusercontent.com/Coralesoft/Openwrt-Wireguard-Installer/main/wg-peer-manage.sh
wget https://raw.githubusercontent.com/Coralesoft/Openwrt-Wireguard-Installer/main/wg-key-rotate.sh
wget https://raw.githubusercontent.com/Coralesoft/Openwrt-Wireguard-Installer/main/wg-uninstall.sh
chmod +x wg-*.sh
```
### 2. 运行安装器
```
./wg-openwrt-installer.sh
```
安装器将会：
1. 检查缺失的软件包并提示进行安装
2. 通过实用的提示引导你完成配置
3. 生成服务器和 peer 的密钥
4. 配置网络和防火墙
5. 生成二维码以便于在移动设备上设置
6. 将 `/etc/wireguard` 添加到备份配置中
**交互式提示：**
- WireGuard 接口名称（默认：`wg0`）
- UDP 端口（默认：`51820`）
- VPN 子网（默认：`192.168.20.1/24`）
- 公共 endpoint（路由器的公网 IP/域名）
- LAN/WAN 区域名称
- 为 peer 提供 DNS 服务器
- 初始创建的 peer 数量
### 3. 管理 Peer（新功能！）
使用交互式 peer 管理工具：
```
./wg-peer-manage.sh
```
**交互式菜单：**
```
WireGuard Peer Management
════════════════════════════════════════
Interface: wg0
1. List all peers
2. Add new peer
3. Manage existing peer
4. Show traffic statistics
5. Show active connections
6. Restart WireGuard interface
7. Exit
Select option [1-7]: _
```
**功能：**
- 📋 列出带有编号和状态的 peer
- ➕ 添加新 peer 并自动分配 IP
- 🔧 启用/禁用 peer 而无需删除它们
- 🗑️ 删除 peer 并自动进行归档
- 📊 查看流量统计
- 🔍 显示 peer 详细信息并重新生成二维码
- 🔄 在需要时重启接口
**命令行模式（可脚本化）：**
```
./wg-peer-manage.sh --list # List all peers
./wg-peer-manage.sh --add # Add new peer
./wg-peer-manage.sh --show=laptop # Show peer details + QR
./wg-peer-manage.sh --remove=old-phone # Remove peer
./wg-peer-manage.sh --disable=tablet # Temporarily disable
./wg-peer-manage.sh --enable=tablet # Re-enable
./wg-peer-manage.sh --traffic # Show bandwidth usage
./wg-peer-manage.sh --active # Show connected peers
./wg-peer-manage.sh --no-clear # Disable screen clearing
```
### 4. 配置 Peer 设备
添加 peer 后，配置文件可在以下位置找到：
```
/etc/wireguard/peers/
```
每个 peer 会获得：
- `.conf` 文件 - WireGuard 配置
- `-privatekey` - 该 peer 的私钥
- `-publickey` - 该 peer 的公钥
- `.png` - 二维码（如果安装了 qrencode）
#### 在移动设备上：
1. 安装 WireGuard 应用程序
2. 点击 "+" → "扫描二维码"
3. 扫描显示的二维码
4. 激活隧道
#### 在台式机/笔记本电脑上：
```
# 将 .conf 文件复制到 peer 设备，然后：
sudo cp peer.conf /etc/wireguard/wg0.conf
sudo wg-quick up wg0
# 开机启用（可选）：
sudo systemctl enable wg-quick@wg0
```
## 🔑 密钥轮换
定期轮换密钥对安全至关重要。请使用内置的轮换脚本：
### 轮换所有内容（最高安全性）
```
./wg-key-rotate.sh --server --all-peers
```
### 轮换特定 Peer
```
./wg-key-rotate.sh --peer=laptop --peer=phone
```
### 仅轮换服务器密钥
```
./wg-key-rotate.sh --server
```
**重要注意事项：**
- 轮换服务器密钥后，所有 peer 必须更新其配置！
- 旧密钥会备份到 `/etc/wireguard/backup/`
- 新的 peer 配置和二维码会自动生成
- 脚本将提示重启网络接口
**选项：**
```
--server Rotate server keypair
--peer=NAME Rotate specific peer (can use multiple times)
--all-peers Rotate all peer keypairs
--no-backup Skip creating backups
--interface=NAME Specify interface (default: wg0)
```
## 🗑️ 卸载
要完全移除 WireGuard 配置：
```
# 预览将要删除的内容（建议作为第一步）
./wg-uninstall.sh --dry-run
# 完全卸载
./wg-uninstall.sh
# 卸载特定 interface
./wg-uninstall.sh --interface=wg1
```
卸载程序会移除：
- ✅ 网络接口配置 (UCI)
- ✅ 所有 peer 配置
- ✅ 防火墙规则和区域
- ✅ WireGuard 密钥和配置 (`/etc/wireguard/`)
- ✅ 运行中的网络接口
- ✅ 从备份配置中移除 `/etc/wireguard`
**注意：** 卸载程序在进行任何更改前会要求你确认。
## 📁 文件结构
安装完成后，WireGuard 的文件组织如下：
```
/etc/wireguard/
├── privatekey # Server private key
├── publickey # Server public key
├── peers/ # Peer configurations
│ ├── laptop.conf # Peer config file
│ ├── laptop-privatekey # Peer private key
│ ├── laptop-publickey # Peer public key
│ └── laptop.png # QR code
├── backup/ # Key rotation backups
│ └── 20251101-120000/ # Timestamped backup directory
└── removed/ # Archived removed peers
└── 20251101-130000-old-device/
/etc/config/
├── network # UCI network config
├── firewall # UCI firewall config
├── network.bak.* # Automatic backups
└── firewall.bak.* # Automatic backups
/etc/sysupgrade.conf # Contains /etc/wireguard for backups
```
## 🛡️ 安全最佳实践
1. **定期轮换密钥**：每 3-6 个月轮换一次密钥
2. **安全分发密钥**：切勿通过未加密的渠道发送配置
3. **防火墙配置**：确保仅开放必要的端口
4. **Peer 管理**：使用 `wg-peer-manage.sh` 及时删除未使用的 peer
5. **备份密钥**：系统备份现在会自动包含 `/etc/wireguard`
6. **监控连接**：定期使用 `--active` 检查已连接的 peer
## 💾 备份与恢复
### 自动集成备份
安装器会自动将 `/etc/wireguard/` 添加到 OpenWrt 的备份配置 (`/etc/sysupgrade.conf`) 中。
**这意味着：**
- ✅ 你的 WireGuard 密钥将包含在系统备份中
- ✅ 配置在系统升级后依然保留
- ✅ 通过 LuCI 创建的备份包含 WireGuard
### 创建手动备份
```
# 创建备份归档
sysupgrade -b /tmp/backup-$(date +%Y%m%d).tar.gz
# 验证是否包含 WireGuard
tar -tzf /tmp/backup-*.tar.gz | grep wireguard
```
### 从备份恢复
```
# 全新安装或升级后：
sysupgrade -r /tmp/backup-20251101.tar.gz
# Router 将重启并恢复 WireGuard 配置
```
## 🔧 高级配置
### 自定义接口名称
在安装过程中，只需在出现提示时输入不同的接口名称：
```
./wg-openwrt-installer.sh
# 出现提示时：输入 WireGuard interface 名称 [wg0]: wg1
```
### 多个 WireGuard 接口
使用不同的接口名称多次运行安装程序：
```
# 第一个 VPN
./wg-openwrt-installer.sh # Use wg0
# 第二个 VPN
./wg-openwrt-installer.sh # Use wg1
# 分别管理
./wg-peer-manage.sh --interface=wg0
./wg-peer-manage.sh --interface=wg1
```
### 手动配置 UCI
安装完成后，你可以手动编辑：
```
# 显示当前配置
uci show network.wg0
# 更改端口
uci set network.wg0.listen_port='51821'
uci commit network
/etc/init.d/network restart
# 添加手动 peer
uci add network wireguard_wg0
uci set network.@wireguard_wg0[-1].description='manual-peer'
uci set network.@wireguard_wg0[-1].public_key=''
uci set network.@wireguard_wg0[-1].allowed_ips='192.168.20.10/32'
uci commit network
```
## 📊 监控
### 使用 Peer 管理脚本
```
./wg-peer-manage.sh --active # Show currently connected peers
./wg-peer-manage.sh --traffic # Show bandwidth usage per peer
./wg-peer-manage.sh --list # List all configured peers
```
### 命令行
```
# 显示 interface 状态
wg show wg0
# 显示所有已连接 peer 的详细信息
wg show wg0 peers
# 检查最新 handshakes（指示活动连接）
wg show wg0 latest-handshakes
# 显示传输统计信息
wg show wg0 transfer
# 所有信息的紧凑视图
wg show wg0 dump
```
### 使用 LuCI Web 界面
如果已安装 `luci-proto-wireguard`：
1. 导航到：`Status` → `WireGuard`
2. 查看已连接的 peer 和流量统计
3. 或者：`Network` → `Interfaces` → `wg0` → `Edit`
## 🐛 故障排除
### Peer 无法连接
```
# 1. 检查 WireGuard 是否正在运行
wg show wg0
# 2. 验证 interface 是否具有正确的 IP
ip addr show wg0
# 3. 检查防火墙规则
uci show firewall | grep wg0
# 4. 验证端口是否正在监听
netstat -ulnp | grep 51820
# 5. 检查日志
logread | grep -i wireguard
# 6. 从 peer 设备进行测试
ping 192.168.20.1 # Should work if connected
```
### 无握手
- 验证 peer 配置中的 endpoint 是否与你的公网 IP/域名匹配
- 检查路由器上的 UDP 端口是否已开放/转发
- 确保两台设备上的时间已同步（WireGuard 要求此项）
- 验证服务器和 peer 配置之间的密钥是否匹配
- 检查 peer 是否已启用：`./wg-peer-manage.sh --list`
### DNS 问题
- 检查 peer 配置中的 DNS 服务器：`cat /etc/wireguard/peers/device.conf`
- 验证 OpenWrt 上是否启用了 DNS 转发
- 首先使用 IP 地址进行测试：`ping 192.168.1.1`
- 检查 LAN 防火墙是否接受来自 VPN 的 DNS 请求
### 系统恢复后
如果恢复备份后 WireGuard 无法正常工作：
```
# 1. 验证文件是否已恢复
ls -la /etc/wireguard/
# 2. 检查 UCI 配置
uci show network.wg0
# 3. 重启网络
/etc/init.d/network restart
# 4. 检查 interface
wg show wg0
```
### Peer 管理脚本问题
```
# 如果您看到 "Server public key not found":
# 尚未安装 WireGuard server
./wg-openwrt-installer.sh
# 某些终端上的屏幕清除问题：
./wg-peer-manage.sh --no-clear
```
## 📝 完整脚本参考
### wg-openwrt-installer.sh
**用途：** 初始化 WireGuard 服务器设置
**功能：**
- 自动检测并安装缺失的软件包
- 提供实用提示的交互式配置
- 创建带有二维码的初始 peer
- 配置网络、防火墙和 UCI
- 将 WireGuard 添加到备份配置
- 出现问题时提供回滚选项
**用法：**
```
./wg-openwrt-installer.sh
# 遵循交互式提示
```
### wg-peer-manage.sh
**用途：** 日常 peer 管理
**交互模式：**
```
./wg-peer-manage.sh # Full interactive menu
./wg-peer-manage.sh --no-clear # Without screen clearing
```
**命令行模式：**
```
./wg-peer-manage.sh --list
./wg-peer-manage.sh --add
./wg-peer-manage.sh --show=NAME
./wg-peer-manage.sh --remove=NAME
./wg-peer-manage.sh --enable=NAME
./wg-peer-manage.sh --disable=NAME
./wg-peer-manage.sh --traffic
./wg-peer-manage.sh --active
./wg-peer-manage.sh --interface=wg1
./wg-peer-manage.sh --help
```
### wg-key-rotate.sh
**用途：** 安全密钥轮换
**用法：**
```
./wg-key-rotate.sh --server # Rotate server only
./wg-key-rotate.sh --peer=laptop # Rotate one peer
./wg-key-rotate.sh --peer=laptop --peer=phone # Multiple peers
./wg-key-rotate.sh --all-peers # All peers
./wg-key-rotate.sh --server --all-peers # Everything
./wg-key-rotate.sh --no-backup # Skip backup
./wg-key-rotate.sh --interface=wg1 # Specific interface
./wg-key-rotate.sh --help
```
### wg-uninstall.sh
**用途：** 彻底移除 WireGuard
**用法：**
```
./wg-uninstall.sh --dry-run # Preview only
./wg-uninstall.sh # Full removal
./wg-uninstall.sh --interface=wg1 # Specific interface
./wg-uninstall.sh --help
```
## 📄 许可证
本项目是开源的，基于 [MIT 许可证](LICENSE) 提供。
**版权所有：** C.Brown CoraleSoft, 2025-2026
## 📮 支持
如有问题、疑问或建议：
- 在 [GitHub](https://github.com/Coralesoft/Openwrt-Wireguard-Installer/issues) 上提交 issue
- 查看现有的 issue 获取解决方案
- 报告问题时请提供路由器型号和 OpenWrt 版本
## 🔗 链接
- [WireGuard 官网](https://www.wireguard.com/)
- [OpenWrt 文档](https://openwrt.org/docs/guide-user/services/vpn/wireguard/start)
- [OpenWrt 上的 WireGuard Wiki](https://openwrt.org/docs/guide-user/services/vpn/wireguard/basics)
## 🎯 版本历史
### 2026.4.2（当前版本）
- ✨ 在 peer 管理器中增加了密钥轮换支持
- ✨ 在交互式菜单中选中时显示 peer 详情
- ✨ 使用网络重启代替接口重启
- 🐛 修复了包检测 grep 模式中尾随空格的问题 (PR #8)
### 2026.4.1
- ✨ 支持 `apk` 包管理器（OpenWrt 24.10+ 从 opkg 切换到了 apk）
### 2026.1.0
- 🐛 修复了带有连字符的 peer 名称导致 UCI 错误的问题 (issue #6)
- 🐛 通过使用 `luci-proto-wireguard` 修复了 LuCI “缺少协议” 的问题 (issue #7)
### 2025.11.2
- ✨ 增加了自动安装软件包的功能
- ✨ 增加了交互式 peer 管理工具 (`wg-peer-manage.sh`)
- ✨ 增加了备份配置集成 (`/etc/sysupgrade.conf`)
- ✨ 改进了卸载程序，支持预览（dry-run）和接口选项
- 🐛 修复了密钥轮换中 sed 分隔符的 bug
- 🐛 修复了 peer 管理器中 IP 分配的检测问题
### 2025.9.1
- ✨ 初始密钥轮换脚本
- 🔒 安全的密钥备份功能
### 2025.8.1
- ✨ 首次公开发布
- 🚀 支持二维码生成的基础安装程序
**注意：** 在部署到生产环境之前，请务必在安全的环境中进行测试。保留可用配置的备份！
**测试环境：** OpenWrt 23.05.x / 24.10.x，包含多种路由器（如 Flint 2 (MT6000)）
标签：Cutter, OpenWrt, VPN, WireGuard, 数字取证, 网络配置, 自动化脚本, 运维工具