VoxyWatch VoxyWatch
开始使用
VoxyWatch 官方文档

VoxyWatch 接入指南与技术参考

VoxyWatch 是一款专为电信工程师和 NOC 运维团队打造的私有化语音网络可观测性与智能诊断平台，完全运行于本地。

默认摄取端口：HEPv1/v2/v3 (UDP/TCP 9060)、SIPREC 或端口镜像。Web 门户：HTTPS 443 端口。

版本说明、签名二进制文件与文档（GitHub）： github.com/VoxyWatch/publish

快速安装

单条命令即可完成全套系统安装（支持 Debian、Ubuntu、Amazon Linux 2023、RHEL/Rocky 等）：

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/install.sh | sudo bash

安装完成后，浏览器访问 https://YOUR-IP。默认账号：admin / voxywatch。免费版支持高达 100 路并发通话。

许可证激活

使用 node /opt/voxywatch/get-hwid.js 或在“设置 → 许可证”中获取硬件 ID。支持两种激活方式：

1. Web 门户激活：在“设置 → 许可证”页面上传您的 .key 文件。

2. 终端激活：将 .key 文件复制到 /etc/voxywatch/license.key（权限 640）。

# Terminal activation: Copy your license file into place
cp voxywatch.key /etc/voxywatch/license.key
chown root:voxywatch /etc/voxywatch/license.key
chmod 640 /etc/voxywatch/license.key

SBC 兼容性与流量摄取方式

全面兼容主流 SBC 与网关（Cisco、AudioCodes、Ribbon、Kamailio、Asterisk、Metaswitch 等）。

3 种通用摄取方式

根据网络拓扑灵活选择最适合的接入方式：

  • 1. HEP (v1 / v2 / v3)： 通过 UDP/TCP 9060 端口接收封装的 SIP 信令与 RTCP 遥测数据。
  • 2. SIPREC (原生 SRS)： 会话录音协议（RFC 7865/7866），支持双声道音频直接重建。
  • 3. Port Mirroring / Traffic Mirroring (SPAN, ERSPAN, 云端镜像)： 通过交换机或云端被动复制网络报文（支持 Cisco SPAN/RSPAN/ERSPAN、Juniper/MikroTik/Arista Port Mirroring、AWS VPC Traffic Mirroring [VXLAN]、GCP Packet Mirroring、VMware vSwitch），由 voxywatch-probe 接收，无需修改 SBC 配置。
网络与防火墙规划： 端口需求取决于摄取方式：端口镜像使用无监听端口的专用网卡，而 HEP 和 SIPREC 使用特定的 UDP/TCP 端口。详情请参阅 GitHub 平台与抓包验证指南 ↗

voxywatch-probe — 轻量化抓包探针

基于 Go + libpcap 开发的独立探针，可从镜像网口被动嗅探 SIP/RTP/RTCP 并以 HEPv3 转发至 VoxyWatch。

安装至服务器或采集节点（只读被动抓包）：

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/voxywatch-probe/master/install.sh | sudo bash -s -- --server YOUR_VOXYWATCH:9060

作为 systemd 守护进程常驻运行。使用 systemctl status voxywatch-probe 查看状态。

各机型配置手册与兼容性列表： github.com/VoxyWatch/voxywatch-probe/docs/sbc.

SNMP 代理与 Traps 告警

内置 SNMP v2c/v3 代理与边缘触发 Traps，可轻松集成至 PRTG、Zabbix、Nagios 及企业 NMS 系统。

公开指标： 包含 30 多个 OID，覆盖系统健康度与 VoIP KPI（ASR、NER、MOS、抖动、丢包）。

Traps 告警： 在抓包中断或话音质量恶化时即刻触发告警。

在“设置 → SNMP”中下载 MIB 并配置凭据。默认端口：UDP 161 (Agent) / UDP 162 (Traps)。

事件与 NOC 智能诊断

检测到的异常将生成具有完整时间线的事件，并在网络恢复稳定后自动关闭。

基于遥测的自动化根因分析

VoxyWatch 自动关联失败呼叫样本、SIP 错误码及 IP 路径，秒级定位故障根因。

统计置信度

仅在确认持续偏离基线时产生告警（实测减少 92% 的误报干扰）。

Telegram 与 SMTP 邮件告警

严重事件将实时推送至手机或 NOC 邮箱，附带根因诊断与操作按钮（确认 · 调查）。

2 分钟快速配置

  1. 在“设置 → 通知”中根据向导创建 Telegram 机器人。
  2. 运维人员通过一次性验证码绑定个人或群组会话。
  3. 按需设置告警等级与接收通道。

所有操作均记录至门户运维审计日志。

