GitLab安装配置：从零开始的详细指南与常见问题解答
GitLab安装配置：从零开始的详细指南与常见问题解答
GitLab安装配置的核心问题在于如何成功搭建一个功能完善且稳定运行的GitLab服务器。这通常包括选择合适的安装方式（如Omnibus包、Docker或从源码安装），准备必要的服务器环境（如操作系统、内存、CPU、存储空间），执行安装脚本，并进行基本的网络和用户配置。
一、 GitLab是什么？
GitLab 是一个基于 Web 的 Git 仓库管理工具，提供了从代码托管、版本控制到 CI/CD（持续集成/持续部署）的全套 DevOps 生命周期解决方案。它允许开发者在一个集成的平台上进行代码协作、项目管理、自动化测试和部署，极大地提高了软件开发的效率和质量。
二、 GitLab安装配置前的准备
在开始GitLab的安装配置之前，充分的准备工作至关重要。这不仅能确保安装过程的顺利进行，还能为后续的稳定运行打下坚实基础。
1. 系统要求
GitLab对服务器的硬件和软件有一定的要求。请根据您选择的GitLab版本和预期的用户量来规划服务器资源：
- CPU： 建议至少4个CPU核心，对于大型或高并发场景，建议8核或更多。
- 内存： 至少8GB RAM。对于生产环境，建议16GB或更高。
- 存储： 至少20GB可用磁盘空间用于安装GitLab本身，但考虑到代码仓库、日志和数据库等数据，建议预留至少100GB或更多。SSD硬盘会显著提升性能。
- 操作系统： 支持主流的Linux发行版，如Ubuntu (LTS版本推荐), CentOS/RHEL (较新版本推荐), Debian。Windows Server 不直接支持 Omnibus 安装。
- 网络： 服务器需要有公网IP地址或内部可访问的IP地址，并且确保必要的端口（如HTTP 80, HTTPS 443, SSH 22）是开放的。
2. 软件依赖
GitLab的安装方式会影响依赖项的处理。使用Omnibus包安装时，大部分依赖项会被打包，但仍需确保系统具备基础的环境。
- SSH 服务器： 用于Git协议的访问。
- Postfix 或 Sendmail： 用于发送邮件通知（如注册确认、代码合并请求通知等）。
- curl, policycoreutils-python, openssh-server, perl, postfix, systemd, ufw： 这些是Omnibus安装在Debian/Ubuntu或CentOS/RHEL上可能需要的包。
三、 GitLab安装配置方法
GitLab提供了多种安装方式，其中Omnibus包是官方推荐且最便捷的方式，它将GitLab及其所有依赖项打包在一起，大大简化了安装过程。
1. 使用Omnibus包安装（推荐）
这是最常见且最推荐的安装方式，适用于大多数场景。
a. 在Ubuntu/Debian系统上安装
- 更新系统包列表：
sudo apt update sudo apt upgrade -y - 安装必要的依赖项：
sudo apt install -y curl openssh-server ca-certificates postfix在安装Postfix时，会提示您进行一些配置，通常选择“Internet Site”并填写您的域名即可。
- 添加GitLab的APT仓库：
首先，下载并安装GitLab的GPG密钥：
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash注意：如果您需要社区版（CE），请将 `gitlab-ee` 替换为 `gitlab-ce`。
- 安装GitLab软件包：
设置GitLab的外部URL。请将 `your.gitlab.com` 替换为您实际的域名或IP地址。
sudo EXTERNAL_URL="http://your.gitlab.com" apt install gitlab-ee注意：如果您需要HTTPS，建议先安装Nginx，配置好SSL证书，再设置 `EXTERNAL_URL` 为 `https://your.gitlab.com`。
- 启动并启用GitLab服务：
安装完成后，GitLab会自动启动。您可以通过以下命令检查状态：
sudo gitlab-ctl status如果需要手动启动/停止/重启：
sudo gitlab-ctl start sudo gitlab-ctl stop sudo gitlab-ctl restart
b. 在CentOS/RHEL系统上安装
- 安装必要的依赖项：
sudo yum install -y curl policycoreutils-python openssh-server postfix sudo systemctl enable postfix sudo systemctl start postfix - 添加GitLab的YUM仓库：
首先，下载并安装GitLab的RPM包，它会包含仓库配置：
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh | sudo bash注意：如果您需要社区版（CE），请将 `gitlab-ee` 替换为 `gitlab-ce`。
- 安装GitLab软件包：
设置GitLab的外部URL。请将 `your.gitlab.com` 替换为您实际的域名或IP地址。
sudo EXTERNAL_URL="http://your.gitlab.com" yum install gitlab-ee注意：如果您需要HTTPS，建议先安装Nginx，配置好SSL证书，再设置 `EXTERNAL_URL` 为 `https://your.gitlab.com`。
- 启动并启用GitLab服务：
安装完成后，GitLab会自动启动。您可以通过以下命令检查状态：
sudo gitlab-ctl status如果需要手动启动/停止/重启：
sudo gitlab-ctl start sudo gitlab-ctl stop sudo gitlab-ctl restart - 防火墙配置 (CentOS/RHEL)：
如果服务器开启了防火墙 (firewalld)，需要允许HTTP和HTTPS流量：
sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --permanent --add-service=https sudo firewall-cmd --reload
2. 使用Docker安装
Docker是一种快速部署GitLab的流行方式，尤其适合测试和开发环境。
- 安装Docker和Docker Compose：
请参考Docker官方文档安装Docker和Docker Compose。
- 创建Docker Compose配置文件：
创建一个名为 `docker-compose.yml` 的文件，内容如下（以GitLab CE为例）：
version: 3.6 services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab restart: always hostname: your.gitlab.com environment: GITLAB_OMNIBUS_CONFIG: | external_url http://your.gitlab.com gitlab_rails[gitlab_shell_ssh_port] = 22 # Add other GitLab configurations here, e.g.: # gitlab_rails[smtp_enable] = true # gitlab_rails[smtp_address] = "smtp.example.com" # gitlab_rails[smtp_port] = 587 # gitlab_rails[smtp_user_name] = "[email protected]" # gitlab_rails[smtp_password] = "your_smtp_password" # gitlab_rails[smtp_domain] = "smtp.example.com" # gitlab_rails[gitlab_email_from] = "[email protected]" ports: - 80:80 - 443:443 - 22:22 # For SSH access to Git repositories volumes: - ./config:/etc/gitlab - ./logs:/var/log/gitlab - ./data:/var/opt/gitlab shm_size: 256m # Required for PostgreSQL 12+请将 `your.gitlab.com` 替换为您实际的域名或IP地址。
- 启动GitLab容器：
sudo docker-compose up -d - 访问GitLab：
通过浏览器访问您配置的 `external_url`，您应该能看到GitLab的登录页面。
四、 GitLab安装配置后的基础设置
安装完成后，一些基础的配置可以帮助您更好地使用GitLab。
1. 首次登录与修改Root密码
在浏览器中输入您配置的 `EXTERNAL_URL`。首次访问时，您会看到一个设置Root用户密码的页面。设置一个强密码，并妥善保存。
登录后，您可以使用 `root` 用户进行后续的管理操作。
2. 配置SMTP发送邮件
为了接收通知和进行用户注册，配置SMTP服务器是必不可少的。
- 编辑GitLab的配置文件：
sudo gitlab-ctl edit /etc/gitlab/gitlab.rb - 找到 `gitlab_rails[smtp_enable]` 部分，并取消注释（删除前面的 `#`）和修改相关配置。例如：
gitlab_rails[smtp_enable] = true gitlab_rails[smtp_address] = "smtp.example.com" gitlab_rails[smtp_port] = 587 gitlab_rails[smtp_user_name] = "[email protected]" gitlab_rails[smtp_password] = "your_email_password" gitlab_rails[smtp_domain] = "example.com" # e.g. smtp.example.com gitlab_rails[gitlab_email_from] = "[email protected]" # The email address displayed in emails gitlab_rails[gitlab_email_reply_to] = "[email protected]"请将占位符信息替换为您实际的SMTP服务器配置。
- 保存文件后，重新配置GitLab：
sudo gitlab-ctl reconfigure - 测试邮件发送：
sudo gitlab-rails console Notify.test_email([email protected], Subject, Body).deliver_now将 `[email protected]` 替换为您的接收邮箱地址。
3. 配置HTTPS（SSL/TLS）
为了数据安全，强烈建议配置HTTPS。
- 使用Lets Encrypt自动续期：
如果您的GitLab服务器可以通过域名访问，并且开放了80端口，Lets Encrypt是最佳选择。
- 编辑GitLab配置文件：
sudo gitlab-ctl edit /etc/gitlab/gitlab.rb - 找到 `external_url`，将其改为HTTPS并填写您的域名：
external_url https://your.gitlab.com - 启用Lets Encrypt：
letsencrypt[enable] = true letsencrypt[contact_emails] = [[email protected]] # Optional, but recommended # letsencrypt[auto_renew_hour] = "0" # Optional: specify renewal hour # letsencrypt[auto_renew_minute] = "30" # Optional: specify renewal minute # letsencrypt[auto_renew_day_of_month] = "*/4" # Optional: renew every 4 days - 保存文件并重新配置：
sudo gitlab-ctl reconfigure
- 编辑GitLab配置文件：
- 手动配置SSL证书：
如果您有自己的SSL证书（例如 `.crt` 和 `.key` 文件），可以进行手动配置。
- 将您的证书文件上传到服务器（例如 `/etc/gitlab/ssl/your.gitlab.com.crt` 和 `/etc/gitlab/ssl/your.gitlab.com.key`）。
- 编辑GitLab配置文件：
sudo gitlab-ctl edit /etc/gitlab/gitlab.rb - 配置HTTPS和证书路径：
external_url https://your.gitlab.com nginx[enable] = true nginx[ssl_certificate] = "/etc/gitlab/ssl/your.gitlab.com.crt" nginx[ssl_certificate_key] = "/etc/gitlab/ssl/your.gitlab.com.key" - 保存文件并重新配置：
sudo gitlab-ctl reconfigure
4. 用户与群组管理
登录GitLab后，您可以通过图形界面来创建用户、群组和项目。通常，您会创建一个或多个管理员用户，并为团队分配不同的群组。
五、 GitLab安装配置常见问题
在安装和配置过程中，可能会遇到一些挑战。以下是一些常见问题及其解决方法。
1. 无法访问GitLab界面
- 检查防火墙： 确保您服务器的防火墙开放了HTTP (80) 和 HTTPS (443) 端口。
- 检查Nginx服务： 运行 `sudo gitlab-ctl status` 确认Nginx正在运行。
- 检查Nginx配置文件： 确保 `external_url` 配置正确，并且没有语法错误。
- DNS解析： 确认您使用的域名能够正确解析到服务器的IP地址。
- SELinux (CentOS/RHEL)： 如果SELinux是Enforcing模式，可能阻止Nginx访问文件。可以临时禁用SELinux进行测试：`sudo setenforce 0`。如果问题解决，需要配置SELinux策略。
2. Git Clone/Push 失败，提示权限问题
- SSH密钥配置： 确保用户在本地生成的SSH公钥已添加到GitLab的用户账户中。
- SSH服务是否运行： 检查 `sudo gitlab-ctl status`，确保SSH服务正常。
- SSH端口： 确保GitLab配置的SSH端口（默认为22）在防火墙中是开放的。
- GitLab Shell配置： 检查 `external_url` 是否正确配置了SSH访问协议（例如，如果使用HTTPS，SSH克隆也需要正确配置）。
3. 邮件发送失败
- SMTP配置检查： 仔细核对 `gitlab.rb` 文件中的SMTP配置参数，包括服务器地址、端口、用户名、密码和域名。
- SMTP服务器可用性： 尝试从服务器上使用 `telnet` 或 `nc` 命令连接SMTP服务器，检查网络连通性。
- 防火墙： 确保服务器的防火墙允许连接到SMTP服务器的端口（通常是25, 465, 587）。
- 邮箱账户权限： 检查SMTP账户是否开启了“允许应用发送邮件”等相关选项。
4. GitLab性能问题
- 硬件资源不足： 检查服务器的CPU、内存和磁盘I/O使用情况。如果资源耗尽，考虑升级硬件或优化GitLab配置。
- 数据库性能： GitLab使用PostgreSQL数据库。定期检查数据库性能，可能需要调整数据库参数。
- Sidekiq队列： Sidekiq是GitLab的后台任务处理系统。如果Sidekiq进程过多或任务堆积，会影响性能。可以通过 `sudo gitlab-ctl tail` 查看Sidekiq日志。
- GitLab配置优化： 调整 `gitlab.rb` 中的一些参数，例如 Puma 的工作进程数量，可以对性能产生影响。
5. 升级GitLab
GitLab定期发布新版本，升级是保持安全性和获取新功能的重要途径。
- 备份： 在升级前，务必完整备份GitLab数据（包括配置、数据库和仓库）。
sudo gitlab-backup create - 更新包源： 按照您最初的安装方法，更新GitLab的软件源（例如，更新APT或YUM仓库）。
- 执行升级命令：
在Ubuntu/Debian上：
sudo apt update sudo apt install gitlab-ee在CentOS/RHEL上：
sudo yum update gitlab-ee - 重新配置：
sudo gitlab-ctl reconfigure - 执行数据库迁移（如果需要）： 某些大版本升级可能需要手动执行数据库迁移命令。请参考官方文档中关于版本升级的部分。
GitLab的安装配置是一个涉及多个层面的过程，从服务器环境的准备到软件的安装、再到后续的功能配置，每一个环节都需要细致的处理。本文提供了一个全面的指南，希望能够帮助您顺利完成GitLab的搭建和部署。
