# NCVpn

**Repository Path**: deep-learing_admin/NCVpn

## Basic Information

- **Project Name**: NCVpn
- **Description**: 简单科学上完工具，由codex编写
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NCVpn

NCVpn 是一个基于 Xray Core 的开源代理客户端。项目包含 Windows WPF 客户端、Windows/macOS Avalonia 桌面客户端以及 Android 原生客户端，当前核心连接能力以 **VLESS + Reality** 为主。

> 本项目仅供网络技术研究与合法用途。使用者应遵守所在地法律法规以及网络服务提供商的使用条款。

## 功能特性

- VLESS + Reality 节点连接，支持 TCP、WebSocket 和 gRPC 传输参数
- 一键连接、断开以及连接状态显示
- 规则代理和全局代理两种模式
  - 规则模式：`geosite:cn`、`geoip:cn` 和私有地址直连
  - 全局模式：除私有地址外的流量通过代理
- Windows/macOS 系统代理自动设置与断开恢复
- Android `VpnService` 全设备流量接管
- 节点添加、编辑、删除、延迟测试、导入和导出
- `vless://` 分享链接剪贴板导入
- 订阅地址保存与更新
- 出口 IP、地理位置、连接时长和实时流量展示
- Windows 系统托盘、开机自动连接、最小化到托盘和通知设置
- Windows WPF 已实现 DNS 防泄漏、Chrome/Edge/Firefox WebRTC 防泄漏、Kill Switch 和局域网访问控制
- 便携式配置：配置、节点和日志保存在程序目录中

## 平台支持

| 平台 | 客户端 | 当前状态 | 连接方式 |
| --- | --- | --- | --- |
| Windows 10/11 | WPF | 主要桌面版本 | 系统代理；TUN 设置目前在界面中禁用 |
| Windows 10/11 | Avalonia | 可运行的跨平台桌面版本 | 系统代理 |
| macOS Intel / Apple Silicon | Avalonia | 支持便携包 | 系统 HTTP/HTTPS 代理，不支持 TUN |
| Android arm64-v8a / x86_64 | 原生 Kotlin | 实验性实现 | Android `VpnService` + Xray TUN |

目前节点模型预留了 VMess、Trojan 和 Shadowsocks 字段，但 Xray 配置生成器只实现了 VLESS 出站，请勿将其他协议视为已支持功能。

## 软件架构

```text
NCVpnClient/
├── src/
│   ├── NCVpnClient.Core/       # 共享模型、配置、节点和 Xray 运行服务
│   ├── NCVpnClient/            # Windows WPF 客户端
│   ├── NCVpnClient.Avalonia/   # Windows/macOS Avalonia 客户端
│   └── NCVpnClient.Android/    # Android 原生客户端
├── tests/                      # Core、WPF 和 Avalonia 测试
├── tools/                      # macOS 发布、Android 构建等脚本
├── docs/                       # 平台实现和打包说明
└── NCVpnClient.sln
```

桌面端采用 MVVM 分层：

- `NCVpnClient.Core`：跨平台业务逻辑，包括 `NodeService`、`SettingsService`、`XrayService` 和 `XrayConfigBuilder`
- `NCVpnClient`：WPF 界面、Windows 注册表系统代理、托盘和 Windows 平台服务
- `NCVpnClient.Avalonia`：跨平台界面以及 Windows/macOS 系统代理实现
- `NCVpnClient.Android`：Kotlin UI、`VpnService`、原生 Xray 启动桥接和 Android 路由配置

主要技术栈为 .NET 8、WPF、Avalonia 12、CommunityToolkit.Mvvm、Kotlin、Gradle 和 Xray Core。

## 获取源码

```bash
git clone https://gitee.com/deep-learing_admin/NCVpn.git
cd NCVpn/NCVpnClient
```

仓库已包含桌面端所需的 Xray 可执行文件、`geoip.dat`、`geosite.dat` 和 Windows `wintun.dll`。Android 构建还需要本机安装 Android SDK。

## 编译与运行

### Windows WPF 客户端

环境要求：

- Windows 10/11
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- 可选：Visual Studio 2022（安装“.NET 桌面开发”工作负载）

```powershell
cd NCVpnClient
dotnet restore NCVpnClient.sln
dotnet build src/NCVpnClient/NCVpnClient.csproj -c Release
./Release/NCVpnClient.exe
```

