1. 项目概述为什么你需要一个自己的GitLab如果你是一名开发者或者正在管理一个技术团队那么“代码放哪儿”这个问题可能比“今晚吃什么”更让你头疼。用网盘版本混乱协作困难。用公共Git托管服务私有仓库要收费数据安全心里没底。这时候一个自托管的GitLab就成为了很多团队和个人的“终极答案”。GitLab不仅仅是一个Git仓库管理器。它集成了代码托管、CI/CD流水线、问题跟踪、Wiki文档、容器镜像仓库等一系列功能堪称一个“All-in-One”的DevOps平台。从个人开发者搭建一个私密的代码堡垒到中小企业构建完整的研发管理体系GitLab都能覆盖。我见过不少团队从零散的工具链切换到GitLab后开发流程的规范性和效率都有了肉眼可见的提升。这篇教程我会以一个“过来人”的身份带你从零开始搞定GitLab的部署、配置和核心使用避开我当年踩过的那些坑。2. GitLab部署方案全解析与选型在真正动手安装之前选择一个合适的部署方案至关重要。这决定了你后续的维护成本、扩展能力和资源消耗。别急着敲命令我们先来盘一盘几种主流方案。2.1 方案对比从虚拟机到云原生目前主流的部署方式大致有三种传统包安装、Docker容器化、以及基于Kubernetes的云原生部署。1. 传统包安装如Omnibus包这是GitLab官方最推荐、文档最全的方式。它会将GitLab所需的所有服务Ruby on Rails应用、PostgreSQL数据库、Redis、Nginx等打包在一起通过一个安装脚本如apt-get install gitlab-ce完成部署。优点部署简单升级方便一条命令官方维护稳定性极高。所有组件集成度高配置管理集中主要靠一个/etc/gitlab/gitlab.rb文件。缺点“全家桶”模式资源占用相对较高尤其是内存起步建议4GB以上。所有服务耦合在一台机器上不太适合超大规模或需要精细拆分的场景。适用场景中小团队、个人开发者、对容器化技术不熟悉的团队。想要最稳定、最省心的选择就是它。2. Docker容器化部署使用Docker Compose或直接运行GitLab的官方Docker镜像。这是目前非常流行的方式能将GitLab与其运行环境隔离。优点环境隔离部署干净。可以方便地调整资源配置CPU/内存限制易于迁移和备份数据卷管理。资源利用相对灵活。缺点需要一定的Docker和Docker Compose知识。网络、存储卷的配置需要额外关注。直接升级镜像时需要注意版本兼容性和数据迁移。适用场景已经具备Docker环境的团队追求环境一致性和快速部署。适合在开发机、测试环境快速搭建也适用于生产环境。3. Kubernetes (Helm) 部署使用Helm Chart在Kubernetes集群中部署GitLab。这是最云原生、最弹性的方式。优点极致的高可用和弹性伸缩能力。每个组件Web、Sidekiq、Gitaly等都可以独立扩缩容。天然集成Kubernetes的CI/CD Runner。缺点架构复杂部署和维护成本极高。需要专业的K8s运维知识初始资源要求也很高。适用场景大型企业、云原生技术栈成熟的团队对高可用和弹性有严格要求的场景。注意对于绝大多数读者个人、初创团队、中小公司我强烈建议从传统包安装或Docker Compose方式入手。它们的学习曲线平缓能让你快速用起来把精力聚焦在GitLab功能本身而不是复杂的运维上。本教程后续的实操部分也将以这两种方式为主进行演示。2.2 硬件与软件资源规划无论选择哪种方案给GitLab准备一个“舒适的家”是必要的。资源不足会导致页面加载缓慢、操作超时甚至服务崩溃。CPU至少2核。如果用户较多或CI/CD任务繁重需要4核或更多。内存这是最关键的资源。官方最低要求是4GB但这是“能跑起来”的标准。想要流畅使用特别是开启CI/CD等功能后8GB是推荐的起步配置。内存不足是GitLab卡顿最常见的原因。存储需要规划两部分系统盘用于安装GitLab本体和操作系统至少20GB。数据盘这是大头用于存放仓库代码、CI/CD产物Artifacts、容器镜像等。建议单独挂载一块容量较大的磁盘如100GB起步并做好定期备份方案。代码仓库的增长速度可能超乎你的想象。操作系统主流Linux发行版均可如Ubuntu 20.04/22.04 LTS、CentOS 7/8或替代品Rocky Linux/AlmaLinux。长期支持版LTS是首选能获得更长时间的安全更新。3. 实战部署两种主流方式手把手教学理论说完我们进入实战环节。我会分别演示在Ubuntu 22.04上通过Omnibus包安装以及使用Docker Compose安装GitLab社区版CE的完整过程。3.1 方式一Ubuntu 22.04 传统包安装最稳定这种方式适合绝大多数Linux服务器环境。3.1.1 系统准备与依赖安装首先更新系统并安装一些必要的工具。sudo apt-get update sudo apt-get upgrade -y sudo apt-get install -y curl openssh-server ca-certificates tzdata perl接下来配置Postfix用于发送邮件如注册确认、密码重置。如果你有外部SMTP服务器如腾讯企业邮、SendGrid可以跳过此步后续在GitLab配置中设置。# 安装Postfix sudo apt-get install -y postfix # 安装过程中会弹出配置窗口选择“Internet Site”然后设置你的系统邮件名称如 gitlab.yourdomain.com。3.1.2 添加GitLab仓库并安装添加GitLab官方软件仓库这样可以通过apt管理安装和更新。# 下载并执行GitLab仓库脚本 curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本会自动检测你的系统版本并配置好APT源。现在安装GitLab社区版。EXTERNAL_URL参数至关重要它需要设置为你能访问到这个GitLab服务器的地址。# 将 EXTERNAL_URL 替换为你服务器的实际IP或域名 sudo EXTERNAL_URLhttp://your_server_ip_or_domain apt-get install gitlab-ce例如如果你的服务器IP是192.168.1.100且暂时没有域名可以这样设置sudo EXTERNAL_URLhttp://192.168.1.100 apt-get install gitlab-ce。安装过程会持续几分钟它会自动下载包并启动所有服务。安装完成后你会看到类似下面的提示告诉你访问的初始密码存放在哪里。3.1.3 初始配置与登录安装完成后我们需要进行最关键的一步配置。所有配置都集中在/etc/gitlab/gitlab.rb这个文件里。sudo vim /etc/gitlab/gitlab.rb你需要至少修改以下几项# 将 external_url 改为你的地址如果要用HTTPS这里就写 https:// external_url http://your_server_ip_or_domain # 配置邮箱发信非常重要否则用户无法注册、找回密码 gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.your-email-provider.com # 例如 smtp.qq.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] your-emailexample.com gitlab_rails[smtp_password] your-email-password gitlab_rails[smtp_domain] your-email-provider.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] true gitlab_rails[gitlab_email_from] your-emailexample.com修改完配置后必须重新配置GitLab使其生效sudo gitlab-ctl reconfigure这个过程会花费一些时间它会根据你的配置文件重新生成所有服务的配置并重启。完成后在浏览器中打开你设置的EXTERNAL_URL。首次登录的用户名是root密码需要从以下文件中获取sudo cat /etc/gitlab/initial_root_password这个密码文件在24小时后会被自动删除因此登录后第一件事就是去修改root用户的密码。3.2 方式二Docker Compose部署最灵活如果你更喜欢容器化的干净利落Docker Compose是更好的选择。首先确保服务器上已经安装了Docker和Docker Compose。3.2.1 准备Docker Compose文件创建一个目录例如gitlab-docker并在其中创建docker-compose.yml文件。version: 3.6 services: web: image: gitlab/gitlab-ce:latest container_name: gitlab-web restart: always hostname: your_server_ip_or_domain # 同样替换为你的IP或域名 environment: GITLAB_OMNIBUS_CONFIG: | external_url http://your_server_ip_or_domain # 可以在这里添加其他gitlab.rb配置语法相同 gitlab_rails[gitlab_shell_ssh_port] 2222 # 映射宿主机的2222端口到容器的22端口 ports: - 80:80 - 443:443 - 2222:22 # SSH克隆端口映射 volumes: - ./config:/etc/gitlab - ./logs:/var/log/gitlab - ./data:/var/opt/gitlab shm_size: 256m这个配置做了几件关键事使用最新的GitLab CE镜像。设置了external_url。将HTTP(80)、HTTPS(443)和SSH(2222)端口映射到宿主机。注意我们将宿主机的2222端口映射到容器的22端口这是为了不和宿主机本身的SSH服务冲突。将配置、日志、数据三个目录挂载到宿主机这样即使容器删除数据也不会丢失。3.2.2 启动与初始化在docker-compose.yml所在目录下运行docker-compose up -d首次启动会拉取镜像并初始化这个过程可能需要5-10分钟。你可以通过以下命令查看日志等待初始化完成docker-compose logs -f web当你看到日志中出现gitlab Reconfigured!这样的字样时说明启动完成。同样在浏览器中访问http://your_server_ip_or_domain。初始root密码需要通过以下命令在容器内查看# 进入容器 docker exec -it gitlab-web bash # 查看密码 cat /etc/gitlab/initial_root_password实操心得无论哪种安装方式配置邮箱都是部署后必须立即做的事情。没有邮箱服务很多协作功能形同虚设。另外对于Docker方式务必理解端口映射和卷挂载这是数据持久化和外部访问的关键。如果gitlab-ctl reconfigure或Docker启动后无法访问首先检查防火墙是否放行了80/443端口sudo ufw allow 80,443。4. GitLab核心功能实战与配置详解成功登录后面对GitLab的界面你可能会觉得功能繁多。别慌我们抓住几个最核心的“牛鼻子”功能把它们用透就能解决80%的日常开发协作问题。4.1 账户安全与SSH密钥配置使用HTTP方式克隆代码每次都要输密码非常麻烦。配置SSH密钥后可以实现免密认证既安全又方便。4.1.1 生成SSH密钥对本地操作在你的开发电脑上不是GitLab服务器打开终端ssh-keygen -t ed25519 -C your_emailexample.com # 或者使用 RSA 算法: ssh-keygen -t rsa -b 4096 -C your_emailexample.com按回车使用默认保存路径~/.ssh/id_ed25519并设置一个密码可选为空则免密码使用。4.1.2 在GitLab中添加公钥查看并复制公钥内容cat ~/.ssh/id_ed25519.pub登录GitLab点击右上角头像 -Preferences- 左侧菜单SSH Keys。将刚才复制的公钥内容粘贴到“Key”文本框中给它起个标题如“My Laptop”然后点击Add key。4.1.3 测试连接在终端测试是否配置成功ssh -T gityour_server_ip_or_domain -p 2222 # 如果是Docker部署且映射了2222端口 # 或 ssh -T gityour_server_ip_or_domain # 如果是标准安装使用22端口如果看到Welcome to GitLab, username!的欢迎信息说明配置成功。4.2 项目管理与代码协作核心流程GitLab的核心是代码仓库。我们从一个项目的完整生命周期来看如何使用。4.2.1 创建第一个项目点击导航栏的“”号选择New project。Create blank project创建空项目。Import project从其他平台GitHub、Bitbucket等导入。Create from template使用内置模板如Spring、Ruby on Rails等快速初始化。 我们选择“Create blank project”。填写项目名称如my-awesome-app、描述选择可见性级别Private只有被授权的用户才能访问。内部项目首选。Internal所有登录用户都可以访问。适合公司内部分享。Public互联网上任何人都可以无需登录查看。开源项目选择此项。 点击Create project空项目就创建好了。4.2.2 代码推送与拉取创建后GitLab会给出如何将本地已有代码推送到仓库的指引。假设你本地已有代码cd your_local_project_directory git init git remote add origin gityour_server_ip_or_domain:username/my-awesome-app.git git add . git commit -m Initial commit git push -u origin main # 或 master取决于你的默认分支名如果是克隆已有项目git clone gityour_server_ip_or_domain:username/my-awesome-app.git4.2.3 分支策略与合并请求Merge Request这是GitLab协作的精髓。一个好的分支策略如Git Flow能极大规范开发流程。创建功能分支从不直接在main分支上开发。git checkout -b feature/add-new-button开发并提交在feature/add-new-button分支上完成开发并多次提交。git add . git commit -m “feat: add a new submit button” git push origin feature/add-new-button发起合并请求MR在GitLab项目页面的分支列表旁点击“Create merge request”按钮。填写MR的标题和描述清晰说明这个分支修改了什么、为什么修改、如何测试。指定评审者Reviewers是保证代码质量的关键一步。代码评审与讨论评审者在MR的“Changes”标签页查看代码差异可以针对某一行代码发表评论、提出疑问。开发者根据反馈在本地分支修改再次推送MR会自动更新。流水线检查如果配置了CI/CD后面会讲MR会自动触发流水线。只有当流水线通过所有测试、构建成功后才允许合并。这是一个重要的质量门禁。合并与清理评审通过、流水线通过后由MR创建者或项目维护者点击“Merge”按钮。合并后通常可以勾选“Delete source branch”自动删除已合并的特性分支保持仓库整洁。4.3 CI/CD流水线入门自动化构建与部署GitLab CI/CD是其王牌功能通过一个名为.gitlab-ci.yml的配置文件定义从代码提交到部署上线的自动化流程。4.3.1 理解核心概念Pipeline流水线一次CI/CD执行的全过程包含多个阶段。Stage阶段流水线中的步骤如build构建、test测试、deploy部署。一个阶段可以包含多个作业它们并行执行。Job作业阶段内的具体任务是实际执行脚本的最小单位。例如在test阶段可以有unit-test和integration-test两个作业。Runner执行器实际执行作业的机器或容器。你需要至少注册一个Runner到GitLab。4.3.2 编写第一个.gitlab-ci.yml文件在项目根目录创建这个文件。下面是一个Node.js项目的简单示例# .gitlab-ci.yml stages: - install - test - build cache: # 缓存node_modules加速后续流水线 key: ${CI_COMMIT_REF_SLUG} paths: - node_modules/ install_dependencies: stage: install script: - npm ci --onlyproduction # 使用package-lock.json安装更精确 artifacts: paths: - node_modules/ unit_test: stage: test script: - npm run test:unit dependencies: - install_dependencies # 声明依赖可以复用artifacts build_project: stage: build script: - npm run build artifacts: paths: - dist/ # 将构建产物打包供后续阶段或下载 only: - main # 只有main分支的提交会触发构建这个流水线定义了三个阶段安装依赖、单元测试、构建。cache和artifacts是关键它们能缓存依赖和传递构建产物极大提升效率。4.3.3 注册与配置GitLab Runner流水线定义好了需要有个“工人”来执行。我们以注册一个Docker Runner为例。在GitLab项目页面进入Settings - CI/CD展开Runners面板。找到Set up a specific Runner manually部分记录下URL和registration token。在一台可以运行Docker的机器上可以是GitLab服务器本身也可以是另一台机器安装GitLab Runner并注册。# 添加官方仓库 curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash # 安装 sudo apt-get install gitlab-runner # 注册Runner sudo gitlab-runner register根据提示输入GitLab实例URL刚才记录的URL。Registration token刚才记录的token。Runner描述my-docker-runner。Tag标签docker,node可以为Runner打标签在.gitlab-ci.yml中指定作业由特定标签的Runner执行。Executor执行器选择docker。默认Docker镜像node:16-alpine根据你的项目选择如python:3.9,maven:3-openjdk-11。注册成功后回到GitLab的Runners页面就能看到这个Runner处于online状态。此时向项目推送代码或创建MR就会自动触发流水线你可以在CI/CD - Pipelines中查看实时日志和状态。注意事项Runner的网络需要能访问GitLab服务器并且如果作业需要推送到私有仓库或部署到服务器需要在Runner环境中预先配置好SSH密钥、Docker登录凭证等敏感信息。切勿将这些信息写在.gitlab-ci.yml文件里正确做法是在GitLab项目设置Settings - CI/CD - Variables中创建环境变量如DEPLOY_SSH_KEY然后在作业脚本中引用echo $DEPLOY_SSH_KEY key.pem。5. 高级配置、维护与故障排查系统跑起来后日常维护和问题排查是保证其稳定运行的关键。5.1 邮箱、备份与升级5.1.1 邮箱配置补充前面在gitlab.rb中配置了SMTP如果没配或配错了可以随时修改并sudo gitlab-ctl reconfigure。一个常见的坑是邮箱服务商如QQ邮箱、163邮箱需要开启SMTP服务并获取授权码而不是用登录密码。务必使用正确的端口465/SSL或587/TLS和认证方式。5.1.2 数据备份与恢复定期备份是运维的生命线。GitLab的备份命令非常简单# Omnibus 安装方式 sudo gitlab-backup create # 备份文件会存储在 /var/opt/gitlab/backups/ 目录下文件名如 1712345678_2024_04_05_gitlab_backup.tar这个备份包含数据库、仓库、上传文件等。但不包含配置文件因此还需要备份配置文件sudo tar czf /path/to/backup/gitlab_config_backup_$(date %s).tar.gz /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json恢复备份时需要先停止相关服务然后执行恢复sudo gitlab-ctl stop unicorn sudo gitlab-ctl stop sidekiq # 指定备份文件的时间戳部分进行恢复 sudo gitlab-backup restore BACKUP1712345678_2024_04_05 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart5.1.3 版本升级对于Omnibus安装升级非常安全便捷# 更新包列表 sudo apt-get update # 升级到最新版本 sudo apt-get install gitlab-ce # 或者升级到指定版本 sudo apt-get install gitlab-ce16.10.1-ce.0升级前务必先进行完整备份。升级后GitLab会自动运行gitlab-ctl reconfigure。对于Docker部署则是拉取新版本镜像并重启容器同样需要先备份数据卷。5.2 性能调优与监控GitLab卡顿十有八九是资源不足。查看服务状态与日志sudo gitlab-ctl status # 查看所有组件状态 sudo gitlab-ctl tail # 实时查看所有日志 sudo gitlab-ctl tail postgresql # 只看数据库日志监控Sidekiq队列Sidekiq是处理后台作业如发邮件、处理CI的组件如果队列堆积会导致操作缓慢。在GitLab管理后台Admin Area - Monitoring - Background Jobs可以查看队列情况。调整Puma工作进程对于高并发访问可以增加PumaWeb服务器的工作进程数。在gitlab.rb中修改puma[worker_processes] 4 # 默认是CPU核数可适当调高但不要超过内存限制使用Prometheus监控GitLab内置了Prometheus和Grafana可以监控服务器资源、GitLab自身指标。在gitlab.rb中启用prometheus_monitoring并reconfigure后访问http://your-gitlab/-/grafana默认账号/密码admin/admin即可查看丰富的仪表盘。5.3 常见问题排查实录这里记录几个我踩过坑的典型问题及解决方法。问题1页面访问出现“502 Whoops, GitLab is taking too much time to respond.”可能原因最常见的是内存不足导致Puma或Sidekiq进程被系统杀死。排查运行sudo gitlab-ctl status看是否有服务显示down。运行free -h和top查看内存使用情况。解决临时sudo gitlab-ctl restart。根本增加服务器内存。或者在gitlab.rb中调低一些服务的资源占用治标不治本例如减少puma[worker_processes]或增加Swap空间。问题2Git克隆或推送大型仓库时超时或失败可能原因Nginx或GitLab Shell的超时设置过短或网络不稳定。解决修改gitlab.rb增加超时时间。nginx[proxy_read_timeout] 300 gitlab_rails[gitlab_shell_timeout] 300然后sudo gitlab-ctl reconfigure。对于超大文件可以考虑启用Git LFSLarge File Storage。问题3CI/CD流水线一直处于“Pending”状态可能原因没有可用的Runner或Runner离线或作业的标签tags不匹配。排查进入项目Settings - CI/CD - Runners查看是否有Active的Runner。在Runner服务器上运行sudo gitlab-runner status和sudo gitlab-runner verify检查Runner状态。检查.gitlab-ci.yml中的作业是否指定了tags如tags: - docker而你的Runner是否注册了对应的标签。解决确保Runner在线且标签匹配。可以在作业配置中添加tags: - docker或者在Runner注册时打上对应的标签。问题4发送邮件失败可能原因SMTP配置错误、端口被屏蔽、邮箱服务商限制。排查查看邮件发送日志sudo gitlab-ctl tail postfix或sudo gitlab-ctl tail gitlab-rails。解决仔细核对gitlab.rb中的SMTP配置特别是密码/授权码、端口、TLS/SSL设置。使用telnet或openssl s_client命令测试是否能连接到SMTP服务器。对于云服务器检查安全组/防火墙是否放行了465或587端口。问题5登录失败提示“Login failed. Check API token or Gitlab version. Log in via Git if the version is below 15.8.”可能原因这个错误通常出现在使用某些第三方客户端如VS Code插件、Jenkins插件通过API或Git操作认证时。原因可能是使用的个人访问令牌Personal Access Token或API令牌已过期、被撤销或者权限不足。客户端配置的GitLab实例版本信息有误。如果GitLab版本低于15.8某些认证方式可能被调整。排查与解决检查令牌登录GitLab进入Preferences - Access Tokens确认你使用的令牌是否存在、是否在有效期内、是否勾选了足够的权限如api,read_repository,write_repository等。重新生成令牌最稳妥的方法是撤销旧令牌创建一个新的、具有完整权限的令牌并在客户端更新配置。检查客户端配置确保客户端中配置的GitLab URL正确无误不要有多余的斜杠。对于Git操作如果是在命令行进行Git操作git clone,git push时遇到请确认你使用的是SSH方式git...还是HTTP方式。如果是HTTP方式密码可能已失效尝试重新生成令牌并在密码处粘贴令牌。更推荐使用配置了SSH密钥的方式。升级GitLab如果版本确实很旧考虑升级到受支持的版本。