AI Voice Platform 文档

外观

FreeSWITCH 容器化部署与配置指南 ​

本目录包含基于 WSL /data/docker_fs_server 封装的 FreeSWITCH 容器化服务全套生产资产与配置规范。这里保存的是可直接落地的运行时归档、部署资产与运维文档，不是已废止的源码交付包。

底层镜像基于 Debian 13 (Trixie) 编译并打包了 FreeSWITCH 1.11.2 运行时，内置自研的 mod_audio_fork 实时语音流式识别旁路模块、mod_shout 流式 TTS 播放模块、录音静态托管 Nginx、以及 4 个核心底层 C 共享库资产，支持在任何 Linux 宿主机上一键秒级启动与热重载。

专题文档导航 ​

为方便查阅与精细化维护，本指南按领域拆分为以下独立专题文档（位于 docs/ 子目录下）：

专题文档核心内容
🌐 网络模式、IP 绑定与 NAT / STUN 专题强制 Host 模式原理解析、ops_local_ip_v4/ops_db_dsn/esl_host 解耦宏体系、单点修改全局联动生效、XML 预处理器避坑、3 大典型场景（WSL/公网云服务器/WebRTC）对照表
📞 SIP Profiles 架构、配置与外呼网关专题Sofia UA 架构、internal.xml (5060/WebRTC) 与 external.xml (5080) 深度拆解、internal/example.xml 内部级联网关模板实战、外呼 SIP Trunk 网关配置与动态运维指令
🧩 核心模块库与实时 AI 语音集成专题80+ 个预编译模块全景分类表、mod_audio_fork 流式 ASR 分流 (sherpa-asr-server/funasr-asr-server/stream-vad-proxy)、mod_shout 流式 TTS 播放、mod_local_stream 背景音流混音、模块静态加载与运行时动态热管理
⚙️ 模块配置文件详解 (autoload_configs/)switch.conf.xml 核心并发与 PG DSN、local_stream.conf.xml 背景音与等待音流配置、shout.conf.xml、avmd.conf.xml、callcenter.conf.xml、opus.conf.xml 等 60+ 个配置全解与速查
🔌 业务集成、拨号计划与录音托管专题ESL 安全对接 (8021)、Outbound ESL 业务路由 (dialplan 接入 $${esl_host})、send_silence_when_idle=-1 防 NAT 丢包断流、RTP 端口规划、WebRTC 证书与 Nginx 录音托管

1. 压缩包概述与资产组成 ​

归档包名称：docker_fs_server.tar.gz（位于本目录下，压缩包约 20MB，解压展开约 61MB）。

解压后包含以下关键组件：

  1. FreeSWITCH 1.11.2-trixie：位于 freeswitch-install/，包含完整的 bin、etc（配置文件树，含 179 个 XML 配置文件，其中 137 个附带详尽精准中文参数注释与业务导读，覆盖率达 76.5%）、lib（80+ 个 .so 动态模块）、share（内置系统音频资产）与 var 运行状态目录；
  2. mod_audio_fork.so：位于 freeswitch-install/lib/freeswitch/mod/，用于将实时通话音频流无缝旁路推送到 sherpa-asr-server (10096) 或 funasr-asr-server (10099)（亦可通过 stream-vad-proxy:10093 前置代理实现毫秒级 VAD 打断与语音切段）；
  3. deps-lib/ 专有依赖库：预置 4 个平台专有底层 C/C++ 核心共享库（Debian 官方仓库无匹配包，镜像构建时直接注入 /usr/lib/）：
    • libks2.so.2：SignalWire 底层核心运行时库；
    • libsignalwire_client2.so.2：SignalWire C 客户端库；
    • libsofia-sip-ua.so.0.6.0：Sofia-SIP 协议栈核心动态库；
    • libspandsp.so.4.0.0：SpanDSP 信号处理与电信级音频/传真编解码库； (注：libwebsockets、libshout、libmp3lame、libmpg123 等通用运行时库已通过 Debian Trixie 官方 APT 源安装)；
  4. 音频资产与背景音开箱即用：
    • 运行包内已置系统保持音乐（freeswitch-install/share/freeswitch/sounds/music/，含 8k/16k/32k/48k 完整采样率）及标准英文提示音（en/）；
    • 包内已完整内置办公室环境背景音流配置（autoload_configs/local_stream.conf.xml 中已声明 ambient/office/8000 与 ambient/office/16000）及配套预置音频素材（freeswitch-install/share/freeswitch/sounds/ambient/office/{8000,16000}/），解压后开箱即用，无需额外独立配置或手动复制素材；
  5. Nginx 通话录音托管服务：编排 nginx:alpine 容器监听 8088 端口，只读映射 var/recordings，提供录音文件直接在线播放与下载；
  6. 容器自动化编排：Dockerfile、docker-compose.yml 与 docker-entrypoint.sh。

2. 压缩包解压与目录结构 ​

在目标 Linux 服务器执行解压：

bash
# 创建部署目录并解压
mkdir -p /data/docker_fs_server
tar -zxvf docker_fs_server.tar.gz -C /data/docker_fs_server
cd /data/docker_fs_server

解压后的标准目录结构如下：

text
docker_fs_server/
├── Dockerfile                         # FreeSWITCH 基础运行时镜像构建文件
├── docker-compose.yml                 # 容器编排 (Host 模式 + Nginx 录音服务)
├── docker-entrypoint.sh               # 容器初始化脚本 (自动处理权限与 PID 锁)
├── README.md                          # 部署与运维总览导航
├── docs/                              # 模块化专题文档目录
│   ├── network-and-nat.md             # 专题 1：网络与 NAT / STUN
│   ├── sip-profiles.md                # 专题 2：SIP Profiles 与外呼网关
│   ├── ai-and-modules.md              # 专题 3：核心模块与 AI 语音集成
│   ├── module-configs.md              # 专题 4：模块配置文件详解 (autoload_configs/)
│   └── integration-and-dialplan.md    # 专题 5：业务集成与拨号计划
├── deps-lib/                          # 4 个专有 C 共享库 (libks2, libsignalwire_client2, libsofia-sip-ua, libspandsp)
├── nginx/
│   └── conf.d/
│       └── recordings.conf            # Nginx 录音静态托管配置文件 (8088 端口)
└── freeswitch-install/                # FreeSWITCH 完整运行树 (挂载到容器内)
    ├── bin/                           # freeswitch, fs_cli 等核心二进制
    ├── etc/freeswitch/                # 配置文件目录 (179 个 XML 文件，137 个全量精细中文注释与业务导读)
    │   ├── autoload_configs/          # 模块级配置文件 (event_socket, switch, local_stream, modules 等)
    │   ├── dialplan/                  # 拨号计划 (default.xml, public.xml)
    │   ├── directory/                 # 分机用户目录 (default/1000.xml ~ 1019.xml)
    │   ├── sip_profiles/              # SIP 协议栈配置 (internal.xml, external.xml, internal/example.xml 等)
    │   ├── tls/                       # WebRTC / WSS / DTLS-SRTP 证书
    │   ├── freeswitch.xml             # 主配置入口
    │   └── vars.xml                   # 全局解耦宏变量 (ops_local_ip_v4, ops_db_dsn, esl_host 等)
    ├── lib/freeswitch/mod/            # 80+ 个预编译模块 (.so)
    ├── share/freeswitch/sounds/       # 内置系统音频与环境音资产
    │   ├── ambient/                   # 场景背景环境音目录 (由 mod_local_stream 驱动混音，内置 8k/16k 办公室底噪，开箱即用)
    │   └── music/                     # 等待音乐 (Hold Music，8k/16k/32k/48k 完整采样率)
    └── var/                           # 运行时数据 (db, log, run, recordings)

3. 极速启动与验证 ​

步骤 1：按需核对核心配置 ​

