Files
WebHooker/docs/zh/guide/deployment.md
T
翅膀 5fcb129170 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.
2026-10-23 23:24:05 +08:00

17 KiB
Raw Blame History

部署

Cloudflare 设置

wrangler.jsonc 中带有维护者的 account_id 与资源 id。请把 account_id 换成你自己的 Cloudflare 账号 id(bunx wrangler whoami),或删除该字段以部署到当前登录的账号,并按下面的步骤替换各资源 id。

1. 创建 KV 命名空间

bunx wrangler kv namespace create KV

这会输出一个命名空间 ID。更新 wrangler.jsonc,填入 ID:

{
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "your-namespace-id",
    },
  ],
}

2. 设置密钥

bunx wrangler secret put GITHUB_WEBHOOK_SECRET
bunx wrangler secret put GITHUB_CLIENT_ID
bunx wrangler secret put GITHUB_CLIENT_SECRET
bunx wrangler secret put DISCORD_TOKEN
bunx wrangler secret put DISCORD_PUBLIC_KEY   # Discord 应用的公钥(开发者门户获取),交互功能必需
bunx wrangler secret put TELEGRAM_TOKEN       # Telegram Bot Token(BotFather 获取)—— Telegram 路由必需
bunx wrangler secret put FEISHU_APP_ID        # 飞书应用 ID —— 飞书路由必需
bunx wrangler secret put FEISHU_APP_SECRET    # 飞书应用密钥 —— 飞书路由必需
bunx wrangler secret put ADMIN_USER_IDS       # 允许进入 Web UI 的 GitHub 用户 id,逗号分隔(建议写数字 id)
bunx wrangler secret put BASE_URL             # worker 的公网地址——OAuth 回调与 Telegram webhook 同步都需要

::: tip 目标频道按路由配置 不存在全局频道密钥。每条路由在 Web 控制台 中声明各自的目标频道(及可选的子区/thread),因此不需要 DISCORD_CHANNEL_ID。 :::

::: tip GitHub App ID / 私钥为可选 GITHUB_APP_ID + GITHUB_PRIVATE_KEY(PKCS#8 PEM)用于 App 安装流程,在安装后选择页解析安装所属账号的登录名,并用于签发安装令牌做 API 增强——拉取 workflow_run 作业列表与 check-suite 构建日志。不设置时只有超级管理员能绑定安装——安装流程无法解析安装所属账号,也就无法核实登录用户是否管理该安装;公开仓库的作业列表仍会以匿名方式加载,私有仓库的构建日志则省略。OAuth 流程只需要 GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET。 :::

Discord 交互通过 HTTPS Interactions Endpoint 送达,需要设置 DISCORD_PUBLIC_KEY 并把 Interactions Endpoint URL 指向 https://your-domain/discord/interactions。参见下方 Interactions Endpoint。

3. 创建 D1 数据库并执行迁移

bunx wrangler d1 create webhooker

将返回的数据库 ID 填入 wrangler.jsonc:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "webhooker",
      "database_id": "your-database-id",
    },
  ],
}

然后执行迁移:

bun run db:migrate:prod   # 将迁移应用到远端 D1 数据库
bun run db:migrate        # 将迁移应用到本地(Miniflare)数据库

db:migrate 脚本执行 wrangler d1 migrations apply webhooker(见 package.json),逐一应用 migrations/ 下的 SQL 文件,并在 d1_migrations 表中记录已应用的版本。bun run deploy 会在部署前先执行 db:migrate:prod,因此之后新增的迁移会在下次部署时自动应用;已应用的会被跳过,迁移失败时不会继续部署。

::: tip 曾用 d1 execute 迁移过的数据库 如果数据库已有这些表/列(例如之前用 wrangler d1 execute --file 迁移过),可能缺少 d1_migrations 追踪表,db:migrate:prod 会尝试重新执行所有迁移;0002_log_detail.sql 中的 ALTER TABLE ... ADD COLUMN 语句会因列已存在而失败。此时请直接执行数据库尚未应用的文件(ALTER TABLE ... ADD COLUMN 的文件重复执行会失败,已应用的请跳过):

