# FoxPath

**Repository Path**: zdl328465042/FoxPath

## Basic Information

- **Project Name**: FoxPath
- **Description**: GitHub 直连助手 · 本机代理 + PAC 绕过 DNS/hosts · 直连实测可用的 GitHub 官方 IP · 免管理员、不改系统设置
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 狐径 FoxPath

> 作者：**海风（kele551）** · 仓库：https://gitee.com/kele551/FoxPath （GitHub 同名镜像）

![License](https://img.shields.io/badge/license-MIT-blue) ![Platform](https://img.shields.io/badge/platform-Windows-blue) ![Version](https://img.shields.io/badge/version-v1.0.5-blue)

GitHub 直连助手。本机代理 + PAC，绕过 DNS 和 hosts，直连当前实测可用的 GitHub 官方 IP。

**主程序（`github_direct.py` / 发布的 exe）不用管理员权限，不改 hosts，不改系统 DNS。**

> 仓库里另有一个**互不相干的旧版方案** `Fix-GitHub.ps1`（配合 `Run-GitHubFix.bat`）：
> 它走的是完全不同的路子 —— 直接改系统 `hosts` 文件 + 装一个计划任务定时换 IP，
> **需要管理员权限，会改 hosts**。两套方案二选一，别同时用。详见下方文件表。

## 目录

- [解决什么问题](#解决什么问题)
- [原理](#原理)
- [用法](#用法)
- [核心机制](#核心机制)
- [从源码构建](#从源码构建)
- [已知边界](#已知边界)
- [版本记录](#版本记录)
- [联系与反馈](#联系与反馈)
- [许可](#许可)

## 解决什么问题

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

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

根因通常不在墙，而在**本地 DNS 解析出来的那个 GitHub IP 在当前线路上不通**。浏览器老实地按 DNS 走，就卡死了。

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

## 原理

```
浏览器 ──PAC──> 狐径本地代理 127.0.0.1:8787 ──> 实测可用的 GitHub 官方 IP
              （只代理 github.com）            （绕过 DNS）
```

| 传统做法 | 狐径 |
| --- | --- |
| 改 hosts（要管理员、IP 死了就失效） | 本机代理 + PAC，写在 HKCU，普通用户权限即可 |
| 依赖系统 DNS 解析 | 不查 DNS，直连实测能用的官方 IP |
| IP 失效后彻底打不开 | 每 5 分钟重测一轮，死 IP 自动换 |
| 程序退出后系统代理指向空端口，比原来更糟 | 退出/点「退出并还原」都会还原；PAC 带 `DIRECT` 兜底；还有 `--restore` 一键收尾 |

## 用法

1. 从 [Releases](https://gitee.com/kele551/FoxPath/releases) 下载 `FoxPath.exe`
2. 双击运行 → 浏览器自动打开控制面板 `http://127.0.0.1:8788/ui`
3. 勾选「开机自启」即可后台常驻

**首次启动请等 15～20 秒**：程序要并发体检 49 个候选 IP，体检完成前代理还没完全生效。

### 控制面板上有什么

控制面板 `http://127.0.0.1:8788/ui`，从上到下四块：

| 区块 | 显示什么 | 能做什么 |
|---|---|---|
| **版本与升级** | 当前版本 `=====>` 新版本（没有新版时右边是 `—`） | `检查更新` 问一次升级源；真有新版才出现 `立即升级`。点了以后自动下载 → 校验 SHA256 → 覆盖 exe → 重启，下面一条渐变色进度条跟着走 |
| **加速状态** | 出口 IP（含延迟）、加速状态（已启用 / 未启用）、上次体检时间 | `启用加速`、`停用并还原`、`立即重测`、`退出并还原`，以及 `开机自启` 勾选框 |
| **当前可用 IP** | 按延迟排序的可用 IP 表，每 5 分钟自动刷新 | 看当前线路还剩几个能用。一个都没有时会自动重拉官方 IP 表并回退系统 DNS —— 反馈问题时把这栏的数字一起贴上 |
| **日志** | `foxpath.log` 的尾部，自动滚到最新 | 打不开 GitHub 先看这里 |

> 升级不用手动换文件：新版下完先校验 SHA256，通过后交给一个小助手 ——
> 让旧程序退出并还原系统代理 → 覆盖 exe → 自动重启。校验不过就放弃，不会留半成品。

> 从 v1.0.3 起文件名不再带版本号（固定 FoxPath.exe），**版本号写进 exe 的属性里**（鼠标悬停或右键-属性-详细信息可见）。
> 下载文件名故意用 ASCII（`FoxPath.exe`）。GitHub / Gitee 上传附件时会把中文
> 文件名改坏（实测 `狐径-v1.0.0.exe` 传上去变成了 `-v1.0.0.exe`），所以对外一律用 ASCII 名。

**出过问题想自救**：`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 兜底）；
  新版下到 `.new`、比对 SHA256 通过后才交给小助手覆盖并重启。程序没有"安装"这一步，升级就是换 exe。
- **单实例**：用 Windows 命名互斥保证只有一个实例；重复双击不会起两个进程去抢 8787/8788。

## 从源码构建

```bash
pip install pyinstaller

python build_exe.py                   # 打包成 FoxPath.exe
```

> 图标不用管：`app.ico` 已经入库。仓库里那几个 `create_icon*.py` /
> `make_icon_from_user_image.py` 是当初做图标用的一次性脚本，里面的输入输出路径都写死在
> 作者本机（还有一个依赖本机剪贴板缓存），**在别的机器上跑不通**，正常构建不需要它们。

| 文件 | 说明 |
| --- | --- |
| `github_direct.py` | 主程序：代理、PAC、体检、控制面板（推荐用这个） |
| `Fix-GitHub.ps1` | **旧版备用方案**：往 `hosts` 里钉 IP + 装计划任务定时换；**需要管理员权限**，与主程序是两套互不干扰的做法，二选一即可 |
| `Run-GitHubFix.bat` | 以管理员身份拉起 `Fix-GitHub.ps1`（会弹 UAC） |
| `build_exe.py` | PyInstaller 打包脚本 |
| `make_icon_from_user_image.py` | 图标生成（抠图 + 圆角底 + 多尺寸 ICO） |
| `app.ico` | 程序图标 |
| `release-notes.md` | 发行说明 |
| `使用说明.txt` | 中文使用说明 |

打包注意：

- PyInstaller 的 `--clean` 参数在某些受限环境下会因批量删缓存被拦，脚本里已去掉。
- 产物名与版本号都从 `github_direct.py` 的 `APP_VERSION` 推导，只有一个来源，不用改两处。
- **`.ps1` 文件必须保存为「UTF-8 带 BOM」**。PowerShell 5.1 对没有 BOM 的文件按 ANSI 读，
  中文会变乱码，字符串/花括号被破坏后直接 ParserError —— `Fix-GitHub.ps1` 在 v1.0.1 之前
  就是这样：文件本身完整，但因为没有 BOM 而**从未成功运行过**。

## 已知边界

- 只代理 `github.com` / `www.github.com`。GitHub 的 CSS/JS/头像在 `githubassets.com`、`githubusercontent.com` 上，这些域名直连本来就通，**走代理反而连不上**，会导致页面只剩裸 HTML、按钮点不动。
- 不代理 `api.github.com`（本来就通），Git 命令行操作不受影响。
- 绿色单文件，无需安装；但**不能**用 `nohup ... &` 在 shell 里后台启动，那样命令结束进程会被终止。要常驻就双击运行或开开机自启。
- 如果程序被**强制结束**（任务管理器结束进程、关机时强杀），`atexit` 不会执行，系统代理可能仍指向本程序。
  下次启动本程序会自动接管；如果不再用了，跑一次 `--restore` 即可收干净。
- 控制面板只监听 `127.0.0.1`，不对局域网开放；接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding），
  但没有做用户鉴权 —— 本机上以你的身份运行的程序仍然可以调用它。
- **如果你原本设了「静态代理」（Internet 选项里手动填的代理服务器）**：一旦启用本程序，PAC 会优先于静态代理，
  而你手动设的那个代理在启用期间不再生效（其它网站会直连）。停用/退出时会自动还原。程序检测到这种情况会在
  日志里明确写一行提醒。
- 遇到端口被占用、启动失败等情况，exe 会弹一个错误框并写明日志位置，不再"点了没反应"。

## 版本记录

> 当前对外发布版本是 **v1.0.5**（2026-09-22，Gitee 与 GitHub 同步）。`v1.0.2` ~ `v1.0.4` 是本机迭代版本，
> 未单独发版，改动已一并进 v1.0.5。

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原 |
| v1.0.1 | 2026-09-22 | 修「还原不了系统代理」一类缺陷：重复启用不再污染备份、备份失败不再改注册表、静默模式也注册退出还原、加单实例与端口占用提示、日志落文件、新增 `--restore`；`Fix-GitHub.ps1` 补 UTF-8 BOM（此前无法运行）；打包脚本改为 ASCII 产物名 + 版本号单一来源；修正文档与实现不一致之处 |
| v1.0.2 | 2026-09-22 | 修「双击没反应」：程序已在后台时，第二次双击改为**直接打开正在运行的控制面板**再退出（以前只写一行日志就静默退出，用户以为程序坏了） |
| v1.0.3 | 2026-09-22 | 重做图标（去白底卡片、清掉残留边框、裁到狐狸本体居中放大，重出七档尺寸）；产物改名 `FoxPath.exe` 不带版本号，版本号写进 exe 属性 |
| v1.0.4 | 2026-09-22 | 加作者署名（源码文件头、控制面板底部、日志、exe 属性、README 统一为「海风（kele551）」）；README 里的私人邮箱换成 Issues 链接 |
| v1.0.5 | 2026-09-22 | **网页版在线升级**：控制面板里检查更新、版本迁移动画 + 渐变色进度条，下载到 `.new` 校验 SHA256 后由独立小助手接管（先让旧程序退出并还原系统代理 → 覆盖 → 重启） |

详细发行说明见 [release-notes.md](release-notes.md)。

## 联系与反馈

遇到打不开、体检全灭、或者觉得哪里不好用，欢迎直接邮件反馈，我会看：

[仓库 Issues](https://gitee.com/kele551/FoxPath/issues)

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

## 许可

MIT