Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

github-hosts

定时探测 GitHub 边缘 IP,把已验证可用的结果写入本地 hosts.txt,HTTP 接口直接读取该文件返回。Rust 实现,单容器运行。

工作原理

探测(每 900 秒)→ 验证内容 → 原子写入 data/hosts.txt + data/snapshot.json
                                        ↓
                              GET /hosts 直接读文件返回

三个关键性质:

  1. 接口读文件,不读内存。 GET /hosts 返回的就是磁盘上的 hosts.txt,逐字节一致。你可以把它当普通文件同步、备份、或用任何工具检查。
  2. 原子写入。 先写 .tmp 再 rename,读取方永远看到完整的旧文件或完整的新文件,不会读到半截内容。
  3. 重启即用。 启动时回读 snapshot.json,重启后 /hosts 立刻可用,不用等第一轮探测跑完。

访问频率有硬下限:INTERVAL_SECS 低于 600 会被钳制到 600,防止配置笔误把服务变成请求洪水。默认 900 秒,并在调度中加 ±10% 抖动,避免多实例同时开火。

为什么必须验证内容,而不是"这个 IP 通不通"

只看"IP 通不通"不够:有的边缘 TCP 通、TLS 也通,却只回 400,延迟还比真正能服务网页的边缘更低。所以每个域名必须通过真实内容校验:

验证项 判据 对应的用户体验
github.com/ HTTP 200 + 真实 HTML(含 <html、github、≥3KB) 页面能打开
github.githubassets.com 200 + css/js/图片 content-type 页面不是白底无样式
页面里真实引用的 css/js 从首页 HTML 里抓出资产 URL 再取一次 样式和脚本真的能加载
raw.githubusercontent.com 200 + 精确文件内容(Hello World) Raw 与下载按钮可用
avatars.githubusercontent.com 200 + PNG/JPEG 魔数 头像显示
codeload.github.com 完整 tar.gz → gunzip → tar 解析 → 成员数 ≥1 "Download ZIP" 可用
release-assets.githubusercontent.com 真实 release asset 经 302 签名地址下载并校验内容 release 附件下载可用
api.github.com/zen 200 + 非空 JSON API 调用正常
github.com/...info/refs?service=git-upload-pack 真实的 upload-pack advertisement(约 265KB,用加长超时) git clone/pull 可用
objects / media / camo / user-images 任一 HTTP 响应(真实取内容需签名 URL) 制品、LFS、README 图片

两个实测踩过的坑,代码里都留了注释:

  • codeload 的 301 不是成功。 很多边缘对 tar.gz 回 301 到 https://github.com/<repo>/tar.gz/...,而那个地址实测是 404。把 301 当通过会给出一个"下载 ZIP 必然失败"的 IP。
  • 每个域名自己的 DNS 答案优先验证。 codeload 的真实边缘是 20.205.243.165,它不在官方 /32 名单里,按 github.com 的延迟排名永远排不进候选,导致"下载 ZIP"总也通不过。

快速开始

cd github-hosts
docker compose up -d
curl -s http://127.0.0.1:8080/hosts

Podman on Windows:-p 8080:8080 只绑在 WSL 虚拟机的地址上,127.0.0.1:8080 连不上。用 podman machine ssh "ip -4 addr show eth0" 拿到 VM IP 后访问。

接口返回(可直接粘进 hosts 文件):

# >>> github-hosts :: 2026-11-13T10:09:17+08:00 :: mode=pin :: v1.2.0 >>>
# Generated by github-hosts. Do not edit inside this block.
# endpoints 13/14 verified | git ok | cycle 3 | probe 31204ms
20.207.73.82     github.com                                 #    861ms
185.199.109.215  github.githubassets.com                    #    203ms
20.205.243.168   api.github.com                             #    212ms
185.199.110.133  raw.githubusercontent.com                  #    376ms
185.199.110.133  avatars.githubusercontent.com              #    196ms
20.6.7.16        codeload.github.com                        #    406ms
...
# unverified (falls back to system DNS): gist.github.com
# <<< github-hosts <<<

接口

方法 路径 说明
GET / 状态页:浏览器得 HTML,curl 得纯文本(30 秒自动刷新)
GET /hosts 直接读 hosts.txt 文件返回,带 ETag,支持 If-None-Match → 304
GET /hosts?mode=auto 只固定"系统 DNS 给的 IP 与实际验证不符"的域名(从 JSON 现渲染)
GET /hosts?families=web,raw 只要指定分组(web / api / raw / assets / pages)
GET /v1/snapshot 完整探测详情 JSON(读 snapshot.json)
POST /v1/refresh 立即触发一轮探测,返回 202
GET /healthz 数据质量:必需项/git 未通过,或快照超过 3 个周期没更新(stale)时返回 503;JSON 带 age_secs、stale、unverified 和每域名的 unverified_cycles
GET /livez 存活检查,只要进程在服务就 200(容器 HEALTHCHECK 用这个)

