Instalar e registrar um nó AeroNyx

Este guia instala o software de nó de código aberto da AeroNyx em um servidor Linux, registra o nó na sua conta de operador do Nodeboard com um código de uso único e verifica se a rede o admitiu. O caminho suportado é o script do repositório deploy/node/aeronyx-node.sh quickstart, que é o mesmo comando que o Nodeboard gera para você.

• Console do operador: app.aeronyx.network
• Código-fonte (AGPL-3.0): github.com/AeroNyxNetwork/AeroNyx

Antes de operar um nó, leia a Política de Operadores de Nós.

Antes de começar

Por que root: o repositório fica em /root/open/AeroNyx, o instalador grava /etc/aeronyx e /var/lib/aeronyx com modo 700, e server.toml com modo 600. Comandos que leem esses caminhos falham para outros usuários, e o Git se recusa a ler um checkout pertencente ao root a partir de outra conta ("dubious ownership").

O que o quickstart faz

O quickstart executa quatro etapas e para antes de qualquer alteração no host até que você aprove:

1. Imprime o plano de instalação resolvido (somente leitura).
2. Espera que você digite INSTALL. Pressionar Enter interrompe com segurança.
3. Executa verificações prévias, instala pacotes e o toolchain Rust fixado pelo repositório, grava /etc/aeronyx/server.toml se ele não existir (um arquivo existente é mantido), configura o encaminhamento de IP e o NAT, compila o nó, instala a unidade systemd aeronyx-server, registra a identidade do nó com o seu código, inicia o serviço e espera até 120 segundos pela admissão na rede.
4. Imprime status e um resumo de health --json.

A espera pela admissão verifica se a saúde local reporta ok, se o backend devolveu uma política recente (o ciclo de ida e volta do heartbeat funciona), se a descoberta tem pelo menos um par assinado validado e concluiu uma rodada de gossip e, no caso de nós públicos, se o nó está listado no pool público.

Etapa 1: criar um código de registro

1. Entre no Nodeboard e abra Registration Codes.
2. Selecione Generate Code.
3. Mantenha o código em sigilo. Ele expira após 15 minutos, funciona uma única vez e vincula o novo nó à conta que o criou.

Em seguida, o Nodeboard mostra um comando de quickstart, comandos de pré-visualização e de instalação passo a passo, um comando de status e um prompt para assistente de IA. A coluna Install Progress acompanha o instalador por not_started → planning → running → completed | failed.

O backend verifica o código quando o instalador chega à etapa de registro, que vem depois da compilação. Uma primeira compilação em um servidor pequeno pode levar mais de 15 minutos. Se o registro falhar porque o código expirou, gere um novo código e execute o quickstart novamente; a segunda execução reutiliza o cache de compilação.

Etapa 2: obter ou atualizar o repositório

aeronyx-node.sh não é um comando do sistema. Ele vem no repositório. Esta é a linha de clonar-ou-atualizar que o Nodeboard usa:

mkdir -p /root/open && cd /root/open
if [ -d AeroNyx/.git ]; then cd AeroNyx && git fetch origin main && git checkout main && git pull --ff-only origin main; else git clone https://github.com/AeroNyxNetwork/AeroNyx.git AeroNyx && cd AeroNyx; fi
git rev-parse HEAD

Sempre passe --repo-dir "$PWD" (ou --repo-dir /root/open/AeroNyx) ao script. Sem isso, install, upgrade, health e status usam por padrão /opt/aeronyx/AeroNyx.

Etapa 3: executar o quickstart

Execute o quickstart sem o código na linha de comando. Quando roda em um terminal, ele pede o código por um prompt oculto, de modo que o código não é exibido na tela, não fica salvo no histórico do shell e não é passado como argumento de processo:

cd /root/open/AeroNyx
./deploy/node/aeronyx-node.sh quickstart --repo-dir "$PWD" --branch main --quick \
  --node-name "Example1" --region DE --public-vpn

• --node-name é o nome exibido no Nodeboard e na lista de nós da VPN.
• --region é um código de país ISO 3166-1 alfa-2.
• --public-vpn publica o nó no pool público da VPN. Omita-o para manter o nó privado.

Em Nodeboard registration code:, cole o código e pressione Enter. Revise o plano e, em seguida, digite INSTALL.

Sobre o comando que o Nodeboard gera

