AeroNyx 노드 운영 및 점검

이 런북은 등록된 AeroNyx 노드의 일상적인 명령을 다룹니다: 상태, 상태 점검, 로그, 릴레이 및 메일박스 증명, 안전한 업그레이드, 롤백, 그리고 재시작 후 확인할 사항. 모든 명령은 노드 저장소(deploy/node/aeronyx-node.sh와 aeronyx-server 바이너리)에 있으며, 코드가 허용하는 옵션과 함께 제시됩니다.

아직 노드를 설치하지 않았다면 AeroNyx 노드 설치 및 등록부터 시작하십시오.

시작하기 전에

모든 작업은 root 셸(sudo -i)에서 실행하십시오. 구성 디렉터리 /etc/aeronyx와 상태 디렉터리 /var/lib/aeronyx는 모드 700이므로, status, health, 검증, 릴레이 명령은 다른 사용자로는 이를 읽을 수 없습니다.

서비스가 실제로 실행되는 저장소로 이동하고, 모든 스크립트 명령에 --repo-dir로 이를 전달하십시오. --repo-dir이 없으면 스크립트는 /opt/aeronyx/AeroNyx로 가정합니다.

cd "$(systemctl show aeronyx-server -p WorkingDirectory --value)"
pwd

Nodeboard 명령으로 설치한 노드에서는 /root/open/AeroNyx가 출력됩니다.

명령 한눈에 보기

상태

./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"

status는 다음을 순서대로 출력합니다.

