飞书与腾讯会议对接实战：SSO+Webhook+Docker中间件设计

1. 为什么“飞书—腾讯会议对接”不是简单配个Webhook就能跑通？

飞书和腾讯会议，这两个国内企业协同工具的头部玩家，在实际办公场景里经常被同时部署——市场团队用飞书做项目管理与知识沉淀，销售团队用腾讯会议开客户演示，HR用飞书审批流程，却要切到腾讯会议查会议纪要。这种割裂感，就是“对接”需求的真实起点。它从来不是技术炫技，而是解决一个具体痛点：会议信息不能自动同步、状态无法闭环、人工搬运易出错、审计留痕难追溯。

我去年在一家中型SaaS公司落地这个对接时，第一周就踩了三个典型坑：

• 飞书机器人发消息到群，但腾讯会议创建成功后，飞书收不到回调（后来发现是腾讯会议Webhook未开启“会议创建事件”，且飞书侧未配置对应事件订阅）；
• 会议链接生成后直接发到飞书群，但点击跳转时提示“无权限访问”，排查发现是腾讯会议链接带了临时token，而飞书卡片不支持自动携带用户上下文透传；
• 最致命的是SSO单点登录打通失败——飞书员工用企业微信账号登录腾讯会议，结果会议系统识别为“未授权第三方应用”，根本进不去会议室。

这背后暴露的本质问题，是很多人忽略的：飞书与腾讯会议之间没有官方直连通道，所有“对接”都是基于双方开放平台能力的松耦合集成，必须自己设计状态机、补全身份链路、兜住网络抖动与事件丢失。所谓“对接”，其实是构建一套轻量级中间件：它要能监听腾讯会议的生命周期事件（创建/开始/结束/取消），映射飞书组织架构中的成员关系，校验SSO会话有效性，并通过Webhook或Bot API完成双向通知与数据写入。

关键词里反复出现的“Docker”，恰恰说明了行业共识——没人愿意在生产环境裸跑Python脚本。这套中间件必须容器化部署，具备水平扩展能力（比如应对季度财报季会议并发激增3倍），还要能快速回滚（某次腾讯会议API变更导致500错误，我们15分钟内切回旧镜像）。而“SSO”和“Webhook”之所以高频并列，是因为它们构成信任基石：SSO解决“你是谁”，Webhook解决“发生了什么”，缺一不可。

所以，这篇文章不讲“如何开通飞书开发者后台”，也不教“怎么下载腾讯会议SDK”。我要带你从零搭建一个真实可用的对接服务——它能自动把腾讯会议日程同步到飞书日历，会议结束后推送含参会人、时长、录制地址的结构化卡片，当飞书审批流批准某项会议预算后，自动调用腾讯会议API创建专属会议室。所有代码可直接运行，所有配置有明确依据，所有坑我都替你踩过。

2. 对接架构设计：为什么必须绕过“官方插件”走自建服务？

市面上能看到两种所谓“飞书—腾讯会议对接”方案：一种是飞书应用市场里标着“腾讯会议”的插件，另一种是技术博客里写的“用Python调Webhook”。前者看似省事，后者看似自由。但我在三家客户现场验证后，果断否定了这两条路——原因很实在：功能阉割严重，且无法满足企业级可靠性要求。

先说飞书官方插件。它确实能实现基础功能：在飞书日历里点击“新建会议”，弹出腾讯会议创建窗口。但问题在于：

• 它完全依赖飞书客户端渲染，一旦用户用网页版飞书，插件直接失效；
• 会议创建后，所有后续状态（如主持人中途退出、参会人静音状态变更）都无法同步；
• 更关键的是，它根本不处理SSO——插件登录态独立于飞书主账号，员工需二次输入腾讯会议密码，违背“一次登录，处处通行”原则。

再看纯Webhook方案。很多教程教你怎么在腾讯会议后台填一个飞书机器人的Webhook地址。这确实能收到事件，但立刻遇到硬伤：

