mirror of
https://github.com/ReCloudStudio/WebHooker.git
synced 2026-09-22 16:11:29 +00:00
docs: document admin groups, OAuth redirect, and API renames
This commit is contained in:
parent
8c8cfbf211
commit
8c9720b1b3
10 changed files with 324 additions and 142 deletions
|
|
@ -33,12 +33,12 @@ POST /api/comment
|
|||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `issueNumber` | number | 是 | 议题或 PR 编号 |
|
||||
| `body` | string | 是 | 评论内容（支持 Markdown） |
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| ------------- | ------ | ---- | ------------------------- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `issueNumber` | number | 是 | 议题或 PR 编号 |
|
||||
| `body` | string | 是 | 评论内容（支持 Markdown） |
|
||||
|
||||
**响应：** `200` 与 GitHub API 响应。
|
||||
|
||||
|
|
@ -57,19 +57,45 @@ POST /api/merge
|
|||
"owner": "org",
|
||||
"repo": "repo",
|
||||
"pullNumber": 42,
|
||||
"mergeMethod": "squash"
|
||||
"method": "squash"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `pullNumber` | number | 是 | 拉取请求编号 |
|
||||
| `mergeMethod` | string | 否 | `merge`、`squash` 或 `rebase`（默认：`merge`） |
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| ------------ | ------ | ---- | ----------------------------------------------- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `pullNumber` | number | 是 | 拉取请求编号 |
|
||||
| `method` | string | 否 | `merge`、`squash` 或 `rebase`（默认：`squash`） |
|
||||
|
||||
**响应：** `200` 与 GitHub 合并响应。
|
||||
|
||||
### 关闭拉取请求
|
||||
|
||||
```
|
||||
POST /api/close
|
||||
```
|
||||
|
||||
不合并、直接关闭拉取请求。
|
||||
|
||||
**请求体：**
|
||||
|
||||
```json
|
||||
{
|
||||
"owner": "org",
|
||||
"repo": "repo",
|
||||
"pullNumber": 42
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| ------------ | ------ | ---- | ------------ |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `pullNumber` | number | 是 | 拉取请求编号 |
|
||||
|
||||
**响应：** `200` 与 GitHub 更新响应。
|
||||
|
||||
### 添加反应
|
||||
|
||||
```
|
||||
|
|
@ -85,16 +111,16 @@ POST /api/react
|
|||
"owner": "org",
|
||||
"repo": "repo",
|
||||
"issueNumber": 42,
|
||||
"content": "rocket"
|
||||
"reaction": "rocket"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `issueNumber` | number | 是 | 议题、PR 或评论编号 |
|
||||
| `content` | string | 是 | 反应类型（见下方） |
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
| ------------- | ------ | ---- | ------------------- |
|
||||
| `owner` | string | 是 | 仓库所有者 |
|
||||
| `repo` | string | 是 | 仓库名称 |
|
||||
| `issueNumber` | number | 是 | 议题、PR 或评论编号 |
|
||||
| `reaction` | string | 是 | 反应类型（见下方） |
|
||||
|
||||
**反应类型：**
|
||||
|
||||
|
|
@ -104,8 +130,8 @@ POST /api/react
|
|||
|
||||
## 错误响应
|
||||
|
||||
| 状态码 | 响应体 | 原因 |
|
||||
| --- | --- | --- |
|
||||
| `401` | `{"error": "Unauthorized"}` | 缺少或无效的 Bearer Token |
|
||||
| `400` | `{"error": "..."}` | 无效的请求体 |
|
||||
| `500` | `{"error": "..."}` | GitHub API 错误 |
|
||||
| 状态码 | 响应体 | 原因 |
|
||||
| ------ | --------------------------- | ------------------------- |
|
||||
| `401` | `{"error": "Unauthorized"}` | 缺少或无效的 Bearer Token |
|
||||
| `400` | `{"error": "..."}` | 无效的请求体 |
|
||||
| `500` | `{"error": "..."}` | GitHub API 错误 |
|
||||
|
|
|
|||
|
|
@ -21,9 +21,9 @@ GET /auth/github
|
|||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `userId` | 你的应用用户标识符 |
|
||||
| 参数 | 说明 |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `redirect` | 可选，登录后返回的相对路径（如 `/admin`）。必须以 `/` 开头但不能以 `//` 开头；任何不安全的值回退为 `/`。 |
|
||||
|
||||
**响应：** `302` 重定向到 GitHub OAuth 授权 URL。
|
||||
|
||||
|
|
@ -37,12 +37,16 @@ GitHub 授权后重定向到此地址。将 code 交换为访问令牌并存储
|
|||
|
||||
**查询参数（来自 GitHub）：**
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `code` | 授权码 |
|
||||
| 参数 | 说明 |
|
||||
| ------- | ------------------- |
|
||||
| `code` | 授权码 |
|
||||
| `state` | CSRF 保护的状态参数 |
|
||||
|
||||
**响应：** 重定向到你的 `BASE_URL`，附带成功/失败指示。
|
||||
**响应：**
|
||||
|
||||
- **浏览器流程**（`Accept: text/html`）：设置管理员会话 Cookie，然后重定向到 `redirect` 目标；无管理权限的用户被重定向到 `/admin?error=forbidden`。
|
||||
- **JSON 流程**：返回 `{ "userId": "...", "login": "...", "redirectTo": "..." }`。
|
||||
- **Discord 绑定流程**（以未决的 `discordUserId` 启动时）：将 Discord 用户绑定到此 GitHub 账号，返回 `{ "ok": true, "discordUserId": "...", "login": "..." }`——浏览器中则显示成功页面。
|
||||
|
||||
### 撤销 Token
|
||||
|
||||
|
|
@ -66,12 +70,14 @@ Token 以键模式 `token:{userId}` 存储在 KV 中：
|
|||
|
||||
```json
|
||||
{
|
||||
"userId": "12345",
|
||||
"accessToken": "gho_...",
|
||||
"expiresAt": "2025-01-01T00:00:00.000Z"
|
||||
"expiresAt": 1735689600000,
|
||||
"refreshToken": "..."
|
||||
}
|
||||
```
|
||||
|
||||
Token 会根据 `expiresAt` 时间戳自动过期。
|
||||
`expiresAt` 是毫秒级 Unix 时间戳。KV 条目在 Token 有效期的 90% 时过期（至少 60 秒）。反向索引 `token-reverse:{sha256 of token}` 将访问令牌映射回用户 id，使 Bearer 鉴权的端点能解析调用者。与 GitHub 账号绑定的 Discord 用户存储在 `discord-link:{discordUserId}` 下。
|
||||
|
||||
## 使用 Token
|
||||
|
||||
|
|
|
|||
|
|
@ -10,16 +10,34 @@ https://your-worker.workers.dev
|
|||
|
||||
## 端点
|
||||
|
||||
| 方法 | 路径 | 鉴权 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET` | `/health` | 无 | 健康检查 |
|
||||
| `POST` | `/webhook` | HMAC 签名 | GitHub webhook 接入 |
|
||||
| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
|
||||
| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
|
||||
| `DELETE` | `/auth/token/:userId` | 无 | 撤销用户 Token |
|
||||
| `POST` | `/api/comment` | Bearer Token | 创建议题评论 |
|
||||
| `POST` | `/api/merge` | Bearer Token | 合并拉取请求 |
|
||||
| `POST` | `/api/react` | Bearer Token | 添加议题反应 |
|
||||
| 方法 | 路径 | 鉴权 | 说明 |
|
||||
| -------- | ------------------------------ | ------------ | ------------------------ |
|
||||
| `GET` | `/health` | 无 | 健康检查 |
|
||||
| `POST` | `/webhook` | HMAC 签名 | GitHub webhook 接入 |
|
||||
| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
|
||||
| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
|
||||
| `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/api/routes` | 管理员会话 | 列出路由 |
|
||||
| `PUT` | `/admin/api/routes` | 管理员会话 | 替换路由 |
|
||||
| `GET` | `/admin/api/groups` | 管理员会话 | 列出分组（按权限过滤） |
|
||||
| `PUT` | `/admin/api/groups` | 管理员会话 | 替换分组（仅超级管理员） |
|
||||
| `GET` | `/admin/api/groups/:id/routes` | 管理员会话 | 列出某分组的路由 |
|
||||
| `PUT` | `/admin/api/groups/:id/routes` | 管理员会话 | 替换某分组的路由 |
|
||||
| `GET` | `/admin/api/me` | 管理员会话 | 当前会话信息 |
|
||||
| `GET` | `/admin/api/logs` | 管理员会话 | 发送日志（按权限过滤） |
|
||||
|
||||
## 管理控制台
|
||||
|
||||
参见[配置 → Web 控制台](../guide/configuration.md#web-ui)了解设置方法。管理端点需要会话 Cookie，可通过 `GET /admin/login`（GitHub OAuth）获取；登录用户必须列在 `ADMIN_USER_IDS` 中。
|
||||
|
||||
- `GET /admin` — 提供配置控制台 HTML
|
||||
- `GET /admin/api/routes` — 返回 `{ "routes": Route[] }`
|
||||
- `PUT /admin/api/routes` — 请求体为 `{ "routes": Route[] }`；校验每条路由（id 格式、唯一 id、name、enabled、groupId、过滤器、字符串 `target.channelId`）并持久化到 KV `config:routes`。返回 `200 { ok, count }` 或 `400 { error }` / `401 { error }`。
|
||||
|
||||
## 健康检查
|
||||
|
||||
|
|
@ -45,11 +63,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）。
|
||||
|
||||
|
|
@ -63,11 +81,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 限制 |
|
||||
|
||||
## 错误格式
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue