Windows系统下安装与配置FreeSWITCH完整指南

本文提供在 Windows 系统上安装 FreeSWITCH 的完整步骤涵盖下载、安装、配置、启动测试以及可能遇到问题的解决方案帮助你顺利完成开发环境的搭建。一、环境准备与下载1.1 系统要求项目要求操作系统Windows 7/8/10/11Windows Server 2012架构64位推荐/ 32位内存至少 2GB推荐 4GB磁盘空间至少 2GB权限管理员权限安装和运行必需1.2 下载安装包FreeSWITCH 官方提供预编译的 Windows 安装包MSI 格式下载地址官方下载页面http://files.freeswitch.org/windows/installer/选择适合你系统的版本FreeSWITCH-1.10.x-x64.msi64位版本推荐FreeSWITCH-1.6.x-win32.msi32位版本注意文件名中的数字代表版本号建议选择最新的稳定版本。二、安装 FreeSWITCH2.1 运行安装程序1双击安装包然后点击弹出窗口里的【Next】按钮2选择安装类型① 推荐选择 Complete完整安装包含所有核心组件和声音文件② Custom 模式可自定义安装路径和组件3默认安装路径C:\Program Files\FreeSWITCH\⚠️ 安装路径中不要包含空格否则可能导致某些模块加载失败4等待安装完成2.2 验证安装安装完成后进入安装目录三、首次启动与配置3.1 以管理员身份启动重要FreeSWITCH 必须拥有管理员权限才能正常绑定端口和运行 。方式一直接运行控制台右键 FreeSwitchConsole.exe → 以管理员身份运行方式二命令行启动# 以管理员身份打开 CMD 或 PowerShell cd C:\Program Files\FreeSWITCH FreeSwitchConsole.exe成功启动后你会看到类似以下输出3.2 配置 WebSocket 支持用于 SIP.js为了支持浏览器的 SIP.js 连接需要启用 WebSocket 支持。编辑配置文件C:\Program Files\FreeSWITCH\conf\sip_profiles\internal.xml找到并确保以下配置存在默认已配置!-- WebSocket 支持未加密 -- param namews-binding value:5066/ !-- WebSocket 安全支持需证书本地测试可暂不启用 -- !-- param namewss-binding value:7443/ --3.3 默认分机账号FreeSWITCH 默认预置了 20 个分机账号1000-1019密码均为1234。如果需要添加更多分机1进入conf\directory\default\目录2复制1000.xml并重命名为1020.xml3将文件中的1000全部替换为10204在 FreeSWITCH 控制台执行reloadxml使配置生效四、测试通话4.1 安装 SIP 软电话为了测试 FreeSWITCH 是否正常工作需要安装一个 SIP 软电话客户端。推荐以下免费软件软件说明MicroSIP轻量级开源推荐Zoiper功能丰富免费版可用X-Lite经典软电话需官网下载4.2 配置软电话连接以 MicroSIP 为例1打开软件进入账户设置2添加新账户填写以下信息① 用户名1000或 1001、1002 等② 密码1234③ 域名/IP你的局域网 IP保存后状态应显示为已注册或绿色图标4.3 进行通话测试方案一用两个软电话如 1000 呼叫 1001方案二用软电话呼叫 FreeSWITCH 默认会议号9664进入测试会议若通话成功说明 FreeSWITCH 运行正常可以开始集成 SIP.js 了。五、常见问题及解决方案5.1 启动失败端口冲突1问题现象① 控制台窗口闪退② 日志中出现Address already in use或bind failed2原因默认端口5060SIP或8021ESL 管理端口被其他程序占用。3解决方案步骤1检查端口占用netstat -ano | findstr :5060 netstat -ano | findstr :8021输出示例TCP 0.0.0.0:5060 0.0.0.0:0 LISTENING 4567最后一列4567是占用端口的进程 PID。步骤2终止冲突进程taskkill /PID 4567 /F步骤3备选修改 FreeSWITCH 端口编辑conf/sip_profiles/internal.xml!-- 修改默认端口 5060 为其他值如 5070 -- param namesip-port value5070/编辑conf/autoload_configs/event_socket.conf.xmlparam namelisten-port value8031/5.2 启动后立即闪退1问题现象双击 FreeSwitchConsole.exe 后窗口一闪而过。2可能原因与解决方案原因解决方案未以管理员身份运行右键 → “以管理员身份运行”Visual C 运行库缺失安装 VC Redistributable安装路径包含空格重新安装到无空格的路径如C:\FreeSWITCH\防病毒软件拦截将 FreeSWITCH 目录加入杀毒软件白名单5.3 客户端注册失败408 Timeout1问题现象软电话注册时提示 408 Request Timeout。2解决方案① 检查防火墙Windows 防火墙可能阻止了 SIP 端口打开Windows Defender 防火墙 → “高级设置”添加入站规则允许 UDP 5060-5090 端口② 以管理员权限运行 FreeSWITCH③ 检查端口监听状态netstat -an | findstr :5060若无输出说明 FreeSWITCH 未正确监听。5.4 客户端注册失败403 Forbidden1问题现象提示 403 Forbidden 或 Authentication Failed。2原因用户名或密码错误。3解决方案① 确认分机密码是否正确默认分机密码为1234② 如需修改密码编辑conf/directory/default/1000.xml中的param namepassword value新密码/5.5 通话无声音1问题现象呼叫接通但双方听不到声音。2可能原因① 防火墙阻止 RTP 媒体端口默认 16384-32768② NAT 穿透问题局域网内通常正常3解决方案① 在防火墙中添加规则允许 UDP 16384-32768 端口② 启动时添加-nonat参数跳过 NAT 检测 FreeSwitchConsole.exe -nonat5.6 声音文件缺失1问题现象执行 IVR 或会议功能时提示找不到声音文件。2解决方案① 下载并安装声音包从官方下载页面获取freeswitch-sounds-*.exe并安装② 或在线获取声音文件在控制台执行load mod_say_zh加载中文语音模块六、后台运行与常用命令6.1 后台模式启动如果不想保留控制台窗口可以以后台模式启动# 后台启动无控制台 FreeSwitchConsole.exe -nc # 后台启动 跳过 NAT 检测 FreeSwitchConsole.exe -nc -nonat6.2 连接控制台fs_cli后台模式启动后使用fs_cli连接cd C:\Program Files\FreeSWITCH fs_cli.exe默认连接地址127.0.0.1:8021密码为ClueCon。6.3 常用控制台命令命令说明reloadxml重新加载 XML 配置文件sofia status profile internal reg查看已注册的分机status查看系统状态show channels查看当前通话version显示版本信息shutdown关闭 FreeSWITCH6.4 设置 Windows 环境变量用于调试如需启用 SIP 协议调试可在启动前设置环境变量 set SOFIA_DEBUG9 set TPORT_LOG1 FreeSwitchConsole.exe调试日志会输出到控制台帮助排查信令问题。七、快速故障排查流程图启动 FreeSWITCH │ ▼ ┌─────────────────┐ │ 窗口是否正常显示│ └─────────────────┘ │ ├── 否 ──▶ 检查是否以管理员运行 │ │ │ ▼ │ 检查 VC 运行库 │ │ │ ▼ │ 检查安装路径无空格 │ ▼ 是 ┌─────────────────┐ │ 是否有 bind failed 错误 │ └─────────────────┘ │ ├── 是 ──▶ netstat -ano 查端口占用 │ │ │ ▼ │ 终止占用进程 或 修改配置文件端口 │ ▼ 否 ┌─────────────────┐ │ 软电话能否注册 │ └─────────────────┘ │ ├── 否 ──▶ 检查防火墙是否允许 5060 端口 │ │ │ ▼ │ 确认分机密码是否正确默认 1234 │ │ │ ▼ │ 确认 FreeSWITCH 正在运行 │ ▼ 是 ┌─────────────────┐ │ 通话测试成功 │ └─────────────────┘完成以上步骤你的 Windows 开发环境就准备就绪了。如果遇到其他问题欢迎继续交流