FreeSwitch简介FreeSwitch是一个开源的电话交换平台。官方给它的定义是---世界上第一个跨平台的、伸缩性极好的、免费的、多协议的电话软交换平台。你可以把它想象成一个超级电话总机。它能让电脑、手机、普通电话等各种设备互相打电话还能实现很多高级的电话功能。它的设计目标是提供一个灵活、强大的通信框架能够处理各种形式的实时媒体通信包括语音、视频、文字等。官方文档FreeSWITCH Explained | FreeSWITCH Documentation衍生项目RTS官方文档RTS 文档一、FreeSwitch术语介绍SIP协议Session Initiation ProtocolSIP会话初始协议是用于建立、修改和终止多媒体会话如语音、视频通话的信令协议广泛应用于VoIP网络电话和即时通讯。它是互联网工程任务组IETF制定的标准RFC 3261。核心功能会话管理发起、终止通话邀请参与者加入会议。用户定位通过SIP地址如sip:userexample.com找到对方。协议兼容性可与RTP传输语音/视频、SDP描述会话参数等协议协同工作。优势灵活性支持点对点或通过代理服务器通信。可扩展性适应一对一通话、会议、即时消息等场景。标准化兼容不同厂商的设备和服务。工作流程示例INVATE发起通话100 Tring临时响应已经收到正在处理183 Session Progress表示会话正在建立200 OK被叫方同意接听ACK呼叫方同意接听分机号 (Extension)分机号是FreeSWITCH内部用于标识终端用户的基本单位通常由数字组成(如1000-1019是默认配置的分机号范围)。分机号不仅用于内部通信还可以通过网关与外部电话系统对接类似于传统 PBX 系统中的内线号码。分机号的配置存储在directory/default/目录下的 XML 文件中例如1000.xml。功能每个分机代表一个终端用户或设备配置在directory/default/目录下XML文件中定义认证包含用户名、密码、SIP域等信息类型可以是SIP话机、软电话、模拟电话等extension nameMyExtension condition fielddestination_number expression1234 action applicationanswer/ action applicationplayback datahello-world.wav/ action applicationhangup/ /condition /extension分机号和SIP用户的关系每个分机号通常对应一个SIP用户账号如分机1001对应SIP账号1001。用户用SIP账号即分机号注册到SIP服务器后可以通过分机号进行呼叫和接听。分机号是业务层面的标识SIP用户是协议层面的账号两者一般绑定在一起B2BUABack-to-Back User AgentB2BUABack-to-Back User Agent背靠背用户代理是FreeSwitch的核心呼叫控制模型。B2BUA 是一种 SIP 呼叫代理模型位于两个通话端之间将一次通话拆分为两个独立的 SIP 会话。B2BUA 既充当主叫User Agent ClientUAC也充当被叫User Agent ServerUAS。通话双方的信令和媒体都经过 B2BUAB2BUA 可以完全控制、修改、转发信令和媒体流。在 FreeSWITCH 中每次呼叫建立时B2BUA 会创建两条通道ChannelA腿A-leg主叫通道通常是呼叫发起方。B腿B-leg被叫通道通常是被呼叫方。这两条腿由 FreeSWITCH 内部桥接bridge但它们是完全独立的通道可以分别控制、挂断、转接、录音等。例如A腿挂断时B腿可以继续存在如转接、保持等反之亦然。桥接bridge桥接Bridge在 FreeSWITCH 和 SIP 通信中指的是把两个通话通道a-leg 和 b-leg连接起来使主叫和被叫能够直接通话。简单来说桥接就是“把两个人的语音流连通”让双方可以实时对讲。普通点对点通话分机呼叫分机、分机外呼会桥接 a-leg和 b-leg。单腿通话比如只播放语音、IVR 菜单、自动语音通知等场景只有 a-leg没有 b-leg不需要桥接。会议、监听、录音等特殊场景可能有多个“腿”不一定是简单的 a-leg 和 b-leg。拨号计划DialplanFreeSWITCH拨号计划(Dialplan)定义呼叫路由规则的核心组件相当于电话系统的路由表。决定了电话呼叫如何被分析、处理和路由到不同目标当用户拨号时系统会根据拨号计划对号码进行分析进而决定下一步的路由动作。匹配流程呼叫进入 -- 匹配Context-- 按顺序检查Extension -- 执行第一个匹配的Condition拨号计划的作用呼叫路由根据被叫号码、主叫号码等条件将呼叫路由到不同目标。流程控制定义通话过程中的各种行为和流程。功能实现实现呼叫转移、语音播报、IVR、录音等通信功能。案例简单呼叫路由匹配特定号码并播放音频extension nameMyExtension condition fielddestination_number expression1234 action applicationanswer/ action applicationplayback datahello-world.wav/ action applicationhangup/ /condition /extension号码前缀添加为外呼号码添加前缀extension nameforward_call condition fielddestination_number expression^(\d{11})$ action applicationset datadestination_number88${destination_number}/ action applicationbridge datasofia/gateway/gw4/${destination_number}/ /condition /extension电话录音实现单腿录音功能extension namerecord condition fielddestination_number expression1237 action applicationanswer/ action applicationrecord data/tmp/1.wav/ /condition /extension运营商网关对接通过网关外呼extension namecall_out condition fielddestination_number expression([0-1][0-9]{10,11}) action applicationbridge datasofia/gateway/outbound/$1/ /condition /extensionSofia模块mod_sofiaSofia 是 FreeSWITCH 的核心模块负责处理 SIP 协议和 RTP 媒体流。它是 FreeSWITCH 中最重要的模块之一支持 SIP 注册、呼叫建立、媒体协商等功能功能支持 SIP 协议栈RFC 3261。管理 SIP 用户代理UA、代理服务器和网关。处理 SIP 信令和媒体流如音频、视频。配置文件sofia.conf.xml定义 SIP 配置。sip_profiles/包含 SIP 配置文件的目录如internal.xml和external.xmlInternal 和 External Profiles默认端口5060FreeSWITCH 通过internal和external两个 SIP Profile 区分内网和外网通信Internal Profile内部 Profile用途专为内网或受信任的网络环境设计用于处理内部用户如分机、软电话的注册和呼叫。典型配置监听内网 IP 和端口如 192.168.1.100:5060。启用宽松的安全策略如简化认证因为用户被视为可信。绑定内部分机号和拨号计划如 user_context。适用场景企业内部通话、分机互拨、内部会议等。External Profile外部 Profile默认端口5080用途面向公网或不受信任的网络用于连接外部网关如运营商、SIP 中继或处理来自互联网的呼叫。典型配置监听外网 IP 或 NAT 后的地址如 203.0.1.1:5080。严格的安全措施如强制认证、ACL 访问控制。绑定外部网关配置如 external_gateway和公共拨号计划如 public。适用场景外呼至 PSTN、接收外部来电、对接 ITSP互联网电话服务提供商。特性Internal ProfileExternal Profile网络环境内网受信任外网不受信任默认端口50605080安全策略宽松如简化认证严格如 ACL、网关认证主要功能内部分机注册与互拨外呼网关对接、接收外部呼叫配置文件路径conf/sip_profiles/internal.xmlconf/sip_profiles/external.xml域名绑定通常绑定内网域名如 freeswitch.local绑定公网域名或 IP网关Gateway网关在 FreeSWITCH 中是指连接到外部电话网络(如PSTN、SIP提供商、IMS网络等)的接口。它允许FreeSWITCH系统与外部电话系统进行通信。网关配置文件网关配置通常位于freeswitch/sip_profiles/external/目录下每个网关一个XML文件。include gateway nameasterlink.com !-- 账号用户名必填 -- param nameusername valuecluecon/ !-- 认证域可选通常与网关名相同 -- param namerealm valueasterlink.com/ !-- SIP From字段中的用户名可选 -- param namefrom-user valuecluecon/ !-- SIP From字段中的域名可选 -- param namefrom-domain valueasterlink.com/ !-- 账号密码必填 -- param namepassword value2007/ !-- 入站呼叫的分机号可选 -- param nameextension valuecluecon/ !-- 代理服务器地址可选 -- param nameproxy valueasterlink.com/ !-- 注册时使用的代理服务器可选 -- param nameregister-proxy valuemysbc.com/ !-- 注册有效期秒 -- param nameexpire-seconds value60/ !-- 是否注册到SIP服务器 -- param nameregister valuefalse/ !-- 注册时使用的传输协议 -- param nameregister-transport valueudp/ !-- 注册失败或超时后重试间隔秒 -- param nameretry-seconds value30/ !-- 是否在SIP From字段中使用主叫号码 -- param namecaller-id-in-from valuefalse/ !-- 在SIP Contact字段中附加的额外参数 -- param namecontact-params value/ !-- 是否在SIP Contact字段中包含分机号 -- param nameextension-in-contact valuetrue/ !-- 发送SIP OPTIONS心跳包的间隔秒 -- param nameping value25/ !-- 主叫号码类型rpid表示使用Remote-Party-ID -- param namecid-type valuerpid/ !-- 是否启用RFC5626SIP Outbound扩展 -- param namerfc-5626 valuetrue/ !-- RFC5626注册ID -- param namereg-id value1/ /gateway /include软电话软电话是一种通过互联网实现实时通讯的虚拟电话属于通信终端设备。其核心功能在于将语音转换为数据信号传输无需专用硬件即可在计算机、手机或平板等设备上运行。不同类型软电话的区别mrcSIP、Zoiper 这类独立 SIP 软电话与前端网页实现的软电话在技术架构、功能特性和适用场景上有显著区别。以下是主要对比对比项mrcSIP / Zoiper 等独立软电话前端网页软电话如 WebRTC/SIP.js运行环境需安装独立客户端Windows/macOS/Linux/iOS/Android直接在浏览器运行如 Chrome、Edge无需安装依赖技术基于 SIP 协议可能依赖本地库如 PJSIP基于 WebRTC SIP.js依赖浏览器 API注册方式通过 SIP 账号如 1000freeswitch注册到 FreeSWITCH通常使用 WebSocket连接 FreeSWITCH开发语言C、Java、Objective-C 等JavaScript、HTML5、WebSocket集成方式独立运行或嵌入第三方应用如 CRM通过 iframe 或 JS SDK 嵌入网页上下文Context在FreeSWITCH中上下文(Context)是一个核心概念它定义了呼叫路由的逻辑分组和隔离机制是拨号计划(Dialplan)组织和管理的基础架构。上下文是FreeSWITCH中用于隔离不同拨号规则的逻辑容器每个上下文包含一组拨号规则(extensions)系统根据呼叫的来源或属性决定使用哪个上下文来匹配路由规则。主要作用包括路由隔离不同来源的呼叫可以使用不同的路由规则安全隔离限制特定用户只能访问特定上下文中的路由规则逻辑分组将相关功能的路由规则组织在一起多租户支持不同租户可以使用独立的上下文上下文主要在以下配置文件中定义拨号计划文件conf/dialplan/default.xml等SIP Profile配置conf/sip_profiles/*.xmlprofile nameinternal !-- 主叫将路由到default context -- param namecontext valuedefault/ /profile注意点SIP Profile配置的上下文为通过该Profile注册或发起的呼叫提供默认上下文分机注册时的上下文可以覆盖SIP Profile的默认上下文设置SIP Profile本身不受上下文约束它是上下文规则的提供者而非接受者域DomainFreeSWITCH 中的“域domain”是指用于区分和管理不同用户、分机、呼叫路由等逻辑范围的标识类似于 SIP 协议中的“域名”概念。详细说明如下基本概念域domain通常对应一个公司、组织或业务系统的唯一标识常见为 IP 地址或 FQDN如 pbx.example.com。在 SIP 协议中用户的完整标识为 userdomain如 1001pbx.example.com。作用与意义用户隔离不同域下的用户、分机、拨号计划等互相隔离便于多租户multi-tenant部署。呼叫路由FreeSWITCH 根据域名决定呼叫的路由和处理逻辑实现灵活的呼叫分发。安全控制可针对不同域设置独立的认证、权限、策略等提升系统安全性。配置管理conf/directory/ 目录下每个域有独立的用户/分机配置文件便于分组管理。配置方式在 conf/directory/ 下创建以域名命名的目录或 XML 文件定义该域下的用户、分机等信息。在 SIP Profile如 internal.xml中配置 default_domain指定默认域名。呼叫时通过 userdomain 方式区分目标用户所属域。典型应用场景多公司共用一套 FreeSWITCH每家公司一个独立域实现资源隔离。按业务线、部门划分域便于权限和策略管理。总结FreeSWITCH 的域domain是实现多租户、用户隔离、灵活路由和安全管理的核心机制贯穿于用户注册、呼叫路由、配置管理等各个环节。访问控制列表ACLACLAccess Control List访问控制列表是FreeSWITCH中用于控制网络访问权限的核心机制它通过定义规则矩阵来决定哪些IP地址或网络实体可以访问特定资源。ACL在FreeSWITCH中主要用于IP访问控制限制特定IP地址或网段的访问权限SIP鉴权控制哪些IP可以注册或发起呼叫安全防护防止未授权访问和恶意攻击NAT穿越识别内网设备并协助完成NAT穿越ACL的核心思想是默认拒绝显式允许即除非明确允许否则所有访问都将被拒绝。ACL配置文件与结构预设ACL规则FreeSWITCH内置了几种预设ACL规则rfc1918.autoRFC1918定义的私有地址空间nat.autoRFC1918地址空间排除本地LANlocalnet.auto本地LAN的ACLloopback.auto本地回环地址ACL!-- 自定义一个 name -- list nameesl_access defaultdeny node typeallow cidr113.1.1.1/32/ node typeallow cidr127.0.0.1/32/ /listESL (Event Socket Library)8021ESL (Event Socket Library) 是 FreeSWITCH 提供的一个强大的接口允许外部程序通过 TCP 套接字与 FreeSWITCH 核心进行交互。ESL特性基于 TCP 的客户端-服务器接口支持同步和异步通信模式提供对 FreeSWITCH 的实时控制和监控能力支持多种编程语言绑定(Python, PHP, Java, C/C等)两种连接模式Inbound (入站模式)外部应用如 Java 程序作为客户端主动连接 FreeSWITCH 的 ESL 服务端口默认 8021建立 TCP 连接后进行命令交互和事件监听。应用场景需要外部程序主动控制 FreeSWITCH如发起呼叫、挂断、监听事件等。适合做后台管理、监控、自动化控制等。你的 Java 服务就是典型的 Inbound 模式。优点易于部署和管理。支持多客户端同时连接。Outbound (出站模式)FreeSWITCH 在呼叫流程中如拨号计划中 socket 应用主动作为客户端连接到外部应用你的服务端并将通话控制权交给外部应用。应用场景需要对每个呼叫进行实时、细粒度的控制如 IVR、机器人、外呼任务。适合做呼叫中心、自动语音应答、外呼机器人等。外部应用需实现 socket 服务端等待 FreeSWITCH 连接。优点可以对单个通话进行全流程控制。灵活实现复杂业务逻辑总结需要全局管理、事件监听用 Inbound。需要对单个呼叫做复杂控制用 Outbound。配置文件地址conf/autoload_configs/event_socket.conf.xmlconfiguration nameevent_socket.conf descriptionSocket Client settings !-- 不启用 NAT 自动端口映射, 一般服务器部署在公网或有固定端口映射时建议设为 false-- param namenat-map valuefalse/ !-- 0.0.0.0 用于需要让多网卡或外部主机都能访问 ESL 服务的场景。如果只需要本地访问可以用 127.0.0.1更安全。-- param namelisten-ip value::/ param namelisten-port value8021/ !-- 默认密码更改之后 linux使用命令 fs_cli 需要带上新密码例fs_cli -p 1234 -- param namepassword valueClueCon/ !-- inbound模式启用acl -- param nameapply-inbound-acl valueesl_access/ !-- 当端口绑定失败时是否让 FreeSWITCH 直接停止启动境建议开启-- param namestop-on-bind-error valuetrue/ /settings /configuration关于AB腿的区分在 FreeSWITCH 中A-leg 和 B-leg 的判定确实是约定俗成的逻辑概念而非系统强制标记的字段。它们的区分主要依赖呼叫流程的设计、API/Dialplan 的操作顺序或是事件日志的上下文。场景一直接路由终端A直接发起呼叫(a-leg)到FreeSwitchFreeSwitch根据预设的拨号计划自动路由到终端B建立b-leg通话。这是最基础的直接路由呼叫流程。场景二桥接命令ESL客户端使用originate命令带bridge参数发起呼叫。FreeSwitch会先建立与终端A的a-leg连接待A接通后再自动发起与终端B的b-leg连接实现智能顺序桥接。场景三挂起转接ESL客户端先将终端A的呼叫挂起(park)待A应答后通过uuid_transfer命令将通话转接到终端B。这种方式允许在A接通后再决定路由目标。场景四双挂起桥接ESL客户端分别挂起终端A和B的呼叫待两者就绪后通过uuid_bridge命令将两条独立的leg桥接在一起。这种双挂起方式适合需要精确控制桥接时机的场景。二、目录结构根目录结构目录说明bin/二进制文件目录FreeSWITCH 可执行程序和工具所在目录启动/停止服务都依赖这里。conf/核心配置文件目录所有 SIP、拨号计划、模块等配置都在这里。db/数据库目录存放内部数据库如 SQLite用于存储注册信息、计费等。htdocs/Web文件目录仅用于 Web 管理界面或静态网页不影响核心功能。lib/库文件目录FreeSWITCH 运行所需的动态库文件。log/日志目录存放运行日志排查问题必看。mod/模块目录所有功能模块如 mod_sofia、mod_conference 等都在这里。recordings/录音目录通话录音文件存放目录。run/运行时文件目录存放运行时产生的临时文件如 pid 文件。scripts/脚本目录存放自定义脚本如 lua、js 等实现自动化或业务逻辑。sounds/语音文件目录系统语音提示、彩铃等音频文件目录。storage/存储目录通用存储目录可用于语音信箱、传真等。配置文件目录结构conf/目录/文件说明autoload_configs/自动加载目录包含各模块自动加载的配置文件目录dialplan/拨号计划配置目录定义呼叫路由和逻辑directory/分机目录配置sip_profiles/SIP 协议相关配置目录vars.xml全局变量配置文件ivr_menus/IVR语音导航菜单配置目录jingle_profiles/Jingle 协议相关配置目录mime.typesMIME 类型定义文件freeswitch.xml主配置文件包含全局和模块引用...配置文件加载顺序1.vars.xml→ 2.freeswitch.xml→ 3.autoload_configs/*.conf.xml→ 4. 其他按需加载的配置关键配置文件conf/├── autoload_configs/ # 模块自动加载配置│ ├── acl.conf.xml # 访问控制列表(IP黑白名单)│ ├── callcenter.conf.xml # 呼叫中心队列配置│ ├── cdr_csv.conf.xml # CDR话单CSV格式配置│ ├── event_socket.conf.xml # ESL事件套接字配置│ ├── modules.conf.xml # 核心模块加载配置│ ├── sofia.conf.xml # SIP协议栈配置│ ├── unimrcp.conf.xml # MRCP协议模块配置(语音识别/合成)│ ├── verto.conf.xml # WebRTC(Verto)配置│ ├── voicemail.conf.xml # 语音邮件配置│ └── ...│├── dialplan/ # 拨号计划│ ├── default/ # 默认拨号计划│ │ ├── default.xml # 基本呼叫路由规则│ │ ├── features.xml # 系统功能(*号功能码)│ │ ├── public.xml # 公开号码段路由│ │ └── ivr.xml # IVR菜单定义│ ├── public/ # 公共拨号计划(用于PSTN接入)│ └── example.com/ # 自定义域拨号计划(多租户场景)│├── directory/ # 用户目录(分机配置)│ ├── default/ # 默认域用户│ │ ├── 1000.xml # 分机1000配置│ │ ├── 1001.xml # 分机1001配置│ │ └── ...│ ├── example.com/ # 自定义域用户(多租户场景)│ └── profile/ # SIP用户模板配置│├── mrcp_profiles/ # MRCP语音服务配置│├── sip_profiles/ # SIP配置文件│ ├── internal.xml # 内网SIP配置(分机注册)│ ├── external.xml # 外网SIP配置(中继/运营商)│ ├── internal-ipv6.xml # IPv6专用配置│ ├── external/ # 外网SIP子配置目录│ │ ├── carrier_gw.xml # 运营商网关配置│ │ └── ...│ └── ...│├── ivr_menus/ # IVR语音菜单│ ├── demo_ivr.xml # 示例IVR菜单│ ├── customer_service.xml # 客户服务IVR流程│ └── ... # 其他IVR配置│├── lang/ # 多语言提示音配置│ ├── en/ # 英语提示音配置│ ├── zh/ # 中文提示音配置│ └── ... # 其他语言配置│├── vars.xml # 全局变量定义(优先级最高)│├── freeswitch.xml # 主配置文件(启动时加载)│└── xml_curl/ # 动态XML配置接口三、外呼demo点对点呼叫核心命令freeswitch分别拨打1000分机和150手机号再将两个通道桥接在一起originate {origination_caller_id_number123,absolute_codec_stringPCMU,bypass_mediafalse,auto_answertrue}user/1000 bridge({origination_caller_id_number123}sofia/gateway/carrier_gw/手机号)时序图群呼转接核心命令freeswitch拨打外部电话保持挂起originate {origination_caller_id_number123,absolute_codec_stringPCMU,bypass_mediatrue}sofia/gateway/carrier_gw/手机号 park()在通话中播放录音连续发送命令会依次播放uuid_broadcast uuid playback::$${sounds_dir}/en/us/callie/misc/8000/misc-ostag_learn_more.wav桥接外呼通道到指定的分机号uuid_transfer uuid export:origination_uuidext_uuid,bridge:user/1000 inline强制中断媒体流中断正在播放的媒体uuid_break uuid开启录音uuid可以用命令 show channels查询uuid_record uuid start/stop path时序图AI语音参考文章FreeSWITCH 智能呼叫流程设计_chrome freeswitch 呼叫过程-CSDN博客如何在XSwitch中使用mod_unimrcp | XSwitch文档中心最佳实践 | 基于腾讯云MRCP-Server打造简单智能外呼系统-腾讯云开发者社区-腾讯云MRCP协议MRCPMedia Resource Control Protocol媒体资源控制协议是一种用于控制语音服务器资源的网络协议它允许客户端控制语音合成TTS和语音识别ASR等媒体处理资源。在FreeSWITCH的AI语音架构中MRCP扮演着核心角色。MRCP协议相当于语音服务的‘遥控器’它让客户端比如电话系统能远程控制语音服务器上的功能如语音识别、合成而具体的声音传输和连接则由其他协议如SIP/RTSP负责。MRCP的关键特性支持两种版本MRCPv1基于RTSP和MRCPv2基于SIP提供标准化的接口控制ASR/TTS引擎通过SDP协商媒体会话参数支持多种语音编解码器如PCMU、PCMA等mod_unimrcp模块介绍文章mod_unimrcp从FreeSWITCH代码树中删除-腾讯云开发者社区-腾讯云。是FreeSWITCH中实现MRCP客户端功能的模块作为MRCP客户端与MRCP服务器交互。这个模块已经被移除freeswitch的主分支目前用独立git仓库。UniMRCP可以不用这个官网HomeUniMRCP是一个用C/C编写的开源跨平台MRCP(Media Resource Control Protocol)协议实现由Araneus公司开发并维护。它提供了完整的MRCP客户端和服务端实现支持MRCPv1(基于RTSP)和MRCPv2(基于SIP)两个版本EasyMrcp替代上面的UniMRCP官方文档地址EasyMrcp——集成ASR/TTS的mrcp服务器 · 语雀EasyMrcp是基于UniMRCP的二次封装目的为了简化UniMRCP的集成复杂度。EasyMrcp使用java编写目前提供了多种不同的asr和tts的集成做到真正简单使用MRCP可直接替代UniMrcp。