Guia de Configuração do SIP VAULT

Este guia detalha todas as opções de configuração do servidor SIP VAULT, API, agente, política de retenção, proxy reverso nginx, integração com OpenSIPS e parâmetros de análise de qualidade.

Sumário

Configuração do Servidor
Configuração da API
Configuração do Agente
Política de Retenção
Configuração do nginx
Requisitos de Configuração do OpenSIPS
Limiares de Qualidade e Vereditos
Suporte a Codecs

Configuração do Servidor

O sipvault-server lê a configuração a partir de variáveis de ambiente, com fallback opcional para um arquivo de configuração JSON em /etc/sipvault/server.conf. Variáveis de ambiente sempre têm precedência sobre o arquivo.

O arquivo de ambiente está localizado em /etc/sipvault/server.env e é carregado pelo serviço systemd.

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`SIPVAULT_LISTEN_TCP`	Não	`:9060`	Endereço do listener TCP para conexões do agente. Formato: `[host]:port`
`SIPVAULT_LISTEN_HEP`	Não	`:9060`	Endereço do listener UDP para pacotes HEP v3 RTCP. Formato: `[host]:port`
`SIPVAULT_S3_ENDPOINT`	Sim	--	URL do endpoint Cloudflare R2: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`
`SIPVAULT_S3_REGION`	Não	`auto`	Região do S3. Cloudflare R2 sempre usa `auto`
`SIPVAULT_S3_ACCESS_KEY`	Sim	--	Access key ID do Cloudflare R2
`SIPVAULT_S3_SECRET_KEY`	Sim	--	Secret access key do Cloudflare R2
`SIPVAULT_CUSTOMERS`	Sim	--	Array JSON de configurações de clientes (veja abaixo)
`SIPVAULT_LOG_LEVEL`	Não	`info`	Nível de log: `debug`, `info`, `warn`, `error`

Configuração de Clientes (SIPVAULT_CUSTOMERS)

A variável SIPVAULT_CUSTOMERS é um array JSON onde cada elemento define um cliente:

[
  {
    "id": "acme",
    "token": "a1b2c3d4e5f6...",
    "bucket": "sipvault-acme-us"
  },
  {
    "id": "globex",
    "token": "f6e5d4c3b2a1...",
    "bucket": "sipvault-globex-eu"
  }
]

Campo	Obrigatório	Descrição
`id`	Sim	Identificador único do cliente. Usado nos caminhos S3 e na validação de token
`token`	Sim	Token de autenticação que os agentes usam para conectar. Deve corresponder ao `[server] token` do agente
`bucket`	Sim	Nome do bucket R2 para este cliente. Convenção: `sipvault-{customer_id}-{region}`

Em uma variável de ambiente em linha única:

SIPVAULT_CUSTOMERS=[{"id":"acme","token":"a1b2c3d4e5f6","bucket":"sipvault-acme-us"}]

Exemplo de server.env

SIPVAULT_LISTEN_TCP=:9060
SIPVAULT_LISTEN_HEP=:9060
SIPVAULT_S3_ENDPOINT=https://abcdef1234567890.r2.cloudflarestorage.com
SIPVAULT_S3_REGION=auto
SIPVAULT_S3_ACCESS_KEY=your_r2_access_key
SIPVAULT_S3_SECRET_KEY=your_r2_secret_key
SIPVAULT_CUSTOMERS=[{"id":"acme","token":"securetoken123","bucket":"sipvault-acme-us"}]
SIPVAULT_LOG_LEVEL=info

Estrutura de Caminhos no S3

O servidor grava dados de chamadas no S3 usando esta convenção de caminhos:

{bucket}/calls/{YYYY}/{MM}/{DD}/{call_id}/
  sip.pcap.gz          # SIP packets (GZIP compressed)
  rtcp.json.gz         # Raw RTCP reports (GZIP compressed)
  quality.json          # Quality analysis report
  log-000001.gz        # OpenSIPS log chunk 1 (GZIP compressed)
  log-000002.gz        # OpenSIPS log chunk 2
  ...

Máquina de Estados da Sessão de Chamada

O servidor gerencia sessões de chamada com os seguintes estados:

Estado	Timeout	Gatilho	Descrição
PENDING	5 minutos	INVITE recebido	Aguardando o setup da chamada completar
ACTIVE	30 minutos (inatividade)	Chamada estabelecida	Logs são gravados como chunks GZIP de 60 segundos
CLOSING	5 segundos (período de graça)	BYE ou CANCEL recebido	Aguardando pacotes finais
COMPLETE	--	Período de graça expira	Todos os dados gravados no S3

Configuração da API

O serviço FastAPI lê a configuração a partir de variáveis de ambiente. O arquivo de ambiente está em /etc/sipvault/api.env.

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`SIPVAULT_S3_ENDPOINT`	Sim	--	URL do endpoint Cloudflare R2
`SIPVAULT_S3_REGION`	Não	`auto`	Região do S3
`SIPVAULT_HMAC_SECRET`	Sim	--	Segredo HMAC-SHA256 para validação de tokens. Deve corresponder ao segredo de integração do CDR Viewer
`SIPVAULT_HMAC_MAX_AGE`	Não	`3600`	Idade máxima do token em segundos (padrão: 1 hora)
`SIPPULSE_API_URL`	Não	`https://api.sippulse.ai/v1`	Endpoint da API SipPulse AI para a funcionalidade de chat
`SIPPULSE_API_KEY`	Não	--	Chave da API SipPulse AI
`SIPPULSE_AI_MODEL`	Não	`glm-4.7`	Modelo de IA a ser usado para análise via chat
`ANTHROPIC_API_KEY`	Não	--	Chave da API Anthropic (provedor de IA alternativo)
`AWS_ACCESS_KEY_ID`	Sim	--	Access key do R2 para gerar URLs pré-assinadas
`AWS_SECRET_ACCESS_KEY`	Sim	--	Secret key do R2 para gerar URLs pré-assinadas

