koishi-plugin-github-webhook-pusher

Koishi 机器人框架的 GitHub Webhook 推送插件，支持将 GitHub 仓库事件推送到 QQ 群聊或私聊，并支持通过 #<编号> 快速截图查看 Issue/PR 详情。

功能特性

• 🔐 安全验证 - 支持 HMAC SHA256 签名验证，确保 Webhook 请求来源可信
• 📋 信任仓库管理 - 管理员可控制哪些仓库的事件可以被处理
• 🔔 灵活订阅 - 管理员可为群聊/私聊订阅感兴趣的仓库和事件类型
• 📨 多事件支持 - 支持 Issues、Issue Comment、Pull Request、Review、Release、Push、Star、Fork 等常用事件
• 🚀 并发推送 - 支持并发推送到多个订阅目标，可配置并发数
• 💾 数据持久化 - 订阅和信任仓库数据持久化存储
• 🖼️ Issue 截图查询 - 绑定仓库后，发送 #166 即可截图查看对应 Issue/PR，支持配置国内代理

安装

通过 Koishi 插件市场安装

在 Koishi 控制台的插件市场中搜索 github-webhook-pusher 并安装。

通过 npm 安装

npm install koishi-plugin-github-webhook-pusher

配置说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | path | string | /github/webhook | Webhook 接收路径 | | secret | string | (必填) | GitHub Webhook Secret，用于签名验证 | | defaultEvents | string[] | ['issues', 'release', 'push'] | 新订阅的默认事件类型 | | debug | boolean | false | 启用调试模式，输出详细日志 | | allowUntrusted | boolean | false | 是否允许处理非信任仓库的事件 | | concurrency | number | 5 | 消息推送并发数 | | deliveryRetentionDays | number | 30 | 投递记录保留天数（<=0 表示不清理） | | deliveryCleanupIntervalHours | number | 24 | 投递记录清理间隔（小时） | | githubProxy | string | '' | GitHub 访问代理前缀，如 https://gh.072118.xyz（结尾不加斜杠），留空直连 github.com | | issueScreenshot.enabled | boolean | false | 启用 Issue 截图功能（需安装 puppeteer 服务） | | issueScreenshot.timeout | number | 15000 | 页面加载超时（毫秒） | | issueScreenshot.viewportWidth | number | 1280 | 截图视口宽度（像素） |

配置示例

plugins:
  github-webhook-pusher:
    path: /github/webhook
    secret: your-webhook-secret-here
    defaultEvents:
      - issues
      - release
      - push
    debug: false
    allowUntrusted: false
    concurrency: 5
    deliveryRetentionDays: 30
    deliveryCleanupIntervalHours: 24
    githubProxy: https://gh.072118.xyz
    issueScreenshot:
      enabled: true
      timeout: 15000
      viewportWidth: 1280

GitHub Webhook 设置指南

1. 获取 Webhook URL

你的 Webhook URL 格式为：

https://your-koishi-server.com/github/webhook

其中 /github/webhook 是默认路径，可通过 path 配置项修改。

2. 在 GitHub 仓库中配置 Webhook

1. 进入你的 GitHub 仓库
2. 点击 Settings → Webhooks → Add webhook
3. 填写以下信息：
   • Payload URL: 你的 Webhook URL
   • Content type: application/json
   • Secret: 与插件配置中的 secret 保持一致
   • Which events would you like to trigger this webhook?: 选择需要的事件
     • Issues
     • Issue comments
     • Pull requests
     • Pull request reviews
     • Pull request review comments
     • Releases
     • Pushes
     • Stars (Watch)
     • Forks
     • Create
     • Delete
     • Workflow runs
4. 点击 Add webhook 保存

3. 验证配置

配置完成后，GitHub 会发送一个 ping 事件。你可以在 Webhook 设置页面查看投递记录，确认是否收到 200 响应。

命令使用说明

所有带 （管理员） 标注的命令需要用户 authority ≥ 3 才能使用。 在 Koishi 控制台 → 数据库 → user 表中修改对应用户的 authority 字段，或使用 authorize @用户 3 命令授权。

信任仓库管理（管理员）

信任仓库是可以被订阅的仓库白名单。

