mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00

feat(filters): JSONPath field filters, operators, AST groups, fragments, and test-match

Add a field filter type reading any payload value by JSONPath with array expansion, 12 comparison operators (eq/ne/contains/startsWith/endsWith/regex/gt/gte/lt/lte/in/exists), a visual AST builder (all/any/not) in the route editor, chip-based multi-value input, a stateless POST /admin/api/test-match dry-run, and named filter fragments stored in D1 (d1_fragments, migration 0010) inlined into route ASTs on insert.

2026-08-24 22:51:20 +08:00

7.9 KiB

Raw Blame History

配置

本页是密钥与 Web 控制台的参考。核心概念在独立页面中说明：

主题	页面
路由、目标、`fallback` / `stop`、身份组提醒	路由与目标
分组、角色、邀请、自助注册、日志频道	分组与访问控制
Webhook 提供方、分组入口、自定义 webhook	Webhook 接入与租户隔离
KV / D1 键布局	存储布局
过滤器（模式语法参考）	下方过滤器类型 / 过滤器教程

密钥

WebHooker 的运行需要若干密钥。本地开发时放入 .dev.vars，生产环境使用 Cloudflare Worker Secrets。

必需密钥

变量	说明
`GITHUB_WEBHOOK_SECRET`	GitHub App 设置中的 webhook 密钥
`GITEA_WEBHOOK_SECRET`	Gitea 实例的 webhook 密钥（仅接收 Gitea webhook 时需要）
`GITHUB_CLIENT_ID`	App 设置中的 OAuth 客户端 ID
`GITHUB_CLIENT_SECRET`	App 设置中的 OAuth 客户端密钥
`DISCORD_TOKEN`	Discord 机器人 Token
`TELEGRAM_TOKEN`	Telegram 机器人 Token（BotFather 获取）—— Telegram 路由必需

Note

GITHUB_APP_ID 与 GITHUB_PRIVATE_KEY（PKCS#8 PEM）用于 GitHub App 安装流程 （/auth/github/install），通过 App JWT 解析安装所属账号的登录名。两者均为可选—— 未设置时安装页仍可正常使用，但会显示无账号名的匿名 inst-{installationId} 分组。 OAuth 流程本身只需要 GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET。

可选密钥

变量	说明	默认值
`DISCORD_PUBLIC_KEY`	Discord 应用的公钥（开发者门户获取），交互功能必需	未设置时交互返回 401
`DISCORD_APPLICATION_ID`	Discord 应用 ID；省略时自动获取	自动获取
`TELEGRAM_WEBHOOK_SECRET`	`POST /telegram/webhook` 验签密钥（X-Telegram-Bot-Api-Secret-Token）	未设置时不校验
`TELEGRAM_RICH_HEADER_HOST`	外部 rich-header 服务的基础 URL；未设置时使用内置 `GET /api/richheader` 提供 Telegram 头像卡片	内置 `/api/richheader`
`BASE_URL`	OAuth 回调的公共 URL	`http://localhost:8787`
`ADMIN_USER_IDS`	允许访问 WebUI 的 GitHub 用户 ID（或登录名），逗号分隔	未设置时 WebUI 关闭
`ALLOW_SELF_SIGNUP`	开启（`1`/`true`）后，没有任何分组权限的 GitHub 用户首次登录会自动获得个人分组而非 403	关闭
`AUDIT_RETENTION_DAYS`	定时清理时审计日志的保留天数	`90`
`NUXT_PUBLIC_DOCS_URL`	落地页使用的文档站 URL（客户端运行时配置）	落地页默认值
`NUXT_PUBLIC_REPO_URL`	落地页使用的 GitHub 仓库 URL	落地页默认值
`NUXT_PUBLIC_LEGAL_CONTACT`	`/terms` 与 `/privacy` 页面展示的联系方式	未设置时显示占位文本

Web 控制台

WebHooker 在 /admin 提供内置配置控制台，可在浏览器中管理路由、分组、成员、邀请、发送日志与审计日志。它由 GitHub OAuth 与管理员白名单保护。

设置

配置 ADMIN_USER_IDS，填写允许管理一切的 GitHub 用户 ID，也支持登录名，例如 ADMIN_USER_IDS=12345,RhenCloud。未设置时控制台禁用（除非开启 ALLOW_SELF_SIGNUP）。
打开 /admin 并使用 GitHub 登录。
没有任何访问权限的用户会得到 403，除非 ALLOW_SELF_SIGNUP=1（获得个人分组）或跟随分组邀请链接。

控制台以 SPA 形式在 /admin 提供；其标签页可通过 URL 路径直达（/admin/groups、/admin/logs、/admin/audit）。/admin 之外未匹配到端点的 URL 直接返回 404，而不会展示控制台。

所有管理端点（/admin/api/*）见 Admin API。保存的路由和分组会立即持久化到 D1（d1_routes / d1_groups），并使 KV 缓存失效、刷新配置缓存，下一次 webhook 处理即会生效。

过滤器类型

实操指南见过滤器教程，包含完整示例。

类型	匹配对象	示例
`event`	GitHub 事件名称	`push`, `pull_*`, `pull_request`
`repo`	仓库全名	`org/repo`, `org/*`
`actor`	发送者登录名	`username`, `[bot]`, `*[bot]`
`action`	事件操作	`opened`, `closed`, `published`
`branch`	分支名称	`main`, `feature-?`, `/^release-/`
`field`	任意载荷字段（JSONPath）	`path: "pull_request.user.login"`
`keyword`	载荷正文中的文本	`deploy`, `/fix\s+\d+/`

过滤器行为

路由中的所有过滤器必须都匹配才触发路由（AND 逻辑）
在任何过滤器上设置 "exclude": true 可反转匹配逻辑（NOT 逻辑）
所有过滤器类型支持相同的模式形式：纯文本、*/? 通配符（* 任意长度、? 单字符）以及 /正则表达式/——均不区分大小写
字段过滤器（event/repo/actor/action/branch/field）的通配符匹配整个值；keyword 的通配符和正则搜索载荷任意位置；keyword 的纯文本为子串搜索
除 keyword 外的每个过滤器都可加 op 操作符——eq（默认，经典行为）、ne、contains、startsWith、endsWith、regex、gt、gte、lt、lte、in、exists——见过滤器教程
field 过滤器使用点号分隔的 JSONPath path 定位载荷字段；数组会自动展开，任一元素匹配即满足过滤器
路由可将过滤器嵌套在 ast 节点（all / any / not）中，取代扁平的 filters 列表；存在 ast 时它优先
超过 200 个字符的模式不编译为通配符/正则；// 包裹的非法正则匹配不到任何内容
branch 过滤器适用于 push、pull_request、pull_request_review、pull_request_review_comment、create/delete、workflow_run、workflow_job、check_suite、deployment 和 code_scanning_alert 事件

匹配值

过滤器接受单个字符串或字符串数组：

{ "type": "event", "match": "push" }
{ "type": "event", "match": ["push", "pull_request"] }
{ "type": "field", "path": "pull_request.commits", "op": "gt", "match": "1" }

7.9 KiB Raw Blame History Unescape Escape

配置

密钥