O comando de quickstart do Nodeboard coloca o código na própria linha, por exemplo AERONYX_REGISTRATION_CODE='<code>' ./deploy/node/aeronyx-node.sh quickstart --repo-dir "$PWD" --branch main --quick. Isso funciona, mas o código fica salvo no histórico do shell. Se você usá-lo:

• Verifique echo "$HISTCONTROL". Se contiver ignorespace ou ignoreboth, comece o comando com um espaço e o Bash não o registra.
• Caso contrário, remova a entrada depois com history -d <number>.

O código é de uso único e expira após 15 minutos, o que limita a exposição, mas não o cole em tickets, capturas de tela ou chats.

Instalação não interativa

Para automação, primeiro pré-visualize e depois passe o código pela entrada padrão. read -rs o mantém fora da tela e do histórico:

cd /root/open/AeroNyx
./deploy/node/aeronyx-node.sh plan --repo-dir "$PWD" --branch main
read -rs AERONYX_CODE
printf '%s\n' "$AERONYX_CODE" | ./deploy/node/aeronyx-node.sh install \
  --repo-dir "$PWD" --branch main --quick --registration-code-stdin \
  --node-name "Example1" --region DE --public-vpn
unset AERONYX_CODE

install --quick não pede INSTALL. Use-o somente depois de revisar o plano.

Etapa 4: verificar o nó

cd /root/open/AeroNyx
systemctl is-active aeronyx-server
./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"
./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json

Um nó novo e saudável mostra:

• aeronyx-server está active, e health reporta fail=0
• o instalador imprimiu [OK] Node admission accepted com health=ok, management=fresh e discovery=ready (e public_pool=online para um nó público)
• status imprime operator_status=ok e uma próxima etapa
• a última linha JSON de health --json tem "success":true; os avisos aparecem em checks

No Nodeboard, o código aparece como completed, e o nó aparece em Nodes com nome, região, visibilidade e um heartbeat recente. A página de detalhes do nó mostra uma Capacity Decision de ready, watch, blocked ou waiting.

Para verificações do dia a dia, logs, atualizações e rollback, consulte Executar e verificar um nó AeroNyx.

Opcional: participar do relay criptografado

Um nó de VPN e um nó de relay criptografado são escolhas separadas. A participação no relay tem três partes: uma API entre pares pública e alcançável, o papel cego de armazenar e encaminhar do ChatRelay e o papel OnionMiddle, sem saída. Os dois papéis vêm desativados na configuração padrão.

1. Certifique-se de que 8422/TCP esteja alcançável pela internet.

2. Edite /etc/aeronyx/server.toml (por exemplo, nano /etc/aeronyx/server.toml) e defina estas chaves na seção [discovery], usando o seu endereço público:

   toml

   public_endpoint = "http://203.0.113.10:8422"
   public_discovery = true
   region = "DE"
   

3. Valide o arquivo:

   bash

   cd /root/open/AeroNyx
   ./target/release/aeronyx-server validate -c /etc/aeronyx/server.toml
   

4. Ative o ChatRelay sem reiniciar. O auxiliar faz backup da configuração, pede que você digite ENABLE CHATRELAY, valida e restaura o backup se a validação falhar:

   bash

   ./deploy/node/aeronyx-node.sh chat-relay --repo-dir "$PWD" --enable-chat-relay
   

5. Ative o OnionMiddle e reinicie em uma única etapa protegida. Ele pede que você digite ENABLE ONIONMIDDLE e se recusa a reiniciar se o nó tiver sessões ativas ou não conseguir informar uma contagem de sessões:

   bash

   ./deploy/node/aeronyx-node.sh onion-middle --repo-dir "$PWD" --enable-onion-middle --restart
   

   Se ele se recusar, ative o Maintenance Mode do nó em Settings no Nodeboard, espere até que as sessões ativas cheguem a zero e execute-o novamente. Não adicione --yes: ele pula a confirmação e a proteção de sessões ativas.

6. Verifique se o relay está pronto:

   bash

   ./deploy/node/aeronyx-node.sh relay-probe --repo-dir "$PWD" --two-hop --json
   

Ativar um papel não é o mesmo que ser usado em rotas. Um nó só se torna candidato a rota depois que os pares o veem como alcançável e existem evidências recentes de prova de caminho. Consulte Descoberta de nós e relay criptografado.

Participar sem o Nodeboard

join instala o nó e envia o seu descritor assinado a um nó semente para a admissão de Estágio A, sem código de registro nem conta no Nodeboard:

