GitPort GitHub v0.4.0

GitPort GitHub v0.4.0 —— 页面缓存完整架构 · 镜像工作区 · 两轮全仓审计

v0.3.0（2026-10-19 发布）之后 71 个提交。连接复用 2.0、前端遥测拦截、隧道握手分片等 v0.3.0 说明已述的内容本版持续演进，不在此重复；以下为全部新增主题。

资产随代码更新（仍为 v0.4.0）：搜索/列表页 5 分钟短 TTL、注释精简、README 动机叙事均已包含在本次构建内。

一、页面缓存完整架构（本版最大主题，从零建成）

v0.3.0 时页面缓存刚被移除（“浏览器原生缓存是更正确的层”的结论被实测推翻后重建）。本版建成完整体系：

• 命中即秒回：GitHub 三个站（主站 / gist / raw）的“打开网页正文”请求，本地有存且没过保质期就直接回，对 GitHub 零请求
• 保质期按站分治：主站 24 小时（HTML 文档实证 97% 是框架壳子，可见文本仅占 3%，动态数据走 XHR 实时拉）/ gist 30 分钟 / raw 文件 10 分钟
• 动态页短保质期：搜索、issue / PR / 提交 / 发布列表、通知、动态流、探索页，以及任何带 query 参数的页面，只缓存 5 分钟——搜索结果会变，过时比慢更伤信任（用户反复刷新重搜，反而多打 GitHub）；主站其余框架页仍 24 小时
• 两层分工不重叠：静态资源（JS/CSS/图片）归浏览器缓存，代理只接网页正文——代理补的正是浏览器“存了不敢用”（GitHub 响应头逼其每次重新验证）的那层
• 自研单文件存储：弃 cacache——内容寻址去重 / 完整性校验 / 双树索引在单用户页面缓存场景零收益，却带来每次写入全表扫描的常驻成本。现在一页一文件（4 字节头长 + 说明区 + 正文）、临时文件改名原子落盘（永远存不出半页）、文件名散列读时对账（防串页）
• 容量三档：增量记账（累计写 8MB 才查一次）/ 软顶 200MB 按最后使用时间淘汰最旧 / 硬顶 250MB 整个清空重来——网页缓存而已，清了重拉
• 新鲜度模型：保质期绝对时钟（命中不续期）+ 写后即删（发帖 / 改设置成功，同路径缓存立即失效）+ F5 出口（强制刷新故意绕过缓存直连上游，随时能看最新）
• SWR / 后台 ETag 验证明确否决：_gh_sess 每请求轮换，后台验证只能带上一时刻的旧 cookie，GitHub 侧将废弃会话重用判定为账号泄露——这是红线
• 安全边界全套：登录 / 登出 / 会话页排除（防锁死登录、防假登出）；登录态二态指纹分键（user_session 值轮换不打散缓存）；会话死亡防护（带登录凭证却拿到未登录页，不存不当命中）；下发 cookie 永不入缓存；缓存目录 ACL 仅当前用户与 SYSTEM 可读
• 删内存热点表：系统 Page Cache 兜底下缓存读盘 <1ms（上游请求 100–500ms 级），自建 8MB 内存表 + 锁 + 淘汰逻辑不划算
• 演进史可追：cacache 管理 → 管家线程 + 孤儿回收 → 写盘后台化 → 写失效 → 缓存全量化（通知页 / 仪表盘首页 / 设置页纳入）→ SWR 三度反复后定案时钟路由 → 单文件存储 → 动态页短 TTL

二、自定义镜像独立工作区（全新）

• 设置页 Worker 面板完整结构：地址 + 开关双键语义，增 / 删 / 停用逐条管理，列表实时反映链成员
• 注册表模型：自定义镜像与内置镜像链彻底分离——注入改链尾追加（不再插头部打乱校准序），注册表顺序 = 添加先后
• 收编机制：手改 plans.json 塞进来的自建镜像，重启自动进注册表可见可管（幂等）
• 新增 Cloudflare 自建节点教程（全域名名单 + follow 修复的完整原文）
• 修面板列表清空 bug；seeds 去内置镜像链（纯数据驱动，免责设计）；README 补镜像站致谢与自建倡议

