Skip to content

Code Structure

Jump to bottom
dongle edited this page Oct 18, 2026 · 6 revisions

中文 | English

代码结构 (Code Structure)

面向贡献者与二次开发者的仓库结构说明。约定细节见仓库根目录的 AGENTS.md。FlowWeaver 源自 SniShaper，共享部分技术思路（sing-tun 数据面、uTLS/ECH 处理），但代码库独立演进。

技术栈

层 技术
后端 Go 1.27+，Wails v3 绑定，模块名 flowweaver
前端 React 19 + TypeScript + MUI + Vite，@iconify/react 图标（Material Symbols / MDI，离线打包）
核心 Mihomo 衍生核心进程（with_gvisor 标签构建，TUN 依赖 gVisor）；订阅节点拨号/测速以库形式直接复用 mihomo adapter
打包 Windows MSIX（PFX 签名）、跨平台 CLI 12 目标矩阵

目录结构

FlowWeaver/
├── main.go                 # 入口：Wails 应用装配 + 托盘初始化
├── app/                    # Go 后端应用层
│   ├── app_api.go          #   App 结构体与全部前端绑定 API
│   ├── app_subscription.go #   订阅管理 API（导入/切换/节点选择）+ 节点与服务延迟探测
│   ├── app_fragment.go     #   TLS 分片参数 API（读取/设置/重置）
│   ├── app_system.go       #   系统代理开关（注册表写入）
│   ├── autostart_*.go      #   开机自启（Windows: 任务计划程序）
│   ├── app_tray*.go        #   托盘：构建、会话监听、reshow
│   └── app_update*.go      #   版本检查、下载与自更新安装
├── core/                   # 核心进程管理
│   ├── core_client.go      #   核心进程拉起、RPC 客户端（带 token 鉴权）
│   ├── core_api.go         #   核心内 RPC 服务（Ping/Shutdown 需 token 校验）
│   ├── core_runtime.go     #   核心运行时装配（TUN、证书、规则、订阅）
│   └── core_admin_*.go     #   管理员提权
├── 引擎与共享能力包 proxy/ 与 {subscription,singtun,netiface,certmanager,
│         cfpool,dohresolver,rules,tlsfrag,sysproxy,evolution}/   # 已迁至 snishaper-core
├── pkg/                    # 本地功能包（两个）
│   ├── sysproxy/           #   薄封装：委托 core 的 sysproxy.Manager
│   └── platform/           #   平台适配（如 DNS 恢复）
├── internal/rulesguard/    # rules/config.json 数据守卫测试
├── cli/                    # headless CLI（构建标签 headless）
│   ├── main.go             #   入口 + 命令分发
│   ├── catalog.go          #   命令目录（help 与 TUI 的单一事实来源）
│   └── tui.go              #   交互面板
├── frontend/src/           # React SPA，11 个页面
│                           #   Dashboard、Subscription、Proxies、Rules、Routing、
│                           #   DNS、Evolution、Logs、Settings、About、Welcome
├── common/                 # 跨平台工具（打开文件/URL、路径、崩溃日志）
├── rules/config.json       # 站点组规则
├── config/settings.json    # 应用设置：端口、TUN（栈/网卡名）、主题与外观模式、TLS 分片、Cloudflare IP 等
└── Platform.md / build.md  # 平台支持与构建矩阵文档

数据流

前端 (React HashRouter)
   │  Wails 绑定：EventsOn 订阅 + 异步 Go 方法调用
   ▼
