1. 项目概述：为什么需要离线安装GitLab？

在企业的IT基础设施建设和运维过程中，我们经常会遇到一个看似简单却至关重要的场景：生产环境或内网开发环境无法直接访问互联网。无论是出于安全合规的硬性要求，还是网络架构的客观限制，许多核心服务器都运行在“离线”或“隔离”的网络中。这时，如果你需要部署一套像GitLab这样功能强大的代码托管与DevOps平台，直接从官方仓库在线安装的路径就被堵死了。

“gitlab-ce离线安装”这个需求，正是为了解决这个核心痛点。它不是一个简单的“下载-安装”动作，而是一套完整的、可重复的、适用于隔离环境的部署方案。我经历过多次在内网机房、客户保密环境下的GitLab部署，深知其中每一步的细节和可能遇到的“坑”。在线安装可能只需要几条apt-get或yum命令，但离线安装则要求你提前规划好所有依赖，准备好完整的安装包，并清晰地知道安装脚本在离线状态下会如何运行。

对于系统管理员、DevOps工程师或IT架构师而言，掌握GitLab的离线安装能力，意味着你能将这套优秀的工具链部署到任何需要的环境中，不受外部网络波动或策略的影响，保障研发流程的自主与可控。接下来，我将以一个资深实施者的视角，为你拆解从零开始完成GitLab-CE离线部署的全过程，并分享那些官方文档可能不会明说的实操细节。

2. 整体部署思路与前期规划

离线安装绝非把在线安装的步骤简单照搬。它更像一次精密的“物资空投”行动，你需要把在线环境里“唾手可得”的所有资源，提前打包、校验，然后一次性投送到目标服务器。一个清晰的规划是成功的一半。

2.1 环境分析与资源准备清单

首先，你需要明确两个关键环境：

1. 互联网环境（打包机）：一台可以畅通访问外网的服务器或虚拟机，操作系统最好与目标机一致。它的唯一任务就是下载所有必需的安装包和依赖。
2. 离线环境（目标机）：最终要运行GitLab的生产服务器。它完全无法连接互联网。

在动手之前，请务必确认目标机的以下信息，这直接决定了你需要下载哪些包：

• 操作系统及版本：例如，CentOS 7.9、Ubuntu 20.04 LTS。不同发行版的包格式（rpm vs deb）和依赖库截然不同。
• 系统架构：通常是x86_64（amd64），也可能是ARM架构。
• GitLab版本：确定你需要安装的具体版本号，如16.9.1-ce.0。建议选择次新版而非最新版，以规避潜在的新版本Bug。

基于以上信息，你的资源准备清单应包括：

• GitLab-CE安装包本体：对应操作系统和版本的rpm或deb包。
• 依赖包：GitLab运行所必需的底层软件，如openssh-server、postfix（用于邮件通知）、policycoreutils等。
• 运行时环境：GitLab本身基于Ruby on Rails，但它通过Omnibus包已经包含了所需的Ruby、Go、Node.js等环境。不过，一些系统级的共享库（如libicu、libpq）仍可能需要单独准备。

2.2 离线安装的核心逻辑与方案选型

Omnibus安装包是GitLab官方推荐的安装方式，它将GitLab服务、Web服务器（Nginx）、数据库（PostgreSQL）、缓存（Redis）等所有组件打包在一起，极大简化了部署和配置。离线安装的核心，就是让这个“全能包”在缺少外部仓库的情况下也能顺利解压和配置。

方案上主要有两种路径：

1. 全依赖包下载：在打包机上，通过系统包管理器（yum或apt）的downloadonly或--downloaddir功能，将GitLab安装包及其所有依赖下载到本地目录。然后将整个目录拷贝到目标机，建立本地仓库进行安装。
2. 离线仓库镜像：在打包机上搭建一个与目标机系统对应的本地YUM或APT仓库，将GitLab及其依赖包全部放入仓库并创建索引。然后将整个仓库目录拷贝至目标机，在目标机上将本地仓库配置为源。

第一种方法更直接，适合一次性部署；第二种方法更规范，适合需要在内网多次、多台机器部署的场景。本文将重点讲解第一种更通用的“全依赖包下载”方法，因为它理解起来更直观，且所需的前置知识更少。

注意：无论哪种方法，都必须保证打包机与目标机的操作系统大版本（如CentOS 7）和架构完全一致。在RedHat系（如CentOS）和Debian系（如Ubuntu）之间混用安装包是绝对行不通的。

3. 实操详解：从下载到安装的完整流程

让我们以一台CentOS 7.9 x86_64系统的目标机，安装GitLab-CE 16.9.1版本为例，展开全流程操作。请将以下步骤中的版本号替换为你实际需要的版本。

