企业官网建设流程全解析

刚接手公司 GitLab 的时候，我做的第一件事不是迁移仓库，也不是调 CI/CD，而是先弄清楚当前 GitLab 版本。不是我有强迫症，而是后面所有动作都离不开这个数字：安全漏洞通告要对照版本号，Jenkins 插件连不上要知道 API 是否兼容，甚至升级前选什么升级路径也得从版本号算起。很多人觉得查 GitLab 版本很简单，实际真到排查问题时，反而常常卡在这步——不是不知道点哪里，而是不知道自己这台 GitLab 是哪种部署方式，也不知道该信哪个输出。

这篇文章就把 5 种查询 GitLab 版本的方法全部拆开讲一遍，从页面点击到 API 调用，从 SSH 命令行到容器内部，每种方法都会说明适用场景、操作命令和容易踩的坑。不管你是刚接触 GitLab 的新手，还是被升级问题折腾过的运维，应该都能从中找到自己需要的那条路径。

1. 同样叫GitLab，部署方式不同，查版本的方式也不同

1.1 先认清自己用的是哪一种GitLab

很多人上来就执行命令，结果发现报错，于是开始怀疑人生。其实问题往往出在部署形态上。GitLab 虽然对外都是一个统一的 Web 系统，但底层安装方式差别挺大，查询版本的入口也各不相同。

目前常见的部署形态有四种：

• Omnibus 软件包安装：这是 Linux 服务器上最常见的安装方式，安装后所有组件都在/opt/gitlab目录下，由gitlab-ctl统一管理。这种形态下，GitLab 自带的 Ruby、PostgreSQL、Redis 等运行时环境全部封装好了，查询版本可以直接用系统命令，也可以用 GitLab 提供给管理员的专用命令。

• Docker 容器部署：官方镜像本质上是对 Omnibus 的容器化封装，所以你docker exec进容器之后，看到的还是/opt/gitlab那一套。查询逻辑和 Omnibus 大体一致，只是多了容器这层壳。

• Kubernetes Helm Chart 部署：生产环境里越来越多团队这么干。GitLab 在 K8s 里被拆成了多个 Deployment，比如 webservice、sidekiq、toolbox 等，但核心应用容器内部依然是 Omnibus/Docker 镜像的底子。需要注意的是，在 Kubernetes 里你没法直接docker exec，得用kubectl exec。

• 源码安装：这种方式在官方很早就不再推荐，但有些老企业内部还留着。源码安装没有/opt/gitlab/version文件，也没有gitlab-rake命令，版本信息通常写在源码根目录的VERSION文件里。

另外还有 GitLab.com 这类 SaaS 托管服务，用户不接触底层服务器，版本由官方维护，一般不需要自己查。如果非要知道当前 GitLab.com 的版本，官方更新公告和帮助页面里通常能看到，但这不在自主可控的查询范围内。

1.2 版本号到底在告诉你什么

确定部署方式之后，还需要理解版本号的组成。GitLab 的版本号格式一般是这样的：

16.10.2-ee

拆开看就是主版本号、次版本号、补丁版本号，加上一个安装类型后缀。16是大版本，10是小版本，2是补丁修订版，-ee表示这是企业版安装包。在早期版本里，你会看到-ce后缀，表示社区版。新版 GitLab 已经不单独发布社区版安装包，而是以 EE 包为统一分发，核心功能依然免费开源，但查询的时候后缀仍然是-ee。

大版本升级通常伴随破坏性变更，不能随便跳版本。比如从 13.x 直接升到 16.x，官方升级文档一般要求按大版本逐级升，中间可能还要处理好几次数据迁移。所以“当前版本是多少”并不是一个无关紧要的信息，它直接决定了你接下来能走哪条升级路线。补丁版本则通常包含安全修复和 bug 修复，安全通告出来后，第一件事就是对照自己实例的补丁版本判断是否受影响。

2. 5种查询版本的方法，每一种都附完整命令和操作

2.1 方法一：界面查询，适合不想碰命令行的普通用户

如果你的 GitLab 能正常登录，页面查询是最直观的方式。

登录之后，点击右上角的“问号”帮助图标，或者从用户头像菜单里进入 Help 页面。帮助页面会显示当前 GitLab 的版本信息，包括社区版/企业版标识、版本号和修订号。不同版本界面略有差异，但基本都能在帮助页找到。

管理员还可以直接打开/admin后台管理页面，首页通常会显示当前版本号，有些版本还会提示是否有可用更新。这个入口适合管理员日常巡检，不需要记任何命令。

