AeroNyx 노드 설치 및 등록

이 가이드에서는 오픈소스 AeroNyx 노드 소프트웨어를 Linux 서버에 설치하고, 일회용 코드로 Nodeboard 운영자 계정에 등록한 다음, 네트워크가 노드를 승인했는지 확인합니다. 지원되는 경로는 저장소 스크립트 deploy/node/aeronyx-node.sh quickstart이며, Nodeboard가 생성해 주는 명령과 동일합니다.

• 운영자 콘솔: app.aeronyx.network
• 소스 코드(AGPL-3.0): github.com/AeroNyxNetwork/AeroNyx

노드를 운영하기 전에 노드 운영자 정책을 읽으십시오.

시작하기 전에

root가 필요한 이유: 저장소는 /root/open/AeroNyx에 있고, 설치 프로그램은 /etc/aeronyx와 /var/lib/aeronyx를 모드 700으로, server.toml을 모드 600으로 기록합니다. 이 경로를 읽는 명령은 다른 사용자로 실행하면 실패하며, Git은 다른 계정에서 root 소유 체크아웃을 읽는 것을 거부합니다("dubious ownership").

quickstart가 하는 일

quickstart는 네 단계를 실행하며, 사용자가 승인하기 전에는 호스트를 변경하기 전에 멈춥니다.

1. 확정된 설치 계획을 출력합니다(읽기 전용).
2. 사용자가 INSTALL을 입력할 때까지 기다립니다. Enter를 누르면 안전하게 중단됩니다.
3. 사전 점검을 실행하고, 패키지와 저장소에 고정된 Rust 툴체인을 설치하고, /etc/aeronyx/server.toml이 없으면 기록하고(기존 파일은 유지됩니다), IP 포워딩과 NAT를 설정하고, 노드를 빌드하고, aeronyx-server systemd 유닛을 설치하고, 코드로 노드 신원을 등록하고, 서비스를 시작한 다음, 네트워크 승인을 최대 120초 동안 기다립니다.
4. status와 health --json 요약을 출력합니다.

승인 대기 단계에서는 로컬 상태 확인이 ok를 보고하는지, 백엔드가 새 정책을 반환했는지(하트비트 왕복이 동작하는지), 디스커버리에 검증된 서명 피어가 하나 이상 있고 가십 라운드를 한 번 이상 완료했는지, 그리고 공개 노드의 경우 노드가 공개 풀에 등재되었는지를 확인합니다.

1단계: 등록 코드 생성

1. Nodeboard에 로그인하고 Registration Codes를 엽니다.
2. Generate Code를 선택합니다.
3. 코드를 비공개로 유지하십시오. 코드는 15분 후에 만료되고, 한 번만 사용할 수 있으며, 새 노드를 코드를 생성한 계정에 연결합니다.

그러면 Nodeboard에 quickstart 명령, 단계별 미리 보기 및 설치 명령, 상태 명령, AI 어시스턴트 프롬프트가 표시됩니다. Install Progress 열은 설치 프로그램의 진행을 not_started → planning → running → completed | failed 순서로 추적합니다.

백엔드는 설치 프로그램이 등록 단계에 도달했을 때 코드를 확인하며, 이 단계는 빌드 이후에 옵니다. 작은 서버에서 첫 빌드는 15분보다 오래 걸릴 수 있습니다. 그 결과 코드 만료로 등록이 실패하면 새 코드를 생성하고 quickstart를 다시 실행하십시오. 두 번째 실행은 빌드 캐시를 재사용합니다.

2단계: 저장소 받기 또는 업데이트

aeronyx-node.sh는 시스템 명령이 아닙니다. 저장소에 포함되어 배포됩니다. 다음은 Nodeboard가 사용하는 클론 또는 업데이트 명령줄입니다.

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

스크립트에는 항상 --repo-dir "$PWD"(또는 --repo-dir /root/open/AeroNyx)를 전달하십시오. 이 옵션이 없으면 install, upgrade, health, status는 기본값으로 /opt/aeronyx/AeroNyx를 사용합니다.

