完整的使用指南和 API 文档
访问首页，使用 GitHub 或 GitLab 账号登录：
http://localhost:8787点击登录按钮后，系统会引导你完成 OAuth 授权流程。
登录成功后，在 Dashboard 页面点击"创建 Proxy"按钮：
创建成功后，复制生成的 Webhook URL，在 GitHub/GitLab 中配置：
使用 WebSocket 或 SSE 连接到对应的 URL，开始接收实时事件：
// WebSocket 方式
const ws = new WebSocket('wss://your-worker.workers.dev/github/xxx/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('收到事件:', data);
};
// SSE 方式
const es = new EventSource('https://your-worker.workers.dev/github/xxx/sse');
es.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('收到事件:', data);
};系统支持以下登录方式：
新用户可以通过用户名/邮箱/密码注册：
POST /api/account/register
Content-Type: application/json
{
"username": "your-username",
"email": "your-email@example.com",
"password": "your-secure-password"
}登录后，可以在设置页面绑定多种登录方式：
登录后，系统会设置一个 Session Cookie：
Set-Cookie: session=<token>; Path=/; SameSite=Lax; Max-Age=2592000Session 有效期为 30 天，过期后需要重新登录。
访问 /auth/logout 清除 Session。
双因素认证提供额外的安全保护：
无密码登录，更安全更便捷：
验证邮箱地址以增强账号安全：
创建 Proxy 时可以启用签名验证：
每个 Proxy 都有唯一的 Access Token：
POST /api/proxies
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My Project",
"platform": "github",
"webhook_secret": "optional-secret",
"verify_signature": true
}GET /api/proxies
Authorization: Bearer <token>PUT /api/proxies/:id
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Updated Name",
"active": false
}DELETE /api/proxies/:id
Authorization: Bearer <token>除了 Web Dashboard，我们还提供了强大的命令行工具，让你在终端中快速管理 Proxies！
# 使用 npm 全局安装
npm install -g webhook-proxy-cli
# 或使用 yarn
yarn global add webhook-proxy-cli
# 验证安装
webhook-proxy --version1. 直接登录（官方服务用户）
# 运行登录命令
webhook-proxy login
# 选择登录方式：
# ❯ 🔐 GitHub OAuth（推荐）
# 🦊 GitLab OAuth
# 👤 用户名/邮箱 + 密码
# 🔑 Passkey / 指纹 / Face ID
# 📋 手动输入 Token
# CLI 会自动打开浏览器完成 OAuth 授权
# 或根据提示输入用户名密码
# 登录成功后自动保存 session token2. 自建服务用户（可选）
如果你自建了 webhook-proxy 服务，需要先配置 API 地址：
# 设置自建服务地址
webhook-proxy config set-api https://your-api-domain.com
# 然后再登录
webhook-proxy login列出所有 Proxies：
# 完整命令
webhook-proxy proxy list
# 快捷命令
webhook-proxy list
webhook-proxy ls创建新的 Proxy：
# 交互式创建
webhook-proxy proxy create
# 按提示输入：
# - Name: My GitHub Webhook
# - Platform: github / gitlab / qqbot / telegram
# - Webhook Secret: 可选
# - Verify Signature: Yes/No查看 Proxy 详情：
# 使用 Proxy ID
webhook-proxy proxy get <proxy-id>
# 快捷命令
webhook-proxy get <proxy-id>更新 Proxy：
# 交互式更新
webhook-proxy proxy update <proxy-id>
# 快捷命令
webhook-proxy update <proxy-id>删除 Proxy：
# 删除（需确认）
webhook-proxy proxy delete <proxy-id>
# 快捷命令
webhook-proxy delete <proxy-id>
webhook-proxy del <proxy-id>
webhook-proxy rm <proxy-id>配置管理：
# 查看当前配置
webhook-proxy config show
# 设置 API 地址（自建服务）
webhook-proxy config set-api https://your-api-domain.com
# 交互式配置
webhook-proxy config interactive
webhook-proxy config i退出登录：
webhook-proxy logout# 1. 登录
webhook-proxy login
# 选择 "🔐 GitHub OAuth"
# ✓ 登录成功！欢迎 your-username
# 2. 查看现有 Proxies
webhook-proxy list
# 显示所有 Proxy 列表
# 3. 创建新的 GitHub Proxy
webhook-proxy create
# Name: My Project
# Platform: github
# Webhook Secret: my-secret-key
# Verify Signature: Yes
# ✓ Proxy 创建成功！
# 4. 查看 Proxy 详情（包含完整 access_token）
webhook-proxy get abc123
# 显示完整信息，包括：
# - ID
# - Name
# - Platform
# - Webhook URL
# - WebSocket URL
# - SSE URL
# - Access Token（完整，不掩码）
# - Webhook Secret（完整，不掩码）
# 5. 更新 Proxy
webhook-proxy update abc123
# 按提示修改信息
# 6. 删除 Proxy
webhook-proxy delete abc123
# 确认后删除CLI 和 Web Dashboard 各有优势，可以根据场景选择：
| 功能 | CLI | Web Dashboard |
|---|---|---|
| 快速操作 | ✅ 极快 | ⚪ 中等 |
| 显示完整 Secret | ✅ 始终显示 | ⚠️ MFA/Passkey 掩码 |
| 批量操作 | ✅ 适合 | ⚪ 一般 |
| 脚本自动化 | ✅ 完美 | ❌ 不支持 |
| 可视化界面 | ⚪ 文本 | ✅ 图形化 |
| 适合新手 | ⚪ 需学习 | ✅ 更直观 |
Webhook Proxy 是一个开源项目，欢迎查看源码、提交 Issue 和贡献代码！
了解项目使用的技术：
每个 Proxy 生成三个 URL：
如果启用了签名验证，系统会验证以下请求头：
接收到的事件包含以下字段：
{
"id": "github-1234567890-abcdef",
"type": "push",
"platform": "github",
"timestamp": 1234567890000,
"raw": { /* 原始 webhook 数据 */ },
"headers": {
"x-github-event": "push",
"x-github-delivery": "..."
}
}const ws = new WebSocket('wss://your-worker.workers.dev/github/xxx/ws');
ws.onopen = () => {
console.log('WebSocket 已连接');
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('事件类型:', data.type);
console.log('原始数据:', data.raw);
};
ws.onerror = (error) => {
console.error('WebSocket 错误:', error);
};
ws.onclose = () => {
console.log('WebSocket 已断开');
};const eventSource = new EventSource(
'https://your-worker.workers.dev/github/xxx/sse'
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('收到事件:', data);
};
eventSource.onerror = (error) => {
console.error('SSE 错误:', error);
};
// 关闭连接
eventSource.close();Webhook Proxy 支持 QQ 官方机器人的 Webhook 事件转发，使用 Ed25519 数字签名算法进行身份验证。
访问 QQ 开放平台 并完成以下步骤：
在 Dashboard 创建 Proxy 时：
POST /api/proxies
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My QQ Bot",
"platform": "qqbot",
"platform_app_id": "102005927",
"webhook_secret": "your_app_secret_here",
"verify_signature": true
}在 QQ 机器人管理页面：
Webhook Proxy 支持所有 QQ Bot 事件类型（OpCode 0 - Dispatch）：
公域事件：
私域事件（需要权限）：
群聊和私聊：
其他事件：
WebSocket 方式：
const ws = new WebSocket('wss://your-domain.com/qqbot/xxxxx/ws?token=your_access_token');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('QQ Bot 事件:', data);
// 事件结构：
// {
// id: '事件ID',
// platform: 'qqbot',
// type: 'AT_MESSAGE_CREATE', // 事件类型
// timestamp: 1234567890,
// headers: { ... },
// payload: { ... }, // 原始 QQ Bot 数据
// data: {
// opcode: 0,
// event_type: 'AT_MESSAGE_CREATE',
// sequence: 42,
// event_data: { ... }
// }
// }
};SSE 方式：
const es = new EventSource('https://your-domain.com/qqbot/xxxxx/sse?token=your_access_token');
es.onmessage = (event) => {
const data = JSON.parse(event.data);
// 根据事件类型处理
if (data.type === 'AT_MESSAGE_CREATE') {
console.log('收到 @ 消息:', data.data.event_data);
}
if (data.type === 'GROUP_AT_MESSAGE_CREATE') {
console.log('收到群聊 @ 消息:', data.data.event_data);
}
};QQ Bot 使用 Ed25519 数字签名算法：
验证流程：
// QQ 平台发送请求时携带：
X-Signature-Timestamp: 时间戳
X-Signature-Ed25519: 签名（hex 编码）
// Webhook Proxy 验证签名：
message = timestamp + body
verify(message, signature, publicKey)
// 签名验证通过后，转发事件回调地址验证失败：
收不到事件：
签名验证失败：
Webhook Proxy 支持 Telegram 机器人的 Webhook 事件转发，使用简单的 Secret Token 进行身份验证。
通过 BotFather 创建 Telegram Bot：
在 Dashboard 创建 Proxy 时：
POST /api/proxies
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My Telegram Bot",
"platform": "telegram",
"platform_app_id": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"webhook_secret": "my-custom-secret-token",
"verify_signature": true
}使用 Telegram Bot API 设置 Webhook URL：
# 使用 curl 设置 Webhook
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/telegram/xxxxx",
"secret_token": "your-secret-token-if-enabled"
}'
# 验证 Webhook 设置
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"Telegram Bot 支持多种更新类型：
消息类型：
交互类型：
支付和其他：
WebSocket 方式：
const ws = new WebSocket('wss://your-domain.com/telegram/xxxxx/ws?token=your_access_token');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Telegram 事件:', data);
// 事件结构：
// {
// id: '事件ID',
// platform: 'telegram',
// type: 'message', // 更新类型
// timestamp: 1234567890,
// headers: { ... },
// payload: { ... }, // 原始 Telegram Update
// data: {
// update_id: 123456789,
// event_type: 'message',
// chat_id: 123456789,
// user_id: 987654321,
// message_text: 'Hello, Bot!'
// }
// }
// 处理不同类型的消息
if (data.type === 'message' && data.payload.message) {
const msg = data.payload.message;
console.log('消息文本:', msg.text);
console.log('发送者:', msg.from.username);
}
};SSE 方式：
const es = new EventSource('https://your-domain.com/telegram/xxxxx/sse?token=your_access_token');
es.onmessage = (event) => {
const data = JSON.parse(event.data);
// 根据事件类型处理
switch (data.type) {
case 'message':
console.log('新消息:', data.data.message_text);
break;
case 'callback_query':
console.log('按钮回调:', data.payload.callback_query.data);
break;
case 'inline_query':
console.log('内联查询:', data.payload.inline_query.query);
break;
}
};Secret Token 提供额外的安全保护：
// Telegram 请求头示例：
X-Telegram-Bot-Api-Secret-Token: my-custom-secret-token
// Webhook Proxy 验证流程：
if (secretToken !== configured_secret_token) {
return 401 Unauthorized;
}Webhook 设置失败：
收不到消息：
删除 Webhook：
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook"项目已配置 GitHub Actions 自动部署到 Cloudflare Workers。
1. Fork 本仓库
2. 配置 GitHub Secrets
在仓库的 Settings → Secrets and variables → Actions 中添加：
3. 推送代码自动部署
git push origin masterGitHub Actions 会自动：
访问仓库的 Actions 页面查看工作流运行状态。
# 安装依赖
npm install
# 配置环境变量
cp .dev.vars.example .dev.vars
# 创建本地数据库
npm run db:migrate:local
# 启动开发服务器
npm run dev# 登录 Cloudflare
npx wrangler login
# 创建 D1 数据库
npm run db:create
# 运行数据库迁移
npm run db:migrate
# 配置环境变量
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GITLAB_CLIENT_ID
npx wrangler secret put GITLAB_CLIENT_SECRET
npx wrangler secret put SESSION_SECRET
npx wrangler secret put JWT_SECRET
npx wrangler secret put RESEND_API_KEY
# 部署
npm run deploy