还有一个容易被误导的入口：登录页底部。有些 GitLab 实例会在登录页直接显示版本号，但也有不少管理员出于安全考虑会通过反向代理或配置隐藏这部分信息。所以登录页能看到版本号只是运气好，看不到也不代表查不了，不要依赖这一处。

界面查询最大的缺点是没法自动化。如果你要管理几十台 GitLab 实例，不可能一台台登录页面去记。这时候就需要用到后面几种方式。

2.2 方法二：API查询，适合脚本和监控系统

GitLab 官方提供了一个专门返回实例版本信息的 API 接口：

GET /api/v4/version

调用这个接口需要身份验证。推荐先在 GitLab 里创建一个 Personal Access Token，路径一般是：

用户头像 -> Edit Profile -> Access Tokens

创建时勾选read_api或api权限，具体取决于你的 GitLab 版本对只读 Token 的支持情况。填写名称和过期时间，生成后立刻复制保存，Token 只显示一次。

然后通过 curl 请求：

curl --header "PRIVATE-TOKEN: 你的token" https://gitlab.example.com/api/v4/version

正常返回结果是这样：

{"version":"16.10.2-ee","revision":"1a2b3c4d"}

version字段是版本号，revision是代码修订哈希，通常在精确定位问题时才有用。

如果你是在脚本里用，一般会配合jq做解析：

curl -sS --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ https://gitlab.example.com/api/v4/version | jq -r .version

API 方式是最适合自动化的查询入口。监控系统、CI/CD 流水线、资产管理系统都可以定时调用这个接口，把版本信息收集起来。需要注意一点，某些旧版本 GitLab 的 API 路径可能是/api/v3/version，而 v3 接口在 11.0 版本中已经被移除。如果你维护的实例非常老，先确认 API 版本，新实例统一走 v4。

2.3 方法三：Omnibus命令行查询，适合SSH登录服务器排障

当 GitLab 页面打不开，或者你需要到服务器上排查故障时，命令行方式就派上用场了。对 Omnibus 安装的 GitLab，最简单直接的办法是读版本文件：

sudo cat /opt/gitlab/version

这个文件是 GitLab 在运行环境中维护的，通常能准确反映当前程序版本。

除了直接读文件，还可以用 GitLab 自带的 rake 命令查看完整的环境信息：

sudo gitlab-rake gitlab:env:info

这个命令输出的信息量比较大，除了 GitLab 版本，还会包含系统平台、Ruby 版本、PostgreSQL 版本、是否使用源码安装等。排障的时候这些信息往往比单纯一个版本号更有用。

如果你习惯用 Rails Runner，也可以这样：

sudo gitlab-rails runner "puts Gitlab::VERSION"

这个命令本质上是进入 GitLab Rails 应用环境，输出内部的Gitlab::VERSION常量，结果和页面显示一致。

为什么我不建议在这种情况下优先用rpm -q或者dpkg -l去查包版本？因为 Omnibus 升级时，系统软件包管理器记录的是安装包状态，而程序真正运行的版本要等gitlab-ctl reconfigure完成之后才更新。在一些中断的升级场景里，包版本和进程实际版本可能不一致。/opt/gitlab/version和gitlab-rake这类入口直接读取程序运行时环境，更接近真实情况。

2.4 方法四：Docker容器查询，适合容器化部署

Docker 部署的 GitLab 虽然也是 Omnibus 内核，但你不能直接在宿主机上执行cat /opt/gitlab/version，因为那是容器内部的路径。先看容器名：

docker ps

找到 GitLab 容器后，直接读版本文件：

docker exec gitlab cat /opt/gitlab/version

也可以进容器执行 rake 命令：

docker exec -it gitlab gitlab-rake gitlab:env:info

这里要注意，-it参数在无人值守的脚本里会挂起，脚本环境中建议去掉-t，只保留-i甚至两个都去掉：

docker exec gitlab gitlab-rake gitlab:env:info

如果你不想进容器，也可以通过镜像标签间接判断。先查容器使用的镜像：

docker inspect gitlab --format '{{.Config.Image}}'

如果输出是gitlab/gitlab-ee:16.10.2-ee.0，那么版本号就在镜像标签里。但这里有个坑：如果当初拉取的是latest标签，或者容器内部做过升级而镜像 tag 没变，通过docker inspect拿到的版本就不可信。所以在容器环境里，我始终建议优先用docker exec读内部版本文件，而不是依赖镜像 tag。

Kubernetes 部署同理。先用kubectl get pods找到 GitLab 相关 Pod，然后 exec 进去：

kubectl exec -it deploy/gitlab-webservice-default -- cat /opt/gitlab/version

