agent

package
v2.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package agent 实现 RelayMesh 终端 Agent:运行在被管理主机上的常驻进程, 主动连接 Hub(服务端)的通用入口,按需在本机的伪终端里运行 shell,并把它安全地中继给 Web 浏览器。

关键性质:

  • 伪终端由「会话守护进程」(internal/agent/holder)持有:外置模式下它是独立进程,Agent 升级、重启乃至崩溃都不会 打断会话;内嵌模式(Windows 临时启动、`--holder=embedded`)下它与 Agent 同进程,会话随进程结束,且会如实标注;
  • 伪终端的寿命只取决于守护进程自身、显式 kill 与 TTL,绝不取决于网络连接(INV-P1);
  • 身份是 Ed25519 密钥,机器码由公钥派生;服务端只存公钥,没有任何可冒充主机的秘密;
  • Agent 必须验证服务端(系统 CA / --pin 指纹 / TOFU),失败即关闭,绝不降级为明文;
  • 限额由守护进程自己强制执行,服务端策略只能收紧。

Index

Constants

View Source
const AgentWSPath = "/api/v1/terminal/agent/ws"

AgentWSPath 是 Hub 上通用 Agent 入口的路径。

Variables

View Source
var ErrNoIdentity = errors.New("identity file does not exist")

ErrNoIdentity 表示持久身份文件不存在。

View Source
var Rev = ""

Rev 是这个二进制的「Agent 侧代码指纹」(见 internal/agentrev、termproto.ValidAgentRev),构建时通过 -ldflags "-X main.rev=…" 注入后由 main 赋值;空表示非发布构建,此时服务端回退到版本号比较。

View Source
var Version = "dev"

Version 是 Agent 的版本号,独立二进制构建时通过 -ldflags "-X github.com/teacat99/RelayMesh/v2/internal/agent.Version=…" 注入。

Functions

func AutoAttemptsPath

func AutoAttemptsPath(dataDir string) string

AutoAttemptsPath 是尝试记录的路径(与升级相关的其他文件放在一起)。

func AutoCheckNotePath

func AutoCheckNotePath(dataDir string) string

AutoCheckNotePath 是检查结果文件的路径(与升级相关的其他文件放在一起)。

func AutoUpgradeMode

func AutoUpgradeMode(dataDir string) string

AutoUpgradeMode 返回握手里声明的模式:已开启时是 notify / silent,否则是 off。

func AutoUpgradePath

func AutoUpgradePath(dataDir string) string

AutoUpgradePath 是同意文件的路径。

func ClearAutoAttempts

func ClearAutoAttempts(dataDir string) error

ClearAutoAttempts 清掉尝试记录(所有者重新 enable、或收回同意时)。文件不存在不算错。

func DefaultConfigDir

func DefaultConfigDir() string

DefaultConfigDir 返回服务配置与已信任服务器指纹(known_servers)的默认目录。

func DefaultDataDir

func DefaultDataDir() string

DefaultDataDir 返回身份文件等持久数据的默认目录(按是否以管理员权限运行区分)。

Linux  root : /var/lib/relaymesh-agent          普通用户: $XDG_STATE_HOME 或 ~/.local/state 下的 relaymesh-agent
macOS  root : /Library/Application Support/RelayMesh Agent   普通用户: ~/Library/Application Support/RelayMesh Agent
Windows 管理员: %ProgramData%\RelayMesh\Agent    普通用户: %LocalAppData%\RelayMesh\Agent

func Fingerprint

func Fingerprint(der []byte) string

Fingerprint 返回证书(DER)的 SHA-256 指纹,格式 "sha256:<小写十六进制>"。

func HardenDir

func HardenDir(dir string) error

HardenDir 把目录收紧为仅本人(与管理员 / SYSTEM)可访问:Unix 由创建时的 0700 保证,Windows 设置私有 ACL。 会话守护进程的目录(状态文件与本地套接字)靠它防止其他用户接入。

func HostMeta

func HostMeta(version, kind string) termproto.Meta

HostMeta 收集握手时自报的主机信息。它们全部是「不可信自报字段」,服务端会净化并只按纯文本展示, 仅用于让管理员在启用时辨认主机——真正的身份是公钥。

func IdentityPath

func IdentityPath(dir string) string

IdentityPath 返回 dir 下持久身份文件的路径。

