Resolução de problemas

Os modos de falha, organizados por onde são percebidos, como cada um se manifesta e onde ler a causa. Toda resposta HTTP traz um X-Correlation-Id; informe-o e o operador encontra na hora as linhas do log do Servidor e as linhas da Trilha de Auditoria da requisição.

O Servidor não inicia

Toda inicialização recusada gera uma linha Critical citando a causa. A tabela completa está em Instalação do Servidor. A versão resumida:

Sintoma	Causa
Uma linha citando KeyRingProtector:	Não há protetor, o valor não está em base64, a senha está errada ou não há chave RSA. Toda implantação precisa de um.
…the Key Ring Protector configured here opens none of them	Um protetor trocado. Restaure o antigo, ou adicione-o em RetiredCertificates.
…could not be reached in 90 seconds	O banco de dados nunca respondeu na inicialização. No Azure SQL, verifique o acesso pela rede pública ou o private endpoint (erro 47073).
…is behind the build … by N migration(s)	MigrateOnStart está desligado e há migrações pendentes.
…has N migration(s) applied that this build does not contain	Uma imagem mais antiga sobre um esquema mais novo, ou um banco de dados criado pelo Servidor 1.2.0 ou anterior.
Signer:ApiKey is required…	Um endereço do Signer sem chave.
Sessions:MaxDuration abaixo de DefaultDuration, ou outra regra entre chaves	Uma configuração recusada; a linha cita as duas chaves.
No App Service, o container é encerrado e reiniciado em loop sem nada útil no log	Uma migração que demora mais que WEBSITES_CONTAINER_START_TIME_LIMIT (padrão de 230 s). Defina-o como 1800.

O Servidor iniciou, mas não funciona

Sintoma	O que é	Onde olhar
/ responde 200, /healthz responde 503	O banco de dados caiu depois da inicialização. O contrato falha; o cofre está fechado.	A connection string, a disponibilidade do SQL Server.
Toda assinatura e importação no cofre é recusada, enquanto as estações de trabalho assinam normalmente	A trava do cofre: o Servidor subiu antes do banco de dados.	O aviso VaultReadiness na inicialização. O cofre se abre no primeiro uso depois que o banco de dados responde.
Todo Certificado do Cofre aparece como UNTRUSTED; importações recusadas	Não há licença do PKI SDK, ou ela expirou.	A linha Critical de LacunaPkiRuntime na inicialização. Defina Certificates__Validation__License.
Todo certificado no Servidor aparece como UNTRUSTED, embora a licença esteja válida	Nenhuma âncora consegue terminar uma cadeia: UseIcpBrasil desligado sem nenhuma Autoridade Certificadora Confiável que seja raiz, ou um sistema de arquivos somente leitura sem /tmp gravável, de modo que a licença não pôde ser carregada.	As duas linhas Critical sobre o conjunto de âncoras; monte um tmpfs sobre /tmp.
Uma configuração não tem efeito	Uma das sete chaves que podem ser sobrepostas foi salva na tela Configurações e usuários, e a camada do banco de dados prevalece silenciosamente.	/admin/settings; restaure os padrões implantados.
O console administrativo em http:// nunca conclui o login	Um cookie sem Secure em um link que a plataforma converte para HTTPS.	No App Service, --https-only true. Atrás de um proxy, ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.
Toda linha de auditoria registra o endereço do proxy	Os forwarded headers estão desligados.	ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.
Linhas KeyRingProvider[48] ou XmlKeyManager[24] em um Servidor que iniciou sem erros	O banco de dados está inacessível, não o protetor.	/healthz.
Uma linha Critical com uma linha de auditoria inteira	O banco de dados recusou uma gravação de auditoria; a linha só existe nessa entrada do log.	Guarde o fluxo de log. O console mostra um alerta.
Um banner de aviso em todas as páginas administrativas	UseLacunaTestPki está ligado, ou uma gravação de auditoria falhou.	Desligue a PKI de testes em tudo que não seja uma máquina de desenvolvimento.

Estações de trabalho