在启动前，请根据部署环境完成最基础的配置校准：

  1. 核心网络与服务解耦宏：参考 网络与 NAT 专题 修改 freeswitch-install/etc/freeswitch/vars.xml 中的核心变量 ops_local_ip_v4（局域网/公网 IP 单点修改，自动联动生效到 domain、external_rtp_ip 与 external_sip_ip），以及 esl_host（业务中台地址）与 ops_db_dsn（若启用 PostgreSQL 存储）；
  2. 分机默认密码：在 vars.xml 中修改 default_password；
  3. 会议背景音就绪说明：运行包已完整内置办公室环境背景音配置及 8k/16k 预置音频素材，local_stream://ambient/office/16000 与 8000 开箱即用，无需再执行额外的目录创建与文件复制步骤。如需替换或扩充自定义背景音，可直接向 freeswitch-install/share/freeswitch/sounds/ambient/office/{8000,16000}/ 放入单声道 WAV 文件并执行 fs_cli -x "reloadxml"；

步骤 2：构建镜像并启动容器 ​

bash
# 1. 构建镜像（基于 Debian 13 Trixie + 注入 deps-lib）
docker compose build

# 2. 后台启动服务 (freeswitch + fs-recordings-nginx)
docker compose up -d

# 3. 查看容器运行状态
docker compose ps

步骤 3：健康检查与连通性验证 ​

bash
# 1. 查看 FreeSWITCH 核心运行状态
docker exec -it fs-app fs_cli -x "status"

# 2. 检查关键 AI 模块 mod_audio_fork 是否成功加载
docker exec -it fs-app fs_cli -x "module_exists mod_audio_fork"
# 正常应返回: true

# 3. 查看 SIP Profile 监听状态
docker exec -it fs-app fs_cli -x "sofia status"

# 4. 测试 Nginx 录音服务端口 (8088)
curl -I http://127.0.0.1:8088/recordings/

4. 核心端口与防火墙放行清单 ​

由于采用 network_mode: "host"，请确保宿主机或云安全组已放行以下端口：

端口 / 协议服务 / 模块核心用途访问来源
5060/UDP, 5060/TCPSofia internal内部分机 SIP 注册与信令办公网 / 局域网 / 软电话
5080/UDP, 5080/TCPSofia external运营商 SIP Trunk 中继与公网进线运营商 / PSTN 网关
5066/TCPWebRTC WS浏览器 SIP over WebSocket (未加密)内部 Web 前端
7443/TCPWebRTC WSS浏览器 SIP over Secure WebSocket公网 Web 浏览器
8021/TCPInbound ESLFreeSWITCH 管理控制端口仅限 callflow-esl 所在主机 (严格限制)
30000-30199/UDPRTP 媒体流动态语音 RTP 传输通道必须全网放行 (0.0.0.0/0)
8088/TCPNginx Recordings通话录音 HTTP 静态拉取与播放业务系统 Web 端

5. 配置生效机制与热重载指南 ​

得益于 ./freeswitch-install 目录与容器内部的双向实时挂载穿透：

变更场景是否需要重启容器？操作指令生效耗时
修改 XML 配置文件 (vars.xml, dialplan, directory 等)❌ 无需重启docker exec -it fs-app fs_cli -x "reloadxml"< 1 秒（零停机）
修改 SIP Profile 或网关 (sip_profiles/internal.xml 等)❌ 无需重启docker exec -it fs-app fs_cli -x "sofia profile internal rescan"< 1 秒
重新加载特定模块 (mod_audio_fork, mod_sofia 等)❌ 无需重启docker exec -it fs-app fs_cli -x "reload mod_audio_fork"< 1 秒
新增/更新扩展模块 (mod_xxx.so)❌ 无需重启拷贝 .so 到 lib/freeswitch/mod/ 后执行 fs_cli -x "load mod_xxx"< 1 秒
调整核心全局参数 / 环境变量 / 挂载配置 (docker-compose.yml, switch.conf.xml 核心端口)✅ 重启容器docker compose restart~ 2 秒
修改 Dockerfile / 底层 apt 依赖 / deps-lib 动态库✅ 重新构建docker compose build && docker compose up -d~ 10 秒

6. 常用运维指令速查表 ​

6.1 容器生命周期指令 ​

bash
# 后台启动
docker compose up -d

# 停止容器
docker compose stop

# 重启容器
docker compose restart

# 查看容器运行状态与健康检查
docker compose ps

# 查看实时日志（最后 100 行并持续追踪）
docker compose logs -f --tail=100 freeswitch

# 销毁容器（不丢失挂载的配置与数据）
docker compose down

