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

系列 2:FCC 控制面深入——事件、幂等、续传与对账

本文是《从零搭建 AI + 人工呼叫中心》的补充篇。主篇里,controller.py 只用了 FCC 的一小部分:收到来电、转到 AI。本篇讲清楚 FCC 的数据模型和可靠性语义,以及怎样在它上面写出一个不丢事件、不重复拨打、重启后能自动恢复的业务后端。

完整接口文档见 mod_fcc 仓库:https://github.com/taering365/mod_fcc。本文基于 FCC 1.2.1-open。


目录


1. FCC 的定位

FCC 是运行在 FreeSWITCH 进程里的受约束的业务控制面:

业务后端 ──HTTP 命令──► FCC ──► FreeSWITCH 命令(originate / uuid_* / callcenter_config …)
业务后端 ◄──WS 事件─── FCC ◄── FreeSWITCH 事件(progress / answer / DTMF / hangup / callcenter::info)

它做三件事:

  1. 把命令收窄:只开放白名单内的动作,并校验参数(不允许 {}、换行、单引号等能注入 FreeSWITCH 命令的字符);
  2. 把状态归一化:把 FreeSWITCH 零散的通道事件整理成每通电话一个状态,以及有序的业务事件;
  3. 把标识稳定化:用 call_id 贯穿一通电话的整个生命周期,包括转接和排队。

它不做的事:音频、录音、会议、ASR/TTS、坐席心跳、外呼任务调度、报表。这些都属于业务后端或其他模块。

↑ 回到目录


2. 数据模型:call_id、uuid 和事件

2.1 两个标识

标识 格式 谁生成 用途
call_id call_<UUID> FCC 业务主键。持久化它;跨重启不重复
uuid FreeSWITCH UUID FreeSWITCH(外呼时由 FCC 指定) 通道标识。推流模块、ESL 都用它

外呼时,FCC 生成 UUID 后通过 origination_uuid 指定给新通道,所以 call_id 就是 call_ 加上这个 UUID。所有 /calls/{call_id} 路径都同时接受这两种标识。

2.2 事件

每个业务事件长这样:

{"type":"call.answered","sequence":103,"timestamp_ms":1785744002500,
 "data":{"request_id":"order-1","call_id":"call_…","uuid":"…","direction":"outbound",
         "caller":"1000","callee":"1001","did":"","service":"","status":"answered",
         "hangup_cause":"","detail":""}}
  • sequence:全局单调递增,所有通话共用一个序号空间;
  • data.status:事件发生后这通电话的状态快照;
  • data.detail:事件附加信息,比如 DTMF 的按键、动作名、挂机原因。

2.3 三处保存

位置 保存什么 容量 跨重启
单通话事件表 该通话最近的事件 64 条 ✗
全局事件环 所有通话的事件,用于 WS 续传 4096 条 ✗
通话快照(内存) 每通电话的当前状态 已结束的保留 call_history_ttl_sec(3600 秒),最多 call_history_max_records(10000)条 ✗
SQLite 非空 request_id、call_id、uuid、规范化请求、终态 通话结束后保留 idempotency_ttl_sec(86400 秒) ✓

FCC 的事件缓存不是持久消息队列。 业务状态必须落你自己的数据库。

↑ 回到目录


3. 状态机与事件归属

3.1 状态

外呼:  dialing ──► ringing ──► answered ──► hangup
           │           │
           └───────────┴──────────────────► no_answer
入呼:  incoming ──► answered ──► hangup
           └──► decision_timeout
  • ringing 不是接听。它对应 SIP 180/183,有可能只是运营商的彩铃或者"您拨打的用户已关机"的提示音。任何"接通后才做"的动作都要等 answered。
  • 结束时只会有一个 call.hangup 事件,用 data.status 区分:no_answer 表示从来没接通(包括 originate 提交失败),hangup 表示接通后结束。没有单独的 call.no_answer 事件。

3.2 事件归属

一通电话在 FreeSWITCH 里可能对应多个通道:loopback 有 A、B 两条腿,转进队列后还有坐席腿。FCC 只根据自己持有的那个 UUID 更新状态:事件的 Unique-ID 必须等于 FCC 记录的 UUID。

这保证了:

  • loopback 另一条腿挂机时,不会被误判为客户挂机;
  • 继承了 fcc_call_id 变量的其他通道,不会产生重复的 call.hangup。