3단계: quickstart 실행

명령줄에 코드를 넣지 않고 quickstart를 실행하십시오. 터미널에서 실행하면 숨김 프롬프트로 코드를 요청하므로, 코드가 화면에 표시되지 않고, 셸 기록에 저장되지 않으며, 프로세스 인수로 전달되지 않습니다.

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은 Nodeboard와 VPN 노드 목록에 표시되는 이름입니다.
• --region은 ISO 3166-1 alpha-2 국가 코드입니다.
• --public-vpn은 노드를 공개 VPN 풀에 게시합니다. 노드를 비공개로 유지하려면 생략하십시오.

Nodeboard registration code:에서 코드를 붙여 넣고 Enter를 누릅니다. 계획을 검토한 다음 INSTALL을 입력합니다.

Nodeboard가 생성하는 명령에 대하여

Nodeboard의 quickstart 명령은 코드를 명령에 직접 넣습니다. 예: AERONYX_REGISTRATION_CODE='<code>' ./deploy/node/aeronyx-node.sh quickstart --repo-dir "$PWD" --branch main --quick. 이 방식도 동작하지만 코드가 셸 기록에 저장됩니다. 이 명령을 사용한다면 다음을 따르십시오.

• echo "$HISTCONTROL"을 확인하십시오. ignorespace 또는 ignoreboth가 포함되어 있으면 명령을 공백으로 시작하십시오. 그러면 Bash가 기록하지 않습니다.
• 그렇지 않으면 실행 후 history -d <number>로 해당 항목을 삭제하십시오.

코드는 일회용이고 15분 후에 만료되므로 노출 범위가 제한되지만, 티켓, 스크린샷, 채팅에 붙여 넣지 마십시오.

비대화형 설치

자동화할 때는 먼저 미리 본 다음, 코드를 표준 입력으로 전달하십시오. read -rs는 코드를 화면과 기록에 남기지 않습니다.

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은 INSTALL 입력을 요청하지 않습니다. 계획을 검토한 후에만 사용하십시오.

4단계: 노드 확인

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

정상적인 새 노드는 다음과 같이 표시됩니다.

• aeronyx-server가 active이고, health가 fail=0을 보고합니다
• 설치 프로그램이 health=ok, management=fresh, discovery=ready(공개 노드의 경우 public_pool=online도)와 함께 [OK] Node admission accepted를 출력했습니다
• status가 operator_status=ok와 다음 단계를 출력합니다
• health --json의 마지막 JSON 줄에 "success":true가 있습니다. 경고는 checks 아래에 표시됩니다

Nodeboard에서는 코드가 completed로 표시되고, 노드가 이름, 지역, 공개 여부, 최신 하트비트와 함께 Nodes 아래에 나타납니다. 노드 상세 페이지에는 ready, watch, blocked 또는 waiting 중 하나의 Capacity Decision이 표시됩니다.

일상적인 점검, 로그, 업그레이드, 롤백은 AeroNyx 노드 운영 및 점검을 참조하십시오.

선택 사항: 암호화 릴레이 참여

VPN 노드와 암호화 릴레이 노드는 별개의 선택입니다. 릴레이 참여는 세 부분으로 구성됩니다. 접근 가능한 공개 피어 API, 블라인드 ChatRelay 저장 후 전달 역할, 그리고 출구가 없는 OnionMiddle 역할입니다. 두 역할 모두 기본 구성에서는 꺼져 있습니다.

1. 인터넷에서 8422/TCP에 접근할 수 있는지 확인하십시오.

2. /etc/aeronyx/server.toml을 편집하고(예: nano /etc/aeronyx/server.toml) 공개 주소를 사용하여 [discovery] 섹션에 다음 키를 설정합니다.

   toml

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

3. 파일을 검증합니다.

   bash

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

4. 재시작 없이 ChatRelay를 활성화합니다. 이 도우미는 구성을 백업하고, ENABLE CHATRELAY를 입력하도록 요청하고, 검증한 다음, 검증에 실패하면 백업을 복원합니다.

   bash

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

