定时探测 GitHub 边缘 IP,把已验证可用的结果写入本地 hosts.txt,HTTP 接口直接读取该文件返回。Rust 实现,单容器运行。
探测(每 900 秒)→ 验证内容 → 原子写入 data/hosts.txt + data/snapshot.json
↓
GET /hosts 直接读文件返回
三个关键性质:
- 接口读文件,不读内存。
GET /hosts返回的就是磁盘上的hosts.txt,逐字节一致。你可以把它当普通文件同步、备份、或用任何工具检查。 - 原子写入。 先写
.tmp再 rename,读取方永远看到完整的旧文件或完整的新文件,不会读到半截内容。 - 重启即用。 启动时回读
snapshot.json,重启后/hosts立刻可用,不用等第一轮探测跑完。
访问频率有硬下限:INTERVAL_SECS 低于 600 会被钳制到 600,防止配置笔误把服务变成请求洪水。默认 900 秒,并在调度中加 ±10% 抖动,避免多实例同时开火。
只看"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/hostsPodman 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 用这个) |
设计上的三个承诺:
- 不下发空文件。 一轮什么都没验通(
FAMILIES配错、整网被封)时不覆盖磁盘,/hosts继续给上一份完整结果,状态页同时显示"数据陈旧"。 - 不保留过期数据。 每一轮都覆盖上一轮:本轮没验通的域名不会继续留着上轮的 IP,它从 block 里消失并回落到系统 DNS。留下的旧 IP 只是"曾经通过",等于把过期数据当成已验证结果下发。连续失败的轮数会显示出来(状态页
gist.github.com (连续 5 轮)),所以"一直失败"看得见,而不是被一条陈旧记录掩掉。 - 不抖动。 上一轮选中的 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,重建容器不会丢;不挂卷每次重建都要冷启动等一轮。
两个文件无法原子地一起替换。先后写会留下一个窗口: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 |
日志级别 |
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.0CI 在打包前会跑 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 秒预算兜住。