---
title: "Operação"
description: "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 necessária."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/operations"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# 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:

```text
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](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation#atualizando).

## 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:

```bash
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](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation#se-a-máquina-nunca-aparece-na-fila).
- **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.