企业官网建设流程全解析

1. 为什么我选择用Docker搭GitLab，而不是直接安装

1.1 先理清Git、GitLab、IDEA三者关系

很多新手一开始会被这三个词搞晕，我先把它们的关系说明白。Git是一个分布式版本控制工具，它负责记录代码的每一次改动，让你可以随时回溯、对比、合并。GitLab则是一个基于Git的远程仓库管理平台，你可以把它理解成“放在服务器上的代码中心”，团队所有人通过它来同步代码、管理分支、做代码审查。而IDEA（IntelliJ IDEA）是日常写代码的IDE，它内置了Git客户端，让我们不用敲命令行，直接在图形界面里完成提交、拉取、推送、解决冲突这些操作。

这三者的关系就像什么呢？Git是“记账本”，GitLab是“公共账房”，IDEA就是“柜台”。你在柜台（IDEA）记账（Git提交），然后把账本副本交到公共账房（GitLab）保存，大家都能从账房取最新账本查看。

1.2 Docker部署GitLab的优势与演进思路

搭建GitLab服务器，业界最主流的方式有两种：一种是直接用官方Omnibus包安装到物理机或虚拟机，另一种就是我今天要重点讲的，用Docker容器化部署。

我先后用过这两种方式，如果让我给现在的团队重新选，我肯定会用Docker。原因有三个：

第一，隔离性好。GitLab依赖的组件非常多——PostgreSQL数据库、Redis缓存、Nginx反向代理、Gitaly存储服务等等，用Omnibus安装时这些组件会散落在系统各处，升级、卸载、迁移都是灾难。而Docker把这些全部装进一个容器里，宿主机干干净净。

第二，升级回滚极其方便。GitLab的升级其实是个容易踩坑的活，特别是跨大版本升级，经常要一步步来，还不能跳版本。用Docker后，只需要拉新镜像、重启容器，几分钟搞定；如果出问题，切回旧镜像就行。我后面会详细讲。

第三，迁移方便。换服务器？直接把挂载的目录打包拷走，新机器上一条docker run命令就能恢复原样，数据完全一致。

当然，Docker部署也有缺点，比如容器内的数据卷权限问题、性能上略有损耗，但对于中小团队和私人仓库来说，这些完全可以接受。我这也算是“先折腾，后省心”的路线，下面把我的完整部署过程分享出来。

2. GitLab服务器搭建全流程

2.1 初始化环境与挂载目录准备

我假设你已经有一台Linux服务器，系统是CentOS 7或者Ubuntu 20.04以上都行，内存建议不低于4G，GitLab对内存的要求不低，实测2G内存跑起来会经常告警，4G才能比较流畅。

先更新系统并安装Docker，注意这里用的是官方脚本安装，比某些教程里从第三方源安装靠谱得多：

# 更新系统包（CentOS用yum，Ubuntu用apt，我以Ubuntu为例） sudo apt update && sudo apt upgrade -y # 安装必要的依赖 sudo apt install -y curl vim git # 安装Docker（官方脚本） curl -fsSL https://get.docker.com | bash -s docker # 设置Docker开机自启并启动 sudo systemctl enable docker sudo systemctl start docker

接下来创建GitLab的数据挂载目录。Docker容器是无状态的，容器一删，里面的数据就没了。所以我必须把GitLab的数据目录挂载到宿主机上，这样容器删除重建，数据依然还在。

# 创建三个重要目录 sudo mkdir -p /srv/gitlab/config # 配置文件 sudo mkdir -p /srv/gitlab/logs # 日志文件 sudo mkdir -p /srv/gitlab/data # 仓库数据、数据库数据

这三个目录分别对应GitLab的配置、日志和核心数据。特别是data目录，里面存着所有的代码仓库、数据库记录、用户信息，可以说是命根子，一定要定期备份。我在实际部署中就吃过亏——一开始没把data目录挂出来，后来容器出问题想重建，才发现什么都没留下，只能从头再配。

2.2 Docker运行GitLab的关键参数

环境准备好后，跑GitLab容器。先设置一个环境变量GITLAB_HOME，后面所有命令都会用到，省得每次打一串路径：

export GITLAB_HOME=/srv/gitlab

