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 se comporta 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 SQL. 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 SQL pelo menos uma vez; um banco de dados inacessível na inicialização resulta numa inicialização recusada depois de cerca de noventa segundos.

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.

Seis 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
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 está ausente ou vencida	TrustBridge.Pki.Validation.LacunaPkiRuntime	Toda inicialização, com o cofre ligado
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

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.

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 Stranded; os clientes recebem SESSION_EXPIRED e criam novas com o mesmo PIN
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 em Pending é encerrada por uma varredura como Failed, 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. 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.

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

Um Servidor e uma frota nunca são atualizados no mesmo minuto. O Servidor aceita a versão atual do protocolo das estações de trabalho (2) e a anterior, e a regra que importa é: atualize primeiro o Servidor, depois as estações de trabalho, com no máximo uma release de diferença.

Situação	O que acontece
Servidor à frente de uma máquina	Suportado. A máquina se conecta, assina e informa vereditos como antes. Uma Autoridade Certificadora Confiável adicionada no Servidor não chega a ela, e a tela da frota mostra Requer atualização na linha dela.
Máquina à frente do seu Servidor	A máquina não consegue se conectar. O Servidor mais antigo recusa o handshake, registra isso na linha da máquina na tela da frota e na Trilha de Auditoria como um workstation.connect com falha, e a máquina não assina nada até o Servidor ser atualizado.

Atualizar um Servidor para o protocolo 2 também é o que faz uma frota preparada passar a receber dele a política de confiança: uma máquina com Certificates:Validation:UseServerTrustedCas no padrão recebe as Autoridades Certificadoras Confiáveis do Servidor segundos depois do próximo handshake e deixa de considerar os próprios arquivos de âncora enquanto tiver um conjunto não vazio. Uma frota que precisa manter o próprio pipeline de âncoras desliga essa opção nas máquinas antes de elas encontrarem o Servidor atualizado.

Atualizar as estações de trabalho é instalar um MSI mais novo sobre o antigo, sem propriedades. Veja Instalação das estações de trabalho.

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 do Lacuna PKI SDK vence numa data, e nada falha de forma evidente quando isso acontece: todo certificado passa a informar UNTRUSTED, a criação de sessões é recusada com CERT_NOT_ACTIVE, e uma linha Critical na inicialização é o único aviso. 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>[^<]*'

• No Servidor (só com o cofre ligado): defina Certificates__Validation__License com o novo base64 e reinicie. No App Service com uma referência do Key Vault, uma nova versão do secret e um reinício.
• Na frota: publique o novo valor pela configuração de licença do modelo de Diretiva de Grupo e depois reinicie o Workstation Service em cada máquina, já que o registro é lido uma única vez na inicialização. Sem Diretiva de Grupo, faça um reparo silencioso do MSI com PKI_LICENSE=<base64> em cada máquina.

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.

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 desativada deve ser revogada na tela da frota, tenha sido desinstalada ou não. A revogação não depende da cooperação da máquina.
• Uma máquina reinstalada é uma máquina nova, com uma impressão digital nova, e chega de novo à fila. Uma atualização ou um reparo continua sendo a mesma máquina.
• Uma máquina que mostra Atrasada na coluna de Autoridades Certificadoras Confiáveis se reconecta e busca o conjunto de novo sozinha; uma que mostra Requer atualização precisa que os componentes atuais da estação de trabalho sejam instalados.
• 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: A workstation assertion was refused: Expired ou NotYetValid, com a diferença. A solução é a sincronização de horário.

Os diretórios temporários

O Servidor grava dois 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

Um sistema de arquivos somente leitura é tolerado, com uma exceção: 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 em que todo Certificado do Cofre está UNTRUSTED. Monte um tmpfs sobre /tmp. Para mover os dois, 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	Contínuo ou diário, conforme a sua política
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.