• 腾讯会议Webhook只推送JSON格式的原始事件，字段命名混乱（比如meeting_id有时是字符串有时是数字），且文档更新滞后；
• 飞书机器人Webhook接收端无认证机制，任何知道URL的人都能伪造事件（曾有客户因此被刷屏发送垃圾会议链接）；
• 最致命的是，Webhook本身无重试保障——腾讯会议服务器偶尔超时，事件就永久丢失，而会议结束这种关键事件丢了，意味着无人知晓会议已结束。

所以，我们最终采用的架构是：自建Docker化服务作为可信中间层。它长这样：

腾讯会议API（事件推送/主动查询） ↓ [飞书-腾讯会议对接服务] ← Docker容器集群（Nginx负载 + Flask/Gunicorn + Redis队列） ↓ 飞书Bot API（发送卡片/更新日历） + 飞书SSO鉴权服务（校验JWT Token）

这个设计解决了所有痛点：
✅状态可靠：腾讯会议推送事件到我们的服务，我们先存入Redis队列，再异步处理。即使处理逻辑卡住，队列里的事件也不会丢；
✅身份可信：所有飞书来的请求，必须携带由飞书签发的JWT Token，我们用飞书提供的公钥实时验签；所有腾讯会议来的请求，必须携带腾讯会议颁发的Access Token，我们调用其/v1/user/me接口反向校验；
✅双向可控：不是被动等Webhook，而是主动轮询+事件驱动结合——对高优先级事件（如会议开始）用Webhook实时响应，对低频事件（如会议纪要生成）用定时任务每5分钟拉取一次，避免漏单；
✅运维友好：Docker Compose一键启停，日志统一输出到stdout供ELK采集，CPU占用超80%自动扩容副本。

提示：不要试图用Serverless函数（如阿里云FC）替代Docker服务。Serverless冷启动延迟高（平均300ms），而会议开始前1分钟必须完成飞书卡片预生成，这点延迟会导致用户体验断层。我们实测Docker容器常驻内存，响应稳定在12ms内。

3. SSO身份映射：如何让飞书ID和腾讯会议ID真正“认得上”？

SSO（单点登录）常被误解为“点一次登录按钮就完事”。但在飞书与腾讯会议对接中，SSO真正的价值是建立跨系统身份锚点——让飞书里的张三（employee_id: FE2023001）和腾讯会议里的张三（user_id: tx_7a8b9c）在后台被识别为同一人。没有这个锚点，所有自动化都成空中楼阁：你无法把飞书审批流里指定的“会议主持人”准确映射到腾讯会议API所需的host_id参数，也无法在会议结束后精准@飞书群里的参会人。

难点在于：飞书和腾讯会议的用户体系天然隔离。飞书用手机号/邮箱作为主标识，腾讯会议用微信号/企业微信ID。而企业微信又可能和飞书同属一个集团，但ID格式完全不同。我们试过三种映射方案，最终选定第三种：

3.1 方案对比：为什么“邮箱匹配”最稳妥？

方案	实现方式	缺陷	我们的实测结果
API实时查询	每次需要映射时，调用飞书/contact/v3/users和腾讯会议/v1/users接口查邮箱	调用量爆炸（一场会议10人=20次API调用），腾讯会议QPS限制严格（5次/秒）	单场会议平均耗时2.3秒，超时率17%
数据库硬编码	运维手动维护一张feishu_id ↔ tx_user_id映射表	新员工入职需人工录入，离职员工ID失效难追踪	上线首月就因3名员工换邮箱导致会议通知发错人
邮箱正则归一化	统一提取邮箱本地部分（@前），去除大小写和特殊字符（如[e-mail]→zhangsan），再比对	依赖邮箱一致性，但企业邮箱规范度高，且飞书/腾讯会议均强制绑定企业邮箱	99.2%员工匹配成功，剩余0.8%由HR后台补录

我们最终采用邮箱归一化方案，因为：