例外:DTMF 事件经过传播后可能缺少 variable_fcc_call_id,这时 FCC 会按 UUID 找到自己持有的通话。

3.3 一通电话的完整事件序列

以主篇"AI 先接、再转人工"的流程为例:

call.incoming        ← fcc_inbound 注册
action.accepted      ← detail=transfer(controller 转到 8000)
call.answered        ← 8000 执行 answer
action.accepted      ← detail=transfer(AI 转到 7000)
queue.joined         ← 进入 support@default
queue.agent_offered  ← 选中坐席,坐席振铃
queue.bridged        ← 坐席接听
queue.bridge_ended
queue.completed
call.hangup          ← status=hangup,detail=NORMAL_CLEARING

↑ 回到目录


4. HTTP 动作的真实含义

POST /calls/{call_id}/{action} 返回 200 {"code":"OK","message":"submitted"},只表示 FreeSWITCH 接受了命令。比如:

  • transfer 返回 200 时,目标 extension 可能还没开始执行;
  • bridge 返回 200 时,媒体可能还没接通;
  • hangup 返回 200 时,call.hangup 事件还没到。

每个被识别的动作都会产生一个 action.accepted 或 action.failed 事件。以事件为准,以查询为辅。

动作和 FreeSWITCH 命令的对应关系:

动作 命令 备注
answer / pre_answer / park uuid_answer / uuid_pre_answer / uuid_park
reject uuid_kill <cause> 默认 CALL_REJECTED
hangup uuid_kill
hold / unhold uuid_hold / uuid_hold off 对 FCC bridge 的通话会记住对端,处理保持音乐
clear uuid_break 停止当前播放或应用,常用来打断 park 继续执行拨号计划
dtmf uuid_send_dtmf
play_file uuid_broadcast <file> aleg
transfer uuid_transfer … XML <context>
bridge uuid_bridge other_uuid 必须是 FreeSWITCH UUID

通话结束后,快照仍然可以查询,但所有实时动作都返回 409 COMMAND_FAILED。

↑ 回到目录


5. 幂等:怎样保证不重复拨打

外呼最怕的事故是:网络超时后重试,结果同一个客户被打了两次。FCC 的 request_id 就是为此设计的。

5.1 机制

  1. 请求带非空 request_id 时,FCC 在发起呼叫之前,先在 SQLite 里原子占位;
  2. 同时对规范化后的 caller、callee、gateway、route_mode、route_context、user_domain 计算请求指纹;
  3. 再次收到同一个 request_id:
    • 指纹相同 → 不拨打,直接返回原来的 call_id/uuid 和当前状态,message 为 idempotent replay;
    • 指纹不同 → 409 IDEMPOTENCY_CONFLICT;
  4. 并发的相同请求只有一个会真正拨打;
  5. 记录跨模块重载和 FreeSWITCH 重启保留,通话结束后过 idempotency_ttl_sec 才删除;
  6. SQLite 不可用时返回 503 IDEMPOTENCY_UNAVAILABLE,不会在没有幂等保护的情况下拨打。

5.2 怎么生成 request_id

request_id 应该代表一次业务意图,而不是一次 HTTP 请求:

✅ campaign-20261120-客户ID-第1次尝试
✅ crm-callback-工单号
❌ 每次请求随机生成 UUID          ← 重试时变了,就起不到幂等作用
❌ 只用客户号码                    ← 第二天再打时会被当成重复(在 TTL 内)

重试时复用同一个 request_id;需要真正再拨一次(比如第二次尝试)时,换一个新的。

5.3 重试策略

结果 处理
网络超时、连接断开 用同一个 request_id 重试,安全
200 记录 call_id
409 IDEMPOTENCY_CONFLICT 代码有 bug:同一个 key 用在了不同的请求上
409 ORIGINATE_FAILED 提交失败,这次尝试结束(已产生 call.hangup,status=no_answer)
429 RATE_LIMITED 达到并发或 CPS 上限,退避后用同一个 request_id 重试
503 FCC 的 SQLite 有问题,告警,暂停外呼

↑ 回到目录


6. WebSocket:握手、续传、背压

6.1 握手

