Publicando o SRI Integrador na intranet

Como o Integrador escuta

No modo standalone existem dois níveis de processo:

• Balanceador — um único processo, escutando na porta definida na chave Porta da seção [Web] de C:\SRI_SERVICES\IntegraSRI.ini. É a porta que o navegador, o PDV e o SRICASH usam.

• Instâncias da API (SRI API 1, SRI API 2, …) — escutam em Porta+1, Porta+2 e assim por diante, sempre em 127.0.0.1, e recebem tráfego apenas do balanceador, em round-robin com verificação de saúde.

Somente o balanceador é publicável. As instâncias filhas são internas por construção: elas permanecem em loopback mesmo quando o balanceador está na rede, e não devem receber regra de firewall. É isso que mantém a superfície exposta reduzida a uma única porta, por mais instâncias que existam.

SRI_BALANCER_HOST controla exclusivamente em qual interface o balanceador escuta. Ela não abre portas, não altera o firewall e não muda o número da porta.

SRI_BALANCER_HOST: os três valores possíveis

Ausente ou 127.0.0.1 — o padrão

O balanceador aceita conexões apenas da própria máquina. O painel abre normalmente pela bandeja, PDVs instalados no mesmo computador funcionam, e nenhuma estação da rede alcança a API. É o comportamento correto para a instalação de balcão, em que o PDV e o Integrador convivem no mesmo Windows.

Neste modo, não crie regra de firewall. Ela não teria efeito algum — o serviço sequer aceita conexões externas — e só ampliaria a superfície declarada sem necessidade.

O IP da placa de rede — evite

Informar 192.168.0.139 publica a API na rede, mas fecha o loopback: a partir daquele momento 127.0.0.1 passa a recusar conexão. E o aplicativo da bandeja verifica a saúde do backend justamente em http://127.0.0.1:<porta>/healthz.

O resultado é o sintoma mais confuso de todos: a janela do painel chega a abrir, e segundos depois cai com a mensagem de que o backend deixou de responder — enquanto, pela rede, a API está perfeitamente no ar.

Um IP fixo só faz sentido em um servidor com várias placas de rede em que se queira deliberadamente escolher uma delas. Mesmo aí, o custo é perder o acesso local pelo painel e por qualquer ferramenta que aponte para localhost.

0.0.0.0 — o valor recomendado

0.0.0.0 não é “qualquer IP da Internet”: significa todas as interfaces locais desta máquina, inclusive a loopback. O painel continua abrindo em 127.0.0.1 e as estações da rede passam a alcançar o IP da placa. É o valor indicado para uma instalação que atua como API central da intranet.

Quem decide de onde as conexões podem vir deixa de ser o Node e passa a ser o firewall — que é o lugar certo para essa decisão, porque é lá que se restringe por sub-rede e por perfil de rede.

Como criar a variável de ambiente no Windows

Use sempre o escopo Machine (Variáveis do sistema). O escopo de usuário não é lido quando o aplicativo roda sob outra conta, como serviço ou por tarefa agendada.

Pelo PowerShell (recomendado)

Abra o PowerShell como Administrador. Esta forma não depende da tradução dos menus do Windows:

[Environment]::SetEnvironmentVariable('SRI_BALANCER_HOST', '0.0.0.0', 'Machine')

# conferir o valor gravado
[Environment]::GetEnvironmentVariable('SRI_BALANCER_HOST', 'Machine')

# remover, se precisar voltar ao padrão
[Environment]::SetEnvironmentVariable('SRI_BALANCER_HOST', $null, 'Machine')

Pela interface gráfica

1. Menu Iniciar → digite Editar as variáveis de ambiente do sistema.

2. Botão Variáveis de Ambiente….

3. No quadro de baixo, Variáveis do sistema — não o de cima, que é o do usuário.

4. Novo… → Nome SRI_BALANCER_HOST, Valor 0.0.0.0.

5. OK em todas as janelas abertas.

O passo que quase sempre é esquecido

Gravar a variável não altera processos que já estão em execução. Cada processo recebe uma cópia do ambiente no momento em que inicia e a mantém até encerrar. Depois de gravar:

1. Encerre o Integrador pelo menu da bandeja, em Sair — fechar apenas a janela do navegador não encerra o backend.

2. Feche terminais, prompts e editores abertos, que ainda carregam o valor anterior.

3. Inicie o aplicativo novamente.

Para ver o que o processo realmente enxerga, e não o que está gravado no registro:

Get-ChildItem Env: | Where-Object Name -like 'SRI_*'

Antes do firewall: confirme a porta certa

A porta é a chave Porta da seção [Web] do INI. Não presuma 8080. A antiga [GERAL] Porta deixou de ser lida — se o arquivo tiver as duas chaves, é a de [Web] que vale, e liberar a outra no firewall não produz efeito nenhum.

