assist/docs/FEISHU_LONGCONN.md

飞书长连接模式使用指南

已验证可用 - 2026-02-11

本文档介绍如何使用飞书官方 SDK 的长连接模式，无需公网域名即可接入飞书机器人。

🎯 什么是长连接模式？

飞书官方 SDK 提供了事件订阅 2.0（长连接模式），相比传统的 webhook 模式有以下优势：

特性	Webhook 模式（旧）	长连接模式（新）
公网域名	必需	不需要
SSL 证书	必需	不需要
回调配置	需要配置	不需要
内网部署	不支持	支持
实时性	中等（HTTP 轮询）	高（WebSocket）
稳定性	中等	高（自动重连）

---

📦 安装步骤

1. 安装依赖

cd /Users/macos/Desktop/tsp-assist/assist
pip install -r requirements.txt

核心依赖：

• lark-oapi==1.3.5 - 飞书官方 Python SDK

2. 配置环境变量

编辑 .env 文件：

# 飞书配置（必需）
FEISHU_APP_ID=cli_xxxxxxxxxxxxx       # 你的飞书应用 ID
FEISHU_APP_SECRET=xxxxxxxxxxxxx        # 你的飞书应用密钥

# 数据库配置
DATABASE_URL=sqlite:///./data/tsp_assistant.db

# LLM 配置
LLM_PROVIDER=qwen
LLM_API_KEY=sk-xxxxxxxxxxxxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus-latest

3. 初始化数据库

python init_database.py

4. 在飞书开放平台配置应用权限

访问 飞书开放平台，为您的应用添加以下权限：

必需权限：

• im:message - 获取与发送单聊、群组消息
• im:message:send_as_bot - 以应用的身份发消息
• im:chat - 获取群组信息

可选权限（用于工单同步）：

• bitable:app - 查看、评论、编辑和管理多维表格

注意： 添加权限后需要重新发布应用版本。

---

🚀 启动服务

方式 1: 使用启动脚本（推荐）

python start_feishu_bot.py

启动后会看到：

================================================================================
🚀 TSP Assistant - 飞书长连接客户端
================================================================================

📋 配置信息:
   - App ID: cli_xxxxxxxxxxxxx
   - 数据库: sqlite:///./data/tsp_assistant.db
   - LLM: qwen/qwen-plus-latest
   - 日志级别: INFO

🔌 启动模式: 事件订阅 2.0（长连接）
 优势:
   - 无需公网域名
   - 无需配置 webhook
   - 自动重连
   - 实时接收消息

💡 提示: 按 Ctrl+C 停止服务
================================================================================

🚀 启动飞书长连接客户端...
   - App ID: cli_xxxxxxxxxxxxx
   - 模式: 事件订阅 2.0（长连接）
   - 无需公网域名和 webhook 配置
 飞书长连接服务初始化成功

方式 2: 在代码中集成

如果您想将长连接服务集成到现有的 Flask 应用中：

import threading
from src.integrations.feishu_longconn_service import get_feishu_longconn_service

# 在后台线程中启动长连接服务
def start_feishu_in_background():
    service = get_feishu_longconn_service()
    service.start()

# 启动
feishu_thread = threading.Thread(target=start_feishu_in_background, daemon=True)
feishu_thread.start()

# 然后启动 Flask 应用
app.run(...)

---

🧪 测试

1. 在飞书群聊中测试

场景 1：单个用户对话

用户 A: @TSP助手 车辆无法连接网络怎么办？
机器人: [基于工单知识库的智能回复]

用户 A: 还有其他解决方法吗？
机器人: [基于上下文的多轮对话回复]

场景 2：多用户群聊隔离

群聊 1:
  用户 A: @TSP助手 我的车有问题
  机器人: [针对用户 A 的回复]

  用户 B: @TSP助手 我的车有问题
  机器人: [针对用户 B 的独立回复，不受用户 A 影响]

群聊 2:
  用户 A: @TSP助手 我的车有问题
  机器人: [全新对话，不受群聊 1 影响]

2. 查看日志

服务运行时会实时输出日志：

📨 [Feishu LongConn] 收到消息
   - 消息ID: om_xxxxxxxxxxxxx
   - 群聊ID: oc_xxxxxxxxxxxxx
   - 发送者: ou_xxxxxxxxxxxxx
   - 消息类型: text
   - 原始内容: @TSP助手 车辆无法连接网络
   - 清理后内容: 车辆无法连接网络
🔑 会话用户标识: feishu_oc_xxxxxxxxxxxxx_ou_xxxxxxxxxxxxx
 为用户 ou_xxxxxxxxxxxxx 在群聊 oc_xxxxxxxxxxxxx 创建新会话: session_xxxxxxxxxxxxx
🤖 调用 TSP Assistant 处理消息...
📤 准备发送回复 (长度: 156)
 成功回复消息: om_xxxxxxxxxxxxx

---

🔧 与旧模式的对比