Pod 名称会根据 Helm Chart 版本变化，如果 exec 不进去，也可以看 Deployment 的镜像 tag：

kubectl get deployment gitlab-webservice-default -o jsonpath='{.spec.template.spec.containers[0].image}'

但和 Docker 一样，镜像 tag 反映的是启动时的镜像版本，容器内后续升级过就不准确了。最稳妥的还是 exec 进入主应用容器读/opt/gitlab/version。

2.5 方法五：包管理器与源码文件查询，适合资产审计

有些场景下你不需要登录 GitLab，也不方便进容器，只想知道这台服务器上到底装了哪个版本的 GitLab 安装包。这时候可以直接问系统包管理器。

RPM 系（CentOS、Rocky Linux 等）：

rpm -q gitlab-ce

如果安装的是企业版，把包名换成gitlab-ee：

rpm -q gitlab-ee

不确定包名的话，可以模糊搜索：

rpm -qa | grep gitlab

Debian/Ubuntu 系：

dpkg -l | grep gitlab

运行结果会显示安装的 GitLab 软件包版本。这个方法很适合资产盘点，快速确定一批服务器上的 GitLab 版本分布。但请记住，它只代表软件包层面的安装/升级记录，不代表进程实际运行版本，排查问题时需要以 2.3 节的方式交叉确认。

源码安装的情况比较少见。如果你手上真有源码部署，版本信息一般在源码根目录的VERSION文件里：

cat VERSION

也有可能是从 Git 仓库直接拉的代码，那就要看当前 checkout 的 tag 或 commit 来确认版本了。

3. 方法选型对照：什么场景下用哪种方式最顺手

3.1 一张表看清5种方式的差异

把上面五种方式放在一起看，各自的适用场景差异其实很明显：

准确度方面，界面、API、Omnibus 命令、容器内部文件这几种方式都指向 GitLab 程序自身，基本可以认为是权威来源。包管理器只能作为辅助验证，在异常升级场景下可能和真实版本有差异。

3.2 我的选型习惯

日常工作中，我基本遵循这样的选择路径：

如果只是同事问一句“现在 GitLab 什么版本”，我会直接打开/help页面复制版本号发给他，最快也最没有歧义。

如果是排查 Jenkins 集成问题或者其他服务连接问题，我会先用 API 手动 curl 一下/api/v4/version，确认当前版本号和接口是否正常。这一步能同时验证版本、Token、网络三个因素。

如果是登录不了页面、服务起不来，那就 SSH 到服务器先cat /opt/gitlab/version，再执行gitlab-rake gitlab:env:info查看完整环境信息。这个组合基本能覆盖 90% 的启动类故障。

如果是容器环境，一律用docker exec进容器查，不信任镜像 tag。尤其是有同事拉过latest标签的情况，镜像 tag 很容易误导人。

如果是要做几十台服务器版本盘点，我会写一个基于 API 的批量脚本，循环调用版本接口，把结果整理成一个 CSV 或直接输出到终端。这个方法最安全，因为不需要批量 SSH 到每台机器上执行命令，对生产环境打扰最小。

4. 查版本翻车实录：常见报错与排查链路

4.1 Jenkins 连接 GitLab 报 “login failed. check api token or gitlab version.”

这个报错在排查 GitLab 集成问题时非常常见，很多同学一看到 “check api token or gitlab version” 就开始怀疑版本，其实这个提示的意思是“GitLab 插件调用 API 失败了”，具体原因可能有很多。

我一般的排查链路是：

第一步，先在浏览器里确认 GitLab 版本，同时看 Jenkins 里安装的 GitLab 插件版本。

第二步，手动用 curl 验证 API 和 Token 是否正常：

curl -i --header "PRIVATE-TOKEN: 你的token" https://gitlab.example.com/api/v4/version

如果返回 200 和 JSON 版本信息，说明 Token 和 API 路径没问题，问题大概率在 Jenkins 插件配置本身，比如填写的 GitLab URL 不对、Token 复制多了空格、或者 Jenkins 到 GitLab 之间有网络限制。

如果返回 401 或 403，那问题出在 Token 权限或有效性上。很多插件配置里需要的是具备apiscope 的 Token，而不仅仅是read_repository权限。

如果返回 404，就要检查是不是 API 路径写错，或者旧插件默认请求了api/v3，而当前 GitLab 已经不支持 v3 接口。这种情况下，升级 Jenkins 里的 GitLab 插件往往就能解决。

这个报错提示里出现的 “gitlab version”，指的是插件和 GitLab API 版本之间的兼容性，不是让你去升级 GitLab 主版本。除非插件文档明确要求更高版本，否则不要为了消除这个报错贸然升级生产环境。

