Ubuntu上用Docker部署GitLab实战：从环境搭建到CI/CD流水线

在 Ubuntu 上折腾 GitLab，这事我干过不止一次。从最早在大学服务器上裸装 GitLab，到后来用 Docker 一键拉起整个环境，中间踩过的坑、填过的土，足够写一本小册子了。今天不聊那些花里胡哨的架构，就聊聊我自己在 Ubuntu 上部署和日常使用 GitLab 的真实经历，包括那些官网文档里不会明说的细节。这篇东西不是单纯的操作步骤罗列，而是把“为什么这么干”和“实际跑起来会遇到什么”都讲清楚。

GitLab 这个工具，说白了就是企业级的代码托管平台，功能覆盖了源码管理、CI/CD、代码审查、安全扫描等一整套 DevOps 流程。对团队来说，它解决了代码放哪里、怎么协作、怎么自动构建发布的问题。我认识的不少朋友，最开始都是在 Windows 上装个虚拟机体验，真正落地到服务器基本都会选 Ubuntu + Docker 这条路。为什么？因为 Ubuntu 对 Docker 的支持最省心，Docker 部署 GitLab 能把环境隔离做到极致，备份迁移都方便。这篇文章适合谁看？准备在 Ubuntu 上搭 GitLab 的运维新手，以及已经开始用但遇到各种奇怪问题的人。我会把从零部署到日常维护的完整链路都给你过一遍。

1. 部署前的整体设计与方案选型

1.1 为什么选择 Docker 方式部署 GitLab

先说结论：在自己机器上实验或者正式环境刚起步，Docker 部署 GitLab 是最省心的一条路。我最早在 Ubuntu 18.04 上直接用 apt 装过 GitLab CE，当时是因为要跑内网环境，图省事没上 Docker。后来发现坑不少——升级的时候偶尔会碰到依赖冲突，卸载也不干净，换个服务器迁移更是麻烦。折腾过一轮之后，我就彻底转向 Docker 了，后面所有环境基本都是 docker-compose 一把梭。

Docker 部署的好处在于环境隔离和一致性。GitLab 官方镜像集成了所有需要的运行环境和依赖，你不需要关心 Ruby、PostgreSQL、Redis 这些组件在 Ubuntu 上怎么装、怎么配、怎么升级。整个 GitLab 被打包成一个黑盒，你只需要映射端口和卷目录，剩下的交给镜像。升级 GitLab 的时候，直接替换镜像版本重启就行，如果新版本有问题，也能快速回滚到旧镜像，这是裸机安装很难做到的。

另一个实际收益是备份迁移。裸机安装要备份 GitLab 的配置文件、Git 仓库数据、数据库和上传文件，恢复的时候还得先搭建同样版本的环境，过程相当繁琐。Docker 部署下，你只需要备份挂载的那个数据目录，到了一台新机器上重新 docker run 一把，把数据目录恢复到原路径，几分钟就能跑起来。我后来帮朋友迁移过一台 GitLab 服务器，整个流程不到半小时就完成了。

当然 Docker 部署也有代价，主要是多了一层网络和存储的抽象，排查问题的时候要多想一步。比如容器内部的网络访问、文件权限问题（容器内进程以什么用户运行、挂载目录权限是否正确），这些是裸机安装不会遇到的。但从日常维护的整体成本来看，Docker 的优势非常明显，特别是对中小团队来说。

1.2 服务器资源配置与系统准备

GitLab 不是个轻量级应用，它对内存和磁盘的要求比较明确。根据我实际体验，2 核 4G 内存的机器跑 GitLab 社区版，勉强能用但会比较吃力，尤其是开启 CI/CD Runner 之后，内存经常飙到 85% 以上。推荐生产环境至少 4 核 8G，磁盘建议使用 SSD，系统盘和数据盘分离会更好。GitLab 的仓库数据量增长很快，我个人建议系统盘和数据盘分开挂载，数据目录放数据盘，避免以后磁盘空间不足导致 GitLab 拒绝写入。

