feat(proxy): 支持远程推送升级与proxy元数据上报

- aether-proxy 注册和心跳时上报 proxy_metadata（含版本号）
- 心跳 ACK 支持 upgrade_to 字段，proxy 收到后自动执行升级
- 重构 upgrade 逻辑，新增 perform_upgrade 用于远程触发的自动升级
- stream_handler 延迟统计改为仅记录连接建立延迟(DNS+TCP/TLS+TTFB)
- 后端新增 proxy_metadata 数据库字段和批量升级 API
- 远程配置支持下发 upgrade_to 版本指令
- 前端展示节点版本号，支持单节点和批量升级操作

aether-proxy/src/registration/client.rs

@@ -20,6 +20,8 @@ struct RegisterRequest {
     hardware_info: Option<serde_json::Value>,
     #[serde(skip_serializing_if = "Option::is_none")]
     estimated_max_concurrency: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    proxy_metadata: Option<serde_json::Value>,
     tunnel_mode: bool,
 }
 
@@ -107,6 +109,9 @@ impl AetherClient {
             heartbeat_interval: config.heartbeat_interval,
             hardware_info: hw.and_then(|h| serde_json::to_value(h).ok()),
             estimated_max_concurrency: hw.map(|h| h.estimated_max_concurrency),
+            proxy_metadata: Some(serde_json::json!({
+                "version": env!("CARGO_PKG_VERSION"),
+            })),
             tunnel_mode: true,
         };
 

aether-proxy/src/setup/upgrade.rs

@@ -281,8 +281,17 @@ fn atomic_replace(new_binary: &Path) -> anyhow::Result<PathBuf> {
 
 // ── Public entry point ───────────────────────────────────────────────────────
 
-/// `aether-proxy upgrade [version]` -- self-upgrade from GitHub releases.
-pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
+#[derive(Clone, Copy)]
+enum RestartMode {
+    BestEffort,
+    Required,
+}
+
+async fn execute_upgrade(
+    version: Option<&str>,
+    require_root: bool,
+    restart_mode: RestartMode,
+) -> anyhow::Result<()> {
     // Resolve exe path once; reuse throughout the function
     let current_exe = std::env::current_exe()?.canonicalize()?;
     let exe_dir = current_exe
@@ -290,8 +299,12 @@ pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
         .ok_or_else(|| anyhow::anyhow!("cannot determine binary directory"))?;
     let temp_path = exe_dir.join(".aether-proxy.upgrade.tmp");
 
-    // Check write permission to binary directory
+    if require_root {
         if !super::service::is_root() {
+            anyhow::bail!("automatic upgrade requires root privileges");
+        }
+    } else if !super::service::is_root() {
+        // Check write permission to binary directory for manual upgrade mode.
         let test_path = exe_dir.join(".aether-proxy.write-test");
         match std::fs::File::create(&test_path) {
             Ok(_) => {
@@ -311,7 +324,7 @@ pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
     eprintln!("  Current version: {}", CURRENT_VERSION);
 
     let client = build_github_client()?;
-    let release = fetch_release(&client, version.as_deref()).await?;
+    let release = fetch_release(&client, version).await?;
     let target_tag = &release.tag_name;
     let target_semver = target_tag.strip_prefix("proxy-v").unwrap_or(target_tag);
 
@@ -341,6 +354,8 @@ pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
         }
     };
 
+    match restart_mode {
+        RestartMode::BestEffort => {
             // Restart systemd service if running.
             // Use best-effort: binary is already replaced, so a restart failure should
             // not abort the whole upgrade -- the user can restart manually.
@@ -362,6 +377,16 @@ pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
             } else {
                 eprintln!("  No active systemd service detected, skipping restart.");
             }
+        }
+        RestartMode::Required => {
+            if !super::service::is_root() {
+                anyhow::bail!("automatic upgrade requires root privileges");
+            }
+            eprintln!("  Restarting systemd service...");
+            super::service::run_cmd("systemctl", &["restart", "aether-proxy"])?;
+            eprintln!("  Service restarted.");
+        }
+    }
 
     eprintln!();
     eprintln!("  Upgrade complete!");
@@ -371,3 +396,16 @@ pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
     );
     Ok(())
 }
+
+/// `aether-proxy upgrade [version]` -- self-upgrade from GitHub releases.
+pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
+    execute_upgrade(version.as_deref(), false, RestartMode::BestEffort).await
+}
+
+/// Perform automatic upgrade to a specific version.
+///
+/// This path is designed for server-pushed upgrades in systemd/root scenarios:
+/// it requires root and requires a successful `systemctl restart aether-proxy`.
+pub async fn perform_upgrade(version: &str) -> anyhow::Result<()> {
+    execute_upgrade(Some(version), true, RestartMode::Required).await
+}

aether-proxy/src/state.rs