| 命令 | 说明 | 示例 | |------|------|------| | gh.trust.add <repo> | 添加信任仓库 | gh.trust.add koishijs/koishi | | gh.trust.remove <repo> | 移除信任仓库 | gh.trust.remove koishijs/koishi | | gh.trust.list | 列出所有信任仓库 | gh.trust.list | | gh.trust.enable <repo> | 启用信任仓库 | gh.trust.enable koishijs/koishi | | gh.trust.disable <repo> | 禁用信任仓库 | gh.trust.disable koishijs/koishi |

订阅管理（管理员）

管理员可以为当前群聊/私聊订阅信任列表中的仓库，接收事件通知。

| 命令 | 说明 | 示例 | |------|------|------| | gh.sub <repo> | 订阅仓库（交互式选择事件） | gh.sub koishijs/koishi | | gh.unsub <repo> | 取消订阅（交互式选择事件，可整体取消） | gh.unsub koishijs/koishi | | gh.list | 列出当前会话的所有订阅 | gh.list |

Issue 截图查询（管理员绑定，所有人触发）

管理员为当前群聊/私聊绑定一个仓库后，任何人发送 #<编号> 即可查看对应 Issue/PR。

| 命令 | 说明 | 示例 | |------|------|------| | gh.bind <repo> | 绑定 Issue 查询仓库（管理员） | gh.bind AUTO-MAS-Project/AUTO-MAS | | gh.unbind | 解绑 Issue 查询仓库（管理员） | gh.unbind | | #<编号> | 截图查看对应 Issue/PR | #166 |

截图功能需要启用 issueScreenshot.enabled 并安装 koishi-plugin-puppeteer。 未安装 puppeteer 时会降级为直接发送链接。 服务器在国内时建议配置 githubProxy 代理地址。

工具命令

| 命令 | 说明 | 示例 | |------|------|------| | gh.ping | 查看插件状态 | gh.ping | | gh.test <repo> <event> | 生成测试消息（管理员） | gh.test koishijs/koishi push |

支持的事件类型

| 事件类型 | 显示名称 | Emoji | 说明 | |----------|----------|-------|------| | issues | Issue | 📌 | Issue 的创建、关闭、重新打开、编辑 | | issue_comment | Issue Comment | 💬 | Issue 评论的创建、编辑、删除 | | pull_request | PR | 🔀 | Pull Request 的创建、关闭、合并 | | pull_request_review | PR Review | 🧪 | PR Review 的提交、编辑、撤销 | | pull_request_review_comment | PR Review Comment | 💬 | PR Review 评论的创建、编辑、删除 | | release | Release | 🚀 | 版本发布 | | push | Commit | ⬆️ | 代码推送（最多显示 3 条提交） | | star | Star | ⭐ | Star 操作 | | fork | Fork | 🍴 | Fork 操作 | | create | Create | ✨ | 分支/标签创建 | | delete | Delete | 🗑️ | 分支/标签删除 | | workflow_run | Workflow | 🧩 | Workflow 运行 |

消息格式示例

Issues 事件

📌 [owner/repo] Issue
user opened #123: Issue 标题
https://github.com/owner/repo/issues/123

Push 事件

⬆️ [owner/repo] Commit
user 推送了 3 个提交到 main

• abc1234 - 提交消息1
• def5678 - 提交消息2
• ghi9012 - 提交消息3

https://github.com/owner/repo/compare/...

Release 事件

🚀 [owner/repo] Release
user 发布了 v1.0.0
https://github.com/owner/repo/releases/tag/v1.0.0

常见问题解答

Q: Webhook 返回 401 错误？

A: 签名验证失败。请检查：

1. GitHub Webhook 设置中的 Secret 与插件配置的 secret 是否一致
2. Content type 是否设置为 application/json
3. 如果服务器未保留 raw body，插件会使用解析后的 body 回退验签，可能导致签名不一致；建议配置保留原始请求体

Q: 收不到 Webhook 事件？

A: 请检查：

1. Koishi 服务器是否可以从公网访问
2. Webhook URL 是否正确（包括端口号）
3. 防火墙是否允许 GitHub 的 IP 访问
4. 在 GitHub Webhook 设置页面查看投递记录，确认请求是否发送成功

Q: 订阅仓库时提示"不在信任列表中"？

A: 需要管理员先使用 gh.trust.add owner/repo 将仓库添加到信任列表。

Q: 如何修改订阅的事件类型？

A: 直接再次执行 gh.sub owner/repo 可交互式添加未订阅的事件；执行 gh.unsub owner/repo 可交互式移除已订阅的事件，回复 all 则整体取消订阅。回复支持空格或逗号分隔多个编号。