我部署时的系统环境是 Ubuntu 22.04 LTS，这个版本目前生态最成熟。准备工作主要有这几个：先更新系统软件包列表，然后安装 Docker Engine 和 Docker Compose 插件。Ubuntu 仓库自带的 docker.io 也可以，但版本可能偏老，建议直接从 Docker 官方源安装。安装完把当前用户加入 docker 用户组，这样不用每次敲命令都加 sudo。还有一个细节是检查防火墙和 SELinux/AppArmor 状态，Ubuntu 默认启用 AppArmor，如果之前改过配置需要注意对 Docker 容器的影响。

磁盘规划方面，我的习惯是给 GitLab 单独建一个数据目录，比如 /data/gitlab，下面分三个子目录分别存放配置、数据和日志。这样做的目的很直接：恢复和排查问题的时候，看一眼目录结构就知道哪里出了问题。内存开销要心里有数，GitLab 启动时至少要占 2G 内存，4G 内存的机器勉强能跑但 Swap 使用会比较频繁。有条件就上 8G，运行起来流畅得多。

2. 基于 Docker 部署 GitLab 的完整实操

2.1 docker-compose 编排文件设计

部署 GitLab 我强烈建议直接用 docker-compose，而不是一行行的 docker run 命令。用编排文件的优势是可以把配置版本化管理，换机器迁移时直接复用同一份 yaml，避免漏掉某个参数。下面是我目前在用的 docker-compose.yml，实际跑过很多次，比较稳定：

yaml复制version: '3.8'

services:
  gitlab:
    image: gitlab/gitlab-ce:16.11.2-ce.0
    container_name: gitlab
    restart: always
    hostname: gitlab.example.com
    ports:
      - "8080:80"
      - "8443:443"
      - "2222:22"
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://gitlab.example.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        postgresql['shared_buffers'] = "256MB"
        unicorn['worker_processes'] = 2
        prometheus_monitoring['enable'] = false
    volumes:
      - /data/gitlab/config:/etc/gitlab
      - /data/gitlab/logs:/var/log/gitlab
      - /data/gitlab/data:/var/opt/gitlab
    shm_size: '256m'

解释一下几个关键参数的用意。hostname 设置为主机名，external_url 是对外访问的地址，这两处要对应起来，否则 Web 页面跳转时地址会不对。端口映射我刻意做了改动，宿主机 8080 映射到容器 80，SSH 端口用 2222 映射容器的 22，这样做是为了避免宿主机上的端口冲突，同时也算是个安全策略，不暴露默认端口。postgresql 的 shared_buffers 和 unicorn 的 worker_processes 是资源调优参数，需要根据机器内存调整，避免 GitLab 吃光所有内存。prometheus_monitoring 我关掉了，因为对小型部署来说监控不是刚需，还白占内存。

有个细节需要注意：shm_size 建议设置成 256m 或更大。GitLab 使用了共享内存，默认的 64M 有时候会导致数据库出现问题，尤其是跑 CI 的时候报错。这个参数是踩坑踩出来的，不设置的话 GitLab 在负载高时会偶发 500 错误。

2.2 初始化配置与启动验证

docker-compose.yml 准备好之后，在文件所在目录执行 docker compose up -d，GitLab 就启动了。首次启动时间比较长，因为容器内部要做各种初始化工作，从拉取镜像到真正能访问，通常需要 3 到 5 分钟。怎么判断启动完成了？看日志：

bash复制docker logs -f gitlab --tail 200

当日志中出现 "GitLab is ready" 之类的输出，说明服务已经起来了。另外可以通过 docker ps 查看容器状态，如果 STATUS 显示 healthy 且持续稳定，说明容器内的健康检查已经通过。启动过程中容器可能会重启一两次，这是正常的，不用慌，留意最终状态是否稳定即可。

