fix(update): 重启交还 guard、OTA 支持 release/包两种来源、修三处真 bug

## 一、重启不再由 update 自己 systemctl（用户口径：应该通知 guard）原 internal/update 直接 `systemctl restart homeagent`。三个问题： ① 杀掉整个 cgroup（unit 里 KillMode=control-group）⇒ **guard 跟着死**，而 guard 存在的意义就是不让自己死。 ② 丢失 exit 42 语义：guard 的 failures/failbackRound/failbackDone 全丢。 ③ 自毁竞态：发命令的进程正是被重启杀掉的进程 ⇒ CombinedOutput 可能报错， **一次成功的升级被误判失败而回滚**。现在 internal/update 只到"产物就绪"：预检 → 备份 → 写 pending → 原子替换。重启由调用方走**既有**通道（restartCh → exit 42 → guard 用新二进制重拉）： · webui h.kernelCtl.RequestKernelRestart（本来就有，且是白名单内） · pluginmgr p.sdk.KernelControl().RequestKernelRestart（见下面第三条） · CLI 外部管理命令，restart unit 后按**版本自报**核对是否真生效 ## 二、OTA 支持两种来源（release 自动更新 / 指定安装包）新增 internal/update/source.go： Source{Kind: FromPackage, Path} → 直接用本地包 Source{Kind: FromRelease} → 查最新 Release → 下载 → 校验 digest ParseSource(pkg, release) 统一判空规则（pkg 优先），避免三端各写一套。两条来源解析后进**同一条** Apply，不存在两份升级实现。 ## 三、修三处已提交代码里的真 bug ① **HEAD 编译不过**：d17e261 提交了 kernelmod/update/mod.go（引用 ks.Update），但 kernelboot/kernelstate.go 的字段改动从未提交。干净 worktree 实测 `ks.Update undefined` —— 推上去的仓库是坏的。本次补上。 ② **kernelDataDir 算错一级**：Dir(Dir("/home/newqqagent/plugins")) = "/home"，而第 0 层 update 模块从 ks.DataDir=/home/newqqagent 读 pending ⇒ **agent 发起的升级一旦启动失败就永不回滚**（静默失效）。改为 Dir 一次。 ③ **pluginmgr 的 KernelControl 恒为 nil**：它不在 kernelControlAllowed 里，于是 `if kc := p.sdk.KernelControl(); kc != nil` 永不成立 ⇒ 换完二进制**从不重启** ⇒ pending 留着 ⇒ 下次重启被判"未确认"而回滚。修法**不是**把 pluginmgr 加进完整白名单 —— 那等于让 LLM 能关机整个服务（kernel_control_gate_test 明确拦这个）。而是拆出**仅重启**授权： kernelControlAllowed = {webui} 完整（含关机） kernelRestartAllowed = {pluginmgr} 仅重启（shutdown 直接报错）两者的危险程度差一个量级：重启几秒后 guard 自己拉回来，关机不会自己回来。 ## 四、EventBus：插件请求更新不必 import internal/update 新增 events.EventUpdateRequest，pluginmgr 订阅并受理： scope=kernel → kernelUpdateApply；scope=plugin → pluginUpdate(apply)。它在 internal/plugins/webui 的 SSE 守卫里显式登记为**内核内部控制事件** （不该推给浏览器：前端要的是 update_progress/update_result，不是"谁发了请求"）。 ## 五、顺手修掉的静默失败 · webui /kernel/update 原实现：**先**写 202 Accepted，**再**解析 body，之后每个错误都直接 `return` —— 用户看到"已受理"然后什么都没发生。改为同步 Apply（失败可如实报 HTTP 状态），成功后才请求重启。 · pluginmgr 拿不到控制通道时不再假装成功，而是回报 applied=true + 明确原因（否则用户以为已升级，进程却还在跑旧镜像）。 · update 事件 publishResult 的 errMsg 原先是死代码（`_ = errMsg`），按 payload 约定写回 error 字段。
2026-11-06 09:17:31 +00:00 · 2026-10-26 13:45:54 +08:00
parent 6dc87965ad
commit 817f6c59ae
12 changed files with 557 additions and 200 deletions
--- a/internal/update/kernel.go
+++ b/internal/update/kernel.go
@ -246,31 +246,36 @@ func FileSize(p string) int64 {
 	return 0
 }

-// doUpgrade 执行真实升级：备份 → 预检 → 原子替换 → 重启 → 后置验证 → 失败回滚。
+// Apply 执行真实升级：预检 → 备份 → 写 pending → 原子替换。
 //
