執行與檢查 AeroNyx 節點：健康檢查、升級、復原

Q: 發現異常時，應該先執行哪個指令？

以 root 身分執行 ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"。它會顯示服務狀態、本機健康狀態、探索與建議的下一步，而且不會變更主機。

Q: 為何健康檢查會因「config missing」或 Git 警告而失敗？

您很可能不是 root，或指向了錯誤的儲存庫。/etc/aeronyx 與 /var/lib/aeronyx 僅限 root 存取，而且若未傳入 --repo-dir，指令碼會檢查 /opt/aeronyx/AeroNyx，而不是服務實際執行所在的工作目錄。

Q: relay-probe 與 relay-smoke 有什麼差別？

relay-probe 會傳送一個合成的不透明信封，只能顯示中繼路徑會接受流量。relay-smoke 則以真實用戶端的身分運作：它會針對一則加密測試訊息，驗證已簽署的終端回執，以及完整的信箱提取與確認接收。

Q: 可以在不中斷使用者連線的情況下升級嗎？

您可以在使用者連線期間，以 --no-restart 建置並暫存升級。切換到新版本需要重新啟動，因此請先以 Maintenance Mode 排空節點，再執行 upgrade --skip-pull。

Q: 如何回到先前的版本？

升級失敗時會自動復原。若之後要復原，請對 /var/lib/aeronyx/releases/ 中的其中一份備份使用 promote-binary；它要求作用中工作階段為零，且若升格的版本不健康，會還原先前的二進位檔。

本操作手冊涵蓋已註冊 AeroNyx 節點的日常指令：狀態、健康檢查、日誌、中繼與信箱證明、安全升級、復原，以及重新啟動後應檢查的項目。所有指令都位於節點儲存庫中（deploy/node/aeronyx-node.sh 與 aeronyx-server 二進位檔），並以程式碼接受的選項呈現。

如果您尚未安裝節點，請先閱讀安裝並註冊 AeroNyx 節點。

開始之前

所有操作都請在 root shell（sudo -i）中執行。設定目錄 /etc/aeronyx 與狀態目錄 /var/lib/aeronyx 的模式為 700，因此以其他使用者身分執行時，狀態、健康檢查、驗證與中繼指令都無法讀取它們。

請切換到服務實際執行所在的儲存庫，並在每個指令碼指令中以 --repo-dir 傳入。若未傳入 --repo-dir，指令碼會假設為 /opt/aeronyx/AeroNyx。

bash

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

在以 Nodeboard 指令安裝的節點上，這會列印 /root/open/AeroNyx。

指令一覽

指令	會變更主機嗎？	用途
`./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"`	否	初步查看：服務狀態、本機健康狀態、探索、升級狀態與建議的下一步
`./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json`	否	完整診斷；最後一行為 JSON
`./deploy/node/aeronyx-node.sh logs --repo-dir "$PWD" --lines 200`	否	近期服務日誌（使用 `--follow` 持續追蹤）
`./deploy/node/aeronyx-node.sh relay-probe --repo-dir "$PWD" --two-hop --json`	不變更主機；向對等節點傳送一個合成的加密信封	中繼路徑是否可用？
`./target/release/aeronyx-server relay-smoke --confirm-live-relay-smoke --json`	建立兩個短期測試工作階段	經驗證中繼投遞的端對端證明
`./target/release/aeronyx-server mailbox-probe … --confirm-live-mailbox-probe --json`	在目標節點上建立一個短期信箱	經由洋蔥路由的匿名信箱端對端證明
`./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" …`	是	建置、驗證並切換到新版本，具備復原機制

狀態

bash

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

status 會依序列印：

systemctl status aeronyx-server（最後 20 行）
本機健康 API（http://127.0.0.1:8421/api/vpn/health）與營運者狀態 API（http://127.0.0.1:8421/api/operator/status）的摘要
來自 http://127.0.0.1:8422/api/discovery/status 的本機探索就緒狀態：ChatRelay 公告與對等節點法定數量
來自 /var/lib/aeronyx/upgrade-status.json 的上一次升級流程狀態
營運者建議：operator_status、operator_title、operator_detail 與 operator_next_step

