qctm/wireguard-networkd-topology-studio
GitHub: qctm/wireguard-networkd-topology-studio
一款面向 systemd-networkd 的声明式 WireGuard 拓扑引擎，通过 YAML 统一定义网络意图，支持 AI 辅助设计，实现可扩展的网状网络或中心辐射状架构的自动化编排。
Stars: 0 | Forks: 0
# systemd-networkd 的 WireGuard 拓扑管理器
[](https://qctm.github.io)
## 🚀 网络编织者的工具箱 – 打造符合意图的覆盖网络架构
想象一下你正在建造一座由隧道组成的城市，每条隧道都有自己的用途、规则和权限。**WireGuard 拓扑管理器** 将蓝图与施工队融为一体。你无需再手动拼凑晦涩难懂的配置文件，只需定义 *意图*——该工具便会将其转化为纯净的、适配 systemd-networkd 的配置。
这不是又一个 VPN 包装器。这是一个面向专业人士的 **声明式拓扑引擎**，满足对可复现、可审计且版本可控的网络覆盖层的需求。无论你是在编排多区域 Kubernetes 集群、连接短暂的边缘设备，还是为远程团队构建弹性的 mesh 网络——该工具都会将你的网络拓扑视为基础设施即代码流水线中的一等公民。
## 🔮 核心理念："配置即地图学"
大多数 VPN 工具会问：*"我该如何连接这两个点？"*
我们则问：*"每对节点之间应该存在怎样的信任、延迟和带宽模式？"*
你不是在配置隧道。你是在 **设计一张图**——而拓扑管理器会将其具象化。
[]()
```
graph LR
subgraph "Hub-and-Spoke"
A[Hub Node] --> B[Spoke 1]
A --> C[Spoke 2]
A --> D[Spoke 3]
end
subgraph "Mesh Overlay"
B <--> C
C <--> D
D <--> B
end
subgraph "systemd-networkd"
E[.netdev] --> F[.network]
G[wireguard.conf] --> E
end
```
## 🌍 为什么会有这个项目（以及它的独特之处）
传统的 VPN 配置工具将每条隧道孤立对待。你运行一个脚本，得到一个配置，然后继续。但 *真实的* 网络是存在约束条件的：
- **节点发现顺序很重要** – 某些节点无法发起连接。
- **路由规则会级联生效** – 配置错误的 metric 会导致流量黑洞。
- **密钥轮换需要编排** – 如果你轮换了一个私钥，每个节点配置都必须原子性地更新。
**WireGuard 拓扑管理器** 通过引入 **拓扑清单** 来解决这些问题——这是一个 YAML 或 TOML 文件，将 *整个* 网络描述为一个单一的内聚结构。基于该清单，它会生成：
- 适用于每个节点的 Systemd `.netdev` 和 `.network` 文件
- 预共享密钥包（如果需要）
- 具有适当 metric 和 scope 的路由表
- 用于部署排序的依赖图
## 📋 示例 Profile 配置
以下是一个可用于生产环境的三节点拓扑清单的完整示例。请注意，每个节点是如何声明自己的角色、节点和转发规则的——而不仅仅是隧道端点。
```
# topology.yaml
version: "2026.1"
project: "edge-mesh-demo"
nodes:
hub-01:
wireguard_interface: wg0
listen_port: 51820
private_key: "ENV:WG_HUB_PRIVATE_KEY"
address: "10.200.0.1/24"
dns: ["10.200.0.53"]
peers:
- node: spoke-alpha
allowed_ips: ["10.200.0.2/32", "10.0.1.0/24"]
persistent_keepalive: 25
- node: spoke-beta
allowed_ips: ["10.200.0.3/32", "10.0.2.0/24"]
spoke-alpha:
wireguard_interface: wg0
listen_port: 51821
private_key: "ENV:WG_ALPHA_PRIVATE_KEY"
address: "10.200.0.2/24"
peers:
- node: hub-01
endpoint: "hub.example.com:51820"
allowed_ips: ["0.0.0.0/0"]
route_metric: 100
spoke-beta:
wireguard_interface: wg0
listen_port: 51822
private_key: "ENV:WG_BETA_PRIVATE_KEY"
address: "10.200.0.3/24"
peers:
- node: hub-01
endpoint: "hub.example.com:51820"
allowed_ips: ["0.0.0.0/0"]
route_metric: 200
```
## 🖥️ 示例控制台调用
一旦你的拓扑清单准备就绪，生成和部署配置只需一条命令：
```
# 为所有节点生成配置文件
wireguard-topology-manager generate --manifest topology.yaml --output ./generated-configs
# 创建包含生成文件的 ansible-ready inventory
wireguard-topology-manager inventory --manifest topology.yaml --format ansible > inventory.yml
# 对照 systemd-networkd schema 验证所有配置 (dry-run)
wireguard-topology-manager validate --path ./generated-configs
# 通过 SSH 部署到远程节点 (需要 SSH config)
wireguard-topology-manager deploy --inventory inventory.yml --ssh-user admin
```
该工具将：
1. 解析你的拓扑图。
2. 解析节点依赖关系（谁先连接）。
3. 生成格式正确的 systemd 单元文件。
4. 可选择通过你偏好的编排工具将它们推送到远程机器。
## 📊 操作系统兼容性矩阵
| 操作系统 | systemd-networkd 支持 | 已测试版本 | 状态 |
|------------------|--------------------------|----------------|--------|
| 🐧 Ubuntu 22.04+ | ✅ 原生 | v0.1 – 2026 | ✅ 已验证 |
| 🐧 Debian 12+ | ✅ 原生 | v0.1 – 2026 | ✅ 已验证 |
| 🐧 Arch Linux | ✅ 原生 | 滚动更新 | ✅ CI 测试通过 |
| 🐧 Fedora 38+ | ✅ 原生 | v0.1 – 2026 | ✅ 已验证 |
| 🐧 Alpine Linux | ⚠️ 需 openrc 适配 | Edge | 🧪 实验性 |
| 🐧 RHEL 9 / Rocky 9 | ✅ 原生 | v0.1 – 2026 | ✅ 已验证 |
| 🪟 Windows (WSL2) | ❌ 不支持 | – | – |
| 🍏 macOS | ❌ 不支持 | – | – |
## 🎯 功能列表
- **🔐 多密钥配置** – 为公钥和私钥对生成配置，可选包含 PSK。
- **🧩 感知依赖的部署** – 自动排序节点连接：先中心后分支，先全网状后部分网状。
- **📦 原生 Systemd-Networkd** – 直接输出 `*.netdev`、`*.network` 和 `wireguard.conf` 文件。
- **📐 路由表分段** – 为每个接口分配独立的路由表，并带有正确的 `Table` 指令。
- **🔄 变量替换** – 对密钥使用 `ENV:` 前缀；支持 `.env` 文件用于本地测试。
- **🔍 Dry-Run 验证** – 在生成之前检查重复的 IP、重叠的 CIDR、缺失的密钥以及不可达的节点。
- **🗂️ 清单导出** – 从同一清单生成 Ansible、Terraform 或纯 JSON 清单。
- **🛡️ 合规性模板** – 在整个集群中强制执行允许的 IP、MTU 限制和 keepalive 间隔。
- **🌐 多语言文档** – 所有错误消息和帮助文本均提供英文、德文和日文版本（`.help` 命令标志：`--lang de`）。
## 🧠 AI 集成：OpenAI 与 Claude API
本工具附带一个可选的 **AI 辅助清单生成器**——一个配套脚本，与语言模型对话以基于自然语言描述起草拓扑。
### OpenAI 集成
```
# 从提示生成拓扑 (需要 OPENAI_API_KEY)
wireguard-topology-manager ai-generate --provider openai --prompt \
"Create a hub-and-spoke topology for 5 edge servers in AWS,
each with a /28 subnet behind them. Hub should have public IP."
```
### Claude API 集成
```
# 同上，但使用 Claude 的 API
wireguard-topology-manager ai-generate --provider anthropic --prompt \
"Design a full mesh for 3 data centers, each running Kubernetes.
Ensure no split-brain routing possible."
```
两项集成都尊重你的 API 密钥（通过环境变量设置）。AI 会生成原始 YAML，你可以在运行 `generate` 之前对其进行编辑。
## ⚠️ 免责声明
**本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性保证。** 在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，因本软件或本软件的使用或其他交易而产生、与之相关或与之相连。
WireGuard® 是 Jason A. Donenfeld 的注册商标。本项目未获得 WireGuard 项目的附属或认可。加密密钥和节点配置的使用由操作者自行承担全部责任。在部署到生产环境之前，请务必根据你的安全策略验证生成的配置。
## 📜 许可证
本项目基于 **MIT 许可证** 授权 – 详见 [LICENSE](LICENSE.md) 文件。
[](https://opensource.org/licenses/MIT)
## 🧪 后续步骤与下载
[](https://qctm.github.io)
- **想要贡献？** 清单 schema 是可扩展的。为 `multicast_relay` 或 `auto_ipam` 等新功能提交 PR。
- **需要帮助设计拓扑？** `ai-generate` 命令接受多句描述——试试看吧！
- **发现了 Bug？** 附上你的拓扑清单（已脱敏）以及 `wireguard-topology-manager validate --verbose` 的输出来提交 Issue。
*构建有目的的网络。不是隧道，而是拓扑。不是脚本，而是架构。不是配置，而是意图。*
标签：Awesome, DevOps工具, EC2, Hub-and-Spoke, IaC, Kubernetes集群, Linux网络, Mesh组网, overlay网络, Petitpotam, PE 加载器, systemd-networkd, VPN, WireGuard, 图论网络, 声明式配置, 拓扑构建器, 流量捕获, 点对点加密, 特权提升, 系统提示词, 系统管理, 网状网络, 网络拓扑, 网络架构, 网络蓝图, 自动化部署, 节点互联, 虚拟专用网络, 覆盖网络, 边缘计算, 远程办公, 逆向工具, 配置自动化, 集线器-辐射