Ubuntu 24.04 安装 FreeSWITCH 完整教程

Ubuntu 24.04 安装 FreeSWITCH 完整教程（国内环境）

一、系统准备

1. 检查系统版本

# 查看系统版本
lsb_release -a

# 输出应该显示：
# Distributor ID: Ubuntu
# Description: Ubuntu 24.04 LTS
# Release: 24.04
# Codename: noble

2. 更新系统（需要 sudo 权限）

# 更新软件包列表
sudo apt-get update

# 升级已安装的软件包（可选）
sudo apt-get upgrade -y

二、安装 FreeSWITCH（完整步骤）

方法一：使用官方仓库安装（推荐）

# ========== 步骤 1: 安装必要工具 ==========
sudo apt-get install -y wget gnupg2 software-properties-common

# ========== 步骤 2: 添加 FreeSWITCH GPG 密钥 ==========
# 使用国内可访问的官方文件服务器
wget -O – https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | sudo gpg –dearmor -o /usr/share/keyrings/freeswitch-archive-keyring.gpg

# ========== 步骤 3: 添加 FreeSWITCH 软件源 ==========
# Ubuntu 24.04 的代号是 noble
echo "deb [signed-by=/usr/share/keyrings/freeswitch-archive-keyring.gpg] https://files.freeswitch.org/repo/deb/debian-release/ noble main" | sudo tee /etc/apt/sources.list.d/freeswitch.list

# ========== 步骤 4: 更新软件源 ==========
sudo apt-get update

# ========== 步骤 5: 安装 FreeSWITCH ==========
# 安装完整版（推荐）
sudo apt-get install -y freeswitch-meta-all

# 或者只安装核心组件
# sudo apt-get install -y freeswitch-meta-bare freeswitch-conf-vanilla freeswitch-mod-commands

# ========== 步骤 6: 安装音频文件（可选但推荐）==========
sudo apt-get install -y freeswitch-music-default freeswitch-sounds-en-us-callie

方法二：源码编译安装（如果仓库方式失败）

#!/bin/bash

# 下载预编译的 FreeSWITCH 压缩包

set -e

echo "=== 下载 FreeSWITCH 预编译包 ==="

# 创建工作目录
cd /tmp

# 下载预编译包
echo "1. 下载 FreeSWITCH 源码包…"
wget https://files.freeswitch.org/releases/freeswitch/freeswitch-1.10.11.-release.tar.gz

# 解压
echo "2. 解压…"
tar -zxvf freeswitch-1.10.11.-release.tar.gz
cd freeswitch-1.10.11.-release

# 安装编译依赖
echo "3. 安装编译依赖…"
sudo apt-get update
sudo apt-get install -y \\
build-essential cmake automake autoconf libtool-bin \\
pkg-config wget curl \\
libssl-dev zlib1g-dev libdb-dev unixodbc-dev \\
libncurses5-dev libexpat1-dev libgdbm-dev bison \\
libbison-dev libcurl4-openssl-dev libpcre3-dev \\
libspeex-dev libspeexdsp-dev libldns-dev \\
libedit-dev libtiff5-dev yasm libopus-dev \\
libsndfile1-dev libshout3-dev libmpg123-dev \\
libmp3lame-dev libsqlite3-dev libpq-dev \\
libmariadb-dev liblua5.3-dev uuid-dev

# 配置
echo "4. 配置编译选项…"
./configure –prefix=/usr/local/freeswitch

# 编译
echo "5. 编译（使用 $(nproc) 个 CPU 核心）…"
make -j$(nproc)

# 安装
echo "6. 安装…"
sudo make install

# 安装配置和音频
echo "7. 安装配置文件和音频…"
sudo make cd-sounds-install cd-moh-install
sudo make samples

echo ""
echo "✅ 安装完成！"

三、配置 FreeSWITCH 用户和权限

# ========== 创建系统用户 ==========
# 检查用户是否已存在
if ! id -u freeswitch > /dev/null 2>&1; then
sudo groupadd -r freeswitch
sudo useradd -r -g freeswitch -d /var/lib/freeswitch -s /bin/false freeswitch
echo "freeswitch 用户创建成功"
else
echo "freeswitch 用户已存在"
fi

# ========== 设置目录权限 ==========
# 如果是仓库安装
sudo chown -R freeswitch:freeswitch /etc/freeswitch
sudo chown -R freeswitch:freeswitch /var/lib/freeswitch
sudo chown -R freeswitch:freeswitch /var/log/freeswitch
sudo chown -R freeswitch:freeswitch /usr/share/freeswitch
sudo chmod -R o-rwx /etc/freeswitch

# 如果是编译安装
# sudo chown -R freeswitch:freeswitch /usr/local/freeswitch
# sudo chmod -R o-rwx /usr/local/freeswitch

四、配置 systemd 服务

仓库安装（服务已自动配置）

# 检查服务文件是否存在
ls -l /lib/systemd/system/freeswitch.service

编译安装（需要手动创建服务）

# 创建 systemd 服务文件
sudo tee /etc/systemd/system/freeswitch.service > /dev/null <<'EOF'
[Unit]
Description=FreeSWITCH open source telephony platform
After=syslog.target network.target local-fs.target

[Service]
Type=forking
PIDFile=/usr/local/freeswitch/run/freeswitch.pid
Environment="DAEMON_OPTS=-nonat"
EnvironmentFile=-/etc/default/freeswitch
ExecStartPre=/bin/mkdir -p /usr/local/freeswitch/run
ExecStart=/usr/local/freeswitch/bin/freeswitch -u freeswitch -g freeswitch -ncwait $DAEMON_OPTS
TimeoutSec=45s
Restart=always
WorkingDirectory=/usr/local/freeswitch
User=freeswitch
Group=freeswitch
LimitCORE=infinity
LimitNOFILE=100000
LimitNPROC=60000
LimitSTACK=250000
LimitRTPRIO=infinity
LimitRTTIME=infinity
IOSchedulingClass=realtime
IOSchedulingPriority=2
CPUSchedulingPolicy=rr
CPUSchedulingPriority=89

[Install]
WantedBy=multi-user.target
EOF

# 重新加载 systemd 配置
sudo systemctl daemon-reload

五、修改默认密码（重要安全步骤）

# ========== 编辑配置文件 ==========
# 仓库安装
sudo vi /etc/freeswitch/vars.xml

# 编译安装
# sudo vi /usr/local/freeswitch/conf/vars.xml

# 找到以下行（按 / 搜索 "default_password"）
# <X-PRE-PROCESS cmd="set" data="default_password=1234"/>

# 修改为强密码（例如）：
# <X-PRE-PROCESS cmd="set" data="default_password=YourStrongPassword123!@#"/>

# 保存退出（按 ESC，输入 :wq）

六、配置防火墙

# ========== 检查防火墙状态 ==========
sudo ufw status

# 如果防火墙已启用，添加规则
sudo ufw allow 5060/tcp comment 'FreeSWITCH SIP TCP'
sudo ufw allow 5060/udp comment 'FreeSWITCH SIP UDP'
sudo ufw allow 5080/tcp comment 'FreeSWITCH WS'
sudo ufw allow 5081/tcp comment 'FreeSWITCH WSS'
sudo ufw allow 8021/tcp comment 'FreeSWITCH ESL'
sudo ufw allow 16384:32768/udp comment 'FreeSWITCH RTP'

# 重载防火墙
sudo ufw reload

# 查看规则
sudo ufw status numbered

七、启动 FreeSWITCH 服务

# ========== 启动服务 ==========
sudo systemctl start freeswitch

# ========== 设置开机自启 ==========
sudo systemctl enable freeswitch

# ========== 查看服务状态 ==========
sudo systemctl status freeswitch

# 应该看到 "active (running)" 状态

八、验证安装

1. 检查进程

# 查看 FreeSWITCH 进程
ps aux | grep freeswitch

# 查看端口监听
sudo ss -tulnp | grep freeswitch
# 或
sudo netstat -tulnp | grep freeswitch

# 应该看到：
# 5060 – SIP
# 8021 – ESL (Event Socket)
# 16384-32768 – RTP

2. 连接到控制台

# 连接到 FreeSWITCH 控制台
fs_cli

# 或指定连接参数
# fs_cli -H 127.0.0.1 -P 8021 -p ClueCon

3. 执行测试命令

# 在 fs_cli 控制台中执行：

# 查看版本
version

# 查看状态
status

# 查看 Sofia SIP 配置
sofia status

# 查看内部配置文件注册信息
sofia status profile internal reg

# 查看模块
show modules