4.2 API 返回 404 或 403，但不清楚原因

API 调用失败时，先用curl -i看完整响应头和响应体，很多信息都藏在里面。

403 通常是权限问题。检查 Token 是否过期、是否勾选了apiscope、用户是否被禁用或锁定。GitLab 实例启用了 IP 白名单限制时，你的来源 IP 不在范围内也可能被拒绝。

404 比较迷惑人，因为 GitLab API 出于安全考虑，有时候对“无权限访问的资源”也会返回 404 而不是 403，目的是不暴露资源是否存在。如果你确认 URL 没问题，可以换个管理员 Token 再试一次，往往就能区分是路径问题还是权限问题。

另一个 404 的常见原因是反向代理没有把/api路径转发到 GitLab。Nginx 或者云负载均衡的转发规则里，如果只配了/而 GitLab 的external_url路径配置不一致，页面上能打开但 API 访问会失败。

4.3gitlab-rake命令找不到命令

如果你 SSH 到服务器执行sudo gitlab-rake gitlab:env:info，系统提示command not found，大概率这台机器不是个标准的 Omnibus 安装。可能的情况包括：

• 你跑错了容器，到了某个没有安装 GitLab 的机器上。
• GitLab 是通过源码方式部署的，没有gitlab-rake封装。
• 安装目录不是默认的/opt/gitlab，命令不在 PATH 里。

可以先用which gitlab-rake看一下，再检查/opt/gitlab/bin/下是否存在。Omnibus 安装的 GitLab 一般会把命令软链到/usr/bin/gitlab-rake，如果/opt/gitlab/bin下存在但软链丢了，可以手动用绝对路径执行：

sudo /opt/gitlab/bin/gitlab-rake gitlab:env:info

4.4 登录页、包管理器、API 三处版本对不上

这种情况我遇到过不止一次。

最典型的是你刚执行完rpm -Uvh gitlab-ee.rpm，还没跑gitlab-ctl reconfigure，此时包管理器的版本已经变成新的，但 GitLab 程序还在用旧版本运行。页面和 API 返回的是旧版本，rpm -q显示的是新版本。

遇到这种情况不用慌，完整的升级流程应该是：

sudo rpm -Uvh gitlab-ee-16.10.2-ee.0.rpm sudo gitlab-ctl reconfigure sudo gitlab-ctl restart sudo cat /opt/gitlab/version

/opt/gitlab/version文件是在 reconfigure 过程中更新的，所以它和程序实际运行版本更一致。我在升级场景里始终以它和 API 返回结果为准，rpm -q只作为辅助判断安装包是否落地。

还有一种情况是你看了错误的那台服务器。公司里有测试环境和生产环境，域名长得差不多，同事改个 Hosts 指到了测试环境，结果版本和预期完全不一样。查版本之前，先确认你访问的域名、端口、服务器 IP 对应关系，这是排查这类问题最容易忽略的一步。

4.5 Docker 镜像 tag 是 latest，看不出任何有用信息

Docker 部署时，很多人图方便直接用latest标签拉镜像。这么做在测试环境没关系，生产环境后患无穷：容器重新创建时拉取的镜像版本可能和之前不一样，升级不受控，而且排查问题时docker inspect输出gitlab/gitlab-ee:latest，你根本不知道跑的是什么版本。

正确做法是：

• 脚本或文档里明确记录当前期望的完整版本 tag。
• 查版本时用docker exec gitlab cat /opt/gitlab/version，不要依赖docker inspect。
• 如果发现容器内版本和预期不符，赶紧把镜像 tag 固定下来，重新规划升级。

这里多说一句，Docker 内部虽然可以升级 GitLab，但很多人忽略了容器升级后镜像本身不变，一旦重新docker run，又会回到旧镜像版本。所以容器部署要养成“以镜像 tag 作为版本声明，以容器内版本文件作为实际运行事实”的习惯。

5. 把版本检查变成自动化：脚本与日常运维习惯

5.1 用一个脚本批量检查多台 GitLab 实例

当你需要管理多台 GitLab 的时候，再一台台去点页面或者 SSH 就太浪费时间了。我习惯写一个简单的 shell 脚本，通过 API 批量查询版本。

下面是一个可以直接套用的脚本：