客户端 → Upgrade(带 Authorization: Bearer <token>)
客户端 → {"type":"client.hello","request_id":"h1","client_id":"worker-1","protocol_version":1,"last_sequence":<已处理的最大序号>}
FCC    → {"type":"server.hello","code":"OK","data":{"current_sequence":…,"oldest_sequence":…,"resume_supported":true,"heartbeat_interval_ms":15000,…}}
FCC    → 补发 last_sequence 之后、仍在环里的事件
FCC    → 实时事件 …
  • 首帧不是 hello → server.error/HELLO_REQUIRED,连接关闭;
  • 协议版本不对 → server.hello/UNSUPPORTED_PROTOCOL,连接关闭;
  • 没完成握手的连接收不到任何事件。

6.2 续传

  • last_sequence=0:不补发,只接收之后的新事件;
  • last_sequence=N:补发所有 sequence > N 并且仍在 4096 条环里的事件;
  • N 已经被挤出环:收到 {"type":"resume.failed","code":"SEQUENCE_EXPIRED"},需要对账(见第 7 章)。

server.hello 里的 oldest_sequence 和 current_sequence 可以让你预先判断能否续传。

持久化序号的时机:处理完一个事件、业务状态写入数据库之后,再保存它的 sequence。先保存再处理,崩溃时就会丢事件;处理完再保存,最坏情况是重复处理一次,所以业务处理本身也要幂等(按 sequence 去重)。

event.ack 可以发,但 FCC 当前会忽略它,不影响事件保留。

6.3 心跳与背压

  • FCC 每 15 秒发一次 Ping,45 秒内收不到 Pong 就断开。大多数 WebSocket 库会自动回 Pong;
  • 每个客户端最多积压 1000 条待发消息,超过就断开这个"慢消费者"。所以不要在事件循环里做慢操作(同步数据库写入、调用大模型),把事件放进内部队列,交给其他协程或线程处理。

6.4 用 WebSocket 发命令

除了 HTTP,也可以在同一条 WebSocket 上发命令:

{"type":"call.create","request_id":"c-1","callee":"1001","caller":"1000","route_mode":"user"}
{"type":"call.query","request_id":"q-1","call_id":"call_…"}
{"type":"call.transfer","request_id":"t-1","call_id":"call_…","destination":"7000","context":"default"}

结果以 <type>.result 返回,response 字段里是对应 HTTP 接口的返回体。call.create 里的 request_id 同时也是幂等键。坐席和队列接口只有 HTTP 版本。

6.5 一条连接还是多条

FCC 会把所有事件推送给每一个完成握手的客户端。推荐:

  • 每个业务后端进程维持一条 WebSocket;
  • 后端内部按 call_id 分发给各自的状态机;
  • 浏览器、坐席工作台等前端连接你自己的后端,不要直连 FCC。

多个后端进程同时连接时,每个进程都会收到全部事件,需要自己按业务归属过滤(比如外呼进程只处理自己发起的 call_id)。

↑ 回到目录


7. 对账:续传失败或 FCC 重启之后

以下情况会导致事件缺失:

  • 断线太久,SEQUENCE_EXPIRED;
  • FCC 模块重载或 FreeSWITCH 重启,内存里的事件环清空,序号重新开始。

这时用 HTTP 查询逐个恢复:

1. 从自己的数据库取出所有"未结束"的 call_id
2. 逐个 GET /calls/{call_id}
   ├── 404 CALL_NOT_FOUND:内存快照已过期或 FCC 重启过 → 按"结果未知"处理,人工核查或标记失败
   ├── status = hangup / no_answer:补执行"通话结束"的业务逻辑
   └── 其他:更新本地状态,继续等待事件
3. 对账完成后,再恢复外呼补量等会产生新呼叫的逻辑

判断 FCC 是否重启过:server.hello 里的 current_sequence 小于你保存的序号,说明序号重新开始了。这时应该清空保存的序号(从 0 开始),并执行一次完整对账。

重启时哪些通话能恢复,要分情况看:

情况 带非空 request_id 的外呼 入呼、空 request_id 的外呼
只重载 FCC 模块(reload mod_fcc) 从 SQLite 恢复到内存,包括还没结束的;之后的事件按 UUID 继续更新 不会恢复,后续事件不再推送,查询返回 404
FreeSWITCH 整体重启 通话本身已经断开;恢复出来的记录如果重启前还没结束,可能停留在挂机前的状态 同左,且查询返回 404

所以:

  • 外呼务必带 request_id,它不仅防重复,也让模块重载后还能继续跟踪;
  • FreeSWITCH 整体重启后,把"重启前还没结束"的通话统一标记为异常结束,不要等它们的 call.hangup;
  • 生产环境避免在业务高峰期重载 FCC 或重启 FreeSWITCH。

