★ FEATURED ARTICLE 1. force_transfer_context它到底是什么1.1 从一次诡异的电话转接故障说起先说个我实际调过的案例。某公司内部用 FreeSWITCH 做总机内部分机通过 SIP REFER 方式转接外线电话。有一阵子客服反馈A 分机把一通外线电话转给 B 分机B 接通后说话双方都听得到但过了几秒整个通话被莫名其妙地挂断。更怪的是同一套配置在测试环境完全复现不了只有那个特定外线的号码进线时才会出现。查日志查到最后问题落在 FreeSWITCH 收到 REFER 请求后去哪个 dialplan 上下文context里找转接目标的路由规则。默认情况下FreeSWITCH 做 REFER 转接时是拿 REFER 消息里的目标号码结合对话自身的 channel 变量去匹配 context。但如果对方传来的 REFER 里带了特定的 context 信息或者当前这个呼叫的 channel 变量里存了和实际拨号计划不一致的 context 值路由就会跑偏。而 force_transfer_context 这个参数就是用来强制指定这种情况下“到底该去哪个 context 找路由”的开关。这个参数平时很少有人提网上搜一圈也多是文档里一句话带过。但真正做过多租户、多域、或者对接过复杂 SIP 中继的人早晚会遇到它。这篇就把这个参数从头到尾撕开讲清楚包括它默认怎么工作、什么时候必须改、改了之后会话流程变成什么样、以及我踩过的几个坑。1.2 force_transfer_context 在 FreeSWITCH 参数体系里的位置FreeSWITCH 处理呼叫转接时主要涉及几个相关的 channel 变量和拨号计划参数transfer_context transfer_dialplan transfer_filename transfer_data force_transfer_context前面四个是常规转接用的。transfer_context 指定转到哪个 contexttransfer_dialplan 指定用哪个拨号计划默认 XMLtransfer_filename 指定拨号计划文件transfer_data 是透传给拨号计划的额外数据。force_transfer_context 的作用是当 SIP REFER 请求带有目标 context 信息、或者系统内部转接时存在 context 混淆风险通过设置这个参数为 true强制所有 REFER 转接一律使用当前拨号计划中指定的 context而不是从 REFER 消息或 channel 变量里继承来的 context。换句话说它是个“路由兜底开关”。默认不打开的时候FreeSWITCH 在某些场景下会根据 REFER 消息头里携带的上下文信息去解析转接目标打开了之后FreeSWITCH 就忽略外部带来的上下文指示统一走你配置里写死的 context。这样做的好处是路由行为可预测缺点是如果你内部多 context 的路由本身很灵活反而可能被这个强制开关捆住手脚。这个参数生效的位置主要在 mod_sofia 的 SIP 会话层。在收到 REFER 请求时mod_sofia 会尝试把 REFER 转成一个新的拨号计划 session。在这个转换过程中force_transfer_context 决定新 session 的 context 来源优先级。1.3 默认值和最直观的理解默认情况下force_transfer_context 是 false。把这个参数类比一下你家小区有两个物业电话一个是紧急维修一个是日常咨询。正常情况下你打到总机总机根据你按的数字转到对应物业。但有个隐患——如果打电话的人外部SIP设备在电话里直接说“转给日常咨询”总机就真的直接转过去了哪怕这通电话本来应该走紧急维修的流程。force_transfer_context 设成 true 之后总机只认自己内部的转接规则表外部说什么都不好使一律按规则表走。这个开关一旦打开REFER 转接目标号码的 context 查找就变得非常“死板”转接目标只能在当前呼叫所在 context 的同名规则里找或者走你显式指定的 transfer_context。跨 context 转接这类操作就需要你更明确地在配置里写清楚而不是依赖 FreeSWITCH 从 SIP 信令里自动猜。2. 什么时候必须开什么时候千万别开2.1 多租户、多域环境下 REFER 转发的噩梦我在生产环境里遇到过最典型的需要开 force_transfer_context 的场景就是多租户环境。假设你在一台 FreeSWITCH 上跑了三个租户每个租户一套分机号段、一套路由规则、一个独立 context分别是 tenant_a、tenant_b、tenant_c。每个租户有自己的 SIP 中继和外部号码路由。某天租户 A 的一个分机接到一通外线来电。这通电话从租户 A 的中继进来channel 里带着的 context 是 tenant_a。此时分机 A 想把这通电话转给租户 B 的分机 6001。分机 A 的终端设备比如某款 IP 话机发出 SIP REFER 请求目标是 sip:6001pbx.domain。问题来了FreeSWITCH 收到这个 REFER 后转接目标 6001 在哪个 context 里找路由如果 channel 变量里带着的 context 是 tenant_a那么 6001 会先在 tenant_a 里匹配。如果 tenant_a 里恰好没有 6001 这个分机这是大概率事件因为 6001 是租户 B 的分机FreeSWITCH 就会报 404 或者执行默认的 fallback 动作转接失败。但如果某些条件下REFER 消息里带来了一个 context 信息比如 IP 话机把本机配置的 domain 当作 context 传过来或者 SIP 消息头里带了一些自定义参数FreeSWITCH 可能去一个你完全没预料到的 context 里找 6001。如果那个 context 里碰巧有一条匹配 6001 的规则呼叫可能“意外地”接通了但路由逻辑完全不受你控制。这种场景下把 force_transfer_context 设成 true并且在 dialplan 里显式指定 transfer_context 为 tenant_b转接就会稳定发生在 tenant_b 的拨号计划里。代价是你必须对每个租户之间的转接关系有清晰的规划。这里给一个我实际用过的配置片段extension nametenant_b_ext_6001 condition fielddestination_number expression^6001$ action applicationanswer/ action applicationbridge datauser/6001tenant_b/ /condition /extension配合在 sofia 配置里或者拨号计划变量里设置action applicationset dataforce_transfer_contexttrue/ action applicationset datatransfer_contexttenant_b/这样无论 REFER 从哪来、带什么头转接 6001 这个动作的 context 查找范围都被锁死在 tenant_b。呼叫路由的确定性一下子就提高了。2.2 外网设备直接发 REFER 的场景另一个高频场景是外部 SIP 设备直接向 FreeSWITCH 发 REFER。我调试过一个对接项目对方是一个第三方的呼叫中心中间件它会在特定场景下主动向 FreeSWITCH 发起 REFER要求把当前通话转接到某个号码。问题在于这个中间件发的 REFER 请求里Request-URI 的 host 部分填的是它自己的 IP 地址而不是 FreeSWITCH 的 IP。而且 Refer-To 头里目标号码的格式也很随意有时候带 86 前缀有时候不带有时候是 0 开头。这种情况下FreeSWITCH 对 REFER 的 context 判断就很容易出幺蛾子。第一次对接时我没设 force_transfer_context结果发现从外部 REFER 转出去的呼叫有一部分走到了 public context因为 REFER 请求本身被当成一个无认证的外部请求来解析有一部分走进了 default context还有一部分因为解析不到 context 直接 500。整个行为完全不可控。后来我把 force_transfer_context 设成 true同时在 SIP profile 的对应 domain 配置里指定了 transfer_context并且用正则把 Refer-To 里的号码归一化。改动之后所有外部 REFER 转接的行为统一了无论中间件发的 REFER 长什么样FreeSWITCH 一律按我配置的 context 和号码归一化规则走。这也让问题排查变得简单——出问题就只看那一个 context 的路由不用再到处猜。2.3 开启前必须评估的安全边界force_transfer_context 不是银弹它甚至会带来新的安全风险用之前一定要想清楚。一个真实的案例某个客户为了“规范路由行为”在全局default context 的所有分机都把 force_transfer_context 设成了 true。结果出了个什么事呢某个分机的账号密码泄露了攻击者直接用这个分机注册后向 FreeSWITCH 发 REFER尝试把通话转接到一个内部高权限号码。由于 force_transfer_context 强制所有转接走同一个 context而那个 context 里没有任何针对“外部来源 REFER 转接”的限制攻击者成功地把一个外线来电转接到了内网管理号码上绕过了原本应该有的权限隔离。所以我的建议是force_transfer_context 这个开关要尽量缩小作用范围。能在特定 extension、特定 channel 上设置就不要放到全局默认变量里。尤其是那些承接外部 SIP 中继、又同时服务内部高权限分机的系统一定要在转接链路上做好 ACL 和条件判断不要把所有 REFER 都一视同仁地强制到同一个 context。你可以通过${sofia_contact}、${sip_req_user}、${sip_req_host}这些变量在拨号计划里做来源判断再决定是否设置 force_transfer_context而不是无脑全局打开。3. 配置方法与会话流程的完整走查3.1 在拨号计划里配置 transfer 标签实际配置 force_transfer_context 时最常用的位置有两个一个是在 extension 里面通过action applicationset设置 channel 变量另一个是在 SIP profile 的参数里直接定义。先看 dialplan 里的配置方式。比如某个分机 2000 收到一通电话需要无条件转接到 2001并且希望 REFER 路由严格按当前 context 来解析extension nameext_2000_refer condition fielddestination_number expression^2000$ action applicationset dataforce_transfer_contexttrue/ action applicationset datatransfer_contextdefault/ action applicationset datatransfer_dialplanXML/ action applicationanswer/ action applicationsleep data1000/ action applicationtransfer data2001 XML default/ /condition /extension这里有个细节要留意action applicationset dataforce_transfer_contexttrue/是在当前 channel 上设置变量但 transfer 发生时它是否随 channel 带到新会话取决于 FreeSWITCH 版本的变量继承机制。大部分情况下当前 channel 的变量在 transfer 后会被新 session 继承但有些特殊变量需要在 transfer 的目标 context 里显式重新 set 一下才保险。一个更可靠的做法是直接在对方按 user 查找时设置extension nameext_2001_user condition fielddestination_number expression^2001$ action applicationset dataforce_transfer_contexttrue/ action applicationset datatransfer_contextdefault/ action applicationanswer/ action applicationbridge datauser/2001default/ /condition /extension这样做的含义是无论这个分机是被直接呼叫还是被 REFER 转接过来只要最终落到 2001 这个分机的 context 查找force_transfer_context 就会被设置。转接发生时新会话发现这个变量存在就会强制使用新会话自己的 context。3.2 在 SIP profile 层做全局配置如果你管理的是一个垂直单域系统所有用户都在同一个 context 下可以在 SIP profile 层面直接配profile nameinternal param namecontext valuedefault/ param nameforce-transfer-context valuetrue/ ... /profile注意SIP profile 层的参数名用的是连字符风格force-transfer-context而拨号计划变量里用的是下划线风格force_transfer_context。这两个写法不要搞混实际排查中我见过有人在 profile 里写了 underscore 风格结果配置不生效日志里一直看不到预期的行为变化。在 SIP profile 层开启的效果是所有通过这个 profile 注册进来的用户在发起或接收 REFER 时都强制使用 profile 里context参数指定的拨号计划上下文。这也是最低成本的全局控制手段适合单 context 系统。但如果你是多 context 系统我不建议在 profile 层开这个开关因为它的作用范围太粗了。还是回到拨号计划里精细化控制比较好。3.3 参数生效后的会话路由逻辑理解了这个参数还要把 REFER 转接的完整流程走一遍才能在出问题时知道卡在哪一步。正常 REFER 转接流程A 分机和外线用户 B 正在通话中通话 leg 是 FreeSWITCH bridge 起来的channel A 和 channel B 都在同一个 call session 里。A 分机按话机上的“转接”按钮话机发送 SIP REFER 到 FreeSWITCH。REFER 的 Refer-To 头写成sip:2001your-pbx-address表示要把 B 这条腿转给 2001。FreeSWITCH 收到 REFER 后先看 REFER 的来源是否合法是否是当前通话中的一方或者有转接权限。接下来进入关键步骤决定新会话在哪个 context 里解析 2001。mod_sofia 会检查当前 channel 是否有 transfer_context 变量如果有就用它如果没有就用会话的默认 context通常来自 SIP profile 或 channel 创建时的 context。这个过程中如果 force_transfer_context 为 true则“强制使用当前 channel 的 context 或显式指定的 transfer_context”而不会去参考 REFER 消息里可能存在的上下文参数。新会话创建后在选定的 context 里执行 XML 拨号计划匹配 2001 的 extension执行对应的 bridge 动作。如果匹配成功FreeSWITCH 会把 B 腿和 2001 腿桥接起来。如果匹配失败执行transfer_fallback_extension或默认的 404 处理。force_transfer_context 对这个流程最直接的影响在第 4 步。没有它的时候第 4 步可能会因为外部 REFER 消息头里的参数比如某些话机会带上自己配置的 context 名跳到你预期之外的 context有了它第 4 步就被固定住了。从调试角度说如果你在日志里看到这种情况Dialplan: sofia/internal/1000pbx:2001 parsing [default] continue Dialplan: sofia/internal/1000pbx:2001 Regex (ORGINAL) FAIL而你又确认 2001 在另一个 context 里明明存在那大概率就是 context 解析跳错了地方。此时就需要检查该 channel 的 transfer_context 和 force_transfer_context 变量。3.4 和 local_context、transfer_fallback_extension 的关系force_transfer_context 不是单独工作的它和另外两个参数关系非常紧密local_context和transfer_fallback_extension。local_context一般出现在 sofia profile 配置里。它表示当 FreeSWITCH 无法从注册信息或 channel 变量中确定用户属于哪个 context 时默认落到哪个 context。这个参数可以看作是最底层的兜底。一个常见组合是param namelocal_context valuepublic/ param namecontext valuedefault/外部未认证的呼叫进 public内部注册用户进 default。如果此时一个外部来话被 REFER 转接而 force_transfer_context 没开新会话的 context 很可能被解析到 local_context因为外部来话没有可靠的内部 context 信息也就是 public。如果 public 里没有你要转接的分机号码就会失败。transfer_fallback_extension则是更后面的兜底。当 REFER 目标在选定 context 里匹配不到任何 extension 时FreeSWITCH 会把目标号码重新改写为 transfer_fallback_extension 指定的号码在同一个 context 里再跑一次拨号计划。这个机制可以用来做“转接失败统一进总机”的友善提示。我见过一个比较经典的生产配置是param nametransfer-fallback-extension valueoperator/意思是转接目标找不到时统一转给 operator 分机。但如果你没开 force_transfer_contextfallback 到 operator 这个动作也是在被错误解析的 context 里执行的——如果那个 context 里没有 operator 扩展fallback 也 fallback 了个寂寞。这时候把 force_transfer_context 和 transfer_fallback_extension 配合起来才能真正形成一个闭环。我自己在项目里通常这样组合SIP profile 层把local_context设为 public。内网分机的拨号计划第一行就设置force_transfer_contexttrue。同时设置transfer_context为当前租户的 context。设置transfer_fallback_extension指向一个当前 context 里必定存在的应急分机。这样无论内部怎么转、外部怎么 refer路由的终点都是可控的。4. 排查实录日志怎么看、问题怎么定位4.1 转接后呼叫被立即挂断这是最常见的故障现象而且很容易被误判为“媒体问题”。我遇到过好几次类似 case用户说“转接后能通话几秒然后断”第一反应都是去看 RTP 媒体流、NAT、防火墙结果查了半天媒体没问题真实原因在信令路由。当 force_transfer_context 没开外部 REFER 带来一个未知 context 时FreeSWITCH 创建的新会话经常无法在正确 context 里匹配到号码然后就执行了默认挂断。有时候因为 fallback 机制的存在先匹配到了一个不完整的规则执行到一半出错也会呈现为通话数秒后断开。排查步骤我建议按这个顺序来开启 sofia 的完整 SIP 信令日志sofia global siptrace on拿到 REFER 的完整 SIP 消息头。在日志里搜索Dialplan:关键字找到新会话解析时实际进入的是哪个 context。检查 REFER 消息头里是否携带了额外的 context 参数常见于一些老式 IP-PBX 或软交换实现。查看当前 channel 的 channel 变量里 transfer_context 有没有被正确设置在 fs_cli 里执行channel_dump uuid uuid。确认 force_transfer_context 是 true 还是 false以及它在哪个层级被设置。我之前排查过一个案例问题就出在话机型号上。某款 IP 话机在发送 REFER 时会把 Registry 里的账号参数填到 Refer-To 的 user 部分比如sip:2001;contexttenant_apbx然后 FreeSWITCH 默认情况下把它当成新的目标号码去解析结果整个拨号计划匹配全部乱套。开了 force_transfer_context 之后这种怪异的 REFER 头内容直接被无视路由恢复正常。4.2 转出去的路由走到了错误的 context另一种典型问题是REFER 转接没有失败但转到的号码在错误 context 里匹配到了一条完全无关的规则导致呼叫被接到了错误的分机甚至外线。举个例子。某个项目中内部有 default 和 tenants 两个 context。default 里有一个号码 8888指向总机。tenants 里也有一个 8888指向某个租户经理的手机。有一次外部 REFER 转接 8888由于 force_transfer_context 没开新会话解析到了 default结果本应转到租户经理的通话直接打到了总机前台。前台接了电话一脸懵这个 bug 持续了挺久才被发现。排查方法是用 fs_cli 执行show channels找到被转接的那条 channel看它的variable_transfer_context和variable_current_context。如果 current_context 和你的预期不一致再追溯 REFER 消息来源和 channel 变量继承过程。这个案例也说明了 force_transfer_context 的另一个价值它能帮助你在转接路由中建立“白名单思维”。你想让 8888 转到哪个 context就显式指定不要指望系统自动猜。在投屏、多方会议、呼叫队列这类业务里误路由的代价往往比直接失败更大因为用户感知到的是“接了但不该接的电话”。4.3 REFER 消息里带不带 context区别在哪里了解 SIP 的人可能会问REFER 请求本身并没有标准的 context 头为什么会有“消息里带的 context”这种说法实际上一些 SIP 设备会通过 Request-URI 的参数、Contact 头、或者自定义扩展头来携带上下文信息。比如REFER sip:2001192.168.1.10 SIP/2.0 Refer-To: sip:2001192.168.1.10;contextspecial这种情况下mod_sofia 在解析 Refer-To 时会把;contextspecial部分识别为参数影响新会话的 context 选择。FreeSWITCH 文档里没有把这个行为写得非常详细但实际测试中确实存在不同版本差异。我测过几个版本总体规律是较老版本对 Refer-To 参数的容忍度较高较新版本则倾向于忽略无法识别的 URI 参数。但不管版本行为如何最稳妥的方式始终是主动控制而非被动依赖——也就是打开 force_transfer_context不让外部消息头和内部 channel 变量去影响 context 判定。另外如果对接的是运营商或上游 SIP 中继有时候中继平台会在 REFER 里附带一些业务标识头如 P-Called-Party-ID这些头不会直接改变 context但会干扰我们排查时的判断。建议在抓包或抓 SIP trace 时把 Refer-To、Contact、Route、P-Called-Party-ID 一起看了再结合 FreeSWITCH 的日志确认最终拨号计划解析结果。4.4 和 enable_three_party 之间的那些坑还有一个经常被忽略的坑enable_three_party这个 SIP profile 参数会和 REFER 处理打架。enable_three_party 用于控制是否支持三方通话中的 REFER 处理。当它设成 false 时FreeSWITCH 会忽略某些 ATTENDED 转接attended transfer场景下的 REFER转接行为可能直接失败。当它设成 true 时支持的 REFER 类型更丰富同时也意味着更多的 context 解析分支。如果你同时开了 enable_three_partytrue 和 force_transfer_contextfalse某些话机发起的 attended transfer 会走一条复杂的处理路径其中新会话的 context 来源更依赖 REFER 消息内容和当前 channel 状态出问题的概率显著升高。我在项目里固定下来一个组合enable_three_party 保持 true因为要支持话机 BLF 和 attended transfer但 force_transfer_context 必须 true把复杂度压回去。还有一点值得提某些话机特别是老版本固件在 attended transfer 成功后会用 REFER 带一个 replaces 头。replaces 的处理逻辑也会参与 context 选择。如果 force_transfer_context 没开这一层跳转同样可能踩到错误 context。所以排查时看到日志里有Received Refer with replaces就要意识到 context 判定又多了一个变量。4.5 我建议的配置基线最后给一套我目前在新项目中默认采用的 REFER 转接参数组合供参考。SIP profile 层param namecontext valuedefault/ param namelocal_context valuepublic/ param nameforce-transfer-context valuetrue/ param nameenable_three_party valuetrue/ param nametransfer-fallback-extension valueoperator/拨号计划层内部用户分机入口action applicationset dataforce_transfer_contexttrue/ action applicationset datatransfer_contextdefault/ action applicationset datatransfer_dialplanXML/多租户环境里把 transfer_context 替换成各租户自己的 context 名并在每个租户的 context 内各自配置一个 operator 分机兜底。这套组合实测下来在单域和多域场景都比较稳REFER 转接行为可预期日志排查路径清晰。它的代价是如果你某个 context 里本身就需要依赖外部传来的 context 信息做灵活路由这套组合会让你丢掉这个灵活性。但说实话绝大多数业务场景里“可控”比“灵活”值钱得多。转接路由一旦乱了用户的感知永远是“电话断线”“打错了”“转了没人接”而且极难复现这种问题才是真正消耗运维精力的无底洞。从我个人的经验看force_transfer_context 这个参数平时用不着天天动它但一旦你的系统要面对复杂 REFER 来源、多租户隔离、或者外部设备直接发起转接它就是帮你保住路由确定性的关键一道闸。入手前先想清楚自己的 context 拓扑再决定是在 profile 层全局开、还是拨号计划里按需开——这一步想清楚了后面能少踩一大半的坑。
阅读完成 · 觉得有帮助？
