1. FreeSWITCH运行环境准备
FreeSWITCH作为一款开源的软交换平台,其运行环境的搭建是使用过程中的首要步骤。在开始运行FreeSWITCH之前,我们需要确保系统环境满足基本要求并完成必要的准备工作。
1.1 系统要求与依赖安装
FreeSWITCH支持在多种操作系统上运行,包括Linux、Windows和macOS等。对于生产环境,推荐使用Linux系统(如Ubuntu、CentOS等),因为它们通常能提供更好的性能和稳定性。在安装FreeSWITCH之前,需要确保系统已安装以下基本依赖:
- GCC/G++编译器(版本4.8或更高)
- GNU make工具
- libtool
- autoconf/automake
- pkg-config
- openssl开发库
- SQLite3开发库
- libcurl开发库
在Ubuntu/Debian系统上,可以通过以下命令安装这些依赖:
bash复制sudo apt-get update
sudo apt-get install -y build-essential automake autoconf libtool pkg-config \
libssl-dev libsqlite3-dev libcurl4-openssl-dev libpcre3-dev libspeex-dev \
libspeexdsp-dev libedit-dev libldns-dev libpq-dev
1.2 FreeSWITCH源码获取与编译
FreeSWITCH提供了多种安装方式,包括源码编译安装和预编译包安装。对于需要深度定制或希望了解内部工作原理的用户,推荐从源码编译安装:
bash复制git clone https://github.com/signalwire/freeswitch.git
cd freeswitch
./bootstrap.sh
./configure
make
sudo make install
注意:编译过程可能需要较长时间(取决于硬件配置),建议在性能较好的机器上执行。如果遇到依赖缺失问题,configure脚本会给出明确提示,需要根据提示安装相应开发包。
1.3 配置文件准备
FreeSWITCH安装完成后,默认配置文件位于/usr/local/freeswitch/conf目录下。这些配置文件定义了FreeSWITCH的基本行为,包括:
- vars.xml:系统变量定义
- sip_profiles/*.xml:SIP协议配置
- dialplan/default/*.xml:拨号计划配置
- directory/default/*.xml:用户目录配置
首次运行前,建议先检查这些配置文件,特别是vars.xml中的以下关键参数:
xml复制<X-PRE-PROCESS cmd="set" data="domain=$${local_ip_v4}"/>
<X-PRE-PROCESS cmd="set" data="local_ip_v4=你的服务器IP"/>
<X-PRE-PROCESS cmd="set" data="external_rtp_ip=stun:stun.freeswitch.org"/>
<X-PRE-PROCESS cmd="set" data="external_sip_ip=stun:stun.freeswitch.org"/>
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. FreeSWITCH启动方式详解
FreeSWITCH提供了多种启动方式,适用于不同的使用场景。了解这些启动方式及其区别,对于日常运维和问题排查都非常重要。
2.1 前台运行模式
最简单的启动方式是在前台运行FreeSWITCH,这种方式适合调试和开发环境:
bash复制/usr/local/freeswitch/bin/freeswitch
前台运行模式下,所有日志信息都会直接输出到控制台,方便实时查看系统状态。按Ctrl+C可以停止服务。这种模式下,FreeSWITCH不会作为守护进程运行,终端关闭后服务也会停止。
2.2 后台守护进程模式
生产环境通常需要FreeSWITCH以守护进程方式运行:
bash复制/usr/local/freeswitch/bin/freeswitch -nc
-nc参数表示"no console",即不启动控制台界面,让FreeSWITCH在后台运行。此时可以使用以下命令查看运行状态:
bash复制ps aux | grep freeswitch
2.3 系统服务管理
为了方便管理,可以将FreeSWITCH配置为系统服务。在Linux系统上,可以创建/etc/init.d/freeswitch或使用systemd服务文件。以下是systemd服务文件的示例:
ini复制[Unit]
Description=FreeSWITCH
After=syslog.target network.target
[Service]
Type=forking
PIDFile=/usr/local/freeswitch/run/freeswitch.pid
ExecStart=/usr/local/freeswitch/bin/freeswitch -nc -nonat -nf
ExecStop=/usr/local/freeswitch/bin/freeswitch -stop
TimeoutSec=45s
Restart=always
[Install]
WantedBy=multi-user.target
保存为/etc/systemd/system/freeswitch.service后,执行以下命令启用服务:
bash复制sudo systemctl daemon-reload
sudo systemctl enable freeswitch
sudo systemctl start freeswitch
2.4 关键启动参数解析
FreeSWITCH提供了丰富的命令行参数,用于控制启动行为。以下是一些常用参数:
| 参数 | 说明 | 适用场景 |
|---|---|---|
| -nc | 无控制台模式 | 生产环境后台运行 |
| -nonat | 禁用NAT检测 | 已知网络环境无需NAT穿透时 |
| -nf | 不自动fork | 调试时使用 |
| -c | 检查配置文件 | 验证配置文件语法 |
| -help | 显示帮助信息 | 查询参数用法 |
| -version | 显示版本信息 | 确认版本号 |
| -stop | 停止运行中的实例 | 服务管理 |
| -reload | 重新加载配置 | 配置更新后 |
例如,要在前台运行并显示详细日志,可以使用:
bash复制/usr/local/freeswitch/bin/freeswitch -nf -dbg
3. FreeSWITCH控制台操作
FreeSWITCH控制台是与运行中实例交互的主要界面,掌握控制台操作是管理FreeSWITCH的基础技能。
3.1 控制台基本操作
当FreeSWITCH在前台运行时,可以直接在启动终端中输入命令。如果FreeSWITCH在后台运行,可以通过以下方式连接控制台:
bash复制/usr/local/freeswitch/bin/fs_cli
控制台支持以下基本操作:
- 输入命令后按回车执行
- 按Tab键可以自动补全命令
- 按上/下箭头可以浏览历史命令
- 输入/help可以查看帮助信息
- 输入/exit或按Ctrl+D退出控制台
3.2 常用控制台命令
FreeSWITCH控制台提供了大量命令用于系统管理和监控。以下是一些最常用的命令:
系统信息类:
- version:显示FreeSWITCH版本
- status:显示系统状态
- reloadxml:重新加载XML配置
- sofia status:显示SIP状态
- show channels:显示当前通话
日志管理类:
- loglevel
:设置日志级别(0-7) - /log info:查看info级别日志
- /log debug:查看debug级别日志
通话控制类:
- originate:发起呼叫
- uuid_kill
:终止指定通话 - uuid_transfer
:转移通话
模块管理类:
- module list:列出已加载模块
- module load <mod_name>:加载模块
- module unload <mod_name>:卸载模块
3.3 高级控制台技巧
命令别名设置:
可以通过以下方式创建命令别名,简化常用操作:
bash复制alias add reload_all reloadxml; reload mod_sofia; reload mod_dialplan
之后只需输入reload_all即可执行这三个重新加载命令。
日志过滤:
使用/event命令可以订阅特定事件,例如只查看与特定呼叫相关的日志:
bash复制/event plain CHANNEL_CREATE CHANNEL_ANSWER CHANNEL_HANGUP
批量执行命令:
可以通过管道或-f参数批量执行命令:
bash复制echo "version\nstatus" | fs_cli
或
bash复制fs_cli -x "version; status"
4. FreeSWITCH高级运行管理
4.1 多实例运行
在某些场景下,可能需要在一台服务器上运行多个FreeSWITCH实例。这可以通过指定不同的配置目录实现:
bash复制/usr/local/freeswitch/bin/freeswitch -conf /path/to/conf1 -log /path/to/log1 -db /path/to/db1
/usr/local/freeswitch/bin/freeswitch -conf /path/to/conf2 -log /path/to/log2 -db /path/to/db2
每个实例需要:
- 独立的配置文件目录
- 独立的日志目录
- 独立的数据库目录
- 不同的SIP端口设置
4.2 性能调优
对于高负载环境,需要进行适当的性能调优:
系统参数调优:
bash复制# 增加文件描述符限制
ulimit -n 65536
# 调整内核网络参数
sysctl -w net.core.somaxconn=4096
sysctl -w net.ipv4.tcp_max_syn_backlog=8192
FreeSWITCH参数调优:
在vars.xml中调整以下参数:
xml复制<X-PRE-PROCESS cmd="set" data="max_sessions=1000"/>
<X-PRE-PROCESS cmd="set" data="sessions-per-second=30"/>
<X-PRE-PROCESS cmd="set" data="rtp-timer-name=soft"/>
4.3 端口配置修改
默认情况下,FreeSWITCH使用5060端口作为SIP端口。要修改默认端口,需要编辑以下文件:
- 修改vars.xml中的sip端口变量:
xml复制<X-PRE-PROCESS cmd="set" data="internal_sip_port=5080"/>
<X-PRE-PROCESS cmd="set" data="external_sip_port=5080"/>
- 修改sip_profiles/internal.xml和external.xml中的端口设置:
xml复制<param name="sip-port" value="$${internal_sip_port}"/>
- 重新加载SIP配置:
bash复制reload mod_sofia
4.4 自动化控制
通过Event Socket接口(ESL)可以实现对FreeSWITCH的自动化控制。以下是使用Python通过ESL连接FreeSWITCH的示例代码:
python复制import ESL
conn = ESL.ESLconnection("localhost", "8021", "ClueCon")
if conn.connected():
response = conn.api("status")
print(response.getBody())
else:
print("Connection failed")
ESL提供了完整的编程接口,可以实现:
- 发起/控制通话
- 监控系统状态
- 处理事件通知
- 动态修改配置
5. 常见问题与解决方案
5.1 启动失败排查
问题现象: FreeSWITCH启动失败,无日志输出或立即退出。
排查步骤:
- 检查依赖是否完整:
ldd /usr/local/freeswitch/bin/freeswitch - 检查配置文件语法:
/usr/local/freeswitch/bin/freeswitch -c - 以调试模式启动:
/usr/local/freeswitch/bin/freeswitch -nf -dbg - 检查端口冲突:
netstat -tulnp | grep 5060
常见原因:
- 缺少依赖库
- 配置文件语法错误
- 端口被占用
- 权限问题
5.2 控制台连接问题
问题现象: fs_cli无法连接FreeSWITCH实例。
解决方案:
- 确认FreeSWITCH是否运行:
ps aux | grep freeswitch - 检查IPC套接字权限:
ls -l /usr/local/freeswitch/run/freeswitch.sock - 尝试指定密码连接:
fs_cli -p mypassword - 检查event_socket.conf.xml配置:
xml复制<param name="listen-ip" value="127.0.0.1"/>
<param name="listen-port" value="8021"/>
<param name="password" value="ClueCon"/>
5.3 性能问题优化
问题现象: 高负载下系统响应慢或崩溃。
优化建议:
- 调整会话限制:
xml复制<X-PRE-PROCESS cmd="set" data="max_sessions=500"/>
- 启用会话缓存:
xml复制<param name="enable-session-cache" value="true"/>
- 优化编解码设置:
xml复制<param name="global-codec-prefs" value="PCMU,PCMA,G729"/>
<param name="outbound-codec-prefs" value="PCMU,PCMA"/>
- 考虑启用会话代理:
bash复制load mod_session_proxy
5.4 日志管理技巧
日志轮转配置:
在logrotate.d中添加FreeSWITCH日志轮转配置:
code复制/usr/local/freeswitch/log/freeswitch.log {
daily
rotate 7
missingok
notifempty
compress
delaycompress
sharedscripts
postrotate
/usr/bin/killall -HUP freeswitch
endscript
}
关键日志位置:
- 主日志:/usr/local/freeswitch/log/freeswitch.log
- SIP消息:/usr/local/freeswitch/log/sip.log
- 媒体日志:/usr/local/freeswitch/log/rtp.log
- 通话记录:/usr/local/freeswitch/log/cdr-csv/
6. 实际应用案例
6.1 构建基础PBX系统
通过FreeSWITCH可以快速搭建企业PBX系统,主要配置步骤包括:
- 配置SIP分机:
xml复制<!-- directory/default/1000.xml -->
<user id="1000">
<params>
<param name="password" value="1234"/>
</params>
<variables>
<variable name="user_context" value="default"/>
</variables>
</user>
- 设置拨号规则:
xml复制<!-- dialplan/default.xml -->
<extension name="internal_extensions">
<condition field="destination_number" expression="^(10[0-9]{2})$">
<action application="bridge" data="user/$1"/>
</condition>
</extension>
- 配置外线网关:
xml复制<!-- sip_profiles/external/gw1.xml -->
<gateway name="gw1">
<param name="username" value="myaccount"/>
<param name="password" value="mypassword"/>
<param name="proxy" value="sip.provider.com"/>
<param name="register" value="true"/>
</gateway>
6.2 实现IVR语音菜单
创建交互式语音应答(IVR)系统:
- 定义IVR菜单:
xml复制<!-- dialplan/public/ivr_demo.xml -->
<extension name="ivr_demo">
<condition field="destination_number" expression="^5000$">
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="ivr" data="demo_ivr"/>
</condition>
</extension>
- 配置IVR流程:
xml复制<!-- ivr_menus/demo_ivr.xml -->
<menu name="demo_ivr" greet-long="phrase:demo_ivr_greet" greet-short="phrase:demo_ivr_short">
<entry action="menu-exec-app" digits="1" param="playback phrase:demo_ivr_option1"/>
<entry action="menu-exec-app" digits="2" param="playback phrase:demo_ivr_option2"/>
<entry action="menu-exec-app" digits="3" param="transfer 1000 XML default"/>
</menu>
- 录制语音提示:
bash复制uuid_record <uuid> start /usr/local/freeswitch/sounds/en/us/callie/ivr/8000/demo_ivr_greet.wav
6.3 集成数据库存储
FreeSWITCH可以集成多种数据库系统,以SQLite为例:
- 启用SQLite模块:
bash复制load mod_db
load mod_db_sqlite
- 配置数据库连接:
xml复制<!-- autoload_configs/db.conf.xml -->
<settings>
<param name="core-db-type" value="sqlite"/>
<param name="core-db-path" value="/usr/local/freeswitch/db/core.db"/>
</settings>
- 使用API操作数据库:
bash复制db insert/select/delete/update
- 通过拨号计划访问数据库:
xml复制<action application="set" data="result=${db(select/domain/users/where/username=${destination_number})}"/>
6.4 实现通话录音
配置通话录音功能:
- 全局录音设置:
xml复制<!-- vars.xml -->
<X-PRE-PROCESS cmd="set" data="record_path=/usr/local/freeswitch/recordings"/>
<X-PRE-PROCESS cmd="set" data="record_template=${caller_id_number}_${destination_number}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>
- 按需录音:
xml复制<action application="record_session" data="${record_path}/${record_template}"/>
- 立体声录音:
xml复制<action application="set" data="record_stereo=true"/>
- 录音文件管理:
bash复制# 列出录音文件
ls /usr/local/freeswitch/recordings
# 播放录音文件
playback /usr/local/freeswitch/recordings/1000_1001_2023-01-01-12-00-00.wav
7. 监控与维护
7.1 系统状态监控
FreeSWITCH提供了多种监控方式:
实时监控命令:
- show status:显示系统状态
- show calls count:显示通话计数
- show channels count:显示通道计数
- show registrations:显示注册用户
SNMP监控:
- 加载SNMP模块:
bash复制load mod_snmp
- 配置SNMP:
xml复制<!-- snmp.conf.xml -->
<configuration name="snmp.conf" description="SNMP Configuration">
<settings>
<param name="enabled" value="true"/>
<param name="community" value="public"/>
<param name="syslocation" value="Office"/>
</settings>
</configuration>
7.2 性能指标收集
收集关键性能指标:
通过API获取指标:
bash复制# 获取CPU使用率
status | grep "CPU"
# 获取内存使用
status | grep "Mem"
# 获取会话统计
show calls count
日志分析:
bash复制# 统计每小时通话量
grep "NEW CHANNEL" /usr/local/freeswitch/log/freeswitch.log | \
awk '{print $1,$2}' | cut -d: -f1,2 | uniq -c
7.3 定期维护任务
数据库维护:
bash复制# SQLite数据库优化
sqlite3 /usr/local/freeswitch/db/core.db "VACUUM; ANALYZE;"
日志清理:
bash复制# 清理30天前的日志
find /usr/local/freeswitch/log -type f -name "*.log*" -mtime +30 -delete
配置文件备份:
bash复制# 备份配置
tar czvf freeswitch_conf_$(date +%Y%m%d).tar.gz /usr/local/freeswitch/conf
7.4 安全加固建议
- 修改默认密码:
xml复制<!-- event_socket.conf.xml -->
<param name="password" value="StrongPassword123!"/>
- 限制访问IP:
xml复制<!-- acl.conf.xml -->
<list name="trusted" default="deny">
<node type="allow" cidr="192.168.1.0/24"/>
</list>
- 启用TLS加密:
xml复制<!-- sip_profiles/internal.xml -->
<param name="tls" value="true"/>
<param name="tls-bind-params" value="transport=tls"/>
<param name="tls-cert-dir" value="/usr/local/freeswitch/certs"/>
- 定期更新:
bash复制git pull
./bootstrap.sh
./configure
make
make install
