狐径 FoxPath

🦊 GitHub 访问优化助手　·　只在本机做网络分流，退出即还原

作者 海风（kele551）　·　GitCode（主）　·　GitHub（镜像）　·　AtomGit（镜像）　·　English

GitHub 访问优化助手。本机网络分流 + PAC，不依赖域名解析，直连当前实测可用的 GitHub 官方 IP。

主程序（github_direct.py / 发布的 exe）不用管理员权限，不改 hosts，不改系统 DNS。 主程序从代码到运行都不碰 hosts 文件：它只把代理设置写进当前用户的注册表（HKCU）， 代理范围与还原方式见下面「原理」「核心机制」两节。

说明（2026-10-16）：仓库里不再附带任何会改 hosts 的脚本。早期版本曾提供一个上一代 做法的 Fix-GitHub.ps1 / Run-GitHubFix.bat（改 hosts + 装计划任务 + 需要管理员权限）， 为了与「不改 hosts、不改系统 DNS、不需要管理员权限」的承诺一致，已从仓库移除。 如果你以前跑过它、需要收尾：任务计划程序里删掉 GitHubDirectFix 任务，并删掉 hosts 里 # >>> GitHubDirectFix BEGIN >>> 到 # <<< GitHubDirectFix END <<< 之间的那段。

三步上手

绿色单文件、无需安装、不要管理员权限；以后升级就在面板里点「检查更新 → 立即升级」。

想先看它长什么样：仓库里有一页演示页，内嵌 2 分 30 秒的演示视频 （录制于 v1.0.7，界面以实际版本为准；最新变化见 release-notes.md），点开即播。

三个平台代码一致：GitCode（主源）· GitHub（镜像）· AtomGit（自动镜像 GitHub，含发行版附件）。 二进制发行包请从 GitCode（主）或 GitHub（镜像）下载；三个平台都收 Issue / PR。

目录

上手与用法：三步上手 · 解决什么问题 · 用法 原理与边界：原理 · 核心机制 · 升级时请注意 · 已知边界 版本与构建：版本记录 · 从源码构建与发版自检 · 路线图（Roadmap） 治理文档：贡献指南 · 安全政策 · 代码签名政策 · 参与贡献与治理 · 联系与反馈 · 许可 · 第三方组件与许可 上手代码：项目结构与上手路线 —— 15 分钟看懂从哪进、改哪儿、改完怎么验

解决什么问题

国内访问 github.com 时通时断，典型症状：

• 浏览器转圈半天最后超时，但手机开流量却能正常打开
• api.github.com 一直是通的，只有 github.com 网页打不开
• 手动往 hosts 里钉 IP，过两天又失效

根因通常不在网络本身，而在本地域名解析出来的那个 GitHub IP 在当前线路上不通。浏览器按解析结果走，就会卡住。

狐径不查 DNS——它自己拿着一批 GitHub 官方 IP 逐个实测握手，挑能用的直连。

原理

浏览器 ──PAC──> 狐径本地代理 127.0.0.1:8787 ──> 实测可用的 GitHub 官方 IP
              （接管 github.com + raw/附件 + Pages）  （不依赖域名解析）

用法

核心机制

从源码构建与发版自检

构建命令、仓库文件说明、打包注意事项见 CONTRIBUTING.md 第四节与第七节； 发版前自检（发布闸门 tools/preflight_release.py）的完整说明见 CONTRIBUTING.md 第八节。 主程序零第三方依赖（只用 Python 标准库）；产物由本仓库源码构建、可复现， 逐项说明见 CODE_SIGNING_POLICY.md。

发版需要一把签名私钥：升级源 version.json 的 Ed25519 签名由 tools/publish.py 在发版时生成 （写成 version.json.sig，与 version.json 一起提交到仓库、一起作为发行版附件上传）。 私钥只在维护者机器上，仓库里没有、也不会有；脚本按 「环境变量 FOXPATH_ED25519_KEY → 本机私有配置 ~/.foxpath-publish.json 的 ed25519_key」的顺序找它， 找不到就明确报错、拒绝发布（不会静默发一份没有签名的升级源出去）。 公钥内置在 github_direct.py（UPDATE_PUBKEY，公开无妨）。

升级时请注意

• 升级不用手动换文件：升级源先过 Ed25519 公钥验签 → 下载 → 校验 SHA256 与字节数 → 小助手让旧程序退出并还原系统代理 → 覆盖 exe → 自动重启；任何一道不过就放弃，不会留半成品。
• 升级源被改过就一律拒绝：version.json 必须带一份同目录的 version.json.sig（用维护者离线私钥签的）。签名缺失、格式不对、对不上内容 —— 这条源直接作废、换下一个候选，全都不行就保留当前版本，面板上给一句「更新源校验未通过，已保留当前版本」。签名只能防"升级源被篡改"（比如账号被盗后有人推了恶意版本），防不了维护者机器上的私钥被偷，也不等于 Windows 代码签名证书。
• 不会把「降级」当「升级」：按版本号语义比较（1.0.10 > 1.0.9 这种也算得对），线上不比本地新时按钮置灰、服务端也拒绝执行。
• 升级失败会自动回滚：新版连续起不来时，小助手把旧版本放回去并重新启动它。
• 升级完成后程序会自动重新打开；万一它没出现，双击 FoxPath.exe 就能正常使用 —— 升级本身是完成的，系统代理已还原，不会影响上网。
• 升级源不通时（2026-10-12 补）：点「检查更新」长时间连不上源，不必干等 —— 到 GitCode 发行页 下载最新 FoxPath.exe，关掉旧程序后双击覆盖即可，配置全部保留。

升级细节与历史说明更正（_PYI_* 环境变量真因、v1.0.6→v1.0.7 那一跳、各版本护栏边界）见 CONTRIBUTING.md 第九节。

已知边界

• 代理范围：github.com / www.github.com / raw.githubusercontent.com / objects.githubusercontent.com / avatars.githubusercontent.com / camo.githubusercontent.com；githubassets.com 与 api.github.com 仍然直连。
• git 接管的范围：只碰 ~/.gitconfig 里的 http.<url>.proxy 这几条键，credential / 别名 / 其它段落一个字节都不动； 名单外的键只有"值正好指着狐径端口、域名又属于 GitHub 家族"时才跟着走。SSH 只探测、不写配置。
• 端口可能不是 8787：被占时会顺延到备选端口，PAC / git / 面板 / 日志都跟着实际端口走； Windows 注册表里的 AutoConfigURL 会指向 PAC 的 127.0.0.1:8788，具体在听哪个端口以日志里那行为准。
• 不能用 nohup ... & 在 shell 里后台启动（命令结束进程会被终止）；要常驻就双击运行或开开机自启。
• 程序被强制结束（任务管理器结束进程、关机时强杀）时 atexit 不执行，系统代理可能仍指向本程序 —— 下次启动会自动接管；不再用了跑一次 --restore 即可收干净。
• 原本设了「静态代理」（Internet 选项里手动填的代理服务器）时，启用本程序后 PAC 优先，你手填的代理在启用期间不再生效（其它网站直连），停用/退出时会自动还原，日志里会写一行提醒。
• 控制面板只监听 127.0.0.1，不对局域网开放；接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding），但没有做用户鉴权 —— 本机上以你的身份运行的程序仍然可以调用它。
• 遇到端口被占用、启动失败等情况，exe 会弹一个错误框并写明日志位置，不再"点了没反应"。

逐条的完整说明（专属 IP 池为什么必须分开、头像域实测数字、两个平台发行版附件个数差异）见 CONTRIBUTING.md 第十节。

版本记录

当前对外发布版本 v1.2.4（2026-10-31）。主源 GitCode · 镜像 GitHub；自 2026-10-16 起代码另在 AtomGit 有镜像。完整逐版说明见 CHANGELOG.md 与 release-notes.md。

v1.0.0 ～ v1.0.7 其余各版的详细说明（原文一字未改）见 CONTRIBUTING.md 第十一节；一行摘要见 CHANGELOG.md。

联系与反馈

遇到打不开、体检全灭、或哪里不好用，欢迎直接提 Issue：GitHub Issues　·　GitCode Issues

反馈时顺手附上控制面板「当前可用 IP」那一栏的数字，定位会快很多。

许可

MIT

免费、无广告、不收费；不采集、不上传任何用户数据：没有账号系统、没有统计上报、没有广告，运行日志只写本机数据目录（见 COMPLIANCE.md）。

第三方组件与许可

主程序零第三方依赖：github_direct.py 只用 Python 标准库（socket / ssl / http.server / winreg / json …）， 所以发布的 FoxPath.exe、或直接 python github_direct.py 运行，都不需要装任何第三方包。

只有"开发 / 发布用"的脚本依赖下面两个包（不参与程序运行、也不进 exe）：

• 版本口径写在 requirements.txt，打包版本固定，便于复现；
• 打包进 exe 的 Python 运行时是 Python 3.13（PSF 许可）；
• 本项目不随发行版分发任何第三方素材（图标为自绘，见 COMPLIANCE.md）。

路线图（Roadmap）

按优先级从高到低，都是已经排进计划、能落到代码上的事：

1. 自动升级 + 升级结果气泡（代码已就绪，待发版）：启动后静默检查新版本，默认自动下载、校验 SHA256、替换并重启，不弹确认框； 设置里的 auto_update 可以关掉，关掉后回到"发现新版只在面板提示一句"。三道护栏：只对打包版 exe 生效、只认 https 升级源、同版本 24 小时内最多 2 次。 升级成功或失败会弹一次气泡并在面板留一行状态，详见「核心机制 → 在线升级」。
2. IPv6 实测地址池：候选池目前只有 IPv4（内置 45 个 + 官方 meta 补充）。 要加的是"真的握手成功过才入池"的 IPv6 地址，而不是把段表直接塞进去。
3. 线路自适应：按当前线路的历史成败给候选排序，换网（宽带 ↔ 热点）后不从头再摸一遍。
4. 代码签名申请：产物已自带 SHA256 与可复现构建说明，下一步申请免费代码签名， 缓解"首次运行被安全软件拦一下"的体验问题。详见 CODE_SIGNING_POLICY.md。

路线图只列真实在办的事，做完一项改一项；临时想到的、还没验证的想法不写在这里。

参与贡献与治理

支持项目

如果 狐径 FoxPath 帮到了你，给仓库点个 Star ⭐ 就是最好的支持 —— 它能让更多人看到这个项目。

如果想再进一步，请作者喝杯咖啡（完全自愿，不影响任何功能）：

_{微信扫一扫 · 金额随缘}

本项目以 MIT 协议自由开源，没有付费版、也没有付费功能；捐赠纯属自愿， 与功能开放、版本更新、Issue 响应没有任何关系。

_{© 2026 海风（kele551） · MIT License · GitCode 主仓库 · GitHub 镜像}