5. 보호 장치가 있는 한 단계로 OnionMiddle을 활성화하고 재시작합니다. ENABLE ONIONMIDDLE을 입력하도록 요청하며, 노드에 활성 세션이 있거나 세션 수를 보고할 수 없으면 재시작을 거부합니다.

   bash

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

   거부되면 Nodeboard Settings에서 해당 노드의 Maintenance Mode를 켜고, 활성 세션이 0이 될 때까지 기다린 다음 다시 실행하십시오. --yes를 추가하지 마십시오. 이 옵션은 확인 단계와 활성 세션 보호 장치를 건너뜁니다.

6. 릴레이 준비 상태를 확인합니다.

   bash

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

역할을 활성화하는 것은 경로에 사용되는 것과 같지 않습니다. 노드는 피어가 해당 노드를 접근 가능한 것으로 확인하고 최신 경로 증명 증거가 존재한 후에야 경로 후보가 됩니다. 노드 디스커버리와 암호화 릴레이를 참조하십시오.

Nodeboard 없이 참여

join은 등록 코드나 Nodeboard 계정 없이 노드를 설치하고, Stage-A 승인을 위해 노드의 서명된 디스크립터를 시드 노드에 제출합니다.

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는 1~8개의 공개 시드 노드를 받으며, 요청은 첫 번째 노드로 전송됩니다. --public-endpoint는 노드의 접근 가능한 피어 API입니다. 둘 다 호스트 이름이 아닌 공개 IP 주소를 사용하는 http 또는 https URL이어야 합니다.
• systemd를 사용하는 Linux에서 root로 실행되며, Python 3.11 이상 또는 tomli 패키지가 설치된 python3이 필요합니다.
• 여섯 개의 [discovery] 값(enabled, advertise_self, public_discovery, gossip_enabled, public_endpoint, seed_endpoints)을 설정하고 파일의 나머지 부분은 건드리지 않습니다.
• 서비스가 이미 다른 설정으로 실행 중이면 아무것도 변경하지 않고 중단합니다.
• --commit <40-hex SHA>는 정확한 소스 커밋을 고정합니다. --dry-run은 변경 없이 계획된 결과를 출력합니다. --check-only는 아무것도 전송하지 않고 이미 참여한 노드를 확인합니다.

성공 결과는 "route_authority":false 및 "route_ready":false와 함께 "admission_stage":"stage_a_candidate"입니다. Stage-A 승인은 시드가 디스크립터를 수락했다는 의미입니다. 이것으로 노드가 라우팅 가능해지거나, Nodeboard 또는 VPN 풀에 등재되거나, 지급 대상이 되지는 않습니다. 시드가 HTTPS를 사용하지 않는 한 시드의 응답은 일반 HTTP로 전달되므로, 암호학적 영수증이 아닙니다.

Docker를 사용한 TEE 배포

저장소에는 dstack을 실행하는 기밀 VM(Phala Cloud 또는 자체 호스팅 Intel TDX)용 컨테이너 배포도 포함되어 있습니다: deploy/node/Dockerfile, deploy/node/compose.tee.yaml, deploy/node/server.tee.toml, deploy/node/tee-entrypoint.sh.

이 역할은 VPN 노드가 아닙니다.

• vpn.enabled = false: TUN 장치, DNS 프록시, MemChain이 없습니다. 컨테이너는 모든 Linux capability를 제거하고 no-new-privileges로 실행됩니다.
• 어니언 릴레이(advertise_onion_middle = true), ChatRelay, 익명 메일박스를 실행하며 8422만 노출합니다.
• 노드 신원은 dstack 키 관리 서비스([server_key] source = "dstack")에서 가져옵니다. 키 파일은 없습니다.
• 고정 시드. server.tee.toml은 discovery.pinned_seeds로 시드 노드 네 개를 고정합니다. 운영자 스냅샷이 없는 노드에는 다른 신뢰 기점이 없으며, 각 고정 항목은 신원에 묶인 TLS로만 접속합니다. 고정 항목을 유지하거나 교체하세요. 자세한 내용은 노드 탐색과 암호화된 멀티홉 릴레이를 참고하세요.