6.2 fs_cli 核心诊断指令 ​

在宿主机执行 docker exec -it fs-app fs_cli -x "<COMMAND>"：

命令功能说明
status查看 FreeSWITCH 运行状态、在线时长、并发呼叫数、CPU 占用
show channels查看当前正在进行的通话通道列表与 UUID
show calls查看当前正在进行的双向通话
show registrations查看当前已注册上线的 SIP 分机与联系人地址
module_exists mod_audio_fork检查 mod_audio_fork 是否已成功加载（返回 true/false）
load mod_audio_fork动态加载指定模块
unload mod_audio_fork动态卸载指定模块
reload mod_audio_fork动态重新加载指定模块
reloadxml重新解析全部 XML 配置文件（无缝热生效）
sofia status查看所有 SIP Profile 运行状态与监听 IP/端口
sofia status profile internal查看 internal SIP 端口注册与监听详情
sofia status profile external查看 external SIP 网关注册状态
sofia profile external rescan重新扫描并加载 SIP Profile 新增的 Gateway 或配置
sofia profile internal restart重启 internal SIP profile
eval $${local_ip_v4}评估并打印预处理变量的实际计算值

7. 常见问题排查与避坑指南 (FAQs) ​

Q1: 容器异常重启，日志报错 Cannot lock pid file /usr/local/freeswitch/var/run/freeswitch/freeswitch.pid ​

  • 原因：上次容器未正常停止（如宿主机突然断电或强杀），残留了 .pid 锁文件。
  • 解决：docker-entrypoint.sh 已内置自动清理机制。若手动排查，可在宿主机执行：
    bash
    rm -f freeswitch-install/var/run/freeswitch/*.pid
docker compose restart

Q2: 启动报错 Failed to set SCHED_FIFO scheduler ​

  • 原因：Docker 默认限制了容器调整线程实时调度优先级的权限。
  • 解决：docker-compose.yml 中已配置 cap_add: [SYS_NICE, NET_ADMIN]，保证音频流低延迟调度正常运行。

Q3: 运行日志或 SQLite 报错 Permission denied 无法写入 ​

  • 原因：容器以 freeswitch 独立账户（UID=1000, GID=1000）运行，宿主机目录权限不匹配。
  • 解决：docker-entrypoint.sh 启动时会自动执行 chown -R freeswitch:freeswitch var/。宿主机手动修复指令：
    bash
    sudo chown -R 1000:1000 freeswitch-install/var

Q4: 通话接通后单通或无声（RTP 丢包） ​

  • 排查步骤：
    1. 详细阅读 网络模式与 NAT 专题；
    2. 检查 freeswitch-install/etc/freeswitch/vars.xml 中的 ops_local_ip_v4（或 external_rtp_ip）是否正确配置为当前主机的真实可达公网/局域网 IP；
    3. 检查云安全组是否已放行 30000-30199/UDP 端口；
    4. 确认 docker-compose.yml 使用的是 network_mode: "host"；
    5. 检查是否与 coturn relay 端口范围产生重叠冲突。

Q5: callflow-esl 连不上 FreeSWITCH (ESL Connection Refused / Timeout) ​

  • 排查步骤：
    1. 执行 docker exec -it fs-app fs_cli -x "status" 确认 FreeSWITCH 正常运行；
    2. 检查 autoload_configs/event_socket.conf.xml 中的 listen-port（默认 8021）和 password 是否与 callflow-esl 的 config.toml 一致；
    3. 检查 listen-ip 是否绑定为 :: 或 0.0.0.0，而非仅限 127.0.0.1（若跨主机访问）。

Q6: mod_audio_fork 报错无法连接 ASR WebSocket ​

  • 排查步骤：
    1. 检查 ASR 服务（sherpa-asr-server 监听 10096 或 funasr-asr-server 监听 10099）是否已正常启动；
    2. 在宿主机通过 curl http://<asr-host>:10096/health 验证健康检查；
    3. 检查 apps/callflow-esl/config.toml 中的 audioFork.wsUrl 是否为 FreeSWITCH 所在网络能够直接访问的地址。

文档与代码在同一仓库维护，现有 Markdown 是唯一内容源。

AI Voice Platform