简介本资源是一份面向VoIP通信工程师与FreeSWITCH初学者的实战配置指南聚焦呼入呼出路由核心场景系统解决SIP中继对接、对等模式外呼、内网呼叫分发等典型问题。内容涵盖FreeSWITCH V1.2.7架构解析、XML拨号计划编写逻辑、sip_profiles中继参数配置含IP/端口/传输协议/认证设置、安全加固与错误恢复策略等关键实践要点特别适合需快速部署企业级语音中继或调试网关互通的技术人员。资源为单文件DOC文档共17页大小221KB结构清晰含引言、组件架构、CORE启动流程、MOD_SOFIA模块详解及参考目录便于按模块查阅与实操对照。目前已有6451人学习下载提供从原理理解到配置落地的完整闭环是少有的兼顾协议基础、配置细节与排错提示的轻量级专项参考资料。1. Freeswitch呼入呼出路由配置详解不是写几行XML就完事而是要让每通呼入不丢、每路外呼可溯、每个中继不哑火你刚配好 FreeSWITCHsip_profiles 下的 external.xml 也 reload 了但呼入电话一来就 404 Not Found外呼拨出去直接 503 Service Unavailable或者更玄学的是——白天全链路正常凌晨三点突然所有外呼失败日志里只有一句sofia: sofia/external is down查防火墙、查网关、查 DNS 全都没问题。这不是玄学是路由逻辑没闭环。本文讲的不是“FreeSWITCH 怎么安装”而是聚焦在真实生产环境里最常翻车的呼入呼出路由环节从 SIP 中继怎么填才不被对端拒绝到 dialplan 里condition fielddestination_number expression^1[3-9]\d{9}$这种正则为什么在某些 profile 下根本匹配不到从bridge应用里sofia/gateway/myisp/13800138000的 gateway 名称必须和sip_profiles/external/myisp.xml文件名严格一致到originate命令里漏写ignore_early_mediatrue导致媒体流卡在 early 183 而无法建立通话。它适合正在调试 SIP 中继对接的某公司 VoIP 工程师、接手遗留 FreeSWITCH 系统的某高校实验室运维、或准备用 FreeSWITCH 搭建多租户呼叫中心的某跨平台系统开发者——你不需要从零造轮子但必须知道哪颗螺丝松了会整机停摆。2. 呼入路由落地SIP Profile 是入口守门员dialplan 是决策大脑二者错位一毫呼入即失FreeSWITCH 的呼入不是“电话打进来就自动进 dialplan”而是一条严格分段的流水线SIP 协议栈收包 → Profile 解析 From/To/Contact → Channel 创建 → Dialplan 匹配 context → 执行 application。任何一环断开呼入就静音。下面拆解真实可复现的配置链路全部基于 V1.2.7 源码结构与默认 conf 目录布局非 Docker 镜像路径。2.1 SIP Profile 配置external.xml 不是模板是你的对外身份证呼入流量首先进入conf/sip_profiles/external.xml。很多人直接复制官网示例却忽略三个致命字段param namertp-ip value$${local_ip_v4}/、param namesip-ip value$${local_ip_v4}/和param nameext-rtp-ip valueauto-nat/。它们不是可选项而是决定呼入能否穿透 NAT 的关键。!-- conf/sip_profiles/external.xml -- configuration namesip_profile descriptionExternal SIP Profile settings param namertp-ip value192.168.1.100/ param namesip-ip value192.168.1.100/ param nameext-rtp-ip value203.0.113.45/ param nameext-sip-ip value203.0.113.45/ param namertp-port-range value16384-20000/ param nameinbound-codec-prefs valuePCMU,PCMA,G722,OPUS/ /settings gateways !-- 此处不填gateway呼入走profile直连非中继模式 -- /gateways /configuration参数说明rtp-ip/sip-ip必须填 FreeSWITCH 所在服务器的内网真实 IP如192.168.1.100不能写auto或0.0.0.0否则 Sofia 栈无法绑定端口ext-rtp-ip/ext-sip-ip必须填你暴露给公网的NAT 映射 IP如云服务器的弹性公网 IP203.0.113.45这是告诉远端设备“我的媒体和信令实际从这个 IP 来”rtp-port-range务必避开系统保留端口1024和常用服务端口如 5060、8080实测16384-20000是安全区间inbound-codec-prefs顺序即优先级PCMUG.711u放首位避免因编解码协商失败导致 488 Not Acceptable Here。配置完必须执行fs_cli -x sofia status profile external重点核对三行Status: UP RTP IP: 192.168.1.100 Ext RTP IP: 203.0.113.45若Status为DOWN90% 是rtp-ip或sip-ip填错若Ext RTP IP显示auto-nat说明未生效需检查变量$${local_ip_v4}是否在vars.xml中正确定义。2.2 Dialplan Context 绑定profile 和 context 必须双向认证单向匹配等于白配Profile 收到 SIP INVITE 后会根据To头中的 SIP URI 提取 domain再匹配dialplan中context name...的name属性。这不是模糊匹配而是精确字符串比对。例如!-- conf/dialplan/default.xml -- context namepublic extension namehandle_inbound condition fielddestination_number expression^1[3-9]\d{9}$ action applicationlog dataINFO Incoming call to ${destination_number}/ action applicationbridge datauser/1001${domain_name}/ /condition /extension /context此处context namepublic必须与external.xml中的param namecontext valuepublic/完全一致。若external.xml里写的是param namecontext valuedefault/而 dialplan 只有publiccontext则所有呼入直接返回404 Not Found且日志中不会报错只会静默丢弃。验证方法在fs_cli中执行sofia status profile external找到Context:字段确认其值与 dialplan 文件中context namexxx的xxx严格相等。常见错误是external.xml里写default而default.xml里 context 名却是public——这种错位在 reloadxml 后毫无提示只能靠人工核对。2.3 呼入号码标准化别信 From 头用 regex 重写 destination_number 才可靠运营商或中继网关发来的呼入 INVITETo头里的destination_number可能带国家码8613800138000、分机号1001;ext101、甚至非法字符138-0013-8000。FreeSWITCH 默认不做清洗直接拿原始字符串去 dialplan 匹配必然失败。正确做法是在 dialplan 最顶层加一个预处理 extension用setregex统一规整!-- conf/dialplan/public.xml -- context namepublic !-- 预处理清洗 destination_number -- extension namenormalize_number condition fielddestination_number expression^(\86|86|0086)(1[3-9]\d{9})$ action applicationset datadialed_extension$2/ /condition condition fielddestination_number expression^(1[3-9]\d{9})$ action applicationset datadialed_extension$1/ /condition condition fielddestination_number expression^([0-9]{3,4})$ action applicationset datadialed_extension$1/ /condition condition fielddestination_number expression^.*$ action applicationlog dataWARNING Invalid number format: ${destination_number}/ action applicationhangup dataUNALLOCATED_NUMBER/ /condition /extension !-- 主路由逻辑用清洗后的 dialed_extension -- extension nameroute_to_user condition fielddialed_extension expression^1[3-9]\d{9}$ action applicationbridge datauser/${dialed_extension}${domain_name}/ /condition /extension /context逻辑说明第一个 condition 匹配带86/86/0086前缀的 11 位手机号提取$2纯数字赋给dialed_extension第二个 condition 匹配无前缀的 11 位号直接赋值第三个 condition 匹配短号如1001保留原样最后一个兜底 condition对所有未匹配项记录警告并挂断避免误入其他 extension后续所有路由逻辑都基于dialed_extension而非原始destination_number彻底规避格式干扰。3. 外呼路由落地Gateway 是信用背书originate 是执行指令参数错一位外呼即中断外呼不是 dialplan 里写个bridge sofia/gateway/myisp/13800138000就能跑通。它依赖三层强耦合gateway 配置必须与中继服务商要求完全一致 → originate 命令必须携带必要参数 → dialplan 中的 bridge 必须指向正确 gateway 名称。缺一不可。3.1 SIP Gateway 配置myisp.xml 不是名字是与中继商签的电子合同conf/sip_profiles/external/myisp.xml是 FreeSWITCH 对接 SIP 中继商的契约文件。它必须包含中继商要求的全部认证、编码、超时参数。以国内某主流 SIP 中继为例非真实厂商典型配置如下!-- conf/sip_profiles/external/myisp.xml -- include gateway namemyisp param nameusername valueFS20231001/ param namepassword valueaBcDeFgHiJkLmNoPqRsTuVwXyZ/ param namerealm valuesip.myisp.com/ param namefrom-user valueFS20231001/ param namefrom-domain valuesip.myisp.com/ param nameproxy valuesip.myisp.com:5060/ param nameregister valuetrue/ param nameregister-transport valueudp/ param nameexpire-seconds value3600/ param nameretry-seconds value30/ param nameping value30/ param namecaller-id-in-from valuetrue/ param nameextension valueFS20231001/ param namecontext valuepublic/ param namedtmf-type valuerfc2833/ param nameinbound-codec-prefs valuePCMU,PCMA,G722/ param nameoutbound-codec-prefs valuePCMU,PCMA,G722/ /gateway /include参数说明username/password/realm必须与中继商后台分配的账户逐字一致大小写敏感proxy必须填中继商提供的 SIP 代理地址如sip.myisp.com:5060不能写成120.192.100.50:5060除非明确要求 IP 直连register必须为trueFreeSWITCH 需主动向中继商注册否则中继商不认你为合法 clientregister-transport必须与中继商支持的协议一致UDP 是默认若对方强制 TCP 则必须改tcpoutbound-codec-prefs外呼时优先使用的编解码必须包含中继商支持的列表否则协商失败返回488context此 gateway 发起的外呼将进入该 context 的 dialplan必须与conf/dialplan/public.xml中的context namepublic对应。配置后执行fs_cli -x sofia status gateway myisp关键字段必须为State: REGED Expires: 3599 Ping: 30若State为FAIL或UNREG立即检查username/password/proxy三要素若Expires为0说明注册被拒大概率是realm或from-domain填错。3.2 Originate 命令与 Bridge 应用外呼不是“拨号”是构造完整 SIP 事务外呼触发有两种方式CLI 手动originate或 dialplan 中bridge。无论哪种都必须显式指定sofia/gateway/myisp/13800138000其中myisp必须与myisp.xml的gateway namemyisp完全一致包括大小写、下划线。CLI 外呼调试用# fs_cli 中执行 originate {origination_caller_id_number13800138000,origination_caller_id_nameFS-Test}sofia/gateway/myisp/13800138000 echo(hello world)参数说明{...}内是 channel variablesorigination_caller_id_number设定主叫号码必须是中继商允许的号码如你购买的 DID 号sofia/gateway/myisp/13800138000是核心路由串sofia协议栈→gateway类型→myispgateway 名→13800138000被叫echo(hello world)是外呼成功后执行的应用此处为播放语音若省略{...}主叫 ID 将为空中继商可能直接拒接。Dialplan 外呼生产用!-- conf/dialplan/public.xml -- context namepublic extension nameoutbound_call condition fielddestination_number expression^0\d{10,12}$ !-- 国内固话加 0 前缀 -- action applicationset dataoutbound_number${destination_number:1}/ action applicationbridge datasofia/gateway/myisp/${outbound_number}/ /condition condition fielddestination_number expression^1[3-9]\d{9}$ !-- 国内手机 -- action applicationbridge datasofia/gateway/myisp/${destination_number}/ /condition /extension /context关键点bridge的 data 字段必须是sofia/gateway/{gateway_name}/{number}格式{gateway_name}不能拼错若中继商要求主叫号码必须为 DID 号需在bridge前用set设置origination_caller_id_number否则外呼失败bridge后不加ignore_early_mediatrue当对方返回 183 Session Progress 时FreeSWITCH 会等待媒体流若对方不发 early media 则超时挂断现象外呼拨通但无声。3.3 外呼失败排障看 sip_trace别猜日志外呼失败时freeswitch.log里往往只有Channel [sofia/external/...] hanging up毫无价值。真正线索在 SIP 信令流# 在 fs_cli 中开启信令跟踪 sofia global siptrace on # 然后发起一次外呼 originate sofia/gateway/myisp/13800138000 echo(test) # 查看实时信令 sofia global siptrace off # 日志会输出完整 INVITE/407/ACK 流程重点关注INVITE 中的Via、From、To、Contact头是否符合中继商要求是否收到407 Proxy Authentication Required若有说明username/password错是否收到403 Forbidden检查realm和from-domain是否收到486 Busy Here说明 gateway 注册成功但中继商侧线路忙是否 INVITE 发出后无任何响应检查proxy地址和防火墙 UDP 5060 端口。4. 呼入呼出联动Dialplan 是胶水变量传递是命脉漏传一个变量整条链路断裂呼入转外呼如 IVR 后转坐席、外呼回呼如短信通知后用户回拨等场景本质是channel variables 在不同 context 间的安全传递。FreeSWITCH 默认不透传变量必须显式声明。4.1 呼入转外呼从 public context 到 outbound context 的变量桥接典型场景呼入 IVR 播报后用户按 1 转接外线坐席如 400 电话。此时需将呼入的caller_id_number作为外呼主叫!-- conf/dialplan/public.xml -- context namepublic extension nameivr_transfer condition fielddestination_number expression^9999$ !-- IVR 入口号 -- action applicationivr datamain_ivr/ /condition /extension !-- IVR 转外呼分支 -- extension nametransfer_to_outbound condition field${ivr_result} expression^1$ !-- 用户按 1 -- action applicationset dataoutbound_target4008001234/ action applicationset dataorigination_caller_id_number${caller_id_number}/ action applicationset dataorigination_caller_id_name${caller_id_name}/ action applicationtransfer dataoutbound_call XML public/ /condition /extension /context !-- conf/dialplan/outbound.xml -- context nameoutbound extension namemake_outbound condition fielddestination_number expression^400\d{3}\d{4}$ action applicationlog dataINFO Outbound to ${destination_number} from ${origination_caller_id_number}/ action applicationbridge datasofia/gateway/myisp/${destination_number}/ /condition /extension /context变量传递逻辑transfer应用将当前 channel 切换到outboundcontext同时继承所有已设置的 variablesorigination_caller_id_number和origination_caller_id_name是 FreeSWITCH 内置变量bridge会自动将其映射为 SIPFrom头若未显式set则外呼主叫为空中继商拒接transfer后必须跟XML public表示 dialplan 文件名和 context 名缺一不可。4.2 外呼回呼用 uuid 生成唯一回拨键避免并发冲突外呼通知后用户回拨需关联原始外呼 session。不能用caller_id_number多个用户同号必须用 FreeSWITCH 分配的uuid!-- 外呼发起时记录 uuid -- action applicationset datacallback_uuid${uuid}/ action applicationset datacallback_number${caller_id_number}/ action applicationlog dataINFO Callback UUID: ${callback_uuid} for ${callback_number}/ !-- 将 callback_uuid 编码为 DTMF 可播号码如 1234567890ABCD -- action applicationset datadtmf_code${uuid:0:4}${uuid:24:4}${uuid:8:4}/ action applicationplayback dataivr/please_dial.wav/ action applicationplayback dataivr/callback_code.wav/ action applicationsay data${dtmf_code}/用户回拨时IVR 采集 DTMF再通过hash或数据库反查uuid最后用uuid_broadcast触发事件唤醒原始 session!-- 回拨匹配逻辑 -- condition field${dtmf_input} expression^([0-9A-F]{12})$ action applicationset datatarget_uuid${odbc(select uuid from callbacks where dtmf_code${dtmf_input} limit 1)}/ action applicationuuid_broadcast data${target_uuid} playback::voicemail/vm-thankyou.wav/ /condition关键设计uuid全局唯一128 位截取 12 位足够区分uuid:0:4取前 4 位uuid:24:4取第 24 位起 4 位uuid:8:4取第 8 位起 4 位odbc查询必须用limit 1防止多条记录导致uuid_broadcast广播到错误 sessionuuid_broadcast是 FreeSWITCH 内置应用无需额外模块直接向指定 uuid channel 发送事件。5. 避坑指南FreeSWITCH 呼入呼出路由的五个血泪现场现象、原因、解法全列清FreeSWITCH 的坑不在代码在配置的隐式依赖。以下五条是某公司线上系统连续三次凌晨告警后总结的硬核避坑清单每一条都对应真实故障时间点与恢复操作。5.1 现象呼入电话响三声后自动挂断fs_cli 中sofia status profile external显示UP但无任何 error 日志原因external.xml中param nameinbound-codec-prefs value.../未包含中继网关实际发送的编解码如对方发 G.729你只配了 PCMU/PCMA。FreeSWITCH 收到 SDP 后发现无可协商 codec静默 hangup。解决开启sofia global siptrace on抓取呼入 INVITE 的 SDP查看maudio行的artpmap确认对方支持的 codec如18 G729/8000将G729加入inbound-codec-prefs并确保 FreeSWITCH 已加载mod_g729需商业授权reloadxml后测试。5.2 现象外呼始终返回503 Service Unavailablesofia status gateway myisp显示REGED但INVITE发不出原因myisp.xml中param nameproxy value.../填的是域名但服务器/etc/hosts或 DNS 未解析该域名或resolv.conf配置错误导致域名解析超时默认 5 秒Sofia 栈放弃重试。解决在 FreeSWITCH 服务器执行nslookup sip.myisp.com确认解析正常若解析慢改用 IP 地址param nameproxy value203.0.113.45:5060/或在vars.xml中增加X-PRE-PROCESS cmdset datadns_timeout2/缩短 DNS 超时sofia restart重载 profile。5.3 现象呼入号码匹配 dialplan 正则但bridge user/1001${domain_name}失败日志报Cant find user 1001原因user/1001${domain_name}中的domain_name变量为空因为external.xml未配置param namedomain valueyourdomain.com/FreeSWITCH 默认 domain 为localhost而directory中用户存在1001yourdomain.com。解决在external.xmlsettings中添加param namedomain valueyourdomain.com/确保conf/directory/default/1001.xml中domain nameyourdomain.com与之匹配reloadxml后执行sofia status profile external确认Domain:字段为yourdomain.com。5.4 现象外呼成功接通但通话中一方听不到声音单通sofia status显示 RTP 流量为 0原因external.xml中param namertp-ip value.../填的是内网 IP如192.168.1.100但中继商位于公网尝试向该内网 IP 发 RTP 包自然失败。解决rtp-ip必须填服务器对外可见的公网 IP如云服务器弹性 IP若服务器在 NAT 后如家庭宽带必须配置ext-rtp-ip为公网 IP并在路由器做 16384-20000 端口映射执行tcpdump -i any portrange 16384-20000 -w rtp.pcap抓包确认 RTP 包是否进出。5.5 现象transfer到另一个 context 后origination_caller_id_number变为空外呼主叫丢失原因transfer应用默认不继承所有 variables仅继承部分内置变量origination_caller_id_number需显式export才能透传。解决在 transfer 前添加action applicationexport datanolocal:origination_caller_id_number${origination_caller_id_number}/export的nolocal:前缀表示该变量将随 channel 一起迁移在目标 context 中用${origination_caller_id_number}即可取到值验证在目标 extension 中加action applicationlog dataDEBUG CID: ${origination_caller_id_number}/。6. 进阶技巧用 Lua 脚本动态路由把硬编码 dialplan 变成可热更新的策略引擎FreeSWITCH 的 XML dialplan 适合静态规则但面对“工作日 9-18 点走 A 中继其余时间走 B 中继”“VIP 用户优先用高码率编解码”等动态策略XML 就力不从心。此时Lua 脚本是最佳解法——它在 FreeSWITCH 进程内运行毫秒级响应且无需重启服务。6.1 准备工作启用 mod_lua 并验证脚本权限首先确认conf/autoload_configs/modules.conf中已启用load modulemod_lua/然后reloadxml在fs_cli中执行luarun print(Hello from Lua!)若返回Hello from Lua!说明 mod_lua 加载成功。6.2 动态外呼路由脚本根据时间、号码、用户等级选择 gateway创建scripts/route_outbound.lua-- scripts/route_outbound.lua local function get_gateway_by_time() local hour os.date(*t).hour if hour 9 and hour 18 then return myisp_premium else return myisp_basic end end local function get_gateway_by_number(number) if string.match(number, ^1[3-9]%d{9}$) then return myisp_mobile elseif string.match(number, ^0%d{2,3}%d{7,8}$) then return myisp_landline else return myisp_default end end -- 主路由函数 function route_outbound(session, args) local number session:getVariable(destination_number) local user_level session:getVariable(user_level) or standard local gateway myisp_default -- VIP 用户强制走 premium if user_level vip then gateway myisp_premium else -- 按时间路由 gateway get_gateway_by_time() -- 按号码类型微调 if string.len(number) 11 then gateway get_gateway_by_number(number) end end -- 设置外呼参数 session:setVariable(origination_caller_id_number, session:getVariable(caller_id_number)) session:setVariable(effective_caller_id_number, session:getVariable(caller_id_number)) -- 执行 bridge session:execute(bridge, sofia/gateway/ .. gateway .. / .. number) end6.3 在 dialplan 中调用 Lua 脚本!-- conf/dialplan/public.xml -- context namepublic extension namedynamic_outbound condition fielddestination_number expression^[\0-9]$ action applicationlua dataroute_outbound.lua route_outbound/ /condition /extension /context执行逻辑lua应用加载route_outbound.lua并调用其中的route_outbound函数session对象可读取/设置任意 channel variable如caller_id_number、user_levelsession:execute(bridge, ...)等效于 dialplan 中的action applicationbridge .../脚本修改变量后后续 dialplan 步骤仍可使用如log记录选中的 gateway。6.4 热更新技巧用 inotifywait 监控脚本变更自动 reloadLua 脚本修改后无需重启 FreeSWITCH但需通知其重新加载。用 Linuxinotifywait实现# 安装 inotify-tools apt-get install inotify-tools # 创建监控脚本 reload_lua.sh #!/bin/bash while inotifywait -e modify /usr/local/freeswitch/scripts/route_outbound.lua; do echo $(date): Reloading Lua script echo luarun package.reload(route_outbound) | nc localhost 8021 done原理FreeSWITCH 的 Event Socket端口 8021支持luarun命令package.reload强制重载 Lua 模块实现秒级热更新。从那以后我每次上线新路由策略都先跑一遍inotifywait监控再改脚本——再也不用reloadxml后祈祷所有 channel 没断。希望帮到你。本文还有配套的精品资源点击获取
简介本资源是一份面向VoIP通信工程师与FreeSWITCH初学者的实战配置指南聚焦呼入呼出路由核心场景系统解决SIP中继对接、对等模式外呼、内网呼叫分发等典型问题。内容涵盖FreeSWITCH V1.2.7架构解析、XML拨号计划编写逻辑、sip_profiles中继参数配置含IP/端口/传输协议/认证设置、安全加固与错误恢复策略等关键实践要点特别适合需快速部署企业级语音中继或调试网关互通的技术人员。资源为单文件DOC文档共17页大小221KB结构清晰含引言、组件架构、CORE启动流程、MOD_SOFIA模块详解及参考目录便于按模块查阅与实操对照。目前已有6451人学习下载提供从原理理解到配置落地的完整闭环是少有的兼顾协议基础、配置细节与排错提示的轻量级专项参考资料。1. Freeswitch呼入呼出路由配置详解不是写几行XML就完事而是要让每通呼入不丢、每路外呼可溯、每个中继不哑火你刚配好 FreeSWITCHsip_profiles 下的 external.xml 也 reload 了但呼入电话一来就 404 Not Found外呼拨出去直接 503 Service Unavailable或者更玄学的是——白天全链路正常凌晨三点突然所有外呼失败日志里只有一句sofia: sofia/external is down查防火墙、查网关、查 DNS 全都没问题。这不是玄学是路由逻辑没闭环。本文讲的不是“FreeSWITCH 怎么安装”而是聚焦在真实生产环境里最常翻车的呼入呼出路由环节从 SIP 中继怎么填才不被对端拒绝到 dialplan 里condition fielddestination_number expression^1[3-9]\d{9}$这种正则为什么在某些 profile 下根本匹配不到从bridge应用里sofia/gateway/myisp/13800138000的 gateway 名称必须和sip_profiles/external/myisp.xml文件名严格一致到originate命令里漏写ignore_early_mediatrue导致媒体流卡在 early 183 而无法建立通话。它适合正在调试 SIP 中继对接的某公司 VoIP 工程师、接手遗留 FreeSWITCH 系统的某高校实验室运维、或准备用 FreeSWITCH 搭建多租户呼叫中心的某跨平台系统开发者——你不需要从零造轮子但必须知道哪颗螺丝松了会整机停摆。2. 呼入路由落地SIP Profile 是入口守门员dialplan 是决策大脑二者错位一毫呼入即失FreeSWITCH 的呼入不是“电话打进来就自动进 dialplan”而是一条严格分段的流水线SIP 协议栈收包 → Profile 解析 From/To/Contact → Channel 创建 → Dialplan 匹配 context → 执行 application。任何一环断开呼入就静音。下面拆解真实可复现的配置链路全部基于 V1.2.7 源码结构与默认 conf 目录布局非 Docker 镜像路径。2.1 SIP Profile 配置external.xml 不是模板是你的对外身份证呼入流量首先进入conf/sip_profiles/external.xml。很多人直接复制官网示例却忽略三个致命字段param namertp-ip value$${local_ip_v4}/、param namesip-ip value$${local_ip_v4}/和param nameext-rtp-ip valueauto-nat/。它们不是可选项而是决定呼入能否穿透 NAT 的关键。!-- conf/sip_profiles/external.xml -- configuration namesip_profile descriptionExternal SIP Profile settings param namertp-ip value192.168.1.100/ param namesip-ip value192.168.1.100/ param nameext-rtp-ip value203.0.113.45/ param nameext-sip-ip value203.0.113.45/ param namertp-port-range value16384-20000/ param nameinbound-codec-prefs valuePCMU,PCMA,G722,OPUS/ /settings gateways !-- 此处不填gateway呼入走profile直连非中继模式 -- /gateways /configuration参数说明rtp-ip/sip-ip必须填 FreeSWITCH 所在服务器的内网真实 IP如192.168.1.100不能写auto或0.0.0.0否则 Sofia 栈无法绑定端口ext-rtp-ip/ext-sip-ip必须填你暴露给公网的NAT 映射 IP如云服务器的弹性公网 IP203.0.113.45这是告诉远端设备“我的媒体和信令实际从这个 IP 来”rtp-port-range务必避开系统保留端口1024和常用服务端口如 5060、8080实测16384-20000是安全区间inbound-codec-prefs顺序即优先级PCMUG.711u放首位避免因编解码协商失败导致 488 Not Acceptable Here。配置完必须执行fs_cli -x sofia status profile external重点核对三行Status: UP RTP IP: 192.168.1.100 Ext RTP IP: 203.0.113.45若Status为DOWN90% 是rtp-ip或sip-ip填错若Ext RTP IP显示auto-nat说明未生效需检查变量$${local_ip_v4}是否在vars.xml中正确定义。2.2 Dialplan Context 绑定profile 和 context 必须双向认证单向匹配等于白配Profile 收到 SIP INVITE 后会根据To头中的 SIP URI 提取 domain再匹配dialplan中context name...的name属性。这不是模糊匹配而是精确字符串比对。例如!-- conf/dialplan/default.xml -- context namepublic extension namehandle_inbound condition fielddestination_number expression^1[3-9]\d{9}$ action applicationlog dataINFO Incoming call to ${destination_number}/ action applicationbridge datauser/1001${domain_name}/ /condition /extension /context此处context namepublic必须与external.xml中的param namecontext valuepublic/完全一致。若external.xml里写的是param namecontext valuedefault/而 dialplan 只有publiccontext则所有呼入直接返回404 Not Found且日志中不会报错只会静默丢弃。验证方法在fs_cli中执行sofia status profile external找到Context:字段确认其值与 dialplan 文件中context namexxx的xxx严格相等。常见错误是external.xml里写default而default.xml里 context 名却是public——这种错位在 reloadxml 后毫无提示只能靠人工核对。2.3 呼入号码标准化别信 From 头用 regex 重写 destination_number 才可靠运营商或中继网关发来的呼入 INVITETo头里的destination_number可能带国家码8613800138000、分机号1001;ext101、甚至非法字符138-0013-8000。FreeSWITCH 默认不做清洗直接拿原始字符串去 dialplan 匹配必然失败。正确做法是在 dialplan 最顶层加一个预处理 extension用setregex统一规整!-- conf/dialplan/public.xml -- context namepublic !-- 预处理清洗 destination_number -- extension namenormalize_number condition fielddestination_number expression^(\86|86|0086)(1[3-9]\d{9})$ action applicationset datadialed_extension$2/ /condition condition fielddestination_number expression^(1[3-9]\d{9})$ action applicationset datadialed_extension$1/ /condition condition fielddestination_number expression^([0-9]{3,4})$ action applicationset datadialed_extension$1/ /condition condition fielddestination_number expression^.*$ action applicationlog dataWARNING Invalid number format: ${destination_number}/ action applicationhangup dataUNALLOCATED_NUMBER/ /condition /extension !-- 主路由逻辑用清洗后的 dialed_extension -- extension nameroute_to_user condition fielddialed_extension expression^1[3-9]\d{9}$ action applicationbridge datauser/${dialed_extension}${domain_name}/ /condition /extension /context逻辑说明第一个 condition 匹配带86/86/0086前缀的 11 位手机号提取$2纯数字赋给dialed_extension第二个 condition 匹配无前缀的 11 位号直接赋值第三个 condition 匹配短号如1001保留原样最后一个兜底 condition对所有未匹配项记录警告并挂断避免误入其他 extension后续所有路由逻辑都基于dialed_extension而非原始destination_number彻底规避格式干扰。3. 外呼路由落地Gateway 是信用背书originate 是执行指令参数错一位外呼即中断外呼不是 dialplan 里写个bridge sofia/gateway/myisp/13800138000就能跑通。它依赖三层强耦合gateway 配置必须与中继服务商要求完全一致 → originate 命令必须携带必要参数 → dialplan 中的 bridge 必须指向正确 gateway 名称。缺一不可。3.1 SIP Gateway 配置myisp.xml 不是名字是与中继商签的电子合同conf/sip_profiles/external/myisp.xml是 FreeSWITCH 对接 SIP 中继商的契约文件。它必须包含中继商要求的全部认证、编码、超时参数。以国内某主流 SIP 中继为例非真实厂商典型配置如下!-- conf/sip_profiles/external/myisp.xml -- include gateway namemyisp param nameusername valueFS20231001/ param namepassword valueaBcDeFgHiJkLmNoPqRsTuVwXyZ/ param namerealm valuesip.myisp.com/ param namefrom-user valueFS20231001/ param namefrom-domain valuesip.myisp.com/ param nameproxy valuesip.myisp.com:5060/ param nameregister valuetrue/ param nameregister-transport valueudp/ param nameexpire-seconds value3600/ param nameretry-seconds value30/ param nameping value30/ param namecaller-id-in-from valuetrue/ param nameextension valueFS20231001/ param namecontext valuepublic/ param namedtmf-type valuerfc2833/ param nameinbound-codec-prefs valuePCMU,PCMA,G722/ param nameoutbound-codec-prefs valuePCMU,PCMA,G722/ /gateway /include参数说明username/password/realm必须与中继商后台分配的账户逐字一致大小写敏感proxy必须填中继商提供的 SIP 代理地址如sip.myisp.com:5060不能写成120.192.100.50:5060除非明确要求 IP 直连register必须为trueFreeSWITCH 需主动向中继商注册否则中继商不认你为合法 clientregister-transport必须与中继商支持的协议一致UDP 是默认若对方强制 TCP 则必须改tcpoutbound-codec-prefs外呼时优先使用的编解码必须包含中继商支持的列表否则协商失败返回488context此 gateway 发起的外呼将进入该 context 的 dialplan必须与conf/dialplan/public.xml中的context namepublic对应。配置后执行fs_cli -x sofia status gateway myisp关键字段必须为State: REGED Expires: 3599 Ping: 30若State为FAIL或UNREG立即检查username/password/proxy三要素若Expires为0说明注册被拒大概率是realm或from-domain填错。3.2 Originate 命令与 Bridge 应用外呼不是“拨号”是构造完整 SIP 事务外呼触发有两种方式CLI 手动originate或 dialplan 中bridge。无论哪种都必须显式指定sofia/gateway/myisp/13800138000其中myisp必须与myisp.xml的gateway namemyisp完全一致包括大小写、下划线。CLI 外呼调试用# fs_cli 中执行 originate {origination_caller_id_number13800138000,origination_caller_id_nameFS-Test}sofia/gateway/myisp/13800138000 echo(hello world)参数说明{...}内是 channel variablesorigination_caller_id_number设定主叫号码必须是中继商允许的号码如你购买的 DID 号sofia/gateway/myisp/13800138000是核心路由串sofia协议栈→gateway类型→myispgateway 名→13800138000被叫echo(hello world)是外呼成功后执行的应用此处为播放语音若省略{...}主叫 ID 将为空中继商可能直接拒接。Dialplan 外呼生产用!-- conf/dialplan/public.xml -- context namepublic extension nameoutbound_call condition fielddestination_number expression^0\d{10,12}$ !-- 国内固话加 0 前缀 -- action applicationset dataoutbound_number${destination_number:1}/ action applicationbridge datasofia/gateway/myisp/${outbound_number}/ /condition condition fielddestination_number expression^1[3-9]\d{9}$ !-- 国内手机 -- action applicationbridge datasofia/gateway/myisp/${destination_number}/ /condition /extension /context关键点bridge的 data 字段必须是sofia/gateway/{gateway_name}/{number}格式{gateway_name}不能拼错若中继商要求主叫号码必须为 DID 号需在bridge前用set设置origination_caller_id_number否则外呼失败bridge后不加ignore_early_mediatrue当对方返回 183 Session Progress 时FreeSWITCH 会等待媒体流若对方不发 early media 则超时挂断现象外呼拨通但无声。3.3 外呼失败排障看 sip_trace别猜日志外呼失败时freeswitch.log里往往只有Channel [sofia/external/...] hanging up毫无价值。真正线索在 SIP 信令流# 在 fs_cli 中开启信令跟踪 sofia global siptrace on # 然后发起一次外呼 originate sofia/gateway/myisp/13800138000 echo(test) # 查看实时信令 sofia global siptrace off # 日志会输出完整 INVITE/407/ACK 流程重点关注INVITE 中的Via、From、To、Contact头是否符合中继商要求是否收到407 Proxy Authentication Required若有说明username/password错是否收到403 Forbidden检查realm和from-domain是否收到486 Busy Here说明 gateway 注册成功但中继商侧线路忙是否 INVITE 发出后无任何响应检查proxy地址和防火墙 UDP 5060 端口。4. 呼入呼出联动Dialplan 是胶水变量传递是命脉漏传一个变量整条链路断裂呼入转外呼如 IVR 后转坐席、外呼回呼如短信通知后用户回拨等场景本质是channel variables 在不同 context 间的安全传递。FreeSWITCH 默认不透传变量必须显式声明。4.1 呼入转外呼从 public context 到 outbound context 的变量桥接典型场景呼入 IVR 播报后用户按 1 转接外线坐席如 400 电话。此时需将呼入的caller_id_number作为外呼主叫!-- conf/dialplan/public.xml -- context namepublic extension nameivr_transfer condition fielddestination_number expression^9999$ !-- IVR 入口号 -- action applicationivr datamain_ivr/ /condition /extension !-- IVR 转外呼分支 -- extension nametransfer_to_outbound condition field${ivr_result} expression^1$ !-- 用户按 1 -- action applicationset dataoutbound_target4008001234/ action applicationset dataorigination_caller_id_number${caller_id_number}/ action applicationset dataorigination_caller_id_name${caller_id_name}/ action applicationtransfer dataoutbound_call XML public/ /condition /extension /context !-- conf/dialplan/outbound.xml -- context nameoutbound extension namemake_outbound condition fielddestination_number expression^400\d{3}\d{4}$ action applicationlog dataINFO Outbound to ${destination_number} from ${origination_caller_id_number}/ action applicationbridge datasofia/gateway/myisp/${destination_number}/ /condition /extension /context变量传递逻辑transfer应用将当前 channel 切换到outboundcontext同时继承所有已设置的 variablesorigination_caller_id_number和origination_caller_id_name是 FreeSWITCH 内置变量bridge会自动将其映射为 SIPFrom头若未显式set则外呼主叫为空中继商拒接transfer后必须跟XML public表示 dialplan 文件名和 context 名缺一不可。4.2 外呼回呼用 uuid 生成唯一回拨键避免并发冲突外呼通知后用户回拨需关联原始外呼 session。不能用caller_id_number多个用户同号必须用 FreeSWITCH 分配的uuid!-- 外呼发起时记录 uuid -- action applicationset datacallback_uuid${uuid}/ action applicationset datacallback_number${caller_id_number}/ action applicationlog dataINFO Callback UUID: ${callback_uuid} for ${callback_number}/ !-- 将 callback_uuid 编码为 DTMF 可播号码如 1234567890ABCD -- action applicationset datadtmf_code${uuid:0:4}${uuid:24:4}${uuid:8:4}/ action applicationplayback dataivr/please_dial.wav/ action applicationplayback dataivr/callback_code.wav/ action applicationsay data${dtmf_code}/用户回拨时IVR 采集 DTMF再通过hash或数据库反查uuid最后用uuid_broadcast触发事件唤醒原始 session!-- 回拨匹配逻辑 -- condition field${dtmf_input} expression^([0-9A-F]{12})$ action applicationset datatarget_uuid${odbc(select uuid from callbacks where dtmf_code${dtmf_input} limit 1)}/ action applicationuuid_broadcast data${target_uuid} playback::voicemail/vm-thankyou.wav/ /condition关键设计uuid全局唯一128 位截取 12 位足够区分uuid:0:4取前 4 位uuid:24:4取第 24 位起 4 位uuid:8:4取第 8 位起 4 位odbc查询必须用limit 1防止多条记录导致uuid_broadcast广播到错误 sessionuuid_broadcast是 FreeSWITCH 内置应用无需额外模块直接向指定 uuid channel 发送事件。5. 避坑指南FreeSWITCH 呼入呼出路由的五个血泪现场现象、原因、解法全列清FreeSWITCH 的坑不在代码在配置的隐式依赖。以下五条是某公司线上系统连续三次凌晨告警后总结的硬核避坑清单每一条都对应真实故障时间点与恢复操作。5.1 现象呼入电话响三声后自动挂断fs_cli 中sofia status profile external显示UP但无任何 error 日志原因external.xml中param nameinbound-codec-prefs value.../未包含中继网关实际发送的编解码如对方发 G.729你只配了 PCMU/PCMA。FreeSWITCH 收到 SDP 后发现无可协商 codec静默 hangup。解决开启sofia global siptrace on抓取呼入 INVITE 的 SDP查看maudio行的artpmap确认对方支持的 codec如18 G729/8000将G729加入inbound-codec-prefs并确保 FreeSWITCH 已加载mod_g729需商业授权reloadxml后测试。5.2 现象外呼始终返回503 Service Unavailablesofia status gateway myisp显示REGED但INVITE发不出原因myisp.xml中param nameproxy value.../填的是域名但服务器/etc/hosts或 DNS 未解析该域名或resolv.conf配置错误导致域名解析超时默认 5 秒Sofia 栈放弃重试。解决在 FreeSWITCH 服务器执行nslookup sip.myisp.com确认解析正常若解析慢改用 IP 地址param nameproxy value203.0.113.45:5060/或在vars.xml中增加X-PRE-PROCESS cmdset datadns_timeout2/缩短 DNS 超时sofia restart重载 profile。5.3 现象呼入号码匹配 dialplan 正则但bridge user/1001${domain_name}失败日志报Cant find user 1001原因user/1001${domain_name}中的domain_name变量为空因为external.xml未配置param namedomain valueyourdomain.com/FreeSWITCH 默认 domain 为localhost而directory中用户存在1001yourdomain.com。解决在external.xmlsettings中添加param namedomain valueyourdomain.com/确保conf/directory/default/1001.xml中domain nameyourdomain.com与之匹配reloadxml后执行sofia status profile external确认Domain:字段为yourdomain.com。5.4 现象外呼成功接通但通话中一方听不到声音单通sofia status显示 RTP 流量为 0原因external.xml中param namertp-ip value.../填的是内网 IP如192.168.1.100但中继商位于公网尝试向该内网 IP 发 RTP 包自然失败。解决rtp-ip必须填服务器对外可见的公网 IP如云服务器弹性 IP若服务器在 NAT 后如家庭宽带必须配置ext-rtp-ip为公网 IP并在路由器做 16384-20000 端口映射执行tcpdump -i any portrange 16384-20000 -w rtp.pcap抓包确认 RTP 包是否进出。5.5 现象transfer到另一个 context 后origination_caller_id_number变为空外呼主叫丢失原因transfer应用默认不继承所有 variables仅继承部分内置变量origination_caller_id_number需显式export才能透传。解决在 transfer 前添加action applicationexport datanolocal:origination_caller_id_number${origination_caller_id_number}/export的nolocal:前缀表示该变量将随 channel 一起迁移在目标 context 中用${origination_caller_id_number}即可取到值验证在目标 extension 中加action applicationlog dataDEBUG CID: ${origination_caller_id_number}/。6. 进阶技巧用 Lua 脚本动态路由把硬编码 dialplan 变成可热更新的策略引擎FreeSWITCH 的 XML dialplan 适合静态规则但面对“工作日 9-18 点走 A 中继其余时间走 B 中继”“VIP 用户优先用高码率编解码”等动态策略XML 就力不从心。此时Lua 脚本是最佳解法——它在 FreeSWITCH 进程内运行毫秒级响应且无需重启服务。6.1 准备工作启用 mod_lua 并验证脚本权限首先确认conf/autoload_configs/modules.conf中已启用load modulemod_lua/然后reloadxml在fs_cli中执行luarun print(Hello from Lua!)若返回Hello from Lua!说明 mod_lua 加载成功。6.2 动态外呼路由脚本根据时间、号码、用户等级选择 gateway创建scripts/route_outbound.lua-- scripts/route_outbound.lua local function get_gateway_by_time() local hour os.date(*t).hour if hour 9 and hour 18 then return myisp_premium else return myisp_basic end end local function get_gateway_by_number(number) if string.match(number, ^1[3-9]%d{9}$) then return myisp_mobile elseif string.match(number, ^0%d{2,3}%d{7,8}$) then return myisp_landline else return myisp_default end end -- 主路由函数 function route_outbound(session, args) local number session:getVariable(destination_number) local user_level session:getVariable(user_level) or standard local gateway myisp_default -- VIP 用户强制走 premium if user_level vip then gateway myisp_premium else -- 按时间路由 gateway get_gateway_by_time() -- 按号码类型微调 if string.len(number) 11 then gateway get_gateway_by_number(number) end end -- 设置外呼参数 session:setVariable(origination_caller_id_number, session:getVariable(caller_id_number)) session:setVariable(effective_caller_id_number, session:getVariable(caller_id_number)) -- 执行 bridge session:execute(bridge, sofia/gateway/ .. gateway .. / .. number) end6.3 在 dialplan 中调用 Lua 脚本!-- conf/dialplan/public.xml -- context namepublic extension namedynamic_outbound condition fielddestination_number expression^[\0-9]$ action applicationlua dataroute_outbound.lua route_outbound/ /condition /extension /context执行逻辑lua应用加载route_outbound.lua并调用其中的route_outbound函数session对象可读取/设置任意 channel variable如caller_id_number、user_levelsession:execute(bridge, ...)等效于 dialplan 中的action applicationbridge .../脚本修改变量后后续 dialplan 步骤仍可使用如log记录选中的 gateway。6.4 热更新技巧用 inotifywait 监控脚本变更自动 reloadLua 脚本修改后无需重启 FreeSWITCH但需通知其重新加载。用 Linuxinotifywait实现# 安装 inotify-tools apt-get install inotify-tools # 创建监控脚本 reload_lua.sh #!/bin/bash while inotifywait -e modify /usr/local/freeswitch/scripts/route_outbound.lua; do echo $(date): Reloading Lua script echo luarun package.reload(route_outbound) | nc localhost 8021 done原理FreeSWITCH 的 Event Socket端口 8021支持luarun命令package.reload强制重载 Lua 模块实现秒级热更新。从那以后我每次上线新路由策略都先跑一遍inotifywait监控再改脚本——再也不用reloadxml后祈祷所有 channel 没断。希望帮到你。本文还有配套的精品资源点击获取
