Administrator
发布于 2026-11-21 / 2 阅读
0
0

系列 8:排障手册(完整版)

本文是《从零搭建 AI + 人工呼叫中心》系列的最后一篇,把主篇和前 7 篇里的排障内容按"症状"重新组织,供出问题时快速查阅。每一节先给出定位思路,再列出常见原因和处理方法。

约定:fs <命令> 表示在 FreeSWITCH 容器里执行 fs_cli -x "<命令>"(主篇第 3 章定义的快捷命令);fscli 表示进入交互式控制台看实时日志。


目录


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::play

↑ 回到目录


13. 收集信息求助

在社区或者向作者求助时,带上这些信息,能大大缩短沟通时间:

  1. 环境:服务器系统和架构;部署方式(Docker 镜像版本或源码编译);fs taering_stream version 和 fs taering_stream license 的输出(隐去指纹等敏感字段);
  2. 现象:什么操作、期望什么、实际发生什么;稳定复现还是偶发;
  3. 一通出问题的电话:它的 uuid / call_id,以及这通电话前后的 FreeSWITCH 日志(log_debug 打开时更好);
  4. 配置:相关的拨号计划、mod_taering_stream.conf.xml、mod_fcc.conf.xml(隐去 token 和密码);
  5. 后端日志:机器人、controller 在同一时间段的日志;
  6. 已经做过的排查:按第 0 章的顺序,哪一层确认过是正常的。

发出去之前,检查一遍有没有包含 API Key、Token、SIP 密码、客户手机号等敏感信息。

商业授权和技术支持:taering@vip.qq.com


相关链接

系列文章

↑ 回到顶部


评论