Documentation
¶
Overview ¶
Package sshexec 是 RelayMesh 的 SSH 执行后端的传输层:严格固定主机密钥的连接、会话执行、按主机复用的连接池, 以及在远端主机上启动 / 轮询 / 读取 / 取消「后台任务」的 POSIX 脚本。
本包不知道 Hub 的运行状态机、闸门和数据库:它只负责「安全地把一小段脚本送到一台已确认身份的主机上并取回结果」。 凭据的加密保存、授权与审计都在调用方(internal/terminal)。
Index ¶
- Constants
- Variables
- func CancelCommand(runID string) (cmd string, stdin []byte, err error)
- func FactsCommand() (cmd string, stdin []byte)
- func LaunchCommand(sp LaunchSpec) (cmd string, stdin []byte, err error)
- func NormalizeAddr(raw string) (string, error)
- func ParseLocaleProbe(out []byte) (charmap, utf8 string)
- func PollCommand(sp PollSpec) (cmd string, stdin []byte, err error)
- func ReadCommand(sp ReadSpec) (cmd string, stdin []byte, err error)
- func SweepCommand(days int) (cmd string, stdin []byte, err error)
- func ValidRemoteShell(s string) bool
- func ValidRunID(id string) bool
- func ValidUser(u string) bool
- type CancelResult
- type Client
- type Credential
- type Facts
- type HostKey
- type LaunchResult
- type LaunchSpec
- type PollResult
- type PollSpec
- type Pool
- type ReadResult
- type ReadSpec
- type Result
- type Shell
- type ShellExit
- type ShellOptions
- type Spec
Constants ¶
const ( DefaultDialTimeout = 10 * time.Second // DefaultMaxOutput 是一次会话里每一路输出在内存中的上限:本包只运行短脚本,远端不应该返回大量数据。 DefaultMaxOutput = 2 << 20 )
连接与执行的默认参数。
const ( AuthPassword = "password" AuthKey = "key" )
认证方式。
const ( LaunchErrHome = "home" LaunchErrMkdir = "mkdir" LaunchErrB64 = "b64" LaunchErrDecode = "decode" LaunchErrCwd = "cwd" LaunchErrSpawn = "spawn" )
启动失败的原因(LaunchResult.Err)。
const ( DefaultKeepAliveEvery = 30 * time.Second DefaultKeepAliveMisses = 3 )
保活的默认参数:每 30 秒一次,连续 3 次没有应答就视为连接已断开。
const MaxChunkBytes = 256 << 10
MaxChunkBytes 是一次轮询在每一路上最多取回的原始字节数。
const RemoteShell = "sh -s"
RemoteShell 是执行脚本时使用的命令(脚本从 stdin 输入)。
Variables ¶
var ( ErrHostKeyMismatch = errors.New("主机密钥与已固定的不一致") ErrAuthFailed = errors.New("SSH 认证失败") ErrUnreachable = errors.New("无法连接到 SSH 主机") ErrPassphrase = errors.New("私钥已加密,需要提供口令") ErrBadCredential = errors.New("凭据格式无效") ErrBadAddress = errors.New("地址无效") ErrTooLarge = errors.New("远端返回的数据超过上限") ErrUnsupported = errors.New("目标主机不是受支持的 POSIX 环境") ErrNoHostKey = errors.New("没有固定的主机密钥,拒绝连接") ErrProtocol = errors.New("远端返回了无法解析的内容") ErrConn = errors.New("SSH 连接中断") // ErrViaGateway:这份规格属于经网关接入的主机(Spec.Via 非空),只能由网关出站连接,本进程不得直连。 ErrViaGateway = errors.New("这台 SSH 主机经网关主机接入,不能由本机直连") )
稳定的错误值:调用方用 errors.Is 判断,并映射成稳定的错误码。
Functions ¶
func CancelCommand ¶
CancelCommand 生成取消脚本:对整个进程组先发 TERM,宽限约 3 秒后发 KILL。
func LaunchCommand ¶
func LaunchCommand(sp LaunchSpec) (cmd string, stdin []byte, err error)
LaunchCommand 生成启动脚本。
func NormalizeAddr ¶
NormalizeAddr 把管理员输入的地址规整成 host:port(默认 22 端口)。 拒绝 user@host、URL、空白与控制字符:用户名单独配置,目标 ID 之外的地址永远不会来自模型。
func ParseLocaleProbe ¶
ParseLocaleProbe 解析探测输出:对方当前的字符集,以及一个可用的 UTF-8 locale 名(没有则为空)。
func PollCommand ¶
PollCommand 生成轮询脚本。
func ReadCommand ¶
ReadCommand 生成读取脚本。
func SweepCommand ¶
SweepCommand 生成清理脚本:删除已结束且超过 days 天的任务目录(仍在运行的不动)。
func ValidRemoteShell ¶
ValidRemoteShell 判断 shell 名称是否允许用于 SSH 主机。
Types ¶
type CancelResult ¶
type CancelResult struct {
Gone bool // 任务目录不存在
Done bool // 命令已经自行结束
NoPID bool
Killed bool // 宽限期后仍存活,被 KILL
Termed bool // TERM 后退出
}
CancelResult 是取消脚本的输出。
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client 是一条已认证的 SSH 连接。
type Credential ¶
type Credential struct {
Kind string `json:"kind"`
Password string `json:"password,omitempty"`
PrivateKey string `json:"private_key,omitempty"`
Passphrase string `json:"passphrase,omitempty"`
}
Credential 是连接一台主机所需的认证材料。它永远不应该被打印:String / GoString 都做了脱敏。
func ParseCredential ¶
func ParseCredential(b []byte) (Credential, error)
ParseCredential 还原 Marshal 的输出(不做私钥解析,解析发生在真正连接时)。
func (Credential) Validate ¶
func (c Credential) Validate() error
Validate 检查凭据的格式(私钥会被真正解析一次,口令不对 / 缺失会被发现)。
type Facts ¶
Facts 是目标主机的环境信息。
func ParseFacts ¶
ParseFacts 解析探测输出;不是 POSIX 环境(没有 uname)或缺少 base64 时返回 ErrUnsupported。
type HostKey ¶
type HostKey struct {
Type string // 例如 ssh-ed25519
Key ssh.PublicKey // 公钥本体
Fingerprint string // SHA256:xxxx(与 ssh-keygen -l 的输出一致)
}
HostKey 是被探测到 / 被固定的主机公钥。
type LaunchResult ¶
type LaunchResult struct {
PID int
Shell string
Duplicate bool // 任务目录已存在:脚本被重放,没有再次启动
Err string // 非空表示没有启动
}
LaunchResult 是启动脚本的输出。
type LaunchSpec ¶
type LaunchSpec struct {
RunID string
Command string
Shell string // 空表示自动选择(bash,其次 sh)
Cwd string // 空表示家目录
TimeoutSec int
}
LaunchSpec 是一次启动的参数。
type PollResult ¶
type PollResult struct {
Gone bool // 任务目录不存在(已被清理或从未创建)
Problem string // 脚本自身报告的问题(例如 home)
PID int
Alive bool
ExitCode *int // 运行器写出了退出码才有值
Finished int64 // 结束时间(Unix 秒,主机时钟),未结束为 0
OutSize int64
ErrSize int64
Out, Err []byte // 从请求的偏移起取回的新增内容
}
PollResult 是轮询的结果。
type PollSpec ¶
type PollSpec struct {
RunID string
OutOff int64
ErrOff int64
MaxBytes int // 每一路最多取回的字节数,缺省并限制为 MaxChunkBytes
}
PollSpec 是一次轮询的参数:从两路输出的指定偏移起取回新增内容。
type Pool ¶
type Pool struct {
DialTimeout time.Duration
MaxSessions int // 每台主机同时进行的会话数上限,默认 8
IdleTimeout time.Duration // 连接空闲多久后被回收,默认 90 秒
// contains filtered or unexported fields
}
Pool 按主机复用 SSH 连接,并限制每台主机上同时进行的会话数。
func (*Pool) Exec ¶
func (p *Pool) Exec(ctx context.Context, key string, sp Spec, cmd string, stdin []byte, maxOut int) (Result, error)
Exec 在 key 对应的主机上运行 cmd。连接层面的失败(连接被对端关掉等)会用新连接重试一次; 因此调用方传入的脚本必须是幂等的。
type ReadResult ¶
ReadResult 是读取的结果。
type Shell ¶
type Shell struct {
// contains filtered or unexported fields
}
Shell 是一个已启动的交互式 shell。它拥有底层的 SSH 连接:使用者读完输出后必须调用 Close(会一并关闭连接)。
type ShellExit ¶
type ShellExit struct {
// Code 是远端 shell 的退出码;被信号终止或连接丢失时为 -1。
Code int
// Signal 是远端报告的终止信号名(没有则为空)。
Signal string
// Lost 为 true 表示不是远端自己退出,而是连接中断(网络断开、保活无应答、被本地关闭除外)。
Lost bool
// Reason 在 Lost 时给出已净化的简短原因。
Reason string
}
ShellExit 描述一个 shell 会话是如何结束的。
type ShellOptions ¶
type ShellOptions struct {
Term string
Rows uint16
Cols uint16
// KeepAliveEvery <= 0 使用默认值;KeepAliveMisses <= 0 使用默认值。
KeepAliveEvery time.Duration
KeepAliveMisses int
// KeepAliveReplyWait <= 0 使用默认值(单次保活请求等待应答的上限)。
KeepAliveReplyWait time.Duration
// NoLocaleProbe 为 true 时不探测、也不下发字符集(默认会探测,见 localeProbeScript)。
NoLocaleProbe bool
}
ShellOptions 是 OpenShell 的参数。零值使用默认值。