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
- Variables
- func Compute(root string) (string, error)
- func ComputeDirs(root string, dirs []string) (string, error)
- func Files(root string, dirs []string) ([]string, error)
- func GOOSFromDescription(desc string) string
- func GOOSFromPlatform(plat string) string
- func IsKnownSystem(s string) bool
- func NormalizeBump(in []string) ([]string, error)
- func ParseBump(s string) ([]string, error)
- type Entry
- type History
- func (h *History) Append(e Entry) error
- func (h *History) Between(goos, from, to string) (Span, bool)
- func (h *History) Entries() []Entry
- func (h *History) Has(rev string) bool
- func (h *History) Index(rev string) (int, bool)
- func (h *History) Last() (Entry, bool)
- func (h *History) Len() int
- func (h *History) Level(goos, rev string) (int, bool)
- func (h *History) Marshal() []byte
- func (h *History) WriteFile(path string) error
- type Span
Constants ¶
const ( SystemAll = "all" SystemNone = "none" SystemWindows = "windows" SystemLinux = "linux" SystemDarwin = "darwin" )
登记表里 bump 的取值:all(所有系统)、none(无需升级)或 windows / linux / darwin 的任意组合。
const HistoryFile = "internal/agentrev/history.json"
HistoryFile 是登记表相对模块根的路径。
const Length = 12
Length 是指纹的十六进制长度。
const MaxNoteRunes = 160
MaxNoteRunes 是一行说明的字数上限:它会原样显示在主机卡片的悬停里。
Variables ¶
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 ComputeDirs ¶
ComputeDirs 与 Compute 相同,但目录清单由调用方给出(测试用)。
func Files ¶
Files 返回参与指纹的文件(相对模块根、斜杠分隔、按路径排序):go.mod / go.sum,以及各目录下的非测试 .go 文件。 所有平台的文件都计入(含 _windows.go 之类),所以同一份源码在任何平台上算出同一个指纹。
func GOOSFromDescription ¶ added in v2.2.0
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
GOOSFromPlatform 从 Agent 握手里的平台名(「linux-amd64」这样的 GOOS-GOARCH)取出系统;不认识返回空串。
func IsKnownSystem ¶ added in v2.2.0
IsKnownSystem 判断 s 是不是 bump 里能写的系统名(不含 all / none)。
func NormalizeBump ¶ added in v2.2.0
NormalizeBump 校验并规范 bump:不能为空;all / none 必须单独出现;其余必须是已知系统且不重复;顺序固定为 windows、linux、darwin。
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 是登记表的一行。
type History ¶ added in v2.2.0
type History struct {
// contains filtered or unexported fields
}
History 是解析并校验过的登记表。零值是一张空表。
func LoadEmbedded ¶ added in v2.2.0
LoadEmbedded 解析编进二进制的登记表(Hub 用它判断主机要不要升级)。
func LoadHistoryFile ¶ added in v2.2.0
LoadHistoryFile 读取并解析磁盘上的登记表。
func ParseHistory ¶ added in v2.2.0
ParseHistory 解析并校验登记表:每一行合规、指纹不重复。空表合法(Hub 会回退到只比指纹 / 版本号)。
func (*History) Between ¶ added in v2.2.0
Between 算 goos 这个系统从 from 走到 to 要经过的行。任何一边没登记返回 false(调用方必须回退到只比指纹 / 版本号)。
func (*History) Level ¶ added in v2.2.0
Level 是 goos 这个系统在 rev 这一行的级别:表里到这一行为止、对它生效的行数。指纹没登记返回 false。
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
NeedsUpgrade 说明按级别算这个系统是否需要升级:升级方向上,至少有一行对它生效。