cd /root/open/AeroNyx
./deploy/node/aeronyx-node.sh join --repo-dir "$PWD" \
  --seed http://SEED_PUBLIC_IP:8422 \
  --public-endpoint http://YOUR_PUBLIC_IP:8422 --json

• --seed aceita de 1 a 8 nós semente públicos; a solicitação vai para o primeiro. --public-endpoint é a API entre pares alcançável do seu nó. Ambos precisam ser URLs http ou https com um endereço IP público, não um nome de host.
• Ele roda como root em Linux com systemd e precisa de Python 3.11 ou posterior, ou de python3 com o pacote tomli.
• Ele define seis valores de [discovery] (enabled, advertise_self, public_discovery, gossip_enabled, public_endpoint, seed_endpoints) e deixa o restante do arquivo intacto.
• Se o serviço já estiver em execução com configurações diferentes, ele para sem alterar nada.
• --commit <40-hex SHA> fixa o commit exato do código-fonte. --dry-run imprime o resultado planejado sem fazer alterações. --check-only verifica um nó que já participa sem enviar nada.

Um resultado bem-sucedido é "admission_stage":"stage_a_candidate" com "route_authority":false e "route_ready":false. A admissão de Estágio A significa que o nó semente aceitou o seu descritor. Ela não torna o nó roteável, não o lista no Nodeboard nem no pool da VPN e não o torna elegível para pagamento. A resposta do nó semente trafega por HTTP simples, a menos que o nó semente use HTTPS, portanto não é um comprovante criptográfico.

Implantação em TEE com Docker

O repositório também contém uma implantação em contêiner para VMs confidenciais que executam o dstack (Phala Cloud ou Intel TDX auto-hospedado): deploy/node/Dockerfile, deploy/node/compose.tee.yaml, deploy/node/server.tee.toml e deploy/node/tee-entrypoint.sh.

Esse papel não é um nó de VPN:

• vpn.enabled = false: sem dispositivo TUN, sem proxy de DNS, sem MemChain. O contêiner roda com todas as capabilities do Linux removidas e com no-new-privileges.
• Ele executa o relay onion (advertise_onion_middle = true), o ChatRelay e a caixa postal anônima, e expõe somente 8422.
• A identidade do nó vem do serviço de gerenciamento de chaves do dstack ([server_key] source = "dstack"). Não há arquivo de chave.
• Sementes fixadas. O server.tee.toml fixa quatro nós semente com discovery.pinned_seeds. Um nó sem instantâneo do operador não tem outras âncoras de confiança, e cada semente fixada só é contatada por TLS vinculado à identidade. Mantenha ou substitua as sementes fixadas; veja Descoberta de nós e relay criptografado de múltiplos saltos.

Para implantar:

1. Escolha uma imagem de release em ghcr.io/aeronyxnetwork/aeronyx-node. A CI compila imagens linux/amd64 a partir de tags node-v* e anexa uma atestação de proveniência da compilação. Encontre o digest, por exemplo com docker buildx imagetools inspect ghcr.io/aeronyxnetwork/aeronyx-node:<tag>.
2. Em compose.tee.yaml, substitua IMAGE_DIGEST por esse digest. Sempre fixe pelo digest, não pela tag; em uma VM dstack, o arquivo compose faz parte da implantação medida.
3. Defina AERONYX_PUBLIC_ENDPOINT como a origem https:// que o gateway do dstack atribui à porta 8422. O entrypoint recusa qualquer outro esquema.
4. Opcionalmente, defina AERONYX_REGION (padrão tee).
5. Somente na primeira inicialização, forneça AERONYX_REGISTRATION_CODE como um segredo criptografado. O entrypoint o envia por pipe para aeronyx-server register --code-stdin. Depois que node_info.json existir no volume /var/lib/aeronyx, o código não é mais necessário.

O contêiner não inclui aeronyx-node.sh. Monitore um nó TEE no Nodeboard e pela sua API pública de descoberta.

Instalação com um assistente de programação com IA

Assistentes de terminal como Claude Code, Codex, OpenClaw ou Hermes podem executar este procedimento. O Nodeboard oferece um AI assistant prompt pronto ao lado de cada código. Estas regras valem para qualquer assistente que você usar.

O operador humano:

• fornece o servidor e aprova toda alteração no host
• digita INSTALL pessoalmente depois de ler o plano
• mantém o código de registro em sigilo. O prompt de IA do Nodeboard contém o código, então colá-lo compartilha o código com o provedor do assistente. Para evitar isso, deixe o assistente atualizar o repositório e executar o plan, que não usa código, e depois execute quickstart você mesmo e digite o código no prompt oculto. Devolva ao assistente para a verificação.

