# FoxPath **Repository Path**: kele551/FoxPath ## Basic Information - **Project Name**: FoxPath - **Description**: 已迁移到 GitCode：gitcode.com/kele551/FoxPath（国内、可统计下载）。Gitee 停止更新，最后一版 v1.2.1（2026-10-17）。原因：Gitee 不公开下载数、API 有限。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 16 - **Forks**: 3 - **Created**: 2026-09-20 - **Last Updated**: 2026-10-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
狐径 FoxPath

狐径 FoxPath

Downloads Gitee 访问 License Platform Release Last Commit GitHub Star Gitee Star GitHub Fork Follow Author Category No Admin No Hosts DNS > **📦 已迁移到 GitCode，本仓库（Gitee）停止更新（2026-10-17）** > > **Gitee 最后一版是 v1.2.1（2026-10-17）**；以后的更新只在 [GitCode](https://gitcode.com/kele551/FoxPath/releases)（主源）与 [GitHub](https://github.com/kele551/FoxPath)（镜像）发布。 > > - **为什么迁**：Gitee 不公开发行版附件的下载数，统计不到真实下载量；GitCode（=AtomGit）能放 exe 附件、有准确的下载数接口，API 也更全。 > - **老用户怎么过渡**：照常从本仓库升级即可，升到 **v1.2.1** 后客户端会自动切到 GitCode，**不用重装、不用改配置**；原有升级链继续有效。 > - **三平台关系**：GitCode（主源）· Gitee（历史 + 旧入口）· GitHub（镜像），代码逐字节一致。 Zero Deps Download from Gitee GitHub mirror Bilibili demo Issues Sponsor

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

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

📊 仓库数据一览（点击展开）

Release Date Commit Activity Contributors Issues Resolved Gitee Fork Language Code Size PRs Welcome

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 <<<` 之间的那段。 --- ## 三步上手 | 步骤 | 做什么 | |---|---| | **① 下载** | [GitCode 发行页](https://gitcode.com/kele551/FoxPath/releases)（国内主源、直连快）或 [Gitee](https://gitee.com/kele551/FoxPath/releases) / [GitHub Releases](https://github.com/kele551/FoxPath/releases)，拿 `FoxPath.exe`。代码另在 [AtomGit](https://atomgit.com/kele551/FoxPath) 有镜像 | | **② 运行** | 双击 `FoxPath.exe` → 浏览器自动弹出控制面板（首次启动等 15～20 秒，它在并发体检 IP） | | **③ 启用** | 面板点「启用加速」完事；不用了点「退出并还原」，系统设置恢复原样 | 绿色单文件、无需安装、不要管理员权限；以后升级就在面板里点「检查更新 → 立即升级」。 > 想先看它长什么样：仓库里有一页[演示页](docs/demo/index.html)，内嵌 2 分 30 秒的演示视频 > （**录制于 v1.0.7**，界面以实际版本为准；最新变化见 [release-notes.md](docs/release-notes.md)），点开即播。 > **三个平台代码一致**：[Gitee](https://gitee.com/kele551/FoxPath)（主源）· [GitHub](https://github.com/kele551/FoxPath)（镜像）· [AtomGit](https://atomgit.com/kele551/FoxPath)（代码镜像，只提供源码归档）。 > **二进制发行包请从 GitCode（主）或 Gitee / GitHub（镜像）下载**；三个平台都收 Issue / PR。 --- ## 目录 **上手与用法**：[三步上手](#三步上手) · [解决什么问题](#解决什么问题) · [用法](#用法) **原理与边界**：[原理](#原理) · [核心机制](#核心机制) · [升级时请注意](#升级时请注意) · [已知边界](#已知边界) **版本与构建**：[版本记录](#版本记录) · [从源码构建与发版自检](#从源码构建与发版自检) · [路线图（Roadmap）](#路线图roadmap) **治理文档**：[贡献指南](docs/CONTRIBUTING.md) · [安全政策](docs/SECURITY.md) · [代码签名政策](docs/CODE_SIGNING_POLICY.md) · [参与贡献与治理](#参与贡献与治理) · [联系与反馈](#联系与反馈) · [许可](#许可) · [第三方组件与许可](#第三方组件与许可) **上手代码**：[项目结构与上手路线](docs/ARCHITECTURE.md) —— 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） （不依赖域名解析） ``` | 传统做法 | 狐径 | | --- | --- | | 改 hosts（要管理员、IP 死了就失效） | 本机代理 + PAC，写在 HKCU，普通用户权限即可 | | 依赖系统 DNS 解析 | 不查 DNS，直连实测能用的官方 IP | | IP 失效后彻底打不开 | 每 5 分钟重测一轮，死 IP 自动换 | | 程序退出后系统代理指向空端口，比原来更糟 | 退出/点「退出并还原」都会还原；PAC 带 `DIRECT` 兜底；还有 `--restore` 一键收尾 |
--- ## 用法
用法（点击展开） 1. 从 [Gitee Releases](https://gitee.com/kele551/FoxPath/releases)（国内主源，直连快）或 [GitHub Releases](https://github.com/kele551/FoxPath/releases) 下载 `FoxPath.exe` 2. 双击运行 → 浏览器自动打开控制面板 `http://127.0.0.1:8788/ui` 3. 勾选「开机自启」即可后台常驻 **首次启动请等 15～20 秒**：程序要并发体检 49 个候选 IP，体检完成前代理还没完全生效。 > 升级最简单的方式是面板里的「检查更新 → 立即升级」（v1.1.1 起手动检查强制联网，不再被缓存挡住）。 > 万一升级源也连不上，到 [Gitee 发行页](https://gitee.com/kele551/FoxPath/releases) 下载最新 `FoxPath.exe` > 覆盖安装即可，配置与收藏全部保留、无需卸载。 ### 控制面板上有什么 控制面板 `http://127.0.0.1:8788/ui`，从上到下四块：**版本与升级** · **加速状态** · **当前可用 IP** · **日志**。 - **版本与升级**：看当前版本与升级结果，点 `检查更新` / `立即升级`（`自动升级`、`升级结果气泡` 默认开）。 - **加速状态**：看出口 IP 与延迟，点 `启用加速` / `停用并还原` / `立即重测` / `退出并还原`，勾 `开机自启`。 - **当前可用 IP**：按延迟排序、每 5 分钟刷新；一个都没有时会自动重拉官方 IP 表并回退系统 DNS。 - **日志**：`foxpath.log` 的尾部，自动滚到最新 —— 打不开 GitHub 先看这里。 四块逐项说明（各自能做什么、文件名为什么是 ASCII）见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第九节。 反馈问题时把「当前可用 IP」那栏的数字一起贴上，定位会快很多。 **出过问题想自救**：`FoxPath.exe --restore` 只做一件事 —— 把系统代理里本程序留下的 PAC 设置清掉，不起代理、不开面板。万一程序被强杀、或者你直接把 exe 删了但 `AutoConfigURL` 还指向 `127.0.0.1:8788`，跑这一条就能收干净。 **日志在哪**：`%LOCALAPPDATA%\FoxPath\foxpath.log`（exe 是无窗口的，屏幕上什么都看不到， 有问题先看这个文件）。
--- ## 核心机制
核心机制（点击展开） - **体检**：每 5 分钟并发重测候选池，条件是 TCP 443 握手 + TLS 证书校验 + HTTP 首包必须返回 2xx/3xx。 最后这条很关键——有些 IP 证书是对的，但只服务 API/CDN，访问 github.com 首页会返回 400，必须过滤掉。 - **候选池刷新**：定期从 `api.github.com/meta` 重拉 GitHub 官方公布的 IP 段，官方换 IP 了也能跟上。 - **自愈**：候选全部失效时，依次尝试重拉官方表 → 查询系统 DNS → 放宽超时重测。三步都不通才判定真不通，此时退回系统解析（和没装本程序一样，不会更糟）。 - **退出安全**：正常退出和**静默模式（开机自启）**都会把系统代理恢复成运行前的状态； 还原备份固定存在 `%LOCALAPPDATA%\FoxPath\proxy-backup.json`（不再依赖 exe 同级是否可写）； 备份写不进去时**不会**去改注册表（宁可不开，也不留下无法还原的状态）。 另有一条 `--restore`：即使备份没了、程序也删了，也能把残留的 PAC 设置收干净。 - **在线升级**：控制面板最上面那张卡片里检查更新，升级源读仓库的 `version.json`（Gitee raw 优先、GitHub 兜底）； 升级源必须过两道闸：**① Ed25519 公钥验签**（同目录的 `version.json.sig`，用程序内置的公钥，验不过一律拒绝这条源， 换下一个候选，全都不行就保留当前版本）、**② 新版 exe 的 SHA256 与字节数**；两道都过了才下到 `.new` 并交给小助手覆盖重启。 程序没有"安装"这一步，升级就是换 exe。（签名防的是**升级源被篡改**；它不防维护者机器上的私钥本身被偷， 也不等于 Windows 代码签名证书 —— 详见 [SECURITY.md](docs/SECURITY.md)。） 升级**成功或失败**都会在屏幕右下角弹一次气泡提醒（成功 =「狐径已自动升级到 vX.Y.Z」， 失败 = 一句人话 + 怎么重试），几秒后自己消失、不用点、不打断你；**平时不弹**（已是最新版、或没在升级时不弹）。 不想要气泡就在面板「版本与升级」卡片里取消勾选 `升级结果气泡`（设置里的 `notify_bubble`，默认开）—— 关掉后升级结果仍会留在卡片里的「上次升级结果」那一行。 - **单实例**：用 Windows 命名互斥保证只有一个实例；重复双击不会起两个进程去抢 8787/8788。
--- ## 从源码构建与发版自检 构建命令、仓库文件说明、打包注意事项见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第四节与第七节； 发版前自检（发布闸门 `tools/preflight_release.py`）的完整说明见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第八节。 主程序**零第三方依赖**（只用 Python 标准库）；产物由本仓库源码构建、可复现， 逐项说明见 [CODE_SIGNING_POLICY.md](docs/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 补）**：点「检查更新」长时间连不上源，不必干等 —— 到 [Gitee 发行页](https://gitee.com/kele551/FoxPath/releases) 下载最新 `FoxPath.exe`，关掉旧程序后双击覆盖即可，配置全部保留。 > 升级细节与历史说明更正（`_PYI_*` 环境变量真因、v1.0.6→v1.0.7 那一跳、各版本护栏边界）见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第九节。 --- ## 已知边界 - **代理范围**：`github.com` / `www.github.com` / `raw.githubusercontent.com` / `objects.githubusercontent.com` / `avatars.githubusercontent.com` / `camo.githubusercontent.com`；`githubassets.com` 与 `api.github.com` **仍然直连**。 - **不能**用 `nohup ... &` 在 shell 里后台启动（命令结束进程会被终止）；要常驻就双击运行或开开机自启。 - 程序被**强制结束**（任务管理器结束进程、关机时强杀）时 `atexit` 不执行，系统代理可能仍指向本程序 —— 下次启动会自动接管；不再用了跑一次 `--restore` 即可收干净。 - **原本设了「静态代理」**（Internet 选项里手动填的代理服务器）时，启用本程序后 PAC 优先，你手填的代理在启用期间不再生效（其它网站直连），停用/退出时会自动还原，日志里会写一行提醒。 - 控制面板只监听 `127.0.0.1`，不对局域网开放；接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding），但**没有做用户鉴权** —— 本机上以你的身份运行的程序仍然可以调用它。 - 遇到端口被占用、启动失败等情况，exe 会弹一个错误框并写明日志位置，不再"点了没反应"。 > 逐条的完整说明（专属 IP 池为什么必须分开、头像域实测数字、两个平台发行版附件个数差异）见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第十节。 --- ## 版本记录 > 当前对外发布版本 **v1.2.1**（2026-10-17）。主源 **GitCode** · 历史 **Gitee** · 镜像 **GitHub**；自 2026-10-16 起代码另在 [AtomGit](https://atomgit.com/kele551/FoxPath) 有镜像。完整逐版说明见 [CHANGELOG.md](docs/CHANGELOG.md) 与 [release-notes.md](docs/release-notes.md)。 | 版本 | 日期 | 说明 | | --- | --- | --- | | **v1.1.1** | 2026-10-12 | 「检查更新」强制联网（修 6 小时缓存挡升级提示）；exe 下载多源回退 `mirrors[]`；手动下载口径进文档 | | **v1.1.0** | 2026-10-12 | **重大更新**：吞吐挑 IP、raw/pages IPv6 双池、IPv6 闸门、好 IP 复用 + 失败降权、头像域纳入代理、静默启动、PAC 总闸修正 | | **v1.0.8** | 2026-10-10 | 升级链路加固与仓库治理（10-11 曾同版本号换过一次包） | | v1.0.7 | 2026-10-09 | 升级护栏：拒绝降级、失败自动回滚、修「升级后起不来」真因 | > **v1.0.0 ～ v1.0.7 其余各版的详细说明**（原文一字未改）见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 第十一节；一行摘要见 [CHANGELOG.md](docs/CHANGELOG.md)。 --- ## 联系与反馈 遇到打不开、体检全灭、或哪里不好用，欢迎直接提 Issue：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues) 反馈时顺手附上控制面板「当前可用 IP」那一栏的数字，定位会快很多。 --- ## 许可 MIT --- ## 第三方组件与许可 **主程序零第三方依赖**：`github_direct.py` 只用 Python 标准库（socket / ssl / http.server / winreg / json …）， 所以发布的 `FoxPath.exe`、或直接 `python github_direct.py` 运行，都**不需要装任何第三方包**。 只有"开发 / 发布用"的脚本依赖下面两个包（不参与程序运行、也不进 exe）： | 组件 | 用途 | 许可 | |---|---|---| | PyInstaller | 把主程序打包成单文件 exe（`build_exe.py`） | GPLv2-or-later **+ 官方特殊例外**（允许把用它打包的程序按自身许可分发） | | requests | 发布流水线（`tools/publish.py` 调 Gitee API、下载回验） | Apache-2.0 | - 版本口径写在 [requirements.txt](requirements.txt)，打包版本固定，便于复现； - 打包进 exe 的 Python 运行时是 Python 3.13（PSF 许可）； - 本项目**不随发行版分发任何第三方素材**（图标为自绘，见 [COMPLIANCE.md](docs/COMPLIANCE.md)）。 --- ## 路线图（Roadmap） 按优先级从高到低，都是已经排进计划、能落到代码上的事： 1. **自动升级 + 升级结果气泡（代码已就绪，待发版）**：启动后静默检查新版本，**默认自动下载、校验 SHA256、替换并重启，不弹确认框**； 设置里的 `auto_update` 可以关掉，关掉后回到"发现新版只在面板提示一句"。三道护栏：只对打包版 exe 生效、只认 https 升级源、同版本 24 小时内最多 2 次。 升级**成功或失败**会弹一次气泡并在面板留一行状态，详见「核心机制 → 在线升级」。 2. **IPv6 实测地址池**：候选池目前只有 IPv4（内置 45 个 + 官方 `meta` 补充）。 要加的是"真的握手成功过才入池"的 IPv6 地址，而不是把段表直接塞进去。 3. **线路自适应**：按当前线路的历史成败给候选排序，换网（宽带 ↔ 热点）后不从头再摸一遍。 4. **代码签名申请**：产物已自带 SHA256 与可复现构建说明，下一步申请免费代码签名， 缓解"首次运行被安全软件拦一下"的体验问题。详见 [CODE_SIGNING_POLICY.md](docs/CODE_SIGNING_POLICY.md)。 > 路线图只列真实在办的事，做完一项改一项；临时想到的、还没验证的想法不写在这里。 --- ## 参与贡献与治理 | 项目 | 说明 | | --- | --- | | 维护者 | [@kele551](https://github.com/kele551)（海风），一人维护，同时担任提交者、审查者与发布批准者 | | 响应预期 | Issue / PR 一般 **7 天内**给第一次答复；安全类问题按 [SECURITY.md](docs/SECURITY.md) 私下走，**3 天内**响应 | | 参与方式 | 参与方式、Issue 模板、PR 流程、代码风格、本地构建与自查、提交信息规范见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) | | 行为准则 | 参与讨论与协作的底线（基于 Contributor Covenant 2.1），见 [CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) | | 许可与合规 | MIT（见 [LICENSE](LICENSE)），提交贡献即表示同意按同一许可发布；法律与知识产权边界见 [COMPLIANCE.md](docs/COMPLIANCE.md) | | 发布纪律 | 主程序零第三方依赖；每次发布都要先跑发版前自检 `tools/preflight_release.py`（版本一致性、冷启动演练、升级演练、失败分支、退出还原）全绿，才允许上传附件 | --- ## 支持项目 如果 **狐径 FoxPath** 帮到了你，**给仓库点个 Star ⭐** 就是最好的支持 —— 它能让更多人看到这个项目。 如果想再进一步，请作者喝杯咖啡（**完全自愿，不影响任何功能**）：

海风的微信赞赏码
微信扫一扫 · 金额随缘

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

© 2026 海风（kele551） · MIT License · Gitee 主仓库 · GitHub 镜像