建議來自健康檢查。其狀態為下列之一：

`operator_status`	優先順序	意義
`critical`	`fix_failed_healthcheck` 或 `fix_failed_upgrade`	有檢查失敗，或上一次升級失敗
`warning`	`service_not_active`、`privacy_protocol_degraded` 或 `review_warnings`	服務已停止、本機健康狀態不是 `ok`，或有警告
`info`	`upgrade_staged`	已暫存一個建置，正在等待重新啟動
`ok`	`monitor`	沒有失敗的檢查

健康檢查

bash

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

健康檢查會讀取檔案、systemd 與本機端點；它絕不會變更主機。每項檢查會列印 [PASS]、[WARN] 或 [FAIL]，接著是一行 [SUMMARY] pass=… warn=… fail=…，然後是一行 JSON。使用 --json-only 可只列印 JSON。若有任何檢查失敗，指令會以非零狀態結束。

檢查項目：儲存庫、受追蹤的 Cargo.lock 與發行版二進位檔；以 aeronyx-server validate 進行設定驗證；註冊與金鑰檔案；systemd 單元、重新啟動政策與強化設定；記憶體、磁碟以及連接埠 51820 與 8421；IP 轉送與 NAT；本機健康端點；探索；以及版本備份。

主要 JSON 欄位：

欄位	意義
`success`	沒有檢查失敗時為 `true`
`summary`	`pass`、`warn` 與 `fail` 的計數
`operator_action`	`status` 顯示的建議（`status`、`priority`、`title`、`detail`、`next_step`）
`local_vpn_health`	`status`（健康時為 `ok`）、`active_sessions`、`placement_readiness`、`encrypted_message_forwarding`
`capacity`	節點回報的容量計數器與風險
`discovery_readiness`	ChatRelay 功能（已設定、端點就緒、執行階段就緒、已公告、阻礙因素）、`peer_quorum`（`quorum_ready`、`valid_peers`、`healthy_peers`、`routeable_chat_relays`、`routeable_onion_middle_hops`、`next_action`）、`network_story`（單跳與兩跳就緒狀態）以及 `recovery_anchor`
`runtime`	工作目錄的 Git 提交與分支、受追蹤檔案是否有修改、二進位檔與設定的時間、`service_active`、`service_enabled`、systemd 重新啟動政策、單元是否指向此二進位檔與設定、VPN 子網路、版本備份
`upgrade_status`	上一次升級的步驟、狀態與訊息
`checks`	每項檢查及其狀態與訊息

您可以直接讀取原始的本機端點：

bash

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

日誌

bash

./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（合成）

bash

./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；當無法建立兩跳路徑時，two_hop_readiness 會說明缺少什麼。它會讀取對等節點快取與節點金鑰，因此需要 root。它不是使用者流量，也不能證明信箱投遞。fleet-smoke 會對您以 --endpoints 列出的多個公開節點執行類似的合成檢查。

relay-smoke（經驗證、端對端）

bash

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

relay-smoke 會以真實用戶端的身分，對本主機上的節點進行操作。它以拋棄式身分開啟兩個短期工作階段，並完成正式環境握手，且固定使用此節點的金鑰。它會透過經驗證的多跳中繼路徑，傳送一則 48 位元組、經端對端加密的隨機訊息。接著，它會驗證該確切請求的已簽署終端回執，從此節點的信箱提取該訊息、解密、確認接收，並檢查信箱已清空、工作階段已關閉。

除非每一道關卡都通過，否則它會拒絕啟動：