设计上的三个承诺:

  1. 不下发空文件。 一轮什么都没验通(FAMILIES 配错、整网被封)时不覆盖磁盘,/hosts 继续给上一份完整结果,状态页同时显示"数据陈旧"。
  2. 不保留过期数据。 每一轮都覆盖上一轮:本轮没验通的域名不会继续留着上轮的 IP,它从 block 里消失并回落到系统 DNS。留下的旧 IP 只是"曾经通过",等于把过期数据当成已验证结果下发。连续失败的轮数会显示出来(状态页 gist.github.com (连续 5 轮)),所以"一直失败"看得见,而不是被一条陈旧记录掩掉。
  3. 不抖动。 上一轮选中的 IP 只要还活着就继续用(粘性),即使有更快的也不换 —— 换 IP 会打断在途连接。

判定"两轮之间"只用于报告(lost_hosts → 日志 cycle N lost 3 host(s) the previous cycle had: ...),不用于门禁: 以前的做法是新一轮排名低于旧结果就整轮丢弃,结果是网络里只要有一个可选域名长期不通,快照就再也不更新,而磁盘上一直留着那台已经验证不通的 IP。

两个实现细节:

  • 被 FAMILIES 关掉的分组记在 snapshot.json 的 suppressed 里(#[serde(default)],旧文件照常读),不算失败、不进 unverified_cycles,也不出现在 lost 日志里 —— 改配置不等于域名挂了。
  • unverified_cycles 只存在内存,重启后归零;snapshot.json 里的 generated_at 才是"多久没更新"的权威依据(状态页和 /healthz 都用它)。

落盘文件

路径 内容
${STATE_DIR}/commit.json 提交点:记录本轮 cycle、渲染 mode、hosts.txt 的哈希
${STATE_DIR}/hosts.txt 渲染好的 block,/hosts 直接返回它
${STATE_DIR}/snapshot.json 结构化结果,用于派生视图、状态页、重启恢复

STATE_DIR 默认 data(容器内 /data)。容器里挂了 named volume,重建容器不会丢;不挂卷每次重建都要冷启动等一轮。

为什么多了一个 commit.json

两个文件无法原子地一起替换。先后写会留下一个窗口:hosts.txt 已是新 cycle 而 snapshot.json 还是旧的(或反之),此时 /hosts 和 /v1/snapshot 会给出不同的答案;若第二次写失败,这个不一致会一直持续到下一轮成功。

所以数据文件先写、commit.json 最后写。它记录 cycle、mode 和 hosts.txt 的哈希,读取方只信任与它一致的数据文件:

  • /hosts 与 /v1/snapshot 都由同一个 authoritative() 决策,不可能互相矛盾
  • hosts.txt 被外部改动(哈希不符)→ 判定磁盘状态失效,改用内存版本
  • snapshot.json 的 cycle 与 commit 不符 → 同样拒绝

落盘失败为什么安全

因为 commit 是提交点,写失败时旧 commit 仍在,而内存里持有更新的好结果。authoritative() 见到 persisted == false 就直接用内存,不读盘——这正是"只读卷仍能继续服务"的实现方式。

  • 单文件写入是原子的:.tmp(带 pid 防多实例互踩)+ rename + sync_all
  • Unix 上 rename 后额外 fsync 父目录,否则掉电可能丢失已报告的 rename
  • 文件损坏不会导致启动失败,只会忽略并重新探测

配置

变量 默认 说明
PORT 8080 监听端口
INTERVAL_SECS 900 探测间隔,低于 600 会被钳制到 600
STATE_DIR data / /data 落盘目录
PROBE_TIMEOUT_SECS 6 单次连接超时。短一点,让黑洞 IP 尽快被放弃
CONCURRENCY 12 并发探测数
MAX_SCAN 40 每个分组最多筛多少个候选 IP
TOP_K 12 每个域名最多验证几个候选
REPEATS 2 传输失败的重试次数(内容不符不重试)
FAMILIES 全部 只探测指定分组,如 web,raw
HOSTS_MODE pin 默认输出模式
RUST_LOG info 日志级别

不使用 Docker

cargo build --release
./target/release/github-hosts --once     # 探测一次、落盘、打印后退出(日志走 stderr)
./target/release/github-hosts            # 常驻 + HTTP 接口

--once 适合放进计划任务,自己写文件。但不要和常驻进程共用同一个 STATE_DIR:两者没有互斥,一个在坏窗口的 --once 会覆盖另一个的好快照(运行期接口不会分叉,因为 authoritative() 优先用内存,但重启后磁盘上那份差的就是真的了)。

镜像

v* 标签推送时 GitHub Actions 自动构建并推送到 GHCR,多架构(amd64 + arm64):

docker pull ghcr.io/wwbgo/github-hosts:latest
docker pull ghcr.io/wwbgo/github-hosts:1.2.0

CI 在打包前会跑 cargo fmt --check、cargo clippy -D warnings、cargo test,任一失败都不产镜像。

局限

  • hosts 一个域名只能映射一个 IP。封禁轮换时最多有一个探测间隔的延迟。
  • gist.github.com、以及所有 SNI 层被阻断的域名,换 IP 无效,工具会标 unverified。
  • 部分 Azure 边缘(48.202.x、20.175.x 等)出现在官方 web 名单里,但对 codeload 只回 301,会被正确拒绝。
  • 某分组整体被封锁时,一轮探测会拉长到 80 秒左右(每个候选都要吃满超时),由每域名 25 秒预算兜住。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages