# 防御型端口转发器 **Repository Path**: ahsin/cn-magic-port-forwarder ## Basic Information - **Project Name**: 防御型端口转发器 - **Description**: CN魔力 - 防御型端口转发器 v1.5.2:Windows TCP/UDP 端口映射与透明转发工具(WPF + 独立引擎进程 + WinDivert 透明 NAT + 防攻击引擎 + 前置内网检测) - **Primary Language**: C# - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-08-09 - **Last Updated**: 2026-10-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CN魔力 - 防御型端口转发器 · 开发说明 > **本项目全部由 AI 开发。** > > **开源协议:拿去随便玩,与我无关。** > 本文档用于让新环境(新电脑 / 新 AI 会话)快速理解本项目的开发逻辑。 > 读完本文档 + 浏览代码目录结构,即可继续迭代开发。 --- ## 1. 项目简介 **CN魔力 - 防御型端口转发器**:Windows 下的 TCP/UDP 端口映射与透明转发工具。 - 普通转发:监听本机端口 → 转发到目标 IP+端口(新建连接,目标看到转发者 IP) - 透明转发(透明 NAT):数据包级改写目标地址、**保留访客真实源 IP**,目标服务器看到的是访客 IP(等同路由器行为),依赖 WinDivert 内核驱动 - 内置防攻击引擎:限速、并发上限、SYN 洪泛检测、端口扫描识别、威胁评分自动封禁、黑白名单 - 完整监控:连接监控、GEOIP 离线解析、世界地图热点、攻击时间线回放、HTML/CSV 报告导出 ### 界面预览 ![界面预览 1](项目介绍图片/1.png) ![界面预览 2](项目介绍图片/2.png) ![界面预览 3](项目介绍图片/3.png) ![界面预览 4](项目介绍图片/4.png) ![界面预览 5](项目介绍图片/5.png) ![界面预览 6](项目介绍图片/6.png) --- ## 2. 技术栈 | 项 | 选择 | |---|---| | 语言/UI | C# / WPF(.NET 10,`net10.0-windows`) | | 引擎进程 | 独立 .NET 进程(`net10.0`),发布为 **cneg.dll**(WinExe 无控制台) | | IPC | NamedPipe + JSON 帧协议(4 字节长度前缀 + UTF-8 JSON) | | 透明 NAT | WinDivert 2.2-A(P/Invoke,数据包级双向 NAT) | | GEOIP | 内置离线 CIDR 国家库(80+ 国家/地区,无需联网) | | 持久化 | 配置文件 JSON(exe 同目录 `config.json`) | | 打包 | 单文件自包含发布(PublishSingleFile + SelfContained) | --- ## 3. 目录结构 ``` code/ ├── src/ │ ├── PortMapper.UI/ # WPF 主程序(界面 + 引擎托管/守护) │ │ ├── MainWindow.xaml # 主窗口(映射列表、监控页、防攻击设置) │ │ ├── AboutWindow.xaml # 关于窗口(可点击官网链接) │ │ ├── EngineHost.cs # 引擎进程拉起 / 守护 / IPC / 心跳 / 重启 │ │ ├── Controls/ # 自定义控件:WorldMap 热点图、TimelinePanel 时间线等 │ │ └── Report/ # HTML/CSV 报告导出 │ ├── PortMapper.Engine/ # 转发引擎(独立进程,发布为 cneg.dll) │ │ ├── EngineCore.cs # 引擎主逻辑:映射管理、防攻击、快照 │ │ └── Windivert/ # 透明 NAT:P/Invoke、驱动安装、双向改写 │ └── PortMapper.Core/ # 共享:模型、消息、ConfigStore、GEOIP ├── thirdparty/windivert/ # WinDivert.dll + WinDivert64.sys(来源文件) ├── ui/ # 品牌资源 logo.ico(多尺寸 16~256)/ logo.png(1024) ├── dist/CN魔力 - 防御型端口转发器/ # 发布包(最终交付物) └── tests/ # 测试脚本(e2e 等) ``` --- ## 4. 架构与数据流 ``` ┌──────────────┐ NamedPipe + JSON ┌──────────────────┐ │ PortMapper │◄────────────────────►│ cneg.dll │ │ .UI (WPF) │ 配置下发/心跳/快照 │ PortMapper │ │ 主程序/守护 │ │ .Engine │ └──────────────┘ └────────┬─────────┘ │ WinDivert(管理员) 数据包级透明 NAT → 目标服务器 ``` - **UI 负责**:规则增删改、配置持久化、监控展示、把引擎当黑盒托管 - **引擎负责**:实际监听/转发/透明 NAT/防攻击/监控数据采集,通过管道推快照 - **进程隔离**:引擎是独立进程,UI 崩溃不影响转发;引擎崩溃/卡死由 UI 守护自动重启 ### 进程守护机制(EngineHost) - 心跳:引擎每 2 秒通过管道推送心跳;超时(默认 8 秒)判卡死 → 强杀重启 - 崩溃:`Process.Exited` 事件 → 自动重启(带最大重启次数上限,默认 5 次) - 强杀统一用 `taskkill /PID /T /F`(透明模式下 `_proc` 是 cmd 提权包装进程,`/T` 才能连引擎一起终止) - **宿主监护(防残留)**:UI 启动引擎时传 `--parent `;引擎后台线程 `WaitForExit` 监护该进程,UI 退出(正常关闭/被强杀/崩溃)后引擎自动优雅结束(`EngineCore.ShutdownForParentExit`),不再产生孤儿 cneg.dll 进程。透明模式经 cmd+runas 提权也不影响(PID 独立于进程树) --- ## 5. 透明 NAT(WinDivert)关键点 - **原理**:`WinDivertOpen` 拦截本机收发数据包,改写目标 IP:端口,保留源 IP(等同路由器 NAT),双向改写 + 重算校验和 - **权限**:透明映射必须管理员权限。引擎经 UI 拉起:存在透明映射时用 `cmd.exe` + `runas` + 隐藏窗口提权(引擎是 cneg.dll,ShellExecute 的 runas 对 .dll 不可靠,故借系统 cmd 提权后 CreateProcess 执行) - **驱动**:`WinDivert64.sys` 首次使用自动复制到 `System32\drivers` 并 `sc create/start` 服务(驱动为微软签名,无警告) - **回包路径(方案A,唯一方式)**:VM/应用的默认网关必须指向转发机,回包才会经转发机改写(纯 WinDivert,**零额外依赖,不再使用 Npcap/ARP 接管**)。未收到回包时会明确告警提示检查 VM 网关 - **文件位置**:`WinDivert.dll` 与 `WinDivert64.sys` 必须放在 **引擎 exe 同目录(软件根目录)**;引擎从根目录加载(`WinDivertNative` 用 `DllImportResolver` 显式解析 DLL) - **驱动安装代码**:`WinDivertDriver.cs`(管理员检测 / 安装 / 本机 IP) --- ## 6. 配置与数据文件(都在 exe 同目录) | 文件 | 用途 | |---|---| | `config.json` | 映射规则 + 全局设置(UI 与引擎共用,引擎启动时也会读) | | `logs/engine.log` | 引擎运行日志(超 5MB 自动轮转保留一个 `.bak`) | | `logs/ui-crash.log` | UI 崩溃日志 | | `logs/stats-YYYYMMDD.jsonl` | 监控统计持久化(JSON Lines:心跳采样/威胁事件,按天滚动,只保留最近 7 天) | **监控数据内存策略**:监控统计由 UI 通过 `StatsRecorder` 先写内存缓冲(ConcurrentQueue),**每 30 分钟批量落盘一次**到 `logs/stats-*.jsonl`(降低硬盘写入频率),程序退出时排空一次;内存仅保留最近一帧快照、最近 720 个时间线采样点(约 24 分钟)与各展示集合(每次快照 Clear+重建),长时间运行内存有界、不累积。 **托盘常驻模式**:主窗口点大叉仅 `Hide()` 到系统托盘(不退出,引擎继续运行);托盘图标右键菜单含「关于 / 退出」,「退出」才会真正结束程序(`_reallyClosing` 置位后走正常关闭流程);左键单击托盘图标恢复主窗口。依赖 WinForms `NotifyIcon`(csproj 已 `UseWindowsForms` 并移除其隐式 using,MainWindow 内用别名 `WF` 引用)。托盘菜单颜色随系统主题(`DarkMenuColorTable` 自定义配色,Opening 时刷新)。 **输入过滤**:映射对话框的「转发名称/备注」在保存前剔除 ASCII 控制字符(`SanitizeText`),防止异常字符破坏 config.json;引号/反斜杠由 System.Text.Json 序列化自动转义。「每IP最大连接数/建连速率」留空 = 0 = 使用全局设置(界面有"留空则使用全局设置"提示)。 **单实例**:`App.OnStartup` 用命名互斥体 `CNMagic.PortMapper.SingleInstance` 防止重复启动;已运行则弹提示并 `Shutdown()` 退出(不创建主窗口),`OnExit` 释放互斥体。 **注意**:配置刻意不写入 `%LOCALAPPDATA%`,全部跟随软件目录(绿色便携)。 --- ## 7. 版本管理规范(重要) - **版本号单点定义**:三个 csproj 的 `` 必须一致(UI / Engine / Core) - **自动同步**:主窗口标题、右下角状态栏、关于窗口、exe 文件属性均从**程序集版本**读取,改 csproj 一处即可全部同步 - **迭代规则**:**每次功能/修复迭代,版本号都要累加**。版本号遵循 **单数.单数.单数**(主.次.修订,每段均为**一位数字 0~9**,禁止出现两位数)。逐位迭代,末位到 9 后向前进位:`1.1.9 → 1.2.0 → 1.2.1 → … → 1.2.9 → 1.3.0`(不再出现 1.1.10 这类两位数写法) --- ## 8. 发布打包流程 命令(在 `code/` 目录执行): ```powershell # 1) 发布主程序(单文件自包含,WPF 原生库内嵌自解压) dotnet publish src/PortMapper.UI/PortMapper.UI.csproj -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true /p:IncludeNativeLibrariesForSelfExtract=true -o dist/_publish/ui # 2) 发布引擎(单文件自包含) dotnet publish src/PortMapper.Engine/PortMapper.Engine.csproj -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true -o dist/_publish/engine ``` 组装发布包(`dist/CN魔力 - 防御型端口转发器/`): ``` CN魔力 - 防御型端口转发器.exe ← ui/PortMapper.UI.exe cneg.dll ← engine/PortMapper.Engine.exe(改名!引擎发布名固定为 cneg.dll) WinDivert.dll ← thirdparty 拷贝(发布时已随引擎输出到根目录) WinDivert64.sys ← 同上 ``` **要点**: - 引擎文件必须叫 **cneg.dll**(防误双击运行;UI 的 `EngineHost.LocateEngineExe` 按此名查找) - `WinDivert.dll / WinDivert64.sys` 放**软件根目录**(引擎从根目录加载) - UI 的 `engine/` 定位有多个候选路径,发布形态是"与 UI 同目录" - 发布包 `config.json` 为运行时数据,重建发布包会清空,正常现象 --- ## 9. 开发约定 - 全程使用**中文注释**;代码注释说明"为什么"而非"是什么" - 命名:C# 标准(PascalCase 类型/方法,camelCase 局部变量) - 关键常量/行为变更时,同步更新本文档与版本号 - **配置保存权限**:程序装在无写权限目录(如 `C:\Program Files\`)时,`config.json` 保存会失败。UI 在 `SaveAndApply` 捕获 `UnauthorizedAccessException/IOException` 等并弹出权限提醒(仅首次弹详细说明,后续失败只在状态栏提示),**不改变** config.json 保存路径;解决方式是管理员运行或把程序移到可写目录 - **IPEndPoint/IPAddress JSON 序列化**:`ConnectionEntry.Client/Target`(`IPEndPoint`)经 STJ 序列化时会读取 `IPAddress.ScopeId`(仅 IPv6 支持),对 IPv4 抛 `SocketException 10045` 导致快照推送失败。已在 `FrameCodec.JsonOptions` 注册 `IpAddressJsonConverter / IpEndPointJsonConverter`,一律按字符串("IP:端口")序列化/反序列化,新增此类端点在模型里直接使用即可 - **防攻击默认值(面向 Web 论坛 Discuz 优化)**:`MaxNewConnectionsPerSecPerIp=60`、`HalfOpenRatioThreshold=0.8`、`ThreatScoreBanThreshold=300`、`BanDurationSeconds=120`、`ScanConnectionsPerSecThreshold=200`。**注意:这些新默认值只对全新 config.json 生效**;老配置里的旧值不会自动迁移,用户在设置页核对一次即可 - **防攻击误伤防护(重要)**:`AntiAttackEnabled` 主开关现在真正生效(关闭后跳过限速/封禁/并发限制,白/黑名单仍生效);威胁评分同一 IP 2s 内只计一次(防突发页面加载被秒封);评分每 2s 自然衰减 -1、半开计数每周期减半、封禁到期自动降到阈值一半——误判可自愈 - **引擎崩溃可观测性**:引擎崩溃(Unhandled/Unobserved/顶层异常)同时写入 `engine.log` 与 `engine-crash.log`;退出码(0xC0000005=内存违例等)由 UI 通过告警浮层提示;周期循环内日志写入失败不中断心跳 - **TCP 转发"几秒后卡死"修复(重要)**:根因是单向 pump 结束后 `Task.WhenAll` 永久挂起(目标侧 keep-alive 阻塞在 ReadAsync),导致两端套接字 + 跟踪条目泄漏,句柄耗尽后 accept 循环 `catch(SocketException) break` 退出,映射"假活"——显示运行中但新连接全部被拒。修复:`WhenAny` 后立即 `Shutdown(Both)` 解除另一方向阻塞再 `WhenAll`;accept/接收循环遇瞬时错误改为记录+200ms 重试,绝不退出循环 - **去除 Npcap / ARP 接管(1.3.4,透明 NAT 只保留方案A)**:删除整个方案B(`NpcapArp.cs`、ARP 周期毒化 + 请求即时应答、`AppSettings.ArpGatewayOverride`、设置页"ARP 接管网关"、UI 的 Npcap 检测/安装引导)。透明 NAT 回包路径**唯一依赖** VM/应用默认网关指向转发机(纯 WinDivert,零额外依赖)。ARP 方案曾引发转发机自身 ARP 缓存被毒化导致断网、以及与真网关抢答导致间歇性丢包卡顿,故整体移除。新增"数据面15s"统计日志(入站/回包改写量)辅助定位卡顿 - **PROXY 协议透传真实访客IP(新增)**:`MappingRule.ProxyProtocol`(仅 TCP 有效,与透明 NAT 互斥)。连接建立后先向目标发送 `PROXY TCP4 <访客IP> <目标IP> <访客端口> <目标端口>\r\n`,目标端 nginx 开启 `proxy_protocol on` 即可读到真实访客 IP。适用同网段旁挂/DMZ 等透明 NAT 物理不可行的拓扑。UI:映射对话框新增复选框(含模式互斥与动态提示),列表"模式"列显示"PROXY",状态显示"运行中(PROXY)" - **透明 NAT 重组(1.2.8,多规则任意端口)**:`TransparentNatHost` 重写为 `TransparentNatManager`:多规则表(任意端口)、NETWORK + NETWORK_FORWARD 双 layer 句柄(回包方向此前完全缺失)、不匹配包原样重注入(不再丢弃)、自动开启 IP 路由、启动 12s 无回包自动告警。回包路径两种方式:方案B(推荐)转发机安装 **Npcap**,引擎用 `wpcap.dll` P/Invoke(`pcap_open_live`/`pcap_sendpacket`)周期发 ARP 应答冒充默认网关,接管 VM 出网路径(VM 零配置;Npcap 未安装/不可用会自动提示并引导);方案A VM/应用默认网关指向转发机(零额外依赖)。**注意**:IP 路由(IPEnableRouter)改注册表,若未立即生效需重启一次系统;ARP 接管每 3s 刷新一次 - **Npcap 启动引导(1.2.9)**:UI 启动时检测 `wpcap.dll`;缺失则弹窗引导安装随附 `npcap\*.exe`(runas 提权,官方安装器;若未放安装包则引导从 npcap.com 下载)。安装后需重启程序生效。发布包需自带 `npcap/` 目录 - **启动环境检查(1.3.0)**:启动时若非管理员弹出提示(透明 NAT/驱动安装需管理员);Npcap 引导弹窗补充"全程下一步,默认安装即可"。透明 NAT 启动时明确记录「IP 路由已开启(若仍不通请重启系统)」或「开启失败」,便于排查 - **ARP 接管网关修复(1.3.1)**:此前用 `GetDefaultGateway()`(转发机自身默认网关,多网段时可能不是 VM 的网关)冒充,导致 ARP 应答发了 VM 不理会、回包照旧不过机。现改为:逐 VM 用 `GetGatewayTo()` 优先取「与 VM 同网段网卡」的网关;ARP 发送网卡也选 VM 所在网段网卡;设置页新增「ARP 接管网关」可手动覆盖(`AppSettings.ArpGatewayOverride`,留空自动检测)。日志逐 VM 打印「VM X → 冒充网关 Y」 - **兼容性:国家地区展示去掉 emoji**:Win10/Server2022 老系统对国旗/🏠/🌐 等 emoji 渲染为乱码,`GeoLocation.DisplayName` 改为纯文字("中国"/"本机/内网"/"未知地区"),并移除 `Flag` 属性及相关赋值 - **托盘气泡**:点击窗口大叉隐藏到托盘时,托盘图标弹出气泡"我在最小化继续运行中哦..."(`ShowTrayBalloon`) - 透明 NAT / WinDivert 改动后,用 `tests/` 下脚本做端到端验证(真实流量 + 目标服务器确认看到访客 IP) - 图标:`ui/logo.ico` 必须是多尺寸(16~256 各一帧),单帧 256 会导致资源管理器小图标模糊 ### 9.1 UI 亮/暗主题自适应(重要) - **机制**:`ThemeManager.cs` 读取注册表 `HKCU\...\Themes\Personalize\AppsUseLightTheme`(0=深色),并通过 `SystemEvents.UserPreferenceChanged` 监听系统主题切换,**运行时实时**替换应用级主题字典(DynamicResource 随之更新,无需重启) - **启动顺序(关键)**:`App.xaml` **不能设 StartupUri**,必须在 `App.OnStartup` 中**先** `ThemeManager.Init()` **再** `new MainWindow().Show()`——隐式样式在元素首次解析时固定,若窗口先于主题加载,按钮/表格/下拉框会回落为系统默认样式(暗色系统下白底白字) - **显式样式必须 BasedOn 主题**:自定义具名样式(如 `ToolButton`)与 Window 级隐式样式(如 DataGrid)需 `BasedOn="{StaticResource {x:Type 对应控件}}"` 继承主题字典样式,否则背景/前景不跟随主题 - **字典**:`Themes/Light.xaml`(亮)与 `Themes/Dark.xaml`(暗),两文件键名必须一一对应;`App.xaml.cs` 启动时调用 `ThemeManager.Init()` - **颜色键**:`ThemeWindowBg / ThemePanelBg / ThemeHeaderBg / ThemeBorder / ThemeGridLine / ThemeTextPrimary / ThemeTextSecondary / ThemeTextMuted / ThemeTextFaint / ThemeAccent / ThemeAccentDark / ThemeDanger / ThemeWarn / ThemeOk / ThemeInputBg / ThemeInputBorder / ThemeTrackBg / ThemeHover / ThemeChartBg / ThemeRowAltBg` - **新增/修改界面硬编码颜色时,一律改用上述主题键(`{DynamicResource ThemeXxx}`),禁止直接写 `#xxxxxx`** - **控件状态色**:Button 样式带自定义模板,Normal/Hover/Pressed/Disabled 分别用 `ThemeHeaderBg / ThemeHover / ThemeTrackBg / 半透明+ThemeTextFaint`——暗色下禁止让控件回落为系统默认模板(浅色高亮) - **ComboBox**:自带完整模板(内容区/下拉箭头/弹出列表/ComboBoxItem 均走主题色),暗色下不会残留系统浅色箭头与白色弹出列表 - 控件隐式样式(TextBlock/TextBox/Button/DataGrid 等)已在字典中定义,颜色统一走主题