@@ -47,6 +47,8 @@ pub struct ServerContext {
 /// Aggregate metrics for reporting to Aether.
 pub struct ProxyMetrics {
     pub total_requests: AtomicU64,
+    /// Cumulative connection-establishment latency in nanoseconds
+    /// (DNS + TCP/TLS + TTFB, excludes response body streaming).
     pub total_latency_ns: AtomicU64,
     pub failed_requests: AtomicU64,
     pub dns_failures: AtomicU64,
@@ -64,8 +66,10 @@ impl ProxyMetrics {
         }
     }
 
-    pub fn record_request(&self, elapsed: Duration) {
-        let nanos = u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX);
+    /// Record a completed request with its connection-establishment latency
+    /// (DNS + TCP/TLS + TTFB, excludes response body streaming).
+    pub fn record_request(&self, connect_elapsed: Duration) {
+        let nanos = u64::try_from(connect_elapsed.as_nanos()).unwrap_or(u64::MAX);
         self.total_requests.fetch_add(1, Ordering::Release);
         self.total_latency_ns.fetch_add(nanos, Ordering::Release);
     }

aether-proxy/src/tunnel/heartbeat.rs

@@ -1,6 +1,6 @@
 //! Tunnel heartbeat: sends metrics over the tunnel, processes ACKs.
 
-use std::sync::atomic::Ordering;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
 use std::time::SystemTime;
@@ -8,7 +8,7 @@ use std::time::UNIX_EPOCH;
 
 use bytes::Bytes;
 use tokio::sync::watch;
-use tracing::{debug, warn};
+use tracing::{debug, info, warn};
 
 use crate::config::Config;
 use crate::registration::client::RemoteConfig;
@@ -18,8 +18,15 @@ use crate::state::ServerContext;
 use super::protocol::{Frame, MsgType};
 use super::writer::FrameSender;
 
+const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
+static UPGRADE_IN_PROGRESS: AtomicBool = AtomicBool::new(false);
+static NON_ROOT_UPGRADE_WARNED: AtomicBool = AtomicBool::new(false);
+
 enum AckDecision {
-    Accept(Option<u64>),
+    Accept {
+        heartbeat_id: Option<u64>,
+        upgrade_to: Option<String>,
+    },
     Ignore,
 }
 
@@ -130,7 +137,10 @@ pub fn spawn(
                 }
                 Some(ack_payload) = ack_rx.recv() => {
                     match handle_ack(&server, &ack_payload) {
-                        AckDecision::Accept(ack_id) => {
+                        AckDecision::Accept {
+                            heartbeat_id: ack_id,
+                            upgrade_to,
+                        } => {
                             if let Some((pending_id, _)) = pending {
                                 match ack_id {
                                     Some(id) if id == pending_id => {
@@ -144,6 +154,7 @@ pub fn spawn(
                                     _ => {}
                                 }
                             }
+                            maybe_trigger_upgrade(upgrade_to);
                         }
                         AckDecision::Ignore => {}
                     }
@@ -229,6 +240,9 @@ fn build_heartbeat_payload(
         "failed_requests": snapshot.failed,
         "dns_failures": snapshot.dns_failures,
         "stream_errors": snapshot.stream_errors,
+        "proxy_metadata": {
+            "version": CURRENT_VERSION,
+        },
     });
 
     Bytes::from(serde_json::to_vec(&payload).unwrap_or_default())
@@ -236,7 +250,10 @@ fn build_heartbeat_payload(
 
 fn handle_ack(server: &ServerContext, payload: &[u8]) -> AckDecision {
     if payload.is_empty() {
-        return AckDecision::Accept(None);
+        return AckDecision::Accept {
+            heartbeat_id: None,
+            upgrade_to: None,
+        };
     }
 
     #[derive(serde::Deserialize)]
@@ -247,6 +264,8 @@ fn handle_ack(server: &ServerContext, payload: &[u8]) -> AckDecision {
         config_version: u64,
         #[serde(default)]
         heartbeat_id: Option<u64>,
+        #[serde(default)]
+        upgrade_to: Option<String>,
     }
 
     match serde_json::from_slice::<AckPayload>(payload) {
@@ -254,7 +273,10 @@ fn handle_ack(server: &ServerContext, payload: &[u8]) -> AckDecision {
             if let Some(ref rc) = ack.remote_config {
                 runtime::apply_remote_config(&server.dynamic, rc, ack.config_version);
             }
-            AckDecision::Accept(ack.heartbeat_id)
+            AckDecision::Accept {
+                heartbeat_id: ack.heartbeat_id,
+                upgrade_to: ack.upgrade_to.and_then(normalize_upgrade_target),
+            }
         }
         Err(e) => {
             warn!(error = %e, "failed to parse heartbeat ACK");
@@ -262,3 +284,57 @@ fn handle_ack(server: &ServerContext, payload: &[u8]) -> AckDecision {
         }
     }
 }
+
+fn normalize_upgrade_target(raw: String) -> Option<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let normalized = trimmed.strip_prefix("proxy-v").unwrap_or(trimmed);
+    if normalized == CURRENT_VERSION {
+        return None;
+    }
+    Some(normalized.to_string())
+}
+
+fn maybe_trigger_upgrade(version: Option<String>) {
+    let Some(target_version) = version else {
+        return;
+    };
+    if !crate::setup::service::is_root() {
+        if NON_ROOT_UPGRADE_WARNED
+            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+            .is_ok()
+        {
+            warn!(
+                target_version = %target_version,
+                "remote upgrade skipped: root privileges are required"
+            );
+        }
+        return;
+    }
+    if UPGRADE_IN_PROGRESS
+        .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+        .is_err()
+    {
+        debug!(target_version = %target_version, "upgrade already in progress, ignoring");
+        return;
+    }
+
+    tokio::spawn(async move {
+        info!(target_version = %target_version, "received remote upgrade instruction");
+        match crate::setup::upgrade::perform_upgrade(&target_version).await {
+            Ok(()) => {
+                info!(target_version = %target_version, "remote upgrade finished");
+            }
+            Err(e) => {
+                warn!(
+                    target_version = %target_version,
+                    error = %e,
+                    "remote upgrade failed"
+                );
+                UPGRADE_IN_PROGRESS.store(false, Ordering::Release);
+            }
+        }
+    });
+}

aether-proxy/src/tunnel/stream_handler.rs

@@ -55,13 +55,15 @@ pub async fn handle_stream(
     mut body_rx: mpsc::Receiver<Frame>,
     frame_tx: FrameSender,
 ) {
-    let start = Instant::now();
     server.active_connections.fetch_add(1, Ordering::Release);
 
+    let connect_elapsed =
         handle_stream_inner(&state, &server, stream_id, meta, &mut body_rx, &frame_tx).await;
 
     server.active_connections.fetch_sub(1, Ordering::Release);
-    server.metrics.record_request(start.elapsed());
+    if let Some(d) = connect_elapsed {
+        server.metrics.record_request(d);
+    }
 }
 
 /// Send a frame to the writer with a timeout. Returns false if send failed.
@@ -80,6 +82,9 @@ async fn send_frame(tx: &FrameSender, frame: Frame) -> bool {
     }
 }
 
+/// Returns the connection-establishment duration (DNS + TCP/TLS + TTFB) if the
+/// upstream request succeeded, or `None` if the request never reached the
+/// response-headers stage.
 async fn handle_stream_inner(
     state: &AppState,
     server: &ServerContext,
@@ -87,7 +92,7 @@ async fn handle_stream_inner(
     meta: RequestMeta,
     body_rx: &mut mpsc::Receiver<Frame>,
     frame_tx: &FrameSender,
-) {
+) -> Option<Duration> {
     // Collect request body
     let mut body_parts: Vec<Bytes> = Vec::new();
     let mut body_done = false;
@@ -106,7 +111,7 @@ async fn handle_stream_inner(
                                 &format!("gzip decompress failed: {e}"),
                             )
                             .await;
-                            return;
+                            return None;
                         }
                     };
                     if !payload.is_empty() {
@@ -120,11 +125,11 @@ async fn handle_stream_inner(
                 {
                     body_done = true;
                     if frame.msg_type == MsgType::StreamError {
-                        return; // Client cancelled
+                        return None; // Client cancelled
                     }
                 }
             }
-            None => return, // Channel closed
+            None => return None, // Channel closed
         }
     }
 
@@ -146,7 +151,7 @@ async fn handle_stream_inner(
         Ok(u) => u,
         Err(e) => {
             send_error(frame_tx, stream_id, &format!("invalid URL: {e}")).await;
-            return;
+            return None;
         }
     };
 
@@ -160,7 +165,7 @@ async fn handle_stream_inner(
                 &format!("unsupported URL scheme: {other}"),
             )
             .await;
-            return;
+            return None;
         }
     }
 
@@ -168,13 +173,13 @@ async fn handle_stream_inner(
         Some(h) => h.to_string(),
         None => {
             send_error(frame_tx, stream_id, "missing host in URL").await;
-            return;
+            return None;
         }
     };
     let port = target_url.port_or_known_default().unwrap_or(443);
 
     // DNS + target validation (populates dns_cache for SafeDnsResolver)
-    let dns_start = Instant::now();
+    let connect_start = Instant::now();
     {
         let allowed_ports = Arc::clone(&server.dynamic.load().allowed_ports);
         if let Err(e) =
@@ -182,10 +187,10 @@ async fn handle_stream_inner(
         {
             server.metrics.dns_failures.fetch_add(1, Ordering::Release);
             send_error(frame_tx, stream_id, &format!("target blocked: {e}")).await;
-            return;
+            return None;
         }
     }
-    let dns_ms = dns_start.elapsed().as_millis() as u64;
+    let dns_ms = connect_start.elapsed().as_millis() as u64;
 
     // Execute upstream request
     let client = &state.reqwest_client;
@@ -231,10 +236,14 @@ async fn handle_stream_inner(
                 format!("upstream error: {e}")
             };
             send_error(frame_tx, stream_id, &msg).await;
-            return;
+            return None;
         }
     };
 
