mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
* fix(nuxt): pre-bundle the CommonJS deps of the markdown stack
`debug` and `extend` are imported by micromark and unified through
@elysola/ui. Served unbundled by the dev server they have no default
export, so the console page failed with a 500 in `nuxt dev`.
* docs(deployment): list the fragments and feishu link migrations
The manual `d1 execute` fallback stopped at 0008, and AGENTS.md named
0001..0010 although 0011 already exists.
* feat(storage): persist the per-group route order
Routes used to load in id order, so the order saved from the console
was lost on the next read. Migration 0012 adds `d1_routes.position`:
saving writes each route's index within its own group (saving one group
never shifts another), and routes load by `group_id, position, id`.
A database without the column keeps working: only a "no such column" /
"has no column named" error falls back to the legacy statements, and
nothing is cached, so a later migration is picked up on the next call.
* feat(console): add in-app destructive-action confirmation
Deleting a route or a group used `window.confirm`, which blocks the page
and ignores the console theme. A promise-based `useConfirm()` now drives
one <ConfirmDialog /> built on the reka-ui AlertDialog that
@elysola/ui ships; reka-ui is pre-bundled so dev keeps a single copy and
the dialog stacks with the Rc dialogs.
A request never outlives its asker: one made after the asking component
unmounted resolves false, and one still open when it unmounts is
cancelled.
* feat(console): confirm member and webhook removal
Removing a member, revoking an invite link and disabling a group's
webhook endpoint took effect on the first click. They now ask first;
disabling the webhook explains that senders still using the secret will
be rejected, and its button is styled as destructive.
* feat(console): confirm removing filled editor rows
Filter conditions and groups, delivery targets, saved fragments and forge
hosts vanished on a single click, taking whatever had been typed with
them. Rows holding content now ask first, while empty, never-filled
rows (`isBlankNode`: default operator, no path, no values, not negated)
are still removed directly.
* fix(i18n): remove duplicate button glyphs
"New Route", "New Group" and the group cards' "Open" link render a Plus
or ArrowRight icon next to their label, so the "+" and "→" baked into
the strings appeared twice.
* style(console): redesign route cards for narrow screens
The card was one flex row whose badges, filter chips, targets and five
hand-drawn icon buttons squeezed the route name on small screens. It is
now a grid driven by a container query: name and actions share the top
line, the filter summary (clamped to two lines) and targets follow, and
the tags wrap below; from 40rem the tags move up beside the title.
Targets of the same platform collapse into one tag with a count, long
ids truncate instead of widening the page, and the actions use lucide
icons with accessible labels.
* feat(console): reorder a group's routes by drag or keyboard
The per-card up/down arrows saved after every single step, so moving a
route five places took five writes. A Reorder mode on the group page now
swaps each card's switch for a drag handle: pointer drags (mouse and
touch) slide the neighbours out of the way and auto-scroll near the
viewport edges, Arrow Up/Down on a focused handle moves a card by one
and is announced to screen readers, and nothing is written until Save
order. Cancel or Escape (unless a dialog or list owns it) drops the
draft.
The cards move into a new RouteList component that owns the drag state.
* style(members): align member cards and invite actions
* style(group-editor): size forge and log target controls
Keep source hosts, platform selectors and remove actions aligned without stretching short controls across the dialog. Wrap component roots explicitly so their internal markup cannot break the grid.
* style(route-editor): group options and delivery target fields
Give each target labeled fields and a compact platform header, widen the filter workspace, and align fragment controls. Scroll failed validation into view when the footer is far from the affected section.
* feat(filters): add bilingual suggestions and value validation
Catalog forge events, actions, payload paths and known values with searchable English and Chinese descriptions. Match-value validation mirrors the server and only rejects inputs that cannot match.
* feat(filters): add searchable creatable value inputs
Build a theme-aligned combobox on the shared reka-ui primitives. Rank stored keys before bilingual descriptions, allow validated custom values, and preserve unconfirmed multi-value drafts instead of silently committing them.
* feat(filter-editor): integrate searchable condition inputs
Replace chip-only values with context-aware bilingual inputs and a compact condition grid. Preserve drafts across tree changes, block saves and tests until drafts are resolved, and keep keyword filters free of hidden operators.
* feat(filters): split pasted values without breaking regexes
Accept multiple values separated by commas or lines while retaining commas inside wrapped expressions and raw regex patterns. Pasting replaces the selected range and keeps rejected values as an explicit draft.
* fix(filters): adapt suggestions to the selected operator
Offer literal prefixes and suffixes for substring operators, escaped anchored patterns for regex, and numeric suggestions only for comparisons. Suggestion syntax must mean what the selected matcher actually reads.
* fix(filters): preserve regex meaning when changing operators
Swap wrapped and raw regex sources only when both compile identically after saving. Leave literal, glob, multiline and Unicode-sensitive comparisons unchanged rather than inventing non-equivalent conversions.
* a11y(filter-editor): label type and operator controls
Associate each fixed select with a stable per-condition label while keeping the compact visual layout unchanged.
* fix(editors): ignore accidental backdrop dismissal
Do not discard unsaved route or group edits when the user clicks outside the dialog. Preserve Escape, Cancel and explicit close, including popovers and confirmation dialogs stacked above the editor.
* feat(dispatch)!: scope stop and fallback to each group
A match in one group must not suppress delivery in another group. Track regular matches and stopped scopes independently, and document the routing-table boundary.
BREAKING CHANGE: stop and fallback no longer apply globally across
groups. Put mutually exclusive routes in the same group and define
fallback routes in each group that needs its own catch-all.
* fix(dispatch): honor stop on a matching fallback route
Once a fallback matches with stop enabled, skip later routes of the same group without affecting other groups. Cover multiple fallback routes in the group-isolation regression test.
* style(console): pin theme and language controls to the right
Separate utility controls from page actions so narrow screens retain a readable title column and right-aligned actions below. Wrap long headings without letting them push controls out of view.
* style(groups): place creation beside the aligned group count
Keep the new-group action inside the group list at every width and align the label and count on one baseline with a consistent type scale.
* style(groups): align card footers and keep role badges intact
Give long names two lines, show the current role in its own non-wrapping row, and anchor every card footer to the grid-row bottom regardless of optional source metadata.
* style(logs): prevent filter labels and metadata overflow
Keep filter labels on one line and allow long channel, thread and repository identifiers to wrap instead of widening the page.
* style(console): scale the sidebar and hide mobile tab tracks
Narrow the sidebar proportionally while retaining enough room for both locales. Keep mobile navigation swipeable without a visible horizontal scrollbar.
* feat(console): give each group its own routes URL
Resolve the selected group from /admin/groups/{groupId}, validate console paths, and use browser history for back navigation. Keep Groups active and let an active mobile-tab tap return to the list. Scope pending route loads to their group and retain the count beside long headings.
* feat(console): confirm leaving unsaved page work
Guard route changes when an editor or changed order draft is open. Cancel superseded questions and restore the shown history entry when repeated Back or Forward navigation is refused; only completed navigation resets page work.
* feat(console): confirm sign-out from desktop and mobile
Expose sign-out in the mobile topbar when the sidebar is hidden. Both entry points use the in-app confirmation before navigating to the server logout endpoint.
* fix(console): keep topbar tools clear of very narrow headings
Below 360px, place the full-width heading beneath the breadcrumb and utility row so the three top-right buttons cannot overlap it.
* feat(console): prioritize group titles over actions
Place New Route after Reorder in the group bar. Measure available space and remove the reorder label first, then the creation label, before truncating the group title; remeasure on resize, locale and font changes.
* fix(editors): focus the dialog without selecting its name field
Cancel the non-bubbling FocusScope mount event in the capture phase and focus the dialog itself. Keep keyboard navigation working without highlighting the name or opening the touch keyboard automatically.
* perf(console): preserve one instance across admin navigation
Use a fixed page key instead of remounting the whole console for each URL. Refresh each view when shown and isolate overview metrics and logs so page filters cannot leak into the dashboard.
* fix(console-data): discard superseded load responses
Only the latest request may update a list, its error or loading state. Invalidate pending group loads after a save so an older response cannot restore stale configuration during persistent-console navigation.
* fix(routes): serialize writes and reject unloaded route lists
Whole-list saves must start from loaded data and wait for other route writes. Lock switches and actions during saves, recheck deletion after confirmation, and rebuild saved ordering from the newest route objects.
* fix(editors): scope async results and fragment writes to sessions
A completed save or dry run must not close or overwrite a newer editor. Keep fragment state scoped by group, reject writes until the real list is ready, and retain in-flight fragment locks across navigation.
* fix(groups): serialize edits and isolate group detail panels
Prevent overlapping whole-list writes, avoid duplicate ids after rename, and discard delete confirmations prepared on a page that has since been left. Key member and webhook panels by group so local state cannot cross tenants.
* fix(console): omit the empty action row outside overview
Render the refresh-action container only where it has content so narrow layouts do not reserve a blank row after creation controls move into their page bars.
* perf(metrics): send all seven queries in one D1 batch
Avoid seven sequential network round trips and read totals, breakdowns and recent failures in one consistent transaction. Reuse the failed-send statement and row mapping while retaining group scoping.
* fix(admin-api): bypass browser cache locks for live requests
Use no-store on both client requests and admin responses. Personalized live data must not be reused, and one stalled same-URL cache entry must not block later log requests behind the browser cache lock.
* docs(routes): Clarify fallback hints and document group-scoped stop and fallback upgrade behavior
106 lines
9.2 KiB
Markdown
106 lines
9.2 KiB
Markdown
# 配置
|
||
|
||
本页是密钥与 Web 控制台的参考。核心概念在独立页面中说明:
|
||
|
||
| 主题 | 页面 |
|
||
| ------------------------------------------- | ------------------------------------------------------- |
|
||
| 路由、目标、`fallback` / `stop`、身份组提醒 | [路由与目标](./routes) |
|
||
| 分组、角色、邀请、自助注册、日志频道 | [分组与访问控制](./groups) |
|
||
| Webhook 提供方、分组入口、自定义 webhook | [Webhook 接入与租户隔离](./ingress) |
|
||
| KV / D1 键布局 | [存储布局](./storage) |
|
||
| 过滤器(模式语法参考) | 下方[过滤器类型](#过滤器类型) / [过滤器教程](./filters) |
|
||
|
||
## 密钥
|
||
|
||
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 路由必需 |
|
||
| `FEISHU_APP_ID` | 飞书应用 ID(应用凭证页获取)—— 飞书路由必需 |
|
||
| `FEISHU_APP_SECRET` | 飞书应用密钥 —— 飞书路由必需 |
|
||
|
||
> [!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 关闭 |
|
||
| `DEBUG_MODE` | 仅本地开发:精确设为 `true` 时跳过全部 `/admin` 身份验证并授予完整权限 | 关闭 |
|
||
| `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 与管理员白名单保护。
|
||
|
||
### 设置
|
||
|
||
1. 配置 `ADMIN_USER_IDS`,填写允许管理一切的 GitHub 用户 ID,也支持登录名,例如 `ADMIN_USER_IDS=12345,RhenCloud`。未设置时控制台禁用(除非开启 `ALLOW_SELF_SIGNUP`)。
|
||
2. 打开 `/admin` 并使用 GitHub 登录。
|
||
3. 没有任何访问权限的用户会得到 `403`,除非 `ALLOW_SELF_SIGNUP=1`(获得个人分组)或跟随分组[邀请链接](./groups#邀请)。
|
||
|
||
仅供本地调试:设置 `DEBUG_MODE=true` 可跳过 GitHub OAuth,并授予完整控制台权限。部署环境切勿设置此变量。
|
||
|
||
控制台以 SPA 形式在 `/admin` 提供;其标签页可通过 URL 路径直达(`/admin/groups`、`/admin/logs`、`/admin/audit`),每个分组的路由页也有独立 URL(`/admin/groups/{groupId}`)。各页面都会记入浏览器历史:从分组返回分组列表请使用浏览器(或设备)自带的返回;若页面上有打开的编辑器或未保存的路由顺序,离开前会先确认。未知的控制台路径显示控制台的 404 页面。`/admin` 之外未匹配到端点的 URL 直接返回 `404`,而不会展示控制台。
|
||
|
||
删除类操作——删除路由、分组、过滤条件、片段、目标或来源主机,移除成员,撤销邀请,停用分组 webhook——都会先弹出应用内确认框(从未填写过的空行直接删除)。路由与分组编辑弹窗点击遮罩不会关闭,避免丢失未保存的内容;请用「取消」、✕ 或 <kbd>Esc</kbd> 关闭。
|
||
|
||
所有管理端点(`/admin/api/*`)见 [Admin API](../api/admin)。保存的路由和分组会立即持久化到 D1(`d1_routes` / `d1_groups`),并使 KV 缓存失效、刷新配置缓存,下一次 webhook 处理即会生效。
|
||
|
||
## 过滤器类型
|
||
|
||
实操指南见[过滤器教程](./filters),包含完整示例。
|
||
|
||
| 类型 | 匹配对象 | 示例 |
|
||
| --------- | ------------------------ | ---------------------------------- |
|
||
| `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`——见[过滤器教程](./filters#操作符)
|
||
- `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 事件
|
||
|
||
### 匹配值
|
||
|
||
过滤器接受单个字符串或字符串数组:
|
||
|
||
```json
|
||
{ "type": "event", "match": "push" }
|
||
{ "type": "event", "match": ["push", "pull_request"] }
|
||
{ "type": "field", "path": "pull_request.commits", "op": "gt", "match": "1" }
|
||
```
|