然后运行容器。我这里用的是gitlab-ce镜像，CE是社区版，免费且功能足够用。注意，如果你是在国内服务器上拉取镜像，建议先配置Docker加速器，否则docker pull可能慢到怀疑人生。

sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8443:443 --publish 8080:80 --publish 2022:22 \ --name gitlab \ --restart always \ --volume $GITLAB_HOME/config:/etc/gitlab \ --volume $GITLAB_HOME/logs:/var/log/gitlab \ --volume $GITLAB_HOME/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest

别急着复制命令，我先拆解一下这几个参数：

• --hostname gitlab.example.com：这是最关键的一个参数，它决定了GitLab生成的所有仓库clone地址中的域名。如果你有域名就填域名，没有域名可以填IP地址，比如--hostname 192.168.1.100，后续所有URL都会用这个IP。
• --publish 8443:443：把宿主机的8443端口映射到容器的443端口，这是HTTPS访问地址，我实际用8080比较多。
• --publish 8080:80：宿主机8080端口映射容器80端口，这是HTTP访问地址。之所以不用默认的80端口，是因为我的服务器上还有别的Web服务，避免冲突。
• --publish 2022:22：宿主机2022端口映射容器22端口，这是SSH协议的访问地址。GitLab的SSH通道默认走22端口，但我的服务器本身就用22端口做系统SSH，所以映射成2022，避免冲突。
• --restart always：容器挂了或者服务器重启后自动拉起，非常实用，否则你半夜被报警吵醒只是去起个容器，太亏了。

2.3 初始root密码获取与首次登录

第一次启动GitLab，容器初始化过程比较慢，因为里面要初始化数据库、编译一堆东西。我第一次部署时不知道这个情况，以为卡死了，盯着屏幕看了十分钟。后来才知道可以这样检查状态：

sudo docker logs -f gitlab # 持续查看日志 sudo docker ps # 查看容器状态

看到日志中出现gitlab Reconfigured!，说明GitLab已经准备好。这时候打开浏览器，访问http://你的服务器IP:8080，页面会跳转到设置root密码的界面。新版本GitLab首次访问会让你设置root管理员密码，直接输一个强密码就行。

如果没出现设置密码的页面，而是让你登录，那密码就在配置目录里。我用过一个很实用的方法获取初始密码：

# 进入GitLab容器 sudo docker exec -it gitlab bash # 查看初始root密码 cat /etc/gitlab/initial_root_password

这个文件在首次配置完成后会自动删除，所以如果它已经不存在了，就说明密码已经设置过了，直接在登录页用root加你设置的密码登录即可。

登录之后，第一件事建议去修改语言。新版GitLab支持简体中文，在右上角头像的偏好设置里把Language改成“简体中文”，整体体验会好很多。不过说实话，用久了你会发现英文界面反而更顺手，很多技术文档里的名词都是英文的，不过我理解新手阶段中文界面更友好。

提示：GitLab首次启动的等待时间大约需要3-10分钟，根据不同机器的性能而定。这期间不要强制重启容器，否则可能导致配置文件损坏，再等的时间更久。

我自己的服务器开机时间大概5分钟，期间我一般去准备SSH密钥和IDEA环境，时间刚好利用起来。

3. 基础配置：SSH密钥、HTTP clone地址与仓库安全

3.1 SSH密钥配置：一次配置，处处免密

GitLab配置SSH密钥，核心目的就是让你在clone、push代码时不用每次输密码。原理很简单：本地生成一对密钥（公钥和私钥），把公钥放到GitLab服务器上，之后GitLab通过公钥识别你的身份，而私钥留在本地不离开你的电脑，安全又方便。

第一步，在本地电脑生成密钥。Windows用户打开Git Bash，Mac和Linux用户打开终端：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

这里我推荐用ed25519算法而不是传统的rsa，因为ed25519更安全、密钥更短、生成更快。如果你不想改，用默认的rsa也行，就是密钥文件会大一点。

敲完回车后会有几个交互提示：第一个问你要把密钥存在哪里，默认是~/.ssh/id_ed25519，直接回车即可；第二个问你设置passphrase（密钥口令），这个可设可不设，我建议在公司电脑上设置一个，多一层保护。设置后每次使用SSH需要输一次口令，用ssh-agent可以记住，不影响体验。

