qiniu-feishu-bot/WEBSOCKET.md

WebSocket 长连接模式配置指南

📡 两种模式对比

特性	HTTP 回调	WebSocket 长连接
公网 IP	✅ 需要	❌ 不需要
域名	✅ 需要	❌ 不需要
HTTPS	✅ 推荐	❌ 不需要
内网部署	❌ 困难	✅ 简单
实时性	好	更好
配置复杂度	简单	中等

---

🚀 配置 WebSocket 模式

1️⃣ 飞书开放平台配置

1. 访问 https://open.feishu.cn/
2. 进入你的应用管理页面
3. 点击"事件订阅"
4. 选择"WebSocket 长连接"方式
5. 开启"启用事件订阅"
6. 添加订阅事件：
   • im.message.receive_v1 - 接收消息
7. 保存并复制：
   • Verification Token
   • Encrypt Key

2️⃣ 修改配置文件

编辑 .env 文件：

# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx

# 设置为 WebSocket 模式
FEISHU_MODE=websocket

# 七牛云配置
QINIU_ACCESS_KEY=xxxxxxxxxxxxxx
QINIU_SECRET_KEY=xxxxxxxxxxxxxx
QINIU_BUCKET=your-bucket-name
QINIU_REGION=z0
QINIU_DOMAIN=https://your-cdn.com

# 服务配置
PORT=3030
NODE_ENV=production

3️⃣ 安装依赖

cd /path/to/qiniu-feishu-bot
npm install

4️⃣ 启动服务

# 使用 PM2
pm2 restart qiniu-bot

# 或直接启动
npm start

5️⃣ 查看日志

# PM2 日志
pm2 logs qiniu-bot

# 应该看到：
# 🚀 七牛云上传机器人启动 (WebSocket 长连接模式)
# 📡 WebSocket 已启动
# ✅ WebSocket 连接成功

---

🔧 故障排查

WebSocket 连接失败

检查配置：

# 验证 .env 配置
cat .env | grep FEISHU

# 确认 FEISHU_MODE=websocket

查看日志：

pm2 logs qiniu-bot --lines 100

常见错误：

1. 验证失败

   • 检查 Verification Token 是否正确
   • 检查 Encrypt Key 是否正确

2. 连接被拒绝

   • 检查防火墙是否允许出站连接
   • 确认服务器能访问外网

3. 认证失败

   • 检查 App ID 和 App Secret

---

📊 监控 WebSocket 状态

健康检查

curl http://localhost:3030/health

返回：

{
  "status": "ok",
  "timestamp": "2026-03-05T08:00:00.000Z",
  "mode": "websocket",
  "port": 3030
}

连接状态

查看 PM2 日志中的连接状态：

pm2 logs qiniu-bot | grep -E "(WebSocket|连接|open|close)"

---

🔄 切换模式

从 HTTP 切换到 WebSocket

# 1. 修改 .env
nano .env
# 设置 FEISHU_MODE=websocket

# 2. 重启服务
pm2 restart qiniu-bot

# 3. 验证
pm2 logs qiniu-bot

从 WebSocket 切换到 HTTP

# 1. 修改 .env
nano .env
# 设置 FEISHU_MODE=http

# 2. 重启服务
pm2 restart qiniu-bot

# 3. 在飞书开放平台改回 HTTP 回调方式

---

💡 最佳实践

WebSocket 模式适用场景

• ✅ 内网服务器（无公网 IP）
• ✅ 开发测试环境
• ✅ 不想配置域名和 HTTPS
• ✅ 需要更好的实时性

HTTP 回调模式适用场景

• ✅ 云服务器（有公网 IP）
• ✅ 生产环境
• ✅ 已有域名和 HTTPS
• ✅ 需要更可控的连接管理

---

📝 注意事项

1. WebSocket 长连接会保持在线状态

   • 确保服务器网络稳定
   • 断线会自动重连（5 秒间隔）

2. 两种方式不能同时使用

   • 通过 FEISHU_MODE 配置选择
   • 飞书开放平台也要对应配置

3. 健康检查始终可用

   • 无论哪种模式，/health 端点都工作
   • 可用于监控服务状态

---

🍙 祝你使用愉快！