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

chore: auto-fix lint & formatting [skip ci]

Browse source
This commit is contained in:
github-actions[bot] 2026-08-13 22:46:35 +00:00
parent 6f1a334150
commit 811f8646e0
26 changed files with 304 additions and 306 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.zh.md
View file

@ -54,7 +54,7 @@ bunx wrangler dev # 启动本地开发服务器
### 密钥（本地用 `.dev.vars`，生产用 Worker Secrets） ### 密钥（本地用 `.dev.vars`，生产用 Worker Secrets）
| 变量 | 说明 | | 变量 | 说明 |
|-----------------------------|-----------------------------------------------------------------------------| | --------------------------- | --------------------------------------------------------------------------- |
| `GITHUB_WEBHOOK_SECRET` | GitHub webhook 密钥 | | `GITHUB_WEBHOOK_SECRET` | GitHub webhook 密钥 |
| `GITEA_WEBHOOK_SECRET` | Gitea webhook 密钥（仅接收 Gitea webhook 时需要） | | `GITEA_WEBHOOK_SECRET` | Gitea webhook 密钥（仅接收 Gitea webhook 时需要） |
| `GITHUB_APP_ID` | GitHub App ID（用于 App 安装流程解析安装所属账号） | | `GITHUB_APP_ID` | GitHub App ID（用于 App 安装流程解析安装所属账号） |

4
docs-plan.md
View file

@ -8,7 +8,7 @@
## 一、现状总览 ## 一、现状总览
| 文档 | 规模 | 状态 | | 文档 | 规模 | 状态 |
|---|---|---| | -------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
| `docs/`（VitePress，en+zh 镜像） | 11 页 ×2，约 75KB | 结构完整但存在事实错误、覆盖缺失、信息架构混乱 | | `docs/`（VitePress，en+zh 镜像） | 11 页 ×2，约 75KB | 结构完整但存在事实错误、覆盖缺失、信息架构混乱 |
| `README.md` / `README.zh.md` | 363 行 | 与 docs 大量重复（secrets、GitHub App 设置、部署），已出现漂移 | | `README.md` / `README.zh.md` | 363 行 | 与 docs 大量重复（secrets、GitHub App 设置、部署），已出现漂移 |
| `AGENTS.md` | 222 行 | 基本同步，个别过时 | | `AGENTS.md` | 222 行 | 基本同步，个别过时 |
@ -109,7 +109,7 @@
## 五、中英一致性（zh 滞后） ## 五、中英一致性（zh 滞后）
| 严重度 | 文件 | 差异 | | 严重度 | 文件 | 差异 |
|---|---|---| | ------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
| 高 | guide/introduction.md | zh 技术栈仍是"Nux3 静态 SPA"，en 已为"Nuxt 4 (Vue 3 + Tailwind CSS v3)" | | 高 | guide/introduction.md | zh 技术栈仍是"Nux3 静态 SPA"，en 已为"Nuxt 4 (Vue 3 + Tailwind CSS v3)" |
| 高 | guide/getting-started.md | zh 脚本表缺 `bun run build`、`bun test` 两行；`bun run dev` 描述不一致（wrangler vs Nuxt HMR） | | 高 | guide/getting-started.md | zh 脚本表缺 `bun run build`、`bun test` 两行；`bun run dev` 描述不一致（wrangler vs Nuxt HMR） |
| 中 | api/overview.md | zh 漏"or manage a group"准入条件；漏"空过滤器仅 fallback 路由允许" | | 中 | api/overview.md | zh 漏"or manage a group"准入条件；漏"空过滤器仅 fallback 路由允许" |

2
docs/api/admin.md
View file

@ -7,7 +7,7 @@ The console itself is served at `/admin`; its tabs are deep-linkable via the URL
## Endpoints ## Endpoints
| Endpoint | Description | | Endpoint | Description |
|-------------------------------------------------|-------------------------------------------------------------------| | ----------------------------------------------- | ----------------------------------------------------------------- |
| `GET /admin` | Config console UI | | `GET /admin` | Config console UI |
| `GET /admin/login` | Start admin sign-in (GitHub OAuth) | | `GET /admin/login` | Start admin sign-in (GitHub OAuth) |
| `GET /admin/logout` | Sign out and destroy the session | | `GET /admin/logout` | Sign out and destroy the session |

8
docs/api/overview.md
View file