第二步，查看公钥内容并复制：

cat ~/.ssh/id_ed25519.pub # 输出类似：ssh-ed25519 AAAAB3NzaC1yc2EAAAADAQABAAABAQ... 你的邮箱@example.com

第三步，登录GitLab网页，点击右上角头像，选择“偏好设置”->“SSH密钥”，把公钥内容粘进去，标题随便填（比如“我自己的MacBook”），过期时间可以不选，然后点击“添加密钥”。

配置好之后，验证是否成功：

ssh -T git@你的GitLab服务器IP -p 2022

如果看到Welcome to GitLab, @用户名!这样的欢迎语，说明一切正常。这里有个小细节新手容易搞混：在SSH协议下，连接的用户名固定是git，不是你的GitLab用户名，更不是root，它就是个固定前缀。

3.2 HTTP clone地址如何从机器ID改为域名

这个问题我见太多了，也是你标题里的热搜词“gitlab clone with http 怎么clone设置为域名 不是机器id”。很多人用Docker部署GitLab时，--hostname参数没有设成域名，或者干脆没设置，结果在GitLab网页上看到的clone地址长这样：

http://a1b2c3d4e5f6/group/project.git

这个a1b2c3d4e5f6就是容器的机器ID，网络上的其他电脑根本访问不了这个地址，所以clone必然失败。要解决这个问题，不能去改每个项目的URL，得改GitLab的全局配置。

进入GitLab容器编辑配置文件：

sudo docker exec -it gitlab vi /etc/gitlab/gitlab.rb

找到这两行，去掉注释并修改：

external_url 'http://你自己的域名或者IP:8080' gitlab_rails['gitlab_shell_ssh_port'] = 2022

第一个external_url非常关键，它就是所有HTTP clone地址的前缀。如果填的是域名，那克隆地址就是http://域名/group/project.git；如果填的是IP，就是http://IP:8080/group/project.git。

保存退出后，执行重配置并重启：

sudo docker exec gitlab gitlab-ctl reconfigure sudo docker restart gitlab

等GitLab重启完成，再回到项目页面，你会发现clone地址已经变成了你设置的域名或IP。如果还显示旧的，强制刷新浏览器缓存（Ctrl+Shift+R）即可。

3.3 GitLab高危漏洞修复与版本升级思路

GitLab因为功能庞大，历史上有过不少高危漏洞，比如任意文件读取、SSRF、账户接管等。如果你部署的是旧版本，建议尽快升级到安全修复版本。

检查当前版本：

sudo docker exec gitlab cat /opt/gitlab/version-manifest.txt | grep gitlab-ce

升级的思路是这样的：用Docker部署最大的优势就是升级方便，直接拉取新版本镜像，删除旧容器，用相同参数创建新容器。但有一点必须注意——跨大版本的升级不能跳版本。比如你从12.x升到15.x，不能直接拉15.x的镜像跑，会报数据库迁移错误。正确姿势是一步步升：12 -> 13 -> 14 -> 15，每个大版本先升到该版本的最新patch。

我一般这样操作一个版本的升级：

# 1. 先做数据备份（这一步绝对不能省） sudo docker exec gitlab gitlab-backup create # 2. 拉取目标版本镜像 sudo docker pull gitlab/gitlab-ce:13.12.15-ce.0 # 3. 删除旧容器（数据都在挂载卷里，不会丢） sudo docker stop gitlab && sudo docker rm gitlab # 4. 用相同参数创建新容器，只改镜像版本 sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8443:443 --publish 8080:80 --publish 2022:22 \ --name gitlab \ --restart always \ --volume $GITLAB_HOME/config:/etc/gitlab \ --volume $GITLAB_HOME/logs:/var/log/gitlab \ --volume $GITLAB_HOME/data:/var/opt/gitlab \ gitlab/gitlab-ce:13.12.15-ce.0

升级过程中只要不变更挂载目录，数据是完全连续的。我升级过多次，从未丢过数据，但每次依然会先备份，这是职业习惯了——数据安全这件事，永远不要赌运气。

4. IDEA集成GitLab：从插件配置到日常操作

4.1 在IDEA中启用Git插件并配置路径

