使用 gliderlabs/ssh 将 Docker 容器封装为 SSH 服务:以 jq 为例的完整实战指南

原创2026-10-14 13:37:292,227 阅读
文章标签:网络通信后端认证鉴权Web框架

使用 gliderlabs/ssh 将 Docker 容器封装为 SSH 服务:以 jq 为例的完整实战指南

导读:本文基于开源仓库 gh_mirrors/ss/ssh(Glider Labs 出品的 Go SSH 服务器库)中的官方示例 _examples/ssh-docker,讲解如何利用该库把任意 Docker 镜像"包装"成一个可通过标准 SSH 客户端调用的命令行服务。读完本文,你将掌握:用 Go 快速搭建 SSH 服务器、把 SSH 用户名映射为 Docker 镜像名、把 SSH 会话的标准输入/输出与 Docker 容器对接、实现 TTY 与管道输入透传,以及解决 host key 冲突等常见问题。

示例概览:让 jq 成为 SSH 服务

这个示例的最终效果非常直观:本地只需一条命令 ssh jq@localhost -p 2222,就能进入一个运行着 jq 的 Docker 容器;你甚至可以把 JSON 数据通过管道 | 喂进这个 SSH 服务,让远端容器完成 JSON 解析后再把结果返回终端。其背后依赖两件事:

  1. gliderlabs/ssh——一个让"在 Go 里写 SSH 服务器"变得极其简单的库,核心入口见仓库根目录的 ssh.go 与 session.go;
  2. Docker Engine——服务端通过 Docker API 动态创建、连接并销毁容器,相关代码见 _examples/ssh-docker/docker.go。

整个设计可以用一句话概括:SSH 会话的用户名即 Docker 镜像名,SSH 会话的命令行参数即容器启动参数,SSH 会话的 stdin/stdout/stderr 即容器的 stdin/stdout/stderr。

环境准备与安装

示例依赖两样东西:Go 语言环境与 Docker(服务端需要能调用 Docker API;客户端需要标准 ssh 与 curl 命令)。按原文档 _examples/ssh-docker/README.md 的步骤:

  1. 安装 gliderlabs/ssh 依赖包:

    go get github.com/gliderlabs/ssh
    

    在当前仓库中,该依赖对应的模块信息见 go.mod,模块路径为 github.com/gliderlabs/ssh,Go 版本要求 1.20 及以上。

  2. 构建示例所用的 jq 镜像:

    docker build --rm -t jq .
    

    注意:必须在 _examples/ssh-docker 目录下执行,因为 docker build 的上下文(即 Dockerfile 所在目录)就是当前目录。

构建镜像:Dockerfile 解析

_examples/ssh-docker/Dockerfile 的内容极为精简,只有三行:

FROM alpine
RUN apk add -U jq
ENTRYPOINT ["jq"]

它的含义是:基于 Alpine Linux 基础镜像,用 apk 包管理器安装 jq(-U 表示更新软件源索引),并把容器的入口程序固定为 jq。这样容器启动时会把所有追加参数直接交给 jq 执行——这正是"SSH 命令行参数透传给容器"能够成立的关键前提。

服务端源码深度解析

服务端代码全部位于 _examples/ssh-docker/docker.go。它虽然只有一百多行,却完整演示了 gliderlabs/ssh 会话处理、Docker 容器生命周期管理、流对接与 TTY 支持这四块核心能力。

1. 注册会话处理器并启动服务器

func main() {
	ssh.Handle(func(sess ssh.Session) {
		_, _, isTty := sess.Pty()
		cfg := &container.Config{
			Image:        sess.User(),
			Cmd:          sess.Command(),
			Env:          sess.Environ(),
			Tty:          isTty,
			OpenStdin:    true,
			AttachStderr: true,
			AttachStdin:  true,
			AttachStdout: true,
			StdinOnce:    true,
			Volumes:      make(map[string]struct{}),
		}
		status, cleanup, err := dockerRun(cfg, sess)
		defer cleanup()
		if err != nil {
			fmt.Fprintln(sess, err)
			log.Println(err)
		}
		sess.Exit(int(status))
	})

	log.Println("starting ssh server on port 2222...")
	log.Fatal(ssh.ListenAndServe(":2222", nil))
}

