Operação

A operação do dia a dia de um TrustBridge implantado: o que monitorar, o que ler nos logs, como um reinício e uma atualização se comportam, como manter a frota numa versão que o Servidor aceita e a manutenção recorrente que uma implantação exige.

Saúde e monitoramento

Probe	O que comprova	Para que usar
GET /healthz	Uma ida e volta ao banco de dados. Healthy (200) ou Unhealthy (503), e nada mais no corpo. Anônimo, não auditado.	Monitoramento de disponibilidade e alertas. Um 503 é um container no ar com um banco de dados fora do ar.
GET /	O container está vivo. Responde 200 mesmo sem o banco de dados.	Um gatilho de reinício, onde a plataforma tiver um (o Health check do App Service).
Entrar em /admin	O caminho que uma requisição real percorre, passando pelo banco de dados.	A verificação depois de toda implantação e atualização.

O /healthz não informa nada sobre a frota: um Servidor sem nenhuma estação de trabalho conectada está Healthy. A presença de uma máquina é assunto da tela da frota.

O Servidor inicia e continua no ar com o banco de dados inacessível depois da inicialização, para que uma instabilidade momentânea do banco não vire uma indisponibilidade que uma pessoa precise resolver. Enquanto o banco de dados está fora, a porta de entrada responde 200, o contrato falha e o cofre fica fechado. Crie alertas sobre o /healthz, não sobre o container.

Como o Servidor aplica o próprio schema na inicialização, um container em execução já comprovou que acessou o banco de dados pelo menos uma vez; um banco de dados inacessível na inicialização resulta numa inicialização recusada depois de cerca de noventa segundos.

O que o console administrativo informa

• O Painel (/admin/dashboard), onde todo login cai, conta os documentos e hashes assinados hoje, neste mês e nos últimos 30 dias, consolidados alguns minutos atrás, e lista ao lado o que precisa de você: a Atividade de assinatura atrasada, as falhas das últimas 24 horas, as máquinas recusadas até serem atualizadas, as máquinas admitidas não conectadas, as leitoras com falha, os tokens bloqueados e os certificados a vencer, cada um com o link para a tela que resolve. É a primeira página a ler; veja Painel.
• A faixa de situação, no topo de toda página administrativa, conta as estações de trabalho conectadas, as máquinas cujo protocolo o Servidor não aceita mais (N exigem atualização), as sessões ativas, os documentos e hashes assinados nas últimas 24 horas consolidadas, as falhas das últimas 24 horas e os certificados que vencem em 30 dias. Cada chip abre a tela que resume. N falhas (24 h) abre a Trilha de Auditoria filtrada nas falhas desde o momento em que a contagem começou; é o caminho mais curto entre "algo está errado" e as linhas que dizem o quê. Um chip Atividade de assinatura parada em … significa que a contagem do Painel parou de avançar: leia o log do Servidor (veja Avisos que merecem um alerta).
• Um banner em todas as páginas administrativas significa uma de três coisas: a licença da PKI do Servidor foi recusada, então nenhum Certificado do Cofre assina e nenhuma estação de trabalho assinará depois que o serviço dela reiniciar (renove-a); as gravações de auditoria estão caindo para o log do Servidor; ou as ACs de teste da Lacuna são confiáveis.
• Para comprovar que a implantação assina de ponta a ponta, faça uma Assinatura de teste na tela Assinatura de teste (/admin/test-signature): um CPF, o PIN dele e a chave de API de uma Aplicação Cliente devolvem um PDF de uma página assinado, ou a etapa que falhou. No Docker, ela precisa antes de um listener de loopback; veja A Assinatura de teste.
• Por que uma estação de trabalho se desconectou está na linha workstation.disconnect dela, e ao lado de cada desconexão no painel da máquina na tela da frota: timed-out (o Servidor deixou de ouvi-la; veja Workstations:ClientTimeout), closed, revoked, removed, returned-to-queue, server-stopping ou error, com o transporte que ela usava. Um closed em LongPolling também pode ser uma máquina que ficou em silêncio: o long polling não sofre timeout, e um proxy que não transporta WebSockets é o motivo mais comum para uma máquina estar nele.
• O que está errado numa máquina, sem estar nela: uma máquina no Workstation 1.8.0 ou posterior informa a própria situação, mostrada no chip Relatório da linha dela, no painel de detalhes e na tela Relatórios das Estações de Trabalho, e, a partir do Workstation 1.10.0, quem está no console dela. As recusas das últimas 24 horas são contadas na linha dela. Veja Relatórios das Estações de Trabalho e Encontrar os problemas de uma máquina.

Avisos que merecem um alerta

