Versão 1.0.0-alpha.1mais recente
Capítulo 2.15
Dia dois: operar o Nexus
O trabalho de rotina de manter uma instalação em funcionamento após a primeira semana. Começa com a abertura do cofre de chaves após um reinício e termina com a desinstalação.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

Na primeira vez que faltou a energia na sala de servidores da Harrow Port Authority, tudo voltou a funcionar, exceto as partes que precisavam de chaves. Os pods estavam em execução (Running) e a consola carregou. Ninguém conseguia abrir um ficheiro. Tomás Reilly tinha lido sobre isto e, ainda assim, demorou vinte minutos a lembrar-se do motivo. O desselador do repositório de chaves inicia selado após cada reinício do seu nó, e apenas um custódio o pode abrir.
Este capítulo acompanha a rotina do operador após a primeira semana, desde o repositório de chaves e os seus custódios até à desinstalação. Cada verbo nexusctl aqui aceita --explain, que imprime as operações kubectl e helm que executaria sem as executar. Utilize-o na primeira vez que executar algo num cluster de produção.
Custódia do cofre de chaves
Uma instalação tem dois servidores OpenBao no seu namespace. O repositório de chaves, openbao, guarda todas as chaves que o Nexus utiliza. O desselador, openbao-unsealer, é um segundo OpenBao, mais pequeno, cuja única função é desselar o repositório de chaves. O repositório de chaves dessela-se a si próprio através da chave de trânsito do desselador; o desselador é selado com o esquema de Shamir, sob a forma de 5 partes das quais quaisquer 3 o desselam.
Na primeira instalação, um Job de custódia inicializa ambos os servidores dentro do cluster. Este encripta as partes do desselador e as chaves de recuperação do repositório de chaves na sua própria memória para cada custódio nomeado em keys.custody.recipients, e armazena apenas o texto cifrado (os Secrets openbao-unseal-shares-encrypted e openbao-recovery-keys-encrypted). Revoga ambos os tokens de raiz no mesmo Job. O pacote de cada custódio contém partes suficientes para desselar por si só, pelo que basta um custódio após um reinício.
Após o reinício de um nó
Após qualquer reinício do nó onde o desselador é executado (um corte de energia, um reinício da máquina, um reinício do tempo de execução do contentor), o desselador inicia selado. Até que um custódio o dessele, o repositório de chaves também permanece selado e nada que precise de uma chave funciona. A consola continua a responder e as pessoas ainda podem iniciar sessão, mas qualquer ação que necessite de uma chave do repositório de chaves fica a aguardar: abrir conteúdo encriptado, uma reivindicação, uma verificação de uma parte compilada.
Pergunte ao próprio OpenBao, dentro de cada pod. Este é o desselador:
kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
bao status -format=json -address=https://127.0.0.1:8200 \
-ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"Execute o mesmo comando contra openbao-0 com -tls-server-name=openbao para o repositório de chaves. bao status termina com o código 0 quando o servidor está desselado, 2 quando está selado e 1 quando não conseguiu responder. Uma saída com 1 não permite concluir nada, porque o pod pode ainda não estar ativo. Aguarde um minuto e pergunte novamente. Se o desselador estiver desselado e o repositório de chaves ainda estiver selado, o repositório de chaves está a desselar-se a si próprio e não tem de fazer nada.
Desselagem
O chart disponibiliza unseal.sh, na sua pasta files/custody/, exatamente igual byte por byte em cada lançamento. Um custódio executa-o na sua própria máquina. Este lê o Secret encriptado, desencripta-o uma vez com a identidade do custódio (uma identidade Secure Enclave pede o Touch ID uma vez), submete as partes ao desselador e confirma que está desselado. Nenhuma parte é alguma vez escrita num ficheiro ou colocada numa linha de comandos.
A Harrow executa-o em modo direto, através de um port-forward:
kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &
AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh<path-to-your-custodian-identity> é o ficheiro de identidade age do custódio, a metade privada de um dos destinatários em keys.custody.recipients. UNSEAL_RESOLVE é o nome que o certificado do desselador contém (<namespace> é o namespace onde o Nexus está instalado, nexus por predefinição), pelo que o TLS é verificado contra a própria CA do desselador, mesmo que a ligação vá para 127.0.0.1. O script nunca desativa a verificação de certificados.
| Saída | Última linha | Significado |
|---|---|---|
| 0 | UNSEALED nexus/openbao-unsealer-0 |
Desselado. Se já estava, nada foi enviado |
| 1 | STILL-SEALED … |
Ainda selado, ou uma chamada de desselagem falhou |
| 2 | UNSEAL-REFUSED … |
Falta um pré-requisito, indicado na mensagem |
| 3 | UNSEAL-REFUSED … |
Esta identidade não consegue desencriptar as partes, pelo que não é um custódio desta instalação. Nada foi enviado |
Dentro de um minuto, o repositório de chaves segue-se por si só. Verifique com kubectl -n nexus get deploy,statefulset se tudo está pronto novamente.
Os custódios são escolhidos antes da instalação e cada um cria a sua própria chave na sua própria máquina. O chart apenas vê a metade pública:
age-keygen -o custodian.key
age-plugin-se keygen --access-control=any-biometry -o custodian.keyO primeiro comando cria uma identidade age comum; o seu destinatário é a linha # public key: age1... no ficheiro. O segundo cria uma guardada no Secure Enclave de um Mac, com um destinatário que começa por age1se1. Qualquer um dos destinatários entra em keys.custody.recipients. O ficheiro de identidade fica com o respetivo custódio, offline.
Cópia de segurança e restauro
Cópia de segurança e restauro mostra cada repositório com a sua última cópia de segurança e a última vez que um restauro do mesmo foi efetivamente testado. Uma cópia de segurança só é comprovada depois de ter sido restaurada, pelo que a página regista ambos. São feitas cópias de segurança de seis repositórios. A base de dados principal guarda pessoas e definições; tarefas e o registo de auditoria. Ao lado desta encontram-se o grafo de conhecimento e o índice de pesquisa, seguidos do repositório de ficheiros e do repositório de memória. As chaves são o sexto, seladas e mantidas separadas dos dados. As cópias de segurança vão para o seu próprio armazenamento, encriptadas com as suas próprias chaves, e a Adverant não as consegue ler. Quando um repositório não teve um restauro testado dentro da sua regra, a página mostra a placa RESTORE_TEST_OVERDUE com um botão Testar agora. Um restauro de teste é executado num espaço separado e ninguém dá por isso.
As mesmas duas ações estão disponíveis a partir da linha de comandos:
nexusctl backup now
nexusctl backup verifybackup now faz uma cópia de segurança de todos os repositórios de uma só vez. backup verify verifica a cópia de segurança mais recente. Execute ambos antes de qualquer alteração que o deixe apreensivo.
Para restaurar, deve indicar o nome da cópia de segurança:
nexusctl restore --from <backup-id><backup-id> provém da lista em Cópia de segurança e restauro. Um restauro necessita da aprovação de uma segunda pessoa e, enquanto é executado, a barra de progresso mostra-o com a hora a que começou e quem o aprovou. Todos ficam em modo só de leitura durante o restauro, o que é diferente de estar bloqueado: as pessoas podem iniciar sessão e ler. As tarefas não iniciam (os agendamentos aguardam e recuperam o atraso) e a pesquisa regressa quando o índice de pesquisa estiver de volta. Tudo o que foi escrito após a realização da cópia de segurança é perdido, pelo que o relatório de restauro lista esses dados por proprietário para que os possam refazer.
Guarde mais uma coisa com as suas cópias de segurança: o Secret nexus-generated no namespace nexus. O chart cria as palavras-passe geradas e as chaves de encriptação da instalação na primeira instalação e volta a lê-las a partir desse Secret em cada atualização. Os dados selados sob EXTERNAL_KEY_ENCRYPTION_KEY abrem apenas com essa chave. Armazene uma cópia do Secret onde quer que guarde o material mais sensível que possui, porque qualquer pessoa que o detenha detém essas chaves.
Atualizações
Tomás atualiza em dois passos. Primeiro, pergunta o que irá mudar:
nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarO plano lista o que muda no lançamento, qualquer alteração à estrutura da base de dados e se pode ser revertida. Em seguida, aplica-a:
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarA aplicação faz primeiro uma cópia de segurança e executa as verificações prévias (preflight). Depois, move os motores por vagas, e cada vaga aguarda até que a anterior esteja saudável durante 10 minutos. A página Atualização mostra cada vaga à medida que avança e o estado de saúde da instalação entretanto. Também indica até quando o caminho de regresso permanece aberto; após essa data, voltar atrás requer um restauro. Se um passo falhar, o Nexus reverte todos os motores para o lançamento anterior e verifica-os. O aviso UPGRADE_ROLLED_BACK indica então o nome do passo que falhou e informa que os dados não foram alterados. A correção aparece antes de Tentar novamente, e o pacote de suporte está à distância de um botão.
Para uma instalação sem ligação ao exterior, o pacote chega em suporte físico. A opção Importar de suporte físico verifica a assinatura do lançamento contra a chave de lançamento da Adverant instalada na instalação e garante que as versões apenas avançam. Os ficheiros assinados por qualquer outra entidade são recusados com MEDIA_SIGNATURE_INVALID: nada é carregado e o lançamento em execução continua a funcionar.
O que acontece nos bastidores
nexusctl upgrade apply executa helm upgrade contra o chart. Se atualizar com o Helm por conta própria, aplicam-se as mesmas regras:
helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900sO esquema avança antes de os novos pods serem implementados. As migrações do chart são hooks de pré-atualização que são executados por ordem: primeiro o bootstrap da base de dados, depois as migrações de cada serviço e, por fim, as do backend for frontend (BFF) da consola. O Job de custódia também é executado e, numa instalação que já esteja inicializada, confirma esse facto e não altera nada. Cada Job de hook tem um limite de tentativas (backoff limit) de 0, pelo que uma migração que falhe interrompe a atualização e nunca é repetida silenciosamente: leia o respetivo registo com kubectl -n nexus logs job/<hook-job> antes de tentar novamente.
O pod de cada serviço aguarda num contentor de inicialização (init container), wait-for-schema, até que o registo de lançamentos mostre as suas migrações aplicadas para a imagem do novo lançamento. Após uma reversão, ou uma atualização que tenha alterado apenas valores, um pod reiniciado encontra a sua linha e inicia de imediato.
Antes de atualizar
Vale a pena planear tendo em conta três pontos das notas de lançamento:
- Atualize num período calmo. Na primeira atualização de uma instalação feita a partir de um chart anterior, a tarefa de bootstrap retira os antigos direitos de tabela predefinidos, e cada serviço recupera os seus através da sua própria migração. Até que essa migração seja executada, um serviço não pode utilizar as suas tabelas. O intervalo dura segundos. Se os segundos importarem, escale primeiro os serviços para zero e volte a escalar assim que as tarefas de migração tiverem terminado.
- Atribua uma organização a cada chave da interface de programação de aplicações (API). Uma chave sem organização é recusada com
403 TOKEN_ORG_MISSINGpor todos os serviços que verificam chaves através do nexus-auth, incluindo o nexus-graphrag. Antes de atualizar, atribua uma organização a cada uma dessas chaves ou emita uma nova chave. As chaves bcrypt antigas continuam a funcionar até à sua data de revogação definitiva. - Limpe as chaves de API em cache posteriormente. Até uma hora de entradas de chaves em cache contém o nome da aplicação incorreto até que o faça. Execute isto contra a cache do nexus-auth, o Valkey da instalação (
nexus-valkey, palavra-passe no Secretnexus-generatedsobVALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"Isto aplica-se ao repositório predefinido dentro do cluster. Com dataTier.valkey.mode: external não existe tal pod: execute a mesma análise e eliminação contra o seu próprio anfitrião Valkey, com a palavra-passe do Secret indicado em dataTier.valkey.external.existingSecret.
Reversão (Rollback)
Dentro do período que a página Atualização mostra, a opção Voltar atrás devolve todos os motores ao lançamento anterior. Após esse período, voltar atrás significa restaurar a cópia de segurança que a atualização fez primeiro.
Dois valores nunca devem mudar ao longo de uma atualização ou reversão.
keys.installationName é permanente. O primeiro bootstrap do repositório de chaves cria a identidade da instalação sob este valor, e é essa identidade que a sua licença refere. Utilize exatamente o mesmo valor em todos os ficheiros de valores que alguma vez aplicar a esta instalação.
O Secret nexus-generated deve permanecer como está. Em cada atualização, o chart lê EXTERNAL_KEY_ENCRYPTION_KEY a partir dele e verifica a sua estrutura. Um valor que não seja base64 de 32 bytes nem a chave bruta de 32 bytes de uma instalação mais antiga interrompe a renderização com EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, e o chart nunca imprime o valor. Isto significa que alguém editou ou substituiu o Secret. Reponha a chave sob a qual os dados desta instalação estão selados, como base64 dos seus 32 bytes (printf %s "$OLD" | base64), e atualize novamente. Uma nova chave aleatória deixaria ilegível tudo o que estivesse selado sob a antiga.
Escalonamento
Cada componente tem um interruptor e um tamanho no ficheiro de valores. Os componentes obrigatórios não podem ser desligados: o chart executa-os independentemente do que diga o seu interruptor. Aos outros podem ser atribuídas mais réplicas e mais recursos.
# harrow-values.yaml (Helm values): scaling
components:
gateway:
replicas: 2
resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
graphrag:
replicas: 2
workflows:
replicas: 2
workflows:
concurrency: "8"
dataTier:
qdrant:
resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }Aplique-o com helm upgrade conforme indicado acima. Os volumes são dimensionados sob dataTier.<store>.size; verifique se a sua classe de armazenamento permite aumentar um volume antes de o elevar. A página Como está a instalação apresenta gráficos sobre o quão ocupados têm estado os processadores e a memória do cluster, com o espaço livre restante em cada um. Aumente o que se esgotar primeiro.
Pacotes de suporte
Quando a Harrow precisa da ajuda da Adverant, Tomás cria um pacote de suporte:
nexusctl support-bundle --out harrow-support-4471.tar.gzA página Pacote de suporte da consola cria o mesmo ficheiro. Esta recolhe os registos dos motores das últimas 24 horas com detalhes de saúde e de versão. As definições entram sem os seus segredos, juntamente com os relatórios de verificações prévias (preflight) e de instalação. Antes de algo ser escrito, a ocultação substitui nomes e segredos por marcadores de posição, e pode ler uma pré-visualização daquilo que irá exatamente sair. O conteúdo próprio das pessoas nunca é recolhido. O pacote segue para a Adverant através de carregamento para a página Suporte e pacotes de suporte da sua conta ou como um ficheiro transportado em suporte físico. Apenas os engenheiros de suporte nomeados no pedido o podem abrir, e é apagado após 30 dias.
Exportação de evidências
Os auditores e a sua própria equipa de conformidade querem frequentemente provas de que a plataforma se comporta conforme descrito. nexusctl evidence export escreve essas provas:
nexusctl evidence export --out harrow-evidence-2027-01Juntamente com os registos que exporta, o comando executa as sondas de aceitação da plataforma: o encaminhador de inteligência artificial (IA) está acessível e responde, uma tarefa UNO é enviada e concluída, e uma leitura entre organizações é recusada. Os respetivos resultados encontram-se em probes.json na pasta de saída.
Estado num relance
nexusctl status --json responde se a instalação está saudável e em que estado se encontra cada componente. Também comunica o estado da licença com a respetiva data de expiração, a edição e o lançamento em execução. Cada parte compilada é listada com o seu resumo criptográfico (digest) e assinatura. É o comando ideal para colocar por trás da sua própria monitorização.
Desinstalação
nexusctl uninstall --profile <profile-file><profile-file> é o perfil de implementação para o cluster, o mesmo ficheiro que passou para nexusctl handoff --profile <profile-file> --out <dir> se a sua equipa de plataforma gerir o cluster. A transferência (handoff) escreve, para essa equipa, uma lista em linguagem simples do que o Nexus precisa do cluster e os manifestos para o satisfazer. A desinstalação remove os namespaces do Nexus e nada mais, mantendo as suas cópias de segurança. A identidade da instalação desaparece com ela. Uma instalação posterior no mesmo cluster é uma nova instalação com uma nova identidade, pelo que a sua reivindicação é uma nova reivindicação e a sua licença é uma nova licença.
As páginas Esta instalação (This installation)
Os operadores da instalação têm o seu próprio grupo no menu, Esta instalação, e é nas suas páginas que ocorre a maior parte deste capítulo na consola. Um membro que abra uma delas vê a página Não é um administrador, que indica quem pode agir.
| Página | Para que serve |
|---|---|
| Licença e o que desbloqueia | A licença e os seus grupos de funcionalidades (capítulo 2.13, Licenças) |
| Se a licença expirar | A escada de expiração por palavras, com as datas desta licença |
| Partes compiladas | Cada módulo licenciado com a sua verificação de assinatura noturna |
| Declaração de utilização para a Adverant | Os contadores anuais, legíveis antes de saírem |
| Versões e atualizações | Cada versão instalada, com quem a instalou e quando |
| Atualização | A atualização faseada e o caminho de regresso |
| Cópia de segurança e restauro | Cada repositório, a sua última cópia de segurança e o seu último restauro testado |
| Estado da instalação | Nós, capacidade e custo de operação, com avisos |
| Chaves e apagamento | A chave de cada organização, e Apagar com um motivo e uma segunda pessoa |
| Incidentes | Problemas abertos e fechados, com o que foi feito |
| A descontinuar em breve | Funcionalidades a serem desligadas, com datas, exportação e substituição |
| Estado | Cada parte do Nexus agora e ao longo de 30 dias, em palavras que qualquer pessoa pode ler |
| Pacote de suporte | O que sai para a Adverant, e como |
Duas destas páginas merecem uma menção. Partes compiladas verifica todas as noites cada módulo licenciado contra a assinatura da Adverant. Uma cópia alterada de um módulo é recusada e nunca é carregada, enquanto a cópia assinada continua em execução, e a página conta as recusas por mês para que uma cópia adulterada não passe despercebida. Estado está escrito de forma a que qualquer pessoa na organização o possa ler. Mostra cada parte do Nexus agora e ao longo dos últimos 30 dias como uma faixa de dias, com manutenção agendada e incidentes recentes, e um operador adiciona um incidente ou uma janela de manutenção a partir da mesma página.
Uma instalação Community tem uma página, Esta instalação (Community), com a sua versão, saúde e atualizações. As páginas Enterprise aparecem nela como amostras que indicam quem as pode ativar.