3.1 阶段一：在互联网环境（打包机）准备离线包

假设你的打包机也是一台CentOS 7.9。

步骤1：安装必要工具并创建工作目录

# 确保系统已安装用于下载的工具 sudo yum install -y yum-utils wget createrepo # 创建一个清晰的工作目录 mkdir -p ~/gitlab-offline-packages cd ~/gitlab-offline-packages

步骤2：下载GitLab-CE官方安装包前往 GitLab官方仓库 查找确切的下载链接，或者使用wget直接下载。你可以通过官方提供的Repo来帮助定位。

# 首先，添加GitLab官方仓库（仅用于获取下载链接和依赖解析，打包机需要） curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash # 然后，使用yum的downloadonly插件只下载不安装 sudo yum install --downloadonly --downloaddir=./ gitlab-ce-16.9.1-ce.0.el7

执行上述命令后，gitlab-ce-16.9.1-ce.0.el7.x86_64.rpm这个主安装包就会出现在当前目录。--downloadonly是yum-plugin-downloadonly插件提供的功能，如果系统没有，请先安装该插件。

步骤3：下载所有系统依赖包这是最关键也最容易出错的一步。GitLab的Omnibus包声明了它对其他系统包的依赖（如openssh-server,policycoreutils,libicu等）。我们需要把这些依赖也一并下载下来。

# 使用repoquery工具（来自yum-utils）查询gitlab-ce的所有依赖 repoquery --requires --resolve gitlab-ce-16.9.1-ce.0.el7.x86_64.rpm | xargs sudo yum install --downloadonly --downloaddir=./

这条命令做了两件事：1. 解析rpm包的依赖列表；2. 将这些依赖包下载到当前目录。但是，请注意，这种方法可能无法下载到某些深层或间接的依赖。

一个更可靠但稍显“笨拙”的方法是，在打包机上实际安装一次GitLab，但在安装前启用yum的缓存，并保留所有rpm包。

# 1. 修改yum配置，启用缓存并保留所有包 sudo sed -i 's/keepcache=0/keepcache=1/g' /etc/yum.conf # 2. 在打包机上执行一次安装（安装后可以卸载） sudo yum install -y gitlab-ce-16.9.1-ce.0.el7 # 3. 安装完成后，所有下载的rpm包都保存在/var/cache/yum目录下。将其复制到我们的工作目录 find /var/cache/yum -name "*.rpm" -exec cp {} ~/gitlab-offline-packages/ \; # 4. （可选）在打包机上卸载GitLab，保持环境干净 sudo yum remove -y gitlab-ce

这种方法能确保下载到最完整的依赖树，因为yum在解决依赖关系时是最权威的。

步骤4：整理与传输现在，~/gitlab-offline-packages目录下应该包含了GitLab主包和数十个甚至上百个依赖包。使用ls -lh *.rpm | wc -l可以查看数量。

# 打包整个目录，准备传输 tar -czf gitlab-offline-el7-16.9.1.tar.gz ./*.rpm

接下来，通过U盘、内部文件服务器、或安全的离线传输方式（如物理隔离网络下的SCP），将gitlab-offline-el7-16.9.1.tar.gz这个压缩包拷贝到目标离线服务器。

3.2 阶段二：在离线环境（目标机）执行安装

步骤1：上传并解压离线包假设你将压缩包上传到了目标机的/tmp目录。

# 创建安装目录 sudo mkdir -p /opt/gitlab-offline-packages sudo tar -xzf /tmp/gitlab-offline-el7-16.9.1.tar.gz -C /opt/gitlab-offline-packages cd /opt/gitlab-offline-packages

步骤2：手动安装所有依赖包在离线环境下，我们需要使用rpm命令手动安装所有依赖包，并且要处理包之间的安装顺序。rpm不会自动解决依赖，所以我们需要一个技巧：使用rpm的测试模式(--test)来找出安装顺序，或者更简单，直接使用yum localinstall。

# 方法A：使用yum localinstall，它会自动处理本地rpm文件的依赖关系（推荐） sudo yum localinstall -y ./*.rpm # 注意：即使离线，yum localinstall也会尝试连接网络仓库，可能会报错或等待超时。我们需要先禁用所有网络仓库。

更稳妥的做法是，临时禁用所有远程repo，让yum只从本地文件安装。

# 1. 备份现有的repo文件 sudo mkdir -p /etc/yum.repos.d/backup sudo mv /etc/yum.repos.d/*.repo /etc/yum.repos.d/backup/ 2>/dev/null # 2. 执行本地安装 sudo yum localinstall -y /opt/gitlab-offline-packages/*.rpm # 3. 安装完成后，恢复repo文件 sudo mv /etc/yum.repos.d/backup/*.repo /etc/yum.repos.d/ 2>/dev/null