• 飞书管理员后台可导出全员邮箱列表（CSV格式），腾讯会议企业版也提供/v1/users/export接口导出带邮箱的用户数据；
• 归一化规则极简：re.sub(r'[^a-zA-Z0-9]', '', email.split('@')[0].lower())，一行Python搞定；
• 匹配失败时，服务自动告警并生成待办：飞书机器人推送消息到IT群，“请核查以下员工邮箱：李四（feishu_id: FS456）未在腾讯会议用户库中找到匹配项”。

注意：腾讯会议API返回的邮箱字段名为email，但飞书API返回的是email（v3）和work_email（v2）两个字段。我们优先取work_email，因其为企业邮箱；若为空，则取email并校验是否含公司域名。这个细节不处理，会导致外包员工邮箱匹配失败。

3.2 SSO会话透传：如何让飞书用户点击会议链接直接进腾讯会议室？

这是用户感知最强烈的环节。理想状态是：飞书群里的会议卡片，用户点击“加入会议”按钮，无需再次登录，直接进入腾讯会议室。这需要打通SSO会话链路。

技术路径是：

1. 用户在飞书内点击卡片按钮，飞书前端发起/api/redirect请求到我们的服务；
2. 我们服务校验该用户飞书JWT Token有效性，提取user_id；
3. 根据user_id查邮箱映射表，得到腾讯会议user_id；
4. 调用腾讯会议/v1/users/{user_id}/meeting_join_url接口，生成带签名的临时加入链接（有效期15分钟）；
5. 302重定向到该链接，腾讯会议服务端验证签名后，自动登录并跳转会议室。

关键点在于第4步的签名算法。腾讯会议要求：

• 将app_id+user_id+timestamp（毫秒时间戳）拼接；
• 用腾讯会议分配的secret_key进行HMAC-SHA256签名；
• 签名结果Base64编码后作为sign参数。

我们封装成Python函数：

import hmac import base64 import time def generate_meeting_join_url(app_id: str, user_id: str, secret_key: str) -> str: timestamp = int(time.time() * 1000) sign_str = f"{app_id}{user_id}{timestamp}" signature = base64.b64encode( hmac.new( secret_key.encode(), sign_str.encode(), digestmod='sha256' ).digest() ).decode() return f"https://meeting.tencent.com/xxxx?appid={app_id}&userid={user_id}&timestamp={timestamp}&sign={signature}"

提示：secret_key绝不能硬编码在代码里！我们用Docker环境变量TX_SECRET_KEY注入，配合Vault做密钥轮换。曾有客户把key写死在GitHub，导致被爬虫批量生成会议链接——这是真实发生过的安全事件。

4. Webhook事件精炼：如何过滤无效事件并构建可靠状态机？

腾讯会议Webhook推送的事件类型多达17种，但真正需要对接的只有5类：meeting.created、meeting.started、meeting.ended、meeting.cancelled、meeting.recorded。其他如user.joined、user.left等事件，因高频且易受网络抖动影响，我们选择弃用——宁可牺牲实时性，也要保证核心状态100%准确。

更麻烦的是，同一事件可能重复推送。腾讯会议文档明确说明：“网络异常时，Webhook可能重复投递”。我们实测发现，平均每1000次事件推送，有3.2次重复（主要发生在会议结束瞬间）。如果不对重复事件去重，会导致飞书群被刷屏发“会议已结束”卡片。

解决方案是：基于事件唯一ID + Redis布隆过滤器（Bloom Filter）实现幂等。具体步骤：

1. 腾讯会议每个事件JSON里都有event_id字段（如tx_event_abc123_def456），我们提取它作为去重键；
2. 服务启动时，初始化Redis连接，使用pybloom_live库创建布隆过滤器（容量100万，误判率0.01%）；
3. 收到事件后，先检查event_id是否已在布隆过滤器中：
   • 若存在，直接返回HTTP 200（告诉腾讯会议“已处理”）；
   • 若不存在，将event_id加入过滤器，再执行业务逻辑；
4. 每24小时自动清空布隆过滤器（避免内存无限增长）。

为什么不用Redis SET？因为SET内存占用大（每个ID约64字节），而布隆过滤器100万容量仅占1.2MB内存。我们压测过：单节点服务每秒处理200个事件，Redis内存占用稳定在15MB以内。

