Skip to content

ZH Architecture

Jump to bottom
SlimRG edited this page Aug 23, 2026 · 1 revision

架构

shadowsocks-reborn 5.2.31 是面向 Windows 10/11 x64 的 WinUI 3 桌面客户端。项目将平台无关核心、Windows 集成、WinUI 集成、主应用以及提升权限的透明抓包 helper 分离。

项目关系

Shadowsocks.WinUI
  ├── Shadowsocks.Core
  ├── Shadowsocks.Windows
  └── Shadowsocks.Windows.WinUI

Shadowsocks.Windows
  └── Shadowsocks.Core

Shadowsocks.Windows.WinUI
  └── 独立的 WinUI shell/tray 集成库

Shadowsocks.NetworkService
  └── 独立 elevated helper
      + linked 的 dependency-free FilterEngine.cs
  • Shadowsocks.Core (net10.0)：配置、协议、加密、GeoSite、PAC 模型、managed routing、本地化和通用服务。
  • Shadowsocks.Windows：系统代理、存储、启动、自更新、热键、插件、UAC/Admin Mode、WinDivert 和 NetworkService 协调。
  • Shadowsocks.Windows.WinUI：WinUI-specific 的 tray/QR/power/shell 集成，不通过 ProjectReference 依赖 Core/Windows。
  • Shadowsocks.WinUI：主 WinUI 3 应用，release assembly 名为 Shadowsocks。
  • Shadowsocks.NetworkService：x64 提权 helper，负责 transparent TCP/UDP capture。
  • Shadowsocks.UnitTests：不依赖 presentation layer 的测试项目。

Shadowsocks.Core 不应依赖 WinUI、WinForms、WPF 或 Windows App SDK。项目不再引入 WinForms/WPF。

Managed routing：最终 Variant B

Local GeoSite + EasyList/ABP routing 的唯一决策引擎是 C# Shadowsocks.Routing.FilterEngine。

GeoSite + user-rule.txt
        ↓
C# FilterEngine
        ↓
RoutingDecision
   ├── DIRECT
   └── PROXY

历史 abp.js、compiled-PAC compatibility backend、backend selector 和可执行 custom abp.txt 已移除。

支持的 network-filter subset 包括 @@、||domain^、| anchors、*、^、正则规则、$domain= 与 $match-case。简单域名规则通过 suffix index 匹配；复杂规则使用 keyword index 和 bounded decision cache。

User Mode / Local PAC

Windows 系统代理仍需要 PAC 作为入口，因此 Local PAC 只保留最小 FindProxyForURL，把请求送入本地 managed proxy。PAC 本身不负责 DIRECT/PROXY 判断。

WinINet / system PAC
      ↓
minimal PAC funnel
      ↓
ManagedHttpProxyService
      ↓
application rules
      ↓
C# FilterEngine
      ↓
DIRECT / PROXY

Online PAC

Online PAC 是独立且显式启用的模式。外部 .pac 按 PAC 标准本身就是 JavaScript 程序，由 Windows 执行。它不属于 Local EasyList/ABP engine，也不会重新引入 abp.js。

Administrator Mode

在 WinDivert SYN 阶段通常只有 PID 与 destination IP，没有可靠 hostname。因此没有显式 application rule 的普通 TCP 首先得到 Deferred。

Transparent TCP relay 只缓存有限的客户端前缀（上限 64 KiB），并解析：

  • HTTP request line + Host；
  • TLS ClientHello SNI。

不解密 TLS、不安装 CA、不替换证书。获得 Host/SNI 后，helper 使用同一 dependency-free FilterEngine，选择 direct socket 或现有 Shadowsocks SOCKS5 path。

Application Direct / Proxy / Block 规则优先级更高。UDP 在该层没有可靠 hostname；ECH/no-SNI/server-first/未知协议采用确定性 fallback。DNS/53 使用独立 DNS policy。

DNS

DNS policy 包括 System、Direct、Proxy、CustomDoh、DnsCrypt。

Administrator Mode 可透明处理 UDP/TCP 53。DNSCrypt 作为按需下载并验证的 managed component 运行。活跃 DNSCrypt 使用 fail-closed 逻辑：切换或故障期间不能回退到明文系统 DNS。

应用生命周期

Program.Main
  ↓
Windows App SDK AppInstance
  ↓
ProcessSingleInstanceGuard
  ↓
App
  ↓
WindowsStorageBootstrapper
  ↓
ShadowsocksController
  ↓
MainWindow / tray / pages

关闭主窗口只是隐藏窗口；显式 Quit 才停止 controller。AppInstance redirect 加上独立 process-wide guard，避免 primary EXE 与 LocalAppData startup copy 同时占用端口。

SIP003 插件

插件位于 Plugins\<plugin-id>。只有受信任的内置目录 xray-plugin、v2ray-plugin、qtun 可进行后台网络更新：controller 启动后运行 maintenance，manager 将成功 release check 限制为每 24 小时一次，正在使用的插件推迟到后续检查。手工 ZIP/TAR.GZ import 永不 auto-update。更新通过 staging + rollback-safe directory swap 完成，并在替换前再次验证 provenance。任意 repository source 在建立独立 trust/asset-selection contract 前不接受。运行时通过 PluginManager 解析，不使用任意 PATH 或 EXE 旁路径 fallback。

自更新

Self-update 只接受规范的 Shadowsocks-win-x64.zip 与 .sha256，验证 checksum、ZIP layout 与 FileVersion，在 %TEMP%\Shadowsocks\Updates staging，并采用 rollback-safe replacement 与 anti-downgrade 检查。

存储

可变数据绝不写到 release EXE 旁。详见 存储策略。

相关页面

DNSCrypt 解析器目录引导

Shadowsocks Reborn 由应用自身刷新已签名的 DNSCrypt 解析器目录，不允许 dnscrypt-proxy 通过 bootstrap DNS 解析远程 source 主机名。主解析路径为 Cloudflare DoH（1.1.1.1，TLS/SNI cloudflare-dns.com），备用路径为 Google DoH（8.8.8.8，TLS/SNI dns.google）；两条 DoH HTTPS 连接都通过当前本地 Shadowsocks SOCKS5 打开。源主机名经该 DoH 路径解析后，public-resolvers.md 与 .minisig 的 HTTPS 下载同样通过 Shadowsocks。

下载大小受到限制，并在发布前使用固定的 DNSCrypt 公共 Minisign 密钥验证。随后 dnscrypt-proxy 只获得本地认证缓存，配置为 urls = []、bootstrap_resolvers = [] 和 ignore_system_dns = true。如果刷新暂时失败，可以继续使用已有且签名有效的缓存；若不存在有效缓存，则操作 fail-closed，并保留之前的 DNS 模式。

Clone this wiki locally