yum localinstall会分析当前目录下所有rpm包的元数据，并计算出正确的安装顺序，一次性安装所有包，包括GitLab主包。

步骤3：初始配置与启动安装完成后，GitLab的配置文件位于/etc/gitlab/gitlab.rb。在首次启动前，强烈建议你先修改一个关键配置：外部访问URL。

# 使用vim或其他编辑器编辑配置文件 sudo vim /etc/gitlab/gitlab.rb

找到external_url这一行，将其值修改为你打算访问GitLab的地址。例如，如果服务器IP是192.168.1.100，你可以设置为：

external_url 'http://192.168.1.100'

如果将来要配置域名和HTTPS，也可以在这里设置，例如external_url 'https://gitlab.yourcompany.com'。离线环境下通常先使用HTTP，证书问题后续再解决。

保存退出后，执行重配置命令，这是GitLab Omnibus安装中最重要的一步，它会根据配置文件生成所有组件的实际配置并启动服务。

# 执行重配置，这个过程会比较长（5-15分钟），请耐心等待 sudo gitlab-ctl reconfigure

当命令执行完毕，出现“gitlab Reconfigured!”的提示时，说明安装和初始配置已成功。

步骤4：验证安装通过以下命令检查GitLab各核心服务的状态：

sudo gitlab-ctl status

你应该能看到run: postgresql:,run: redis:,run: nginx:等服务均为ok状态。 打开浏览器，访问你配置的external_url（如http://192.168.1.100）。首次访问会强制你为root用户设置密码。设置完成后，即可用root和刚设置的密码登录，开始使用你的私有GitLab了！

4. 核心配置解析与优化要点

安装成功只是第一步，让GitLab稳定、高效、安全地运行在内网环境中，还需要进行一些关键配置。/etc/gitlab/gitlab.rb这个文件是这一切的核心，它使用Ruby语法，所有配置都通过取消注释和修改变量值来完成。

4.1 基础必要配置

