Ubuntu环境下GitLab离线部署与私有化代码托管实战

1. 为什么要在内网离线部署GitLab从零开始的完整思路如果你在一家对代码安全要求极高的公司或者你的开发环境压根就没法连上互联网那你肯定遇到过和我一样的烦恼想用GitLab管理代码但服务器是“与世隔绝”的。几年前我接手一个军工背景的项目所有开发机都在物理隔离的内网里当时为了搭个代码仓库真是把能踩的坑都踩了一遍。最后发现离线部署GitLab是唯一靠谱的解决方案。它不仅仅是把安装包拷进去那么简单而是一套完整的、可复现的私有化代码托管体系。简单来说离线部署就是在没有互联网连接的环境下手动准备好GitLab所需的所有“零件”然后在你的Ubuntu服务器上把它们组装并运行起来。这背后的核心价值就两个字安全和可控。你的所有代码数据、用户信息、CI/CD流水线都完全掌握在自己公司的机房内不用担心代码泄露到第三方云平台也不用受制于外网的速度和稳定性。对于金融、政务、军工、科研等敏感行业这几乎是刚需。听起来很美好但实际操作起来离线环境会给你带来一系列连锁反应。最大的挑战就是依赖地狱。在线上apt-get install一条命令能自动解决所有依赖但在离线环境你得自己当“搬运工”把主程序包、系统库、Ruby环境、PostgreSQL数据库、Redis缓存等等一个不落地全部提前下载好。任何一个环节的依赖缺失都可能导致安装失败。我记得第一次尝试时就卡在了一个不起眼的libicu库上因为服务器系统版本和下载依赖包的版本对不上折腾了大半天。所以在动手之前我们必须有一个清晰的作战计划。整个离线部署流程可以拆解为三个核心阶段战前准备在能上网的机器上搜集所有“弹药”、阵地转移安全地将“弹药”运输到内网服务器、阵地建设在内网服务器上完成安装和配置。接下来我就带你一步步走完这个全过程分享我积累下来的实战经验和那些容易翻车的细节。2. 战前准备如何一次性备齐所有离线安装“弹药”这一步是整个离线部署成功的基础核心原则是在能联网的机器上模拟一个与内网服务器尽可能一致的环境把所有需要的东西打包带走。我强烈建议你找一台和內网服务器系统版本比如都是Ubuntu 20.04 LTS一致的虚拟机或临时云主机来操作这能最大程度避免因系统差异导致的兼容性问题。2.1 获取GitLab官方离线安装包首先我们需要GitLab社区版CE的离线安装包。官方提供了针对不同Ubuntu版本的.deb包。这里有个关键点不要只下载一个主包。以Ubuntu 20.04 (Focal)为例你可以访问GitLab的官方软件仓库页面。但更稳妥的方式是使用apt工具配合--download-only参数它能帮你把包及其依赖都拉到本地。# 在联网的Ubuntu机器上操作 # 1. 信任GitLab的GPG密钥确保下载的包是官方的、未被篡改的 curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash # 2. 更新本地软件包列表 sudo apt-get update # 3. 仅下载gitlab-ce软件包及其所有依赖但不安装 # 这会把所有.deb文件下载到 /var/cache/apt/archives/ 目录 sudo apt-get install --download-only gitlab-ce执行完上述命令后所有相关的.deb文件都躺在/var/cache/apt/archives/目录下了。你可以用ls -la命令查看会发现除了gitlab-ce_xxx.deb还有很多其他以lib、ruby、postgresql开头的包这些都是GitLab运行所必需的依赖。把它们全部拷贝出来放到一个单独的文件夹比如~/gitlab-offline-packages/。2.2 处理系统依赖与潜在陷阱你以为下载完apt列出的包就万事大吉了太天真了。在实际安装过程中GitLab的Omnibus包一个全功能一体包内部还会调用其自带的组件这些组件可能对系统库有特定版本要求。我遇到过最常见的问题是证书错误和老旧库缺失。证书问题GitLab的reconfigure过程会尝试从外部下载一些资源或验证证书。在内网这必然失败。解决方法是在配置文件中提前禁用这些检查。我们可以在联网机上也编辑一下配置文件模板或者记下这个关键配置项待会用到。库版本问题比如GitLab 15.x之后对OpenSSL的版本有更高要求。如果你的内网服务器是Ubuntu 18.04其自带的OpenSSL可能版本过低。这就需要你提前下载高版本的OpenSSL库及其依赖手动安装。一个实用的技巧是在联网机上使用apt-cache depends gitlab-ce和apt-cache rdepends命令递归地查看更深层次的依赖关系尽可能多地下载相关包。为了管理这些杂乱的包我习惯创建一个目录结构清晰的“离线资源库”gitlab-offline-bundle/ ├── debs/ # 存放所有下载的.deb包 ├── config-templates/ # 存放修改好的配置文件模板如gitlab.rb └── scripts/ # 存放自己写的安装后配置脚本把所有.deb包复制到debs/目录后你可以使用dpkg-scanpackages工具生成一个本地的Packages.gz索引文件这样在内网服务器上就可以通过file://协议源来安装了比手动dpkg -i一个个装要方便和可靠得多。# 在打包目录的上一级执行 cd /path/to/gitlab-offline-bundle dpkg-scanpackages debs /dev/null | gzip debs/Packages.gz生成后debs目录就变成了一个完整的本地APT仓库。把这个gitlab-offline-bundle文件夹完整地压缩打包准备带入内网。3. 阵地转移与安装在内网服务器上构建私有仓库现在我们通过U盘、内部文件服务器或任何被允许的介质将准备好的gitlab-offline-bundle.tar.gz压缩包拷贝到内网的Ubuntu服务器上。假设我们放在/opt/目录下。3.1 搭建本地软件源并安装在内网服务器上我们首先解压资源包并将本地DEB目录配置为APT源这样就能用熟悉的apt命令来安装了它会自动处理包之间的依赖关系。# 1. 解压资源包 sudo tar -xzf gitlab-offline-bundle.tar.gz -C /opt/ # 2. 将本地目录添加为APT软件源 echo deb [trustedyes] file:///opt/gitlab-offline-bundle/debs ./ | sudo tee /etc/apt/sources.list.d/gitlab-offline.list # 3. 更新APT源列表现在源指向本地文件 sudo apt-get update # 4. 安装GitLab sudo apt-get install gitlab-ce看到apt开始从本地文件解析依赖并安装心里就踏实了一大半。安装过程可能会持续几分钟最后你会看到那个经典的ASCII艺术字和提示信息告诉你需要配置external_url。这和在线安装的体验几乎一致。3.2 关键配置让GitLab认识你的内网环境安装完成只是第一步让GitLab适配你的内网环境才是重头戏。核心配置文件是/etc/gitlab/gitlab.rb。用sudo vim或你喜欢的编辑器打开它。首先找到并修改external_url。这里不能再用gitlab.example.com这种域名了因为内网没有DNS解析。你有两种选择使用IP地址和端口external_url http://192.168.1.100:8080。这是最简单直接的方式所有内网用户通过这个IP和端口访问。使用内网域名如果你们内网有自建的DNS服务器比如corp.local可以配置为external_url http://gitlab.corp.local。然后在DNS服务器上将该域名指向GitLab服务器的IP。这种方式更规范便于记忆和管理。接下来是几个在离线环境下必须调整的配置能避免后续很多奇葩错误# 禁用与外部服务的连接检查防止reconfigure时卡住或报错 gitlab_rails[gitlab_shell_ssh_port] 22 gitlab_rails[smtp_enable] false gitlab_rails[gitlab_email_enabled] false # 如果服务器内存小于4GB务必调整Unicorn和Sidekiq的工作进程数避免内存耗尽 unicorn[worker_processes] 2 sidekiq[concurrency] 5 # 非常重要明确指定PostgreSQL和Redis使用内嵌的版本并监听本地 postgresql[listen_address] localhost redis[bind] 127.0.0.1配置完成后执行那个神圣而又漫长的命令sudo gitlab-ctl reconfigure。这个过程会基于你的配置文件初始化所有服务数据库、Redis、Nginx等。在内网服务器上由于没有网络干扰速度可能比想象中快但请耐心等待它跑完直到看到Chef Infra Client finished, X/XXXX resources updated和gitlab Reconfigured!的成功提示。4. 初始化、优化与日常维护指南reconfigure成功后打开浏览器访问你配置的external_url比如http://192.168.1.100:8080。第一次访问会强制你为root账户设置一个高强度密码。这个密码务必记好它是你GitLab实例的超级管理员钥匙。4.1 基础安全与项目初始化登录后第一件事我建议你立刻进入“管理员区域”做以下几件事关闭公开注册在“设置” - “通用” - “账号和限制”中取消“允许新用户注册”。私有化部署通常用于团队内部手动添加成员更安全。配置邮箱通知可选如果内网有邮件服务器可以配置SMTP让GitLab能发送重置密码、合并请求等通知。如果没条件就像我之前配置的那样直接禁用相关功能。创建第一个项目点击页面上的“新建项目”创建一个空白项目或导入已有代码。这里你可以体验一下内网Git的速度那感觉就像从乡间小路换到了专用光纤提交、拉取代码都是瞬间完成再也不受外网波动的影响。4.2 性能调优与备份策略默认配置是为通用场景设计的针对你的服务器硬件可以做些微调来提升体验。除了之前提到的调整工作进程数还有两个地方可以优化仓库存储路径默认在/var/opt/gitlab/git-data。如果你的/var分区空间不大但挂载了一个大容量的数据盘比如/data可以在gitlab.rb中修改git_data_dirs将仓库指向更大的磁盘空间。备份这是生命线GitLab提供了简单的命令行工具进行全量备份。我习惯每周日凌晨3点通过cronjob自动执行# 编辑crontab: sudo crontab -e # 添加以下行备份文件会保存在 /var/opt/gitlab/backups/ 0 3 * * 0 /opt/gitlab/bin/gitlab-backup create CRON1记得定期把备份文件拷贝到另一台机器或磁带库实现异地容灾。4.3 故障排查我踩过的那些坑即使准备再充分内网环境也可能出现意外。分享几个我遇到过的典型问题及解法访问页面出现502 Whoops错误这通常是UnicornGitLab的Web应用服务器没启动或崩溃了。首先运行sudo gitlab-ctl status查看哪些服务是down状态。最常见的是内存不足导致Unicorn被杀。可以尝试sudo gitlab-ctl restart unicorn并检查/var/log/gitlab/unicorn/current日志文件。根本解决方法是增加服务器内存或者如前所述调低unicorn[worker_processes]。git clone或git push速度极慢检查SSH配置。GitLab默认使用22端口进行SSH克隆。确保内网防火墙没有屏蔽该端口并且服务器的sshd服务正常运行sudo systemctl status ssh。也可以考虑在gitlab.rb中修改gitlab_rails[gitlab_shell_ssh_port]为一个非标端口并在防火墙上放行。sudo gitlab-ctl reconfigure卡住不动这经常发生在配置了外部邮件服务器但网络不通的情况下。检查你的gitlab.rb中是否有类似smtp_的配置项如果内网无邮件服务器请确保它们被注释或设置为false。可以尝试中断命令注释掉相关配置后再次运行。离线部署GitLab确实比一键在线安装繁琐得多但当你和团队在一个安全、高速、完全自主的内网环境中流畅地进行代码协作、代码评审和CI/CD集成时你会觉得所有前期投入都是值得的。这套环境一旦搭建稳定几乎可以“一劳永逸”地运行下去成为团队研发效率的核心基石。最后再啰嗦一句一定要做好定期备份和更新规划虽然离线更新又是另一个话题了数据无价。