배포 방법:

1. ghcr.io/aeronyxnetwork/aeronyx-node에서 릴리스 이미지를 선택합니다. CI는 node-v* 태그로부터 linux/amd64 이미지를 빌드하고 빌드 출처 증명(build-provenance attestation)을 첨부합니다. 예를 들어 docker buildx imagetools inspect ghcr.io/aeronyxnetwork/aeronyx-node:<tag>로 다이제스트를 확인합니다.
2. compose.tee.yaml에서 IMAGE_DIGEST를 해당 다이제스트로 바꿉니다. 항상 태그가 아니라 다이제스트로 고정하십시오. dstack VM에서는 compose 파일이 측정되는 배포의 일부입니다.
3. AERONYX_PUBLIC_ENDPOINT를 dstack 게이트웨이가 포트 8422에 할당한 https:// 오리진으로 설정합니다. 엔트리포인트는 다른 스킴을 거부합니다.
4. 필요하면 AERONYX_REGION(기본값 tee)을 설정합니다.
5. 첫 시작에 한해 AERONYX_REGISTRATION_CODE를 암호화된 시크릿으로 제공합니다. 엔트리포인트는 이를 aeronyx-server register --code-stdin으로 파이프합니다. /var/lib/aeronyx 볼륨에 node_info.json이 생기면 더 이상 코드가 필요하지 않습니다.

컨테이너에는 aeronyx-node.sh가 포함되어 있지 않습니다. TEE 노드는 Nodeboard와 노드의 공개 디스커버리 API를 통해 모니터링하십시오.

AI 코딩 어시스턴트로 설치

Claude Code, Codex, OpenClaw, Hermes 같은 터미널 어시스턴트가 이 절차를 실행할 수 있습니다. Nodeboard는 각 코드 옆에 바로 사용할 수 있는 AI assistant prompt를 제공합니다. 어떤 어시스턴트를 사용하든 다음 규칙이 적용됩니다.

사람 운영자는:

• 서버를 제공하고 모든 호스트 변경을 승인합니다
• 계획을 읽은 후 INSTALL을 직접 입력합니다
• 등록 코드를 비공개로 유지합니다. Nodeboard의 AI 프롬프트에는 코드가 포함되어 있으므로, 이를 붙여 넣으면 어시스턴트 제공업체와 코드를 공유하게 됩니다. 이를 피하려면 어시스턴트가 저장소를 업데이트하고 코드가 필요 없는 plan을 실행하게 한 다음, quickstart를 직접 실행하여 숨김 프롬프트에 코드를 입력하십시오. 확인 작업은 다시 어시스턴트에게 넘깁니다.

어시스턴트는 반드시:

• github.com/AeroNyxNetwork/AeroNyx의 deploy/node/aeronyx-node.sh만 사용하고 --repo-dir을 전달해야 합니다
• 스크립트가 문서화한 옵션(./deploy/node/aeronyx-node.sh help)만 사용해야 합니다. 알 수 없는 옵션은 실패합니다. 예를 들어 --api-base를 사용하면 설치 프로그램이 Unknown option과 함께 중단됩니다.
• 호스트를 변경하기 전에 계획을 보여 주거나 요약하고 승인을 기다려야 합니다
• 설치 또는 업그레이드 후 status를 실행하여 operator_status, operator_title, operator_detail, operator_next_step을 보고하고, 더 자세한 정보가 필요하면 health --json을 실행해야 합니다
• 경고는 경고로 보고해야 하며, 프로세스가 실행 중이라는 사실만으로 성공을 선언해서는 안 됩니다
• 사용자가 유지 관리 시간대의 재시작을 승인하지 않는 한 upgrade --no-restart를 우선 사용해야 합니다
• 사용자의 명시적 승인 없이 --force 또는 --yes를 사용하거나 활성 세션이 있는 노드를 재시작해서는 안 됩니다
• 등록 코드, 개인 키, API 시크릿, 클라이언트 공인 IP, 목적지, DNS 내용, 패킷 페이로드, 채팅 평문을 절대 출력해서는 안 됩니다

