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

本文提供在 Windows 系统上安装 FreeSWITCH 的完整步骤，涵盖下载、安装、配置、启动测试，以及可能遇到问题的解决方案，帮助你顺利完成开发环境的搭建。

一、环境准备与下载

1.1 系统要求

项目	要求
操作系统	Windows 7/8/10/11，Windows Server 2012+
架构	64位（推荐）/ 32位
内存	至少 2GB（推荐 4GB+）
磁盘空间	至少 2GB
权限	管理员权限（安装和运行必需）

1.2 下载安装包

FreeSWITCH 官方提供预编译的 Windows 安装包（MSI 格式），下载地址：

官方下载页面 ：http://files.freeswitch.org/windows/installer/

选择适合你系统的版本：

FreeSWITCH-1.10.x-x64.msi：64位版本（推荐）

FreeSWITCH-1.6.x-win32.msi：32位版本

注意：文件名中的数字代表版本号，建议选择最新的稳定版本。

二、安装 FreeSWITCH

2.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 name="ws-binding" value=":5066"/>

<!-- WebSocket 安全支持（需证书，本地测试可暂不启用） -->
<!-- <param name="wss-binding" value=":7443"/> -->

3.3 默认分机账号

FreeSWITCH 默认预置了 20 个分机账号（1000-1019），密码均为 1234 。

如果需要添加更多分机：

1）进入 conf\directory\default\ 目录

2）复制 1000.xml 并重命名为 1020.xml

3）将文件中的 1000 全部替换为 1020

4）在 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 failed

2）原因

默认端口 5060（SIP）或 8021（ESL 管理端口）被其他程序占用。

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 name="sip-port" value="5070"/>

编辑 conf/autoload_configs/event_socket.conf.xml：

复制代码

<param name="listen-port" value="8031"/>

5.2 启动后立即闪退

1）问题现象

双击 FreeSwitchConsole.exe 后窗口一闪而过。

2）可能原因与解决方案

原因	解决方案
未以管理员身份运行	右键 → "以管理员身份运行"
Visual C++ 运行库缺失	安装 VC++ Redistributable
安装路径包含空格	重新安装到无空格的路径，如 `C:\FreeSWITCH\`
防病毒软件拦截	将 FreeSWITCH 目录加入杀毒软件白名单

5.3 客户端注册失败（408 Timeout）

1）问题现象

软电话注册时提示 408 Request Timeout。

2）解决方案

① 检查防火墙：Windows 防火墙可能阻止了 SIP 端口

打开"Windows Defender 防火墙" → "高级设置"

添加入站规则：允许 UDP 5060-5090 端口

② 以管理员权限运行 FreeSWITCH

③ 检查端口监听状态：

复制代码

netstat -an | findstr :5060

若无输出，说明 FreeSWITCH 未正确监听。

5.4 客户端注册失败（403 Forbidden）

1）问题现象

提示 403 Forbidden 或 Authentication Failed。

2）原因

用户名或密码错误。

3）解决方案

① 确认分机密码是否正确（默认分机密码为 1234）

② 如需修改密码，编辑 conf/directory/default/1000.xml 中的 <param name="password" value="新密码"/>

5.5 通话无声音

1）问题现象

呼叫接通但双方听不到声音。

2）可能原因

① 防火墙阻止 RTP 媒体端口（默认 16384-32768）

② NAT 穿透问题（局域网内通常正常）

3）解决方案

① 在防火墙中添加规则，允许 UDP 16384-32768 端口

② 启动时添加 -nonat 参数跳过 NAT 检测：

复制代码

FreeSwitchConsole.exe -nonat

5.6 声音文件缺失

1）问题现象

执行 IVR 或会议功能时提示找不到声音文件。

2）解决方案

① 下载并安装声音包：从官方下载页面获取 freeswitch-sounds-*.exe 并安装

② 或在线获取声音文件：在控制台执行 load mod_say_zh 加载中文语音模块

六、后台运行与常用命令

6.1 后台模式启动

如果不想保留控制台窗口，可以以后台模式启动：

复制代码

# 后台启动（无控制台）
FreeSwitchConsole.exe -nc

# 后台启动 + 跳过 NAT 检测
FreeSwitchConsole.exe -nc -nonat

6.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`	关闭 FreeSWITCH

6.4 设置 Windows 环境变量（用于调试）

如需启用 SIP 协议调试，可在启动前设置环境变量：

复制代码

set SOFIA_DEBUG=9
set TPORT_LOG=1
FreeSwitchConsole.exe

调试日志会输出到控制台，帮助排查信令问题。

七、快速故障排查流程图

复制代码

启动 FreeSWITCH
      │
      ▼
┌─────────────────┐
│ 窗口是否正常显示？│
└─────────────────┘
      │
      ├── 否 ──▶ 检查是否以管理员运行
      │              │
      │              ▼
      │         检查 VC++ 运行库
      │              │
      │              ▼
      │         检查安装路径无空格
      │
      ▼ 是
┌─────────────────┐
│ 是否有 bind failed 错误？ │
└─────────────────┘
      │
      ├── 是 ──▶ netstat -ano 查端口占用
      │              │
      │              ▼
      │         终止占用进程 或 修改配置文件端口
      │
      ▼ 否
┌─────────────────┐
│ 软电话能否注册？ │
└─────────────────┘
      │
      ├── 否 ──▶ 检查防火墙是否允许 5060 端口
      │              │
      │              ▼
      │         确认分机密码是否正确（默认 1234）
      │              │
      │              ▼
      │         确认 FreeSWITCH 正在运行
      │
      ▼ 是
┌─────────────────┐
│   通话测试成功！ │
└─────────────────┘