SMTP 邮件告警

内置 SMTP 引擎，可直接将事件推送到值班邮件列表。

规划中： Microsoft Teams 与 Slack 专用 Webhook 集成正在开发中。

MCP 服务器 (Model Context Protocol)

将 Claude Desktop、Cursor 等 AI 助手直接连接至话音网络遥测，无需赋予 Shell 或数据库权限。

安全隔离与防护

  • 12 项只读运维工具： 实时查询话务量、MOS 质量、事件、CDR 及欺诈证据。
  • 杜绝 Shell 与 SQL 执行： 严格沙箱隔离，无法执行终端命令或更改路由。
  • 细粒度安全认证： 专属 MCP API Key 鉴权与本地审计保护。

配置指南： GitHub 上的 MCP 服务器文档 ↗

Flash Call 与反欺诈预警

被动监测闪断认证呼叫与国际话务异常，不干涉正常业务路由。

Flash Call 闪断检测

通过端口镜像、HEP 或 SIPREC 被动识别零时长自动化认证呼叫（A2P OTP），支持 Shadow 影子或 Alert 告警模式。

反欺诈情报

对高风险国际目的地突增、短呼叫风暴等中继话务异常提供早期预警。

100% 被动观测：VoxyWatch 绝不阻断或修改任何 SBC 通话。

技术规范： GitHub 上的 FLASH_CALL_DETECTION.md ↗

PCI-DSS 音频合规抑制

在报文源头（voxywatch-probe）精准丢弃电话支付期间的敏感 RTP 音频，确保银行卡信息不经过网络、不进入存储。

工作原理

探针端动态热加载抑制规则，无需重启任何服务。

呼叫中心业务联动

坐席在 CRM 中点击暂停录音时，系统联动通知探针实时停止发送音频流。

完整技术规范： GitHub 上的 PCI-DSS 技术文档 ↗ 包含详细 JSON 结构。

通话语音转写

从捕获的通话音频中生成可检索、可导出的双声道文本。

核心能力

  • 在通话详情页面按需针对单通电话生成转写文本。
  • 双声道立体声独立转写并按时间戳精准对齐。
  • 交互式播放器：转写文本段落可点击并同步跳转播放音频。
  • 多格式导出：支持下载 TXT、JSON 及 SRT 字幕文件。
  • 支持在转写呼叫库中进行全文关键词检索。

安全与合规

完全运行于私有基础设施（0600 权限），严格遵循 PCI-DSS 音频抑制规则。

技术文档： GitHub 上的 SPEECH_TO_TEXT_BETA.md ↗

服务器容量计算器

根据并发通话量与存储保留周期，快速测算所需的服务器硬件配置。

服务器大小计算器

源自生产中的真实测量结果（1104 个样本）。根据您的负载估计硬件。

高级选项（ACD、编解码器、录制百分比）

推荐规格

测量的
虚拟CPU8
内存16 GB
磁盘—
IOPS—
网络—
同时通话—
— 录音 — SIP/CDR SSD · 磁盘类型
AWS实例—
相当于 GCP—

目标利用率模型 0.65（35% 标头）。大小按峰值计算，而不是平均值。如需 >300 CPS，请联系我们。

NOC AI 运维副驾驶

智能分析中继指标与异常特征，以清晰的自然语言解释故障根因。严格保持只读模式。

自带密钥 (BYOK) — 在“设置 → AI”中配置：

支持 OpenAI、Anthropic Claude、Google Gemini 及本地 Ollama 大模型。

平台持续更新并适配最新 AI 模型，以获得更优的推理分析能力。

请求在本地缓存保护，未经配置不会向外发送任何数据。

集成 API /api/v1

专为计费、工单及监控系统设计的只读 REST API。

可用接口： CDR 查询、SIP JSON 追踪、PCAP 数据导出与音频流下载。

安全认证： 权限分离的 API Key 鉴权，支持 IP 白名单与 RFC 9457 错误响应规范。

在“设置 → API 密钥”中管理。示例请求：

curl -H "Authorization: Bearer YOUR_KEY" \
     https://YOUR-VOXYWATCH/api/v1/cdr?from=2026-06-01&to=2026-06-07&carrier=acme

账单、付款与取消

许可证付款、订阅管理与发票均由 Stripe 提供安全处理。

VoxyWatch 为软件许可方，Stripe 为官方支付处理商。

管理订阅或下载发票请访问 Stripe 客户门户：

打开 Stripe 门户

使用购买邮箱接收一次性验证码即可登录。

取消订阅

支持随时取消，服务将持续至当前计费周期结束。

退款政策

若软件无法在您的网络环境中正常运行，支持 14 天内全额退款。