@ -11,7 +11,7 @@ https://your-worker.workers.dev
## Endpoints ## Endpoints
| Method | Path | Auth | Description | | Method | Path | Auth | Description |
|----------|---------------------------------|-------------------|--------------------------------------------------------------------| | -------- | --------------------------- | ----------------- | ------------------------------------------------------------------ |
| `GET` | `/health` | None | Health check | | `GET` | `/health` | None | Health check |
| `POST` | `/webhook` | HMAC signature | GitHub / Gitea / custom webhook ingestion (provider auto-detected) | | `POST` | `/webhook` | HMAC signature | GitHub / Gitea / custom webhook ingestion (provider auto-detected) |
| `POST` | `/webhook/:groupId` | Per-group secret | Per-group webhook ingress (only that group's routes fire) | | `POST` | `/webhook/:groupId` | Per-group secret | Per-group webhook ingress (only that group's routes fire) |
@ -63,7 +63,7 @@ Accepts GitHub webhook payloads. Requires valid `X-Hub-Signature-256` header.
**Headers:** **Headers:**
| Header | Required | Description | | Header | Required | Description |
|-------------------------|------------|----------------------------------------------------| | --------------------- | -------- | ------------------------------------------------ |
| `X-Hub-Signature-256` | Yes | HMAC-SHA256 signature | | `X-Hub-Signature-256` | Yes | HMAC-SHA256 signature |
| `X-GitHub-Event` | Yes | Event type name | | `X-GitHub-Event` | Yes | Event type name |
| `X-GitHub-Delivery` | No | Unique delivery ID (used for dedup when present) | | `X-GitHub-Delivery` | No | Unique delivery ID (used for dedup when present) |
@ -83,7 +83,7 @@ When `X-GitHub-Delivery` is present and the same delivery was already processed
**Error Responses:** **Error Responses:**
| Status | Body | Cause | | Status | Body | Cause |
|----------|------------------------------------|------------------------------------------| | ------ | -------------------------------- | -------------------------------------- |
| `401` | `{"error": "Invalid signature"}` | Signature verification failed | | `401` | `{"error": "Invalid signature"}` | Signature verification failed |
| `400` | `{"error": "Invalid event"}` | Missing event header or malformed body | | `400` | `{"error": "Invalid event"}` | Missing event header or malformed body |
| `413` | `{"error": "Request too large"}` | Body exceeds 1MB limit | | `413` | `{"error": "Request too large"}` | Body exceeds 1MB limit |
@ -103,7 +103,7 @@ Any JSON payload signed with `X-WebHooker-Signature: sha256=<hex>` (HMAC-SHA256
The primary flow is the App's **Setup URL** — set it to `{BASE_URL}/auth/github/install`. After a user installs the App, the browser lands on: The primary flow is the App's **Setup URL** — set it to `{BASE_URL}/auth/github/install`. After a user installs the App, the browser lands on:
| Method | Path | Description | | Method | Path | Description |
|----------|-------------------------------|--------------------------------------------------------------------------------------------------| | ------ | --------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET` | `/auth/github/install` | Choice page: bind the installation to a new group or an existing group the signed-in user owns | | `GET` | `/auth/github/install` | Choice page: bind the installation to a new group or an existing group the signed-in user owns |
| `POST` | `/auth/github/install/bind` | Provisions the binding (owner role re-checked) and redirects to `/admin?install=ok` | | `POST` | `/auth/github/install/bind` | Provisions the binding (owner role re-checked) and redirects to `/admin?install=ok` |

6
docs/events/supported.md
View file

@ -5,7 +5,7 @@ WebHooker supports 28 GitHub webhook event types, each with a dedicated formatte
## Events Table ## Events Table
| Event | Description | Embed Highlights | | Event | Description | Embed Highlights |
|---------------------------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------| | ----------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `push` | Code pushed to a branch | Commit list, branch, author, diff stats | | `push` | Code pushed to a branch | Commit list, branch, author, diff stats |
| `pull_request` | PR opened/closed/merged/edited | PR title, branch, diff stats, labels | | `pull_request` | PR opened/closed/merged/edited | PR title, branch, diff stats, labels |
| `issues` | Issue opened/closed/edited | Issue title, labels, assignees | | `issues` | Issue opened/closed/edited | Issue title, labels, assignees |
@ -41,7 +41,7 @@ WebHooker supports 28 GitHub webhook event types, each with a dedicated formatte
Each event type uses a distinct color in the Discord embed (from `server/lib/formatters/colors.ts`): Each event type uses a distinct color in the Discord embed (from `server/lib/formatters/colors.ts`):
| Color | Events | | Color | Events |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Green (`#2da44e`) | push, PR opened / ready for review, issue opened, workflow success, release published, check success, review approved, deployment success, member added, milestone closed, discussion answered | | Green (`#2da44e`) | push, PR opened / ready for review, issue opened, workflow success, release published, check success, review approved, deployment success, member added, milestone closed, discussion answered |
| Red (`#f85149`) | PR closed, issue closed, workflow failure, release deleted, delete, check failure, review changes requested, deployment failure, member removed, code scanning / dependabot critical & high | | Red (`#f85149`) | PR closed, issue closed, workflow failure, release deleted, delete, check failure, review changes requested, deployment failure, member removed, code scanning / dependabot critical & high |
| Purple (`#8957e5`) | PR merged, label, discussion | | Purple (`#8957e5`) | PR merged, label, discussion |
@ -67,7 +67,7 @@ Any event type without a dedicated formatter falls through to the generic format
See the [Filter Tutorial](../guide/filters) for a hands-on guide with worked examples. See the [Filter Tutorial](../guide/filters) for a hands-on guide with worked examples.
| Filter | Works With | | Filter | Works With |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | All events | | `event` | All events |
| `repo` | All events | | `repo` | All events |
| `actor` | All events | | `actor` | All events |

4
docs/guide/commands.md
View file

@ -7,7 +7,7 @@ After [linking your GitHub account](#linking-your-account), you can act on GitHu
You must link your GitHub account once before using any command: You must link your GitHub account once before using any command:
| Platform | Command | Effect | | Platform | Command | Effect |
|----------|-----------------------------------|------------------------------------------------------------------| | -------- | --------------------------------- | ---------------------------------------------------------------- |
| Discord | `/gh login` | Returns an ephemeral OAuth link to authorize your GitHub account | | Discord | `/gh login` | Returns an ephemeral OAuth link to authorize your GitHub account |
| Discord | `/gh logout` | Unlinks your GitHub account | | Discord | `/gh logout` | Unlinks your GitHub account |
| Telegram | `/gh login` (reply to a message) | Returns an OAuth link | | Telegram | `/gh login` (reply to a message) | Returns an OAuth link |
@ -44,7 +44,7 @@ Notifications for open PRs include **合并 / 关闭** (merge/close) buttons:
### Requirements ### Requirements
| Item | How | | Item | How |
|--------------|----------------------------------------------------------------------------------------------------| | ------------ | -------------------------------------------------------------------------------------------------- |
| Public key | `DISCORD_PUBLIC_KEY` set + Interactions Endpoint URL configured | | Public key | `DISCORD_PUBLIC_KEY` set + Interactions Endpoint URL configured |
| Invite scope | Bot invited with `applications.commands` (see [Discord Bot Setup](./deployment#discord-bot-setup)) | | Invite scope | Bot invited with `applications.commands` (see [Discord Bot Setup](./deployment#discord-bot-setup)) |
| OAuth | `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` and `BASE_URL` configured | | OAuth | `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` and `BASE_URL` configured |

4
docs/guide/groups.md
View file

@ -21,7 +21,7 @@ Routes belong to groups. Groups scope admin access and can restrict which events
``` ```
| Field | Type | Required | Description | | Field | Type | Required | Description |
|------------------|----------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Lowercase id (`a-z0-9`, `-`); referenced by each route's `groupId`. Editable: renaming a group re-points its routes, per-group webhook secret and pending invites | | `id` | string | Yes | Lowercase id (`a-z0-9`, `-`); referenced by each route's `groupId`. Editable: renaming a group re-points its routes, per-group webhook secret and pending invites |
| `name` | string | Yes | Human-readable group name | | `name` | string | Yes | Human-readable group name |
| `members` | object[] | No | `{ login, role }` entries; role is `owner`, `admin`, or `viewer` | | `members` | object[] | No | `{ login, role }` entries; role is `owner`, `admin`, or `viewer` |
@ -38,7 +38,7 @@ Routes belong to groups. Groups scope admin access and can restrict which events
Every group member has one of three roles. Super admins (`ADMIN_USER_IDS`) always bypass them. Every group member has one of three roles. Super admins (`ADMIN_USER_IDS`) always bypass them.
| Role | View routes/logs | Edit routes | Manage members & invites | Edit group settings | | Role | View routes/logs | Edit routes | Manage members & invites | Edit group settings |
|----------|------------------|-------------|--------------------------|---------------------| | -------- | ---------------- | ----------- | ------------------------ | ------------------- |
| `owner` | ✓ | ✓ | ✓ | ✓ (except `owners`) | | `owner` | ✓ | ✓ | ✓ | ✓ (except `owners`) |
| `admin` | ✓ | ✓ | ✗ | ✗ | | `admin` | ✓ | ✓ | ✗ | ✗ |
| `viewer` | ✓ (read-only) | ✗ | ✗ | ✗ | | `viewer` | ✓ (read-only) | ✗ | ✗ | ✗ |

2
docs/guide/i18n.md
View file

@ -13,7 +13,7 @@ Translation overrides are merged from KV under the key `i18n:<lang>` as a flat J
```jsonc ```jsonc
// KV key: i18n:zh // KV key: i18n:zh
{ {
"events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}" "events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}",
} }
``` ```

4
docs/guide/ingress.md
View file

@ -5,7 +5,7 @@
WebHooker ingests webhooks from multiple forges through the same `POST /webhook` endpoint; the provider is auto-detected from the request headers, so point every forge's webhook at `{BASE_URL}/webhook`. WebHooker ingests webhooks from multiple forges through the same `POST /webhook` endpoint; the provider is auto-detected from the request headers, so point every forge's webhook at `{BASE_URL}/webhook`.
| Provider | Event header | Signature header | Signature format | Secret | | Provider | Event header | Signature header | Signature format | Secret |
|----------|------------------|-----------------------|----------------------------|-------------------------| | -------- | ---------------- | --------------------- | -------------------------- | ----------------------- |
| GitHub | `X-GitHub-Event` | `X-Hub-Signature-256` | `sha256=<hex>` HMAC-SHA256 | `GITHUB_WEBHOOK_SECRET` | | GitHub | `X-GitHub-Event` | `X-Hub-Signature-256` | `sha256=<hex>` HMAC-SHA256 | `GITHUB_WEBHOOK_SECRET` |
| Gitea | `X-Gitea-Event` | `X-Gitea-Signature` | plain hex HMAC-SHA256 | `GITEA_WEBHOOK_SECRET` | | Gitea | `X-Gitea-Event` | `X-Gitea-Signature` | plain hex HMAC-SHA256 | `GITEA_WEBHOOK_SECRET` |
@ -51,7 +51,7 @@ Payload schema:
``` ```
| Field | Type | Description | | Field | Type | Description |
|---------------|----------|------------------------------------------------------------------------------------------------------------------| | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `title` | string | Message title (falls back to "Custom message") | | `title` | string | Message title (falls back to "Custom message") |
| `description` | string | Optional message body | | `description` | string | Optional message body |
| `color` | string | Optional embed color: a word (`red`, `green`, `yellow`, `blue`, `purple`, `orange`, `cyan`, `gray`) or `#rrggbb` | | `color` | string | Optional embed color: a word (`red`, `green`, `yellow`, `blue`, `purple`, `orange`, `cyan`, `gray`) or `#rrggbb` |

2
docs/guide/logs.md
View file

@ -5,7 +5,7 @@
Every dispatch attempt is recorded in the D1 `send_logs` table and browsable in the console (**Logs** tab). Fields: Every dispatch attempt is recorded in the D1 `send_logs` table and browsable in the console (**Logs** tab). Fields:
| Field | Meaning | | Field | Meaning |
|--------------|-------------------------------------------------------------------------| | ------------ | ---------------------------------------------------------------- |
| `routeId` | Route that matched | | `routeId` | Route that matched |
| `groupId` | Route's group | | `groupId` | Route's group |
| `event` | Event type (e.g. `push`, `pull_request`, `custom`) | | `event` | Event type (e.g. `push`, `pull_request`, `custom`) |

2
docs/guide/routes.md
View file

@ -32,7 +32,7 @@ There are **no default routes** — each route must define its own target. If no
Each entry of `targets` is a push destination, so one route can forward to several channels at once (e.g. a Discord channel **and** a Telegram group). `target.platform` selects the platform: `discord` (default) or `telegram`. For **Discord**, `target.channelId` is required (a thread in `target.threadId` is optional). For **Telegram**, `target.chatId` (the group/supergroup chat id, e.g. `-1001234567890`) is required and `target.topicId` (the `message_thread_id` of a topic, equivalent of a Discord thread) is optional. There is no fallback to a default channel. Each entry of `targets` is a push destination, so one route can forward to several channels at once (e.g. a Discord channel **and** a Telegram group). `target.platform` selects the platform: `discord` (default) or `telegram`. For **Discord**, `target.channelId` is required (a thread in `target.threadId` is optional). For **Telegram**, `target.chatId` (the group/supergroup chat id, e.g. `-1001234567890`) is required and `target.topicId` (the `message_thread_id` of a topic, equivalent of a Discord thread) is optional. There is no fallback to a default channel.
| Field | Type | Required | Description | | Field | Type | Required | Description |
|------------------|----------|----------|-------------------------------------------------------------------------------------------------| | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
| `groupId` | string | Yes | Id of the [group](./groups) this route belongs to | | `groupId` | string | Yes | Id of the [group](./groups) this route belongs to |
| `fallback` | boolean | No | When `true`, fires only if no non-fallback route matched the event; its own filters are ignored | | `fallback` | boolean | No | When `true`, fires only if no non-fallback route matched the event; its own filters are ignored |
| `stop` | boolean | No | When `true` and this route matches, no further routes are evaluated for this event | | `stop` | boolean | No | When `true` and this route matches, no further routes are evaluated for this event |

4
docs/guide/storage.md
View file

@ -3,7 +3,7 @@
## KV Storage Layout ## KV Storage Layout
| Key Pattern | Value | TTL | | Key Pattern | Value | TTL |
|--------------------------------|-------------------------------------------------------------------------------|--------------------| | ------------------------------ | ----------------------------------------------------------------------------- | ------------------ |
| `config:routes` | JSON array of routes | Permanent | | `config:routes` | JSON array of routes | Permanent |
| `config:groups` | JSON array of groups | Permanent | | `config:groups` | JSON array of groups | Permanent |
| `session:{id}` | Admin session `{ userId, login }` | 7 days | | `session:{id}` | Admin session `{ userId, login }` | 7 days |
@ -26,7 +26,7 @@
The D1 database (`DB` binding, database `webhooker`) holds four tables: The D1 database (`DB` binding, database `webhooker`) holds four tables:
| Table | Purpose | | Table | Purpose |
|------------------|------------------------------------------------------------------------------------------------| | ---------------- | ---------------------------------------------------------------------------------------------- |
| `send_logs` | One row per dispatch attempt (route id, event, target, ok/error, duration, error code, detail) | | `send_logs` | One row per dispatch attempt (route id, event, target, ok/error, duration, error code, detail) |
| `audit_logs` | One row per admin operation (login/logout, group/route/member/invite changes) | | `audit_logs` | One row per admin operation (login/logout, group/route/member/invite changes) |
| `discord_links` | Maps `discord_user_id` → `github_user_id` for `/gh` Discord commands | | `discord_links` | Maps `discord_user_id` → `github_user_id` for `/gh` Discord commands |

2
docs/guide/tasks.md
View file

@ -3,7 +3,7 @@
WebHooker runs three maintenance tasks on the scheduled trigger (`*/5 * * * *`, every 5 minutes). They only run on the deployed worker (Cloudflare cron); local `wrangler dev` runs them when triggered via `wrangler dev --test-scheduled`. WebHooker runs three maintenance tasks on the scheduled trigger (`*/5 * * * *`, every 5 minutes). They only run on the deployed worker (Cloudflare cron); local `wrangler dev` runs them when triggered via `wrangler dev --test-scheduled`.
| Task | Purpose | | Task | Purpose |
|-----------------|------------------------------------------------------------------------------------------------------------------| | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `discord-sync` | Registers the Discord slash/context-menu commands: per-guild (instant) and globally (24h dedup, ~1h propagation) | | `discord-sync` | Registers the Discord slash/context-menu commands: per-guild (instant) and globally (24h dedup, ~1h propagation) |
| `telegram-sync` | Calls `setWebhook` to `{BASE_URL}/telegram/webhook` (with `TELEGRAM_WEBHOOK_SECRET` as `secret_token` when set) | | `telegram-sync` | Calls `setWebhook` to `{BASE_URL}/telegram/webhook` (with `TELEGRAM_WEBHOOK_SECRET` as `secret_token` when set) |
| `audit-prune` | Deletes `audit_logs` entries older than `AUDIT_RETENTION_DAYS` (default 90) | | `audit-prune` | Deletes `audit_logs` entries older than `AUDIT_RETENTION_DAYS` (default 90) |

2
docs/zh/api/admin.md
View file

@ -7,7 +7,7 @@
## 端点 ## 端点
| 端点 | 说明 | | 端点 | 说明 |
|-------------------------------------------------|-------------------------------------------------------------------| | ----------------------------------------------- | -------------------------------------------------------- |
| `GET /admin` | 配置控制台页面 | | `GET /admin` | 配置控制台页面 |
| `GET /admin/login` | 开始管理员登录（GitHub OAuth） | | `GET /admin/login` | 开始管理员登录（GitHub OAuth） |
| `GET /admin/logout` | 退出登录并销毁会话 | | `GET /admin/logout` | 退出登录并销毁会话 |

8
docs/zh/api/overview.md
View file

@ -11,7 +11,7 @@ https://your-worker.workers.dev
## 端点 ## 端点
| 方法 | 路径 | 鉴权 | 说明 | | 方法 | 路径 | 鉴权 | 说明 |
|------------|----------------------------------------------|----------------|--------------------------------------------------------| | -------- | --------------------------- | ------------ | ---------------------------------------------------- |
| `GET` | `/health` | 无 | 健康检查 | | `GET` | `/health` | 无 | 健康检查 |
| `POST` | `/webhook` | HMAC 签名 | GitHub / Gitea / 自定义 webhook 接入（自动识别来源） | | `POST` | `/webhook` | HMAC 签名 | GitHub / Gitea / 自定义 webhook 接入（自动识别来源） |
| `POST` | `/webhook/:groupId` | 分组 secret | 分组级 webhook 入口（只触发该分组的路由） | | `POST` | `/webhook/:groupId` | 分组 secret | 分组级 webhook 入口（只触发该分组的路由） |
@ -63,7 +63,7 @@ POST /webhook
**请求头：** **请求头：**
| 头部 | 必需 | 说明 | | 头部 | 必需 | 说明 |
|-------------------------|--------|---------------------------------| | --------------------- | ---- | ----------------------------- |
| `X-Hub-Signature-256` | 是 | HMAC-SHA256 签名 | | `X-Hub-Signature-256` | 是 | HMAC-SHA256 签名 |
| `X-GitHub-Event` | 是 | 事件类型名称 | | `X-GitHub-Event` | 是 | 事件类型名称 |
| `X-GitHub-Delivery` | 否 | 唯一投递 ID（存在时用于去重） | | `X-GitHub-Delivery` | 否 | 唯一投递 ID（存在时用于去重） |
@ -83,7 +83,7 @@ POST /webhook
**错误响应：** **错误响应：**
| 状态码 | 响应体 | 原因 | | 状态码 | 响应体 | 原因 |
|----------|------------------------------------|--------------------------------| | ------ | -------------------------------- | ---------------------------- |
| `401` | `{"error": "Invalid signature"}` | 签名验证失败 | | `401` | `{"error": "Invalid signature"}` | 签名验证失败 |
| `400` | `{"error": "Invalid event"}` | 缺少事件头或格式错误的请求体 | | `400` | `{"error": "Invalid event"}` | 缺少事件头或格式错误的请求体 |
| `413` | `{"error": "Request too large"}` | 请求体超过 1MB 限制 | | `413` | `{"error": "Request too large"}` | 请求体超过 1MB 限制 |
@ -103,7 +103,7 @@ POST /webhook
主要流程是 App 的 **Setup URL** —— 将其设置为 `{BASE_URL}/auth/github/install`。用户安装 App 后浏览器会跳转到： 主要流程是 App 的 **Setup URL** —— 将其设置为 `{BASE_URL}/auth/github/install`。用户安装 App 后浏览器会跳转到：
| 方法 | 路径 | 说明 | | 方法 | 路径 | 说明 |
|----------|-------------------------------|-----------------------------------------------------------------| | ------ | --------------------------- | ------------------------------------------------------------- |
| `GET` | `/auth/github/install` | 选择页：将安装绑定到新分组或登录用户拥有 owner 权限的已有分组 | | `GET` | `/auth/github/install` | 选择页：将安装绑定到新分组或登录用户拥有 owner 权限的已有分组 |
| `POST` | `/auth/github/install/bind` | 执行绑定（再次校验 owner 角色）并跳转 `/admin?install=ok` | | `POST` | `/auth/github/install/bind` | 执行绑定（再次校验 owner 角色）并跳转 `/admin?install=ok` |

6
docs/zh/events/supported.md
View file

@ -5,7 +5,7 @@ WebHooker 支持 28 种 GitHub webhook 事件类型，每种都有专用的格
## 事件表 ## 事件表
| 事件 | 说明 | 嵌入亮点 | | 事件 | 说明 | 嵌入亮点 |
|---------------------------------|-----------------------------|------------------------------------------------------------------------------------------------------------------| | ----------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `push` | 代码推送到分支 | 提交列表、分支、作者、差异统计 | | `push` | 代码推送到分支 | 提交列表、分支、作者、差异统计 |
| `pull_request` | PR 打开/关闭/合并/编辑 | PR 标题、分支、差异统计、标签 | | `pull_request` | PR 打开/关闭/合并/编辑 | PR 标题、分支、差异统计、标签 |
| `issues` | 议题打开/关闭/编辑 | 议题标题、标签、指派人 | | `issues` | 议题打开/关闭/编辑 | 议题标题、标签、指派人 |
@ -41,7 +41,7 @@ WebHooker 支持 28 种 GitHub webhook 事件类型，每种都有专用的格
每种事件类型在 Discord 嵌入中使用不同的颜色（来自 `server/lib/formatters/colors.ts`）： 每种事件类型在 Discord 嵌入中使用不同的颜色（来自 `server/lib/formatters/colors.ts`）：
| 颜色 | 事件 | | 颜色 | 事件 |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------| | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 绿色 (`#2da44e`) | push、PR 打开/可审查、issue 打开、工作流成功、发布已发布、检查成功、审查已批准、部署成功、成员添加、里程碑关闭、讨论已回答 | | 绿色 (`#2da44e`) | push、PR 打开/可审查、issue 打开、工作流成功、发布已发布、检查成功、审查已批准、部署成功、成员添加、里程碑关闭、讨论已回答 |
| 红色 (`#f85149`) | PR 关闭、issue 关闭、工作流失败、发布已删除、delete、检查失败、审查请求修改、部署失败、成员移除、代码扫描/Dependabot 严重与高危 | | 红色 (`#f85149`) | PR 关闭、issue 关闭、工作流失败、发布已删除、delete、检查失败、审查请求修改、部署失败、成员移除、代码扫描/Dependabot 严重与高危 |
| 紫色 (`#8957e5`) | PR 合并、label、discussion | | 紫色 (`#8957e5`) | PR 合并、label、discussion |
@ -67,7 +67,7 @@ WebHooker 支持 28 种 GitHub webhook 事件类型，每种都有专用的格
实操指南见[过滤器教程](../guide/filters)，包含完整示例。 实操指南见[过滤器教程](../guide/filters)，包含完整示例。
| 过滤器 | 适用事件 | | 过滤器 | 适用事件 |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | 所有事件 | | `event` | 所有事件 |
| `repo` | 所有事件 | | `repo` | 所有事件 |
| `actor` | 所有事件 | | `actor` | 所有事件 |

4
docs/zh/guide/commands.md
View file

@ -7,7 +7,7 @@
使用任何命令前，需先绑定一次 GitHub 账号： 使用任何命令前，需先绑定一次 GitHub 账号：
| 平台 | 命令 | 效果 | | 平台 | 命令 | 效果 |
|----------|----------------------------------|-------------------------------------------------------------| | -------- | ---------------------------- | --------------------------------------------------- |
| Discord | `/gh login` | 返回一条仅你可见的 OAuth 链接，用于授权 GitHub 账号 | | Discord | `/gh login` | 返回一条仅你可见的 OAuth 链接，用于授权 GitHub 账号 |
| Discord | `/gh logout` | 解除绑定 | | Discord | `/gh logout` | 解除绑定 |
| Telegram | `/gh login`（引用一条消息） | 返回 OAuth 链接 | | Telegram | `/gh login`（引用一条消息） | 返回 OAuth 链接 |
@ -44,7 +44,7 @@ Discord 命令为**斜杠命令**与**消息右键菜单命令**，由定时任
### 前置条件 ### 前置条件
| 项目 | 如何满足 | | 项目 | 如何满足 |
|--------------|-----------------------------------------------------------------------------------------------------| | ---------- | --------------------------------------------------------------------------------------------------- |
| 公钥 | 设置 `DISCORD_PUBLIC_KEY` 并配置 Interactions Endpoint URL | | 公钥 | 设置 `DISCORD_PUBLIC_KEY` 并配置 Interactions Endpoint URL |
| 邀请 scope | 机器人以 `applications.commands` scope 邀请（见 [Discord Bot 设置](./deployment#discord-bot-设置)） | | 邀请 scope | 机器人以 `applications.commands` scope 邀请（见 [Discord Bot 设置](./deployment#discord-bot-设置)） |
| OAuth | 配置 `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` 与 `BASE_URL` | | OAuth | 配置 `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` 与 `BASE_URL` |

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

@ -63,7 +63,7 @@ curl http://localhost:8787/health
## 可用脚本 ## 可用脚本
| 脚本 | 说明 | | 脚本 | 说明 |
|------------------------|--------------------------------------| | ---------------------- | ------------------------------------ |
| `bun run dev` | 启动 Nuxt 开发服务器 (HMR) | | `bun run dev` | 启动 Nuxt 开发服务器 (HMR) |
| `bun run build` | 生产构建（cloudflare_module preset） | | `bun run build` | 生产构建（cloudflare_module preset） |
| `bun run deploy` | 部署到 Cloudflare | | `bun run deploy` | 部署到 Cloudflare |

4
docs/zh/guide/groups.md
View file

@ -21,7 +21,7 @@
``` ```
| 字段 | 类型 | 必需 | 说明 | | 字段 | 类型 | 必需 | 说明 |
|------------------|----------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | ---------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | 是 | 小写 id（`a-z0-9`、`-`）；被每条路由的 `groupId` 引用。可编辑：重命名分组会同步其路由、分组 webhook secret 与待处理邀请 | | `id` | string | 是 | 小写 id（`a-z0-9`、`-`）；被每条路由的 `groupId` 引用。可编辑：重命名分组会同步其路由、分组 webhook secret 与待处理邀请 |
| `name` | string | 是 | 人类可读的分组名 | | `name` | string | 是 | 人类可读的分组名 |
| `members` | object[] | 否 | `{ login, role }` 条目；角色为 `owner`、`admin` 或 `viewer` | | `members` | object[] | 否 | `{ login, role }` 条目；角色为 `owner`、`admin` 或 `viewer` |
@ -38,7 +38,7 @@
每个分组成员拥有三种角色之一。超级管理员（`ADMIN_USER_IDS`）始终绕过这些限制。 每个分组成员拥有三种角色之一。超级管理员（`ADMIN_USER_IDS`）始终绕过这些限制。
| 角色 | 查看路由/日志 | 编辑路由 | 管理成员与邀请 | 编辑分组设置 | | 角色 | 查看路由/日志 | 编辑路由 | 管理成员与邀请 | 编辑分组设置 |
|----------|---------------|----------|----------------|------------------| | -------- | ------------- | -------- | -------------- | ---------------- |
| `owner` | ✓ | ✓ | ✓ | ✓（除 `owners`） | | `owner` | ✓ | ✓ | ✓ | ✓（除 `owners`） |
| `admin` | ✓ | ✓ | ✗ | ✗ | | `admin` | ✓ | ✓ | ✗ | ✗ |
| `viewer` | ✓（只读） | ✗ | ✗ | ✗ | | `viewer` | ✓（只读） | ✗ | ✗ | ✗ |

2
docs/zh/guide/i18n.md
View file

@ -13,7 +13,7 @@
```jsonc ```jsonc
// KV 键：i18n:zh // KV 键：i18n:zh
{ {
"events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}" "events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}",
} }
``` ```

4
docs/zh/guide/ingress.md
View file

@ -5,7 +5,7 @@
WebHooker 通过同一个 `POST /webhook` 端点接收多个 forge 的 webhook，按请求头自动识别来源；只需把各 forge 的 webhook 指向 `{BASE_URL}/webhook` 即可。 WebHooker 通过同一个 `POST /webhook` 端点接收多个 forge 的 webhook，按请求头自动识别来源；只需把各 forge 的 webhook 指向 `{BASE_URL}/webhook` 即可。
| 提供方 | 事件请求头 | 签名请求头 | 签名格式 | 密钥 | | 提供方 | 事件请求头 | 签名请求头 | 签名格式 | 密钥 |
|--------|------------------|-----------------------|----------------------------|-------------------------| | ------ | ---------------- | --------------------- | -------------------------- | ----------------------- |
| GitHub | `X-GitHub-Event` | `X-Hub-Signature-256` | `sha256=<hex>` HMAC-SHA256 | `GITHUB_WEBHOOK_SECRET` | | GitHub | `X-GitHub-Event` | `X-Hub-Signature-256` | `sha256=<hex>` HMAC-SHA256 | `GITHUB_WEBHOOK_SECRET` |
| Gitea | `X-Gitea-Event` | `X-Gitea-Signature` | 纯 hex HMAC-SHA256 | `GITEA_WEBHOOK_SECRET` | | Gitea | `X-Gitea-Event` | `X-Gitea-Signature` | 纯 hex HMAC-SHA256 | `GITEA_WEBHOOK_SECRET` |
@ -51,7 +51,7 @@ Gitea 载荷会被归一化为与 GitHub 事件相同的内部结构，因此路
``` ```
| 字段 | 类型 | 说明 | | 字段 | 类型 | 说明 |
|---------------|----------|----------------------------------------------------------------------------------------------------------| | ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `title` | string | 消息标题（缺省时为 "Custom message"） | | `title` | string | 消息标题（缺省时为 "Custom message"） |
| `description` | string | 可选消息正文 | | `description` | string | 可选消息正文 |
| `color` | string | 可选嵌入颜色：颜色词（`red`、`green`、`yellow`、`blue`、`purple`、`orange`、`cyan`、`gray`）或 `#rrggbb` | | `color` | string | 可选嵌入颜色：颜色词（`red`、`green`、`yellow`、`blue`、`purple`、`orange`、`cyan`、`gray`）或 `#rrggbb` |

2
docs/zh/guide/logs.md
View file

@ -5,7 +5,7 @@
每次分发尝试都会记录到 D1 `send_logs` 表，并可在控制台（**日志**标签页）查看。字段： 每次分发尝试都会记录到 D1 `send_logs` 表，并可在控制台（**日志**标签页）查看。字段：
| 字段 | 含义 | | 字段 | 含义 |
|--------------|-------------------------------------------------------------| | ------------ | -------------------------------------------------------- |
| `routeId` | 匹配的路由 | | `routeId` | 匹配的路由 |
| `groupId` | 路由所属分组 | | `groupId` | 路由所属分组 |
| `event` | 事件类型（如 `push`、`pull_request`、`custom`） | | `event` | 事件类型（如 `push`、`pull_request`、`custom`） |

2
docs/zh/guide/routes.md
View file

@ -32,7 +32,7 @@
`targets` 的每一项都是一个推送目标，因此一条路由可同时转发到多个频道（例如一个 Discord 频道**和**一个 Telegram 群组）。`target.platform` 选择平台：`discord`（默认）或 `telegram`。**Discord** 目标要求 `target.channelId`（可选 `target.threadId` 指定子区）；**Telegram** 目标要求 `target.chatId`（群组/超级群组 id，如 `-1001234567890`），可选 `target.topicId`（话题的 `message_thread_id`，相当于 Discord 子区）。没有默认频道回退。 `targets` 的每一项都是一个推送目标，因此一条路由可同时转发到多个频道（例如一个 Discord 频道**和**一个 Telegram 群组）。`target.platform` 选择平台：`discord`（默认）或 `telegram`。**Discord** 目标要求 `target.channelId`（可选 `target.threadId` 指定子区）；**Telegram** 目标要求 `target.chatId`（群组/超级群组 id，如 `-1001234567890`），可选 `target.topicId`（话题的 `message_thread_id`，相当于 Discord 子区）。没有默认频道回退。
| 字段 | 类型 | 必需 | 说明 | | 字段 | 类型 | 必需 | 说明 |
|------------------|----------|------|-----------------------------------------------------------------------------| | ---------------- | -------- | ---- | ------------------------------------------------------------------------ |
| `groupId` | string | 是 | 路由所属[分组](./groups)的 id | | `groupId` | string | 是 | 路由所属[分组](./groups)的 id |
| `fallback` | boolean | 否 | 为 `true` 时仅在没有其他非 fallback 路由匹配时才触发；其自身过滤器被忽略 | | `fallback` | boolean | 否 | 为 `true` 时仅在没有其他非 fallback 路由匹配时才触发；其自身过滤器被忽略 |
| `stop` | boolean | 否 | 为 `true` 且该路由匹配时，不再评估后续路由 | | `stop` | boolean | 否 | 为 `true` 且该路由匹配时，不再评估后续路由 |

4
docs/zh/guide/storage.md
View file

@ -3,7 +3,7 @@
## KV 存储布局 ## KV 存储布局
| 键模式 | 值 | TTL | | 键模式 | 值 | TTL |
|---------------------------------|--------------------------------------------------------------------------------|--------------------| | ------------------------------ | ----------------------------------------------------------------------------- | ------------------ |
| `config:routes` | 路由 JSON 数组 | 永久 | | `config:routes` | 路由 JSON 数组 | 永久 |
| `config:groups` | 分组 JSON 数组 | 永久 | | `config:groups` | 分组 JSON 数组 | 永久 |
| `session:{id}` | 管理员会话 `{ userId, login }` | 7 天 | | `session:{id}` | 管理员会话 `{ userId, login }` | 7 天 |
@ -26,7 +26,7 @@
D1 数据库（`DB` 绑定，数据库 `webhooker`）包含四张表： D1 数据库（`DB` 绑定，数据库 `webhooker`）包含四张表：
| 表 | 用途 | | 表 | 用途 |
|-------------------|--------------------------------------------------------------------------------------------------| | ---------------- | ---------------------------------------------------------------------- |
| `send_logs` | 每次分发尝试一行（路由 id、事件、目标、ok/error、耗时、错误码、详情） | | `send_logs` | 每次分发尝试一行（路由 id、事件、目标、ok/error、耗时、错误码、详情） |
| `audit_logs` | 每次管理员操作一行（登录/登出、分组/路由/成员/邀请变更） | | `audit_logs` | 每次管理员操作一行（登录/登出、分组/路由/成员/邀请变更） |
| `discord_links` | 映射 `discord_user_id` → `github_user_id`，供 `/gh` Discord 命令使用 | | `discord_links` | 映射 `discord_user_id` → `github_user_id`，供 `/gh` Discord 命令使用 |

2
docs/zh/guide/tasks.md
View file

@ -3,7 +3,7 @@
WebHooker 通过定时触发器（`*/5 * * * *`，每 5 分钟）运行三个维护任务。它们只在部署后的 Worker 上运行（Cloudflare cron）；本地 `wrangler dev` 可用 `wrangler dev --test-scheduled` 触发。 WebHooker 通过定时触发器（`*/5 * * * *`，每 5 分钟）运行三个维护任务。它们只在部署后的 Worker 上运行（Cloudflare cron）；本地 `wrangler dev` 可用 `wrangler dev --test-scheduled` 触发。
| 任务 | 用途 | | 任务 | 用途 |
|-----------------|---------------------------------------------------------------------------------------------------------------------| | --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `discord-sync` | 注册 Discord 斜杠/右键菜单命令：按服务器即时注册，并全局注册（24h 去重，约 1 小时传播） | | `discord-sync` | 注册 Discord 斜杠/右键菜单命令：按服务器即时注册，并全局注册（24h 去重，约 1 小时传播） |
| `telegram-sync` | 调用 `setWebhook` 指向 `{BASE_URL}/telegram/webhook`（设置了 `TELEGRAM_WEBHOOK_SECRET` 时作为 `secret_token` 传入） | | `telegram-sync` | 调用 `setWebhook` 指向 `{BASE_URL}/telegram/webhook`（设置了 `TELEGRAM_WEBHOOK_SECRET` 时作为 `secret_token` 传入） |
| `audit-prune` | 删除早于 `AUDIT_RETENTION_DAYS`（默认 90）天的 `audit_logs` 记录 | | `audit-prune` | 删除早于 `AUDIT_RETENTION_DAYS`（默认 90）天的 `audit_logs` 记录 |

4
server/lib/web/admin.ts
View file

@ -284,9 +284,7 @@ export function validateGroups(
if ( if (
g.providers !== undefined && g.providers !== undefined &&
(!Array.isArray(g.providers) || (!Array.isArray(g.providers) ||
!g.providers.every( !g.providers.every((p) => typeof p === "string" && ["github", "gitea"].includes(p)))
(p) => typeof p === "string" && ["github", "gitea"].includes(p),
))
) { ) {
return { return {
ok: false, ok: false,