aleaz/wgpl

# WGPL (WireGuard Peer Lite) - 基于数据库的零停机 Peer 管理与 IPAM CLI [](https://github.com/aleaz/wgpl/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/)  **WGPL (WireGuard Peer Lite)** 是一个轻量级、基于数据库的 CLI，用于管理跨多台服务器的 WireGuard peer。 **面临的问题：** 手动管理 WireGuard 意味着需要编辑文本文件（`wg0.conf`）、猜测哪些 IP 是空闲的，并且为了添加一个用户就要重启接口（这会导致所有活跃连接中断）。此外，这也缺乏关于谁被授予了访问权限的清晰历史记录。 **解决方案：** WGPL 将 peer 管理与你的操作系统解耦。它使用本地 SQLite 数据库自动处理 IP 分配（IPAM），原生生成配置，并以**零停机**的方式将更改应用到 Linux 内核。它具有基于 SQLite 触发器构建的、健壮的只追加审计追踪。结合适当的操作系统级别访问控制，它通过生成集中的 IP 分配和 peer 生命周期历史记录，简化了 SOC2 和 ISO27001 合规性，减少了访问审查期间的开销。 ## 与 wg-quick 的对比 | 特性 | `wg-quick` (手动) | `wgpl` | | --- | --- | --- | | **Peer 存储** | 文本文件 (`.conf`) | 关系型 SQLite 数据库 | | **IP 分配** | 手动（有冲突风险） | 自动化 CIDR IPAM | | **应用更改** | 重启接口（中断连接） | 零停机热重载 (`wg syncconf`) | | **审计与历史** | 无 | 健壮的只追加日志 | | **过期机制** | 手动清理 | 内置 TTL (`--expires 24h`) | ## 1 分钟快速开始 ### 1. 安装 **选项 A：独立二进制文件（推荐用于 Linux 路由器）** 无需任何依赖。 ``` curl -sL https://github.com/aleaz/wgpl/releases/latest/download/wgpl-linux-amd64 -o /usr/local/bin/wgpl chmod +x /usr/local/bin/wgpl ``` **选项 B：Python / uv（推荐用于开发者和管理员）** 需要 Python 3.12+。使用 `uv` 非常方便，因为它让获取最新更新变得轻而易举（只需运行 `uv tool upgrade wgpl`），或者直接从代码库安装最前沿的版本。 ``` uv tool install wgpl ``` ### 2. 注册接口并添加 Peer WGPL 不负责创建接口；它只管理谁连接到该接口。 ``` # 注册一个接口并定义其 IP 池 wgpl interface add wg0 vpn.example.com 10.0.0.0/24 # 添加一个用户 (WGPL 会自动分配下一个空闲的 IP) wgpl peer add wg0 "Alice_Laptop" ``` ### 3. 应用并导出 ``` # 将更改同步到 Linux kernel 而不断开连接 (需要 sudo 权限以写入 /etc/wireguard) sudo wgpl apply wg0 # 获取 Alice 手机的 QR code wgpl peer qr "Alice_Laptop" # 或者获取她桌面端的配置文件 wgpl peer config "Alice_Laptop" > alice.conf # 注意：请确保您的 umask 已安全设置，或者运行 `chmod 600 alice.conf` 以保护私钥。 ``` ## 目录 - [解耦架构 (BYOI)](#decoupled-architectures-byoi) - [功能特性](#features) - [客户端配置（终端用户设备）](#client-provisioning-end-user-devices) - [企业级生命周期与审计 (SRE)](#enterprise-lifecycle--audit-sre) - [高级集成](#advanced-integrations) - [配置说明](#configuration) - [贡献指南](#contributing) ## 解耦架构 (BYOI) WGPL 遵循“自带接口”（BYOI）理念。**它不是网络守护进程，不负责路由流量，也不创建初始的 `wg0` 接口。** 你提供接口；WGPL 管理 peer。 ``` graph TD DB[(WGPL SQLite SSOT)] --> CLI(wgpl CLI) CLI -->|Zero-Downtime Reload| Linux[Linux Kernel wg0] CLI -->|SSH / Ansible| Remote[Remote Servers] CLI -->|JSON Export| Router[RouterOS / Edge] CLI -->|QR Code PNG| Mobile[iOS / Android] ``` ### 1. 原生 Linux 服务器（零停机 Systemd） 直接在 VPN 网关（Debian/Ubuntu）上运行 WGPL。你可以使用 Systemd 自动化垃圾回收和 peer 同步，而无需将接口下线。 **Systemd 自动化示例：** 创建一个 systemd 服务（`/etc/systemd/system/wgpl-sync.service`）来清理过期的 peer 并热重载内核： ``` [Unit] Description=WGPL Sync & Prune After=wg-quick@wg0.service [Service] Type=oneshot ExecStartPre=/usr/local/bin/wgpl peer prune wg0 ExecStart=/usr/bin/sudo /usr/local/bin/wgpl apply wg0 ``` 通过 `.timer` 每 5 分钟触发一次，即可全面自动化你的 VPN 生命周期。 ### 2. 远程 Linux 服务器（CI/CD 流水线） 在你的 GitHub Actions、GitLab CI 或 Ansible 控制节点中运行 WGPL，通过 SSH 远程配置多台服务器。 ``` # 1. 为 Server A 导出声明式配置 wgpl interface export server-a-wg0 > server-a.conf # 2. 通过 SSH 安全地进行管道传输，以无缝应用更改 cat server-a.conf | ssh root@server-a "wg syncconf wg0 /dev/stdin" ``` ### 3. MikroTik (RouterOS v7) 设备 为原生缺乏这些功能的硬件路由器引入现代的 IPAM、TTL 和审计功能。 ``` # 通过 JSON 提取配置并生成一个 .rsc 脚本 wgpl --json peer list | jq -r '.[] | "/interface wireguard peers add interface=wg0 public-key=\"\(.public_key)\" allowed-address=\"\(.ip_address)/32\""' > mikrotik_sync.rsc ``` 然后将 `mikrotik_sync.rsc` 导入到你的路由器中。 ### 4. Docker 容器（临时 CI/CD） WGPL 以轻量级 Docker 容器的形式提供。要持久化你的数据库，请将本地目录挂载到 `/data`。 ``` alias wgpl='docker run --rm -it -v $(pwd)/wgpl-data:/data ghcr.io/aleaz/wgpl' # 现在您可以像使用本地 CLI 一样使用它 wgpl interface list ``` **应用更改的注意事项：** 如果你希望容器将更改应用到宿主机的 Linux 内核（通过 `wg syncconf`），你必须授予其网络管理能力，并在宿主机的网络命名空间中运行它： ``` docker run --rm -v $(pwd)/wgpl-data:/data \ --cap-add NET_ADMIN --network host \ ghcr.io/aleaz/wgpl apply wg0 ``` ## 功能特性 ### 多服务器支持 通过单个 SQLite 数据库管理无限数量的 WireGuard 服务器。 - **复合身份：** 接口名称（例如 `wg0`）可以在不同服务器上重复。WGPL 通过复合键（`名称 + Endpoint + 端口`）来识别隧道。 - **全局 IPAM：** 在每台服务器的 CIDR 块内自动分配空闲的 IPv4 地址。 - **天生的幂等性：** 重复运行 `wgpl apply` 是完全安全的。它只会将增量同步到内核。 ### 安全的并发 - **CI/CD 就绪：** SQLite WAL 模式和独占锁可确保多个 CI/CD 流水线在并发运行时不会损坏状态。 ### 高级网络 自动为你的隧道带来企业级网络功能： - **细粒度的 Peer 级配置：** 可在接口级别（默认）自定义 `MTU`、`PersistentKeepalive` 和 `DNS`，或者针对单个 peer 进行覆盖。 - **支持 FQDN 和 IP：** Endpoints 会根据 RFC 1123 进行主动验证，确保生成的配置始终能被 WireGuard 解析。 ### 安全与加密 - **原生生成：** 使用 Python 的 `cryptography` 在原生 RAM 中生成公钥/私钥（X25519）（无需 `wg genkey` 子进程）。 - **强化的验证：** 32 字节的 Base64 密钥验证可防止在配置同步期间发生内核恐慌。 - **默认安全：** 自动对数据库和导出的二维码应用严格的权限（`chmod 600`）。 ### 自动化与状态 - **严格的 JSON 输出 (`--json`)**，用于 M2M 集成（Ansible、Terraform、Bash）。 - **热重载：** 使用 `wg syncconf` 与 Linux 内核进行声明式同步（不会中断 TCP 连接）。 ## 客户端配置（终端用户设备） 将 VPN 交付给终端用户就像运行一个命令一样简单。WGPL 为每个平台提供了现成的格式。 ### 移动端（iOS / Android） 运行官方 WireGuard App 的用户可以扫描二维码。 ``` # 直接在终端中显示 ASCII QR Code wgpl peer qr # 或者将其导出以安全地发送给远程用户 wgpl peer qr -o ios_tunnel.png ``` ### 桌面端（Windows / macOS） 导出标准的 `.conf` 文件，以导入到官方的 WireGuard 桌面客户端中。 ``` wgpl peer config > my_laptop.conf # 注意：请确保您的 umask 已安全设置，或者运行 `chmod 600 my_laptop.conf` 以保护私钥。 ``` ### Linux 客户端 对于 Linux 上的用户，将配置直接导出到 `/etc/wireguard/` 并启用该服务。 ``` wgpl peer config | sudo tee /etc/wireguard/wg0.conf > /dev/null sudo systemctl enable --now wg-quick@wg0 ``` ## 企业级生命周期与审计 (SRE) WGPL 专为需要可追溯性和访问控制的运维团队而构建。 ### 临时访问 (TTL) 创建会自动过期的 peer。非常适合承包商或临时访问场景。 ``` wgpl peer add wg0 "Contractor_Audit" --expires 48h ``` *（过期的 peer 会被 `wgpl apply` 和 `wgpl interface export` 忽略）* ### 垃圾回收与删除 WGPL 默认使用**软删除**，以在释放 IP 地址的同时保留历史记录。 ``` # 软删除一个 peer (释放 IP，保留历史记录) wgpl peer remove wg0 # 永久清除过期或软删除的 peer wgpl peer prune wg0 # 硬删除 (物理 DB 擦除 + Audit 事件) wgpl peer remove wg0 --hard ``` ### 审计追踪 WGPL 使用 SQLite 触发器来维护健壮的、只追加的审计日志。 ``` # 查看一个接口的生命周期历史记录 wgpl interface history wg0 # 审计每一个 IP 更改、DNS 覆盖或特定 peer 的 Expiration wgpl peer history wg0 ``` ### 备份与时间点恢复 为了防止数据丢失并简化迁移过程，WGPL 提供了一个原子备份系统，该系统会在替换数据库之前验证 schema 的完整性。 ``` # 将 SQLite 数据库转储为一个逻辑 .sql 文件 wgpl db dump > backup.sql # 自动还原，保留权限并清除临时 WAL 文件 wgpl db restore backup.sql ``` ## 高级集成 WGPL 旨在无缝集成到现代 DevOps 和云原生技术栈中。为了保持本 README 的简洁，我们在 `examples/` 目录中提供了完全可用的示例： - **[Ansible Playbook](examples/ansible-deployment.yml)：** 从 Ansible 控制节点集中进行多服务器零停机更新。 - **[Terraform 与云防火墙](examples/terraform-external-data.tf)：** 使用 Terraform 的 `external` 数据源，在 AWS Security Group（或 GCP/Azure）中动态地将 WireGuard peer IP 加入白名单。 - **[GitHub Actions (GitOps)](examples/github-actions-gitops.yml)：** 通过 CI/CD 从声明式的 YAML 状态无缝部署 VPN 配置。 - **[FastAPI 自助门户](examples/fastapi-self-service.py)：** 将 WGPL 嵌入到 Python Web API 中，以自动生成二维码并返回给用户。非常适合在无需构建沉重 UI 的情况下，将 VPN 访问权限委托给非技术的 HR 或 IT 支持人员。 ## 配置说明 WGPL 开箱即用，无需任何配置，但它支持以下环境变量： | 变量 | 描述 | 默认值 | | --- | --- | --- | | `WGPL_DB_PATH` | 用于存储加密状态的本地 SQLite 数据库的路径。 | `~/.wgpl.db` | | `WGPL_WG_BIN` | `apply` 和 `syncconf` 使用的 `wg` 二进制文件的路径。（**安全提示：** 以 root 身份运行时会被忽略，以防止提权；安全地默认为 `/usr/bin/wg`） | `wg` (PATH) | *注意：如果你想在同一台机器上运行 `wgpl apply`，则**只有**此时才需要 `wireguard-tools` (`wg`)。* WGPL 具有自文档化的 CLI。运行 `wgpl --help` 来探索命令，或者查看 [完整 CLI 参考](docs/cli.md) 了解详情。 ## 作者 - **Alejandro Azario** - [GitHub](https://github.com/aleaz) ## 许可证 MIT

标签：IPAM, VPN, WireGuard, 请求拦截, 运维, 逆向工具, 零停机部署