当前位置： 首页 > news >正文

GitLab 从零部署到核心工作流：代码托管、SSH 密钥配置与合并请求实战

news 2026/8/17 3:05:39

1. 背景与核心概念

在团队协作开发中，代码管理是项目成功的基石。你是否曾因代码版本混乱、多人修改冲突或部署流程繁琐而头疼？GitLab 正是为解决这些问题而生的强大一体化 DevOps 平台。它不仅仅是一个 Git 代码仓库，更集成了项目管理、持续集成/持续部署（CI/CD）、代码审查、安全扫描、容器镜像仓库等全套工具链，旨在打通从“想法”到“产品”的整个软件开发生命周期。

对于初学者而言，GitLab 的核心价值在于其“一体化”和“开箱即用”。你无需再为代码仓库、CI/CD 服务器、制品库等工具间的集成而烦恼。GitLab 社区版（CE）提供了绝大部分核心功能，足以满足个人开发者、初创团队乃至中小企业的需求。本文将聚焦于 GitLab 的初阶使用，带你从零开始，掌握代码托管、分支管理、合并请求（Merge Request）等核心工作流，为后续深入 CI/CD 和高级 DevOps 实践打下坚实基础。

2. 环境准备与版本说明

在开始 GitLab 之旅前，你需要一个运行环境。GitLab 支持多种安装方式，包括 Omnibus 包（推荐）、Docker、云托管等。为了获得最接近生产环境的体验，我们选择在 Ubuntu 22.04 LTS 服务器上使用官方 Omnibus 包进行安装。这种方式集成了 GitLab 所需的所有服务（如 Nginx, PostgreSQL, Redis），管理起来最为方便。

环境要求：

  • 操作系统：Ubuntu 22.04.5 LTS（其他 Linux 发行版步骤类似，包管理命令不同）。
  • 硬件资源：至少 4GB 可用内存。GitLab 本身较为消耗资源，内存不足会导致启动缓慢或服务异常。
  • 网络：服务器需要能够访问互联网以下载安装包和依赖。
  • 权限：需要sudo或root权限执行安装和配置命令。

版本说明：本文将以 GitLab 社区版（CE）为例，安装时我们将获取当前稳定版本。软件版本迭代迅速，具体版本号可能会随时间变化，但核心配置和操作流程是通用的。所有命令和配置均基于 Ubuntu 22.04 和 GitLab CE 的典型环境，其他环境请参考官方文档进行适配。

3. 安装与初始配置

3.1 系统准备与依赖安装

首先，我们需要更新系统包列表并安装一些必要的工具。

# 以 root 用户或使用 sudo 执行 # 更新本地软件包索引 sudo apt update # 升级已安装的软件包 sudo apt upgrade -y # 安装 curl、openssh-server、ca-certificates 等基础工具 sudo apt install -y curl openssh-server ca-certificates tzdata perl

接下来，我们需要配置 Postfix 来发送通知邮件。如果你有外部 SMTP 服务器（如腾讯企业邮、阿里云邮件推送），可以跳过此步，后续在 GitLab 界面中配置。这里我们选择“仅本地投递”，这样系统生成的邮件会保存在本地，适合测试环境。

# 安装 Postfix sudo apt install -y postfix

在安装过程中，会弹出配置窗口。选择“Internet Site”，然后系统主机名（如gitlab.yourdomain.com）可以直接按回车使用默认值。

3.2 添加 GitLab 仓库并安装

使用官方脚本添加 GitLab 软件仓库，这将确保我们获取到经过签名的、最新的安装包。

# 下载并执行 GitLab 仓库安装脚本 curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

脚本执行成功后，就可以安装 GitLab 社区版了。EXTERNAL_URL参数至关重要，它定义了 GitLab 实例的访问地址。请将其替换为你服务器的实际 IP 地址或域名。

# 安装 GitLab CE，并设置初始访问 URL sudo EXTERNAL_URL="http://your_server_ip_or_domain" apt install gitlab-ce

例如，如果你的服务器 IP 是192.168.1.100，则命令为：