Linha do log do Servidor, em Warning	O que significa
Workstation … holds a candidate certificate for this session but is connected at protocol 5, below 6: it cannot hold a Signing Authorization …	Uma máquina no Workstation 1.5.0 foi ignorada para uma sessão cuja Aplicação Cliente tem o PIN por transação ligado. Ela conta como offline para essas sessões até rodar a 1.6.0. Veja Ordem de atualização.
Workstation … has given N PIN Proof(s) for CPF … that did not check …	Uma máquina esgotou o seu limite de provas com falha para um titular (Sessions:MaxPinFailures dentro de Sessions:PinFailureWindow). Nada é pedido a ela para esse CPF até as falhas saírem da janela. Registrado na auditoria como pin.proof-budget-spent.
The Certificate Vault has tried N password(s) for CPF … that opened nothing …	O mesmo limite, esgotado pelo cofre. Também registrado como pin.proof-budget-spent, com Certificate Vault como nome do titular.
Passwords are switched off on this Server's admin console …	Registrado em toda inicialização enquanto Admin:CertificateSignIn:Required está ligado. Conta as contas habilitadas sem CPF vinculado e quantas delas são de Administradores. Quando esse número chega ao número de Administradores habilitados, ninguém consegue administrar a plataforma.
Forwarded headers: honoured from whoever connects …, and this Server is not on App Service	Uma implantação Docker que ainda usa ASPNETCORE_FORWARDEDHEADERS_ENABLED. Cite o proxy em ForwardedHeaders:TrustedProxies e remova a variável.
… pings every 00:00:15, but Workstations:ClientTimeout is …	Uma máquina envia pings com menos frequência do que o timeout permite, então é desconectada e se reconecta sem parar.
Um Warning na inicialização citando chaves TestSignature: que não são mais lidas	Uma implantação atualizada a partir do Servidor 1.14.x ainda define TestSignature:Cpfs, ApiKey, FallbackEmail, Turnstile:* ou Timeout. Remova-as e revogue a chave que ApiKey guardava. Veja A Assinatura de teste.
Sessions:SignatureAllowance is set and is no longer read (ADR-0050) …	Uma implantação atualizada a partir de uma versão anterior ao Servidor 1.17.0 ainda define a franquia de toda a implantação. As sessões dela ficam sem limite até que um Administrador defina uma Franquia de Assinaturas em cada Aplicação Cliente que precisa de uma; depois, remova a chave. Veja Atualização para o Servidor 1.17.0 ou posterior.
Audit retention purge is held at …, where Signing Activity is folded to, rather than …	A Atividade de assinatura do Painel está atrasada, então a limpeza mantém linhas de auditoria além de Audit:RetentionDays até elas serem contadas. Registrado em Error quando o atraso chega a um dia ou mais. O Painel e a faixa de situação dizem onde ela parou.
Signing Activity fold skipped a pass: the database answered its lock with a fault …	Uma passagem da contagem do Painel não rodou. Repetida a cada minuto, é uma contagem que nunca avança.
Signing Activity is held at … by a Test Signature that began then and has not ended …	Uma Assinatura de teste segura a contagem do Painel enquanto roda; esta já roda há mais tempo do que qualquer uma consegue. Nada depois dela é contado até ela terminar ou o Servidor reiniciar.

Um limite esgotado não é o bloqueio de PIN do titular: um PIN errado custa à própria máquina do titular uma prova com falha por certificado dele que ela guarda, então uma máquina pode ser ignorada antes de o bloqueio disparar. Os dois se resolvem conforme as falhas saem da janela.

A trava do cofre

Num Servidor com Vault:Enabled, as verificações de inicialização do cofre leem o banco de dados. Quando o Servidor sobe antes de o banco de dados responder, o cofre fica travado fechado, em vez de o host recusar a inicialização:

warn: TrustBridge.Server.Common.Vault.VaultReadiness[0]
      The Certificate Vault is on, but its start-time checks could not read the database, so the
      vault is closed until they have run. Nothing will be signed with a certificate this Server
      holds and nothing new will be imported until then; the checks are retried at the first
      attempt to use it (ADR-0024 §8).

Um cofre fechado é um Servidor com aparência saudável que recusa toda assinatura com um certificado guardado no servidor e toda importação, enquanto o nível das estações de trabalho funciona normalmente. As verificações são repetidas na primeira tentativa de usar o cofre, e um banco de dados que voltou as conclui com o cofre aberto. O que um cofre fechado nunca pode fazer é gerar uma chave nova, o que deixaria órfão tudo o que está armazenado: é por isso que a trava existe.

Leitura dos logs

A saída do console é o registro. Envie-a para um lugar com a retenção que você escolheu: o logging driver do container no Docker, o Application Insights ou um workspace do Log Analytics no App Service. O arquivo rotativo em /tmp/trustbridge-logs alimenta a tela Log do Servidor do console administrativo e é uma conveniência, não uma cópia a guardar.

Estas categorias trazem as linhas que um operador deve reconhecer, todas visíveis no nível padrão:

Linha	Categoria	Quando
Quais migrações foram aplicadas, ou por que o schema foi recusado	…Persistence.SchemaUpgrade	Toda inicialização
Qual Protetor do Chaveiro está selando, o thumbprint dele e quantos aposentados estão legíveis	…KeyRings.KeyRingPosture	Toda inicialização
Se o cofre está desligado, aberto ou travado fechado	…Vault.VaultReadiness	Toda inicialização, e quando a trava se abre
Em quais proxies reversos o Servidor confia para o endereço de quem chama, numa linha que começa com Forwarded headers:	…Http.TrustedProxies	Toda inicialização
Quantas contas não têm CPF vinculado enquanto as senhas estão desligadas	…Admin.CertificateSignInPosture, em Warning	Toda inicialização com Admin:CertificateSignIn:Required ligado
Uma linha de auditoria não conseguiu chegar ao banco de dados, com a própria linha	…Audit.AuditLog, em Critical	Sempre que o banco de dados recusa uma gravação
A licença do PKI SDK foi recusada: vencida, corrompida ou não é uma licença	TrustBridge.Pki.Validation.LacunaPkiRuntime, em Critical	Toda inicialização, com ou sem cofre, e quando uma licença vence com o Servidor em execução
Os overrides do Administrador não puderam ser relidos depois da etapa do schema	…Persistence.SchemaGate	Uma inicialização em que a tabela de configurações não respondeu
Uma máquina ignorada na criação de uma sessão: no protocolo 4, ou com o limite de provas com falha esgotado	…Sessions.CreateSession.Handler, em Warning	Sempre que acontece
Como a Atividade de assinatura foi preenchida retroativamente, e se os hashes são contados desde a instalação ou a partir da linha de auditoria mais antiga que sobrou	…Dashboard.SigningActivityFold	A primeira inicialização do Servidor 1.17.0 ou posterior
O que a limpeza da auditoria excluiu, ou que ela está esperando a Atividade de assinatura	…Audit.AuditRetentionPurge	Na inicialização e depois diariamente
Um documento de uma aplicação que assina com o REST PKI Core que não pôde ser assinado antes de qualquer chave ser usada: uma chave que o REST PKI Core recusa, uma chave sem o papel Worker, um contexto de segurança que ele não tem, ou a seção RestPkiCore que não existe mais	…Signatures.RestPkiCoreAdmission, em Error	Cada chamada de assinatura que ele recusa

