agentrev

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package agentrev 计算「Agent 侧代码指纹」(AgentRev)。

背景(#124 / #143):整个仓库只有一个构建版本号,服务端每热更一次它就变一次;而 Agent 二进制只依赖少数几个包, 这些包没有变化时,不同版本号的 Agent 行为完全一样。拿版本号判断「可升级」,就会在每次服务端热更后让所有主机亮灯, 升级之后也看不出守护进程是否需要重启。

指纹是这些包的非测试源文件加上 go.mod / go.sum 的内容哈希:Agent 侧的代码真的变了,它才会变。 构建 Agent 时由 -X main.rev 注入;分发目录里的 REV 文件记录同一个值,服务端据此判断「可升级」。

设计约束:

  • 只看文件内容与相对路径,不依赖 git、不依赖构建机的 Go 版本,所以在 Docker 构建上下文(没有 .git)里也能得到同一个值;
  • 换行统一成 \n 再哈希,Windows 检出(CRLF)与 Linux 检出得到同一个值;
  • 目录清单是静态的,覆盖是否完整由测试用 go list 在全部发布平台上核对(见 agentrev_test.go),清单漏项会让测试失败。

Index

Constants

View Source
const (
	SystemAll     = "all"
	SystemNone    = "none"
	SystemWindows = "windows"
	SystemLinux   = "linux"
	SystemDarwin  = "darwin"
)

登记表里 bump 的取值:all(所有系统)、none(无需升级)或 windows / linux / darwin 的任意组合。

View Source
const HistoryFile = "internal/agentrev/history.json"

HistoryFile 是登记表相对模块根的路径。

View Source
const Length = 12

Length 是指纹的十六进制长度。

View Source
const MaxNoteRunes = 160

MaxNoteRunes 是一行说明的字数上限:它会原样显示在主机卡片的悬停里。

Variables

View Source
var Dirs = []string{
	"cmd/relaymesh-agent",
	"internal/agent",
	"internal/agent/cli",
	"internal/agent/files",
	"internal/agent/guiwake",
	"internal/agent/holder",
	"internal/agent/ptyhost",
	"internal/agent/record",
	"internal/agent/runlog",
	"internal/agent/sshcred",
	"internal/buildinfo",
	"internal/relsign",
	"internal/relsign/trust",
	"internal/secure",
	"internal/sshexec",
	"internal/termproto",
	"internal/termstate",
}

Dirs 是 Agent 二进制(cmd/relaymesh-agent)在所有发布平台上依赖的、本模块内的包目录(相对模块根,不含子目录)。 Agent 新增依赖而没有更新这份清单时,agentrev_test.go 里的覆盖测试会失败——这是它唯一的防漏机制,不要绕过。

Functions

func Compute

func Compute(root string) (string, error)

Compute 计算模块根 root 下的 Agent 侧代码指纹(Length 位小写十六进制)。

func ComputeDirs

func ComputeDirs(root string, dirs []string) (string, error)

ComputeDirs 与 Compute 相同,但目录清单由调用方给出(测试用)。

func Files

func Files(root string, dirs []string) ([]string, error)

Files 返回参与指纹的文件(相对模块根、斜杠分隔、按路径排序):go.mod / go.sum,以及各目录下的非测试 .go 文件。 所有平台的文件都计入(含 _windows.go 之类),所以同一份源码在任何平台上算出同一个指纹。

func GOOSFromDescription added in v2.2.0

func GOOSFromDescription(desc string) string

GOOSFromDescription 从主机上报的系统描述推出系统;不认识返回空串。

Agent 握手里的 os 是给人看的描述,不是 GOOS:Linux 上是 /etc/os-release 的 PRETTY_NAME(「Ubuntu 24.04.2 LTS」、 「Debian GNU/Linux 12 (bookworm)」),macOS 是「macOS 14.5」,Windows 是「windows」。已经装好的旧 Agent 不会再多报一个 GOOS, 所以只能从描述归一。规则与前端 hostGOOS(frontend/src/lib/terminal/upgrade.ts)一致:认出 Windows / macOS 的写法, 单个词又不是这三种的(freebsd 之类)视为不认识,其余描述(多个词的发行版名)按 Linux。

func GOOSFromPlatform added in v2.2.0

func GOOSFromPlatform(plat string) string

GOOSFromPlatform 从 Agent 握手里的平台名(「linux-amd64」这样的 GOOS-GOARCH)取出系统;不认识返回空串。

func IsKnownSystem added in v2.2.0

func IsKnownSystem(s string) bool

IsKnownSystem 判断 s 是不是 bump 里能写的系统名(不含 all / none)。

func NormalizeBump added in v2.2.0

func NormalizeBump(in []string) ([]string, error)

NormalizeBump 校验并规范 bump:不能为空;all / none 必须单独出现;其余必须是已知系统且不重复;顺序固定为 windows、linux、darwin。

func ParseBump added in v2.2.0

func ParseBump(s string) ([]string, error)

ParseBump 把「windows,linux」这样的命令行写法拆成 bump(逗号分隔,忽略空白与大小写)。

Types

type Entry added in v2.2.0

type Entry struct {
	// Rev 是这一行登记的代码指纹(Length 位小写十六进制)。
	Rev string `json:"rev"`
	// Bump 说明这次改动要让哪些系统升级:["all"]、["none"],或 windows / linux / darwin 的组合。
	Bump []string `json:"bump"`
	// Note 是一句话说明:对要升级的系统,它是「升级后得到什么」;对无需升级的,它说明为什么无需升级。
	Note string `json:"note"`
	// At 是这次改动的日期(YYYY-MM-DD,可省略)。
	At string `json:"at,omitempty"`
}

Entry 是登记表的一行。

func (Entry) Applies added in v2.2.0

func (e Entry) Applies(goos string) bool

Applies 说明这一行对 goos 这个系统是否要升级。goos 不认识(空或 freebsd 之类)时按最保守的算:只要这一行不是 none 就算要升级, 宁可多提醒一次,也不要让一台说不清系统的主机漏掉升级。

type History added in v2.2.0

type History struct {
	// contains filtered or unexported fields
}

History 是解析并校验过的登记表。零值是一张空表。

func LoadEmbedded added in v2.2.0

func LoadEmbedded() (*History, error)

LoadEmbedded 解析编进二进制的登记表(Hub 用它判断主机要不要升级)。

func LoadHistoryFile added in v2.2.0

func LoadHistoryFile(path string) (*History, error)

LoadHistoryFile 读取并解析磁盘上的登记表。

func ParseHistory added in v2.2.0

func ParseHistory(data []byte) (*History, error)

ParseHistory 解析并校验登记表:每一行合规、指纹不重复。空表合法(Hub 会回退到只比指纹 / 版本号)。

func (*History) Append added in v2.2.0

func (h *History) Append(e Entry) error

Append 把一行登记到表的末尾(校验与解析时相同);指纹已登记会报错。

func (*History) Between added in v2.2.0

func (h *History) Between(goos, from, to string) (Span, bool)

Between 算 goos 这个系统从 from 走到 to 要经过的行。任何一边没登记返回 false(调用方必须回退到只比指纹 / 版本号)。

func (*History) Entries added in v2.2.0

func (h *History) Entries() []Entry

Entries 返回全部行的副本(按登记顺序,旧的在前)。

func (*History) Has added in v2.2.0

func (h *History) Has(rev string) bool

Has 说明指纹是否已登记。

func (*History) Index added in v2.2.0

func (h *History) Index(rev string) (int, bool)

Index 返回指纹在表里的位置(从 0 起);没登记返回 false。

func (*History) Last added in v2.2.0

func (h *History) Last() (Entry, bool)

Last 返回最后一行(空表返回 false)。

func (*History) Len added in v2.2.0

func (h *History) Len() int

Len 是已登记的行数。

func (*History) Level added in v2.2.0

func (h *History) Level(goos, rev string) (int, bool)

Level 是 goos 这个系统在 rev 这一行的级别:表里到这一行为止、对它生效的行数。指纹没登记返回 false。

func (*History) Marshal added in v2.2.0

func (h *History) Marshal() []byte

Marshal 输出规范的 JSON:一行一条,追加一行只会在 diff 里多一行。

func (*History) WriteFile added in v2.2.0

func (h *History) WriteFile(path string) error

WriteFile 把登记表原子地写到 path(先写临时文件再改名,写到一半不会留下损坏的表)。

type Span added in v2.2.0

type Span struct {
	// Forward 为 true 表示 to 在表里排在 from 之后(from → to 是升级的方向);
	// false 表示两者是同一行,或 to 排在 from 之前(主机比服务端自带的更新,例如服务端回退过)。
	Forward bool
	// Gains 是 (from, to] 里对这个系统要升级的行(旧的在前):升级之后得到的东西。
	Gains []Entry
	// Skipped 是 (from, to] 里对这个系统无需升级的行(旧的在前)。
	Skipped []Entry
}

Span 是从一个指纹走到另一个指纹之间、登记表里的那几行。

func (Span) NeedsUpgrade added in v2.2.0

func (s Span) NeedsUpgrade() bool

NeedsUpgrade 说明按级别算这个系统是否需要升级:升级方向上,至少有一行对它生效。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL