团队要做一个内部通信调度平台，需要支持 SIP 分机注册、组呼、分区广播和通话录音。选型上排除了商业软交换平台（二次开发接口受限），最终选了 FreeSWITCH 作为软交换核心，用 Python 通过 ESL 做调度业务控制。

环境：CentOS 7，FreeSWITCH 1.10.12 源码编译安装，Python 3.10，pyst2。

下面把从环境搭建到功能跑通的完整过程中遇到的 5 个问题和排查过程记录下来。

问题一：源码编译卡在 apr 依赖上

按官方文档执行 configure 后，报错提示 APR not found。直觉上以为装了 apr-devel 就行了，但执行 yum install apr-devel 后重新 configure，报错依旧。

翻看 config.log 才发现，FreeSWITCH 1.10.x 需要的是 apr 和 apr-util 的源码版本，不是通过 yum 安装的二进制包。而且它对目录结构有要求，必须在同一个父目录下，目录名固定为 apr 和 apr-util。

cd /usr/local/src

wget https://archive.apache.org/dist/apr/apr-1.7.0.tar.gz
wget https://archive.apache.org/dist/apr/apr-util-1.6.1.tar.gz

tar -zxvf apr-1.7.0.tar.gz && mv apr-1.7.0 apr
tar -zxvf apr-util-1.6.1.tar.gz && mv apr-util-1.6.1 apr-util

cd apr && ./configure --prefix=/usr/local/apr && make && make install
cd ../apr-util && ./configure --prefix=/usr/local/apr --with-apr=/usr/local/apr && make && make install

回到 FreeSWITCH 源码目录重新 configure：

./configure --with-apr=/usr/local/apr --with-apr-util=/usr/local/apr

踩坑总结：FreeSWITCH 的 apr 依赖必须用源码编译，目录名固定不能带版本号。yum 装的 apr-devel 只提供库文件和头文件，但没有 FreeSWITCH 需要的构建目录结构。

问题二：配置文件目录缺失导致 Sofia profile 起不来

编译安装完成后启动 FreeSWITCH，控制台看到 Sofia 模块加载了，但执行 sofia status 显示 0 profiles defined，所有 SIP 分机注册都超时。

tail -100 /usr/local/freeswitch/log/freeswitch.log | grep -i error

看到关键报错：Could not open /usr/local/freeswitch/conf/freeswitch.xml。原因是编译安装时不会自动复制配置文件，需要从源码目录手动复制：

cp -r /usr/local/src/freeswitch/conf /usr/local/freeswitch/

ls /usr/local/freeswitch/conf/freeswitch.xml

重启后 sofia status 正常显示 internal 和 external 两个 profile。

踩坑总结：FreeSWITCH 源码编译安装不会自动复制配置文件，必须手动从源码目录的 conf 文件夹复制到安装目录。

问题三：SIP 分机能注册但打不通

分机 8001 和 8002 都注册成功了，但 8001 拨打 8002 听到的是“您拨打的号码是空号”。检查拨号计划目录发现只有默认文件，没有自定义分机路由规则。

<include>
  <extension name="local_extensions">
    <condition field="destination_number" expression="^(8\d{3})$">
      <action application="bridge" data="user/$1"/>
    </condition>
  </extension>
</include>

踩坑总结：FreeSWITCH 的拨号计划是完全数据驱动的，没有匹配规则就不会路由。编译安装后默认的拨号计划覆盖范围很有限，自定义分机号段必须手动添加 extension。

问题四：组呼时部分分机没声音

用 mod_conference 实现组呼，10 人会议中部分分机能听到别人说话但自己的声音传不出去。

输出显示所有成员都在会议中，但问题成员的音频能量为 0。进一步排查发现，这些分机协商的编解码是 Opus，而其他分机用的是 G.711。mod_conference 的混音引擎需要统一编码格式，Opus 的压缩编码导致转码后音频丢失。

在拨号计划中强制统一编解码：

同时在 Sofia profile 中调整编码优先级：

fs_cli -x "sofia profile internal restart reloadxml"

踩坑总结：mod_conference 对编解码格式敏感，混用不同编码会导致部分成员音频丢失。组呼场景建议统一用 G.711，牺牲一点带宽换取混音稳定性。

问题五：ESL 连接成功但收不到事件

Python 服务通过 ESL 连接 FreeSWITCH，TCP 连接建立成功，auth ClueCon 返回 +OK，但收不到任何 CHANNEL_ANSWER、CHANNEL_HANGUP 事件。

认证后发送 event plain all，telnet 下能看到事件推送，说明 FreeSWITCH 侧正常。问题在客户端——ESL 的 TCP 连接建立不等于事件订阅开启，必须显式发送 event 命令才能收到事件，而且订阅命令必须在 auth 成功后才能发送。客户端在 connect 回调中立即发送 event 命令，没有等待 auth 响应返回，导致命令被丢弃。

import ESL

conn = ESL.ESLconnection("127.0.0.1", "8021", "ClueCon")

auth_result = conn.api("status")
if auth_result and auth_result.getBody():
    conn.events("plain", "CHANNEL_ANSWER CHANNEL_HANGUP CHANNEL_CREATE")
    print("事件订阅成功")
else:
    print("ESL 认证失败")

while True:
    e = conn.recvEvent()
    if e:
        event_name = e.getHeader("Event-Name")
        uuid = e.getHeader("Unique-ID")
        print(f"事件: {event_name}, UUID: {uuid}")

事件处理逻辑如果耗时较长，建议放到独立线程，主线程只负责 recv，避免阻塞导致事件在 FreeSWITCH 侧被丢弃。

踩坑总结：ESL 事件订阅三个关键点：必须显式发送 event 命令、要在 auth 成功后发送、读取不能阻塞。这三点中任何一个出问题，都会表现为“连接正常但收不到事件”。

最终方案在测试环境下的实测数据：

服务器配置：4 核 8GB，CentOS 7，SATA SSD。

这 5 个问题覆盖了 FreeSWITCH 调度系统开发中的典型坑点。

环境搭建方面，apr 依赖必须源码编译，配置文件必须手动复制。拨号路由方面，FreeSWITCH 的拨号计划是纯数据驱动的，自定义分机号段必须手动添加 extension。组呼会议方面，mod_conference 对编解码格式敏感，统一用 G.711 是最稳妥的方案。ESL 方面，事件订阅必须显式发送 event 命令，且要在 auth 成功后发送，读取不能阻塞。

以上基于 CentOS 7 + FreeSWITCH 1.10.12 环境实测，具体参数需根据实际部署环境调整。

FreeSWITCH 调度系统开发实录：SIP 注册、组呼与录音的 5 个实现问题

去年接手了一个矿山调度通信系统的开发任务。需求方要求把矿区现有的模拟电话、新建的IP话机、广播终端统一纳入一套调度平台，支持一键组呼、分区广播、通话录音和应急指挥。项目规模不大，大约24路模拟话机需要利旧接入，系统注册容量按50路规划，调度台用触摸屏操作。

音视频

网络与通信

后端

FreeSWITCH调度平台搭建避坑指南：源码编译需手动处理apr依赖及配置文件；拨号计划必须自定义extension；组呼统一G.711编解码防音频丢失；ESL事件订阅需auth成功后显式发送。实测支持40路组呼、1.5秒建立，录音CPU占用12%，提供完整排查思路与性能参考。

服务器

路由

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

FreeSWITCH 调度系统开发实录：SIP 注册、组呼与录音的 5 个实现问题

FreeSWITCH 调度系统开发实录：SIP 注册、组呼与录音的 5 个实现问题

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