# 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` 端点都工作
   - 可用于监控服务状态

---

**🍙 祝你使用愉快！**