완료의 기준:

• 저장소가 main에 있고 커밋이 보고되었습니다
• quickstart 또는 install이 Node admission accepted로 완료되었습니다
• status가 operator_status=ok를 보고하거나, 각 경고에 대한 설명이 있습니다
• health --json이 "success":true를 보고합니다
• Nodeboard에 최신 하트비트와 Capacity Decision이 있는 노드가 표시됩니다
• Alerts / Events → Incident Closure에 해당 노드의 검토되지 않은 open 항목이 없습니다
• Nodeboard에서 노드의 상세 페이지를 알고 있습니다

등록된 노드가 보고하는 내용

로컬 진단(status, health, relay-probe)은 집계 값만 출력합니다: 서비스 상태, 용량, 패킷 카운터, 디스커버리 준비 상태, 증명 결과.

등록된 VPN 노드는 각 VPN 세션도 AeroNyx 백엔드에 보고합니다: 세션 ID, 클라이언트의 키(client_wallet), 터널의 가상 IP, 바이트 수, 시간 정보, 링크 품질. 클라이언트 공인 IP, 목적지, DNS 내용, 패킷 페이로드는 보고하지 않습니다. 운영자는 Nodeboard에서 자신의 노드에 대한 이러한 세션 기록을 볼 수 있습니다. Nodeboard 운영자 콘솔 가이드를 참조하십시오. 다른 모든 VPN 서버와 마찬가지로 노드 자체는 출구에서 클라이언트 트래픽을 평문으로 처리하므로, 운영자는 노드 운영자 정책을 따라야 합니다.

관련 페이지

• AeroNyx 노드 운영 및 점검
• Nodeboard 운영자 콘솔 가이드
• 노드 디스커버리와 암호화 릴레이
• 네트워크 통계와 프라이버시 경계

자주 묻는 질문

aeronyx-node.sh는 어디에서 오나요?

시스템 명령이 아니라 AeroNyx 노드 저장소의 deploy/node/aeronyx-node.sh에 있는 파일입니다. https://github.com/AeroNyxNetwork/AeroNyx를 /root/open/AeroNyx에 클론하거나 업데이트하고, 그곳에서 --repo-dir "$PWD"와 함께 실행하십시오.

등록 코드가 셸 기록에 남지 않게 하려면 어떻게 하나요?

코드 없이 quickstart를 실행하고 숨김 Nodeboard registration code: 프롬프트에 코드를 입력하십시오. 스크립트에서는 read -rs로 읽어 install --quick --registration-code-stdin으로 파이프하십시오.

스크립트가 /opt/aeronyx/AeroNyx를 찾는 이유는 무엇인가요?

그것은 스크립트에 내장된 --repo-dir의 기본값이며, Nodeboard는 /root/open/AeroNyx에 클론합니다. install, health, status, upgrade가 모두 서비스가 실행되는 체크아웃을 사용하도록 모든 명령에 --repo-dir을 전달하십시오.

설치 중에 코드가 만료되면 어떻게 되나요?

등록 단계가 실패하고 설치 프로그램은 서비스를 시작하기 전에 중단됩니다. 코드는 빌드 이후에 확인되므로, 새 코드를 생성하고 quickstart를 다시 실행하십시오. 두 번째 실행은 빌드 캐시를 재사용합니다.

노드를 운영하려면 Nodeboard가 필요한가요?

아니요. join은 등록 코드 없이 노드를 설치하고 Stage-A 승인을 위해 제출합니다. join으로 참여한 노드는 라우팅 가능하지 않고, Nodeboard나 VPN 풀에 등재되지 않으며, 지급 대상이 아닙니다.

기밀 VM에서 노드를 실행할 수 있나요?

예. 저장소에는 어니언 릴레이, ChatRelay, 익명 메일박스를 실행하는 dstack 기밀 VM용 Docker 배포가 포함되어 있습니다. 이 배포는 VPN 서비스를 제공하지 않으며, 신원은 dstack 키 관리 서비스에서 가져옵니다.