1. 项目概述为什么需要离线安装GitLab在企业的IT基础设施建设和运维过程中我们经常会遇到一个看似简单却至关重要的场景生产环境或内网开发环境无法直接访问互联网。无论是出于安全合规的硬性要求还是网络架构的客观限制许多核心服务器都运行在“离线”或“隔离”的网络中。这时如果你需要部署一套像GitLab这样功能强大的代码托管与DevOps平台直接从官方仓库在线安装的路径就被堵死了。“gitlab-ce离线安装”这个需求正是为了解决这个核心痛点。它不是一个简单的“下载-安装”动作而是一套完整的、可重复的、适用于隔离环境的部署方案。我经历过多次在内网机房、客户保密环境下的GitLab部署深知其中每一步的细节和可能遇到的“坑”。在线安装可能只需要几条apt-get或yum命令但离线安装则要求你提前规划好所有依赖准备好完整的安装包并清晰地知道安装脚本在离线状态下会如何运行。对于系统管理员、DevOps工程师或IT架构师而言掌握GitLab的离线安装能力意味着你能将这套优秀的工具链部署到任何需要的环境中不受外部网络波动或策略的影响保障研发流程的自主与可控。接下来我将以一个资深实施者的视角为你拆解从零开始完成GitLab-CE离线部署的全过程并分享那些官方文档可能不会明说的实操细节。2. 整体部署思路与前期规划离线安装绝非把在线安装的步骤简单照搬。它更像一次精密的“物资空投”行动你需要把在线环境里“唾手可得”的所有资源提前打包、校验然后一次性投送到目标服务器。一个清晰的规划是成功的一半。2.1 环境分析与资源准备清单首先你需要明确两个关键环境互联网环境打包机一台可以畅通访问外网的服务器或虚拟机操作系统最好与目标机一致。它的唯一任务就是下载所有必需的安装包和依赖。离线环境目标机最终要运行GitLab的生产服务器。它完全无法连接互联网。在动手之前请务必确认目标机的以下信息这直接决定了你需要下载哪些包操作系统及版本例如CentOS 7.9、Ubuntu 20.04 LTS。不同发行版的包格式rpm vs deb和依赖库截然不同。系统架构通常是x86_64amd64也可能是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等所有组件打包在一起极大简化了部署和配置。离线安装的核心就是让这个“全能包”在缺少外部仓库的情况下也能顺利解压和配置。方案上主要有两种路径全依赖包下载在打包机上通过系统包管理器yum或apt的downloadonly或--downloaddir功能将GitLab安装包及其所有依赖下载到本地目录。然后将整个目录拷贝到目标机建立本地仓库进行安装。离线仓库镜像在打包机上搭建一个与目标机系统对应的本地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/keepcache0/keepcache1/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/nullyum 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 基础必要配置配置存储位置默认情况下GitLab的所有数据仓库、上传文件、数据库等都放在/var/opt/gitlab目录。如果该分区空间不足你需要将数据目录迁移到更大的存储上。git_data_dirs({ default { path /data/gitlab-data # 修改为你的大容量数据盘挂载路径 } })修改后需要再次运行sudo gitlab-ctl reconfigure。重要务必在GitLab刚安装、尚未正式使用前进行此操作。如果已有数据需要先停机手动迁移数据这是一个高风险操作。备份配置离线环境的数据备份尤为重要。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在内存小的机器上可以调低如10Puma工作进程数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 常见问题与解决方案速查表以下是我在多次离线部署中遇到的典型问题及解决方法问题现象可能原因排查与解决步骤sudo gitlab-ctl reconfigure执行失败报错关于某个服务启动失败。1. 端口被占用。2. 依赖的服务如Redis配置文件错误。3. 磁盘空间不足。1. 检查端口sudo netstat -tlnp | grep :端口号。2. 查看详细日志sudo gitlab-ctl tail 服务名如sudo gitlab-ctl tail postgresql。3. 检查磁盘df -h。浏览器访问GitLab出现502 Whoops, GitLab is taking too much time to respond.1. Puma或Sidekiq服务没有正常启动。2. 服务器内存不足导致进程被系统杀死OOM。1. 检查服务状态sudo gitlab-ctl status重点看puma和sidekiq。2. 查看系统日志sudo journalctl -xe或dmesg | tail -20看是否有Out of memory的Kill记录。3. 尝试重启sudo gitlab-ctl restart。用户无法通过SSH协议推送代码git clone ssh://...。1. SSH服务未运行或配置错误。2. 服务器防火墙未开放22端口。3. GitLab内置的gitlab-shell组件故障。1. 检查SSH服务sudo gitlab-ctl status gitlab-shell。2. 检查防火墙sudo firewall-cmd --list-allCentOS 7。3. 检查/var/log/gitlab/gitlab-shell/下的日志。后台任务堆积邮件发不出去。1. Sidekiq进程卡死或停止。2. 邮件服务器如Postfix配置错误在离线内网中很常见。1. 重启Sidekiqsudo gitlab-ctl restart sidekiq。2. 对于内网环境可以考虑禁用邮件发送或配置一个中继服务器。在gitlab.rb中设置gitlab_rails[smtp_enable] false。备份命令sudo gitlab-backup create执行失败。1. 备份目录权限不正确。2. 磁盘空间不足。3. PostgreSQL数据库连接问题。1. 确保备份目录存在且GitLab用户可写sudo chown git:git /var/opt/gitlab/backups。2. 检查空间df -h。3. 查看备份日志sudo tail -f /var/log/gitlab/gitlab-rails/backup.log。5.2 离线升级策略当需要升级GitLab版本时例如从16.9.1升级到16.10.1你的操作流程如下在打包机按照“阶段一”的步骤下载新版本的GitLab-CE安装包及其所有依赖。关键点必须使用与新版本对应的仓库信息。有时新版本会引入新的系统依赖。在目标机 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只查看NginxWeb服务器的访问日志和错误日志。sudo gitlab-ctl tail postgresql只查看数据库日志。sudo gitlab-ctl tail gitlab-rails查看主应用日志这里包含了用户操作、API调用、错误回溯等最丰富的信息。当遇到任何问题时第一个动作就应该是打开相关的日志文件从错误信息中寻找线索。例如一个常见的Rails应用错误会在这里显示完整的Ruby堆栈跟踪明确指出是哪一行代码或哪个依赖出了问题。6. 安全加固与内网集成考量将GitLab部署在内网并不意味着可以忽视安全。相反由于它是代码和知识产权的核心仓库安全加固尤为重要。防火墙策略即使在内网也应配置防火墙仅开放必要的端口如80/443用于HTTP/HTTPS22用于SSH可选开放9090用于Prometheus监控。关闭所有其他不必要的端口。# CentOS 7 使用firewalld示例 sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --permanent --add-servicessh sudo firewall-cmd --reload定期更新与漏洞修复离线环境最大的安全风险是无法及时获取安全更新。你需要建立一套流程定期如每季度在打包机检查GitLab的安全公告下载最新的安全版本离线包并在维护窗口期内对生产环境进行升级。忽略安全更新等同于将系统暴露在已知风险之下。与内网账户系统集成LDAP/AD对于企业内网让员工使用统一的公司账号登录GitLab是提升体验和安全性的好办法。GitLab支持与LDAP或Active Directory集成。配置在gitlab.rb的gitlab_rails[ldap_servers]部分。虽然配置稍复杂但一旦完成用户管理和认证就变得非常简便和安全。在离线环境下配置时请确保GitLab服务器能解析到内网的域控制器地址。备份加密与离线存储/var/opt/gitlab/backups目录下的备份文件包含了所有代码、数据库和附件。务必确保该目录的权限严格如700并考虑对备份文件进行加密然后再传输到其他离线存储介质如磁带库或加密硬盘。你可以编写一个备份后自动加密的脚本集成到cron任务中。完成一次GitLab的离线安装就像完成了一次精密的系统工程。它考验的不仅是对GitLab本身的理解更是对Linux系统、网络、软件依赖管理和故障排查的综合能力。每一次成功的部署都为团队构建了一道自主可控的研发基石。记住在离线世界里充分的准备、清晰的文档和严谨的流程是你最可靠的伙伴。