O assistente deve:

• usar somente deploy/node/aeronyx-node.sh de github.com/AeroNyxNetwork/AeroNyx e passar --repo-dir
• usar somente opções que o script documenta (./deploy/node/aeronyx-node.sh help). Opções desconhecidas falham; por exemplo, --api-base interrompe o instalador com Unknown option.
• mostrar ou resumir o plano antes de qualquer alteração no host e esperar a aprovação
• executar status depois da instalação ou da atualização e reportar operator_status, operator_title, operator_detail e operator_next_step, e depois health --json quando for preciso mais detalhe
• reportar avisos como avisos, e não declarar sucesso apenas porque um processo está em execução
• preferir upgrade --no-restart, a menos que você aprove uma reinicialização em janela de manutenção
• nunca usar --force ou --yes, e nunca reiniciar um nó com sessões ativas, sem a sua aprovação explícita
• nunca imprimir códigos de registro, chaves privadas, segredos de API, IPs públicos de clientes, destinos, conteúdo de DNS, payloads de pacotes ou texto puro de chat

Concluído significa:

• o repositório está em main e o commit foi reportado
• o quickstart ou a instalação terminou com Node admission accepted
• status reporta operator_status=ok, ou cada aviso foi explicado
• health --json reporta "success":true
• o Nodeboard mostra o nó com um heartbeat recente e uma Capacity Decision
• Alerts / Events → Incident Closure não tem nenhum item open não revisado para o nó
• você conhece a página de detalhes do nó no Nodeboard

O que um nó registrado reporta

Os diagnósticos locais (status, health, relay-probe) imprimem apenas valores agregados: estado do serviço, capacidade, contadores de pacotes, prontidão da descoberta e resultados das provas.

Um nó de VPN registrado também reporta cada sessão de VPN ao backend da AeroNyx: ID da sessão, a chave do cliente (client_wallet), o IP virtual do túnel, contagens de bytes, tempos e qualidade do link. Ele não reporta IPs públicos de clientes, destinos, conteúdo de DNS nem payloads de pacotes. Os operadores podem ver esses registros de sessão dos seus próprios nós no Nodeboard; consulte o Guia do console do operador Nodeboard. Como qualquer servidor de VPN, o próprio nó lida com o tráfego do cliente em claro na saída, por isso os operadores precisam seguir a Política de Operadores de Nós.

Páginas relacionadas

• Executar e verificar um nó AeroNyx
• Guia do console do operador Nodeboard
• Descoberta de nós e relay criptografado
• Estatísticas da rede e fronteira de privacidade

Perguntas frequentes

De onde vem o aeronyx-node.sh?

É um arquivo do repositório do nó AeroNyx em deploy/node/aeronyx-node.sh, não um comando do sistema. Clone ou atualize https://github.com/AeroNyxNetwork/AeroNyx em /root/open/AeroNyx e execute-o a partir dali com --repo-dir "$PWD".

Como mantenho o código de registro fora do histórico do shell?

Execute quickstart sem o código e digite-o no prompt oculto Nodeboard registration code:. Em scripts, leia-o com read -rs e envie-o por pipe para install --quick --registration-code-stdin.

Por que o script procura em /opt/aeronyx/AeroNyx?

Esse é o padrão embutido do script para --repo-dir, enquanto o Nodeboard clona em /root/open/AeroNyx. Passe --repo-dir em todos os comandos para que install, health, status e upgrade usem o checkout a partir do qual o serviço roda.

O que acontece se o meu código expirar durante a instalação?

A etapa de registro falha e o instalador para antes de iniciar o serviço. O código é verificado depois da compilação, então gere um novo código e execute o quickstart novamente; a segunda execução reutiliza o cache de compilação.

Preciso do Nodeboard para executar um nó?

Não, join instala um nó e o envia para a admissão de Estágio A sem código de registro. Um nó que entra dessa forma não é roteável, não é listado no Nodeboard nem no pool da VPN e não é elegível para pagamento.

Posso executar um nó em uma VM confidencial?

Sim, o repositório inclui uma implantação Docker para VMs confidenciais dstack que executa o relay onion, o ChatRelay e a caixa postal anônima. Ela não fornece serviço de VPN e obtém a sua identidade do serviço de gerenciamento de chaves do dstack.