首次访问页面时，GitLab 会让你设置 root 用户的初始密码。一个容易忽略的点是：如果你在 docker-compose 的环境变量里没有显式配置 GITLAB_ROOT_PASSWORD，那么初始密码的获取方式是通过查看 /etc/gitlab/initial_root_password 文件，这个文件会在首次配置后 24 小时自动删除。所以建议在启动前就在环境变量里设置好初始密码，避免后面还要进容器里翻文件。

启动验证这块，我的建议是不要只看端口通不通，要把完整的链路都验证一遍：浏览器能打开登录页、能正常登录、能创建项目，另外 SSH 端口也要测一下，用 ssh -T -p 2222 git@ 这样的命令验证是否能正常握手。我在实际部署中遇到过 Web 正常但 SSH 连不上的情况，就是因为端口映射配错了，这两条链路要分别验证。

2.3 常见部署问题：端口冲突与地址配置

端口冲突是部署 GitLab 时最常见的坑，尤其是 80 端口和 22 端口。很多服务器上 NGINX 或其他 Web 服务已经占了 80，或者 SSH 服务占了 22，这时 GitLab 的端口映射就会失败。解决办法就是在端口映射时避开这些常用端口，像我上面那样把 80 映射为 8080、22 映射为 2222。

端口映射改了之后，external_url 和 SSH 端口也要联动调整。external_url 是 Web 访问地址，如果映射了非 80 端口，URL 里要带上端口号，比如 http://gitlab.example.com:8080。SSH 这是更复杂的点：因为容器内 Git SSH 服务的 22 端口被映射到了宿主机的 2222，所以用户在 clone 仓库时，Git 命令里的 SSH 端口默认是 22，不指定的话会连不上。解决办法是在 GitLab 的配置里设置 gitlab_rails['gitlab_shell_ssh_port'] = 2222，这样 GitLab 在生成的 clone 地址里就会自动带上正确的端口。这也是我在 2.1 配置里那个参数存在的原因。

还有个场景需要注意：如果你用云服务器，记得在安全组里放行对应的端口，宿主机上的防火墙也要同步开放。很多时候端口映射配好了，死活访问不了，最后发现是云安全组没放行，这个低级错误我犯过一次，后来写成了自己的排查清单第一项。

3. 日常使用高频操作与配置要点

3.1 SSH 密钥配置与多账号管理

GitLab 日常使用频率最高的操作就是代码的拉取和推送，而要流畅地做这些事，SSH 密钥配置是绕不开的第一步。我见过不少同事在 Windows 上用 HTTPS 方式反复输入账号密码，效率很低，SSH 配置好之后基本可以做到无感操作。

SSH 密钥的生成很简单，在 Ubuntu 终端执行：

bash复制ssh-keygen -t ed25519 -C "your_email@example.com"

默认生成的私钥在 ~/.ssh/id_ed25519，公钥在 ~/.ssh/id_ed25519.pub。把公钥内容复制，到 GitLab 的 Preferences -> SSH Keys 页面粘贴保存，就完成了配置。验证是否成功用：

bash复制ssh -T -p 2222 git@gitlab.example.com

第一次连接会提示确认 host 指纹，输入 yes 回车即可，之后就能正常 clone/push 了。有个小细节：如果服务器上还有 GitHub 或其他 Git 平台的密钥，建议给不同平台配置不同的 SSH key，然后用 ~/.ssh/config 文件做分流。我本人就是这样配置的，工作电脑上同时使用 GitLab 和 GitHub，互不干扰。

常见的 SSH 连接问题包括：Permission denied (publickey)、网络超时等。大半都是私钥路径不对或者没有加载私钥导致的。如果用了非默认文件名，需要在 ~/.ssh/config 里显式指定 IdentityFile，或者用 ssh-add 手动添加私钥。

3.2 访问 Token 的获取与使用场景

