飞书/Lark 组织切换 · 配置重置与迁移方案
目标:在新的 Lark 组织上重置一套命名统一、按用途收敛的配置,废弃旧飞书组织的应用与散落的 webhook。本文给出现状盘点、目标方案、旧→新映射与迁移 runbook。
为什么"乱":①命名飞书/Lark 混用(
FEISHU_* 与 LARK_* 指同一平台,属性 seahub.feishu.* vs seahub.monitor.lark-* 并存);②webhook 目的地多达 8 个、按单个功能各起一套 URL+secret,还有深层回退链(如 h5 → ops-lark → feishu → lark);③密钥散落两处:阿里云 OOS(.ai-workbench/secret)与 GitHub Actions(beex-doc)。1. 现状盘点(飞书/Lark 全部配置)
1.1 一套「自建应用」凭证 —— 承载 3 类用途
| 用途 | 属性 / 环境变量 | 消费方 |
|---|---|---|
| 机器人发消息 | seahub.feishu.bot.*:SEAHUB_FEISHU_BOT_APP_ID/APP_SECRET/CHAT_ID/ENABLED/OPEN_API_BASE_URL | admin-service、beex-service、beex-sso;服务端异常告警复用此群 |
| 管理后台 SSO 登录 | seahub.feishu.oauth.*:SEAHUB_FEISHU_OAUTH_TENANT_KEY/SELF_BASE_URL/PRD_BASE_URL/SESSION_TTL_SECONDS | beex-sso（SsoFeishuOAuthController,回调 /admin/auth/feishu/callback）、admin-service 内嵌登录 |
| 事件订阅回调 | seahub.feishu.event.*:SEAHUB_FEISHU_EVENT_VERIFICATION_TOKEN、...CORE_WEBHOOK_ENABLED | beex-service 飞书事件回调验签 |
密钥:feishu-bot-app-secret(app-secret)。
1.2 八个「webhook 群机器人」目的地(散落、命名不一)
| webhook | 密钥(OOS) | 当前用途 |
|---|---|---|
SEAHUB_FEISHU_WEBHOOK_URL/SECRET | feishu-webhook-secret | 通用飞书 webhook(回退兜底) |
SEAHUB_LARK_WEBHOOK_URL/SECRET | lark-webhook-secret | CI/CD 部署通知(云效 FeishuPlugin:admin-service、ai-ops-worker、admin-page) |
SEAHUB_OPS_LARK_WEBHOOK_URL/SECRET | ops-lark-webhook-secret | 运维群;monitor 告警默认走它 |
SEAHUB_MONITOR_ALARM_FEISHU_URL/SECRET | — | 云监控告警回调 → 落库 + 转发飞书 |
SEAHUB_I18N_EDITOR_FEISHU_WEBHOOK_URL/SECRET | — | 文案(i18n)编辑通知 |
SEAHUB_H5_PACKAGE_NOTIFY_FEISHU_WEBHOOK_URL/SECRET | — | H5 离线包发布通知(回退链 h5→ops-lark→feishu→lark) |
SEAHUB_APP_LOG_FEEDBACK_EXTRA_LARK_WEBHOOK_URL/SECRET | app-log-feedback-extra-lark-webhook-secret | App 反馈通知 |
SEAHUB_AFFILIATE_ORDER_NOTIFICATION_EXTRA_LARK_WEBHOOK_URL/SECRET | affiliate-order-notification-extra-lark-webhook-secret | 联盟订单通知 |
另:beex-doc GitHub Actions(文档变更通知)独立用 FEISHU_APP_ID/FEISHU_APP_SECRET/FEISHU_DOC_NOTIFY_CHAT_ID(存在 GitHub Secrets,不在 OOS),走 App API 发消息。
2. 目标方案(新 Lark 组织,更合理)
原则
- 命名统一到
LARK:环境变量前缀SEAHUB_LARK_*、属性命名空间seahub.lark.*,不再飞书/Lark 混用。 - 一个自建应用承载 SSO + 机器人 API + 事件订阅(一套凭证)。
- webhook 目的地从 8 个收敛到 3 个「按用途分群」,去掉回退链。
- 密钥单一来源:全部进阿里云 OOS(
.ai-workbench/secret);GitHub Actions 只引用同一套值。
2.1 一个 Lark 自建应用
| 键 | 说明 |
|---|---|
SEAHUB_LARK_APP_ID / SEAHUB_LARK_APP_SECRET | 新 Lark 应用凭证(机器人 API + SSO 共用) |
SEAHUB_LARK_OAUTH_TENANT_KEY | 新组织 tenant key(SSO 用) |
SEAHUB_LARK_EVENT_VERIFICATION_TOKEN(+可选 ..._ENCRYPT_KEY) | 事件订阅回调验签/解密 |
SEAHUB_LARK_BOT_CHAT_ID | 机器人主动发消息的默认目标群 chat_id |
SEAHUB_LARK_OPEN_API_BASE_URL | 待确认:新组织是 Lark 海外版 https://open.larksuite.com 还是飞书国内 https://open.feishu.cn(见 §5) |
| SSO 重定向 URL | 在 Lark 应用后台加:https://sso.beexofficial.com/admin/auth/feishu/callback(beex-sso)+ admin-service 内嵌登录域(如仍用) |
2.2 三个按用途分群的 webhook 机器人
| 群 / 键 | 收敛谁 |
|---|---|
告警群 SEAHUB_LARK_ALERT_WEBHOOK_URL/SECRET | 服务端异常告警、云监控告警(monitor + monitor.alarm)、运维(ops) |
研发/发布群 SEAHUB_LARK_DEVOPS_WEBHOOK_URL/SECRET | CI/CD 部署通知(云效各 pipeline)、H5 包发布、i18n 文案编辑、文档变更(beex-doc 建议改用 webhook 或统一到此应用) |
业务运营群 SEAHUB_LARK_BIZ_WEBHOOK_URL/SECRET | 联盟订单通知、App 反馈 |
每个群 = 新 Lark 组织里建一个群 + 加一个「自定义机器人」→ 拿到 webhook URL + 签名密钥。三个足够;确需再细分时按此模式加,不要再一功能一套。
3. 旧 → 新 映射与取舍
| 旧 | 新 | 处置 |
|---|---|---|
seahub.feishu.bot.* / SEAHUB_FEISHU_BOT_* | seahub.lark.bot.* / SEAHUB_LARK_APP_ID/APP_SECRET/BOT_CHAT_ID | 改名迁移 |
seahub.feishu.oauth.* / SEAHUB_FEISHU_OAUTH_* | seahub.lark.oauth.* / SEAHUB_LARK_OAUTH_TENANT_KEY 等 | 改名迁移(tenant-key 换新组织) |
SEAHUB_FEISHU_EVENT_VERIFICATION_TOKEN | SEAHUB_LARK_EVENT_VERIFICATION_TOKEN | 改名迁移 |
SEAHUB_LARK_WEBHOOK_* / SEAHUB_OPS_LARK_WEBHOOK_* / SEAHUB_MONITOR_ALARM_FEISHU_* | 并入 SEAHUB_LARK_ALERT_WEBHOOK_*(部署通知并入 DEVOPS) | 收敛/废弃 |
SEAHUB_H5_PACKAGE_NOTIFY_FEISHU_* / SEAHUB_I18N_EDITOR_FEISHU_* | 并入 SEAHUB_LARK_DEVOPS_WEBHOOK_* | 收敛/废弃 |
SEAHUB_AFFILIATE_..._EXTRA_LARK_* / SEAHUB_APP_LOG_FEEDBACK_EXTRA_LARK_* | 并入 SEAHUB_LARK_BIZ_WEBHOOK_* | 收敛/废弃 |
SEAHUB_FEISHU_WEBHOOK_*(通用兜底)+ 各深层回退链 | 删除,不再需要兜底 | 废弃 |
| OOS 密钥:feishu-bot-app-secret、feishu-webhook-secret、lark-webhook-secret、ops-lark-webhook-secret、affiliate-...、app-log-... | 新:lark-app-secret、lark-alert-webhook-secret、lark-devops-webhook-secret、lark-biz-webhook-secret | 备份后删旧 |
beex-doc GitHub Secrets FEISHU_APP_ID/SECRET/DOC_NOTIFY_CHAT_ID | 换成新 Lark 应用凭证 + DEVOPS 群 chat_id | 换值 |
| 旧飞书组织的自建应用 + tenant | — | 停用/删除 |
4. 迁移 Runbook(执行顺序)
- 新 Lark 组织后台:①建 1 个自建应用,拿
App ID / App Secret / Verification Token / Encrypt Key,开权限(机器人发消息、SSO 登录 scope);②配 SSO 重定向 URL(见 §2.1);③建 3 个群,每群加自定义机器人拿webhook URL + 签名密钥;④拿机器人默认群chat_id与新组织tenant_key;⑤确认 open-api 域名(§5)。 - 写入 OOS 密钥(
.ai-workbench/secret set):lark-app-secret、lark-alert-webhook-secret、lark-devops-webhook-secret、lark-biz-webhook-secret;非敏感项(app-id/tenant-key/chat-id/webhook-url)进云效流水线变量。 - 改代码/配置:各仓库
application.properties命名空间seahub.feishu.*→seahub.lark.*、envSEAHUB_FEISHU_*→SEAHUB_LARK_*;webhook 8→3 收敛、删回退链;云效 pipeline(admin-service/ai-ops-worker/admin-page 的 FeishuPlugin)与 beex-doc GH Actions 同步换键。回调路径/admin/auth/feishu/callback可保留(向后兼容)或统一改/lark/。 - 下发生产:
.ai-workbench/secret apply+ 部署各服务。 - 验证:SSO 登录管理后台通过;告警群/研发群/业务群各发一条测试消息成功;一次部署的云效通知到达;文档变更通知到达。
- 废弃旧:确认新配置全绿后,备份并删除旧 OOS 密钥、停用旧飞书组织应用、清理旧云效/GitHub 变量。
5. 待你确认的关键决策
- open-api 域名:新 Lark 组织是 Lark 海外版(
open.larksuite.com) 还是 飞书国内(open.feishu.cn)?—— 决定SEAHUB_LARK_OPEN_API_BASE_URL与 SSO/事件回调域。 - 分群粒度:确认「告警 / 研发发布 / 业务运营」3 群是否合适,还是要按 3 个国家/环境(id-test、id-prod)再拆。
- SSO 回调路径:是否保留
/admin/auth/feishu/callback(改动最小),还是趁迁移统一改成/admin/auth/lark/callback(更干净但要同步前端与后台重定向白名单)。 - beex-doc 文档通知:继续用 App API(需 GitHub 存 App 凭证),还是改成 webhook(和其它统一、更省事)。
- 新组织的实际凭证:App ID/Secret、tenant-key、3 组 webhook、chat-id 我拿不到(要在新 Lark 后台创建后给我),这是执行"重置"的前置。