4.1 会议状态机：从“创建”到“归档”的7个状态跃迁

单纯按事件类型处理远远不够。一场会议的真实生命周期远比API文档复杂。比如：

• meeting.created事件推送后，会议可能被主持人取消（触发meeting.cancelled），也可能从未开始就过期；
• meeting.ended事件推送时，录制文件可能尚未生成（meeting.recorded事件延后3-5分钟才来）；
• 更隐蔽的是：主持人可能中途离开，由其他人接管主持，此时meeting.started事件里的host_id已失效。

因此，我们设计了7状态机，存储在PostgreSQL中（非Redis，因需事务和历史追溯）：

状态	触发条件	飞书动作	数据库字段
created	收到meeting.created	发送“会议待开始”卡片，含预约时间、主持人、入会链接	status='created',created_at=now()
started	收到meeting.started	更新卡片状态为“进行中”，添加“静音/共享屏幕”快捷按钮	status='started',started_at=now()
host_changed	meeting.started中host_id与created时不一致	@原主持人和新主持人，发送交接提醒	host_id='new_id',updated_at=now()
ended	收到meeting.ended	卡片置灰，显示“会议已结束”，但暂不展示录制地址	status='ended',ended_at=now()
recorded	收到meeting.recorded	更新卡片，添加“查看回放”按钮，附带播放页URL和下载链接	status='recorded',record_url='xxx'
cancelled	收到meeting.cancelled	卡片打上“已取消”标签，显示取消原因（如有）	status='cancelled',cancelled_at=now()
archived	recorded后24小时	自动归档，卡片折叠，仅保留摘要信息	status='archived',archived_at=now()

这个状态机的关键价值在于：它让飞书卡片成为会议事实的单一可信源。当销售同事问“昨天的客户会议回放在哪？”，他不需要切到腾讯会议后台查，直接翻飞书群历史记录即可——卡片始终反映最新状态。

注意：meeting.ended和meeting.recorded事件的时间差是业务指标。我们监控该差值，若超过10分钟，自动告警并触发人工核查。上线三个月，共捕获7次腾讯会议录制服务异常，平均修复时效42分钟。

5. Docker部署实战：从本地调试到生产环境的完整交付链

所有逻辑写完，最终要跑在服务器上。我们拒绝“本地能跑就行”的心态——生产环境的Docker部署，本质是把开发、测试、运维的协作契约固化到代码里。下面是我打磨半年形成的标准化交付链。

5.1 Dockerfile：为什么基础镜像选python:3.11-slim而非alpine？

FROM python:3.11-slim # 安装系统依赖（slim版已剔除gcc等，需显式安装） RUN apt-get update && apt-get install -y \ libpq-dev \ && rm -rf /var/lib/apt/lists/* # 复制requirements.txt并安装（分层缓存优化） COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . /app WORKDIR /app # 创建非root用户（安全基线） RUN groupadd -g 1001 -r app && \ useradd -r -u 1001 -g app app USER app # 暴露端口 EXPOSE 8000 # 启动命令 CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "app:app"]

选python:3.11-slim而非alpine，是因为：

• alpine的musl libc与某些Python包（如psycopg2-binary）存在兼容问题，曾导致PostgreSQL连接随机失败；
• slim镜像仅128MB，比alpine（112MB）略大，但稳定性高得多；
• slim基于Debian，企业内网防火墙策略通常更适配Debian系。

提示：pip install必须加--no-cache-dir。否则Docker构建时会缓存pip索引，导致不同环境安装版本不一致。我们吃过亏——测试环境装的是requests==2.31.0，生产环境因缓存装了2.30.0，后者不支持HTTP/2，会议API调用全部超时。

5.2 docker-compose.yml：如何用最少配置实现高可用？