除了 SSH 方式，API 访问和 CI/CD 自动化场景下最常用的是 Personal Access Token。很多初学者会困惑 GitLab Token 在哪里获取，其实入口就在用户头像下的 Preferences -> Access Tokens。点进去之后可以设置 Token 的名称、过期时间和权限范围。权限范围要按最小化原则勾选，比如只想读取仓库信息就只勾 read_repository，不要直接给 api 权限。

Token 只有在创建时才会完整显示一次，关闭页面后就再也看不到了，所以创建后要立即复制保存。我习惯把 Token 放到本地密码管理器里，而不是直接写在项目代码中。如果 Token 泄露了，去 Access Tokens 页面把人对应的 Token 撤销掉，再重新生成一个新 Token 即可，不用改密码。

有个高频报错特别容易让人懵：login failed. check api token or gitlab version. log in via git if the version...。这个报错通常出现在你用一个老版本的 Git 客户端或者 IDE 插件去访问新版本 GitLab 时。此时 Git 客户端发送的认证方式 GitLab 不认，或者 Token 权限不足。解决办法：确认 Git 版本较新，确认 Token 勾选了必要的权限，或者干脆用 SSH 方式代替 HTTPS。我实际帮同事排查过这个问题，最后定位到是他 IDE 里缓存的旧 Token 失效，刷新之后就正常了。

3.3 代码拉取推送与分支管理

代码拉取推送是 GitLab 使用者的基本功，但有几个操作细节值得展开说说。首先，clone 代码时有 HTTPS 和 SSH 两种地址，上面提到配置好 SSH 之后，我会统一使用 SSH 地址，避免每次推送都要输密码。其次，拉取新代码时，我习惯先 git fetch origin，再 git pull，虽然 git pull 本身会做 fetch，但分开操作可以更清楚地看到远端有哪些新分支、哪些分支被删除，避免出现"怎么我拉不下来"的尴尬。

分支管理方面，GitLab 上最常用的操作是合并请求（Merge Request）。在 GitLab 的界面上创建 MR 时，要注意选择正确的源分支和目标分支，很多新手把方向搞反了，结果把开发分支的东西误合并到了主分支。提交 MR 前，建议先在本地把自己分支的代码 rebase 到目标分支最新代码上，减少冲突的可能。命令是：

bash复制git checkout feature-branch
git fetch origin
git rebase origin/main
git push --force-with-lease

这里用 --force-with-lease 而不是 --force，是一个重要的安全习惯。--force-with-lease 只有在远端分支没有被其他人更新的情况下才会强制推送，能避免誤覆盖别人提交的代码。这是我在团队协作里反复强调的一点。

4. CI/CD 落地与自动化流水线配置

4.1 配置 .gitlab-ci.yml 示例与关键参数说明

GitLab 最有价值的能力之一就是内置 CI/CD，你不用额外搭建 Jenkins 就能实现代码提交后自动构建、测试和部署。要实现这个能力，需要两步：一是确保有 GitLab Runner 在运行，二是在项目根目录创建 .gitlab-ci.yml 文件，定义流水线的阶段和任务。

Runner 的注册不是本文重点，我默认你已经有可用的 Runner 了。下面是我一个 Python 项目的 .gitlab-ci.yml 示例，很简洁但覆盖面广：

yaml复制stages:
  - test
  - build
  - deploy

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"

cache:
  paths:
    - .pip-cache/

before_script:
  - python --version
  - pip install -r requirements.txt

test:
  stage: test
  script:
    - pytest --junitxml=report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA $CI_REGISTRY_IMAGE:latest
  only:
    - main

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  environment: production
  only:
    - main
  when: manual

