wg-quick-win

wg-quick-win 是 Windows 上的 wg-quick 风格服务和命令行工具。它通过 Windows 服务统一管理 WireGuard / wireguard-mix 接口，支持按接口指定 WgBin、域名 endpoint DDNS 刷新、DoH/DoT 解析、SOCKS5/HTTP 传输代理、服务日志、WgBin 日志和 NamedPipe IPC。

English documentation: README.en.md

功能

• Windows 服务托管，CLI 通过 IPC 控制接口。
• 支持 up / down / sync / status / list / ddns-update / wg 常用命令。
• 支持每个接口自定义 WgBin，可使用官方 WireGuard 或 wireguard-mix，两种后端使用不同启动模式。
• 支持 DoH / DoT DNS resolver，SOCKS5 / HTTP 作为 DoH/DoT 的传输代理。
• 支持 DDNS。
• 支持开机自启动接口。

常用命令

wg-quick-win.exe help
wg-quick-win.exe version
wg-quick-win.exe list
wg-quick-win.exe status
wg-quick-win.exe status wg0
wg-quick-win.exe up wg0
wg-quick-win.exe sync wg0
wg-quick-win.exe ddns-update
wg-quick-win.exe ddns-update wg0
wg-quick-win.exe wg show
wg-quick-win.exe wg show wg0
wg-quick-win.exe down wg0

up、down、sync、ddns-update 和 wg 会实时打印服务端进度，便于定位 WgBin 启动、UAPI、wg.exe setconf 和网络配置错误。

从零安装

1. 安装官方 WireGuard for Windows。

   从 WireGuard 安装页 安装官方客户端。

   它提供官方 NT 后端需要的 wireguard.exe、公共控制工具 wg.exe，以及 WireGuardNT 系统组件。接口配置里不写 WgBin 时，wg-quick-win 就使用这个官方 NT 后端。

2. 准备 wg-quick-win 目录。

   推荐把程序和配置都放在同一个透明目录里：

   C:\opt\bin\wg-quick-win\
     wg-quick-win.exe
     config.toml
     interfaces\
       wg0.conf
     logs\
   

   复制示例配置：

   New-Item -ItemType Directory -Force C:\opt\bin\wg-quick-win\interfaces
   Copy-Item .\examples\config.toml C:\opt\bin\wg-quick-win\config.toml
   Copy-Item .\examples\interfaces\wg0.conf C:\opt\bin\wg-quick-win\interfaces\wg0.conf

3. 如果只使用官方 NT 后端，可以跳过 Wintun DLL 和 wireguard-mix。

   这种模式下接口配置不要写 WgBin。wg-quick-win 会自动查找官方 wireguard.exe 启动接口后，再统一用官方的 wg.exe 写入 WireGuard 配置、地址、DNS 和路由。

4. 如果要使用 userspace 后端，下载 Wintun DLL。

   • 从 wintun.net 下载 Wintun

   • 解压后选择与系统架构匹配的 wintun.dll，通常是 amd64 版本。 可以把 wintun.dll 放在 wireguard userspace 程序同目录，也可以在 config.toml 的 [wireguard].wintun 里显式填写 DLL 路径。

   • userspace 后端启动前，wg-quick-win 会把该 DLL 同步到 WgBin 所在目录，避免程序找不到库，因为 userspace 后端只查找程序目录和 System32 目录。

   注意：官方 WireGuard 安装后系统里可能已经有 Wintun/WireGuardNT 驱动，但它通常不会在安装目录放一个可供 userspace 程序加载的 wintun.dll。userspace 后端需要的是这个 DLL 文件。

5. 如果要使用 wireguard-mix，下载 WgBin。

   从 BaiMeow/wireguard-mix 下载 wireguard-mix.exe，例如放到：

   C:\opt\bin\wg-quick-win\wireguard-mix.exe
   

   然后在对应接口配置里写：

   [Interface]
   WgBin = C:\opt\bin\wg-quick-win\wireguard-mix.exe

   只要接口配置了自定义 WgBin，wg-quick-win 就按 userspace 后端 + wintun 模式启动。