-// 每一步失败都往回退，且**回滚后必须能正常启动**——这是本函数的核心承诺：
-// 宁可升级失败，不可让机器起不来。
-func DoUpgrade(root, binPath, newDG, pluginsDir, dataDir string) error {
-	return DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir, nil)
-}
-
-// DoUpgradeBus 同 DoUpgrade，但把每个步骤发布到事件总线。
+// ## ★ 本函数**不重启**内核
 //
-// ★ 为什么必须"先发事件再动作"：升级的最后几步会让进程消失
-// （replace → restart）。顺序一反，最后几步的事件永远发不出去 ——
-// 而那时用户最需要知道"升级到哪一步了/失败了/已回滚"。
+// 重启必须由**调用方**通过内核控制通道发起，理由见
+// cmd/homed/kernel_control.go 的说明：worker 是被守护方，只有 guard
+// 知道这次退出该不该重拉（exit 42 → 重拉且不计失败轮次）。
 //
-// bus 为 nil 时退化成纯 printf（CLI 场景没有总线）。
-func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.Bus) error {
+// 本包若自己调 `systemctl restart`，会带来三个问题：
+//
+//	· 杀掉整个 cgroup（含 guard）—— 把监督者一起杀掉
+//	· 丢失 exit 42 语义：guard 的 failures/failbackRound 状态全丢
+//	· 发命令的进程正是被重启杀掉的进程 ⇒ 返回值不可靠，
+//	  一次成功的升级会被误判成失败而触发回滚
+//
+// 所以这里只承诺到"磁盘上的产物已就绪，pending 标记已写"。
+// 后续重启 → 新内核启动 → update 模块（第 0 层）确认或回滚。
+//
+// 每一步失败都往回退：替换中途失败 ⇒ 立即用备份还原并清标记
+// （此时尚未重启，回滚在本进程内完成，机器始终可启动）。
+func Apply(root, binPath, newDG, dataDir string, bus *events.Bus) (*Outcome, error) {
 	newBin := FindFile(root, "homed")
 	if newBin == "" {
-		return fmt.Errorf("包内无 homed")
+		return nil, fmt.Errorf("包内无 homed")
 	}

 	// ── 预检：新二进制必须能自报版本（说明它是可执行的、架构对的）──
 	nv, err := ReadBinVersion(newBin)
 	if err != nil {
-		return fmt.Errorf("预检失败，新二进制不可执行: %w", err)
+		return nil, fmt.Errorf("预检失败，新二进制不可执行: %w", err)
 	}
 	publishProgress(bus, "kernel", "", "verify", "新内核可执行，版本 "+nv.Version)
 	fmt.Printf("\n== 预检通过 ==\n新内核 %s 可执行\n", nv.Version)
@ -279,7 +284,7 @@ func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.
 	ts := NowStamp()
 	backup := filepath.Join("/root", "homed-upgrade-backup-"+ts)
 	if err := os.MkdirAll(backup, 0755); err != nil {
-		return fmt.Errorf("建备份目录: %w", err)
+		return nil, fmt.Errorf("建备份目录: %w", err)
 	}
 	targets := []string{binPath}
 	if dg := filepath.Join(filepath.Dir(binPath), "depgraph.bin"); FileExists(dg) {
@ -287,7 +292,7 @@ func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.
 	}
 	for _, t := range targets {
 		if err := CopyFile(t, filepath.Join(backup, filepath.Base(t))); err != nil {
-			return fmt.Errorf("备份 %s: %w", t, err)
+			return nil, fmt.Errorf("备份 %s: %w", t, err)
 		}
 	}
 	publishProgress(bus, "kernel", "", "backup", fmt.Sprintf("已备份 %d 个文件", len(targets)))
@ -297,9 +302,6 @@ func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.
 	//
 	// 顺序很关键：先写标记再替换。若反过来（替换后才写），"替换成功但
 	// 没来得及写标记就崩了"会丢标记 ⇒ 下次启动不知道该回滚。
-	//
-	// 标记由 update 模块（第 0 层）在下次启动时读；读到就说明上次升级
-	// 留下的版本没能活到清除标记 ⇒ 回滚（见 internal/update/rollback.go）。
 	curVer := &BinVersion{}
 	if v, verr := ReadBinVersion(binPath); verr == nil {
 		curVer = v
@ -314,14 +316,15 @@ func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.
 		}); perr != nil {
 			// 写不成功 ⇒ 放弃本次升级：没有标记就没有回滚能力，
 			// 而不带回滚的升级等于赌运气。
-			return fmt.Errorf("写升级确认标记失败（放弃升级，未替换任何文件）: %w", perr)
+			return nil, fmt.Errorf("写升级确认标记失败（放弃升级，未替换任何文件）: %w", perr)
 		}
 		fmt.Printf("已写升级确认标记 → %s\n", pendingPath(dataDir))
 	}