这里有几个参数是很讲究的。PIP_CACHE_DIR 和 cache 配置是把 Python 包依赖缓存起来，这样每次 CI 跑不用重新下载全部依赖，流水线时间能大幅缩短。artifacts 是把测试报告保存下来，GitLab 的 Merge Request 页面可以直接展示测试结果，非常方便。deploy 阶段我设置了 when: manual，意思是流水线跑完测试和构建后，部署这一步需要人工在 GitLab 页面上点击确认，避免每次提交都自动上生产。这种"自动测试、手动部署"的策略，对生产环境来说是底线要求。

CI 流水线跑起来之后，常见的问题之一就是 "gitlab cicd python 依赖 仓库地址" 相关。默认情况下 pip 会从公网 PyPI 拉取依赖，但有些企业环境访问外网受限，或者需要走内网私有源。解决办法是在 variables 里配置 PIP_INDEX_URL：

yaml复制variables:
  PIP_INDEX_URL: "http://your-pypi-mirror.com/simple"
  PIP_TRUSTED_HOST: "your-pypi-mirror.com"

PIP_TRUSTED_HOST 是为了在 HTTP（非 HTTPS）源的情况下让 pip 信任该主机，否则会报错。这个配置我在内网环境里踩过一次坑，补充了这个参数之后就正常了。

4.2 Runner 与流水线的几类典型坑

CI 跑不起来，最常见的情况是 Runner 没有正确注册或者标签不匹配。在 GitLab 上注册 Runner 时会要求填写标签（tags），而 .gitlab-ci.yml 里的任务如果没有指定 tags，默认会跑到未设置 tags 的 Runner 上。如果 Runner 的 tags 和任务对不上，任务就会一直 pending。解决的办法是在 Runner 注册时把 tags 设置成空，然后让任务显式指定可以运行的 Runner 类型，或者把任务的 tags 配置为 Runner 的标签。

第二个高频问题是容器内执行权限。如果你用的是 Docker 类型 Runner，任务默认是在一个临时容器里跑的，容器内的用户和宿主机的权限映射会导致产物文件权限不对。我处理的办法是在任务脚本里加上用户权限调整的步骤，或者让 Runner 以特权模式运行（不推荐但确实能解决很多问题）。更细一点的问题：流水线里执行 docker 命令（比如上面的 docker build），Runner 的容器内不一定有 docker 客户端，通常会报 docker: command not found，这时候需要以 docker:dind 模式运行，或者把 Runner 注册为 shell 执行器并提前装好 docker。这些细节官方文档有说明，但真遇到的时候往往比较慌，记录下来备用。

还有一个优化点是流水线的超时设置。默认任务超时时间是 60 分钟，如果你的测试或部署过程可能超过这个时间，要么在 .gitlab-ci.yml 里给任务显式加 timeout 配置，要么在 GitLab 的管理后台调整 Runner 的超时时间。我有一个项目跑数据迁移脚本，单次执行就要 40 多分钟，加上测试和打包，稍不留神就会超时，最后在 CI/CD 设置里调大了超时阈值才消停。如果你的任务经常超时，也要反思是不是脚本本身太慢，CI 的最佳实践是保持单次任务尽量短，快了更容易排查问题。

5. 常见问题排查与安全加固实录

5.1 高频故障排查速查表

GitLab 在 Ubuntu 上运行，用的时间长了总会遇到一些"莫名其妙"的问题。以下是我实际经历和排查过的高频故障汇总，整理成速查表，方便大家按图索骥：

这个表不是我凭空编的，每一条都对应着具体的排查动作。比如遇到容器反复重启，我的第一反应永远是 docker logs，看输出里是权限问题还是 OOM 问题。遇到页面 502，大概率是 GitLab 还在启动中，耐心等几分钟再看。遇到磁盘空间告警，先 du -sh /data/gitlab/logs 看日志是不是爆炸了，再考虑仓库数据占用。

5.2 GitLab 未授权访问漏洞与高危漏洞修复方案

