fix(agent): 升级 Agent 保持 HTTPS 直连并清理残留反代并发布 v1.5.2

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.5.2] - 2026-09-28
+
+### 修复
+
+- **升级 Agent 不再强制切回 SSH 隧道**：HTTPS 直连模式下点击「升级 Agent」原先会无条件建立隧道并把 transport 改回 `tunnel`，用户升级后需要重新切换 HTTPS。现在升级前是 `https-pin` 时会保持 HTTPS 直连，只更新 Token 密文并重新验证连通
+- **清理隧道模式下残留的 HTTPS 反代**：旧升级流程切回隧道时没有关闭 Agent 上的 `fonuagent-https.conf`，导致 7443 等端口继续暴露。现在从 HTTPS 迁移到隧道、应用启动恢复隧道、手动「重启隧道」时都会通过隧道调用 `DisableHTTPS` 清理残留
+
+### 变更
+
+- 版本号提升到 1.5.2；`AgentVersion` 保持 **0.14.1**，本次是中央端修复，不需要重新升级 Agent
+
+### 测试
+
+- `internal/frp` 现有单元测试与编译校验通过；升级分支依赖真实 SSH/Agent 环境，未新增本地集成测试
+
 ## [v1.5.1] - 2026-09-28
 
 ### 变更

VERSION

@@ -1 +1 @@
-1.5.1
+1.5.2

docs/README.md

@@ -1,7 +1,7 @@
 # Fonu 文档索引
 
 > 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
-> 最近更新：2026-09-28（v1.5.1）
+> 最近更新：2026-09-28（v1.5.2）
 
 ## 方案与设计（本目录）
 

docs/system-upgrade.md

@@ -238,16 +238,16 @@ FONU_VERSION=<旧版本> docker compose up -d --no-deps --force-recreate fonu
 
 ## 10. 在线升级验证
 
-示例页面用于验证升级结果。v1.5.1 的验证流程：
+示例页面用于验证升级结果。v1.5.2 的验证流程：
 
 1. 确认当前线上实例为 v1.3.0，且 `fonu-updater` sidecar 已运行。
-2. 确认远端 `main` 分支的 `VERSION` 为 `1.5.1`。
+2. 确认远端 `main` 分支的 `VERSION` 为 `1.5.2`。
 3. 在侧栏看到「一键升级」后点击并确认。
 4. 等待升级弹窗显示成功，页面自动刷新。
 5. 打开侧栏「示例页面」，确认：
    - 页面路由为 `/example`；
-   - 页面显示的版本为 `1.5.1`；
+   - 页面显示的版本为 `1.5.2`；
-   - 页面显示验证标识 `v1.5.1-example-page`；
+   - 页面显示验证标识 `v1.5.2-example-page`；
    - 页面显示独立的「本次升级验证」区块；
    - 「升级验证」显示为「通过」。
 

internal/frp/service.go

@@ -745,6 +745,10 @@ func (s *Service) AgentInstall(ctx context.Context, serverID int64) (Server, err
 	if err != nil {
 		return Server{}, err
 	}
+	// 已是 HTTPS 直连时，升级 Agent 不应把用户的传输方式改回隧道。
+	if server.AgentTransport == "https-pin" {
+		return s.keepAgentHTTPSAfterInstall(ctx, server, token, agentToken)
+	}
 	localPort, listener, err := s.reserveAgentTunnelPort(ctx, serverID, server.AgentLocalPort)
 	if err != nil {
 		return Server{}, err
@@ -786,10 +790,45 @@ func (s *Service) AgentInstall(ctx context.Context, serverID int64) (Server, err
 		_ = (AgentInstaller{SSH: installer}).RestorePreviousConfig(ctx)
 		return Server{}, err
 	}
+	// 旧版升级流程可能残留 fonuagent-https.conf，这里通过隧道顺手关闭，避免 7443 继续暴露。
+	_ = client.DisableHTTPS(ctx)
 	s.invalidateAgentClient(serverID)
 	return updated, nil
 }
 
+// keepAgentHTTPSAfterInstall 在 HTTPS 直连模式下完成 Agent 升级：
+// 保持 agent_url、pin 与 transport 不变，只更新 Token 密文并重新验证连通。
+func (s *Service) keepAgentHTTPSAfterInstall(ctx context.Context, server Server, token, agentToken string) (Server, error) {
+	baseURL := agentHTTPSBaseURL(server)
+	pins := agentTransportPins(server)
+	if len(pins) == 0 {
+		return Server{}, fmt.Errorf("Agent 已升级，但 HTTPS 直连缺少证书指纹；请重新切换 HTTPS 直连")
+	}
+	client := NewAgentClientWithPins(baseURL, token, pins...)
+	if err := client.Ping(ctx); err != nil {
+		return Server{}, fmt.Errorf("Agent 已升级，但 HTTPS 直连验证失败: %w", err)
+	}
+	input := ServerInput{
+		Name: server.Name, ServerAddr: server.ServerAddr, ServerPort: server.ServerPort,
+		TLS: server.TLS, TLSServerName: server.TLSServerName, Enabled: server.Enabled,
+		Options: server.Options, AgentURL: baseURL,
+		AgentToken: token, SSHHost: server.SSHHost, SSHPort: server.SSHPort, SSHUser: server.SSHUser,
+		SSHAuth: server.SSHAuth, MgmtEnabled: true,
+	}
+	if _, err := s.store.UpdateServer(ctx, server.ID, input, "", false, agentToken, true, "", false); err != nil {
+		return Server{}, err
+	}
+	listenAddr := strings.TrimSpace(server.AgentListenAddr)
+	if listenAddr == "" {
+		listenAddr = fmt.Sprintf("0.0.0.0:%d", listenPort("", 7443))
+	}
+	if err := s.store.SetAgentTransport(ctx, server.ID, baseURL, "https-pin", server.AgentLocalPort, server.AgentTLSPin, listenAddr, "connected", ""); err != nil {
+		return Server{}, err
+	}
+	s.invalidateAgentClient(server.ID)
+	return s.store.GetServer(ctx, server.ID)
+}
+
 func (s *Service) tunnelContext(fallback context.Context) context.Context {
 	s.downloadMu.RLock()
 	base := s.baseCtx
@@ -885,8 +924,19 @@ func (s *Service) StartAgentTunnels(ctx context.Context) {
 		}
 		if _, err := s.ensureAgentTunnel(ctx, server.ID); err != nil {
 			s.logger.Warn("Agent 隧道启动失败", "server_id", server.ID, "error", err.Error())
+			continue
+		}
+		s.cleanupLegacyAgentHTTPS(ctx, server.ID)
 	}
 }