Toda resposta HTTP traz um X-Correlation-Id, e toda linha de log gravada durante o atendimento dela traz o mesmo id, assim como as linhas da Trilha de Auditoria que ela gerou. A reclamação de um cliente, uma linha de log e uma linha de auditoria se encontram por esse id.

O fallback da auditoria faz parte da sua retenção de logs, e não dos seus backups. Uma linha de auditoria que o banco de dados não aceitou é gravada no log do Servidor no nível Critical e em nenhum outro lugar, e o console administrativo mostra um alerta. A trilha tem um buraco exatamente onde o banco de dados estava fora; as linhas Critical são o que o preenche.

A Trilha de Auditoria

A retenção é Audit:RetentionDays (365), que aceita override na tela Configurações e usuários. Uma limpeza diária exclui as linhas mais antigas. Ajuste-a ao prazo de contestação da implantação. A limpeza sobre uma tabela AuditEvents grande também é o que torna alguma migração ocasional demorada, e é para isso que servem o WEBSITES_CONTAINER_START_TIME_LIMIT=1800 no App Service e o prazo de trinta minutos por comando.

A limpeza espera a Atividade de assinatura do Painel, que é contada a partir da Trilha de Auditoria. Na primeira inicialização do Servidor 1.17.0 ou posterior, a Atividade de assinatura é preenchida retroativamente a partir de toda a Trilha de Auditoria, um bloco por vez, e a limpeza não exclui nada até isso terminar. Depois disso, ela nunca exclui além do ponto até o qual a Atividade de assinatura está consolidada: enquanto a contagem está atrasada, as linhas de auditoria são mantidas além da retenção, e a limpeza registra um Warning dizendo isso, e um Error quando o atraso chega a um dia ou mais. A Atividade de assinatura em si não guarda dados pessoais e nunca é apagada, então os totais do Painel desde a instalação podem ser maiores do que o que a Trilha de Auditoria ainda guarda.

Relatórios e consultas escritos diretamente sobre o banco de dados precisam saber o que mudou nas linhas que leem:

• Desde o Servidor 1.24.0, uma linha api.call traz errorCode, o código de erro com que a chamada foi respondida, quando ela foi respondida com um envelope de erro. As linhas mais antigas não têm esse campo.
• Desde o Servidor 1.23.0, SigningOperations.FailureCause registra o que a Estação de Trabalho respondeu quando uma execução falhou nela (PIN_NOT_CACHED, PIN_REJECTED, TOKEN_LOCKED, CERTIFICATE_UNAVAILABLE, NOT_AUTHORIZED, FAILED, ou UNANSWERED quando nenhuma resposta voltou), ao lado de FailureCode. É nula em qualquer outra falha e numa execução que falhou antes da atualização. Workstations ganha sete colunas que aceitam nulo, com o console que o último relatório trouxe (ConsoleAccountSid, ConsoleAccountLabel, ConsoleLocked, ConsoleTrayAttached, ConsoleTrayVersion, ConsoleOtherTraySessions, ConsoleReportedAt). Uma linha pin.prompt-answered respondida Undeliverable traz detail, no formato descrito a seguir.
• Desde o Servidor 1.22.0, uma linha signing.authorization-refused cujo motivo é NO_TRAY traz detail: o motivo da máquina, a sessão do console, as sessões em que havia um Tray App conectado e o build do Tray. É nulo em qualquer outro motivo e vindo de uma máquina anterior ao Workstation 1.9.0.
• Desde o Servidor 1.21.0, SigningSessions.WorkstationId e SigningOperations.WorkstationId não são mais chaves estrangeiras. Elas registram o id da máquina à qual a sessão ou a operação estava vinculada, e, para uma máquina removida, esse id não corresponde a nenhuma linha de Workstations: use um left join. A linha de auditoria admin.workstation-removed da remoção identifica a máquina enquanto for mantida.
• Desde o Servidor 1.20.0, os thumbprints de certificado são gravados em hexadecimal maiúsculo no registro de certificados, no cofre e nas Autoridades Certificadoras Confiáveis, e todo momento é gravado em UTC. A Trilha de Auditoria nunca é reescrita, então as linhas antigas dela mantêm a grafia com que foram gravadas.
• Desde o Servidor 1.18.0, toda linha que a execução de assinatura de um documento grava traz documentSigner, e session.created traz pin ("proven" ou "none").
• Desde o Servidor 1.17.0, as linhas de resultado de assinatura trazem os tempos (timing e, quando a máquina deu o próprio relato, machineReported), qualquer que seja o valor de Diagnostics:ServerTiming.

E duas mudanças desde o Servidor 1.11.0:

• certificate.encoding-dropped e certificate.announcement-refused gravam uma linha por snapshot, e não uma por certificado. Os detalhes passam a ser { count, entries: [...] }. As linhas gravadas antes da 1.11.0 mantêm os campos planos, então tudo o que interpreta esses detalhes precisa ler os dois formatos. O cpf da linha só é preenchido quando todas as entradas citam o mesmo titular; uma linha que cobre vários é encontrada pela máquina, não pelo CPF.
• Workstations.EnrolledAt agora é Workstations.FirstSeenAt. Só o nome da coluna mudou; o console administrativo já dizia "Vista pela primeira vez".

Reinícios e atualizações

Uma única instância, então todo reinício é uma indisponibilidade visível de um ou dois minutos. O que sobrevive:

	Sobrevive a um reinício do Servidor
Conexões das estações de trabalho	As máquinas se reconectam sozinhas, com backoff
Sessões de Assinatura vinculadas a estações de trabalho	Sim, intactas: o PIN em que se apoiam está em cache na máquina
Sessões de Assinatura vinculadas ao cofre	Não. Terminam como Interrompida; os clientes recebem SESSION_EXPIRED e criam novas com o mesmo PIN. Uma sessão com PIN por transação vinculada ao cofre (transactionPin: "client") não guarda nenhum segredo entre as chamadas e sobrevive
Logins de Administradores	Sim: o chaveiro das sessões web está no banco de dados
Requisições de assinatura em andamento	Não; falham de forma que podem ser repetidas. Uma Operação de Assinatura que ficou Pendente é encerrada por uma varredura como Com falha, com RUN_STRANDED
Overrides de configuração do Administrador	Sim

