mod_ali_oss 模块使用文档项目概述mod_ali_oss是一个 FreeSWITCH 模块用于将录音文件自动上传到阿里云 OSS对象存储服务。该模块通过监控录音目录的文件变化实时将新生成的录音文件上传至阿里云 OSS并在上传成功后删除本地文件实现录音文件的云端存储和管理。核心功能1. 自动文件监控使用 Linux inotify 机制监控录音目录变化支持多目录同时监控按日期分目录实时检测新文件写入完成事件IN_CLOSE_WRITE2. 智能目录管理自动创建按日期格式YYYYMMDD命名的子目录预创建未来几天的监控目录可配置自动清理过期的空目录每日凌晨1点自动维护目录结构3. 多线程上传支持配置多个上传线程并发处理队列化管理待上传文件上传成功后自动删除本地文件4. 授权验证集成 LicenseCC 授权验证机制授权失效时自动卸载模块技术架构依赖组件FreeSWITCH: 开源通信平台阿里云 OSS C SDK: 用于对象存储操作LicenseCC: 模块授权验证库APR: Apache 可移植运行时库系统库: pthread、libcurl、OpenSSL关键技术inotify: Linux 文件系统事件监控epoll: 高效的 I/O 事件通知机制C11: 多线程、智能指针、原子操作STL容器: 队列管理和映射关系维护配置说明配置文件位置配置文件ali_oss.conf.xml需要放置在 FreeSWITCH 的配置目录中通常是/usr/local/freeswitch/conf/autoload_configs/ali_oss.conf.xml配置参数详解参数名称说明默认值示例sub录音子目录名称archivearchivethreads上传线程数量72pre-watchs预监控目录个数77region阿里云地域-cn-shanghaioss-endpointOSS服务端点-https://oss-cn-shanghai-internal.aliyuncs.comoss-access-key-id阿里云访问密钥ID-oss-secret-access-key阿里云访问密钥Secret-oss-bucketOSS存储桶名称-配置文件示例configurationnameali_oss.confdescriptionali oss Configurationsettingsparamnamesubvaluearchive/paramnamethreadsvalue2/paramnamepre-watchsvalue7/paramnameregionvaluecn-shanghai/paramnameoss-endpointvaluehttps://oss-cn-shanghai-internal.aliyuncs.com/paramnameoss-access-key-idvalue您的AccessKey/paramnameoss-secret-access-keyvalue您的SecretKey/paramnameoss-bucketvalue您的Bucket名称//settings/configuration目录结构本地目录结构{recordings_dir}/archive/ ├── 20250509/ # 日期目录 │ ├── file1.mp3 # 录音文件 │ └── file2.wav ├── 20250510/ │ └── file3.mp3 └── 20250511/ └── file4.wavOSS 存储结构bucket/archive/ ├── 20250509/ │ ├── file1.mp3 │ └── file2.wav ├── 20250510/ │ └── file3.mp3 └── 20250511/ └── file4.wavAPI 接口模块提供以下 FreeSWITCH API 命令获取 OSS URL# 获取外网访问URLfs_cli-xoss external-url# 返回: https://bucket.oss-cn-shanghai.aliyuncs.com# 获取内网访问URLfs_cli-xoss internal-url# 返回: https://bucket.oss-cn-shanghai-internal.aliyuncs.com工作流程1. 模块初始化流程模块加载授权验证读取配置文件初始化OSS客户端创建inotify监控扫描现有文件启动监控目录启动工作线程模块就绪2. 文件上传流程是否录音文件写入inotify事件触发文件加入上传队列上传线程获取文件上传到OSS上传成功?删除本地文件记录错误日志完成3. 目录管理流程是否每日凌晨1点获取最大最小日期目录检查最小目录是否可删除目录为空且非当日?删除最小日期目录保留目录创建新的监控目录等待下次执行日志说明日志级别INFO: 正常操作信息文件上传、目录创建等ERROR: 错误信息上传失败、目录操作失败等NOTICE: 重要通知模块加载/卸载关键日志示例# 模块加载成功 [INFO] 模块加载成功:[mod_ali_oss] # 文件上传 [INFO] 正在上传文件到OSS:[bucket:test][key:archive/20250509/file.mp3][path:/path/to/file.mp3] [INFO] 结束上传文件到OSS:[bucket:test][key:archive/20250509/file.mp3][path:/path/to/file.mp3] # 目录管理 [INFO] 添加监控目录:[/path/to/archive/20250509], 总共监控目录数:[7] [INFO] 删除目录成功:[/path/to/archive/20250502] # 错误示例 [ERROR] 上传文件[/path/to/file.mp3]失败,[code: xxx][error: xxx][request_id: xxx]安全考虑1. 访问密钥安全建议使用 RAM 子账号创建访问密钥限制子账号仅具有必要的 OSS 操作权限定期轮换访问密钥2. 网络安全支持内网 Endpoint减少公网流量OSS SDK 支持 SSL/TLS 加密传输可配置关闭 SSL 验证测试环境3. 文件安全上传成功后立即删除本地文件支持断点续传依赖 SDK 版本自动重试机制依赖 SDK 实现故障排除常见问题模块加载失败检查授权文件是否有效确认依赖库是否正确安装查看 FreeSWITCH 日志获取详细错误信息文件上传失败验证阿里云访问密钥是否有效检查 OSS Endpoint 和 Region 配置确认 Bucket 是否存在且有写权限目录监控异常检查录音目录权限验证 inotify 资源限制查看是否有足够的文件描述符性能优化建议线程数量根据服务器性能调整上传线程数避免线程数过多导致资源竞争监控目录数量根据录音保留策略调整 pre-watchs 参数过多目录会消耗 inotify 资源网络优化优先使用内网 Endpoint考虑地域就近性选择版本信息版本: 1.0作者: pzh创建日期: 2025/05/14更新日期: 2025/09/10技术支持如遇到问题请检查FreeSWITCH 日志文件模块配置文件格式阿里云 OSS 控制台设置系统资源使用情况注意: 本文档基于当前代码版本编写使用前请确保所有依赖组件已正确安装和配置。如有问题或建议请联系开发团队。这篇文章把 AI 外呼的链路和落地要点讲清楚了。这个开源模块的完整源码我已开源可以在下面的仓库获取GitHubhttps://github.com/pzhu1015/salesGitee国内访问更快https://gitee.com/pzhu1015/sales如果你正在做或打算做智能外呼 / 呼叫中心除了这个模块还有 FreeSWITCH 部署、ASR/TTS 对接、Kamailio 负载、录音上云等相关方案欢迎到仓库交流和看更多实现。欢迎技术交流一起把 AI 外呼做好。
FreeSWITCH 阿里云OSS通话录音自动上传插件
mod_ali_oss 模块使用文档项目概述mod_ali_oss是一个 FreeSWITCH 模块用于将录音文件自动上传到阿里云 OSS对象存储服务。该模块通过监控录音目录的文件变化实时将新生成的录音文件上传至阿里云 OSS并在上传成功后删除本地文件实现录音文件的云端存储和管理。核心功能1. 自动文件监控使用 Linux inotify 机制监控录音目录变化支持多目录同时监控按日期分目录实时检测新文件写入完成事件IN_CLOSE_WRITE2. 智能目录管理自动创建按日期格式YYYYMMDD命名的子目录预创建未来几天的监控目录可配置自动清理过期的空目录每日凌晨1点自动维护目录结构3. 多线程上传支持配置多个上传线程并发处理队列化管理待上传文件上传成功后自动删除本地文件4. 授权验证集成 LicenseCC 授权验证机制授权失效时自动卸载模块技术架构依赖组件FreeSWITCH: 开源通信平台阿里云 OSS C SDK: 用于对象存储操作LicenseCC: 模块授权验证库APR: Apache 可移植运行时库系统库: pthread、libcurl、OpenSSL关键技术inotify: Linux 文件系统事件监控epoll: 高效的 I/O 事件通知机制C11: 多线程、智能指针、原子操作STL容器: 队列管理和映射关系维护配置说明配置文件位置配置文件ali_oss.conf.xml需要放置在 FreeSWITCH 的配置目录中通常是/usr/local/freeswitch/conf/autoload_configs/ali_oss.conf.xml配置参数详解参数名称说明默认值示例sub录音子目录名称archivearchivethreads上传线程数量72pre-watchs预监控目录个数77region阿里云地域-cn-shanghaioss-endpointOSS服务端点-https://oss-cn-shanghai-internal.aliyuncs.comoss-access-key-id阿里云访问密钥ID-oss-secret-access-key阿里云访问密钥Secret-oss-bucketOSS存储桶名称-配置文件示例configurationnameali_oss.confdescriptionali oss Configurationsettingsparamnamesubvaluearchive/paramnamethreadsvalue2/paramnamepre-watchsvalue7/paramnameregionvaluecn-shanghai/paramnameoss-endpointvaluehttps://oss-cn-shanghai-internal.aliyuncs.com/paramnameoss-access-key-idvalue您的AccessKey/paramnameoss-secret-access-keyvalue您的SecretKey/paramnameoss-bucketvalue您的Bucket名称//settings/configuration目录结构本地目录结构{recordings_dir}/archive/ ├── 20250509/ # 日期目录 │ ├── file1.mp3 # 录音文件 │ └── file2.wav ├── 20250510/ │ └── file3.mp3 └── 20250511/ └── file4.wavOSS 存储结构bucket/archive/ ├── 20250509/ │ ├── file1.mp3 │ └── file2.wav ├── 20250510/ │ └── file3.mp3 └── 20250511/ └── file4.wavAPI 接口模块提供以下 FreeSWITCH API 命令获取 OSS URL# 获取外网访问URLfs_cli-xoss external-url# 返回: https://bucket.oss-cn-shanghai.aliyuncs.com# 获取内网访问URLfs_cli-xoss internal-url# 返回: https://bucket.oss-cn-shanghai-internal.aliyuncs.com工作流程1. 模块初始化流程模块加载授权验证读取配置文件初始化OSS客户端创建inotify监控扫描现有文件启动监控目录启动工作线程模块就绪2. 文件上传流程是否录音文件写入inotify事件触发文件加入上传队列上传线程获取文件上传到OSS上传成功?删除本地文件记录错误日志完成3. 目录管理流程是否每日凌晨1点获取最大最小日期目录检查最小目录是否可删除目录为空且非当日?删除最小日期目录保留目录创建新的监控目录等待下次执行日志说明日志级别INFO: 正常操作信息文件上传、目录创建等ERROR: 错误信息上传失败、目录操作失败等NOTICE: 重要通知模块加载/卸载关键日志示例# 模块加载成功 [INFO] 模块加载成功:[mod_ali_oss] # 文件上传 [INFO] 正在上传文件到OSS:[bucket:test][key:archive/20250509/file.mp3][path:/path/to/file.mp3] [INFO] 结束上传文件到OSS:[bucket:test][key:archive/20250509/file.mp3][path:/path/to/file.mp3] # 目录管理 [INFO] 添加监控目录:[/path/to/archive/20250509], 总共监控目录数:[7] [INFO] 删除目录成功:[/path/to/archive/20250502] # 错误示例 [ERROR] 上传文件[/path/to/file.mp3]失败,[code: xxx][error: xxx][request_id: xxx]安全考虑1. 访问密钥安全建议使用 RAM 子账号创建访问密钥限制子账号仅具有必要的 OSS 操作权限定期轮换访问密钥2. 网络安全支持内网 Endpoint减少公网流量OSS SDK 支持 SSL/TLS 加密传输可配置关闭 SSL 验证测试环境3. 文件安全上传成功后立即删除本地文件支持断点续传依赖 SDK 版本自动重试机制依赖 SDK 实现故障排除常见问题模块加载失败检查授权文件是否有效确认依赖库是否正确安装查看 FreeSWITCH 日志获取详细错误信息文件上传失败验证阿里云访问密钥是否有效检查 OSS Endpoint 和 Region 配置确认 Bucket 是否存在且有写权限目录监控异常检查录音目录权限验证 inotify 资源限制查看是否有足够的文件描述符性能优化建议线程数量根据服务器性能调整上传线程数避免线程数过多导致资源竞争监控目录数量根据录音保留策略调整 pre-watchs 参数过多目录会消耗 inotify 资源网络优化优先使用内网 Endpoint考虑地域就近性选择版本信息版本: 1.0作者: pzh创建日期: 2025/05/14更新日期: 2025/09/10技术支持如遇到问题请检查FreeSWITCH 日志文件模块配置文件格式阿里云 OSS 控制台设置系统资源使用情况注意: 本文档基于当前代码版本编写使用前请确保所有依赖组件已正确安装和配置。如有问题或建议请联系开发团队。这篇文章把 AI 外呼的链路和落地要点讲清楚了。这个开源模块的完整源码我已开源可以在下面的仓库获取GitHubhttps://github.com/pzhu1015/salesGitee国内访问更快https://gitee.com/pzhu1015/sales如果你正在做或打算做智能外呼 / 呼叫中心除了这个模块还有 FreeSWITCH 部署、ASR/TTS 对接、Kamailio 负载、录音上云等相关方案欢迎到仓库交流和看更多实现。欢迎技术交流一起把 AI 外呼做好。
