CentOS 7.9 源码编译安装 FreeSWITCH 全流程与避坑指南-北京尧图网络

最近在一台 CentOS 7.9 的旧服务器上重新部署 FreeSWITCH从拉源码到编译再到服务化又实打实走了一遍全流程。网上讲 CentOS 7.9 安装 FreeSWITCH 的教程不算少但很多直接给个 RPM 仓库地址或者默认你已经有一台配置很好的新机器真正能照着跑完、不中途踩坑的反而少。这篇就把我在 centos7.9 上安装 freeswitch 的完整经过写清楚适合要在存量机房或公司内网里自建软交换、呼叫中心实验环境、SIP 接入层的人也适合刚接触 VoIP 想跑一套真实系统练手的同学。我会从系统初始化、依赖安装、源码编译讲到 systemd 托管、防火墙放行最后附上我实际遇到的编译坑和运行期隐患。1. 为什么 CentOS 7.9 FreeSWITCH 的组合仍然值得认真对待1.1 存量机器的真实生态说实话CentOS 7 的生命周期已经进入末期生产环境里它的占比在下降但很多通信机房、政企内网、IDC 托管设备里依旧跑着一大批 CentOS 7 系列系统。我见过不少客户机房的语音网关、SIP 线路对接机都还是 CentOS 7.9 的最低环境上面跑着 FreeSWITCH 或者老版本 Asterisk业务稳定不出事谁也不想轻易动系统。另外很多内网环境出于合规考虑不允许随意换操作系统这种情况下 CentOS 7.9 就是现实选项。还有一个客观原因FreeSWITCH 对系统没有特别激进的要求CentOS 7 的 glibc、openssl、内核版本完全能满足 1.10.x 的编译和运行。只要不开一些非常新、依赖过高版本系统库的功能在 CentOS 7.9 上跑 FreeSWITCH 完全可以做到稳定。我并不建议你在生产上为了“追新”而把一个运行了多年的 CentOS 7.9 直接升级到大版本反而更推荐在新版本系统上新建一套环境做灰度验证。可现实里存量服务器上能把 FreeSWITCH 顺利装起来仍然是很多同学要面对的第一步。1.2 版本选型为什么我挑 1.10.x如果你去翻 GitHub会看到 FreeSWITCH 有多个分支老的 1.6、1.8 已经停止维护1.10 是目前还在持续维护的稳定分支。以我这次在 CentOS 7.9 上部署的经验来说1.10 对新的编解码库、TLS 支持、WebRTC 相关模块都要友好得多。1.8 年代编译时常常会遇到 openssl 版本太新导致头文件不兼容的问题1.10 在这块已经收敛了很多。我这次直接用 v1.10 分支没有去碰 master 上的新特性代码。原因很简单通信系统要的是稳不是天天追新功能。master 分支可能有一些还处于开发中的功能模块依赖变化也快不是短时间能摸透的。对于大多数业务场景1.10 分支上的稳定版本足够支撑 SIP 注册、呼叫路由、媒体转发、录音、TTS/ASR 对接等常规需求。如果你是为了学习那也建议先把 1.10 分支跑熟再看新分支的新特性这样遇到问题时你能更好地区分是配置问题还是代码问题。2. 编译前按我的顺序装依赖没那么多幺蛾子2.1 先决定一件事源码编译还是 RPM 安装FreeSWITCH 官方文档里提供了 SignalWire 维护的 RPM 仓库方式理论上yum install freeswitch一行就能搞定。但我在 CentOS 7.9 上踩过一次坑官方 RPM 仓库对 CentOS 7 的支持已经不像前几年那么积极经常遇到依赖库版本不对、GPG 密钥过期、仓库里软件包版本落后的问题。而且 RPM 方式安装出来的目录结构、模块组合不是你完全可控的出了问题想排查就得先搞清楚它把配置放在了哪里。所以我坚持源码编译。花点时间但换来的好处很实在安装目录固定模块你可以自由裁剪编译参数可以自己控制升级时也能通过 git 切 tag 来精确管理版本。编译一次大约需要几十分钟这时间相比后面生产运行一年的稳定期来说完全值得。2.2 最小化系统环境与软件包安装命令如果你的 CentOS 7.9 还没有装好建议选择最小化安装模式镜像去国内常见镜像站下载就行版本串注意选 7.9.2009。最小化安装能减少很多不必要的系统服务干扰后面跑 FreeSWITCH 也更干净。装完系统第一件事把基础工具和 YUM 源准备好# 更新现有软件包 yum update -y # 启用 EPEL 源后面很多依赖包都靠它 yum install -y epel-release # 编译工具链 yum install -y gcc gcc-c make automake autoconf libtool然后是 FreeSWITCH 编译需要的具体开发库这些缺一个后面 configure 阶段或 make 阶段就会报一个错让你来回折腾yum install -y libuuid-devel zlib-devel openssl-devel \ libjpeg-turbo-devel sqlite-devel libcurl-devel pcre-devel \ speex-devel ldns-devel libedit-devel libxml2-devel yasm \ nasm wget git如果后面要启用特定模块比如 WebRTC 或录音格式转换还会用到这些yum install -y opus-devel libvpx-devel libsndfile-devel \ lua-devel ncurses-devellibedit-devel是 fs_cli 命令行工具需要的依赖如果没有它装完你连控制台都用不起来。sqlite-devel对应 FreeSWITCH 内部数据库支持很多注册信息、通话记录都存在 SQLite 里这个库不能少。speex、opus这类是编码库虽然运行时也可以动态加载但编译期就带上会更省事。提示如果某些包在默认源里提示找不到多半是因为没有装 EPEL或者 EPEL 源拉取失败。先确认/etc/yum.repos.d/epel.repo存在并且能访问再重新执行安装。3. 源码编译全流程configure、make、install 的分段处理3.1 拉取源码和分支选择最稳妥的源码获取方式是直接克隆官方仓库的 v1.10 分支mkdir -p /usr/local/src cd /usr/local/src git clone -b v1.10 https://github.com/signalwire/freeswitch.git freeswitch如果你在拉取 GitHub 时速度长时间卡住也可以找国内开源镜像站上的 FreeSWITCH 镜像仓库效果一样。拉取完成后先看一下源码目录里有没有configure文件如果没有需要先执行./bootstrap.sh或者build/bootstrap.sh来生成 configure 脚本。1.10 分支下通常 bootstrap 脚本会自动完成 autoreconf。cd /usr/local/src/freeswitch ./bootstrap.sh这一步会跑一段时间主要是生成 configure、Makefile 等构建文件。看到提示成功后再继续。3.2 configure 阶段依赖检查与常见失败默认安装路径是/usr/local/freeswitch这个路径我觉得清晰好记所有二进制、配置、日志都集中在一个目录下后面做备份迁移都方便。执行cd /usr/local/src/freeswitch ./configure --prefix/usr/local/freeswitchconfigure 脚本会检查上一节里安装的各类库和头文件。如果缺依赖它会明确告诉你缺什么比如提示缺少某个 lib。这时候不要急着瞎装先看报错信息里的关键关键字很多时候是某个*-devel包没装。我自己遇到过缺libedit和uuid头文件的情况执行完 2.2 的命令后就没再出现问题。一个实用技巧源码目录下有个modules.conf文件里面按行列出了所有要编译的模块。如果你机器资源有限或者明确知道用不到某些模块就把它们注释掉。比如不打算做 TTS/ASR 对接的可以注释掉相关 module不需要某些小众协议支持的也先关掉。这样能显著缩短编译时间也减少后续运行时的维护面。3.3 make 阶段并行度、OOM 与模块裁剪依赖都通过后接下来是编译。我建议不要一上来就make -j$(nproc)尤其当你的服务器只有 2GB 或者 4GB 内存的时候。FreeSWITCH 编译过程中会同时跑很多编译任务并行度太高容易把内存直接吃满最终表现为 make 进程无端消失系统出现“Killed”实际上是内存不足被系统干掉了。我的经验是 4GB 内存机器用make -j2或make -j42GB 内存机器老老实实make -j1。虽然耗时会长一些但至少不会反复中断。执行cd /usr/local/src/freeswitch make -j4如果编译过程中某个模块失败不要整个重来。看一下终端上失败的模块名称然后回到modules.conf把对应的模块注释掉重新执行./configure make -j4。FreeSWITCH 的 make 是增量式的已经编译过的不会重来所以你不用太担心时间浪费。3.4 make install 与语音包编译完成后安装make install这一步会把二进制、默认配置、脚本拷贝到/usr/local/freeswitch下。装完后建议安装内置语音包和音乐包不然拨测时没有提示音可用make cd-sounds-install cd-moh-install这步会从官方源下载声音文件如果因为网络原因下载失败不会影响主程序运行可以等网络好的时候重新执行一次。声音文件会放到/usr/local/freeswitch/sounds和/usr/local/freeswitch/moh目录下。下载的是默认的 en-us-callie 语音包基本够测试用了。安装完成看一下目录结构ls /usr/local/freeswitch/ ls /usr/local/freeswitch/bin/正常情况下能看到freeswitch、fs_cli这两个核心可执行文件conf、db、log、recordings、sounds等目录也都会存在。4. 装完不等于能用服务化、SELinux 与端口放行4.1 创建服务用户和目录权限用 root 跑 FreeSWITCH 不是不行但风险太高。万一某个接口被攻击整个系统权限都丢了。我自己部署一定创建一个专用用户useradd --system --home-dir /usr/local/freeswitch --shell /sbin/nologin freeswitch chown -R freeswitch:freeswitch /usr/local/freeswitch chmod -R 750 /usr/local/freeswitch这个用户不能登录系统只用来跑 FreeSWITCH 进程所有配置、日志、数据库都归它管。后续你会发现很多启动失败的问题其实都是目录权限不对提前把权限设好能少踩一堆坑。4.2 一份开箱即用的 systemd unitCentOS 7 使用 systemd 管理服务我选择手动写一个 unit 文件而不是用官方自带的启动脚本。原因是官方脚本在一些环境下对环境变量处理得不理想而自定义 unit 非常简单直接[Unit] DescriptionFreeSWITCH Afternetwork.target [Service] Userfreeswitch Groupfreeswitch WorkingDirectory/usr/local/freeswitch ExecStart/usr/local/freeswitch/bin/freeswitch -nc -nf ExecReload/usr/local/freeswitch/bin/fs_cli -x reloadxml Restarton-failure LimitNOFILE65536 [Install] WantedBymulti-user.target把上述内容保存到/etc/systemd/system/freeswitch.service然后systemctl daemon-reload systemctl enable freeswitch systemctl start freeswitch这里需要注意-nc表示不进入控制台模式-nf表示不 fork 到后台systemd 要求服务进程在前台运行这两个参数配合正合适。LimitNOFILE设置大一点是为了防止高并发下文件描述符不够用这个值在通信软件里很重要。如果修改过 event socket 密码ExecReload里的fs_cli -x命令也要对应加上-p 新密码不然重载会失败。这个细节很容易忽略。4.3 SELinux 与 firewalld 放行CentOS 7 默认是 SELinux enforcing 状态对自定义编译的软件影响特别大。FreeSWITCH 启动后会有很多动态库加载、端口绑定、文件读写动作都可能被 SELinux 拦截。如果启动失败先看日志再查 SELinuxgrep freeswitch /var/log/audit/audit.log | tail -20如果你确认这台机器就是专用通信服务器可以临时把 SELinux 设为 permissive 来排查setenforce 0如果验证下来就是 SELinux 导致的生产环境请按公司安全基线处理要么正确配置策略放行要么在必要且允许的前提下调整 SELinux 模式。硬顶着 SELinux 跑不是不行但你会不断遇到莫名其妙的权限问题。防火墙也一样CentOS 7 的 firewalld 默认不让你出 SIP 端口。需要放行以下端口firewall-cmd --permanent --add-port5060/udp firewall-cmd --permanent --add-port5080/udp firewall-cmd --permanent --add-port5060/tcp firewall-cmd --permanent --add-port5080/tcp firewall-cmd --permanent --add-port16384-32768/udp firewall-cmd --reload5060 是 internal profile 默认监听的 SIP 端口5080 是 external profile 的端口16384-32768 是 RTP 媒体流端口范围。很多人只放行了 5060结果分机注册上了但电话打不通一查才发现 RTP 端口没放这种问题很难排查提前放好最省心。4.4 启动前必须改掉的默认配置FreeSWITCH 安装后默认配置里有几个非常“危险”的默认值如果你打算把它暴露到非可信网络必须先改。最典型的是默认密码分机密码默认是1234定义在/usr/local/freeswitch/conf/vars.xml里的default_password管理接口 event socket 的默认密码是ClueCon定义在/usr/local/freeswitch/conf/autoload_configs/event_socket.conf.xml修改方式很简单把 vars.xml 里对应的密码替换成强密码然后把 event_socket 的密码也换掉。修改后执行/usr/local/freeswitch/bin/fs_cli -x reloadxml systemctl restart freeswitch另外检查一下 external profile 里的公网 IP 配置如果这台机器要对接外网 SIP 线路把ext-sip-ip和ext-rtp-ip改成你的公网 IP或者设置成auto-nat模式。默认的$${local_ip_v4}在 NAT 环境下会导致信令和媒体地址错误这是一个非常隐蔽的问题。5. 验证安装成果推荐一套从命令行到真实呼叫的检查清单5.1 进程、端口、模块三连查装完别急着配业务先用三条命令确认基础运行状态# 看版本 /usr/local/freeswitch/bin/freeswitch -version # 看运行状态 /usr/local/freeswitch/bin/fs_cli -x status # 看监听端口 ss -lntup | grep -E 5060|5080|8021fs_cli是 FreeSWITCH 自带的管理客户端默认通过本地 8021 端口的 event socket 和主进程通信。如果执行fs_cli -x status提示 connection refused先确认主进程有没有起来systemctl status freeswitch tail -f /usr/local/freeswitch/log/freeswitch.log日志是排障的第一现场日志目录/usr/local/freeswitch/log/下不仅有freeswitch.log还有按天轮转的老日志。能看到Freeswitch version ... starting就说明主进程启动成功了。再深入一点检查 SIP 模块加载情况/usr/local/freeswitch/bin/fs_cli -x sofia status这个命令会列出 internal 和 external 两个 profile 的运行状态、监听地址。如果某个 profile 没起来大概率是对应 XML 配置有问题或者端口被别的程序占用。5.2 用软电话完成首次真实呼叫命令行终归是间接验证最直观的成果是拿一个真实 SIP 电话终端注册上来完成一次通话。我自己习惯用 MicroSIP 或者 Zoiper都是免费的配置也很简单服务器地址填 CentOS 7.9 机器的 IP端口填 5060账号填默认分机号比如 1000密码填修改后的分机密码分机号 1000 到 1019 在默认配置里就已经存在对应的文件在/usr/local/freeswitch/conf/directory/default/下。注册成功后在 fs_cli 里执行/usr/local/freeswitch/bin/fs_cli originate user/1000 echo软电话会响铃接听后你就能从耳机里听到自己的回声。这一步通过说明从 SIP 注册到媒体协商、RTP 传输整条链路都通了。如果注册不上先看 softphone 上有没有显示 SIP 403 或 404403 多数是密码错误404 多半是分机号不存在或者 dialplan 没加载。再不行就抓包看一下 SIP 信令。提示拨测时最好把软电话和 CentOS 7.9 放在同一个网段或者确认两端 UDP 端口没有防火墙拦截否则很容易出现“注册成功但通话没声音”的情况。6. 实测中的编译坑与运行期隐患6.1 编译链路踩坑实录第一类坑是 configure 阶段报缺库。报错关键字通常是cannot find、no such file or directory、checking for ... not found。比如提示找不到uuid.h那就是缺libuuid-devel找不到ssl.h就是缺openssl-devel。按第 2.2 节的命令列表装完后绝大部分问题都能解决。如果提示缺一些不常用的库我的做法是先看它是哪个模块要用不重要的直接把 modules.conf 里对应模块注释掉不折腾。第二类坑是 make 阶段机器被“Killed”。这在我第一次部署时出现过当时看到终端突然断掉还以为代码有问题后来查dmesg才发现是 OOM。小内存机器一定控制并行度make -j1虽然慢但稳。编译期间最好别同时跑其他吃内存的服务比如 MySQL、Redis。第三类坑是编译某个模块失败常见于 mod_vpx、mod_openh264 这类依赖外部代码库的模块。遇到这种情况回到 modules.conf 注释掉它再重新 configure、make。对于测试环境音视频编码先依赖系统内置的 codec 就够了。6.2 运行期的坑和排查建议FreeSWITCH 编译成功后运行期我也踩过几个印象深刻的坑。最烦的是启动后进程秒退查日志发现是db目录无法写入原因是用户权限没对。这不算稀奇但每次换新机器都容易忘所以我习惯装完立刻用ls -l /usr/local/freeswitch/检查目录 owner。第二个是 IP 地址被 NAT 时导致注册失败或单通。FreeSWITCH 明确区分了 internal profile 和 external profile内网注册用 internal公网或跨网络通信要考虑 external 的 NAT 配置。如果你的系统放在内网后面带公网映射记得在 external 配置里把外网地址写清楚否则对端看到的 SIP Contact 是内网地址回包根本到不了。第三个是 fs_cli 连接不上的问题。如果fs_cli一直提示 connection refused大概率是 event socket 没有监听或者只监听了 127.0.0.1 而你从远程执行 fs_cli。默认 event socket 监听 127.0.0.1这是安全设计远程管理应该先 SSH 到服务器再执行而不是把 8021 端口直接暴露出去。6.3 升级替换别忘了备份配置文件最后说一个看似简单但经常出事的点升级。FreeSWITCH 升级时很多人直接make install覆盖旧版本结果新版本启动后分机全部掉线、配置失效。原因往往是旧版本里你改过的配置文件被新版本默认配置覆盖了或者数据库目录结构不兼容。我的习惯是升级前完整备份这几个目录cp -a /usr/local/freeswitch/conf /backup/freeswitch-conf-YYYYMMDD cp -a /usr/local/freeswitch/db /backup/freeswitch-db-YYYYMMDD cp -a /usr/local/freeswitch/store /backup/freeswitch-store-YYYYMMDD然后去源码目录切到新版本 tag重新 configure、make、make install。装完先不急着启动把备份的 conf 目录覆盖回去重点对比一下freeswitch.xml和vars.xml有没有新增必填项。升级后先跑一轮注册和呼叫测试再切真实业务流量。这样就算新版本有问题也能随时把旧进程拉起来回滚至少业务不会长时间中断。编译安装 FreeSWITCH 这件事说难其实也不难最难的部分往往不是编译本身而是你对系统环境和版本选择的把握。按这篇的顺序走下来CentOS 7.9 上跑起来一套可用的 FreeSWITCH 基本不会出大问题。等到你把它稳定跑起来之后再去折腾拨号计划、外呼线路、媒体转码这些高阶功能心里就有底了。

CentOS 7.9 源码编译安装 FreeSWITCH 全流程与避坑指南

相关推荐

测试环境云化实战：浏览器矩阵与按需调度

技能高考必刷题，（1）【程序设计】输入三角形的三条边，判断其能否构成三角形，如果可以，则判断出三角形的种类：等腰三角形、等边三角形、直角三角形或一般三角形。注意：输出分五种情况：“等边三角形\n“；

局域网离线考试系统技术架构与实战落地解析

更多资讯

2026年降AI率工具真实测评：10款改写工具的优劣与使用边界

BigBanana AI Director：一站式AI短剧与漫剧导演平台工程实践

BigBanana AI Director：工业级AI短剧与漫剧全流程制作实战指南

深入理解Spring三级缓存：循环依赖的机制、局限与排查实践

用编程思维打造个人知识体系：IoC、依赖注入与响应式学习实操指南

联邦学习赋能大模型WAF：破解数据孤岛与攻击变异难题

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？