rogee/sip-research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
sip-research/freeswitch
T
History

README.md

FreeSWITCH/ESL AI 外呼底座 — 部署与运维文档

目标机器: 39.106.106.246 (阿里云 2vCPU/3.5G, Debian 13) · 交付物: /opt/freeswitch-esl/ 项目: https://github.com/signalwire/freeswitch · 镜像: safarov/freeswitch (FreeSWITCH 1.10.12) 范围: 仅外呼 (ESL originate ×2 + uuid_bridge), Mock SIP 运营商 + Mock LLM/ASR, 已端到端验证双向语音。 前置: asterisk 运行时已下线 (ast-* 容器清零、8088/8089 释放); Docker 与内核调优沿用 livekit 期成果。

1. 水平扩展结论 (先行)

结论: 零共享状态的独立节点复制 —— 与 Asterisk 同构。FreeSWITCH 无内置集群, 每节点呼叫状态全在本机内存; 扩容 = 加一个节点, 呼叫发起侧 (agent/业务后端) 在节点名单上选节点建 ESL 连接。不需要 Redis, 不需要任何协调组件。

层 状态存放 扩容方式 调度机制
FreeSWITCH 节点 本机内存 (通道/桥) 复制 service 块 (独立宿主 ESL 端口) 呼叫发起侧选节点 (call.sh 的 NODE 参数 = 生产中的 LB 名单)
AI Agent (生产) 无状态 worker --scale/K8s HPA 每个外呼任务自带节点选择与 ESL/SIP/RTP 会话

三方案对比: livekit-sip 需 Redis 存 trunk/呼叫状态并派发; Asterisk (ARI) 与 FreeSWITCH (ESL) 出站外呼均零共享层, 每呼叫自包含 (originate ×2 + bridge 全在一个节点内闭环), 节点间零交互。实测 1→2 节点零配置变更 (共用同一套 etc-fs), 呼叫按发起侧选择分摊 (见 §7)。

瓶颈与边界: ① 单节点容量受 CPU 与 RTP 端口段限制 — vanilla 默认 16384-32768 (约 1.6 万端口, 每桥接呼叫 2 腿各 1 对 RTP+RTCP ≈ 4000 并发/节点, 实际 CPU/fd 先到顶); ② ESL 是单连接同步命令式接口, 高并发控制面需连接池或 bgapi; ③ 无跨节点媒体互通 — 仅外呼场景无影响; ④ 未来要呼入/注册时前置 Kamailio dispatcher, 纯出站不需要。

2. 架构

业务后端 / AI Agent (mock-agent, 容器, 纯 stdlib Python)
  │  ① ESL TCP 连接 fs:8021 (auth)                    — 控制面 (等价 ARI REST)
  │  ② 本侧 SIP UAS 监听 :5062 + RTP :40001           — 媒体面 (等价 ARI externalMedia)
  │  ③ originate 腿1 → sofia/external/agent@me:5062 &park()
  │  ④ originate 腿2 → sofia/gateway/mock-trunk/<被叫> &park()
  │  ⑤ uuid_bridge 腿1 腿2 → RTP 经 FreeSWITCH 双向
  ▼
┌─ docker net: fsnet ─────────────────────────────────────────────┐
│  fs1  (ESL :8021, sofia ext :5080/udp, RTP 16384+) ← 独立节点   │
│  fs2  (ESL :8021→宿主 8022, 其余同上)              ← 零共享状态 │
│        │ INVITE / 100/180 / 200 OK (SDP, PCMU) / ACK            │
│        ▼                                                         │
│  mock-provider (SIP UAS :5060/udp, RTP :40000, 440Hz 应答音)    │
└──────────────────────────────────────────────────────────────────┘
  agent ⇄ FreeSWITCH: RTP 双向 (PCMU)
    TX = 440Hz 间歇音 (Mock LLM/TTS) → 被叫听到的 "AI 说话"
    RX = RMS 统计     (Mock ASR)     → 被叫语音进 "识别"