No App Service, a plataforma reinicia containers para a própria manutenção, então uma cadência de reinícios que não é sua fica visível para a assinatura com o cofre. Deixe DOCKER_ENABLE_CI desligado e faça deploy de forma deliberada.

Atualizar o Servidor é usar uma nova tag de imagem: docker compose pull && docker compose up -d, ou uma nova imagem no App Service, por exemplo trustbridge-server:1.24.0. A nova imagem aplica as próprias migrações na inicialização e as cita no log. Com Database:MigrateOnStart=false, aplique-as antes, ou a nova imagem não inicia.

Faça backup do banco de dados antes de toda atualização: é o único caminho de volta. A maioria das releases do Servidor a partir da 1.9.0 migra o schema (a 1.14.1, a 1.16.0, a 1.19.0, a 1.22.0 e a 1.24.0 não; o Changelog diz quais), e uma imagem mais antiga não inicia sobre um banco de dados que uma mais nova migrou. Reverter, portanto, é restaurar o backup de antes da atualização e implantar a imagem anterior, nunca só trocar a tag. A única exceção é uma release que não acrescenta migração em relação à anterior: voltar da 1.24.0 para a 1.23.0, por exemplo, é só trocar a imagem. Uma frota que já passou para um protocolo de estação de trabalho mais novo também não consegue se conectar ao Servidor mais antigo. No PostgreSQL, o backup é um pg_dump; veja Instalação do Servidor.

Atualizando a partir do Servidor 1.6.x: defina Certificates:Validation:License antes. Todo Servidor desde a 1.7.0 precisa da licença da PKI, com ou sem cofre, e não inicia sem ela.

Atualização para o Servidor 1.17.0 ou posterior

Três coisas a saber na primeira atualização depois da 1.16.x:

• Sessions:SignatureAllowance não é mais lida, então uma implantação que a define fica com sessões sem limite depois da atualização. Nenhuma Aplicação Cliente tem Franquia de Assinaturas depois da migração, e nada leva o valor da chave adiante. Logo depois de atualizar, defina o valor na tela Aplicações Cliente para cada aplicação cujas sessões ela limitava (1 para um integrador que pediu sessões de uso único) e depois remova a chave. Um Servidor que ainda a encontra definida inicia, com um Warning que a cita, qualquer que seja o valor.
• A Atividade de assinatura é preenchida retroativamente a partir de toda a Trilha de Auditoria, um bloco por vez, com o Servidor em execução. O Painel diz que nada foi consolidado ainda até isso terminar, e a limpeza da auditoria não exclui nada até lá (A Trilha de Auditoria).
• Dashboard:TimeZone (padrão UTC) define onde começam os dias e os meses do Painel. Defina-a com a zona IANA da implantação, como America/Sao_Paulo, se a meia-noite UTC não for o dia que a implantação quer dizer; uma zona que o Servidor não conhece, ou um id de fuso do Windows, recusa a inicialização.

A partir do Servidor 1.18.0, Signing:StrandedAfter precisa ser maior que o dobro de Signing:RequestBudget mais Signing:SignerCancelBudget. Os padrões atendem a isso; uma implantação que definiu StrandedAfter entre o piso antigo e o novo não inicia, e a linha cita a chave.

Atualização para o Servidor 1.23.0 ou posterior

O Servidor 1.23.0 aplica três migrações na inicialização, nos dois mecanismos de banco de dados: ReportWorkstationConsole acrescenta sete colunas que aceitam nulo a Workstations, RecordTheRunsFailureCause acrescenta a coluna FailureCause, que aceita nulo, a SigningOperations, e IndexTheAuditLogByWorkstationAndTime indexa a Trilha de Auditoria por máquina e momento, para a aba Eventos, o filtro de Estação de Trabalho da Trilha de Auditoria e a contagem de recusas da tela Estações de Trabalho. As duas primeiras são rápidas. O índice é construído sobre toda a tabela AuditEvents, então a duração cresce com a Trilha de Auditoria:

• Vá direto para o Servidor 1.24.0. O Servidor 1.23.0 construía o índice offline, o que mantém um lock que bloqueia as gravações na Trilha de Auditoria durante a maior parte da construção, e toda chamada de assinatura grava uma. O Servidor 1.24.0 constrói o mesmo índice online, em baixa prioridade, onde o SQL Server consegue: Azure SQL Database, Azure SQL Managed Instance e as edições Enterprise ou Developer (em baixa prioridade a partir da 2022, simplesmente online nas mais antigas). Um banco de dados que já aplicou a migração com a 1.23.0 não precisa de nada.
• O SQL Server Standard, Express e Web, e o PostgreSQL, ainda constroem o índice segurando as gravações. Com uma Trilha de Auditoria grande, atualize num momento tranquilo, sem outra instância do Servidor ainda atendendo o mesmo banco de dados.

Nada muda no protocolo dos Servidores 1.22.0 a 1.24.0, e nenhum deles exige atualizar o Workstation.

Ordem de atualização: primeiro o Servidor, depois a frota

O Servidor aceita duas versões do protocolo das estações de trabalho: a dele e a anterior. Uma máquina num protocolo mais antigo é recusada com Atualização necessária; uma num protocolo mais novo é recusada com update the Server first. As duas recusas ficam registradas na linha da máquina na tela da frota e na Trilha de Auditoria como um workstation.connect com falha, e uma máquina recusada não assina nada.

