FoxPath 发行版 - Gitee.com

v1.2.1

2026-10-17 12:32 v1.2.1 7c53e8c

狐径 FoxPath v1.2.1 — 升级源切到 GitCode（国内访问更快）+ 下载地址多源回退

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**不能少**，否则老版本拿不到升级提示 |
| `version.json.sig` | version.json 的 Ed25519 签名，本版及以后客户端验签用。**不能少**，否则新版拿不到升级 |

## 这一版改了什么

### 1. 主升级源切到 GitCode（国内访问更快）
- 升级检查**优先走 GitCode**（国内），Gitee / GitHub 保留兜底；
- **下载地址优先 GitCode**，Gitee / GitHub 作镜像回退（`mirrors[]`，老版本自动忽略该字段）；
- 老用户通过原来的入口升级到本版后，自动切到 GitCode，无需重装、无需改配置。

### 2. 升级验签照旧
- Ed25519 公钥验签不变：**验不过 / 缺签名 / 签名格式不对，一律拒绝并保留当前版本**；
- 签名私钥只在维护者机器上，绝不进程序、绝不进仓库。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- 线路分钟级抖动期间，主站可能"通几秒、堵几十秒"，体检与吞吐挑 IP 会如实反映。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.2.1 | 2026-10-17 | 升级源 / 下载地址切到 GitCode（国内更快），Gitee / GitHub 兜底；验签不变 |
| v1.2.0 | 2026-10-16 | 升级通道加固：在线升级增加 Ed25519 公钥验签（验不过拒绝、缺签名拒绝）；文档与仓库治理一并带上 |
| 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.6 | 2026-10-08 | 候选池扩到官方全量、IP 表三源依次试、raw 与发布附件加速 |
| v1.0.5 | 2026-09-22 | 网页版在线升级（检查更新/立即升级/进度条/小助手） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、IP 体检、候选池刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.2.1

v1.2.0

2026-10-16 17:16 v1.2.0 0532c09

狐径 FoxPath v1.2.0 — 升级通道加固：在线升级增加 Ed25519 公钥验签

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**不能少**，否则老版本拿不到升级提示 |
| `version.json.sig` | **新增**：version.json 的 Ed25519 签名，本版及以后客户端验签用。**不能少**，否则新版拿不到升级 |

## 这一版修了什么

### 1. 在线升级增加 Ed25519 公钥验签（安全加固）

- **为什么**：以前的升级校验只比 sha256，而 sha256 与安装包放在同一个升级源里——源被整体替换
  （例如仓库账号被盗、有人推了恶意 version.json + 恶意 exe）时，sha256 会一起被改，等于没验。
- **现在**：升级源 version.json 必须带一份同目录的 version.json.sig，客户端用**内置公钥**验签；
  **验签不过 / 缺签名 / 签名格式不对，一律拒绝并保留当前版本**，绝不"先替换再校验"。
- **密钥**：签名私钥只在维护者机器上（绝不进程序、不进仓库）；客户端只带 32 字节公钥（公开无妨）。
- **能力边界（如实说明）**：签名能防"升级源被篡改 / 中间人换包"，**防不了**"维护者机器上的私钥被偷"，
  也不等于 Windows 代码签名证书（那解决的是杀软误报，属另一件事）。
- **兼容性**：老版本不认识 .sig、只读 version.json，升级行为不受影响；本版起强制验签。

### 2. 文档与仓库治理（随本版一并带上）

- 使用说明去掉 Markdown 残留、版本章节改免维护写法；CHANGELOG 补齐 v1.0.2 / v1.0.3 / v1.0.4；
  行为准则补中文抬头；演示页注明录制版本；三平台（Gitee / GitHub / AtomGit）代码一致。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- 线路分钟级抖动期间，主站可能"通几秒、堵几十秒"，体检与吞吐挑 IP 会如实反映。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.2.0 | 2026-10-16 | 升级通道加固：在线升级增加 Ed25519 公钥验签（验不过拒绝、缺签名拒绝）；文档与仓库治理一并带上 |
| 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.6 | 2026-10-08 | 候选池扩到官方全量、IP 表三源依次试、raw 与发布附件加速 |
| v1.0.5 | 2026-09-22 | 网页版在线升级（检查更新/立即升级/进度条/小助手） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、IP 体检、候选池刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.2.0

v1.1.1

2026-10-12 11:09 v1.1.1 4ea5840

狐径 FoxPath v1.1.1 — 修复版：「检查更新」强制联网（不再被 6 小时缓存挡住）

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这一版修了什么

### 1. 「检查更新」被 6 小时缓存挡死（重大缺陷修复）