bunx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0004_add_group_id.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0005_audit_logs.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0006_config_d1.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0007_send_logs_index.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0008_storage_d1.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0010_fragments.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0011_feishu_links.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0012_route_position.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0013_prune_indexes.sql

这类数据库没有迁移历史,bun run deploy(会先执行 db:migrate:prod)会再次尝试所有迁移并中止。请用 bunx wrangler deploy 部署,之后新增的迁移文件也按上面的方式手动执行。

:::

4. 创建 R2 Bucket(可选)

PAYLOAD 绑定将超大 webhook 负载暂存在 R2(webhooker-payloads)而非 KV。未设置时,超大负载回退到 KV 键 queue:payload:*。布局见存储。

bunx wrangler r2 bucket create webhooker-payloads

然后取消 wrangler.jsonc 中 r2_buckets 块的注释(默认是注释掉的);没有该绑定时,超大负载仍暂存在 KV。

5. 创建队列(可选)

QUEUE 绑定会通过 Cloudflare Queues 投递 webhook(异步分发,带重试退避与死信队列)。如需保持同步内联分发,请删除或注释掉 wrangler.jsonc 中的 queues 块;保留该块时两个队列都必须存在。

bunx wrangler queues create webhooker-delivery
bunx wrangler queues create webhooker-delivery-dlq

队列已在 wrangler.jsonc 中声明(queues.producers / queues.consumers),无需修改绑定。webhooker-delivery 消费者对可重试失败(5xx、429、网络错误、限流重试耗尽、飞书 token 错误)做指数退避重试(5s/30s/2m/10m),达到 max_retries 后消息进入 webhooker-delivery-dlq 并标记为 dead。重试按目标进行:已成功或已永久失败的目标会被记录且不再尝试,因此单个坏目标不会取消其他目标的重试,重试也不会重发已记录的目标(发送成功但记录写入失败的目标可能被重发)。每次消费者调用最多取 3 条消息,共享 12 分钟与 20 次目标发送的预算,因为 Workers 免费版的限额(50 次 D1 查询、50 个子请求)按单次调用计算:预算没轮到的消息会被重试,目标数超过预算的投递会以新的队列消息继续。只要过程中有任一目标永久失败,即使其余目标最终都已处理,该投递仍以 failed 结束。领取投递带 5 分钟租约,两个消费者不会同时分发同一投递。

Note

R2 没有按对象的 TTL。暂存负载在分发后删除,定时任务 storage-prune 会清理超过五天的遗留对象;也可以为 webhooks/ 前缀添加 bucket 生命周期规则。

6. 部署

bun run deploy   # 先应用待执行的 D1 迁移,再执行 wrangler deploy

在终端中运行时,wrangler 会在应用待执行的迁移前请求确认;在 CI 中会直接继续。如果通过 Cloudflare 的 Git 集成(Workers Builds)部署,请把其部署命令设为 bun run deploy,以便同样自动应用迁移。

Worker 现在可通过 https://webhooker.<your-subdomain>.workers.dev 访问。

7. 配置 GitHub Webhook

  1. 进入 GitHub App 设置页面
  2. 设置 Webhook URL 为 https://webhooker.<your-subdomain>.workers.dev/webhook
  3. 设置 Webhook secret 与 GITHUB_WEBHOOK_SECRET 一致

8.(可选)配置 Gitea Webhook

  1. 在 Gitea 仓库中进入 设置 → Web 钩子 → 添加 Web 钩子 → Gitea
  2. 设置 目标 URL 为 https://webhooker.<your-subdomain>.workers.dev/webhook
  3. 设置 HTTP 方法 为 POST、Content Type 为 application/json
  4. 设置 密钥 与 GITEA_WEBHOOK_SECRET 一致
  5. 选择要触发的事件(push、议题、拉取请求、发布等)

GitHub App 设置