A forma mais segura é olhar o que está efetivamente no ar:

Get-NetTCPConnection -State Listen |
  Where-Object { (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).Name -like 'SRI*' } |
  Select-Object LocalAddress, LocalPort, OwningProcess

O resultado esperado, com o balanceador já publicado, é parecido com este:

A regra de firewall

Com a porta confirmada, crie a regra de entrada em PowerShell como Administrador. O exemplo usa 8090; troque pela porta do seu INI:

New-NetFirewallRule -DisplayName "SRI Integrador (HTTP 8090)" `
  -Direction Inbound -Protocol TCP -LocalPort 8090 `
  -Action Allow -Profile Private,Domain

A crase no fim das linhas é apenas a continuação de linha do PowerShell; o comando pode ser escrito em uma linha só. Parâmetro a parâmetro:

O erro que mais engana: preencher a Porta Remota

Toda conexão TCP envolve duas portas, e elas são diferentes. O cliente sorteia uma porta de origem efêmera — na faixa 49152–65535 — e conecta na porta de destino do servidor.

Em uma regra de entrada, o Windows chama:

• Porta Local — a porta deste servidor. É conhecida e não muda: 8090.

• Porta Remota — a porta de origem do cliente. É sorteada a cada conexão e a cada estação, portanto imprevisível.

Preencher Porta Remota = 8090 significa exigir que o cliente também esteja saindo da porta 8090. Isso praticamente nunca acontece: a chance é de aproximadamente uma em dezesseis mil. A regra fica habilitada, aparece como Permitir na lista, e ainda assim não casa com nenhum pacote.

O que torna esse erro particularmente difícil de enxergar é que o acesso a partir do próprio servidor não passa por esse filtro. O administrador testa http://192.168.0.139:8090 na própria máquina, vê o painel abrir, conclui que o firewall está correto — e a rede inteira continua sem acesso.

Se a regra já foi criada assim, não é preciso recriá-la. Pela interface: Propriedades da regra → aba Protocolos e Portas → Porta remota → trocar de Portas específicas para Todas as portas. Ou, em uma linha:

Set-NetFirewallRule -DisplayName "SRI Integrador (HTTP 8090)" -RemotePort Any

Perfil da regra: atenção quando há VPN instalada

O parâmetro -Profile define em quais redes a regra vale. Antes de escolher, veja como o Windows classificou cada adaptador:

Get-NetConnectionProfile | Select-Object Name, InterfaceAlias, NetworkCategory

Adaptadores de VPN — Hamachi, NordLynx, OpenVPN e semelhantes — costumam aparecer como Público, enquanto a rede da empresa aparece como Particular ou Domínio. Usar -Profile Any, ou marcar “Tudo” na interface gráfica, publicaria a API também por esses túneis, para fora do perímetro que se pretendia atender.

Restrinja ao perfil da rede que realmente precisa de acesso. Em uma intranet corporativa, isso normalmente significa Private,Domain.

Validação

No próprio servidor, os dois endereços devem responder:

$porta = 8090
Invoke-RestMethod "http://127.0.0.1:$porta/healthz"
Invoke-RestMethod "http://192.168.0.139:$porta/healthz"   # IP real da placa de rede

O resultado esperado é ok = True nos dois. Se o primeiro falhar e o segundo funcionar, a variável está com IP fixo em vez de 0.0.0.0.

Em seguida, na outra máquina da intranet:

Test-NetConnection 192.168.0.139 -Port 8090

TcpTestSucceeded : True confirma que a rota e o firewall estão corretos, e o painel abre em http://192.168.0.139:8090.

Se esse teste falhar mesmo com a regra correta, a causa está fora do Windows: isolamento de clientes no ponto de acesso Wi-Fi, VLANs distintas ou estações em sub-redes diferentes sem rota entre elas.

Cuidados de segurança

• Libere somente a porta do balanceador. As instâncias em Porta+1 … Porta+N são internas e devem permanecer inalcançáveis pela rede.

• Restrinja a regra às sub-redes confiáveis e ao perfil de rede correto. Nunca exponha essa porta à Internet.

• A autenticação interativa do SRICASH aceita HTTP dentro da intranet, mas senha e tokens trafegam pela rede. Se o tráfego sair do perímetro confiável, coloque um proxy TLS na frente e publique apenas o 443.

• PDVs e automações que usam API key exigem HTTPS quando a rede não for integralmente confiável.

Diagnóstico rápido

Resumindo: SRI_BALANCER_HOST=0.0.0.0 decide que o serviço aceita conexões da rede; a regra de firewall decide quem pode chegar até ele. A variável precisa de reinício do aplicativo para valer, e a regra precisa da porta correta do INI com a Porta Remota deixada em Qualquer.