1. 项目概述为什么选择自建GitLab在团队协作开发中代码仓库是核心资产的管理平台。虽然市面上有众多优秀的SaaS服务但对于许多追求数据自主可控、需要深度定制流程或处于特定网络环境下的团队而言在自有服务器上部署一套私有的GitLab社区版gitlab-ce是一个极具吸引力的选择。它不仅仅是一个Git服务器更是一套集成了代码托管、CI/CD、问题跟踪、Wiki文档等功能的完整DevOps平台。我选择gitlab-ce主要基于几个实际考量首先是成本社区版对中小团队完全免费功能已足够强大其次是可控性所有数据物理存储在自己的服务器上安全策略、备份机制完全自主再者是定制化从仓库权限、合并请求流程到CI/CD流水线都可以根据团队习惯精细调整。当然官方安装包默认是英文界面这对于部分团队成员可能构成使用门槛因此在完成基础安装后进行界面汉化就成了提升团队协作效率的一个必要步骤。本文将基于一台全新的Linux服务器以Ubuntu 22.04 LTS为例手把手带你完成从零开始安装gitlab-ce到应用中文语言包的完整过程。过程中我会穿插讲解关键配置项的作用、安装时可能遇到的“坑”以及汉化的原理和注意事项目标是让你获得一个稳定、可用且符合中文使用习惯的私有GitLab环境。2. 安装环境准备与规划在开始敲命令之前充分的准备工作能避免后续很多麻烦。安装GitLab对服务器有一定的资源要求并且需要规划好访问方式。2.1 服务器资源要求与系统配置GitLab是一个资源消耗相对较大的应用尤其是当用户量增长、CI/CD任务并行时。对于一个小型团队10人左右的初期使用我建议的最低配置如下CPU: 2核以上。这是保证Web界面响应和后台任务处理的基础。内存: 4GB 绝对最低8GB 推荐。内存不足是GitLab运行缓慢甚至崩溃的最常见原因。GitLab的组件如Puma、Sidekiq都比较吃内存。存储: 至少20GB可用空间用于存放操作系统、GitLab软件、仓库数据以及日志。考虑到代码仓库的增长建议预留100GB以上并规划好备份策略。操作系统: 官方支持的主流Linux发行版如Ubuntu、Debian、CentOS/RHEL等。本文以Ubuntu 22.04 LTS为例因为它有长期支持社区资源丰富。注意务必使用一个干净的、新安装的系统环境。如果服务器上已经运行了Nginx、PostgreSQL等服务可能会与GitLab内置的组件Nginx、PostgreSQL产生端口冲突处理起来会比较棘手。对于生产环境强烈建议使用专用服务器或虚拟机。首先我们更新系统并安装一些基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl openssh-server ca-certificates tzdata perl确保SSH服务已启动并设置开机自启因为后续我们主要通过SSH管理服务器和Git克隆推送代码sudo systemctl enable sshd sudo systemctl start sshd2.2 网络与域名规划GitLab需要通过域名访问这不仅是为了好看更是为了功能正常运行如邮件通知中的链接。你需要准备一个域名例如git.yourcompany.com并将其DNS解析指向你的服务器公网IP地址。如果只是在内部网络测试你可以在本地机器的hosts文件Windows在C:\Windows\System32\drivers\etc\hosts Linux/macOS在/etc/hosts中添加一条记录192.168.1.100 gitlab.local这里192.168.1.100是你的服务器内网IPgitlab.local是你自定义的域名。关键点在安装GitLab前你需要明确最终访问它的URL。在安装配置阶段这个URL会被写入GitLab的配置文件后期修改虽然可以但过程相对繁琐。3. GitLab-CE 核心安装流程解析官方提供了多种安装方式如Omnibus包、Docker、源码编译等。对于绝大多数用户我强烈推荐使用Omnibus包安装。它将GitLab所需的所有服务Nginx、PostgreSQL、Redis、Sidekiq等及其依赖打包在一起通过一套统一的工具进行管理极大地简化了安装、升级和运维的复杂度。3.1 通过官方脚本安装Omnibus包Omnibus包的安装非常标准化。我们首先信任并添加GitLab的官方软件仓库。下载并执行安装脚本curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本会自动检测你的系统版本并将GitLab官方的APT仓库源添加到你的系统中。执行安装接下来安装gitlab-ce包。这里有一个非常重要的参数EXTERNAL_URL它定义了你的GitLab实例的访问地址。sudo EXTERNAL_URLhttp://gitlab.local apt install gitlab-ce请将http://gitlab.local替换为你规划好的实际URL例如https://git.yourcompany.com。如果你使用HTTPS后续还需要配置SSL证书。安装过程会持续几分钟它会自动下载并安装GitLab及其所有依赖。3.2 初始配置与管理员密码设置安装完成后我们需要进行一项最重要的初始化配置。重新配置GitLab运行以下命令它会根据你提供的EXTERNAL_URL和其他默认设置生成所有服务的配置文件并启动它们。sudo gitlab-ctl reconfigure这个过程会比较长屏幕上会滚动大量输出信息显示它正在配置PostgreSQL、Redis、Nginx等组件。耐心等待其完成直到出现类似“gitlab Reconfigured!”的提示。获取初始管理员密码GitLab安装后会为默认的root管理员账户生成一个随机密码。这个密码存储在/etc/gitlab/initial_root_password文件中并且24小时后会自动删除。sudo cat /etc/gitlab/initial_root_password记录下输出中的Password字段的值。登录验证打开浏览器访问你设置的EXTERNAL_URL如http://gitlab.local。首次访问可能会稍慢因为服务在完全启动。使用用户名root和刚才查到的密码登录。成功登录后你应该立即做两件事修改root用户密码在用户设置中将密码改为一个强密码并妥善保管。创建普通用户尽量不要直接使用root账户进行日常操作而是创建一个新的普通用户并为其分配管理员权限如果需要。3.3 关键配置文件详解与调优Omnibus包的所有配置都集中在一个文件/etc/gitlab/gitlab.rb。这是一个Ruby语法的配置文件通过修改它并重新运行sudo gitlab-ctl reconfigure来生效。以下是一些初期可能需要关注的配置项外部URL已设置external_url http://gitlab.local邮箱配置GitLab发送用户注册、密码重置等通知邮件必须配置。以SMTP为例这里使用腾讯企业邮箱示例请替换为你自己的信息gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.exmail.qq.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabyourcompany.com gitlab_rails[smtp_password] your_password gitlab_rails[smtp_domain] exmail.qq.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性能调优如果服务器内存较小可以限制GitLab使用的worker进程数但这会影响性能。例如调整PumaWeb服务器和Sidekiq后台任务的并发数puma[worker_processes] 2 # 默认是CPU核数可调小 sidekiq[max_concurrency] 10 # 默认25可调小修改完配置后务必执行sudo gitlab-ctl reconfigure使更改生效并根据需要重启服务sudo gitlab-ctl restart。4. 汉化方案选择与实施细节安装好的GitLab是英文界面。汉化本质上是将前端界面中的英文字符串替换为中文。社区有热心维护者提供汉化补丁包。4.1 汉化补丁的原理与版本匹配汉化补丁通常是一个基于特定GitLab版本代码库的“diff”文件集合它只包含语言文件位于app/assets/localesvendor/assets/locales等目录的更改。应用补丁的过程就是用中文翻译文件覆盖或合并原有的英文文件。最重要的一点汉化补丁的版本必须与你的GitLab-ce版本严格一致版本不匹配会导致部分界面翻译缺失、错位甚至引发前端JavaScript错误导致页面无法正常加载。首先检查你安装的GitLab确切版本sudo gitlab-rake gitlab:env:info | grep “Version”输出类似Version: 16.9.0。请牢记这个版本号。4.2 使用社区汉化包手动汉化目前一个较为知名的汉化项目托管在GitLab上。我们需要手动下载对应版本的汉化包并应用。停止相关服务为了避免在替换文件时产生冲突先停止GitLab的前端服务。sudo gitlab-ctl stop nginx sudo gitlab-ctl stop gitlab-workhorse sudo gitlab-ctl stop puma # 也可以使用一条命令停止所有服务但会影响其他功能 # sudo gitlab-ctl stop下载汉化包我们需要根据查到的版本号下载对应的汉化补丁。假设版本是16.9.0。# 进入临时目录 cd /tmp # 下载对应版本的汉化补丁包版本号需要替换 wget https://gitlab.com/xhang/gitlab/-/archive/16-9-stable-zh/gitlab-16-9-stable-zh.tar.bz2注意汉化包的命名规则可能是16-9-stable-zh对应16.9.0你需要根据实际情况在项目发布页找到正确的包名。如果找不到完全一致的版本可以尝试使用上一个次要版本的汉化包如16.8.x的包用于16.9.0但可能有风险不推荐用于生产环境。解压并应用补丁# 解压下载的包 tar -xjf gitlab-16-9-stable-zh.tar.bz2 # 备份原始的本地化文件目录可选但建议 sudo cp -r /opt/gitlab/embedded/service/gitlab-rails/app/assets/locales /opt/gitlab/embedded/service/gitlab-rails/app/assets/locales.backup # 复制汉化文件覆盖原文件 sudo cp -rf /tmp/gitlab-16-9-stable-zh/app/assets/locales/* /opt/gitlab/embedded/service/gitlab-rails/app/assets/locales/ sudo cp -rf /tmp/gitlab-16-9-stable-zh/vendor/assets/locales/* /opt/gitlab/embedded/service/gitlab-rails/vendor/assets/locales/这里覆盖的是Omnibus包安装的路径。如果是源码安装路径会不同。清理缓存并重启服务汉化文件替换后需要清理GitLab的缓存并重启服务使其生效。# 清理缓存 sudo gitlab-rake cache:clear sudo gitlab-rake assets:clean sudo gitlab-rake assets:precompile # 重新启动之前停止的服务 sudo gitlab-ctl start puma sudo gitlab-ctl start gitlab-workhorse sudo gitlab-ctl start nginx # 或者简单重启所有服务 # sudo gitlab-ctl restart验证汉化效果刷新浏览器中的GitLab页面。绝大部分界面包括菜单、按钮、提示信息都应该变成了中文。登录后你还可以在“用户设置” - “偏好设置”中确认“语言”选项是否为“中文简体”。4.3 汉化过程中的注意事项与陷阱版本鸿沟是最大敌人再次强调务必使用版本完全匹配的汉化包。如果找不到对应版本宁可不汉化也不要使用不匹配的包。备份原文件在执行覆盖操作前备份原始语言文件目录是一个好习惯。如果汉化后出现严重问题可以快速回滚。汉化不完全社区汉化包可能无法覆盖100%的界面尤其是新版本刚发布时一些新增功能的字符串可能还是英文。这是正常现象。企业版功能如果你使用的是GitLab企业版EE部分企业版特有的功能界面社区汉化包可能没有翻译。升级后的处理当你未来升级GitLab版本时汉化会被覆盖界面将恢复英文。你需要重复上述汉化步骤使用与新版本匹配的汉化包重新操作。5. 安装后的必要安全与维护配置安装和汉化只是第一步要让GitLab稳定、安全地运行还需要进行一些基础配置。5.1 防火墙与SSH安全加固确保服务器防火墙只开放必要的端口。GitLab默认使用HTTP80、HTTPS443和SSH22端口。# 假设使用ufwUbuntu sudo ufw allow ssh sudo ufw allow http sudo ufw allow https sudo ufw enable对于SSH建议禁用root直接登录并使用密钥认证# 编辑SSH配置文件 sudo vim /etc/ssh/sshd_config找到并修改PermitRootLogin no PasswordAuthentication no # 禁用密码登录强制使用密钥然后重启SSH服务sudo systemctl restart sshd。在操作前请确保你已添加了SSH公钥到当前用户否则会被锁在服务器外5.2 配置HTTPS访问使用Let‘s Encrypt生产环境必须使用HTTPS。Omnibus包内置了Let‘s Encrypt自动证书申请和续期功能配置非常方便。编辑/etc/gitlab/gitlab.rbexternal_url https://git.yourcompany.com # 必须改为https letsencrypt[enable] true letsencrypt[contact_emails] [adminyourcompany.com] # 接收证书到期提醒的邮箱保存后运行sudo gitlab-ctl reconfigure。在运行过程中GitLab会自动尝试向Let‘s Encrypt申请证书这要求你的域名git.yourcompany.com已经正确解析到服务器公网IP且80/443端口可从公网访问。5.3 设置自动备份数据无价。GitLab提供了简单的备份命令sudo gitlab-backup create备份文件默认存储在/var/opt/gitlab/backups/目录下文件名包含时间戳。为了自动化可以将其加入crontab# 编辑root用户的crontab sudo crontab -e添加一行例如每天凌晨2点备份0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON1重要提示备份命令不包含配置文件你需要手动备份/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json包含数据库加密密钥这两个关键配置文件。恢复时需要它们。6. 常见问题排查与效能优化心得即使按照步骤操作也可能会遇到问题。这里记录几个我踩过的坑和解决方法。6.1 安装与启动故障排查问题gitlab-ctl reconfigure运行失败提示端口冲突。原因服务器上已有其他服务占用了80、8080、9090等GitLab需要使用的端口。排查运行sudo netstat -tlnp查看端口占用情况。解决修改/etc/gitlab/gitlab.rb中冲突服务的端口或停止冲突的第三方服务。例如修改Nginx监听端口nginx[listen_port] 8080。问题Web页面打开502错误。原因通常是Puma应用服务器或GitLab Workhorse没有正常启动。排查查看日志是最快的方式。sudo gitlab-ctl tail puma # 查看Puma日志 sudo gitlab-ctl tail gitlab-workhorse # 查看Workhorse日志 sudo gitlab-ctl status # 查看所有组件状态常见解决内存不足可能导致进程崩溃。尝试增加服务器Swap空间或调整配置降低并发数后重启sudo gitlab-ctl restart puma gitlab-workhorse。问题汉化后页面部分空白或JS错误。原因几乎可以肯定是汉化包版本不匹配导致语言文件结构错误。解决恢复备份的原始语言文件或重新安装GitLab极端情况。严格按照版本号寻找汉化包。6.2 日常运维与性能调优建议监控服务器资源使用htop、df -h等命令定期查看CPU、内存、磁盘使用情况。GitLab日志文件增长很快记得定期清理或配置日志轮转。# 清理GitLab日志谨慎操作 sudo gitlab-ctl logrotate sudo find /var/log/gitlab -name “*.log” -type f -mtime 7 -delete升级策略小版本升级如16.9.0 - 16.9.1通常比较安全。在升级前务必完整备份数据和配置文件。查看官方升级文档了解从当前版本到目标版本的升级路径。有时需要逐级升级不能跳版本。性能瓶颈如果感觉GitLab变慢首先检查内存和磁盘I/O。Sidekiq后台任务队列积压也会导致操作卡顿。可以在管理后台“管理区域” - “监控” - “后台作业”查看Sidekiq队列情况。对于仓库克隆推送慢可能是服务器磁盘IO或网络问题可以考虑将仓库存储目录放到SSD磁盘上。备份恢复测试定期进行的备份一定要做恢复测试可以在一台测试机上模拟恢复流程确保在真正灾难发生时你的备份是有效的。恢复命令大致如下# 停止相关服务 sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq # 恢复备份BACKUP_TIMESTAMP替换为备份文件名中的时间戳 sudo gitlab-backup restore BACKUPBACKUP_TIMESTAMP # 恢复配置文件 sudo cp /path/to/backup/gitlab.rb /etc/gitlab/ sudo cp /path/to/backup/gitlab-secrets.json /etc/gitlab/ # 重新配置并启动 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart经过以上步骤你应该已经拥有了一个完全由自己掌控、界面友好的私有GitLab服务。从安装、汉化到基础运维这个过程涉及了系统管理、网络和应用配置多个方面。最关键的是理解每个步骤背后的目的这样在遇到问题时你才能有的放矢地进行排查。私有化部署给了你最大的灵活性但也意味着你需要承担起维护的责任。定期更新、监控和备份是让这个开发核心资产稳定运行的基石。