1. 配置存储位置：默认情况下，GitLab的所有数据（仓库、上传文件、数据库等）都放在/var/opt/gitlab目录。如果该分区空间不足，你需要将数据目录迁移到更大的存储上。

   git_data_dirs({ "default" => { "path" => "/data/gitlab-data" # 修改为你的大容量数据盘挂载路径 } })

   修改后需要再次运行sudo gitlab-ctl reconfigure。重要：务必在GitLab刚安装、尚未正式使用前进行此操作。如果已有数据，需要先停机，手动迁移数据，这是一个高风险操作。

2. 备份配置：离线环境的数据备份尤为重要。GitLab提供了简单的备份命令，但需要配置备份存储位置和保留策略。

   # 设置备份路径 gitlab_rails['backup_path'] = "/var/opt/gitlab/backups" # 设置备份保留时长（秒），例如保留7天 gitlab_rails['backup_keep_time'] = 604800

   执行备份的命令是sudo gitlab-backup create。请务必制定计划任务（cron job）定期执行备份，并将备份文件拷贝到其他物理设备上。

4.2 性能与资源调优

GitLab Omnibus默认的资源分配可能不适合你的服务器硬件。对于小型团队（少于100人），2核4G的服务器可能勉强够用，但会明显感觉慢。以下是一些关键参数：

• Sidekiq进程数：Sidekiq是GitLab的后台作业处理器，负责发送邮件、处理CI/CD管道等。内存充足的情况下，增加其进程数可以提升后台任务处理能力。

  sidekiq['max_concurrency'] = 10 # 默认是25，在内存小的机器上可以调低，如10

• Puma工作进程数：Puma是GitLab的Web应用服务器。增加工作进程可以处理更多并发Web请求，但也会消耗更多内存。

  puma['worker_processes'] = 2 # 默认是CPU核心数，在内存有限的机器上，可以设置为2或3

• 数据库连接数：PostgreSQL的最大连接数需要根据Puma和Sidekiq的进程数进行调整，避免连接不足。

  postgresql['max_connections'] = 200 # 默认是200，通常够用。如果调整了Puma和Sidekiq，确保此值大于 (puma workers * puma threads) + sidekiq concurrency

  修改任何性能参数后，都需要执行sudo gitlab-ctl reconfigure和sudo gitlab-ctl restart使之生效。

实操心得：在离线环境，尤其是资源受限的服务器上，“先监控，后调优”是黄金法则。不要一上来就盲目修改参数。安装后先让系统运行几天，使用sudo gitlab-ctl tail查看日志，用top或htop命令观察内存和CPU使用情况。如果发现内存持续吃紧（Swap被频繁使用），再回头来调低上述的进程和并发数。对于内网小团队使用，稳定性远比极致性能重要。

5. 离线安装后的维护与问题排查

离线环境下的维护挑战在于，你无法使用yum update这样的命令一键升级。所有更新都需要重复“下载-传输-安装”的离线流程。同时，问题排查也因缺少即时网络搜索而更依赖本地经验和日志。

5.1 常见问题与解决方案速查表

以下是我在多次离线部署中遇到的典型问题及解决方法：

5.2 离线升级策略

当需要升级GitLab版本时（例如从16.9.1升级到16.10.1），你的操作流程如下：

1. 在打包机：按照“阶段一”的步骤，下载新版本的GitLab-CE安装包及其所有依赖。关键点：必须使用与新版本对应的仓库信息。有时新版本会引入新的系统依赖。
2. 在目标机： a.务必先进行完整备份：sudo gitlab-backup create。 b. 停止服务（可选但推荐）：sudo gitlab-ctl stop。 c. 将新版本的离线包传输到目标机，并像初次安装一样，使用sudo yum localinstall进行安装。Yum会识别出这是更新，自动进行升级。 d. 升级完成后，执行sudo gitlab-ctl reconfigure和sudo gitlab-ctl restart。

重要警告：GitLab的版本升级有严格的路径限制，通常只支持从一个次要版本升级到下一个次要版本（如16.9 -> 16.10），或者跨一个主要版本（如15.x -> 16.x）但需要遵循官方升级指南。绝对不要跳过多个主要版本直接升级（如14.x -> 16.x）。在离线环境中，回退极其困难，因此升级前必须确认版本路径，并在测试环境先行验证。

5.3 日志：你的第一道故障排查防线

在离线环境，日志就是你的“眼睛”。GitLab Omnibus将所有组件的日志集中管理，位于/var/log/gitlab/目录下。掌握几个最常用的日志查看命令，能快速定位问题根源：

• sudo gitlab-ctl tail：实时滚动查看所有核心服务的日志（综合视图）。
• sudo gitlab-ctl tail nginx：只查看Nginx（Web服务器）的访问日志和错误日志。
• sudo gitlab-ctl tail postgresql：只查看数据库日志。
• sudo gitlab-ctl tail gitlab-rails：查看主应用日志，这里包含了用户操作、API调用、错误回溯等最丰富的信息。

当遇到任何问题时，第一个动作就应该是打开相关的日志文件，从错误信息中寻找线索。例如，一个常见的Rails应用错误会在这里显示完整的Ruby堆栈跟踪，明确指出是哪一行代码或哪个依赖出了问题。

6. 安全加固与内网集成考量

将GitLab部署在内网，并不意味着可以忽视安全。相反，由于它是代码和知识产权的核心仓库，安全加固尤为重要。

1. 防火墙策略：即使在内网，也应配置防火墙，仅开放必要的端口（如80/443用于HTTP/HTTPS，22用于SSH，可选开放9090用于Prometheus监控）。关闭所有其他不必要的端口。

   # CentOS 7 使用firewalld示例 sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --permanent --add-service=https sudo firewall-cmd --permanent --add-service=ssh sudo firewall-cmd --reload

2. 定期更新与漏洞修复：离线环境最大的安全风险是无法及时获取安全更新。你需要建立一套流程：定期（如每季度）在打包机检查GitLab的安全公告，下载最新的安全版本离线包，并在维护窗口期内对生产环境进行升级。忽略安全更新等同于将系统暴露在已知风险之下。

3. 与内网账户系统集成（LDAP/AD）：对于企业内网，让员工使用统一的公司账号登录GitLab是提升体验和安全性的好办法。GitLab支持与LDAP或Active Directory集成。配置在gitlab.rb的gitlab_rails['ldap_servers']部分。虽然配置稍复杂，但一旦完成，用户管理和认证就变得非常简便和安全。在离线环境下配置时，请确保GitLab服务器能解析到内网的域控制器地址。

4. 备份加密与离线存储：/var/opt/gitlab/backups目录下的备份文件包含了所有代码、数据库和附件。务必确保该目录的权限严格（如700），并考虑对备份文件进行加密，然后再传输到其他离线存储介质（如磁带库或加密硬盘）。你可以编写一个备份后自动加密的脚本，集成到cron任务中。

完成一次GitLab的离线安装，就像完成了一次精密的系统工程。它考验的不仅是对GitLab本身的理解，更是对Linux系统、网络、软件依赖管理和故障排查的综合能力。每一次成功的部署，都为团队构建了一道自主可控的研发基石。记住，在离线世界里，充分的准备、清晰的文档和严谨的流程，是你最可靠的伙伴。