Q: 如何查看当前订阅了哪些仓库？

A: 使用 gh.list 命令查看当前会话的所有订阅。

Q: 消息推送失败会影响其他订阅者吗？

A: 不会。插件使用错误隔离机制，单个目标的推送失败不会影响其他目标。

Q: 如何测试消息格式？

A: 管理员可以使用 gh.test owner/repo event 命令生成测试消息，例如：

gh.test koishijs/koishi issues
gh.test koishijs/koishi push

Q: #166 没有反应？

A: 请检查：

1. 是否已使用 gh.bind owner/repo 绑定了仓库
2. 配置中 issueScreenshot.enabled 是否设为 true（关闭时只发链接，需要手动发送 #166）
3. 服务器在国内时是否配置了 githubProxy

Q: 截图显示不全或加载失败？

A: 可以适当增大 issueScreenshot.timeout 值（如 30000），或检查 githubProxy 代理是否可用。

依赖

• Koishi 4.x
• 需要 server 服务（提供 HTTP 路由）
• 需要 database 服务（数据持久化）
• 可选 puppeteer 服务（用于 Issue 截图功能，需安装 koishi-plugin-puppeteer）

许可证

MIT License

功能特性

• 🔐 安全验证 - 支持 HMAC SHA256 签名验证，确保 Webhook 请求来源可信
• 📋 信任仓库管理 - 管理员可控制哪些仓库的事件可以被处理
• 🔔 灵活订阅 - 用户可自由订阅感兴趣的仓库和事件类型
• 📨 多事件支持 - 支持 Issues、Issue Comment、Pull Request、Review、Release、Push、Star、Fork 等常用事件
• 🚀 并发推送 - 支持并发推送到多个订阅目标，可配置并发数
• 💾 数据持久化 - 订阅和信任仓库数据持久化存储

安装

通过 Koishi 插件市场安装

在 Koishi 控制台的插件市场中搜索 github-webhook-pusher 并安装。

通过 npm 安装

npm install koishi-plugin-github-webhook-pusher

配置说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | path | string | /github/webhook | Webhook 接收路径 | | secret | string | (必填) | GitHub Webhook Secret，用于签名验证 | | defaultEvents | string[] | ['issues', 'release', 'push'] | 新订阅的默认事件类型 | | debug | boolean | false | 启用调试模式，输出详细日志 | | allowUntrusted | boolean | false | 是否允许处理非信任仓库的事件 | | concurrency | number | 5 | 消息推送并发数 | | deliveryRetentionDays | number | 30 | 投递记录保留天数（<=0 表示不清理） | | deliveryCleanupIntervalHours | number | 24 | 投递记录清理间隔（小时） |

配置示例

plugins:
  github-webhook-pusher:
    path: /github/webhook
    secret: your-webhook-secret-here
    defaultEvents:
      - issues
      - release
      - push
    debug: false
    allowUntrusted: false
    concurrency: 5
    deliveryRetentionDays: 30
    deliveryCleanupIntervalHours: 24

GitHub Webhook 设置指南

1. 获取 Webhook URL

你的 Webhook URL 格式为：

https://your-koishi-server.com/github/webhook

其中 /github/webhook 是默认路径，可通过 path 配置项修改。

2. 在 GitHub 仓库中配置 Webhook

1. 进入你的 GitHub 仓库
2. 点击 Settings → Webhooks → Add webhook
3. 填写以下信息：
   • Payload URL: 你的 Webhook URL
   • Content type: application/json
   • Secret: 与插件配置中的 secret 保持一致
   • Which events would you like to trigger this webhook?: 选择需要的事件
     • Issues
     • Issue comments
     • Pull requests
     • Pull request reviews
     • Pull request review comments
     • Releases
     • Pushes
     • Stars (Watch)
     • Forks
     • Create
     • Delete
     • Workflow runs
4. 点击 Add webhook 保存

3. 验证配置

配置完成后，GitHub 会发送一个 ping 事件。你可以在 Webhook 设置页面查看投递记录，确认是否收到 200 响应。

命令使用说明

信任仓库管理（管理员）

信任仓库是可以被订阅的仓库白名单，只有管理员可以管理。

