Skip to content

README.zh CN

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

shadowsocks-reborn for Windows

Shadowsocks logo

English | Русский | 简体中文 | 中文使用说明

shadowsocks-reborn 是经典 Shadowsocks for Windows v4 客户端面向现代 Windows 的延续版本。当前构建基于 .NET 10、WinUI 3 / Windows App SDK，仅支持 x64，系统要求为 Windows 10 2004 / build 19041 或更高版本以及 Windows 11。

本项目是独立 fork，不是 shadowsocks/shadowsocks-windows 上游仓库。

当前版本：2.2.31

2.2.31 已在 Administrator Mode 中实现 System、Direct、Proxy、CustomDoh 和 DnsCrypt 五种 DNS policy 的透明 DNS 拦截/路由，同时包含 DNSCrypt/DoH 管理（ODoH 保持关闭）、自动更新加固、开机启动重复实例保护以及当前 WinUI 3 界面。发布流程还会检查 .NET 安全基线、NuGet 漏洞审计、Windows 10 build 19041 兼容性以及最终 EXE 的版本元数据。

完整版本历史见 Changelog。

主要特性

  • 原生 WinUI 3 桌面界面；产品 UI 不再依赖 WinForms/WPF。
  • unpackaged、self-contained、win-x64、single-file 发布。
  • 正式发布包中只包含 Shadowsocks.exe。
  • 用户配置和可写数据统一存放在 %LOCALAPPDATA%\Shadowsocks。
  • Clean Mode（EXE 文件名在 .exe 前以 p 结尾）把全部可写状态重定向到一次性的 %TEMP%\Shadowsocks\Clean\... 会话。
  • 内置 HTTP/1.1 proxy 与 HTTPS CONNECT；Privoxy/sysproxy 已移除。
  • 按应用设置 Proxy、Direct、Block 路由。
  • Administrator Mode 通过 WinDivert 对 TCP/UDP 进行透明捕获。
  • 自动 Game Mode 会在配置的游戏/程序运行期间暂停 Admin capture，退出后自动恢复。
  • SIP003 插件管理：内置 xray-plugin、v2ray-plugin、qtun 选项，并支持手动导入 ZIP/TAR.GZ。
  • UDP relay、二维码导入/导出、热键以及单一内嵌 CSV 本地化目录。

流量模式

只有两种可选流量模式：

  • User Mode — 不需要提权，也不会解包 NetworkService。路由仅作用于进入本地/系统代理的流量。
  • Admin Mode — 请求 UAC，将内嵌的 Shadowsocks.NetworkService.exe 按需释放到当前存储根目录，校验后提权启动，并通过 WinDivert 启用透明 TCP/UDP 捕获。

Game Mode 是自动兼容状态，不是第三种流量模式。 当选择 Admin Mode 且配置的游戏/程序启动时，WinDivert capture 会暂停；程序退出后自动恢复。

Traffic 页面会显示配置模式、运行模式、NetworkService、WinDivert、TCP/UDP capture 状态以及 redirect ports。

系统要求

  • Windows 10 2004 / build 19041 或更高版本，或 Windows 11；
  • x64 Windows；
  • 从源码构建需要 .NET SDK 10.0.303 或更高版本（release build 使用 .NET 10.0.11 安全基线）。

正式发布版本为 self-contained，不要求用户另行安装 .NET Runtime。

Solution 结构

  • Shadowsocks.Core — 协议、加密、配置模型、PAC/GeoSite、路由模型、本地化和存储抽象。
  • Shadowsocks.Windows — 文件存储 bootstrap、WinINet/system proxy、开机启动、UAC/Admin capture、WinDivert runtime、热键和其他 Windows 集成。
  • Shadowsocks.Windows.WinUI — WinUI 专用 Windows shell/tray 集成。
  • Shadowsocks.WinUI — WinUI 3 应用 shell 和正式发布项目（Shadowsocks.exe）。
  • Shadowsocks.NetworkService — 内嵌到正式版本中的独立提权 WinDivert helper。
  • Shadowsocks.UnitTests — 不依赖 presentation layer 的 Core/Windows 测试。