- **现象**：用户按下「检查更新」，面板回"已是最新版"——但**根本没下网络**，读的是 6 小时内的缓存。
  后果一：新版发布后，老用户最长 6 小时毫无感知，自动升级同样被缓存挡住；
  后果二：刚升级完的实例读到升级前的旧缓存，面板误报"本地版本比线上新"。
- **根因**：手动检查、立即升级的闸门与静默检查共用了 `use_cache=True` 的 6 小时 TTL。
- **修复**：「检查更新」和「立即升级」**强制联网**；静默自动检查保留 6 小时节奏（不轰炸源站）。
  联网全失败时回读缓存，并在结论里明说"**（联网失败，显示的是上次检查的结果）**"——
  不再拿过期数据装现状。
- 已按用户路径做对照验证：植入"新鲜但过期"的假缓存（线上=1.0.5，_checked=现在），
  修复版点检查正确返回真实线上版本并把缓存刷成真值。

### 2. exe 下载支持多源回退（能力储备）

- `version.json` 的 `exe` 节点新增可选 `mirrors[]`：下载时按 `url → mirrors` 依次试错，
  只认 https；全失败时报出"共试 N 个源"。当前仍只发 Gitee 主源 + GitHub 镜像两个仓库，
  不新增平台；此字段为后续任何镜像留位。老版本读到 `mirrors` 自动忽略，无兼容风险。

### 3. 文档口径

- README/发行说明明确：**升级源不通（检查更新长时间连不上）时，到 Gitee 发行页手动下载
  `FoxPath.exe` 覆盖安装即可**，配置保留、无需卸载。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- 线路分钟级抖动期间，主站可能"通几秒、堵几十秒"，体检与吞吐挑 IP 会如实反映。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 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.6 | 2026-10-08 | 候选池扩到官方全量、IP 表三源依次试、raw 与发布附件加速 |
| v1.0.5 | 2026-09-22 | 网页版在线升级（检查更新/立即升级/进度条/小助手） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、IP 体检、候选池刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.1.1

v1.1.0

2026-10-12 10:18 v1.1.0 7d4c0c8

狐径 FoxPath v1.1.0 — 重大更新：吞吐挑 IP、IPv6 双池与 IPv6 闸门（"时好时坏"的集中收口）

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这次更新了什么、为什么

v1.0.8 线上包（10-11 21:09 构建）与仓库代码之间差了一批**已在真机验证、但从未随包发布**的改动。
很多用户报的"GitHub 时好时坏"，根子就在这些没发出去的修复上。本次一并收口，发一个正式版本号，让已装用户能自动吃到。

### 1. 挑 IP 改看真实吞吐，不再只看握手（重大）

- **目的**：治"连得上、页面打不开"。实测大量存在"TCP/TLS 握手 0.1 秒成功、HTTP 整页 8~25 秒下不完"的 IP，按握手快慢排队必然挑错。
- **做法**：热备池在挑人前用短窗口实测吞吐（KB/s 排序）；赌输一次立刻作废该证据，避免拿过期数据反复陪选。

### 2. IPv6 双池：raw 与 Pages 各用各的 IPv6 候选（重大）

- **目的**：IPv4 全线拥塞时给 raw/附件/Pages 留一条不一起堵的活路（10-11 下午 IPv4 全灭时段实测：IPv4 `185.199.108.133` 超时，IPv6 `2606:50c0:800x::154` 拉 gitignore 文件 200、0.15 秒）。
- **做法**：`raw` 池并入 `2606:50c0:8000~8003::154` 四址，`pages` 池并入 `::153` 四址——两组证书不同（`*.githubusercontent.com` vs `*.github.io`），不混用。**github.com 主站没有可用 IPv6**（扫过 144 个候选），主站池继续不配 IPv6，不白占名额。

### 3. IPv6 闸门（本版新增）

- **目的**：家里/单位没有 IPv6 出口的线路，IPv6 候选每轮白超时 8 个名额，体检变慢且"IPv6 可用 0/N"永远难看。
- **做法**：探测前先用一次 UDP connect（不发任何包、只查本机 IPv6 路由）判断本机有无 IPv6 出口；没有就本轮跳过 IPv6 探测，成功缓存 5 分钟，失败 60 秒后自动重探——哪天 IPv6 通了/修好了，下一轮体检自然把它们捡起来用。

### 4. 上次连通的好 IP 优先复用 + 连续失败降权

