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

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

@ -6,29 +6,29 @@
## 端点
| 端点 | 说明 |
|-------------------------------------------------|-------------------------------------------------------------------|
| `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/groups/:id/invites` | 列出待处理的邀请（owner） |
| `POST /admin/api/groups/:id/invites` | 创建邀请链接（owner） |
| `DELETE /admin/api/invites/:token` | 撤销邀请（owner） |
| `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） |
| `GET /admin/api/logs` | 发送日志（按可访问的路由过滤） |
| `GET /admin/api/logs/:id` | 单条发送日志（按权限过滤） |
| `GET /admin/api/audit` | 审计日志（按可访问的分组过滤） |
| 端点 | 说明 |
| ----------------------------------------------- | -------------------------------------------------------- |
| `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/groups/:id/invites` | 列出待处理的邀请（owner） |
| `POST /admin/api/groups/:id/invites` | 创建邀请链接（owner） |
| `DELETE /admin/api/invites/:token` | 撤销邀请（owner） |
| `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） |
| `GET /admin/api/logs` | 发送日志（按可访问的路由过滤） |
| `GET /admin/api/logs/:id` | 单条发送日志（按权限过滤） |
| `GET /admin/api/audit` | 审计日志（按可访问的分组过滤） |
## 校验

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

@ -10,27 +10,27 @@ https://your-worker.workers.dev
## 端点
| 方法 | 路径 | 鉴权 | 说明 |
|------------|----------------------------------------------|----------------|--------------------------------------------------------|
| `GET` | `/health` | 无 | 健康检查 |
| `POST` | `/webhook` | HMAC 签名 | GitHub / Gitea / 自定义 webhook 接入（自动识别来源） |
| `POST` | `/webhook/:groupId` | 分组 secret | 分组级 webhook 入口（只触发该分组的路由） |
| `POST` | `/discord/interactions` | Ed25519 签名 | Discord 交互（斜杠命令、按钮、modal） |
| `POST` | `/telegram/webhook` | Secret token | Telegram 更新（bot `/gh` 命令） |
| `GET` | `/api/richheader` | 无 | 用于 Telegram 头像链接预览卡片的 Open Graph 页面 |
| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
| `GET` | `/auth/github/install` | 管理员会话 | 安装后选择页：将安装绑定到某个分组 |
| `POST` | `/auth/github/install/bind` | 管理员会话 | 执行选定的安装绑定 |
| `DELETE` | `/auth/token/:userId` | 管理员会话 | 撤销用户 Token |
| `POST` | `/api/comment` | Bearer Token | 创建议题评论 |
| `POST` | `/api/merge` | Bearer Token | 合并拉取请求 |
| `POST` | `/api/close` | Bearer Token | 关闭拉取请求 |
| `POST` | `/api/react` | Bearer Token | 添加议题反应 |
| `GET` | `/admin` | 管理员会话 | 配置控制台页面 |
| `GET` | `/admin/login` | 无 | 开始管理员登录（GitHub OAuth） |
| `GET` | `/admin/logout` | 管理员会话 | 退出登录并销毁会话 |
| `GET` | `/admin/invite` | 管理员会话 | 接受分组邀请（浏览器页面，`?token=…`） |
| 方法 | 路径 | 鉴权 | 说明 |
| -------- | --------------------------- | ------------ | ---------------------------------------------------- |
| `GET` | `/health` | 无 | 健康检查 |
| `POST` | `/webhook` | HMAC 签名 | GitHub / Gitea / 自定义 webhook 接入（自动识别来源） |
| `POST` | `/webhook/:groupId` | 分组 secret | 分组级 webhook 入口（只触发该分组的路由） |
| `POST` | `/discord/interactions` | Ed25519 签名 | Discord 交互（斜杠命令、按钮、modal） |
| `POST` | `/telegram/webhook` | Secret token | Telegram 更新（bot `/gh` 命令） |
| `GET` | `/api/richheader` | 无 | 用于 Telegram 头像链接预览卡片的 Open Graph 页面 |
| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
| `GET` | `/auth/github/install` | 管理员会话 | 安装后选择页：将安装绑定到某个分组 |
| `POST` | `/auth/github/install/bind` | 管理员会话 | 执行选定的安装绑定 |
| `DELETE` | `/auth/token/:userId` | 管理员会话 | 撤销用户 Token |
| `POST` | `/api/comment` | Bearer Token | 创建议题评论 |
| `POST` | `/api/merge` | Bearer Token | 合并拉取请求 |
| `POST` | `/api/close` | Bearer Token | 关闭拉取请求 |
| `POST` | `/api/react` | Bearer Token | 添加议题反应 |
| `GET` | `/admin` | 管理员会话 | 配置控制台页面 |
| `GET` | `/admin/login` | 无 | 开始管理员登录（GitHub OAuth） |
| `GET` | `/admin/logout` | 管理员会话 | 退出登录并销毁会话 |
| `GET` | `/admin/invite` | 管理员会话 | 接受分组邀请（浏览器页面，`?token=…`） |
`/admin/api/*` 端点（路由、分组、成员、邀请、webhook 密钥、发送日志、审计日志）在 [Admin API](./admin) 中单独说明。
@ -62,11 +62,11 @@ POST /webhook
**请求头：**
| 头部 | 必需 | 说明 |
|-------------------------|--------|---------------------------------|
| `X-Hub-Signature-256` | 是 | HMAC-SHA256 签名 |
| `X-GitHub-Event` | 是 | 事件类型名称 |
| `X-GitHub-Delivery` | 否 | 唯一投递 ID（存在时用于去重） |
| 头部 | 必需 | 说明 |
| --------------------- | ---- | ----------------------------- |
| `X-Hub-Signature-256` | 是 | HMAC-SHA256 签名 |
| `X-GitHub-Event` | 是 | 事件类型名称 |
| `X-GitHub-Delivery` | 否 | 唯一投递 ID（存在时用于去重） |
**请求体：** GitHub webhook JSON 载荷（最大 1MB）。
@ -82,11 +82,11 @@ POST /webhook
**错误响应：**
| 状态码 | 响应体 | 原因 |
|----------|------------------------------------|--------------------------------|
| `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 限制 |
### 分组级 Webhook（`POST /webhook/:groupId`）
@ -102,10 +102,10 @@ POST /webhook
主要流程是 App 的 **Setup URL** —— 将其设置为 `{BASE_URL}/auth/github/install`。用户安装 App 后浏览器会跳转到：
| 方法 | 路径 | 说明 |
|----------|-------------------------------|-----------------------------------------------------------------|
| `GET` | `/auth/github/install` | 选择页：将安装绑定到新分组或登录用户拥有 owner 权限的已有分组 |
| `POST` | `/auth/github/install/bind` | 执行绑定（再次校验 owner 角色）并跳转 `/admin?install=ok` |
| 方法 | 路径 | 说明 |
| ------ | --------------------------- | ------------------------------------------------------------- |
| `GET` | `/auth/github/install` | 选择页：将安装绑定到新分组或登录用户拥有 owner 权限的已有分组 |
| `POST` | `/auth/github/install/bind` | 执行绑定（再次校验 owner 角色）并跳转 `/admin?install=ok` |
## 错误格式