这次我们来看一个面向初学者的 GitLab 入门教程。GitLab 作为一个集代码托管、CI/CD、项目管理于一体的 DevOps 平台对于开发者团队来说几乎是标配。但很多新手在初次接触时往往被其丰富的功能界面和复杂的配置项劝退。本教程的目标就是帮你快速上手从零开始搭建一个可用的 GitLab 环境并掌握最核心的日常操作。本文将重点解决几个关键问题GitLab 是什么它和 GitHub 有什么区别如何在本地或服务器上快速部署一个 GitLab 实例如何配置 SSH 密钥、创建项目、进行代码的拉取与推送以及如何应对常见的启动失败、登录失败等问题。无论你是个人开发者想搭建私有代码仓库还是团队需要部署一套内部 DevOps 平台这篇文章都能提供一条清晰的路径。1. 核心能力速览在深入细节之前我们先通过一个表格快速了解 GitLab 的核心能力与部署门槛让你判断它是否适合你的需求。能力项说明项目类型一体化 DevOps 平台包含 Git 仓库、CI/CD、项目管理、Wiki、容器注册表等。开源/商业提供社区免费版CE和企业付费版EE社区版功能已足够强大。主要功能代码版本控制、问题跟踪、合并请求、持续集成/持续部署CI/CD、代码审查、Wiki、容器镜像仓库。推荐硬件最低配置2核CPU4GB内存仅用于体验。生产推荐4核CPU8GB内存及以上。内存是关键直接影响运行流畅度。存储占用安装包约1-2GB运行后根据项目数量和代码量增长。需要预留足够磁盘空间用于仓库、备份和容器镜像。支持平台LinuxUbuntu, CentOS, Debian 等主流发行版是官方首选。Windows 下可通过 Docker 或虚拟机部署。启动方式多种方式Linux 原生包安装Omnibus、Docker/Docker Compose、Kubernetes Helm Chart、云市场镜像。是否支持 API是。提供功能完善的 REST API可用于自动化管理项目、用户、流水线等。是否支持批量任务是。通过 CI/CD 流水线、API 或脚本可以实现代码检查、构建、测试、部署的自动化批量处理。适合场景个人/团队私有代码托管、企业内部 DevOps 流程建设、学习 Git 和 CI/CD、作为 Jenkins 等工具的替代或补充。2. 适用场景与使用边界GitLab 功能强大但并非所有场景都适用。明确它的边界能帮助你更好地决策。GitLab 最适合谁中小型开发团队需要一个集代码管理、代码审查、自动化构建部署于一体的私有化平台。个人开发者希望拥有完全自主控制的私有 Git 仓库用于存放个人项目、学习笔记或敏感代码。DevOps 学习者想亲手搭建并实践一套完整的 CI/CD 流水线从代码提交到自动部署。企业 IT 部门需要构建内部统一的研发管理平台并与现有的 LDAP、监控等系统集成。GitLab 能解决什么问题代码集中管理告别散落的代码文件夹实现版本化、协作化的代码管理。流程规范化通过合并请求Merge Request强制代码审查提升代码质量。自动化提效通过.gitlab-ci.yml配置文件实现代码提交后自动测试、构建、打包、部署解放重复劳动。知识沉淀利用 Wiki 和 Issues 记录项目文档和任务追踪。GitLab 可能不适合什么场景超小规模或个人临时项目如果只是需要一个地方放代码GitHub、Gitee 的免费公有仓库可能更轻量、更方便。资源极度受限的环境GitLab 本身有一定资源消耗尤其是内存在低配 VPS 或旧电脑上运行可能比较吃力。只需要单纯的 Git 服务器如果团队只需要最基础的 Git 远程仓库功能类似 Gogs/Gitea那么更轻量的方案可能更合适。安全与合规边界提醒私有部署数据自主这是 GitLab 私有部署的最大优势所有代码和数据都保存在你自己的服务器上。及时更新需关注 GitLab 官方发布的安全更新及时修补高危漏洞防止被攻击。权限控制合理设置项目、分支的访问权限避免代码泄露。定期备份务必配置定期备份策略防止服务器故障导致数据丢失。3. 环境准备与前置条件在开始安装之前请确保你的环境满足以下要求。这里我们以最常用的Ubuntu 22.04 LTS服务器环境为例进行说明。操作系统推荐Ubuntu 22.04/20.04 LTS, CentOS 8/7 (请注意 CentOS 7 已停止维护建议用 Rocky/AlmaLinux 替代)。可接受其他主流 Linux 发行版但安装命令可能不同。Windows/Mac建议通过 Docker 方式运行以获得接近原生体验。硬件资源CPU2 核或以上。用于 CI/CD 运行构建任务时核心数越多越好。内存这是关键最低 4GB但强烈建议 8GB 或以上。内存不足是导致 GitLab 启动慢、页面卡顿甚至启动失败 (gitlab waiting for gitlab to boot) 的最常见原因。磁盘至少 20GB 可用空间。需要考虑操作系统、GitLab 安装包、仓库数据、备份文件以及容器镜像如果使用 CI/CD的存储。网络与端口GitLab 默认使用以下端口请确保它们未被占用或防火墙已放行80(HTTP) /443(HTTPS)Web 界面访问。22(SSH)Git SSH 协议克隆/推送代码。注意如果你的服务器 SSH 服务已占用 22 端口GitLab 会使用8022等端口需要另行配置。如果需要从外网访问请配置好服务器的公网 IP、域名和 DNS 解析。软件依赖GitLab Omnibus 包推荐安装方式已包含所有必要依赖如 PostgreSQL, Redis, Nginx。如果通过 Docker 安装则需要预先安装 Docker 和 Docker Compose。系统需要安装curl、openssh-server等基础工具。4. 安装部署与启动方式GitLab 提供了多种安装方式这里介绍两种最主流、最适合新手的方案Linux 原生包安装和Docker Compose 安装。4.1 方案一Linux 原生包安装Omnibus - 推荐这是官方最推荐的方式集成度高管理方便。以下以 Ubuntu 22.04 为例。步骤 1安装必要依赖并配置仓库# 更新系统包列表 sudo apt update sudo apt install -y curl openssh-server ca-certificates tzdata perl # 添加 GitLab 官方仓库并安装 curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash步骤 2安装 GitLab CE社区版安装命令中的EXTERNAL_URL需要替换为你打算访问 GitLab 的地址。如果是初次体验可以用服务器的 IP 地址。# 将 EXTERNAL_URL 替换为你的实际地址例如 http://your-server-ip 或 https://gitlab.yourdomain.com sudo EXTERNAL_URLhttp://your-server-ip apt install gitlab-ce安装过程会自动下载并安装所有组件耗时可能几分钟到十几分钟取决于网络速度。步骤 3初始配置与启动安装完成后需要进行一次初始配置这会根据你设置的EXTERNAL_URL重新生成配置。# 重新配置 GitLab (这步很重要) sudo gitlab-ctl reconfigure这个过程会启动所有服务PostgreSQL, Redis, Sidekiq, GitLab Workhorse等并设置管理员账户。请耐心等待直到看到命令执行完成。步骤 4访问与登录在浏览器中打开你设置的EXTERNAL_URL例如http://your-server-ip。 首次访问会强制你为root用户设置密码。设置一个强密码后即可使用root和该密码登录。4.2 方案二Docker Compose 安装灵活轻量如果你熟悉 Docker或者希望在非 Linux 系统如 Windows/macOS上运行Docker Compose 是个好选择。它更灵活清理也方便。步骤 1创建docker-compose.yml文件在一个目录下例如~/gitlab-docker创建该文件。version: 3.8 services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab restart: always hostname: your-server-ip # 或你的域名 environment: GITLAB_OMNIBUS_CONFIG: | external_url http://your-server-ip # 与 hostname 一致 # 可以在此添加其他配置如关闭用户注册 # gitlab_rails[gitlab_signup_enabled] false ports: - 80:80 - 443:443 - 8022:22 # 将宿主机的8022端口映射到容器的22端口避免与宿主机SSH冲突 volumes: - ./config:/etc/gitlab - ./logs:/var/log/gitlab - ./data:/var/opt/gitlab shm_size: 256m关键配置说明hostname和external_url请替换为你的服务器 IP 或域名。ports8022:22映射是为了避免与宿主机 SSH 服务冲突。之后克隆仓库的地址需要带上端口如ssh://gityour-server-ip:8022/username/project.git。volumes将配置、日志、数据持久化到宿主机避免容器删除后数据丢失。步骤 2启动 GitLab 容器# 进入 docker-compose.yml 所在目录 cd ~/gitlab-docker # 启动服务后台运行 docker-compose up -d首次启动会下载镜像并初始化耗时较长可能超过10分钟。可以通过docker-compose logs -f gitlab查看实时日志。步骤 3等待启动完成并登录同样在浏览器访问http://your-server-ip。初始设置root密码的流程与原生安装一致。5. 功能测试与效果验证安装并登录后我们来进行一系列核心功能测试确保 GitLab 运行正常。5.1 测试 1创建第一个项目目的验证 GitLab 最基本的代码仓库创建功能。登录后点击导航栏上的号选择New project。选择Create blank project。填写项目名称如my-first-project可见性级别选择Private私有。点击Create project。预期结果成功进入项目空仓库页面页面显示了如何推送现有仓库或创建新文件的指引。这说明项目创建功能正常。5.2 测试 2配置 SSH 密钥并克隆项目目的解决gitlab配置ssh密钥问题实现免密代码拉取和推送。这是日常开发最关键的一步。生成 SSH 密钥对如果本地没有ssh-keygen -t ed25519 -C your_emailexample.com # 一路回车使用默认路径和空密码查看并复制公钥cat ~/.ssh/id_ed25519.pub复制输出的全部内容。在 GitLab 中添加公钥点击右上角用户头像 -Edit profile-SSH Keys。将复制的公钥粘贴到Key文本框中Title会自动生成也可自定义。点击Add key。测试 SSH 连接ssh -T gityour-server-ip -p 8022 # 如果是 Docker 安装且映射了8022端口需要加 -p如果看到Welcome to GitLab, username!的欢迎信息说明配置成功。克隆刚才创建的项目 在项目主页找到Clone按钮选择Clone with SSH复制地址。git clone ssh://gityour-server-ip:8022/root/my-first-project.git # 或 git clone gityour-server-ip:root/my-first-project.git (如果使用标准22端口)预期结果能成功克隆一个空仓库到本地。这验证了 SSH 认证和 Git 协议通信正常。5.3 测试 3基础 Git 操作推送与拉取目的验证完整的代码提交、推送、拉取流程。进入克隆的本地仓库目录。创建一个新文件并提交cd my-first-project echo # My First GitLab Project README.md git add README.md git commit -m Add README.md git push origin main # 或 master取决于默认分支名刷新 GitLab 项目页面。预期结果在 GitLab 网页上能看到刚刚提交的README.md文件及其内容。这证明代码推送功能正常。5.4 测试 4创建合并请求Merge Request目的体验 GitLab 的核心协作功能。在 GitLab 项目页点击Repository-Branches创建一个新分支feature-add-log。在本地切换到该分支修改文件并推送git checkout -b feature-add-log echo console.log(Hello GitLab); main.js git add main.js git commit -m Add a log message git push origin feature-add-log推送后GitLab 页面通常会弹出创建合并请求的提示。点击它或手动进入Merge Requests-New merge request。选择源分支feature-add-log和目标分支main填写标题和描述点击Create merge request。预期结果成功创建一个合并请求。你可以在这个 MR 页面进行代码讨论、评论模拟团队协作中的代码审查流程。6. 接口 API 与批量任务GitLab 的强大不仅在于 Web 界面更在于其全面的 API允许你通过编程方式进行几乎所有操作。6.1 访问 API首先你需要一个访问令牌Access Token。点击右上角头像 -Edit profile-Access Tokens。输入令牌名称如api-test选择权限范围例如api、read_repository、write_repository。点击Create personal access token务必立即复制并保存好生成的令牌它只会显示一次。6.2 基础 API 调用示例使用curl或任何 HTTP 客户端如 Pythonrequests即可调用。示例 1获取当前用户信息curl --header PRIVATE-TOKEN: 你的访问令牌 http://your-server-ip/api/v4/user这将返回一个 JSON包含你的用户 ID、用户名等信息。示例 2使用 Python 脚本创建项目import requests GITLAB_URL http://your-server-ip PRIVATE_TOKEN 你的访问令牌 headers {PRIVATE-TOKEN: PRIVATE_TOKEN} # 创建新项目 create_project_data { name: api-created-project, visibility: private } response requests.post(f{GITLAB_URL}/api/v4/projects, headersheaders, jsoncreate_project_data) print(f创建项目响应: {response.status_code}, {response.json()})这个脚本可以集成到自动化流程中实现项目的批量创建。6.3 批量任务实践使用 CI/CD 流水线GitLab CI/CD 是天然的批量任务执行引擎。通过在项目根目录创建.gitlab-ci.yml文件可以定义自动化任务。一个简单的.gitlab-ci.yml示例stages: - test - build unit-test: stage: test script: - echo Running unit tests... - npm test # 假设是 Node.js 项目 docker-build: stage: build script: - echo Building Docker image... - docker build -t my-app . only: - main # 仅在 main 分支提交时触发当你推送代码后GitLab 会自动启动一个流水线依次执行test和build阶段的任务。你可以在项目的CI/CD-Pipelines页面查看所有流水线的状态和日志实现了对批量构建/测试任务的可视化管理。7. 资源占用与性能观察GitLab 启动后需要关注其资源消耗尤其是在资源有限的服务器上。如何观察资源占用Linux 原生安装# 查看 GitLab 相关进程资源占用 sudo gitlab-ctl status # 查看服务状态 top # 查看整体资源按 M 按内存排序找到 rubyUnicorn, Sidekiq等进程 # 或者使用 htop 工具更直观Docker 安装docker stats gitlab # 查看容器的 CPU、内存、网络 IO 实时占用典型资源占用情况空闲时一个刚安装好、没有项目的 GitLab内存占用可能在1.5GB - 2.5GB左右。这是由 Ruby on Rails 应用、PostgreSQL、Redis 等组件共同占用的基础内存。活跃时当有用户访问、执行 CI/CD 流水线会启动新的 Runner 容器或进程时内存和 CPU 占用会显著上升。一个运行简单构建任务的 Runner 可能额外占用 500MB-1GB 内存。磁盘/var/opt/gitlab原生安装或你配置的 Docker 数据卷会持续增长需定期清理无用镜像、日志和构建缓存。性能优化建议增加内存这是提升体验最直接有效的方式建议生产环境至少 8GB。调整 Puma 工作进程数编辑/etc/gitlab/gitlab.rb原生安装或 Docker 环境变量调整puma[worker_processes]默认可能为2根据 CPU 核心数设置。使用外部数据库和 Redis对于更高负载可以考虑将 GitLab 的数据和缓存迁移到独立的、性能更好的 PostgreSQL 和 Redis 服务器。配置 CI/CD Runner 为独立服务器将计算密集型的 CI/CD 任务交给专门的 Runner 服务器执行避免影响 GitLab 主服务的稳定性。8. 常见问题与排查方法部署和使用 GitLab 时你可能会遇到以下问题。这里提供快速排查思路。问题现象可能原因排查方式解决方案页面无法访问 (502/404)服务未完全启动Nginx 配置错误端口冲突。1.sudo gitlab-ctl status查看服务状态。2.sudo gitlab-ctl tail nginx查看 Nginx 日志。3.netstat -tlnp检查 80/443 端口占用。1. 等待或执行sudo gitlab-ctl restart。2. 检查external_url配置是否正确。3. 停止占用端口的其他服务。gitlab waiting for gitlab to boot最常见于内存不足。GitLab 组件特别是 Puma 和 Sidekiq启动需要时间。1. 使用free -h或top检查内存和 Swap 使用情况。2.sudo gitlab-ctl tail查看所有组件日志。1.增加服务器内存或 Swap 空间。2. 耐心等待首次启动可能长达 20 分钟。3. 对于 Docker检查shm_size是否足够。login failed. check api token or gitlab version. log in via git if the versi使用错误的 API Token 或 Token 权限不足GitLab 版本与客户端工具不兼容。1. 确认使用的 Token 有效且具有所需权限如api。2. 确认 GitLab 版本某些旧版 CLI 工具可能不支持新版 API。1. 在 GitLab 用户设置中重新生成 Token 并妥善保存。2. 更新你的 Git 或 API 客户端到最新版本。3. 尝试使用 SSH 认证替代。SSH 克隆/推送失败SSH 密钥未添加或添加错误SSH 端口非标准 22 且未正确配置。1.ssh -T gityour-server-ip -p 端口测试连接。2. 检查~/.ssh/config是否有针对服务器的特殊配置。1. 重新在 GitLab 添加正确的公钥。2. 对于 Docker 的 8022 端口克隆地址需写为ssh://githost:8022/...或在~/.ssh/config中配置端口。CI/CD 流水线未触发项目未配置 Runner.gitlab-ci.yml语法错误Runner 未注册或离线。1. 进入项目Settings-CI/CD-Runners查看是否有可用 Runner。2. 在 CI Lint 工具/-/ci/lint中验证 YAML 语法。1. 安装并注册一个 GitLab Runner 到项目或群组。2. 根据 Runner 标签tags调整.gitlab-ci.yml中的tags。上传大文件失败超过 Git 或 GitLab 默认文件大小限制。查看上传时的错误信息。1.客户端git config http.postBuffer 524288000。2.服务器修改/etc/gitlab/gitlab.rb中的gitlab_rails[git_max_size]等参数并sudo gitlab-ctl reconfigure。汉化问题安装的是英文原版。社区有汉化补丁但非官方可能滞后于版本更新。1. 接受英文界面核心操作词汇不多。2. 如需汉化可搜索“gitlab 汉化”寻找对应版本的补丁但需自行承担升级风险。9. 最佳实践与使用建议为了让你的 GitLab 用得更顺畅、更安全这里有一些经验之谈。从小规模开始第一次部署先用最低配置或 Docker 快速拉起一个实例完成所有核心功能测试创建项目、SSH克隆、提交、合并请求再考虑迁移到生产服务器。务必立即修改 root 密码并创建新管理员首次登录后除了设置强密码建议立即创建一个普通用户并将其提升为管理员然后减少 root 的直接使用。规划目录结构对于 Docker 部署明确config、data、logs卷的宿主机路径并做好备份。配置备份定期备份至关重要。使用sudo gitlab-backup create原生安装或备份 Docker 数据卷。同时备份配置文件/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json。善用项目模板和 CI/CD 模板对于新项目可以从模板创建快速获得.gitlab-ci.yml、LICENSE、.gitignore等文件统一团队规范。精细化权限管理不要给所有人Maintainer权限。利用Guest、Reporter、Developer、Maintainer、Owner不同角色结合项目可见性私有、内部、公开控制代码访问范围。集成外部服务GitLab 可以集成 Jira、Slack、Mattermost 等工具将代码提交、合并请求、流水线状态同步到团队沟通平台提升效率。监控与维护关注服务器磁盘、内存、CPU 使用情况。定期查看 GitLab 的监控面板Admin Area-Monitoring并更新到最新的安全版本。10. 总结与下一步通过这篇教程你应该已经能够完成 GitLab 从零到一的部署并掌握了创建项目、配置 SSH、代码操作、合并请求等核心功能。GitLab 的学习曲线前期可能稍陡但一旦熟悉它将成为团队研发效能提升的强大引擎。最值得尝试的下一步深入 CI/CD尝试为一个简单项目编写.gitlab-ci.yml实现代码提交后自动运行测试、构建 Docker 镜像。这是 GitLab 的精华所在。探索容器注册表GitLab 内置了 Docker 镜像仓库学习如何将 CI/CD 构建的镜像推送到其中并用于部署。配置 Runner搭建一个专属的 GitLab Runner可以在另一台服务器上用于执行 CI/CD 任务减轻主服务器压力。API 自动化尝试写个小脚本用 API 自动创建一周的开发任务Issue或批量拉取项目统计信息。最容易踩的坑内存不足导致服务启动失败或运行卡顿务必保证足够内存。SSH 端口冲突特别是宿主机已有 SSH 服务时Docker 部署要妥善映射端口。忘记备份没有备份策略是最大的风险点一定要设置自动化备份。GitLab 的生态系统非常丰富本文仅涵盖了初阶核心内容。当你熟悉了基础操作后可以进一步探索其高级功能如 Geo 异地复制、Kubernetes 集成、安全扫描等以构建更健壮、更安全的 DevOps 流水线。建议将官方文档作为常备参考书遇到具体问题时它能提供最权威的解答。