IntelliJ IDEA从2019.2版本开始，Git插件已经默认内置，不需要额外安装。你要做的只是告诉IDEA你的Git可执行文件在哪里。

打开IDEA，依次进入：File -> Settings -> Version Control -> Git。

这里有个关键配置项：Path to Git executable。Windows用户一般装在C:\Program Files\Git\bin\git.exe，IDEA会自动检测到；如果检测不到，就手动点击“...”（省略号）按钮去找到git.exe的位置。Mac和Linux用户一般是/usr/bin/git。

填好后，点击右侧的“Test”按钮。如果看到Git版本号弹出来，说明配置成功。如果IDEA提示找不到Git，可以先在Git Bash里执行which git确认Git确实已安装，再回到IDEA指定路径。

4.2 IDEA账号配置：Token方式与账号切换

IDEA连接GitLab，有两种认证方式：一种是用户名密码，一种是Personal Access Token。新版GitLab对密码认证越来越严格，而且如果你开启了双因素认证（2FA），就必须用Token，所以我直接推荐用Token方式。

在GitLab网页上创建Token：登录 -> 点击头像 -> 偏好设置 -> 访问令牌。填写一个名称，然后勾选权限范围。注意不要全勾，按需最小授权：

• 只拉取代码、提交代码：勾选read_repository和write_repository即可。
• 需要创建分支、管理合并请求：再加api权限。

创建完成后，GitLab会显示一串以glpat-开头的字符串，这个Token只会显示一次，一定要立即复制保存到密码管理器里，因为关掉页面后就再也看不到了。

回到IDEA，操作路径：File -> Settings -> Version Control -> GitLab。

在Login页面，Server填GitLab的地址（比如http://192.168.1.100:8080），Token填刚复制的glpat-...，点击Login。如果一切正常，IDEA会显示你的GitLab用户名。

各个账号切换的问题，很多公司会有多个GitLab平台，或者个人有公网GitLab和内网GitLab。IDEA支持在多账号间切换：在同一个设置页面，点“Add”可以添加多个GitLab服务器，使用哪个就登录哪个。如果提示“Logged in to GitLab as xxx”，说明当前登录了这个账号，切换只需要重新登录另一个即可。

4.3 从GitLab拉取项目到IDEA

现在到了最关键的实操环节：把GitLab上的代码拉到IDEA里。

在IDEA欢迎页点击“Get from VCS”，或者在打开的项目里进入File -> New -> Project from Version Control，然后在URL栏输入项目的clone地址，建议用HTTP地址（http://192.168.1.100:8080/group/project.git），因为HTTP地址只要Token认证，SSH地址还需要本机配置好SSH密钥并保持IDEA能识别，相对麻烦一些。

选好项目目录后，点击“Clone”，IDEA会自动下载代码，然后弹窗询问“要不要为这个项目创建IDEA工程”，选“Trust Project”信任项目，它会自动识别构建系统（Maven/Gradle），下载依赖，建立索引。第一次打开大项目会比较慢，因为要建立项目索引，耐心等待右下角进度条走完。

克隆完成后，IDEA右下角会显示当前分支。这时候你就可以正常改代码了。改完文件会有蓝色标记，新增文件是绿色，删除文件是灰色，这是IDEA的版本控制状态颜色，非常直观。

当你改完一批代码要提交推送，步骤是：右键项目 -> Git -> Commit Directory，弹出提交窗口。在提交窗口里，IDEA会把修改过的文件列出来，你可以勾选要提交哪些文件。填写提交信息（Commit Message）非常关键，我团队里我经常强调：提交信息要写清楚“做了什么、为什么做”，不要写一个“update”或者“fix”就完事。一份清晰的提交历史，能帮你在几个月后回溯问题时省下大量时间。

勾选Commit旁边的箭头按钮，选择“Commit and Push”可以一次完成提交和推送。如果只想提交不想推送，就点“Commit”。IDEA的提交窗口下方有个“Diff”按钮，可以在提交前查看每个文件的改动内容，强烈建议养成提交前先看Diff的习惯，能拦住很多低级错误，比如不小心改错了配置文件、多删了一行代码。

4.4 分支管理与合并冲突实战