sudo EXTERNAL_URL="http://192.168.1.100" apt install gitlab-ce

安装过程会自动下载约几百 MB 的包，并完成所有服务的初始配置，包括 Nginx、PostgreSQL、Redis 等。这可能需要几分钟时间。

3.3 初始访问与密码修改

安装完成后，GitLab 服务会自动启动。你可以通过上面设置的EXTERNAL_URL在浏览器中访问你的 GitLab 实例。

首次访问时，你会被重定向到一个设置管理员账户密码的页面。这个账户的用户名是root。请务必设置一个强密码并妥善保管。

  1. 在浏览器打开http://your_server_ip_or_domain。
  2. 为root用户设置新密码。
  3. 使用用户名root和刚设置的密码登录。

登录成功后，你就进入了 GitLab 的管理员界面。恭喜，你的私有 GitLab 服务器已经搭建完成！

3.4 基础安全配置（可选但重要）

出于安全考虑，生产环境至少应该做两件事：

  1. 配置 HTTPS：使用 Let‘s Encrypt 免费证书或自己的商业证书。Omnibus 包内置了 Let’s Encrypt 支持，只需修改配置文件/etc/gitlab/gitlab.rb中的external_url为https://开头，并设置letsencrypt['contact_emails']即可。
  2. 限制注册：默认情况下，任何人都可以注册账户。对于内部使用的 GitLab，建议关闭公开注册。
    • 以管理员身份登录后，点击左上角“菜单” -> “管理员” -> “设置” -> “通用” -> “注册限制”。
    • 取消勾选“注册已启用”，然后滚动到页面底部点击“保存更改”。

4. GitLab 核心功能初阶使用

4.1 创建你的第一个项目

项目（Project）是 GitLab 中组织代码的基本单位，相当于 GitHub 中的 Repository。

  1. 登录后，点击导航栏上的“+”号，选择“新建项目”。
  2. 选择“创建空白项目”。
  3. 填写项目信息：
    • 项目名称：例如my-first-project。
    • 项目URL：它会根据组和项目名自动生成，可以保持默认。
    • 项目描述：（可选）简单描述项目用途。
    • 可见性级别：选择“私有”（只有你授权的用户能看到）。这是最安全的初始选择。
  4. 点击“创建项目”。

项目创建成功后，页面会显示如何将本地已有的代码推送到这个空仓库，或者如何从零开始初始化项目。我们选择从零开始。

4.2 配置 SSH 密钥（实现免密推送）

为了避免每次推送代码都输入用户名和密码，最安全便捷的方式是使用 SSH 密钥进行认证。这也是网络热词中“gitlab配置ssh密钥”的核心操作。

在本地机器上生成 SSH 密钥对：打开终端（Linux/Mac）或 Git Bash（Windows），执行以下命令。将your_email@example.com替换为你的邮箱。

ssh-keygen -t ed25519 -C “your_email@example.com”

-t ed25519指定生成更安全、更快的 Ed25519 算法密钥。你也可以使用-t rsa -b 4096。 连续按三次回车，接受默认的密钥保存路径（~/.ssh/id_ed25519）和不设置密码（为方便起见，生产环境建议设置密码）。

将公钥添加到 GitLab：

  1. 查看并复制公钥内容：
    cat ~/.ssh/id_ed25519.pub
    输出是一长串以ssh-ed25519开头的文本，全部复制。
  2. 在 GitLab 网页上，点击右上角头像 -> “编辑个人资料”。
  3. 在左侧边栏选择“SSH 密钥”。
  4. 将复制的公钥内容粘贴到“密钥”文本框中。“标题”会自动生成，你也可以手动修改（如“My Laptop”）。
  5. 点击“添加密钥”。

测试连接：

ssh -T git@your_server_ip_or_domain

首次连接会询问是否信任主机，输入yes。如果看到 “Welcome to GitLab, @username!”，说明配置成功。

4.3 本地 Git 基础操作与远程同步

现在，我们将本地开发与 GitLab 远程仓库关联起来。

初始化本地仓库并关联远程：

