installer

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: 16 Imported by: 0

Documentation

Overview

Package installer 是服务端自带的「Agent 安装源」。

为什么要自带:安装命令原先指向公开仓库 main 分支上的脚本,而公开仓库只在发版时才同步, 新脚本还没发布时用户拿到的是 404 或旧脚本(旧脚本甚至用了 bash 专有语法)。让服务端自己提供脚本与 Agent 二进制, 命令就永远和服务端版本一致,也不依赖 GitHub 是否可达。

本包只含与 HTTP 无关的部分,便于单独测试:

  • assets/install.sh、assets/install.ps1:安装脚本的唯一正本(公开库根目录的同名文件由同步脚本从这里复制);
  • Render:把本次发现窗口的票据(以及内置 HTTPS 的公钥指纹)写进脚本前导;
  • Dist:Agent 各平台二进制所在的目录,及其 checksums.txt。

票据的签发、校验与路由在 internal/terminal(它们与发现窗口的生命周期绑定)。

Index

Constants

View Source
const (
	ScriptSh  = "install.sh"
	ScriptPS1 = "install.ps1"
)

脚本文件名,同时也是下载路径的最后一段。

View Source
const ChecksumsName = "checksums.txt"

ChecksumsName 是校验文件名;格式与 sha256sum 一致("<十六进制> <文件名>"),install.sh / install.ps1 都按这个格式读取。

View Source
const RevFileName = "REV"

RevFileName 是分发目录里记录「这批 Agent 二进制的 Agent 侧代码指纹」的文件(第一行即指纹)。 它与 VERSION 同时写入(镜像构建与 scripts/build-agent-dist.sh),同样不是可分发的文件。 版本号跟着整个仓库的构建走,服务端每热更一次就变一次;指纹只在 Agent 依赖的代码真的变了才变—— 服务端据此判断主机「可升级」,而不是拿版本号一比就让所有主机亮灯(计算方式见 internal/agentrev)。

View Source
const SignatureSuffix = ".sig"

SignatureSuffix 是发布签名文件的后缀:每个 Agent 程序旁边放一个 <程序名>.sig,里面是 relsign 格式的签名文本。 签名文件不是可分发的文件(/i/ 不会发出它):服务端读到后,只在回答静默自动升级的请求时原样转交给 Agent, 由 Agent 用自己信任的公钥验证——服务端自己不持有任何公钥,也就无从替 Agent 判断签名的真假。

View Source
const VersionFileName = "VERSION"

VersionFileName 是分发目录里记录「这批 Agent 二进制是哪个版本」的文件(第一行即版本号)。 镜像构建(Dockerfile.multistage)与 scripts/build-agent-dist.sh 会写入它;它不是可分发的文件,/i/ 不会发出它。

Variables

View Source
var ErrNotFound = errors.New("installer: not found")

ErrNotFound 表示请求的文件不在分发目录里(或根本不是允许分发的名字)。

Functions

func ContentType

func ContentType(name string) string

ContentType 返回安装脚本的响应类型。两种脚本都按纯文本发送:浏览器不会渲染或执行,也避开了 MIME 嗅探。

func IsScript

func IsScript(name string) bool

IsScript 判断 name 是否是可渲染的安装脚本。

func RawScript

func RawScript(name string) ([]byte, error)

RawScript 返回内嵌脚本的原文(不含票据),供测试与公开库同步校验使用。

func Render

func Render(name string, p Prelude) ([]byte, error)

Render 读取内嵌的脚本并写入前导。

func ResolveDir

func ResolveDir(explicit string) string

ResolveDir 确定分发目录:显式配置(RELAYMESH_AGENT_DIST_DIR)优先,即使它不存在也按配置走(部署方的意图明确); 否则依次尝试可执行文件旁的 agent-dist、容器内的 /app/agent-dist 与工作目录下的 agent-dist,取第一个存在的目录。

func ValidAssetName

func ValidAssetName(name string) bool

ValidAssetName 判断 name 是否是允许分发的 Agent 二进制文件名。

func ValidHookAssetName

func ValidHookAssetName(name string) bool