日常开发中，分支管理是Git最核心的日常用法。IDEA右下角的分支按钮可以查看所有本地和远程分支，点击某个远程分支、再选“New Branch from Selected”就能基于它创建新分支。

团队协作最常遇到的场景是：你基于主分支拉了一个开发分支，同事也拉了一个，大家各自开发，最后要把代码合并回主分支。在IDEA里的流程我拆解一下：

第一步，更新目标分支的代码。切换到主分支（双击），然后执行Git -> Pull，把远端主分支的最新代码拉到本地。

第二步，把你的开发分支合并进来。右键当前主分支 -> Git -> Merge Branches，选择你的开发分支，点击Merge。这时候如果有冲突，IDEA会弹出冲突窗口。

冲突解决是新手最慌的环节。实际上IDEA的冲突解决工具做得非常好用：冲突文件会列出左右两栏，左边是“你的版本”（本地的），右边是“传入的版本”（别人提交的），中间是合并结果。你可以逐块选择接受左边、接受右边，或者手动修改中间的内容，把两边都想要的代码拼在一起。

我有个心得：遇到大冲突，不要急着点Accept，先读一遍两边的代码，搞清楚冲突的上下文再动手。因为很多时候，两边改的虽然是同一个文件的相近位置，但改的目的完全不同，脑残式全选一边可能直接把同事的功能改没了。我有个同事就干过这种事，合并时只看冲突块，“看起来左边的对，就全选了左边的”，结果把同事新加的配置全部覆盖了，上线后直接报错。所以解决冲突，本质上是要理解代码逻辑，而不是做选择题。

解决完所有冲突后，标记文件为已合并，然后Commit，Push，合并流程结束。

4.5 IDEA自动关闭与性能问题排查

好几位朋友和我提过一个问题，说IDEA打开一个大项目后，用着用着突然自动关闭，甚至有时候开机一打开就退出。这不是GitLab集成的问题，但既然咱们聊到IDEA的日常使用了，我顺便把这个常见的坑说一下。

IDEA突然自动关闭，绝大多数情况是内存不足。IDEA是个吃内存的大户，你同时开着好几个大项目、跑着Tomcat或者Gradle守护进程，默认的堆内存根本不够用。解决办法是手动调整IDEA的虚拟机参数：

1. 找到IDEA安装目录下的bin/idea64.exe.vmoptions（Windows）或者/Applications/IntelliJ IDEA.app/Contents/bin/idea.vmoptions（Mac）。
2. 打开后把-Xmx参数调大，比如调到2048m或4096m（取决于你机器内存）。
3. 我自己用的是16G内存的机器，给IDEA分了4G，各种操作都流畅很多。

另外一个经常被忽视的问题：IDEA的插件装太多，也会拖慢甚至导致崩溃。特别是那些“智能”类的AI辅助插件，如果不常用就卸载掉，保持IDE干净才是稳定运行的根本。

5. GitLab使用中的常见问题排查实录

5.1 “Login failed. Check API token or GitLab version.”解决方案

这个报错在标题的热搜词里出现了，我推测有相当多人被这个问题卡住过。我先说结论，这个报错一般是三种原因：

第一种，Token本身不对或者已过期。GitLab的Personal Access Token可以设置过期时间，如果过期了，在IDEA里登录就会报这个错。解决办法很简单：去GitLab重新生成一个Token，注意不要把过期时间设为“永不”——出于安全考虑，团队里我都建议设置1-3个月的过期时间，到时间换Token，长期挂着的Token反而容易泄露。

第二种，你给Token勾选的权限范围不够。IDEA连接GitLab不仅需要读仓库的权限，还需要api权限才能获取分组、项目列表。如果你只勾了read_repository，IDEA能拉项目但会在某些操作上报这个错误。我的建议是：如果是个人开发，直接勾选api权限最省事；如果是公司环境，再根据安全要求收缩权限。

第三种，GitLab版本过老，IDEA的GitLab插件接口不兼容。这种情况在老旧GitLab上比较常见，比如GitLab 9.x之前的老版本和现在新版IDEA之间存在API差异。解决办法：要么升级GitLab（推荐），要么把IDEA的GitLab插件降级到兼容版本。