+    // Capture connection-establishment duration (DNS + TCP/TLS + TTFB)
+    // before proceeding to stream the response body.
+    let connect_elapsed = connect_start.elapsed();
+
     // Send RESPONSE_HEADERS
     let status = response.status().as_u16();
     let ttfb_ms = upstream_start.elapsed().as_millis() as u64;
@@ -271,7 +280,7 @@ async fn handle_stream_inner(
     )
     .await
     {
-        return;
+        return Some(connect_elapsed);
     }
 
     // Stream response body — relay upstream bytes through the tunnel.
@@ -291,7 +300,7 @@ async fn handle_stream_inner(
                     )
                     .await
                     {
-                        return;
+                        return Some(connect_elapsed);
                     }
                 } else {
                     // Split oversized chunks, compress each slice
@@ -306,7 +315,7 @@ async fn handle_stream_inner(
                         )
                         .await
                         {
-                            return;
+                            return Some(connect_elapsed);
                         }
                         offset = end;
                     }
@@ -316,7 +325,7 @@ async fn handle_stream_inner(
                 server.metrics.stream_errors.fetch_add(1, Ordering::Release);
                 warn!(stream_id, error = %e, "upstream body read error");
                 send_error(frame_tx, stream_id, &format!("body read error: {e}")).await;
-                return;
+                return Some(connect_elapsed);
             }
         }
     }