# 1. 在本地创建一个项目目录并进入 mkdir my-first-project cd my-first-project # 2. 初始化本地 Git 仓库 git init # 3. 创建一个简单的文件并提交 echo “# My First GitLab Project” > README.md git add README.md git commit -m “Initial commit with README” # 4. 添加 GitLab 远程仓库地址 # 地址格式：git@your_server_ip_or_domain:username/project.git # 你可以在 GitLab 项目主页找到 “克隆” 按钮，选择 “用 SSH 克隆” 并复制地址 git remote add origin git@your_server_ip_or_domain:root/my-first-project.git # 5. 将本地 master/main 分支推送到远程仓库 # 如果本地分支名是 master git push -u origin master # 如果本地分支名是 main（Git 2.28+ 默认） git push -u origin main

-u参数设置了上游（upstream）分支，以后在这个分支上直接使用git push和git pull即可，无需再指定远程和分支名。

日常开发流程：

# 拉取远程最新代码（建议每次开始工作前执行） git pull # 创建并切换到一个新功能分支 git checkout -b feature/add-login # ... 进行代码修改 ... # 将修改添加到暂存区 git add . # 提交修改到本地仓库 git commit -m “feat: add user login functionality” # 将功能分支推送到远程 GitLab git push -u origin feature/add-login

4.4 使用合并请求（Merge Request）进行代码审查

合并请求（MR）是 GitLab 协作的核心。它允许你将一个分支的更改合并到另一个分支（如main），并在此过程中进行代码讨论、审查和持续集成检查。

  1. 推送分支后创建 MR：当你将像feature/add-login这样的分支推送到远程后，GitLab 通常会提示你 “Create merge request”。点击它。
  2. 填写 MR 信息：
    • 标题：清晰描述改动，如“添加用户登录功能”。
    • 描述：详细说明改动内容、原因、测试方法等。可以使用 Markdown 格式。
    • 源分支：选择feature/add-login。
    • 目标分支：选择main。
    • 分配：可以分配给特定同事进行审查。
    • 里程碑/标签：可选，用于项目管理。
  3. 提交 MR：点击“创建合并请求”。
  4. 代码审查：审查者可以在 MR 的“更改”标签页查看代码差异，对具体行添加评论。开发者可以根据评论在线修改代码并再次推送，MR 会自动更新。
  5. 合并：当所有讨论都解决，且 CI/CD 流水线（如果配置了）通过后，具有权限的成员可以点击“合并”按钮。你可以选择“合并提交”、“压缩提交”或“变基后合并”等策略。

4.5 使用 Issue 进行任务跟踪

Issue 用于跟踪任务、增强功能、缺陷报告或任何需要讨论的事项。

  1. 在项目侧边栏，进入“议题” -> “新建议题”。
  2. 填写标题和描述。描述应尽可能清晰，可以包含步骤、预期结果、实际结果、截图等。
  3. 可以分配负责人、设置截止日期、关联里程碑、添加标签（如bug，enhancement）。
  4. 提交后，团队成员可以在下方评论。当开发对应功能时，可以在提交信息或 MR 描述中通过#1这样的格式引用 Issue，GitLab 会自动建立关联。

5. 常见问题与排查思路

在 GitLab 使用过程中，尤其是初学阶段，难免会遇到一些问题。下面列出一些高频问题及其解决方法。

