1. 从HTTP到HTTPS：一次GitLab安全加固的实战复盘

最近在给团队内部的GitLab做安全审计，发现一个挺要命的问题：我们一直用的都是HTTP协议。这年头，代码仓库这种核心资产还裸奔在HTTP上，就跟把保险柜钥匙放在家门口脚垫下面一样，风险太大了。随便一个中间人攻击，代码、凭证、CI/CD流水线的密钥都可能被截获。正好借着这个机会，我把整个从HTTP迁移到HTTPS的过程完整走了一遍，踩了几个不大不小的坑，也总结了一套比较稳妥的配置方案。今天这篇复盘，就详细聊聊怎么把GitLab从HTTP配置成HTTPS访问，核心会围绕Nginx的SSL配置展开，毕竟这是最主流也最可控的方式。无论你是用Omnibus包安装的GitLab，还是源码编译，或者是跑在Docker里，思路都是相通的。我会重点讲清楚每一步背后的“为什么”，而不仅仅是“怎么做”，特别是遇到像502 Bad Gateway、SSL certificate verify failed这类经典错误时，如何一步步定位和解决。

2. 准备工作：证书、域名与架构理解

在动手改配置之前，有三样东西必须准备好，缺一不可。很多人在这一步没想清楚，后面就会遇到各种诡异的问题。

2.1 SSL证书的选择与获取

SSL证书是HTTPS的基石。对于内部使用的GitLab，通常有几个选择：

1. 自签名证书：自己用OpenSSL生成的证书。成本为零，但最大的问题是浏览器和Git客户端会报“不安全”警告，每次访问都需要手动确认，非常影响体验，也不适合自动化工具调用。除非是纯测试环境，否则不推荐。
2. 企业内部CA颁发的证书：如果你的公司有自建的PKI（公钥基础设施）和CA（证书颁发机构），可以申请内部证书。这种证书需要在所有客户端机器上信任你的企业根证书，之后体验就和公网证书一样了。这是企业内网部署的首选方案。
3. 公有云免费证书：比如Let‘s Encrypt，或者阿里云、腾讯云提供的免费DV证书。这是最推荐用于公网或希望获得广泛兼容性的方案。以Let‘s Encrypt为例，你可以使用Certbot工具自动申请和续期。阿里云的免费SSL证书申请也很方便，控制台点点就能下载，还支持免费续期，对于个人或小团队项目非常友好。

实操建议：无论用哪种，最终你都需要两个文件：一个是证书文件（通常以.crt或.pem结尾），另一个是私钥文件（通常以.key结尾）。请务必妥善保管私钥，并确保其权限为600（仅所有者可读可写）。

2.2 明确你的GitLab部署架构

GitLab的访问路径取决于你的安装方式，这直接决定了你需要修改哪个Nginx配置文件。主要分两大类：

• Omnibus Package / Docker 安装：这是最常见的方式。GitLab会自带一个捆绑的Nginx服务器。你需要修改的配置文件是/etc/gitlab/gitlab.rb，然后通过gitlab-ctl reconfigure命令让配置生效。GitLab会根据这个文件生成它自己的Nginx配置（位于/var/opt/gitlab/nginx/conf下），切记不要直接去改生成的Nginx conf文件，因为reconfigure时会覆盖。
• 源码编译安装：这种情况下，你可能使用一个独立的、自己安装的Nginx（比如通过yum或apt安装）。你需要修改的是这个独立Nginx的配置文件，通常是/etc/nginx/nginx.conf或/etc/nginx/sites-available/gitlab（Ubuntu/Debian系）。

为什么强调这个？我见过有人用Omnibus包安装，却跑去改/etc/nginx/nginx.conf，结果配置完全不生效，还排查了半天。所以第一步，先用ps aux | grep nginx看看跑着的Nginx进程的路径，或者用gitlab-ctl status看看nginx服务是否存在，来确定你的架构。

2.3 规划域名与网络

