Versão 1.0.0-alpha.1mais recente
Capítulo 2.8
Instalações numa única máquina
Instalar o Nexus num único servidor Linux com o nexusctl, ou avaliá-lo num portátil com o k3d, e aceder à consola por HTTPS para que o início de sessão e as chaves de acesso (passkeys) funcionem.
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

Antes de a Harrow Port Authority colocar o Nexus no seu cluster de produção, Tomás Reilly pretendia fazer duas instalações mais pequenas. Uma era um piloto num servidor Linux sobressalente no edifício de operações, destinado às doze pessoas que o iriam experimentar primeiro. A outra corria no seu próprio portátil, para que pudesse testar tudo até ao limite sem que ninguém desse por isso. Este capítulo abrange ambas as opções. Utilizam o mesmo chart, as mesmas imagens e a mesma execução inicial de uma instalação completa de Kubernetes, pelo que tudo o que aprender numa máquina é válido para as outras.
O caminho para o servidor resume-se a um comando: nexusctl install --single-node cria um cluster k3s na máquina, instala o cert-manager e, de seguida, instala o Nexus. O caminho para o portátil é mais prático. Cria você mesmo um cluster k3d, instala o cert-manager e o chart com o Helm e, depois, realiza uma tarefa adicional que apanha quase toda a gente desprevenida: coloca a consola atrás de HTTPS na sua própria máquina, uma vez que um simples encaminhamento de portas (port-forward) nunca permite iniciar sessão.
Qual a dimensão necessária para a máquina
O Nexus requer cerca de 2.05 núcleos de CPU (unidade central de processamento) e 6.7 GiB de memória em pedidos com os valores predefinidos do chart, e os seus volumes somam 142 GiB. Esse total divide-se em 50 para PostgreSQL, 5 para Valkey, 20 para Neo4j, 10 para Qdrant, 50 para o armazenamento de objetos, 1 e 5 para os dois armazenamentos do OpenBao e 1 para o volume de recibos. Os pedidos correspondem ao que o escalonador reserva, sendo que a utilização real é superior assim que as pessoas começam a trabalhar.
| Máquina | CPU | Memória (RAM, memória de acesso aleatório) | Disco |
|---|---|---|---|
| Nó único recomendado | 8 vCPU | 32 GiB | 250 GB SSD (unidade de estado sólido) |
| Mínimo para avaliação | 4 vCPU | 16 GiB | 200 GB |
Um portátil que cumpra os requisitos mínimos de avaliação conseguirá executar o Nexus, mas o que conta é o próprio limite de memória do Docker, e não o do portátil. Atribua pelo menos 16 GiB ao Docker antes de começar.
Ambos os caminhos requerem o Kubernetes 1.33 ou posterior. O caminho de nó único inclui a sua própria distribuição: k3s v1.33.6+k3s1, na qual todas as versões de lançamento são testadas.
Parte um: um servidor Linux com o nexusctl
O servidor piloto do Tomás é uma máquina de 8 núcleos com 32 GiB de memória e um SSD de 500 GB, a executar uma versão atual de Linux sem mais nada instalado. A instalação requer permissões de root, uma vez que instala o k3s como um serviço do sistema.
Obter o nexusctl e verificá-lo
- Transfira o
nexusctlpara a sua arquitetura a partir dehttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/, juntamente com a chave pública da versão. Guarde a chave comorelease.pub. O Capítulo 2.4, Obter e verificar uma versão, explica como confirmar a impressão digital da chave comparando-a com a que a Adverant publica. - Verifique o binário e a versão com a chave:
nexusctl version --json
nexusctl verifyO nexusctl verify verifica a transferência através da chave de lançamento da Adverant e recusa qualquer ficheiro que não consiga validar. Se falhar, pare e transfira novamente. Nunca execute uma instalação a partir de um ficheiro que não tenha sido verificado.
Criar a chave de custodiante
O armazenamento de chaves da instalação sela as suas chaves de recuperação para um ou mais custodiantes. Um custodiante é uma pessoa que detém um ficheiro de identidade age offline, sendo que o chart se recusa a instalar sem que exista pelo menos um. Na própria máquina do custodiante:
age-keygen -o custodian.keyO ficheiro começa com uma linha # public key: age1.... Essa parte pública é o que vai para o ficheiro de valores. O ficheiro de identidade propriamente dito nunca sai da máquina do custodiante. Num Mac com Secure Enclave, age-plugin-se keygen --access-control=any-biometry -o custodian.key cria uma chave que requer o Touch ID para ser utilizada, e a sua parte pública começa por age1se1.
Escrever o ficheiro de valores
# harrow-pilot-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
enterprise:
enabled: false
tls:
mode: existing
existingSecret: harrow-public-tls
keys:
installationName: harrow-pilot
custody:
recipients:
- "<custodian-age-recipient>"<custodian-age-recipient> é a linha age1... de custodian.key. Adicione uma entrada na lista por cada custodiante.
keys.installationName é permanente. O primeiro arranque do armazenamento de chaves emite a identidade da instalação sob esse nome, e nada o poderá renomear posteriormente. Tem de corresponder a ^[a-z][a-z0-9-]{0,62}$: letras minúsculas, começando por uma letra, com um máximo de 63 caracteres. Não copie nexus-example nem o destinatário de exemplo dos ficheiros de exemplo do próprio chart. O chart recusa ambos pelo nome, e a verificação prévia (preflight) reporta logo os mesmos códigos.
Os três anfitriões (hosts) constituem a identidade da instalação. Todos os serviços se recusam a iniciar sem eles, e cada início de sessão, cookie e chave de acesso (passkey) fica vinculado a hosts.console. Escolha nomes que continuará a querer manter daqui a cinco anos.
Apontar os três nomes para o servidor
As pessoas acedem à consola, à API (interface de programação de aplicações) e ao serviço de início de sessão através do controlador de ingress integrado do k3s, o Traefik, nas portas 80 e 443 do servidor. Adicione três registos DNS (Sistema de Nomes de Domínio) para console.harrow.example, api.harrow.example e auth.harrow.example, cada um a apontar para o endereço do servidor. A verificação prévia (preflight) valida cada nome e indica-lhe qual deles não tem registo.
A política de rede do chart permite que apenas um namespace aceda aos três serviços públicos. O seu valor predefinido, kube-system, é onde o k3s executa o Traefik, pelo que num nó único não deve alterar networkPolicy.ingressNamespace.
Executar a verificação prévia e instalar
- Execute a verificação prévia (preflight) com a opção de nó único. Esta lê a máquina e o seu ficheiro de valores sem alterar nada.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Leia a linha de resumo no final. Um aviso nunca bloqueia a instalação, mas uma falha sim, e cada linha com falha apresenta uma indicação
fix.
────────────────────────────────────────────────────────────
9 passed · 1 warning · 0 failed You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed
- Instale. A opção
--editiontem de coincidir comeditionno ficheiro de valores.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Acompanhe a execução. O processo executa novamente a verificação prévia, instala o k3s v1.33.6+k3s1, instala o cert-manager v1.21.3, instala o Nexus e aguarda que todos os serviços respondam à respetiva verificação de integridade (health check). No servidor do Tomás, demorou um pouco menos de dez minutos.
done Preflight again 9 passed · 1 warning
done k3s v1.33.6+k3s1 node Ready
done cert-manager v1.21.3 ready
done Database and search ready
done Engines started
done Console https://console.harrow.example
Installed. Nobody can sign in yet.
Open https://console.harrow.example/claim
Code <code> works once, for 30 minutes
Fingerprint of this installation, to compare in the browser:
3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7
Mantenha essa impressão digital no ecrã. Irá compará-la no navegador quando reclamar a instalação com o código. Se o código expirar antes de o utilizar, nexusctl claim-code --administrator <email> gera um novo. O Capítulo 2.12, A primeira execução, continua a partir daqui.
Colocar o certificado no devido lugar
Com tls.mode: existing, as três rotas de ingress servem o certificado no Secret indicado por tls.existingSecret. Este tem de abranger todos os três anfitriões. A verificação prévia lê esse Secret quando ele existe e emite um aviso se o certificado expirar no espaço de 30 dias. Quando o Secret ainda não se encontra lá, a linha indica-lhe que o deve criar, tratando-se de um aviso e não de uma falha.
Num nó único, o cluster não existe até que a instalação o tenha criado; por conseguinte, crie o Secret imediatamente após a instalação. Extraia primeiro o kubeconfig do cluster (a última secção deste capítulo explica como o fazer) e, em seguida, crie o Secret com ele:
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt contém o certificado seguido de quaisquer certificados intermédios, e harrow-public.key a respetiva chave privada. Se os seus certificados provierem de uma CA (autoridade de certificação) privada, nexusctl preflight e nexusctl install aceitam --ca-bundle <file> para que possam verificar a cadeia. As outras formas de gerir o TLS (Transport Layer Security) encontram-se no capítulo 2.11, Variações: armazenamentos externos, TLS e ingress.
Se isto falhar
| O que vê | O que significa | O que fazer |
|---|---|---|
PREFLIGHT_FAILED (409) |
A verificação prévia encontrou uma falha, pelo que a instalação não foi iniciada. Nada foi instalado. | Corrija cada linha com falha, utilizando a respetiva indicação fix, e execute a instalação novamente. |
INSTALLATION_NAME_MISSING |
keys.installationName está vazio. |
Defina o nome permanente próprio da instalação. |
INSTALLATION_NAME_EXAMPLE |
O nome é o que consta nos valores de exemplo do chart. | Escolha o seu próprio nome. |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients está vazio. |
Adicione o destinatário público age1... de cada custodiante. |
KEYS_CUSTODIAN_EXAMPLE |
Um destinatário corresponde ao custodiante de exemplo do chart, cuja identidade ninguém detém. | Substitua-o pelos destinatários dos seus custodiantes. |
nexusctl termina com o código 0 quando pode prosseguir, 1 quando uma verificação o bloqueou e 2 quando não pôde sequer ser executado (um ficheiro de valores ilegível, uma opção incorreta). Um script pode ramificar a sua execução com base nestes três valores.
Parte dois: uma avaliação num portátil com o k3d
O k3d executa o k3s dentro de contentores Docker, pelo que todo um cluster reside num portátil e desaparece com um único comando. As ferramentas de lançamento que testam cada versão do Nexus constroem os seus clusters exatamente desta forma, e copiar as suas definições poupa-lhe o trabalho de voltar a descobrir os problemas com que elas já se depararam.
Necessita do Docker, k3d 5.8.3, kubectl, Helm v4 e Chrome. O Tomás utilizou o seu Mac.
Criar o cluster
k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
--image rancher/k3s:v1.33.6-k3s1 \
--k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfigCada opção tem uma razão de ser.
--agents 0fornece um nó de servidor e nenhum nó de processamento (worker). O Nexus funciona perfeitamente num único nó, e um segundo nó apenas consome memória.--image rancher/k3s:v1.33.6-k3s1fixa a versão do k3s na qual todas as versões de lançamento são testadas. Sem isto, obtém a versão predefinida do k3d.--disable=traefik@server:0exclui o Traefik. Um portátil não tem um endereço público para servir, pelo que acederá à consola através da sua própria interface HTTPS (ver abaixo).--wait --timeout 300sregressa apenas quando o cluster responde, ou falha após cinco minutos.
Se criar um espelho (mirror) do registo de lançamentos no seu portátil, adicione --registry-config <registries.yaml> para enviar as transferências de imagens para o espelho, e --k3s-arg "--disable-default-registry-endpoint@server:0" para que nada recorra a um registo a montante (upstream). As ferramentas de lançamento funcionam desta forma, com todas as imagens a provirem exclusivamente do espelho.
Instalar o cert-manager
O chart cria a sua própria CA local, nexus-local-ca, como um emissor do cert-manager, e todos os serviços obtêm o seu certificado a partir dela. Sem os recursos do cert-manager no cluster, helm install recusa o chart em poucos segundos. Instale primeiro o cert-manager v1.21.3, a partir do chart que o projeto cert-manager publica:
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mO Nexus não necessita de mais nada do cert-manager e, em particular, não necessita do trust-manager.
Instalar o Nexus
- Escreva um ficheiro de valores para o portátil. O TLS termina na sua própria interface (front), pelo que
tls.modeénone.
# harrow-eval-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
tls:
mode: none
keys:
installationName: harrow-eval
custody:
recipients:
- "<custodian-age-recipient>"- Instale o chart a partir do registo e omita
--wait(o aviso abaixo explica o motivo).
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
-n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m- De seguida, aguarde você mesmo pelas cargas de trabalho (workloads):
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
doneO ciclo do StatefulSet existe porque alguns deles atualizam um pod de cada vez a pedido, e kubectl rollout status recusa-os. Aguardar por readyReplicas funciona para qualquer estratégia de atualização.
Quando ambos os comandos terminam, cada Deployment está Available e cada StatefulSet tem os seus pods prontos. Ninguém consegue iniciar sessão ainda. Isso está correto: a instalação ainda não foi reclamada.
Porque é que um reencaminhamento de portas (port-forward) nunca permite iniciar sessão
O passo seguinte óbvio seria kubectl port-forward svc/nexus-alpha 3000:3000 e abrir um navegador em http://127.0.0.1:3000. As páginas da consola carregam, pelo que parece funcionar. Mas não funciona, e nenhuma definição o fará funcionar. Há três fatores que o impedem, cada um deles intencional.
| O que o impede | Porquê |
|---|---|
| A origem | O início de sessão da consola recusa qualquer pedido cuja origem não seja https://<hosts.console>, neste caso https://console.harrow.example. Uma página servida a partir de http://127.0.0.1:3000 tem a origem incorreta, pelo que o início de sessão nunca chega a começar. |
| O cookie | A sessão consiste num cookie __Host- marcado como Secure. Os navegadores armazenam um cookie deste tipo apenas através de HTTPS, sem atributo de domínio, exclusivamente para o anfitrião exato que o definiu. Através de HTTP simples, o navegador descarta-o. |
| A chave de acesso (passkey) | O primeiro administrador inicia sessão com uma chave de acesso (passkey), e uma chave de acesso requer um contexto seguro com um certificado válido. O Chrome recusa-se a criar uma chave de acesso perante um aviso de certificado, mesmo que tenha clicado para avançar. |
Por conseguinte, o navegador tem de comunicar com https://console.harrow.example, com um certificado em que confie, e esse nome tem de conduzir ao seu portátil.
Aceder à consola por HTTPS no seu portátil
O método abaixo utiliza a própria CA do chart para emitir o certificado, um encaminhamento de portas (port-forward) para alcançar a consola e um perfil do Chrome separado que confia nessa CA específica e mapeia o nome da consola para o seu portátil. O armazenamento de confiança do seu sistema e /etc/hosts permanecem inalterados.
Emitir um certificado para o nome da consola
- Solicite ao cert-manager um certificado para o anfitrião da consola, assinado pelo emissor do chart:
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: nexus-console-front
namespace: nexus
spec:
secretName: nexus-console-front-tls
dnsNames: [console.harrow.example]
duration: 24h
usages: [server auth, digital signature, key encipherment]
privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120sO cert-manager assina-o dentro do cluster. Nunca chega a ler a chave privada da CA.
- Copie o certificado, a respetiva chave e o certificado da CA a partir do Secret:
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key- Calcule o pin da CA. O Chrome identifica uma chave fidedigna através do hash SHA-256 em base64 da respetiva chave pública:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Fixe (pin) a chave da CA, e não a do certificado. O certificado dura um dia e recebe uma chave nova sempre que o cert-manager o renova, ao passo que a CA permanece a mesma.
Colocar uma interface HTTPS à frente de um encaminhamento de portas
- Encaminhe o Service da consola. A sua porta é a que se denomina
http, que corresponde à 3000 nesta versão:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Execute um listener HTTPS em
127.0.0.1:28443que encaminhe para127.0.0.1:3000. Qualquer proxy inverso em que já confie servirá, desde que cumpra quatro requisitos:- sirva
tls.crtseguido deca.crtcomo a cadeia, comtls.key; - mantenha o cabeçalho
Hostcomoconsole.harrow.example; - defina
X-Forwarded-Proto: https; - deixe passar atualizações (upgrades) de WebSocket, uma vez que a consola as utiliza.
- sirva
Um encaminhamento de portas para um Service associa-se ao único pod que escolheu quando foi iniciado. Depois de uma atualização ou de um reinício substituir o pod da consola, o encaminhamento mantém-se ativo mas não encaminha para nada, e o navegador apresenta um erro de bad gateway. Reinicie o encaminhamento de portas sempre que o pod da consola mudar.
Abrir o Chrome com o pin e o mapeamento de nomes
Num Mac:
open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
"--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
"--ignore-certificate-errors-spki-list=<ca-pin>" \
https://console.harrow.example/install<ca-pin> é o resultado da linha openssl. No Linux, inicie o Chrome com as mesmas três opções.
As três opções funcionam em conjunto. --host-resolver-rules envia console.harrow.example na porta 443 para a sua interface (front), apenas dentro deste perfil. --ignore-certificate-errors-spki-list confia nos certificados emitidos por essa chave de CA específica, e o Chrome só o respeita com --user-data-dir. O perfil separado mantém a exceção afastada da sua navegação diária. Não se trata de um interruptor geral para "ignorar erros de certificado": qualquer elemento que não seja assinado pela CA do cluster continuará a falhar.
Com esse perfil aberto, https://console.harrow.example/install conduz à página de reclamação da instalação, e já é possível criar uma chave de acesso (passkey). O Capítulo 2.12, A primeira execução, retoma o processo a partir daqui.
Quando o portátil reinicia
O armazenamento de chaves tem duas partes: o armazenamento de chaves propriamente dito e um pequeno desselador (unsealer) que detém a sua chave de desbloqueio. Após qualquer reinício do nó (um reinício do Docker, um reinício do portátil, k3d cluster stop e start), o desselador inicia selado. O armazenamento de chaves dessela-se através dele, pelo que, até que um custodiante dessele o desselador com a sua própria identidade age, nada do que necessite de uma chave funciona. Esta é uma propriedade da arquitetura, e funciona da mesma forma num cluster de produção. O Capítulo 2.15, Dia dois: operar o Nexus, mostra o processo de desselagem.
Quando terminar a avaliação:
k3d cluster delete harrow-evalEliminar o cluster elimina a instalação e tudo o que nela existe.
nexusctl kubeconfig
Um cluster que o nexusctl install --single-node criou pertence ao nexusctl. Para o alcançar com kubectl, helm ou qualquer outra ferramenta, solicite o respetivo kubeconfig:
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetO ficheiro concede acesso administrativo total ao cluster. Mantenha-o no modo 600, nas máquinas das pessoas que gerem a instalação, e em mais nenhum local. Todos os comandos posteriores na Parte 2 que aceitam --context ou leem KUBECONFIG funcionam num nó único através deste ficheiro. O mesmo se aplica a uma atualização: nexusctl upgrade plan --bundle <file> e nexusctl upgrade apply --bundle <file> num nó único também atualizam o cluster k3s que o nexusctl detém.
nexusctl install --single-node coloca num servidor Linux.O que transita para um cluster
Tudo o que fez numa máquina tem um equivalente num cluster. O ficheiro de valores é o mesmo ficheiro com um registo, modo TLS ou classe de armazenamento diferentes, tal como mostra o capítulo 2.11, Variações: armazenamentos externos, TLS e ingress. A primeira execução é idêntica. O que não é possível transferir é a instalação em si: o nome da instalação é fixado em definitivo, e uma instalação não pode ser movida de um portátil para um servidor. Quando o Tomás passou do seu portátil para o servidor piloto, começou de novo com um novo nome, harrow-pilot, e manteve harrow-eval para experiências.