| 命令 | 说明 | 示例 | |------|------|------| | gh.trust.add <repo> | 添加信任仓库 | gh.trust.add koishijs/koishi | | gh.trust.remove <repo> | 移除信任仓库 | gh.trust.remove koishijs/koishi | | gh.trust.list | 列出所有信任仓库 | gh.trust.list | | gh.trust.enable <repo> | 启用信任仓库 | gh.trust.enable koishijs/koishi | | gh.trust.disable <repo> | 禁用信任仓库 | gh.trust.disable koishijs/koishi |

订阅管理

用户可以订阅信任列表中的仓库，接收事件通知。

| 命令 | 说明 | 示例 | |------|------|------| | gh.sub <repo> | 订阅仓库（交互式选择事件） | gh.sub koishijs/koishi | | gh.unsub <repo> | 取消订阅（交互式选择事件，可整体取消） | gh.unsub koishijs/koishi | | gh.list | 列出当前会话的所有订阅 | gh.list |

工具命令

| 命令 | 说明 | 示例 | |------|------|------| | gh.ping | 查看插件状态 | gh.ping | | gh.test <repo> <event> | 生成测试消息（管理员） | gh.test koishijs/koishi push |

支持的事件类型

| 事件类型 | 显示名称 | Emoji | 说明 | |----------|----------|-------|------| | issues | Issue | 📌 | Issue 的创建、关闭、重新打开、编辑 | | issue_comment | Issue Comment | 💬 | Issue 评论的创建、编辑、删除 | | pull_request | PR | 🔀 | Pull Request 的创建、关闭、合并 | | pull_request_review | PR Review | 🧪 | PR Review 的提交、编辑、撤销 | | pull_request_review_comment | PR Review Comment | 💬 | PR Review 评论的创建、编辑、删除 | | release | Release | 🚀 | 版本发布 | | push | Commit | ⬆️ | 代码推送（最多显示 3 条提交） | | star | Star | ⭐ | Star 操作 | | fork | Fork | 🍴 | Fork 操作 | | create | Create | ✨ | 分支/标签创建 | | delete | Delete | 🗑️ | 分支/标签删除 | | workflow_run | Workflow | 🧩 | Workflow 运行 |

消息格式示例

Issues 事件

📌 [owner/repo] Issue
user opened #123: Issue 标题
https://github.com/owner/repo/issues/123

Push 事件

⬆️ [owner/repo] Commit
user 推送了 3 个提交到 main

• abc1234 - 提交消息1
• def5678 - 提交消息2
• ghi9012 - 提交消息3

https://github.com/owner/repo/compare/...

Release 事件

🚀 [owner/repo] Release
user 发布了 v1.0.0
https://github.com/owner/repo/releases/tag/v1.0.0

常见问题解答

Q: Webhook 返回 401 错误？

A: 签名验证失败。请检查：

1. GitHub Webhook 设置中的 Secret 与插件配置的 secret 是否一致
2. Content type 是否设置为 application/json
3. 如果服务器未保留 raw body，插件会使用解析后的 body 回退验签，可能导致签名不一致；建议配置保留原始请求体

Q: 收不到 Webhook 事件？

A: 请检查：

1. Koishi 服务器是否可以从公网访问
2. Webhook URL 是否正确（包括端口号）
3. 防火墙是否允许 GitHub 的 IP 访问
4. 在 GitHub Webhook 设置页面查看投递记录，确认请求是否发送成功

Q: 订阅仓库时提示"不在信任列表中"？

A: 需要管理员先使用 gh.trust.add owner/repo 将仓库添加到信任列表。

Q: 如何修改订阅的事件类型？

A: 直接再次执行 gh.sub owner/repo 可交互式添加未订阅的事件；执行 gh.unsub owner/repo 可交互式移除已订阅的事件，回复 all 则整体取消订阅。回复支持空格或逗号分隔多个编号。

Q: 如何查看当前订阅了哪些仓库？

A: 使用 gh.list 命令查看当前会话的所有订阅。

Q: 消息推送失败会影响其他订阅者吗？

A: 不会。插件使用错误隔离机制，单个目标的推送失败不会影响其他目标。

Q: 如何测试消息格式？

A: 管理员可以使用 gh.test owner/repo event 命令生成测试消息，例如：

gh.test koishijs/koishi issues
gh.test koishijs/koishi push

依赖

• Koishi 4.x
• 需要 server 服务（提供 HTTP 路由）
• 需要 database 服务（数据持久化）

许可证

MIT License