阅读 241

GitLab系列4 GitLab Shell

看了前三期 GitLab 相关解析的读者(假装有读者)

都会发现我总会贴 GitLab 的架构图。至此我们将 GitLab 如何处理 HTTP/HTTPS 请求的过程解释了“一半”:用户请求从 HTTP/HTTPS 入口进来,经由 nginx 到达 gitlab-workhorse ,如果能处理的请求自己优先处理,不能处理的请求再交给 unicorn ,unicorn 可以认为是一层外壳,保障了请求能高效地调度与处理,而真正处理请求的内核主要还是看 GitLab Rails ,即 gitlab-ce ,请求处理的“另一半”就交给 gitlab-ce 去处理了


本期我并不打算介绍 GitLab Rails ,因为这个项目实在太庞大和复杂了(当然也可以简单地看成是一个需要持久化数据库 PostgreSQL 和分布式缓存 Redis 支撑的 web 应用),完全可以另起一个专题进行介绍。而且本系列打算尽可能介绍 GitLab 每一个组件的功能(而不是介绍开源项目的代码结构等),刚才也说了 GitLab Rails 相当于 GitLab 的真内核,大部分用户请求的处理逻辑都在这里实现了(有个打算是,未来将结合某些业务场景对 gitlab-ce 做源码跟踪及分析)

那本期介绍什么呢?别忘了前几期都是讲 http/https 的路由情况,那 ssh 的呢?从架构图上看,ssh 入口的第一站即是 GitLab Shell。本节主要讲解理解 GitLab-Shell 运作原理的预备知识


一谈到 Shell,我们可能会联想到类似 bash 或 zsh 这样的命令行终端,某种程度上 GitLab Shell 也可以被看成是一系列预定义命令的集大成者,但也不止是这样

GitLab Shell 是 shell ?

还记得之前第一期的时候贴的这张解释 SSH 利用对称加密算法登录登录服务器的流程吗?回顾一下:其实整个过程主要使用了公钥加密、私钥解密的对称加密算法:用户将自己本机的 SSH 公钥上传至远程服务器上(远程服务器的 $HOME/.ssh/authorized_keys 文件将保存用户上传的公钥,一般情况直接追加到文件末尾即可)登录的时候远程服务器向用户发送一段随机序列,用户用自己本机的 SSH 私钥加密后发回远程服务器,远程服务器用事先储存的公钥进行解密,如果成功就证明用户是可信的,允许你登录并且不再要求密码



