Guia de Instalação do SIP VAULT

Este guia cobre a instalação completa do SIP VAULT, incluindo os componentes do servidor (sipvault-server, FastAPI, nginx, dashboard) e o componente agente implantado nos servidores OpenSIPS dos clientes.

Sumário

Requisitos do Sistema
Visão Geral da Arquitetura
Configuração do Armazenamento S3 (Cloudflare R2)
Instalação do Servidor
Instalação do Agente
Verificando a Instalação
Resolução de Problemas

Requisitos do Sistema

Servidor (Digital Ocean / Ubuntu 24)

Requisito	Especificação
SO	Ubuntu 24.04 LTS
CPU	2+ vCPUs (recomendado: 4 vCPUs para 10.000+ chamadas simultâneas)
RAM	16 GB
Disco	40 GB SSD (sem armazenamento local de chamadas; todos os dados vão para o S3)
Rede	IP público, portas 80/443 (HTTPS), 9060/tcp (agente), 9060/udp (HEP)
Software	nginx, Python 3.10+, certbot

Agente (Servidores OpenSIPS dos Clientes)

O agente suporta dois modos de captura dependendo da versão do kernel:

Modo	Requisito de Kernel	Dependências	Capabilities
eBPF (padrão em kernels modernos)	Linux >= 4.18	Nenhuma (binário estático, sem CGO)	CAP_BPF + CAP_NET_ADMIN + CAP_SYS_PTRACE
pcap (sistemas legados)	Qualquer Linux (CentOS 6+, Debian 7+, Ubuntu 14.04+)	libpcap	root ou CAP_NET_RAW

Requisito	Especificação
Arquitetura	x86_64 (amd64) ou aarch64 (arm64)
Disco	100 MB para armazenamento de buffer (configurável)
Rede	TCP de saída para o servidor na porta 9060

Dashboard

Requisito	Especificação
Tipo	SPA estático (React + TypeScript + Tailwind)
Ferramenta de build	Vite
Servido por	nginx no host do servidor
Navegador	Qualquer navegador moderno (Chrome, Firefox, Safari, Edge)

Visão Geral da Arquitetura

Customer site:
  sipvault-agent (eBPF or libpcap) --TCP:9060--> sipvault-server --> S3 (per-customer bucket)
  acct_rtcp_hep (RTPProxy) --HEP/UDP:9060--> sipvault-server

User access:
  CDR Viewer --HMAC link--> Dashboard SPA <--> FastAPI <--> S3

Todos os componentes rodam em uma única VM de servidor, exceto o agente que roda em cada servidor OpenSIPS do cliente. Quando o RTPProxy roda em uma máquina separada do OpenSIPS, o módulo acct_rtcp_hep envia dados RTCP diretamente para o servidor via HEP sobre UDP -- nenhum agente é necessário no servidor de mídia.

Configuração do Armazenamento S3 (Cloudflare R2)

O SIP VAULT utiliza o Cloudflare R2 como armazenamento de objetos compatível com S3. Cada cliente recebe um bucket dedicado para isolamento de tenant.

Passo 1: Criar um Bucket no Cloudflare R2

Faça login no painel do Cloudflare em https://dash.cloudflare.com
Navegue até R2 Object Storage
Clique em Create bucket
Nomeie o bucket usando a convenção: sipvault-{customer_id}-{region}
Exemplo: sipvault-acme-us
Selecione a localização de armazenamento apropriada
Repita para cada cliente

Passo 2: Criar Tokens de API do R2

Você precisa de dois conjuntos de credenciais:

Credenciais do servidor (usadas pelo sipvault-server para gravar dados de chamadas):

Vá em R2 > Manage R2 API Tokens
Clique em Create API Token
Defina as permissões: Object Read & Write
Limite o escopo aos buckets específicos do cliente
Salve o Access Key ID e o Secret Access Key

Credenciais da API (usadas pelo serviço FastAPI para gerar URLs pré-assinadas):

Crie outro API Token
Defina as permissões: Object Read apenas
Limite o escopo a todos os buckets de clientes
Salve o Access Key ID e o Secret Access Key

Passo 3: Anotar o Account ID

A URL do endpoint R2 segue este padrão:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Encontre seu Account ID no painel do Cloudflare em R2 > Overview. Você precisará dele tanto para o server.env quanto para o api.env.