GitLab 作为代码托管平台，一旦被攻破，源码泄露的后果非常严重，所以安全加固必须重视。前几年 GitLab 爆过几个高危漏洞，包括未授权访问漏洞，攻击者可以通过构造特定的 API 请求，在未登录的情况下获取用户信息甚至仓库数据。修复这类漏洞的根本思路是升级到官方修复版本，同时检查线上实例是否存在被利用的痕迹，比如有没有异常注册用户、异常访问日志等。

围绕 "gitlab未授权访问漏洞常见路径" 这个热搜词，我多说几句。GitLab 的漏洞利用路径通常集中在几个 API 接口，比如 /api/v4/users、/api/v4/groups、/api/v4/projects 等。在旧版本中，某些接口在没有认证的情况下会返回数据。排查方法很简单：用 curl 不带 Token 去访问这些接口，如果返回了数据列表，说明实例存在未授权访问风险。完整的排查思路是：

bash复制curl -s http://gitlab.example.com/api/v4/users | head -20
curl -s http://gitlab.example.com/api/v4/projects | head -20

如果返回了 JSON 数据，应立即处理。修复方案有三步，按优先级来：第一，升级 GitLab 到官方最新 LTS 版本（高危漏洞修复通常随版本更新发布）；第二，检查并回收所有可疑账号；第三，在系统层面限制对 API 路径的访问，只允许必要的 IP 段访问。之后要做的防御动作是开启 GitLab 的审计日志，方便追溯异常行为。补丁之外，建议把网页访问也改成 HTTPS，用 Let's Encrypt 或者其他证书，避免审计凭证和代码数据在网络上明文传输。对于公网可访问的 GitLab，强烈建议开启两步验证（2FA），尤其是管理员账号，这是成本最低也最有效的一层防护。

5.3 密码找回、系统重装与迁移经验

忘了管理员密码是很多人迟早会遇到的事。遇到这种情况不需要重装 GitLab，直接在服务器上执行重置命令即可。进入 GitLab 容器：

bash复制docker exec -it gitlab bash
gitlab-rails runner "user = User.find_by(username: 'root'); user.password = '新密码'; user.password_confirmation = '新密码'; user.save!"

执行完就能用新密码登录了。这个操作我用过好几次，每次都成功，前提是你有宿主机 root 权限或者 docker 组的权限。所以日常给团队的权限分配中，docker 组的权限管理一定要严格，因为能操作 Docker 基本等于能操作整个 GitLab。

系统重装和数据迁移有几个经验值得单独说。如果 Ubuntu 系统要重装，建议先备份 /data/gitlab 整个目录。恢复时先搭好同样版本的 GitLab 容器，再停掉容器，把备份的数据目录原路径替换回去，重启容器。版本差异太大的情况下，GitLab 会自动做数据库迁移，一般可以成功，但保险起见尽量用同版本或相近版本的镜像做恢复。我在一次迁移中因为跨了多个大版本，先是恢复到中间版本，再逐步升级，虽然费了点时间但非常稳。

另外，备份要养成定时任务的习惯。GitLab 官方提供了 gitlab-backup create 命令，可以配合 crontab 定期执行。我的做法是每天晚上 2 点执行备份，再把备份文件同步到另一台机器，这样即使整个服务器挂了，最多损失一天的代码记录，不至于丢失所有仓库。

6. 资源调优与 Proxy/VSCode 等场景扩展

6.1 内存与磁盘紧张时的调优方案

GitLab 跑在 Ubuntu 上，最常见的就是内存捉襟见肘。之前提到过 4G 内存可以跑，但是跑起来之后你会发现 Swap 使用率很高，操作响应变慢。这时候可以做一些取舍和调优。首先是关掉不必要的组件，比如 Prometheus 监控、Grafana，这些都是内存大户，对小型部署来说不是必需品。配置环境变量：

yaml复制environment:
  GITLAB_OMNIBUS_CONFIG: |
    prometheus_monitoring['enable'] = false
    grafana['enable'] = false
    gitlab_rails['env'] = { 'LDAP' => 'false' }