这里用到了 gliderlabs/ssh 的三个关键 API:

  • ssh.Handle(handler):把传入的 handler 注册为 DefaultHandler,源码见 ssh.go。由于后续 ListenAndServe(":2222", nil) 传入的 handler 为 nil,服务器会自动使用这个默认处理器。
  • ssh.ListenAndServe(addr, handler):在指定 TCP 地址上监听并处理 SSH 连接,源码见 ssh.go。在 server.go 的实现中,如果 Addr 为空则会回退到 :22——示例显式指定了 :2222,因此客户端连接时也必须加上 -p 2222。
  • sess.Exit(code):向客户端发送退出状态并关闭会话,底层通过 SSH 的 exit-status 请求实现,见 session.go。示例会把 Docker 容器的退出码原样透传给 SSH 客户端。

2. 用户名即镜像名、命令即容器参数

container.Config 的填充方式体现了整个设计:

container.Config 字段 来源 说明
Image sess.User() SSH 连接时的用户名,直接用作 Docker 镜像名
Cmd sess.Command() SSH 会话的已解析命令参数,透传给容器
Env sess.Environ() SSH 会话携带的环境变量(key=value 形式)
Tty sess.Pty() 返回值 会话是否申请了 PTY,决定是否以 TTY 模式启动容器
OpenStdin / AttachStdin / AttachStdout / AttachStderr / StdinOnce 固定 true 要求容器以可交互、三流全挂载的方式运行
Volumes 空 map 不挂载任何数据卷

这几个 Session 方法的语义定义在 session.go:

  • User() 返回建立连接时使用的用户名;
  • Command() 返回按 POSIX shell 规则解析后的命令参数切片——注意它内部通过 shlex.Split 处理了引号与空白,见 session.go;当返回空切片时,表示客户端请求的是交互式 shell;
  • Environ() 返回客户端为本会话设置的环境变量副本;
  • Pty() 返回 (Pty, <-chan Window, bool) 三元组——bool 表示会话是否申请并获得了 PTY,Pty 中包含终端类型 Term 与窗口大小 Window。

3. dockerRun:容器生命周期与流对接

dockerRun 是核心函数,它完整走了一遍 Docker 容器的生命周期:

func dockerRun(cfg *container.Config, sess ssh.Session) (status int64, cleanup func(), err error) {
	docker, err := client.NewEnvClient()
	...
	// 1. 创建容器
	res, err := docker.ContainerCreate(ctx, cfg, nil, nil, "")
	// 2. 挂上清理函数(会话结束删除容器、关闭流)
	cleanup = func() {
		docker.ContainerRemove(ctx, res.ID, types.ContainerRemoveOptions{})
		stream.Close()
	}
	// 3. 附加到容器流
	stream, err := docker.ContainerAttach(ctx, res.ID, opts)
	...
	// 4. 容器输出 → SSH 会话输出
	go func() {
		if cfg.Tty {
			_, err = io.Copy(sess, stream.Reader)
		} else {
			_, err = stdcopy.StdCopy(sess, sess.Stderr(), stream.Reader)
		}
		outputErr <- err
	}()
	// 5. SSH 会话输入 → 容器输入
	go func() {
		defer stream.CloseWrite()
		io.Copy(stream.Conn, sess)
	}()
	// 6. 启动容器
	err = docker.ContainerStart(ctx, res.ID, types.ContainerStartOptions{})
	...
	// 7. 等待容器退出并透传退出码
	resultC, errC := docker.ContainerWait(ctx, res.ID, container.WaitConditionNotRunning)
	...
}