旧模式（Webhook）- 已废弃

文件： src/web/blueprints/feishu_bot.py

工作流程：

飞书 → 公网域名 → Webhook → Flask → 处理消息

缺点：

• 需要公网域名
• 需要配置 SSL
• 内网无法部署
• 需要在飞书后台配置回调地址

新模式（长连接）- 推荐

文件： src/integrations/feishu_longconn_service.py

工作流程：

飞书 ← WebSocket 长连接 ← SDK 客户端 ← 处理消息

优点：

• 无需公网域名
• 无需 SSL 证书
• 内网可部署
• 无需配置回调地址
• 自动重连
• 更稳定

---

架构说明

┌─────────────────────────────────────────────────────────────┐
│                      飞书服务器                               │
│                  (open.feishu.cn)                           │
└───────────────────────┬─────────────────────────────────────┘
                        │ WebSocket 长连接
                        │ (事件订阅 2.0)
                        ↓
┌─────────────────────────────────────────────────────────────┐
│          TSP Assistant (内网部署)                             │
│  ┌────────────────────────────────────────────────────┐    │
│  │  feishu_longconn_service.py                        │    │
│  │  - 飞书 SDK 长连接客户端                             │    │
│  │  - 自动接收消息事件                                   │    │
│  │  - 群聊隔离 (feishu_群ID_用户ID)                      │    │
│  └──────────────┬─────────────────────────────────────┘    │
│                 ↓                                           │
│  ┌────────────────────────────────────────────────────┐    │
│  │  RealtimeChatManager                               │    │
│  │  - 会话管理                                          │    │
│  │  - 多轮对话                                          │    │
│  └──────────────┬─────────────────────────────────────┘    │
│                 ↓                                           │
│  ┌────────────────────────────────────────────────────┐    │
│  │  TSP Assistant 智能引擎                             │    │
│  │  - LLM 调用                                         │    │
│  │  - 工单知识库匹配                                    │    │
│  │  - AI 分析和建议                                     │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

---

⚙️ 高级配置

1. 调整日志级别

编辑 .env：

LOG_LEVEL=DEBUG  # 查看详细日志
LOG_LEVEL=INFO   # 默认（推荐）
LOG_LEVEL=WARNING  # 仅警告和错误

2. 同时运行 Web 管理后台和长连接服务

方式 1：使用两个终端

# 终端 1 - Web 管理后台
python start_dashboard.py

# 终端 2 - 飞书长连接服务
python start_feishu_bot.py

方式 2：使用进程管理器（推荐生产环境）

创建 supervisord.conf：

[program:tsp-web]
command=python start_dashboard.py
directory=/Users/macos/Desktop/tsp-assist/assist
autostart=true
autorestart=true

[program:tsp-feishu]
command=python start_feishu_bot.py
directory=/Users/macos/Desktop/tsp-assist/assist
autostart=true
autorestart=true

启动：

supervisord -c supervisord.conf

---

❓ 常见问题

Q1: SSL 证书验证失败怎么办？

错误信息：

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain

解决方案（macOS）：

1. 运行 Python 证书安装脚本（推荐）：

open "/Applications/Python 3.10/Install Certificates.command"

或者手动运行：

/Applications/Python\ 3.10/Install\ Certificates.command

2. 升级 certifi 包：

python3 -m pip install --upgrade certifi

3. 验证修复：

python3 -c "import urllib.request; urllib.request.urlopen('https://open.feishu.cn', timeout=5); print(' SSL 验证成功')"

解决方案（Linux/Windows）：

pip3 install --upgrade certifi

Q2: 启动后没有收到消息？

检查清单：

1. 确认飞书应用权限已配置（im:message）
2. 确认应用已发布最新版本
3. 确认机器人已添加到群聊
4. 查看日志是否有连接成功的提示
5. 确认没有 SSL 证书错误（见 Q1）

Q3: 提示"权限不足"？

解决方案：

1. 登录飞书开放平台
2. 进入应用管理 → 权限管理
3. 添加所需权限
4. 创建新版本并发布
5. 重启长连接服务

Q4: 如何停止服务？

按 Ctrl+C 即可优雅停止。

Q5: 可以在多台服务器上运行吗？

不建议。同一个飞书应用只应运行一个长连接客户端实例，否则会导致消息重复处理。

Q6: 如何迁移旧的 Webhook 模式？

建议：

1. 保留旧代码（feishu_bot.py）作为备份
2. 使用新的长连接模式（start_feishu_bot.py）
3. 测试无误后，可以移除 webhook 端点

---

🎉 总结

现在您的 TSP Assistant 已经支持飞书官方 SDK 的长连接模式！

核心优势：

• 无需公网域名
• 无需 webhook 配置
• 内网可部署
• 自动重连
• 群聊隔离
• 完整的工单管理和 AI 分析功能

使用方式：

python start_feishu_bot.py

就这么简单！🚀