三、网络层增量

• TLS 会话恢复：重拨注入 session ticket 走 1-RTT PSK，不再重传验整条证书链
• api.mcp.github.com 挪出 core 池进直连白名单：证书 SAN 不覆盖致 27 连败全灭
• 镜像腿统一浏览器 UA
• 文档对齐：双连接 / EWMA / 遥测拦截 / mcp 白名单补进 README

四、两轮全仓审计修复（23 项）

第一轮（10 项）：TTL 与 Touch 时钟分离、写防污染、管家线程 panic 护栏、写盘 fsync、测试补全
第二轮（13 项）：

安全与正确性：

• WebUI 镜像 URL HTML 注入：转义函数五个危险字符全部处理
• 风控拦截页（403/400）被缓存：只收成功响应，旧脏条目读时自愈
• 304 空体响应被缓存回放：同一白名单解决
• 全新安装镜像链为空导致下载 502：空链自动回落直连串发
• settings.json 保存竞态丢更新：全程互斥锁
• plans.json 单池写坏整表重建：容错解析，哪段坏只丢哪段，原文件备份 .bak
• 剪贴板写入失败泄漏全局堆块：两个失败分支都补释放
• 非 Windows 死代码桩：删除

性能与语义：

• 写失效阻塞 POST 响应路径：拆成内存同步清 + 磁盘异步删
• 首圈串发最坏数分钟无预算：20 秒耗时预算，到期快速失败
• 熔断表只进不出：过期条目惰性清除 + 4096 硬顶
• 明文 HTTP 漏过滤逐跳头：按头名切分，与 MITM 路径同款名单

五、WebUI 与交互变化

• 砍掉 IP 池页（IP 死活全凭串发实测，代码零 IP 名单，面板无信息量）
• MITM 断开噪音不显示；侧栏收窄
• Worker 面板见主题二

六、代码健康与文档

• mitm.rs 拆分为 mitm/ 模块文件夹（按职责分四个文件）
• 注释精简：模块头 37 行压到 10 行，全仓注释净删近百行——决策只留一处，历史叙事去掉，安全红线与踩坑记录保留
• 删 WebSocket 升级支持（确认无使用场景）；删 ourPAC / ProxyGuard / CountingBody / image 依赖；熔断器去 6 个纯转发函数；权限收紧走 icacls；删自建系统调用与重复包装层；settings 单一解析路径
• seeds.json 同步为 plans.json 全量快照（池 27/6/22 + 镜像链 9×6）
• 退出 / 收托盘即清 WebView2 数据目录，启动兜底——绿色零残留
• README 新增「它为什么对 GitHub 友好」（遥测拦截 / 强制 gzip / 页面缓存 / 数据层验活）与「选哪个镜像」（只给作者实测最慢的一个）两节
• 全轮净变化：+751 / −797 行（砍的比加的多）

七、测试

自动化测试 46 → 59 个（新增：plans 容错、熔断惰性清除、per-host TTL、动态页短 TTL、正文类型闸门、单文件存储覆盖写 / 截断自愈 / 防串页、明文 hop-by-hop 剥除等）

升级注意

• 单文件直接替换旧版即可；首次启动自动清理旧版 cacache 格式缓存（.cache 里的旧数据作废重拉，属预期）
• 页面缓存随 MITM 开关走：不开 MITM 则无缓存（与旧版一致）
• plans.json 格式未变；单池写坏不再连坐整表，坏段可从 plans.json.bak 捡回
• 自定义镜像若此前手改在 plans.json 里，重启后自动收编进 Worker 面板管理

下载：Assets 里的 gitport-github.exe（9.33MB，md5 bc6c3341c529b9575fae5df220e0d944，2026-10-24 构建）。