### Avalonia 桌面客户端

直接运行开发版本：

```powershell
cd NCVpnClient
dotnet run --project src/NCVpnClient.Avalonia/NCVpnClient.Avalonia.csproj
```

发布 macOS Intel 和 Apple Silicon 便携包：

```powershell
./tools/publish_macos.ps1 -Runtime all -Configuration Release -Version 1.0.0
```

生成的压缩包位于 `dist/macos/`。在 macOS 解压后先执行：

```bash
bash ./test_macos_package.sh
./NCVpnClient.Avalonia
```

如果系统阻止首次启动，请前往“系统设置 → 隐私与安全性”允许该应用。详细说明见 [`NCVpnClient/docs/macos-portable-zh.md`](NCVpnClient/docs/macos-portable-zh.md)。

### Android 客户端

环境要求：

- JDK 17
- Android SDK（设置 `ANDROID_HOME` 或 `ANDROID_SDK_ROOT`）
- Android NDK 与 CMake

```powershell
cd NCVpnClient
./tools/build_android.ps1 -Configuration Debug
```

脚本在找不到 Gradle 时会下载 Gradle 8.9。Debug APK 默认生成在：

```text
src/NCVpnClient.Android/app/build/outputs/apk/debug/app-debug.apk
```

## 使用说明

### 1. 添加或导入节点

1. 打开“节点管理”。
2. 点击“添加节点”手动填写名称、地址、端口、UUID、传输方式、SNI、Reality 公钥、Short ID、Flow 和指纹。
3. 或复制完整的 `vless://` 分享链接，然后点击“从剪贴板导入”。
4. 保存节点，可使用“测速”检查服务器 TCP 连接延迟。

示例链接结构：

```text
vless://UUID@server.example.com:443?encryption=none&security=reality&type=tcp&sni=example.com&pbk=PUBLIC_KEY&sid=SHORT_ID&flow=xtls-rprx-vision&fp=chrome#节点名称
```

请使用自己的有效节点信息；仓库中的示例节点不保证可用。

### 2. 选择代理模式

- **规则**：国内域名、国内 IP 和局域网地址直连，其余流量使用节点。
- **全局**：除局域网等私有地址外，流量均使用节点。

### 3. 连接

1. 在主界面选择节点和代理模式。
2. 点击“连接”。
3. 等待状态变为“已连接”，界面将展示脱敏后的出口 IP 和连接信息。
4. 使用完成后点击“断开”，程序会恢复连接前的系统代理设置。

Windows WPF 客户端会在正常断开、启动恢复和 watchdog 异常退出恢复中尽量还原系统代理、DNS、浏览器策略和防火墙规则。若整机断电或系统阻止管理员权限导致恢复失败，请重新启动客户端触发恢复，或按 [`NCVpnClient/docs/windows-network-protection.md`](NCVpnClient/docs/windows-network-protection.md) 手动核查。

### 4. Windows 网络保护设置

以下设置仅指 Windows WPF 客户端：

- **DNS 防泄漏**：连接前保存活动网卡 DNS，连接时切换到自定义 DNS 或默认安全 DNS，断开、启动恢复或 watchdog 恢复时还原原 DHCP/静态 DNS。启用时会请求管理员权限。
- **WebRTC 防泄漏**：写入当前用户的 Chrome、Edge 和 Firefox 企业策略，限制 WebRTC 直接暴露本机地址；浏览器通常需要重启后完全生效。
- **Kill Switch**：Xray 异常退出时先启用会话级 Windows 防火墙规则阻断外连，然后在 10 秒内尝试自动重连；重连失败则恢复连接前状态。
- **允许局域网访问**：开启时保留 `192.168.x.x`、`10.x.x.x` 等家庭/公司内网直连；关闭时连接期间阻止访问局域网地址，降低本机内网地址泄漏风险。

DNS 防泄漏和 Kill Switch 依赖 Windows DNS/防火墙配置，系统会弹出 UAC 管理员权限确认。拒绝授权时本次连接会失败并回滚已应用的保护。

### 5. 订阅管理

在“节点管理”中填写订阅名称和 URL 后添加订阅，再执行更新。订阅内容应为 Base64 编码或逐行排列的 `vless://` 链接。

## 配置和运行目录

桌面客户端采用便携目录，不写入 `%AppData%`：

