Documentation
¶
Overview ¶
Package selfupdate 提供 Control Plane 与 Worker Node 共用的二进制在线自替换能力（FR-081，见 ADR-020 §4）。
职责三件：流式下载并 SHA-256 校验、原子替换当前可执行文件、重启自身。 完整性校验靠 SHA-256（同构制品库 ADR-011 的内容寻址校验思路）； 替换跨平台处理（Unix rename 直接换 inode，Windows 先移走运行中的旧 exe）。
Index ¶
- Constants
- Variables
- func BackupCurrent(component, currentVersion string, root *dataroot.Root) error
- func BackupCurrentFrom(component, currentVersion, srcExe string, root *dataroot.Root) error
- func Download(ctx context.Context, url, expectedSHA256, destPath string, allowInsecure bool) error
- func DownloadWith(ctx context.Context, client *http.Client, url, expectedSHA256, destPath string, ...) error
- func FileSHA256(path string) (string, error)
- func ReplaceExecutable(target, newPath string) error
- func Restart() error
- type BackupMeta
Constants ¶
const ( // ComponentControlPlane 是 Control Plane 组件标识。 ComponentControlPlane = "control-plane" // ComponentWorker 是 Worker Node 组件标识。 ComponentWorker = "worker" )
自更新组件标识（备份目录 <component> 段取值；与 controlplane service 的 Component* 取值一致）。 定义在 platform 层避免反向依赖 controlplane（架构不变量：platform 不得依赖上层包）。
Variables ¶
var ErrChecksumMismatch = errors.New("二进制 sha256 校验不符")
ErrChecksumMismatch 下载产物的 SHA-256 与期望值不符（完整性校验失败，绝不替换）。
var ErrInsecureURL = errors.New("下载源非 https 且未允许不安全下载")
ErrInsecureURL 下载源为非 https 且未显式允许（默认仅允许 https，避免中间人篡改二进制）。
var ErrNoBackup = errors.New("无可回滚的备份")
ErrNoBackup 无可回滚的备份（从未升级过 / 备份元数据缺失）。
Functions ¶
func BackupCurrent ¶
BackupCurrent 备份当前进程的可执行文件（os.Executable()）到组件备份目录（FR-182，见 ADR-042）。 currentVersion 为被备份二进制的版本号（写入 meta，回滚时回报）。升级流程在替换前调用。 每组件只留一份，再次备份覆盖上一份。
func BackupCurrentFrom ¶
BackupCurrentFrom 同 BackupCurrent，但备份指定路径 srcExe（供测试指向假二进制）。 复制（而非移动）srcExe 到 <backupDir>/binary——当前二进制仍在运行不能移走； 用「临时文件 + rename」原子落地，避免半截备份。同写 meta.json。
func Download ¶
Download 流式下载 url 到 destPath，边下边算 SHA-256，校验通过才保留。
用 http.DefaultClient 出站（不经显式代理）；生产路径应改用 DownloadWith 注入 经 httpclient.New 构造的进程级代理 client（FR-174，见 ADR-037）。本函数保留为 薄包装，向后兼容既有调用与测试。
func DownloadWith ¶
func DownloadWith(ctx context.Context, client *http.Client, url, expectedSHA256, destPath string, allowInsecure bool) error
DownloadWith 同 Download，但用调用方注入的 *http.Client 出站。
client 为 nil 时回退 http.DefaultClient。生产路径传 httpclient.New(cfg.Proxy) 构造的 进程级代理 client，使二进制下载经配置的出站代理（FR-174，见 ADR-037）。 expectedSHA256 为期望的十六进制 sha256（大小写不敏感）；为空表示跳过校验（不推荐，仅内部测试）。 allowInsecure=false 时拒绝非 https 源（ErrInsecureURL）。校验不符删除已下载文件并返回 ErrChecksumMismatch。 destPath 的父目录须已存在（调用方通常用数据根 cache/ 目录）。
func FileSHA256 ¶
FileSHA256 计算文件的十六进制 SHA-256（小写）。供测试与校验复用。
func ReplaceExecutable ¶
ReplaceExecutable 用 newPath 处的新二进制原子替换 target 处的可执行文件。
target 通常是 os.Executable() 返回的当前进程可执行文件。 Unix：直接 rename（替换 inode；正在运行的进程持有旧 inode 不受影响）。 Windows：运行中的 exe 不能被覆盖/删除，先把 target 改名为 target.old，再把 newPath 落到 target。 替换在同目录内进行以保证 rename 为原子操作（跨卷 rename 会失败）。
Types ¶
type BackupMeta ¶
type BackupMeta struct {
// Version 是备份时的（被备份二进制的）版本号——回滚后即回报为「回滚到的版本」。
Version string `json:"version"`
// SHA256 是备份二进制的十六进制 sha256（小写）；回滚前据此校验备份未被损坏。
SHA256 string `json:"sha256"`
// BackedUpAt 是备份发生的时间。
BackedUpAt time.Time `json:"backedUpAt"`
}
BackupMeta 描述一份升级前备份的元数据（落 meta.json）。
func BackupInfo ¶
func BackupInfo(component string, root *dataroot.Root) (BackupMeta, bool)
BackupInfo 只读查组件备份元数据；无备份（meta.json 缺失/损坏）返回 (零值, false)。 供「检查更新」透出 backupVersion 与前端判定回滚按钮可用性。
func Rollback ¶
func Rollback(component string, root *dataroot.Root) (BackupMeta, error)
Rollback 把当前进程的可执行文件换回组件备份（FR-182，见 ADR-042）。 流程：读 meta（无 → ErrNoBackup）→ 校验备份二进制 sha256 与 meta 一致（防损坏）→ 复制备份到临时文件 → ReplaceExecutable 换回 → 返回 meta（含回滚到的版本）。 不在此重启——与升级一致，替换成功后由调用方异步延迟重启。
func RollbackTo ¶
func RollbackTo(component, target string, root *dataroot.Root) (BackupMeta, error)
RollbackTo 同 Rollback，但替换指定目标 target（供测试指向假二进制）。
Source Files