1. 创建 App

  1. 打开 https://github.com/settings/apps/new
  2. 填写:
    • GitHub App name: WebHooker(或自定义名称)
    • Homepage URL: 你的域名
    • Webhook URL: https://your-domain/webhook
    • Webhook secret: 生成并复制到 GITHUB_WEBHOOK_SECRET
  3. 设置权限:
    • Repository permissions: Contents (read)、Issues (write)、Pull requests (write)、Metadata (read)、Checks (read)、Actions (read)、Deployments (read)、Discussions (read)、Code scanning alerts (read)、Dependabot alerts (read)
    • Organization permissions: Members (read) —— 如果需要
  4. 订阅事件(全部 28 种支持的事件):
    • Push、Pull request、Issues、Issue comment、Workflow run、Workflow job、Status、Deployment、Deployment status、Ping、Release、Create、Delete、Star、Fork、Check run、Check suite、Pull request review、Pull request review comment、Commit comment、Member、Label、Milestone、Discussion、Discussion comment、Repository、Code scanning alert、Dependabot alert
  5. 生成私钥并设置 GITHUB_APP_ID + GITHUB_PRIVATE_KEY:安装流程需要它们核实安装者是否管理该安装(没有时只有超级管理员能绑定安装),私有仓库的 API 增强(作业列表、构建日志)也用它们鉴权(见上方提示)。

2. 安装 App

  1. 创建后,进入 App 设置页面
  2. 点击 "Install App" → 选择组织/用户
  3. 选择要监控的仓库

3. 配置 OAuth

  1. 进入 App → OAuth 设置
  2. 设置 Callback URL: https://your-domain/auth/github/callback
  3. 将 Client ID 和 Client Secret 复制到环境变量

Discord Bot 设置

  1. 打开 https://discord.com/developers/applications

  2. 创建新应用 → 进入 Bot 部分

  3. 将 Bot Token 复制到 DISCORD_TOKEN

  4. 使用 bot 与 applications.commands 两个 scope 邀请 Bot,并勾选 View Channels + Send Messages + Send Messages in Threads 权限(组合整数 274877910016):

    https://discord.com/oauth2/authorize?client_id=YOUR_BOT_CLIENT_ID&permissions=274877910016&scope=bot+applications.commands
    
  5. 在 Web UI(/admin)中按路由配置目标频道——无需全局频道 ID。

Interactions Endpoint

消息通过 Discord REST API 发送,因此仅凭 DISCORD_TOKEN 即可推送。交互(斜杠命令、按钮、modal)则通过 HTTPS Interactions Endpoint 送达:

  1. 在 Discord 开发者门户 → General Information 复制应用的 Public Key,填入 DISCORD_PUBLIC_KEY。
  2. 将 Interactions Endpoint URL 设为 https://your-domain/discord/interactions。
  3. 所有交互请求都使用 Ed25519 签名验证(X-Signature-Ed25519 覆盖 X-Signature-Timestamp + body)。

/gh 斜杠命令与 GitHub: 添加/编辑/删除评论 消息命令由定时任务(每 5 分钟)同步注册:按服务器即时可用(每轮最多 30 次 API 调用),同时全局注册(约 1 小时传播);命令定义变化时两者都会重新注册。Bot 从不连接 Discord Gateway,因此显示为离线——消息推送不受影响(始终走 REST)。

用户运行 /gh login 绑定自己的 GitHub 账号,即可以本人身份评论 issue/PR。完整命令说明见机器人命令。

Telegram 机器人配置

  1. 用 @BotFather 创建机器人,将 Token 复制到 TELEGRAM_TOKEN。
  2. (可选)设置 TELEGRAM_WEBHOOK_SECRET;webhook 注册时会作为 secret_token 传给 Telegram,POST /telegram/webhook 使用时间安全比较校验。未设置时改用由 TELEGRAM_TOKEN 派生的密钥,端点始终需要认证(下一次定时同步会用它重新注册 webhook)。
  3. Worker 会在定时任务中自动同步 webhook(setWebhook 指向 {BASE_URL}/telegram/webhook,仅在注册内容变化时以及每天一次),因此无需手动调用 setWebhook——只需确保 BASE_URL 已设置。
  4. 将机器人加入群组(或启用话题),在路由配置中用 chatId / topicId 指定目标。请使用数字 chat id(如 -1001234567890),不接受 @username 目标。