排查的时候，建议先在浏览器里手动访问一下http://你的GitLab地址/api/v4/projects，加上Token参数，如果返回JSON数据就说明GitLab的API是通的，问题主要在IDEA和Token配置上；如果返回404或者500，那就是GitLab本身的问题了。

5.2 “git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks”这条命令是什么

如果你在使用IDEA的Git功能时打开控制台，会看到类似这样的一长串命令被自动执行。很多人第一次看到以为出了什么问题，其实这串命令是IDEA在后台帮你执行Git操作，不用管它。但这些参数确实值得了解一下：

• -c diff.mnemonicprefix=false：让Git在diff输出中不使用简写的字母前缀，而是用a/、b/这样的完整前缀，这样diff的内容更直观。
• -c core.quotepath=false：让Git输出文件名时不要转义非ASCII字符。如果不开这个参数，你提交一个中文文件名会变成\346\265\213\350\257\225这样的乱码，IDEA自动加这个参数就是为了解决中文文件名显示问题。
• --no-optional-locks：告诉Git在做只读操作时不要获取可选的锁，避免一些后台命令阻塞其他操作。

知道这些之后，你看到IDEA命令行窗口输出这些内容就可以放心了，这是IDEA正常的行为。

5.3 Jenkins配置GitLab Connection失败？先检查这几处

除了IDEA集成，你还会遇到Jenkins和GitLab的对接问题。搜索结果里有“jenkins配置gitlab connection”，我也一并说下这个经典问题。

Jenkins中配置GitLab Connection，地址是：Manage Jenkins -> Configure System -> GitLab。

需要填三个核心信息：

• Connection name：随便起个名，比如“公司GitLab”。
• Gitlab host URL：填http://你的GitLab地址:8080。注意这里不要带路径，直接域名/IP加端口就行。
• Credentials：点击Add添加一个GitLab Token凭证，Secret text填你的Personal Access Token，注意这个Token同样需要api权限。

如果配置后测试连接报错，我遇到过的原因主要有：Token权限不够导致API调用失败；网络不通，Jenkins服务器访问不到GitLab。我建议直接在Jenkins所在的机器上用curl测一下连通性：

curl http://你的GitLab地址:8080/api/v4/version --header "PRIVATE-TOKEN: 你的Token"

如果返回了带有版本信息的JSON，说明网络和Token都正常，问题出在Jenkins的配置格式上。

5.4 GitLab CI/CD中Docker镜像构建与自动化部署实践

GitLab最大的价值之一就是自带的CI/CD能力。当你把代码推送到GitLab后，它可以自动构建、测试、打包，甚至自动部署到服务器。这里我分享一个很通用的自动化部署流程：用GitLab Runner构建Docker镜像并自动部署。

首先需要在GitLab服务器上安装并注册一个GitLab Runner。Runner相当于一个执行器，GitLab告诉它“有代码更新了”，它就去执行你写的CI脚本。

安装Runner：

# 下载并安装 curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash sudo apt-get install gitlab-runner

注册Runner需要两个信息：GitLab地址和注册Token。Token在GitLab网页的“设置 -> CI/CD -> Runner”里可以找到。

sudo gitlab-runner register

注册过程中会让你选执行器类型，我建议选docker，这样每次构建都在干净的容器环境里执行，不会污染宿主机。

然后在项目根目录创建.gitlab-ci.yml文件，这是CI/CD的配置文件。下面是一个最典型的Docker镜像构建和推送的示例：

stages: - build - deploy variables: IMAGE_NAME: registry.example.com:5000/myapp IMAGE_TAG: $CI_COMMIT_SHORT_SHA build: stage: build image: docker:latest services: - docker:dind script: - docker build -t $IMAGE_NAME:$IMAGE_TAG . - docker push $IMAGE_NAME:$IMAGE_TAG only: - main deploy: stage: deploy image: alpine:latest before_script: - apk add --no-cache openssh-client script: - ssh -o StrictHostKeyChecking=no deployer@服务器IP "docker pull $IMAGE_NAME:$IMAGE_TAG && docker stop myapp || true && docker rm myapp || true && docker run -d --name myapp -p 8081:80 $IMAGE_NAME:$IMAGE_TAG" only: - main