确保你用于访问GitLab的域名（比如gitlab.yourcompany.com）已经正确解析到你的服务器IP。如果你是从旧的HTTP地址迁移，最好提前通知团队成员，并准备好一个短暂的维护窗口。因为切换过程中，服务可能会有短暂的中断。

3. Omnibus GitLab 配置HTTPS全流程

这里以最普遍的Omnibus安装方式为例，演示如何配置。我们假设你已经准备好了证书文件gitlab.yourcompany.com.crt和私钥文件gitlab.yourcompany.com.key。

3.1 核心配置修改：编辑/etc/gitlab/gitlab.rb

这个文件是GitLab的总控配置文件，所有修改都在这里进行。找到并修改以下几项：

# 1. 将外部URL从HTTP改为HTTPS。这是最关键的一步，GitLab内部许多链接（如仓库克隆地址）都基于此生成。 external_url 'https://gitlab.yourcompany.com' # 2. 告诉捆绑的Nginx启用SSL并监听443端口 nginx['listen_port'] = 443 nginx['listen_https'] = true # 3. 指定SSL证书和私钥的路径。你需要将证书文件放到服务器上，比如 /etc/gitlab/ssl/ 目录下。 nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.yourcompany.com.crt" nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.yourcompany.com.key" # 4. (可选但推荐) 设置SSL协议和加密套件，提升安全性，禁用老旧不安全的协议如SSLv3。 nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3" nginx['ssl_ciphers'] = "ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384"

重要细节：

• 创建证书目录并设置权限：sudo mkdir -p /etc/gitlab/ssl && sudo chmod 700 /etc/gitlab/ssl。然后把你的.crt和.key文件放进去。
• external_url的改动影响深远。它不仅改变Web访问，还会影响Git克隆地址、API端点、Webhook地址等。确保所有集成服务（如Jenkins、CI Runner）后续都更新为HTTPS地址。
• 关于ssl_ciphers，你可以使用Mozilla推荐的现代安全配置，上述示例是一个较安全的集合。如果你有兼容老客户端的需要，可以调整。

3.2 应用配置与重定向设置

编辑完gitlab.rb后，执行以下命令让配置生效：

sudo gitlab-ctl reconfigure

这个命令会：

1. 根据gitlab.rb生成新的Nginx、GitLab Workhorse等组件的配置文件。
2. 重启相关服务。

现在，你应该已经可以通过https://gitlab.yourcompany.com访问了。但还有一个重要问题：旧的HTTP链接怎么办？直接丢弃会让用户书签和脚本失效。最好的做法是设置HTTP到HTTPS的301永久重定向。

在gitlab.rb中继续添加：

# 启用Nginx的HTTP重定向到HTTPS nginx['redirect_http_to_https'] = true # 如果你为HTTP监听指定了非80端口，也需要在这里设置 nginx['redirect_http_to_https_port'] = 80

再次运行sudo gitlab-ctl reconfigure。这样，当用户访问http://gitlab.yourcompany.com时，Nginx会自动返回一个301状态码，将请求重定向到对应的HTTPS地址。

3.3 验证与测试

配置完成后，不要只看浏览器能打开就完事，需要进行多维度验证：

1. 浏览器访问：直接打开https://你的地址，查看地址栏是否有锁标志，点击锁标志可以查看证书详情，确认颁发给（Subject）是你的域名。
2. 命令行工具检查：
   • 使用curl -I https://gitlab.yourcompany.com检查返回的HTTP状态码是否为200。
   • 使用openssl s_client -connect gitlab.yourcompany.com:443 -servername gitlab.yourcompany.com可以详细查看SSL握手过程和证书链信息。
3. Git操作测试：这是核心。找一个仓库，尝试用HTTPS URL进行克隆、拉取和推送。git clone https://gitlab.yourcompany.com/group/project.git。如果之前配置过HTTP的密码缓存（credential helper），可能需要清除或更新。在Linux上，可以检查~/.git-credentials文件；在Windows上，去凭据管理器里修改。
4. 重定向测试：访问http://gitlab.yourcompany.com（注意是http），观察浏览器地址栏是否自动跳转到了https，并且网络请求的响应码应该是301 Moved Permanently。