Exemplo de api.env

SIPVAULT_S3_ENDPOINT=https://abcdef1234567890.r2.cloudflarestorage.com
SIPVAULT_S3_REGION=auto
SIPVAULT_HMAC_SECRET=YOUR_HMAC_SECRET_HERE
SIPVAULT_HMAC_MAX_AGE=3600
SIPPULSE_API_URL=https://api.sippulse.ai/v1
SIPPULSE_API_KEY=your_sippulse_ai_key
SIPPULSE_AI_MODEL=glm-4.7
ANTHROPIC_API_KEY=your_anthropic_key
AWS_ACCESS_KEY_ID=your_r2_read_access_key
AWS_SECRET_ACCESS_KEY=your_r2_read_secret_key

Gerando o Segredo HMAC

Use um gerador criptograficamente seguro:

openssl rand -hex 32

Este mesmo segredo deve ser configurado em: - /etc/sipvault/api.env como SIPVAULT_HMAC_SECRET - O código de integração do CDR Viewer (PHP/Python/Node.js)

Configuração do Agente

O agente lê sua configuração a partir de um arquivo em formato INI em /etc/sipvault/agent.conf. O arquivo é dividido em quatro seções.

Referência Completa de Configuração

[server]
# Server address in HOST:PORT format (required)
address = 10.0.0.1:9060

# Customer identifier, must match server SIPVAULT_CUSTOMERS[].id (required)
customer_id = acme

# Authentication token, must match server SIPVAULT_CUSTOMERS[].token (required)
token = securetoken123

[capture]
# Capture mode: auto, ebpf, or pcap (default: auto)
# auto = select based on kernel version (ebpf if >= 4.18, pcap otherwise)
mode = auto

# Comma-separated SIP ports to monitor (default: 5060)
sip_ports = 5060

# Network interface for packet capture (default: auto-detected from default route)
interface = eth0

# OpenSIPS log file path for pcap mode log tailing (default: empty = disabled)
# In eBPF mode, logs are captured via kprobe on sendmsg instead
log_file = /var/log/opensips.log

# RTP port range for RTCP capture (default: 10000-30000)
# Should match your RTPProxy/RTPEngine port range
rtp_port_min = 10000
rtp_port_max = 30000

[buffer]
# Path to the disk buffer file (default: /var/lib/sipvault/buffer.dat)
path = /var/lib/sipvault/buffer.dat

# Maximum disk buffer size in bytes (default: 104857600 = 100 MB)
# When the TCP connection to the server is lost, data is buffered locally
max_size = 104857600

[logging]
# Log level: debug, info, warn, error (default: info)
level = info

Seção: [server]

Chave	Obrigatória	Padrão	Descrição
`address`	Sim	--	Endereço do servidor SIP VAULT como `host:port`
`customer_id`	Sim	--	Identificador do cliente
`token`	Sim	--	Token de autenticação

Seção: [capture]