# 退出控制台
/exit
# 或按 Ctrl+D

九、完整一键安装脚本

将以下内容保存为 install_freeswitch_ubuntu24.sh：

#!/bin/bash

# FreeSWITCH Ubuntu 24.04 一键安装脚本（国内环境）
# 使用方法: sudo bash install_freeswitch_ubuntu24.sh

set -e

# 颜色定义
RED='\\033[0;31m'
GREEN='\\033[0;32m'
YELLOW='\\033[1;33m'
NC='\\033[0m' # No Color

# 日志函数
log_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}

log_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}

log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}

# 检查是否为 root 用户
if [ "$EUID" -ne 0 ]; then
log_error "请使用 root 权限运行此脚本"
echo "使用方法: sudo bash $0"
exit 1
fi

log_info "开始安装 FreeSWITCH on Ubuntu 24.04…"

# 检测系统版本
if [ -f /etc/os-release ]; then
. /etc/os-release
if [ "$ID" != "ubuntu" ] || [ "$VERSION_ID" != "24.04" ]; then
log_warn "检测到系统为: $ID $VERSION_ID"
log_warn "此脚本专为 Ubuntu 24.04 设计，继续安装可能遇到问题"
read -p "是否继续？(y/n): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
exit 1
fi
fi
else
log_error "无法检测系统版本"
exit 1
fi

# 更新系统
log_info "更新系统软件包…"
apt-get update

# 安装基础依赖
log_info "安装基础依赖…"
apt-get install -y wget gnupg2 software-properties-common curl

# 添加 FreeSWITCH GPG 密钥
log_info "添加 FreeSWITCH GPG 密钥…"
wget -O – https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | gpg –dearmor -o /usr/share/keyrings/freeswitch-archive-keyring.gpg

# 添加 FreeSWITCH 软件源
log_info "添加 FreeSWITCH 软件源…"
echo "deb [signed-by=/usr/share/keyrings/freeswitch-archive-keyring.gpg] https://files.freeswitch.org/repo/deb/debian-release/ noble main" > /etc/apt/sources.list.d/freeswitch.list

# 更新软件源
log_info "更新软件源…"
apt-get update

# 安装 FreeSWITCH
log_info "安装 FreeSWITCH（这可能需要几分钟）…"
DEBIAN_FRONTEND=noninteractive apt-get install -y freeswitch-meta-all

# 安装音频文件
log_info "安装音频文件…"
apt-get install -y freeswitch-music-default freeswitch-sounds-en-us-callie

# 创建 freeswitch 用户
if ! id -u freeswitch > /dev/null 2>&1; then
log_info "创建 freeswitch 系统用户…"
groupadd -r freeswitch
useradd -r -g freeswitch -d /var/lib/freeswitch -s /bin/false freeswitch
else
log_info "freeswitch 用户已存在"
fi

# 设置权限
log_info "设置目录权限…"
chown -R freeswitch:freeswitch /etc/freeswitch
chown -R freeswitch:freeswitch /var/lib/freeswitch
chown -R freeswitch:freeswitch /var/log/freeswitch
chown -R freeswitch:freeswitch /usr/share/freeswitch
chmod -R o-rwx /etc/freeswitch

# 修改默认密码
log_info "修改默认密码…"
NEW_PASSWORD="FS$(date +%s)@Pass"
sed -i "s/default_password=1234/default_password=${NEW_PASSWORD}/g" /etc/freeswitch/vars.xml
log_warn "默认密码已修改为: ${NEW_PASSWORD}"
log_warn "请记录此密码！配置文件位置: /etc/freeswitch/vars.xml"

# 配置防火墙
log_info "配置防火墙规则…"
if command -v ufw &> /dev/null; then
ufw –force enable
ufw allow 5060/tcp comment 'FreeSWITCH SIP TCP'
ufw allow 5060/udp comment 'FreeSWITCH SIP UDP'
ufw allow 5080/tcp comment 'FreeSWITCH WS'
ufw allow 5081/tcp comment 'FreeSWITCH WSS'
ufw allow 8021/tcp comment 'FreeSWITCH ESL'
ufw allow 16384:32768/udp comment 'FreeSWITCH RTP'
ufw reload
log_info "防火墙规则已配置"
else
log_warn "未检测到 ufw，跳过防火墙配置"
fi