@@ -334,6 +343,7 @@ async fn handle_stream_inner(
     .await;
 
     debug!(stream_id, status, "stream completed");
+    Some(connect_elapsed)
 }
 
 async fn send_error(tx: &FrameSender, stream_id: u32, msg: &str) {

alembic/versions/20260302_1300_1d2e3f4a5b6c_add_proxy_metadata_to_proxy_nodes.py

@@ -0,0 +1,46 @@
+"""add_proxy_metadata_to_proxy_nodes
+
+Revision ID: 1d2e3f4a5b6c
+Revises: f0c3a7b9d1e2
+Create Date: 2026-03-02 13:00:00.000000+00:00
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "1d2e3f4a5b6c"
+down_revision: str | None = "f0c3a7b9d1e2"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    bind = op.get_bind()
+    insp = inspect(bind)
+    columns = [c["name"] for c in insp.get_columns(table_name)]
+    return column_name in columns
+
+
+def upgrade() -> None:
+    if not _column_exists("proxy_nodes", "proxy_metadata"):
+        op.add_column(
+            "proxy_nodes",
+            sa.Column(
+                "proxy_metadata",
+                sa.JSON(),
+                nullable=True,
+                comment="aether-proxy 上报元数据（版本等）",
+            ),
+        )
+
+
+def downgrade() -> None:
+    if _column_exists("proxy_nodes", "proxy_metadata"):
+        op.drop_column("proxy_nodes", "proxy_metadata")

frontend/src/api/proxy-nodes.ts

@@ -5,6 +5,7 @@ export interface ProxyNodeRemoteConfig {
   allowed_ports?: number[]
   log_level?: string
   heartbeat_interval?: number
+  upgrade_to?: string | null
 }
 
 export interface ProxyNode {
@@ -37,6 +38,7 @@ export interface ProxyNode {
   failed_requests: number
   dns_failures: number
   stream_errors: number
+  proxy_metadata: Record<string, unknown> | null
   created_at: string
   updated_at: string
 }
@@ -109,6 +111,14 @@ export const proxyNodesApi = {
     return response.data
   },
 
+  async batchUpgrade(version: string): Promise<{ version: string; updated: number; skipped: number; node_ids: string[] }> {
+    const response = await apiClient.post<{ version: string; updated: number; skipped: number; node_ids: string[] }>(
+      '/api/admin/proxy-nodes/upgrade',
+      { version }
+    )
+    return response.data
+  },
+
   async testProxyUrl(data: { proxy_url: string; username?: string; password?: string }): Promise<ProxyNodeTestResult> {
     const response = await apiClient.post<ProxyNodeTestResult>('/api/admin/proxy-nodes/test-url', data)
     return response.data

frontend/src/views/admin/ProxyNodes.vue

@@ -13,6 +13,14 @@
               代理节点
             </h3>
             <div class="flex items-center gap-2">
+              <Button
+                size="sm"
+                variant="outline"
+                class="h-7 text-xs"
+                @click="showBatchUpgradeDialog = true"
+              >
+                升级
+              </Button>
               <Button
                 size="sm"
                 class="h-7 text-xs"
@@ -89,6 +97,14 @@
               </SelectContent>
             </Select>
             <div class="h-4 w-px bg-border" />
+            <Button
+              variant="outline"
+              size="sm"
+              class="h-8 text-xs"
+              @click="showBatchUpgradeDialog = true"
+            >
+              批量升级
+            </Button>
             <Button
               variant="ghost"
               size="icon"
@@ -132,6 +148,9 @@
               <TableHead class="w-[100px] h-12 font-semibold text-center">
                 延迟
               </TableHead>
+              <TableHead class="w-[120px] h-12 font-semibold text-center">
+                版本
+              </TableHead>
               <TableHead class="w-[160px] h-12 font-semibold">
                 最后心跳
               </TableHead>
@@ -192,6 +211,9 @@
               <TableCell class="py-4 text-center">
                 <span class="text-sm tabular-nums">{{ node.avg_latency_ms != null ? `${node.avg_latency_ms.toFixed(0)}ms` : '-' }}</span>
               </TableCell>
+              <TableCell class="py-4 text-center">
+                <span class="text-sm tabular-nums">{{ node.is_manual ? '-' : nodeProxyVersion(node) }}</span>
+              </TableCell>
               <TableCell class="py-4">
                 <span class="text-xs text-muted-foreground">{{ formatTime(node.last_heartbeat_at) }}</span>
               </TableCell>
@@ -258,7 +280,7 @@
             </TableRow>
             <TableRow v-if="paginatedNodes.length === 0">
               <TableCell
-                colspan="9"
+                colspan="10"
                 class="py-12 text-center text-muted-foreground text-sm"
               >
                 {{ store.loading ? '加载中...' : '暂无代理节点' }}
@@ -296,6 +318,12 @@
                 <HardwareTooltip :node="node" />
               </div>
               <code class="text-xs text-muted-foreground">{{ nodeAddress(node) }}</code>
+              <div
+                v-if="!node.is_manual"
+                class="text-[11px] text-muted-foreground mt-1"
+              >
+                版本: {{ nodeProxyVersion(node) }}
+              </div>
             </div>
             <Badge
               :variant="statusVariant(node.status)"
@@ -540,6 +568,16 @@
             />
           </div>
         </div>
+        <div class="space-y-1.5">
+          <Label>升级到版本</Label>
+          <Input
+            v-model="configForm.upgrade_to"
+            placeholder="例如 0.2.3"
+          />
+          <p class="text-xs text-muted-foreground">
+            留空可清除已有升级指令
+          </p>
+        </div>
         <div
           v-if="configNode"
           class="text-xs text-muted-foreground"
@@ -563,6 +601,43 @@
       </template>
     </Dialog>
 
+    <!-- 批量升级对话框 -->
+    <Dialog
+      :model-value="showBatchUpgradeDialog"
+      title="批量升级"
+      description="向所有在线 tunnel 节点下发升级版本指令"
+      :icon="Settings"
+      size="sm"
+      @update:model-value="(open: boolean) => { if (!open) { showBatchUpgradeDialog = false; batchUpgradeVersion = '' } }"
+    >
+      <form
+        class="space-y-4"
+        @submit.prevent="handleBatchUpgrade"
+      >
+        <div class="space-y-1.5">
+          <Label>目标版本</Label>
+          <Input
+            v-model="batchUpgradeVersion"
+            placeholder="例如 0.2.3"
+          />
+        </div>
+      </form>
+      <template #footer>
+        <Button
+          variant="outline"
+          @click="showBatchUpgradeDialog = false; batchUpgradeVersion = ''"
+        >
+          取消
+        </Button>
+        <Button
+          :disabled="batchUpgrading || !batchUpgradeVersion.trim()"
+          @click="handleBatchUpgrade"
+        >
+          {{ batchUpgrading ? '下发中...' : '确认下发' }}
+        </Button>
+      </template>
+    </Dialog>
+
     <!-- 连接事件对话框 -->
     <Dialog
       :open="showEventsDialog"
@@ -699,7 +774,11 @@ const configForm = ref({
   allowed_ports: '',
   log_level: 'info',
   heartbeat_interval: '30',
+  upgrade_to: '',
 })
+const showBatchUpgradeDialog = ref(false)
+const batchUpgradeVersion = ref('')
+const batchUpgrading = ref(false)
 
 // 连接事件对话框
 const showEventsDialog = ref(false)
@@ -840,6 +919,7 @@ function handleConfig(node: ProxyNode) {
     allowed_ports: rc.allowed_ports?.join(', ') || '',
     log_level: rc.log_level || 'info',
     heartbeat_interval: String(rc.heartbeat_interval || node.heartbeat_interval || 30),
+    upgrade_to: rc.upgrade_to || '',
   }
   showConfigDialog.value = true
 }
@@ -873,6 +953,12 @@ async function handleSaveConfig() {
     if (!isNaN(hb) && hb >= 5) {
       data.heartbeat_interval = hb
     }
+    const targetVersion = configForm.value.upgrade_to.trim()
+    if (targetVersion) {
+      data.upgrade_to = targetVersion
+    } else if (configNode.value.remote_config?.upgrade_to) {
+      data.upgrade_to = null
+    }
     await proxyNodesApi.updateNodeConfig(configNode.value.id, data)
     success('远程配置已保存，将在下次心跳时生效')
     handleConfigDialogClose(false)
@@ -884,6 +970,23 @@ async function handleSaveConfig() {
   }
 }
 
+async function handleBatchUpgrade() {
+  const version = batchUpgradeVersion.value.trim()
+  if (!version || batchUpgrading.value) return
+  batchUpgrading.value = true
+  try {
+    const result = await proxyNodesApi.batchUpgrade(version)
+    success(`升级指令已下发：${result.updated} 个节点，跳过 ${result.skipped} 个`)
+    showBatchUpgradeDialog.value = false
+    batchUpgradeVersion.value = ''
+    await store.fetchNodes()
+  } catch (err: unknown) {
+    toastError(parseApiError(err, '批量升级下发失败'))
+  } finally {
+    batchUpgrading.value = false
+  }
+}
+
 async function handleDelete(node: ProxyNode) {
   const confirmed = await confirmDanger(
     `确定要删除代理节点 "${node.name}" (${node.tunnel_mode ? node.ip : `${node.ip}:${node.port}`}) 吗？`,
@@ -1009,4 +1112,13 @@ function nodeAddress(node: ProxyNode) {
   if (node.tunnel_mode) return node.ip || 'WebSocket Tunnel'
   return `${node.ip}:${node.port}`
 }
+
+function nodeProxyVersion(node: ProxyNode) {
+  const metadata = node.proxy_metadata
+  if (!metadata || typeof metadata !== 'object') return '-'
+  const version = (metadata as Record<string, unknown>).version
+  if (typeof version !== 'string') return '-'
+  const normalized = version.trim()
+  return normalized || '-'
+}
 </script>

src/api/admin/proxy_nodes/routes.py

@@ -39,11 +39,15 @@ class ProxyNodeRegisterRequest(BaseModel):
     # 指标（可选）
     active_connections: int | None = Field(None, ge=0, description="当前活跃连接数")
     total_requests: int | None = Field(None, ge=0, description="累计请求数")
-    avg_latency_ms: float | None = Field(None, ge=0, description="平均延迟（毫秒）")
+    avg_latency_ms: float | None = Field(None, ge=0, description="平均连接建立延迟(ms)")
 
     # 硬件信息
     hardware_info: dict | None = Field(None, description="硬件信息 JSON")
     estimated_max_concurrency: int | None = Field(None, ge=0, description="估算最大并发连接数")
+    proxy_metadata: dict[str, Any] | None = Field(None, description="aether-proxy 元数据（版本等）")
+    proxy_version: str | None = Field(
+        None, max_length=20, description="兼容字段：aether-proxy 软件版本"
+    )
 
     @field_validator("ip")
     @classmethod
@@ -62,7 +66,11 @@ class ProxyNodeHeartbeatRequest(BaseModel):
 
     active_connections: int | None = Field(None, ge=0, description="当前活跃连接数")
     total_requests: int | None = Field(None, ge=0, description="累计请求数")
-    avg_latency_ms: float | None = Field(None, ge=0, description="平均延迟（毫秒）")
+    avg_latency_ms: float | None = Field(None, ge=0, description="平均连接建立延迟(ms)")
+    proxy_metadata: dict[str, Any] | None = Field(None, description="aether-proxy 元数据（版本等）")
+    proxy_version: str | None = Field(
+        None, max_length=20, description="兼容字段：aether-proxy 软件版本"
+    )
 
 
 class ProxyNodeUnregisterRequest(BaseModel):
@@ -76,6 +84,7 @@ class ProxyNodeRemoteConfigRequest(BaseModel):
     allowed_ports: list[int] | None = Field(None, description="允许代理的目标端口")
     log_level: str | None = Field(None, description="日志级别 (trace/debug/info/warn/error)")
     heartbeat_interval: int | None = Field(None, ge=5, le=600, description="心跳间隔（秒）")
+    upgrade_to: str | None = Field(None, max_length=50, description="下发升级目标版本")
 
     @field_validator("allowed_ports")
     @classmethod
@@ -93,6 +102,28 @@ class ProxyNodeRemoteConfigRequest(BaseModel):
             raise ValueError("log_level 必须是 trace/debug/info/warn/error 之一")
         return v
 
+    @field_validator("upgrade_to")
+    @classmethod
+    def validate_upgrade_to(cls, v: str | None) -> str | None:
+        if v is None:
+            return None
+        vv = v.strip()
+        if not vv:
+            return None
+        return vv
+
+
+class ProxyNodeBatchUpgradeRequest(BaseModel):
+    version: str = Field(..., min_length=1, max_length=50, description="目标版本号")
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, v: str) -> str:
+        vv = v.strip()
+        if not vv:
+            raise ValueError("version 不能为空")
+        return vv
+
 
 class ManualProxyNodeCreateRequest(BaseModel):
     """手动创建代理节点"""
@@ -187,6 +218,12 @@ async def create_manual_proxy_node(request: Request, db: Session = Depends(get_d
     return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
 
 
+@router.post("/upgrade")
+async def batch_upgrade_proxy_nodes(request: Request, db: Session = Depends(get_db)) -> Any:
+    adapter = AdminBatchUpgradeProxyNodesAdapter()
+    return await pipeline.run(adapter=adapter, http_request=request, db=db, mode=adapter.mode)
+
+
 @router.patch("/{node_id}")
 async def update_manual_proxy_node(
     node_id: str, request: Request, db: Session = Depends(get_db)
@@ -274,6 +311,8 @@ class AdminRegisterProxyNodeAdapter(AdminApiAdapter):
             active_connections=req.active_connections,
             total_requests=req.total_requests,
             avg_latency_ms=req.avg_latency_ms,
+            proxy_metadata=req.proxy_metadata,
+            proxy_version=req.proxy_version,
             registered_by=context.user.id if context.user else None,
         )
 
@@ -305,6 +344,8 @@ class AdminHeartbeatProxyNodeAdapter(AdminApiAdapter):
             active_connections=req.active_connections,
             total_requests=req.total_requests,
             avg_latency_ms=req.avg_latency_ms,
+            proxy_metadata=req.proxy_metadata,
+            proxy_version=req.proxy_version,
         )
 
         context.add_audit_metadata(
@@ -477,6 +518,7 @@ class AdminUpdateProxyNodeConfigAdapter(AdminApiAdapter):
 
         # Build config dict with only the supplied fields
         config_updates: dict[str, Any] = {}
+        fields_set = req.model_fields_set
         if req.node_name is not None:
             config_updates["node_name"] = req.node_name
         if req.allowed_ports is not None:
@@ -485,6 +527,8 @@ class AdminUpdateProxyNodeConfigAdapter(AdminApiAdapter):
             config_updates["log_level"] = req.log_level
         if req.heartbeat_interval is not None:
             config_updates["heartbeat_interval"] = req.heartbeat_interval
+        if "upgrade_to" in fields_set:
+            config_updates["upgrade_to"] = req.upgrade_to
 
         node = ProxyNodeService.update_node_config(
             context.db, node_id=self.node_id, config_updates=config_updates
@@ -504,6 +548,29 @@ class AdminUpdateProxyNodeConfigAdapter(AdminApiAdapter):
         }
 
 
+@dataclass
+class AdminBatchUpgradeProxyNodesAdapter(AdminApiAdapter):
+    """批量向在线 tunnel 节点下发升级指令。"""
+
+    name: str = "admin_batch_upgrade_proxy_nodes"
+
+    async def handle(self, context: ApiRequestContext) -> Any:
+        payload = context.ensure_json_body()
+        try:
+            req = ProxyNodeBatchUpgradeRequest.model_validate(payload)
+        except ValidationError as exc:
+            raise InvalidRequestException("输入验证失败: " + _format_validation_error(exc))
+
+        result = ProxyNodeService.batch_upgrade_online_nodes(context.db, version=req.version)
+        context.add_audit_metadata(
+            action="proxy_node_batch_upgrade",
+            version=result["version"],
+            updated=result["updated"],
+            skipped=result["skipped"],
+        )
+        return result
+
+
 class TestProxyUrlRequest(BaseModel):
     proxy_url: str = Field(..., min_length=1, max_length=500)
     username: str | None = Field(None, max_length=255)

src/models/database.py

@@ -919,10 +919,11 @@ class ProxyNode(Base):
     # 性能指标（心跳上报）
     active_connections = Column(Integer, default=0, nullable=False)
     total_requests = Column(BigInteger, default=0, nullable=False)
-    avg_latency_ms = Column(Float, nullable=True)
+    avg_latency_ms = Column(Float, nullable=True, comment="平均连接建立延迟(ms), DNS+TCP/TLS+TTFB")
     failed_requests = Column(BigInteger, default=0, nullable=False, comment="累计失败请求数")
     dns_failures = Column(BigInteger, default=0, nullable=False, comment="累计 DNS 失败数")
     stream_errors = Column(BigInteger, default=0, nullable=False, comment="累计流错误数")
+    proxy_metadata = Column(JSON, nullable=True, comment="aether-proxy 上报元数据（版本等）")
 
     # 硬件信息（注册时上报，JSON 可扩展）
     hardware_info = Column(

src/services/proxy_node/hub_transport.py

@@ -351,7 +351,7 @@ class HubConnectionManager:
 
         def _sync_heartbeat() -> dict[str, object]:
             from src.database import create_session
-            from src.services.proxy_node.service import ProxyNodeService
+            from src.services.proxy_node.service import ProxyNodeService, build_heartbeat_ack
 
             if not node_id:
                 return {}
@@ -367,12 +367,10 @@ class HubConnectionManager:
                     failed_requests=data.get("failed_requests"),
                     dns_failures=data.get("dns_failures"),
                     stream_errors=data.get("stream_errors"),
+                    proxy_metadata=data.get("proxy_metadata"),
+                    proxy_version=data.get("proxy_version"),
                 )
-                result: dict[str, object] = {}
-                if node.remote_config:
-                    result["remote_config"] = node.remote_config
-                    result["config_version"] = node.config_version or 0
-                return result
+                return build_heartbeat_ack(node)
             finally:
                 db.close()
 

src/services/proxy_node/service.py

@@ -62,6 +62,7 @@ def node_to_dict(node: ProxyNode) -> dict[str, Any]:
         "failed_requests": node.failed_requests,
         "dns_failures": node.dns_failures,
         "stream_errors": node.stream_errors,
+        "proxy_metadata": node.proxy_metadata,
         "hardware_info": node.hardware_info,
         "estimated_max_concurrency": node.estimated_max_concurrency,
         "remote_config": node.remote_config,
@@ -95,6 +96,40 @@ def _sanitize_proxy_error(err: Exception) -> str:
     return re.sub(r"://[^@/]+@", "://***@", str(err))
 
 
+def _normalize_proxy_metadata(
+    proxy_metadata: Any | None, proxy_version: str | None = None
+) -> dict[str, Any] | None:
+    """规范化 proxy 元数据，兼容旧版单独上报 proxy_version。"""
+    normalized: dict[str, Any] = {}
+    if isinstance(proxy_metadata, dict):
+        normalized = {str(k): v for k, v in proxy_metadata.items() if k is not None}
+
+    version: str | None = None
+    raw_version = normalized.pop("version", None)
+    if isinstance(raw_version, str) and raw_version.strip():
+        version = raw_version.strip()[:20]
+    if proxy_version is not None and proxy_version.strip():
+        version = proxy_version.strip()[:20]
+    if version is not None:
+        normalized["version"] = version
+
+    return normalized or None
+
+
+def build_heartbeat_ack(node: ProxyNode) -> dict[str, Any]:
+    """从心跳后的节点构建 ACK 响应 payload（供 hub_transport / tunnel_manager 使用）。"""
+    result: dict[str, Any] = {}
+    if not node.remote_config:
+        return result
+    result["remote_config"] = node.remote_config
+    result["config_version"] = node.config_version or 0
+    if isinstance(node.remote_config, dict):
+        raw_upgrade = node.remote_config.get("upgrade_to")
+        if isinstance(raw_upgrade, str) and raw_upgrade.strip():
+            result["upgrade_to"] = raw_upgrade.strip()
+    return result
+
+
 async def _test_proxy_connectivity(proxy_url: str) -> dict[str, Any]:
     """通过代理 URL 测试连通性，返回标准化结果 dict"""
     import time as _time
@@ -250,11 +285,14 @@ class ProxyNodeService:
         active_connections: int | None = None,
         total_requests: int | None = None,
         avg_latency_ms: float | None = None,
+        proxy_metadata: dict[str, Any] | None = None,
+        proxy_version: str | None = None,
         registered_by: str | None = None,
     ) -> ProxyNode:
         """注册或更新 aether-proxy 节点（tunnel 模式）"""
 
         now = datetime.now(timezone.utc)
+        normalized_proxy_metadata = _normalize_proxy_metadata(proxy_metadata, proxy_version)
 
         node = (
             db.query(ProxyNode)
@@ -283,6 +321,8 @@ class ProxyNodeService:
                 node.total_requests = total_requests
             if avg_latency_ms is not None:
                 node.avg_latency_ms = avg_latency_ms
+            if normalized_proxy_metadata is not None:
+                node.proxy_metadata = normalized_proxy_metadata
         else:
             node = ProxyNode(
                 id=str(uuid.uuid4()),
@@ -298,6 +338,7 @@ class ProxyNodeService:
                 active_connections=active_connections or 0,
                 total_requests=total_requests or 0,
                 avg_latency_ms=avg_latency_ms,
+                proxy_metadata=normalized_proxy_metadata,
                 hardware_info=hardware_info,
                 estimated_max_concurrency=estimated_max_concurrency,
                 tunnel_mode=True,
@@ -322,6 +363,8 @@ class ProxyNodeService:
         failed_requests: int | None = None,
         dns_failures: int | None = None,
         stream_errors: int | None = None,
+        proxy_metadata: dict[str, Any] | None = None,
+        proxy_version: str | None = None,
     ) -> ProxyNode:
         """处理节点心跳（仅 tunnel 模式节点，更新指标并修正状态不一致）
 
@@ -357,6 +400,9 @@ class ProxyNodeService:
             values["active_connections"] = active_connections
         if avg_latency_ms is not None:
             values["avg_latency_ms"] = avg_latency_ms
+        normalized_proxy_metadata = _normalize_proxy_metadata(proxy_metadata, proxy_version)
+        if normalized_proxy_metadata is not None:
+            values["proxy_metadata"] = normalized_proxy_metadata
 
         # 区间增量指标 -- 使用数据库原子自增，避免并发心跳读改写丢增量
         if total_requests is not None and total_requests > 0:
@@ -626,7 +672,11 @@ class ProxyNodeService:
         # Merge with existing config (so partial updates are preserved)
         # Copy to a new dict so SQLAlchemy detects the change on the JSON column
         existing = dict(node.remote_config) if node.remote_config else {}
-        existing.update(config_updates)
+        for key, value in config_updates.items():
+            if key == "upgrade_to" and value is None:
+                existing.pop("upgrade_to", None)
+                continue
+            existing[key] = value
 
         node.remote_config = existing
         node.config_version = (node.config_version or 0) + 1
@@ -635,3 +685,44 @@ class ProxyNodeService:
         db.commit()
         db.refresh(node)
         return node
+
+    @staticmethod
+    def batch_upgrade_online_nodes(db: Session, *, version: str) -> dict[str, Any]:
+        """批量向在线 tunnel 节点下发 upgrade_to。"""
+        normalized = version.strip()
+        if not normalized:
+            raise InvalidRequestException("version 不能为空")
+
+        nodes = (
+            db.query(ProxyNode)
+            .filter(
+                ProxyNode.is_manual == False,  # noqa: E712
+                ProxyNode.tunnel_mode == True,  # noqa: E712
+                ProxyNode.status == ProxyNodeStatus.ONLINE,
+            )
+            .all()
+        )
+
+        updated_node_ids: list[str] = []
+        skipped = 0
+        now = datetime.now(timezone.utc)
+        for node in nodes:
+            existing = dict(node.remote_config) if node.remote_config else {}
+            if existing.get("upgrade_to") == normalized:
+                skipped += 1
+                continue
+            existing["upgrade_to"] = normalized
+            node.remote_config = existing
+            node.config_version = (node.config_version or 0) + 1
+            node.updated_at = now
+            updated_node_ids.append(node.id)
+
+        if updated_node_ids:
+            db.commit()
+
+        return {
+            "version": normalized,
+            "updated": len(updated_node_ids),
+            "skipped": skipped,
+            "node_ids": updated_node_ids,
+        }

src/services/proxy_node/tunnel_manager.py

@@ -470,7 +470,7 @@ class TunnelManager:
 
         def _sync_heartbeat() -> dict[str, Any]:
             from src.database import create_session
-            from src.services.proxy_node.service import ProxyNodeService
+            from src.services.proxy_node.service import ProxyNodeService, build_heartbeat_ack
 
             db = create_session()
             try:
@@ -483,12 +483,10 @@ class TunnelManager:
                     failed_requests=data.get("failed_requests"),
                     dns_failures=data.get("dns_failures"),
                     stream_errors=data.get("stream_errors"),
+                    proxy_metadata=data.get("proxy_metadata"),
+                    proxy_version=data.get("proxy_version"),
                 )