Servidor	Aceita os protocolos	Versões do Workstation que aceita
1.6.x	1–2	1.0.x
1.7.0 – 1.8.0	2–3	1.0.x, 1.1.0 – 1.3.0
1.9.0 – 1.12.0	3–4	1.1.0 – 1.3.0, 1.4.x
1.13.0 – 1.14.1	4–5	1.4.x (conecta, mas não atende sessões novas), 1.5.0
1.15.0 – 1.24.0	5–6	1.5.0 (atende toda sessão, exceto as com PIN por transação), 1.6.0 – 1.10.0

O Workstation 1.0.x fala o protocolo 2, da 1.1.0 à 1.3.0 o protocolo 3, da 1.4.0 à 1.4.2 o protocolo 4, a 1.5.0 o protocolo 5, e da 1.6.0 à 1.10.0 o protocolo 6.

O Workstation 1.8.0 e posteriores vão com o Servidor 1.20.0 ou posterior, embora o protocolo seja o mesmo. Eles enviam ao Servidor um Relatório da Estação de Trabalho, que só o Servidor 1.20.0 e posteriores aceitam, com mensagens de até 1 MB no canal das estações de trabalho: um Servidor anterior encerra a conexão de um relatório acima de 32 KB, o que uma máquina no 1.8.0 com muitos tokens, middlewares ou erros pode enviar. A partir do Workstation 1.8.1 a máquina continua conectada a um Servidor anterior: até o Servidor aceitar um relatório numa conexão, ela mantém os relatórios abaixo de 32 KB. O Workstation 1.7.0 não exige nenhuma mudança no Servidor.

O que um Workstation mais novo acrescenta só aparece num Servidor mais novo, e um Servidor mais antigo o ignora, então qualquer um dos lados pode ir primeiro dentro dessas releases. O motivo de um NO_TRAY do Workstation 1.9.0 é registrado a partir do Servidor 1.22.0. O console do Workstation 1.10.0, e o motivo de um pedido de PIN na criação da sessão que ele não conseguiu mostrar, são guardados e exibidos a partir do Servidor 1.23.0, em que uma máquina numa versão anterior mostra Precisa da Estação de Trabalho 1.10.0 na coluna Conta no console. Os Servidores 1.22.0 a 1.24.0 vão com qualquer Workstation dentro da janela deles.

Dentro de uma janela de protocolos, a regra é: atualize primeiro o Servidor, depois as estações de trabalho, com no máximo uma release de diferença. Uma máquina à frente do seu Servidor não consegue se conectar: o Servidor mais antigo a recusa com update the Server first, não lhe entrega a licença da PKI, e todo certificado dessa máquina aparece como UNTRUSTED no Tray App até o Servidor ser atualizado. Um Servidor à frente de uma máquina que ainda está na janela dele é suportado.

O protocolo 5 foi a exceção: o Servidor 1.13.0 e o Workstation 1.5.0 andaram juntos. No protocolo 5 o Servidor não envia mais o PIN da aplicação cliente a nenhuma estação de trabalho: ele desafia cada máquina que tem um certificado candidato e confere a Prova de PIN (PIN Proof) com que a máquina responde. Uma máquina no protocolo 4 (Workstation 1.4.x) ainda se conecta ao Servidor 1.13.0, recebe a licença, busca as Autoridades Certificadoras Confiáveis, anuncia os certificados, assina para as sessões já vinculadas a ela e pode receber a oferta de uma versão. Ela nunca recebe um desafio de PIN nem uma solicitação de PIN, então, para a criação de sessões, conta como offline. Um titular cujas máquinas estão todas ainda na 1.4.x recebe 422 WORKSTATION_OFFLINE até que uma delas seja atualizada, e o Servidor registra um Warning cada vez que ignora uma máquina assim. A atualização é, portanto, uma indisponibilidade para todo titular cujas máquinas forem atualizadas com atraso. Uma máquina na 1.3.0 ou anterior é recusada de vez.

O protocolo 6 volta a ser primeiro o Servidor. O Servidor 1.15.0 recusa o Workstation 1.4.x, e o Workstation 1.6.0 não se conecta a um Servidor anterior à 1.15.0. Uma máquina na 1.5.0 se conecta à 1.15.0 e atende toda sessão como antes; só uma sessão cuja Aplicação Cliente tem o PIN por transação ligado a ignora. Uma atualização para o Servidor 1.15.0 ou posterior, na ordem:

1. Faça backup do banco de dados.
2. Procure na tela Estações de Trabalho alguma máquina admitida ainda na 1.4.x e passe-a antes para o Workstation 1.5.0 (ofereça a versão, ou instale-a à mão ou por Política de Grupo). Ela será recusada no handshake assim que o Servidor for atualizado.
3. Atualize o Servidor.
4. Envie a versão do Workstation na tela Versões da Estação de Trabalho, a 1.6.0 ou posterior (a 1.8.0, a 1.9.0 ou a 1.10.0 só depois que o Servidor estiver na 1.20.0 ou posterior, e a 1.10.0 com o Servidor 1.23.0 ou posterior para ver o console), e ofereça-a com Entregar a todas ainda não atualizadas…. As máquinas cuja Política de Grupo desliga as atualizações pelo Servidor recebem a versão à mão ou por Política de Grupo.
5. Só ligue o PIN por transação de uma Aplicação Cliente quando as máquinas dos titulares dela rodarem a 1.6.0 ou posterior, acompanhando as linhas Warning que citam máquinas no protocolo 5 ignoradas.

Os integradores cuja Aplicação Cliente não usa o PIN por transação não veem nada de novo, exceto que um pin enviado numa chamada de assinatura, que os Servidores anteriores ignoravam, agora é recusado com 400 INVALID_REQUEST.

Um Servidor anterior à 1.13.0 com a frota na 1.4.x não pode ir direto para a 1.15.0 ou posterior: o novo Servidor recusaria toda máquina na 1.4.x, e o Workstation 1.5.0 não se conecta a um Servidor anterior à 1.13.0. Passe antes pelo Servidor 1.14.1 e pelo Workstation 1.5.0, nessa ordem, e depois siga os passos acima:

1. Faça backup do banco de dados.
2. Planeje as máquinas que o Servidor não consegue atualizar: as que estão no Workstation 1.3.0 ou anterior, e as cuja Política de Grupo desliga as atualizações pelo Servidor. Elas precisam do Workstation 1.5.0 instalado à mão ou por Política de Grupo, na mesma janela de manutenção, porque uma máquina na 1.5.0 não se conecta a um Servidor anterior à 1.13.0.
3. Atualize o Servidor para a 1.14.1.
4. Envie o TrustBridge-Workstation-1.5.0-x64.msi na tela Versões da Estação de Trabalho e ofereça-o com Entregar a todas ainda não atualizadas… na tela Estações de Trabalho. O envio precisa esperar a atualização: um Servidor recusa uma versão que fala um protocolo mais novo que o dele.
5. Acompanhe a coluna Versão do serviço da tela da frota e as linhas Warning que citam máquinas no protocolo 4, até toda máquina rodar a 1.5.0. Depois, se quiser que máquinas que sumiram apareçam como offline mais cedo, reduza Workstations:ClientTimeout para 00:00:15: toda máquina que consegue se conectar à 1.13.0 envia pings com frequência suficiente para isso.

Nessa etapa nada muda para as aplicações cliente: o PIN continua chegando em POST /v1/sessions, e a partir da 1.13.0 ele não passa do Servidor.

Atualizar as estações de trabalho à mão é instalar um MSI mais novo sobre o antigo, sem propriedades. Veja Instalação das estações de trabalho. A partir do Workstation 1.4.0, uma máquina também pode receber uma versão entregue pelo Servidor: veja Atualização da frota pelo Servidor.

Atualização da frota pelo Servidor

Desde o Servidor 1.9.0, um Administrador pode entregar uma Versão da Estação de Trabalho à frota pelo console administrativo, e uma máquina com o Workstation 1.4.0 ou posterior a instala sozinha.

1. Envie a versão na tela Versões da Estação de Trabalho: o MSI assinado, de até 256 MB. O Servidor lê do próprio arquivo a versão, o protocolo que ela fala e o assinante, e a armazena no banco de dados. Ele recusa, citando o motivo e sem armazenar nada, um arquivo que não é um MSI, um pacote não assinado, um assinado por um certificado que o Publisher Pin dele não lista, uma versão que não são três números, um pacote que não declara protocolo (toda versão anterior ao Workstation 1.3.0), um protocolo fora da janela do Servidor e uma versão já armazenada. Cada recusa é uma linha admin.workstation-release-uploaded com falha na Trilha de Auditoria. No App Service, o envio é uma única requisição e precisa terminar dentro do timeout de quatro minutos do front end.
2. Ofereça-a na tela Estações de Trabalho: Oferecer versão… para as máquinas selecionadas, ou Entregar a todas ainda não atualizadas…, que lista toda máquina que a versão alcança para você desmarcar o que quiser antes de confirmar. Uma oferta só alcança uma máquina Admitida, no protocolo 4 ou posterior, abaixo da versão, cujo Publisher Pin lista o assinante da versão e cuja Política de Grupo deixa as atualizações ligadas. As demais aparecem com o motivo e mantêm o que tinham.
3. Cada máquina a instala sozinha: depois de uma espera aleatória de até dez minutos, baixa o pacote do Servidor, verifica-o, espera até não haver assinatura em andamento nem solicitação de PIN aberta, e o instala. Ela informa o resultado no próximo handshake, como installed, failed (com o código de saída do msiexec e o final do log dele) ou refused (citando a verificação que falhou). Cada resultado é uma linha workstation.update-installed, -failed ou -refused na Trilha de Auditoria.

Uma versão que falhou ou foi recusada não é tentada de novo até ser oferecida de novo. Corrija a causa e ofereça a mesma versão à máquina outra vez, ou use Entregar a todas ainda não atualizadas…, que oferece de novo a toda máquina que seleciona. Uma máquina que estava offline quando a versão foi oferecida de novo tenta no próximo handshake. Uma instalação que o Windows Installer estava ocupado demais para iniciar (código 1618) é repetida pela própria máquina cerca de quinze minutos depois.

Retirar a oferta interrompe toda máquina que ainda não começou a instalação: Retirar oferta para as máquinas selecionadas, Retirar de todas na tela Versões da Estação de Trabalho para uma versão. Uma versão oferecida a alguma máquina não pode ser excluída até as ofertas serem retiradas. Uma máquina que já instalou uma versão continua nela.

Quem o Servidor não alcança aparece na tela Estações de Trabalho: Atualizações desativadas por política para uma máquina cuja política Receber atualizações do Servidor TrustBridge está desativada, e Precisa de atualização manual para uma cuja versão não recebe atualizações do Servidor. O Workstation 1.3.0 e anteriores nunca recebem uma versão por esse caminho. Essas máquinas recebem a versão à mão ou por Política de Grupo.

Os downloads têm um limite próprio, WorkstationReleases:MaxConcurrentDownloads (20); uma máquina acima dele é informada de quando voltar. Eles não contam para o throttling das aplicações cliente, então uma distribuição não faz o contrato responder 429.

Rotação do Protetor do Chaveiro

A rotação é aditiva: um protetor novo sela as chaves novas e nunca re-cifra o que já está armazenado.

1. Mova o base64 do protetor que está saindo para KeyRingProtector__RetiredCertificates__0__Certificate (com …__0__CertificatePassword ao lado, se ele tiver senha). Um segundo protetor aposentado usa o índice 1, e assim por diante.
2. Coloque o novo em KeyRingProtector__Certificate.
3. Reinicie. A linha KeyRingPosture deve passar a citar o novo thumbprint e 1 retired protector(s).
4. Guarde o PKCS#12 antigo nos seus backups, permanentemente. Não existe um momento em que a rotação "termina".

Nunca coloque uma entrada aposentada vazia num template: uma entrada que resulta numa string vazia recusa a inicialização.

Renovação da licença do PKI SDK

