Wiki

Solução de problemas

Soluções para problemas comuns: serviço travado, código de ativação rejeitado, PostgreSQL, TLS.

O serviço não inicia

Linux: systemctl start falha

sudo journalctl -u uversion-server -n 100 --no-pager

Causas comuns:

PostgreSQL inativo: sudo systemctl status postgresql
Senha do banco de dados perdida: o postinst regenera a configuração com --reconfigure (sudo dpkg-reconfigure uversion-server)
Porta 8443 ocupada: consulte a seção dedicada mais abaixo

Windows: erro 1053 ou 1067

O serviço inicia e depois para. Verifique o Visualizador de Eventos:

Get-EventLog -LogName Application -Source uVersionServer -Newest 50

Causas comuns:

Variável de ambiente CONFIG_PATH ausente: normalmente definida pelo instalador em HKLM\SYSTEM\CurrentControlSet\Services\uVersionServer\Environment
PostgreSQL inativo: Get-Service postgresql*

O código de ativação é rejeitado

Verifique se o código não foi usado em outra máquina (cada código está vinculado ao server-ID da primeira instalação). Solicite um novo código na sua área da conta.
Verifique a conectividade com licence.uversion.io: curl -I https://licence.uversion.io/api/v1/health
Se você quiser reutilizar um código em uma nova máquina após desinstalar, entre em contato com o suporte para liberar o server-ID anterior.

PostgreSQL inacessível

O serviço uVersion não consegue se conectar ao banco de dados. Teste manualmente:

# Linux
sudo -u postgres psql -c "SELECT 1;"

# Windows
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -h 127.0.0.1 -c "SELECT 1;"

Se o PostgreSQL estiver instalado mas a senha do superusuário for perdida, o instalador do uVersion (tanto o postinst do Linux quanto o install.ps1 do Windows) pode colocar o PostgreSQL de volta no modo trust automaticamente, redefinir a senha e depois restaurar a configuração original. Execute novamente:

# Linux
sudo dpkg-reconfigure uversion-server

# Windows
iwr https://uversion.io/downloads/server/install.ps1 -UseBasicParsing | iex
# (re-passe par le script avec -Reconfigure)

A porta 8443 já está em uso

O uVersion escuta por padrão em HTTPS na 8443 (e mantém a 8080 aberta como fallback HTTP). Se uma das duas estiver ocupada:

# Linux
sudo ss -tlnp | grep -E '8443|8080'

# Windows
Get-NetTCPConnection -LocalPort 8443 | Select-Object OwningProcess, State
Get-Process -Id <PID>

Para alterar a porta TLS, edite config.toml:

[tls]
https_port = 9443

Depois reinicie o serviço.

O cliente recusa a conexão TLS

O uVersion usa um certificado autoassinado bloqueado via TOFU no lado do cliente (consulte Impressão digital TLS). As causas mais comuns:

Primeira conexão não confirmada: o cliente desktop exibe uma caixa de diálogo com a impressão digital. Compare-a com o que o administrador compartilhou. Na CLI, execute uversion trust <url>.
Impressão digital alterada (aviso vermelho): o servidor foi reinstalado e regenerou seu certificado. Confirme out-of-band com o administrador e depois:
- Desktop: clique em Trust new fingerprint na caixa de diálogo vermelha
- CLI: uversion mistrust <url> depois uversion login <url>
O servidor não fornece HTTPS: verifique se ele está realmente escutando na 8443, não na 8080:
```
# Linux
ss -tlnp | grep 8443
# Windows
Get-NetTCPConnection -LocalPort 8443 -State Listen
```
Se nada estiver escutando, verifique se [tls] disabled = false em config.toml (esse é o padrão).

Reexibir a impressão digital no lado do servidor:

# Linux
sudo cat /var/lib/uversion/data/tls/fingerprint
# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

Reset completo

Consulte as páginas Desinstalar no Ubuntu/Debian ou Desinstalar no Windows para começar com uma instalação limpa.