在 Telegram 中,/gh 命令(/gh login、/gh logout、/gh comment <内容>、/gh merge、/gh close)通过在通知消息上回复来使用——见机器人命令。

头像使用内置 GET /api/richheader 渲染为链接预览卡片(可用 TELEGRAM_RICH_HEADER_HOST 覆盖;未设置 BASE_URL 时直接以头像图片作为预览)。消息始终是文本消息,原地更新时仍有完整的 4096 字符上限。

飞书机器人配置

  1. 进入飞书开放平台 → 创建应用 → 选择企业自建应用 → 填写应用名称。
  2. 在凭证与基础信息中复制 App ID 与 App Secret,分别填入 FEISHU_APP_ID 和 FEISHU_APP_SECRET。
  3. 在权限管理中添加以下任一消息发送权限,用于发送(与读取)消息:
    • im:message(读取和发送单聊与群聊消息)
    • im:message:send_as_bot(以应用机器人身份发送消息)
    • im:message:send(旧版发送消息权限)
  4. 在机器人功能中启用机器人。将机器人添加到目标群聊(或创建新群),并在群设置中复制 Chat ID。
  5. 在 WebHooker /admin 中创建或编辑路由,添加目标:platform: "feishu",chatId 填写飞书 Chat ID(oc_…);飞书目标没有话题。

WebHooker 使用应用级凭证(FEISHU_APP_ID / FEISHU_APP_SECRET)请求 tenant_access_token(有效期约 2 小时),按应用缓存在内存与 KV 中、到期前不久为止,被飞书拒绝时立即丢弃,并以卡片消息(interactive)形式发送。workflow_run / check_run 的进度更新同样会调用飞书消息编辑接口,原地更新消息。

入站:指令与按钮

与 Discord、Telegram 一样,WebHooker 可接收飞书事件,让用户直接在聊天里操作 PR/Issue:

  • /gh login —— 绑定 GitHub 账号(打开 OAuth 页面)。
  • /gh logout —— 解绑 GitHub 账号。
  • /gh comment <PR/Issue 链接> <内容> —— 以绑定的 GitHub 身份发表评论。
  • /gh merge <PR 链接> / /gh close <PR 链接> —— 以绑定身份合并 / 关闭 PR。
  • 卡片上的 合并 / 关闭 按钮触发相同操作。

开启入站:

  1. 在应用的事件订阅中,把请求地址设为 https://<你的-worker>/feishu/webhook(飞书会发送 url_verification 校验,WebHooker 自动应答)。
  2. 订阅以下事件:
    • im.message.receive_v1 —— 接收 /gh 指令(依赖 im:message 权限)。
    • card.action.trigger —— 接收卡片按钮点击。
  3. 在事件与回调 → 加密策略中,把 Encrypt Key 填入 FEISHU_ENCRYPT_KEY(WebHooker 会校验 X-Lark-Signature——timestamp + nonce + key + body 的 SHA-256——并解密加密回调),和/或把 Verification Token 填入 FEISHU_VERIFICATION_TOKEN。至少需要其中一个;都未设置时所有回调都会被拒绝。同一事件 id 只执行一次,飞书重试也不会重复执行。
  4. /gh login 只能在与机器人的单聊(p2p)中使用;GitHub 用户需在同时显示双方账号的确认页上确认绑定。

所需权限

权限 用途
im:message 读取和发送单聊与群聊消息。
im:message:send_as_bot 以应用机器人身份发送消息(im:message 的替代)。
im:message:send 旧版发送消息权限(im:message 的替代)。

Note

不支持“自定义机器人”的群级 Webhook URL。WebHooker 统一使用应用机器人,以保持与 Discord、Telegram 一致的凭证管理、消息编辑、多群路由与入站指令能力。

自定义域名(可选)

要使用自定义域名替代 *.workers.dev:

  1. 进入 Cloudflare Worker 设置
  2. 添加自定义域名或路由
  3. 更新 BASE_URL 以匹配

Note

本项目是一个 Cloudflare Worker,依赖 wrangler.jsonc 中声明的 KV 与 D1 绑定,无法作为独立的 Node/容器进程运行。Queues 绑定(QUEUE)可选——未绑定时 webhook 分发保持内联同步。