Sintoma	O que é	Onde olhar
Instalação com código de saída 1603, log cita SERVER_URL	A condição de inicialização: URL vazia ou sem esquema.	Passe SERVER_URL=https://….
Instalação com código de saída 1603, log diz que uma versão mais nova está instalada	Um downgrade.	Desinstale antes; a máquina volta como uma máquina nova.
A instalação é revertida em Starting services	O serviço se recusou a iniciar: uma licença que o SDK não lê, uma INSTALLER_KEY que não pode ser interpretada ou um valor de Registro do tipo errado.	Log de eventos Aplicativo, origem TrustBridge Workstation Service.
Instalada, nunca aparece na fila de admissão, nada no Servidor	A URL do Servidor está errada, ou uma GPO a está sobrepondo, ou a máquina não confia na cadeia TLS.	A linha Server:Url is …, supplied by … do serviço na inicialização; HKLM\Software\Policies\TrustBridge em um PowerShell de 64 bits.
Nunca aparece, e o log da máquina diz que a requisição de admissão foi recusada	Uma de quatro causas: revogada, uma Installer Key em que o Servidor não confia, requisições demais do endereço dela ou fila cheia. O Servidor deliberadamente não diz qual.	As duas últimas se resolvem sozinhas. Procure uma linha revogada na tela Estações de Trabalho.
Está na fila, e o Tray mostra Ainda não admitida	Não é uma falha.	Admita-a em /admin/admission.
Admitida, mas não se conecta; o log do Servidor diz Protocol version 2 is newer than this server's supported window	A estação de trabalho foi atualizada antes do Servidor.	Atualize o Servidor.
Admitida, mas não se conecta; o log do Servidor diz A workstation assertion was refused: Expired ou NotYetValid	O relógio da máquina está mais de 60 s fora.	A sincronização de horário da máquina.
Todo certificado aparece como UNTRUSTED	Não há licença da PKI, ou ela expirou, ou nenhuma âncora consegue terminar uma cadeia.	A linha Critical na inicialização do serviço; PKI_LICENSE por reparo ou por Diretiva de Grupo e, em seguida, reinicie o serviço.
Um certificado aparece como UNTRUSTED enquanto a licença está em ordem	O emissor dele não está no conjunto de âncoras da máquina.	Confiar no emissor, no Registro de Certificados, que adiciona uma Autoridade Certificadora Confiável que chega à máquina. Uma máquina no protocolo 1 precisa de arquivos de âncora.
Um certificado aparece como STALE	Não foi possível baixar a LCR da AC dele por mais tempo que a janela de tolerância (24 h).	Se a máquina consegue acessar a AC.
Um token está conectado, mas nenhum certificado aparece	Um middleware incomum, fora da lista fornecida; ou um módulo citado em Certificates:Pkcs11:Modules que não carrega.	O log do serviço cita o módulo. A varredura também detecta, em até um minuto, um gatilho de mudança perdido.
O Tray App não aparece depois da instalação	Ele inicia no próximo login.	Saia e entre de novo, ou inicie Tray App\TrustBridge.TrayApp.exe.
O Tray App diz Sem conexão	Ele não conseguiu abrir o pipe do serviço. O Workstation 1.0.0 tinha um bug aqui, corrigido na 1.0.1.	Atualize o pacote da estação de trabalho.
Uma solicitação de PIN continua na tela depois de o cliente já ter recebido um erro	Esperado: o timeout da solicitação no Servidor (60 s) é menor que o do Tray (90 s), e um Servidor que desistiu não consegue fechar a solicitação.	Nada.
Uma alteração de diretiva não teve efeito	O Registro é lido uma vez, na inicialização.	Restart-Service "TrustBridge Workstation Service".
Uma máquina perfeitamente configurada parece vazia no Registro	Um PowerShell de 32 bits redirecionado para WOW6432Node.	Use um PowerShell de 64 bits.
Todo certificado de uma máquina aparece como ACTIVE, inclusive os de exemplo	UseLacunaTestPki ligado, ou uma seção FakeTokens no arquivo de configuração.	Remova os dois de qualquer máquina em que alguém assine.

Erros na aplicação cliente

Decida com base em error.code. O vocabulário completo está na página API REST.