- **目的**：治"体检名次过期还死守第一名"。实测体检刚排第一的 IP 会在两分钟间隔里悄悄死掉，转发串行撞死 IP 要空等 8 秒才轮到好的。
- **做法**：记下每个池"上一次真正连通成功的 IP"，下次转发优先复用；同时失败计数**跨体检周期保留**，连败的往后靠，一旦成功清零——"时好时坏"的 IP 自动让位给稳定的。

### 5. 头像/外链图域名纳入代理；启动彻底安静

- `avatars.` / `camo.githubusercontent.com` 进代理池（与 raw 同段同证书）；282KB 头像直连均值 10.68 秒 → 走代理 2.65 秒。主站 HTML 秒开但头像转圈导致的"整页打不开"观感就此解决。
- 双击后不再自动弹面板、不弹气泡；错误一律只进日志。左键点托盘看面板，右键「退出并还原」。

### 6. PAC 总闸修正（10-11 修复，随本版正式发包）

- Windows 下 `AutoConfigURL` 必须配合 `ProxyEnable=1` 才生效；此前只写 PAC 不开总闸，表现为"已启用加速但浏览器不读 PAC、GitHub 依旧打不开"。启用/退出均按备份对称还原，不残留。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- raw / 发布附件的专属池在部分线路上**时通时不通**，体检会如实反映，不会假装成功。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding）。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 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.6 | 2026-10-08 | 候选池扩到官方全量、IP 表三源依次试、raw 与发布附件加速、面板线路体检 |
| v1.0.5 | 2026-09-22 | 网页版在线升级：检查更新/立即升级/进度条，独立小助手接管覆盖重启 |
| v1.0.1 | 2026-09-22 | 修「还原不了系统代理」一类缺陷 |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.1.0

v1.0.8

2026-10-10 10:47 v1.0.8 031c14d

狐径 FoxPath v1.0.8 — 升级链路加固与仓库治理（一次代码体检带来的修复）

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这一版改了什么

这一版**没有新功能**，全部来自一次完整的源码体检（逐行读代码 + 语法检查 + 隔离实验 + 线上升级源比对）
之后的修复。目的只有一个：**让升级这条路更不容易断，也让"照文档就能复现"这句话成立**。

### 升级链路

- **升级脚本里的版本号做了转义**：以前写进 PowerShell 小助手脚本时是直接拼字符串，
  版本号里若出现单引号会让整段脚本语法出错 —— 结果是**覆盖、重试、回滚一行都执行不到**，
  用户侧看到的就是"点了升级没反应"。现在统一转义，并在入口按字符集卡死，非法版本号直接拒绝。
- **失败时的清理不再被跳过**：发版前自检脚本里的收尾逻辑（还原注册表、还原升级源文件、
  把用户原本在跑的程序拉起来）此前依赖一个在异常路径上可能还不存在的变量 ——
  一旦演练中途出错，**整段清理都会被跳过**，还会把真正的错误盖掉。已修正初始化顺序。

### 仓库治理（评审与协作者直接受益）

- **发版前自检脚本现在能在仓库目录里直接跑**：此前它按"工作区布局"推导路径，
  在仓库里执行文档给的那条命令会直接报错（`FileNotFoundError`）——
  评审或协作者照 README 操作看到的是一堆异常。现在两种目录布局都能自动识别。
- **自检脚本在中文控制台下不再崩**：结论那行用了符号字符，在某些代码页下会抛编码异常，
  于是"检查明明全绿"却以一段报错收场。已统一改成 UTF-8 输出。
- **上传清单里删掉一个早已不存在的文件**：以前即使其余文件全部上传成功，
  也会因为这一条永远报"完成 14/15"并返回失败码。
- **移除三个一次性图标脚本**：它们把输入输出路径写死在作者本机、在别的机器上跑不通，
  其中还有一个用到了第三方的吉祥物素材 —— 与仓库里"图标为自绘、不含任何第三方吉祥物或标志"
  的合规声明相冲突。当前在用的图标**确为自绘**，这一版把遗留脚本清理掉，让声明与仓库一致。
- README 的图标说明同步改成中性表述并强化了"图标为自绘"。

## 升级时请注意

- **从 v1.0.6 或更早升上来**：那一跳用的仍是**老版小助手**（不重试、不回滚），**可能失败一次**；
  失败了**双击一下 `FoxPath.exe`** 即可（升级本身是完成的）。