-	rollback := func(cause error) error {
+	// restore 在替换失败时把已动的文件还原（尚未重启，机器仍可启动）。
+	restore := func(cause error) (*Outcome, error) {
 		publishProgress(bus, "kernel", "", "rollback", cause.Error())
-		fmt.Printf("\n❌ %v\n== 开始回滚 ==\n", cause)
+		fmt.Printf("\n❌ %v\n== 就地还原（尚未重启，机器仍可启动）==\n", cause)
 		if dataDir != "" {
 			if cerr := ClearPendingUpgrade(dataDir); cerr != nil {
 				fmt.Printf("  ⚠️ 清除升级确认标记失败: %v\n", cerr)
@ -330,74 +333,41 @@ func DoUpgradeBus(root, binPath, newDG, pluginsDir, dataDir string, bus *events.
 		for _, t := range targets {
 			src := filepath.Join(backup, filepath.Base(t))
 			if err := CopyFile(src, t); err != nil {
-				fmt.Printf("  ⚠️ 回滚 %s 失败: %v（需人工处理）\n", t, err)
+				fmt.Printf("  ⚠️ 还原 %s 失败: %v（需人工处理）\n", t, err)
 				continue
 			}
 			fmt.Printf("  已恢复 %s\n", t)
 		}
-		if err := restartService(); err != nil {
-			fmt.Printf("  ⚠️ 重启失败: %v（需人工处理）\n", err)
-		} else if !WaitHealthy(60) {
-			fmt.Println("  ⚠️ 回滚后仍不健康，需人工介入")
-		} else {
-			fmt.Println("  ✅ 已回滚并恢复正常运行")
-		}
-		return fmt.Errorf("升级失败已回滚: %w", cause)
+		publishResult(bus, "kernel", "", false, curVer.Version, nv.Version, true, cause.Error())
+		return nil, fmt.Errorf("替换失败已还原（未重启）: %w", cause)
 	}

 	// ── 替换（depgraph 必须与 homed 同批，顺序无关但都要成）──
 	if newDG != "" {
 		dst := filepath.Join(filepath.Dir(binPath), "depgraph.bin")
 		if err := CopyFile(newDG, dst); err != nil {
-			return rollback(fmt.Errorf("替换 depgraph.bin: %w", err))
+			return restore(fmt.Errorf("替换 depgraph.bin: %w", err))
 		}
 		fmt.Println("已替换 depgraph.bin")
 	}
 	if err := CopyFile(newBin, binPath); err != nil {
-		return rollback(fmt.Errorf("替换 homed: %w", err))
+		return restore(fmt.Errorf("替换 homed: %w", err))
 	}
 	fmt.Println("已替换 homed")
+	publishProgress(bus, "kernel", "", "ready", "新内核已就位，等待重启")

-	// ── 重启 + 后置验证 ──
-	if err := restartService(); err != nil {
-		return rollback(fmt.Errorf("重启: %w", err))
-	}
-	if !WaitHealthy(90) {
-		return rollback(fmt.Errorf("新版本未在超时内达到健康状态"))
-	}
-
-	// 版本复核：确认跑起来的**确实**是新版本（而不是重启失败后旧的还在）
-	got, err := ReadBinVersion(binPath)
-	if err != nil || got.Version != nv.Version || got.Commit != nv.Commit {
-		return rollback(fmt.Errorf("版本复核不符：期望 %s/%s，实际 %v", nv.Version, ShortCommit(nv.Commit), got))
-	}
-	publishResult(bus, "kernel", "", true, curVer.Version, got.Version, false, "")
-	fmt.Printf("\n✅ 升级完成：%s (commit %s)\n", got.Version, ShortCommit(got.Commit))
-	fmt.Printf("   备份保留在 %s（确认稳定后可删）\n", backup)
-	return nil
+	return &Outcome{
+		From:      curVer,
+		To:        nv,
+		BackupDir: backup,
+	}, nil
 }

-// waitHealthy 轮询 systemd 的 active 状态。
-func WaitHealthy(seconds int) bool {
-	for i := 0; i < seconds; i++ {
-		out, err := exec.Command("systemctl", "is-active", "homeagent").Output()
-		if err == nil && strings.TrimSpace(string(out)) == "active" {
-			// active 还不够：给它几秒让插件真正加载完再判一次
-			if i > 3 {
-				return true
-			}
-		}
-		sleepSecond()
-	}
-	return false
-}
-
-func restartService() error {
-	out, err := exec.Command("systemctl", "restart", "homeagent").CombinedOutput()
-	if err != nil {
-		return fmt.Errorf("%v (%s)", err, strings.TrimSpace(string(out)))
-	}
-	return nil
+// Outcome 是一次替换的结果（**不含重启**，重启由调用方走内核控制通道）。
+type Outcome struct {
+	From      *BinVersion // 升级前版本（回滚目标）
+	To        *BinVersion // 已就位的新版本
+	BackupDir string      // 备份目录（确认稳定后可删）
 }

 func CopyFile(src, dst string) error {
@ -437,9 +407,6 @@ func NowStamp() string {
 	return time.Now().Format("20060102-150405")
 }

-// sleepSecond 隔一秒（抽出来便于将来换成可注入的等待，测试不必真睡）。
-func sleepSecond() { time.Sleep(time.Second) }
-
 // inferVersionFromRunning 在老内核不支持 --version 时，尽力推断当前版本。
 //
 // 手段按可靠性排序，任一成功即返回：
--- a/internal/update/source.go
+++ b/internal/update/source.go
@ -0,0 +1,101 @@
+package update
+
+// OTA 的**来源**解析：从 Release 自动更新，或指定本地安装包。
+//
+// ## 为什么把"来源"做成一个显式类型
+//
+// 两种来源的后半段完全一致（解包 → 预检 → 备份 → 替换 → pending），
+// 只有"包从哪来"不同。若在各入口各写一遍 if release { 下载 } else { 用路径 }，
+// 就会重演"三端三份实现慢慢漂移"的老问题。
+//
+// 所以：**来源解析一次，升级流程只有一条**。
+//
+//	Source{Kind: FromRelease}        → 查 GitHub Release → 下载 → 解包
+//	Source{Kind: FromPackage, Path}  → 直接用本地包 → 解包
+//	                        ↓
+//	                  Apply() 同一条路
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// SourceKind 是 OTA 包的来源类别。
+type SourceKind string
+
+const (
+	// FromPackage 表示"用户直接给了安装包路径"。
+	//
+	// 为什么保留它：离线机器、内网部署、灰度验证都需要先自己拿到包再升级；
+	// 而且它是**可复现**的（同一个文件升同一台机器）。
+	FromPackage SourceKind = "package"
+
+	// FromRelease 表示"从仓库最新 GitHub Release 自动取包"。
+	//
+	// 适用场景：常规运维升级，不想手工下载。
+	// ★ 拿到的是**最新 Release**，不一定是用户以为的那个版本 ——
+	//   所以 Resolve 会把 release tag 一并回报，让调用方打印出来。
+	FromRelease SourceKind = "release"
+)
+
+// Source 是一次 OTA 的包来源。
+type Source struct {
+	Kind SourceKind
+	// Path 是本地安装包路径（仅 Kind=FromPackage 时有意义）。
+	Path string
+}
+
+// ParseSource 从参数解析来源（CLI/WebAPI 共用，避免各写一套判空逻辑）。
+//
+// 规则：
+//
+//	pkg 非空          → 本地包（**优先**：显式给的路径比"自动取最新"更明确）
+//	pkg 为空 + release → 从 Release 取
+//	两者都空           → 报错（不允许"猜一个默认动作"）
+func ParseSource(pkg string, release bool) (Source, error) {
+	pkg = strings.TrimSpace(pkg)
+	switch {
+	case pkg != "":
+		return Source{Kind: FromPackage, Path: pkg}, nil
+	case release:
+		return Source{Kind: FromRelease}, nil
+	default:
+		return Source{}, fmt.Errorf("必须指定安装包路径（pkg），或选择从 Release 自动更新（release）")
+	}
+}
+
+// Resolve 把来源解析成"解包后的根目录"，供 Apply 使用。
+//
+// workDir 是调用方提供的临时目录（由调用方负责清理）。
+// 返回的 rel 仅在 Kind=FromRelease 时非 nil（携带用的是哪个 tag/资产）。
+func (s Source) Resolve(workDir string) (root string, rel *ReleaseInfo, err error) {
+	switch s.Kind {
+	case FromPackage:
+		if s.Path == "" {
+			return "", nil, fmt.Errorf("来源是本地包，但路径为空")
+		}
+		st, serr := os.Stat(s.Path)
+		if serr != nil {
+			return "", nil, fmt.Errorf("安装包不存在: %s（%v）", s.Path, serr)
+		}
+		if st.IsDir() {
+			return "", nil, fmt.Errorf("安装包是目录，不是文件: %s", s.Path)
+		}
+		root, err = ExtractPkg(s.Path, workDir)
+		return root, nil, err
+
+	case FromRelease:
+		pkgPath := filepath.Join(workDir, "release.tar.gz")
+		info, derr := DownloadLatestRelease(pkgPath)
+		if derr != nil {
+			return "", info, derr
+		}
+		root, err = ExtractPkg(pkgPath, workDir)
+		return root, info, err
+
+	default:
+		return "", nil, fmt.Errorf("未知的 OTA 来源: %q", s.Kind)
+	}
+}