關卡	失敗時的訊息
本機健康狀態為 `ok`，且沒有健康檢查失敗	`node health is not ready` / `node health has failed checks`
節點的作用中工作階段為零	`relay smoke requires zero active sessions for evidence attribution`
對等節點法定數量、路由池與兩跳洋蔥路由均已就緒	`peer quorum is not ready` / `route pool is not ready` / `two-hop onion route is not ready`
存在一條經驗證的投遞路徑，且至少有兩個支援投遞回執的對等節點	`authenticated delivery path is not ready: <reason>`，其中原因為 `no_receipt_capable_terminal`、`no_receipt_capable_middle` 或 `no_network_diverse_receipt_path`
設定中已啟用 ChatRelay，且其執行階段已就緒	`chat relay is disabled in node configuration` / `chat relay runtime is not ready`
中繼保管儲存已驗證具備完整提交持久性（SQLite `FULL` 或更強）	`encrypted custody durability is unavailable; restart the node with the current binary` / `… is not FULL-or-stronger`
執行中的二進位檔回報經驗證的洋蔥中繼健康狀態	`authenticated onion relay health is unavailable; restart the node with the current binary`

注意事項：

它必須以 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。
作用中工作階段為零，代表服務 VPN 使用者的節點必須先完成排空。請在 Nodeboard 中開啟 Maintenance Mode，並等待工作階段降為零。
兩個測試工作階段是真實的協定工作階段，因此可能會短暫出現在 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（以用戶端為來源）

bash

./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 節點收集的已簽署描述元建立自己的洋蔥路由，並以純 HTTP 傳送到入口節點的公開對等節點 API，不使用 VPN 工作階段。它會在目標節點上執行完整的匿名信箱生命週期：ticket_issue、lease_create、put、pull_one、ack，以及最後一次 pull_one。它會檢查提取的位元組是否相符，以及信箱之後是否已清空。通過時會回報 "status": "verified" 以及跳點數量。

--seed 可以重複指定。若未指定 --entry，路由只有一個跳點。
節點 ID 是節點 64 個字元的十六進位公開金鑰。在您營運的節點上，./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：

bash

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

它會執行以下操作：

取得部署鎖；若工作目錄中受追蹤的檔案有修改，則拒絕執行（--allow-dirty 可覆寫）。
拉取 main（或以 --commit <40-hex SHA> 在隔離的工作目錄中建置確切的提交）。
使用儲存庫固定版本的 Rust 工具鏈建置。live 優先順序（預設）與 --build-jobs auto 只使用約一半的 CPU，讓執行中的節點持續提供服務。
以新的二進位檔驗證 /etc/aeronyx/server.toml。設定檔絕不會被覆寫。
將實際執行中的二進位檔備份到 /var/lib/aeronyx/releases/。
在建置完成後、以及即將重新啟動之前，再次檢查作用中工作階段。若有任何作用中工作階段，或服務執行期間無法讀取工作階段數量，它會停止且不切換版本。
更新 systemd 單元、換入新的二進位檔，並重新啟動服務。
最多等待 180 秒（90 次檢查，每次間隔 2 秒），直到本機健康狀態從剛建置的提交回報 ok。若重新啟動、服務狀態或健康檢查失敗，它會自動還原先前的二進位檔與單元。
每種類型保留最近的 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，等待作用中工作階段降為零，再次執行相同指令。重新建置會重複使用快取。

現在暫存，稍後重新啟動

bash

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

--no-restart 會建置、驗證並備份，然後將新的二進位檔安裝到磁碟上而不重新啟動。之後 status 會回報 upgrade_staged。執行中的處理程序仍保留舊版本。之後任何一次重新啟動，包括重新開機或當機後的自動重新啟動，都會啟動新的二進位檔。

若要在維護時段內切換，請排空節點並在不拉取的情況下再次執行升級，讓它以工作階段檢查、健康等待與復原機制，切換到您所暫存的確切版本：

bash

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

請勿使用 --force。即使有作用中工作階段或工作階段數量未知，它也會重新啟動，並中斷使用者的連線。

手動復原

當新版本無法啟動或無法回報健康時，升級會自動復原。若之後要回到較早的版本，請升格其中一個已儲存的二進位檔：

bash

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 會以所選的二進位檔驗證設定，且除非作用中工作階段恰好為零，否則拒絕執行。它會要求您輸入 PROMOTE BINARY，將目前的二進位檔備份在其旁邊，換入二進位檔並重新啟動。若服務未在 180 秒內恢復健康，它會還原先前的二進位檔。它只替換二進位檔，不替換 systemd 單元。

