easy-keepalive-github

GitHub 直连保活工具（Windows / Node.js）。GitHub 在国内访问不稳定，经常出现"hosts 里的 IP 突然连不通"。本工具由 Windows 计划任务驱动，每 1 分钟后台检测一次 github.com 连通性，发现当前 IP 不可达时持续循环重试、必须找到一个可用候选 IP 才切换，更新 hosts 并刷新 DNS。候选 IP 池自进化：自动用多个公共 DNS 查询 GitHub 官方 A 记录并实测入池，无需人工维护。全程 node.exe 以 SYSTEM 身份后台运行，无弹窗、无感。

说明：本工具是直连 IP 调优（GitHub 本身未被完全封锁，仅间歇性不稳），不涉及代理/翻墙。

安装（一条命令）

npx @zicolasjac-ai/easy-keepalive-github install

普通终端直接跑即可：非管理员会自动弹 UAC 请求提权（务必点"是"），点完后在新开的管理员窗口里自动完成——装包、部署脚本到 C:\ProgramData\GitHubKeepalive\、创建 SYSTEM 计划任务、自动验证，最后等待回车关闭。

⚠️ 容易踩的坑：UAC 弹窗点了"否"的话部署不会发生——计划任务每分钟照常触发，但找不到脚本，出现"hosts IP 永远不切换"的假象。重跑命令并在 UAC 点"是"即可。

成功输出（自动验证任务）：

[OK] 已同步部署: ...\src\keepalive.js -> C:\ProgramData\GitHubKeepalive\keepalive.js
[OK] 计划任务 GitHubKeepAlive 已就绪
[验证]
     身份:    SYSTEM
     命令:    C:\nvm4w\nodejs\node.exe
     参数:    "C:\ProgramData\GitHubKeepalive\keepalive.js"
     触发器:  BootTrigger + TimeTrigger(PT1M)

手动触发测试: schtasks /Run /TN GitHubKeepAlive
查看日志:    Get-Content C:\ProgramData\GitHubKeepalive\logs\keepalive.log

失败诊断速查

| 现象 | 原因 / 处理 | |---|---| | UAC 弹窗后什么都没发生 | 用户点了"否"；重跑命令 | | [失败] 请以管理员身份运行本脚本 | UAC 被禁用或脚本执行策略限制；右键 PowerShell 以管理员身份跑 | | schtasks /Query 能看到任务但 C:\ProgramData\GitHubKeepalive\ 是空的 | 部署失败，重跑 install | | 任务每分钟触发但 hosts IP 不变、日志文件根本没生成 | 脚本未部署，重跑 install |

工作原理

计划任务 GitHubKeepAlive (SYSTEM, 每1分钟)
        │ node.exe 无窗口运行
        ▼