与 Asterisk 方案的关键差异: FreeSWITCH 没有 ARI externalMedia 式外挂媒体 API。标准做法是 agent 自身充当一个 SIP 端点 (UAS): FreeSWITCH originate 一条到 agent 的 SIP 腿 (agent 应答 200 OK+SDP), 再 originate 被叫腿, uuid_bridge 桥接。控制面从 "ARI REST + 事件 WS" 变为 "ESL TCP 单连接命令式"。agent 的 RTP 收发逻辑与 asterisk 版相同, 仅增加 SIP UAS 部分。

外呼信令流 (仅出站):

agent → ESL auth → originate sofia/external/agent@host:5062 &park()   (腿1, agent 应答)
      → originate sofia/gateway/mock-trunk/+1510... &park()           (腿2, 被叫应答)
      → uuid_bridge <腿1> <腿2> → 双向 RTP 经 FS
      → uuid_kill 双腿 → BYE → agent 输出双向统计

3. 端口规划

端口 组件 说明
8021/tcp fs1 ESL 控制面, 宿主映射 8021
8022/tcp→8021 fs2 第二节点 ESL (profile scale)
5080/udp fs1/fs2 sofia external profile 信令 (容器网内, 未映射宿主)
16384-32768/udp fs1/fs2 RTP 媒体 (vanilla 默认段, 各容器独立 netns 不冲突)
5060/udp, 40000/udp mock-provider Mock 运营商 SIP + RTP
5062/udp, 40001/udp mock-agent (每次呼叫) 本侧 SIP UAS + RTP

生产外网仅需放行: SIP 5060/udp (+5061/tls) 与 RTP 段; ESL 8021/8022 只对 agent 内网放行 (强密码+ACL), 严禁公网裸开 — ESL 拿到即完全控制 FreeSWITCH (可执行任意系统命令 system)。

4. 从零部署步骤 (全部实测)

# ── 4.1 Docker 与内核调优: 沿用 livekit 项目成果
#    (/etc/sysctl.d/99-livekit-sip.conf 已应用, 见 §8; asterisk 运行时已下线)

# ── 4.2 部署栈 ─────────────────────────────────────────────────────
mkdir -p /opt/freeswitch-esl && cd /opt/freeswitch-esl   # = 仓库 deploy/ 目录
./scripts/setup-conf.sh       # 生成 etc-fs/ (镜像 vanilla 配置 + 4 处补丁, 见踩坑)
docker compose up -d                                  # fs1 + mock-provider
docker compose --profile scale up -d                  # (可选) fs2 第二节点

# ── 4.3 验证 ───────────────────────────────────────────────────────
./scripts/health.sh                     # 容器 + ESL status + gateway 状态 + 活动呼叫
./scripts/call.sh +15105550123 12 1     # 端到端外呼 (节点1)
./scripts/call.sh +15105550123 10 2     # 端到端外呼 (节点2, 验证扩展)

配置仅 2 个小文件 (conf/): event_socket.conf.xml (ESL 0.0.0.0:8021 + 密码 + rfc1918.auto ACL)、mock-trunk.xml (sofia 网关: 无注册 + OPTIONS ping 25s 探活); 其余由 setup-conf.sh 从镜像 vanilla 配置生成并打补丁。

⚠ 踩坑1 (最关键): safarov 镜像 entrypoint 在 /etc/freeswitch/freeswitch.xml 不存在时从 vanilla 种子整目录 cp —— 按文件 RO 挂载会报 "Read-only file system" 且配置落空; 必须整目录挂载 (./etc-fs:/etc/freeswitch), 由 setup-conf.sh 生成 (每次全量重建, 幂等)。 ⚠ 踩坑2: vanilla event_socket 的 listen-ip=:: 在本容器 getaddrinfo 失败 → mod_event_socket 起不来; 改 0.0.0.0。 ⚠ 踩坑3: vanilla vars.xml 的 stun-set 在配置解析期做外网 STUN 查询, 不通则 Invalid ext-sip-ip → mod_sofia 整体加载失败; setup-conf.sh 已剥离 stun-set 与 ext-sip-ip/ext-rtp-ip。 ⚠ 踩坑4 (ESL ACL, 折腾最久): 不设 apply-inbound-acl → 默认 loopback.auto, 容器网内 agent 被拒 (text/rude-rejection); localnet.auto 不含 127.0.0.1 → 容器内 fs_cli 被拒; 自定义 acl.conf.xml 列表在此镜像实测不生效 (127.0.0.1 与 eth0 均被拒)。解: 内置 rfc1918.auto (10/8+172.16/12+192.168/16) — agent 与 fs_cli 均放行, fs_cli 需 -H $(hostname -i) 走 eth0 源地址。 ⚠ 踩坑5: 镜像缺 CA 证书, mod_signalwire 每分钟刷 Curl 77 错误日志 → 从 modules.conf.xml 删除加载行。 ⚠ 踩坑6: fs_cli 默认连 localhost+ClueCon, 需显式 -H <ip> -P 8021 -p <密码>; 且 count 类命令输出首行是空行, 解析要过滤。 ⚠ 踩坑7: FS 启动后第一个 originate 可能因网关冷启动未就绪失败; mock-agent 对腿2 已做 3 次重试。

