故障与问题分类

遇到异常时请优先确认 Diagnostics 面板与系统日志。本节整理了最常见的问题模式、定位思路与建议命令。

1. 注册/信令问题

症状	排查步骤	解决方案
分机无法注册	Diagnostics → SIP → Locator registry，检查是否存在绑定/到期时间	核对分机密码、SIP 端口、防火墙；必要时重置密码或清除陈旧绑定
Trunk 状态异常	Diagnostics → Trunks 运行探测或 OPTIONS Probe	确认对端 IP、鉴权方式；在 `config/trunks` 中启用备用线路
Invite 无响应	使用 `sngrep` 或 Diagnostics → Routing Evaluate 确认是否命中规则	检查路由是否匹配、是否被 ACL 拒绝
ACL 拦截异常流量	ACL 规则仅在入站 Trunk 路径上生效——分机呼出的呼叫不受 ACL 过滤	针对 Trunk 的 `inbound_hosts` 添加 ACL 规则；分机间内部呼叫不走 ACL
被叫对话挂起	转接或 re-INVITE 后旧版本的残留被叫对话可能持续存在	升级至 v0.4.10+，该版本已在 `SipSession` 中优化了被叫对话管理

单向音/无音：
- 检查服务器与对端的 NAT/端口映射；
- 确认 config.toml 中 rtp_start_port/rtp_end_port 范围已开放并在防火墙放行；
- 使用 Diagnostics → Web Dialer 或真实终端复现，并在服务器上通过 tcpdump/sngrep 检查 RTP 是否返回。
- 查看 CDR 中的媒体证据:proxy.leg_media_incomplete 标记从未交付媒体的腿;media_loss_pct/media_jitter_ms/media_rtt_ms 展示该 Trunk 腿应答后的质量。
- 在 EIP/NAT 等直连容易失败的环境,可打开 dialplan 级 relay_only 开关,强制媒体走代理中继。
噪音/抖动：
- 切换到低码率编解码；
- 启用 fixtures/ 中的降噪模型或在终端开启回声消除；
- 检查链路 QoS 与带宽。
通话中媒体停滞（0.5+）：媒体桥会检测停滞的媒体流并尝试恢复;若停滞与特定运营商相关,结合 CDR 媒体指标与 SipFlow 捕获定位,并对严格 full-ICE 对端考虑开启 ice_lite = true。

路由未生效：确认是否执行了 Reload；查看 config/routes 是否语法错误（可用 tomlcheck 或 CI 校验）。
误路由：使用 Diagnostics → Routing Evaluate 查看匹配到的 rule/trunk，必要时调整 priority 或 match 条件。CDR 会记录命中的路由 id/名称,可以精确确认历史通话走了哪条规则。
转接失败：0.5 加固了 REFER 处理,支持 B2BUA 兜底与应用侧接管保留。转接失败时,检查通话记录腿时间线中的转接标记以及目标是否拒绝（409 = 咨询转未被应答）;运营商需要上下文头时,在相关 Trunk 上开启转接头透传。
计费异常：在 Call Records 中导出 CDR，核对计费模板；若缺少匹配的 prefix，会记录 no_rate 告警。

无法登录：检查 console 段配置与数据库连接；确认浏览器时间同步以避免 Token 过期。
API 500 错误：查看 logs/console（或 stdout）中的堆栈；多数为配置缺失或数据库迁移未完成。
Diagnostics 空白：多发生在未启动 SIP server 或登录账号无权限的场景；确认 RustPBX 主进程健康（/health 返回 ok）并确保当前用户拥有 diagnostics 访问权。

CPU 过高：使用 top/bt 定位热点线程，降低并发或扩展节点，检查是否存在过度转码。SRTP 加密的 RTP 代理是 CPU 的主要消耗者——预估每个 vCPU 可承载 5–8 路并发呼叫。
内存增长：检查 callrecord/storage.rs 中录音缓冲区的清理逻辑。长时间通话配合大录音缓冲区（尤其在 SipFlow 捕获模式下）可能导致内存累积。如发现泄漏模式，在维护窗口重启节点。
呼叫生命周期泄漏：确保 call-lifecycle 资源被正确释放。v0.4.10 之前的版本中，某些呼叫拆除路径可能保留会话状态。如果观察到与呼叫量成正比的增长，请升级到最新版本。
崩溃/重启：查阅 journalctl 或容器日志——配置语法错误或依赖不可达（DB/Redis）是常见原因。二进制会自动重试并指数退避（最多 10 次）。
并发呼叫限制：每条 Trunk 的 max_calls 和每个租户的 max_concurrency 独立生效。超出限制将返回 SIP 503。在 Diagnostics → Trunks 中查看容量使用情况。