问题现象可能原因排查思路与解决方案
git push失败，提示Permission denied (publickey).1. SSH 密钥未添加到 GitLab。
2. SSH 代理未运行或未添加密钥。
3. 服务器防火墙阻止了 SSH 端口（22）。		1. 执行ssh -T git@your_server_ip测试连接。如果失败，检查 GitLab 上 SSH 密钥是否添加正确。
2. 确保私钥已加载到 SSH 代理：eval $(ssh-agent)然后ssh-add ~/.ssh/id_ed25519。
3. 检查服务器安全组或防火墙规则，确保 22 端口对客户端 IP 开放。
git clone或git push速度极慢1. 网络问题。
2. 仓库过大，且 Git 协议未优化。		1. 检查网络连接。对于国内服务器，确保客户端网络环境良好。
2. 考虑使用git config --global http.postBuffer 524288000增大缓冲区，或使用浅克隆git clone --depth 1。
登录 GitLab 失败，提示Invalid login or password.1. 用户名或密码错误。
2. 如果配置了 LDAP/OmniAuth，可能认证源有问题。
3. 用户被禁用。		1. 确认用户名（注意大小写）和密码。可以使用“忘记密码”功能重置。
2. 检查管理员是否配置了外部认证，并确保其正常工作。
3. 联系管理员检查用户状态。
GitLab 页面访问很慢或502错误1. 服务器资源（内存/CPU）不足。
2. GitLab 服务未完全启动或崩溃。
3. Nginx 配置问题。		1. 使用sudo gitlab-ctl status检查所有服务是否都是run状态。如果有down，查看日志sudo gitlab-ctl tail。
2. 使用free -h和top检查系统资源。GitLab 需要至少 4GB 可用内存。
3. 尝试重启 GitLab：sudo gitlab-ctl restart。
执行git push提示remote: GitLab: You are not allowed to push code to this project.用户对该项目没有推送权限。1. 确认你登录的账户是否有该项目的开发者（Developer）或维护者（Maintainer）角色。
2. 联系项目管理员将你添加到项目成员中，并分配相应权限。
合并请求（MR）无法创建，提示“源分支与目标分支相同”你在同一个分支上操作，或者源分支已经合并/删除。确保你正在从一个不同的功能分支（如feature/xxx）向主分支（如main）创建 MR。在推送新分支后再尝试创建 MR。
GitLab 启动时卡在gitlab waiting for gitlab to boot通常是服务启动超时，可能因为服务器配置低、磁盘慢或首次启动需要初始化数据库。1.耐心等待，首次启动可能需要 5-10 分钟。
2. 查看具体服务的日志：sudo gitlab-ctl tail unicorn或sudo gitlab-ctl tail sidekiq。
3. 增加服务器资源配置（尤其是内存）。

6. 最佳实践与工程建议

掌握基础操作后，遵循一些最佳实践能让你的团队协作更高效、代码库更健康。

  1. 分支策略：

    • 主分支保护：将main或master分支设置为“受保护分支”，禁止直接推送，强制所有更改通过合并请求（MR）进行。这为代码审查和 CI/CD 检查提供了入口。
    • 功能分支开发：为每个新功能、修复或实验创建一个新的分支，命名规范如feature/user-auth，fix/login-error，hotfix/critical-bug。
    • 分支生命周期：功能合并后，及时删除远程功能分支。可以在 MR 合并设置中勾选“合并后删除源分支”。

  2. 提交信息规范：

    • 使用清晰、简洁的提交信息。推荐使用约定式提交（Conventional Commits），例如：
      • feat: 添加用户登录功能
      • fix: 修复首页图片无法加载的问题
      • docs: 更新 API 接口文档
      • style: 调整代码格式，无逻辑变更
      • refactor: 重构用户模块代码
    • 这有助于自动生成变更日志（CHANGELOG）。

  3. .gitignore文件：

    • 在项目根目录创建.gitignore文件，列出不需要纳入版本控制的文件，如编译产物（*.class，*.o）、依赖目录（node_modules/，vendor/）、IDE 配置文件（.idea/，.vscode/）、系统文件（.DS_Store）等。
    • 这能保持仓库清洁，避免提交无关的大文件。

  4. 利用 GitLab 内置功能：

    • Wiki：为项目维护文档、架构说明、开发指南。
    • Snippets：分享常用的代码片段。
    • Container Registry：存储 Docker 镜像，与 CI/CD 无缝集成。
    • Pages：可以免费托管静态网站（如项目文档、博客）。

  5. 定期备份与更新：

    • 备份：定期执行sudo gitlab-rake gitlab:backup:create进行完整备份，并将备份文件传输到异地。
    • 更新：关注 GitLab 官方发布的安全更新公告，定期升级到新版本以修复漏洞。使用sudo apt update && sudo apt upgrade gitlab-ce进行升级。

  6. 权限管理最小化原则：

    • 为用户分配刚好够用的权限。GitLab 角色从低到高有：访客（Guest）、报告者（Reporter）、开发者（Developer）、维护者（Maintainer）、所有者（Owner）。
    • 对于普通开发成员，通常“开发者”角色即可，允许推送代码、创建分支和 MR，但不能直接推送到受保护分支或操作生产环境设置。