这种优化能节省大概 1G 内存。其次是调整 unicorn 或 puma 的进程数，之前配置里写的 worker_processes = 2 就是基于 4G 内存的保守设置，8G 内存可以适当增加到 4。进程数不是越多越好，太多了反而会导致内存不足，系统频繁交换磁盘，性能更差。

磁盘方面，GitLab 日志增长速度快得惊人。我会配置日志轮转，让系统定期清理旧日志。GitLab 自身也提供了日志清理机制，但默认阈值偏大，我一般会把 /etc/gitlab/logrotate 的频率调高一些。另一种更彻底的做法是给日志目录单独挂载一块大容量磁盘，避免日志把系统盘占满导致整个 Ubuntu 卡死。

6.2 与 VSCode 和 IDE 的集成配置

很多用 GitLab 的开发者其实日常都在 IDE 里工作，与 GitLab 的集成配置也是高频需求。VSCode 有 GitLab Workflow 插件，功能包括查看 MR、创建 MR、查看流水线状态、管理 issue 等。配置方式很简单：插件安装后，在 VSCode 的设置里填入 GitLab 的地址和 Personal Access Token（在 3.2 里获取过），然后在 GitLab Workflow 插件里选择 GitLab 实例即可。这里的坑跟 3.2 提到的 login failed 很像——Token 过期后插件会报权限错误，需要重新生成并更新配置。

IntelliJ IDEA 系列的配置也类似，在 Settings -> Version Control -> GitLab 里添加 GitLab 实例地址和 Token，就能直接在 IDE 内创建 MR、查看代码审查。我之前用 IDEA 配 GitLab 时被一个问题困扰了很久：IDEA 总是使用自己内置的 Git 客户端，某些 SSH 相关的配置读不到系统的 ~/.ssh/config，导致 SSH clone 报错。后来我把 IDEA 的 SSH 客户端切换为系统 SSH，问题就消失了。这个细节如果你也遇到，则可以马上检查一下。

6.3 多仓库协作与权限管理建议

GitLab 用了一段时间之后，仓库数量会快速增长，权限管理变得尤其重要。一个实用的做法是使用群组（Group）来组织项目，通过群组划分不同团队的权限边界。比如后端团队、前端团队各建一个 Group，Group 下面再建各自的项目。成员加入 Group 后自动继承对应的权限（Guest、Reporter、Developer、Maintainer、Owner），不需要在几十个项目里一个个添加，管理效率提升非常明显。

权限级别的选择也有讲究。给开发者的默认权限一般是 Developer，可以推送代码、创建 MR，但不可以直接推到受保护的主分支。主分支的保护规则建议在项目设置里配置为只有 Maintainer 允许直接推送，其他人都必须走 MR 流程。这个规则能有效避免代码被误推到主分支导致生产事故。我在团队里推行过三个月，效果显著，主分支的代码质量明显提升。

还要提醒一点：管理员权限（Owner）一定要严格控制人数，最好只保留 1 到 2 个人。Owner 能操作整个 GitLab 实例的设置、改所有人的权限、甚至删除所有项目，给多了人操作很容易失控。我的建议是至少建立一个"只读"的管理员账号作为后备，平时用普通账号操作，避免日常误操作造成不可逆的影响。

写在最后的一点体会

从最初在 Ubuntu 上老老实实用 apt 装 GitLab，到后来全面转向 Docker 部署，我在这个组合上花了不少时间，也积累了一些经验。回头来看，Ubuntu 和 GitLab 这个搭配之所以流行，不是没有原因：Ubuntu 对容器化支持好，GitLab 本身功能完整、社区版的功能也足够绝大多数团队使用。最关键的是，这套方案的容错性比想象中好——出了问题，容器日志、数据目录、配置文件都在明面上，排查起来有路可循。如果你正在准备部署或已经在使用过程中，希望这篇文章能帮你绕开我踩过的那些坑，把 GitLab 用得既稳又顺。