---

0、 一个fs的web配置界面预览

对于需要通过图形化界面管理 FreeSWITCH 的场景，可直接访问以下 Web 配置界面。

01、 Web 配置界面预览

界面地址	备用地址	登录信息
http://myfs.f3322.net:8020/	http://www.fspbx.cn/	用户名：admin密码：admin

02、 Web界面安装参考

若需自行部署 FreeSWITCH 图形化界面，包含 Docker、脚本、ISO 镜像三种安装方式，适配不同系统环境：

• 安装指南地址：https://blog.csdn.net/jia198810/article/details/137820796
• 核心安装方式概览：

1. Docker 安装：快速部署；
2. 脚本安装：适配 Almalinux、RockyLinux、Debian、Ubuntu 、欧拉等系统，提供一键安装命令，安装后需重启初始化；
3. ISO 镜像安装：基于 Almalinux制作的镜像，刻录到 U 盘或光盘后可自动安装，适合全新服务器部署。

---

1、user-agent-filter

当部署的freeswitch环境中的SIP 客户端类型固定时，我们可以利用 user-agent-filter 功能，仅允许特定 User-Agent 的设备注册，从而有效防止未知或恶意客户端接入，提升系统安全性。

SIP 协议本身是开放的，任何符合标准的客户端都可以尝试向 FreeSWITCH 发起注册请求。虽然可以通过用户名/密码认证进行基本防护，但在以下场景中，仅靠密码仍存在风险：

• 弱密码被暴力破解
• 已泄露的账号被第三方 UA 工具滥用
• 非授权设备，擅自接入内网

而如果你的系统只使用特定客户端（例如：内部开发的 客户端），那么完全可以基于 User-Agent 字段做白名单过滤，实现“双重验证”——既验身份，也验设备类型。

FreeSWITCH 的 mod_sofia 模块支持这一功能，通过 user-agent-filter 参数即可实现。

2、修改 Sofia Profile 配置

2.1. 定位配置文件

通常，Sofia 的配置位于：

/usr/local/freeswitch/conf/sip_profiles/internal.xml

（根据你的安装路径和 profile 名称可能不同，如 external.xml）

2.2. 添加 user-agent-filter 参数

在 <profile> 标签下，加入如下参数：

<param name="user-agent-filter" value="xxx"/>

完整示例片段：

<profile name="internal">
  <gateways>
    <!-- your gateways -->
  </gateways>

  <aliases>
    <!-- your aliases -->
  </aliases>

  <domains>
    <domain name="all" alias="false" parse="true"/>
  </domains>

  <settings>
    <!-- 其他参数... -->
    <!-- 关键配置：只允许指定 User-Agent -->
    <!-- 
	  1、模糊匹配（子串包含）  
	  只要注册请求中的 User-Agent 字符串 **包含** 配置中的任意关键词，即视为合法。  
	  优点：配置简单，兼容性强。  
	  风险：可能被伪造 UA 绕过（例如 "FakeMicroSIP" 也会匹配成功）。  
	-->
   <param name="user-agent-filter" value="MicroSIP|eyeBeam|Linphone-Desktop"/>


	<!-- 
	  2、前缀匹配（推荐用于带版本号但版本不固定的场景）  
	  要求 User-Agent **以指定字符串开头**（使用 ^ 锚定），适用于官方客户端 UA 结构稳定、但版本号动态变化的情况。  
	  示例：  
	    - "MicroSIP/3.20"  
	    - "Linphone-Desktop/5.3.1"  
	    - "MyMicroSIP" （不以 MicroSIP 开头）  
	  安全性与灵活性兼顾，**推荐大多数生产环境使用**。  
	-->
   <param name="user-agent-filter" value="^(MicroSIP|eyeBeam|Linphone-Desktop)"/>
  
  <!-- 
  【3】精确匹配（仅适用于 UA 完全固定不变的场景）  
  要求 User-Agent **完全等于** 配置值（使用 ^ 和 $ 锚定首尾）。  
  适用场景极少——通常只有测试设备或高度定制的嵌入式终端才会使用固定 UA。  
  一旦客户端升级导致 UA 变化，将立即无法注册。  
  示例：  
    - "MicroSIP/3.21.6"  
    - "MicroSIP/3.22.0" （版本不同，匹配失败）  
	-->
	<param name="user-agent-filter" value="^(MicroSIP/3.21.6|eyeBeam release 1100l stamp 	46320|Linphone-Desktop/5.3.1)$"/>

    <!-- 可选：开启认证失败日志，便于调试 -->
    <param name="log-auth-failures" value="true"/>
  </settings>
</profile>

---

不同匹配模式的选择：模糊匹配 vs 前缀匹配 vs 精确匹配，在 user-agent-filter 中，正则表达式的写法决定了匹配的严格程度。根据客户端 UserAgent 的变化规律，可选择合适的匹配策略。

2.3. 重载配置并测试

测试的配置文件

    <param name="user-agent-filter" value="^(MicroSIP/3.21.6|eyeBeam|Linphone-Desktop)$"/>
    <param name="log-auth-failures" value="true"/>

重载 Sofia Profile

进入 FreeSWITCH CLI：

fs_cli

执行重载命令（假设 profile 名为 internal）：

sofia profile internal rescan
# 或更彻底地重启
sofia profile internal restart

测试允许的客户端

使用 MicroSIP/3.21.6尝试注册：

✅ 预期结果：注册成功
✅ 日志（若开启 debug）：

2025-12-13 11:50:15.863583 100.00% [DEBUG] sofia_reg.c:3353 SIP auth OK (REGISTER) due to user-agent-filter.  Filter "^(MicroSIP/3.21.6|eyeBeam|Linphone-Desktop)$" User-Agent "MicroSIP/3.21.6"

测试禁止的客户端

使用其他 UA（如 eyebeam和linphone）注册：

❌ 预期结果：返回 403 Forbidden，注册失败
⚠️ 日志（需开启 log-auth-failures）：

2025-12-13 11:45:29.703515 100.00% [WARNING] sofia_reg.c:3359 SIP auth failure (REGISTER) due to user-agent-filter.  Filter "^(MicroSIP/3.21.6|eyeBeam|Linphone-Desktop)$" User-Agent "eyeBeam release 1100l stamp 46320"

祝君成功，好运连连，牛气冲天