架构说明见 Architecture。

构建

在 Windows 上使用 .NET SDK 10.0.303 或更高版本：

dotnet restore .\shadowsocks-reborn.sln -p:Platform=x64 -r win-x64
dotnet build .\shadowsocks-reborn.sln -c Release -p:Platform=x64 -m:1 --no-restore
dotnet test .\Shadowsocks.UnitTests\Shadowsocks.UnitTests.csproj -c Release -p:Platform=x64 --no-build

构建正式 ZIP 与 SHA-256：

.\packaging\Build-Release.ps1 -Version 2.2.31

GitHub Release 的固定资源名为：

Shadowsocks-win-x64.zip
Shadowsocks-win-x64.zip.sha256

最终 publish 目录与 ZIP 中只能有：

Shadowsocks.exe

存储与开机启动

普通模式把持久化状态存放在：

%LOCALAPPDATA%\Shadowsocks

配置文件为 %LOCALAPPDATA%\Shadowsocks\settings.json，并使用原子备份 settings.backup.json。插件安装在 %LOCALAPPDATA%\Shadowsocks\Plugins。本地化只使用内嵌在 Shadowsocks.exe 中的 i18n.csv。

将 EXE 名称改为在 .exe 前以 p 结尾即可进入 Clean Mode，例如 Shadowsocksp.exe 或 Shadowsocks-cleanp.exe。Clean Mode 会把 settings、cache、PAC、logs、插件、runtime/helper 工作目录统一放入 %TEMP%\Shadowsocks\Clean\...，退出时尽力清理。Clean Mode 不允许启用 Start with Windows。

普通模式下，Start with Windows 使用 %LOCALAPPDATA%\Shadowsocks\Startup\Shadowsocks.exe 的已校验稳定副本。启动时会迁移旧的 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 项、删除重复项；关闭开机启动时也会清理匹配的旧项。与 EXE identity 无关的进程级 single-instance guard 可阻止 startup copy 与原始 EXE 同时启动两个 controller 并争用同一端口。

详细规则见 Storage Policy。

自动更新

下载资源先写入 *.download，文件句柄关闭后才在 Windows 上通过 File.Move 提升为正式临时文件。.sha256 支持两种格式：<hash> Shadowsocks-win-x64.zip 或单独的 64 位十六进制 SHA-256。

应用默认在启动后检查 GitHub Releases，要求同时存在准确命名的 ZIP 与 .sha256，并校验 SHA-256、ZIP 布局以及 payload FileVersion。新 EXE 在 %TEMP%\Shadowsocks\Updates 中 staging；UAC handoff 期间 staged updater 还会再次通过自身 SHA-256 校验，随后等待旧进程退出、保留 rollback 状态、替换主 EXE、启动新版本并清理临时 transaction。

Embedded NetworkService

Release build 会把 self-contained single-file 的 Shadowsocks.NetworkService 内嵌进 Shadowsocks.exe。

User Mode 不会解包 helper。Admin Mode 才会按需释放到当前 storage root，串行化 extraction，进行 SHA-256 校验，并通过 elevated control pipe 做版本握手。停止 broker 后会尽力删除 helper，旧 runtime 目录随后清理。

WinDivert 验证

只有提权 capture 进程成功打开 WinDivert 后，Admin Mode 才会报告为 active。日志中会出现类似：

WinDivert capture confirmed (start): Admin capture active.; TCP redirect port=..., UDP redirect port=...

功能测试可给 curl.exe 配置 Block，临时关闭 Windows system proxy，然后执行：

curl.exe -4 --noproxy "*" https://example.com

在 User Mode 中直连请求应绕过 application routing；在 Admin Mode 中应被阻止。

PAC、HTTP forwarding 与 DNS

Local PAC 使用配置的 GeoSite source 与持久化 cache；Online PAC 通过 Shadowsocks 下载并由本地 /pac endpoint 提供给 WinINet。