那当我们在本机执行 git-over-ssh 操作的时候,难道就能登录到服务器的 bash 终端搞事情吗?显然是不可能的:服务器不可能让我们用户登录终端执行一切命令,除非服务器管理人员想让用户体验 rm -rf /* 删库跑路的感觉


因此 GitLab 使用了 SSH 的一个特性:通过 authorized_keys 指定登录后要执行的命令。之前登录的时候远程服务器是直接将用户公钥追加到 $HOME/.ssh/authorized_keys 文件末尾


而现在作为服务器管理人员,你肯定是不希望用户登录到你服务器的终端乱搞的,所以思路就是仅允许用户执行管理员所指定的 shell 命令,达到安全控制的作用,如下图所示


上图主要是说,当我们在 $HOME/.ssh/authorized_keys 末尾追加如下格式的内容:

# command="./cmd ssh-rsa <my-rsa-key>"
command="/home/git/gitlab-shell/bin/gitlab-shell key-10",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa <my-rsa-key>
复制代码

用户就没办法用 ssh 登录到服务器终端搞事情了,用户登录后只能执行这条命令,执行完毕就退出

/home/git/gitlab-shell/bin/gitlab-shell key-10
复制代码

这就是为什么 GitLab Shell 如此命名,其实还是很形象的:仅允许你在服务器执行 GitLab Shell ,别的 Shell 命令,比如 rm -rf /* 一把梭的用户少给我乱来,其中这个 key-10就是 /home/git/gitlab-shell/bin/gitlab-shell 命令的执行参数 ARGV,表示的当然是用户的密钥标识

接下来我们来看看 /home/git/gitlab-shell/bin/gitlab-shell 的代码


注意,我们还能用 $SSH_ORIGINAL_COMMAND 变量取到客户端发来的命令,现在做个实验:打印出 /home/git/gitlab-shell/bin/gitlab-shellwhooriginal 变量值

# 打印变量值
File.write("/tmp/git_original_cmd", original_cmd)
File.write("/tmp/git_who", who)
复制代码

 当我在本地分别执行 git push | git fetch | git pull | git clone 的时候,打印的值分别是:

// action => original_cmd who
git push => git-receive-pack 'BradeHyj/ToyProject.git' key-11
git fetch => git-upload-pack 'BradeHyj/ToyProject.git' key-11
git pull => git-upload-pack 'BradeHyj/ToyProject.git' key-11
git clone => git-upload-pack 'BradeHyj/ToyProject.git' key-11
复制代码

git-receive-pack - Receive what is pushed into the repository

git-upload-pack - Send objects packed back to git-fetch-pack

上述说明了什么?当我们在本地执行 git push 操作的时候,包含了登录服务器执行命令的操作(而且这个登录操作后面是带 gitlab-shell 所能识别的命令),写具体点就是:

# git push
ssh user@host:port git-receive-pack 'BradeHyj/ToyProject.git'
复制代码

以上,针对 GitLab Shell 是如何接收到客户端 ssh 请求,我们做了相应的解释,我们再回头看变量 whooriginal_cmd

  • who : sshd 调用 GitLab Shell 时传入的参数
  • original_cmd : 前面提到的 $SSH_ORIGINAL_COMMAND 变量,取到后即移除

感兴趣的可以深入研究 Pro git 2 关于 ssh 智能传输协议的介绍,具体如下:git-scm.com/book/zh/v1/…

凡是经过 gitlab-shell 执行的 git 命令,在真正执行前都会进行校验权限的操作,具体如下代码所示

# lib/gitlab-shell.rb
...
  def verify_access
    status = api.check_access(@git_access, nil, @repo_name, @who || @gl_id, '_any', GL_PROTOCOL)

    raise AccessDeniedError, status.message unless status.allowed?

    status
  end
复制代码

Git 钩子为何物

GitLab Shell 的处理逻辑是依赖 git 钩子脚本的。GitLab 服务器端存储的所有代码仓库的 hooks 文件夹都是链接到 /home/git/gitlab-shell/hooks 中的,所以理解 gitlab-shell 钩子脚本的执行逻辑非常重要


此处引用 Pro Git 2 对服务端钩子的内容介绍:git-scm.com/book/zh/v2/…

钩子都被存储在 Git 目录下的 hooks 子目录中。 也即绝大部分项目中的 .git/hooks 。 当你用 git init 初始化一个新版本库时,Git 默认会在这个目录中放置一些示例脚本。这些脚本除了本身可以被调用外,它们还透露了被触发时所传入的参数。 所有的示例都是 shell 脚本,其中一些还混杂了 Perl 代码,不过,任何正确命名的可执行脚本都可以正常使用 —— 你可以用 Ruby 或 Python,或其它语言编写它们。 这些示例的名字都是以 .sample 结尾,如果你想启用它们,得先移除这个后缀。

把一个正确命名且可执行的文件放入 Git 目录下的 hooks 子目录中,即可激活该钩子脚本。 这样一来,它就能被 Git 调用

作为系统管理员,你可以使用若干服务器端的钩子对项目强制执行各种类型的策略。这些钩子脚本在推送到服务器之前和之后运行。推送到服务器前运行的钩子可以在任何时候以非零值退出,拒绝推送并给客户端返回错误消息,还可以依你所想设置足够复杂的推送策略。

  • pre-receive : 处理来自客户端的推送操作时,最先被调用的脚本是 pre-receive。 它从标准输入获取一系列被推送的引用。如果它以非零值退出,所有的推送内容都不会被接受。 你可以用这个钩子阻止对引用进行非快进(non-fast-forward)的更新,或者对该推送所修改的所有引用和文件进行访问控制。
  • update : update 脚本和 pre-receive 脚本十分类似,不同之处在于它会为每一个准备更新的分支各运行一次。 假如推送者同时向多个分支推送内容,pre-receive 只运行一次,相比之下 update 则会为每一个被推送的分支各运行一次。 它不会从标准输入读取内容,而是接受三个参数:引用的名字(分支),推送前的引用指向的内容的 SHA-1 值,以及用户准备推送的内容的 SHA-1 值。 如果 update 脚本以非零值退出,只有相应的那一个引用会被拒绝;其余的依然会被更新。
  • post-receive : post-receive 挂钩在整个过程完结以后运行,可以用来更新其他系统服务或者通知用户。 它接受与 pre-receive 相同的标准输入数据。 它的用途包括给某个邮件列表发信,通知持续集成(continous integration)的服务器,或者更新问题追踪系统(ticket-tracking system) —— 甚至可以通过分析提交信息来决定某个问题(ticket)是否应该被开启,修改或者关闭。 该脚本无法终止推送进程,不过客户端在它结束运行之前将保持连接状态,所以如果你想做其他操作需谨慎使用它,因为它将耗费你很长的一段时间。

咱们先看看 gitlab-shell 的pre-receive 的逻辑(以下示例代码均在 $gitlab-shell/hooks文件夹里)


可以看到在对服务器仓库进行推送(git-receive-pack)之前得先执行用户权限认证及授权等准备工作


post-receive 同理,与 pre-receive 的区别主要是执行逻辑不同


对于服务器端仓库操作的任何 git 命令执行完成后,都要调用 GitLab Rails 的 post_receive 接口处理后续逻辑


GitLab Shell 组件简介

GitLab Shell 组件用于处理 GitLab 所有的 git SSH 会话。当用户以 SSH 的方式访问 GitLab 时(例如 git pull/push over ssh),GitLab Shell 组件会做下列事情:

  1. 限制用户使用预定义的 git 命令(git push, git pull 等)
  2. 调用 GitLab Rails 的 API 接口以检查用户是否已授权,以及判断用户通过哪台 Gitaly 服务器访问代码仓库(Gitaly 组件的主要功能是进行与代码仓库相关的操作)
  3. 在 SSH 客户端和 Gitaly 服务器之间来回拷贝数据

当我们执行 git pull/push over ssh 时,分别发生以下的事情:

  1. git pull over ssh -> gitlab-shell -> 调用 gitlab-rails 的 api 接口以认证用户信息并授权 -> 授权成功或失败 -> 建立 Gitaly 会话
  2. git push over ssh -> gitlab-shell(此时服务器的 git 命令还未被执行) -> 建立 Gitaly 会话 -> 在 Gitaly 服务器执行 gitlab-shell 的 pre-receive 钩子脚本 -> 调用 gitlab-rails 的 api 接口以认证用户信息并授权 -> 授权成功或失败

由于历史原因 gitlab-shell 组件也包含了允许 GitLab 校验用户 git push 命令的钩子脚本(例如,判断当前用户是否有权限将本地代码变动 push 到某保护分支),这些钩子脚本同时也能触发 GitLab 的事件(比如当用户成功推送代码后触发 CI 流水线启动等)。从目前的架构来看,gitlab-shell 的 git 钩子脚本是属于 Gitaly 组件的,钩子脚本只会运行在 Gitaly 服务器。在 Gitaly 服务器安装 gitlab-shell 组件实属没必要,具体看 gitlab.com/gitlab-org/…

附录

参考链接

gitlab-shell 官方仓库

Pro git 2

GitLab系列1 基础功能及架构简介
GitLab系列2 GitLab Workhorse
GitLab系列3 Unicorn


关注下面的标签,发现更多相似文章
评论