ReCloudStudio/WebHooker
1
0
Fork 0
mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

merge: resolve conflicts with origin/main (auto-fix formatting)

Browse source
This commit is contained in:
RhenCloud 2026-08-14 06:45:15 +08:00
commit 6f1a334150
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
22 changed files with 921 additions and 910 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/guide/configuration.md
View file

@ -2,13 +2,13 @@
This page is the reference for secrets and the Web UI. Core concepts live in dedicated pages:
| Topic | Page |
|---------------------------------------------------|----------------------------------------------------------------------|
| Routes, targets, `fallback` / `stop`, role pings | [Routes & Targets](./routes) |
| Groups, roles, invites, self sign-up, log channel | [Groups & Access Control](./groups) |
| Webhook providers, per-group ingress, custom | [Webhook Ingress & Tenancy](./ingress) |
| KV / D1 key layout | [Storage Layout](./storage) |
| Filters (pattern syntax reference) | [Filter Types](#filter-types) below / [Filter Tutorial](./filters) |
| Topic | Page |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| Routes, targets, `fallback` / `stop`, role pings | [Routes & Targets](./routes) |
| Groups, roles, invites, self sign-up, log channel | [Groups & Access Control](./groups) |
| Webhook providers, per-group ingress, custom | [Webhook Ingress & Tenancy](./ingress) |
| KV / D1 key layout | [Storage Layout](./storage) |
| Filters (pattern syntax reference) | [Filter Types](#filter-types) below / [Filter Tutorial](./filters) |
## Secrets
@ -17,7 +17,7 @@ WebHooker requires several secrets to function. For local development, store the
### Required Secrets
| Variable | Description |
|-------------------------|--------------------------------------------------------------------------|
| ----------------------- | ------------------------------------------------------------------------ |
| `GITHUB_WEBHOOK_SECRET` | Webhook secret from your GitHub App settings |
| `GITEA_WEBHOOK_SECRET` | Webhook secret from your Gitea instance (only to receive Gitea webhooks) |
| `GITHUB_CLIENT_ID` | OAuth client ID from App settings |
@ -35,7 +35,7 @@ WebHooker requires several secrets to function. For local development, store the
### Optional Secrets
| Variable | Description | Default |
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `DISCORD_PUBLIC_KEY` | Discord application public key (Developer Portal) — required for interactions | Unset → interactions return `401` |
| `DISCORD_APPLICATION_ID` | Discord application id; auto-resolved when omitted | Auto-resolved |
| `TELEGRAM_WEBHOOK_SECRET` | Secret token for `POST /telegram/webhook` verification (X-Telegram-Bot-Api-Secret-Token) | Disabled (no verification) |
@ -67,7 +67,7 @@ All management endpoints (`/admin/api/*`) are documented in the [Admin API](../a
See the [Filter Tutorial](./filters) for a hands-on guide with worked examples.
| Type | Matches | Example |
|-----------|----------------------|------------------------------------|
| --------- | -------------------- | ---------------------------------- |
| `event` | GitHub event name | `push`, `pull_*`, `pull_request` |
| `repo` | Repository full name | `org/repo`, `org/*` |
| `actor` | Sender login | `username`, `[bot]`, `*[bot]` |

526
docs/guide/filters.md
View file

@ -1,263 +1,263 @@
# Filter Tutorial
Filters decide which webhook events a [route](./routes) forwards. A route fires only when **every** filter in its `filters` array matches (AND logic). This page is a hands-on tutorial: it explains how each filter type behaves and how to combine them into real-world routing rules.
See [Filter Types](./configuration#filter-types) in the configuration guide for the reference table, and [Supported Events](../events/supported) for the full event list.
## How Matching Works
- All filters in a route must match, otherwise the route is skipped.
- Each filter matches the event against one field of the webhook payload.
- Matching is **case-insensitive** for every filter type.
- The `match` value accepts either a single string or an array of strings. An array behaves as OR — the filter matches if any of its values match.
- Setting `"exclude": true` inverts the result (NOT logic): the filter matches when the value does **not** match.
```json
{
"type": "event",
"match": ["push", "pull_request"],
"exclude": false
}
```
The route above matches both `push` and `pull_request` events.
## Pattern Syntax
Every filter type shares the same three pattern forms:
| Pattern | Meaning |
| ---------------------- | -------------------------------------------------------------- |
| `plain text` | Field filters: **exact** match. `keyword`: search anywhere. |
| `*` / `?` | **Glob wildcards** — `*` any run, `?` one char. |
| `/regular expression/` | Compiled as a **regular expression** (case-insensitive flag). |
- On field filters (`event`/`repo`/`actor`/`action`/`branch`), plain text and globs match the whole value; on `keyword` they search anywhere in the payload.
- Regexes always search: `/^feat/` matches values *starting* with `feat`, `/feat/` matches anywhere.
Examples:
```json
{ "type": "event", "match": "pull_*" }
```
Matches `pull_request`, `pull_request_review`, `pull_request_review_comment`, ...
```json
{ "type": "repo", "match": "myorg/*" }
```
```json
{ "type": "branch", "match": "feature-?" }
```
Matches `feature-x`, `feature-1`, but not `feature-xy`.
```json
{ "type": "branch", "match": "/^feat/" }
```
Matches any branch whose name starts with `feat`.
> [!TIP]
> Globs and regular expressions are case-insensitive too, and `*` matches across `/` in repo names (`myorg/*` also matches `myorg/sub/backend`).
## Filter Types in Depth
### `event` — Event type
Matches the GitHub event name, e.g. `push`, `pull_request`, `issues`, `release`. Use this as the backbone of every route.
```json
{ "type": "event", "match": "release" }
```
Match several events with an array:
```json
{ "type": "event", "match": ["create", "delete"] }
```
### `repo` — Repository
Matches the repository **full name** (`owner/name`). Case-insensitive.
```json
{ "type": "repo", "match": "myorg/backend" }
```
Route multiple repositories to one channel:
```json
{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] }
```
### `actor` — Sender
Matches the **sender's GitHub login** that triggered the event (`sender.login` in the payload). Useful for ignoring bots.
```json
{ "type": "actor", "match": "dependabot[bot]", "exclude": true }
```
The route above fires for every event **except** those triggered by Dependabot.
### `action` — Event action
Matches the `action` field of the payload, e.g. `opened`, `closed`, `published`, `completed`. Not all events carry an action — see [Filter Compatibility](../events/supported#filter-compatibility). Combine it with `event` to narrow down a specific lifecycle step:
```json
{
"type": "event",
"match": "pull_request",
"exclude": false
},
{
"type": "action",
"match": ["opened", "reopened"]
}
```
This fires when a pull request is opened or reopened (and not on merge/close/edit).
### `branch` — Branch
Matches the branch involved in the event. What counts as "the branch" depends on the event type:
| Event | Branch extracted |
| --------------------------- | ------------------------------------------- |
| `push` | The branch that was pushed to |
| `pull_request` (and review) | The pull request's **head** (source) branch |
| `create` / `delete` | The created/deleted branch or tag |
| `workflow_run` | The `head_branch` the workflow ran on |
| `workflow_job` | The `head_branch` the job ran on |
| `check_suite` | The `head_branch` of the check suite |
| `deployment` | The deployment ref (strips `refs/heads/`) |
| `code_scanning_alert` | The branch the alert belongs to |
```json
{
"type": "event",
"match": "push"
},
{
"type": "branch",
"match": "main"
}
```
Fires for pushes to `main` only. To watch several long-lived branches:
```json
{ "type": "branch", "match": ["main", "develop"] }
```
> [!NOTE]
> `branch` matching is case-insensitive. Use globs (`feature/*`) or a `//`-wrapped regex (`/^release-/`) for prefix or wildcard-style matching.
### `keyword` — Text in the payload
Matches against the **full JSON payload**, lowercased. It is the most flexible filter: plain text searches anywhere, `*`/`?` globs search with wildcards, and `//`-wrapped patterns are compiled as regular expressions (with the `i` flag).
```json
{ "type": "keyword", "match": "deploy" }
```
Fires when the payload contains `deploy` anywhere. Because the payload is lowercased, this matches `Deploy`, `DEPLOY`, etc.
```json
{ "type": "keyword", "match": "*release-*" }
```
```json
{ "type": "keyword", "match": "/^(fix|hotfix)/" }
```
```json
{ "type": "keyword", "match": "/release-[0-9]+/" }
```
Behavior details:
- Patterns longer than 200 characters are **not** compiled as glob/regex and fall back to plain matching.
- A `//`-wrapped pattern that is not a valid regex matches **nothing** (the filter stays false) rather than erroring.
- To search for text that is a glob or regex special character (e.g. `v1.2.3`), rely on the plain-text form — a pattern without `*`, `?`, or `//` wrapping matches literally.
- The search covers the **entire** payload: commit messages, PR titles and bodies, labels, refs, even repository and sender names.
### Combining `exclude` with `keyword`
Just like the other filters, `exclude` inverts the keyword match:
```json
{ "type": "keyword", "match": "/wip|draft/", "exclude": true }
```
Skips events whose payload mentions `wip` or `draft`.
## Worked Example 1: PR alerts that skip bots and drafts
Forward pull request activity, but ignore bot authors and draft PRs, to a `#prs` channel:
```json
{
"id": "pr-notices",
"name": "PR Notices",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "pull_request" },
{ "type": "actor", "match": "dependabot[bot]", "exclude": true },
{ "type": "keyword", "match": "\"draft\": true", "exclude": true }
],
"target": { "channelId": "111111111111111111" }
}
```
The `"draft": true` pattern matches the `draft` field that GitHub includes in pull request payloads; combined with `exclude: true` it filters out draft PRs.
## Worked Example 2: Release-only channel
Forward only published releases from a specific repo:
```json
{
"id": "release-alerts",
"name": "Release Alerts",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "release" },
{ "type": "action", "match": "published" },
{ "type": "repo", "match": "myorg/backend" }
],
"target": { "channelId": "222222222222222222" }
}
```
## Worked Example 3: CI failures
Forward workflow runs that ended in failure on any branch, to a `#ci` channel:
```json
{
"id": "ci-failures",
"name": "CI Failures",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "workflow_run" },
{ "type": "action", "match": "completed" },
{ "type": "keyword", "match": "\"conclusion\":\"failure\"" }
],
"target": { "channelId": "333333333333333333" }
}
```
## Common Pitfalls
- **Wildcards are globs, not regex.** `repo: "myorg/*"` matches any repo under `myorg` (and `myorg/sub/backend`), but `repo: "myorg/.*"` matches literally. Use `//` wrapping for regex: `"/myorg\/.*/"`.
- **A `//`-wrapped invalid regex never matches.** Unlike plain text, an unwrapped invalid pattern is matched literally — wrap patterns only when they are real regular expressions.
- **An `action` filter on an action-less event never matches.** Check the event has an `action` field first (see [Filter Compatibility](../events/supported#filter-compatibility)).
- **`branch` on an event without a branch never matches.** A `branch` filter on an `issues` event will always be false. Use `keyword` if you need branch-like matching there.
- **`keyword` searches everything.** Because it scans the whole payload, a pattern like `"fix"` can match commit messages, issue titles, *and* repository names. Be as specific as possible.
- **Forgetting `exclude` semantics.** `exclude: true` negates the whole filter — one non-matching value in an array does not "block" the route; the negated filter matches only when *none* of the values match.
# Filter Tutorial
Filters decide which webhook events a [route](./routes) forwards. A route fires only when **every** filter in its `filters` array matches (AND logic). This page is a hands-on tutorial: it explains how each filter type behaves and how to combine them into real-world routing rules.
See [Filter Types](./configuration#filter-types) in the configuration guide for the reference table, and [Supported Events](../events/supported) for the full event list.
## How Matching Works
- All filters in a route must match, otherwise the route is skipped.
- Each filter matches the event against one field of the webhook payload.
- Matching is **case-insensitive** for every filter type.
- The `match` value accepts either a single string or an array of strings. An array behaves as OR — the filter matches if any of its values match.
- Setting `"exclude": true` inverts the result (NOT logic): the filter matches when the value does **not** match.
```json
{
"type": "event",
"match": ["push", "pull_request"],
"exclude": false
}
```
The route above matches both `push` and `pull_request` events.
## Pattern Syntax
Every filter type shares the same three pattern forms:
| Pattern | Meaning |
| ---------------------- | ------------------------------------------------------------- |
| `plain text` | Field filters: **exact** match. `keyword`: search anywhere. |
| `*` / `?` | **Glob wildcards** — `*` any run, `?` one char. |
| `/regular expression/` | Compiled as a **regular expression** (case-insensitive flag). |
- On field filters (`event`/`repo`/`actor`/`action`/`branch`), plain text and globs match the whole value; on `keyword` they search anywhere in the payload.
- Regexes always search: `/^feat/` matches values _starting_ with `feat`, `/feat/` matches anywhere.
Examples:
```json
{ "type": "event", "match": "pull_*" }
```
Matches `pull_request`, `pull_request_review`, `pull_request_review_comment`, ...
```json
{ "type": "repo", "match": "myorg/*" }
```
```json
{ "type": "branch", "match": "feature-?" }
```
Matches `feature-x`, `feature-1`, but not `feature-xy`.
```json
{ "type": "branch", "match": "/^feat/" }
```
Matches any branch whose name starts with `feat`.
> [!TIP]
> Globs and regular expressions are case-insensitive too, and `*` matches across `/` in repo names (`myorg/*` also matches `myorg/sub/backend`).
## Filter Types in Depth
### `event` — Event type
Matches the GitHub event name, e.g. `push`, `pull_request`, `issues`, `release`. Use this as the backbone of every route.
```json
{ "type": "event", "match": "release" }
```
Match several events with an array:
```json
{ "type": "event", "match": ["create", "delete"] }
```
### `repo` — Repository
Matches the repository **full name** (`owner/name`). Case-insensitive.
```json
{ "type": "repo", "match": "myorg/backend" }
```
Route multiple repositories to one channel:
```json
{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] }
```
### `actor` — Sender
Matches the **sender's GitHub login** that triggered the event (`sender.login` in the payload). Useful for ignoring bots.
```json
{ "type": "actor", "match": "dependabot[bot]", "exclude": true }
```
The route above fires for every event **except** those triggered by Dependabot.
### `action` — Event action
Matches the `action` field of the payload, e.g. `opened`, `closed`, `published`, `completed`. Not all events carry an action — see [Filter Compatibility](../events/supported#filter-compatibility). Combine it with `event` to narrow down a specific lifecycle step:
```json
{
"type": "event",
"match": "pull_request",
"exclude": false
},
{
"type": "action",
"match": ["opened", "reopened"]
}
```
This fires when a pull request is opened or reopened (and not on merge/close/edit).
### `branch` — Branch
Matches the branch involved in the event. What counts as "the branch" depends on the event type:
| Event | Branch extracted |
| --------------------------- | ------------------------------------------- |
| `push` | The branch that was pushed to |
| `pull_request` (and review) | The pull request's **head** (source) branch |
| `create` / `delete` | The created/deleted branch or tag |
| `workflow_run` | The `head_branch` the workflow ran on |
| `workflow_job` | The `head_branch` the job ran on |
| `check_suite` | The `head_branch` of the check suite |
| `deployment` | The deployment ref (strips `refs/heads/`) |
| `code_scanning_alert` | The branch the alert belongs to |
```json
{
"type": "event",
"match": "push"
},
{
"type": "branch",
"match": "main"
}
```
Fires for pushes to `main` only. To watch several long-lived branches:
```json
{ "type": "branch", "match": ["main", "develop"] }
```
> [!NOTE]
> `branch` matching is case-insensitive. Use globs (`feature/*`) or a `//`-wrapped regex (`/^release-/`) for prefix or wildcard-style matching.
### `keyword` — Text in the payload
Matches against the **full JSON payload**, lowercased. It is the most flexible filter: plain text searches anywhere, `*`/`?` globs search with wildcards, and `//`-wrapped patterns are compiled as regular expressions (with the `i` flag).
```json
{ "type": "keyword", "match": "deploy" }
```
Fires when the payload contains `deploy` anywhere. Because the payload is lowercased, this matches `Deploy`, `DEPLOY`, etc.
```json
{ "type": "keyword", "match": "*release-*" }
```
```json
{ "type": "keyword", "match": "/^(fix|hotfix)/" }
```
```json
{ "type": "keyword", "match": "/release-[0-9]+/" }
```
Behavior details:
- Patterns longer than 200 characters are **not** compiled as glob/regex and fall back to plain matching.
- A `//`-wrapped pattern that is not a valid regex matches **nothing** (the filter stays false) rather than erroring.
- To search for text that is a glob or regex special character (e.g. `v1.2.3`), rely on the plain-text form — a pattern without `*`, `?`, or `//` wrapping matches literally.
- The search covers the **entire** payload: commit messages, PR titles and bodies, labels, refs, even repository and sender names.
### Combining `exclude` with `keyword`
Just like the other filters, `exclude` inverts the keyword match:
```json
{ "type": "keyword", "match": "/wip|draft/", "exclude": true }
```
Skips events whose payload mentions `wip` or `draft`.
## Worked Example 1: PR alerts that skip bots and drafts
Forward pull request activity, but ignore bot authors and draft PRs, to a `#prs` channel:
```json
{
"id": "pr-notices",
"name": "PR Notices",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "pull_request" },
{ "type": "actor", "match": "dependabot[bot]", "exclude": true },
{ "type": "keyword", "match": "\"draft\": true", "exclude": true }
],
"target": { "channelId": "111111111111111111" }
}
```
The `"draft": true` pattern matches the `draft` field that GitHub includes in pull request payloads; combined with `exclude: true` it filters out draft PRs.
## Worked Example 2: Release-only channel
Forward only published releases from a specific repo:
```json
{
"id": "release-alerts",
"name": "Release Alerts",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "release" },
{ "type": "action", "match": "published" },
{ "type": "repo", "match": "myorg/backend" }
],
"target": { "channelId": "222222222222222222" }
}
```
## Worked Example 3: CI failures
Forward workflow runs that ended in failure on any branch, to a `#ci` channel:
```json
{
"id": "ci-failures",
"name": "CI Failures",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "workflow_run" },
{ "type": "action", "match": "completed" },
{ "type": "keyword", "match": "\"conclusion\":\"failure\"" }
],
"target": { "channelId": "333333333333333333" }
}
```
## Common Pitfalls
- **Wildcards are globs, not regex.** `repo: "myorg/*"` matches any repo under `myorg` (and `myorg/sub/backend`), but `repo: "myorg/.*"` matches literally. Use `//` wrapping for regex: `"/myorg\/.*/"`.
- **A `//`-wrapped invalid regex never matches.** Unlike plain text, an unwrapped invalid pattern is matched literally — wrap patterns only when they are real regular expressions.
- **An `action` filter on an action-less event never matches.** Check the event has an `action` field first (see [Filter Compatibility](../events/supported#filter-compatibility)).
- **`branch` on an event without a branch never matches.** A `branch` filter on an `issues` event will always be false. Use `keyword` if you need branch-like matching there.
- **`keyword` searches everything.** Because it scans the whole payload, a pattern like `"fix"` can match commit messages, issue titles, _and_ repository names. Be as specific as possible.
- **Forgetting `exclude` semantics.** `exclude: true` negates the whole filter — one non-matching value in an array does not "block" the route; the negated filter matches only when _none_ of the values match.

2
docs/guide/getting-started.md
View file

@ -63,7 +63,7 @@ curl http://localhost:8787/health
## Available Scripts
| Script | Description |
|------------------------|---------------------------------------------|
| ---------------------- | ------------------------------------------- |
| `bun run dev` | Start Nuxt dev server (HMR) |
| `bun run build` | Production build (cloudflare_module preset) |
| `bun run deploy` | Deploy to Cloudflare |

72
docs/zh/guide/configuration.md
View file

@ -2,13 +2,13 @@
本页是密钥与 Web 控制台的参考。核心概念在独立页面中说明：
| 主题 | 页面 |
|--------------------------------------------------|----------------------------------------------------------------------|
| 路由、目标、`fallback` / `stop`、身份组提醒 | [路由与目标](./routes) |
| 分组、角色、邀请、自助注册、日志频道 | [分组与访问控制](./groups) |
| Webhook 提供方、分组入口、自定义 webhook | [Webhook 接入与租户隔离](./ingress) |
| KV / D1 键布局 | [存储布局](./storage) |
| 过滤器（模式语法参考） | 下方[过滤器类型](#过滤器类型) / [过滤器教程](./filters) |
| 主题 | 页面 |
| ------------------------------------------- | ------------------------------------------------------- |
| 路由、目标、`fallback` / `stop`、身份组提醒 | [路由与目标](./routes) |
| 分组、角色、邀请、自助注册、日志频道 | [分组与访问控制](./groups) |
| Webhook 提供方、分组入口、自定义 webhook | [Webhook 接入与租户隔离](./ingress) |
| KV / D1 键布局 | [存储布局](./storage) |
| 过滤器（模式语法参考） | 下方[过滤器类型](#过滤器类型) / [过滤器教程](./filters) |
## 密钥
@ -16,14 +16,14 @@ WebHooker 的运行需要若干密钥。本地开发时放入 `.dev.vars`，生
### 必需密钥
| 变量 | 说明 |
|-------------------------|-------------------------------------------------------------------|
| `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 路由必需 |
| 变量 | 说明 |
| ----------------------- | ----------------------------------------------------------- |
| `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 **安装流程**
@ -33,19 +33,19 @@ WebHooker 的运行需要若干密钥。本地开发时放入 `.dev.vars`，生
### 可选密钥
| 变量 | 说明 | 默认值 |
|-----------------------------|--------------------------------------------------------------------------------------------------|-------------------------|
| `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` 页面展示的联系方式 | 未设置时显示占位文本 |
| 变量 | 说明 | 默认值 |
| --------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------- |
| `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 控制台
@ -65,14 +65,14 @@ WebHooker 在 `/admin` 提供内置配置控制台，可在浏览器中管理路
实操指南见[过滤器教程](./filters)，包含完整示例。
| 类型 | 匹配对象 | 示例 |
|-----------|------------------|--------------------------------------|
| `event` | GitHub 事件名称 | `push`, `pull_*`, `pull_request` |
| `repo` | 仓库全名 | `org/repo`, `org/*` |
| `actor` | 发送者登录名 | `username`, `[bot]`, `*[bot]` |
| `action` | 事件操作 | `opened`, `closed`, `published` |
| `branch` | 分支名称 | `main`, `feature-?`, `/^release-/` |
| `keyword` | 载荷正文中的文本 | `deploy`, `/fix\s+\d+/` |
| 类型 | 匹配对象 | 示例 |
| --------- | ---------------- | ---------------------------------- |
| `event` | GitHub 事件名称 | `push`, `pull_*`, `pull_request` |
| `repo` | 仓库全名 | `org/repo`, `org/*` |
| `actor` | 发送者登录名 | `username`, `[bot]`, `*[bot]` |
| `action` | 事件操作 | `opened`, `closed`, `published` |
| `branch` | 分支名称 | `main`, `feature-?`, `/^release-/` |
| `keyword` | 载荷正文中的文本 | `deploy`, `/fix\s+\d+/` |
### 过滤器行为

526
docs/zh/guide/filters.md
View file

@ -1,263 +1,263 @@
# 过滤器教程
过滤器决定哪些 Webhook 事件会被[路由](./routes)转发。只有当路由 `filters` 数组中的**每一个**过滤器都匹配时，路由才会触发（AND 逻辑）。本页是一份上手教程：解释每种过滤器类型的行为，以及如何组合它们实现真实场景的路由规则。
参考表格见配置指南的[过滤器类型](./configuration#过滤器类型)，完整事件列表见[支持的事件](../events/supported)。
## 匹配机制
- 路由中所有过滤器都必须匹配，否则该路由被跳过。
- 每个过滤器将事件与 Webhook 载荷的某个字段进行匹配。
- 所有过滤器类型都**不区分大小写**。
- `match` 值可以是单个字符串，也可以是字符串数组。数组相当于 OR——只要其中一个值匹配，该过滤器即匹配。
- 设置 `"exclude": true` 会反转结果（NOT 逻辑）：当值**不**匹配时，该过滤器才匹配。
```json
{
"type": "event",
"match": ["push", "pull_request"],
"exclude": false
}
```
上面这条路由同时匹配 `push` 和 `pull_request` 事件。
## 模式语法
所有过滤器类型共享以下三种模式写法：
| 模式 | 含义 |
| -------------- | ----------------------------------------------------------------- |
| `纯文本` | 字段过滤器：**完全相等**匹配；`keyword`：在载荷中任意位置搜索。 |
| `*` / `?` | **通配符（glob）**——`*` 任意长度、`?` 恰好一个字符。 |
| `/正则表达式/` | 按**正则表达式**编译（忽略大小写标志）。 |
- 字段过滤器（`event`/`repo`/`actor`/`action`/`branch`）的纯文本与通配符匹配整个值；`keyword` 则在载荷中任意位置搜索。
- 正则表达式始终是搜索语义：`/^feat/` 匹配以 `feat` **开头**的值，`/feat/` 匹配任意位置出现 `feat` 的值。
示例：
```json
{ "type": "event", "match": "pull_*" }
```
匹配 `pull_request`、`pull_request_review`、`pull_request_review_comment` 等。
```json
{ "type": "repo", "match": "myorg/*" }
```
```json
{ "type": "branch", "match": "feature-?" }
```
匹配 `feature-x`、`feature-1`，但不匹配 `feature-xy`。
```json
{ "type": "branch", "match": "/^feat/" }
```
匹配任何以 `feat` 开头的分支名。
> [!TIP]
> 通配符和正则同样不区分大小写，且 `*` 可以跨过仓库名中的 `/`（`myorg/*` 也能匹配 `myorg/sub/backend`）。
## 各过滤器类型详解
### `event` — 事件类型
匹配 GitHub 事件名称，如 `push`、`pull_request`、`issues`、`release`。它是每条路由的主干。
```json
{ "type": "event", "match": "release" }
```
用数组匹配多种事件：
```json
{ "type": "event", "match": ["create", "delete"] }
```
### `repo` — 仓库
匹配仓库**全名**（`owner/name`）。不区分大小写。
```json
{ "type": "repo", "match": "myorg/backend" }
```
将多个仓库路由到同一频道：
```json
{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] }
```
### `actor` — 发送者
匹配触发事件的 **GitHub 发送者登录名**（载荷中的 `sender.login`）。常用于忽略机器人。
```json
{ "type": "actor", "match": "dependabot[bot]", "exclude": true }
```
上面这条路由对**除** Dependabot 触发之外的所有事件都会触发。
### `action` — 事件操作
匹配载荷中的 `action` 字段，如 `opened`、`closed`、`published`、`completed`。并非所有事件都带有 action——参见[过滤器兼容性](../events/supported#过滤器兼容性)。与 `event` 组合可精确到某个生命周期步骤：
```json
{
"type": "event",
"match": "pull_request",
"exclude": false
},
{
"type": "action",
"match": ["opened", "reopened"]
}
```
上面的规则在拉取请求被打开或重新打开时触发（合并/关闭/编辑时不触发）。
### `branch` — 分支
匹配事件涉及的分支。何种字段算作「分支」取决于事件类型：
| 事件 | 提取的分支 |
| --------------------------- | ----------------------------------- |
| `push` | 推送到的目标分支 |
| `pull_request`（及 review） | 拉取请求的 **head**（源）分支 |
| `create` / `delete` | 创建/删除的分支或标签 |
| `workflow_run` | 工作流运行所在的 `head_branch` |
| `workflow_job` | 作业运行所在的 `head_branch` |
| `check_suite` | 检查套件的 `head_branch` |
| `deployment` | 部署引用（去除 `refs/heads/` 前缀） |
| `code_scanning_alert` | 告警所属的分支 |
```json
{
"type": "event",
"match": "push"
},
{
"type": "branch",
"match": "main"
}
```
仅当推送到 `main` 时触发。要关注多个长期分支：
```json
{ "type": "branch", "match": ["main", "develop"] }
```
> [!NOTE]
> `branch` 匹配不区分大小写。需要前缀或通配符式匹配时，可直接使用通配符（`feature/*`）或用 `/` 包裹正则（`/^release-/`）。
### `keyword` — 载荷中的文本
匹配整个 JSON 载荷（转为小写）。它是最灵活的过滤器：纯文本在任意位置搜索，`*`/`?` 通配符带通配搜索，`//` 包裹的模式按正则表达式编译（带 `i` 标志）。
```json
{ "type": "keyword", "match": "deploy" }
```
当载荷中任意位置包含 `deploy` 时触发。由于载荷已被转为小写，`Deploy`、`DEPLOY` 等都会匹配。
```json
{ "type": "keyword", "match": "*release-*" }
```
```json
{ "type": "keyword", "match": "/^(fix|hotfix)/" }
```
```json
{ "type": "keyword", "match": "/release-[0-9]+/" }
```
行为细节：
- 超过 200 个字符的模式**不**编译为通配符/正则，回退为纯文本匹配。
- 被 `/` 包裹但**不是合法正则**的模式匹配**任何内容都不命中**（过滤器恒为 false），而不会报错。
- 要搜索是通配符或正则特殊字符的文本（如 `v1.2.3`），使用纯文本形式即可——不含 `*`、`?` 且未被 `//` 包裹的模式按字面匹配。
- 搜索覆盖**整个**载荷：提交信息、PR 标题与正文、标签、引用，甚至仓库名和发送者名。
### `keyword` 与 `exclude` 组合
与其他过滤器一样，`exclude` 会反转关键词匹配：
```json
{ "type": "keyword", "match": "/wip|draft/", "exclude": true }
```
跳过载荷中提及 `wip` 或 `draft` 的事件。
## 示例 1：PR 通知，跳过机器人和草稿
转发拉取请求动态，但忽略机器人作者和草稿 PR，发往 `#prs` 频道：
```json
{
"id": "pr-notices",
"name": "PR Notices",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "pull_request" },
{ "type": "actor", "match": "dependabot[bot]", "exclude": true },
{ "type": "keyword", "match": "\"draft\": true", "exclude": true }
],
"target": { "channelId": "111111111111111111" }
}
```
`"draft": true` 模式匹配 GitHub 在拉取请求载荷中包含的 `draft` 字段；配合 `exclude: true` 即可过滤掉草稿 PR。
## 示例 2：仅发布通知频道
只转发特定仓库的已发布 release：
```json
{
"id": "release-alerts",
"name": "Release Alerts",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "release" },
{ "type": "action", "match": "published" },
{ "type": "repo", "match": "myorg/backend" }
],
"target": { "channelId": "222222222222222222" }
}
```
## 示例 3：CI 失败
转发任意分支上以失败结束的 workflow run，发往 `#ci` 频道：
```json
{
"id": "ci-failures",
"name": "CI Failures",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "workflow_run" },
{ "type": "action", "match": "completed" },
{ "type": "keyword", "match": "\"conclusion\":\"failure\"" }
],
"target": { "channelId": "333333333333333333" }
}
```
## 常见陷阱
- **通配符是 glob，不是正则。** `repo: "myorg/*"` 匹配 `myorg` 下的任意仓库（含 `myorg/sub/backend`），但 `repo: "myorg/.*"` 按字面匹配。需要正则请用 `/` 包裹：`"/myorg\/.*/"`。
- **被 `/` 包裹的非法正则永远不匹配。** 与纯文本不同——未包裹的非法模式按字面匹配。只有确定是真正的正则时才使用 `//` 包裹。
- **`action` 过滤器遇到无 action 的事件永远不匹配。** 先确认该事件带有 `action` 字段（见[过滤器兼容性](../events/supported#过滤器兼容性)）。
- **`branch` 过滤器遇到无分支的事件永远不匹配。** 在 `issues` 事件上使用 `branch` 过滤器恒为假。此时需要类似分支的匹配可用 `keyword`。
- **`keyword` 会搜索一切。** 因为它扫描整个载荷，`"fix"` 这样的模式可能同时匹配提交信息、issue 标题和仓库名。请尽量写得更具体。
- **牢记 `exclude` 语义。** `exclude: true` 反转的是整个过滤器——数组中的一个值不匹配并不会「阻断」路由；只有当**所有**值都不匹配时，取反后的过滤器才匹配。
# 过滤器教程
过滤器决定哪些 Webhook 事件会被[路由](./routes)转发。只有当路由 `filters` 数组中的**每一个**过滤器都匹配时，路由才会触发（AND 逻辑）。本页是一份上手教程：解释每种过滤器类型的行为，以及如何组合它们实现真实场景的路由规则。
参考表格见配置指南的[过滤器类型](./configuration#过滤器类型)，完整事件列表见[支持的事件](../events/supported)。
## 匹配机制
- 路由中所有过滤器都必须匹配，否则该路由被跳过。
- 每个过滤器将事件与 Webhook 载荷的某个字段进行匹配。
- 所有过滤器类型都**不区分大小写**。
- `match` 值可以是单个字符串，也可以是字符串数组。数组相当于 OR——只要其中一个值匹配，该过滤器即匹配。
- 设置 `"exclude": true` 会反转结果（NOT 逻辑）：当值**不**匹配时，该过滤器才匹配。
```json
{
"type": "event",
"match": ["push", "pull_request"],
"exclude": false
}
```
上面这条路由同时匹配 `push` 和 `pull_request` 事件。
## 模式语法
所有过滤器类型共享以下三种模式写法：
| 模式 | 含义 |
| -------------- | --------------------------------------------------------------- |
| `纯文本` | 字段过滤器：**完全相等**匹配；`keyword`：在载荷中任意位置搜索。 |
| `*` / `?` | **通配符（glob）**——`*` 任意长度、`?` 恰好一个字符。 |
| `/正则表达式/` | 按**正则表达式**编译（忽略大小写标志）。 |
- 字段过滤器（`event`/`repo`/`actor`/`action`/`branch`）的纯文本与通配符匹配整个值；`keyword` 则在载荷中任意位置搜索。
- 正则表达式始终是搜索语义：`/^feat/` 匹配以 `feat` **开头**的值，`/feat/` 匹配任意位置出现 `feat` 的值。
示例：
```json
{ "type": "event", "match": "pull_*" }
```
匹配 `pull_request`、`pull_request_review`、`pull_request_review_comment` 等。
```json
{ "type": "repo", "match": "myorg/*" }
```
```json
{ "type": "branch", "match": "feature-?" }
```
匹配 `feature-x`、`feature-1`，但不匹配 `feature-xy`。
```json
{ "type": "branch", "match": "/^feat/" }
```
匹配任何以 `feat` 开头的分支名。
> [!TIP]
> 通配符和正则同样不区分大小写，且 `*` 可以跨过仓库名中的 `/`（`myorg/*` 也能匹配 `myorg/sub/backend`）。
## 各过滤器类型详解
### `event` — 事件类型
匹配 GitHub 事件名称，如 `push`、`pull_request`、`issues`、`release`。它是每条路由的主干。
```json
{ "type": "event", "match": "release" }
```
用数组匹配多种事件：
```json
{ "type": "event", "match": ["create", "delete"] }
```
### `repo` — 仓库
匹配仓库**全名**（`owner/name`）。不区分大小写。
```json
{ "type": "repo", "match": "myorg/backend" }
```
将多个仓库路由到同一频道：
```json
{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] }
```
### `actor` — 发送者
匹配触发事件的 **GitHub 发送者登录名**（载荷中的 `sender.login`）。常用于忽略机器人。
```json
{ "type": "actor", "match": "dependabot[bot]", "exclude": true }
```
上面这条路由对**除** Dependabot 触发之外的所有事件都会触发。
### `action` — 事件操作
匹配载荷中的 `action` 字段，如 `opened`、`closed`、`published`、`completed`。并非所有事件都带有 action——参见[过滤器兼容性](../events/supported#过滤器兼容性)。与 `event` 组合可精确到某个生命周期步骤：
```json
{
"type": "event",
"match": "pull_request",
"exclude": false
},
{
"type": "action",
"match": ["opened", "reopened"]
}
```
上面的规则在拉取请求被打开或重新打开时触发（合并/关闭/编辑时不触发）。
### `branch` — 分支
匹配事件涉及的分支。何种字段算作「分支」取决于事件类型：
| 事件 | 提取的分支 |
| --------------------------- | ----------------------------------- |
| `push` | 推送到的目标分支 |
| `pull_request`（及 review） | 拉取请求的 **head**（源）分支 |
| `create` / `delete` | 创建/删除的分支或标签 |
| `workflow_run` | 工作流运行所在的 `head_branch` |
| `workflow_job` | 作业运行所在的 `head_branch` |
| `check_suite` | 检查套件的 `head_branch` |
| `deployment` | 部署引用（去除 `refs/heads/` 前缀） |
| `code_scanning_alert` | 告警所属的分支 |
```json
{
"type": "event",
"match": "push"
},
{
"type": "branch",
"match": "main"
}
```
仅当推送到 `main` 时触发。要关注多个长期分支：
```json
{ "type": "branch", "match": ["main", "develop"] }
```
> [!NOTE]
> `branch` 匹配不区分大小写。需要前缀或通配符式匹配时，可直接使用通配符（`feature/*`）或用 `/` 包裹正则（`/^release-/`）。
### `keyword` — 载荷中的文本
匹配整个 JSON 载荷（转为小写）。它是最灵活的过滤器：纯文本在任意位置搜索，`*`/`?` 通配符带通配搜索，`//` 包裹的模式按正则表达式编译（带 `i` 标志）。
```json
{ "type": "keyword", "match": "deploy" }
```
当载荷中任意位置包含 `deploy` 时触发。由于载荷已被转为小写，`Deploy`、`DEPLOY` 等都会匹配。
```json
{ "type": "keyword", "match": "*release-*" }
```
```json
{ "type": "keyword", "match": "/^(fix|hotfix)/" }
```
```json
{ "type": "keyword", "match": "/release-[0-9]+/" }
```
行为细节：
- 超过 200 个字符的模式**不**编译为通配符/正则，回退为纯文本匹配。
- 被 `/` 包裹但**不是合法正则**的模式匹配**任何内容都不命中**（过滤器恒为 false），而不会报错。
- 要搜索是通配符或正则特殊字符的文本（如 `v1.2.3`），使用纯文本形式即可——不含 `*`、`?` 且未被 `//` 包裹的模式按字面匹配。
- 搜索覆盖**整个**载荷：提交信息、PR 标题与正文、标签、引用，甚至仓库名和发送者名。
### `keyword` 与 `exclude` 组合
与其他过滤器一样，`exclude` 会反转关键词匹配：
```json
{ "type": "keyword", "match": "/wip|draft/", "exclude": true }
```
跳过载荷中提及 `wip` 或 `draft` 的事件。
## 示例 1：PR 通知，跳过机器人和草稿
转发拉取请求动态，但忽略机器人作者和草稿 PR，发往 `#prs` 频道：
```json
{
"id": "pr-notices",
"name": "PR Notices",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "pull_request" },
{ "type": "actor", "match": "dependabot[bot]", "exclude": true },
{ "type": "keyword", "match": "\"draft\": true", "exclude": true }
],
"target": { "channelId": "111111111111111111" }
}
```
`"draft": true` 模式匹配 GitHub 在拉取请求载荷中包含的 `draft` 字段；配合 `exclude: true` 即可过滤掉草稿 PR。
## 示例 2：仅发布通知频道
只转发特定仓库的已发布 release：
```json
{
"id": "release-alerts",
"name": "Release Alerts",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "release" },
{ "type": "action", "match": "published" },
{ "type": "repo", "match": "myorg/backend" }
],
"target": { "channelId": "222222222222222222" }
}
```
## 示例 3：CI 失败
转发任意分支上以失败结束的 workflow run，发往 `#ci` 频道：
```json
{
"id": "ci-failures",
"name": "CI Failures",
"enabled": true,
"groupId": "eng",
"filters": [
{ "type": "event", "match": "workflow_run" },
{ "type": "action", "match": "completed" },
{ "type": "keyword", "match": "\"conclusion\":\"failure\"" }
],
"target": { "channelId": "333333333333333333" }
}
```
## 常见陷阱
- **通配符是 glob，不是正则。** `repo: "myorg/*"` 匹配 `myorg` 下的任意仓库（含 `myorg/sub/backend`），但 `repo: "myorg/.*"` 按字面匹配。需要正则请用 `/` 包裹：`"/myorg\/.*/"`。
- **被 `/` 包裹的非法正则永远不匹配。** 与纯文本不同——未包裹的非法模式按字面匹配。只有确定是真正的正则时才使用 `//` 包裹。
- **`action` 过滤器遇到无 action 的事件永远不匹配。** 先确认该事件带有 `action` 字段（见[过滤器兼容性](../events/supported#过滤器兼容性)）。
- **`branch` 过滤器遇到无分支的事件永远不匹配。** 在 `issues` 事件上使用 `branch` 过滤器恒为假。此时需要类似分支的匹配可用 `keyword`。
- **`keyword` 会搜索一切。** 因为它扫描整个载荷，`"fix"` 这样的模式可能同时匹配提交信息、issue 标题和仓库名。请尽量写得更具体。
- **牢记 `exclude` 语义。** `exclude: true` 反转的是整个过滤器——数组中的一个值不匹配并不会「阻断」路由；只有当**所有**值都不匹配时，取反后的过滤器才匹配。