1. 为什么要在内网离线部署GitLab很多朋友一听到要自己搭GitLab第一反应可能是“直接用GitHub或者Gitee不香吗”。确实对于个人或者可以连接公网的小团队来说直接用云服务是最省心的。但如果你所在的公司尤其是金融、军工、政府或者一些对代码安全有极高要求的研发部门开发环境是完全隔离在内部局域网里的根本连不上外网那情况就完全不同了。这时候一个部署在内网的、完全自主掌控的代码仓库平台就成了刚需。GitLab作为一款集代码托管、CI/CD、项目管理于一体的DevOps平台功能非常强大社区版CE也足够大多数团队使用。离线部署说白了就是把GitLab这个“大房子”整个搬进你的内网机房让它在不接触互联网的情况下也能为你的团队提供全套服务。我经历过从用SVN管理文档、用轻量级Git服务再到被迫全面转向GitLab的整个过程。最初也觉得GitLab太重尝试过GitBlit这类轻量方案但后来因为安全漏洞和功能限制最终还是回到了GitLab。尤其是在Windows服务器为主的环境里这个迁移过程踩了不少坑比如Docker在Windows上的各种水土不服最终选择了用虚拟机装Linux再部署GitLab这条“曲线救国”的路。这套方法虽然步骤多了点但非常稳定适合大多数对Linux不熟、但服务器又是Windows的运维或开发同学。接下来我就把这套从零开始、手把手的离线部署实战经验分享给你帮你避开我当年踩过的那些“坑”。2. 部署前的核心准备选对版本和找对包离线部署的第一步也是最关键的一步不是急着敲命令而是做好“粮草”准备。如果软件包没选对后面所有操作都可能白费。2.1 版本选择要稳定不要追新很多技术人有个习惯喜欢用最新版本。但在离线部署的生产环境里稳定压倒一切。新版本可能引入未知的Bug而你的内网环境无法快速在线更新或打补丁。我的建议是选择比当前最新版落后1-2个的稳定版本。比如你可以先去GitLab官网的Release页面看看找一个已经被标记为稳定、社区反馈问题较少的版本。另一个必须考虑的因素是硬件资源。GitLab是个“资源大户”尤其是内存。官方建议4GB内存是起步价但要流畅运行8GB或以上是更稳妥的选择。CPU核心数、磁盘IO性能也会直接影响响应速度。在规划虚拟机时一定要把这些因素考虑进去别等到装好了才发现卡得没法用。2.2 获取离线安装包唯一的官方渠道因为是完全离线所以我们必须提前在有网络的环境下把安装包下载好再拷贝到内网服务器上。绝对不要从任何第三方不明网站下载安装包安全风险极高。唯一的官方下载地址是https://packages.gitlab.com/gitlab/gitlab-ce。打开这个页面后你会看到很多目录这里需要你睁大眼睛看清楚三个关键信息操作系统通常是ubuntu、debian或centos。这取决于你虚拟机里安装的Linux发行版。版本号找到你心仪的那个稳定版本号对应的目录。CPU架构现在绝大多数服务器都是amd64(也就是x86_64)。如果你的服务器是比较老的32位系统或者ARM架构那就要选对应的包。举个例子如果你打算在Ubuntu 20.04的64位系统上安装GitLab 14.9.3那么你应该下载的文件名大概长这样gitlab-ce_14.9.3-ce.0_amd64.deb。把这个.deb包下载到你的本地电脑然后通过U盘、内部文件服务器或者其他安全方式传输到内网环境中的目标虚拟机里。注意有些教程会教你去修改系统的软件源地址指向一个内网搭建的包镜像。这对于需要安装大量软件的大规模部署确实是个好办法但对于我们这种一次性部署单个GitLab的场景直接下载离线包是最简单直接的。3. 搭建基础环境Windows服务器上的Linux虚拟机我们的场景是Windows服务器所以直接原生安装GitLab的路走不通。最稳妥的方案就是在Windows上利用虚拟机软件如VMware Workstation、Hyper-V创建一个Linux虚拟机把GitLab装在里面。3.1 选择并安装Linux系统虚拟机里装什么Linux我的血泪教训是选一个你或团队稍微熟悉一点的发行版。别为了“炫技”选一个完全没接触过的。对于新手我强烈推荐Ubuntu Server LTS版本。它社区活跃资料多遇到问题容易搜到解决方案。安装Ubuntu Server时记得在配置阶段就勾选安装OpenSSH Server。这样装完系统后你就可以直接从你的Windows主机上使用SSH工具比如PuTTY、Xshell、或者Windows Terminal连接到虚拟机告别在虚拟机窗口里敲命令的憋屈操作。另外确保网络配置正确让虚拟机能和你的Windows主机、以及内网其他机器互通。我最初图省事装了一个极简的Ubuntu Server结果发现连ifconfig这个查看IP的命令都没有还得先安装net-tools而安装它又需要网络……这就陷入了死循环。所以如果你的离线环境里没有配置本地软件源那么在制作虚拟机模板时就应该把这些基础工具包如net-toolsvimcurl预先安装好。3.2 上传安装包与系统准备把之前下载好的GitLab的.deb安装包从Windows主机上传到虚拟机。有很多方法如果虚拟机安装了图形界面和VMware Tools/VirtualBox Guest Additions可以直接拖拽。更通用的方法是使用SCP命令。在Windows主机打开PowerShell或命令提示符使用scp命令Win10/11通常自带scp C:\Users\你的用户名\Downloads\gitlab-ce_14.9.3-ce.0_amd64.deb username虚拟机IP地址:/home/username/或者使用WinSCP这类图形化SFTP工具像操作FTP一样拖过去。上传完成后通过SSH连上虚拟机先更新一下系统包索引如果本地有源的话并安装一些可能的依赖sudo apt-get update sudo apt-get install -y curl openssh-server ca-certificates tzdata perl这些依赖是GitLab官方文档中建议的提前装好可以避免后续安装报错。4. 核心安装与初始配置环境准备好安装包也到位了接下来就是最核心的安装和配置环节。4.1 执行安装命令进入你上传安装包的目录执行安装命令。对于Debian/Ubuntu系统使用dpkg命令sudo dpkg -i gitlab-ce_14.9.3-ce.0_amd64.deb这个安装过程可能会持续几分钟因为它会设置大量的服务和依赖。安装完成后你会看到GitLab的ASCII艺术logo和一堆提示信息这表示软件包已经安装到系统里了但还没有启动和配置。4.2 关键一步修改gitlab.rb配置文件安装完成后不要急着启动。必须先修改GitLab的主配置文件/etc/gitlab/gitlab.rb。这个文件是所有配置的入口用任何文本编辑器如vim、nano打开它sudo vi /etc/gitlab/gitlab.rb这个文件内容非常多但别慌对于最基本的离线部署你99%的配置只需要改一个地方找到external_url这一行。把它修改为你打算访问GitLab的地址。因为在内网通常就是虚拟机的IP地址加上一个你喜欢的端口号避免用80、8080等常见端口防止冲突。例如external_url http://192.168.1.100:9999这里的192.168.1.100就是你虚拟机的内网IP9999是端口。这个地址非常重要它不仅是浏览器访问的地址也会成为你项目Clone时SSH或HTTP链接的一部分。超级重要的避坑提示很多新手包括当年的我会在这个文件里看到一大堆其他配置比如关于PumaGitLab的Web服务器的端口设置。里面有一行puma[port] 8080可能被注释掉了。请你千万不要去动它尤其不要把它改成和external_url里一样的端口比如9999。Puma默认监听8080端口是给内部Nginx反向代理用的。如果你改了它或者把它改成和外部端口一样会导致端口冲突最直接的现象就是访问GitLab页面出现502 Bad Gateway错误。我当年就被这个问题折磨了一整天。4.3 让配置生效并启动GitLab保存并退出配置文件后执行让配置生效的神奇命令sudo gitlab-ctl reconfigure这个命令会运行很久可能10-20分钟因为它会根据你的配置文件自动配置所有组件Nginx, PostgreSQL, Redis, Puma等。过程中会刷出大量日志只要不出现红色的错误信息ERROR就耐心等待它完成。当看到绿色的gitlab Reconfigured!字样时恭喜你GitLab服务已经启动并运行了你可以用以下命令快速检查服务状态sudo gitlab-ctl status你应该能看到run状态的一长串服务列表比如puma、sidekiq、nginx等。4.4 找到管理员初始密码GitLab安装后会为默认的超级管理员账户root生成一个随机密码。这个密码存放在一个文件中并且24小时后会自动删除。在刚才reconfigure命令输出的日志里仔细找一下会有类似这样的提示Notes: Default admin account has been configured with following details: Username: root Password: You didn‘t opt-in to print initial root password to STDOUT. Password stored to /etc/gitlab/initial_root_password.密码文件路径就是/etc/gitlab/initial_root_password。用cat命令查看它sudo cat /etc/gitlab/initial_root_password你会看到一串复杂的密码赶紧复制下来。4.5 防火墙与首次登录现在打开你的Windows主机上的浏览器输入http://[你的虚拟机IP]:9999比如http://192.168.1.100:9999。如果网络通畅你应该能看到GitLab的登录界面。如果打不开很可能是虚拟机的防火墙挡住了端口。Ubuntu默认可能使用ufw防火墙。你可以选择关闭它仅用于内网测试或者放行端口sudo ufw allow 9999/tcp # 允许9999端口的TCP流量 sudo ufw reload # 重新加载防火墙规则用sudo ufw status可以查看规则是否生效。在登录界面用户名输入root密码粘贴刚才复制的那个复杂密码。登录成功后第一件事就是去修改root用户的密码在右上角用户头像 - Settings - Password 里进行修改。因为那个初始密码文件一旦被他人获取你的代码库就毫无安全可言了。5. 部署后的必备运维与调优GitLab跑起来了但要让它在内网环境中稳定、高效地服务还需要做一些运维工作。5.1 日常运维命令记住这几个命令日常管理基本就够了查看所有服务状态sudo gitlab-ctl status。哪个服务停了一眼就能看出来。重启GitLabsudo gitlab-ctl restart。修改了重要配置后需要执行。查看实时日志sudo gitlab-ctl tail。这个命令可以附加-f参数来跟踪日志排查问题时非常有用比如sudo gitlab-ctl tail -f nginx专门看Web访问日志。系统检查sudo gitlab-rake gitlab:check SANITIZEtrue。这个命令会检查GitLab的各项配置、数据库连接等是否正常并给出修复建议。5.2 性能与存储调优内网服务器的资源可能有限所以需要做一些调优。减少Sidekiq并发数Sidekiq是处理后台作业如发邮件、CI任务的。如果服务器内存小可以在/etc/gitlab/gitlab.rb中修改sidekiq[max_concurrency] 5默认是25减少其内存占用。调整Puma工作进程数Puma是Web服务器。同样在配置文件中可以调整puma[worker_processes]默认是CPU核心数。内存不足时可以适当调低。修改仓库存储路径默认仓库存储在/var/opt/gitlab/git-data。如果你的系统盘空间小数据盘挂载在别的目录比如/data可以修改git_data_dirs配置将仓库路径指向大容量磁盘。配置邮件服务器虽然离线但GitLab的很多通知如合并请求、流水线失败依赖邮件。你需要配置一个内网的SMTP服务器地址在配置文件中搜索smtp_enable、smtp_address等配置项进行设置。否则用户注册、密码找回等功能会受限。5.3 权限与项目初始化作为管理员登录后首先要做的是配置团队和权限。关闭公开注册在 Admin Area - Settings - General - Sign-up restrictions 里取消勾选“Sign-up enabled”。内网系统通常不需要开放注册由管理员统一创建账户。创建用户和组在 Admin Area - Users 和 Admin Area - Groups 里为你的团队成员创建账户和项目组。GitLab的权限模型是群组(Group) - 项目(Project)。建议先按部门或团队创建群组设置好群组权限如Private, Internal然后在群组下创建项目。这样管理权限更加清晰。推送第一个项目在本地开发机上配置远程仓库地址为你的内网GitLab地址如http://192.168.1.100:9999/group-name/project-name.git然后就可以像使用GitHub一样进行git push和git pull了。6. 避坑指南那些我踩过的“雷”回顾整个部署过程有几个地方特别容易出错我单独拎出来强调一下。6.1 配置文件修改的“唯一真理”这是最最最重要的原则所有配置只要可能都只修改/etc/gitlab/gitlab.rb这一个文件然后运行sudo gitlab-ctl reconfigure。GitLab使用了一套名为“Omnibus”的打包技术它会把分散的组件Nginx, Redis, PostgreSQL等的配置都通过gitlab.rb这个总控文件来生成。如果你去手动修改其他地方的配置文件比如/var/opt/gitlab/nginx/conf/gitlab-http.conf(Nginx配置)/opt/gitlab/embedded/service/gitlab-shell/config.yml(Git Shell配置)你会发现这些文件的开头都有一行警告“This file is managed by gitlab-ctl. Manual changes will be erased!”。意思是这个文件由gitlab-ctl管理手动修改会被擦除下次你一执行reconfigure你的修改就被无情地覆盖了。所以一定要养成习惯只在gitlab.rb里改配置。6.2 端口冲突与502错误前面提到过external_url的端口和Puma/Nginx内部监听端口不能冲突。这里再展开一下external_url ‘http://ip:port‘这个port是用户浏览器访问的端口。puma[‘port‘]默认是8080这是Puma应用服务器监听的端口。GitLab内置的Nginx会监听external_url中指定的端口然后将请求反向代理到Puma的8080端口。如果你把puma[‘port‘]也改成了9999那么Nginx和Puma就会争抢同一个端口必然有一个启动失败结果就是Nginx无法将请求转发给Puma浏览器就会报502。所以除非你非常清楚自己在做什么否则不要动Puma的端口配置。6.3 虚拟机资源不足导致服务异常GitLab在启动和运行时会消耗大量资源。如果你的虚拟机分配的内存不足比如只给了2GB可能会遇到一些诡异的问题比如Sidekiq进程频繁崩溃、页面加载奇慢无比、甚至reconfigure命令执行到一半失败。我的经验是对于一个小团队20人以内使用的GitLab虚拟机至少分配4核CPU、8GB内存、50GB磁盘。磁盘空间要留足因为代码仓库、CI/CD的构建缓存、容器镜像仓库都会占用大量空间。6.4 备份与恢复策略内网部署没有云服务的自动备份数据安全全靠自己。一定要定期备份GitLab提供了简单的备份命令sudo gitlab-backup create这个命令会在/var/opt/gitlab/backups目录下生成一个类似1660032012_2022_08_09_14.9.3_gitlab_backup.tar的备份文件。你需要制定计划定期执行这个命令并把备份文件拷贝到另一台物理存储上。同时不要忘记备份配置文件sudo tar czf /path/to/backup/gitlab-config-$(date %s).tar.gz /etc/gitlab/恢复时先确保新环境的GitLab版本与备份文件版本一致然后停止服务恢复配置最后用sudo gitlab-backup restore BACKUP备份文件名来恢复数据。把GitLab成功部署到内网只是第一步。接下来你可以探索它的CI/CD流水线功能在内网搭建自己的自动化构建和部署环境也可以启用容器镜像仓库统一管理Docker镜像。这个过程虽然前期有些繁琐但一旦搭建完成你就会拥有一个完全自主、安全可控的研发协作平台这种掌控感是使用任何外部云服务都无法比拟的。