Skip to content

quickstart.md

Latest commit

 

History

History
147 lines (102 loc) · 7.94 KB

quickstart.md

File metadata and controls

147 lines (102 loc) · 7.94 KB
Raw

快速开始

镜像包含不可变的默认配置，并默认启用配置热重载。使用 Compose 启动时，程序会把缺失的默认配置文件初始化到本地 ./configs（已有文件不会被覆盖）；./configs 和 ./logs 会挂载到容器里，方便实时编辑与查看日志。

想从源码构建 / 改代码部署？请看 从源码构建。

1. 下载 docker-compose.yml

前置：已安装 wget（或手动下载）、Docker 与 Docker Compose。

mkdir feishu-github-tracker && cd feishu-github-tracker
# 下载仓库 main 分支的 docker-compose.yml
wget -O docker-compose.yml https://raw.githubusercontent.com/hnrobert/feishu-github-tracker/main/docker-compose.yml

2. 启动

docker compose（现代 Compose） 
docker compose up -d
docker compose logs -f
docker-compose（早期 Compose） 
docker-compose up -d
docker-compose logs -f

说明：

  • 首次启动会把镜像内的默认配置复制到本地配置目录（已有配置不会被覆盖）：
    • 本地 ./configs ↔ 容器 /app/configs
    • 本地 ./logs ↔ 容器 /app/logs
  • 镜像默认启用热重载：每次收到 webhook 时会重新加载配置，所以改完 ./configs/ 无需重启即生效。

3. 访问健康检查

服务默认监听 4594 端口：

http://localhost:4594/health

4. 修改配置

编辑 ./configs/ 下的运行时配置，参考 ../README.md 或 ../example-configs 下示例文件的注释。最常需要改的有：

  • ./configs/server.yaml（示例：server.yaml）：监听地址、端口、secret（测试可不设）、面板账号
  • ./configs/feishu-bots.yaml（示例：feishu-bots.yaml）：飞书机器人的 Webhook URL 与别名
    • 不清楚「飞书机器人 / Webhook URL」是什么？参考 飞书文档，在群里建一个机器人并复制其 Webhook URL
  • ./configs/patterns/*.yaml（示例：patterns/）：要监听的 GitHub 仓库规则，每条规则一个文件（pattern + weight 优先级 + 事件 + 通知对象）
  • ./configs/events/（示例：events/event_sets/、events/definitions/）：事件集合与事件过滤定义，每个集合/事件一个文件
  • ./configs/templates/<语言>/<事件>.json（示例：templates/default/）：消息模板，按语言分目录（default / cn），每个事件一个文件

修改后保存，程序会在下一次收到 GitHub Webhook 时自动热重载。

5. Web 管理面板（可选）

除了手改 YAML，还内置一个 Web 管理面板，可在浏览器里增删改：仓库规则、飞书机器人、服务设置、事件配置、消息模板。

  • 面板地址：http://localhost:4594/（与 webhook 同端口；/webhook、/health 仍照常工作）
  • 默认账号：用户名 admin / 密码 admin（默认配置已带；老版本升级且未配置面板账号时，也自动用 admin/admin）
    • 用户名：可在 ./configs/server.yaml 的 panel.username、环境变量 PANEL_USERNAME，或面板「服务设置」页修改
    • 密码（优先级从高到低）：
      • 环境变量（推荐）：PANEL_PASSWORD=你的密码
      • panel.password（明文）：存在则优先使用；启动 / reload 时会自动转为 password_hash（覆盖原 hash）、删除该明文行并补回 # password: "admin" 注释
      • panel.password_hash（直接填 sha256(密码) 的十六进制：printf '%s' '你的密码' | openssl dgst -sha256 | awk '{print $NF}'；浏览器登录时会发送同样的 SHA-256 值，已有的 password_hash 不会失效；旧版 bcrypt 哈希也兼容）
    • 修改密码需先填「当前密码」校验通过后才生效；保存后下次登录即用新账号，无需重启
  • 面板内修改保存后会自动 reload 生效（无需等下一次 webhook 或重启）；手动编辑 ./configs/ 则需以 --reload 启动或重启进程。端口 / 密钥的改动仍需重启
  • 注意：事件配置在面板里是逐文件的可视化编辑，保存时 YAML 注释与格式原样保留

6. 多模板配置（可选）

为不同飞书 bot 配置不同消息模板（如中英文双语）：

feishu_bots:
  - alias: 'team-cn'
    url: 'https://open.feishu.cn/open-apis/bot/v2/hook/cn-webhook'
    template: 'cn' # 不设置则默认用 templates/default/

模板按语言放在 ./configs/templates/<名称>/ 目录（如 templates/cn/），目录内每个事件一个 <事件名>.json 文件；可复制 templates/default/ 后修改，再在 feishu-bots.yaml 中用 template 引用。

7. 添加 GitHub Webhook

  • 进入要监听的 GitHub 仓库 → Settings → Webhooks → Add webhook
  • Payload URL：你的服务器地址，如 http://your-domain-or-ip:4594/webhook
  • Content type：选什么都支持
  • Secret：填你在 server.yaml 配置的 secret（如果配了）
  • 事件类型：可选 Let me select individual events 勾选需要的事件，并在 ./configs/patterns/ 对应仓库规则里用 all: 等做更细控制；详见 event_sets 示例
  • 点击 Add webhook
  • ✅ 配置无误的话，几秒后飞书群会收到一条「GitHub Webhook 添加成功」通知（GitHub 发送的 ping 事件），说明 Webhook 已生效

8. 简要调试

没收到通知？检查：

  • GitHub Webhook 配置（Payload URL、Secret、事件类型）
  • docker compose logs -f 里的错误日志；若完全没日志，确认 GitHub 是否真的发请求过来了
  • 改完配置后，触发一次 GitHub 事件，看日志确认是否重载成功

9. 更新版本

镜像与配置是分离的：你的 ./configs、./logs 是挂载卷，升级镜像不会覆盖它们。

docker compose pull      # 拉取最新镜像
docker compose up -d     # 用新镜像重建容器（本地配置保留）

升级后注意：

  • 你已有的 ./configs/ 配置都会保留；镜像只会在文件缺失时补上默认配置
  • 旧版单文件配置默认不迁移、可一直正常使用（面板编辑也会写回原文件）。想切换到分文件格式（patterns/、events/、templates/<语言>/，含 weight 优先级）时，在管理面板「服务设置」页点「迁移到新配置格式」，或在 server.yaml 设 server.migrate_config: true 重启（完成后该行自动注释掉）；原文件连同注释完整备份到 ./configs/legacy/
  • 新版本引入的新默认配置项，也只在你对应文件缺失时才会自动补入
  • 管理面板账号：若你从老版本升级且没配置过面板账号，默认登录 admin / admin（见 §5）

从旧版仓库迁移

旧版本曾将运行时配置直接纳入 Git 跟踪。首次拉取本次目录迁移前，请先备份并暂存本地配置，避免 Git 因配置文件修改拒绝更新：

cp -a configs ../feishu-github-tracker-configs-backup
git stash push -m "backup runtime configs before config split" -- configs
git pull
mkdir -p configs
cp -a ../feishu-github-tracker-configs-backup/. configs/

迁移后 configs/ 已被忽略；以后更新时可直接比较 example-configs/ 与本地 configs/，不会再产生配置文件的 Git 修改。

从源码部署的更新方式见 从源码构建 · 更新源码版本。

更多配置与高级用法见 ../README.md、../example-configs 示例注释，或 ../internal/handler、../internal/template 下的文档。