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

docs: document WebUI, optional gateway, routes-only config and slash commands

Browse source
This commit is contained in:
RhenCloud 2026-08-02 06:51:41 +08:00
parent d68aeb20d5
commit 4349b24d2a
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
6 changed files with 282 additions and 90 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/api/overview.md
View file

@ -20,6 +20,17 @@ https://your-worker.workers.dev
| `POST` | `/api/comment` | Bearer token | Create issue comment |
| `POST` | `/api/merge` | Bearer token | Merge pull request |
| `POST` | `/api/react` | Bearer token | Add reaction to issue |
| `GET` | `/admin` | Admin session | Config console UI |
| `GET` | `/admin/api/routes` | Admin session | List routes |
| `PUT` | `/admin/api/routes` | Admin session | Replace routes |
## Admin Console
See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup. Admin endpoints require a session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS`.
- `GET /admin` — Serves the config console HTML
- `GET /admin/api/routes` — Returns `{ "routes": Route[] }`
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id, name, enabled, ≥1 valid filter, string `target.channelId`) and persists to KV `config:routes`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }`.
## Health Check

58
docs/guide/configuration.md
View file

@ -14,19 +14,42 @@ WebHooker requires several secrets to function. For local development, store the
| `GITHUB_CLIENT_ID` | OAuth client ID from App settings |
| `GITHUB_CLIENT_SECRET` | OAuth client secret from App settings |
| `DISCORD_TOKEN` | Discord bot token |
| `DISCORD_CHANNEL_ID` | Default Discord channel ID for messages |
### Optional Secrets
| Variable | Description | Default |
| ---------- | ------------------------------ | ----------------------- |
| `BASE_URL` | Public URL for OAuth callbacks | `http://localhost:8787` |
| Variable | Description | Default |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------- |
| `BASE_URL` | Public URL for OAuth callbacks | `http://localhost:8787` |
| `ADMIN_USER_IDS` | Comma-separated GitHub user IDs (or logins) allowed to access the Web UI | Disabled |
| `DISCORD_GATEWAY_ENABLED` | Set to `true` to connect the Discord Gateway (bot online status); messaging works without it via REST | `false` |
## Web UI
WebHooker ships with a built-in config console at `/admin` for managing routes in the browser. It is protected by GitHub OAuth plus an admin whitelist.
### Setup
1. Configure `ADMIN_USER_IDS` with the GitHub user IDs allowed to manage routes. Logins are also accepted, e.g. `ADMIN_USER_IDS=12345,RhenCloud`. If unset, the console is disabled.
2. Open `/admin` and sign in with GitHub.
3. Only users in the whitelist receive a session cookie; everyone else gets `403`.
### Endpoints
| Endpoint | Description |
| ----------------------- | --------------------------- |
| `GET /admin` | Config console UI |
| `GET /admin/login` | Start GitHub OAuth sign-in |
| `GET /admin/logout` | Destroy session |
| `GET /admin/api/routes` | List routes (admin only) |
| `PUT /admin/api/routes` | Replace routes (admin only) |
The console lets you add, edit, delete, and toggle routes. Saved routes are written to KV `config:routes` immediately and the config cache is invalidated so the webhook pipeline picks them up on the next run.
## Routes
Routes define which events get forwarded to which Discord channels. They are stored in Cloudflare KV under the key `config:routes` as a JSON array.
On first boot, 7 default routes are used if no KV config exists.
There are **no default routes** — each route must define its own target. If no routes are configured, no events are forwarded.
### Route Schema
@ -40,23 +63,13 @@ On first boot, 7 default routes are used if no KV config exists.
{ "type": "repo", "match": "org/repo", "exclude": false }
],
"target": {
"channelId": "DISCORD_CHANNEL_ID",
"channelId": "REQUIRED_CHANNEL_ID",
"threadId": "OPTIONAL_THREAD_ID"
}
}
```
### Default Routes
| ID | Event(s) | Description |
| ----------------- | ------------------ | -------------------------------- |
| `all-push` | `push` | All push events |
| `pull-requests` | `pull_request` | All PR activity |
| `issues` | `issues` | Issue open/close/edit |
| `issue-comments` | `issue_comment` | Issue and PR comments |
| `workflow-runs` | `workflow_run` | CI/CD workflow completions |
| `releases` | `release` | Release publish/edit |
| `branch-activity` | `create`, `delete` | Branch/tag creation and deletion |
`target.channelId` is required and used as-is; there is no fallback to a default channel.
### Custom Route Example
@ -108,8 +121,9 @@ Filters accept either a single string or an array of strings:
## KV Storage Layout
| Key Pattern | Value | TTL |
| ---------------- | ---------------------------- | ------------ |
| `config:routes` | JSON array of routes | Permanent |
| `token:{userId}` | `{ accessToken, expiresAt }` | Until expiry |
| `state:{hex}` | `{ userId, createdAt }` | 600 seconds |
| Key Pattern | Value | TTL |
| ---------------- | --------------------------------- | ------------ |
| `config:routes` | JSON array of routes | Permanent |
| `session:{id}` | Admin session `{ userId, login }` | 7 days |
| `token:{userId}` | `{ accessToken, expiresAt }` | Until expiry |
| `state:{hex}` | `{ userId, createdAt }` | 600 seconds |

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

@ -6,27 +6,50 @@ WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars`
### 必需密钥
| 变量 | 说明 |
| --- | --- |
| `GITHUB_WEBHOOK_SECRET` | GitHub App 设置中的 Webhook 密钥 |
| `GITHUB_APP_ID` | GitHub App 的数字 ID |
| `GITHUB_PRIVATE_KEY` | App 私钥（PEM 格式，用 `\n` 转义） |
| `GITHUB_CLIENT_ID` | App 设置中的 OAuth 客户端 ID |
| `GITHUB_CLIENT_SECRET` | App 设置中的 OAuth 客户端密钥 |
| `DISCORD_TOKEN` | Discord Bot Token |
| `DISCORD_CHANNEL_ID` | 消息发送的默认 Discord 频道 ID |
| 变量 | 说明 |
| ----------------------- | ---------------------------------- |
| `GITHUB_WEBHOOK_SECRET` | GitHub App 设置中的 Webhook 密钥 |
| `GITHUB_APP_ID` | GitHub App 的数字 ID |
| `GITHUB_PRIVATE_KEY` | App 私钥（PEM 格式，用 `\n` 转义） |
| `GITHUB_CLIENT_ID` | App 设置中的 OAuth 客户端 ID |
| `GITHUB_CLIENT_SECRET` | App 设置中的 OAuth 客户端密钥 |
| `DISCORD_TOKEN` | Discord Bot Token |
### 可选密钥
| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `BASE_URL` | OAuth 回调的公开 URL | `http://localhost:8787` |
| 变量 | 说明 | 默认值 |
| ------------------------- | -------------------------------------------------------------------------- | ----------------------- |
| `BASE_URL` | OAuth 回调的公开 URL | `http://localhost:8787` |
| `ADMIN_USER_IDS` | 允许访问 WebUI 的 GitHub 用户 ID（或登录名），逗号分隔 | 未设置时 WebUI 关闭 |
| `DISCORD_GATEWAY_ENABLED` | 设为 `true` 连接 Discord Gateway（bot 在线状态）；不启用也能通过 REST 推送 | `false` |
## Web 控制台
WebHooker 内置了位于 `/admin` 的配置控制台，可在浏览器中管理路由。它由 GitHub OAuth 和管理员白名单保护。
### 设置
1. 配置 `ADMIN_USER_IDS`，填写允许管理路由的 GitHub 用户 ID，也支持登录名，例如 `ADMIN_USER_IDS=12345,RhenCloud`。未设置时控制台禁用。
2. 打开 `/admin` 并使用 GitHub 登录。
3. 只有白名单中的用户会获得会话 Cookie；其他人收到 `403`。
### 端点
| 端点 | 说明 |
| ----------------------- | ---------------------- |
| `GET /admin` | 配置控制台页面 |
| `GET /admin/login` | 开始 GitHub OAuth 登录 |
| `GET /admin/logout` | 销毁会话 |
| `GET /admin/api/routes` | 列出路由（仅管理员） |
| `PUT /admin/api/routes` | 替换路由（仅管理员） |
控制台支持新增、编辑、删除和开关路由。保存后立即写入 KV `config:routes` 并使配置缓存失效，下一次 webhook 处理即会生效。
## 路由
路由定义了哪些事件被转发到哪些 Discord 频道。它们以 JSON 数组形式存储在 Cloudflare KV 中，键为 `config:routes`。
首次启动时，如果 KV 中没有配置，则使用 7 条默认路由。
**没有默认路由**——每条路由必须自行定义目标频道。若未配置任何路由，则不会转发任何事件。
### 路由模式
@ -40,23 +63,13 @@ WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars`
{ "type": "repo", "match": "org/repo", "exclude": false }
],
"target": {
"channelId": "DISCORD_CHANNEL_ID",
"threadId": "OPTIONAL_THREAD_ID"
"channelId": "必填频道ID",
"threadId": "可选线程ID"
}
}
```
### 默认路由
| ID | 事件 | 说明 |
| --- | --- | --- |
| `all-push` | `push` | 所有推送事件 |
| `pull-requests` | `pull_request` | 所有 PR 活动 |
| `issues` | `issues` | 议题打开/关闭/编辑 |
| `issue-comments` | `issue_comment` | 议题和 PR 评论 |
| `workflow-runs` | `workflow_run` | CI/CD 工作流完成 |
| `releases` | `release` | 发布创建/编辑 |
| `branch-activity` | `create`, `delete` | 分支/标签创建和删除 |
`target.channelId` 必填且按原样使用，不存在默认频道回退。
### 自定义路由示例
@ -81,14 +94,14 @@ WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars`
## 过滤器类型
| 类型 | 匹配对象 | 示例 |
| --- | --- | --- |
| `event` | GitHub 事件名称 | `push`, `pull_request`, `issues` |
| `repo` | 仓库全名 | `org/repo` |
| `actor` | 发送者登录名 | `username`, `[bot]` |
| `action` | 事件操作 | `opened`, `closed`, `published` |
| `branch` | 分支名称 | `main`, `feature/*` |
| `keyword` | 载荷正文中的文本 | `deploy`, `/fix\s+\d+/` (正则) |
| 类型 | 匹配对象 | 示例 |
| --------- | ---------------- | -------------------------------- |
| `event` | GitHub 事件名称 | `push`, `pull_request`, `issues` |
| `repo` | 仓库全名 | `org/repo` |
| `actor` | 发送者登录名 | `username`, `[bot]` |
| `action` | 事件操作 | `opened`, `closed`, `published` |
| `branch` | 分支名称 | `main`, `feature/*` |
| `keyword` | 载荷正文中的文本 | `deploy`, `/fix\s+\d+/` (正则) |
### 过滤器行为
@ -108,8 +121,9 @@ WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars`
## KV 存储布局
| 键模式 | 值 | TTL |
| --- | --- | --- |
| `config:routes` | JSON 路由数组 | 永久 |
| `token:{userId}` | `{ accessToken, expiresAt }` | 至过期 |
| `state:{hex}` | `{ userId, createdAt }` | 600 秒 |
| 键模式 | 值 | TTL |
| ---------------- | ------------------------------ | ------ |
| `config:routes` | JSON 路由数组 | 永久 |
| `session:{id}` | 管理员会话 `{ userId, login }` | 7 天 |
| `token:{userId}` | `{ accessToken, expiresAt }` | 至过期 |
| `state:{hex}` | `{ userId, createdAt }` | 600 秒 |