version: '3.8' services: web: build: . image: feishu-tx-meeting:latest restart: unless-stopped environment: - FEISHU_APP_ID=${FEISHU_APP_ID} - FEISHU_APP_SECRET=${FEISHU_APP_SECRET} - TX_APP_ID=${TX_APP_ID} - TX_SECRET_KEY=${TX_SECRET_KEY} - DATABASE_URL=postgresql://user:pass@db:5432/meeting - REDIS_URL=redis://redis:6379/0 ports: - "8000:8000" depends_on: - db - redis healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 db: image: postgres:15-alpine environment: - POSTGRES_DB=meeting - POSTGRES_USER=user - POSTGRES_PASSWORD=pass volumes: - ./postgres-data:/var/lib/postgresql/data redis: image: redis:7-alpine command: redis-server --save 60 1 --loglevel warning volumes: - ./redis-data:/data

关键配置解读：

• restart: unless-stopped：确保容器崩溃后自动重启，但允许运维手动docker stop停止；
• healthcheck：Docker Swarm或K8s会据此判断服务健康状态，避免流量打到假死进程；
• redis的--save 60 1：每60秒且至少1个key变更时持久化，平衡性能与数据安全；
• db卷挂载用./postgres-data而非/var/lib/postgresql/data，方便本地备份。

5.3 生产环境 checklist：上线前必须验证的12件事

项目	验证方法	不通过后果	我们的处理方式
1. 环境变量完整性	docker-compose config检查是否所有${VAR}都被替换	启动失败，报错KeyError	CI流水线增加envsubst < docker-compose.yml.template > docker-compose.yml步骤
2. 数据库连接池	SELECT count(*) FROM pg_stat_activity WHERE datname='meeting';	连接数超限，新请求排队	SQLALCHEMY_POOL_SIZE=20，SQLALCHEMY_MAX_OVERFLOW=10
3. Redis连接超时	redis-cli -h redis ping	布隆过滤器失效，重复事件暴增	REDIS_SOCKET_TIMEOUT=5，REDIS_RETRY_ON_TIMEOUT=True
4. Webhook签名时效	手动构造过期timestamp的腾讯会议Webhook	事件被拒，状态丢失	服务启动时校准系统时间，ntpd -q
5. 飞书Bot限频	模拟1秒内发10条消息	Bot被封禁24小时	内置令牌桶，rate_limit=5/minuteper chat_id
6. 日志结构化	docker logs web | grep '"level":"error"'	故障定位耗时翻倍	所有日志JSON化，{"event":"meeting_started","user_id":"FS123","status":"success"}
7. SSL证书有效性	openssl s_client -connect your-domain.com:443 -servername your-domain.com	飞书/腾讯会议回调失败	Nginx配置ssl_trusted_certificate指向Let's Encrypt根证书
8. 时区一致性	docker exec web datevsdocker exec db date	会议时间显示错乱	所有容器-e TZ=Asia/Shanghai
9. CPU限制	docker stats web观察峰值	会议高峰时服务OOM	deploy.resources.limits.cpu: '1.0'
10. 网络策略	curl -I https://api.meeting.tencent.comfrom inside container	腾讯会议API调用超时	防火墙放行api.meeting.tencent.com:443
11. 备份策略	pg_dump -h db -U user meeting > backup.sql	数据丢失无法恢复	每日02:00自动备份到S3，保留7天
12. 回滚预案	docker-compose pull && docker-compose up -d切换镜像	版本升级失败，服务中断	CI发布时自动打tag，feishu-tx-meeting:v1.2.3，回滚只需改compose文件

最后强调一个血泪教训：永远不要在生产环境用docker-compose up -d直接启动。必须通过CI/CD流水线构建镜像、推送到私有Registry、再由Ansible或K8s Helm Chart部署。我们曾因运维手动docker-compose up，导致线上版本与Git记录不符，一次安全补丁漏发，被渗透测试团队打穿。

6. 飞书卡片设计：如何让一条通知承载完整会议上下文？

技术实现只是骨架，飞书卡片才是用户每天接触的血肉。很多团队把对接做成“发个链接”，结果用户反馈：“每次都要点开链接再找入口，比原来还慢”。问题不在技术，而在交互设计——卡片必须成为会议信息的聚合中心，让用户一眼获取所有关键动作。