ManagedHttpProxyService 支持 HTTP/1.1 与 HTTPS CONNECT。HTTPS 仅进行 byte tunnel，因此 TLS 内协商 HTTP/2 不需要本地 HTTP/2 parser。未实现 FTP gateway。

DNS policy 合约

2.2.31 的配置/IPC 包含五种 DNS policy。Administrator Mode 已通过 Shadowsocks.NetworkService + WinDivert 对 UDP/TCP 53 的经典 DNS 实现透明路由：

Policy 当前行为
System 保持捕获的经典 DNS 使用原始/系统 destination，不做 policy-specific redirect。
Direct 可保留原始 destination，或把 DNS 重定向到配置的主/备用 IPv4/IPv6 resolver；也可把所选 DNS endpoint 通过本地 Shadowsocks SOCKS5 路由。
Proxy 把捕获的经典 DNS 通过 Shadowsocks 转发。
CustomDoh 将捕获的 DNS wire message 桥接到指定 HTTPS DoH endpoint；DoH upstream 可独立选择是否通过 Shadowsocks。
DnsCrypt 重定向到动态分配的本地 dnscrypt-proxy listener；安全 runtime 不可用时采用 fail-closed。

因此，2.2.31 已实现透明的系统级 DNS interception/routing，但必须使用 Administrator Mode。User Mode 仍可使用 Shadowsocks 管理的 DNS/DNSCrypt，但不会拦截任意系统 DNS。Game Mode 暂停 Admin capture 时也会暂停系统级 DNS 拦截。透明拦截范围为 UDP/TCP 53 的经典 DNS；应用内部的 DoH、DoT、DoQ 不会被通用拦截。

DNS 页面可以管理可选且经过签名校验的 dnscrypt-proxy。Automatic 根据 DNSSEC、no-log、无过滤、IPv4/IPv6 等约束从签名公共目录选择具体 DNSCrypt/DoH resolver 并固定到 server_names。活动 runtime 使用 bootstrap_resolvers = [] 与 ignore_system_dns = true；仅在尚无签名 resolver cache 时，目录更新可使用一次性 bootstrap DNS。Manual 支持 DNSCrypt/DoH resolver 以及协议、国家、地址族和隐私过滤；ODoH 保持关闭。

DNS 页面还提供 Test DNSCrypt 与 DNS privacy self-test。loopback listener 端口会确认同一数字端口可同时用于 UDP/TCP。DNSCrypt PID/port 变化会实时同步到 NetworkService。启动、重启、恢复或 runtime 故障期间采用 fail-closed，不会把已拦截 DNS 静默降级到 plaintext system DNS。需要 DNS/proxy rewrite 的分片 datagram 会整体丢弃，防止后续 fragment 绕过策略；direct fragment 仍保持 direct。

WinDivert 2.2.2 只从固定官方 release URL 下载，并在加载前校验 x64 DLL/driver 的固定 SHA-256。read-only FLOW observer 提供 endpoint PID ownership，IP Helper 作为 fallback。

DNSCrypt Automatic 优先选择与当前 Shadowsocks server 国家匹配的兼容 resolver，无匹配时选择签名目录中的最佳兼容项。resolver 国家只根据 endpoint IP 的 GeoIP 推导，不使用名称/description。Manual resolver latency 异步测量，活动 resolver 在可用时使用 dnscrypt-proxy 实际 RTT。组件自动更新检查最多每 24 小时一次；首次安装始终需要用户显式操作。如果 DNSCrypt 自身通过 Shadowsocks 路由，则 Shadowsocks/forward-proxy endpoint 必须使用 IP literal，以避免 DNS bootstrap 递归。

文档

长篇 Markdown 文档统一维护在 GitHub Wiki 中；.github/*.md 仍保留在主仓库，因为 GitHub 的 issue/PR template 依赖这些路径。

许可证

shadowsocks-reborn 使用 GPL-3.0-or-later。见 License 与主仓库中的 LICENSE.txt。第三方组件保留各自许可证，详情见 Third-party notices。

Clone this wiki locally