func IsElevated

func IsElevated() bool

IsElevated 报告是否以 root 身份运行。

func NormalizePin

func NormalizePin(s string) (string, error)

NormalizePin 接受 "sha256:AB:CD…" / "AB:CD…" / 纯十六进制,统一成 "sha256:<小写十六进制>"。

func PrivLevel

func PrivLevel() string

PrivLevel 返回自报的特权等级:root、admin(属于管理员组,可提权)或 user。

func ReadUpgradeNote

func ReadUpgradeNote(dataDir string) *termproto.UpgradeNote

ReadUpgradeNote 读取上一次升级的结果(已净化);没有或损坏时返回 nil。

func RecordAutoAttempt

func RecordAutoAttempt(dataDir, version string, now time.Time) error

RecordAutoAttempt 记一次「对 version 开始静默升级」。同一个版本累加,换了版本从 1 重新数。 要在开始下载之前写好:Agent 在升级中途崩溃、或升级后被还原重启,这次尝试也不会丢。

func RemoveAutoCheckNote

func RemoveAutoCheckNote(dataDir string) error

RemoveAutoCheckNote 删除检查结果(收回同意时一并清掉,免得 status 以后还展示一份过期的结果)。文件不存在不算错。

func RemoveAutoUpgrade

func RemoveAutoUpgrade(dataDir string) error

RemoveAutoUpgrade 收回同意。文件本来就不存在不算错。

func RemoveIdentity

func RemoveIdentity(dir string) error

RemoveIdentity 删除 dir 下的持久身份文件(文件不存在不算错误)。

func RemoveOnlineMarker

func RemoveOnlineMarker(dataDir string)

RemoveOnlineMarker 删除上线标记(升级进程在重启服务之前清掉旧标记,避免把旧版本留下的标记当成新版本上线)。

func SetWebUpgradeAllowed

func SetWebUpgradeAllowed(dataDir string, on bool) error

SetWebUpgradeAllowed 打开或关闭开关。关闭时文件本来就不存在不算错。

func StagedBinaryPath

func StagedBinaryPath(dataDir string) string

StagedBinaryPath 是下载并校验过的新版本的存放路径。

func UpgradeDir

func UpgradeDir(dataDir string) string

UpgradeDir 是升级相关文件(下载的新版本、上线标记、结果)所在的目录。

func WebUpgradeAllowed

func WebUpgradeAllowed(dataDir string) bool

WebUpgradeAllowed 报告主机所有者是否允许从 Web 升级:开关文件存在且是普通文件。 每次都现读,不缓存——所有者随时可以用 `web-upgrade off` 收回。

func WebUpgradeFlagPath

func WebUpgradeFlagPath(dataDir string) string

WebUpgradeFlagPath 是「允许从 Web 升级」开关文件的路径。

func WriteAutoCheckNote

func WriteAutoCheckNote(dataDir string, n AutoCheckNote) error

WriteAutoCheckNote 保存最近一次检查的结果。

func WriteAutoUpgrade

func WriteAutoUpgrade(dataDir string, cfg AutoUpgradeConfig) error

WriteAutoUpgrade 写入同意(先写临时文件再改名,读的一方不会看到写了一半的内容)。

func WriteOnlineMarker

func WriteOnlineMarker(dataDir, version string, now time.Time) error

WriteOnlineMarker 记下「本 Agent(version)已经与 Hub 握手成功」。

func WriteUpgradeNote

func WriteUpgradeNote(dataDir string, n termproto.UpgradeNote) error

WriteUpgradeNote 保存上一次升级的结果。

Types

type Agent

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

Agent 是终端 Agent 的运行实例。

func New

func New(opts Options) (*Agent, error)

New 校验参数并创建 Agent。

func (*Agent) MachineCode

func (a *Agent) MachineCode() string

MachineCode 返回本机的机器码。

func (*Agent) Manager

func (a *Agent) Manager() *Manager

Manager 返回内嵌模式下的会话管理器(主要供测试观察;外置守护进程模式下为 nil)。

func (*Agent) Run

func (a *Agent) Run(ctx context.Context) error

Run 保持与 Hub 的连接直到 ctx 被取消:断线自动重连,会话在重连期间继续运行。 内嵌模式下返回时已终止全部会话(PTY 的寿命不超过 Agent 进程);外置守护进程模式下会话由守护进程继续持有。