```text
程序目录/
├── NCVpnClient.exe 或 NCVpnClient.Avalonia
├── xray.exe 或 xray
├── geoip.dat
├── geosite.dat
├── wintun.dll                 # 仅 Windows
├── Config/
│   ├── settings.json
│   ├── nodes.json
│   ├── subscriptions.json
│   └── xray_config.json       # 连接时生成
├── Logs/
│   └── xray.log
└── Resources/
    ├── default-settings.json
    └── nodes.json
```

程序目录需要有写权限。备份时复制 `Config/` 即可保留设置、节点和订阅。

本地代理端口由当前实现固定为：

- SOCKS5：`127.0.0.1:10808`
- HTTP：`127.0.0.1:10809`

## 节点配置示例

`Config/nodes.json` 为 JSON 数组，示例：

```json
[
  {
    "Id": "node-001",
    "Name": "示例节点",
    "Protocol": "VLESS",
    "Address": "server.example.com",
    "Port": 443,
    "UUID": "00000000-0000-0000-0000-000000000000",
    "Encryption": "none",
    "Transport": "tcp",
    "Security": "reality",
    "Sni": "example.com",
    "PublicKey": "REALITY_PUBLIC_KEY",
    "ShortId": "SHORT_ID",
    "Fingerprint": "chrome",
    "Flow": "xtls-rprx-vision",
    "Group": "默认分组",
    "Enabled": true
  }
]
```

## 测试

运行全部 .NET 测试：

```powershell
cd NCVpnClient
dotnet test NCVpnClient.sln
```

macOS 包还可以使用随包附带的脚本检查文件、架构、Xray 配置和启动条件：

```bash
bash ./test_macos_package.sh
```

## 常见问题

### 连接失败

- 检查节点地址、端口、UUID、SNI、公钥和 Short ID 是否匹配。
- 确认系统时间正确，Reality/TLS 对时间偏差较敏感。
- 检查服务器端口是否可达。
- 查看 `Logs/xray.log` 获取 Xray 错误信息。

### 已连接但浏览器无法访问网络

- 确认已启用“系统代理”。
- 检查 `127.0.0.1:10809` 是否被其他程序占用。
- 断开其他代理软件，避免系统代理配置冲突。
- 可临时将浏览器 HTTP 代理设为 `127.0.0.1:10809` 排查问题。

### macOS 断开后仍保留代理

打开当前网络服务的代理设置，关闭“网页代理 (HTTP)”和“安全网页代理 (HTTPS)”。正常断开或退出时客户端会自动恢复原设置。

### Windows TUN 无法启用

当前 WPF 设置页中的 TUN 开关处于禁用状态，Avalonia macOS 版也明确不支持 TUN。Windows 请使用系统代理模式；Android 使用系统 `VpnService`。

## 当前限制

- Xray 出站目前只完整实现 VLESS，其他协议尚未接入配置生成器。
- Windows/macOS 桌面端主要使用系统代理，并非所有不遵循系统代理的应用都会被接管。
- macOS 暂不支持 TUN。
- Windows WPF 的 TUN 选项暂不可用。
- Windows 网络保护依赖管理员权限和 Windows 防火墙/注册表策略；浏览器 WebRTC 策略需要重启浏览器后完整生效。
- watchdog 能处理客户端进程崩溃后的恢复，但无法覆盖整机断电、系统服务不可用或权限被拒绝等情况。
- Android 客户端仍属于实验性实现，发布前应在目标设备和网络环境中充分验证。
- “自定义监听端口”目前为保留设置，实际 SOCKS/HTTP 端口仍固定为 10808/10809。

## 参与贡献

1. Fork 本仓库。
2. 从主分支创建功能分支，例如 `feature/node-import`。
3. 提交代码并补充相应测试或文档。
4. 确保 `dotnet test NCVpnClient.sln` 通过。
5. 提交 Pull Request，说明变更目的、平台和验证方式。

## 相关链接

- [Gitee 仓库](https://gitee.com/deep-learing_admin/NCVpn)
- [问题反馈](https://github.com/huangyhg/VPN/issues)
- [赞助支持](https://paypal.me/NCVPN)
- [macOS 便携版说明](NCVpnClient/docs/macos-portable-zh.md)
- [Android 运行时说明](NCVpnClient/docs/android-vpn-runtime.md)

## 作者

主作者：yoyo

## 版本

当前项目版本：`1.0.0`