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_URLhttp://your_server_ip_or_domain apt install gitlab-ce例如如果你的服务器 IP 是192.168.1.100则命令为sudo EXTERNAL_URLhttp://192.168.1.100 apt install gitlab-ce安装过程会自动下载约几百 MB 的包并完成所有服务的初始配置包括 Nginx、PostgreSQL、Redis 等。这可能需要几分钟时间。3.3 初始访问与密码修改安装完成后GitLab 服务会自动启动。你可以通过上面设置的EXTERNAL_URL在浏览器中访问你的 GitLab 实例。首次访问时你会被重定向到一个设置管理员账户密码的页面。这个账户的用户名是root。请务必设置一个强密码并妥善保管。在浏览器打开http://your_server_ip_or_domain。为root用户设置新密码。使用用户名root和刚设置的密码登录。登录成功后你就进入了 GitLab 的管理员界面。恭喜你的私有 GitLab 服务器已经搭建完成3.4 基础安全配置可选但重要出于安全考虑生产环境至少应该做两件事配置 HTTPS使用 Let‘s Encrypt 免费证书或自己的商业证书。Omnibus 包内置了 Let’s Encrypt 支持只需修改配置文件/etc/gitlab/gitlab.rb中的external_url为https://开头并设置letsencrypt[contact_emails]即可。限制注册默认情况下任何人都可以注册账户。对于内部使用的 GitLab建议关闭公开注册。以管理员身份登录后点击左上角“菜单” - “管理员” - “设置” - “通用” - “注册限制”。取消勾选“注册已启用”然后滚动到页面底部点击“保存更改”。4. GitLab 核心功能初阶使用4.1 创建你的第一个项目项目Project是 GitLab 中组织代码的基本单位相当于 GitHub 中的 Repository。登录后点击导航栏上的“”号选择“新建项目”。选择“创建空白项目”。填写项目信息项目名称例如my-first-project。项目URL它会根据组和项目名自动生成可以保持默认。项目描述可选简单描述项目用途。可见性级别选择“私有”只有你授权的用户能看到。这是最安全的初始选择。点击“创建项目”。项目创建成功后页面会显示如何将本地已有的代码推送到这个空仓库或者如何从零开始初始化项目。我们选择从零开始。4.2 配置 SSH 密钥实现免密推送为了避免每次推送代码都输入用户名和密码最安全便捷的方式是使用 SSH 密钥进行认证。这也是网络热词中“gitlab配置ssh密钥”的核心操作。在本地机器上生成 SSH 密钥对打开终端Linux/Mac或 Git BashWindows执行以下命令。将your_emailexample.com替换为你的邮箱。ssh-keygen -t ed25519 -C “your_emailexample.com”-t ed25519指定生成更安全、更快的 Ed25519 算法密钥。你也可以使用-t rsa -b 4096。 连续按三次回车接受默认的密钥保存路径~/.ssh/id_ed25519和不设置密码为方便起见生产环境建议设置密码。将公钥添加到 GitLab查看并复制公钥内容cat ~/.ssh/id_ed25519.pub输出是一长串以ssh-ed25519开头的文本全部复制。在 GitLab 网页上点击右上角头像 - “编辑个人资料”。在左侧边栏选择“SSH 密钥”。将复制的公钥内容粘贴到“密钥”文本框中。“标题”会自动生成你也可以手动修改如“My Laptop”。点击“添加密钥”。测试连接ssh -T gityour_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 远程仓库地址 # 地址格式gityour_server_ip_or_domain:username/project.git # 你可以在 GitLab 项目主页找到 “克隆” 按钮选择 “用 SSH 克隆” 并复制地址 git remote add origin gityour_server_ip_or_domain:root/my-first-project.git # 5. 将本地 master/main 分支推送到远程仓库 # 如果本地分支名是 master git push -u origin master # 如果本地分支名是 mainGit 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-login4.4 使用合并请求Merge Request进行代码审查合并请求MR是 GitLab 协作的核心。它允许你将一个分支的更改合并到另一个分支如main并在此过程中进行代码讨论、审查和持续集成检查。推送分支后创建 MR当你将像feature/add-login这样的分支推送到远程后GitLab 通常会提示你 “Create merge request”。点击它。填写 MR 信息标题清晰描述改动如“添加用户登录功能”。描述详细说明改动内容、原因、测试方法等。可以使用 Markdown 格式。源分支选择feature/add-login。目标分支选择main。分配可以分配给特定同事进行审查。里程碑/标签可选用于项目管理。提交 MR点击“创建合并请求”。代码审查审查者可以在 MR 的“更改”标签页查看代码差异对具体行添加评论。开发者可以根据评论在线修改代码并再次推送MR 会自动更新。合并当所有讨论都解决且 CI/CD 流水线如果配置了通过后具有权限的成员可以点击“合并”按钮。你可以选择“合并提交”、“压缩提交”或“变基后合并”等策略。4.5 使用 Issue 进行任务跟踪Issue 用于跟踪任务、增强功能、缺陷报告或任何需要讨论的事项。在项目侧边栏进入“议题” - “新建议题”。填写标题和描述。描述应尽可能清晰可以包含步骤、预期结果、实际结果、截图等。可以分配负责人、设置截止日期、关联里程碑、添加标签如bugenhancement。提交后团队成员可以在下方评论。当开发对应功能时可以在提交信息或 MR 描述中通过#1这样的格式引用 IssueGitLab 会自动建立关联。5. 常见问题与排查思路在 GitLab 使用过程中尤其是初学阶段难免会遇到一些问题。下面列出一些高频问题及其解决方法。问题现象可能原因排查思路与解决方案git push失败提示Permission denied (publickey).1. SSH 密钥未添加到 GitLab。2. SSH 代理未运行或未添加密钥。3. 服务器防火墙阻止了 SSH 端口22。1. 执行ssh -T gityour_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. 尝试重启 GitLabsudo 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. 最佳实践与工程建议掌握基础操作后遵循一些最佳实践能让你的团队协作更高效、代码库更健康。分支策略主分支保护将main或master分支设置为“受保护分支”禁止直接推送强制所有更改通过合并请求MR进行。这为代码审查和 CI/CD 检查提供了入口。功能分支开发为每个新功能、修复或实验创建一个新的分支命名规范如feature/user-authfix/login-errorhotfix/critical-bug。分支生命周期功能合并后及时删除远程功能分支。可以在 MR 合并设置中勾选“合并后删除源分支”。提交信息规范使用清晰、简洁的提交信息。推荐使用约定式提交Conventional Commits例如feat: 添加用户登录功能fix: 修复首页图片无法加载的问题docs: 更新 API 接口文档style: 调整代码格式无逻辑变更refactor: 重构用户模块代码这有助于自动生成变更日志CHANGELOG。.gitignore文件在项目根目录创建.gitignore文件列出不需要纳入版本控制的文件如编译产物*.class*.o、依赖目录node_modules/vendor/、IDE 配置文件.idea/.vscode/、系统文件.DS_Store等。这能保持仓库清洁避免提交无关的大文件。利用 GitLab 内置功能Wiki为项目维护文档、架构说明、开发指南。Snippets分享常用的代码片段。Container Registry存储 Docker 镜像与 CI/CD 无缝集成。Pages可以免费托管静态网站如项目文档、博客。定期备份与更新备份定期执行sudo gitlab-rake gitlab:backup:create进行完整备份并将备份文件传输到异地。更新关注 GitLab 官方发布的安全更新公告定期升级到新版本以修复漏洞。使用sudo apt update sudo apt upgrade gitlab-ce进行升级。权限管理最小化原则为用户分配刚好够用的权限。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 丰富的官方文档和社区资源。