跳到主要内容

故障与问题分类

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

1. 注册/信令问题​

症状排查步骤解决方案
分机无法注册Diagnostics → SIP → Locator registry，检查是否存在绑定/到期时间核对分机密码、SIP 端口、防火墙；必要时重置密码或清除陈旧绑定
Trunk 状态异常Diagnostics → Trunks 运行探测或 OPTIONS Probe确认对端 IP、鉴权方式；在 config/trunks 中启用备用线路
Invite 无响应使用 sngrep 或 Diagnostics → Routing Evaluate 确认是否命中规则检查路由是否匹配、是否被 ACL 拒绝

2. 媒体与质量问题​

  1. 单向音/无音：
    • 检查服务器与对端的 NAT/端口映射；
    • 确认 config.toml 中 rtp_start_port/rtp_end_port 范围已开放并在防火墙放行；
    • 使用 Diagnostics → Web Dialer 或真实终端复现，并在服务器上通过 tcpdump/sngrep 检查 RTP 是否返回。
  2. 噪音/抖动：
    • 切换到低码率编解码；
    • 启用 fixtures/ 中的降噪模型或在终端开启回声消除；
    • 检查链路 QoS 与带宽。

3. 路由与计费问题​

  • 路由未生效：确认是否执行了 Reload；查看 config/routes 是否语法错误（可用 tomlcheck 或 CI 校验）。
  • 误路由：使用 Diagnostics → Routing Evaluate 查看匹配到的 rule/trunk，必要时调整 priority 或 match 条件。
  • 计费异常：在 Call Records 中导出 CDR，核对计费模板；若缺少匹配的 prefix，会记录 no_rate 告警。

4. 控制台/接口问题​

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

5. 性能与稳定性​

  • CPU 过高：使用 top/bt 定位线程，可适当降低并发或扩容节点；检查是否大量进行编解码转换。
  • 内存持续增长：确认是否启用了大量录音缓存；检查 callrecord/storage.rs 的清理计划。
  • 崩溃/重启：查看 systemd journal 或容器日志，通常是配置格式错误或依赖服务（数据库、Redis）不可达。

6. 故障处理流程建议​

  1. 收集信息：截图 Diagnostics、导出日志、记录时间范围。
  2. 快速回滚：若为配置变更导致，使用 Git 回滚 config/ 并 Reload。
  3. 验证修复：执行测试呼叫、检查 CDR/告警是否恢复正常。
  4. 复盘归档：将原因、影响、修复步骤记录到内部 wiki，便于下次复用。

（此处可插入“故障流程图”截图）