这段配置我拆解一下：stages定义了流水线的阶段顺序；before_script是在正式脚本前执行的准备工作；only: - main意味着只在main分支提交时触发。$CI_COMMIT_SHORT_SHA是GitLab预定义的环境变量，取当前提交的短哈希值，天然保证了每次构建的镜像标签是唯一的，不会覆盖。

这套流水线跑通之后，团队推代码 -> 自动构建镜像 -> 自动部署到服务器，整个过程不需要人工干预，效率提升非常明显。我当初在公司推这套流程，把原本每次发版要花半小时的手动操作压缩到了两分钟，团队上下都很满意。

5.5 删除仓库、上传分支等高频操作的IDEA姿势

搜索结果里还有“gitlab删除仓库”、“gitlab上传代码到仓库”、“gitlab上传分支”这几个高频操作，我在这里一并讲清楚。

删除GitLab仓库的官方途径是在网页上操作：进入项目仓库首页 -> 设置（Settings） -> 通用（General） -> 拉到底部“高级”（Advanced） -> 找到“删除项目”（Delete project）。它会让你输入项目名确认，输入后仓库就会被彻底删除。这里要特别提醒：删除操作不可恢复，除非你做了备份。我先在本地确认过没有需要的代码，才会去点删除按钮。

上传代码和上传分支，本质上是同一个操作：把本地分支推送到远程。在IDEA里，右下角切换到你要推送的分支，执行Git -> Push即可。如果要推送新分支第一次推送到远程，IDEA会弹窗询问是否要设置上游分支（Set upstream），确认后就会在GitLab上创建同名分支。如果你用命令行，对应的指令是git push -u origin branch-name，-u参数就是“把本地分支和远程分支关联起来”的意思。

还有一个实用的小技巧：如果你想删除远程分支，IDEA里右键远程分支 -> Delete Remote Branch即可；命令行是git push origin --delete branch-name。远程分支删除后，本地分支还在，不会影响你的工作区。

6. 实际部署后的稳定性建议

GitLab服务器搭好、IDEA也集成了，这只是第一步，后续的运维才是真正考验人的地方。我根据自己几年的使用体验，给出几点稳定性建议。

内存方面，GitLab官方推荐4G内存起步，我的服务器是8G，比较宽裕。如果内存紧迫，可以在配置里关掉一些用不到的功能，比如Mattermost、Prometheus监控等。这些功能默认是开启的，但中小团队根本用不到，关掉能省不少内存：

sudo docker exec gitlab vi /etc/gitlab/gitlab.rb # 注释掉或设置为 false 的功能 prometheus_monitoring['enable'] = false mattermost['enable'] = false

注意，修改完配置后要执行gitlab-ctl reconfigure和gitlab-ctl restart才能生效。

备份方面，Docker部署的GitLab备份其实很简单——备份整个挂载目录就行。我写了个简单的cron定时任务，每天凌晨3点把/srv/gitlab打包，存到独立的备份磁盘或者对象存储上：

0 3 * * * tar -czf /backup/gitlab_$(date +\%Y\%m\%d).tar.gz /srv/gitlab && find /backup -name "gitlab_*" -mtime +30 -delete

这个任务做了两件事：打包当天数据、自动清理30天前的旧备份。我建议你真的把这个脚本用起来，GitLab的代码数据丢失是灾难级别的，尤其是别人码了一个月的需求被你搞没了，这种锅背不起。

另外，GitLab容器建议设置时间同步，否则证书过期、日志时间错乱这些问题会接踵而至。服务器层面配置好NTP时间同步，一劳永逸。

7. 踩坑记录：我部署GitLab时遇到的那些想骂人的问题

7.1 端口冲突：你的服务器22端口被系统占用了

我第一次部署时，按网上教程直接--publish 30022:22映射，后来发现GitLab配置SSH是走22端口，但我把宿主机的22端口留给系统SSH了。直到有同事说“clone代码失败，连接被拒绝”才发现。

排查步骤其实很简单：先在本地执行ssh -T git@服务器 -p 2022测试，如果提示连接成功但权限不对，那就是证书的问题；如果直接报连接拒绝，那就要查端口映射。最终我的解决方式就是上面已经说的，把宿主机2022映射到容器22，在gitlab.rb里设置gitlab_rails['gitlab_shell_ssh_port'] = 2022，问题解决。