6. 安装并启动服务。

   以管理员权限运行：

   .\wg-quick-win.exe install
   .\wg-quick-win.exe start-service

   程序会把当前正在运行的 wg-quick-win.exe 路径注册到服务，所以注册完以后请不要删除或移动该文件。

   安装命令可选参数：

   • --allow-interactive-ipc 表示允许登录用户不提权访问 IPC，方便个人使用
   • --no-allow-interactive-ipc 只有 Administrators 和 LocalSystem 有权限和服务进程通信
   • --config 指定配置文件位置，之后服务每次启动都会读取该配置文件

7. 启动接口并查看状态。

   .\wg-quick-win.exe list
   .\wg-quick-win.exe up wg0
   .\wg-quick-win.exe status
   .\wg-quick-win.exe wg show

8. 如有需要，可以把该程序加入 Path 便于调用。

卸载

.\wg-quick-win.exe stop-service
.\wg-quick-win.exe uninstall

注意：如果服务启动时读取的配置里设置了 stop_interfaces_on_exit = false，停止服务时不会主动关闭接口，卸载后也可能保留接口或 userspace 进程。需要完全清理时，请先执行 .\wg-quick-win.exe down <接口名>，再卸载服务。

构建

.\scripts\build.ps1

默认输出到 bin\wg-quick-win.exe，并自动注入版本、commit 和构建时间。发布构建示例：

.\scripts\build.ps1 -Version 2.0.1 -Package

打包产物会写到 bin\wg-quick-win-<version>-windows-amd64.zip。

Windows Network Profile 清理

普通 userspace WireGuard 程序通过 Wintun 重新创建同名网卡时，Windows 可能分配新的 Adapter GUID，并留下 wg0 2、wg0 3 之类的历史 Network Profile。为避免这些记录持续累积，wg-quick-win 会给自己管理的 userspace Profile 写入以 DO_NOT_EDIT:WG_QUICK_WIN_NETPROFILE: 开头的 Description 标记。

接口关闭后，程序只会在 Adapter 已消失且标记完整匹配时，删除对应 Profile GUID 及其精确关联的 Signature。活动接口、官方 NT 后端、无标记 Profile，以及被用户修改过 Description 的 Profile 都不会删除；用户修改标记等同于主动退出自动清理。Adapter 销毁较慢时，清理会由服务启动时和运行期间的后台检查继续完成。

stop_interfaces_on_exit = false 时，无论收到普通停止、服务重启还是 Windows 关机信号，服务都不会主动关闭或清理接口。服务再次启动后，会按 wg.exe 中的接口名和对应配置文件里的 WgBin 重新接管仍在线的 userspace 接口，不核对实际进程路径，也不重启它；若服务停止期间接口消失或被重新创建，旧 Profile 会被清理，新 Profile 会重新标记。外部重启没有恢复完整网络配置时，可运行 wg-quick-win.exe sync <接口名>。

配置文件

WireGuard 后端

wg-quick-win 支持两类后端：

• 官方 NT 后端：接口配置不写 WgBin 时使用。wg-quick-win 调用官方 WireGuard for Windows 的 wireguard.exe /installtunnelservice 创建 WireGuardNT 接口，然后自行写入运行时配置并配置地址、DNS 和路由。
• userspace 后端：接口配置写了 WgBin 时使用。无论二进制叫什么名字，都按 userspace 程序启动，并按 [wireguard].wintun 或自动查找结果注入 Wintun。

全局 WireGuard 路径配置：

[wireguard]
official_bin = ""
wg_tool = ""
wintun = ""

official_bin、wg_tool 和 wintun 都是可选项：

• 为空或不写时才会自动查找；只要显式填了路径，就严格使用该路径。配置路径不存在会立即报错，不会再 fallback 到自动查找。
• official_bin 为空时，会自动查找官方 WireGuard for Windows 的 wireguard.exe，查找顺序包括 C:\Program Files\WireGuard、C:\Program Files (x86)\WireGuard 和 PATH。
• wg_tool 为空时，会自动查找 wg.exe，用于 wg 子命令、状态查询和 userspace 后端的 setconf 回退。
• wintun 可填 wintun.dll 文件路径或所在目录；为空时，userspace 后端会从 WgBin 自身目录、PATH、官方 WireGuard 目录和 System32 自动查找。找到后会同步到 WgBin 所在目录，确保 Wintun 加载器能找到它。
• 如果使用自动查找，请先安装官方 WireGuard for Windows；它提供 wireguard.exe、wg.exe 和官方 NT 后端所需的系统组件。
• 如果使用 userspace 后端，请另外准备来自 wintun.net 的 wintun.dll。官方 WireGuard 安装目录通常没有这个 DLL。
• default_bin 已废弃并会被忽略；userspace 后端必须在接口配置里显式写 WgBin。

