GitLab离线安装实战指南：内网环境部署与配置详解

1. 为什么需要离线安装GitLab在开始之前我们先明确一个核心问题为什么放着官方便捷的在线安装方式不用非要折腾离线安装这绝不是为了炫技而是企业级开发环境中一个非常现实且普遍的需求。我经历过不止一次新项目组刚组建开发环境还没完全就绪网络策略也还在审批但代码仓库必须立刻搭建起来。这时候在线安装的“yum install gitlab-ce”或者“apt-get install gitlab-ce”命令就会变成一个永远在转圈的无用符号。离线安装的核心驱动力源于内网环境的隔离性。很多金融、军工、政府或对数据安全有极高要求的互联网公司其研发和生产网络与互联网是物理隔离或逻辑强隔离的。服务器根本无法直接访问GitLab的官方仓库或Docker Hub。在这种环境下任何软件的引入都需要通过一个“摆渡”机制先在可以上网的机器通常称为“跳板机”或“中转机”上下载好所有必需的安装包和依赖然后通过U盘、内部文件服务器或特定的安全传输通道将安装介质搬运到目标内网服务器上。这个过程我们称之为“软件入网”。除了网络隔离离线安装还能带来部署的一致性和可控性。在线安装依赖于远程仓库的可用性和版本一致性如果某个依赖包的镜像站临时出现问题或者版本发生了意料之外的更新就可能导致安装失败或环境差异。而离线安装包是一个完整的、版本锁定的集合只要在测试环境验证通过就可以百分百复用到生产环境确保了从开发、测试到生产环境的高度一致这对于CI/CD流水线的稳定至关重要。因此掌握GitLab的离线安装是运维工程师和DevOps工程师的一项基本功。2. 离线安装前的全面规划与资源准备离线安装不是简单地下载一个gitlab-ce的RPM或DEB包就完事了。它更像是一个小型项目需要周密的规划和完整的物料清单BOM。盲目开始你大概率会在安装过程中被各种缺失的依赖项折磨得焦头烂额。首先你需要确定目标服务器的操作系统及其具体版本。GitLab官方对不同的Linux发行版提供了不同的安装包。最常见的是基于RPM的CentOS/RHEL/Oracle Linux和基于DEB的Ubuntu/Debian。你需要执行cat /etc/os-release或lsb_release -a来精确获取系统信息。例如是CentOS 7.9还是Ubuntu 22.04 LTS这直接决定了你该下载哪个安装包。其次规划GitLab的版本。对于生产环境我强烈建议选择长期支持LTS版本或至少是次新稳定版而不是追求最新的功能版。新版本可能引入未知的Bug而LTS版本经过了更长时间的测试社区积累的解决方案也更丰富。你可以访问GitLab的官方Release页面查看版本信息。确定版本后就要准备完整的依赖链。一个完整的GitLab离线安装包集合通常包括GitLab主程序包即gitlab-ce-version的RPM或DEB文件。操作系统基础依赖如openssh-server,postfix用于邮件通知,policycoreutilsSELinux相关等。这些可以通过系统镜像或对应的离线仓库获取。关键运行时依赖这是最容易出问题的地方。以较新版本的GitLab如14.x之后为例它依赖于特定版本的Ruby、Go、Node.js等。虽然官方Omnibus包即gitlab-ce已经将这些运行时打包在内使其成为一个相对自包含的单元但你仍然需要确保系统满足一些最基础的先决条件比如正确版本的curl和openssl用于下载和SSL通信。systemd现代Linux发行版默认都有用于服务管理。足够的磁盘空间和内存官方建议至少4GB内存但实际体验中8GB是保证流畅运行的门槛。磁盘空间需预留至少10GB用于数据和日志。我的经验是在可以联网的“中转机”上搭建一个与目标内网服务器系统版本完全一致的虚拟机或容器。然后在这台机器上尝试进行一次模拟在线安装sudo EXTERNAL_URLhttp://中转机地址 yum install gitlab-ce。安装过程中yum或apt会列出所有将要下载的依赖包。你的任务就是完整记录下这个列表。之后利用yum install --downloadonly --downloaddir./gitlab_packages或apt-get download $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances gitlab-ce | grep ^\w | sort -u)这类命令将所有依赖包包括gitlab-ce本身下载到本地目录。这个目录就是你最终需要拷贝进内网的“离线安装物料包”。注意除了安装包别忘了还有许可证文件如果你使用企业版GitLab EE和初始配置脚本。将安装步骤和后续的配置命令如修改/etc/gitlab/gitlab.rb写成Shell脚本一并放入物料包能极大减少人为操作失误。3. 分步详解CentOS/RHEL 环境离线安装实战假设我们现在的目标是在一台全新的、无法访问外网的CentOS 7.9服务器上安装GitLab 16.9.1社区版。以下是经过无数次内网部署锤炼后的标准操作流程。3.1 系统基础环境检查与配置首先以root用户登录目标服务器。第一步不是急着安装而是做好“体检”。检查系统版本和内核cat /etc/redhat-release uname -r确认是CentOS 7.9内核版本在3.10以上即可。检查关键基础服务GitLab需要SSH和邮件服务可选但建议。确保sshd服务已安装并开机自启。systemctl status sshd # 如果未安装你需要从系统安装镜像中找到 openssh-server 的RPM包进行离线安装。 # 安装命令示例rpm -ivh openssh-server-*.rpm systemctl enable sshd --now邮件服务如Postfix用于发送仓库通知、密码重置邮件等。如果内网有其他邮件网关可以在GitLab中配置SMTP此处可暂不安装Postfix。关闭并禁用防火墙与SELinux仅用于快速搭建测试环境生产环境需谨慎配置对于内网POC或测试环境为了排除网络访问问题我通常会先临时处理它们。# 关闭防火墙 systemctl stop firewalld systemctl disable firewalld # 临时关闭SELinux重启后失效 setenforce 0 # 永久关闭SELinux需修改配置文件并重启 sed -i s/SELINUXenforcing/SELINUXdisabled/g /etc/selinux/config重要提示在生产环境中绝对不建议直接禁用防火墙和SELinux。正确的做法是开放GitLab所需端口HTTP:80, HTTPS:443, SSH:22并配置SELinux布尔值或策略模块。但离线安装调试阶段先关闭它们可以快速定位问题是否出在软件本身。创建离线软件仓库将之前准备好的包含所有RPM包的物料包假设已拷贝到/opt/gitlab-offline目录创建成本地YUM源。# 安装createrepo工具如果本地包里有的话 cd /opt/gitlab-offline # 假设createrepo包也在里面 rpm -ivh createrepo-*.rpm # 创建本地仓库元数据 createrepo . # 备份原有YUM源配置并创建本地源配置 cd /etc/yum.repos.d/ mkdir bak mv *.repo bak/ cat local-gitlab.repo EOF [local-gitlab] nameLocal GitLab Repository baseurlfile:///opt/gitlab-offline enabled1 gpgcheck0 EOF # 清理YUM缓存并重建 yum clean all yum makecache现在你的服务器就可以像访问网络仓库一样安装本地目录里的所有包了。3.2 安装GitLab Omnibus包通过本地仓库安装GitLab主包。这里的关键是EXTERNAL_URL环境变量它定义了GitLab实例将来被访问的地址。sudo EXTERNAL_URLhttp://your-server-hostname-or-ip yum install -y gitlab-ce命令中的your-server-hostname-or-ip请替换为你服务器的实际IP或域名如果内网有DNS解析。例如http://192.168.1.100或http://gitlab.internal.company.com。这个URL会在安装过程中被写入GitLab的配置用于生成仓库克隆地址等。安装过程会持续几分钟它会自动配置一个自包含的环境包括Nginx、PostgreSQL、Redis、Sidekiq等所有组件。3.3 初始配置与启动安装完成后需要对GitLab进行初始配置。所有的配置都集中在/etc/gitlab/gitlab.rb这个文件中。这是一个Ruby语法格式的配置文件。首先编辑这个文件至少修改external_url以匹配你安装时设置的URL。vi /etc/gitlab/gitlab.rb找到external_url http://gitlab.example.com这一行将其修改为你的实际地址例如external_url http://192.168.1.100如果你打算使用HTTPS这里就需要配置为https://开头并同时配置SSL证书路径。对于内网测试HTTP通常足够。更重要的一个配置是存储路径。默认情况下GitLab的所有数据仓库、上传文件、备份等都存放在/var/opt/gitlab下。如果你的/var分区空间不大强烈建议在安装后首次运行前就修改这个路径避免后续数据迁移的麻烦。# 例如将数据目录指向一个更大的磁盘挂载点 git_data_dirs({ default { path /data/gitlab-data } })配置修改完成后需要让GitLab重新配置以应用更改。这是GitLab Omnibus一个非常强大的功能。sudo gitlab-ctl reconfigure这个命令会花费较长时间5-15分钟不等它会根据gitlab.rb的配置生成所有组件的实际配置文件如Nginx的虚拟主机配置并启动或重启相关服务。请耐心等待其执行完毕。3.4 验证安装与获取初始密码reconfigure命令成功运行后GitLab服务就应该已经启动了。可以通过以下命令检查服务状态sudo gitlab-ctl status你应该看到run:开头的行显示postgresql,redis,sidekiq,gitlab-workhorse,nginx等服务的状态都是ok。接下来在浏览器中输入你设置的EXTERNAL_URL如http://192.168.1.100访问GitLab。首次访问时你会被重定向到一个设置初始管理员密码的页面。但是在完全离线的环境或者页面没有自动跳转时初始密码在哪里这是新手常遇到的第一个“坑”。初始密码在安装过程中自动生成并保存在服务器的一个文件中sudo cat /etc/gitlab/initial_root_password这个文件只会在首次reconfigure后的24小时内保留之后出于安全考虑会被自动删除。请立即使用这个密码以root用户身份登录。登录后第一件事就是去修改一个强密码。4. 安装后的关键配置与优化安装成功并登录只是第一步要让这个GitLab实例真正可用、好用且安全还需要进行一系列配置。4.1 基础安全与网络配置修改管理员密码如上所述用初始密码登录后立即在用户设置中修改root用户的密码。配置SSH克隆用户通常使用SSH协议克隆代码。你需要让用户将其公钥id_rsa.pub添加到GitLab个人设置中。同时确保服务器sshd服务的22端口对内网开发机开放。配置HTTP/HTTPS如果使用HTTP确保所有用户知晓这是非加密连接。对于生产环境必须配置HTTPS。你需要将SSL证书.crt和.key文件放到服务器上如/etc/gitlab/ssl然后在gitlab.rb中配置external_url https://gitlab.yourdomain.com nginx[redirect_http_to_https] true nginx[ssl_certificate] /etc/gitlab/ssl/gitlab.yourdomain.com.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.yourdomain.com.key再次运行sudo gitlab-ctl reconfigure生效。配置防火墙如果之前关闭了重新启用防火墙并开放必要端口。systemctl start firewalld firewall-cmd --permanent --add-servicehttp firewall-cmd --permanent --add-servicehttps firewall-cmd --permanent --add-servicessh firewall-cmd --reload4.2 邮件服务配置没有邮件服务用户无法注册、无法收到合并请求通知。内网环境通常有企业自己的SMTP服务器。 在gitlab.rb中搜索gitlab_rails[smtp_enable]取消注释并配置gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.yourcompany.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabyourcompany.com gitlab_rails[smtp_password] your-password gitlab_rails[smtp_domain] yourcompany.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] true gitlab_rails[gitlab_email_from] gitlabyourcompany.com配置后执行sudo gitlab-ctl reconfigure并重启邮件相关服务sudo gitlab-ctl restart mailroom。可以通过GitLab后台的“管理区域 - 监控 - 后台任务”发送测试邮件验证。4.3 存储与备份策略仓库存储位置如前所述在gitlab.rb中通过git_data_dirs配置大容量存储路径。备份GitLab的备份命令非常简单但必须定期执行。# 手动备份备份文件默认在 /var/opt/gitlab/backups/ sudo gitlab-backup create你需要编写一个cron任务定期执行备份并将备份文件拷贝到另一台机器或存储上。记住备份命令不会备份配置文件/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json包含数据库加密密钥必须手动备份。一个完整的恢复需要备份tar包和这两个配置文件。日志管理GitLab组件众多日志也分散在/var/log/gitlab/下。可以使用logrotate进行日志轮转默认配置已包含但你可以根据磁盘空间调整策略。4.4 性能调优初探对于用户量少的小团队默认配置可能够用。但随着项目和人数的增长性能问题会凸显。Sidekiq并发数Sidekiq是处理后台任务如发送邮件、处理Webhook的组件。如果任务队列经常堆积可以适当增加其并发数。在gitlab.rb中修改sidekiq[max_concurrency]然后reconfigure。调整后需要观察服务器内存使用情况。工作进程数处理前端请求的Puma和GitLab Workhorse进程数也可以调整。但除非你非常了解其原理否则不建议轻易改动默认值。数据库连接池对于高并发场景可能需要调整PostgreSQL的连接池设置。这涉及到gitlab.rb中postgresql[max_connections]等参数调整需谨慎最好结合监控数据进行。最有效的优化往往是硬件升级给GitLab服务器增加内存到16GB或更高和使用SSD硬盘对性能的提升是立竿见影的。5. 常见故障排查与修复指南离线安装由于环境封闭出了问题排查起来更麻烦。以下是几个我踩过的经典坑和解决方案。5.1 服务启动失败端口冲突这是最常见的问题。GitLab默认使用80HTTP、443HTTPS、22SSH如果配置了内置SSH服务器、9090Prometheus等端口。如果这些端口被其他程序占用服务就会启动失败。排查sudo gitlab-ctl status # 查看哪个服务是down的 sudo journalctl -u gitlab-runsvdir -f # 查看守护进程日志 sudo netstat -tlnp | grep :80 # 检查80端口被谁占用解决停止占用端口的服务如已有的Nginx、Apache。或者修改GitLab的默认端口。在gitlab.rb中修改nginx[listen_port] 8080 # 将HTTP改为8080端口 nginx[listen_https] false # 如果不使用这个端口的HTTPS就关掉 # 同时需要修改external_url以反映端口变化 external_url http://your-server:8080修改后执行sudo gitlab-ctl reconfigure。5.2 页面访问502或无法连接服务显示是run但浏览器访问就是502。排查检查Nginxsudo gitlab-ctl tail nginx查看Nginx错误日志。常见错误是connect() to unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket failed这通常是gitlab-workhorse服务没起来。检查Workhorse和Pumasudo gitlab-ctl status gitlab-workhorse和sudo gitlab-ctl status puma。看它们是否在运行。检查资源运行free -h和df -h看是不是内存或磁盘空间不足。GitLab在启动和运行时需要较多内存如果内存不足进程可能会被系统OOM Killer杀掉。解决如果是服务没启动尝试sudo gitlab-ctl restart gitlab-workhorse或sudo gitlab-ctl restart puma。查看更详细的日志sudo gitlab-ctl tail可以跟踪所有服务的日志。如果是资源不足考虑增加服务器资源或者通过gitlab.rb调低一些服务的资源消耗治标不治本。5.3 备份与恢复失败备份失败通常是因为磁盘空间不足或权限问题。确保/var/opt/gitlab/backups目录有足够空间且git用户有写入权限。恢复失败这是更严重的问题。错误信息通常会在执行恢复命令时显示。最常见的原因是版本不匹配试图用高版本GitLab的备份文件恢复到低版本实例。备份只能恢复到与创建备份时相同版本的GitLab。缺少gitlab-secrets.json文件这个文件包含了数据库加密密钥。如果恢复时没有这个文件即使数据恢复了用户会话、CI/CD变量等加密内容也会全部丢失。务必在备份时同时备份/etc/gitlab/gitlab-secrets.json。权限问题恢复操作需要停止相关服务并以正确权限运行。标准的恢复步骤是# 停止连接数据库的进程 sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq # 确保备份文件权限正确 sudo chown git:git /var/opt/gitlab/backups/备份文件名.tar # 执行恢复BACKUP后面的部分不要带.tar后缀 sudo gitlab-backup restore BACKUP备份文件名 # 恢复配置文件如果发生了变更 sudo cp /path/to/backup/gitlab-secrets.json /etc/gitlab/ sudo cp /path/to/backup/gitlab.rb /etc/gitlab/ # 重新配置并启动 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart5.4 日常维护命令备忘掌握以下命令能让你在管理GitLab时游刃有余sudo gitlab-ctl reconfigure万能配置应用命令修改gitlab.rb后必须运行。sudo gitlab-ctl restart重启所有GitLab服务。sudo gitlab-ctl stop/start [service-name]停止/启动单个服务如puma,sidekiq,nginx。sudo gitlab-ctl status查看所有服务状态。sudo gitlab-ctl tail [service-name]查看特定服务的实时日志加-f参数可跟踪。sudo gitlab-rake gitlab:check运行一系列健康检查查看系统配置是否有问题。sudo gitlab-rake gitlab:doctor:secrets检查密钥文件状态。sudo gitlab-backup create创建备份。6. 从安装到生产后续步骤与扩展思考成功安装并完成基础配置只是一个开始。要让这个GitLab实例成为团队高效的协作平台还有很长的路要走。用户与权限管理不要所有人都用root账号。创建不同的用户并利用群组Group和项目Project来组织代码。深刻理解GitLab的权限模型Guest, Reporter, Developer, Maintainer, Owner为不同角色的成员分配合适的权限。对于企业可以考虑集成LDAP/AD进行统一认证这需要在gitlab.rb中配置ldap相关段落。CI/CD流水线搭建GitLab CI/CD是其核心魅力之一。你需要在内网环境中配置GitLab Runner。Runner同样需要离线安装你可以从同一台“中转机”下载对应版本的Runner安装包和依赖。将Runner注册到你的GitLab实例后就可以在项目根目录创建.gitlab-ci.yml文件定义自动化构建、测试、部署的流程。内网环境可能需要为Runner配置私有镜像仓库或软件源。高可用与扩展对于核心生产系统单节点部署存在单点故障风险。GitLab支持复杂的高可用HA架构包括数据库PostgreSQL集群、Redis哨兵、多个应用节点和共享存储如NFS或对象存储。但这会极大地增加部署和维护的复杂度。对于中小团队一个更务实的“高可用”策略是做好完备且频繁的备份并确保能在1-2小时内快速恢复。这比维护一个复杂的HA集群要简单可靠得多。监控与日志利用GitLab内置的Prometheus和GrafanaOmnibus包已包含监控服务器和GitLab自身的健康状态。将/var/log/gitlab下的日志接入公司的集中日志系统如ELK便于问题排查和审计。最后一个来自实践的经验文档化一切。将你的离线安装包获取步骤、安装过程、配置项、备份恢复流程、故障处理手册全部记录下来。当半年后服务器宕机或者需要在新机房部署一套新环境时这份文档的价值就会无限放大。离线安装GitLab不仅仅是一次性的技术任务更是构建稳定、可控、自主的研发基础设施的重要一环。