诊断工具

RustPBX 的 Diagnostics 页面与相关 API 集中提供线路验证、路由模拟、注册状态与测试拨号等能力，是日常排障的核心入口。

1. Reload 与预检

触发方式：
- UI：Settings → Reload，可单独 Reload Routing、ACL 或整套应用。
- API：调用 AMI/管理接口的 /reload/acl、/reload/app 等端点，便于脚本化发布。
预检逻辑：preflight::validate_reload 会阻止危险配置，例如删除 console 配置、移除仍被使用的 Trunk、ACL 语法错误等。
处理提示：若提示 Reload would disable the console，请在 config.toml 中恢复 [console] 段；若提示 Trunk 缺失，则需在数据库/配置文件中补齐映射。

Reload 面板

2. Diagnostics 面板解读

Diagnostics 页面包含多个标签页，对应的功能均在 templates/console/diagnostics.html 中实现：

Connection：展示 realm、可用传输（UDP/TCP/TLS/WebSocket）、示例账号，并附带 WebRTC ICE Probe，可验证 [ice_servers] 配置是否生效。
Trunks：读取运行时 Trunk Snapshot，通过 /diagnostics/trunks/test 校验某个 IP/域名是否匹配 inbound_hosts/dest，并可向运营商发送 OPTIONS 探测。
Routing：/diagnostics/routes/evaluate 支持对 runtime 或 database 数据集进行规则匹配模拟，输出命中的 route、selected trunk、rewrite、Queue/IVR 结果以及可选的 abort code。
SIP：
- Active SIP dialogs：列出当前 INVITE 对话，可展开查看 SDP Offer/Answer。
- Locator registry：通过 /diagnostics/locator/* 查询或清理注册记录，定位分机注册异常。
Web Dialer：嵌入 JsSIP，结合 Connection 面板提供的账号即可在浏览器里直接拨测，并记录最近 80 条 WebSocket 消息帮助排查信令问题。

Diagnostics 标签页

3. 日志、健康检查与外部工具

日志：在 config.toml 中配置 log_level、log_file 和 log_rotation。文件日志使用 tracing 结构化格式，支持可选的日志轮转（hourly/daily）。业务类拒绝日志为 WARN,SIP 协议栈噪音被抑制,故障时间窗内的日志保持可读。
通话记录：callrecord 模块负责 CDR 写入和录音 URL 管理；控制台的 Call Records 页面从 models::call_record 读取数据进行对账。每条记录带有腿时间线（每条腿的振铃/应答/保持/转接标记）、命中路由（id 与名称）以及最终 SIP 响应码。
媒体证据：应答后的 Trunk 腿会在 CDR 中上报基于 RTCP 的质量指标——media_loss_pct、media_jitter_ms、media_rtt_ms;从未交付媒体的腿会被标记为 proxy.leg_media_incomplete,而不是静默计入健康应答。
错误参考：影响通话的失败会发出统一的 call_error 事件并归一化到共享错误目录;控制台的记录详情页将呼叫追踪时间线与错误参考并列呈现,“为什么这通电话失败了“基本不用再打开 PCAP。
健康探针：handler::ami 暴露 /health 端点，报告数据库、SIP 核心和任务状态;集群节点还会暴露会话心跳 gauges。可供负载均衡器或 perfcli --ping 消费。
流量捕获：平台未内置抓包按钮——运行 sngrep、tcpdump，或通过 Web Dialer 重现场景后手动抓取 RTP/SIP。
Prometheus 指标：GET /metrics 导出 Prometheus 格式的指标，包括 SIP 注册数、对话数、Trunk 呼叫速率、RTP 统计、队列等待时间和系统资源信息。
SipFlow 查询：通过 GET /sipflow/flow/{call_id} 查询 SIP 信令流，GET /sipflow/media/{call_id} 查询 RTP 媒体流。控制台的 SipFlow 页面提供浏览已捕获呼叫的 UI。
报表：GET /reports/v2/call|trunk|… 提供按时间分桶的呼叫/中继/域报表并支持 CSV 导出;控制台 Reports 页面以热力图和快照差值可视化。
频率限制：GET /frequency_limits 列出当前活跃的限流封锁；DELETE /frequency_limits 清除全部封锁。在应急响应中可用于监控异常封锁模式。
Trunk 注册状态：GET /trunk_registrations 返回所有外呼 Trunk 的注册状态，包括过期计时器和上次错误码。

4. AMI API 参考

诊断 REST API 通过 {ami_path}（默认 /ami/v1）暴露：

方法	路径	说明
`GET`	`/health`	节点健康（版本、运行时间、活跃通话、任务状态、SipFlow 统计）
`GET`	`/dialogs`	列出所有活跃 SIP 对话及 SDP 详情
`GET`	`/hangup/{id}`	强制挂断指定对话
`GET`	`/transactions`	列出正在运行的 SIP 事务
`POST`	`/shutdown`	优雅关闭
`POST`	`/reload/trunks`	重新加载 SIP Trunk 配置
`POST`	`/reload/routes`	重新加载路由规则
`POST`	`/reload/acl`	重新加载 ACL 规则
`POST`	`/reload/app`	完整应用重载（包含预检验证）
`GET`	`/trunk_registrations`	获取 Trunk 注册状态
`GET/DELETE`	`/frequency_limits`	列出或清除频率限制
`GET`	`/sipflow/flow/{call_id}`	查询呼叫的 SIP 信令流
`GET`	`/sipflow/media/{call_id}`	查询呼叫的 RTP 媒体流

5. 常见排查路径

场景	排查顺序
路由没生效	Settings → Reload → Diagnostics → Routing（Evaluate database & runtime）→ 检查 `config/routes/*.toml` 语法
注册失败	Diagnostics → SIP → Locator registry → 确认绑定是否存在 → 结合 `proxy.acl_rules` 检查 IP 是否被拒绝
Trunk 拨入被拒	Diagnostics → Trunks → 输入对端 IP/IP 域名 → 看是否匹配 `inbound_hosts`，必要时调整 `config/trunks/*.toml`
单向音/媒体异常	确认 `rtp_start_port`/`rtp_end_port` 开放 → 使用 Web Dialer 或真实终端复现 → 在服务器上抓取 RTP 并检查 NAT/防火墙
计费或队列异常	在 Call Records 中核对模板 → Diagnostics → Routing 查看是否命中期望的 route/queue

6. 自动化与脚本

Reload Pipeline：CI 在修改 config/、config.toml 后，可调用 /reload/acl、/reload/app 完成热加载，并读取 HTTP 响应判断是否通过 Preflight。
健康监控：使用 curl http://<host>:8080/health（或相应暴露端口）探测，若 status 字段非 ok，可触发告警或摘除实例。
性能回归：examples/perfcli.rs 支持批量注册/呼叫，结合 Diagnostics → Routing 结果可快速验证优化是否生效。

熟悉上述工具后，即可把“改配置→Reload→验证“这一闭环控制在分钟级，显著降低线路运维成本。