GitHub-File-Watcher — 轻量级 GitHub 仓库变更与文件监控工具

一个极轻量、低内存占用的纯后台 GitHub 仓库文件级变更监控与主动通知推送服务。

---

核心特性

• 纯 API 驱动：无需在本地 Clone 仓库，完全基于 GitHub REST API（Conditional GET + ETag）。
• 极轻量状态管理：本地仅保存 data/state.json 单文件状态，无需任何外部数据库依赖，运行时内存 < 30MB。
• 双 Cron 解耦：变更检测周期（fetch_cron）与通知发送周期（notify_cron）独立配置，支持 realtime（实时）与 digest（定时汇总）两种推送模式。
• Rate Limit 规避：
  • 支持多 Personal Access Token 负载均衡池，配额耗尽/失效时自动切换降级。
  • 公开仓库支持免 Token 匿名访问。
  • 均匀时间片调度（Staggered Scheduling），将 API 请求打散至整个周期，彻底消除触发频率限制风暴。
• 多渠道主动推送：原生支持 Telegram Bot、Discord Webhook、Slack Webhook、飞书 Webhook（加签）、钉钉 Webhook（加签）以及自定义 HTTP Webhook。
• 通配符过滤与语义标签：支持分支通配符（如 release/*）与递归文件匹配（如 src/**/*.go），并可为匹配的文件附带自定义 Label 注释。

---

快速开始

本地编译运行

# 1. 克隆代码
git clone https://github.com/Myraxion/github-file-watcher.git
cd github-file-watcher

# 2. 准备配置文件与环境变量
cp configs/config.example.yml config.yml
export GITHUB_TOKEN_1="your_personal_access_token"
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

# 3. 编译并运行
go build -o github-file-watcher ./cmd/github-file-watcher
./github-file-watcher -config config.yml

Docker Compose 部署 (推荐)

# 1. 准备配置与环境变量
cp configs/config.example.yml config.yml
cp .env.example .env

# 2. 在 .env 中填入你的 Token / Webhook 密钥，在 config.yml 中配置监控仓库

# 3. 一键启动服务
docker compose up -d

Docker 容器化运行 (命令行)

docker run -d \
  --name github-file-watcher \
  -v $(pwd)/config.yml:/etc/github-file-watcher/config.yml:ro \
  -v $(pwd)/data:/data \
  -e GITHUB_TOKEN_1="your_token" \
  -e TELEGRAM_BOT_TOKEN="your_bot_token" \
  -e TELEGRAM_CHAT_ID="your_chat_id" \
  -p 8080:8080 \
  myraxion/github-file-watcher:latest

---

配置规范 (config.yml)

github:
  tokens:
    - "${GITHUB_TOKEN_1}"
    - "${GITHUB_TOKEN_2}"
  branch_list_cache_ttl: 3600

schedule:
  fetch_cron: "0 */12 * * *"   # 每 12 小时检测一轮
  notify_cron: "0 9 * * *"     # 每天上午 9 点汇总推送
  notify_mode: "digest"        # "realtime" 或 "digest"

repositories:
  - owner: "kubernetes"
    repo: "kubernetes"
    branches:
      - name: "master"
        file_patterns:
          - pattern: "staging/src/k8s.io/api/**/*.go"
            label: "K8s API 核心定义"
          - pattern: "CHANGELOG/*.md"
            label: "版本日志"
      - name: "release-1.28"

notifications:
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    chat_id: "${TELEGRAM_CHAT_ID}"

storage:
  data_dir: "./data"

logging:
  level: "info"

health:
  enabled: true
  port: 8080

---

健康检查

当 health.enabled: true 时，系统暴露极简 HTTP 端点：

$ curl http://localhost:8080/healthz
{"status":"ok","uptime":"2h15m30s"}

---

许可证

MIT License