+
+// cleanupLegacyAgentHTTPS 清理隧道模式下可能残留的 fonuagent-https.conf，避免 7443 继续暴露。
+func (s *Service) cleanupLegacyAgentHTTPS(ctx context.Context, serverID int64) {
+	client, ok := s.agentClient(ctx, serverID)
+	if !ok {
+		return
+	}
+	_ = client.DisableHTTPS(ctx)
 }
 
 func (s *Service) stopAgentTunnels() {
@@ -933,6 +983,7 @@ func (s *Service) RestartAgentTunnel(ctx context.Context, serverID int64) (Serve
 		_ = s.store.SetAgentTransport(ctx, serverID, current.AgentURL, "tunnel", current.AgentLocalPort, current.AgentTLSPin, current.AgentListenAddr, "failed", err.Error())
 		return Server{}, err
 	}
+	s.cleanupLegacyAgentHTTPS(ctx, serverID)
 	server, err := s.store.GetServer(ctx, serverID)
 	if err != nil {
 		return Server{}, err

web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "fonu-web",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fonu-web",
-      "version": "1.5.1",
+      "version": "1.5.2",
       "dependencies": {
         "@codemirror/commands": "^6.11.1",
         "@codemirror/lang-javascript": "^6.2.5",

web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fonu-web",
   "private": true,
-  "version": "1.5.1",
+  "version": "1.5.2",
   "packageManager": "npm@10.9.4",
   "type": "module",
   "scripts": {

web/src/views/ExampleView.vue

@@ -8,7 +8,7 @@
     </template>
   </PageHeader>
 
-  <n-alert type="success" :bordered="false" class="example-alert" title="v1.5.1 示例页面验证标识已生效">
+  <n-alert type="success" :bordered="false" class="example-alert" title="v1.5.2 示例页面验证标识已生效">
     当前页面由 v{{ version }} 提供，验证标识为 <span class="mono">{{ verificationMarker }}</span>。
     如果你是在升级后首次看到这行内容，说明前端构建、镜像重建和服务重启均已成功。
   </n-alert>
@@ -19,7 +19,7 @@
       <strong class="example-proof__value">{{ verificationRound }}</strong>
     </div>
     <div class="example-proof__hint">
-      看到这个新区块，说明前端资源已经从旧版本切换到 v1.5.1。
+      看到这个新区块，说明前端资源已经从旧版本切换到 v1.5.2。
     </div>
   </div>
 
@@ -33,16 +33,16 @@
     <StatCard label="本次验证标识" :value="verificationMarker" sub="用于区分升级前后的前端资源" tone="blue" value-small>
       <template #icon><n-icon :component="FlashOutline" /></template>
     </StatCard>
-    <StatCard label="页面状态" value="已更新" sub="v1.5.1 前端资源已加载" tone="teal">
+    <StatCard label="页面状态" value="已更新" sub="v1.5.2 前端资源已加载" tone="teal">
       <template #icon><n-icon :component="CheckmarkCircleOutline" /></template>
     </StatCard>
   </div>
 
   <FonuCard title="本次示例页变化" subtitle="用于确认升级后的页面内容确实发生变化">
     <ul class="example-changes">
-      <li>页面版本提示更新为 v1.5.1。</li>
+      <li>页面版本提示更新为 v1.5.2。</li>
-      <li>「本次升级验证」区块和页面状态同步更新为 v1.5.1。</li>
+      <li>「本次升级验证」区块和页面状态同步更新为 v1.5.2。</li>
-      <li>验证标识更新为 <span class="mono">v1.5.1-example-page</span>。</li>
+      <li>验证标识更新为 <span class="mono">v1.5.2-example-page</span>。</li>
     </ul>
   </FonuCard>
 
@@ -87,8 +87,8 @@ const message = useMessage()
 const version = ref(__APP_VERSION__)
 const checkedAt = ref('')
 const refreshing = ref(false)
-const verificationRound = 'v1.5.1'
+const verificationRound = 'v1.5.2'
-const verificationMarker = 'v1.5.1-example-page'
+const verificationMarker = 'v1.5.2-example-page'
 
 async function refreshVersion() {
   refreshing.value = true