GitHub hosts 加速 Windows 桌面工具。
很多场景下访问 GitHub 慢、git push/pull 失败，根本原因是本地 DNS 解析出来的 IP 不可达或被污染。FastGithub 绕开系统 DNS，用公共 DNS 服务器直接解析 GitHub 各域名，挑出 443 通 + Ping 最低的 IP，写回 Windows hosts 文件。
| 项 | 内容 |
|---|---|
| 版本 | 2.1.1（见 CHANGELOG.md） |
| 源码 | src/FastGithub/（主程序）+ src/FastGithub.Launcher/（引导器） |
| 配置模板 | src/FastGithub/config.example.json |
| 解决方案 | FastGithub.sln |
| 文档 | 本文件（使用说明 + 技术栈 + 架构）、CHANGELOG.md（发布说明）、docs/PRODUCT.md（产品介绍） |
| 测试 | tests/FastGithub.Tests/ + tests/FastGithub.Launcher.Tests/（已加入 .gitignore，本地保留） |
| 双 exe 产物 | publish/FastGithub.exe（~12 KB 引导器）+ publish/FastGithub.App.exe（~220 KB 主程序）+ config.example.json |
| 层 | 技术 |
|---|---|
| 主程序运行时 | .NET 9（net9.0-windows），FrameworkDependent |
| 引导器运行时 | .NET Framework 4.8（Windows 10/11 自带，零依赖） |
| UI 框架 | WPF（<UseWPF>true</UseWPF>） |
| 系统托盘 | WinForms 互操作（<UseWindowsForms>true</UseWindowsForms>，用 NotifyIcon） |
| 引导器 UI | WinForms（进度窗口、MessageBox） |
| 架构模式 | MVVM（Models / Core / Services / ViewModels / Views） |
| DNS 协议 | 手写 DNS 报文编解码（UDP 直连 53 端口，不依赖 System.Net.Dns） |
| 网络测试 | TCP 443 端口连通性 + System.Net.NetworkInformation.Ping 延迟选优 |
| 配置 | System.Text.Json 读写 config.json，首次运行从 config.example.json 复制 |
| 日志 | 自实现 LogService（文件句柄 + 锁），输出到 github-hosts-update.log |
| 测试 | xUnit + .NET Test SDK，单元测试 + 集成测试分类（[Trait("Category","Integration")]） |
| 发布 | 主程序单文件 FrameworkDependent（~220 KB）+ 引导器 .NET Framework 4.8（~12 KB） |
- DNS 直连：手写 DNS 协议报文（UDP），直连配置里的公共 DNS（默认 114/腾讯/阿里/Google/Cloudflare），不读本地 hosts，避免被污染。
- 端口连通性测试：对每个候选 IP 测 443 端口是否可连。
- Ping 选优：从 443 可达的 IP 中选延迟最低的写入 hosts。
- 标记块管理：写 hosts 时用
# === GitHub Hosts Start (Managed by FastGithub) ===/End ===包裹，下次刷新只替换这个块，不动用户其他条目。 - DNS 缓存刷新：写完调用
ipconfig /flushdns让新条目立即生效。
用户双击 FastGithub.exe（引导器）
│
▼
UAC 提权（引导器 manifest 要求 requireAdministrator）
│
▼
检测 %ProgramFiles%\dotnet\shared\Microsoft.WindowsDesktop.App\9.x
│
├── 已装 .NET 9 Runtime ───► 启动 FastGithub.App.exe → 引导器退出
│
▼ 未装
弹窗：「未检测到 .NET 9 Desktop Runtime，是否自动下载并安装？」
│
├── 选「否」 ──────────────► 引导器退出
│
▼ 选「是」
进度窗口（可最小化）
1. 下载 windowsdesktop-runtime-9.0.17-win-x64.exe（~58 MB）
进度条显示百分比
2. 静默安装：/quiet /norestart
进度条切 Marquee 动画
│
├── 安装成功 ──────────────► 启动 FastGithub.App.exe → 引导器退出
│
▼ 安装失败
弹窗提示错误码 + 手动下载链接 → 引导器退出
- Windows 10 / 11 x64
- 管理员权限（修改 hosts 文件必须，引导器启动即触发 UAC）
- 无需预装 .NET 9 Runtime——引导器会自动检测并安装
- 双击
FastGithub.exe（引导器），会弹 UAC 提权请求，点是。 - 首次运行若未装 .NET 9 Runtime，引导器会弹窗询问是否自动下载安装，选「是」等待进度条走完。
- 主程序
FastGithub.App.exe启动后，主窗口有三个标签页：- 仪表盘：点击"立即刷新"，实时看到每个域名的解析/测试/写 hosts 进度，完成后表格列出每个域名当前 IP、状态、延迟、上次更新时间。
- 配置：增删要加速的域名、增删 DNS 服务器、调整最大备份数和超时。保存后下次刷新立即生效，不必重启程序。
- 日志：所有刷新过程日志按时间顺序显示，可按级别过滤、可一键用记事本打开完整日志文件。
- 关闭主窗口会最小化到系统托盘，不会退出程序。右键托盘图标可"立即刷新"或"显示主窗口"或"退出"。
- 首次最小化到托盘时会弹气泡提示，之后不再打扰。
配置文件 config.json（与 exe 同目录，首次运行自动从 config.example.json 复制）。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Domains |
string[] | github.com 等 23 个域名 | 需要加速的域名列表 |
DnsServers |
string[] | 114.114.114.114 / 119.29.29.29 / 223.5.5.5 / 8.8.8.8 / 1.1.1.1 | 候选 DNS 服务器，按顺序尝试，第一个成功即用 |
HostsPath |
string | C:\Windows\System32\drivers\etc\hosts |
hosts 文件路径，一般不要改 |
MaxBackupCount |
int | 10 | hosts 备份保留份数，超出自动删最旧的 |
TimeoutMs |
int | 3000 | DNS / TCP 443 / Ping 单次操作超时（毫秒） |
修改后点击配置页底部"保存"按钮即可，下次刷新会用新配置。
dotnet build使用发布脚本（构建 + 收集交付物 + 可选代码签名）：
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1带代码签名发布（详见 AGENTS.md 的「代码签名」章节）：
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1 -Sign -CertPath .\scripts\FastGithub.pfx -CertPassword yourpassword产物路径：publish/
| 文件 | 大小 | 说明 |
|---|---|---|
FastGithub.exe |
~12 KB | 引导器（.NET Framework 4.8，Windows 自带，零依赖） |
FastGithub.App.exe |
~220 KB | 主程序（FrameworkDependent 单文件，不含 .NET 运行时） |
config.example.json |
~1 KB | 配置模板 |
首次运行时引导器会自动检测并安装 .NET 9 Desktop Runtime（~58 MB，一次性）。
dotnet test测试分两个项目：
FastGithub.Tests（主程序）：19 个测试FastGithub.Launcher.Tests（引导器）：9 个测试
测试分类：
- 单元测试（默认运行）：用 fake 接口隔离真实网络，覆盖 HostsUpdater 选优逻辑、HostsFileManager 标记块管理、ConfigService 配置读写、DnsResolver 协议编解码、RuntimeDetector/RuntimeInstaller 常量与路径。
- 集成测试（默认也运行，但可排除）：
NetworkTesterTests中两个测试真实访问192.0.2.1（TEST-NET-1 保留地址）验证超时返回 false/null。
排除集成测试：
dotnet test --filter Category!=IntegrationQ: 刷新后访问 GitHub 还是慢？
A: 浏览器有 DNS 缓存，重启浏览器或 ipconfig /flushdns 后再试。Chrome 内部还有自己的 DNS 缓存（chrome://net-internals/#dns 清空）。
Q: 杀毒软件拦截 hosts 写入？
A: 部分杀软会保护 hosts 文件。把 FastGithub.exe 加入信任列表即可。备份文件 hosts.githubbak.* 同目录可手动恢复。
Q: 程序显示"刷新失败: 拒绝访问"？
A: 没有管理员权限。重新启动 FastGithub.exe，在 UAC 弹窗点"是"。
Q: 如何彻底清除 FastGithub 写入的 hosts 条目？
A: 直接编辑 hosts 文件，删除 # === GitHub Hosts Start (Managed by FastGithub) === 到 End === 之间的所有内容。也可以在程序里"重置为默认"再"保存"再"刷新"覆盖。
Q: 程序退出后 hosts 还有效吗？ A: 有效。hosts 是 Windows 系统级配置，FastGithub 只负责写入，程序退出不影响已写入的条目，直到下次 Windows DNS 缓存过期或被其他工具覆盖。
Q: 引导器下载 Runtime 失败怎么办？
A: 弹窗会附带下载链接，可手动下载安装。直链：https://builds.dotnet.microsoft.com/dotnet/WindowsDesktop/9.0.17/windowsdesktop-runtime-9.0.17-win-x64.exe。安装后再次双击引导器即可直接启动主程序。
Q: Windows 提示「智能应用控制已阻止此应用」？ A: 这是 Windows Smart App Control 安全功能，因为程序没有数字签名。解决方案：
- 自签名证书（自己用）：生成自签名证书并安装到受信任根，然后用签名版本发布。详见 AGENTS.md 的「代码签名」章节。
- 手动允许：在 Windows 安全中心 → 应用和浏览器控制 → 智能应用控制中找到并选择「仍要运行」。
- 正式证书（发布给他人）：申请正式代码签名证书（如 Certum 开源免费证书、OV/EV 证书）。
Q: 为什么用了自签名证书，其他电脑运行还是提示不安全？ A: 自签名证书只在安装了该证书的电脑上受信任。发布给其他用户需要使用受信任的 CA（证书颁发机构）签发的正式代码签名证书。推荐开源项目申请 Certum Open Source 免费证书，或购买商业 OV/EV 证书。
Q: 时间戳服务连接失败怎么办？ A: 时间戳服务用于确保证书过期后签名仍然有效。如果连接失败，可以：
- 更换时间戳服务器（如
http://timestamp.digicert.com、http://timestamp.sectigo.com） - 忽略时间戳（不推荐，证书过期后签名将失效）
src/
├── FastGithub/ 主程序（.NET 9 WPF）
│ ├── Models/ AppConfig / HostsEntry / UpdateProgress / UpdateResult / LogLevel
│ ├── Core/ DnsResolver / HostsFileManager / HostsUpdater / NetworkTester + 接口
│ ├── Services/ ConfigService / LogService / TrayService
│ ├── ViewModels/ DashboardViewModel / ConfigViewModel / LogViewModel / MainWindowViewModel / ViewModelBase / RelayCommand
│ ├── Views/ DashboardView / ConfigView / LogView（XAML + 后缀代码）
│ ├── App.xaml 应用资源
│ ├── App.xaml.cs 入口：UAC 检测 + 依赖注入
│ ├── MainWindow.* 主窗口（标签页容器）
│ ├── app.manifest UAC 提权（写 hosts 需要）
│ └── config.example.json 默认配置模板
└── FastGithub.Launcher/ 引导器（.NET Framework 4.8）
├── Program.cs 入口：编排检测→弹窗→安装→启动主程序
├── RuntimeDetector.cs 检测 .NET 9 Desktop Runtime 是否已安装
├── RuntimeInstaller.cs 下载 + 静默安装，带进度回调
├── ProgressForm.cs WinForms 进度窗口（可最小化）
├── app.manifest UAC 提权（requireAdministrator）
└── FastGithub.Launcher.csproj
tests/ 测试项目（已加入 .gitignore，本地保留）
├── FastGithub.Tests/ 主程序测试（19 个）
└── FastGithub.Launcher.Tests/ 引导器测试（9 个）
- 架构：MVVM。Models 层纯数据；Core 层无 UI 依赖，可独立测试；Services 持有外部资源（文件/托盘）；ViewModels 编排 UI 状态；Views 纯 XAML。
- DNS 协议：
Core/DnsResolver.cs手写 DNS 报文（不依赖 System.Net.Dns），支持 A 记录查询与响应解析，UDP 直连 53 端口。 - hosts 写入并发：
HostsFileManager.Read/Write带 5 次重试 + 500ms 间隔，应对杀软短暂锁定文件。 - 托盘：WPF 与 WinForms 互操作（NotifyIcon 在 WinForms），需要
<UseWPF>true</UseWPF>+<UseWindowsForms>true</UseWindowsForms>同时开启。 - UAC：引导器与主程序都有
app.manifest要求requireAdministrator，启动即提权。 - 引导器线程模型：UI 线程跑
Application.Run(form)维护消息循环；worker 线程跑installer.Install()（阻塞下载 + 静默安装）；事件回调通过BeginInvoke切回 UI 线程更新进度条。 - Runtime 版本：固定 .NET 9.0.17（2026-06-09 发布的累积更新）。URL 用
builds.dotnet.microsoft.com稳定模式，避免旧download.visualstudio.microsoft.com的 hash 路径失效。