#!/bin/bash # check_gitlab_version.sh # 用法: GITLAB_TOKEN=xxx ./check_gitlab_version.sh GITLAB_TOKEN="${GITLAB_TOKEN:?请先设置 GITLAB_TOKEN}" # 定义要检查的实例列表 INSTANCES=( "https://gitlab1.example.com" "https://gitlab2.example.com" "https://gitlab3.example.com" ) # 可选：设置期望版本，留空则只输出版本不比对 EXPECTED_VERSION="16.10.2-ee" for url in "${INSTANCES[@]}"; do echo "===== $url =====" result=$(curl -sS --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "$url/api/v4/version") if [ $? -ne 0 ]; then echo "连接失败" continue fi echo "$result" | jq -r '"version: " + .version + ", revision: " + .revision' if [ -n "$EXPECTED_VERSION" ]; then current=$(echo "$result" | jq -r .version) if [ "$current" = "$EXPECTED_VERSION" ]; then echo "版本符合预期" else echo "版本不一致，当前 $current，期望 $EXPECTED_VERSION" fi fi done

使用的时候：

export GITLAB_TOKEN="你的token" ./check_gitlab_version.sh

脚本里用环境变量传递 Token，避免把密钥硬编码进文件。如果输出包含版本和“符合预期”或“不一致”的提示，一眼就能看出哪些实例需要关注。把这个脚本放到跳板机或运维机上，比每次手工 SSH 高效得多。

Token 的权限建议尽量收敛。只用来查版本的话，read_api通常够用；如果实例版本比较老，对只读 Token 支持不完善，再用api权限。Token 要设置过期时间，别为了省事设一个永久 Token 然后遗忘在脚本里。

5.2 把检查放到 CI 或 cron 里，形成巡检习惯

脚本写完之后，最重要的是定时执行。我通常会在一个专门的运维仓库里加一个 GitLab CI Job，每天跑一次版本检查：

stages: - check version-check: stage: check image: alpine:latest script: - apk add --no-cache curl jq - export GITLAB_TOKEN="$READ_ONLY_API_TOKEN" - ./check_gitlab_version.sh only: - schedules

这里用schedules触发定时流水线，Token 放在 CI 变量里，脚本里不用出现明文密钥。如果检查逻辑里返回非零退出码，GitLab CI 就会标记失败并发送通知，相当于一个轻量级的版本合规监控。

如果你不想引入 CI，也可以在服务器上写 crontab：

0 9 * * * export GITLAB_TOKEN=xxx; /opt/scripts/check_gitlab_version.sh > /tmp/version_check.log 2>&1

注意 crontab 里环境变量处理比较别扭，建议把 Token 放到一个只有 root 可读的配置文件里，比如/etc/gitlab_version_check.env，脚本启动时读取这个文件。这样即使服务器被非管理员用户访问，Token 也不会暴露。

自动化版本检查的价值主要体现在两个地方：

一是安全通告发布后，你能在几分钟内过滤出哪些实例受影响，而不是一台台登录进去查。二是升级规划时，你能直接拉出当前生产环境所有实例的版本列表，结合官方升级路径判断哪些需要先升、哪些可以直接升。

5.3 升级前后我必做的几件事

最后分享一个我自己的操作习惯，算不上标准流程，但踩过几次坑之后一直没有再出过大问题。

升级前，我会用至少两种方式交叉确认当前版本。比如先看/opt/gitlab/version，再调一次/api/v4/version，两者一致才开始规划。这个确认动作很基础，但经常被省略，尤其是生产环境有多个实例的时候，查错实例是升级事故的常见前奏。

然后查官方升级路径文档。GitLab 官方对跨大版本的升级路线有严格要求，不是所有版本都能直接跳到最新版。比如一些老版本要先升到特定中间版本，再继续往后升。如果忽略了中间版本，升级过程中很可能遇到数据库迁移失败或者服务起不来。

升级前还要做配置备份和数据备份。Omnibus 环境下常用的备份方式：

sudo gitlab-backup create sudo cp -r /etc/gitlab /path/to/backup/gitlab-config-$(date +%F)

gitlab-backup备份的是 GitLab 的核心数据，/etc/gitlab里是配置文件、密钥、证书等。两个备份最好分开放，分别保存，因为恢复时两者可能都需要用。

升级完成后，我会再次执行版本查询，确认已经变成目标版本。然后花几分钟检查几个关键入口是否正常：页面能登录、API 能返回版本、Runner 能注册或能拿到任务。如果有人正在使用 Jenkins 集成，也会顺手确认一下 GitLab 插件连接是否正常，因为大版本升级有时候会影响 API 返回的数据结构，导致插件报错。

这些都确认完之后，我才会在交接记录里写“本次升级完成”。查版本虽然只是其中一个不起眼的动作，但整个升级过程的安全感，恰恰是从这些不起眼的确认步骤里来的。