↑ 回到目录


8. 入呼接管与决策超时

8.1 机制

<action application="fcc_inbound" data="service=customer_service"/>
<action application="park"/>
<!-- 超时兜底 -->
<action application="transfer" data="7000 XML default"/>
  • fcc_inbound 注册通道,设置 fcc_call_id、fcc_direction=inbound、fcc_service、fcc_register_status,发布 call.incoming;不应答、不接管路由;
  • 参数必须写成 service=xxx,否则 service 记为 default;
  • 达到并发或 CPS 上限时,fcc_register_status=rate_limited,并以 USER_BUSY 挂机;
  • 后端在 inbound_decision_timeout_ms(默认 5000)内做出决策;
  • 超时后发布 call.decision_timeout,然后:
    • continue_dialplan(默认):执行 uuid_break 打断 park,拨号计划继续往下执行兜底逻辑;
    • hangup:直接挂断。

8.2 决策的写法

async def on_incoming(data):
    call_id = data["call_id"]
    caller, did, service = data["caller"], data["did"], data["service"]
    if in_blacklist(caller):
        return await fcc.action(call_id, "reject", {"cause": "CALL_REJECTED"})
    if not in_business_hours():
        return await fcc.transfer(call_id, "voicemail")
    if is_vip(caller):
        return await fcc.transfer(call_id, "7000")          # VIP 直接转人工
    return await fcc.transfer(call_id, "8000")              # 其余交给 AI

8.3 超时多长合适

  • 决策逻辑要查数据库、调 CRM 时,留足时间,但不要让客户等在静默里太久:可以在 park 之前先 answer 并播放一段提示音,或者用 pre_answer 加早期媒体;
  • 兜底逻辑要能独立工作:后端整体不可用时,客户应该被送到一个"最安全"的地方,比如人工队列或留言。

↑ 回到目录


9. 与 mod_callcenter 配合

9.1 分工

负责方
员工登录、心跳、超时自动下线 业务后端
SIP 注册 软电话 / 浏览器(SIP over WSS)
坐席创建、签入、签出、暂停、恢复 后端调用 FCC
排队、选坐席、振铃、拒接惩罚、话后整理 mod_callcenter
队列事件 → 业务事件 FCC

9.2 坐席接口要点

  • FCC 创建的是 callback 类型坐席,contact 由 FCC 内部生成:[leg_timeout=20]user/<extension>@<domain>;
  • 初始状态 Logged Out,同时加入指定队列(tier);
  • sign-in / resume 会先检查 SIP 注册,未注册返回 409 AGENT_NOT_REGISTERED;
  • sign-out / pause 只阻止新的分配,不会挂断正在进行的通话;
  • 生命周期动作是幂等的状态赋值,可以放心重试;
  • GET /callcenter/agents/{id} 返回的 registered 和 status 互相独立。

坐席心跳的推荐做法:

坐席工作台每 15 秒向业务后端发心跳
业务后端:60 秒没收到心跳 → POST /callcenter/agents/{id}/sign-out
          坐席重新上线 → 确认 registered=true → sign-in

9.3 队列事件

FCC 订阅 callcenter::info,用 CC-Member-Session-UUID 把队列事件关联到原始 call_id:

FCC 事件 mod_callcenter 动作 用途
queue.joined member-queue-start / resume 开始排队,计算排队时长的起点
queue.agent_offered agent-offering 选中坐席,开始振铃
queue.bridged bridge-agent-start 坐席接听;agent_uuid 是坐席腿的 UUID
queue.bridge_ended bridge-agent-end 人工通话结束
queue.abandoned member-queue-end(Cancel) 排队中客户挂机
queue.timeout member-queue-end(TIMEOUT / NO_AGENT_TIMEOUT) 排队超时
queue.completed member-queue-end(Terminated) 正常结束

queue.bridged 里的 agent_uuid 很有用:系列 4 就是用它在坐席腿上开启质检推流。

队列终态之后一定还会有 call.hangup。统计排队结果看队列事件,驱动"通话结束"逻辑只看 call.hangup,否则会重复处理。

↑ 回到目录


10. 容量控制

配置 含义 超限表现
max_concurrent_calls 已注册、尚未挂机完成的通话数(入呼 + 外呼) 外呼 429 RATE_LIMITED;入呼 USER_BUSY 挂机
max_cps 每个自然秒内新建的通话数(入呼外呼共用) 同上

