1. 项目概述为什么我们需要一个自托管的GitLab如果你是一名开发者、运维工程师或者是一个小团队的负责人你一定对代码托管和协作开发不陌生。GitHub、GitLab.com这些云端服务固然方便但当你需要将代码资产完全掌控在自己手中或者出于网络环境、数据安全、合规性要求的考虑时自托管一个代码仓库平台就成了刚需。GitLab Community Edition简称GitLab-CE就是一个完美的选择它是一个开源的、功能完整的DevOps平台集成了代码仓库、CI/CD、项目管理、代码审查等一系列功能。我之所以选择写这篇关于GitLab-CE安装及汉化的文章是因为在过去的几年里我亲手为不同规模的公司和团队部署过不下十次GitLab。从物理服务器到云主机从Docker到原生安装几乎踩遍了所有能踩的坑。我发现虽然官方文档很全但对于国内用户尤其是初次接触的开发者来说安装过程中的网络问题、依赖冲突以及安装后面对全英文界面的茫然都是不小的门槛。因此这篇内容旨在提供一个“一站式”的解决方案不仅告诉你如何稳定地安装GitLab-CE更会详细拆解如何对其进行汉化让你和你的团队能更快地上手使用。2. 核心需求解析安装与汉化背后的考量在动手之前我们得先想清楚几个问题为什么要自建GitLab为什么选择CE版以及为什么需要汉化这决定了我们后续所有操作的出发点和细节处理。2.1 选择GitLab-CE的理由GitLab分为三个版本免费的Community EditionCE、付费的Premium和Ultimate。对于绝大多数中小团队和个人开发者CE版的功能已经绰绰有余。它包含了核心的Git仓库管理、Issue跟踪、Wiki、基本的CI/CD流水线使用GitLab Runner、容器镜像仓库等。除非你需要诸如高级安全扫描、合规性仪表盘、史诗级项目管理等企业级功能否则CE版完全够用。自托管的CE版让你拥有数据的绝对控制权可以自定义集成到内网的其他系统并且没有用户数或仓库数的限制。2.2 汉化的必要性探讨关于汉化这是一个见仁见智的问题。对于技术团队尤其是开发人员英文界面或许不是障碍甚至有助于统一术语。但对于项目管理人员、产品经理或其他非技术背景的协作者一个全英文的界面可能会显著增加学习成本和沟通障碍。汉化能降低工具的入门门槛让团队所有成员都能更顺畅地参与到DevOps流程中。GitLab官方并未提供完整的中文语言包但开源社区有优秀的汉化项目我们可以直接利用。需要注意的是汉化包通常滞后于官方版本更新在升级GitLab主版本时需要留意兼容性。2.3 环境准备与方案选型安装GitLab-CE主要有几种方式使用官方提供的Omnibus包推荐、Docker容器化部署、从源码编译。对于生产环境我强烈推荐使用Omnibus包。它是一个将所有依赖Ruby, PostgreSQL, Redis, Nginx等打包好的独立安装包极大地简化了安装和升级流程也方便统一管理。Docker方式虽然灵活轻量但在数据持久化、备份恢复和性能调优上需要更多的手动配置更适合对容器技术有深入理解的团队。本文将基于最稳定、最通用的Omnibus包安装方式进行操作系统以Ubuntu 22.04 LTS为例CentOS/RHEL等步骤类似主要是包管理命令不同。同时我们会使用国内开发者维护的汉化补丁实现界面中文化。3. 安装前关键准备避开第一个大坑很多安装失败都源于准备工作没做好。这一步的目标是搭建一个干净、稳定、网络通畅的基础环境。3.1 系统要求检查首先确保你的服务器满足最低要求。对于一个小型团队20人以内建议配置至少2核CPU、4GB内存、40GB存储。内存是关键GitLab运行起来后比较吃内存4GB是能流畅运行的门槛如果同时运行CI/CD任务建议8GB或以上。可以用free -h和df -h命令检查内存和磁盘空间。其次检查防火墙和端口。GitLab默认使用HTTP80、HTTPS443和SSH22端口。确保这些端口在服务器的防火墙如ufw或firewalld中是开放的并且没有被其他进程占用。你可以用sudo ss -tulpn | grep :80这样的命令检查端口占用情况。3.2 解决国内网络访问难题这是国内用户安装GitLab时最大的障碍。GitLab的官方安装脚本和软件源服务器在国外直接运行可能会因为网络超时而失败。我们有几种应对策略使用国内镜像源对于Ubuntu/Debian系统可以替换apt的软件源为阿里云、腾讯云等国内镜像加速系统包的下载。但这只解决系统包不解决GitLab自身的包。手动下载Omnibus包这是最可靠的方法。我们可以先通过浏览器或wget从GitLab的国内镜像站如清华大学TUNA镜像站下载好对应版本的.deb安装包然后进行本地安装。配置安装脚本的下载源在运行官方安装脚本时通过环境变量指定一个国内的软件仓库镜像地址。为了确保成功率本文将采用策略2手动下载安装包。这样即使网络波动我们也只需要重下载一个文件而不是在安装脚本运行到一半时失败。3.3 依赖安装与主机名配置在安装GitLab之前我们需要确保一些基础工具已就绪并正确设置服务器的主机名这关系到GitLab生成的仓库URL。# 更新系统包列表并安装一些常用工具如curl, vim sudo apt update sudo apt install -y curl vim openssh-server ca-certificates # 设置服务器的主机名假设你的服务器IP是192.168.1.100你想通过 gitlab.yourcompany.com 访问 # 请将下面的域名替换为你实际要使用的域名或IP sudo hostnamectl set-hostname gitlab.yourcompany.com # 编辑 /etc/hosts 文件确保主机名能正确解析到本机IP # 使用 vim 或你喜欢的编辑器 sudo vim /etc/hosts # 在文件末尾添加一行假设你的服务器内网IP是192.168.1.100 # 192.168.1.100 gitlab.yourcompany.com gitlab注意如果你只是在测试没有域名也可以直接用服务器的公网IP或内网IP作为主机名。但请注意一旦设置后续修改会比较麻烦可能涉及GitLab配置的重置。4. 分步安装GitLab-CE从下载到首次登录准备工作就绪现在开始核心安装步骤。我会详细解释每一步的作用让你明白自己在做什么而不是机械地复制命令。4.1 下载与安装Omnibus包首先访问GitLab官方发布页面或国内镜像站找到适合你系统版本的包。这里以gitlab-ce_16.9.1-ce.0_amd64.deb版本号请以最新稳定版为准为例从清华镜像下载。# 进入一个临时目录如下载目录 cd /tmp # 使用 wget 从清华镜像站下载指定版本的安装包 # 你需要根据实际情况替换版本号如16.9.1和系统架构如amd64 wget https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu/pool/focal/main/g/gitlab-ce/gitlab-ce_16.9.1-ce.0_amd64.deb # 下载完成后使用 dpkg 命令进行安装 # -i 参数表示安装如果遇到依赖问题可以用下面的 apt 命令修复 sudo dpkg -i gitlab-ce_16.9.1-ce.0_amd64.deb运行dpkg -i时你可能会看到一些关于缺少依赖的警告如libssl版本。别担心这是正常的因为Omnibus包是相对独立的但可能会和系统已有软件有轻微冲突。安装程序通常会尝试自动处理。如果安装中断可以运行sudo apt --fix-broken install来修复依赖关系然后重新运行sudo dpkg -i命令。4.2 初始配置与启动安装完成后GitLab的配置文件位于/etc/gitlab/gitlab.rb。这是一个非常庞大的Ruby配置文件但我们初期只需要关注几个关键项。# 使用 vim 编辑主配置文件 sudo vim /etc/gitlab/gitlab.rb找到external_url这一行。这是最重要的配置它定义了GitLab对外访问的地址。将其修改为你之前设置的主机名或IP并带上协议http或https。初次安装强烈建议先使用HTTP避免证书问题带来的复杂度。# 将 # external_url http://gitlab.example.com # 修改为例如 external_url http://gitlab.yourcompany.com # 或 http://你的服务器IP如果你想一劳永逸地使用HTTPS也可以在这里设置为https://...但你需要提前准备好SSL证书可以是自签名证书也可以是Let‘s Encrypt免费证书。Omnibus包内置了Let’s Encrypt自动申请功能只需额外配置几行即可但为了简化初次安装流程我们暂不展开。保存并退出编辑器后运行重配置命令。这个命令会根据/etc/gitlab/gitlab.rb中的设置生成所有服务的实际运行配置并启动它们。# 执行重配置这个过程会比较长5-15分钟因为它要编译配置、设置数据库、生成密钥等。 sudo gitlab-ctl reconfigure请耐心等待命令执行完成。当你看到类似“gitlab Reconfigured!”的提示时就表示成功了。4.3 获取初始密码并登录GitLab安装完成后会为默认的root管理员账户生成一个随机密码这个密码存储在/etc/gitlab/initial_root_password文件中并且24小时后会自动删除。# 查看初始root密码 sudo cat /etc/gitlab/initial_root_password复制输出的密码然后打开浏览器访问你设置的external_url例如http://gitlab.yourcompany.com。使用用户名root和刚才复制的密码登录。登录后第一件事立即修改root用户的密码点击右上角用户头像 - “Edit profile” - 左侧菜单 “Password”修改密码。4.4 基础安全与优化设置可选但建议登录后建议进行几项基础设置关闭用户自助注册对于内部使用的GitLab通常不需要开放注册。进入 “Admin Area”管理区域左下角扳手图标 - “Settings” - “General” - 展开 “Sign-up restrictions” - 取消勾选 “Sign-up enabled”。配置邮箱服务器为了让GitLab能发送重置密码、通知等邮件需要配置SMTP。这步稍复杂需要你有可用的邮箱服务如企业邮箱、SendGrid等。可以在/etc/gitlab/gitlab.rb中搜索gitlab_rails[smtp_*]进行配置然后再次sudo gitlab-ctl reconfigure。创建普通用户和项目不要一直使用root账户。创建一个属于你自己的普通账户并赋予管理员权限如果需要然后用这个账户创建项目、组开始你的协作之旅。5. 深度汉化实战不仅仅是替换文字GitLab的汉化本质上是替换其前端界面中的英文字符串文件。社区有热心的开发者将这部分工作做成了补丁。我们将使用一个广泛流传的汉化方案。5.1 汉化方案选择与原理目前主流的汉化方法是使用xhang/gitlab的汉化补丁。其原理是在GitLab的源代码中所有界面文字都存储在.yml或.po格式的本地化文件中。汉化补丁就是将这些文件替换为翻译好的中文版本。由于GitLab版本更新频繁汉化补丁通常针对特定的GitLab版本。因此汉化前务必确认你的GitLab版本并找到对应版本的汉化补丁版本不匹配会导致界面错乱甚至功能异常。5.2 汉化操作步骤详解假设我们安装的GitLab版本是16.9.1。汉化过程需要在服务器上操作。第一步停止GitLab服务为了避免在替换文件时产生冲突我们先停止相关服务。sudo gitlab-ctl stop unicorn sudo gitlab-ctl stop sidekiq sudo gitlab-ctl stop nginx # 也可以使用一条命令停止所有服务但停止核心的几个即可 # sudo gitlab-ctl stop第二步备份原始文件至关重要这是必须的步骤如果汉化出现问题我们可以迅速回滚。# 创建一个备份目录 sudo mkdir -p /var/opt/gitlab/backups/i18n # 备份GitLab自带的本地化文件目录 sudo cp -r /opt/gitlab/embedded/service/gitlab-rails/locale /var/opt/gitlab/backups/i18n/locale.original.$(date %F)第三步下载对应版本的汉化补丁我们需要找到16.9.1版本对应的汉化补丁。通常汉化项目会提供不同版本的发布包。我们可以从GitHub等代码托管平台获取。# 进入临时目录 cd /tmp # 下载汉化包。注意以下URL是示例你需要根据实际情况找到正确的下载链接。 # 例如可以从 https://gitlab.com/xhang/gitlab/-/releases 查看是否有对应版本的补丁 # 这里假设我们下载了一个名为 gitlab-16-9-1-zh.tar.gz 的包 sudo wget -O gitlab-16-9-1-zh.tar.gz [实际的汉化包下载链接] # 解压汉化包 sudo tar -xzf gitlab-16-9-1-zh.tar.gz第四步应用汉化补丁解压后汉化包里通常有一个locale/目录里面就是翻译好的中文文件zh-CN或zh_HANS。我们需要用它们覆盖GitLab原有的文件。# 复制汉化文件覆盖原始文件 # 请确认解压出的目录结构假设汉化文件在 /tmp/gitlab-16-9-1-zh/locale/ sudo cp -rf /tmp/gitlab-16-9-1-zh/locale/* /opt/gitlab/embedded/service/gitlab-rails/locale/ # 设置正确的文件权限和所有权GitLab服务通常以git用户运行 sudo chown -R git:git /opt/gitlab/embedded/service/gitlab-rails/locale第五步清理缓存并重启服务文件替换后需要清除GitLab的缓存让新语言生效。# 清理缓存 sudo gitlab-rake cache:clear sudo gitlab-rake assets:clean sudo gitlab-rake assets:precompile # 重新启动之前停止的服务 sudo gitlab-ctl start unicorn sudo gitlab-ctl start sidekiq sudo gitlab-ctl start nginx # 或者直接启动所有服务 # sudo gitlab-ctl start5.3 验证汉化效果与问题排查完成以上步骤后刷新浏览器中的GitLab页面。登录后进入用户设置右上角头像 - “Settings”在 “Preferences” 选项卡中找到 “Language”将其从 “English” 更改为 “简体中文”。保存后整个界面应该就变成中文了。常见问题与排查界面部分英文/部分中文这通常是汉化包版本与GitLab版本不完全匹配或者某些新增功能尚未翻译。可以尝试寻找更新版本的汉化包或者接受部分英文的存在。界面错乱或功能异常这很可能是汉化包版本严重不匹配破坏了某些关键文件。立即回滚使用第二步的备份sudo rm -rf /opt/gitlab/embedded/service/gitlab-rails/locale sudo cp -r /var/opt/gitlab/backups/i18n/locale.original.[日期] /opt/gitlab/embedded/service/gitlab-rails/locale sudo chown -R git:git /opt/gitlab/embedded/service/gitlab-rails/locale sudo gitlab-ctl restart切换语言后无变化尝试强制刷新浏览器缓存CtrlF5或者清理浏览器Cookie后重新登录。6. 生产环境进阶配置与优化安装和汉化只是第一步。要让GitLab在生产环境中稳定、高效、安全地运行还需要进行一些关键配置。6.1 配置HTTPS与自动续期证书使用HTTP是不安全的所有流量包括密码都是明文传输。我们必须启用HTTPS。Omnibus GitLab内置了Nginx和自动获取Let‘s Encrypt证书的功能配置起来非常方便。编辑/etc/gitlab/gitlab.rb# 1. 将 external_url 改为 https external_url https://gitlab.yourcompany.com # 2. 开启Lets Encrypt自动证书管理 letsencrypt[enable] true letsencrypt[contact_emails] [adminyourcompany.com] # 设置联系邮箱 letsencrypt[auto_renew] true letsencrypt[auto_renew_hour] 12 # 自动续期的时间小时 letsencrypt[auto_renew_minute] 30 letsencrypt[auto_renew_day_of_month] */7 # 每7天尝试续期一次 # 3. 重定向所有HTTP流量到HTTPS可选但推荐 nginx[redirect_http_to_https] true保存后运行sudo gitlab-ctl reconfigure。第一次运行会尝试从Let‘s Encrypt申请证书请确保你的域名gitlab.yourcompany.com的DNS记录已正确指向服务器公网IP并且服务器的80和443端口能从公网访问。申请成功后证书会自动配置到Nginx中。6.2 配置外部数据库与Redis高级默认安装使用了内嵌的PostgreSQL和Redis。对于大型实例或希望统一管理数据库的情况可以迁移到外部数据库。这步操作复杂且有风险务必在测试环境充分验证并做好备份。主要步骤包括在外部服务器上安装并配置PostgreSQL/Redis。在/etc/gitlab/gitlab.rb中注释掉内嵌服务配置并添加指向外部服务的配置。使用gitlab-ctl reconfigure停止内嵌服务但不会自动迁移数据。需要手动从内嵌数据库导出数据再导入到外部数据库。这是一个专业运维操作官方文档有详细指南但非必需不建议新手改动。6.3 性能调优与监控GitLab运行后可以通过以下命令监控其状态# 查看所有服务状态 sudo gitlab-ctl status # 查看实时日志按CtrlC退出 sudo gitlab-ctl tail # 查看特定服务日志如postgresql sudo gitlab-ctl tail postgresql如果发现服务器响应慢可以从以下几个方面排查内存不足使用htop或free -h查看。可以考虑增加Swap空间或者升级服务器配置。Sidekiq队列堆积Sidekiq是处理后台任务如发邮件、CI流水线的服务。如果任务过多会导致界面卡顿。可以进入管理区域 - “Monitoring” - “Background Jobs” 查看队列情况。数据库优化对于项目、用户数量很大的实例可能需要数据库索引优化。可以启用慢查询日志进行分析。6.4 备份与恢复策略定期备份是生命线Omnibus GitLab提供了简单的备份命令# 执行备份备份文件会默认存储在 /var/opt/gitlab/backups/ 目录下文件名如 1712345678_2024_04_05_16.9.1_gitlab_backup.tar sudo gitlab-backup create这个备份包含了数据库、仓库、上传文件等几乎所有数据但不包含配置文件。因此你还需要手动备份两个关键配置文件sudo cp /etc/gitlab/gitlab.rb /var/opt/gitlab/backups/ sudo cp /etc/gitlab/gitlab-secrets.json /var/opt/gitlab/backups/ # 这个文件包含加密密钥丢失会导致两步验证等数据无法解密恢复备份确保新服务器的GitLab版本与备份文件版本完全一致。停止相关服务sudo gitlab-ctl stop puma; sudo gitlab-ctl stop sidekiq。恢复备份文件sudo gitlab-backup restore BACKUP备份文件名前缀注意不带_gitlab_backup.tar后缀。恢复配置文件将备份的gitlab.rb和gitlab-secrets.json复制回/etc/gitlab/。重配置并重启sudo gitlab-ctl reconfigure sudo gitlab-ctl restart。7. 日常维护与升级指南GitLab社区版迭代很快定期升级可以获取新功能和安全补丁。7.1 小版本升级如16.9.1 - 16.9.2小版本升级同一大版本下的次要版本通常比较安全。Omnibus包升级很简单# 1. 备份重要的事情说三遍 sudo gitlab-backup create # 2. 停止服务非必须但推荐 sudo gitlab-ctl stop # 3. 下载新版本的.deb包例如16.9.2 cd /tmp wget https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu/pool/focal/main/g/gitlab-ce/gitlab-ce_16.9.2-ce.0_amd64.deb # 4. 安装新包这会自动升级 sudo dpkg -i gitlab-ce_16.9.2-ce.0_amd64.deb # 5. 重新配置并启动 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart7.2 大版本升级如16.x - 17.x大版本升级可能存在不兼容的变更。务必先查看官方升级文档通常会有特殊的升级路径要求例如不能跨大版本升级需要按顺序升级。同样备份是第一步。升级后汉化包很可能失效需要等待对应新版本的汉化包发布后再重新应用汉化流程。7.3 汉化包的升级当GitLab升级后你需要等待社区发布对应新版本的汉化包。重复第5章的汉化步骤停止服务 - 备份当前locale - 下载新汉化包 - 覆盖文件 - 重启服务。如果新版本汉化包未发布你可能需要暂时使用英文界面或者尝试手动合并部分汉化文件不推荐容易出错。8. 常见问题排查与实战心得根据我多次部署的经验下面这些问题是最高频遇到的我把它们整理成表方便你快速定位。问题现象可能原因排查与解决步骤访问http://服务器IP显示502错误1. GitLab服务未完全启动。2. 内存不足导致PumaWeb服务器启动失败。3. 端口冲突。1. 运行sudo gitlab-ctl status查看哪些服务是down状态。2. 运行sudo gitlab-ctl tail查看日志重点关注unicorn或puma的日志。3. 检查内存free -h考虑增加Swapsudo dd if/dev/zero of/swapfile bs1M count2048 sudo mkswap /swapfile sudo swapon /swapfile。4. 检查80端口是否被占用sudo ss -tulpn | grep :80。gitlab-ctl reconfigure运行极慢或卡住1. 服务器DNS解析问题无法连接外部资源。2. 下载包或证书时网络超时。1. 检查/etc/resolv.conf确保DNS服务器设置正确如8.8.8.8。2. 可以尝试在/etc/gitlab/gitlab.rb中设置letsencrypt[enable] false先跳过证书申请。3. 查看具体卡在哪一步打开另一个终端运行sudo tail -f /var/log/gitlab/reconfigure/*.log。推送代码时提示“HTTP Basic: Access denied”1. 账号密码错误。2. 如果使用SSH可能是SSH密钥未添加或代理问题。3. 项目权限不足。1. 确认用户名密码或在GitLab网页端生成一个“Access Token”代替密码使用。2. 对于SSH运行ssh -T git你的gitlab服务器测试连接将本地~/.ssh/id_rsa.pub内容添加到GitLab用户设置的SSH Keys中。3. 确认你在项目中有推送权限。汉化后界面出现乱码或方框服务器或客户端缺少中文字体支持。在服务器上安装中文字体包sudo apt install -y fonts-wqy-microhei fonts-wqy-zenhei然后重启GitLab服务。发送邮件失败SMTP配置不正确。1. 检查/etc/gitlab/gitlab.rb中SMTP配置的每一项地址、端口、用户名、密码、认证方式。2. 运行sudo gitlab-rails console进入控制台尝试发送测试邮件Notify.test_email(接收邮箱, 测试标题, 测试正文).deliver_now观察报错信息。3. 查看邮件日志sudo gitlab-ctl tail postfix如果使用内置Postfix。磁盘空间告急仓库数据、Docker镜像、备份文件、日志文件占用过多。1. 清理旧的备份文件sudo rm /var/opt/gitlab/backups/旧备份文件.tar。2. 设置日志轮转在/etc/gitlab/gitlab.rb中配置logrotate。3. 对于Docker镜像仓库如果启用进入管理区域 - “Admin” - “Dependency Proxy” 或 “Container Registry” 清理未使用的镜像。几点个人心得测试环境先行任何重要的配置变更如大版本升级、外部数据库迁移务必先在克隆的生产环境的测试服务器上操作一遍。文档是你的朋友遇到复杂问题第一个去处是 官方文档 搜索错误信息往往能找到解决方案。善用日志sudo gitlab-ctl tail是你排查问题的瑞士军刀。学会从日志中寻找ERROR或FATAL级别的信息。社区力量在 GitLab Forum 或相关技术社区搜索你遇到的问题很可能别人已经遇到并解决了。关于汉化对于生产环境如果团队英文能力尚可我有时会建议先使用英文界面一段时间。这能让你更熟悉原生术语方便查阅英文文档。当团队稳定后再根据需求决定是否汉化这样可以避免因汉化包更新延迟而带来的维护成本。
1. 项目概述为什么我们需要一个自托管的GitLab如果你是一名开发者、运维工程师或者是一个小团队的负责人你一定对代码托管和协作开发不陌生。GitHub、GitLab.com这些云端服务固然方便但当你需要将代码资产完全掌控在自己手中或者出于网络环境、数据安全、合规性要求的考虑时自托管一个代码仓库平台就成了刚需。GitLab Community Edition简称GitLab-CE就是一个完美的选择它是一个开源的、功能完整的DevOps平台集成了代码仓库、CI/CD、项目管理、代码审查等一系列功能。我之所以选择写这篇关于GitLab-CE安装及汉化的文章是因为在过去的几年里我亲手为不同规模的公司和团队部署过不下十次GitLab。从物理服务器到云主机从Docker到原生安装几乎踩遍了所有能踩的坑。我发现虽然官方文档很全但对于国内用户尤其是初次接触的开发者来说安装过程中的网络问题、依赖冲突以及安装后面对全英文界面的茫然都是不小的门槛。因此这篇内容旨在提供一个“一站式”的解决方案不仅告诉你如何稳定地安装GitLab-CE更会详细拆解如何对其进行汉化让你和你的团队能更快地上手使用。2. 核心需求解析安装与汉化背后的考量在动手之前我们得先想清楚几个问题为什么要自建GitLab为什么选择CE版以及为什么需要汉化这决定了我们后续所有操作的出发点和细节处理。2.1 选择GitLab-CE的理由GitLab分为三个版本免费的Community EditionCE、付费的Premium和Ultimate。对于绝大多数中小团队和个人开发者CE版的功能已经绰绰有余。它包含了核心的Git仓库管理、Issue跟踪、Wiki、基本的CI/CD流水线使用GitLab Runner、容器镜像仓库等。除非你需要诸如高级安全扫描、合规性仪表盘、史诗级项目管理等企业级功能否则CE版完全够用。自托管的CE版让你拥有数据的绝对控制权可以自定义集成到内网的其他系统并且没有用户数或仓库数的限制。2.2 汉化的必要性探讨关于汉化这是一个见仁见智的问题。对于技术团队尤其是开发人员英文界面或许不是障碍甚至有助于统一术语。但对于项目管理人员、产品经理或其他非技术背景的协作者一个全英文的界面可能会显著增加学习成本和沟通障碍。汉化能降低工具的入门门槛让团队所有成员都能更顺畅地参与到DevOps流程中。GitLab官方并未提供完整的中文语言包但开源社区有优秀的汉化项目我们可以直接利用。需要注意的是汉化包通常滞后于官方版本更新在升级GitLab主版本时需要留意兼容性。2.3 环境准备与方案选型安装GitLab-CE主要有几种方式使用官方提供的Omnibus包推荐、Docker容器化部署、从源码编译。对于生产环境我强烈推荐使用Omnibus包。它是一个将所有依赖Ruby, PostgreSQL, Redis, Nginx等打包好的独立安装包极大地简化了安装和升级流程也方便统一管理。Docker方式虽然灵活轻量但在数据持久化、备份恢复和性能调优上需要更多的手动配置更适合对容器技术有深入理解的团队。本文将基于最稳定、最通用的Omnibus包安装方式进行操作系统以Ubuntu 22.04 LTS为例CentOS/RHEL等步骤类似主要是包管理命令不同。同时我们会使用国内开发者维护的汉化补丁实现界面中文化。3. 安装前关键准备避开第一个大坑很多安装失败都源于准备工作没做好。这一步的目标是搭建一个干净、稳定、网络通畅的基础环境。3.1 系统要求检查首先确保你的服务器满足最低要求。对于一个小型团队20人以内建议配置至少2核CPU、4GB内存、40GB存储。内存是关键GitLab运行起来后比较吃内存4GB是能流畅运行的门槛如果同时运行CI/CD任务建议8GB或以上。可以用free -h和df -h命令检查内存和磁盘空间。其次检查防火墙和端口。GitLab默认使用HTTP80、HTTPS443和SSH22端口。确保这些端口在服务器的防火墙如ufw或firewalld中是开放的并且没有被其他进程占用。你可以用sudo ss -tulpn | grep :80这样的命令检查端口占用情况。3.2 解决国内网络访问难题这是国内用户安装GitLab时最大的障碍。GitLab的官方安装脚本和软件源服务器在国外直接运行可能会因为网络超时而失败。我们有几种应对策略使用国内镜像源对于Ubuntu/Debian系统可以替换apt的软件源为阿里云、腾讯云等国内镜像加速系统包的下载。但这只解决系统包不解决GitLab自身的包。手动下载Omnibus包这是最可靠的方法。我们可以先通过浏览器或wget从GitLab的国内镜像站如清华大学TUNA镜像站下载好对应版本的.deb安装包然后进行本地安装。配置安装脚本的下载源在运行官方安装脚本时通过环境变量指定一个国内的软件仓库镜像地址。为了确保成功率本文将采用策略2手动下载安装包。这样即使网络波动我们也只需要重下载一个文件而不是在安装脚本运行到一半时失败。3.3 依赖安装与主机名配置在安装GitLab之前我们需要确保一些基础工具已就绪并正确设置服务器的主机名这关系到GitLab生成的仓库URL。# 更新系统包列表并安装一些常用工具如curl, vim sudo apt update sudo apt install -y curl vim openssh-server ca-certificates # 设置服务器的主机名假设你的服务器IP是192.168.1.100你想通过 gitlab.yourcompany.com 访问 # 请将下面的域名替换为你实际要使用的域名或IP sudo hostnamectl set-hostname gitlab.yourcompany.com # 编辑 /etc/hosts 文件确保主机名能正确解析到本机IP # 使用 vim 或你喜欢的编辑器 sudo vim /etc/hosts # 在文件末尾添加一行假设你的服务器内网IP是192.168.1.100 # 192.168.1.100 gitlab.yourcompany.com gitlab注意如果你只是在测试没有域名也可以直接用服务器的公网IP或内网IP作为主机名。但请注意一旦设置后续修改会比较麻烦可能涉及GitLab配置的重置。4. 分步安装GitLab-CE从下载到首次登录准备工作就绪现在开始核心安装步骤。我会详细解释每一步的作用让你明白自己在做什么而不是机械地复制命令。4.1 下载与安装Omnibus包首先访问GitLab官方发布页面或国内镜像站找到适合你系统版本的包。这里以gitlab-ce_16.9.1-ce.0_amd64.deb版本号请以最新稳定版为准为例从清华镜像下载。# 进入一个临时目录如下载目录 cd /tmp # 使用 wget 从清华镜像站下载指定版本的安装包 # 你需要根据实际情况替换版本号如16.9.1和系统架构如amd64 wget https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu/pool/focal/main/g/gitlab-ce/gitlab-ce_16.9.1-ce.0_amd64.deb # 下载完成后使用 dpkg 命令进行安装 # -i 参数表示安装如果遇到依赖问题可以用下面的 apt 命令修复 sudo dpkg -i gitlab-ce_16.9.1-ce.0_amd64.deb运行dpkg -i时你可能会看到一些关于缺少依赖的警告如libssl版本。别担心这是正常的因为Omnibus包是相对独立的但可能会和系统已有软件有轻微冲突。安装程序通常会尝试自动处理。如果安装中断可以运行sudo apt --fix-broken install来修复依赖关系然后重新运行sudo dpkg -i命令。4.2 初始配置与启动安装完成后GitLab的配置文件位于/etc/gitlab/gitlab.rb。这是一个非常庞大的Ruby配置文件但我们初期只需要关注几个关键项。# 使用 vim 编辑主配置文件 sudo vim /etc/gitlab/gitlab.rb找到external_url这一行。这是最重要的配置它定义了GitLab对外访问的地址。将其修改为你之前设置的主机名或IP并带上协议http或https。初次安装强烈建议先使用HTTP避免证书问题带来的复杂度。# 将 # external_url http://gitlab.example.com # 修改为例如 external_url http://gitlab.yourcompany.com # 或 http://你的服务器IP如果你想一劳永逸地使用HTTPS也可以在这里设置为https://...但你需要提前准备好SSL证书可以是自签名证书也可以是Let‘s Encrypt免费证书。Omnibus包内置了Let’s Encrypt自动申请功能只需额外配置几行即可但为了简化初次安装流程我们暂不展开。保存并退出编辑器后运行重配置命令。这个命令会根据/etc/gitlab/gitlab.rb中的设置生成所有服务的实际运行配置并启动它们。# 执行重配置这个过程会比较长5-15分钟因为它要编译配置、设置数据库、生成密钥等。 sudo gitlab-ctl reconfigure请耐心等待命令执行完成。当你看到类似“gitlab Reconfigured!”的提示时就表示成功了。4.3 获取初始密码并登录GitLab安装完成后会为默认的root管理员账户生成一个随机密码这个密码存储在/etc/gitlab/initial_root_password文件中并且24小时后会自动删除。# 查看初始root密码 sudo cat /etc/gitlab/initial_root_password复制输出的密码然后打开浏览器访问你设置的external_url例如http://gitlab.yourcompany.com。使用用户名root和刚才复制的密码登录。登录后第一件事立即修改root用户的密码点击右上角用户头像 - “Edit profile” - 左侧菜单 “Password”修改密码。4.4 基础安全与优化设置可选但建议登录后建议进行几项基础设置关闭用户自助注册对于内部使用的GitLab通常不需要开放注册。进入 “Admin Area”管理区域左下角扳手图标 - “Settings” - “General” - 展开 “Sign-up restrictions” - 取消勾选 “Sign-up enabled”。配置邮箱服务器为了让GitLab能发送重置密码、通知等邮件需要配置SMTP。这步稍复杂需要你有可用的邮箱服务如企业邮箱、SendGrid等。可以在/etc/gitlab/gitlab.rb中搜索gitlab_rails[smtp_*]进行配置然后再次sudo gitlab-ctl reconfigure。创建普通用户和项目不要一直使用root账户。创建一个属于你自己的普通账户并赋予管理员权限如果需要然后用这个账户创建项目、组开始你的协作之旅。5. 深度汉化实战不仅仅是替换文字GitLab的汉化本质上是替换其前端界面中的英文字符串文件。社区有热心的开发者将这部分工作做成了补丁。我们将使用一个广泛流传的汉化方案。5.1 汉化方案选择与原理目前主流的汉化方法是使用xhang/gitlab的汉化补丁。其原理是在GitLab的源代码中所有界面文字都存储在.yml或.po格式的本地化文件中。汉化补丁就是将这些文件替换为翻译好的中文版本。由于GitLab版本更新频繁汉化补丁通常针对特定的GitLab版本。因此汉化前务必确认你的GitLab版本并找到对应版本的汉化补丁版本不匹配会导致界面错乱甚至功能异常。5.2 汉化操作步骤详解假设我们安装的GitLab版本是16.9.1。汉化过程需要在服务器上操作。第一步停止GitLab服务为了避免在替换文件时产生冲突我们先停止相关服务。sudo gitlab-ctl stop unicorn sudo gitlab-ctl stop sidekiq sudo gitlab-ctl stop nginx # 也可以使用一条命令停止所有服务但停止核心的几个即可 # sudo gitlab-ctl stop第二步备份原始文件至关重要这是必须的步骤如果汉化出现问题我们可以迅速回滚。# 创建一个备份目录 sudo mkdir -p /var/opt/gitlab/backups/i18n # 备份GitLab自带的本地化文件目录 sudo cp -r /opt/gitlab/embedded/service/gitlab-rails/locale /var/opt/gitlab/backups/i18n/locale.original.$(date %F)第三步下载对应版本的汉化补丁我们需要找到16.9.1版本对应的汉化补丁。通常汉化项目会提供不同版本的发布包。我们可以从GitHub等代码托管平台获取。# 进入临时目录 cd /tmp # 下载汉化包。注意以下URL是示例你需要根据实际情况找到正确的下载链接。 # 例如可以从 https://gitlab.com/xhang/gitlab/-/releases 查看是否有对应版本的补丁 # 这里假设我们下载了一个名为 gitlab-16-9-1-zh.tar.gz 的包 sudo wget -O gitlab-16-9-1-zh.tar.gz [实际的汉化包下载链接] # 解压汉化包 sudo tar -xzf gitlab-16-9-1-zh.tar.gz第四步应用汉化补丁解压后汉化包里通常有一个locale/目录里面就是翻译好的中文文件zh-CN或zh_HANS。我们需要用它们覆盖GitLab原有的文件。# 复制汉化文件覆盖原始文件 # 请确认解压出的目录结构假设汉化文件在 /tmp/gitlab-16-9-1-zh/locale/ sudo cp -rf /tmp/gitlab-16-9-1-zh/locale/* /opt/gitlab/embedded/service/gitlab-rails/locale/ # 设置正确的文件权限和所有权GitLab服务通常以git用户运行 sudo chown -R git:git /opt/gitlab/embedded/service/gitlab-rails/locale第五步清理缓存并重启服务文件替换后需要清除GitLab的缓存让新语言生效。# 清理缓存 sudo gitlab-rake cache:clear sudo gitlab-rake assets:clean sudo gitlab-rake assets:precompile # 重新启动之前停止的服务 sudo gitlab-ctl start unicorn sudo gitlab-ctl start sidekiq sudo gitlab-ctl start nginx # 或者直接启动所有服务 # sudo gitlab-ctl start5.3 验证汉化效果与问题排查完成以上步骤后刷新浏览器中的GitLab页面。登录后进入用户设置右上角头像 - “Settings”在 “Preferences” 选项卡中找到 “Language”将其从 “English” 更改为 “简体中文”。保存后整个界面应该就变成中文了。常见问题与排查界面部分英文/部分中文这通常是汉化包版本与GitLab版本不完全匹配或者某些新增功能尚未翻译。可以尝试寻找更新版本的汉化包或者接受部分英文的存在。界面错乱或功能异常这很可能是汉化包版本严重不匹配破坏了某些关键文件。立即回滚使用第二步的备份sudo rm -rf /opt/gitlab/embedded/service/gitlab-rails/locale sudo cp -r /var/opt/gitlab/backups/i18n/locale.original.[日期] /opt/gitlab/embedded/service/gitlab-rails/locale sudo chown -R git:git /opt/gitlab/embedded/service/gitlab-rails/locale sudo gitlab-ctl restart切换语言后无变化尝试强制刷新浏览器缓存CtrlF5或者清理浏览器Cookie后重新登录。6. 生产环境进阶配置与优化安装和汉化只是第一步。要让GitLab在生产环境中稳定、高效、安全地运行还需要进行一些关键配置。6.1 配置HTTPS与自动续期证书使用HTTP是不安全的所有流量包括密码都是明文传输。我们必须启用HTTPS。Omnibus GitLab内置了Nginx和自动获取Let‘s Encrypt证书的功能配置起来非常方便。编辑/etc/gitlab/gitlab.rb# 1. 将 external_url 改为 https external_url https://gitlab.yourcompany.com # 2. 开启Lets Encrypt自动证书管理 letsencrypt[enable] true letsencrypt[contact_emails] [adminyourcompany.com] # 设置联系邮箱 letsencrypt[auto_renew] true letsencrypt[auto_renew_hour] 12 # 自动续期的时间小时 letsencrypt[auto_renew_minute] 30 letsencrypt[auto_renew_day_of_month] */7 # 每7天尝试续期一次 # 3. 重定向所有HTTP流量到HTTPS可选但推荐 nginx[redirect_http_to_https] true保存后运行sudo gitlab-ctl reconfigure。第一次运行会尝试从Let‘s Encrypt申请证书请确保你的域名gitlab.yourcompany.com的DNS记录已正确指向服务器公网IP并且服务器的80和443端口能从公网访问。申请成功后证书会自动配置到Nginx中。6.2 配置外部数据库与Redis高级默认安装使用了内嵌的PostgreSQL和Redis。对于大型实例或希望统一管理数据库的情况可以迁移到外部数据库。这步操作复杂且有风险务必在测试环境充分验证并做好备份。主要步骤包括在外部服务器上安装并配置PostgreSQL/Redis。在/etc/gitlab/gitlab.rb中注释掉内嵌服务配置并添加指向外部服务的配置。使用gitlab-ctl reconfigure停止内嵌服务但不会自动迁移数据。需要手动从内嵌数据库导出数据再导入到外部数据库。这是一个专业运维操作官方文档有详细指南但非必需不建议新手改动。6.3 性能调优与监控GitLab运行后可以通过以下命令监控其状态# 查看所有服务状态 sudo gitlab-ctl status # 查看实时日志按CtrlC退出 sudo gitlab-ctl tail # 查看特定服务日志如postgresql sudo gitlab-ctl tail postgresql如果发现服务器响应慢可以从以下几个方面排查内存不足使用htop或free -h查看。可以考虑增加Swap空间或者升级服务器配置。Sidekiq队列堆积Sidekiq是处理后台任务如发邮件、CI流水线的服务。如果任务过多会导致界面卡顿。可以进入管理区域 - “Monitoring” - “Background Jobs” 查看队列情况。数据库优化对于项目、用户数量很大的实例可能需要数据库索引优化。可以启用慢查询日志进行分析。6.4 备份与恢复策略定期备份是生命线Omnibus GitLab提供了简单的备份命令# 执行备份备份文件会默认存储在 /var/opt/gitlab/backups/ 目录下文件名如 1712345678_2024_04_05_16.9.1_gitlab_backup.tar sudo gitlab-backup create这个备份包含了数据库、仓库、上传文件等几乎所有数据但不包含配置文件。因此你还需要手动备份两个关键配置文件sudo cp /etc/gitlab/gitlab.rb /var/opt/gitlab/backups/ sudo cp /etc/gitlab/gitlab-secrets.json /var/opt/gitlab/backups/ # 这个文件包含加密密钥丢失会导致两步验证等数据无法解密恢复备份确保新服务器的GitLab版本与备份文件版本完全一致。停止相关服务sudo gitlab-ctl stop puma; sudo gitlab-ctl stop sidekiq。恢复备份文件sudo gitlab-backup restore BACKUP备份文件名前缀注意不带_gitlab_backup.tar后缀。恢复配置文件将备份的gitlab.rb和gitlab-secrets.json复制回/etc/gitlab/。重配置并重启sudo gitlab-ctl reconfigure sudo gitlab-ctl restart。7. 日常维护与升级指南GitLab社区版迭代很快定期升级可以获取新功能和安全补丁。7.1 小版本升级如16.9.1 - 16.9.2小版本升级同一大版本下的次要版本通常比较安全。Omnibus包升级很简单# 1. 备份重要的事情说三遍 sudo gitlab-backup create # 2. 停止服务非必须但推荐 sudo gitlab-ctl stop # 3. 下载新版本的.deb包例如16.9.2 cd /tmp wget https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu/pool/focal/main/g/gitlab-ce/gitlab-ce_16.9.2-ce.0_amd64.deb # 4. 安装新包这会自动升级 sudo dpkg -i gitlab-ce_16.9.2-ce.0_amd64.deb # 5. 重新配置并启动 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart7.2 大版本升级如16.x - 17.x大版本升级可能存在不兼容的变更。务必先查看官方升级文档通常会有特殊的升级路径要求例如不能跨大版本升级需要按顺序升级。同样备份是第一步。升级后汉化包很可能失效需要等待对应新版本的汉化包发布后再重新应用汉化流程。7.3 汉化包的升级当GitLab升级后你需要等待社区发布对应新版本的汉化包。重复第5章的汉化步骤停止服务 - 备份当前locale - 下载新汉化包 - 覆盖文件 - 重启服务。如果新版本汉化包未发布你可能需要暂时使用英文界面或者尝试手动合并部分汉化文件不推荐容易出错。8. 常见问题排查与实战心得根据我多次部署的经验下面这些问题是最高频遇到的我把它们整理成表方便你快速定位。问题现象可能原因排查与解决步骤访问http://服务器IP显示502错误1. GitLab服务未完全启动。2. 内存不足导致PumaWeb服务器启动失败。3. 端口冲突。1. 运行sudo gitlab-ctl status查看哪些服务是down状态。2. 运行sudo gitlab-ctl tail查看日志重点关注unicorn或puma的日志。3. 检查内存free -h考虑增加Swapsudo dd if/dev/zero of/swapfile bs1M count2048 sudo mkswap /swapfile sudo swapon /swapfile。4. 检查80端口是否被占用sudo ss -tulpn | grep :80。gitlab-ctl reconfigure运行极慢或卡住1. 服务器DNS解析问题无法连接外部资源。2. 下载包或证书时网络超时。1. 检查/etc/resolv.conf确保DNS服务器设置正确如8.8.8.8。2. 可以尝试在/etc/gitlab/gitlab.rb中设置letsencrypt[enable] false先跳过证书申请。3. 查看具体卡在哪一步打开另一个终端运行sudo tail -f /var/log/gitlab/reconfigure/*.log。推送代码时提示“HTTP Basic: Access denied”1. 账号密码错误。2. 如果使用SSH可能是SSH密钥未添加或代理问题。3. 项目权限不足。1. 确认用户名密码或在GitLab网页端生成一个“Access Token”代替密码使用。2. 对于SSH运行ssh -T git你的gitlab服务器测试连接将本地~/.ssh/id_rsa.pub内容添加到GitLab用户设置的SSH Keys中。3. 确认你在项目中有推送权限。汉化后界面出现乱码或方框服务器或客户端缺少中文字体支持。在服务器上安装中文字体包sudo apt install -y fonts-wqy-microhei fonts-wqy-zenhei然后重启GitLab服务。发送邮件失败SMTP配置不正确。1. 检查/etc/gitlab/gitlab.rb中SMTP配置的每一项地址、端口、用户名、密码、认证方式。2. 运行sudo gitlab-rails console进入控制台尝试发送测试邮件Notify.test_email(接收邮箱, 测试标题, 测试正文).deliver_now观察报错信息。3. 查看邮件日志sudo gitlab-ctl tail postfix如果使用内置Postfix。磁盘空间告急仓库数据、Docker镜像、备份文件、日志文件占用过多。1. 清理旧的备份文件sudo rm /var/opt/gitlab/backups/旧备份文件.tar。2. 设置日志轮转在/etc/gitlab/gitlab.rb中配置logrotate。3. 对于Docker镜像仓库如果启用进入管理区域 - “Admin” - “Dependency Proxy” 或 “Container Registry” 清理未使用的镜像。几点个人心得测试环境先行任何重要的配置变更如大版本升级、外部数据库迁移务必先在克隆的生产环境的测试服务器上操作一遍。文档是你的朋友遇到复杂问题第一个去处是 官方文档 搜索错误信息往往能找到解决方案。善用日志sudo gitlab-ctl tail是你排查问题的瑞士军刀。学会从日志中寻找ERROR或FATAL级别的信息。社区力量在 GitLab Forum 或相关技术社区搜索你遇到的问题很可能别人已经遇到并解决了。关于汉化对于生产环境如果团队英文能力尚可我有时会建议先使用英文界面一段时间。这能让你更熟悉原生术语方便查阅英文文档。当团队稳定后再根据需求决定是否汉化这样可以避免因汉化包更新延迟而带来的维护成本。