A licença fica só no Servidor, e o Servidor a entrega à frota inteira. Toda estação de trabalho Admitida recebe a licença do Servidor ao se conectar e a mantém apenas em memória. Não há nada a configurar nas máquinas: nenhuma propriedade do MSI e nenhum valor de Política de Grupo traz uma licença.

A licença do Lacuna PKI SDK vence numa data, e nada avisa antes disso. Depois que ela vence, o Servidor registra uma linha Critical, toda página administrativa mostra um banner, e nada na frota nem no cofre consegue assinar: os certificados passam a informar UNTRUSTED, e a criação de sessões é recusada com CERT_NOT_ACTIVE. Leia o vencimento no arquivo e coloque-o no calendário que acompanha as renovações de certificados:

base64 -d license.base64 | grep -o '<Expiration>[^<]*'

Para renovar, substitua Certificates__Validation__License pelo novo base64 e reinicie o Servidor: no Docker, troque o PKI_LICENSE no .env e recrie o container; no App Service com uma referência do Key Vault, crie uma nova versão do secret e reinicie. O reinício é o que chega à frota: toda máquina conectada se reconecta e aplica a nova licença, e uma máquina que estava offline a recebe quando se conectar de novo. Uma máquina no Workstation 1.8.0 ou posterior mostra a licença que tem, válida, expirando, ou expirada ou recusada, no Relatório da Estação de Trabalho do painel de detalhes dela.

Rotação da Installer Key

Só para uma implantação que gerou uma Installer Key própria. O Servidor aceita todas as chaves que lista, então uma troca é uma distribuição gradual, e não uma virada num dia marcado: adicione a nova chave pública ao lado da antiga em Admission:InstallerKeys, reinicie o Servidor, aponte o INSTALLER_KEY das máquinas para a nova por um reparo silencioso, no ritmo de cada uma, e então remova a entrada antiga e reinicie de novo.

Rotação das chaves de API

Emita uma nova chave para a Aplicação Cliente na tela Aplicações Cliente, implante-a no cliente e depois revogue a antiga. Todas as chaves aceitas de uma aplicação são equivalentes, então a troca é invisível para as sessões em andamento.

Relatórios das Estações de Trabalho

Uma máquina no Workstation 1.8.0 ou posterior informa ao Servidor a própria situação, sem que ninguém peça: depois de todo handshake, e de novo alguns segundos depois de qualquer mudança. O Servidor guarda o último relatório de cada máquina, para que o suporte veja o problema de uma máquina sem estar nela, e um Administrador veja o mesmo problema em toda a frota:

• Tela Estações de Trabalho: um chip Relatório por máquina, o pior entre Leitora com falha, Token bloqueado, N tipos de erro (24h) e Sem relatório, com filtros para os dois primeiros. O Painel lista as leitoras com falha e os tokens bloqueados em O que precisa de você.
• Painel de detalhes: as leitoras deixadas com falha, cada token e quão perto o PIN dele está de bloquear, cada middleware e se carregou, a licença da PKI como a máquina a tem, as opções dela e os erros que o Workstation Service e o Tray App registraram, agrupados por modelo de mensagem.
• Tela Relatórios das Estações de Trabalho (/admin/workstation-reports): erros por modelo de mensagem, tokens por modelo e middleware por versão nas máquinas Admitidas, cada linha abrindo as máquinas que conta.

A partir do Workstation 1.10.0, o relatório traz o console: a Conta no console conectada ao console físico da máquina (o SID dela e, quando é resolvido, o nome DOMÍNIO\usuário) ou ninguém, se essa sessão está bloqueada, se um Tray App roda ali e a versão que ele anunciou, e quantas outras sessões têm um Tray App, sem as contas delas. O próprio Workstation Service lê a conta e o bloqueio, então eles são informados mesmo sem nenhum Tray em execução. O relatório é enviado de novo poucos segundos depois de um logon, um logoff, um bloqueio ou desbloqueio, uma troca de usuário no console, e um Tray App que inicia ou termina, e não enquanto o console não muda. O Servidor 1.23.0 e posteriores o guardam e o mostram na coluna Conta no console da tela Estações de Trabalho e na seção No console do painel (Console administrativo); um Servidor anterior o ignora. O Servidor o mantém para uma máquina desconectada e para uma revogada, e um relatório que não conseguiu ler o console daquela vez deixa o último no lugar.

Um relatório não é a Trilha de Auditoria e não grava nada nela; o log da própria máquina continua com todas as linhas. Os grupos de erro aos quais nenhum relatório acrescentou nada por WorkstationReports:ErrorRetentionDays (30 por padrão, contados no relógio do Servidor) são apagados por uma varredura diária, e o relatório de uma máquina vai junto quando ela é removida. Uma máquina pode ser instruída a não enviar relatório, pelo MSI ou por Política de Grupo (Configuração da estação de trabalho); ela passa então a aparecer como Sem relatório, como toda máquina numa versão anterior à 1.8.0. Sem relatório nunca é sinal de uma máquina saudável. Com o relatório desligado, nenhuma conta nem outra parte do console sai da máquina, e o Servidor esquece o console que guardava.

Encontrar os problemas de uma máquina

Duas coisas na tela Estações de Trabalho dizem a um operador quais máquinas vão falhar com os titulares, antes de eles ligarem:

• Conta no console, sem Tray (Servidor 1.23.0 com o Workstation 1.10.0) lista as máquinas conectadas em que alguém está conectado ao console e nenhum Tray App roda ali. Toda chamada de assinatura com PIN por transação e todo pedido de PIN na criação da sessão enviado a uma máquina assim é recusado até que um Tray rode. Peça à pessoa na máquina para abrir o TrustBridge pelo menu Iniciar (Workstation 1.9.0 e posteriores), ou, numa versão anterior, para fazer logoff e logon de novo. Ninguém no console com 1 outra sessão com Tray abaixo é um titular na Área de Trabalho Remota, onde nenhum pedido de PIN chega.
• Com recusas (24h) (Servidor 1.23.0) lista as máquinas com uma Recusa da Estação de Trabalho nas últimas 24 horas que foi um problema da máquina. Abra o painel da máquina: a aba Eventos abre em Somente recusas e diz cada uma por extenso, com o que pedir ao titular quando ele pode resolver. Uma recusa de uma máquina anterior ao Workstation 1.9.0 diz que nenhum Tray App pôde mostrar o pedido, e não diz por quê. Ver tudo na Trilha de Auditoria abre a trilha inteira da máquina.

