GitHub-Buddy

GitHub-Buddy 是一个跨平台命令行工具，通过智能维护 GitHub 域名-IP 映射并修改系统 hosts 文件，解决开发者执行 go mod tidy、git clone 等操作时频繁遇到的 GitHub 网络访问问题。

🚫 本工具不是代理/VPN，仅通过优化 DNS 解析（hosts）来改善连接质量。

✨ 功能特性

🔍 智能 IP 检测 — 多维度并发检测（ICMP Ping / TCP 443 / TCP 22），自动评分筛选最优 IP
🌐 全量域名覆盖 — 维护 github.com、raw.githubusercontent.com、api.github.com 等 11 个核心域名
🖥️ 跨平台支持 — 一套代码覆盖 Windows 10+、macOS 12+、主流 Linux 发行版
🔒 安全保障 — 自动备份 hosts 文件，支持一键回滚，SHA256 完整性校验
📦 零依赖分发 — 静态编译的单二进制文件，下载即用
🔄 缓存管理 — 内置缓存过期检测机制，支持手动更新和系统定时任务自动化
🏷️ 隔离管理 — 使用注释标记区块隔离工具修改内容，不干扰用户手动配置

📥 安装

方式一：从源码编译（推荐）

确保已安装 Go 1.21+：

go install github.com/eyjian/github-buddy/cmd/github-buddy@latest

方式二：手动编译

git clone https://github.com/eyjian/github-buddy.git
cd github-buddy
make build

编译产物为当前目录下的 github-buddy 可执行文件。

方式三：下载预编译二进制

前往 Releases 页面，下载对应平台的二进制文件。

🚀 快速开始

1. 初始化

首次使用时运行 init 命令，自动检测最优 IP 并更新 hosts：

# Linux / macOS 需要 sudo
sudo github-buddy init

# Windows（以管理员身份运行命令提示符）
github-buddy init

2. 查看状态

查看当前 hosts 中 GitHub 域名的映射状态和连通性：

github-buddy status

3. 手动更新

强制重新检测并更新 IP（自动备份当前 hosts）：

sudo github-buddy update

4. 回滚

如遇问题，一键恢复到上次备份的 hosts 文件：

sudo github-buddy rollback

📖 命令参考

命令	说明
`github-buddy init`	初始化工具，首次检测最优 IP 并更新 hosts
`github-buddy update`	强制重新检测 IP，备份并更新 hosts
`github-buddy rollback`	从最近的备份恢复 hosts 文件
`github-buddy status`	查看当前域名映射状态和实时连通性

全局参数

参数	说明
`-v, --verbose`	输出详细日志到控制台
`-f, --force`	跳过确认提示，强制执行
`--version`	显示版本信息
`-h, --help`	显示帮助信息

⚙️ 配置说明

工具的配置文件和数据存储在用户主目录下：

~/.github-buddy/
├── config.json     # 配置文件
├── cache/          # IP 检测缓存
├── backups/        # hosts 备份文件
└── logs/           # 运行日志

配置文件示例（`config.json`）

{
  "update_interval_hours": 6,
  "data_sources": [
    {
      "name": "GitHub520",
      "url": "https://raw.hellogithub.qkg1.top/hosts",
      "priority": 1,
      "enabled": true
    },
    {
      "name": "Ineo6",
      "url": "https://gitlab.com/ineo6/hosts/-/raw/master/hosts",
      "priority": 2,
      "enabled": true
    }
  ],
  "domains": [
    "github.com",
    "ssh.github.com",
    "gist.github.com",
    "raw.githubusercontent.com",
    "api.github.com",
    "assets-cdn.github.com",
    "github.global.ssl.fastly.net",
    "collector.github.com",
    "avatars.githubusercontent.com",
    "codeload.github.com"
  ]
}

配置项说明

字段	类型	默认值	说明
`update_interval_hours`	int	`6`	缓存过期判断阈值（小时），详见配置项详解
`data_sources`	array	GitHub520 + Ineo6	IP 数据源列表，支持多源扩展
`domains`	array	11 个域名	需要维护的 GitHub 域名清单

配置生命周期

graph TD
    A["github-buddy init"] -->|首次运行| B["DefaultConfig() 生成默认配置"]
    B --> C["config.Save() 写入 ~/.github-buddy/config.json"]
    C --> D["配置文件持久化"]
    D --> E["github-buddy update / status"]
    E --> F["config.LoadOrDefault() 加载配置"]
    F -->|文件存在且合法| G["解析 JSON 返回用户配置"]
    F -->|文件不存在或解析失败| H["静默回退到内置默认配置"]
    G --> I["使用配置中的参数执行命令"]
    H --> I

`update_interval_hours` 说明