5. 外呼链路验证 (实测输出)

./scripts/call.sh +15105550123 12 1:

[agent] agent up: sip=udp/5062 rtp=udp/40001 ip=172.18.0.4
[agent] esl connected: freeswitch1:8021
[agent] INVITE from FS 172.18.0.3:5080 call_id=7bdc5fbc-...     ← FS originate 腿1 到 agent
[agent] leg answered (ACK), fs rtp=('172.18.0.3', 18364) codec=PCMU
[agent] leg1 (agent UAS) up: +OK agent-1788159625-782
[agent] leg2 (callee) answered: +OK callee-1788159625-782        ← 经 mock-trunk 外呼被叫
[agent] bridged [agent-... + callee-...], streaming 12.0s
[agent] RX frames=500 avg_rms=8362
RESULT number=+15105550123 rx_frames=536 rx_avg_rms=8246 tx_frames=568 bidirectional=YES

mock-provider (被叫侧) 日志:

INCOMING_INVITE from=172.18.0.3:5080 uri="sip:+15105550123@mock-provider:5060"
ANSWERED media=172.18.0.2:40000 codec=PCMU peer=172.18.0.3:23888  ← SDP 协商 PCMU
ACK confirmed, RTP bridging
CALL_DONE reason=bye dur=13.5s sent_rtp=570 recv_rtp=533 recv_avg_amplitude=8236

双向语音证明: agent RX=534 帧 (被叫→ASR 方向, RMS 8270 = 440Hz 检测到) 与 provider recv_rtp=533 (LLM/TTS→被叫方向) 计数完全对称; agent TX=568 ↔ provider sent_rtp=570。挂断后 show calls count=0, 无泄漏。换真实 LLM/ASR 只需替换 mock-agent 的 TX 音源与 RX 消费循环。

6. 运行状态检测

./scripts/health.sh (实测输出):

== 容器状态        fs1 / fs2 (healthy) / fs-mock-provider   Up
== ESL status      PASS fs1 (UP, FreeSWITCH 1.10.12)  PASS fs2
== sofia 网关      PASS fs1 mock-trunk State=NOREG  PASS fs2  (NOREG=无注册模式+ping 探活, 正常态)
== 活动呼叫        PASS fs1 active calls=0
result: ok=5 fail=0

持续监控: watch -n5 ./scripts/health.sh; 呼叫级状态: provider 日志 CALL_DONE 行 (时长/双向计数); 容器级: docker healthcheck (compose 已配 fs_cli status)。层级与 livekit/asterisk 版对齐: 容器 + API 功能 + 业务功能三层。

7. 水平扩展实证 (双节点, 零配置变更)

① 加节点即扩容: docker compose --profile scale up -d 拉起 fs2, 共用同一套 etc-fs, 无任何既有节点配置改动。

② 3 路并发分摊双节点 (发起侧调度):

$ (./scripts/call.sh +15105550123 10 1 &) (./scripts/call.sh +15105550123 10 1 &) (./scripts/call.sh +15105550123 10 2 &)
RESULT ... rx_frames=440 rx_avg_rms=8245 tx_frames=471 bidirectional=YES
RESULT ... rx_frames=438 rx_avg_rms=8193 tx_frames=471 bidirectional=YES
RESULT ... rx_frames=440 rx_avg_rms=8178 tx_frames=470 bidirectional=YES