我们摒弃了传统“文字+链接”模式，采用飞书卡片的高级组件组合：

6.1 结构化卡片的7个必含模块

{ "config": {"wide_screen_mode": true}, "elements": [ { "tag": "div", "text": { "content": "**会议主题：${title}**\n主持人：${host_name}\n时间：${start_time} - ${end_time}", "tag": "plain_text" } }, { "tag": "action", "actions": [ { "tag": "button", "text": {"content": "▶️ 加入会议", "tag": "plain_text"}, "type": "primary", "url": "${join_url}" }, { "tag": "button", "text": {"content": "📝 查看日程", "tag": "plain_text"}, "type": "default", "url": "${calendar_url}" } ] }, { "tag": "hr" }, { "tag": "div", "text": {"content": "**参会人（${count}人）**", "tag": "plain_text"} }, { "tag": "div", "fields": [ {"text": {"content": "• ${name1}", "tag": "plain_text"}}, {"text": {"content": "• ${name2}", "tag": "plain_text"}}, {"text": {"content": "• ${name3}...", "tag": "plain_text"}} ] }, { "tag": "hr" }, { "tag": "div", "text": { "content": "📌 **会议资料**\n• [飞书云文档](${doc_url})\n• [腾讯会议录制](${record_url})", "tag": "plain_text" } } ] }

这个设计解决了三大体验痛点：
✅减少点击次数：加入会议按钮直接跳转，无需二次确认；
✅消除信息焦虑：参会人名单折叠显示，避免长列表刷屏；
✅强化上下文关联：文档和录制链接并列呈现，用户无需在不同系统间切换。

6.2 动态状态渲染：卡片如何随会议进展自动进化？

飞书卡片不支持服务端实时更新，但我们用“卡片ID复用+状态覆盖”实现伪实时：

• 第一次发送卡片时，生成唯一card_id（如meeting_card_abc123）；
• 后续状态更新（如会议开始、结束），用相同card_id重新发送新卡片；
• 飞书客户端自动替换旧卡片，用户看到的是最新状态。

关键代码（飞书Bot SDK）：

def send_or_update_card(chat_id: str, card_id: str, elements: list): # 先尝试更新，失败则新建 try: requests.post( url="https://open.feishu.cn/open-apis/card/v2/update", headers={"Authorization": f"Bearer {bot_token}"}, json={ "card_id": card_id, "card": {"config": {"wide_screen_mode": True}, "elements": elements} } ) except: # 更新失败，新建卡片 requests.post( url="https://open.feishu.cn/open-apis/card/v2/send", headers={"Authorization": f"Bearer {bot_token}"}, json={ "chat_id": chat_id, "card": {"config": {"wide_screen_mode": True}, "elements": elements} } )

注意：card_id必须全局唯一且可预测。我们用f"meeting_card_{meeting_id}"生成，meeting_id来自腾讯会议事件。这样即使服务重启，也能根据事件ID重建卡片关联。

6.3 权限控制：为什么卡片里绝不出现“删除会议”按钮？

安全红线：飞书卡片上的操作，必须与当前用户在腾讯会议中的实际权限严格对齐。我们曾设计过“一键取消会议”按钮，结果被销售总监误点，导致重要客户会议被取消——因为该按钮调用的是腾讯会议DELETE /v1/meetings/{id}，而飞书Bot的Token权限是全局的。

最终方案是：所有卡片按钮只触发“查询类”操作（加入、查看、下载），写操作（取消、结束、修改）必须跳转到腾讯会议Web端完成。并在卡片底部加一行小字：
💡 提示：会议管理操作请在腾讯会议App或网页端进行，确保权限合规

这看似降低便利性，实则规避了越权风险。企业级系统的第一守则是：宁可多点一次，不可错放一权。

7. 故障排查手册：从“网络不可用”到“事件丢失”的15分钟响应流程

再完美的设计，也会遇到故障。我们把三年运维经验浓缩成一份《15分钟响应手册》，确保任何值班工程师都能快速定位问题。

7.1 首要诊断：区分是飞书问题还是腾讯会议问题？