ValidHookAssetName 判断 name 是否是允许分发的 hook 二进制文件名。

Types

type Asset

type Asset struct {
	Name    string
	Size    int64
	ModTime time.Time
}

Asset 描述分发目录里的一个 Agent 二进制。

func (Asset) Platform

func (a Asset) Platform() string

Platform 返回资产对应的平台标识,例如 "linux-amd64"。

type Dist

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

Dist 是 Agent 二进制的分发目录。目录由部署方提供(Docker 镜像里是 /app/agent-dist),服务端只读不写。

func NewDist

func NewDist(dir string) *Dist

NewDist 创建分发目录视图;dir 为空表示没有分发目录。目录是否存在、里面有什么,每次访问时才检查 (部署方替换二进制后无需重启服务端)。

func (*Dist) Available

func (d *Dist) Available() bool

Available 判断是否至少有一个可分发的 Agent 二进制。

func (*Dist) Checksums

func (d *Dist) Checksums() ([]byte, error)

Checksums 生成 checksums.txt 的内容。哈希按「大小 + 修改时间」缓存:文件被替换后会自动重新计算。 没有任何可分发文件时返回 ErrNotFound。

func (*Dist) Dir

func (d *Dist) Dir() string

Dir 返回分发目录路径(可能为空)。

func (*Dist) HookChecksums

func (d *Dist) HookChecksums() ([]byte, error)

HookChecksums 只包含 hook 二进制的 checksums.txt。

func (*Dist) HooksAvailable

func (d *Dist) HooksAvailable() bool

HooksAvailable 判断是否有 hook 二进制可分发。

func (*Dist) List

func (d *Dist) List() []Asset

List 列出目录里可分发的 Agent 二进制(按文件名排序)。目录不存在或不可读时返回空列表。

func (*Dist) ListHooks

func (d *Dist) ListHooks() []Asset

ListHooks 列出目录里可分发的 hook 二进制。

func (*Dist) Open

func (d *Dist) Open(name string) (*os.File, fs.FileInfo, error)

Open 打开一个 Agent 二进制。name 必须通过 ValidAssetName,调用方拿到的 *os.File 由调用方关闭。

func (*Dist) OpenHook

func (d *Dist) OpenHook(name string) (*os.File, fs.FileInfo, error)

OpenHook 打开 hook 二进制。

func (*Dist) Platforms

func (d *Dist) Platforms() []string

Platforms 返回可分发的平台标识(如 "linux-amd64"),按名称排序。

func (*Dist) Rev

func (d *Dist) Rev() string

Rev 返回分发目录里这批 Agent 的代码指纹(REV 文件的第一行,去掉首尾空白)。 文件不存在(旧镜像 / 没有写 REV 的部署)、不可读或内容不合规时返回空串——此时服务端回退到版本号比较,行为与引入指纹之前一致。

func (*Dist) Signature

func (d *Dist) Signature(name string) (string, bool)

Signature 返回 Agent 程序 name 的发布签名文本(<name>.sig 的第一行,去掉首尾空白)。 name 必须是可分发的程序名;签名文件不存在、不是普通文件、过大、不可读,或写法不合规时返回 false—— 此时这个版本按「没有签名」处理(静默自动升级不会升级到它)。

func (*Dist) Version

func (d *Dist) Version() string

Version 返回分发目录里 Agent 的版本号(VERSION 文件的第一行,去掉首尾空白)。 文件不存在、不可读或内容不合规时返回空串——此时服务端无法判断主机的 Agent 是否过旧,也就不会给出升级提醒。 结果按文件的大小与修改时间缓存:主机列表会被频繁轮询,部署方替换文件后无需重启服务端。

type Prelude

type Prelude struct {
	// Ticket 是本次发现窗口的安装票据(32 位小写十六进制)。
	Ticket string
	// SPKIPin 是内置 HTTPS 叶子证书的公钥指纹(curl --pinnedpubkey 格式);没有内置 HTTPS 时留空。
	SPKIPin string
}

Prelude 是写进脚本前导、由服务端决定的内容。所有字段在写入前都会严格校验,保证不会出现脚本注入。

Jump to

Keyboard shortcuts

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