3769d164b1
新增功能: - 通过 FEISHU_MODE 配置切换模式 (http/websocket) - 安装飞书 SDK (@larksuiteoapi/node-sdk) - WebSocket 模式支持内网部署（无需公网 IP） - 新增 WEBSOCKET.md 配置指南 更新: - README.md 添加两种模式说明 - .env.example 添加 FEISHU_MODE 配置 - 健康检查返回当前模式信息
214 lines
3.6 KiB
Markdown
214 lines
3.6 KiB
Markdown
# 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` 文件：
|
||
|
||
```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️⃣ 安装依赖
|
||
|
||
```bash
|
||
cd /path/to/qiniu-feishu-bot
|
||
npm install
|
||
```
|
||
|
||
### 4️⃣ 启动服务
|
||
|
||
```bash
|
||
# 使用 PM2
|
||
pm2 restart qiniu-bot
|
||
|
||
# 或直接启动
|
||
npm start
|
||
```
|
||
|
||
### 5️⃣ 查看日志
|
||
|
||
```bash
|
||
# PM2 日志
|
||
pm2 logs qiniu-bot
|
||
|
||
# 应该看到：
|
||
# 🚀 七牛云上传机器人启动 (WebSocket 长连接模式)
|
||
# 📡 WebSocket 已启动
|
||
# ✅ WebSocket 连接成功
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 故障排查
|
||
|
||
### WebSocket 连接失败
|
||
|
||
**检查配置：**
|
||
```bash
|
||
# 验证 .env 配置
|
||
cat .env | grep FEISHU
|
||
|
||
# 确认 FEISHU_MODE=websocket
|
||
```
|
||
|
||
**查看日志：**
|
||
```bash
|
||
pm2 logs qiniu-bot --lines 100
|
||
```
|
||
|
||
**常见错误：**
|
||
|
||
1. **验证失败**
|
||
- 检查 Verification Token 是否正确
|
||
- 检查 Encrypt Key 是否正确
|
||
|
||
2. **连接被拒绝**
|
||
- 检查防火墙是否允许出站连接
|
||
- 确认服务器能访问外网
|
||
|
||
3. **认证失败**
|
||
- 检查 App ID 和 App Secret
|
||
|
||
---
|
||
|
||
## 📊 监控 WebSocket 状态
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:3030/health
|
||
```
|
||
|
||
返回：
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": "2026-03-05T08:00:00.000Z",
|
||
"mode": "websocket",
|
||
"port": 3030
|
||
}
|
||
```
|
||
|
||
### 连接状态
|
||
|
||
查看 PM2 日志中的连接状态：
|
||
|
||
```bash
|
||
pm2 logs qiniu-bot | grep -E "(WebSocket|连接|open|close)"
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 切换模式
|
||
|
||
### 从 HTTP 切换到 WebSocket
|
||
|
||
```bash
|
||
# 1. 修改 .env
|
||
nano .env
|
||
# 设置 FEISHU_MODE=websocket
|
||
|
||
# 2. 重启服务
|
||
pm2 restart qiniu-bot
|
||
|
||
# 3. 验证
|
||
pm2 logs qiniu-bot
|
||
```
|
||
|
||
### 从 WebSocket 切换到 HTTP
|
||
|
||
```bash
|
||
# 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` 端点都工作
|
||
- 可用于监控服务状态
|
||
|
||
---
|
||
|
||
**🍙 祝你使用愉快！**
|