转自：https://wayjam.me/post/how-gitlab-shell-works-with-ssh.md
GitLab访问Git仓库
首先回顾GitLab的Git仓库四种访问方式：
- git pull over http -> gitlab-rails (Authorization) -> accept or decline -> execute git command
- git push over http -> gitlab-rails (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
- git pull over ssh -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> execute git command
- git push over ssh -> gitlab-shell (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
四种方式都有GitLab Shell的参与，但不同过程GitLab Shell发挥了不同的作用，并且它并不是一个整体的服务，而是由一些子命令组合而成。HTTP方式的Git操作，经gitlab workhorse直接交由Rails应用处理，然后通过HTTP协议交换数据，对于git的操作有三条路径：Gem包Rugged、Raw Git命令或者Gitaly，push/pull一般只跟后两种有关，GitLab Shell充当的作用仅仅是git hook的作用。
SSH方式的push/pull是GitLab Shell的主场景，而Rails在这其中充当了权限再验证的角色。
Git SSH 传输协议
首先，简要说明Git是如何通过SSH协议与服务端的Git交互数据。
ssh git@example.com "the-command"
在客户端执行这样的命令时候，服务端SSHD验证身份通过后，默认将启动一个Shell解析执行the-command的命令。普通使用中，大多都不加自定义命令，这将启动一个Shell交互式命令解析器。
要了解GitLab Shell的原理，不能不说它的“前任”——Gitolite。Gitolite是一个Git的授权层前端，同样提供了HTTP（httpd）和SSH的方式访问Git仓库。而Gitlab在v5.0完全用GitLab Shell替代了Gitolite，前者完全依赖Rails层的权限认证（项目、分支、用户等的权限），后者则由于需要完全保持一份冗余数据在自身的配置文件，主要由于速度和数据不同步被Gitlab官方放弃。但是，二者仍然采用了authorized_keys的command magic方案。
GitLab CE 10.4之后加入了`AuthorizedKeysCommand`的使用（_require_ OpenSSH 6.9+），使用自定义程序匹配Key而不是文件文本匹配。SSH command magic
SSHD服务端收到客户端的连接请求后，会在authorized_keys进行匹配，认证失败则拒绝连接。查看~/.ssh/authorized_keys文件内容如下：
# Gitolite
command="[path]/gitolite-shell user-one",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
# GitLab Shell
command="/home/git/gitlab-shell/bin/gitlab-shell key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...可以发现保存的每条公钥前面都有command=，Gitolite和GitLab Shell后面的参数代表着用户的识别信息，Gitolite保存在配置文件，而gitlab保存在数据库。当用户的服务端校验成功后，则会执行command=后的命令，而不是shell access，同时将SSH命令所要执行的命令赋值给SSH_ORIGINAL_COMMAND。所以与客户端交互的真正命令是（以pull代码为例）：
SSH_ORIGINAL_COMMAND=git-upload-pack git-pack/home/git/gitlab-shell/bin/gitlab-shell key-1
"Shell"
GitLab Shell由ruby脚本和go程序组成，首先看GitLab Shell入口代码：bin/gitlab-shell。
#!/usr/bin/env ruby
# ...
key_id = /key-[0-9]+/.match(ARGV.join).to_s
original_cmd = ENV.delete('SSH_ORIGINAL_COMMAND')
# ...
require File.join(ROOT_PATH, 'lib', 'gitlab_shell')
if GitlabShell.new(key_id).exec(original_cmd)
# ...
这段代码里面的两个变量：
key_id-> sshd调用GitLab Shell时传入的参数。original_cmd-> 即上文提到的SSH_ORIGINAL_COMMAND环境变量，并且获取完即移除。
举个例子，如果用户通过git客户端调用git clone git@server的时候，实际上git客户端启动的是receive-pack（git由许许多多子命令组成）并且在内部执行的是ssh git@git@server git-upload-pack git@server，那么此时，服务端给GitLab Shell设定的环境变量则是git-upload-pack git@server，。
然后看lib/gitlab-shell.rb代码，初始化一个GitlabShell，并且执行exec，而exec里面有几个关键步骤：
def exec(origin_cmd)
unless origin_cmd
puts "Welcome to GitLab, #{username}!"
return true
end
args = Shellwords.shellwords(origin_cmd)
args = parse_cmd(args)
if GIT_COMMANDS.include?(args.first)
GitlabMetrics.measure('verify-access') { verify_access }
end
process_cmd(args)
true
rescue something #异常
end
1. 解析命令 parse_cmd
主要是处理Windows/Linux命令差异、屏蔽非法命令、LFS命令。
2. 验证权限 verify_access
/api/v4/internal/allowed通过Rails的HTTP API ：/api/v4/internal/allowed发送查询参数到Rails，接口返回此用户对这个仓库是否有此操作的权限。
{
command => git命令
repo => 仓库信息
key_id => SSH key id（在数据库能找查找到对应的用户）
protocol => ssh/env
}
3. 处理命令 process_cmd
处理命令，检测gitaly此特性是否有开启，如果开启则调用gitaly处理，否则则调用git原生命令。
设定环境变量，然后使用Kernel.exec调用目标进程替代当前进程。
env = {
'HOME' => ENV['HOME'],
'PATH' => ENV['PATH'],
'LD_LIBRARY_PATH' => ENV['LD_LIBRARY_PATH'],
'LANG' => ENV['LANG'],
'GL_ID' => @key_id,
'GL_PROTOCOL' => GL_PROTOCOL,
'GL_REPOSITORY' => @gl_repository,
'GL_USERNAME' => @username
}
# ...
Kernel.exec(env, *args, unsetenv_others: true, chdir: ROOT_PATH)
处理Git命令
以Pull，且调用Gitaly为例。
// bin/gitaly-upload-pack
code, err := handler.UploadPack(os.Args[1], &request)
// go/internal/handler/upload_pack.go
func UploadPack(gitalyAddress string, request *pb.SSHUploadPackRequest) (int32, error) {
# ...
conn, err := client.Dial(gitalyAddress, dialOpts())
if err != nil {
return 0, err
}
defer conn.Close()
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
return client.UploadPack(ctx, conn, os.Stdin, os.Stdout, os.Stderr, request)
}
// go/vendor/gitlab.com/gitlab-org/gitaly/client/upload_pack.go
func UploadPack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, stdout, stderr io.Writer, req *pb.SSHUploadPackRequest) (int32, error) {
ctx2, cancel := context.WithCancel(ctx)
defer cancel()
ssh := pb.NewSSHServiceClient(conn)
stream, err := ssh.SSHUploadPack(ctx2)
if err != nil {
return 0, err
}
if err = stream.Send(req); err != nil {
return 0, err
}
inWriter := streamio.NewWriter(func(p []byte) error {
return stream.Send(&pb.SSHUploadPackRequest{Stdin: p})
})
return streamHandler(func() (stdoutStderrResponse, error) {
return smHandler(func() (stdoutStderrResponse, error) {
return stream.Recv()
}, func(errC chan error) {
_, errRecv := io.Copy(inWriter, stdin)
stream.CloseSend()
errC <- errRecv
}, stdout, stderr)
}
可以看到通过grpc跟gitaly server通信，获得响应之后：
# go/vendor/gitlab.com/gitlab-org/gitaly/client/std_stream.go
exited code => resp.GetExitStatus().GetValue()
stderr => stderr.Write(resp.GetStderr())
stdout => stdout.Write(resp.GetStdout())git客户端将标准错误打印到控制台，解析标准输出作为git数据：通过远程ssh调用命令将数据打印到标准输出传输到客户端解析。
Cloning into 'gitlab-shell'...
remote: Counting objects: 5558, done.
remote: Compressing objects: 100% (2548/2548), done.
remote: Total 5558 (delta 3051), reused 5117 (delta 2754)
Receiving objects: 100% (5558/5558), 2.83 MiB | 2.72 MiB/s, done.
Resolving deltas: 100% (3051/3051), done.