mirror of
https://gitee.com/270580156/weiyu.git
synced 2026-05-13 19:02:51 +00:00
419 lines
10 KiB
Markdown
419 lines
10 KiB
Markdown
<!--
|
||
* @Author: jackning 270580156@qq.com
|
||
* @Date: 2024-09-11 10:22:00
|
||
* @LastEditors: jackning 270580156@qq.com
|
||
* @LastEditTime: 2025-06-07 19:49:53
|
||
* @Description: bytedesk.com https://github.com/Bytedesk/bytedesk
|
||
* Please be aware of the BSL license restrictions before installing Bytedesk IM –
|
||
* selling, reselling, or hosting Bytedesk IM as a service is a breach of the terms and automatically terminates your rights under the license.
|
||
* Business Source License 1.1: https://github.com/Bytedesk/bytedesk/blob/main/LICENSE
|
||
* contact: 270580156@qq.com
|
||
* 联系：270580156@qq.com
|
||
* Copyright (c) 2024 by bytedesk.com, All Rights Reserved.
|
||
-->
|
||
# FreeSwitch Integration Module for Bytedesk
|
||
|
||
基于 Spring Boot 的 FreeSwitch 集成模块，支持语音通话、WebRTC、呼叫中心功能和事件监听。
|
||
|
||
## ⚠️ ESL连接问题修复 (2025-06-08)
|
||
|
||
如果遇到 `text/rude-rejection` 或 `Access Denied` 错误，请查看详细修复指南：
|
||
|
||
📋 **[FreeSwitch ESL 连接问题修复指南](FREESWITCH_ESL_FIX_GUIDE.md)**
|
||
|
||
### 快速修复
|
||
|
||
1. **检查连接状态** - 访问健康检查端点：
|
||
|
||
```bash
|
||
curl http://localhost:9003/actuator/health/freeSwitch
|
||
```
|
||
|
||
2. **测试连接** - 使用管理API：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9003/api/v1/freeswitch/test-connection
|
||
```
|
||
|
||
3. **查看配置** - 获取当前配置：
|
||
|
||
```bash
|
||
curl http://localhost:9003/api/v1/freeswitch/config
|
||
```
|
||
|
||
### 新增功能
|
||
|
||
- ✅ **智能错误诊断**: 自动识别连接问题并提供解决建议
|
||
- ✅ **连接重试机制**: 指数退避重试策略
|
||
- ✅ **健康状态监控**: Spring Boot Actuator集成
|
||
- ✅ **管理REST API**: 连接测试和状态查询接口
|
||
- ✅ **启动时连接测试**: 应用启动时自动检测FreeSwitch连接
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **FreeSwitch ESL 集成**: 通过 Event Socket Library 连接和控制 FreeSwitch
|
||
- ✅ **呼叫控制**: 呼叫发起、挂断、转接、保持等基本功能
|
||
- ✅ **WebRTC 支持**: 基于 Verto 协议的 WebRTC 音视频通话
|
||
- ✅ **实时事件监听**: 监听 FreeSwitch 事件并转发到 Spring Boot 应用
|
||
- ✅ **呼叫中心功能**: 队列管理、坐席管理、通话录音
|
||
- ✅ **REST API**: 完整的 HTTP 接口用于呼叫控制和状态查询
|
||
- ✅ **WebSocket 信令**: 支持 WebRTC 信令交换和实时消息推送
|
||
|
||
## 项目结构
|
||
|
||
```bash
|
||
plugins/freeswitch/
|
||
├── pom.xml # Maven 配置文件
|
||
├── readme.md # 项目文档
|
||
└── src/main/java/com/bytedesk/freeswitch/
|
||
├── freeswitch/
|
||
│ ├── FreeSwitchService.java # FreeSwitch 核心服务
|
||
│ ├── FreeSwitchController.java # REST API 控制器
|
||
│ └── WebSocketConfig.java # WebSocket 配置
|
||
├── webrtc/
|
||
│ └── WebRTCSignalingController.java # WebRTC 信令控制器
|
||
├── callcenter/
|
||
│ └── CallService.java # 呼叫服务
|
||
└── resources/
|
||
└── static/
|
||
└── webrtc-demo.html # WebRTC 测试页面
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Java 17+
|
||
- Spring Boot 3.x
|
||
- FreeSwitch 1.10+
|
||
- Maven 3.6+
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装 FreeSwitch
|
||
|
||
```bash
|
||
# macOS
|
||
brew install freeswitch
|
||
|
||
# Ubuntu/Debian
|
||
apt-get update
|
||
apt-get install freeswitch
|
||
|
||
# CentOS/RHEL
|
||
yum install freeswitch
|
||
```
|
||
|
||
### 2. 配置 FreeSwitch
|
||
|
||
将项目提供的配置文件复制到 FreeSwitch 配置目录：
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
cp deploy/private/freeswitch/conf/vars_bytedesk.xml /usr/local/freeswitch/conf/
|
||
cp deploy/private/freeswitch/conf/directory/bytedesk.xml /usr/local/freeswitch/conf/directory/
|
||
cp deploy/private/freeswitch/conf/autoload_configs/event_socket.conf.xml /usr/local/freeswitch/conf/autoload_configs/
|
||
cp deploy/private/freeswitch/conf/autoload_configs/verto_bytedesk.conf.xml /usr/local/freeswitch/conf/autoload_configs/
|
||
```
|
||
|
||
### 3. 启动 FreeSwitch
|
||
|
||
```bash
|
||
# 启动 FreeSwitch
|
||
freeswitch -nonat
|
||
|
||
# 或者作为后台服务启动
|
||
freeswitch -nc -nonat
|
||
```
|
||
|
||
### 4. 配置 Spring Boot
|
||
|
||
在 `application-local.properties` 中配置 FreeSwitch 连接参数：
|
||
|
||
```properties
|
||
# FreeSwitch ESL 配置
|
||
freeswitch.esl.host=127.0.0.1
|
||
freeswitch.esl.port=8021
|
||
freeswitch.esl.password=bytedesk123
|
||
freeswitch.esl.timeout=10000
|
||
|
||
# WebRTC 配置
|
||
freeswitch.webrtc.ws.url=ws://127.0.0.1:15066
|
||
freeswitch.webrtc.wss.url=wss://127.0.0.1:17443
|
||
|
||
# 呼叫中心配置
|
||
freeswitch.callcenter.queue.default=bytedesk_queue
|
||
freeswitch.callcenter.recording.enabled=true
|
||
```
|
||
|
||
### 5. 启动应用
|
||
|
||
```bash
|
||
cd plugins/freeswitch
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
## API 使用示例
|
||
|
||
### 呼叫控制 API
|
||
|
||
#### 发起呼叫
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9003/api/freeswitch/originate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"from": "1000",
|
||
"to": "1001",
|
||
"timeout": 60
|
||
}'
|
||
```
|
||
|
||
#### 挂断呼叫
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9003/api/freeswitch/hangup \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"uuid": "call-uuid-here"
|
||
}'
|
||
```
|
||
|
||
#### 转接呼叫
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9003/api/freeswitch/transfer \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"uuid": "call-uuid-here",
|
||
"destination": "1002"
|
||
}'
|
||
```
|
||
|
||
#### 播放文件
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9003/api/freeswitch/playback \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"uuid": "call-uuid-here",
|
||
"file": "/usr/local/freeswitch/sounds/en/us/callie/ivr/8000/ivr-welcome.wav"
|
||
}'
|
||
```
|
||
|
||
### 呼叫状态查询
|
||
|
||
#### 获取活跃通话
|
||
|
||
```bash
|
||
curl http://localhost:9003/api/freeswitch/calls/active
|
||
```
|
||
|
||
#### 获取通道状态
|
||
|
||
```bash
|
||
curl http://localhost:9003/api/freeswitch/channels/status
|
||
```
|
||
|
||
## WebRTC 集成
|
||
|
||
### 1. 访问测试页面
|
||
|
||
启动应用后，访问：<http://localhost:9003/webrtc-demo.html>
|
||
|
||
### 2. WebSocket 连接
|
||
|
||
```javascript
|
||
// 连接到 WebSocket
|
||
const socket = new SockJS('/ws');
|
||
const stompClient = Stomp.over(socket);
|
||
|
||
stompClient.connect({}, function (frame) {
|
||
console.log('Connected: ' + frame);
|
||
|
||
// 订阅信令消息
|
||
stompClient.subscribe('/topic/webrtc/signaling', function (message) {
|
||
const data = JSON.parse(message.body);
|
||
handleSignalingMessage(data);
|
||
});
|
||
});
|
||
|
||
// 发送 WebRTC Offer
|
||
function sendOffer(offer) {
|
||
stompClient.send("/app/webrtc/offer", {}, JSON.stringify({
|
||
type: 'offer',
|
||
sdp: offer.sdp,
|
||
from: 'user1',
|
||
to: 'user2'
|
||
}));
|
||
}
|
||
```
|
||
|
||
### 3. 呼叫流程
|
||
|
||
1. **发起呼叫**: 通过 WebSocket 发送 offer
|
||
2. **应答呼叫**: 接收方发送 answer
|
||
3. **ICE 候选交换**: 交换网络连接信息
|
||
4. **建立连接**: WebRTC 点对点连接建立
|
||
5. **通话控制**: 静音、挂断等操作
|
||
|
||
## 事件监听
|
||
|
||
应用会自动监听 FreeSwitch 事件并通过 WebSocket 推送：
|
||
|
||
```javascript
|
||
// 订阅呼叫事件
|
||
stompClient.subscribe('/topic/call/events', function (message) {
|
||
const event = JSON.parse(message.body);
|
||
console.log('Call event:', event);
|
||
|
||
switch(event.type) {
|
||
case 'CHANNEL_CREATE':
|
||
console.log('New call created:', event.uuid);
|
||
break;
|
||
case 'CHANNEL_ANSWER':
|
||
console.log('Call answered:', event.uuid);
|
||
break;
|
||
case 'CHANNEL_HANGUP':
|
||
console.log('Call ended:', event.uuid);
|
||
break;
|
||
}
|
||
});
|
||
```
|
||
|
||
## 呼叫中心功能
|
||
|
||
### 队列管理
|
||
|
||
```bash
|
||
# 创建队列
|
||
curl -X POST http://localhost:9003/api/callcenter/queue \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "support_queue",
|
||
"strategy": "longest-idle-agent",
|
||
"timeout": 300
|
||
}'
|
||
|
||
# 加入队列
|
||
curl -X POST http://localhost:9003/api/callcenter/queue/support_queue/join \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"caller": "1000"
|
||
}'
|
||
```
|
||
|
||
### 坐席管理
|
||
|
||
```bash
|
||
# 坐席登录
|
||
curl -X POST http://localhost:9003/api/callcenter/agent/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"agentId": "agent001",
|
||
"queue": "support_queue",
|
||
"extension": "1001"
|
||
}'
|
||
|
||
# 坐席状态设置
|
||
curl -X POST http://localhost:9003/api/callcenter/agent/agent001/status \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"status": "Available"
|
||
}'
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### FreeSwitch 配置文件
|
||
|
||
- **vars_bytedesk.xml**: 全局变量配置
|
||
- **bytedesk.xml**: 用户目录配置
|
||
- **event_socket.conf.xml**: ESL 服务配置
|
||
- **verto_bytedesk.conf.xml**: WebRTC Verto 配置
|
||
|
||
### 关键配置参数
|
||
|
||
```xml
|
||
<!-- ESL 密码 -->
|
||
<param name="password" value="bytedesk123"/>
|
||
|
||
<!-- WebRTC 端口 -->
|
||
<param name="ws-binding" value=":15066"/>
|
||
<param name="wss-binding" value=":17443"/>
|
||
|
||
<!-- SIP 端口 -->
|
||
<param name="sip-port" value="15060"/>
|
||
<param name="rtp-port" value="16000-16129"/>
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **无法连接 FreeSwitch ESL**
|
||
- 检查 FreeSwitch 是否启动
|
||
- 验证 ESL 密码和端口配置
|
||
- 确认防火墙设置
|
||
|
||
2. **WebRTC 连接失败**
|
||
- 检查 Verto 配置是否正确
|
||
- 验证 WebSocket 端口是否开放
|
||
- 确认 STUN/TURN 服务器配置
|
||
|
||
3. **音频质量问题**
|
||
- 检查编解码器配置
|
||
- 验证网络带宽和延迟
|
||
- 调整 RTP 端口范围
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# FreeSwitch 日志
|
||
tail -f /usr/local/freeswitch/log/freeswitch.log
|
||
|
||
# Spring Boot 日志
|
||
tail -f logs/bytedeskim.log
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 添加新的呼叫功能
|
||
|
||
1. 在 `FreeSwitchService` 中添加新方法
|
||
2. 在 `FreeSwitchController` 中暴露 REST API
|
||
3. 更新事件监听逻辑（如需要）
|
||
4. 添加相应的测试用例
|
||
|
||
### 自定义事件处理
|
||
|
||
```java
|
||
@Component
|
||
public class CustomEventHandler {
|
||
|
||
@EventListener
|
||
public void handleChannelCreate(ChannelCreateEvent event) {
|
||
// 处理通道创建事件
|
||
log.info("Channel created: {}", event.getUuid());
|
||
}
|
||
|
||
@EventListener
|
||
public void handleChannelAnswer(ChannelAnswerEvent event) {
|
||
// 处理通话接听事件
|
||
log.info("Channel answered: {}", event.getUuid());
|
||
}
|
||
}
|
||
```
|
||
|
||
## 许可证
|
||
|
||
本项目采用 Business Source License 1.1 许可证。详情请参阅 [LICENSE](../../LICENSE) 文件。
|
||
|
||
## 支持
|
||
|
||
- 邮箱: <270580156@qq.com>
|
||
- 官网: <https://bytedesk.com>
|
||
- GitHub: <https://github.com/Bytedesk/bytedesk>
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request。详情请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
|