Chave	Obrigatória	Padrão	Descrição
`mode`	Não	`auto`	Modo de captura: `auto`, `ebpf` ou `pcap`
`sip_ports`	Não	`5060`	Lista de portas SIP separadas por vírgula
`interface`	Não	Auto-detectada	Nome da interface de rede
`log_file`	Não	(vazio)	Arquivo de log do OpenSIPS para o modo pcap
`rtp_port_min`	Não	`10000`	Porta RTP mínima
`rtp_port_max`	Não	`30000`	Porta RTP máxima

Seção: [buffer]

Chave	Obrigatória	Padrão	Descrição
`path`	Não	`/var/lib/sipvault/buffer.dat`	Caminho do arquivo de buffer de disco
`max_size`	Não	`104857600` (100 MB)	Tamanho máximo do buffer em bytes

Seção: [logging]

Chave	Obrigatória	Padrão	Descrição
`level`	Não	`info`	Nível de log

Comparação dos Modos de Captura

Funcionalidade	Modo eBPF	Modo pcap
Requisito de kernel	>= 4.18	Qualquer
Captura SIP/RTCP	Programas XDP/tc BPF	libpcap nas portas SIP/RTP
Captura de logs	kprobe em sendmsg	Acompanhamento de arquivo (`log_file` config)
Build	`go build` (sem CGO)	`go build -tags pcap` (necessita libpcap-dev)
Capabilities	CAP_BPF + CAP_NET_ADMIN + CAP_SYS_PTRACE	root ou CAP_NET_RAW
SO suportado	Ubuntu 18.04+, Debian 10+, CentOS 8+	CentOS 6+, Debian 7+, Ubuntu 14.04+

Exemplo: Modo pcap no CentOS 6/7

[server]
address = 10.0.0.1:9060
customer_id = acme
token = securetoken123

[capture]
mode = pcap
sip_ports = 5060
interface = eth0
log_file = /var/log/opensips.log
rtp_port_min = 10000
rtp_port_max = 30000

[buffer]
path = /var/lib/sipvault/buffer.dat
max_size = 104857600

[logging]
level = info

Política de Retenção

A política de retenção é configurada em /etc/sipvault/retention.yml e determina por quanto tempo cada tipo de dado de chamada é mantido no S3. Uma tarefa cron noturna exclui dados expirados.

Arquivo de Configuração

# /etc/sipvault/retention.yml
# Run nightly via cron: 0 3 * * * /usr/local/bin/sipvault-retention

default:
  sip_pcap_days: 7
  rtcp_raw_days: 7
  quality_json_days: 30
  log_chunks_days: 14

customers:
  # Per-customer overrides using the customer ID as key
  acme:
    sip_pcap_days: 30
    rtcp_raw_days: 30
    quality_json_days: 365
    log_chunks_days: 90

Retenção por Tipo de Dado

Tipo de Dado	Objeto S3	Padrão	Descrição
`sip_pcap_days`	`sip.pcap.gz`	7 dias	Trace de pacotes SIP capturados
`rtcp_raw_days`	`rtcp.json.gz`	7 dias	Dados brutos de relatórios RTCP
`quality_json_days`	`quality.json`	30 dias	Relatório de análise de qualidade computado
`log_chunks_days`	`log-NNNNNN.gz`	14 dias	Chunks de log do OpenSIPS

Configuração do Cron

Adicione a tarefa de retenção ao cron:

sudo crontab -e

0 3 * * * /usr/local/bin/sipvault-retention

Isso executa a limpeza diariamente às 3:00 da manhã.

Configuração do nginx

A configuração do nginx serve o SPA do dashboard e encaminha requisições de API para o backend FastAPI.

Arquivo de Configuração

Localização: /etc/nginx/sites-available/sipvault.conf

server {
    listen 443 ssl http2;
    server_name vault.example.com;

    ssl_certificate /etc/letsencrypt/live/vault.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vault.example.com/privkey.pem;

    # Dashboard SPA
    root /opt/sipvault/dashboard;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support for AI chat streaming
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }

    # SPA fallback — serves index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
    }
}

# HTTP -> HTTPS redirect
server {
    listen 80;
    server_name vault.example.com;
    return 301 https://$host$request_uri;
}

Pontos Importantes de Configuração

