直接使用 golang.org/x/crypto/ssh 易卡在认证失败或连接挂起，因其仅提供底层能力，需手动处理超时、主机密钥校验、StdoutPipe 缓冲区清理等；封装 SSHClient 应支持密码与私钥双认证，并通过 context 控制命令执行超时，分别读取 stdout/stderr 且调用 session.Wait 获取退出码。
为什么直接用 golang.org/x/crypto/ssh 容易卡在认证失败或连接挂起
Go 标准库不自带 SSH 客户端，必须依赖 golang.org/x/crypto/ssh。但这个包本身只提供底层连接能力，不封装会话、命令执行、超时控制等常见需求——直接调用 ssh.Client.Dial 或 ssh.NewSession 时，常因未设置 Timeout、忽略 HostKeyCallback、未清理 StdoutPipe 缓冲区，导致程序卡死或 panic。
- 连接超时必须显式设置：
net.DialTimeout+ 自定义ssh.ClientConfig中的Timeout -
HostKeyCallback不能写成ssh.InsecureIgnoreHostKey()上生产环境；建议用ssh.FixedHostKey配合已知 host key，或实现简单校验逻辑 - 每次
session.Run()前必须调用session.StdoutPipe()和session.StderrPipe()，否则 stdout/stderr 会阻塞（尤其命令输出 >64KB）
如何封装可复用的 SSHClient 结构体并支持密码和私钥双认证
一个实用的封装必须区分认证方式，且避免重复解析私钥或构造 config。推荐把认证参数收进结构体字段，延迟到 Connect() 时才生成 *ssh.ClientConfig：
type SSHClient struct {
addr string
user string
password string // 可为空
keyPath string // 可为空
timeout time.Duration
}
func (c *SSHClient) Connect() (*ssh.Client, error) {
var auth []ssh.AuthMethod
if c.password != "" {
auth = append(auth, ssh.Password(c.password))
}
if c.keyPath != "" {
key, err := os.ReadFile(c.keyPath)
if err != nil {
return nil, err
}
signer, err := ssh.ParsePrivateKey(key)
if err != nil {
return nil, err
}
auth = append(auth, ssh.PublicKeys(signer))
}
config := &ssh.ClientConfig{
User: c.user,
Auth: auth,
HostKeyCallback: ssh.InsecureIgnoreHostKey(), // 仅测试用，生产请替换
Timeout: c.timeout,
}
client, err := ssh.Dial("tcp", c.addr, config)
return client, err
}
注意：私钥文件路径需提前验证是否存在，ssh.ParsePrivateKey 不区分 PEM 格式错误和权限问题，报错都是 invalid private key，容易误判。
Run 方法必须同时处理 stdout/stderr、退出码和上下文取消
单纯调用 session.Run(cmd) 无法获取输出内容；而用 session.CombinedOutput() 又无法区分 stdout/stderr。更关键的是，没有 context 控制的话，远程命令 hang 住会导致整个 goroutine 永久阻塞。
立即学习“go语言免费学习笔记（深入）”；
- 必须用
context.WithTimeout包裹整个执行流程，超时后主动关闭 session - 用
io.ReadAll分别读取session.StdoutPipe()和session.StderrPipe()，不能用session.Output()—— 它内部用了bytes.Buffer，对大输出不友好 - 执行完必须调用
session.Wait()才能拿到真实退出码；session.Run()返回的 error 不包含 exit code
示例关键片段：
func (c *SSHClient) Run(ctx context.Context, cmd string) (int, []byte, []byte, error) {
client, err := c.Connect()
if err != nil {
return -1, nil, nil, err
}
defer client.Close()
session, err := client.NewSession()
if err != nil {
return -1, nil, nil, err
}
defer session.Close()
stdout, _ := session.StdoutPipe()
stderr, _ := session.StderrPipe()
if err := session.Start(cmd); err != nil {
return -1, nil, nil, err
}
go func() { <-ctx.Done(); session.Signal(ssh.SIGKILL) }()
if err := session.Wait(); err != nil {
// 注意：这里 err 是 *ssh.ExitError 类型，需类型断言才能取 ExitCode()
}
out, _ := io.ReadAll(stdout)
errOut, _ := io.ReadAll(stderr)
return exitCode, out, errOut, nil
}
生产环境必须绕开 ssh.InsecureIgnoreHostKey 的三种可行做法
忽略 host key 检查等于放弃中间人防护，上线前必须替换。最轻量且可控的方式是预存目标服务器的公钥指纹（如 ssh-keyscan -t rsa example.com 输出），然后在回调中比对：
- 用
ssh.ParsePublicKey解析已知 pubkey 字符串，传给ssh.FixedHostKey - 若需支持多台主机，可维护一个 map[string]ssh.PublicKey，key 为 host:port
- 更严谨的做法是实现自定义
HostKeyCallback，从本地文件或配置中心加载已知 keys，并记录首次连接时的 key（类似 OpenSSH 的 known_hosts 行为）
注意：ssh.FixedHostKey 在 key 不匹配时直接返回 error，不会 fallback；且它不校验证书链，只做字节级相等判断——这意味着你得确保拿到的 pubkey 和服务端实际使用的完全一致（包括换行、空格、注释）。