1. systemctl status aeronyx-server(마지막 20줄)
2. 로컬 상태 점검 API(http://127.0.0.1:8421/api/vpn/health)와 운영자 상태 API(http://127.0.0.1:8421/api/operator/status)의 요약
3. http://127.0.0.1:8422/api/discovery/status의 로컬 디스커버리 준비 상태: ChatRelay 광고와 피어 쿼럼
4. /var/lib/aeronyx/upgrade-status.json의 마지막 업그레이드 워크플로 상태
5. 운영자 권장 사항: operator_status, operator_title, operator_detail, operator_next_step

권장 사항은 상태 점검에서 나옵니다. 상태는 다음 중 하나입니다.

상태 점검

./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json

상태 점검은 파일, systemd, 로컬 엔드포인트를 읽기만 하며 호스트를 절대 변경하지 않습니다. 각 점검은 [PASS], [WARN] 또는 [FAIL]을 출력하고, 이어서 [SUMMARY] pass=… warn=… fail=… 줄, 그다음 JSON 한 줄을 출력합니다. JSON만 출력하려면 --json-only를 사용하십시오. 점검이 하나라도 실패하면 명령은 0이 아닌 상태로 종료됩니다.

점검 항목: 저장소, 추적되는 Cargo.lock과 릴리스 바이너리, aeronyx-server validate를 사용한 구성 검증, 등록 및 키 파일, systemd 유닛, 재시작 정책과 보안 강화 설정, 메모리, 디스크, 포트 51820과 8421, IP 포워딩과 NAT, 로컬 상태 점검 엔드포인트, 디스커버리, 릴리스 백업.

주요 JSON 필드:

로컬 엔드포인트의 원시 응답을 직접 읽을 수도 있습니다.

curl -s http://127.0.0.1:8421/api/vpn/health
curl -s http://127.0.0.1:8422/api/discovery/status

로그

./deploy/node/aeronyx-node.sh logs --repo-dir "$PWD" --lines 200
./deploy/node/aeronyx-node.sh logs --repo-dir "$PWD" --follow

이 명령은 journalctl -u aeronyx-server -n <lines> --no-pager(기본 160줄)와 journalctl -u aeronyx-server -f를 감쌉니다. 시간 범위를 지정하려면 journalctl을 직접 사용하십시오. 예: journalctl -u aeronyx-server --since "1 hour ago".

릴레이 및 메일박스 증명

이 명령들은 서로 다른 질문에 답합니다. 합성 프로브를 통과했다고 해서 실제 전달의 증명으로 취급하지 마십시오.

relay-probe(합성)

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

이 노드에서 발견된 ChatRelay 피어로 무작위의 불투명한 합성 BlindRelay 봉투 하나를 보내고, 카운터 변화만 보고합니다. --two-hop은 중간 홉을 거쳐 종단 노드로 보냅니다. 결과 status는 ok, attention, blocked 또는 error이며, 2홉 경로가 불가능할 때는 two_hop_readiness가 무엇이 부족한지 설명합니다. 피어 캐시와 노드 키를 읽으므로 root가 필요합니다. 이것은 사용자 트래픽이 아니며 메일박스 전달을 증명하지 않습니다. fleet-smoke는 --endpoints로 지정한 여러 공개 노드에 대해 유사한 합성 점검을 실행합니다.

relay-smoke(인증, 종단 간)

./target/release/aeronyx-server relay-smoke --confirm-live-relay-smoke --json

relay-smoke는 이 호스트의 노드에 대해 실제 클라이언트로 동작합니다. 일회용 신원으로 수명이 짧은 세션 두 개를 열고, 이 노드의 키에 고정된 프로덕션 핸드셰이크를 완료합니다. 종단 간 암호화된 48바이트 무작위 메시지 하나를 인증된 다중 홉 릴레이 경로로 보냅니다. 그런 다음 바로 그 요청에 대한 서명된 종단 영수증을 검증하고, 이 노드의 메일박스에서 메시지를 가져와 복호화하고 확인 응답을 보낸 뒤, 메일박스가 비어 있고 세션이 닫혔는지 확인합니다.

모든 게이트를 통과하지 않으면 시작을 거부합니다.

참고:

• 노드 자체에서 root로 실행해야 합니다. /etc/aeronyx/server.toml과 노드 키를 읽으며, 루프백 주소만 허용합니다(--server, 기본값 127.0.0.1:51820; --health-url, 기본값 http://127.0.0.1:8421/api/vpn/health).
• --timeout-seconds는 증명 시간 창을 설정합니다: 5~120초, 기본값 30.
• 활성 세션 0개라는 조건은 VPN 사용자에게 서비스하는 노드라면 먼저 세션을 비워야 한다는 뜻입니다. Nodeboard에서 Maintenance Mode를 켜고 세션이 0이 될 때까지 기다리십시오.
• 두 테스트 세션은 실제 프로토콜 세션이므로 Nodeboard Sessions에 잠시 나타날 수 있습니다.
• 통과 시에는 "status": "passed"이고, terminal_receipt_observed, entry_mailbox_round_trip_verified, entry_mailbox_ack_verified, e2e_ciphertext_verified가 모두 true이며, session_cleanup은 explicit_authenticated_close입니다. terminal_replica_cleanup은 node_ttl_managed입니다. 엔트리 노드에서 확인 응답을 보내도 종단 노드가 보관한 사본은 삭제되지 않으며, 그 사본은 스스로 만료됩니다.
• 실패한 게이트, 오류, 누락된 필드는 모두 실패한 증명이며, 부분적인 성공이 아닙니다.

mailbox-probe(클라이언트 측 발신)

./target/release/aeronyx-server mailbox-probe \
  --seed http://SEED_PUBLIC_IP:8422 \
  --target <64-hex node ID of the mailbox node> \
  --entry <64-hex node ID of a different entry node> \
  --confirm-live-mailbox-probe --json

mailbox-probe는 앱처럼 동작합니다. 일회용 키를 사용하고, --seed 노드에서 수집한 서명된 디스크립터로 자체 어니언 경로를 구성하며, VPN 세션 없이 엔트리 노드의 공개 피어 API로 일반 HTTP를 보냅니다. 대상 노드에서 익명 메일박스의 전체 수명 주기를 실행합니다: ticket_issue, lease_create, put, pull_one, ack, 그리고 마지막 pull_one. 가져온 바이트가 일치하는지, 이후 메일박스가 비어 있는지 확인합니다. 통과 시 "status": "verified"와 홉 수를 보고합니다.

• --seed는 여러 번 지정할 수 있습니다. --entry가 없으면 경로는 홉 하나입니다.
• 노드 ID는 노드의 64자 16진수 공개 키입니다. 직접 운영하는 노드에서는 ./target/release/aeronyx-server pubkey -c /etc/aeronyx/server.toml이 이를 출력합니다.
• 대상 노드에서 익명 메일박스가 활성화되어 있어야 합니다([memchain.chat_relay.anonymous_mailbox] enabled = true). 기본값은 꺼짐입니다.
• --work-bits(기본값 12)는 대상의 티켓 작업량 설정 이상이어야 합니다. --timeout-seconds는 요청당 값입니다(기본값 20).
• 로컬 노드 파일을 읽지 않으므로 바이너리가 있는 어떤 머신에서도 실행할 수 있습니다. 불투명한 항목의 보관을 증명할 뿐, 수신자가 이를 복호화할 수 있음을 증명하지는 않습니다.

안전하게 업그레이드

git pull 후 systemctl restart를 실행하지 말고 업그레이드 워크플로를 사용하십시오.

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --build-priority live --build-jobs auto

수행하는 작업:

1. 배포 잠금을 획득하고, 체크아웃의 추적 파일이 수정되어 있으면 실행을 거부합니다(--allow-dirty로 무시할 수 있습니다).
2. main을 가져옵니다(또는 --commit <40-hex SHA>로 격리된 체크아웃에서 정확한 커밋을 빌드합니다).
3. 저장소에 고정된 Rust 툴체인으로 빌드합니다. live 우선순위(기본값)와 --build-jobs auto는 CPU의 약 절반을 사용하므로 실행 중인 노드가 계속 서비스할 수 있습니다.
4. 새 바이너리로 /etc/aeronyx/server.toml을 검증합니다. 구성 파일은 절대 덮어쓰지 않습니다.
5. 실제로 실행 중인 바이너리를 /var/lib/aeronyx/releases/에 백업합니다.
6. 빌드 후, 그리고 재시작 직전에 다시 한 번 활성 세션을 확인합니다. 활성 세션이 있거나, 서비스가 실행 중인데 세션 수를 읽을 수 없으면 버전을 전환하지 않고 중단합니다.
7. systemd 유닛을 업데이트하고, 새 바이너리로 교체한 뒤, 서비스를 재시작합니다.
8. 방금 빌드한 커밋에서 로컬 상태 점검이 ok를 보고할 때까지 최대 180초(2초 간격으로 90회 점검) 기다립니다. 재시작, 서비스 상태 또는 상태 점검이 실패하면 이전 바이너리와 유닛을 자동으로 복원합니다.
9. 유형별로 최근 백업 10개를 보관하고 결과를 /var/lib/aeronyx/upgrade-status.json에 기록합니다.

노드에 활성 세션이 있으면 빌드는 그대로 실행되고, 그 후 업그레이드가 Active sessions appeared during compilation. Enter maintenance mode, drain sessions, and run the upgrade again.과 함께 중단됩니다. Nodeboard Settings에서 Maintenance Mode를 켜고, 활성 세션이 0이 될 때까지 기다린 다음, 같은 명령을 다시 실행하십시오. 재빌드는 캐시를 재사용합니다.

지금 스테이징하고 나중에 재시작

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --no-restart

--no-restart는 빌드, 검증, 백업을 수행한 뒤 재시작하지 않고 새 바이너리를 디스크에 설치합니다. 그러면 status가 upgrade_staged를 보고합니다. 실행 중인 프로세스는 이전 버전을 유지합니다. 이후의 모든 재시작은, 재부팅이나 충돌 후 자동 재시작을 포함하여, 새 바이너리를 시작합니다.

유지 관리 시간대에 전환하려면 노드의 세션을 비우고 가져오기 없이 업그레이드를 다시 실행하십시오. 그러면 세션 확인, 상태 점검 대기, 롤백을 거쳐 스테이징한 바로 그 버전으로 전환됩니다.

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --skip-pull

--force를 사용하지 마십시오. 세션이 활성 상태이거나 세션 수를 알 수 없을 때도 재시작하여 사용자의 연결을 끊습니다.

수동 롤백

새 릴리스가 시작에 실패하거나 정상 상태를 보고하지 못하면 업그레이드가 자동으로 롤백됩니다. 나중에 이전 릴리스로 돌아가려면 저장된 바이너리 중 하나를 승격하십시오.

ls -lt /var/lib/aeronyx/releases/
./deploy/node/aeronyx-node.sh promote-binary --repo-dir "$PWD" \
  --binary /var/lib/aeronyx/releases/<aeronyx-server.binary.YYYYMMDD_HHMMSS.xxxxxx>

promote-binary는 선택한 바이너리로 구성을 검증하고, 활성 세션이 정확히 0이 아니면 실행을 거부합니다. PROMOTE BINARY를 입력하도록 요청하고, 현재 바이너리를 그 옆에 백업한 뒤, 바이너리를 교체하고 재시작합니다. 180초 안에 서비스가 정상 상태가 되지 않으면 이전 바이너리를 복원합니다. 바이너리만 교체하며 systemd 유닛은 교체하지 않습니다.

재시작 후

다음 항목을 순서대로 확인하십시오.

1. systemctl is-active aeronyx-server가 active를 반환합니다. 유닛은 Type=notify이므로 active는 프로세스가 준비 완료를 보고했다는 뜻입니다. systemd가 포기하기 전까지 시작에 최대 300초가 걸릴 수 있습니다.
2. ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"가 operator_status=ok 또는 이해하고 있는 경고를 표시합니다.
3. ./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json이 "success":true로 끝나고 local_vpn_health.status가 ok입니다.
4. 실행 중인 커밋이 의도한 커밋입니다: curl -s http://127.0.0.1:8421/api/vpn/health가 이를 runtime.git_commit으로 보고합니다. (health --json의 runtime.git_commit은 체크아웃의 커밋입니다.)
5. 첫 가십 라운드 후 discovery_readiness.peer_quorum.quorum_ready가 true입니다.
6. 릴레이 노드의 경우: relay-probe --two-hop --json이 ok를 보고합니다.
7. Nodeboard에서 하트비트가 최신이고, Rust Runtime에 새 버전이 표시되며, 재시작이 Alerts / Events 아래에 나타납니다. 작업이 끝나면 Maintenance Mode를 끄십시오.
8. journalctl -u aeronyx-server --since "15 min ago"에 반복되는 오류가 없습니다.

Nodeboard에서의 표시

Nodeboard는 노드의 서명된 하트비트와 세션 보고를 받습니다. Nodeboard가 스스로 호스트에서 명령을 실행하지는 않습니다. Nodeboard에서 선택한 작업은 대기열에 들어가고, 노드가 다음 하트비트 때 이를 실행합니다.

노드 상세에는 감지된 저장소 경로에 맞춘 health, status, logs 및 스테이징 업그레이드 명령을 복사할 수 있는 Operator Runbook 카드도 있습니다.

출력에 포함되는 내용

status, health, relay-probe, relay-smoke, mailbox-probe는 집계 값만 출력합니다: 개수, 상태, 시간 정보, 사유 코드. 개인 키, 등록 코드, 클라이언트 공인 IP, 목적지, DNS 내용, 페이로드, 메시지 평문은 출력하지 않습니다. 클라이언트 키가 포함된 세션 기록은 이러한 출력이 아니라 Nodeboard에서 볼 수 있습니다. Nodeboard 운영자 콘솔 가이드를 참조하십시오. 지원을 요청하며 출력을 공유할 때는 호스트 주소나 자격 증명이 아니라 JSON과 그 타임스탬프를 공유하십시오.

자주 묻는 질문

문제가 있어 보일 때 가장 먼저 어떤 명령을 실행해야 하나요?

root로 ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"를 실행하십시오. 서비스 상태, 로컬 상태 점검, 디스커버리, 권장 다음 단계를 보여 주며 호스트를 변경하지 않습니다.

health가 "config missing"이나 Git 경고와 함께 실패하는 이유는 무엇인가요?

root가 아니거나 잘못된 저장소를 가리키고 있을 가능성이 높습니다. /etc/aeronyx와 /var/lib/aeronyx는 root 전용이며, --repo-dir이 없으면 스크립트는 서비스가 실행되는 체크아웃 대신 /opt/aeronyx/AeroNyx를 점검합니다.

relay-probe와 relay-smoke의 차이는 무엇인가요?

relay-probe는 불투명한 합성 봉투 하나를 보내며, 릴레이 경로가 트래픽을 받아들인다는 것만 보여 줍니다. relay-smoke는 실제 클라이언트로 동작하여, 암호화된 테스트 메시지 하나에 대해 서명된 종단 영수증과 메일박스에서의 전체 가져오기 및 확인 응답을 검증합니다.

relay-smoke가 활성 세션이 0개여야 한다고 하는 이유는 무엇인가요?

카운터 변화를 자신의 테스트 세션에 귀속시키기 때문에 유휴 노드에서만 실행됩니다. Nodeboard에서 Maintenance Mode를 켜고, 활성 세션이 0이 될 때까지 기다린 다음 실행하십시오.

사용자 연결을 끊지 않고 업그레이드할 수 있나요?

사용자가 연결된 상태에서도 --no-restart로 업그레이드를 빌드하고 스테이징할 수 있습니다. 새 버전으로 전환하려면 재시작이 필요하므로, Maintenance Mode로 노드의 세션을 비운 다음 upgrade --skip-pull을 실행하십시오.

이전 버전으로 되돌리려면 어떻게 하나요?

실패한 업그레이드는 자동으로 롤백됩니다. 나중에 롤백하려면 /var/lib/aeronyx/releases/의 백업 중 하나로 promote-binary를 사용하십시오. 활성 세션이 0개여야 하며, 승격한 바이너리가 정상 상태가 아니면 이전 바이너리를 복원합니다.