# 启动服务
log_info "启动 FreeSWITCH 服务…"
systemctl daemon-reload
systemctl enable freeswitch
systemctl start freeswitch

# 等待服务启动
sleep 5

# 检查服务状态
if systemctl is-active –quiet freeswitch; then
log_info "FreeSWITCH 服务启动成功！"
else
log_error "FreeSWITCH 服务启动失败"
log_error "请检查日志: journalctl -u freeswitch -n 50"
exit 1
fi

# 显示安装信息
echo ""
echo "=========================================="
log_info "FreeSWITCH 安装完成！"
echo "=========================================="
echo ""
echo "📍 安装信息："
echo " 版本: $(fs_cli -x 'version' 2>/dev/null | head -n1 || echo '无法获取')"
echo " 配置目录: /etc/freeswitch/"
echo " 日志目录: /var/log/freeswitch/"
echo " 数据目录: /var/lib/freeswitch/"
echo ""
echo "🔐 安全信息："
echo " 默认密码: ${NEW_PASSWORD}"
echo " 配置文件: /etc/freeswitch/vars.xml"
echo ""
echo "🎯 常用命令："
echo " 连接控制台: fs_cli"
echo " 查看状态: systemctl status freeswitch"
echo " 查看日志: tail -f /var/log/freeswitch/freeswitch.log"
echo " 重启服务: systemctl restart freeswitch"
echo ""
echo "📚 控制台常用命令："
echo " status – 查看系统状态"
echo " sofia status – 查看 SIP 状态"
echo " show channels – 查看通话通道"
echo " version – 查看版本信息"
echo " /exit – 退出控制台"
echo ""
echo "=========================================="

# 测试连接
log_info "测试 FreeSWITCH 连接…"
if fs_cli -x "status" &> /dev/null; then
log_info "✅ FreeSWITCH 运行正常！"
else
log_warn "⚠️ 无法连接到 FreeSWITCH，请检查服务状态"
fi

echo ""
log_info "安装脚本执行完毕！"

使用一键安装脚本

# 1. 下载或创建脚本
nano install_freeswitch_ubuntu24.sh

# 2. 粘贴上面的脚本内容，保存退出（Ctrl+O, Enter, Ctrl+X）

# 3. 添加执行权限
chmod +x install_freeswitch_ubuntu24.sh

# 4. 执行安装
sudo ./install_freeswitch_ubuntu24.sh

十、常用管理命令

服务管理（需要 sudo）

# 启动服务
sudo systemctl start freeswitch

# 停止服务
sudo systemctl stop freeswitch

# 重启服务
sudo systemctl restart freeswitch

# 查看状态
sudo systemctl status freeswitch

# 查看实时日志
sudo journalctl -u freeswitch -f

# 查看最近 100 行日志
sudo journalctl -u freeswitch -n 100

# 查看日志文件
sudo tail -f /var/log/freeswitch/freeswitch.log

控制台命令（不需要 sudo，但需要 freeswitch 运行）

# 连接控制台
fs_cli

# 在控制台中执行命令
status
sofia status
show channels
show calls
reloadxml

# 退出控制台
/exit

十一、常见问题排查

1. 服务无法启动

# 查看详细错误日志
sudo journalctl -u freeswitch -n 100 –no-pager

# 检查配置文件语法
sudo freeswitch -t

# 查看进程是否存在
ps aux | grep freeswitch

2. 端口被占用

# 检查 5060 端口
sudo lsof -i :5060

# 如果被占用，停止占用进程或修改 FreeSWITCH 端口

3. 权限问题

# 重新设置权限
sudo chown -R freeswitch:freeswitch /etc/freeswitch
sudo chown -R freeswitch:freeswitch /var/lib/freeswitch
sudo chown -R freeswitch:freeswitch /var/log/freeswitch

4. 无法连接 fs_cli

# 检查 8021 端口
sudo ss -tulnp | grep 8021

# 查看 ESL 配置
sudo cat /etc/freeswitch/autoload_configs/event_socket.conf.xml

十二、总结

✅ 需要管理员权限的操作：

❌ 不需要管理员权限的操作：

🎯 完整安装时间估算：

• 仓库安装：5-10 分钟
• 源码编译：20-40 分钟（取决于 CPU 性能）

安装完成后，FreeSWITCH 将以 freeswitch 用户身份运行，所有操作都需要通过 sudo 进行管理！

需要我帮你解决具体的安装问题吗？