- **从 v1.0.7 往后**：升级全程带护栏 —— 拒绝降级、失败会自动回滚并保留一个能用的版本。
- 程序退出前会还原系统代理，所以升级过程中**不影响上网**。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- raw / 发布附件的专属池在部分线路上**时通时不通**，体检会如实反映，不会假装成功。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding）。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.0.8 | 2026-10-10 | **升级链路加固与仓库治理**（本次对外发布，Gitee 与 GitHub 同步）：升级脚本版本号转义 + 非法版本号拒绝、失败清理不再被跳过；发版前自检脚本可在仓库内直接运行、中文控制台不再报错；上传清单清理；移除三个一次性图标脚本（与"图标为自绘"的合规声明保持一致） |
| v1.0.7 | 2026-10-09 | **升级护栏**：拒绝降级、升级失败自动回滚、修掉「升级后新版起不来」的真因（`_PYI_*` 继承，同时更正此前「杀毒软件拦截」的误判）；默认自动升级 + 升级结果气泡与面板回执；接管 github.io |
| v1.0.6 | 2026-10-08 | 联通/移动友好：候选池扩到官方全量、IP 表三源依次试、raw 文件与发布附件也能加速（回应 issue #1）、面板线路体检与手动指定 IP |
| v1.0.5 | 2026-09-22 | 网页版在线升级：检查更新 / 立即升级 / 进度条，下载校验 SHA256 后由独立小助手接管覆盖重启 |
| v1.0.1 | 2026-09-22 | 修「还原不了系统代理」一类缺陷；`Fix-GitHub.ps1` 补 UTF-8 BOM（此前无法运行） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.0.8

v1.0.7

2026-10-09 14:32 v1.0.7 f4b3e3b

狐径 FoxPath v1.0.7 — 升级护栏：不会把旧版本当新版，升坏了会自动回滚

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这一版修的两个升级问题（都是真机上抓到的）

### ① 不会再把「降级」当「升级」提示

**现象**：本地版本比线上新时（开发/预发布版本），面板仍然显示「发现新版本 vX」，
点「立即升级」会把本地版本**换成更旧的线上版本**。

**这一版**：升级前按**版本号语义**比较（`1.0.10 > 1.0.9` 这种也算得对），三种结论各说各的：

- 线上更高 → 「发现新版本 vX（当前 vY）」，可以升级；
- 一样 → 「已是最新版 vX」；
- 线上更低 → 「本地版本比线上新（线上尚未发布）」，**「立即升级」按钮置灰**。

服务端也加了硬闸门：任何升级入口在「远程 ≤ 本地」时**直接拒绝**并写日志
（`拒绝降级：远程 x < 本地 y`），连下载都不会发生 —— 只挡前端按钮是不够的。

### ② 升级之后新版起不来 —— 真因查清并修掉

**现象**：升级流程走完（下载、校验、覆盖都成功），但新版**一次都没起来**，
用户看到的是「升级之后程序没了」。

**真因**（对照实验钉死）：升级小助手是从主程序里起的，会**继承单文件 exe 的 `_PYI_*` 环境变量**
（`_PYI_PARENT_PROCESS_LEVEL` / `_PYI_APPLICATION_HOME_DIR` / `_PYI_ARCHIVE_FILE`）。
新版本的引导程序一看到 `_PYI_PARENT_PROCESS_LEVEL`，就以为「我是子进程、已经解过包了」，
于是**跳过解包**、去找那个**早已随旧实例退出被删掉的临时目录**，直接失败
（`Failed to load Python DLL`）—— 应用连一行日志都没有。

**修复**：起新版本之前先把这些变量从环境里擦掉（主程序侧 + 小助手脚本各擦一次，双保险）。

> **更正一条旧结论**：2026-10-08 那次同类故障当时记为「杀毒软件拦截」（实测过火绒），
> **真因就是上面这个**，与杀毒软件无关。特此更正。

### 顺带补上的兜底

- 升级「成功」的判定改成**按版本号确认**（新版真的起来了才算成功），不再只是「文件覆盖完了」；
- 新版连续起不来时，小助手会**把旧版本放回去并重新启动它**
  （日志里能看到三步：覆盖失败 / 回滚 / 旧版已起来）；
- 升级交接过程中的启动路径**不再弹模态对话框**（卡住等人点「确定」会让升级看起来像死机）；
- 升级存档带上格式版本并向下兼容，新旧版本互相读对方的存档都不会报错。

## 本版还包含（开发中积累、随本版一起发）

- **默认自动升级**：发现新版本后不再弹确认框，静默完成；**只有失败才提示一次**，可在设置里关掉。
- **升级结果气泡 + 面板回执**：成功/失败都会在系统通知里弹一下；面板「版本与升级」那一栏常驻显示
  「上次升级结果（成功/失败 + 时间 + 原因）」，重启后仍在。