App API (app/app_api.go)
   │
   ├──► snishaper-core/subscription  Clash 订阅解析 → 节点/代理组/规则
   ├──► snishaper-core/proxy          代理服务器（模式分发、多协议拨号、订阅 UDP 中继）
   ├──► core/                         核心进程（TUN、gVisor 栈、自动路由、DNS 劫持）
   └──► snishaper-core/{certmanager,dohresolver,cfpool,gfwlist}  证书 / DoH / CF 优选池 / GFWList
  • 前端状态同步：后端通过 emitFrontendState() 发出 app:state / app:state_changed 事件，前端订阅后刷新 UI。
  • 订阅生效链路：sub use → 订阅规则经 core 的 proxy/rules_merge.go 合并加载并隐藏内置规则 → 节点选择写入订阅存储 → core 的 proxy/subscription_dialer.go 按选中节点拨号（TCP/UDP）。带原始 Clash 配置的节点优先经 core 的 subscription/mihomo.go 走 mihomo adapter.ParseProxy（协议/传输支持与 Clash 内核完全一致，节点测速即内核 URLTest），无原始配置的节点回落自研拨号器。
  • TLS 分片参数三级回落：规则级 frag > 全局 settings.json 的 fragment 段 > tlsfrag.DefaultTLSRF* 预设；NumRecords=1 且 NumSegments>=2 表示「仅 TCP 分片」（字节不改，切点移到 SNI 之前）。
  • WireGuard 隧道以用户态 IP 栈运行：不创建内核网卡、不改系统路由表；TUN 的 UDP 流量经 singtun 的 UDP relay 走当前订阅节点。
  • TUN 数据面只做域名嗅探重建（fake-ip 反查失败时读首包嗅探 SNI），绝不改写 ClientHello —— TLS 转录哈希覆盖整个握手包，中途改字节会导致 bad record MAC；SNI 伪装只在 TLS 端点侧（MITM 出站重放）进行。
  • 核心进程 RPC 隔离：核心与客户端之间用一次性 token 鉴权（Ping/Shutdown 均需校验），避免重叠实例误杀新核心。

snishaper-core 依赖

代理引擎自 github.com/SnishaperTeam/snishaper-core 引入（go.mod 固定 v0.4.0，无 replace），不再 fork 到本仓库：

  • 本仓库直接导入：proxy、certmanager、cfpool、dohresolver、netiface、singtun、subscription、sysproxy、evolution、config、log
  • 另有 tlsfrag（core 的 proxy/proxy.go、proxy/tls_fragment.go）与 gfwlist（core 的 proxy/auto_routing.go）在 core 内部使用，本仓库不直接导入
  • pkg/sysproxy 仅为薄封装：持有单个 core sysproxy.Manager 实例并转发原有包级函数，调用点不变。core 的 Manager 按实例持有原始代理快照与状态缓存，sudo 场景经 sysproxy.WithRunAsUser 注入原用户
  • 产品差异通过注入而非分叉：config.Brand{Name: core.ProductName}（core.ProductName = "FlowWeaver"）、proxy.WithProductName(core.ProductName)，以及两个 subscription.NewStore 调用点的 subscription.WithProductName(core.ProductName)
  • 订阅下载的 User-Agent 由 core 依 config.Brand 拼成（clash-verge/v2.0 <产品名>）。core v0.3.0 及更早把 FlowWeaver 写死、且把每次 SNI 嗅探按 info 级打印；自 v0.4.0 起 sysproxy 与 evolution 也收进库中（此前两个仓库各存一份逐字节相同的副本），故本仓库要求 ^v0.4.0
  • netiface 为按实例使用：netiface.NewSelector() 创建、(*netiface.Selector).Invalidate() 在 TUN 启停后刷新，取代旧的包级 netiface.InvalidateCache()

构建与测试

  • 全量构建：.\build_windows.ps1 -All -Silent（指定平台/架构用 -Platform windows -Arch x64 -Type cli,gui；仅后端/前端用三元组 -Build windows,gui,backend，scope 是第三项，-Build backend 非法。Linux/macOS 用 ./build.sh；12 目标矩阵见 build.md）
  • Go 编译检查：go build -tags with_gvisor ./...
  • Go 测试：go test -tags with_gvisor ./...（flowweaver/app、flowweaver/common、flowweaver/core、flowweaver/internal/rulesguard）
  • Go 静态检查：go vet -tags with_gvisor ./...
  • 前端类型检查（权威）：cd frontend && ./node_modules/.bin/tsc --noEmit
  • headless CLI：见 CLI 命令参考 的自建章节

贡献须知

  • 提交信息使用英文 conventional-commit 风格（feat: / fix: / refactor: …）。
  • 新增 UI 文案必须同步补齐 zh / en / ru 三份 i18n JSON，占位符保持一致。
  • 更改文件性质或新增文件时，同一变更内必须更新本 Wiki（zh + EN 页面）。
  • 安全敏感区（证书、TUN、系统代理、核心 RPC token）改动需维护者审查。

目录 / Contents

中文文档

English Docs

Clone this wiki locally