keepalive.js
  1. 读取 hosts 中 github.com 当前 IP
  2. socket+TLS 直连该 IP (SNI=github.com, 证书校验, https://github.com 返回 200 = 可用)
  3. 可用 → 静默退出 (不写日志)
     不可用 → 循环重试 (每轮全量测试候选池)
              → 找到第一个可用者 → 同步写入 hosts 中所有 GitHub 相关行
              → ipconfig /flushdns → 记录 SWITCH → 退出
              → 一轮全不通 → 记 WARN(仅首轮) → 3 秒后重试, 直到找到为止
  4. 重试期间当前 IP 若自行恢复 → 记 INFO 退出 (不瞎切换)
  5. 每 3 轮刷新候选池: GitHub 官方 meta API + 多公共 DNS 查询 + 实测筛选
     → 持久化 C:\ProgramData\GitHubKeepalive\candidates.pool.json

• 自进化 IP 池：GitHub 官方 meta API + 多 DNS 查询 + 实测筛选，动态获取；GitHub 加新 IP 段自动跟进；用户 candidates.json（可选）作为补充；种子 IP 仅作冷启动最低保障
• 单实例保护：C:\ProgramData\GitHubKeepalive\keepalive.lock 锁文件防止任务并行（锁时间戳每轮刷新；进程崩溃残留超 2 分钟后，下一个触发点自动接管）
• 重试无上限：整段封锁时任务会一直持有并重试（锁挡掉后续触发），放行后自动完成切换

使用

1. 验证是否在运行

# 手动触发一次，然后查看日志
schtasks /Run /TN GitHubKeepAlive
Start-Sleep 30   # 最坏情况 7 个候选 × 6 秒超时
Get-Content C:\ProgramData\GitHubKeepalive\logs\keepalive.log -Encoding UTF8

• 正常（当前 IP 可用）：没有新日志行（设计如此，正常时静默）
• 切换了 IP：出现 SWITCH 行
• 封锁时段：出现 WARN 候选 IP 均不可达, 持续重试中...（仅一次，随后每 3 秒自动重试直到找到）

日志示例：

2026-08-14 14:34:01 SWITCH github.com 192.0.2.1 -> 140.82.112.4 (hosts 已更新, DNS 已刷新)
2026-08-14 13:56:42 WARN 候选 IP 均不可达, 持续重试中...

2. 查看当前生效 IP

Select-String "github.com" C:\Windows\System32\drivers\etc\hosts

3. 常用操作

| 操作 | 命令 | |---|---| | 手动触发一次 | easy-keepalive-github run 或 schtasks /Run /TN GitHubKeepAlive | | 查看任务 | schtasks /Query /TN GitHubKeepAlive /V /FO LIST | | 卸载 | easy-keepalive-github uninstall 或 schtasks /Delete /TN GitHubKeepAlive /F | | 改检测间隔 | 重跑 easy-keepalive-github install（把 scripts\install.js 中的 PT1M 改为其他间隔） |

配置维护：候选 IP

大多数情况下无需维护——运行时 IP 池动态从以下来源获取并实测筛选：

1. GitHub 官方 meta API https://api.github.com/meta：拉取 GitHub 官方 IP 段（hooks/web/api/git/packages/importer/pages 等 CIDR），每段采样 8 个 IP，缓存 1 小时
2. 多公共 DNS 查询：1.1.1.1 / 8.8.8.8 / 8.8.4.4 / 9.9.9.9 / 223.5.5.5 / 119.29.29.29 / 114.114.114.114 / 180.76.76.76 并行查 github.com 的 A 记录
3. 本地候选：candidates.json（自定义 IP）+ 旧池 + 种子 IP，与线上来源合并后一起实测，保证手动维护的 IP 永不被刷掉
4. 实测筛选：所有候选 IP 经 testIP（TCP+TLS+HTTP 200）严格验证、8 路并发测试后才入池

C:\ProgramData\GitHubKeepalive\candidates.pool.json 是最近一次跑出来的可用池，下一次启动会优先采用。

可选：自定义补充候选 IP

如果你想手动加 IP（比如已知稳定但 meta API 还没收录的边缘 IP），编辑 C:\ProgramData\GitHubKeepalive\candidates.json：

{
  "github.com": [
    "你的 IP 1",
    "你的 IP 2"
  ]
}

注意：从此版本起 easy-keepalive-github install 不会覆盖已存在的 candidates.json，你的修改会被保留。如需恢复默认，删除该文件后重跑 install。

一个 IP 是否可用，用手动命令判定：

curl --resolve github.com:443:<IP> --connect-timeout 4 --max-time 6 https://github.com
# 返回 HTTP 200 即可用

失效的 IP 直接从 candidates.json 删掉（也可不动，下次 refreshPool 不会重新收录已被实测踢掉的 IP）。

环境要求

• Windows 10/11 + Node.js 14+（node.exe 用于后台运行；脚本只依赖标准库，零第三方依赖）

注意事项

• 本工具会修改 C:\Windows\System32\drivers\etc\hosts（同步替换所有 GitHub 相关行：github.com / www.github.com / api.github.com / codeload.github.com / raw.githubusercontent.com / raw.github.com / objects.githubusercontent.com；统一指向当前可用 IP，其余保留）
• 首次安装前建议备份 hosts：copy C:\Windows\System32\drivers\etc\hosts hosts.bak
• 日志由脚本自动写入 C:\ProgramData\GitHubKeepalive\logs\keepalive.log（SYSTEM 权限可写，自动创建）
• 文件编码要求（重要，改文件后务必保持）：全部为 UTF-8 无 BOM（中文注释/路径均正常）
• 若封锁为整段（所有候选均不通），工具持续重试直至找到可用 IP，放行后自动恢复

开发

git clone https://github.com/ZicolasJac/easy-keepalive-github.git
node src/keepalive.js          # 直接跑一次核心逻辑
node scripts/install.js        # 管理员: 安装计划任务

许可证

MIT