当用户报告“飞书收不到会议通知”，第一步不是查代码，而是做三方验证：

步骤	操作	预期结果	判定结论
1. 检查腾讯会议Webhook状态	登录腾讯会议管理后台 → 开放平台 → Webhook设置 → 查看“投递状态”	显示“正常”且最近10分钟有成功记录	问题在飞书侧或中间件
2. 检查飞书Bot状态	访问https://open.feishu.cn/api/bot/v2/info?app_id=${APP_ID}	返回{"code":0,"msg":"success","data":{"status":"normal"}}	Bot正常，问题在中间件
3. 检查中间件健康状态	curl http://your-domain.com/health	返回{"status":"healthy","db":"ok","redis":"ok"}	中间件正常，问题在配置或网络

这个流程5分钟内可完成。我们把这三个检查项做成Shell脚本，放在服务器/opt/check.sh，值班人员只需bash /opt/check.sh。

7.2 中间件日志分析：如何从10万行日志里快速定位故障？

中间件日志按INFO/WARNING/ERROR分级。我们约定：

• INFO：常规事件处理（如[INFO] Received meeting.created event for tx_meeting_789）；
• WARNING：可恢复异常（如[WARNING] Redis connection timeout, retrying...）；
• ERROR：阻断性错误（如[ERROR] Failed to verify JWT token from Feishu: invalid signature）。

排查口诀：先看ERROR，再扫WARNING，最后查INFO中的event_id。

例如，用户反馈“会议结束后没收到卡片”，我们这样做：

1. grep "ERROR" /var/log/feishu-tx-meeting.log | tail -20→ 无ERROR；
2. grep "WARNING" /var/log/feishu-tx-meeting.log | tail -20→ 发现[WARNING] Meeting recorded event delayed by 8min, triggering manual fetch；
3. grep "tx_meeting_789" /var/log/feishu-tx-meeting.log→ 找到[INFO] Fetched recording URL: https://record.tencent.com/xxx，但无send_card日志；
4. 进一步查grep "send_card.*tx_meeting_789" /var/log/feishu-tx-meeting.log→ 空，说明卡片发送逻辑未触发；
5. 检查代码，发现meeting.recorded事件处理器里有个if status == 'ended'判断，但数据库状态仍是'started'（因meeting.ended事件丢失）→ 定位到Webhook重复投递导致状态机卡死。

7.3 网络问题专项：为什么“network unavailable”错误90%是DNS问题？

飞书客户端报错network unavailable, please go to feishu network diagnosis，表面是网络问题，实则87%源于DNS解析失败。原因：

• Docker容器默认使用宿主机DNS，但某些云厂商（如阿里云）的DNS服务器会拦截非标准端口查询；
• 腾讯会议API域名api.meeting.tencent.com的CNAME记录指向txmeeting.tls.aliyuncs.com，而该域名在部分DNS服务商处解析超时。

解决方案：

• 在docker-compose.yml中显式指定DNS：

  services: web: dns: - 114.114.114.114 - 8.8.8.8

• 或在Docker daemon.json中全局配置：

  { "dns": ["114.114.114.114", "8.8.8.8"] }

我们上线后，network unavailable投诉下降92%。这个细节，文档里从不提，但却是高频痛点。

最后分享一个技巧：把所有API调用封装成带重试的函数，重试时更换DNS服务器。我们用requests.adapters.HTTPAdapter(max_retries=3)，并在重试时切换DNS，成功率从94%提升到99.97%。

我在实际落地这个对接时，最大的体会是：企业级集成不是堆砌技术，而是管理不确定性。腾讯会议API会变更，飞书Bot权限模型会调整，网络策略会收紧，甚至员工邮箱格式会因HR系统升级而改变。所谓“稳定”，不是写完代码就一劳永逸，而是建立一套持续验证、快速响应、自动修复的机制。现在回头看，当初花两周做的布隆过滤器、花三天写的卡片状态机、花一天配置的Docker健康检查，每一个看似冗余的设计，都在后来某个凌晨三点的故障里，成了救火的关键。