1. 项目概述与核心价值最近在折腾一个挺有意思的自动化场景如何把飞书群里的消息自动、可靠地转发到微信上。听起来像是简单的消息搬运工但真做起来你会发现这里面涉及到跨平台、协议适配、消息保序、状态同步等一系列“坑”。我花了些时间基于一个名为wxkingstar/clawrelay-feishu-server的开源项目把它落地并深度优化了一番。这个项目的核心就是扮演一个“中继服务器”的角色它监听飞书开放平台的事件然后将这些事件比如群消息、消息转换成微信能理解的格式再通过特定的接口推送到个人或群聊。为什么需要这么一个“中继”直接原因很简单飞书和微信是两个完全独立的生态没有官方的、稳定的消息互通渠道。对于需要将飞书工作群的重要通知同步到个人微信或者将飞书机器人接收到的告警、工单信息转发到微信以便及时查看的场景这个中继就成了刚需。它解决的不仅仅是“能收到”更是“如何稳定、准确、不失真地收到”。clawrelay-feishu-server这个名字很贴切“claw”暗示了抓取“relay”就是中继清晰地定义了它的使命。这个项目适合谁呢首先是有跨平台消息同步需求的团队或个人开发者特别是那些重度使用飞书进行协作但又希望关键信息能触达微信的团队。其次是对企业微信、飞书、钉钉等办公平台开放API感兴趣的开发者可以把它当作一个学习事件订阅、消息解析和Webhook处理的绝佳案例。最后对于希望构建稳定、可扩展的自动化流程的运维或产品同学这个项目提供了一个清晰的架构范本。2. 核心架构与设计思路拆解2.1 技术栈选型与考量clawrelay-feishu-server的核心技术栈选择非常务实主要基于 Node.js 生态。选择 Node.js 有几个关键考量首先是其异步非阻塞 I/O 模型非常适合处理大量并发的 HTTP 请求飞书事件推送、向微信发送消息能高效应对消息洪峰。其次是丰富的 npm 生态对于处理 HTTP 服务、加密验证、JSON 解析等任务有成熟的轮子能极大提升开发效率。项目通常会使用Express或Koa这类轻量级 Web 框架来搭建 HTTP 服务器用于接收飞书开放平台的 Webhook 推送。为什么不用更重的框架因为这里的业务逻辑相对聚焦验证请求、解析事件、转换格式、转发消息。轻量级框架足够用且性能开销小部署也更灵活。对于飞书 SDK可能会直接使用官方提供的larksuiteoapi/node-sdk它封装了签名验证、事件解密等复杂流程能避免我们自己踩坑。消息转换和转发是另一个核心。飞书的事件体Event结构复杂包含了会话、消息、发送者等多种信息。而向微信这里通常指通过企业微信应用或公众号接口或个人微信的特定协议如WeChaty发送消息需要完全不同的数据格式。因此项目中必须有一个强大的“消息适配器”Message Adapter层负责将飞书的text、image、file等消息类型映射成微信支持的text、image、file等类型并处理富文本、人员等特殊元素的转换。2.2 整体数据流与组件交互整个系统的数据流可以清晰地分为几个阶段事件订阅与接收在飞书开放平台为指定的应用通常是自建应用配置事件订阅指向我们部署的clawrelay-feishu-server的公网 URL。当飞书群内发生订阅的事件如“接收消息”、“消息已读”飞书服务器会向该 URL 发送一个 HTTPS POST 请求。安全验证与解密服务器收到请求后首要任务是进行安全验证。飞书会携带一个签名X-Lark-Signature和时间戳X-Lark-Request-Timestamp我们需要用应用的Verification Token和Encrypt Key来验证签名的有效性并解密请求体如果启用了加密。这一步至关重要是防止恶意请求的第一道防线。事件解析与路由验证通过后解析 JSON 请求体提取event对象。根据event.type如message和event.message.message_type如text、image进行路由决定由哪个处理器来处理。消息转换与增强处理器调用对应的消息适配器将飞书消息对象转换成目标平台微信的消息对象。这个过程可能涉及内容提取从飞书text消息中提取纯文本处理提及需要将飞书的用户 ID 映射为微信的昵称或备注。媒体处理对于图片、文件飞书返回的是image_key或file_key。我们需要调用飞书的下载文件API 获取临时链接或二进制流然后上传到微信的素材库或通过其他方式发送。这里涉及到文件流的处理和临时存储。上下文补充附加消息来源信息如“来自飞书群[群名]”、“发送者[用户姓名]”。消息发送与状态同步将转换后的消息通过微信的 API如企业微信的“发送应用消息”接口或协议客户端发送出去。同时可以考虑将消息的发送状态成功/失败进行记录甚至异步地回写到飞书例如回复一条“已转发至微信”的消息形成闭环。异步与队列引入为了提升可靠性和应对峰值在“解析”和“发送”之间引入一个消息队列如 Redis List、RabbitMQ是常见的优化手段。服务器解析后将任务推入队列由独立的消费者进程进行发送。这样即使微信接口暂时不可用消息也不会丢失可以在队列中重试。注意直接使用个人微信的协议如基于 Web 协议的库存在账号风险且稳定性无法保证。在生产环境中更推荐使用企业微信作为中转。可以创建一个企业微信应用将消息发送到该应用用户关注该应用即可在微信中接收。这是官方支持且稳定的方案。clawrelay-feishu-server的设计应优先考虑对接企业微信 API。3. 核心细节解析与实操要点3.1 飞书事件订阅的配置“深水区”配置事件订阅是整个流程的起点也是最容易出错的地方。在飞书开放平台你需要创建一个“企业自建应用”。在应用的“事件订阅”页面你需要填写三个核心信息请求网址 URL就是你部署的clawrelay-feishu-server的公网 HTTPS 地址路径例如/feishu/event。飞书只支持 HTTPS所以你需要一个域名和 SSL 证书可以使用 Let‘s Encrypt 免费获取。Verification Token一个由你自定义的字符串用于在“URL 验证”阶段使用。飞书会向你的 URL 发送一个带特定参数的 GET 请求你需要原样返回其中的challenge值。你的服务器代码必须正确处理这个验证请求。Encrypt Key用于加密事件内容的密钥。如果启用飞书推送的事件体会被加密你需要用它来解密。强烈建议启用加密以提升安全性。订阅事件时你需要仔细选择。对于消息转发至少需要订阅im.message.receive_v1接收消息。如果你需要处理消息已读回执或消息撤回还需要订阅相应的事件。这里有个关键点飞书的事件推送有“卡片交互”和“普通消息”之分。如果你希望处理用户点击卡片按钮等交互还需要订阅im.message.interaction等相关事件。在代码中你需要根据header.event_type来区分处理。实操心得在开发调试阶段可以使用ngrok或localtunnel等工具将本地服务暴露为一个临时的公网 HTTPS 地址方便飞书平台回调。但务必注意这些工具生成的地址会变化每次变化后都需要在飞书后台更新“请求网址”。最好在测试环境使用固定域名。3.2 消息解析与转换的“魔鬼细节”飞书的消息结构嵌套较深一个文本消息的 JSON 路径可能类似event.message.content其值是一个 JSON 字符串需要再次解析才能得到真正的文本内容。例如{ event: { message: { content: {\text\:\_user_1 你好这是一条测试消息\}, message_type: text } } }你的代码需要先解析外层的event再解析content字段内的 JSON 字符串。对于提及content中的_user_1是飞书内部的用户 open_id你需要通过飞书 API/contact/v3/users/:user_id去查询该 open_id 对应的真实姓名然后在转换给微信时将其替换为“张三”或根据你的映射规则处理。媒体消息图片、文件的处理更为复杂获取元信息飞书推送的事件中图片消息会包含image_key文件消息包含file_key。调用下载 API使用飞书的下载图片或下载文件API传入image_key/file_key和用户的access_token获取一个临时的、有有效期的下载链接。处理数据你的服务器需要从这个临时链接下载文件数据到内存或临时目录。这里要注意网络超时、文件大小限制飞书和微信都有和错误重试。上传至目标平台将下载的文件数据通过微信企业微信的“上传临时素材”接口进行上传得到微信侧的media_id。发送最后使用这个media_id来构造发送消息。这个过程涉及多次网络 I/O必须做好错误处理和日志记录。一个常见的优化是加入缓存如果同一个image_key在短时间内被多次转发比如群聊中可以缓存其对应的微信media_id避免重复下载和上传节省资源和时间。3.3 微信侧接入的两种路径选择如前所述对接微信侧有两个主要路径路径一企业微信应用推荐用于生产环境注册企业微信创建一个自建应用。在该应用的“接收消息”API设置中配置相同的服务器 URL或另一个端点用于接收用户回复如果需要双向通信。对于单纯的发送主要用到“发送消息”API。获取企业的CorpID、应用的AgentId和Secret。在clawrelay-feishu-server中实现获取企业微信access_token的逻辑需要定时刷新并调用发送应用消息接口。消息可以发送到指定的用户、部门或标签。用户需要在微信中关注“企业微信”公众号并绑定其企业微信账号即可在微信的“企业微信”会话中收到消息。路径二个人微信协议库如 WeChaty仅用于学习或极轻量级场景使用wechaty等基于 Puppet 协议的库。需要处理微信 Web 端或 Pad 端协议的登录可能需扫码、会话管理、消息监听和发送。稳定性风险高腾讯会频繁更新协议导致库失效账号有被限制登录的风险。功能受限通常只能发送给好友或自己所在的群管理能力弱。重要警告对于任何正式、重要的业务场景绝对不要选择路径二。账号安全、消息可达率、功能完整性都无法保障。企业微信 API 是官方、稳定、功能丰富的唯一选择。clawrelay-feishu-server的项目重心应放在与企业微信 API 的深度集成上。4. 环境部署与配置实战4.1 服务器环境准备与部署假设我们使用一台 Linux 服务器如 Ubuntu 22.04进行部署。核心步骤包括安装 Node.js 环境# 使用 NodeSource 安装 LTS 版本的 Node.js curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs node --version # 确认版本获取项目代码并安装依赖git clone https://github.com/wxkingstar/clawrelay-feishu-server.git cd clawrelay-feishu-server npm install # 或使用 yarn/pnpm配置环境变量这是配置的核心避免将敏感信息硬编码在代码中。创建一个.env文件# 飞书应用配置 FEISHU_APP_IDcli_xxxxxx FEISHU_APP_SECRETxxxxxxxxxxxx FEISHU_VERIFICATION_TOKENyour_verification_token FEISHU_ENCRYPT_KEYyour_encrypt_key # 企业微信配置 WECHATY_CORP_IDwwxxxxxx WECHATY_AGENT_ID1000002 WECHATY_AGENT_SECRETxxxxxxxxxxxx # 服务器配置 SERVER_PORT3000 NODE_ENVproduction # Redis 配置如果使用队列 REDIS_URLredis://localhost:6379使用进程守护使用pm2来管理 Node.js 进程保证服务持续运行和崩溃后自动重启。npm install -g pm2 pm2 start ecosystem.config.js # 或直接 pm2 start index.js --name clawrelay pm2 save pm2 startup # 设置开机自启4.2 Nginx 反向代理与 SSL 配置由于飞书要求 HTTPS我们需要配置 Nginx 作为反向代理并配置 SSL 证书。安装 Nginx 和 Certbotsudo apt update sudo apt install nginx certbot python3-certbot-nginx配置 Nginx 站点在/etc/nginx/sites-available/下创建配置文件例如clawrelay.conf。server { listen 80; server_name your-domain.com; # 你的域名 return 301 https://$server_name$request_uri; # HTTP 重定向到 HTTPS } server { listen 443 ssl http2; server_name your-domain.com; # SSL 证书路径由 Certbot 自动生成和配置 ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # 其他 SSL 优化配置... location / { proxy_pass http://localhost:3000; # 指向你的 Node.js 应用 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } # 可选为飞书事件回调专门设置一个路径便于管理和日志 location /feishu/event { # 可以在这里添加一些额外的日志或限流配置 proxy_pass http://localhost:3000/feishu/event; # ... 其他 proxy 设置同上 } }启用站点并获取 SSL 证书sudo ln -s /etc/nginx/sites-available/clawrelay.conf /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置 sudo systemctl reload nginx # 使用 Certbot 自动获取并配置 SSL 证书 sudo certbot --nginx -d your-domain.com执行certbot命令后按照提示操作即可。Certbot 会自动修改你的 Nginx 配置并设置证书自动续期。4.3 飞书与微信后台配置联调这是将整个链路打通的关键一步需要两边平台来回配置。飞书开放平台侧进入开发者后台找到你的应用。权限管理在“权限管理”页面为应用添加所需权限如im:message发送与接收消息、contact:user:readonly读取用户信息等。保存后需要发布新版本并让管理员审核通过。事件订阅在“事件订阅”页面填写配置好的https://your-domain.com/feishu/eventURL、Verification Token和Encrypt Key。点击“保存”后飞书会立即向该 URL 发送一个 GET 请求进行验证。你的服务器必须已启动并正确响应这个验证请求否则保存会失败。订阅事件在下方的事件列表里找到im.message.receive_v1等事件点击“订阅”。确保状态显示“已订阅”。企业微信管理后台侧进入“应用管理”-“自建应用”找到或创建你的应用。记录AgentId和Secret需要点击查看。应用权限在“权限管理”中为应用成员或通讯录范围添加需要接收消息的用户。如果需要双向通信才需要配置“接收消息”的 API。对于单纯发送此步可暂缓。联调测试启动你的clawrelay-feishu-server确保服务运行正常日志无报错。在飞书群中 你的应用机器人或直接向机器人发送一条消息。观察服务器日志应该能看到飞书推送过来的事件日志以及后续处理、调用企业微信 API 的日志。检查目标企业微信用户的微信是否收到了转发的消息。5. 高级功能实现与优化策略5.1 实现消息队列与异步处理直接同步处理“接收-转换-发送”链路在消息量大或下游微信API慢时会导致飞书回调超时飞书有重试机制但可能丢消息。引入消息队列是提升可靠性和吞吐量的标准做法。一个简单的实现是使用Redis的List结构作为队列// 生产者在收到飞书事件并解析后 const redisClient ... // Redis 客户端实例 const messageJob JSON.stringify({ feishuEvent: parsedEvent, receivedAt: Date.now(), // ... 其他上下文 }); await redisClient.lPush(clawrelay:message:queue, messageJob); // 立即响应飞书避免超时 ctx.body { code: 0, msg: success }; // 消费者独立的进程或使用 Bull/Kue 等库 while (true) { const jobJson await redisClient.brPop(clawrelay:message:queue, 0); const job JSON.parse(jobJson.element); try { await processMessageJob(job); // 执行耗时的转换和发送逻辑 } catch (error) { // 记录失败日志可以将其放入另一个重试队列或死信队列 console.error(Process job failed:, error, job); } }使用专业的任务队列库如Bull或Agenda会更强大它们支持延迟任务、重试策略、任务进度监控等功能。将耗时的文件下载、上传操作放在消费者端执行即使耗时较长也不会阻塞飞书的回调。5.2 构建用户与群聊映射关系在转发消息时我们往往希望将消息发送给特定的人或群而不是广播。这就需要建立飞书与微信侧的映射关系。飞书侧标识sender.sender_id.user_id(用户ID)event.message.chat_id(群ID)。微信侧标识企业微信的userid或部门id。我们可以设计一个简单的映射表可以存储在数据库如 SQLite/PostgreSQL或 Redis 中飞书标识类型飞书标识值目标平台目标标识值备注userou_xxxxxxwecomzhangsan张三的个人微信chatoc_xxxxxxwecomall转发到企业微信的“全员”通知chatoc_yyyyyywecom100001转发到企业微信的某个部门在消息处理逻辑中根据飞书事件的chat_id或sender_id去查询这个映射表得到对应的微信接收者信息然后构造企业微信 API 的请求体。这个映射关系可以通过一个管理后台页面来配置和维护。5.3 消息格式的富文本与卡片支持飞书支持丰富的消息格式如文本、图片、文件、语音、视频、富文本post和交互式卡片。clawrelay-feishu-server可以逐步支持这些类型。富文本post飞书的post消息类型结构复杂包含标题、段落、图片、链接等。一种实用的处理方式是将其转换为 Markdown格式然后发送给微信。企业微信的 Markdown 消息支持有限的格式但可读性比纯文本好很多。转换时需要处理图片需要下载并上传到微信将链接替换为微信的图片链接。交互式卡片这是最大的挑战。飞书卡片的按钮、表单等交互元素在微信侧没有直接对应物。一种折中方案是将卡片的标题和描述文本提取出来作为普通消息发送。将卡片的链接如果有附在消息末尾。在消息中注明“这是一张卡片消息请在飞书中查看完整内容和操作”。 虽然损失了交互性但保证了信息的可达性。对于不支持或暂未实现的类型一定要有降级策略。例如收到一个不支持的消息类型如“共享日历”可以转发一条固定文本“[飞书消息] 收到一条暂不支持直接显示的消息类型请在飞书客户端查看。”6. 监控、日志与问题排查实录6.1 关键日志点与监控指标一个健壮的系统离不开完善的日志。在clawrelay-feishu-server中至少应该在以下关键点打日志请求入口记录飞书回调的请求 ID如果有、时间戳、IP、请求路径。验证结果记录签名验证成功或失败。失败时要记录详细的签名信息和计算值便于比对。事件解析记录收到的事件类型 (event.type)、消息类型 (message.message_type)、会话 ID (chat_id)。队列操作记录任务入队、出队、开始处理、处理完成的时间。API 调用记录调用飞书下载 API、微信上传和发送 API 的请求与响应特别是 HTTP 状态码和错误信息。最终状态记录消息是否成功发送到微信以及微信返回的 message_id如果有。监控指标方面可以关注吞吐量每分钟/小时处理的消息数量。延迟从收到飞书事件到成功发送到微信的平均时间、P95、P99 时间。错误率签名验证失败率、消息解析失败率、微信 API 调用失败率。队列深度如果使用了队列监控队列中积压的任务数。可以使用PM2自带的监控、PrometheusGrafana或云服务商的监控服务来实现。6.2 常见问题排查速查表在实际运行中你肯定会遇到各种问题。下面是我踩过的一些坑和解决方法问题现象可能原因排查步骤与解决方案飞书后台“保存”事件订阅URL失败1. URL 不可达或超时2. 服务器未正确响应验证请求3. SSL 证书问题1. 用curl或浏览器直接访问你的https://your-domain.com/feishu/event看是否通。2. 检查服务器日志看是否收到了飞书的 GET 验证请求以及是否正确返回了challenge值。3. 检查 SSL 证书是否有效、是否被信任。收不到飞书消息推送1. 应用权限未开通或版本未发布2. 事件未订阅3. 服务器内部错误导致响应非2001. 去飞书开放平台检查应用权限是否已添加并发布新版本。2. 检查“事件订阅”列表确保所需事件是“已订阅”状态。3. 查看服务器错误日志确保请求处理逻辑没有抛出未捕获的异常。消息能收到但转发失败1. 企业微信access_token失效2. 接收者 ID 不存在或无权限3. 消息内容格式错误或超长4. 媒体文件处理失败1. 检查获取access_token的逻辑确保定时刷新且缓存有效。2. 确认映射表中飞书ID对应的企业微信userid或部门id正确且该用户/部门在应用可见范围内。3. 检查转换后的消息体是否符合企业微信 API 文档要求特别是文本长度限制~2048字符。4. 查看下载/上传文件的日志检查网络、权限和文件大小。图片/文件转发后无法查看1. 微信侧的media_id已过期临时素材3天有效2. 文件类型不被微信支持3. 下载或上传过程中文件损坏1. 临时素材media_id有过期时间转发逻辑中不应缓存过久。对于需要长期访问的文件考虑使用永久素材接口。2. 检查企业微信 API 文档确认支持的文件类型和大小限制。3. 增加文件下载和上传的 MD5 校验。高并发下消息丢失或顺序错乱1. 同步处理导致飞书回调超时飞书停止重试2. 多消费者并发处理同一队列导致乱序1.必须引入异步队列收到事件后快速响应飞书后台异步处理转发。2. 对于需要严格保序的场景如同一个飞书会话的消息可以使用 Redis 的Stream数据结构或者为同一chat_id的消息分配同一个队列消费者。6.3 性能优化与稳定性保障当消息量增大后一些优化措施能显著提升体验连接池与 HTTP 客户端复用无论是请求飞书 API 还是企业微信 API都应该使用一个配置了连接池的 HTTP 客户端如axios、got避免为每个请求都创建新的 TCP 连接减少延迟和系统开销。敏感信息缓存飞书tenant_access_token和企业微信access_token有效期通常为2小时必须缓存并在到期前刷新。使用 Redis 或内存缓存键名包含app_id或agent_id。用户/群聊映射信息如果映射关系不常变化可以缓存起来避免每次转发都查询数据库。媒体文件media_id对于同一飞书file_key其对应的微信media_id在有效期内可以缓存避免重复上传。限流与降级飞书和企业微信的 API 都有调用频率限制。在代码中实现简单的限流如令牌桶算法避免触发限流导致失败。在微信 API 持续不可用时可以考虑降级策略如将消息暂存到数据库待恢复后补发或发送一条降级通知。部署与高可用对于关键业务可以考虑将服务部署在多台服务器上前面用负载均衡如 Nginx 的upstream分发飞书的回调请求。共享的 Redis 队列可以保证任务不被重复执行。确保无状态设计任何一台服务器宕机都不影响整体服务。最后我个人在维护这样一个中继服务时最深的体会是日志和监控是你的眼睛。初期可能觉得麻烦但一旦出现问题详细的日志和清晰的监控图表是快速定位问题的唯一捷径。另一个心得是对第三方 API 的失败要有充分的预期和重试机制。网络抖动、对方服务临时升级、令牌失效都是常态代码不能假设每次调用都成功必须有健壮的错误处理和补偿逻辑。这个项目看似只是简单的消息转发但把它做稳定、做可靠里面涉及的分布式系统、网络编程、API 设计的思想是非常有价值的实战经验。