7.2 大项目clone和push时超时

如果你有一个几百兆的仓库，用HTTP协议clone时经常报超时。这种情况可以调大Git的超时时间和请求缓冲区：

git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999

第一行把POST缓冲区调到500M，解决大提交被服务器拒绝的问题；后面两行禁用了“低速超时”限制，避免网络波动时被强制中断。

但说实话，这只是治标。仓库过大的根本解决办法是检查是不是把不该提交的文件提交进去了，比如node_modules目录、构建产物等，应该加到.gitignore文件里忽略掉。我见过一个团队把编译后的包提交进仓库，仓库体积直接飙到2G，每次clone都痛苦得不行。用Git LFS（Large File Storage）管理大文件，或者做好.gitignore规划，这才是正路。

7.3 GitLab的404页面让人心慌

有时候打开GitLab网页，项目列表是好的，但点进某个项目却显示404。除了权限问题外，最常见的情况是项目路径或者组路径之前改过，导致旧链接失效。

还有一种情况是：你新注册了一个普通用户账号，管理员还没有给你的组授权，别人给你分享的项目链接就打不开。这种问题的排查方向很简单：确认当前登录的账号是否在项目的成员列表里，让管理员检查项目的可见性和成员权限设置即可。

7.4 IDEA里Git提交日期和系统时间差了8小时

这是个很小但很烦人的问题。IDEA显示的提交时间是格林尼治时间，中国是东八区，所以看到的时间比实际时间晚了8小时。解决方法很直接：IDEA的设置里找到Version Control -> Git，打开Show commit timestamp in repository log下面的“使用系统时区”选项，或者直接在设置里搜索“timezone”，把时区设置为Asia/Shanghai。

不过说实话，如果项目组所有人都在同一个时区，这个时间显示问题并不影响协作，偶尔差8个小时看起来也别扭。我是到了影响看日志的时候才发现这个问题，一经设置就再也没管过。

8. 关于IDEA版本与GitLab版本的相互兼容性

这个点放在最后，是因为我发现很多人忽视它，但一旦出问题就非常折腾。

IDEA不是越新越好，GitLab版本的更新速度也很快，两者之间的API兼容性不是一直完美的。比如新版IDEA对老GitLab的API调用可能不兼容，反过来老版IDEA连新版GitLab的API也可能有问题。这就是“Login failed. Check API token or GitLab version”这个报错出现频率这么高的根本原因。

我建议保持一个原则：GitLab版本尽量用最新的稳定版，IDEA也保持更新到当前年度的最新版本，这样可以避免90%的兼容性问题。如果你因为某些原因必须用老版本IDEA（比如公司统一环境），那么GitLab版本就不要盲目升级，确认兼容性后再动。

总结一下我个人推荐的稳健组合：GitLab 15.x/16.x稳定版 + IDEA 2023.x或2024.x + JDK 17，这套组合我用了很久，无论功能稳定性还是API兼容性都表现优秀。

9. 最后分享一个我的日常开发工作流

说了这么多理论，最后分享我个人现在每天都在用的工作流，给你一个整体参考。

每天到工位，打开IDEA，等待项目自动同步（我设置了启动时自动更新项目）。如果后台有Jenkins的构建任务，我会顺手看一眼是否通过。然后切换到今天的开发分支，开始写代码。

写完一个功能点，先跑测试，确认没问题，在IDEA里做一次Commit，提交信息格式是“feat: 添加xx功能”。一个小功能提交一次，不要憋大招到晚上一次性提交几十个文件，那样出了问题根本没法定位。

下班前半小时，把当天的所有提交Push到GitLab，然后在GitLab网页上创建Merge Request，指派给代码审查人。如果团队用了GitLab CI（我配置了自动化检查和测试），我还会确认流水线跑绿了才走人。这几年下来，这套流程帮我避免了很多次发布事故。

搭建一套好用的GitLab + IDEA开发环境，不是一锤子买卖，是一个持续完善的过程。从最早的“能用就行”，到后来加上CI自动化、加上备份策略、加上代码审查流程，每个阶段都有不同的优化空间。希望这篇文章能帮你把最核心的几块地基打牢，后面扩展起来会顺畅很多。