简介针对Freeswitch呼入呼出路由配置与SIP中继设置的实战参考面向VoIP运维、通信开发及网络工程师。文档以FreeSwitch V1.2.7为基础从系统启动与消息分发入手逐步展开呼入路由、外呼策略、对等中继模式下SIP中继地址与端口的配置同时覆盖拨号计划、网关接入、PSTN中继、TLS安全、负载均衡和错误恢复等关键环节。内容预览中可以看到完整的目录结构从核心架构、程序启动、消息分发到mod_sofia模块的组成与启动均有章节说明便于按模块深入查阅。资源包为1个doc文档整体约221KB轻量但信息密度较高。已有6448人学习适合需要快速理解Freeswitch路由机制并落地SIP中继配置的读者也可作为日常排错与二次开发的参考。1. 呼入呼出路由配置到底是什么问题先看懂三个路由黑洞场景一个场景电话拨进公司总机转分机号一直响铃没人接最后掉进语音信箱另一个分机拨 0 外呼电话里直接说呼叫不能完成还有一条两条外线网关都配好了呼出却永远走第一条。三个现象背后是同一个根因—— freeswitch 呼入呼出路由配置详解 这套链路没吃透。这里说的路由不是网络层静态路由而是 FreeSWITCH 拨号计划dialplan为每个通话找出口的过程。下面用可复现的 XML 配置把呼入、呼出、网关选择和排错串起来适合刚拿到 FreeSWITCH 就被拉去配语音的运维也适合已配好基本分机但被外线折腾的人。读完你能自己造一张跑通呼入分机和呼出外线的 dialplan并能定位失败原因。2. 路由配置的根dialplan 的结构与选型理由2.1 dialplan 不是路由表而是一段带正则的 XML 解释器第一次接触 FreeSWITCH 的人最容易把 dialplan 想象成一张和ip route差不多的表号码前缀对网关查表转发。实际上 dialplan 是一段逐条执行的 XML 规则执行顺序是自上而下、逐条匹配命中后执行完就停除非显式要求继续匹配。我把 FreeSWITCH 的拨号计划类比成网络静态路由和 iptables 的某种合体匹配字段、正则表达式、动作串在一起但没有任何动态路由协议在背后自动收敛——你不需要也不能指望它像 OSPF 或 RIP 那样发现新网关后自动学习路由电话网号码和网关之间的关系本来就需要人工维护静态化反而是优点。dialplan 的结构分三层元素作用对应关系context呼叫上下文相当于路由实例呼入用 public分机内部用 default 很常见extension路由条目可以理解成一条路由规则condition匹配条件相当于路由前缀匹配action / anti-action命中后的动作 / 未命中后的动作对应执行操作每个 extension 至少要有一个 conditioncondition 里用field指定要匹配的呼叫变量用expression写正则。常见的 field 是destination_number被叫号码和caller_id_number主叫号码。整个 XML 文件默认放在conf/dialplan/下一个新的 context 可以被多个拨号计划文件共用我一般习惯把呼入、呼出、内部互打拆成三个 XML 文件方便定位问题而不是把所有 extension 堆在同一个 default.xml 里。从跨平台的角度说无论你在 Linux 上从源码编译安装还是直接拿 freeswitch安装win 的安装包装好dialplan 的 XML 语法是一致的差别只在 conf 目录路径和编码细节。Windows 上尤其注意文件的编码后文避坑章会专门说。2.2 为什么 FreeSWITCH 不用「动态路由协议」那一套先说结论电话路由不需要动态收敛所以 FreeSWITCH 选择了静态 XML 解释器模式。电话路由的网段是号码前缀下一跳是网关gateway但前缀和网关的映射变化频率很低而且一条路由配错只影响一类呼叫不会像网络环路一样把整个业务打挂。FreeSWITCH 官方不提供像 OSPF 那样的自动选路模块社区里常见做法就是靠条件判断和 bridge 顺序实现多网关兜底。这带来一个选型上的好处路由逻辑可以被版本化管理改错了随时回滚不会因为一个错误路由扩散波及全盘。但也带来一个代价所有分支都要自己写。比如呼入时间路由、周末路由、节假日路由全部要在 dialplan 里用 condition 堆出来。这与 ensp 里做静态路由配置实验的思路很像——把每条路径显式声明出来而不是依赖协议自动收敛。现实中我看到不少团队会额外加一套配置生成系统用模板把 dialplan 生成出来也没有引入动态路由协议说明静态方案在语音网关这个场景里是够用的。2.3 最小可用的 dialplan 模板看懂 condition / action / anti-action下面是最小可用的一个呼入分机路由它把拨 1000 的呼叫桥接给分机 1000。把这个 context 放进conf/dialplan/default.xml或者在主配置里 include 一个新文件。include context namedefault extension nameinternal-call-to-1000 condition fielddestination_number expression^1000$ action applicationbridge datauser/1000/ /condition /extension /context /include逻辑说明当呼叫进入 default 这个 context 时通道变量destination_number会被拿去和^1000$做整串匹配命中了就执行bridge把呼叫接续到user/1000。bridge是 FreeSWITCH 里最重要的路由动作它不只是转接而是把当前通话通道和一个新通道连起来新通道可以是分机、IVR、队列或网关。参数说明里有两个点值得展开。第一正则里的^和$不是可选的省略后会出现10001 也命中了 1000 路由的意外第二user/1000这个目标是 FreeSWITCH 内置的呼叫定位语法它根据当前拨号计划查找到注册的分机 1000比起直接写sofia/internal/1000domain这种形式更省心。如果 condition 没命中且你写了anti-action就会执行这里的内容一般用来放提示音或拒接日志。我再给一个带 anti-action 的写法保证未匹配时能留下可查痕迹extension namecatch-all-missed condition fielddestination_number expression^(\d)$ anti-action applicationlog dataWARNING 未匹配号码 ${destination_number} 来源 ${caller_id_number}/ anti-action applicationhangup/ /condition /extension逻辑说明anti-action在 condition 的正则匹配失败时执行。上面这段把未匹配的可疑呼叫记进日志然后挂断避免呼叫在 FreeSWITCH 里无线空转。这里有一个常见误区anti-action是跟着 condition 走的不是跟着 extension 走的一个 extension 里多个 condition 时每个 condition 都能有自己的 anti-action。这里还有一个决定路由行为的隐藏开关continue。extension 标签上如果写了continuetrue命中执行完后不会停而是继续往下匹配后面的 extension。这对做补充计费、逐个网关尝试很有用。默认情况不写 continue 时路由是首次命中即终态。我通常只在多网关轮询和呼叫权限审计两块用 continue其他地方尽量少开开着开着就会迷路。3. 呼入路由怎么配从分机直达、IVR 到时间分支3.1 呼入路由的最小闭环把来电转给分机 1000先明确呼入和呼出的分界线。呼入是从外部线路PSTN/中继打进 FreeSWITCH先落在 SIP profile然后进入 dialplan 的某个 context。大部分默认配置文件里外部呼叫会进入publiccontext而public的权限比default小得多。所以配置呼入路由时第一步不是写 bridge而是确认来电落在哪个 context。我的常见做法是在conf/dialplan/public.xml里写一条只处理指定被叫号码的路由。假设总机被叫是86660000来电拨这个号码后转到分机 1000include context namepublic extension nameinbound-to-ext-1000 condition fielddestination_number expression^86660000$ action applicationanswer/ action applicationsleep data500/ action applicationbridge datauser/1000/ /condition /extension /context /include逻辑说明第一步answer先应答让线路进入通话状态第二步sleep 500给 0.5 秒缓冲避免一端刚应答另一端立即接续导致极端情况下首包丢失第三步bridge把呼叫转给分机。这三步是呼入路由的常见起手式先应答再转接可以让后面的动作更顺畅。参数说明datauser/1000依赖分机号存在且在 default context 里可被发现。如果分机注册不在本机比如用了外部 SIP 终端就要把 bridge 目标改成sofia/internal/1000你的域名或IP。domain 配错是呼入转分机失败的高发点因为 FreeSWITCH 会根据 domain 查找分机归属。3.2 按主叫/被叫分流到 IVR 或队列两个常用动作呼入路由很少只做转分机更多是按主叫或被叫去分流。两个高频动作是play_and_get_digits和callcenter。前者做 IVR 交互后者把呼叫送进排队队列。extension nameinbound-ivr condition fielddestination_number expression^86660000$ action applicationanswer/ action applicationplay_and_get_digits data3 8 3 7000 ${ivr_choice} /usr/local/freeswitch/sounds/ivr-menu.wav /usr/local/freeswitch/sounds/ivr-invalid.wav ivr 5 3000/ action applicationset datadest_ext${ivr_choice}/ action applicationbridge datauser/${dest_ext}/ /condition /extension逻辑说明play_and_get_digits是 FreeSWITCH 的按键收集动作参数从左到右分别是最多收 3 位、最大静音 8 秒、最多重试 3 次、超时后默认值 7000按 7、存结果的变量名${ivr_choice}、提示音文件、无效输入提示音、音频模式、识别超时、整体等待。收集完成后set把结果存成新变量dest_ext最后bridge到对应分机。这个写法可以支撑一个很简短的 IVR 菜单。参数说明play_and_get_digits的参数位次不能记错错一位会出现提示音没播完就收键或怎么按都不响应的现象。音频路径建议写绝对路径且最好用 wav 格式MP3 在某些编译版本上需要额外模块支持踩过坑的人大多会改用 wav。把呼叫送进队列用的是callcenter应用。它依赖mod_callcenter队列定义在conf/autoload_configs/callcenter.conf.xml里extension nameinbound-callcenter condition fielddestination_number expression^86660000$ action applicationanswer/ action applicationcallcenter datasupport_queue/ /condition /extension逻辑说明callcenter的第一个参数是队列名这里写的support_queue必须在 callcenter.conf.xml 的queues里定义好否则路由会报 queue not found。队列里可以配坐席策略轮流、最长空闲、最少通话和超时溢出策略。这里我只给到 dialplan 侧的动作队列策略本身仍然留在 callcenter.conf.xml 中不要在 dialplan 里改坐席分配。3.3 呼入的时间路由上班时间进队列下班时间进语音信箱呼入路由的另一个常见维度是时间。FreeSWITCH 的 condition 原生支持hour、wday、mday等字段可以按星期和小时做分支。这里的思路是先匹配时间段再匹配号码而不是在同一个 condition 里堆两个维度。extension nameinbound-business-hours condition fielddestination_number expression^86660000$ hour08:00-18:00 wday1-5 action applicationanswer/ action applicationcallcenter datasupport_queue/ /condition /extension extension nameinbound-after-hours condition fielddestination_number expression^86660000$ action applicationanswer/ action applicationplay_and_get_digits data1 6 2 9 ${vm_option} /usr/local/freeswitch/sounds/afterhours.wav 7000 * 5 3000/ action applicationbridge datauser/1000/ /condition /extension逻辑说明第一个 extension 的 condition 同时带了hour和wday属性只有周一至周五1-5且 08:00 到 18:00 之间才命中第二个 extension 是兜底所有未命中第一个条件的 86660000 来电都会到这里。这里的关键是顺序把限时条件放在前面兜底放在后面FreeSWITCH 的匹配逻辑是先命中先执行一旦第一个命中并执行完后面的 extension 不会再被检查。参数说明wday的取值范围是 1-7对应周一至周日hour使用 24 小时制写法08:00-18:00表示包含两端。需要节假日另配时可以用mday月内日期字段再不行就拉 mod_distributor 做更细的外部日历判断但绝大多数场景时间字段够用。注意上面的第二个 extension 用play_and_get_digits做留言收集参数里把vm_option设为 9 代表转语音信箱但 FreeSWITCH 本身没有内置话务员语音信箱应用这里只是按键收集后转分机真正做语音留言需要再接 voicemail 应用。写这段想说明的是时间路由的优先级顺序比你写的正则还重要别把兜底 extension 放在第一个。呼入路由里还有一类经常被忽略的需求对指定主叫号码放行、对骚扰号码拦截。做法是把 caller_id_number 的匹配条件放在最前面条件命中执行放行或挂断。由于 anti-action 是在条件失败时执行你甚至可以写一条只匹配黑名单前缀的 extension命中就挂断未命中自然落到下一条 extension。注意 FreeSWITCH 对未在拨号计划中显式允许的呼叫默认是拒绝的所以黑名单拦截通常写成白名单模式更稳妥先放行已知分机再统一拒绝未知号码。4. 呼出路由怎么配网关、号码改写和多线路兜底呼出路由的复杂度不在 dialplan 本身而是网关、号码归一化和失败转移三件事。我把它拆成三步走。4.1 先把 SIP 网关配好gateway 命名与三个必调参数呼出路由的第一步是有一个能用的外线网关。FreeSWITCH 的 SIP 网关定义在conf/sip_profiles/external/下的 XML 中或者从conf/sofia.conf.xml里 include 网关文件进来。网关的概念可以这样理解它描述了一个对端 SIP 服务器以及 FreeSWITCH 以什么身份向它发起呼叫。include gateway namegw-sip-trunk param nameusername value10086/ param namepassword valueChangeMe/ param namerealm valuesip.isp-example.com/ param nameproxy valuesip.isp-example.com/ param nameregister valuetrue/ /gateway /include逻辑说明gateway的name属性就是后面 dialplan 里使用的网关名一经配置尽量别改因为 dialplan 和状态查看命令都会引用它。username和password是向对端注册或鉴权用的账号realm一般填对端 SIP 服务器的域名proxy是实际把 INVITE 发往的地址。大部分中继业务里realm和proxy相同但如果对端把注册域和呼叫域分开两个值就不同了。参数说明register设为true时FreeSWITCH 会向对端发 REGISTER适合需要注册鉴权的中继如果对端只收固定 IP 的呼叫、不许注册就把register设为false这时 username/password 仍要保留用于 INVITE 的摘要鉴权。多数呼出不通的问题出在realm填错——很多人在realm里填成 IP 字符串而对端要求填域名。配置好后用fs_cli -x sofia status gateway gw-sip-trunk看注册状态status 为 REGED 才说明网关侧就绪status 不是 REGED 时先别碰 dialplan因为大概率卡在账号密码或 realm 上。网关配置再配上一条路由转发规则相当于把固定号码前缀转发到固定网关这件事声明清楚也就是把哪些号码走哪条外线固定下来。4.2 呼出选路核心bridge 到 sofia/gateway 的写法网关就绪后呼出路由的核心就是一条 bridge 语句。分机拨 0 或拨 0 加号码的外呼在 dialplan 里常见的路由是extension nameoutbound-call condition fielddestination_number expression^0(\d)$ action applicationset dataoutbound_number${regex(${destination_number}|^0(\d)$|$1)}/ action applicationbridge datasofia/gateway/gw-sip-trunk/${outbound_number}/ /condition /extension逻辑说明condition匹配的是用户拨出的号码正则^0(\d)$的意思是用户先拨 0后面才是真实外线号码。命中后先把真实号码提取出来存进outbound_number再通过sofia/gateway/gw-sip-trunk/这个目标语法发起呼叫。sofia/gateway/网关名/号码是 FreeSWITCH 呼出到网关的固定写法网关名必须和 4.1 里gateway的 name 完全一致。参数说明${regex(...)}是 FreeSWITCH 内置字符串处理函数的调用方式格式是源字符串|正则|替换表达式。上面用$1拿回第一个捕获组也就是去掉前导 0 的真实号码。为什么不直接在 bridge 里写sofia/gateway/gw-sip-trunk/0${destination_number}因为很多中继运营商要求来电是 E.164 格式国家码开头而分机用户习惯拨 0 开头拆出来重组会更灵活。如果运营商要求加 0086 或 86 前缀把 set 那行改成dataoutbound_number86${regex(...)}即可。主叫号码的改写也放在呼出路由里。很多中继会校验主叫号码格式随便填会被拒。用下面两个变量在 bridge 前强制指定外显号码action applicationset dataeffective_caller_id_number01012345678/ action applicationset datacaller_id_number01012345678/逻辑说明effective_caller_id_number是 FreeSWITCH 最终对外发送的主叫号码caller_id_number是通道里的原始主叫。有些中继只看前者有些会两者都校验建议两个一起写。如果外显号码是由运营商下发而不是自选的就不要在 dialplan 里覆写交给网关透传即可。4.3 多网关轮询与失败转移一条线路挂了路由怎么换生产中一条外线网关不够用是常态。FreeSWITCH 没有内置的多网关优先级自动选路模块所以常见做法是利用 bridge 的失败顺序执行实现转移第一个 bridge 失败后会继续执行下一个 action。extension nameoutbound-with-fallback condition fielddestination_number expression^0(\d)$ action applicationset dataoutbound_number${regex(${destination_number}|^0(\d)$|$1)}/ action applicationbridge datasofia/gateway/gw-sip-trunk-a/${outbound_number}/ action applicationbridge datasofia/gateway/gw-sip-trunk-b/${outbound_number}/ action applicationbridge datasofia/gateway/gw-sip-trunk-c/${outbound_number}/ action applicationplay data/usr/local/freeswitch/sounds/all-lines-fail.wav/ /condition /extension逻辑说明这段路由先尝试链路 Abridge 返回失败呼叫未建立、超时、被拒后 FreeSWITCH 会自动执行下一个 action也就是链路 B再失败走 C全部失败后播放提示音。注意这里实现的是按顺序兜底不是负载均衡。要做真正的轮流负载均衡需要一个外层分发逻辑比如 mod_distributor 或拨号计划前置脚本我一般只在纯高可用场景用这里的顺序兜底避免同一路由在不同链路上产生怪话务。参数说明bridge 的默认呼叫超时在网关没有注册成功时会很快失败但在网关注册成功而对端不接时可能拖很久。可以在桥接前用变量控制超时或在 bridge 目标前加{ignore_early_mediatrue}这类通道变量来避免被早期媒体卡住。更常见的做法是给每个网关单独设置call_timeout再配合bridge的选项参数做精细控制。重点是不要在 dialplan 里用continuetrue硬叠三个 bridge那会绕晕呼叫详单也会让后续计费逻辑难以为继。5. 避坑呼入呼出路由最常见的 5 个翻车点与排查这一章聚焦实际配置过程中最容易浪费时间的几个坑每一条都按现象 → 原因 → 解决来写。5.1 分机号打了没反应或进了别人的分机condition 匹配顺序和正则错了现象拨 1000 没反应或拨 1001 却被路由到了 1000。原因dialplan 里存在另一条更先命中的 extension或者正则是^1000而不是^1000$导致 1001、10001 都能命中 1000 规则另外同一个 context 里两条 extension 都匹配同一个号码时先写在上面的优先。解决先看当前号码会命中哪条规则fs_cli -x dialplan show 1000这个命令会输出 FreeSWITCH 针对号码 1000 解析出的可命中 extension 列表按顺序从上到下就是实际执行顺序。把不该出现的规则删掉或者给正则补上$。还有一种隐蔽情况主叫呼入时进入了 public context而你把规则写在 default context导致呼叫根本不进这个 context。排查方法是看 SIP profile 与 context 的绑定关系必要时用sofia status profile external确认外部呼叫落在哪个 context。5.2 呼出号码少 0 或多国家码号码归一化没做现象分机拨0 138 0000 0000对方手机上显示13800000000或反而显示013800000000有的中继直接拒呼。原因运营商中继侧对号码格式有严格预期有的要求不带 0、有的要求国家码开头而拨号计划直接bridge了原始拨号串。解决统一在 bridge 前做一次号码加工action applicationset dataoutbound_number${regex(${destination_number}|^0(86)?(\d)$|$2)}/逻辑说明这个正则先吞掉用户拨号前导的 0再吞掉可能的 86把剩余号码提取为outbound_number。如果运营商要求带国家码再在 bridge 目标里写86${outbound_number}。这里最需要固定的是你的网关注册在哪个号码格式下不要同一路由里一会儿传 0 开头一会儿不传中继侧的号码格式是一份必须遵守的契约。我处理过的外呼故障一半以上最终都指向号码格式和中继侧预期不一致。5.3 呼出一直呼不通先看网关注册状态再动 dialplan现象路由写对了分机拨号没报错但听不到对端响应或直接听到运营商提示无法接通。原因大概率是网关根本没有注册成功dialplan 只是把呼叫发到了一个不存在的出口。解决用命令确认网关状态fs_cli -x sofia status gateway gw-sip-trunk输出里看状态字段重点关注 REGED已注册或错误码。如果是 401/407 反复出现回查 username/password/realm如果是 404检查网关配置里的 domain 或拨号目标是否被对端承认如果一直显示 UNREGED先确认 FreeSWITCH 所在机器到对端 SIP 服务器的网络是否通再确认 SIP 端口。记住网关注册不成功时改 dialplan 是无效的因为请求根本出不了网关这道门。这条是我排障时最先检查的一步。5.4 外呼后对方看到主叫号码不对外显号码没设或设错现象呼出能通但对方看到的不是公司总机号而是一个随机的分机号或空号。原因dialplan 没设置effective_caller_id_number或网关侧开启了主叫透传把注册账号名透传过去了。解决在呼出路由的 bridge 前设置主叫变量见 4.2 的 set 写法并让中继侧确认外显号码在白名单内。如果主叫号码被运营商强制替换那是中继策略问题FreeSWITCH 侧改多少遍都不会生效。可以做一个简单的自测用另一部手机打该中继的测试号码看来电显示是否是预期号码以此把问题边界切清楚。5.5 改完 XML 路由不生效没有 reloadxml或文件编码有问题现象XML 文件改了reloadxml也执行了但拨号行为还是老的。原因可能没有执行 reloadxmlFreeSWITCH 不会自动监听 dialplan 文件变化或语法错误导致整个 context 被拒绝加载也可能文件被存成了带 BOM 的 UTF-8。解决执行 reload 并检查是否有语法错误fs_cli -x reloadxml fs_cli -x dialplan show default如果dialplan show里看不到新加的 extension说明文件在解析阶段就被拒了。去conf/dialplan/下找到对应 XML用xmllint --noout检查并确认编辑器保存为 UTF-8 无 BOM。这个坑在 freeswitch安装win 的场景里尤其突出Windows 记事本另存为 UTF-8 时会塞 BOM 头FreeSWITCH 解析 XML 会失败肉眼却看不出区别。建议 Windows 下用 VSCode 或 Notepad 把编码切到 UTF-8无 BOM再保存。6. 不占线路验证路由的三种命令与日常操作习惯路由配完验证是最容易被偷工减料的环节。生产环境里不可能每次改路由都真拨一遍电话占住线路。我常用的验证方式是 originate 命令它可以在不占用分机的情况下从 FreeSWITCH 内部发起一个呼叫观察路由走向。fs_cli -x bgapi originate {origination_caller_id_number01012345678}sofia/gateway/gw-sip-trunk/13800000000 echo逻辑说明originate的格式是通道地址 应用这里把呼叫发往网关gw-sip-trunk号码 13800000000呼叫建立后执行echo应用回声测试。这个方式可以完整走一遍呼出路由的 bridge 流程又不会真的接通一个坐席。呼入侧的验证则可以用user来模拟fs_cli -x bgapi originate user/1000 echo(PING)能看到拨号计划是否能把呼叫定位到分机 1000。还有个更细的命令fs_cli -x dialplan route 86660000可以直接展示号码在拨号计划里的完整命中路径不用发起呼叫就能排查大半路由问题。参数说明bgapi表示后台异步执行不会卡住 fs_cliecho后的(PING)是传给应用的参数随便写一个字符串即可。验证期间建议在另一个终端挂fs_cli -x console loglevel debug看业务日志INFO 级别只能看到有没有 INVITE看不到路由内部的判断分支。我自己的操作习惯是改路由前先跑一遍dialplan route记录基线改完 reloadxml 再跑一遍对比涉及网关变更时先看sofia status再做一次 originate 闭环测试最后才敢让业务真打。这套顺序帮我挡掉了好几次生产事故也算是一点血泪经验换来的流程。路由配置这类东西没有太多玄学剩下的无非是格式、顺序、变量名以及把每一步验证动作做扎实。希望帮到你。本文还有配套的精品资源点击获取