⚠️ 注意：update_interval_hours 不是自动定时更新。工具本身没有后台守护进程或定时器，不会自动执行更新操作。

它的实际作用是 缓存过期判断阈值：当你运行 github-buddy status 时，工具会检查上次更新距今是否超过该阈值，如果超过则提示你手动执行 github-buddy update，但不会自动执行。

如果你需要真正的定时自动更新，请配合系统任务计划使用，参见定时自动更新。

各配置项在命令中的使用

配置项	使用命令	作用说明
`update_interval_hours`	`status`	通过 `UpdateInterval()` 转为时间间隔，判断缓存是否过期，过期时提示用户手动更新（不会自动更新）
`domains`	`update`	用于 `hosts.DetectConflicts()` 检测用户手动写入的 hosts 条目与工具管理的域名是否冲突
`data_sources`	—	配置预留字段，当前版本的 IP 检测器使用内置数据源

如何自定义配置

init 之后，可以直接编辑配置文件：

# 查看当前配置
cat ~/.github-buddy/config.json

# 修改配置（如将更新间隔改为 12 小时）
vi ~/.github-buddy/config.json

修改后无需重新 init，下次运行 update 或 status 命令时自动加载新配置。

⚠️ 如果配置文件被误删或格式损坏，工具会自动回退到内置默认配置，不会报错。

🔧 Hosts 文件管理

工具使用注释标记区块来隔离管理的内容，不会修改标记区块外的任何内容：

# 用户原有的配置不受影响
127.0.0.1  myapp.local

# GitHub-Buddy Auto-Generated Start
# 更新时间: 2024-01-01 12:00:00
140.82.121.3    github.com
185.199.108.133 raw.githubusercontent.com
140.82.121.5    api.github.com
# ... 更多域名映射
# GitHub-Buddy Auto-Generated End

🏗️ 项目结构

github-buddy/
├── cmd/
│   └── github-buddy/          # CLI 入口和命令定义
│       ├── main.go            # 程序入口
│       ├── root.go            # 根命令和全局参数
│       ├── cmd_init.go        # init 命令
│       ├── cmd_update.go      # update 命令
│       ├── cmd_rollback.go    # rollback 命令
│       └── cmd_status.go      # status 命令
├── internal/                  # 内部核心模块
│   ├── detector/              # IP 检测与评分
│   │   ├── detector.go        # 检测调度器
│   │   ├── source.go          # 数据源获取
│   │   ├── ping.go            # ICMP Ping 检测
│   │   ├── tcp.go             # TCP 端口检测
│   │   ├── scorer.go          # 质量评分
│   │   ├── defaults.go        # 兜底 IP 列表
│   │   └── types.go           # 数据类型定义
│   ├── hosts/                 # Hosts 文件管理
│   │   ├── reader.go          # 读取解析
│   │   ├── writer.go          # 写入更新
│   │   ├── block.go           # 标记区块管理
│   │   └── conflict.go        # 冲突检测
│   ├── backup/                # 备份与回滚
│   │   └── backup.go          # 备份/恢复/校验
│   ├── cache/                 # IP 缓存管理
│   │   └── cache.go           # 缓存读写和过期检查
│   ├── config/                # 配置管理
│   │   └── config.go          # 配置加载/保存/默认值
│   ├── logger/                # 日志系统
│   │   └── logger.go          # zerolog + lumberjack
│   ├── platform/              # 平台抽象层
│   │   └── platform.go        # OS 检测和路径适配
│   └── storage/               # 存储管理
│       └── storage.go         # 目录结构管理
├── Makefile                   # 构建脚本
├── go.mod                     # Go Module 依赖
└── go.sum                     # 依赖校验

🔨 构建指南

构建当前平台

make build

交叉编译全平台

make build-all

编译产物输出到 dist/ 目录：

dist/
├── github-buddy-linux-amd64
├── github-buddy-linux-arm64
├── github-buddy-darwin-amd64
├── github-buddy-darwin-arm64
└── github-buddy-windows-amd64.exe

运行测试

# 详细输出
make test

# 简洁输出
make test-short

代码检查

make lint

CI/CD 自动化

项目使用 GitHub Actions + GoReleaser 实现自动测试和跨平台发布。详见 CI/CD 使用指南。

⏰ 定时自动更新（可选）

工具本身不包含后台守护进程，如需定时自动更新 hosts，推荐使用操作系统自带的任务计划功能：

Linux / macOS（crontab）

# 编辑当前用户的 crontab
sudo crontab -e

# 每 6 小时自动更新一次（与默认 update_interval_hours 对应）
0 */6 * * * /usr/local/bin/github-buddy update --force >> /tmp/github-buddy-cron.log 2>&1