任何重新啟動之後

請依序檢查以下項目：

systemctl is-active aeronyx-server 傳回 active。該單元為 Type=notify，因此 active 表示處理程序已回報就緒；在 systemd 放棄之前，啟動最多可能需要 300 秒。
./deploy/node/aeronyx-node.sh status --repo-dir "$PWD" 顯示 operator_status=ok，或是您理解的警告。
./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json 以 "success":true 結尾，且 local_vpn_health.status 為 ok。
執行中的提交是您預期的那一個：curl -s http://127.0.0.1:8421/api/vpn/health 會將其回報為 runtime.git_commit。（health --json 中的 runtime.git_commit 是工作目錄的提交。）
在最初幾輪 gossip 之後，discovery_readiness.peer_quorum.quorum_ready 為 true。
對於中繼節點：relay-probe --two-hop --json 回報 ok。
在 Nodeboard 中，心跳為最新，Rust Runtime 顯示新版本，且重新啟動事件出現在 Alerts / Events 之下。完成後請關閉 Maintenance Mode。
journalctl -u aeronyx-server --since "15 min ago" 中沒有重複出現的錯誤。

在 Nodeboard 中如何呈現

Nodeboard 會接收節點經簽署的心跳與工作階段回報。它本身不會在主機上執行指令；您在其中選擇的動作會排入佇列，由節點在下一次心跳時執行。

在節點上	在 Nodeboard 中
服務狀態與本機健康狀態	Nodes 清單與節點詳細資料：AeroNyx Health、Rust Runtime、AeroNyx Service Readiness
容量計數器	節點詳細資料：Node Capacity 與 Capacity Decision（`ready`、`watch`、`blocked`、`waiting`）
探索與中繼就緒狀態	節點詳細資料：Node Discovery、Encrypted Chat Relay；整個節點群請見 Services
`upgrade-status.json`	節點詳細資料：Rust Upgrade Workflow；Services → Fleet Restart Readiness
服務日誌中的警告	節點詳細資料：Recent Operational Events（已去敏感化，最近 24 小時）
重新啟動與復原	Alerts / Events → Incident Closure（`open`、`watch`、`recovered`）
Maintenance Mode、最大工作階段數、頻寬、等級	Settings，當 Policy Sync 顯示 `synced` 時即已確認

節點詳細資料中也有一張 Operator Runbook 卡片，針對偵測到的儲存庫路徑提供可複製的 health、status、logs 與暫存升級指令。

輸出包含什麼

status、health、relay-probe、relay-smoke 與 mailbox-probe 只會列印彙總值：計數、狀態、時間資訊與原因代碼。它們不會列印私密金鑰、註冊代碼、用戶端公開 IP、目的地、DNS 內容、酬載或訊息明文。含有用戶端金鑰的工作階段記錄可在 Nodeboard 中查看，而不在這些輸出中；請參閱 Nodeboard 營運者主控台指南。為取得支援而分享輸出時，請分享 JSON 及其時間戳記，而不是主機位址或憑證。

常見問題

發現異常時，應該先執行哪個指令？

以 root 身分執行 ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"。它會顯示服務狀態、本機健康狀態、探索與建議的下一步，而且不會變更主機。

為何健康檢查會因「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 表示需要零個作用中工作階段？

它會將計數器的變化歸因於自己的測試工作階段，因此只會在閒置的節點上執行。請在 Nodeboard 中開啟 Maintenance Mode，等待作用中工作階段降為零，然後再執行它。

可以在不中斷使用者連線的情況下升級嗎？

您可以在使用者連線期間，以 --no-restart 建置並暫存升級。切換到新版本需要重新啟動，因此請先以 Maintenance Mode 排空節點，再執行 upgrade --skip-pull。

如何回到先前的版本？

升級失敗時會自動復原。若之後要復原，請對 /var/lib/aeronyx/releases/ 中的其中一份備份使用 promote-binary；它要求作用中工作階段為零，且若升格的版本不健康，會還原先前的二進位檔。