Código	Causa comum	O que fazer
401 UNAUTHORIZED	Chave ausente, digitada errado, revogada ou expirada, ou uma aplicação desativada. Todas recusadas da mesma forma.	Verifique a chave na tela Aplicações Cliente.
401 SESSION_EXPIRED	A sessão expirou por inatividade, foi desativada, foi substituída por uma mais nova do mesmo CPF, esgotou a Franquia de Assinaturas ou estava vinculada ao cofre durante um reinício do Servidor.	Crie uma nova sessão. Nada indica qual foi o caso; isso é deliberado.
400 INVALID_REQUEST em POST /v1/sessions citando cpf	Os dígitos verificadores não conferem, ou é um valor de dígitos repetidos.	Corrija o CPF na origem. Valide os dígitos verificadores no seu formulário.
400 INVALID_REQUEST em uma assinatura	Não há sessionId na requisição.	Envie o id que POST /v1/sessions retornou. Repetir sem alterações falha da mesma forma.
404 CERT_NOT_FOUND	Nenhum certificado do CPF está disponível em lugar nenhum: o token não está conectado, a máquina não está admitida ou conectada, ou o CPF nunca recebeu um certificado.	O Registro de Certificados e a tela Estações de Trabalho.
422 CERT_NOT_ACTIVE	Todo certificado do CPF está EXPIRED, REVOKED, UNTRUSTED ou STALE. UNTRUSTED muitas vezes significa que as âncoras da implantação não cobrem o emissor.	GET /v1/certificates/info para ver o veredito; o Registro de Certificados para ver o emissor.
401 INVALID_PIN	PIN errado, ou uma estação de trabalho com outro PIN em uso.	Pergunte ao titular. Cinco falhas em quinze minutos bloqueiam o CPF.
422 PIN_NOT_AVAILABLE	A solicitação no Tray expirou, foi recusada ou não havia ninguém conectado para respondê-la; ou um Certificado do Cofre não pôde ser aberto.	O titular precisa estar na máquina dele com o Tray App em execução.
422 WORKSTATION_OFFLINE	Toda máquina com um certificado ativo do CPF está offline, depois da tolerância de reconexão, em uma assinatura.	A tela Estações de Trabalho.
422 CERT_INCOMPLETE_IDENTITY	O certificado não traz endereço de e-mail.	Envie email ao criar a sessão.
422 SIGN_TIMEOUT	A assinatura não terminou dentro de Signing:RequestBudget (60 s). Uma máquina lenta ou um Signer lento.	A tela Operações de Assinatura mostra a etapa alcançada.
422 SIGNER_REJECTED	O Lacuna Signer recusou o documento; details traz a mensagem dele.	O próprio documento.
502 SIGNER_ERROR	Não foi possível acessar o Signer.	A disponibilidade do Signer, Signer:BaseAddress.
409 DOCUMENT_NOT_READY que nunca se resolve	A assinatura ainda está em andamento, ou uma execução foi interrompida por um reinício e o Signer ainda mantém o documento aberto.	A tela Operações de Assinatura; RUN_STRANDED.
429 SERVER_BUSY no uso normal	Throttle:ConcurrencyLimit baixo demais para a implantação; não é um problema do cliente.	Aumente-o. Em um pico real, tente de novo com backoff e jitter.
429 TOO_MANY_PIN_ATTEMPTS	O bloqueio por CPF.	Espere a janela (15 min) passar. Tentar de novo piora a situação.
404 ENDPOINT_NOT_FOUND	Uma rota sem o prefixo /v1.	Corrija a URL.
413 DOCUMENT_TOO_LARGE	Acima de Signing:MaxDocumentBytes (10 MB por padrão).	Um documento menor, ou aumente o limite sabendo o que isso custa.
500 INTERNAL_ERROR em uma assinatura, com could not be opened by the reader this platform signs with no log do Servidor	Um Certificado do Cofre importado antes de existir a verificação do formato legado, protegido com pkcs5PBES2.	Exporte de novo com openssl pkcs12 -export -legacy e importe outra vez. Isso exige o arquivo original.

Resultados de assinatura na tela Operações de Assinatura

Uma operação Com falha traz um código de falha e a etapa que alcançou: o 202 do cliente pode ter sido respondido muito antes. RUN_STRANDED significa que o Servidor foi reiniciado durante a execução e uma varredura a encerrou. Uma execução que falhou depois de o documento chegar ao Signer deixa um documento aberto lá, que a busca informa como 409 até que a retenção do próprio Signer ou a limpeza o encerre como 422.

Como obter ajuda

Envie ao suporte da Lacuna Software o X-Correlation-Id da requisição que falhou, a versão do Servidor exibida no rodapé do console administrativo, a versão do pacote da estação de trabalho mostrada na tela Estações de Trabalho e as linhas relevantes do log do Servidor. Para um problema em uma estação de trabalho, acrescente as entradas do log de eventos Aplicativo com origem TrustBridge Workstation Service. Nunca envie um PIN, uma chave de API, o Protetor do Chaveiro nem a licença.