Best Minds · Runbook

飞书→GitHub Issue Bot：从“长连接”切到 HTTP 回调并跑通（校验令牌获取/配置）

2026-02-01 · 开发 / 自动化 · Feishu/Lark · GitHub · Vercel

不在电脑上启动服务：用 Vercel Serverless 接飞书事件并创建 GitHub Issue

你要的“在飞书群里说一句就提 issue”，本质是一个很薄的中间层：接收消息事件 → 校验 token → 解析命令 → 调 GitHub API → 把链接回写到飞书。当前实现已上线到 Vercel，剩下只差把飞书事件订阅从“长连接”切到“HTTP 推送”，并拿到校验令牌配置到环境变量。

ServerlessFeishu/LarkGitHub IssuesVercelChatOpsMVP: no encryption

TL;DR

当前状态（2026-02-01）

  • Serverless 代码已就绪：tools/feishu-github-issue-bot/api/feishu.js
  • Vercel 生产 Webhook：https://feishu-github-issue-bot.vercel.app/api/feishu
  • 仍未跑通的唯一阻塞：飞书控制台目前选的是「使用长连接接收事件（推荐）」——该模式下不会展示校验令牌。

切换到「将事件发送至 开发者服务器」后，复制校验令牌 → 写入 Vercel 环境变量 → 重新部署，即可跑通（MVP：不加密）。

最快跑通（不加密 MVP）

  1. 飞书：开发配置 → 事件与回调 → 事件配置 → 订阅方式选 将事件发送至 开发者服务器
  2. 飞书：请求网址填 https://feishu-github-issue-bot.vercel.app/api/feishu，复制校验令牌
  3. Vercel：设置 env（FEISHU_ID/FEISHU_KEY/FEISHU_VERIFICATION_TOKEN/GITHUB_TOKEN）并重新部署
  4. 飞书：订阅事件勾选 im.message.receive_v1；加密策略先关闭（本实现暂不支持 payload.encrypt）
  5. 群里发送：issue owner/repo Title | Body

最小架构（HTTP 推送 + Serverless）

飞书群聊 / 私聊 用户发送命令 issue Title | Body 或 issue owner/repo ... 飞书开放平台 事件推送（HTTP） 携带 token/challenge 重试（失败时） Vercel Serverless 校验 token 解析命令 / 幂等去重 调用 GitHub + 回写飞书 GitHub POST /issues 返回 issue URL 搜索去重 关键点：飞书只是入口；真正的安全与可控来自 handler 的权限边界（repo/user allowlist）与审计。
HTTP 推送（开发者服务器模式）才会出现「校验令牌」，也才适合 Serverless Webhook。

为什么你现在看不到校验令牌？

飞书控制台当前处于「使用长连接接收事件（推荐）」：它走 SDK 建长连接，不需要配置公网回调 URL，因此也不会展示校验令牌。

事件订阅的两种模式 要让 Vercel Webhook 工作，必须切到 HTTP 推送 A · 使用长连接接收事件（推荐） ✓ 不用公网回调 URL ✓ 适合官方 SDK 常驻服务 ✗ 不展示校验令牌 ✗ 不适合纯 Webhook Serverless B · 将事件发送至 开发者服务器（HTTP） ✓ 需要 Request URL（公网） ✓ 展示校验令牌（token） ✓ 适合 Vercel / CF Workers (可选) 开启加密策略 切换 跑通顺序：切到 B → 填 Request URL → 复制校验令牌 → 配 Vercel env → redeploy → 群里发 issue 命令。
你看到的页面正停留在 A，所以脚本无法“凭空提取 token”。

谁最懂：三位“最强大脑”会怎么说？

① 飞书开放平台工程师（事件订阅/回调）视角

Thesis：回调的安全边界从来不是“加不加密”，而是：校验令牌 +（可选）加密密钥 + 事件类型白名单。

  • 如果你用的是 HTTP 推送，就要把 Request URL + 校验令牌 配齐；否则平台无法验证你是“同一个后端”。
  • 先跑通可以不加密，但必须保留 token 校验，避免任意人伪造请求打你的 webhook。
  • 最容易卡住的是：订阅方式仍在“长连接”，这不是 bug，是模式不匹配。

Limit：纯 Serverless 不适合“长连接”，那是 SDK 常驻服务的路子。

② GitHub 平台安全工程师（token 最小权限）视角

Thesis：优先 GitHub App（短期 token + 仓库级安装）＞ PAT（长期、常扩权）。

  • 如果先用 PAT，也要用 repo allowlist 限定到指定仓库，避免 token 权限外溢。
  • 请求要做幂等：用飞书 message_id 写进 issue body，然后用 GitHub search 去重。

Limit：搜索 API 有速率限制，规模化要做缓存/队列或落库。

③ Serverless SRE（稳定性/重试/可观测）视角

Thesis：你需要把“重复回调”当成常态：HTTP 200 + 幂等 key，远比赌平台不重试可靠。

  • Feishu 失败会重试；所以 handler 里要先 dedupe 再创建。
  • 最小可观测：至少在 issue body 或日志里写入 feishu_message_id。

Limit：如果要强一致/高吞吐，最终还是需要队列（SQS/Upstash/Redis）或 DB。

跑通清单（不加密 MVP）

A · 飞书控制台（必须）

  1. 开发配置 → 事件与回调 → 事件配置 → 订阅方式：将事件发送至 开发者服务器
  2. 请求网址：https://feishu-github-issue-bot.vercel.app/api/feishu
  3. 复制校验令牌（稍后写进 Vercel env）
  4. 订阅事件：勾选 im.message.receive_v1
  5. 加密策略：先关闭（后续再做解密支持）

B · 本地命令（可选：半自动）

用 Playwright 辅助定位 token（浏览器会打开；需要你手动登录/点一次复制）：

set -a
source /Users/zon/Desktop/MINE/DEVELOPE/Tool/clawdbot-feishu/.env
set +a
node tools/feishu-github-issue-bot/scripts/extract_feishu_verification_token.mjs

生成本地 bot .env（gitignored）：

node tools/feishu-github-issue-bot/scripts/write_bot_env.mjs \
  --token-file _tmp/feishu-verify-token-*/verification_token.txt \
  --default-repo owner/repo

推送到 Vercel + 重新部署：

node tools/feishu-github-issue-bot/scripts/push_vercel_env.mjs \
  --env production --scope zons-projects --deploy
One next action：先把飞书的订阅方式切到「将事件发送至 开发者服务器」，然后运行一次 extract_feishu_verification_token.mjs 把 token 拿到。

常见问题速查

现象 原因 怎么做
控制台找不到“校验令牌” 仍在「使用长连接接收事件」 切换到「将事件发送至 开发者服务器」，保存后出现
Webhook 返回 bad_token Vercel env 中 token 不一致 重新复制校验令牌 → push_vercel_env.mjs --deploy
返回 encrypted_event_not_supported 飞书开启了加密策略 先关闭加密；或后续实现解密（AES）
飞书不回消息 / 403 应用权限不足或 tenant token 获取失败 检查应用权限（消息相关）与 FEISHU_ID/FEISHU_KEY

Closing Summary

代码与部署已具备，真正卡点是“事件订阅模式不匹配”：长连接适合 SDK 常驻服务，HTTP 推送才适合 Serverless Webhook。把模式切对，校验令牌就会出现，剩下就是把 env 写进 Vercel 并 redeploy。