Instalação do Servidor

O script de configuração (deploy/setup-server.sh) automatiza a instalação completa do servidor. Ele é idempotente e pode ser executado novamente com segurança.

Pré-requisitos

Antes de executar o script de configuração, compile os componentes:

# Build the sipvault-server binary
cd server
go build -o /tmp/sipvault-deploy/sipvault-server ./cmd/sipvault-server/

# Copy the API source
cp -r api /tmp/sipvault-deploy/api

# Build the dashboard
cd dashboard
npm install
npm run build
cp -r dist /tmp/sipvault-deploy/dashboard

Passo 1: Configurar o Script de Setup

Edite o topo do deploy/setup-server.sh para definir seu domínio e caminhos de arquivos:

DOMAIN="sipvault.sippulse.com.br"
EMAIL="flavio@sippulse.com"
SIPVAULT_SERVER_BIN="/tmp/sipvault-deploy/sipvault-server"
SIPVAULT_API_DIR="/tmp/sipvault-deploy/api"
SIPVAULT_DASHBOARD_DIR="/tmp/sipvault-deploy/dashboard"

Passo 2: Executar o Script de Setup

sudo bash deploy/setup-server.sh

O script realiza os seguintes passos:

Cria o usuário de sistema sipvault -- um usuário sem login em /opt/sipvault
Instala dependências do sistema -- nginx, python3-pip, python3-venv, certbot
Cria a estrutura de diretórios:
/opt/sipvault/api -- Aplicação FastAPI
/opt/sipvault/dashboard -- Arquivos do SPA compilado
/etc/sipvault -- Arquivos de configuração
/var/log/sipvault -- Arquivos de log
Copia binários e arquivos da aplicação:
Binário sipvault-server para /usr/local/bin/sipvault-server
Arquivos da API para /opt/sipvault/api/ com ambiente virtual Python
Arquivos do dashboard para /opt/sipvault/dashboard/
Cria arquivos de ambiente a partir de templates (se ainda não existirem):
/etc/sipvault/server.env (permissões: 640, proprietário root:sipvault)
/etc/sipvault/api.env (permissões: 640, proprietário root:sipvault)
Instala serviços systemd:
sipvault-server.service
sipvault-api.service
Configura o nginx com seu domínio e habilita o site
Obtém um certificado SSL via certbot (Let's Encrypt)
Abre portas do firewall via ufw: 80/tcp, 443/tcp, 9060/tcp, 9060/udp

Passo 3: Configurar Arquivos de Ambiente

Edite o arquivo de ambiente do servidor:

sudo nano /etc/sipvault/server.env

SIPVAULT_LISTEN_TCP=:9060
SIPVAULT_LISTEN_HEP=:9060
SIPVAULT_S3_ENDPOINT=https://YOUR_ACCOUNT_ID.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":"customer1","token":"token1","bucket":"sipvault-customer1"}]
SIPVAULT_LOG_LEVEL=info

Edite o arquivo de ambiente da API:

sudo nano /etc/sipvault/api.env

SIPVAULT_S3_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
SIPVAULT_S3_REGION=auto
SIPVAULT_HMAC_SECRET=your_hmac_secret_here
ANTHROPIC_API_KEY=your_anthropic_key
AWS_ACCESS_KEY_ID=your_r2_access_key
AWS_SECRET_ACCESS_KEY=your_r2_secret_key

Gere um segredo HMAC forte:

openssl rand -hex 32

Passo 4: Iniciar os Serviços

sudo systemctl start sipvault-server
sudo systemctl start sipvault-api

Passo 5: Verificar os Serviços

sudo systemctl status sipvault-server
sudo systemctl status sipvault-api
sudo journalctl -u sipvault-server -f
sudo journalctl -u sipvault-api -f

Detalhes dos Serviços systemd

sipvault-server.service:

[Unit]
Description=SIP VAULT Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sipvault
Group=sipvault
EnvironmentFile=/etc/sipvault/server.env
ExecStart=/usr/local/bin/sipvault-server
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sipvault-api.service:

[Unit]
Description=SIP VAULT API
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sipvault
Group=sipvault
EnvironmentFile=/etc/sipvault/api.env
WorkingDirectory=/opt/sipvault/api
ExecStart=/opt/sipvault/api/venv/bin/python3 -m uvicorn sipvault_api.main:app --host 127.0.0.1 --port 8000 --workers 4
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

A API roda em 127.0.0.1:8000 e é encaminhada pelo nginx no caminho /api/.

Instalação do Agente

O instalador do agente (install/install.sh) suporta sistemas Linux modernos e legados. Ele detecta automaticamente a versão do kernel para escolher o modo de captura apropriado.

Instalação Rápida (Comando Único)

curl -sSL https://install.sipvault.io | bash -s -- \
  --server 10.0.0.1:9060 \
  --customer acme \
  --token SECRET

Instalação Completa com Opções

sudo bash install/install.sh \
  --server 10.0.0.1:9060 \
  --customer acme \
  --token SECRET \
  --sip-ports 5060 \
  --interface eth0 \
  --log-file /var/log/opensips.log \
  --mode auto

Opções do Instalador

Opção	Obrigatória	Padrão	Descrição
`--server`	Sim	--	Endereço do servidor como `HOST:PORT`
`--customer`	Sim	--	Identificador do cliente (deve corresponder à configuração do servidor)
`--token`	Sim	--	Token de autenticação (deve corresponder à configuração do servidor)
`--sip-ports`	Não	`5060`	Portas SIP separadas por vírgula para captura
`--interface`	Não	Auto-detectada	Interface de rede para captura de pacotes
`--log-file`	Não	`/var/log/opensips.log`	Caminho do arquivo de log do OpenSIPS (usado no modo pcap)
`--mode`	Não	`auto`	Modo de captura: `auto`, `ebpf` ou `pcap`

O que o Instalador Faz

Detecta a arquitetura (amd64 ou arm64)
Detecta a versão do kernel para selecionar o modo de captura:
Kernel >= 4.18: modo eBPF (binário: sipvault-agent-linux-{arch})
Kernel < 4.18: modo pcap (binário: sipvault-agent-pcap-linux-{arch})
Instala libpcap se o modo pcap for selecionado (via yum ou apt-get)
Auto-detecta a interface de rede padrão se --interface não for especificado
Cria diretórios:
/etc/sipvault -- Configuração
/var/lib/sipvault -- Buffer de disco
Baixa o binário do agente para /usr/local/bin/sipvault-agent
Grava a configuração em /etc/sipvault/agent.conf
Cria um arquivo de serviço:
systemd (sistemas modernos): /etc/systemd/system/sipvault-agent.service
SysV init (CentOS 6): /etc/init.d/sipvault-agent

Arquivo de Configuração Gerado

O instalador grava /etc/sipvault/agent.conf em formato INI:

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

[capture]
mode = ebpf
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

Iniciando o Agente

Em sistemas com systemd:

sudo systemctl start sipvault-agent
sudo systemctl enable sipvault-agent
sudo systemctl status sipvault-agent

Em sistemas com SysV init (CentOS 6):

sudo service sipvault-agent start
sudo chkconfig sipvault-agent on

Compilando o Agente a Partir do Código-Fonte

Modo eBPF (sem CGO, binário estático):

cd agent
go build -o sipvault-agent ./cmd/sipvault-agent/

Modo pcap (requer libpcap-dev):

# Install build dependency
sudo apt-get install -y libpcap-dev   # Debian/Ubuntu
sudo yum install -y libpcap-devel     # CentOS/RHEL

cd agent
go build -tags pcap -o sipvault-agent-pcap ./cmd/sipvault-agent/

Verificando a Instalação

Verificação do Servidor

Verifique se ambos os serviços estão rodando:

systemctl status sipvault-server
systemctl status sipvault-api

Verifique se o nginx está servindo o dashboard:

curl -sI https://your-domain.com/
# Should return HTTP 200 with content-type text/html

Verifique se a API está acessível:

curl -s https://your-domain.com/api/health

Verifique os logs do servidor para mensagens de inicialização:

journalctl -u sipvault-server --no-pager -n 20
journalctl -u sipvault-api --no-pager -n 20

Verifique o listener TCP (conexões do agente):

ss -tlnp | grep 9060
# Should show sipvault-server listening on TCP :9060

Verifique o listener UDP (HEP):

ss -ulnp | grep 9060
# Should show sipvault-server listening on UDP :9060

Verificação do Agente

Verifique se o serviço está rodando:

systemctl status sipvault-agent

Verifique os logs do agente:

journalctl -u sipvault-agent --no-pager -n 20

Verifique a conectividade com o servidor:

nc -zv SERVER_IP 9060

Verifique se a captura está ativa (verifique nos logs mensagens INVITE capturadas após uma chamada de teste):

journalctl -u sipvault-agent -f

Teste Ponta a Ponta

Faça uma chamada de teste através do servidor OpenSIPS onde o agente está rodando
Aguarde a chamada terminar (desligue em ambos os lados)
Verifique nos logs do servidor se a sessão da chamada foi gravada no S3:

journalctl -u sipvault-server -f | grep "session complete"

Verifique os dados no S3 usando o painel do Cloudflare R2 ou o AWS CLI:

aws s3 ls s3://sipvault-customer1/calls/ \
  --endpoint-url https://ACCOUNT_ID.r2.cloudflarestorage.com

Resolução de Problemas

Problemas do Servidor

sipvault-server falha ao iniciar com "SIPVAULT_S3_ENDPOINT is required"

O arquivo de ambiente /etc/sipvault/server.env não foi configurado. Edite-o com suas credenciais do Cloudflare R2.

sipvault-server falha com "at least one customer must be configured"

A variável SIPVAULT_CUSTOMERS deve conter um array JSON válido. Verifique a formatação correta:

SIPVAULT_CUSTOMERS=[{"id":"customer1","token":"token1","bucket":"sipvault-customer1"}]

API retorna 502 Bad Gateway

O processo FastAPI não está rodando ou não está vinculado à porta 8000. Verifique:

systemctl status sipvault-api
journalctl -u sipvault-api -n 50

certbot falha durante a configuração

Verifique se o registro DNS A do seu domínio aponta para o IP público do servidor. Execute o certbot manualmente:

sudo certbot --nginx -d your-domain.com --email your@email.com

Teste de configuração do nginx falha

Se os certificados SSL ainda não existem, o nginx falhará ao iniciar. Obtenha o certificado primeiro e depois recarregue o nginx.

Problemas do Agente

Agente falha com "permission denied" ou erros de capability

Modo eBPF requer: CAP_BPF, CAP_NET_ADMIN, CAP_SYS_PTRACE (ou executar como root)
Modo pcap requer: root ou CAP_NET_RAW

Conceda capabilities ao binário:

# For eBPF mode
sudo setcap cap_bpf,cap_net_admin,cap_sys_ptrace=eip /usr/local/bin/sipvault-agent

# For pcap mode
sudo setcap cap_net_raw=eip /usr/local/bin/sipvault-agent

Agente não consegue conectar ao servidor

Verifique a conectividade de rede e as regras de firewall:

nc -zv SERVER_IP 9060

Certifique-se de que a porta 9060/tcp está aberta no firewall do servidor (ufw, iptables ou security groups na nuvem).

Agente cai para o modo pcap inesperadamente

A auto-detecção verifica a versão do kernel. Se o kernel for < 4.18, o eBPF não está disponível. Verifique a versão do seu kernel:

uname -r

Para forçar o modo eBPF (não recomendado em kernels mais antigos), defina mode = ebpf em /etc/sipvault/agent.conf.

Nenhum tráfego SIP capturado

Verifique se a configuração sip_ports corresponde às portas de escuta do seu OpenSIPS
Verifique se a configuração interface está correta: ip route show default
No modo pcap, certifique-se de que log_file aponta para o arquivo de log real do OpenSIPS
Verifique se a variante do binário do agente corresponde ao modo (binário pcap para modo pcap)

Buffer de disco cresce continuamente

O agente armazena dados localmente (até 100 MB por padrão) quando a conexão TCP com o servidor é perdida. Verifique a conectividade com o servidor. O buffer está em /var/lib/sipvault/buffer.dat.

Problemas do Dashboard

Dashboard exibe uma página em branco

Verifique se os arquivos do SPA compilado estão em /opt/sipvault/dashboard/ e se o index.html existe:

ls -la /opt/sipvault/dashboard/

Requisições à API falham com erros de CORS

A configuração do nginx encaminha /api/ para o backend FastAPI. Certifique-se de que a configuração do nginx está correta e que o site está habilitado:

ls -la /etc/nginx/sites-enabled/
nginx -t