- **接管 `github.io` / GitHub Pages 相关域名**：演示页、项目主页这类静态站点也能正常打开。
- 十余项边界与安全加固：接口同源校验、数据目录原子写、异常路径的还原与幂等、`/pac` 全 ASCII 等。

## 升级时请注意

- **从 v1.0.6 升到 v1.0.7 这一跳**用的仍然是**老版小助手**（不重试、不回滚），所以**仍可能失败一次**；
  失败了**双击一下 `FoxPath.exe`** 即可（升级本身是完成的）。
- **从 v1.0.7 往后**，升级全程带护栏：失败会自动回滚并保留一个能用的版本。
- 程序退出前会还原系统代理，所以升级过程中**不影响上网**。

## 已知边界（照旧）

- 运营商如果按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 只能换网络或换方案。
- raw / 发布附件的专属池在部分线路上**时通时不通**，体检会如实反映，不会假装成功。
- 只代理 GitHub 相关域名；**不改 hosts、不改系统 DNS**，退出时还原系统设置。
- 控制面板只监听 `127.0.0.1`，接口已做 Host/Origin 同源校验（挡网页 CSRF 与 DNS rebinding）。

## 版本历史（近几版）

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.0.7 | 2026-10-09 | **升级护栏**：拒绝降级、升级失败自动回滚、修掉「升级后新版起不来」的真因（`_PYI_*` 继承，同时更正此前「杀毒软件拦截」的误判）；默认自动升级 + 升级结果气泡与面板回执；接管 github.io（本次对外发布，Gitee 与 GitHub 同步） |
| v1.0.6 | 2026-10-08 | 联通/移动友好：候选池扩到官方全量、IP 表三源依次试、raw 文件与发布附件也能加速（回应 issue #1）、面板线路体检与手动指定 IP |
| v1.0.5 | 2026-09-22 | 网页版在线升级：检查更新 / 立即升级 / 进度条，下载校验 SHA256 后由独立小助手接管覆盖重启 |
| v1.0.1 | 2026-09-22 | 修「还原不了系统代理」一类缺陷；`Fix-GitHub.ps1` 补 UTF-8 BOM（此前无法运行） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原 |

