本文是《从零搭建 AI + 人工呼叫中心》系列的最后一篇,把主篇和前 7 篇里的排障内容按"症状"重新组织,供出问题时快速查阅。每一节先给出定位思路,再列出常见原因和处理方法。
约定:
fs <命令>表示在 FreeSWITCH 容器里执行fs_cli -x "<命令>"(主篇第 3 章定义的快捷命令);fscli表示进入交互式控制台看实时日志。
目录
- 0. 通用排查顺序
- 1. 部署与启动
- 2. 注册与基础通话
- 3. 声音问题:无声、单通、断续
- 4. 推流模块
- 5. AI 机器人
- 6. FCC 与控制面
- 7. 坐席与排队
- 8. 外呼
- 9. 运营商线路
- 10. 质检与坐席辅助
- 11. 性能与延迟
- 12. 诊断命令速查
- 13. 收集信息求助
0. 通用排查顺序
整套系统是一层一层叠起来的,从下往上排查,每一层确认没问题再往上:
⑥ 业务:controller / dialer / qa_assist 的逻辑
⑤ AI:ASR / LLM / TTS(tools/check_dashscope.py)
④ 推流:电话 ↔ 模块 ↔ 后端(拨 9000 + tools/echo_server.py)
③ 控制:FCC 能否收到事件、执行动作(curl /health、controller 日志)
② 媒体:RTP 双向(拨 9196 回声测试)
① 信令:注册、呼叫建立(fs show registrations、siptrace)
⓪ 环境:容器、端口、防火墙、授权打开足够的日志:
fscli
> console loglevel debug
> sofia global siptrace on # 需要看 SIP 时推流模块的详细日志:在配置里把 log_debug 改为 true,执行 fs reload mod_taering_stream。日志量很大,排查完记得关掉。
1. 部署与启动
| 症状 | 可能原因 | 处理 |
|---|---|---|
start.sh 报错找不到 docker compose |
没有安装 Compose V2 插件 | 安装 docker-compose-plugin,确认 docker compose version |
| 容器起不来或反复重启 | 端口被占用(5060、5080、8021、18080) | sudo ss -lntup | grep -E '5060|5080|8021|18080',停掉占用的程序 |
| 在 Mac / Windows / WSL2 上声音不通 | 镜像使用 host 网络,这些环境下行为不同;镜像只有 x86_64 | 使用 x86_64 的 Linux 服务器或虚拟机 |
fs 命令报连接失败 |
改了 Event Socket 密码 | fs_cli 加 -p <新密码> |
fs 命令报找不到 fs_cli |
镜像里的路径不同 | 进容器 which fs_cli,修改快捷命令 |
module_exists mod_fcc 返回 false |
模块没加载 | fs load mod_fcc,看日志里的报错;检查 modules.conf.xml |
| 推流模块加载失败 | 开启了 api_enabled 但 api_token 为空 |
填上 token,或者关掉 HTTP 接口 |
| 改了推流配置不生效 | 只执行了 reloadxml |
必须 fs reload mod_taering_stream |
改了 vars.xml 不生效 |
预处理变量要重启才生效 | sudo docker compose restart |
2. 注册与基础通话
| 症状 | 可能原因 | 处理 |
|---|---|---|
| 软电话注册 403 | 密码错 | 密码是 vars.xml 里的 default_password,改完要重启 |
| 软电话注册超时 | 5060 没放行;IP 填错 | 防火墙、安全组放行 UDP/TCP 5060 |
| 注册成功但呼叫 404 | 拨号计划没匹配到 | fscli 看日志里 destination_number 和匹配过程;确认 reloadxml 过 |
| 呼叫 488 | 编码协商失败 | 软电话至少启用 PCMA / PCMU / G722 中的一个 |
呼叫立即挂断,原因 CALL_REJECTED |
FCC 拒接(黑名单),或者容量限制 | 看 controller 日志;FCC /health 里的 active_calls |
呼叫立即挂断,原因 USER_BUSY |
FCC 并发或 CPS 达到上限 | 调整 max_concurrent_calls、max_cps |
3. 声音问题:无声、单通、断续
先拨 9196(FreeSWITCH 自带回声):
- 9196 也没声音或单通 → 是 SIP/RTP 层面的问题,看本节;
- 9196 正常,AI 分机有问题 → 跳到第 4 章。
| 症状 | 可能原因 | 处理 |
|---|---|---|
| 接通后双方都听不到 | RTP 端口没放行 | 放行 UDP 16384–32768(以镜像配置为准) |
| 单通(一方听得到,另一方听不到) | NAT:SDP 里写的是内网 IP | 云服务器在 vars.xml 设置 external_rtp_ip / external_sip_ip 为公网 IP,重启 |
| 通话 30 秒左右自动断开 | ACK 收不到,通常是 NAT 或防火墙 | 同上;抓包看 ACK |
| 声音断断续续 | 网络丢包;服务器 CPU 过高 | top 看 CPU;在软电话里看丢包统计 |
| 坐席听客户声音很小或有回声 | 终端问题 | 换耳机,开启软电话的回声消除 |
4. 推流模块
先用回声后端排除 AI 的影响:停掉机器人,运行 python -m tools.echo_server,拨 9000。
4.1 启动失败
taering_stream_result=-ERR,或者命令返回 -ERR:
| 原因 | 确认方法 |
|---|---|
授权状态不是 authorized |
fs taering_stream license,见 4.5 |
| 授权并发已满(试用版 1 路) | fs taering_stream stats 看 licensed_active;是不是有通话没有 stop |
| 没有可用的后端地址 | 配置里 default_ws_url / default_ws_urls 是否为空 |
| 这个通道已经在推流 | 拨号计划里返回 +OK already started;API 返回 STREAM_ALREADY_EXISTS |
| 通道不存在 | API 传入的 uuid 是否正确,通话是否已经挂断 |
4.2 后端收不到
| 症状 | 原因 | 处理 |
|---|---|---|
| 后端完全没有连接 | 后端没启动;地址或端口不对 | 机器人监听的地址和 default_ws_url 一致;容器用 host 网络,127.0.0.1 指的是宿主机 |
| 有连接、有 start 帧,但没有音频 | 采集被暂停;通道没 answer |
taering_stream_json {"action":"get","channel_id":"<uuid>"} 看 capture_paused |
| 断断续续收到音频 | 连接在重连 | stats 看 reconnects;后端日志看连接是否被关闭 |
4.3 对方听不到后端的声音
| 原因 | 确认方法 |
|---|---|
start 之后通道没有被保持住,拨号计划直接走到了 hangup |
start 后面要有 park 或 bridge |
播放被暂停(pause_playback,或 default_autoplay=false) |
get 看 playback_paused |
| 下行采样率不对 | 必须等于 start 帧的 sample_rate |
| 下行发成了 stereo,或者不是 PCM16LE | 下行永远是单声道 PCM16LE |
用了 Base64 文本音频,但没开 allow_text_audio |
看 taering_stream::error 事件 |
4.4 声音质量
| 症状 | 原因 | 处理 |
|---|---|---|
| 变调(尖或沉) | 下行采样率和通话不一致 | 按 start 帧的 sample_rate 合成 |
| 有规律的"咔哒"声 | 下行消息没有按整帧对齐,模块对每条消息尾部补零 | 每条消息长度 = sample_rate × 2 × packet_ms / 1000 的整数倍 |
| 吞字、跳字 | 下行缓冲溢出,丢最旧的帧 | 后端按实时节奏发送;rx_buffer_ms 大于后端的领先量;看 stats 里的 rx_drop |
| 开头一小段被吞 | 通道媒体还没完全建立就开始说话 | 开场白前等 300~500 毫秒 |
| AI 的声音和对方的声音混在一起 | 注入是叠加的;通道在 bridge 状态 |
正常行为。只想让 AI 说话时,通道应在 park |
4.5 授权状态
fs taering_stream license 里的 license_status:
| 状态 | 含义 | 处理 |
|---|---|---|
authorized |
正常(试用版和商业版都是这个,看 license_mode 和 max_concurrency 区分) |
— |
pending |
正在等待在线校验 | 确认服务器能访问授权服务;稍等后再查 |
unauthorized |
未授权 | 联系作者开通 |
expired |
授权过期 | 联系作者续期 |
disabled |
授权被停用 | 联系作者 |
instance_conflict |
同一授权在别的实例上使用 | 确认没有重复部署;联系作者 |
client_upgrade_required |
模块版本过旧 | 升级模块或镜像 |
product_mismatch |
授权和产品不匹配 | 联系作者 |
error |
校验出错 | 看 message 字段和 FreeSWITCH 日志 |
商业授权(不限并发)联系 taering@vip.qq.com。
4.6 打断不生效
| 原因 | 确认方法 |
|---|---|
没开 enable_barge_in,或者改了没 reload |
fs taering_stream version 看 barge_in=enabled |
后端没有发 clear,或者先发了 clear 又继续发旧音频 |
后端要先丢弃本地缓冲、取消 TTS,再发 clear |
命令行 interrupt_play 返回 stream not found |
未开启打断时,这个命令也会返回这个提示,先检查配置 |
4.7 挂机后后端没清理
直接挂机时,模块不发 stop 帧,而是直接关闭连接。后端要把"连接关闭"也当作通话结束。
5. AI 机器人
先运行 python -m tools.check_dashscope,单独确认百炼三项服务可用。
| 症状 | 可能原因 | 处理 |
|---|---|---|
机器人启动就退出:请先设置 DASHSCOPE_API_KEY |
.env 没填或不在工作目录 |
在 ai-callcenter-demo 目录下运行 |
| ASR 握手 401 / 403 | Key 错误;Key 不属于华北2(北京) | 检查 Key 和地域 |
task-failed 模型不存在或无权限 |
模型没开通;模型名写错 | 百炼控制台确认;检查 .env |
有 call start,没有欢迎语 |
TTS 失败 | 日志里找 TTS task failed;TTS_VOICE 是否和模型匹配 |
| 欢迎语正常,说话没反应 | ASR 失败;mix_type 不对 |
日志里找 ASR task failed;start 帧 mix_type 应为 mono |
| 识别结果很差 | 8k 窄带;采样率参数不对 | ASR 的 sample_rate 必须等于 start 帧;8k 线路试 paraformer-realtime-8k-v2 |
| AI 自己打断自己 | 推流不是 mono,ASR 听到了 AI 的声音 |
改为 mono(注意 default_mix_type 的内置默认值是 stereo) |
| 背景噪音、"嗯"一声就打断 | 打断阈值太低 | 调大 on_partial 里的字数阈值 |
| 客户话没说完 AI 就抢话 | 断句静音太短 | 调大 max_sentence_silence |
| AI 回复里念出了符号 | 大模型输出了 Markdown | 提示词强调"不要使用任何符号";合成前过滤 |
| 说"转人工"没反应 | 大模型没输出 [转人工] 标记 |
看 BOT 日志末尾有没有 <转人工>;加强提示词 |
转人工时 FCC 返回 CALL_NOT_FOUND |
这通电话没被 FCC 注册(比如直接拨的 9000) | 从 fcc_inbound 的入口进线 |
| 转人工后 AI 还在说话 | 7000 第一行没有 taering_stream stop |
补上 |
| 重连后 AI 又播了一遍欢迎语 | 演示版把重连当成新通话 | 生产版按 uuid 续接(系列 7 第 4.3 节) |
日志出现 reply failed |
LLM / TTS 调用异常 | 看异常堆栈;网络、限流、配额 |
6. FCC 与控制面
| 症状 | 可能原因 | 处理 |
|---|---|---|
| curl 返回 401 | Token 错 | 和 mod_fcc.conf.xml 的 api_token 一致,改完要 reload mod_fcc |
curl 返回 429 AUTH_LOCKED |
连续认证失败被锁 | 等 retry_after_sec(默认 300 秒) |
| curl 返回 501 | 客户端用了分块传输 | 使用固定 Content-Length |
/health/ready 返回 200 但不可用 |
ready 接口总是返回 200 | 检查 data.status 是否为 ok |
| controller 连上了但收不到事件 | 没发 client.hello;hello 被拒 |
看 hello 的返回 code |
| 拨 4000 等 5 秒才进人工 | controller 没运行或没决策成功 | 这是决策超时兜底在工作;看 controller 日志 |
收不到 call.incoming |
拨号计划没执行 fcc_inbound;参数没写 service= |
fscli 看日志 |
service 总是 default |
fcc_inbound 的参数没写成 service=xxx |
改成 service=xxx |
| 事件对不上(转接后状态不更新) | 操作了 FCC 不持有的 UUID | FCC 只跟踪自己注册的那个 UUID |
| 动作返回 200 但没生效 | 200 只表示命令已提交 | 看 action.accepted / action.failed 事件 |
动作返回 409 COMMAND_FAILED |
通话已经结束;FreeSWITCH 拒绝 | 查询通话状态 |
| WS 被断开:慢消费者 | 事件处理太慢,积压超过 1000 条 | 收事件和处理事件分开(系列 2 第 11 章) |
resume.failed / SEQUENCE_EXPIRED |
断线太久 | 按系列 2 第 7 章对账 |
| 重连后序号变小 | FCC 重载或 FreeSWITCH 重启过 | 清零序号,完整对账 |
外呼返回 503 IDEMPOTENCY_UNAVAILABLE |
SQLite 数据库不可用 | 检查 idempotency_db_path 的目录权限和磁盘空间 |
7. 坐席与排队
| 症状 | 可能原因 | 处理 |
|---|---|---|
签入返回 AGENT_NOT_REGISTERED |
坐席软电话没注册;domain 不对 |
fs global_getvar domain 取得正确的 domain;fs sofia_contact 1002@<domain> 应返回 sofia/... |
创建坐席返回 AGENT_EXISTS |
已经创建过 | 直接签入即可 |
队列查询 QUEUE_QUERY_FAILED |
队列不存在 | fs callcenter_config queue list;新增队列后 queue load <名字> |
| 坐席已签入但不振铃 | 坐席没加入这个队列;状态不是 Available |
fs callcenter_config queue list agents support@default |
| 坐席振铃但接起来没声音 | 坐席网络 NAT 问题 | 同第 3 章 |
| 坐席不接,客户一直排队 | 坐席未接后会被暂时跳过;只有这一个坐席 | 设置 max-wait-time-with-no-agent;增加坐席 |
| 客户挂机后坐席还在振铃 | 一般会自动取消;若没有,检查队列配置 | fs callcenter_config queue list members support@default |
| 转人工后排队音乐不响 | 队列 moh-sound 配置不对 |
检查 callcenter.conf.xml |
| 坐席签出了,正在进行的通话没断 | 正常:签出只阻止新的分配 | — |
8. 外呼
| 症状 | 可能原因 | 处理 |
|---|---|---|
外呼 429 RATE_LIMITED |
FCC 并发或 CPS 上限 | 降低 dialer 并发;调整 FCC 配置 |
外呼 409 IDEMPOTENCY_CONFLICT |
同一个 request_id 用在了不同的号码或参数上 |
检查 request_id 生成规则 |
| 同一个客户被打了两次 | 每次重试生成了新的 request_id;在 queue.* 事件上也补量了 |
重试复用 request_id;只在 call.hangup 补量 |
| 客户接了,AI 不说话 | 没收到 call.answered;转 8100 失败 |
dialer 日志看 transfer 的返回;fscli 看 8100 是否执行 |
| 振铃阶段 AI 就开口了 | 把 ringing 当成了接通 |
只在 call.answered 时交给 AI |
route_mode=dialplan 时 AI 听不到客户 |
loopback 方向 | 确认推流模块是 loopback-aware 版本;log_debug 看 capture_dir |
route_mode=user 呼分机失败 |
分机没注册;user_domain 不对 |
fs show registrations;default_user_domain |
| 机器人拿不到客户资料 | customers.csv 里的号码和 callee 不一致 |
号码格式要完全一致 |
| AI 对着语音信箱说话 | 对方的语音信箱"接听"了电话 | 提示词识别录音特征后输出 [挂机];或业务侧加无应答超时 |
9. 运营商线路
| 症状 | 可能原因 | 处理 |
|---|---|---|
网关 FAIL_WAIT / NOREG |
账号密码、地址错误;网络不通 | fs sofia status gateway <名字>;siptrace 看 REGISTER 的响应 |
| 来电进不来 | 防火墙;ACL;运营商没把号码指过来 | siptrace 看有没有 INVITE |
| 来电进来但没路由 | public 里号码格式没匹配 |
看日志里实际的 destination_number |
| 呼出 403 | 主叫号码不允许外显;出口 IP 不在白名单 | 联系运营商核对 |
| 呼出 404 / 484 | 被叫号码格式不对 | 按运营商要求处理前缀 |
| 呼出 488 | 编码不匹配 | outbound_codec_prefs 加上 PCMA |
| 呼出 503 | 超过线路并发或 CPS | 降低外呼并发 |
| 收不到按键 | DTMF 方式不一致 | 和运营商确认 RFC2833 / INFO / 带内 |
| 有陌生号码在呼你的 5080 | 扫描器 | apply-inbound-acl 只放行运营商;防火墙限制 5080 |
10. 质检与坐席辅助
| 症状 | 可能原因 | 处理 |
|---|---|---|
| 推流 HTTP 接口连不上 | 没开 api_enabled;没 reload |
curl http://127.0.0.1:18081/api/v1/health |
| 返回 401 | STREAM_API_TOKEN 和配置不一致 |
核对 token |
返回 400 START_FAILED |
授权并发满(AI 那路没停);坐席腿已结束 | stats 看 licensed_active;7000 第一行要 stop |
| 坐席接起来,qa_assist 没反应 | 没收到 queue.bridged(不是经过队列转的) |
只有经过 mod_callcenter 队列的通话才有这个事件 |
| 客户和坐席的话对调 | 推流挂在了客户腿上 | 挂在 agent_uuid 上;或者对调声道 |
| 耳语被客户听到 | 推流挂在了客户腿上 | 耳语必须挂在坐席腿 |
| 网页打不开 | QA_WEB_HOST 是 127.0.0.1;防火墙 |
局域网访问时改为 0.0.0.0,并限制访问来源 |
| 没有生成小结 | 没有转写;大模型调用失败 | 看 qa_assist 日志 |
11. 性能与延迟
| 症状 | 可能原因 | 处理 |
|---|---|---|
| AI 接话慢 | 断句静音、大模型首字、TTS 首包 | 看 TIMING 日志,按系列 5 逐项优化 |
| 高峰期变慢 | 百炼限流;后端实例不足 | 看服务端错误码;扩容实例;申请提升配额 |
| 某一路通话断续,其他正常 | 该路网络问题 | 看这一路的丢包、get 返回的丢帧计数 |
| 全部通话断续 | CPU 打满(转码、录音);后端事件循环被阻塞 | top;后端不要在事件循环里做同步阻塞操作 |
rx_drop 持续增长 |
后端发送太快;缓冲太小 | 见 4.4 |
tx_drop 持续增长 |
后端读得太慢,或网络拥塞 | 后端尽快读取上行;检查网络 |
reconnects 突增 |
后端实例重启、网络抖动 | 查看后端和网络;负载均衡健康检查 |
12. 诊断命令速查
# 环境
sudo docker compose ps
sudo ss -lntup | grep -E '5060|5080|8021|18080|18081|9000'
# FreeSWITCH
fs status
fs show registrations
fs show channels # 当前通话和编码
fs uuid_dump <uuid> # 一个通道的全部变量
fs global_getvar domain
fs sofia status
fs sofia status profile external
fs sofia status gateway gw_main
fs sofia_contact 1002@<domain>
# 推流模块
fs taering_stream version
fs taering_stream stats
fs taering_stream license
fs 'taering_stream_json {"action":"get","channel_id":"<uuid>"}'
fs taering_stream <uuid> stop
# 坐席与队列
fs callcenter_config queue list
fs callcenter_config queue list agents support@default
fs callcenter_config queue list members support@default
fs callcenter_config agent list
# FCC
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/health/ready
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/calls/<call_id>
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/calls/<call_id>/events
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/callcenter/agents/1002@default
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/metrics
# AI
python -m tools.check_dashscope
python -m tools.echo_server
# 实时日志与抓包(在 fscli 里)
/log debug
sofia global siptrace on
/event plain CUSTOM taering_stream::connect taering_stream::disconnect taering_stream::error taering_stream::play13. 收集信息求助
在社区或者向作者求助时,带上这些信息,能大大缩短沟通时间:
- 环境:服务器系统和架构;部署方式(Docker 镜像版本或源码编译);
fs taering_stream version和fs taering_stream license的输出(隐去指纹等敏感字段); - 现象:什么操作、期望什么、实际发生什么;稳定复现还是偶发;
- 一通出问题的电话:它的
uuid/call_id,以及这通电话前后的 FreeSWITCH 日志(log_debug打开时更好); - 配置:相关的拨号计划、
mod_taering_stream.conf.xml、mod_fcc.conf.xml(隐去 token 和密码); - 后端日志:机器人、controller 在同一时间段的日志;
- 已经做过的排查:按第 0 章的顺序,哪一层确认过是正常的。
发出去之前,检查一遍有没有包含 API Key、Token、SIP 密码、客户手机号等敏感信息。
商业授权和技术支持:taering@vip.qq.com
相关链接
- 主篇:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- mod_fcc:https://github.com/taering365/mod_fcc
- freeswitch-docker:https://github.com/taering365/freeswitch-docker
- freeswitch_stream_mod:https://github.com/taering365/freeswitch_stream_mod
- 配套代码:https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip
系列文章
- 主篇:从零搭建 AI + 人工呼叫中心:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- 系列 1:mod_taering_stream 媒体协议详解:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-01-stream-protocol
- 系列 2:FCC 控制面深入:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-02-fcc
- 系列 3:AI 外呼:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-03-outbound
- 系列 4:实时质检与坐席辅助:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-04-qa-assist
- 系列 5:延迟优化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-05-latency
- 系列 6:接入运营商线路:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-06-carrier
- 系列 7:生产化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-07-production
- 系列 8:排障手册:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-08-troubleshooting