SSL/TLS é gerenciado por certificados Let's Encrypt administrados pelo certbot
Proxy da API remove o prefixo /api/ ao encaminhar para o backend FastAPI (via proxy_pass http://127.0.0.1:8000/)
Suporte a SSE para a funcionalidade de chat com IA requer proxy_buffering off e proxy_cache off
Timeout de leitura é definido como 300 segundos para acomodar respostas longas do chat com IA
Fallback do SPA garante que o roteamento client-side funcione ao retornar ao index.html

Personalização do Domínio

O script de setup substitui vault.example.com pelo seu domínio configurado. Para alterá-lo manualmente:

sudo sed -i 's/vault.example.com/your-domain.com/g' /etc/nginx/sites-available/sipvault.conf
sudo nginx -t && sudo systemctl reload nginx

Requisitos de Configuração do OpenSIPS

Para que o SIP VAULT capture dados corretamente, a instalação do OpenSIPS do cliente deve atender a certos requisitos de configuração.

Facilidade de Log

O OpenSIPS deve gravar logs em um arquivo (não apenas syslog) para que o agente capture dados de log no modo pcap:

# opensips.cfg
log_facility=LOG_LOCAL0
log_level=3

Em /etc/rsyslog.d/opensips.conf:

local0.*    /var/log/opensips.log

O parâmetro log_file na configuração do agente deve apontar para este arquivo:

[capture]
log_file = /var/log/opensips.log

Configuração de Sockets

O SIP VAULT captura tráfego nas portas especificadas na configuração sip_ports do agente. Certifique-se de que o OpenSIPS escuta nessas portas:

# opensips.cfg
listen=udp:0.0.0.0:5060
listen=tcp:0.0.0.0:5060

Autenticação

Nenhuma alteração na autenticação do OpenSIPS é necessária. O SIP VAULT captura pacotes de forma passiva; ele não injeta nem modifica tráfego SIP.

Faixa de Portas RTPProxy / RTPEngine

Os parâmetros rtp_port_min e rtp_port_max do agente devem corresponder à faixa de portas do RTPProxy ou RTPEngine:

# rtpproxy startup
rtpproxy -l 0.0.0.0 -m 10000 -M 30000

# opensips.cfg - modparam for rtpproxy
modparam("rtpproxy", "rtpproxy_sock", "udp:127.0.0.1:7722")

Configuração do agente para corresponder:

[capture]
rtp_port_min = 10000
rtp_port_max = 30000

RTCP em Servidor Separado (RTPProxy em Máquina Separada)

Quando o RTPProxy roda em uma máquina separada do OpenSIPS, use o módulo acct_rtcp_hep para enviar dados RTCP diretamente para o servidor SIP VAULT via HEP. Nenhum agente é necessário no servidor de mídia.

Configure o RTPProxy para enviar RTCP via HEP:

# In OpenSIPS or RTPProxy configuration
# HEP destination: sipvault-server:9060/udp
modparam("rtpproxy", "rtpp_flags", "HEP=sipvault-server:9060")

O servidor SIP VAULT escuta em UDP :9060 para pacotes HEP v3.

Limiares de Qualidade e Vereditos

O SIP VAULT usa o modelo E da ITU-T G.107 para computar métricas de qualidade de voz. O relatório de qualidade (quality.json) inclui um veredito baseado no R-factor e na pontuação MOS.

Fórmula do Modelo E

O R-factor é calculado como:

R = 93.2 - Id - Ie_eff

Onde: - Id (impairment de atraso): 0.024 * d + 0.11 * (d - 177.3) * H(d - 177.3), com d = RTT / 2 (atraso unidirecional em ms) - Ie_eff (impairment de equipamento): Ie + (95 - Ie) * loss% / (loss% + Bpl), onde Ie e Bpl são constantes específicas do codec - H(x) é a função degrau de Heaviside (0 para x < 0, 1 para x >= 0)

O MOS (Mean Opinion Score) é derivado do R-factor:

MOS = 1 + 0.035 * R + R * (R - 60) * (100 - R) * 7e-6

O MOS é limitado ao intervalo [1.0, 4.5].

Limiares de Veredito

O veredito é determinado pelo pior MOS médio entre as duas direções da chamada (UAC e UAS):

Veredito	Faixa de R-Factor	Faixa de MOS	Satisfação do Usuário
Excelente	> 90	> 4.34	Muito satisfeito
Bom	80 - 90	4.03 - 4.34	Satisfeito
Razoável	70 - 80	3.60 - 4.03	Alguns usuários insatisfeitos
Ruim	60 - 70	3.10 - 3.60	Muitos usuários insatisfeitos
Péssimo	< 60	< 3.10	Quase todos os usuários insatisfeitos

Limiares de Métricas Individuais

Além dos vereditos baseados em MOS, limiares de métricas individuais também afetam o veredito:

Métrica	Limiar de Alerta	Limiar Severo	Impacto
Jitter	> 20 ms	> 50 ms	Qualidade afetada / Veredito Péssimo
Latência (unidirecional = RTT/2)	> 150 ms	> 400 ms	Conversação prejudicada / Veredito Péssimo
Perda de Pacotes	> 1%	> 5%	Artefatos audíveis / Veredito Péssimo

Lógica do veredito: - Péssimo: MOS < 3.10, OU jitter > 50ms, OU perda > 5%, OU latência > 400ms - Ruim: MOS entre 3.10 e 3.60 - Razoável: MOS entre 3.60 e 4.03, OU qualquer limiar de alerta excedido - Bom: MOS > 4.03 e todas as métricas dentro dos limiares de alerta

Detecção de Status de Áudio

O SIP VAULT detecta problemas no caminho de áudio a partir dos padrões de amostras RTCP:

Status	Condição	Descrição
Normal	Ambos UAC e UAS possuem amostras RTCP	Áudio bidirecional confirmado
OWA (One-Way Audio)	Apenas uma direção possui amostras RTCP	Uma parte não consegue ouvir a outra
NOA (No Audio)	Nenhuma direção possui amostras RTCP	Caminho de mídia completamente quebrado

Para condições de OWA e NOA, o relatório de qualidade inclui um objeto diagnostic com campos probable_cause e recommendation para auxiliar na resolução de problemas.

Estatísticas por Direção

Cada direção (UAC e UAS) produz os seguintes resumos estatísticos:

Métrica	Campos	Descrição
MOS	avg, min, max, p5, p95	Mean Opinion Score
Jitter	avg, min, max, p5, p95	Jitter de interchegada em ms
Perda	avg, min, max, p5, p95	Percentual de perda de pacotes
RTT	avg, min, max, p5, p95	Tempo de ida e volta em ms

A série temporal fornece pontos de dados agrupados em intervalos de 5 segundos com MOS, jitter e perda por direção.

Detecção de Perna Degradada

O SIP VAULT identifica qual perna está degradada: - "uac": MOS médio da direção do chamador < 3.5 - "uas": MOS médio da direção do chamado < 3.5 - "both": MOS médio de ambas as direções < 3.5 - (vazio): Nenhuma direção está degradada

Suporte a Codecs

O SIP VAULT usa parâmetros de impairment específicos por codec da ITU-T G.113 Appendix I para cálculo preciso do MOS. O codec é detectado a partir da negociação SDP durante o diálogo INVITE.

Codecs Suportados

Codec	Aliases de Nome	Ie (Impairment de Equipamento)	Bpl (Robustez à Perda de Pacotes)	Observações
G.711 mu-law	pcmu, g711	0	25	Codec padrão / referência
G.711 A-law	pcma	0	25	Mesmo que mu-law
G.722	g722	0	25	Codec wideband
G.729	g729, g729a	11	19	Baixa taxa de bits, impairment maior
G.723.1	g723	15	16	Baixa taxa de bits legado
GSM-FR	gsm	20	17	GSM full-rate
Opus	opus	0	25	Codec adaptativo moderno
iLBC	ilbc	11	20	Internet Low Bitrate Codec
AMR	amr	5	20	Adaptive Multi-Rate
AMR-WB	amr-wb	0	25	AMR Wideband
SILK	silk	0	25	Codec do Skype
Speex	speex	11	20	Codec open-source

Entendendo Ie e Bpl

Ie (Fator de Impairment de Equipamento): Representa a perda de qualidade inerente à compressão do codec. G.711 (sem compressão) tem Ie=0. G.729 tem Ie=11 porque a compressão introduz alguma perda de qualidade mesmo com zero perda de pacotes.
Bpl (Fator de Robustez à Perda de Pacotes): Indica quão bem o codec lida com perda de pacotes. Valores mais altos significam que o codec degrada mais graciosamente sob perda de pacotes. G.711 (Bpl=25) tolera perda melhor que G.723 (Bpl=16).

Comportamento de Busca de Codec

O nome do codec é comparado de forma case-insensitive. Se uma correspondência exata não for encontrada, o SIP VAULT tenta uma correspondência por substring contra nomes de codecs conhecidos. Se nenhuma correspondência for encontrada, os padrões do G.711 (Ie=0, Bpl=25) são usados.