从在 Ubuntu 上成功部署 GitLab 实例，到配置 SSH 密钥实现免密操作，再到通过功能分支、合并请求和 Issue 完成一次完整的代码协作流程，你已经走完了 GitLab 初阶使用的核心闭环。这些基础操作是日常开发中最频繁使用的部分，熟练掌握它们意味着你已具备了在团队中使用 GitLab 进行高效协作的能力。

接下来，你可以探索更高级的主题，例如：

  • CI/CD 流水线：在项目根目录创建.gitlab-ci.yml文件，定义自动化构建、测试和部署的流程。
  • Webhook 与集成：将 GitLab 与 Jenkins、钉钉、飞书等工具连接，实现通知自动化。
  • 代码质量与安全扫描：利用 GitLab 内置的 SAST（静态应用安全测试）、依赖扫描等功能提升代码健壮性。

实践是最好的老师。建议你立即创建一个个人项目，模拟一个完整的“功能开发 -> 提交 -> 创建 MR -> 代码审查 -> 合并”流程。遇到问题时，善用 GitLab 丰富的官方文档和社区资源。

http://www.jsqmd.com/news/1408400/

相关文章：

  • 跨镜追踪告别ID跳变：镜像视界融合人脸、服饰与微动作，重塑全域连续管控底座
  • 佛跳墙捞面速冻设备品牌怎么选？资深行业视角给出四条硬标准 - 装修教育财税推荐2026
  • 计算机专业宝藏老师：从基础到前沿，如何找到并最大化学习价值
  • 学生党实惠笔记本怎么选？多款高性价比产品推荐！
  • Firefox插件大全：从管理到精选，打造高效安全浏览器
  • 应对大型程序编译卡死问题
  • MySQL索引高级优化实战：覆盖索引、前缀索引与索引下推深度解析
  • 基于SpringBoot的线上教师培训系统的设计与实现(源码+lw+部署文档+讲解等)
  • 微信小程序“版本过低”报错深度解析：从客户端、基础库到代码的兼容性实战指南
  • 群体观点动力学：固执者与多数规则下的缩放定律仿真分析
  • 第一性原理计算：从量子力学基础到VASP实战应用
  • iOS应用备案必备：从证书与描述文件中提取MD5与公钥的完整指南
  • 机器人算法岗面试核心知识点与实战路径全解析
  • 具身智能数学基础(05)：集合与常用逻辑
  • Vue3 还原一个企业级后台-13-像素级验收
  • LaTeX Beamer制作专业演示文稿：从原理到实践的全流程指南
  • 从单点到集群：Mosquitto桥接集群实战部署与高可用架构设计
  • AI与大模型新闻日报 | 2026-08-16
  • BUCK电路调试：环路补偿、功率级参数与PCB布局的协同设计
  • 科研中的“知其然不知其所以然“：如何从会用方法到讲清原理
  • 集团首都公报：放飞炬人集团财政署资金部批准面值总额4千亿人民币的自主中央本金拨备计划
  • .NET Framework 4.5升级4.8.x实战指南：安全、性能与兼容性全面解析
  • ROOT手机修改系统属性实现微信平板模式多设备共存登录
  • Flutter笔记--SliverFloatingHeader
  • 零基础玩转微信抢红包插件WeChatLuckyMoney：从安装到高阶调优的完整实战笔记
  • 职场新人适应指南：从环境到身份的五个系统性切换
  • 右键菜单越用越乱？可视化开关加免碰注册表，ContextMenuManager 一次清干净
  • LAV Filters 安装配置全攻略：一套解码器搞定 Windows 上几乎所有视频格式
  • PyTorch张量操作与自动微分实战指南
  • CommunityToolkit