docs(worker): align guides with runtime behavior

Synchronize both language guides, API references and examples with
the implemented authorization, storage and delivery behavior.
Document migration requirements and accepted operational limits.
This commit is contained in:
翅膀 committed 2026-10-23 23:24:05 +08:00
1 parent a62044f359
commit 5fcb129170
47 files changed
+938 -660

No files matched your search

+17 -11
View File
@@ -17,9 +17,11 @@ https://your-worker.workers.dev
| `POST` | `/webhook/:groupId` | 分组 secret | 分组级 webhook 入口(只触发该分组的路由) |
| `POST` | `/discord/interactions` | Ed25519 签名 | Discord 交互(斜杠命令、按钮、modal) |
| `POST` | `/telegram/webhook` | Secret token | Telegram 更新(bot `/gh` 命令) |
| `POST` | `/feishu/webhook` | 飞书签名 | 飞书事件(bot `/gh` 命令、卡片按钮) |
| `GET` | `/api/richheader` | 无 | 用于 Telegram 头像链接预览卡片的 Open Graph 页面 |
| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
| `POST` | `/auth/github/link` | 绑定 nonce | 确认机器人账号绑定(由确认页提交) |
| `GET` | `/auth/github/install` | 管理员会话 | 安装后选择页:将安装绑定到某个分组 |
| `POST` | `/auth/github/install/bind` | 管理员会话 | 执行选定的安装绑定 |
| `DELETE` | `/auth/token/:userId` | 管理员会话 | 撤销用户 Token |
@@ -36,7 +38,7 @@ https://your-worker.workers.dev
## 管理控制台
参见[配置 → Web 控制台](../guide/configuration.md#web-ui)了解设置方法,管理端点的完整参考见 [Admin API](./admin)。管理端点需要会话 Cookie,可通过 `GET /admin/login`(GitHub OAuth)获取;登录用户必须列在 `ADMIN_USER_IDS` 中,或管理某个分组。仅限本地开发,精确设置 `DEBUG_MODE=true` 会跳过认证并授予完整权限,绝不能在部署环境启用。
参见[配置 → Web 控制台](../guide/configuration.md#web-控制台)了解设置方法,管理端点的完整参考见 [Admin API](./admin)。管理端点需要会话 Cookie,可通过 `GET /admin/login`(GitHub OAuth)获取;登录用户必须列在 `ADMIN_USER_IDS` 中,或管理某个分组。仅限本地开发,精确设置 `DEBUG_MODE=true` 会跳过认证并授予完整权限,绝不能在部署环境启用。
## 健康检查
@@ -74,27 +76,31 @@ POST /webhook
```json
{
"ok": true
"ok": true,
"requestId": "…"
}
```
当 `X-GitHub-Delivery` 存在且同一投递在最近 5 分钟内已被处理时,Worker 返回 `200 { "ok": true, "duplicate": true }`,不再重复分发。
`requestId` 是写入 worker 日志的关联 id。内联分发(无队列)时,目标永久失败的事件仍返回 `200`,并附带 `"failed": true`。
当 `X-GitHub-Delivery` 存在且同一投递已被接受时,Worker 返回 `200 { "ok": true, "duplicate": true }`,不再重复分发;第一份仍在处理中时,重投会收到 `503`,由发送方稍后重试。
**错误响应:**
| 状态码 | 响应体 | 原因 |
| ------ | -------------------------------- | ---------------------------- |
| `401` | `{"error": "Invalid signature"}` | 签名验证失败 |
| `400` | `{"error": "Invalid event"}` | 缺少事件头或格式错误的请求体 |
| `413` | `{"error": "Request too large"}` | 请求体超过 1MB 限制 |
| 状态码 | 响应体 | 原因 |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------- |
| `401` | `{"error": "Invalid signature"}` | 签名验证失败 |
| `400` | `{"error": "Invalid event"}` | 缺少事件头或格式错误的请求体 |
| `413` | `{"error": "Request too large"}` | 请求体超过 1MB 限制 |
| `503` | `{"error": …}` | 尚未接受——队列拒收、目标暂时失败(内联分发)、同一投递仍在处理,或存储故障;发送方应重投 |
### 分组级 Webhook(`POST /webhook/:groupId`)
使用**分组的** secret(KV `tenant:{groupId}`,在控制台「Webhook 入口」面板生成)验签,并且只分发到该分组的路由。支持 GitHub(`X-Hub-Signature-256`)、Gitea(`X-Gitea-Signature`)和自定义(`X-WebHooker-Signature`)发送方。分组不存在或未配置 secret 时返回 `404`。
使用**分组的** secret(与分组一起存于 D1,在控制台「Webhook 入口」面板生成)验签,并且只分发到该分组的路由。支持 GitHub(`X-Hub-Signature-256`)、Gitea(`X-Gitea-Signature`)和自定义(`X-WebHooker-Signature`)发送方。分组不存在或未配置 secret 时返回 `404`,分组存储的配置无法读取时返回 `503`。
### 自定义 Webhook
任意 JSON 载荷用 `X-WebHooker-Signature: sha256=<hex>`(对原始 body 的 HMAC-SHA256,使用分组或全局 secret)签名后即可成为 `custom` 事件。用 `event: custom` 过滤器的路由接收。可选的 `X-WebHooker-Timestamp` + `X-WebHooker-Nonce` 请求头启用重放防护(对 `{timestamp}.{nonce}.{body}` 签名、±5 分钟窗口、nonce 去重)。载荷格式见[配置 → 自定义 Webhook](../guide/ingress.md#自定义-webhook)。
任意 JSON 对象用 `X-WebHooker-Signature: sha256=<hex>`(对原始 body 的 HMAC-SHA256,使用分组或全局 secret)签名后即可成为 `custom` 事件。用 `event: custom` 过滤器的路由接收。可选的 `X-WebHooker-Timestamp` + `X-WebHooker-Nonce` 请求头启用重放防护(对 `{timestamp}.{nonce}.{body}` 签名、±5 分钟窗口、nonce 去重)。载荷格式见[配置 → 自定义 Webhook](../guide/ingress.md#自定义-webhook)。
### GitHub App 安装事件
@@ -109,7 +115,7 @@ POST /webhook
## 错误格式
所有错误响应都遵循以下格式:
webhook、管理、OAuth 与 Actions 端点的错误响应遵循以下格式;机器人回调(`/discord/interactions`、`/telegram/webhook`、`/feishu/webhook`)的错误响应为纯文本:
```json
{