RustPBX 概览

RustPBX 是一个用 Rust 编写的云原生 PBX,面向语音 AI、呼叫中心和企业级电话业务场景,强调稳定性、低延迟和可观测性。

本概览介绍在部署系统前需要了解的核心能力,内容对应 0.5.x 版本系列。

语音助手(Voice Agent)功能已拆分到独立项目:Active Call。

RustPBX 现在专注于 SIP 代理和 PBX 功能。

平台定位

统一语音平面:SIP 信令、媒体代理、通话记录、计费和访问控制运行在同一个进程内。
配置驱动架构:行为通过 TOML 文件和数据库实体编排,天然适配 DevOps/GitOps 流水线。
原生集群能力:分布式会话注册表、跨节点会话用户数据、按归属节点路由的操作指令,让多节点部署成为一等公民。

以上所有能力都通过内置 Web 控制台管理——分机、中继、路由、带逐通追踪的通话记录、报表和诊断:

0.5.x 版本亮点

集群会话注册表:通话在全集群范围内可见、可操作;会话 user_data 跨节点复制并在转接后保留,CRM 工单号、营销活动标签等业务上下文不会在通话中途丢失。
转接加固:盲转/咨询转 REFER 支持 B2BUA 兜底,保留应用侧接管能力,转接头字段可选择透传到外呼 INVITE。
逐通媒体证据:RTCP 丢包、relay 丢包、腿媒体完整性直接写入 CDR,与腿时间线、统一呼叫错误参考并列呈现。
AI 语音管线:逐通转写计划(供应商、语言、自动启动)、面向 LLM 智能体的 realtime AI-voice bridge、支持动态 TTS 提示音别名的 IVR 流程。
网络会议:编程方式创建会议室、REFER 加入、空房间 watchdog 自动回收。
存储能力升级:S3 presigned 下载 URL、匿名 S3 访问、可配置 HTTP 上传 scheme、录音上传重试 worker。
更智能的队列:遇忙插叫(busy-wait camp-on)、顺序溢出(sequential overflow)、按队列统计等待深度,以及全局 queue_hold_music / voicemail_greeting 默认值。

核心模块地图

目录 / 模块	职责
`src/call/`	呼叫控制、IVR 逻辑、策略、逐通状态机
`src/proxy/`	SIP 代理、ACL 执行、活动呼叫与集群会话注册表、路由引擎、中继管理、定位器、紧急呼叫路由
`src/rwi/`	Real-time WebSocket Interface —— WebSocket 发布/订阅网关,承载呼叫控制、队列事件、语音助手指令,以及带重试/指标/热更新的专用 webhook 运行时
`src/media/`	RTP/SRTP 媒体代理、SDP 协商、混音/转码、WebRTC 媒体桥接、逐通媒体质量证据
`src/report/`	统一多插件报表层(技能组优先的 CC 报表、中继/域报表、热力图、运行时快照)
`src/outbound/`	外呼调度器,带事件与 webhook
`src/models/`	分机、中继、路由、计费、队列、在线状态、RBAC 等数据库实体
`src/console/`	Web 控制台 API、中间件、会话认证、i18n
`src/api/`	带令牌认证的版本化 HTTP API 树
`src/handler/`	AMI(健康检查、对话框、事务、reload、集群感知的活动呼叫查询)与 HTTP 中间件
`src/auth/`	认证后端:JWT、HTTP token、手机号
`src/callrecord/`	CDR 写入、腿时间线、录音/SipFlow 上传、存储后端
`src/sipflow/`	SIP/RTP 流量捕获,FlowDB LSM-tree 存储引擎与远程集群模式
`src/storage/`	对象存储抽象(S3 presigned URL、Azure Blob、GCP)
`src/tts/`	文本转语音集成(CLI 与 HTTP 驱动)
`src/bin/`	二进制入口:`rustpbx`(主 PBX)与 `sipflow`(独立捕获服务)
`config/`	中继、路由、队列、IVR、ACL、录音、CDR、语音模型等运行时配置
`addons/`	社区与商业功能插件架构(呼叫中心、wholesale、IVR 编辑器、语音信箱等)

典型工作流

准备环境:通过容器或裸机部署,并完成“基础安装“章节。
打通链路:添加 SIP 中继、路由策略和计费模板(“路由、中继与计费”)。
分发流量:配置分机、队列和策略,让呼叫到达正确的目的地(“分机管理”)。
监控与诊断:依靠诊断页、呼叫追踪和健康探针验证变更(“诊断“与“运维手册”)。
持续运营:编辑 config.toml 启用高级功能,出现故障时参考“故障排查“。

文档导航

基础安装:部署、安装、第一条中继与初始配置。
分机管理:坐席账号、设备设置、生命周期钩子与安全。
路由、中继与计费:端到端线路管理、计费实践、紧急呼叫路由与 DID 号码池。
诊断:reload 流程、路由评估、健康检查、呼叫追踪、SipFlow 查询与日志辅助。
运维手册:日常例行工作、发布流程、备份、合规与指标。
集群部署:多节点集群、会话注册表、节点间事件同步、SipFlow 集群与负载均衡。
技术规格:兼容性说明、性能指导、SDES-SRTP 与存储后端。
故障排查:分类整理的常见问题与推荐恢复步骤。

可以按顺序阅读,也可以直接跳到与当前任务匹配的章节。