Uma ligação para o suporte normalmente começa por uma pessoa, não por uma máquina: a busca da tela Estações de Trabalho encontra máquinas pelo login do Windows, pelo nome ou pelo CPF de quem ligou. Um titular cuja sessão não inicia aparece em Criações recusadas (24h) na tela Sessões de Assinatura, com cada máquina a que a requisição pediu o PIN e o que cada uma respondeu; uma assinatura que falhou está na tela Operações de Assinatura, por extenso. Veja Console administrativo, e Resolução de problemas para cada motivo que uma máquina informa.

Gerenciamento da frota

• Uma máquina que nunca aparece na fila quase sempre tem um problema de URL ou de cadeia TLS; leia primeiro o log Aplicativo do Visualizador de Eventos dela. Veja Instalação das estações de trabalho.
• Uma máquina perdida, roubada ou comprometida é revogada na tela da frota, tenha sido desinstalada ou não. A revogação não depende da cooperação da máquina, e a chave dela é recusada enquanto o registro dela continuar na frota.
• Uma máquina aposentada, reinstalada do zero ou renomeada pode ser removida na tela da frota: o registro, os certificados e o Relatório da Estação de Trabalho dela saem, enquanto o histórico de assinaturas fica. Se ainda estiver instalada e pedir de novo, ela chega à fila como uma máquina nova. Remover uma máquina revogada desfaz a recusa que prende a chave dela, então mantenha revogada uma máquina perdida ou comprometida. Veja Remover uma máquina.
• Uma máquina reinstalada é uma máquina nova, com uma nova impressão digital da chave, e chega de novo à fila; remova o registro antigo quando nada mais precisar dele. Uma atualização ou um reparo continua sendo a mesma máquina.
• Uma máquina devolvida à fila e abandonada nunca expira: remova-a na fila de admissão.
• Uma máquina recusada com Atualização necessária roda uma versão mais antiga que a janela do Servidor: no Servidor 1.15.0 e posteriores, o Workstation 1.4.x ou anterior. Instale nela a versão atual à mão ou por Política de Grupo.
• Uma máquina que mostra Atrasada na coluna de Autoridades Certificadoras Confiáveis se reconecta e busca o conjunto de novo sozinha.
• Desvio de relógio. Uma máquina cujo relógio está mais de Workstations:ClockSkewTolerance (60 s) fora não consegue se conectar, e o log do Servidor a cita em Warning: A workstation assertion was refused: Expired ou NotYetValid, com o thumbprint da chave da máquina e a diferença, positiva quando a máquina está atrasada em relação ao Servidor e negativa quando está adiantada. A solução é a sincronização de horário.

Os diretórios temporários

O Servidor grava três diretórios em /tmp dentro do container, e nada mais:

Caminho	Contém	Se for perdido
/tmp/trustbridge-pki	O cache do PKI SDK com os emissores e LCRs baixados, e a licença entregue ao SDK como arquivo	Nada. A validação baixa de novo o que precisa, a cerca de 1,15 s por passagem em vez de 140 ms
/tmp/trustbridge-logs	O arquivo de log rotativo que a tela Log do Servidor lê	Nada. Toda linha foi gravada primeiro no console
/tmp/trustbridge-releases	Uma cópia de cada Versão da Estação de Trabalho armazenada, de onde saem os downloads da frota, e um envio enquanto o Servidor o lê	Nada. Cada cópia é refeita a partir da linha da versão no banco de dados no próximo download

Um sistema de arquivos somente leitura é tolerado, com duas exceções. O SDK só lê uma licença a partir de um arquivo, então um container sem nenhum diretório temporário gravável inicia um Servidor cuja licença o SDK nunca leu: nada consegue assinar, e o console administrativo avisa. E um envio na tela Versões da Estação de Trabalho é gravado em trustbridge-releases antes de ser lido, então, onde esse diretório não pode ser gravado ou está cheio, todo envio é recusado com o motivo e o log do Servidor cita o diretório. Os downloads continuam funcionando sem ele, lidos do banco de dados.

Monte um tmpfs sobre /tmp por causa da licença. O diretório de versões cresce cerca de 100 MB por versão armazenada, e um tmpfs conta no limite de memória do container; por isso, onde houver versões armazenadas, monte um volume em disco sobre o próprio /tmp/trustbridge-releases. Para mover os três, defina TMPDIR.

Só apague o diretório de logs com o Servidor parado: o sink mantém o arquivo do dia aberto, e um arquivo removido por baixo dele continua recebendo linhas que ninguém consegue ler até a próxima rotação.

Backups, numa tabela

O quê	Onde	Frequência
O banco de dados	Os seus backups do SQL Server, ou pg_dump no PostgreSQL (Instalação do Servidor)	Contínuo ou diário, conforme a sua política, e antes de toda atualização
O .pfx do Protetor do Chaveiro e cada um dos aposentados	Fora da plataforma, onde ficam as coisas insubstituíveis	Uma vez cada; eles nunca mudam
O certificado TLS (Docker)	Onde ficam os seus certificados	A cada emissão
O fluxo do log do Servidor	A retenção do seu pipeline de logs	Contínuo

Restaure o banco de dados e o protetor juntos. Nada mais precisa ser restaurado; as estações de trabalho se reconectam, e o estado delas fica nas próprias máquinas. As Versões da Estação de Trabalho armazenadas, a Atividade de assinatura do Painel e os últimos Relatórios das Estações de Trabalho também estão no banco de dados.