1. 从零到一为什么你的团队需要一个自托管的GitLab如果你正在带领一个技术团队或者你是一个独立开发者你大概率已经习惯了使用GitHub、Gitee这类托管平台。它们开箱即用省心省力。但当你开始考虑代码资产的安全性、CI/CD流程的深度定制、或者仅仅是希望将开发工具链完全掌握在自己手中时自托管一个GitLab服务器就成了一个绕不开的选项。我经历过从公有云托管服务迁移到自建GitLab的全过程这不仅仅是换一个工具更是对团队研发流程和基础设施掌控力的一次升级。GitLab不仅仅是一个Git仓库管理器。它是一个覆盖了从项目规划、源代码管理、持续集成、持续部署到监控的完整DevOps平台。选择自托管意味着你可以将这套强大的工具链部署在你信任的服务器上无论是公司内网的物理机还是你购买的云服务器。数据完全私有网络访问可控所有插件和集成的选择权都交还给了你。对于中小团队或对代码保密性有严格要求的企业项目自建GitLab几乎是必选项。当然天下没有免费的午餐。自托管带来了控制权也带来了维护成本。你需要自己负责服务器的运维、GitLab版本的升级、数据备份与恢复。这篇内容就是基于我多次在生产环境部署和运维GitLab的经验为你梳理的一份从服务器准备、安装、配置到日常使用的全流程指南。我会尽量避开官方文档式的平铺直叙而是聚焦在实际操作中那些容易踩坑的环节和提升效率的技巧。2. 安装前的关键决策选择最适合你的部署方式在真正执行安装命令之前有几个关键的决策点需要你根据自身情况想清楚。选错了路径后期可能会面临迁移的麻烦。GitLab官方提供了多种安装方式我们主要讨论最常见的两种使用官方Omnibus包和采用Docker容器化部署。2.1 Omnibus包一站式安装适合大多数场景Omnibus包是GitLab官方最推荐的方式尤其对于初次部署和追求稳定性的生产环境。你可以把它理解为一个“全家桶”。它不仅仅包含了GitLab核心的Ruby on Rails应用还捆绑了所有必需的依赖NginxWeb服务器、PostgreSQL数据库、Redis缓存和队列、Prometheus监控等。安装过程就是下载一个.deb对于Ubuntu/Debian或.rpm对于CentOS/RHEL包然后运行安装命令。为什么选择它最大的优点是省心和官方强支持。所有组件都由GitLab团队预先配置好能保证最佳的兼容性和性能。升级也异常简单直接安装新版本的包即可。它的配置文件集中在一个地方通常是/etc/gitlab/gitlab.rb管理起来非常直观。如果你的服务器是纯净的Linux系统并且你希望快速获得一个“开箱即用”、易于维护的GitLab实例Omnibus是不二之选。需要注意的坑Omnibus包对系统资源有“独占”倾向。它会使用自己内置的Nginx、PostgreSQL这可能会和你系统上已有的同名服务冲突端口占用。通常的解决方法是在安装前确保80、443、22等端口没有被其他程序占用或者安装后通过修改gitlab.rb来调整端口。另外它占用的磁盘和内存相对较多因为包含了全套组件。2.2 Docker部署灵活与隔离适合快速体验和特定环境使用Docker Compose部署GitLab是另一种越来越流行的方式。它通过容器技术将GitLab及其所有依赖打包在一个隔离的环境中运行。为什么选择它核心优势是隔离性和可移植性。你可以在任何安装了Docker的机器上包括你的本地开发机快速拉起一个GitLab实例进行测试而不用担心污染主机环境。清理起来也极其方便直接删除容器和镜像即可。对于想在Kubernetes等容器编排平台上部署GitLab的团队这也是必经之路。此外你可以更灵活地选择使用外部的数据库如云数据库RDS或缓存服务。需要权衡的点Docker部署增加了复杂性。你需要熟悉Docker和Docker Compose的基本操作。数据持久化需要你显式地管理数据卷Volume备份和恢复流程与Omnibus方式不同。性能上由于多了一层容器抽象可能会有极细微的损耗但对于中小规模团队通常感知不到。最大的挑战在于一些高级的网络配置、集成第三方服务如SMTP邮件服务器时需要理解容器内外的网络联通配置起来比Omnibus稍显繁琐。我的建议对于生产环境或长期使用的团队服务器我强烈推荐使用Omnibus包安装。它的稳定性和可维护性经过了大量实践检验。Docker方式更适合于开发测试、短期项目、或者你的基础设施已经全面容器化的场景。接下来我将以最经典的Omnibus包在Ubuntu 22.04 LTS上的安装为例展开详细步骤。3. 步步为营Ubuntu系统下Omnibus GitLab安装与初始化详解假设你已经拥有一台满足最低配置推荐至少4核CPU4GB内存100GB存储的Ubuntu 22.04服务器并拥有root或sudo权限。我们将一步步完成安装和初次配置。3.1 系统准备与依赖安装首先通过SSH连接到你的服务器。一个好的习惯是在安装任何新服务前更新系统包列表并升级现有软件。sudo apt update sudo apt upgrade -y安装一些基础工具它们在后续的问题排查中会很有用。sudo apt install -y curl ca-certificates openssh-server接下来我们需要为GitLab配置一个可靠的邮件服务器SMTP用于发送用户注册、密码重置等重要通知。这是安装后最容易被忽略但一旦出问题又非常棘手的环节。你可以使用公司现有的邮件服务器或者使用第三方服务如SendGrid、Mailgun等。这里以配置系统使用sendmail或外部SMTP为例但更佳实践是在GitLab配置文件中直接指定。我们稍后会做。3.2 添加GitLab官方仓库并安装这是关键一步通过添加官方仓库我们可以用包管理器安装并且未来能方便地接收安全更新和版本升级。下载并信任GitLab的GPG密钥用于验证软件包的完整性。curl -fsSL https://packages.gitlab.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/gitlab-archive-keyring.gpg根据你的系统添加对应的软件源。对于Debian/Ubuntuecho deb [signed-by/usr/share/keyrings/gitlab-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/gitlab_gitlab-ce.list注意$(lsb_release -cs)会自动获取你的系统代号如jammy。确保这个代号被GitLab官方仓库支持。更新本地包索引并安装GitLab社区版CE。sudo apt update sudo apt install gitlab-ce安装过程会持续几分钟它会自动下载并设置好所有捆绑的组件。3.3 关键配置让GitLab认识“自己”安装完成后不要急于启动。我们需要先编辑GitLab的主配置文件/etc/gitlab/gitlab.rb。这个文件内容很多但大部分都被注释掉了。我们只需要修改最关键的几项。使用你熟悉的编辑器如vim或nano打开它sudo vim /etc/gitlab/gitlab.rb第一项也是最重要的外部访问URL。找到external_url这一行。它定义了用户访问你这个GitLab实例的完整地址。如果你有域名就配置成域名如https://gitlab.yourcompany.com如果暂时没有就用服务器的公网IP地址如http://your-server-ip。请务必根据实际情况修改。external_url http://your-server-ip # 或 https://gitlab.yourcompany.com注意如果你打算后期配置HTTPS这里可以先写HTTP地址后续在配置SSL证书后再修改为HTTPS并重配置。但最佳实践是一开始就规划好。第二项配置邮件服务器SMTP。搜索gitlab_rails[smtp_enable]相关的配置块。取消注释并修改成你的邮件服务商信息。以下是一个使用Gmail SMTP的示例需开启Gmail的“应用专用密码”gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.gmail.com gitlab_rails[smtp_port] 587 gitlab_rails[smtp_user_name] your-emailgmail.com gitlab_rails[smtp_password] your-app-specific-password gitlab_rails[smtp_domain] gmail.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] false gitlab_rails[gitlab_email_from] your-emailgmail.com gitlab_rails[gitlab_email_reply_to] noreplygmail.com警告不建议使用个人邮箱的主密码务必使用“应用专用密码”或OAuth2令牌。对于生产环境更推荐使用企业邮件服务器或专业的邮件发送服务如SendGrid。第三项可选如果你需要调整默认端口。例如服务器80端口已被占用你可以修改Nginx监听端口nginx[listen_port] 8080 # 将HTTP端口改为8080保存并退出编辑器。3.4 应用配置并启动GitLab配置修改完成后需要让GitLab重新加载配置。这个命令会根据gitlab.rb文件生成所有组件的实际配置文件并重启相关服务。sudo gitlab-ctl reconfigure这个过程会比较长可能会持续5-10分钟屏幕上会滚动大量输出信息显示它在配置什么服务。请耐心等待其完成。完成后使用以下命令检查GitLab各服务的运行状态sudo gitlab-ctl status你应该看到run:状态的一系列服务如nginxpostgresqlredisgitlab-workhorse等且状态为ok。3.5 初次登录与安全加固现在打开浏览器访问你配置的external_url例如http://your-server-ip。首次访问会强制你设置管理员root账户的密码。设置root密码输入一个足够强壮的密码并确认。记住这个root是GitLab的超级管理员账户不是系统root。使用root登录设置成功后使用用户名root和你刚设置的密码登录。关闭开放注册重要登录后点击右上角头像 -Admin Area管理区域。在左侧边栏找到Settings-General展开Sign-up restrictions。强烈建议在初始化后立即取消勾选Sign-up enabled除非你希望任何人都能注册。你可以通过管理员手动创建用户或配置LDAP等外部认证。配置HTTPS强烈推荐对于生产环境必须启用HTTPS。你可以使用Let‘s Encrypt的免费证书Omnibus GitLab内置了支持。在/etc/gitlab/gitlab.rb中将external_url改为https://开头并添加以下配置letsencrypt[enable] true letsencrypt[contact_emails] [adminyourcompany.com] # 用于接收证书过期提醒然后再次运行sudo gitlab-ctl reconfigure。GitLab会自动为你申请和配置证书。4. 日常使用核心功能与高效技巧安装配置只是开始如何高效地使用GitLab才是关键。下面我分享几个超越基础克隆推送的核心功能和技巧。4.1 项目管理与分支策略实战创建新项目后你会面临分支策略的选择。GitLab Flow 是一种结合了Git Flow和GitHub Flow优点的实用策略我团队一直在用。主分支main/master代表可部署到生产环境的代码。始终保持稳定。功能分支feature/*从main拉取用于开发新功能。开发完成后向main发起合并请求Merge Request MR。发布分支release-*当main积累了一批功能准备发布时从main拉取一个release-1.0分支。在此分支上只做Bug修复修复后同时合并回main和release分支。发布时用该分支打标签。紧急修复分支hotfix/*从生产环境对应的标签拉取修复后合并回main和当前的release分支。在GitLab中合并请求MR是协作的核心。创建MR时务必填写清晰的标题和描述使用模板更好。描述里应说明做了什么、为什么做、如何测试。充分利用“Assignee”负责人、“Reviewer”评审者、“Milestone”里程碑和“Labels”标签来管理流程。4.2 内建CI/CD.gitlab-ci.yml入门到精通这是GitLab的王牌功能。你只需要在项目根目录创建一个名为.gitlab-ci.yml的文件定义流水线阶段和任务GitLab Runner一个独立的进程就会自动执行。一个最简单的例子构建一个Node.js应用并运行测试# .gitlab-ci.yml stages: - install - test - build cache: # 缓存node_modules加速后续任务 paths: - node_modules/ install_dependencies: stage: install script: - npm install only: - main # 仅在main分支触发 - merge_requests # 以及在MR时触发 run_tests: stage: test script: - npm test build_project: stage: build script: - npm run build artifacts: # 将构建产物如dist文件夹保存下来供后续阶段或下载 paths: - dist/关键技巧使用cache和artifactscache用于加速重复性任务如安装依赖artifacts用于在不同任务间传递构建结果如将编译好的包传递给部署任务。利用only和except规则精细控制流水线在什么分支、什么标签下触发。例如only: /^release-.*$/表示只在release-开头的分支上运行。配置Runner安装GitLab时已经有一个“共享Runner”在运行通过gitlab-runner服务。对于特定项目或有特殊需求如需要Docker-in-Docker你可以注册专属的Runner。查看Runner状态sudo gitlab-ctl status gitlab-runner。4.3 容器镜像仓库无缝对接你的Docker镜像GitLab内置了一个私有的Docker镜像仓库Container Registry。这意味着你可以在CI/CD流水线中直接构建Docker镜像并推送到这个内置仓库无需依赖Docker Hub或其他第三方服务。启用很简单默认就是开启的地址是your-gitlab-server:5050。在CI中使用的典型步骤build_and_push: stage: build image: docker:latest # 使用docker镜像 services: - docker:dind # 运行Docker in Docker服务 variables: DOCKER_DRIVER: overlay2 IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA # 使用GitLab内置变量 script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG注意dindDocker in Docker模式需要特权在共享Runner上可能被禁用。你可能需要配置自己的Runner并开启特权模式或者使用更安全的kaniko等工具构建镜像。4.4 运维与监控保持你的GitLab健康运行自托管意味着你需要承担运维责任。以下是几个日常命令和监控要点常用管理命令sudo gitlab-ctl start/stop/restart启动/停止/重启所有服务。sudo gitlab-ctl reconfigure应用配置文件更改。sudo gitlab-rake gitlab:check运行一个全面的健康检查会给出很多有用的建议。sudo gitlab-backup create手动创建备份。备份文件默认存储在/var/opt/gitlab/backups/。备份策略必须定期备份最佳实践是配置自动备份。编辑/etc/gitlab/gitlab.rb可以设置备份保留时长和上传到远程存储如S3gitlab_rails[backup_keep_time] 604800 # 保留7天秒数 gitlab_rails[backup_upload_connection] { provider AWS, region us-east-1, aws_access_key_id YOUR_KEY, aws_secret_access_key YOUR_SECRET } gitlab_rails[backup_upload_remote_directory] my-gitlab-backups然后添加一个cron任务每天凌晨执行备份sudo crontab -e添加一行0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON1监控与日志 GitLab内置了Prometheus和Grafana用于监控。访问http://your-gitlab-server/-/grafana即可查看丰富的仪表盘默认账号/密码admin/admin首次登录需修改。 日志文件位于/var/log/gitlab/目录下例如nginx/gitlab_access.log是访问日志gitlab-rails/production.log是应用日志。排查问题时sudo gitlab-ctl tail命令可以实时查看所有服务的日志尾迹。5. 故障排查安装与使用中的常见问题即使按照步骤操作你也可能会遇到一些问题。这里列举几个我踩过的坑及其解决方法。5.1 502 Whoops, GitLab is taking too much time to respond.这是初次安装后访问时最常见的错误。检查服务状态首先运行sudo gitlab-ctl status看所有服务是否都是run和ok。如果有服务没启动尝试sudo gitlab-ctl restart。检查内存GitLab内存消耗很大。使用free -h查看可用内存。如果内存不足特别是小于4GB服务尤其是Sidekiq可能启动失败。考虑增加服务器交换空间Swap或升级内存。查看日志运行sudo gitlab-ctl tail重点关注unicorn和sidekiq的日志看是否有明显的错误信息。常见原因是端口被占用或数据库连接失败。重新配置有时配置文件有误。可以尝试注释掉gitlab.rb中新加的配置然后运行sudo gitlab-ctl reconfigure和sudo gitlab-ctl restart。5.2 邮件发送失败Password Reset等邮件收不到这通常是因为SMTP配置不正确。检查配置确认/etc/gitlab/gitlab.rb中SMTP配置的每一个参数都正确无误特别是密码应用专用密码、端口和TLS/STARTTLS设置。测试邮件发送进入GitLab Rails控制台进行测试sudo gitlab-rails console在控制台中执行Notify.test_email(your-emailexample.com, Test Subject, Test Body).deliver_now观察控制台输出是否有错误。这能帮你快速定位是配置问题还是网络问题。检查防火墙确保服务器出站流量可以访问你配置的SMTP服务器端口如587或465。5.3 备份与恢复失败备份命令sudo gitlab-backup create执行失败。磁盘空间不足备份文件很大。确保/var/opt/gitlab/backups/目录所在分区有足够空间df -h。权限问题确保备份目录的权限属于git用户。可以运行sudo chown -R git:git /var/opt/gitlab/backups。恢复时版本不匹配切记恢复备份时目标GitLab的版本必须与创建备份时的版本完全相同。升级GitLab前务必先备份恢复时先安装相同版本的GitLab包。5.4 CI/CD流水线卡在“Pending”状态任务一直显示“Pending”没有Runner来执行。检查Runner状态在GitLab管理后台 -Admin Area-Overview-Runners查看是否有活跃的Runner以及它是否被分配给了你的项目。Runner未运行在服务器上执行sudo gitlab-ctl status gitlab-runner确保它是运行状态。如果没有尝试sudo gitlab-ctl start gitlab-runner。Runner标签不匹配在项目CI设置或.gitlab-ci.yml中你可能指定了tags如docker。你需要确保有带有相应标签的Runner在线。在Runner管理页面可以给Runner分配标签。共享Runner被禁用在项目设置 -CI/CD-Runners中检查“Enable shared runners for this project”是否被勾选。自托管GitLab是一个需要持续投入和维护的系统但它带来的自主性、安全性和深度集成能力是公有云服务难以比拟的。从安装到熟练使用你会逐渐建立起对团队整个开发工具链的掌控力。
1. 从零到一为什么你的团队需要一个自托管的GitLab如果你正在带领一个技术团队或者你是一个独立开发者你大概率已经习惯了使用GitHub、Gitee这类托管平台。它们开箱即用省心省力。但当你开始考虑代码资产的安全性、CI/CD流程的深度定制、或者仅仅是希望将开发工具链完全掌握在自己手中时自托管一个GitLab服务器就成了一个绕不开的选项。我经历过从公有云托管服务迁移到自建GitLab的全过程这不仅仅是换一个工具更是对团队研发流程和基础设施掌控力的一次升级。GitLab不仅仅是一个Git仓库管理器。它是一个覆盖了从项目规划、源代码管理、持续集成、持续部署到监控的完整DevOps平台。选择自托管意味着你可以将这套强大的工具链部署在你信任的服务器上无论是公司内网的物理机还是你购买的云服务器。数据完全私有网络访问可控所有插件和集成的选择权都交还给了你。对于中小团队或对代码保密性有严格要求的企业项目自建GitLab几乎是必选项。当然天下没有免费的午餐。自托管带来了控制权也带来了维护成本。你需要自己负责服务器的运维、GitLab版本的升级、数据备份与恢复。这篇内容就是基于我多次在生产环境部署和运维GitLab的经验为你梳理的一份从服务器准备、安装、配置到日常使用的全流程指南。我会尽量避开官方文档式的平铺直叙而是聚焦在实际操作中那些容易踩坑的环节和提升效率的技巧。2. 安装前的关键决策选择最适合你的部署方式在真正执行安装命令之前有几个关键的决策点需要你根据自身情况想清楚。选错了路径后期可能会面临迁移的麻烦。GitLab官方提供了多种安装方式我们主要讨论最常见的两种使用官方Omnibus包和采用Docker容器化部署。2.1 Omnibus包一站式安装适合大多数场景Omnibus包是GitLab官方最推荐的方式尤其对于初次部署和追求稳定性的生产环境。你可以把它理解为一个“全家桶”。它不仅仅包含了GitLab核心的Ruby on Rails应用还捆绑了所有必需的依赖NginxWeb服务器、PostgreSQL数据库、Redis缓存和队列、Prometheus监控等。安装过程就是下载一个.deb对于Ubuntu/Debian或.rpm对于CentOS/RHEL包然后运行安装命令。为什么选择它最大的优点是省心和官方强支持。所有组件都由GitLab团队预先配置好能保证最佳的兼容性和性能。升级也异常简单直接安装新版本的包即可。它的配置文件集中在一个地方通常是/etc/gitlab/gitlab.rb管理起来非常直观。如果你的服务器是纯净的Linux系统并且你希望快速获得一个“开箱即用”、易于维护的GitLab实例Omnibus是不二之选。需要注意的坑Omnibus包对系统资源有“独占”倾向。它会使用自己内置的Nginx、PostgreSQL这可能会和你系统上已有的同名服务冲突端口占用。通常的解决方法是在安装前确保80、443、22等端口没有被其他程序占用或者安装后通过修改gitlab.rb来调整端口。另外它占用的磁盘和内存相对较多因为包含了全套组件。2.2 Docker部署灵活与隔离适合快速体验和特定环境使用Docker Compose部署GitLab是另一种越来越流行的方式。它通过容器技术将GitLab及其所有依赖打包在一个隔离的环境中运行。为什么选择它核心优势是隔离性和可移植性。你可以在任何安装了Docker的机器上包括你的本地开发机快速拉起一个GitLab实例进行测试而不用担心污染主机环境。清理起来也极其方便直接删除容器和镜像即可。对于想在Kubernetes等容器编排平台上部署GitLab的团队这也是必经之路。此外你可以更灵活地选择使用外部的数据库如云数据库RDS或缓存服务。需要权衡的点Docker部署增加了复杂性。你需要熟悉Docker和Docker Compose的基本操作。数据持久化需要你显式地管理数据卷Volume备份和恢复流程与Omnibus方式不同。性能上由于多了一层容器抽象可能会有极细微的损耗但对于中小规模团队通常感知不到。最大的挑战在于一些高级的网络配置、集成第三方服务如SMTP邮件服务器时需要理解容器内外的网络联通配置起来比Omnibus稍显繁琐。我的建议对于生产环境或长期使用的团队服务器我强烈推荐使用Omnibus包安装。它的稳定性和可维护性经过了大量实践检验。Docker方式更适合于开发测试、短期项目、或者你的基础设施已经全面容器化的场景。接下来我将以最经典的Omnibus包在Ubuntu 22.04 LTS上的安装为例展开详细步骤。3. 步步为营Ubuntu系统下Omnibus GitLab安装与初始化详解假设你已经拥有一台满足最低配置推荐至少4核CPU4GB内存100GB存储的Ubuntu 22.04服务器并拥有root或sudo权限。我们将一步步完成安装和初次配置。3.1 系统准备与依赖安装首先通过SSH连接到你的服务器。一个好的习惯是在安装任何新服务前更新系统包列表并升级现有软件。sudo apt update sudo apt upgrade -y安装一些基础工具它们在后续的问题排查中会很有用。sudo apt install -y curl ca-certificates openssh-server接下来我们需要为GitLab配置一个可靠的邮件服务器SMTP用于发送用户注册、密码重置等重要通知。这是安装后最容易被忽略但一旦出问题又非常棘手的环节。你可以使用公司现有的邮件服务器或者使用第三方服务如SendGrid、Mailgun等。这里以配置系统使用sendmail或外部SMTP为例但更佳实践是在GitLab配置文件中直接指定。我们稍后会做。3.2 添加GitLab官方仓库并安装这是关键一步通过添加官方仓库我们可以用包管理器安装并且未来能方便地接收安全更新和版本升级。下载并信任GitLab的GPG密钥用于验证软件包的完整性。curl -fsSL https://packages.gitlab.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/gitlab-archive-keyring.gpg根据你的系统添加对应的软件源。对于Debian/Ubuntuecho deb [signed-by/usr/share/keyrings/gitlab-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/gitlab_gitlab-ce.list注意$(lsb_release -cs)会自动获取你的系统代号如jammy。确保这个代号被GitLab官方仓库支持。更新本地包索引并安装GitLab社区版CE。sudo apt update sudo apt install gitlab-ce安装过程会持续几分钟它会自动下载并设置好所有捆绑的组件。3.3 关键配置让GitLab认识“自己”安装完成后不要急于启动。我们需要先编辑GitLab的主配置文件/etc/gitlab/gitlab.rb。这个文件内容很多但大部分都被注释掉了。我们只需要修改最关键的几项。使用你熟悉的编辑器如vim或nano打开它sudo vim /etc/gitlab/gitlab.rb第一项也是最重要的外部访问URL。找到external_url这一行。它定义了用户访问你这个GitLab实例的完整地址。如果你有域名就配置成域名如https://gitlab.yourcompany.com如果暂时没有就用服务器的公网IP地址如http://your-server-ip。请务必根据实际情况修改。external_url http://your-server-ip # 或 https://gitlab.yourcompany.com注意如果你打算后期配置HTTPS这里可以先写HTTP地址后续在配置SSL证书后再修改为HTTPS并重配置。但最佳实践是一开始就规划好。第二项配置邮件服务器SMTP。搜索gitlab_rails[smtp_enable]相关的配置块。取消注释并修改成你的邮件服务商信息。以下是一个使用Gmail SMTP的示例需开启Gmail的“应用专用密码”gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.gmail.com gitlab_rails[smtp_port] 587 gitlab_rails[smtp_user_name] your-emailgmail.com gitlab_rails[smtp_password] your-app-specific-password gitlab_rails[smtp_domain] gmail.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] false gitlab_rails[gitlab_email_from] your-emailgmail.com gitlab_rails[gitlab_email_reply_to] noreplygmail.com警告不建议使用个人邮箱的主密码务必使用“应用专用密码”或OAuth2令牌。对于生产环境更推荐使用企业邮件服务器或专业的邮件发送服务如SendGrid。第三项可选如果你需要调整默认端口。例如服务器80端口已被占用你可以修改Nginx监听端口nginx[listen_port] 8080 # 将HTTP端口改为8080保存并退出编辑器。3.4 应用配置并启动GitLab配置修改完成后需要让GitLab重新加载配置。这个命令会根据gitlab.rb文件生成所有组件的实际配置文件并重启相关服务。sudo gitlab-ctl reconfigure这个过程会比较长可能会持续5-10分钟屏幕上会滚动大量输出信息显示它在配置什么服务。请耐心等待其完成。完成后使用以下命令检查GitLab各服务的运行状态sudo gitlab-ctl status你应该看到run:状态的一系列服务如nginxpostgresqlredisgitlab-workhorse等且状态为ok。3.5 初次登录与安全加固现在打开浏览器访问你配置的external_url例如http://your-server-ip。首次访问会强制你设置管理员root账户的密码。设置root密码输入一个足够强壮的密码并确认。记住这个root是GitLab的超级管理员账户不是系统root。使用root登录设置成功后使用用户名root和你刚设置的密码登录。关闭开放注册重要登录后点击右上角头像 -Admin Area管理区域。在左侧边栏找到Settings-General展开Sign-up restrictions。强烈建议在初始化后立即取消勾选Sign-up enabled除非你希望任何人都能注册。你可以通过管理员手动创建用户或配置LDAP等外部认证。配置HTTPS强烈推荐对于生产环境必须启用HTTPS。你可以使用Let‘s Encrypt的免费证书Omnibus GitLab内置了支持。在/etc/gitlab/gitlab.rb中将external_url改为https://开头并添加以下配置letsencrypt[enable] true letsencrypt[contact_emails] [adminyourcompany.com] # 用于接收证书过期提醒然后再次运行sudo gitlab-ctl reconfigure。GitLab会自动为你申请和配置证书。4. 日常使用核心功能与高效技巧安装配置只是开始如何高效地使用GitLab才是关键。下面我分享几个超越基础克隆推送的核心功能和技巧。4.1 项目管理与分支策略实战创建新项目后你会面临分支策略的选择。GitLab Flow 是一种结合了Git Flow和GitHub Flow优点的实用策略我团队一直在用。主分支main/master代表可部署到生产环境的代码。始终保持稳定。功能分支feature/*从main拉取用于开发新功能。开发完成后向main发起合并请求Merge Request MR。发布分支release-*当main积累了一批功能准备发布时从main拉取一个release-1.0分支。在此分支上只做Bug修复修复后同时合并回main和release分支。发布时用该分支打标签。紧急修复分支hotfix/*从生产环境对应的标签拉取修复后合并回main和当前的release分支。在GitLab中合并请求MR是协作的核心。创建MR时务必填写清晰的标题和描述使用模板更好。描述里应说明做了什么、为什么做、如何测试。充分利用“Assignee”负责人、“Reviewer”评审者、“Milestone”里程碑和“Labels”标签来管理流程。4.2 内建CI/CD.gitlab-ci.yml入门到精通这是GitLab的王牌功能。你只需要在项目根目录创建一个名为.gitlab-ci.yml的文件定义流水线阶段和任务GitLab Runner一个独立的进程就会自动执行。一个最简单的例子构建一个Node.js应用并运行测试# .gitlab-ci.yml stages: - install - test - build cache: # 缓存node_modules加速后续任务 paths: - node_modules/ install_dependencies: stage: install script: - npm install only: - main # 仅在main分支触发 - merge_requests # 以及在MR时触发 run_tests: stage: test script: - npm test build_project: stage: build script: - npm run build artifacts: # 将构建产物如dist文件夹保存下来供后续阶段或下载 paths: - dist/关键技巧使用cache和artifactscache用于加速重复性任务如安装依赖artifacts用于在不同任务间传递构建结果如将编译好的包传递给部署任务。利用only和except规则精细控制流水线在什么分支、什么标签下触发。例如only: /^release-.*$/表示只在release-开头的分支上运行。配置Runner安装GitLab时已经有一个“共享Runner”在运行通过gitlab-runner服务。对于特定项目或有特殊需求如需要Docker-in-Docker你可以注册专属的Runner。查看Runner状态sudo gitlab-ctl status gitlab-runner。4.3 容器镜像仓库无缝对接你的Docker镜像GitLab内置了一个私有的Docker镜像仓库Container Registry。这意味着你可以在CI/CD流水线中直接构建Docker镜像并推送到这个内置仓库无需依赖Docker Hub或其他第三方服务。启用很简单默认就是开启的地址是your-gitlab-server:5050。在CI中使用的典型步骤build_and_push: stage: build image: docker:latest # 使用docker镜像 services: - docker:dind # 运行Docker in Docker服务 variables: DOCKER_DRIVER: overlay2 IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA # 使用GitLab内置变量 script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG注意dindDocker in Docker模式需要特权在共享Runner上可能被禁用。你可能需要配置自己的Runner并开启特权模式或者使用更安全的kaniko等工具构建镜像。4.4 运维与监控保持你的GitLab健康运行自托管意味着你需要承担运维责任。以下是几个日常命令和监控要点常用管理命令sudo gitlab-ctl start/stop/restart启动/停止/重启所有服务。sudo gitlab-ctl reconfigure应用配置文件更改。sudo gitlab-rake gitlab:check运行一个全面的健康检查会给出很多有用的建议。sudo gitlab-backup create手动创建备份。备份文件默认存储在/var/opt/gitlab/backups/。备份策略必须定期备份最佳实践是配置自动备份。编辑/etc/gitlab/gitlab.rb可以设置备份保留时长和上传到远程存储如S3gitlab_rails[backup_keep_time] 604800 # 保留7天秒数 gitlab_rails[backup_upload_connection] { provider AWS, region us-east-1, aws_access_key_id YOUR_KEY, aws_secret_access_key YOUR_SECRET } gitlab_rails[backup_upload_remote_directory] my-gitlab-backups然后添加一个cron任务每天凌晨执行备份sudo crontab -e添加一行0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON1监控与日志 GitLab内置了Prometheus和Grafana用于监控。访问http://your-gitlab-server/-/grafana即可查看丰富的仪表盘默认账号/密码admin/admin首次登录需修改。 日志文件位于/var/log/gitlab/目录下例如nginx/gitlab_access.log是访问日志gitlab-rails/production.log是应用日志。排查问题时sudo gitlab-ctl tail命令可以实时查看所有服务的日志尾迹。5. 故障排查安装与使用中的常见问题即使按照步骤操作你也可能会遇到一些问题。这里列举几个我踩过的坑及其解决方法。5.1 502 Whoops, GitLab is taking too much time to respond.这是初次安装后访问时最常见的错误。检查服务状态首先运行sudo gitlab-ctl status看所有服务是否都是run和ok。如果有服务没启动尝试sudo gitlab-ctl restart。检查内存GitLab内存消耗很大。使用free -h查看可用内存。如果内存不足特别是小于4GB服务尤其是Sidekiq可能启动失败。考虑增加服务器交换空间Swap或升级内存。查看日志运行sudo gitlab-ctl tail重点关注unicorn和sidekiq的日志看是否有明显的错误信息。常见原因是端口被占用或数据库连接失败。重新配置有时配置文件有误。可以尝试注释掉gitlab.rb中新加的配置然后运行sudo gitlab-ctl reconfigure和sudo gitlab-ctl restart。5.2 邮件发送失败Password Reset等邮件收不到这通常是因为SMTP配置不正确。检查配置确认/etc/gitlab/gitlab.rb中SMTP配置的每一个参数都正确无误特别是密码应用专用密码、端口和TLS/STARTTLS设置。测试邮件发送进入GitLab Rails控制台进行测试sudo gitlab-rails console在控制台中执行Notify.test_email(your-emailexample.com, Test Subject, Test Body).deliver_now观察控制台输出是否有错误。这能帮你快速定位是配置问题还是网络问题。检查防火墙确保服务器出站流量可以访问你配置的SMTP服务器端口如587或465。5.3 备份与恢复失败备份命令sudo gitlab-backup create执行失败。磁盘空间不足备份文件很大。确保/var/opt/gitlab/backups/目录所在分区有足够空间df -h。权限问题确保备份目录的权限属于git用户。可以运行sudo chown -R git:git /var/opt/gitlab/backups。恢复时版本不匹配切记恢复备份时目标GitLab的版本必须与创建备份时的版本完全相同。升级GitLab前务必先备份恢复时先安装相同版本的GitLab包。5.4 CI/CD流水线卡在“Pending”状态任务一直显示“Pending”没有Runner来执行。检查Runner状态在GitLab管理后台 -Admin Area-Overview-Runners查看是否有活跃的Runner以及它是否被分配给了你的项目。Runner未运行在服务器上执行sudo gitlab-ctl status gitlab-runner确保它是运行状态。如果没有尝试sudo gitlab-ctl start gitlab-runner。Runner标签不匹配在项目CI设置或.gitlab-ci.yml中你可能指定了tags如docker。你需要确保有带有相应标签的Runner在线。在Runner管理页面可以给Runner分配标签。共享Runner被禁用在项目设置 -CI/CD-Runners中检查“Enable shared runners for this project”是否被勾选。自托管GitLab是一个需要持续投入和维护的系统但它带来的自主性、安全性和深度集成能力是公有云服务难以比拟的。从安装到熟练使用你会逐渐建立起对团队整个开发工具链的掌控力。
 为深度学习植入「可解释大脑」)