func (*Agent) SessionsOutliveAgent

func (a *Agent) SessionsOutliveAgent() bool

SessionsOutliveAgent 报告会话是否由外置守护进程持有(Agent 退出后仍在运行)。auto 模式在 Run 开始后才有确定答案。

type AutoAttempts

type AutoAttempts struct {
	Version string `json:"version"`
	Count   int    `json:"count"`
	// At 是最近一次尝试的 Unix 秒,只用于展示。
	At int64 `json:"at,omitempty"`
	// Unreadable 表示记录文件存在但读不清:按「已经试满」处理(不写进文件)。
	Unreadable bool `json:"-"`
}

AutoAttempts 记录「对哪个版本已经开始过几次静默升级」。

func ReadAutoAttempts

func ReadAutoAttempts(dataDir string) AutoAttempts

ReadAutoAttempts 读取尝试记录。文件不存在是「没有试过」;存在但不是合规的内容则标记 Unreadable, 交给调用方按「已经试满」处理——宁可停下,也不要因为记录坏了而无限重试。

func (AutoAttempts) Paused

func (a AutoAttempts) Paused(version string) bool

Paused 判断对 version 是否已经停止尝试:同一个版本试满次数,或记录本身读不清。

type AutoCheckNote

type AutoCheckNote struct {
	// At 是检查完成的 Unix 秒(本机时钟)。
	At int64 `json:"at"`
	// Status 是 Hub 的回答(termproto.AutoOffer*)或 autoCheckNoReply。
	Status string `json:"status"`
	// Latest 是 Hub 上最新的 Agent 版本(回答里有时才有);Current 是检查时本机的版本。
	Latest  string `json:"latest,omitempty"`
	Current string `json:"current,omitempty"`
	// Install 与 Detail 只有静默模式才有:这一轮检查之后,静默升级做了什么决定(autoInstall*)以及原因的一句话说明。
	Install string `json:"install,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

AutoCheckNote 是最近一次自动升级检查的结果,写在数据目录里,供 `auto-upgrade status` 在本机展示。

func ReadAutoCheckNote

func ReadAutoCheckNote(dataDir string) (AutoCheckNote, bool)

ReadAutoCheckNote 读取最近一次检查的结果;不存在、过大或损坏时返回 false。

type AutoSettings

type AutoSettings struct {
	// Mode 是 notify 或 silent。
	Mode string
	// Window 是允许开始升级的时间段;WindowText 是它的原文(不限为空)。
	Window     AutoWindow
	WindowText string
	// TrustKeys 是主机所有者钉住的公钥(已解析、已去重)。完整的信任名单还要加上编进程序的公钥,见 Keys。
	TrustKeys []ed25519.PublicKey
	// Problem 非空表示设置文件里有读不懂的内容(时间段写法不对、公钥无法解析、公钥太多)。
	// 静默安装遇到它一律不做——读不清楚的时候必须落在不升级的一侧。
	Problem string
}

AutoSettings 是读出来之后经过校验的静默升级设置。

func ReadAutoSettings

func ReadAutoSettings(dataDir string) (AutoSettings, bool)

ReadAutoSettings 读取并整理同意文件;没有同意(或读不清)时第二个返回值为 false。

func (AutoSettings) Keys

func (s AutoSettings) Keys() []ed25519.PublicKey

Keys 是静默升级的完整信任名单:编进程序的发布公钥,加上主机所有者钉住的公钥,按密钥标识去重。 名单为空时静默模式没有任何办法验证新版本,所以既不能开启也不会安装。

type AutoUpgradeConfig

type AutoUpgradeConfig struct {
	// Mode 是 termproto.AutoUpgradeNotify 或 termproto.AutoUpgradeSilent。
	Mode string `json:"mode"`
	// At 是写入时刻(Unix 秒),只用于 `auto-upgrade status` 展示。
	At int64 `json:"at,omitempty"`
	// Window 是静默升级允许开始的时间段(HH:MM-HH:MM,主机本地时间);空表示不限。只对静默模式有意义。
	Window string `json:"window,omitempty"`
	// TrustKeys 是主机所有者钉住的发布公钥(rmpub1:…):与编进程序的公钥一起构成静默升级的信任名单。
	// 只对静默模式有意义;Hub 既不能读到它,也无法添加。
	TrustKeys []string `json:"trust_keys,omitempty"`
}

AutoUpgradeConfig 是主机所有者对「自动升级」的同意。

func ReadAutoUpgrade

func ReadAutoUpgrade(dataDir string) (AutoUpgradeConfig, bool)

ReadAutoUpgrade 读取同意。文件不存在、不是普通文件、过大、不是合规的 JSON、模式不认识,一律视为「没有同意」(false): 自动升级是一项会改动程序的能力,读不清楚的时候必须落在关闭的一侧。

func (AutoUpgradeConfig) Settings

func (c AutoUpgradeConfig) Settings() AutoSettings

Settings 把同意文件的内容整理成可用的设置;写法不对的地方记在 Problem 里,而不是悄悄忽略。

type AutoWindow

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

AutoWindow 是静默自动升级允许「开始」的时间段:主机本地时间、24 小时制、精确到分钟,可以跨午夜(23:00-02:00)。 零值表示不限。时间段只约束「什么时候开始一次升级」;开始之后的下载与安装不会因为时间段结束而被放弃—— 升级做到一半被打断,比稍微超出时间段更糟。

func ParseAutoWindow

func ParseAutoWindow(s string) (AutoWindow, error)

ParseAutoWindow 解析 HH:MM-HH:MM。空串是「不限」;起止相同的写法含义含糊(是整天还是一分钟都没有),一律拒绝。

func (AutoWindow) Always

func (w AutoWindow) Always() bool

Always 表示不限时间。

func (AutoWindow) Contains

func (w AutoWindow) Contains(t time.Time) bool

Contains 判断 t(按它自己的时区取时钟)是否落在时间段内:起点含、终点不含。

func (AutoWindow) String

func (w AutoWindow) String() string

String 还原成 HH:MM-HH:MM;不限时为空串。

func (AutoWindow) UntilOpen

func (w AutoWindow) UntilOpen(t time.Time) time.Duration

UntilOpen 返回距离时间段下一次开始还有多久;此刻已在时间段内(或不限)返回 0。 只按时钟读数推算,不处理夏令时跳变:调用方睡醒之后会重新判断,差一个小时也只是多睡一次。

type Event

type Event struct {
	State  State
	Detail string
	// Code 是对端的 WebSocket 关闭码(没有则为 0)。
	Code int
	// Retry 在 StateRetrying 时给出下次重试前的等待时间。
	Retry time.Duration
}

Event 描述一次状态变化。

type FileOptions

type FileOptions struct {
	// AllowPrivateURLs 允许 push_url 访问回环 / 私网 / 链路本地地址(默认不允许,防止借这台主机探测内网或元数据服务)。
	// 只有这台主机的拥有者能在本机启动参数里打开它,服务端无法设置。
	AllowPrivateURLs bool
}

FileOptions 是文件能力的本机选项。本机只有两个旋钮:一票否决(Options.Exec.DenyExec,与模型执行共用)和这里的网址范围。

type HolderMode

type HolderMode string

HolderMode 决定终端会话由谁持有。

const (
	// HolderEmbedded 让会话运行在 Agent 进程内:行为与最初的实现一致,会话随进程结束,不具持久性。
	// 它也是 Options 的零值——库与测试不会意外去连接机器上真实的守护进程。
	HolderEmbedded HolderMode = "embedded"
	// HolderExternal 只使用外置守护进程;连不上就报告「不可用」并重试,绝不静默退化为内嵌
	// (那会产生不持久的会话,还可能与守护进程里的会话重复)。
	HolderExternal HolderMode = "external"
	// HolderAuto 启动时能连上外置守护进程就用它,否则使用内嵌模式。
	HolderAuto HolderMode = "auto"
)

func ParseHolderMode

func ParseHolderMode(s string) (HolderMode, error)

ParseHolderMode 解析 --holder 选项的取值。

type Identity

type Identity struct {
	Priv ed25519.PrivateKey
	Pub  ed25519.PublicKey
	// Kind 是 persistent(存盘,重启后机器码不变)或 temporary(仅内存,每次运行都不同)。
	Kind string
	// Path 是持久身份的文件路径(临时身份为空)。
	Path string
	// Created 表示这次调用新生成了密钥(首次运行)。
	Created bool
}

Identity 是 Agent 的身份:一对 Ed25519 密钥。机器码由公钥派生,服务端只保存公钥, 因此「知道机器码」不等于「能冒充该主机」——冒充需要私钥。

func LoadIdentity

func LoadIdentity(dir string) (*Identity, error)

LoadIdentity 读取 dir 下的持久身份;不存在时返回 ErrNoIdentity。

func LoadOrCreateIdentity

func LoadOrCreateIdentity(dir string) (*Identity, error)

LoadOrCreateIdentity 读取持久身份,不存在则生成并安全地写盘(首次运行时才生成,绝不随镜像分发)。

func NewTemporaryIdentity

func NewTemporaryIdentity() (*Identity, error)

NewTemporaryIdentity 生成仅存于内存的临时身份:进程退出即消失,下次运行机器码不同,需要重新启用。

func ResetIdentity

func ResetIdentity(dir string) (*Identity, error)

ResetIdentity 丢弃现有持久身份并重新生成(机器码随之改变,需要在 Web 上重新启用)。

func (*Identity) MachineCode

func (i *Identity) MachineCode() string

MachineCode 返回由公钥派生的机器码。

type KnownServers

type KnownServers struct {
	Path string
	// contains filtered or unexported fields
}

KnownServers 是 TOFU 的指纹记录:每行 "host:port sha256:<hex>"。

func (*KnownServers) Add

func (k *KnownServers) Add(host, fp string) error

Add 追加一条记录(原子写入,文件权限 0600)。

func (*KnownServers) Lookup

func (k *KnownServers) Lookup(host string) (fp string, found bool, err error)

Lookup 查询主机的已信任指纹。

type Limits

type Limits = holder.Limits

Limits 与 ShellFunc 的实现在 holder 包里(会话由守护进程持有);这里保留别名, 让命令行与测试沿用 agent.Limits / agent.DefaultLimits 这些名字。

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits 返回默认限额。

type Manager

type Manager = holder.Manager

Manager 是会话管理器(内嵌模式下由 Agent 自己持有)。

type OnlineMarker

type OnlineMarker struct {
	Version string `json:"version"`
	PID     int    `json:"pid"`
	// At 是写入时刻(Unix 秒)。
	At int64 `json:"at"`
}

OnlineMarker 是新版本 Agent 握手成功后留下的标记。

func ReadOnlineMarker

func ReadOnlineMarker(dataDir string) (OnlineMarker, bool)

ReadOnlineMarker 读取上线标记;不存在或损坏时返回 false。

type Options

type Options struct {
	Server   ServerTarget
	Trust    TrustOptions
	Identity *Identity
	// Version 自报的 Agent 版本;空则使用包级 Version。
	Version string
	// Rev 自报的 Agent 侧代码指纹;空则使用包级 Rev(仍为空表示非发布构建)。
	Rev    string
	Limits Limits
	Logf   func(format string, args ...any)
	// OnEvent 在状态变化时被同步调用,必须快速返回。
	OnEvent func(Event)

	// Holder 决定会话由谁持有,零值为内嵌(见 HolderMode)。
	Holder HolderMode
	// HolderSocket 是外置守护进程的本地套接字路径(external / auto 必填)。
	HolderSocket string

	// Record 是终端记录(终端上显示什么就记录什么,只写在本机)的配置。Record.Dir 为空则不提供记录与历史读取。
	// 内嵌模式下由 Agent 自己写入该目录;外置模式下由守护进程写入,Agent 只读。
	// Record.Disabled 是本机的一票否决(--no-record)。
	Record record.Options

	// Exec 是模型执行(非交互命令运行)的配置。Exec.DenyExec 是本机的一票否决(--deny-model-exec):
	// 内嵌模式下由 Agent 自己执行;外置模式下命令由守护进程执行,但 Agent 同样会拦下被否决的请求,
	// 所以无论在哪一侧设置,否决都生效。Exec.Dir 为空表示本机不能执行模型命令。
	Exec holder.ExecOptions

	// Files 是文件能力(模型经 MCP 查看 / 拉取 / 写入文件)的本机选项。文件能力同样受 Exec.DenyExec 一票否决。
	Files FileOptions

	// SSH 非 nil 表示本机开启了 SSH 网关(--ssh-gateway)。内嵌模式下由 Agent 自己的会话宿主承担;
	// 外置模式下是守护进程(holder run --ssh-gateway)去连接 SSH 目标,Agent 只转发帧,这里的值不起作用。
	SSH *holder.SSHOptions

	// SelfUninstall 非 nil 表示这个 Agent 是以常驻服务运行、并且知道如何卸载自己:
	// 管理员删除主机并勾选「同时卸载设备端」时,Hub 会发来 uninstall 帧,Agent 调用它在本机另起一个与自身进程树无关的卸载进程
	// (purge 对应 --purge)。返回 nil 表示卸载进程已成功启动(卸载本身随后异步完成,会停止本 Agent);
	// 返回错误则什么都没有发生,Agent 继续正常运行。前台运行 / 临时身份 / 暂不支持的系统保持 nil。
	SelfUninstall func(purge bool) error

	// SelfUpgrade 非 nil 表示这个 Agent 是以常驻服务运行、知道如何把升级交给一个与自身进程树无关的升级进程:
	// 握手时声明「Web 升级」能力(所有者在本机允许了才是 on),收到 Hub 的 upgrade 帧后下载、校验并交接。
	// 前台运行 / 临时身份 / 暂不支持的系统保持 nil,不声明能力。见 webupgrade.go。
	SelfUpgrade *SelfUpgrade

	// 以下字段供测试注入。
	Spawner ptyhost.Spawner
	Shell   ShellFunc

	// 重试节奏(零值取默认):网络类错误指数退避 MinBackoff→MaxBackoff;
	// 握手无效 / 总闸关闭 / 发现关闭等取 SlowRetry;被停用取 DisabledRetry。
	MinBackoff    time.Duration
	MaxBackoff    time.Duration
	SlowRetry     time.Duration
	DisabledRetry time.Duration
	// Jitter 给等待时间加抖动;默认 ±20%。
	Jitter func(time.Duration) time.Duration
}

Options 是 Agent 的运行参数。

type SelfUpgrade

type SelfUpgrade struct {
	// Allowed 报告主机所有者是否允许从 Web 升级(每次现读,不缓存)。
	Allowed func() bool
	// StageDir 是下载新版本的目录;不存在会被创建(0700)。
	StageDir string
	// Handoff 把已校验的新程序交给一个与 Agent 进程树无关的升级进程,由它替换程序并重启服务。
	// 返回 nil 表示升级进程已经启动,Agent 随后会被重启;返回错误表示什么都没有发生。
	Handoff func(ctx context.Context, newBinary, version string) error
	// Note 返回上一次升级留下的结果,握手时带给 Hub;可为 nil。
	Note func() *termproto.UpgradeNote
	// Connected 在每次与 Hub 握手成功时调用,参数是本进程的版本号;可为 nil。
	// 升级进程靠它留下的「上线标记」判断新版本是否真的连上了 Hub。
	Connected func(version string)
	// AutoMode 报告主机所有者在本机为「自动升级」选的模式(termproto.AutoUpgradeOff / Notify / Silent),每次现读;
	// nil 表示这个 Agent 不提供自动升级,握手里不声明。
	AutoMode func() string
	// AutoChecked 在每次自动升级检查得出结论时调用,把结果交给本机保存(供 `auto-upgrade status` 展示);可为 nil。
	AutoChecked func(AutoCheckNote)
	// AutoSettings 现读主机所有者对自动升级的完整设置(模式、时间段、钉住的公钥);第二个返回值为 false 表示没有同意。
	// nil 表示这个 Agent 读不到设置:静默模式不会安装任何东西(只做提示)。
	AutoSettings func() (AutoSettings, bool)
	// AutoAttempts 返回本机记录的静默升级尝试;AutoAttempted 记一次「对这个版本开始静默升级」(要在下载之前写好)。
	// 任何一个为 nil 都意味着无法记录尝试:静默模式不会安装任何东西。
	AutoAttempts  func() AutoAttempts
	AutoAttempted func(version string) error

	// 以下供测试注入,零值取默认。
	HTTPClient      func() (*http.Client, error)                           // 默认:按 Agent 的信任配置构造
	Platform        func() (goos, goarch string)                           // 默认:runtime.GOOS / GOARCH
	Verify          func(ctx context.Context, file string) (string, error) // 默认:运行 `<file> version` 取版本号
	MaxBytes        int64                                                  // 默认 256 MiB
	DownloadTimeout time.Duration                                          // 默认 5 分钟
	Now             func() time.Time                                       // 默认 time.Now
}

SelfUpgrade 是 Agent 响应 Hub 的 upgrade 帧所需的本机能力与策略。nil 表示这个 Agent 不支持(不声明能力)。

type ServerTarget

type ServerTarget struct {
	URL    string // 完整的 ws:// 或 wss:// 地址(含入口路径)
	Host   string // host:port,TOFU 记录的键
	Secure bool   // wss
}

ServerTarget 是规范化之后的服务端地址。

func ParseServer

func ParseServer(raw string) (ServerTarget, error)

ParseServer 把用户给的服务端地址规范化:

  • 允许省略协议(默认 https);http/https 会转换为 ws/wss;
  • 自动补全入口路径;不接受内嵌账号密码,丢弃查询串与片段。

func (ServerTarget) HTTPBase

func (t ServerTarget) HTTPBase() (string, error)

HTTPBase 返回同一台服务端的 HTTP(S) 基地址(不含末尾斜杠,保留部署在子路径下时的路径前缀)。 Agent 用它拼出升级文件的下载地址:地址只由 Agent 自己配置的服务端推出,不接受 Hub 在帧里指定。

type ShellFunc

type ShellFunc = holder.ShellFunc

Limits 与 ShellFunc 的实现在 holder 包里(会话由守护进程持有);这里保留别名, 让命令行与测试沿用 agent.Limits / agent.DefaultLimits 这些名字。

type State

type State string

State 是 Agent 与 Hub 之间的连接状态(供命令行输出与测试观察)。

const (
	StateConnecting State = "connecting" // 正在拨号 / 握手
	StatePending    State = "pending"    // 已连上,等待管理员在 Web 上启用
	StateOnline     State = "online"     // 已启用,可以提供终端
	StateRetrying   State = "retrying"   // 连接失败或断开,等待重试
)

type TrustOptions

type TrustOptions struct {
	// Pins 是允许的服务端叶子证书 SHA-256 指纹("sha256:<hex>"),可配置多个以便证书轮换。
	Pins []string
	// Insecure 允许明文 ws://。
	Insecure bool
	// KnownServersPath 非空时启用 TOFU 记录;与 Prompt 配合使用。
	KnownServersPath string
	// Prompt 在 TOFU 首次遇到未知指纹时询问人类是否信任;为 nil 则不做 TOFU。
	Prompt func(host, fingerprint string) bool
}

TrustOptions 是连接服务端的信任配置。

func (TrustOptions) HTTPClient

func (o TrustOptions) HTTPClient(t ServerTarget) (*http.Client, error)

HTTPClient 构造用于 WebSocket 升级请求的 HTTP 客户端(HTTP/1.1,支持代理环境变量)。

func (TrustOptions) Validate

func (o TrustOptions) Validate(t ServerTarget) error

Validate 检查配置与目标是否相容(明文地址必须显式 --insecure;指纹必须合法)。

Directories

Path Synopsis
Package cli 是终端 Agent 的命令行:独立二进制 relaymesh-agent 与主程序的 `relaymesh agent` 子命令共用同一份实现。
Package cli 是终端 Agent 的命令行:独立二进制 relaymesh-agent 与主程序的 `relaymesh agent` 子命令共用同一份实现。
Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。
Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。
Package ptyhost 把「伪终端 + 子进程」的平台细节隔离在一个窄接口之后。
Package ptyhost 把「伪终端 + 子进程」的平台细节隔离在一个窄接口之后。
Package record 实现终端会话的**客户端侧**记录:终端上显示什么就记录什么。
Package record 实现终端会话的**客户端侧**记录:终端上显示什么就记录什么。
Package runlog 保存模型运行(非 PTY 的一次性命令)的完整输出。
Package runlog 保存模型运行(非 PTY 的一次性命令)的完整输出。
Package sshcred 是 SSH 网关在本机保存「它代为连接的 SSH 主机的登录凭据」的密封库。
Package sshcred 是 SSH 网关在本机保存「它代为连接的 SSH 主机的登录凭据」的密封库。

Jump to

Keyboard shortcuts

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