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

docs: restructure into core-concept pages and split admin API

Browse source
This commit is contained in:
RhenCloud 2026-08-14 06:41:08 +08:00
parent db49e1f01c
commit a9e50fba50
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
27 changed files with 946 additions and 1203 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,19 +1,29 @@
# 配置
本页是密钥与 Web 控制台的参考。核心概念在独立页面中说明：
| 主题 | 页面 |
|--------------------------------------------------|----------------------------------------------------------------------|
| 路由、目标、`fallback` / `stop`、身份组提醒 | [路由与目标](./routes) |
| 分组、角色、邀请、自助注册、日志频道 | [分组与访问控制](./groups) |
| Webhook 提供方、分组入口、自定义 webhook | [Webhook 接入与租户隔离](./ingress) |
| KV / D1 键布局 | [存储布局](./storage) |
| 过滤器（模式语法参考） | 下方[过滤器类型](#过滤器类型) / [过滤器教程](./filters) |
## 密钥
WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars` 中，生产环境使用 Cloudflare Worker Secrets。
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 Bot Token |
| `TELEGRAM_TOKEN` | Telegram Bot 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 **安装流程**
@ -25,291 +35,44 @@ WebHooker 需要多个密钥才能运行。本地开发时存储在 `.dev.vars`
| 变量 | 说明 | 默认值 |
|-----------------------------|--------------------------------------------------------------------------------------------------|-------------------------|
| `BASE_URL` | OAuth 回调的公开 URL | `http://localhost:8787` |
| `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` |
## 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` |
| Gitea | `X-Gitea-Event` | `X-Gitea-Signature` | 纯 hex HMAC-SHA256 | `GITEA_WEBHOOK_SECRET` |
投递 id 去重使用 `X-GitHub-Delivery`（GitHub）或 `X-Gitea-Delivery`（Gitea）请求头（存在时）。
Gitea payload 会被归一化为与 GitHub 相同的内部结构，因此路由、过滤器与 28 个格式化器无需改动即可复用；未知或未映射的 Gitea 事件回退到通用格式化器。仓库/提交/用户链接基于 payload 的 `repository.html_url` 生成，会指向你的 Gitea 实例。
## Web 控制台
WebHooker 内置了位于 `/admin` 的配置控制台，可在浏览器中管理路由。它由 GitHub OAuth 和管理员白名单保护。
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`（自动获得个人分组）或通过分组[邀请链接](#邀请)加入。
3. 没有任何访问权限的用户会得到 `403`，除非 `ALLOW_SELF_SIGNUP=1`（获得个人分组）或跟随分组[邀请链接](./groups#邀请)。
### 端点
控制台以 SPA 形式在 `/admin` 提供；其标签页可通过 URL 路径直达（`/admin/groups`、`/admin/logs`、`/admin/audit`）。`/admin` 之外未匹配到端点的 URL 直接返回 `404`，而不会展示控制台。
控制台以 SPA 形式挂在 `/admin`，各标签页可通过 URL 路径直达（`/admin/groups`、`/admin/logs`、`/admin/audit`）。`/admin` 之外且未匹配下方端点的 URL 直接返回 `404`，不会再被吞进控制台。
| 端点 | 说明 |
|-------------------------------------------------|----------------------------------------------------------|
| `GET /admin` | 配置控制台页面 |
| `GET /admin/login` | 开始 GitHub OAuth 登录 |
| `GET /admin/logout` | 销毁会话 |
| `GET /admin/invite?token=…` | 接受分组邀请（浏览器页面） |
| `GET /admin/api/me` | 当前会话、权限范围、分组和角色 |
| `GET /admin/api/routes` | 列出路由（按权限过滤） |
| `PUT /admin/api/routes` | 替换路由（按分组 owner/admin 权限） |
| `GET /admin/api/groups` | 列出分组 + 当前用户在各组的角色 |
| `PUT /admin/api/groups` | 替换分组（超管全量；owner 仅自己的组） |
| `GET /admin/api/groups/:id/routes` | 列出某分组的路由 |
| `PUT /admin/api/groups/:id/routes` | 替换某分组的路由（owner/admin） |
| `PUT /admin/api/groups/:id/rename` | 重命名分组（owner）；路由、webhook secret 与邀请自动跟随 |
| `GET /admin/api/logs` | 发送日志（按可访问路由过滤） |
| `GET /admin/api/logs/:id` | 单条发送日志（按权限过滤） |
| `POST /admin/api/groups/:id/invites` | 创建邀请链接（owner） |
| `GET /admin/api/groups/:id/invites` | 列出待接受邀请（owner） |
| `DELETE /admin/api/invites/:token` | 撤销邀请（owner） |
| `GET /admin/api/audit` | 审计日志（按可访问分组过滤） |
| `GET /admin/api/groups/:id/webhook` | 分组 webhook 入口信息（owner） |
| `POST /admin/api/groups/:id/webhook/regenerate` | 生成/重新生成分组 webhook secret（owner） |
| `DELETE /admin/api/groups/:id/webhook` | 停用分组 webhook 入口（owner） |
控制台支持新增、编辑、删除和开关路由。保存后立即写入 KV `config:routes` 并使配置缓存失效，下一次 webhook 处理即会生效。上限：每个实例最多 **200 条路由** 与 **100 个分组**。
## Webhook 端点
### 全局端点（`POST /webhook`）
旧版全局端点使用运维者的全局 secret（`GITHUB_WEBHOOK_SECRET`、`GITEA_WEBHOOK_SECRET`）验签，可分发到**所有**路由。GitHub App 安装事件从该端点进入；多租户场景请用分组的 `installationId` 做隔离。
### 分组端点（`POST /webhook/{groupId}`）
每个分组可以启用独立的 webhook 入口和 secret（在分组页面「Webhook 入口」面板生成，owner 权限）。载荷使用**分组的** secret 验签，且只有该分组的路由会触发。SaaS 用户可以借此配置 Gitea、classic GitHub 或自定义 webhook，无需共享（也无需知道）运维者的全局 secret。
- 支持所有 provider：GitHub（`X-Hub-Signature-256`）、Gitea（`X-Gitea-Signature`）、自定义（`X-WebHooker-Signature`）
- secret 为 64 位十六进制字符串；重新生成后旧值立即失效
- 去重 key 按租户隔离（`delivery:{groupId}:{id}`）
- 分组未配置 secret（或分组不存在）时返回 `404`
### 自定义 Webhook
向 `POST /webhook/{groupId}`（或全局端点）POST 任意 JSON，并用分组的 secret 对原始 body 计算 HMAC-SHA256 放在 `X-WebHooker-Signature: sha256=<hex>` 头中。载荷会变成 `custom` 事件走标准路由管线——创建一条 `event: custom` 的路由（控制台有模板）即可分发到该路由的目标，并自动记录 `send_logs`、出现在分组的日志频道。
载荷格式：
```json
{
"title": "Deploy failed",
"description": "Prod rollout failed at 12:03 UTC",
"color": "red",
"url": "https://ci.example.com/runs/42",
"repo": "acme/widget",
"author": {
"name": "alice",
"iconUrl": "https://…/alice.png",
"url": "https://github.com/alice"
},
"fields": [{ "name": "Env", "value": "prod", "inline": true }],
"footer": "my-monitor",
"deliveryId": "alert-123"
}
```
| 字段 | 类型 | 说明 |
|---------------|----------|----------------------------------------------------------------------------------------------------------|
| `title` | string | 消息标题（缺失时回退为「自定义消息」） |
| `description` | string | 可选的消息正文 |
| `color` | string | 可选消息颜色：颜色词（`red`、`green`、`yellow`、`blue`、`purple`、`orange`、`cyan`、`gray`）或 `#rrggbb` |
| `url` | string | 可选标题链接 |
| `repo` | string | 可选 `owner/repo`；会加在标题前并作为 footer |
| `author` | object | 可选的 `{ name, iconUrl, url }` |
| `fields` | object[] | 可选的嵌入字段 `{ name, value, inline }` |
| `footer` | string | 可选的 footer 覆盖 |
| `deliveryId` | string | 可选的发送方去重 id（重试场景） |
### GitHub App 租户隔离
GitHub App 安装后，**所有**安装方的事件都会到达全局端点。要让租户互相隔离，请把每个分组绑定到应当为其提供事件的安装 ID：`"installationId": 12345678`。该 ID 可从 App 安装 webhook 载荷（`installation.id`）或 GitHub App 安装页 URL 看到。即使分组的 `owners` 为空，来自其它安装的事件也会被拒绝。未设置 `installationId` 的分组保持旧行为（`owners` 过滤）。
绑定是**自动配置**的 —— 将 GitHub App 的 _Setup URL_ 指向 `{BASE_URL}/auth/github/install`。用户安装 App 后浏览器立即跳转到该页面（页面需要已登录的管理员会话——未登录用户会先被重定向走 OAuth 流程），可选择将安装绑定到：**新分组**（`inst-{installationId}`，默认）或任意**自己拥有 owner 权限的已有分组**（提交时再次校验角色；由 `POST /auth/github/install/bind` 完成配置）。无需手动填写 ID。作为兜底（例如未配置 Setup URL 时），`installation.created` webhook 事件也会自动创建/绑定分组 —— `owners` 匹配安装账号的现有分组会被绑定，否则创建独立的 `inst-{installationId}` 分组。之后在控制台为分组添加路由和成员即可。
## 路由
路由定义了哪些事件被转发到哪些频道（Discord 或 Telegram）。它们以 JSON 数组形式存储在 Cloudflare KV 中，键为 `config:routes`。
**没有默认路由**——每条路由必须自行定义目标频道。若未配置任何路由，则不会转发任何事件。
### 路由模式
```json
{
"id": "unique-route-id",
"name": "可读名称",
"enabled": true,
"groupId": "my-group",
"fallback": false,
"stop": false,
"discordRoleIds": ["111111111111111111"],
"filters": [
{ "type": "event", "match": "push" },
{ "type": "repo", "match": "org/repo", "exclude": false }
],
"targets": [
{
"platform": "discord",
"channelId": "必填频道ID",
"threadId": "可选线程ID"
}
]
}
```
`targets` 数组的每一项是一个推送目标，因此一条路由可同时转发到多个频道（例如同时发到 Discord 频道 **和** Telegram 群组）。`target.platform` 选择推送目标：`discord`（默认）或 `telegram`。**Discord** 需 `target.channelId`（`target.threadId` 可选的子区）；**Telegram** 需 `target.chatId`（群组/超级群组聊天 id，如 `-1001234567890`），`target.topicId`（话题的 `message_thread_id`，相当于 Discord 的子区）可选。不存在默认频道回退。
### Discord 身份组提醒
在路由上设置 `discordRoleIds`，当该路由触发时会 @提醒（ping）一个或多个 Discord 身份组。`<@&roleId>` 形式的提醒会拼接到该路由所有 **Discord** 目标的消息正文开头；Telegram 目标会忽略此字段。只有在机器人拥有 `Mention Everyone` 权限（或该身份组被标记为可被提及 mentionable）且机器人能看到该身份组时，提醒才会真正触发通知。
```json
{
"id": "release-notify",
"name": "发布时提醒",
"enabled": true,
"groupId": "default",
"discordRoleIds": ["111111111111111111", "222222222222222222"],
"filters": [{ "type": "event", "match": "release" }],
"targets": [{ "platform": "discord", "channelId": "必填频道ID" }]
}
```
也可以在管理控制台的“Discord 身份组提醒”中配置。
其他路由字段：
| 字段 | 类型 | 必需 | 说明 |
|------------------|----------|------|------------------------------------------------------------------------|
| `groupId` | string | 是 | 该路由所属[分组](#分组)的 id |
| `fallback` | boolean | 否 | 为 `true` 时，仅当没有其它路由匹配该事件时才发送，其自身过滤器会被忽略 |
| `stop` | boolean | 否 | 为 `true` 且该路由匹配时，停止评估后续路由 |
| `discordRoleIds` | string[] | 否 | 该路由触发时要在 Discord 目标中 @提醒的身份组 id |
### 自定义路由示例
```json
[
{
"id": "backend-prs",
"name": "后端 PR",
"enabled": true,
"groupId": "backend-team",
"filters": [
{ "type": "repo", "match": "myorg/backend" },
{ "type": "event", "match": "pull_request" },
{ "type": "actor", "match": "[bot]", "exclude": true }
],
"targets": [
{
"platform": "telegram",
"chatId": "-1001234567890",
"topicId": "9876543210"
}
]
}
]
```
## 分组
路由隶属于分组。分组用于限定管理权限，并可限制哪些事件允许流入。它们以 JSON 数组形式存储在 Cloudflare KV 中，键为 `config:groups`。
### 分组模式
```json
{
"id": "backend-team",
"name": "后端团队",
"members": [
{ "login": "rhencloud", "role": "owner" },
{ "login": "octobot", "role": "admin" },
{ "login": "reader", "role": "viewer" }
],
"owners": ["myorg"],
"providers": ["github", "gitea"],
"installationId": 12345678,
"logTarget": { "platform": "discord", "channelId": "123456789", "threadId": "987654321" }
}
```
| 字段 | 类型 | 必需 | 说明 |
|------------------|----------|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | string | 是 | 小写 id（`a-z0-9`、`-`），由每条路由的 `groupId` 引用。可修改：重命名分组会同步更新其路由、分组级 webhook secret 与待接受邀请 |
| `name` | string | 是 | 可读的分组名称 |
| `members` | object[] | 否 | `{ login, role }` 列表；角色为 `owner`、`admin` 或 `viewer` |
| `adminIds` | string[] | 否 | 已废弃的旧字段；存在时按 role 为 `owner` 的成员处理 |
| `owners` | string[] | 否 | 允许事件进入该分组的组织/用户登录名；为空表示不限制 |
| `providers` | string[] | 否 | 允许进入该分组的来源平台（`github`、`gitea`）；为空表示全部 |
| `installationId` | number | 否 | 绑定到该分组的 GitHub App 安装 ID；只接受该安装的事件（为空表示全部） |
| `emoji` | boolean | 否 | 是否在该分组消息中显示 emoji（默认 `true`） |
| `lang` | string | 否 | 该分组所有路由的消息语言（如 `en`、`zh`；可通过 KV `i18n:<lang>` 自定义）——默认 `en` |
| `logTarget` | object | 否 | Webhook 日志频道：Discord 目标 `{ platform, channelId, threadId? }` 或 Telegram 目标 `{ platform, chatId, topicId? }`，本分组路由每次投递 webhook 时都会向其发送摘要 |
### 角色
每个分组成员拥有三种角色之一。超级管理员（`ADMIN_USER_IDS`）始终绕过角色限制。
| 角色 | 查看路由/日志 | 编辑路由 | 管理成员与邀请 | 编辑分组设置 |
|----------|---------------|----------|----------------|--------------------|
| `owner` | ✓ | ✓ | ✓ | ✓（`owners` 除外） |
| `admin` | ✓ | ✓ | ✗ | ✗ |
| `viewer` | ✓（只读） | ✗ | ✗ | ✗ |
### 权限模型
- **超级管理员**（`ADMIN_USER_IDS`）可查看和编辑所有分组及全部路由；只有他们能修改分组的 `owners` 列表。
- **owner** 管理本组的路由、成员、邀请、名称、id、`emoji` 与 `providers`；不能移除最后一位 owner，也没有其他 owner 时不能把自己降级。
- **admin** 可编辑本组路由并查看日志；**viewer** 只读控制台。
- 分组管理端点通过 `/admin/api/groups/:id/routes` 一次只操作一个分组；`groupId` 由路径参数强制指定。
- `owners` 列表限定哪些事件参与者（发送者登录名）的事件会被该分组的路由投递。
- `providers` 列表限定哪个 forge（`github`、`gitea`）的事件会被该分组的路由投递。即使组织/用户同名，也可以借此将 GitHub 与 Gitea 分组区分开。
### Webhook 日志频道
分组可以设置 `logTarget` 指向一个 Discord 频道/子区或 Telegram 群组/话题。每当该分组的路由分发（dispatch）一个 webhook，就会向那里发送一条摘要消息：事件类型/动作、仓库、投递 ID，以及每条「路由 × 目标」一行的 ✅/❌ 结果（失败时附带错误信息；最多列出前 10 行，其余以 `+N` 汇总）。全部成功时消息为绿色，任一失败则为红色。摘要使用分组的消息语言。日志消息尽力发送，本身不会被记入 D1 发送日志。
### 邀请
owner（及超级管理员）可在分组的「成员」面板创建一次性邀请链接，7 天内有效。接受邀请后用户以邀请角色（`admin` 或 `viewer`，绝不授予 `owner`）加入；已有的 `viewer` 会被升级为 `admin`。邀请存储在 KV `invite:{token}`。
### 自助注册
开启 `ALLOW_SELF_SIGNUP=1` 后，没有分组权限的 GitHub 用户首次登录会获得一个由自己担任 owner 的个人分组（`u-{userId}`），而不是 `403`。这是全自助 SaaS 部署的入口；关闭它则控制台保持仅邀请制。
所有管理端点（`/admin/api/*`）见 [Admin API](../api/admin)。保存的路由会立即写入 KV `config:routes` 并使配置缓存失效，下一次 webhook 处理即会生效。
## 过滤器类型
实操指南见[过滤器教程](./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+/` |
### 过滤器行为
@ -328,37 +91,3 @@ owner（及超级管理员）可在分组的「成员」面板创建一次性邀
{ "type": "event", "match": "push" }
{ "type": "event", "match": ["push", "pull_request"] }
```
## KV 存储布局
| 键模式 | 值 | TTL |
|--------------------------------|-------------------------------------------------------------------------------|--------------------|
| `config:routes` | JSON 路由数组 | 永久 |
| `config:groups` | JSON 分组数组 | 永久 |
| `session:{id}` | 管理员会话 `{ userId, login }` | 7 天 |
| `token:{userId}` | `{ userId, accessToken, expiresAt, refreshToken? }` | 0.9 × Token 有效期 |
| `token-reverse:{sha256}` | 用于按 Token 反查的用户 id | 0.9 × Token 有效期 |
| `state:{hex}` | `{ redirectTo, expiresAt, discordUserId?, telegramUserId?, telegramChatId? }` | 600 秒 |
| `invite:{token}` | `{ groupId, role, expiresAt, createdBy, note? }` | 7 天 |
| `invite:group:{id}` | 每组的 Token 索引（保证邀请列表一致性） | 永久 |
| `delivery:{id}` | Webhook 投递 id（去重标记） | 300 秒 |
| `delivery:{groupId}:{id}` | 分组级 webhook 入口的租户级投递去重 | 300 秒 |
| `tenant:{groupId}` | 分组 webhook secret（64 位 hex，控制台生成） | 永久 |
| `msg:{routeId}:{key}:{target}` | 原地更新用消息 id 追踪（如 `workflow_run` / `check_run`） | 7 天 |
| `cmd:guild:{id}` | 已注册命令的服务器 id（去重标记） | 永久 |
| `cmd:registered:global` | 全局命令已注册标记（24h 去重） | 1 天 |
| `config:discord-app-id` | Discord 应用 id 缓存 | 永久 |
| `i18n:{lang}` | 翻译覆盖，合并到英文之上 | 永久 |
## D1 存储布局
D1 数据库（`DB` 绑定，数据库 `webhooker`）包含四张表：
| 表 | 用途 |
|------------------|------------------------------------------------------------------------|
| `send_logs` | 每次分发尝试一行（路由 id、事件、目标、成功/失败、耗时、错误码、详情） |
| `audit_logs` | 每次管理操作一行（登录/登出、分组/路由/成员/邀请变更） |
| `discord_links` | 映射 `discord_user_id` → `github_user_id`，用于 Discord `/gh` 命令 |
| `telegram_links` | 映射 `telegram_user_id` → `github_user_id`，用于 Telegram `/gh` 命令 |
`audit_logs` 由定时触发器按 `AUDIT_RETENTION_DAYS`（默认 90）自动清理。