几个值得注意的实现细节:

  • TTY 与非 TTY 的输出路径不同:当会话申请了 PTY(例如交互式 ssh 登录)时,直接 io.Copy 把容器输出拷贝到会话即可;而当会话是管道模式(如 curl | ssh ... .)时,则使用 Docker 的 stdcopy.StdCopy 拆分标准输出与标准错误,分别写入 sess 和 sess.Stderr()。这正是"管道输入也能工作"的底层原因。
  • 窗口尺寸同步:当容器以 TTY 模式启动后,代码通过 sess.Pty() 拿到 winCh 通道,监听客户端发来的 window-change 请求并调用 ContainerResize 同步容器终端尺寸。gliderlabs/ssh 内部在 session.go 解析 pty-req 与 window-change 请求,并把最新窗口写入缓冲通道。
  • 清理语义:通过闭包形式累积 cleanup,defer cleanup() 保证无论正常退出还是出错,容器都会被删除、attach 流会被关闭,不会留下僵尸容器。

4. 默认 host key 的生成机制

示例没有显式指定任何 host key,直接 go run docker.go 就能跑。这是因为 gliderlabs/ssh 在服务器启动时会自动生成一个临时 host key:ensureHostSigner 在检测到没有配置任何 HostSigners 时,会调用 generateSigner() 生成一个 2048 位的 RSA 密钥,相关实现见 server.go 与 util.go。这也解释了后文故障排查章节中的 host key 冲突问题——每次重启服务,host key 都是全新的。

运行与连接

启动服务端(在 _examples/ssh-docker 目录下):

go run docker.go

服务端会打印日志 starting ssh server on port 2222... 并开始监听。

使用 jq 用户名连接(用户名即镜像名,这里对应 jq 镜像):

ssh jq@localhost -p 2222

由于服务端未配置任何认证 handler,gliderlabs/ssh 会自动开启 NoClientAuth(见 server.go),因此无需密码即可登录。连接后,jq 容器被启动,其标准输出直接呈现在你的终端上,首先看到的就是 jq 的帮助文本:

jq - commandline JSON processor [version 1.5]
Usage: jq [options] <jq filter> [file...]

	jq is a tool for processing JSON inputs, applying the
	given filter to its JSON text inputs and producing the
	filter's results as JSON on standard output.
	The simplest filter is ., which is the identity filter,
	copying jq's input to its output unmodified (except for
	formatting).
	For more advanced filters see the jq(1) manpage ("man jq")
	and/or https://stedolan.github.io/jq

	Some of the options include:
	 -c		compact instead of pretty-printed output;
	 -n		use `null` as the single input value;
	 -e		set the exit status code based on the output;
	 -s		read (slurp) all inputs into an array; apply filter to it;
	 -r		output raw strings, not JSON texts;
	 -R		read raw strings, not JSON texts;
	 -C		colorize JSON;
	 -M		monochrome (don't colorize JSON);
	 -S		sort keys of objects on output;
	 --tab	use tabs for indentation;
	 --arg a v	set variable $a to value <v>;
	 --argjson a v	set variable $a to JSON value <v>;
	 --slurpfile a f	set variable $a to an array of JSON texts read from <f>;
	See the manpage for more options.
Connection to localhost closed.

看到 jq 的帮助文本,说明容器已被正确创建、启动并接到 SSH 会话上——"Docker 容器即 SSH 服务"已经跑通了。

管道输入:把数据喂给 SSH 服务

原文档特意强调:你甚至可以把数据通过管道喂进这个 SSH 服务。将 GitHub API 返回的 JSON 通过管道传给 SSH 会话,并让 jq 执行身份过滤器 .(原样输出):

curl -s https://api.github.com/orgs/gliderlabs | ssh jq@localhost -p 2222 .

返回结果(示例输出为当时 API 的响应):

{
  "login": "gliderlabs",
  "id": 8484931,
  "url": "https://api.github.com/orgs/gliderlabs",
  "repos_url": "https://api.github.com/orgs/gliderlabs/repos",
  "events_url": "https://api.github.com/orgs/gliderlabs/events",
  "hooks_url": "https://api.github.com/orgs/gliderlabs/hooks",
  "issues_url": "https://api.github.com/orgs/gliderlabs/issues",
  "members_url": "https://api.github.com/orgs/gliderlabs/members{/member}",
  "public_members_url": "https://api.github.com/orgs/gliderlabs/public_members{/member}",
  "avatar_url": "https://avatars3.githubusercontent.com/u/8484931?v=4",
  "description": "",
  "name": "Glider Labs",
  "company": null,
  "blog": "http://gliderlabs.com",
  "location": "Austin, TX",
  "email": "team@gliderlabs.com",
  "has_organization_projects": true,
  "has_organization_projects": true,
  "public_repos": 29,
  "public_gists": 0,
  "followers": 0,
  "following": 0,
  "html_url": "https://github.com/gliderlabs",
  "created_at": "2014-08-18T23:25:37Z",
  "updated_at": "2017-08-21T09:52:17Z",
  "type": "Organization"
}

整个过程可以拆解为三条数据通路:

  1. curl 把 GitHub API 的 JSON 写到 stdout;
  2. OpenSSH 客户端把 stdin 通过 SSH 通道转发给服务端会话,服务端再经 io.Copy(stream.Conn, sess) 写入容器 stdin(见 docker.go);
  3. 容器以非 TTY 模式运行,jq 处理完 JSON 后经 stdcopy.StdCopy 把 stdout 拆送回 SSH 会话,最终呈现在你的终端上(见 docker.go)。

扩展玩法:既然 Cmd 来自 sess.Command(),你完全可以运行 ssh jq@localhost -p 2222 -r .name 之类的命令,把参数透传给容器内的 jq 执行——这正是把"镜像名即用户名、参数即命令"这套机制用活的关键。

结论

通过这个示例,我们用 gliderlabs/ssh 在 Go 中把 jq 封装成了一个可远程调用的服务,并展示了两个核心能力:

  1. 通过 SSH 运行 Docker 容器:用户名映射镜像名、命令参数透传、退出码回传,形成完整的"容器即命令"闭环;
  2. 向 SSH 服务管道输入数据:标准输入/输出/错误三路流的双向对接(含 TTY 与非 TTY 两种模式),让 SSH 服务像本地命令一样可以接入 shell 管道。

这套模式可以推广到任意以 CLI 为入口的 Docker 镜像——只要把 Image 换成别的镜像名(如 python、redis-cli 等),就能快速把它变成团队可远程访问的服务,且天然复用 SSH 的认证、加密与端口管理生态。

故障排查:host key 冲突

由于示例未配置固定 host key,每次重启服务端都会生成全新的 RSA host key(2048 位,见 util.go)。因此第二次运行服务后,客户端大概率会遇到如下报错:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
SHA256:9dyZ8KrMCPGvDqECggoDFyz51gA6DdHa9zpfl/5Kgos.
Please contact your system administrator.
Add correct host key in /Users/murr/.ssh/known_hosts to get rid of this message.
Offending RSA key in /Users/murr/.ssh/known_hosts:7
RSA host key for [localhost]:2222 has changed and you have requested strict checking.
Host key verification failed.

这是 OpenSSH 客户端的安全机制在起作用:known_hosts 中记录的指纹与本次连接收到的指纹不一致。原文档给出的临时解决办法是重新生成(实际是移除)对应条目:

ssh-keygen -R "[localhost]:2222"

-R 会从 known_hosts 中删除该主机的旧密钥条目,下次连接时 OpenSSH 会重新询问并记录新指纹。

更稳妥的生产级做法是让服务端持有持久化的 host key。gliderlabs/ssh 在 options.go 中提供了两个现成的函数式选项:

  • HostKeyFile(filepath):从 PEM 私钥文件加载 host key;
  • HostKeyPEM(bytes):直接传入 PEM 字节。

例如先 ssh-keygen -t rsa -f ./host_key 生成密钥,然后改用:

log.Fatal(ssh.ListenAndServe(":2222", nil, ssh.HostKeyFile("host_key")))

这样重启服务后指纹不再变化,也就不再出现上述报错。若需要同时支持多算法,也可在 server.go 的 AddHostKey 机制下反复调用该选项——同一算法只会保留最后一份 key。

登录后查看全文
ssh