实际可用并发取以下几项的最小值:FCC 配置、线路并发、推流模块授权并发、AI 服务的并发配额、坐席数量(转人工比例 × 并发)、机器压测结果。

监控指标(GET /metrics,Prometheus 格式):fcc_active_calls、fcc_calls_created_total、fcc_calls_rejected_total、fcc_http_requests_total、fcc_errors_total。fcc_calls_rejected_total 持续增长,说明业务侧的并发控制和 FCC 配置不一致。

↑ 回到目录


11. 一个可靠的业务后端骨架

把上面的规则合在一起,一个可靠的事件消费者应该长这样:

import asyncio, json
from websockets.asyncio.client import connect

class FccConsumer:
    def __init__(self, db, handler):
        self.db = db                    # 你的数据库:保存 last_sequence、活动 call_id、业务状态
        self.handler = handler          # 业务处理:async def handle(event),必须幂等
        self.queue = asyncio.Queue(maxsize=10000)

    async def run(self):
        asyncio.create_task(self.worker())
        while True:
            try:
                async with connect(WS_URL, additional_headers=AUTH, ping_interval=None) as ws:
                    saved = await self.db.get_last_sequence()
                    await ws.send(json.dumps({"type": "client.hello", "request_id": "h",
                                              "client_id": "biz-1", "protocol_version": 1,
                                              "last_sequence": saved}))
                    hello = json.loads(await ws.recv())
                    if hello["data"]["current_sequence"] < saved:      # FCC 重启过
                        await self.db.set_last_sequence(0)
                        await self.reconcile()
                    async for raw in ws:                               # 只负责收,不做慢操作
                        ev = json.loads(raw)
                        if ev.get("type") == "resume.failed":
                            await self.reconcile()
                        elif "sequence" in ev:
                            await self.queue.put(ev)
            except Exception:
                await asyncio.sleep(2)

    async def worker(self):
        while True:
            ev = await self.queue.get()
            if await self.db.seen(ev["sequence"]):                     # 去重
                continue
            await self.handler(ev)                                      # 先处理、落库
            await self.db.set_last_sequence(ev["sequence"])            # 再保存序号

    async def reconcile(self):
        for call_id in await self.db.active_call_ids():
            ...  # GET /calls/{call_id},按第 7 章处理

要点回顾:

  1. 一条 WebSocket,收事件和处理事件分开;
  2. 先处理再保存序号,处理本身按 sequence 去重;
  3. 发现 FCC 重启或续传失败,先对账再继续;
  4. 外呼一律带稳定的 request_id;
  5. 驱动"通话结束"的只有 call.hangup。

主篇的 controller.py 和系列 3 的 dialer.py 是这个骨架的简化版。

↑ 回到目录


12. 安全与部署

  • Token:所有接口(包括健康检查、指标、OPTIONS、WebSocket Upgrade)都要 Bearer Token。同一 IP 在 auth_failure_window_sec(60 秒)内失败 auth_max_failures(5)次,锁定 auth_lockout_sec(300 秒),期间返回 429 AUTH_LOCKED;
  • 监听:默认只监听 127.0.0.1。模块只提供明文 HTTP/WS,跨机器访问必须加 TLS 反向代理、防火墙和来源限制。Nginx 配置示例见 mod_fcc 仓库的 README;
  • 输入:不要把用户输入直接当作 callee(含 / 时会被当成完整 endpoint)、file、gateway、destination 或队列名;
  • 请求:只支持定长请求体(Content-Length),最大 1 MiB,5 秒内必须收完;不支持 Transfer-Encoding: chunked(返回 501)。

↑ 回到目录


13. 什么时候该换成 ESL

FCC 适合快速验证业务、搭建标准的呼叫中心流程。出现下面这些需求时,说明该直接使用 ESL(或者在 FCC 旁边加一个 ESL 程序)了:

  • 需要 FCC 白名单以外的命令:录音(uuid_record)、会议、设置任意通道变量、uuid_setvar 等;
  • 需要订阅 FCC 没有转换的原始事件,比如推流模块的 taering_stream::* 事件;
  • 需要按通道粒度精细控制媒体(比如三方通话、监听、强插);
  • 单机并发很高,需要把控制面从 FreeSWITCH 进程里拆出去。

FCC 和 ESL 可以共存:用 FCC 做呼叫和坐席的主流程,用 ESL 补充 FCC 不覆盖的部分。


相关链接

系列文章

↑ 回到顶部


评论