💡 请将 /usr/local/bin/github-buddy 替换为实际安装路径（可通过 which github-buddy 查看）。需要使用 sudo crontab -e（root 的 crontab），因为修改 hosts 文件需要管理员权限。

Windows（任务计划程序）

打开"任务计划程序"（搜索 taskschd.msc）
点击"创建基本任务"
设置触发器为"每天"，并在高级设置中勾选"重复任务间隔"为 6 小时
操作选择"启动程序"，填入 github-buddy.exe 的完整路径，参数填 update --force

⚠️ 创建任务时，请勾选"使用最高权限运行"，否则无法修改 hosts 文件。

❓ 常见问题

更新 hosts 后浏览器访问 GitHub 仍然不通？

修改 hosts 文件后，浏览器（尤其是 Chrome）可能不会立即使用新的 IP，这是因为浏览器有独立的 DNS 缓存机制。

方法一：清除 Chrome 内置缓存（无需重启浏览器）

清除 DNS 缓存：在地址栏输入 chrome://net-internals/#dns，点击 "Clear host cache"
清除连接池：在地址栏输入 chrome://net-internals/#sockets，点击 "Flush socket pools"（Chrome 会复用已建立的 TCP/TLS 连接，不清除连接池可能仍在使用旧 IP）

方法二：重启浏览器

直接关闭并重新打开 Chrome，这是最简单粗暴但有效的方式。

方法三：同时清除系统 DNS 缓存（推荐配合使用）

# Linux (systemd)
sudo systemd-resolve --flush-caches
# 或
sudo resolvectl flush-caches

# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

# Windows
ipconfig /flushdns

💡 推荐操作顺序：执行 github-buddy update → 清除系统 DNS 缓存 → 清除 Chrome DNS 缓存 + Flush sockets

🛡️ 安全说明

权限要求：修改 hosts 文件需要管理员/root 权限，工具会自动检测并给出提权指引
自动备份：每次修改 hosts 前自动创建带时间戳的备份文件，存储于 ~/.github-buddy/backups/
完整性校验：备份文件使用 SHA256 校验，回滚时自动验证文件完整性
隔离修改：仅修改标记区块内的内容，绝不触碰用户手动配置的 hosts 条目
兜底机制：内置默认 IP 列表，即使所有数据源不可达也能正常工作

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建功能分支：git checkout -b feature/your-feature
提交改动：git commit -m "feat: 添加某功能"
推送分支：git push origin feature/your-feature
创建 Pull Request

开发环境

Go 1.21+
Make（可选，用于构建脚本）

代码规范

使用 gofmt 格式化代码
使用 go vet 进行静态检查
新功能需附带单元测试

📋 技术栈

组件	技术选型	说明
编程语言	Go	交叉编译、静态链接、goroutine 并发
CLI 框架	cobra	子命令、自动帮助文档、shell 补全
日志框架	zerolog	零分配、结构化日志
日志轮转	lumberjack	日志文件自动轮转和压缩
网络检测	Go 标准库 `net`	TCP 端口检测、HTTP 请求
构建工具	Make + Goreleaser	交叉编译和自动化发布

📄 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

GitHub520 — 提供 GitHub 域名 IP 数据源
Ineo6 Hosts — 提供 GitHub 域名 IP 数据源
cobra — 优秀的 Go CLI 框架
zerolog — 高性能结构化日志库
lumberjack — 日志文件自动轮转和压缩
GoReleaser — 自动化发布工具

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
cmd/github-buddy		cmd/github-buddy
doc		doc
internal		internal
openspec		openspec
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

GitHub-Buddy

✨ 功能特性

📥 安装

方式一：从源码编译（推荐）

方式二：手动编译

方式三：下载预编译二进制

🚀 快速开始

1. 初始化

2. 查看状态

3. 手动更新

4. 回滚

📖 命令参考

全局参数

⚙️ 配置说明

配置文件示例（config.json）

配置项说明

配置生命周期

update_interval_hours 说明

各配置项在命令中的使用

如何自定义配置

🔧 Hosts 文件管理

🏗️ 项目结构

🔨 构建指南

构建当前平台

交叉编译全平台

运行测试

代码检查

CI/CD 自动化

⏰ 定时自动更新（可选）

Linux / macOS（crontab）

Windows（任务计划程序）

❓ 常见问题

更新 hosts 后浏览器访问 GitHub 仍然不通？

方法一：清除 Chrome 内置缓存（无需重启浏览器）

方法二：重启浏览器

方法三：同时清除系统 DNS 缓存（推荐配合使用）

🛡️ 安全说明

🤝 贡献指南

开发环境

代码规范

📋 技术栈

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

配置文件示例（`config.json`）

`update_interval_hours` 说明

Packages