$ docker logs fs-mock-provider | grep INCOMING | grep -oE "from=[0-9.]+" | sort | uniq -c
     2 from=172.18.0.3      ← fs1 处理 2 路 (源 IP = fs1)
     1 from=172.18.0.4      ← fs2 处理 1 路 (源 IP = fs2)

$ (呼中 t=8s) fs1: 2 calls / 4 channels    fs2: 1 call / 2 channels   ← 每桥接呼叫=2通道
$ (provider) CALL_DONE sent_rtp=473 recv_rtp=439 amplitude=8174       ← 双向对称

→ 加副本即扩容、发起侧调度、双节点各自满血双向, 三项均实证。 资源基线 (3 并发): fs1 0.3%CPU/48M, fs2 0.3%CPU/44M — 2vCPU 单节点距容量上限还有两个数量级余量。

8. 系统调优

内核 (沿用已应用的 /etc/sysctl.d/99-livekit-sip.conf, RTP/UDP 通用, 无需改动):

net.core.rmem_max = 16777216          # UDP 收缓冲上限 (16M, 默认 208K 高并发必丢包)
net.core.wmem_max = 16777216
net.core.rmem_default = 1048576
net.core.wmem_default = 1048576
net.core.netdev_max_backlog = 4096
net.ipv4.ip_local_port_range = 10000 65000   # 出向 SIP/RTP 源端口
net.ipv4.udp_mem = 8388608 12582912 16777216 # 全局 UDP 页缓存 (3.5G 内存安全值)

验证: nstat -az | grep -i udp (UdpRcvbufErrors 应为 0)。

组件级:

  • RTP 段: switch.conf.xml 的 rtp-start-port/rtp-end-port (vanilla 默认 16384-32768 已注释未改); 生产按并发收窄或分段, 端口不够优先加节点 (见 §7)。
  • ESL: 高并发控制面改 bgapi (异步作业) 或 esl 连接池; 单连接串行 api 是同步阻塞的 (本文 mock 场景够用)。# ponytail: 单 ESL 连接串行 api, >100 并发呼叫控制需 bgapi/连接池。
  • sofia 网关: ping=25 OPTIONS 探活快速摘除故障 trunk; 网关冷启动有秒级窗口 (mock-agent 已重试兜底)。
  • 容器: restart: unless-stopped + healthcheck 已配; 双节点各 ~45M 内存, 3.5G 机器无需 mem limit; cap_add: SYS_NICE (FS 定时器优先级)。
  • 监控: health.sh 三层 + show calls count 告警 (骤降); FS 文件日志 /var/log/freeswitch/freeswitch.log; 告警项: 容器重启、gateway State 异常、UdpRcvbufErrors>0。

9. 生产化清单 (Mock → 真实运营商)

  1. trunk: mock-trunk.xml 加 username/password (digest 注册) 或 IP 白名单模式, proxy 换运营商 SIP 域名/IP; 我方 5060/udp(external profile 5080 改)、RTP 段公网放行 (阿里云安全组)。
  2. ESL 安全: 8021/8022 仅对 agent 网段放行; 换强密码; 保持 rfc1918.auto ACL (生产可再收紧到容器网段); ESL 等同 root shell, 公网暴露=事故。
  3. NAT: 阿里云 ECS 1:1 NAT — external profile 配 ext-sip-ip/ext-rtp-ip 为公网 IP (本文已剥离的参数届时显式回填, 不要用 stun); agent 侧 SIP/RTP 地址用宿主可达地址。
  4. AI 侧: mock-agent 替换为真实 STT/LLM/TTS (RX 帧喂识别、TX 换合成音频; SIP UAS + ESL 接口不变)。
  5. 高可用: 节点 ≥2 (已验证); 调度侧带健康检查摘除故障节点; 需要呼入/注册时前置 Kamailio dispatcher。
Reference in New Issue View Git Blame Copy Permalink