反馈：[GitHub Issues](https://github.com/kele551/FoxPath/issues)　·　[Gitee Issues](https://gitee.com/kele551/FoxPath/issues)

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.0.7

v1.0.6

2026-10-08 11:07 v1.0.6 9c06175

狐径 FoxPath v1.0.6 — 联通/移动友好：候选池扩大、raw 文件也能加速、面板能自查

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里 |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少** |

## 这一版修的问题：某些宽带（联通/移动）用不了

**根因**：程序启动时要去 `api.github.com/meta` 拉官方 IP 表 —— 这一步在**联通/移动的部分线路上根本不通**。
拉不到就只剩内置的 15 个手写地址，其中不少早已失效，体检结果就是「可用 0 个」，于是怎么都不通。

这一版做了四件事：

1. **内置候选池扩到官方全量**（45 个 IPv4）：即使在线同步失败，手上也有足够多的地址可试。
2. **IP 表三个源依次试**：`api.github.com/meta` → **Gitee 上的 meta.json**（国内三网都能拉）
   → GitHub raw。联通/移动拉不到官方接口时，走 Gitee 这一条。
3. **raw 文件与发布附件也能加速**（回应 GitHub issue #1）：
   `raw.githubusercontent.com` / `objects.githubusercontent.com` 现在走**专属 IP 池**
   （官方 `185.199.108.0/22`）。以前不代理它们，是因为塞进 `github.com` 的池子会连到错误
   服务器、页面脚本全废 —— 那是池子不对，不是不能代理。头像/资源域仍然直连，不碰页面渲染。
4. **面板新增「线路体检」+「手动指定 IP」**：
   - 体检那一行可以点「复制诊断信息」直接发给作者，内容形如
     `IPv4 可用 31/49 | IPv6 可用 0/0 | raw 可用 2/4 | 表源 官方 | 最快 20.200.245.247(456ms)`；
   - 自动探测全都不通时，填一个你这条线能连上的官方 IP 就能救急（可一键清除）。

## 顺带修掉的两个坑

- **429 限流被当成「死 IP」**：GitHub 对我们的探测有速率限制，返回 429 时服务器其实是活的。
  现在不再判死 —— 实测可用数从 19/49 涨到 **31/49**。
- **不再瞎猜 IPv6**：官方只给网段，照网段猜出来的地址在 HTTP 层返回 `500 Domain Not Found`，
  所以内置表里故意留空；真实 IPv6 从用户自己的 DNS 解析结果里取（IPv4 全灭时才会用到）。

## 升级时请注意（本次重新打包时补入的加固）

升级完成后程序会**自动重新打开**。如果它没出现（个别杀毒软件会拦住升级后的第一次启动，
实测火绒出现过），**双击一下 FoxPath.exe 就能正常使用** —— 升级本身是完成的；
程序退出前已还原系统代理，不会影响上网。

本版重新打包时还给升级流程加了保护（对**由本版发起的后续升级**生效）：
覆盖后先等 3 秒 → 启动后轮询面板确认真的起来了 → 没起来就按 5/10/20/40/60/90 秒
递增重试 6 次 → 仍失败就弹窗提示手动双击；并顺手清理 %TEMP% 里 24 小时前的解包残留。

## 已知边界（照旧）

- 运营商如果是按 **SNI** 掐断（TLS 握手里能看到域名），本地代理帮不上忙 —— 那种情况只能换网络或换方案。
- raw / 附件的专属池在部分线路上会**时通时不通**，体检会如实反映，不会假装成功。

---

狐径 FoxPath v1.0.5 — 在控制面板里直接升级

## 下载

| 文件 | 说明 |
| --- | --- |
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这一版新增：在线升级

升级做进了网页控制面板，不用再手动下载替换：

- 点「检查更新」即走完整流程：读 `version.json` → 比对版本 → 下载新 exe → 校验 SHA256 → 覆盖并重启。
- 界面有版本迁移动画（`1.0.4 ====> 1.0.5`）、渐变色进度条、实时百分比与已下载字节；
  结束给出三种状态 —— 有新版本 / 已是最新 / 失败原因。
- 覆盖交给独立的 PowerShell 小助手：先让旧程序退出并**还原系统代理**，确认进程消失后再替换文件、
  重新启动。不会出现「文件被占用、覆盖不了」。

接口：`POST /api/update/check`、`POST /api/update/start`、`GET /api/update/status`（沿用同源校验）。

## 从 v1.0.1 到这一版

`v1.0.2` ~ `v1.0.4` 是本机迭代版本，未单独发版，改动都并进这一版：

- **双击「打不开」** —— 程序已经在后台跑时，第二次双击以前只写一行日志就退出。程序是无窗口的、
  又没有托盘图标，屏幕上什么都不会出现，只能被判断成「坏了」。现在会把**正在运行的那个控制面板
  交给浏览器打开**；静默模式（开机自启）仍然安静退出。
- **图标重做** —— 原图是白底卡片、构图偏右下、边缘还留着一条线，缩到小尺寸糊成一团。
  改为去白底、清边框、裁到主体后居中放大，重出 16~256 七档 ICO。
- **产物命名** —— 文件名不再带版本号（固定 `FoxPath.exe`），版本号写进 exe 的版本资源。
- **作者署名** —— 源码文件头、控制面板底部、日志、exe 属性统一为「海风（kele551）」；
  README 里的私人邮箱换成仓库 Issues 链接。
- **体检日志带上运行时长** —— 长跑日志里能一眼看出是持续在跑，还是中途死过又重开。

## 用法

1. 下载 `FoxPath.exe`，双击运行
2. 浏览器自动打开控制面板 `http://127.0.0.1:8788/ui`
3. 勾选「开机自启」即可后台常驻

首次启动请等 15~20 秒（要并发体检 49 个候选 IP），体检完成前代理尚未完全生效。

## 已知边界

- 只代理 `github.com` / `www.github.com`；`githubassets.com` / `githubusercontent.com` /
  `api.github.com` 保持直连（走代理反而连不上，会让页面只剩裸 HTML、按钮点不动）
- 不能用 `nohup ... &` 在 shell 里后台启动，那样命令结束进程会被终止
- 控制面板只监听 `127.0.0.1`，但没有鉴权：本机上的其它程序或网页理论上可以调用它的接口
  （本地回环，风险很低；接口已做 Host/Origin 同源校验，挡网页 CSRF 与 DNS rebinding）
- 被强制结束时 `atexit` 不会执行，系统代理可能仍指向本程序；跑一次 `--restore` 收干净

## 版本历史

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v1.0.5 | 2026-09-22 | **网页版在线升级**：检查更新 / 立即升级 / 进度条，下载校验 SHA256 后由独立小助手接管覆盖重启（本次对外发布，Gitee 与 GitHub 同步） |
| v1.0.4 | 2026-09-22 | 作者署名统一为「海风（kele551）」；README 私人邮箱换 Issues 链接（本机迭代，未单独发版） |
| v1.0.3 | 2026-09-22 | 重做图标；产物固定 `FoxPath.exe`，版本号写进 exe 属性（本机迭代，未单独发版） |
| v1.0.2 | 2026-09-22 | 程序已在后台时，第二次双击改为直接打开正在运行的控制面板（本机迭代，未单独发版） |
| v1.0.1 | 2026-09-22 | 修「还原不了系统代理」一类缺陷：重复启用不再污染备份、备份失败不再改注册表、静默模式也注册退出还原、加单实例与端口占用提示、日志落文件、新增 `--restore`；`Fix-GitHub.ps1` 补 UTF-8 BOM（此前无法运行） |
| v1.0.0 | 2026-09-19 | 首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原 |

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

---

维护约定（发版的人看）：这份文件的**首行版本号就是当前线上版本**。发新版前把它整篇换成新版本的说明
（或改用 `--notes <文件>`）；`tools/publish.py` 不带 `--notes` 时会读这份文件，并校验首行版本号与
要发的版本一致，不一致直接中止 —— 免得发行页挂着上一版的文案。

最后提交信息为： release: v1.0.6

v1.0.5

2026-09-22 23:11 v1.0.5 31b5e3e

狐径 FoxPath v1.0.5 — 在控制面板里直接升级

## 下载

| 文件 | 说明 |
|---|---|
| `FoxPath.exe` | 主程序，绿色单文件，双击即用。版本号写在 exe 属性里（鼠标悬停 / 右键-属性-详细信息） |
| `version.json` | 升级信息，已装用户点「检查更新」时读取。**这个附件不能少**，否则老版本拿不到升级提示 |

## 这一版新增：在线升级

升级做进了网页控制面板，不用再手动下载替换：

- 点「检查更新」即走完整流程：读 `version.json` → 比对版本 → 下载新 exe → 校验 SHA256 → 覆盖并重启。
- 界面有版本迁移动画（`1.0.4 ====> 1.0.5`）、渐变色进度条、实时百分比与已下载字节；
  结束给出三种状态 —— 有新版本 / 已是最新 / 失败原因。
- 覆盖交给独立的 PowerShell 小助手：先让旧程序退出并**还原系统代理**，确认进程消失后再替换文件、
  重新启动。不会出现「文件被占用、覆盖不了」。

接口：`POST /api/update/check`、`POST /api/update/start`、`GET /api/update/status`（沿用同源校验）。

## 线上此前停在 v1.0.1，中间几版一并带上

- **双击「打不开」** —— 程序已经在后台跑时，第二次双击以前只写一行日志就退出。程序是无窗口的、
  又没有托盘图标，屏幕上什么都不会出现，只能被判断成「坏了」。现在会把**正在运行的那个控制面板
  交给浏览器打开**；静默模式（开机自启）仍然安静退出。
- **图标重做** —— 原图是白底卡片、构图偏右下、边缘还留着一条线，缩到小尺寸糊成一团。
  改为去白底、清边框、裁到主体后居中放大，重出 16~256 七档 ICO。
- **产物命名与文档** —— 文件名不再带版本号（固定 `FoxPath.exe`），版本号写进 exe 的版本资源。
- **体检日志带上运行时长** —— 长跑日志里能一眼看出是持续在跑，还是中途死过又重开。

## 用法

1. 下载 `FoxPath.exe`，双击运行
2. 浏览器自动打开控制面板 `http://127.0.0.1:8788/ui`
3. 勾选「开机自启」即可后台常驻

首次启动请等 15~20 秒（要并发体检 49 个候选 IP），体检完成前代理尚未完全生效。

## 已知边界

- 只代理 `github.com` / `www.github.com`；`githubassets.com` / `githubusercontent.com` /
  `api.github.com` 保持直连（走代理反而连不上）
- 控制面板只监听 `127.0.0.1`，但没有鉴权：本机上的其它程序或网页理论上可以调用它的接口
- 不能用 `nohup ... &` 在 shell 里后台启动

## 上一版

- v1.0.1（2026-09-22）修复「还原不了系统代理」一类缺陷
- v1.0.0（2026-09-19）首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原

最后提交信息为： docs: 使用说明与控制面板说明按 v1.0.5 重写（补在线升级卡片）

v1.0.1

2026-09-22 12:42 v1.0.1 0c54847

狐径 FoxPath v1.0.1 — 修复「还原不了系统代理」一类缺陷

## 下载

- `FoxPath-v1.0.1.exe` — 绿色单文件，无需安装，双击即用
  （文件名故意用 ASCII：中文名上传到 GitHub/Gitee 会被改坏）

## 这一版修了什么

起因是一次完整的代码审计，加上一次现场复现。最关键的一条是**退出后系统代理还原不回来**：

- **重复点「启用加速」会把还原备份覆盖掉。** 旧版每次点都重新备份一次，而那时注册表里已经是
  本程序的 PAC 地址 —— 备份里存的就成了「指向自己的 PAC」，之后再点「停用并还原」只是把死地址写回去。
  实测：连续点两次启用后，备份里是 `http://127.0.0.1:8788/pac`（正确应为原始值）。
  **现在已启用状态下不再重复备份。**
- **备份写失败也照样改注册表。** 旧版把备份写在 exe 同级目录，若该目录不可写（Program Files、只读介质），
  写入失败被静默吞掉，退出时无从还原。**现在备份固定放 `%LOCALAPPDATA%\FoxPath\`，
  写不进去就干脆不改系统代理**（宁可不开，也不留下无法还原的状态）。
- **静默模式（开机自启）根本没有注册退出还原。** 这正是「程序关了/删了，`AutoConfigURL` 却还指着
  127.0.0.1:8788」的根因。**现在两种模式都注册退出还原。**
- **新增 `--restore`**：即使备份没了、exe 也删了，也能一条命令把残留的 PAC 设置清干净。
- **新增单实例保护**：以前重复双击会起两个进程去抢 8787/8788（Windows 的 `SO_REUSEADDR` 允许抢占同一端口，
  行为未定义）。现在用命名互斥保证只有一个实例。
- **端口被占用不再静默崩溃**：会说明是哪个端口、并提示怎么处理。
- **日志落文件**：exe 是无窗口的，以前出错屏幕上什么都看不到。现在写
  `%LOCALAPPDATA%\FoxPathoxpath.log`（超过 512 KB 自动只留最近 500 行）。
- **PAC 自检**：启动时校验 PAC 模板必须是纯 ASCII —— 历史上这里混进中文会让 `/pac` 返回 500，
  浏览器拿不到 PAC，症状是「网页能开但按钮点不动」，极难定位。
- **版本号只有一个来源**（`github_direct.py` 的 `APP_VERSION`），不再在面板和打包脚本里各写一份。

## 顺带修掉的

- **`Fix-GitHub.ps1` 以前根本跑不起来**：文件是 UTF-8 无 BOM，PowerShell 5.1 按 ANSI 读，
  中文变乱码后字符串与花括号被破坏，直接 ParserError（实测 3 个语法错误；补上 BOM 后为 0）。
  它是**旧版备用方案**（改 hosts + 装计划任务，需要管理员），与主程序二选一。
- **文档与实现不一致**：`使用说明.txt` 曾写 PAC 会代理 `githubusercontent.com` / `githubassets.com`，
  而代码和 README 都明确说这两个域名要走直连、走代理反而坏；下载处的文件名也与实际发布附件不符。
- **`build_exe.py`** 改为从源码读版本号、产出 ASCII 名 `FoxPath-v<版本>.exe`；去掉用不到的 `--hidden-import PIL`。
- **`publish_files.py`** 以前只能首次上传（更新已存在的文件会因缺少 `sha` 返回 422），现在会先取远端 `sha`。

## 用法

1. 下载 exe，双击运行
2. 浏览器自动打开控制面板 `http://127.0.0.1:8788/ui`
3. 勾选「开机自启」即可后台常驻

首次启动请等 15~20 秒（要并发体检 49 个候选 IP），体检完成前代理尚未完全生效。

## 已知边界

- 只代理 `github.com` / `www.github.com`；`githubassets.com` / `githubusercontent.com` / `api.github.com`
  保持直连（走代理反而连不上，会让页面只剩裸 HTML、按钮点不动）
- 不能用 `nohup ... &` 在 shell 里后台启动，那样命令结束进程会被终止
- 控制面板只监听 `127.0.0.1`，但没有鉴权：本机上的其它程序或网页理论上可以调用它的接口
  （本地回环，风险很低；如果你在意，下一版可以加一个启动时随机生成的访问令牌）

## 上一版

- v1.0.0（2026-09-19）首个版本：本地代理 + PAC、每 5 分钟 IP 体检、候选池自动刷新、全灭自愈、退出还原

反馈：75219857 @qq.com

最后提交信息为： release: v1.0.1 修复'退出后系统代理还原不回来'等 23 组缺陷

release_1155348

2026-09-20 14:29 v1.0.0 969dc11

最后提交信息为： FoxPath v1.0.0: GitHub 直连助手首个版本

海风 / FoxPath .gitee-modal { width: 500px !important; }

搜索帮助

海风 / FoxPath