# 鹊桥 (Magpie)

一个用 **Rust 手写**的通用 **WireGuard** VPN 客户端，可连接任何标准 WireGuard 服务器
（公司自建的、云服务器上的、或商业 WireGuard 服务导出的 `.conf`）。

- 协议与加密内核：[`boringtun`](https://github.com/cloudflare/boringtun)（Cloudflare 官方实现）
- Windows 虚拟网卡：[`wintun`](https://www.wintun.net/)（WireGuard 官方驱动）
- 三线程数据泵：`网卡 ↔ 加密/解密 ↔ UDP`

## 目录内容

```
magpie.exe     主程序
wintun.dll     虚拟网卡驱动（必须与 magpie.exe 放在同一目录）
magpie.conf    配置文件（标准 WireGuard 格式）
README.md      本说明
```

## 命令

```
magpie genkey            生成一对密钥（私钥 + 公钥）
magpie pubkey <私钥>     由私钥推导公钥
magpie sample            生成示例配置 magpie.conf 及一对新密钥
magpie selftest          本机自检：内存里跑通一次握手+加解密（无需服务器/管理员）
magpie up [配置文件]      启动隧道（默认 magpie.conf，需以管理员身份运行）
magpie help              帮助
```

## 先自检（强烈建议第一步）

不需要服务器、不需要管理员，验证加密内核在你机器上能跑：

```
magpie selftest
```

看到「✓ 自检通过」即说明 WireGuard 引擎正常。

## 连接真实服务器（三步）

### 1. 生成你的密钥并填配置

```
magpie sample
```

会生成 `magpie.conf` 并打印**你的公钥**。把公钥交给 VPN 服务器管理员登记。

### 2. 编辑 `magpie.conf`

填入服务器给你的信息：

```ini
[Interface]
PrivateKey = （已自动生成，别改）
Address    = 10.7.0.2/24          # 服务器分配给你的内网 IP
DNS        = 1.1.1.1              # 可选
MTU        = 1420

[Peer]
PublicKey           = 服务器的公钥
Endpoint            = vpn.公司域名.com:51820   # 服务器地址:端口
AllowedIPs          = 10.7.0.0/24   # 只走内网=分流；0.0.0.0/0=全局走VPN
PersistentKeepalive = 25
```

> 如果你已经有别处导出的 `.conf`（手机 App、`wg-quick` 等），直接拿来用即可——
> 把它改名为 `magpie.conf`，或运行 `magpie up 你的配置.conf`。

### 3. 用**管理员身份**启动

右键 PowerShell / 终端「以管理员身份运行」，然后：

```
magpie up
```

看到 `✓ 握手成功，隧道已连通` 即表示连上了。按 `Ctrl+C` 断开。

## 说明与限制

- **必须管理员权限**：创建虚拟网卡是系统级操作，Windows 要求管理员。
- `AllowedIPs` 决定哪些流量走 VPN：
  - 只填公司内网网段（如 `10.0.0.0/8`）= **分流**，只有访问内网才走 VPN，上网照常。
  - 填 `0.0.0.0/0` = **全局**，所有流量都走 VPN。此时程序会自动把
    服务器 Endpoint 的那条路由指回真实网关，避免环路。
- 退出时虚拟网卡随进程自动移除。
- 目前实现聚焦 **IPv4** 转发；IPv6 地址可配置但路由策略以 IPv4 为主。

## 从源码编译

```
cargo build --release
# 产物: target/release/magpie.exe
# 记得把 wintun.dll 拷到 exe 同目录
```