-                result: dict[str, Any] = {}
-                if node.remote_config:
-                    result["remote_config"] = node.remote_config
-                    result["config_version"] = node.config_version or 0
-                return result
+                return build_heartbeat_ack(node)
             finally:
                 db.close()
 

tests/unit/test_hub_transport_heartbeat.py

@@ -76,7 +76,10 @@ async def test_handle_heartbeat_normalizes_id_and_updates_db(
 
     def _fake_heartbeat(db: Any, **kwargs: Any) -> Any:
         heartbeat_calls.append(kwargs)
-        return SimpleNamespace(remote_config={"heartbeat_interval": 8}, config_version=5)
+        return SimpleNamespace(
+            remote_config={"heartbeat_interval": 8, "upgrade_to": "0.2.3"},
+            config_version=5,
+        )
 
     redis = _StubRedis(set_result=True)
     monkeypatch.setattr(manager, "_send_frame", _fake_send_frame)
@@ -97,6 +100,7 @@ async def test_handle_heartbeat_normalizes_id_and_updates_db(
                 "failed_requests": 1,
                 "dns_failures": 2,
                 "stream_errors": 0,
+                "proxy_metadata": {"version": "0.2.1"},
             }
         )
     )
@@ -104,13 +108,15 @@ async def test_handle_heartbeat_normalizes_id_and_updates_db(
     assert len(redis.calls) == 1
     assert redis.calls[0][0] == "hub:heartbeat:node-1:sess-1:15"
     assert heartbeat_calls and heartbeat_calls[0]["node_id"] == "node-1"
+    assert heartbeat_calls[0]["proxy_metadata"] == {"version": "0.2.1"}
     assert len(captured_frames) == 1
 
     ack = _decode_ack(captured_frames[0])
     assert ack["heartbeat_id"] == 15
     assert isinstance(ack["heartbeat_id"], int)
-    assert ack["remote_config"] == {"heartbeat_interval": 8}
+    assert ack["remote_config"] == {"heartbeat_interval": 8, "upgrade_to": "0.2.3"}
     assert ack["config_version"] == 5
+    assert ack["upgrade_to"] == "0.2.3"
 
 
 @pytest.mark.asyncio
@@ -182,10 +188,18 @@ async def test_handle_heartbeat_redis_error_falls_back_to_db_update(
     )
 
     await manager._handle_heartbeat(
-        _heartbeat_frame({"node_id": "node-1", "heartbeat_id": 99, "total_requests": 1})
+        _heartbeat_frame(
+            {
+                "node_id": "node-1",
+                "heartbeat_id": 99,
+                "total_requests": 1,
+                "proxy_metadata": {"version": "0.2.2"},
+            }
+        )
     )
 
     assert heartbeat_calls and heartbeat_calls[0]["total_requests"] == 1
+    assert heartbeat_calls[0]["proxy_metadata"] == {"version": "0.2.2"}
     assert len(captured_frames) == 1
     ack = _decode_ack(captured_frames[0])
     assert ack == {"heartbeat_id": 99}