userspace 后端示例：

[Interface]
WgBin = C:\opt\bin\wg-quick-win\wireguard-mix.exe

接口配置支持常用 WireGuard / wg-quick 字段：

[Interface]
PrivateKey = ...
ListenPort = 51820
FwMark = 0
Address = 10.0.0.2/24
DNS = 1.1.1.1
MTU = 1420
Table = auto
PreUp = ...
PostUp = ...
PreDown = ...
PostDown = ...

[Peer]
PublicKey = ...
PresharedKey = ...
Endpoint = example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

SaveConfig 不支持；wg-quick-win 不会回写接口配置文件。接口配置里的未知字段会直接报错，避免配置看起来写了但实际没有生效。

FwMark 主要是 Linux / BSD 上配合策略路由或防火墙使用的 WireGuard 字段，Windows 没有等价语义。wg-quick-win 会解析并下发该字段以兼容配置语法，但在 Windows 上通常没有实际效果；不写 FwMark 表示不下发该字段，FwMark = 0 或 FwMark = off 表示显式清除 mark。

DNS 和 DDNS

DNS resolver 通过 [enhanced_dns].default_resolver 选择：

[enhanced_dns]
default_resolver = "system" # 可选：system, doh, dot

socks5 和 http 不是 resolver 名称，不能填到 default_resolver。它们只在 default_resolver = "doh" 或 "dot" 时作为传输代理使用；两者同时启用时优先使用 SOCKS5。

DoH / DoT 解析 endpoint 时会先查 A 记录；如果没有可用 IPv4 结果，会继续查 AAAA 记录。

ddns-update 会输出：

wg0  endpoint=example.com:51820  previous_ip=1.2.3.4  resolved_ip=1.2.3.4  status=unchanged

状态含义：

• updated：解析 IP 与当前 endpoint 不同，已更新。
• unchanged：解析 IP 没变，没有重写 endpoint。
• skipped: interface not running：接口未运行，不更新。
• error: ...：解析或更新失败。

日志

服务日志由 [log].file 配置，默认示例写到：

C:\opt\bin\wg-quick-win\logs\service.log

每个接口的 WgBin stdout/stderr 默认写到同目录：

C:\opt\bin\wg-quick-win\logs\<接口名>.log

• [log].flush = true 会让服务日志立即落盘。

• [log].wgbin_flush = true 会让 WgBin 日志也立即落盘，通常只在调试 wireguard-mix 时开启。

其他

• only_ifaces 优先级高于 skip_ifaces。
• [start_on_boot].enabled = true 后，服务会按 [start_on_boot].interval 秒定期检查目标接口；接口没运行或被外部关闭时会重新尝试启动，已运行接口会跳过。
• [start_on_boot].only_ifaces 只控制自动启动/保活；[ddns].only_ifaces 只控制 DDNS 监控。两者互不影响。
• DDNS 监控按接口分别定时执行；同一个接口的 up、sync、down、自动保活和 DDNS 更新会串行执行，避免同时改运行中配置。
• [service].stop_interfaces_on_exit = true 时，普通停服、服务重启和 Windows 关机都会尝试关闭接口；设为 false 后，服务收到任何停止信号都不会主动关闭或清理接口，相关工作留到服务下次启动。这个值由服务进程启动时读取，改完配置后需要重启服务才会生效。

排障

• 如果 Go UAPI 无法访问 userspace WgBin，管理器会回退到 wg.exe setconf。

• 服务安装、卸载、启动和停止需要管理员权限。CLI 会针对 1053、1058、1072、权限不足和 IPC pipe 不存在给出提示。

• 如果 Windows 返回 1072，表示服务已标记删除但仍有句柄未释放。关闭 Services 管理器、Event Viewer、旧终端后稍等；必要时重启 Windows。

查看 Windows 网络状态：

netsh interface ipv4 show addresses
netsh interface ipv4 show route
netsh interface ipv4 show dnsservers

查看 WireGuard 状态：

.\wg-quick-win.exe wg show

如果 start-service 报 1058，服务可能被禁用，重新运行：

.\wg-quick-win.exe install
.\wg-quick-win.exe start-service

检查服务安装情况：

sc.exe qc wg-quick-win