4. 独立Nginx反向代理配置详解

如果你的GitLab是通过源码安装，或者你希望用一个统一的独立Nginx来代理多个服务（包括GitLab），那么就需要在独立的Nginx上配置。这种架构更灵活，也是生产环境的常见做法。

假设你的GitLab应用本身运行在http://localhost:8080（可能是Unicorn或Puma），你需要配置Nginx作为反向代理，对外提供HTTPS。

4.1 Nginx Server 块配置

在Nginx的配置目录（如/etc/nginx/conf.d/gitlab.conf或/etc/nginx/sites-available/gitlab）中创建如下配置：

server { # 监听80端口，将所有HTTP请求重定向到HTTPS listen 80; server_name gitlab.yourcompany.com; return 301 https://$server_name$request_uri; } server { # 监听443端口，启用SSL listen 443 ssl http2; server_name gitlab.yourcompany.com; # SSL证书路径（指向你的独立Nginx证书存放位置） ssl_certificate /path/to/your/ssl/gitlab.yourcompany.com.crt; ssl_certificate_key /path/to/your/ssl/gitlab.yourcompany.com.key; # SSL优化配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384; ssl_prefer_server_ciphers off; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 安全响应头 add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; # 设置客户端请求体大小限制（用于大文件上传） client_max_body_size 0; # 代理设置 location / { # 后端GitLab应用服务器的地址 proxy_pass http://localhost:8080; # 传递必要的头部信息，GitLab需要这些来构建正确的URL proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Ssl on; # 如果后端需要 # 超时设置 proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; } # 处理Git over HTTP(S)的智能推送（git-receive-pack等） location ~ ^/([^/]+/){0,1}(info/refs|git-upload-pack|git-receive-pack)$ { proxy_pass http://localhost:8080; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

配置要点解析：

• proxy_set_header X-Forwarded-Proto $scheme;：这行至关重要。它告诉后端的GitLab应用，原始请求是HTTPS（$scheme在Nginx处理HTTPS请求时为https）。没有这个头，GitLab可能会错误地生成HTTP链接。
• client_max_body_size 0;：设置为0表示不限制上传文件大小，这对于Git LFS大文件推送是必要的。你也可以设为一个很大的值，如1024m。
• Strict-Transport-Security (HSTS)头：告诉浏览器在未来一段时间内（这里2年）只能通过HTTPS访问该站点，即使输入HTTP也会强制转HTTPS。这是一个重要的安全增强，但首次部署时要小心，一旦设置，在有效期内很难回退。
• 两个server块：第一个专门处理HTTP重定向，干净利落。第二个处理所有HTTPS流量。

4.2 调整GitLab自身配置

当使用独立Nginx时，GitLab本身（如Unicorn/Puma）可能还在监听某个HTTP端口。你需要确保GitLab知道它正在被一个反向代理服务，并且外部访问的协议是HTTPS。

对于源码安装的GitLab，通常需要修改其配置文件（如/home/git/gitlab/config/gitlab.yml）：

## GitLab settings gitlab: ## Web server settings host: gitlab.yourcompany.com port: 443 # 外部访问端口 https: true # 关键：声明外部使用HTTPS

同时，你可能需要修改GitLab使用的Web服务器（如Unicorn）的配置，使其只监听本地回环地址，而不是对所有网络接口开放，以增强安全性。

配置完成后，使用sudo nginx -t测试配置文件语法，无误后sudo systemctl reload nginx重新加载配置。

5. 深度排坑：常见错误与解决方案

切换HTTPS的过程中，几乎一定会遇到一些问题。下面我把几个最常见的“坑”及其排查思路详细拆解一下。

5.1 “502 Bad Gateway” 错误深度排查

这是最令人头疼的错误之一，页面显示“502 Bad Gateway”，Nginx错误日志（/var/log/nginx/error.log或 GitLab的/var/log/gitlab/nginx/error.log）里可能看到connect() failed (111: Connection refused)或upstream prematurely closed connection。

根本原因：Nginx无法连接到后端的GitLab应用服务（如Unicorn, Puma, 或GitLab Workhorse）。可能的原因和排查链路如下：

1. 后端服务未运行或崩溃：

   • 检查：对于Omnibus安装，运行sudo gitlab-ctl status，查看unicorn,puma,gitlab-workhorse等服务状态是否为 “run”。如果有服务显示 “down”，去对应的日志文件（/var/log/gitlab/unicorn/current等）查看错误原因。
   • 常见诱因：配置错误（如gitlab.rb语法错误）、端口冲突、内存不足导致进程被OOM Killer杀掉。
   • 解决：根据日志修复配置，或尝试sudo gitlab-ctl restart重启所有服务。

2. Nginx配置中的上游地址错误：

   • 检查：核对Nginx配置中proxy_pass指令指向的地址和端口。对于Omnibus GitLab，Workhorse默认监听unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket这个Unix Socket。对于独立Nginx代理，你指向的可能是http://localhost:8080，确保这个端口的服务确实在运行（用netstat -tlnp | grep :8080查看）。
   • 解决：修正proxy_pass地址。Omnibus安装通常不需要手动改这个，除非你自定义过。

3. SELinux或防火墙阻止了连接：

   • 检查：如果后端服务运行正常，Nginx配置也正确，可能是系统安全策略阻止了。检查SELinux状态getenforce。如果是Enforcing模式，查看审计日志sudo ausearch -m avc --start recent。
   • 解决：可以临时将SELinux设为Permissive模式测试（sudo setenforce 0），如果问题解决，则需要为Nginx或后端服务配置正确的SELinux策略。更常见的是防火墙，确保Nginx能访问后端服务的端口（如8080）。对于Omnibus包，内部通信通常走Unix Socket，不受防火墙影响。

我的踩坑记录：有一次遇到502，日志显示upstream prematurely closed connection。排查后发现是client_max_body_size设置得太小，当用户推送一个稍大的LFS文件时，Nginx缓存的请求体还没传完，后端就已经关闭了连接。将其设置为0或一个更大的值后问题解决。

5.2 SSL证书相关错误

1. 浏览器提示“不安全”或“证书无效”：

   • 自签名证书：这是预期行为。你需要将自签名证书的根证书导入到操作系统或浏览器的受信任根证书颁发机构存储中。
   • 证书域名不匹配：证书的Common Name (CN) 或 Subject Alternative Names (SAN) 不包含你实际访问的域名。确保申请证书时填写的域名完全一致。
   • 证书链不完整：有些CA（如Let‘s Encrypt）颁发的证书需要中间证书。你的ssl_certificate文件应该是你的服务器证书和中间证书的合并文件（通常按服务器证书、中间证书的顺序拼接）。你可以用cat your_domain.crt intermediate.crt > bundle.crt命令生成，然后在Nginx中指向bundle.crt。

2. Git客户端报错：SSL certificate problem: unable to get local issuer certificate：

   • 原因：Git（特别是Windows版Git或某些Linux发行版）没有使用系统证书库，或者你的证书（尤其是内部CA证书）不在其信任列表里。
   • 解决：
     • 临时绕过（不推荐用于生产）：git config --global http.sslVerify false。这会关闭SSL验证，极不安全。
     • 永久解决：将你的CA根证书（或自签名证书）导出为PEM格式，然后配置Git使用它：git config --global http.sslCAInfo /path/to/your-ca.pem。

5.3 Git克隆/推送失败（认证或协议问题）

切换HTTPS后，原本用HTTP克隆的仓库地址失效了。

1. 更新远程仓库URL：

   git remote set-url origin https://gitlab.yourcompany.com/group/project.git

2. 认证问题：HTTP可能缓存了密码（通过credential helper），但切换到HTTPS后可能需要重新认证。

   • 清除旧的凭据：git credential reject，然后按提示输入URL。
   • 或者直接编辑~/.git-credentials文件（如果有），更新里面的URL为HTTPS格式。
   • 对于使用个人访问令牌（Personal Access Token）的情况，确保令牌具有足够的权限（read_repository,write_repository），并且在克隆时使用https://oauth2:YOUR_TOKEN@gitlab.yourcompany.com/...格式。

3. Webhook和集成服务失效：这是最容易遗漏的一点。所有配置了GitLab Webhook的外部服务（如Jenkins、钉钉/飞书机器人、自定义CI系统），都需要手动将其中的回调URL从http://更新为https://。否则你会看到Webhook测试失败，提示“Failed to connect”或“SSL error”。

6. 进阶配置与安全加固

基础HTTPS配置完成后，可以考虑一些进阶设置来提升安全性和性能。

6.1 启用HTTP/2

HTTP/2可以显著提升页面加载速度，特别是对于需要加载大量静态资源（如JS、CSS）的GitLab页面。在Nginx配置中，将listen 443 ssl;改为listen 443 ssl http2;即可。注意，HTTP/2要求使用ALPN扩展，这需要较新版本的OpenSSL和Nginx支持，现代系统通常都满足。

6.2 配置OCSP Stapling

OCSP装订（Stapling）可以加快SSL握手速度并提升隐私性。它允许服务器在TLS握手时一并提供证书的吊销状态证明，客户端无需再单独向CA的OCSP服务器查询。在Nginx的SSL server块中添加：

ssl_stapling on; ssl_stapling_verify on; # 指定用于验证OCSP响应的DNS解析器 resolver 8.8.8.8 8.8.4.4 valid=300s; resolver_timeout 5s; # 指定信任的根证书链，用于验证OCSP响应签名 ssl_trusted_certificate /path/to/your/ssl/chain.pem; # 通常是包含根证书和中间证书的链文件

配置后，可以用openssl s_client -connect gitlab.yourcompany.com:443 -status -servername gitlab.yourcompany.com命令测试，在输出中查找OCSP Response Status: successful。

6.3 调整Nginx缓冲区与超时

对于GitLab这种可能涉及大文件推送（Git LFS）的应用，需要适当调整Nginx的缓冲区大小和超时设置，避免在传输过程中出现超时断开。除了前面提到的client_max_body_size，还可以在location /或http块中调整：

proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; proxy_read_timeout 300; proxy_connect_timeout 300;

这些值可以根据你的服务器内存和网络状况进行调整。

6.4 定期更新与监控

• 证书续期：免费证书（如Let‘s Encrypt）通常只有90天有效期。务必设置自动续期。对于Certbot，可以设置一个cron任务：0 0,12 * * * certbot renew --quiet。对于阿里云等提供的免费证书，关注其续期策略，手动或通过API自动续期。
• 监控HTTPS状态：使用监控工具（如Prometheus Blackbox Exporter, Uptime Kuma）定期从外部探测你的https://gitlab.yourcompany.com，检查证书过期时间、HTTP状态码和响应时间。
• 日志分析：定期查看Nginx的访问日志和错误日志，关注异常的访问模式或大量的4xx/5xx错误，这可能是配置问题或攻击的迹象。

整个从HTTP迁移到HTTPS的过程，本质上是一次服务端点的安全升级和配置规范化。它不仅仅是改个协议那么简单，还涉及到证书管理、服务架构理解、客户端兼容性、以及所有上下游集成的更新。最深的体会就是，变更前充分的沟通、变更中细致的验证、变更后全面的回归测试，这三步缺一不可。特别是那些“沉默的依赖”，比如无人维护的自动化脚本里写死的HTTP地址，或者某个边缘业务系统配置的Webhook，往往是在切换后几天甚至几周才会暴露出问题。所以，在正式切换前，最好能有一个“观察期”，在测试环境或通过Hosts文件让部分核心用户先体验HTTPS版本，收集反馈，平稳过渡后再全面切换。