简介这份文档面向使用 Freeswitch 搭建 VoIP 通信平台的运维与开发人员聚焦呼入呼出路由配置这一关键环节帮助读者理清拨号计划、SIP 中继与对等中继模式下的外呼实现思路。资源包内共 1 个 doc 文件约 221KB内容围绕 Freeswitch 系统架构展开涵盖程序启动流程、消息分发机制、mod_sofia 模块组成与启动过程等核心知识点并配有术语定义与条目编号规范便于按模块查阅。文档以个人学习总结的形式梳理整体架构先讲 CORE 再讲 MODULE适合作为理解 Freeswitch 内部运行机制的参考笔记。目前已有 6455 人学习下载对需要配置内呼外呼、设置 SIP 中继及排查路由问题的读者具有一定参考价值。1. 从一通打不通的外呼说起FreeSWITCH 路由配置到底卡在哪很多团队第一次把 FreeSWITCH 接上 SIP 网关时都会遇到一个很典型的现象内部分机互拨一切正常但一拨外线就静默失败日志里只有一句NORMAL_CLEARING看不出任何有用信息。问题往往不在网关也不在运营商而是出在dialplan和sip_profiles这两层配置没有对齐——呼入不知道该落到哪个 context呼出不知道该从哪个 gateway 出去。这份 FreeSWITCH 路由配置资料围绕的正是这个环节它把呼入路由、呼出路由、SIP 中继对等中继模式三件事串成一条可复现的链路适合已经能把 FreeSWITCH 跑起来、但卡在“内外网打通”这一步的运维和通信开发人员。下面按“先看清结构、再动手配、最后排坑”的顺序拆开讲每一步都落到具体文件和参数上。2. 先理清 FreeSWITCH 的模块与事件骨架路由为什么长这样在改任何一行 XML 之前得先明白 FreeSWITCH 为什么把路由拆成拨号计划、端点、中继三块。这不是设计者故意绕弯而是它的核心设计决定的核心只提供通用函数和状态机具体协议能力全部由 module 挂进来。你配的每一条路由最终都是通过某个 module 的接口被调用的。2.1 核心与模块的分层路由配置的落点在哪FreeSWITCH 启动时src/switch.c里的main()先解析启动参数、给全局目录变量SWITCH_GLOBAL_dirs赋值、创建 pid 文件然后调用switch_core_init_and_modload()。这个函数做两件事先switch_core_init()初始化核心APR、会话、控制台、事件、XML、日志、switch.conf、状态机、SQLite 线程、定时任务、RTP再switch_loadable_module_init()按conf/modules.conf和conf/post_load_modules.conf逐个加载模块。每个模块被加载时通过switch_loadable_module_load_module_ex()找到动态库、定位#name#_module_interface入口结构体、执行SWITCH_MODULE_LOAD_FUNCTION。这套机制对路由配置的直接含义是你写的 dialplan 能不能生效取决于对应 endpoint 模块有没有被加载。比如mod_sofia没在modules.conf里sip_profiles下的 profile 根本不会起来呼入呼出都无从谈起。所以排查路由问题的第一步永远是确认模块加载状态而不是盯着 XML 找语法错误。常见做法是先看模块清单再确认 sofia 是否在运行# 进入 fs_cli 后执行确认 sofia 端点已加载 fs_cli -x module_exists mod_sofia # 列出当前所有 sofia profile 及其状态 fs_cli -x sofia status # 查看已注册的网关 fs_cli -x sofia status gatewaymodule_exists返回true说明模块在sofia status会列出每个 profile 的RUNNING状态和绑定的 IP:端口这是后面配中继时的对照基准。如果这里就是空的先回去检查modules.conf别往下走。2.2 事件与状态机呼入呼出在内部是怎么被驱动的FreeSWITCH 每个信道有自己的线程线程通过状态机与核心交互状态变化会以事件形式抛到EVENT_DISPATCH_QUEUE队列由分发线程消费。事件类型定义在src/include/switch_types.h和路由强相关的有SWITCH_EVENT_CHANNEL_CREATE、SWITCH_EVENT_CHANNEL_ANSWER、SWITCH_EVENT_CHANNEL_BRIDGE、SWITCH_EVENT_CHANNEL_HANGUP、SWITCH_EVENT_CHANNEL_EXECUTE等。模块通过switch_event_bind()把回调绑到某类事件上switch_event_unbind()解绑。理解这一层对排障的价值在于呼入进来后走哪个 context、执行了哪个 application都能从事件流里看到。当一通外呼失败时你不需要猜直接订阅事件就能看到信道创建、执行、挂断的完整轨迹。我一般排路由问题会先开一个事件监听窗口# 订阅信道相关事件观察一通呼叫的完整生命周期 fs_cli -x event plain CHANNEL_CREATE CHANNEL_ANSWER CHANNEL_EXECUTE CHANNEL_HANGUP CHANNEL_HANGUP_COMPLETE订阅后拨一通电话终端会逐条打印事件。重点看CHANNEL_EXECUTE里Application字段是不是你预期的bridge或transfer以及CHANNEL_HANGUP_COMPLETE里的Hangup-Cause。如果Application是空的或者停在playback说明 dialplan 匹配到了错误的 extension如果Hangup-Cause是CALL_REJECTED问题多半在网关侧或认证。这一步能把“玄学不通”压缩成一个具体字段。2.3 拨号计划、端点、中继三者的职责边界把职责分清配置才不会互相打架组件配置文件位置负责什么配错的典型症状Dialplanconf/dialplan/*.xml按被叫号码匹配 extension决定执行哪个 application呼入落到默认 context直接挂断SIP Profileconf/sip_profiles/*.xml定义 FreeSWITCH 监听哪个 IP:端口、用 UDP/TCP/TLS、绑定哪个 context外部注册不上sofia status里 profile 不 RUNNINGGatewayconf/sip_profiles/*.xml内gateway定义出局对端地址、认证、注册策略外呼无响应或 407 认证失败呼入链路是外部请求打到某个 profile 的端口 → profile 把呼叫送进它context属性指定的 dialplan context → dialplan 匹配 extension → 执行 application如transfer到分机或bridge到网关。呼出链路是内部分机拨号 → dialplan 匹配到外呼前缀 → 执行bridge sofia/gateway/网关名/号码→ 从对应 gateway 出去。两条链路共用 dialplan但入口和出口不同这就是为什么“内呼通、外呼不通”几乎总是 gateway 或外呼 extension 的问题。3. 呼入路由配置从 profile 的 context 到 dialplan 的 extension呼入配置的核心就一句话让外部呼叫准确落进你写好的 context并被正确的 extension 接住。听起来简单但 profile 的context属性、dialplan 的context名、extension 的destination_number三者任何一处对不上呼叫就会掉进默认逻辑被静默处理。3.1 配置 SIP Profile 的 context 与端口先看 profile。一个典型的 external profile 片段如下重点是context、sip-port、sip-ip三个属性!-- conf/sip_profiles/external.xml 关键片段 -- profile nameexternal !-- 监听端口对等中继模式下对端要往这个端口发 INVITE -- param namesip-port value5080/ !-- 本机对外 IP多网卡时务必写实际可达的那个 -- param namesip-ip value192.0.2.10/ !-- 呼入落到哪个 dialplan context必须与 dialplan 文件名/context 名一致 -- param namecontext valuepublic/ !-- 关闭认证对等中继通常按 IP 信任需要认证时改为 true 并配 directory -- param nameaccept-blind-reg valuefalse/ param nameauth-calls valuefalse/ /profilecontextpublic意味着从 5080 端口进来的呼叫会去conf/dialplan/public.xml里找匹配。sip-ip写错是多网卡环境最常见的翻车点机器上有内网和公网两块网卡时如果这里写了内网地址对端发到公网地址的 INVITE 就到不了监听 socket。auth-calls在对等中继场景下一般关掉靠 IP 白名单信任对端如果对端要求注册认证则要打开并在 directory 里建用户。改完 profile 必须 reload 才生效且 reload 会短暂中断该 profile 上的呼叫# 重载指定 profile观察返回是否 OK fs_cli -x sofia profile external restart # 确认 profile 状态和监听地址 fs_cli -x sofia status profile externalrestart比reload更彻底会重建 socket。返回里重点看RUNNING和Listen IP如果Listen IP不是你写的sip-ip说明配置没被读到或者被别的 profile 占了端口。3.2 在 public context 里写呼入 extensionprofile 把呼叫送进publiccontext 后dialplan 要能接住。下面这段把任意被叫号码转到一个内部分机同时保留原始主叫信息!-- conf/dialplan/public.xml -- include context namepublic extension nameinbound_to_1001 !-- 匹配任意被叫号码实际部署建议按 DID 精确匹配 -- condition fielddestination_number expression^(\d)$ !-- 设置主叫显示便于分机识别来源 -- action applicationset datacaller_id_nameInbound-${caller_id_number}/ !-- 转到内部 context 的分机 1001 -- action applicationtransfer data1001 XML default/ /condition /extension /context /includeexpression^(\d)$匹配纯数字被叫$1可在后续 action 里引用。transfer的data格式是目标 dialplan类型 context这里把呼叫从public转到defaultcontext 的 1001 分机。生产环境不建议用通配应该按实际 DID 写精确正则否则任何打到这个端口的呼叫都会被转走等于把入口敞开。改完 dialplan 用reloadxml热加载不需要重启服务fs_cli -x reloadxml # 验证 extension 是否被解析到 fs_cli -x xml_locate dialplan publicxml_locate会打印该 context 解析后的完整 XML如果里面没有你刚写的 extension说明文件没被 include 或者 XML 语法有误比如标签未闭合这时看控制台日志里的 XML 解析报错。3.3 呼入链路验证用事件和日志确认落点配置写完不要靠“拨一下试试”这种黑匣子方式验证。正确做法是订阅事件 看日志双管齐下。拨入一通电话事件流里应该依次出现CHANNEL_CREATE方向inbound、CHANNEL_EXECUTEApplication: transfer、CHANNEL_BRIDGE如果分机接了。如果CHANNEL_CREATE都没出现说明呼叫根本没到 FreeSWITCH问题在网关或网络层如果出现了但Application不是transfer说明 dialplan 匹配错了 extension。日志侧把 sofia 的日志级别临时调高能看到 SIP 报文交互# 提高 sofia 日志级别观察 INVITE 的接收与应答 fs_cli -x sofia loglevel all 9 # 排查完记得调回避免日志刷屏 fs_cli -x sofia loglevel all 0级别 9 会打印完整 SIP 消息。重点看 FreeSWITCH 有没有回100 Trying和200 OK以及Contact头里的地址是不是可达。如果只看到 INVITE 没有应答回到 3.1 检查 profile 监听地址。4. 呼出路由与对等中继gateway 配置与外呼 extension呼出比呼入多一层除了 dialplan 匹配还要有一个能出去的 gateway。对等中继模式下gateway 指向对端设备FreeSWITCH 作为对等节点直接发 INVITE不经过注册。4.1 对等中继的 gateway 参数怎么填gateway 写在 profile 文件里关键参数是proxy、register、realm!-- conf/sip_profiles/external.xml 内与 profile 同级 -- gateway namepeer_gw !-- 对端设备地址和端口对等中继填对端实际监听地址 -- param nameproxy value198.51.100.20:5060/ !-- 对等中继不注册设为 false需要注册时改 true 并配 username/password -- param nameregister valuefalse/ !-- 认证域对端要求认证时填写 -- param namerealm value198.51.100.20/ param nameusername valuefs_out/ param namepassword value******/ !-- 外呼时主叫号码按对端要求填写 -- param namecaller-id-in-from valuetrue/ /gatewayproxy是对端 SIP 地址对等中继下这就是唯一必须填对的参数。registerfalse表示不向对端注册直接按 IP 发呼叫如果对端是运营商要求注册则改true并填username/password。caller-id-in-fromtrue把主叫号码放进From头很多网关只认From里的号码做鉴权这个参数不设会导致外呼被拒但日志里看不出原因。gateway 改完同样要 restart profile然后用sofia status gateway确认状态是NOREG未注册对等模式正常或REGED已注册fs_cli -x sofia profile external restart fs_cli -x sofia status gateway peer_gw如果状态是FAILED或UNREGED看返回里的State和Status字段通常是proxy地址不可达或认证信息错误。4.2 外呼 extension前缀匹配与 bridge 到 gateway外呼 dialplan 一般写在defaultcontext按拨号前缀匹配然后bridge到 gateway!-- conf/dialplan/default.xml 内 -- extension nameoutbound_via_peer !-- 匹配 0 开头的外线号码去掉前缀 0 后作为被叫 -- condition fielddestination_number expression^0(\d{7,15})$ !-- 设置主叫号码按对端要求调整 -- action applicationset dataeffective_caller_id_number1001/ !-- 从 peer_gw 发出$1 是去掉前缀后的真实号码 -- action applicationbridge datasofia/gateway/peer_gw/$1/ /condition /extensionexpression^0(\d{7,15})$表示以 0 开头、后跟 7 到 15 位数字$1捕获去掉 0 后的号码。bridge的data格式是sofia/gateway/网关名/被叫网关名必须和 gateway 的name属性完全一致。这里最容易踩的坑是前缀没去干净如果直接bridge .../$0对端收到的是带 0 的号码会被判为空号。改完reloadxml然后拨一通外线用事件流确认CHANNEL_EXECUTE里Application: bridge、Application-Data是sofia/gateway/peer_gw/xxx。如果Application-Data里的号码不对回去检查正则捕获组。4.3 外呼失败的三层定位法外呼不通时按三层往下切比盲目改配置高效得多第一层看 dialplan 有没有匹配。事件流里如果没有CHANNEL_EXECUTE的bridge说明正则没匹配上用xml_locate dialplan default确认 extension 在不在。第二层看 gateway 有没有发出去。sofia loglevel all 9下如果看到 FreeSWITCH 发出了 INVITE 但没收到100 Trying问题在对端地址或网络如果收到407 Proxy Authentication Required是认证参数不对回去核对username/password/realm。第三层看对端返回码。CHANNEL_HANGUP_COMPLETE里的Hangup-Cause如果是CALL_REJECTED多半是对端策略拒绝主叫号码不合法、被叫不在白名单如果是NO_ROUTE_DESTINATION是对端没有到该号码的路由。这三层走完问题基本能定位到具体参数。5. 避坑与排查五个真实踩过的坑路由配置的坑大多不是语法错误而是“配置对了但环境不对”。下面五条是我在实际部署里反复遇到的按现象、原因、解决写清楚。坑一profile 显示 RUNNING但外部呼叫进不来。现象是sofia status一切正常对端却收不到应答。原因通常是sip-ip写了内网地址而对端往公网地址发 INVITEsocket 没绑在那个地址上。解决是把sip-ip改成对端实际可达的地址restart profile 后用sofia status profile external确认Listen IP一致。多网卡机器上这个坑几乎必踩。坑二外呼日志显示 bridge 成功但对端说没收到呼叫。现象是CHANNEL_EXECUTE里bridge执行了Hangup-Cause却是NORMAL_CLEARING。原因是 gateway 的proxy地址写成了域名但 DNS 解析到了错误 IP或者端口写错对端监听 5060 你写了 5080。解决是用sofia status gateway peer_gw看解析后的地址必要时在/etc/hosts里固定映射端口以对端实际配置为准。坑三呼入能通但主叫号码显示为 unknown。现象是分机接起来看不到来电号码。原因是 profile 里没开caller-id-in-from或者对端把号码放在P-Asserted-Identity头里而 FreeSWITCH 没解析。解决是在 profile 里加param namecaller-id-in-from valuetrue/并在 dialplan 里用${caller_id_number}显式设置显示名。坑四reloadxml 后新 extension 不生效。现象是文件改了、reloadxml返回成功但呼叫还是走旧逻辑。原因是 XML 文件没被主 dialplan 文件 include或者文件里有未闭合标签导致整个文件解析失败被跳过。解决是xml_locate dialplan context看解析结果里有没有新 extension没有就查控制台日志的 XML 报错逐个文件用xmllint校验。坑五对等中继下外呼被 403 拒绝。现象是 INVITE 发出去收到403 Forbidden。原因是对端按 IP 做信任但你的出口 IP 和对端白名单不一致比如经过 NAT 后源地址变了或者From头里的主叫号码不在对端允许范围。解决是确认出口源 IP必要时在对端加白主叫号码按对端要求用effective_caller_id_number设置成合法号段。提示每次改完 profile 或 gateway先restart再验证改完 dialplan先reloadxml再xml_locate确认解析结果。跳过确认直接拨号等于把排障成本翻倍。6. 进阶用事件订阅和日志级别把路由问题变成可观测数据路由配置做到能通只是及格线真正省时间的是把它变成可观测的。我现在的习惯是任何一次路由变更都先用事件订阅跑一遍完整呼叫把CHANNEL_CREATE到CHANNEL_HANGUP_COMPLETE的事件序列存下来作为这条链路的“基线”。以后出问题拿新的事件序列和基线对比差异点就是故障点。具体做法是开一个长期的事件监听把输出重定向到文件按时间切分# 后台订阅关键事件输出带时间戳便于事后比对 fs_cli -x event plain CHANNEL_CREATE CHANNEL_EXECUTE CHANNEL_BRIDGE CHANNEL_HANGUP_COMPLETE \ | while read -r line; do echo $(date %F %T) $line; done /var/log/fs_route_trace.log这条命令把事件流按行加时间戳落盘。正常呼叫的基线里CHANNEL_CREATE的Call-Direction应该是inbound或outboundCHANNEL_EXECUTE的Application应该是transfer或bridgeCHANNEL_HANGUP_COMPLETE的Hangup-Cause应该是NORMAL_CLEARING。任何一项偏离直接对应到第 3、4 章的具体配置点。配合日志级别做分层排查也很实用。日常把 sofia 日志压到 0只在排障时临时开到 9并且用fs_cli的过滤功能只看某个呼叫的 UUID# 只跟踪指定呼叫 UUID 的日志避免全量刷屏 fs_cli -x console loglevel debug fs_cli -x uuid_setvar call_uuid loglevel debuguuid_setvar给单个信道设日志级别比全局调级别精准得多生产环境排障时不会影响其他呼叫。这个技巧在并发量大的场景下几乎是必备的全局开 debug 会把磁盘写满。还有一个容易被忽略的点switch_core_init()里switch_find_local_ip获取本地 IP 时会访问外部地址如果机器网络受限这一步可能超时拖慢启动。启动慢但最终能起来的情况先查这个。另外EVENT_DISPATCH_QUEUE的容量和 CPU 个数相关高并发下如果事件消费不及时可以适当调大分发线程数但这属于性能调优范畴路由配置阶段先保证事件能正常消费即可。从那以后我每次改完路由配置都强制走一遍“restart → reloadxml → xml_locate → 事件订阅拨测”这四步不跳步。这套流程看着笨但把“改完不知道对不对”变成了“每一步都有明确输出”排障时间从小时级压到分钟级。希望帮到你。本文还有配套的精品资源点击获取