一、问题背景与典型场景

在基于FreeSWITCH的通信系统中，外呼手机号场景下的录音功能失效是常见运维问题。典型表现为：通过FreeSWITCH发起的外部呼叫（如PSTN网关或行业常见技术方案对接）能够正常建立通话，但系统未生成预期的录音文件，或录音文件为空、时长异常。

该问题可能影响客户服务质量监控、合规性审计等核心业务场景。例如某企业客服系统因外呼录音缺失，导致无法追溯客户投诉处理过程，引发合规风险。录音功能依赖FreeSWITCH的录音模块（mod_dptools）、媒体流处理机制及底层存储系统的协同工作，任一环节异常均可能导致功能失效。

二、核心排查维度与解决方案

1. 录音模块配置验证

FreeSWITCH默认通过record_session命令或start_recordingAPI触发录音，需检查以下配置项：

<!-- 在dialplan中显式启用录音 -->
<action application="record_session" data="/var/recordings/${uuid}.wav"/>
<!-- 或通过API动态触发 -->
<action application="set" data="recording_file=/var/recordings/${uuid}.mp3"/>
<action application="set" data="recording_mode=record"/>

关键验证点：

确保record_session或start_recording命令在dialplan中的执行顺序正确（需在桥接前调用）
检查${uuid}变量是否有效生成，避免因变量未解析导致路径错误

验证存储目录权限（FreeSWITCH进程用户需有写入权限）：

chown -R freeswitch:freeswitch /var/recordings
chmod 750 /var/recordings

2. 媒体流处理链路分析

外呼场景下，录音依赖媒体流的正确路由。需通过sofia命令检查媒体流状态：

# 查看通道媒体流详情
freeswitch@host> sofia profile internal reg /uuid <call_uuid>
# 检查RTP流是否建立
freeswitch@host> sofia media debug on

常见问题：

NAT穿透失败：若外呼通过NAT设备，需在sip_profiles/external.xml中配置：

<param name="ext-rtp-ip" value="公网IP"/>
<param name="ext-sip-ip" value="公网IP"/>

编解码不匹配：确保外呼网关与FreeSWITCH支持的编解码（如PCMU、PCMA）一致，可通过show channels检查当前编解码。

3. 录音模块依赖检查

FreeSWITCH录音依赖mod_dptools和mod_sndfile模块，需验证模块加载状态：

freeswitch@host> module_exists mod_dptools
freeswitch@host> module_exists mod_sndfile

若模块未加载，需在modules.conf.xml中启用：

<load module="mod_dptools"/>
<load module="mod_sndfile"/>

性能优化建议：

对高并发外呼场景，建议使用mod_shout替代mod_sndfile以降低CPU占用
录音文件格式选择：WAV（无损）适合短时录音，MP3（有损）适合长时存储

4. 日志与错误码分析

通过fs_cli实时监控日志，重点关注以下错误：

freeswitch@host> log level 7
# 过滤录音相关错误
freeswitch@host> grep -i "record" /var/log/freeswitch/freeswitch.log

典型错误码：

ERR_RECORD_FAILED：存储路径不可写或磁盘空间不足
ERR_MEDIA_NOT_FOUND：媒体流未正确建立
ERR_MODULE_NOT_LOADED：录音模块未加载

三、外呼场景专项优化

1. 网关配置验证

外呼网关（如PSTN网关或行业常见技术方案）需正确配置录音参数：

<!-- 在网关定义中启用录音透传 -->
<param name="record-template" value="/var/recordings/${uuid}.wav"/>
<param name="record-when" value="always"/>

测试方法：

使用originate命令模拟外呼：

freeswitch@host> originate sofia/gateway/gw1/13800138000 &record(/var/recordings/test.wav)

检查录音文件是否生成，并验证音频完整性（使用sox工具）：
```
sox /var/recordings/test.wav -n stat
```

2. 多租户环境隔离

在多租户系统中，需通过context隔离录音存储路径：

<context name="tenant_1">
  <extension name="outbound">
    <condition field="destination_number" expression="^138\d+$">
      <action application="record_session" data="/var/recordings/tenant_1/${uuid}.wav"/>
    </condition>
  </extension>
</context>

四、最佳实践与预防措施

自动化监控：通过Prometheus+Grafana监控录音文件生成情况，设置磁盘空间告警

录音文件生命周期管理：

# 示例：保留30天录音，删除旧文件
find /var/recordings -type f -mtime +30 -delete

容灾设计：对关键业务录音，建议同步存储至分布式文件系统（如HDFS）或对象存储
版本兼容性：升级FreeSWITCH前，在测试环境验证录音功能与新版本的兼容性

五、总结与延伸

FreeSWITCH外呼录音缺失问题通常由配置错误、媒体流异常或模块依赖导致。通过系统性排查配置、网络、模块和日志四个维度，可快速定位问题根源。建议结合自动化监控工具构建录音功能健康检查体系，并定期进行容灾演练。对于大规模部署场景，可参考行业最佳实践，采用分布式录音存储架构提升系统可靠性。

FreeSWITCH外呼录音缺失问题深度解析与解决方案