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通常有几个选择自签名证书自己用OpenSSL生成的证书。成本为零但最大的问题是浏览器和Git客户端会报“不安全”警告每次访问都需要手动确认非常影响体验也不适合自动化工具调用。除非是纯测试环境否则不推荐。企业内部CA颁发的证书如果你的公司有自建的PKI公钥基础设施和CA证书颁发机构可以申请内部证书。这种证书需要在所有客户端机器上信任你的企业根证书之后体验就和公网证书一样了。这是企业内网部署的首选方案。公有云免费证书比如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/gitlabUbuntu/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这个命令会根据gitlab.rb生成新的Nginx、GitLab Workhorse等组件的配置文件。重启相关服务。现在你应该已经可以通过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 验证与测试配置完成后不要只看浏览器能打开就完事需要进行多维度验证浏览器访问直接打开https://你的地址查看地址栏是否有锁标志点击锁标志可以查看证书详情确认颁发给Subject是你的域名。命令行工具检查使用curl -I https://gitlab.yourcompany.com检查返回的HTTP状态码是否为200。使用openssl s_client -connect gitlab.yourcompany.com:443 -servername gitlab.yourcompany.com可以详细查看SSL握手过程和证书链信息。Git操作测试这是核心。找一个仓库尝试用HTTPS URL进行克隆、拉取和推送。git clone https://gitlab.yourcompany.com/group/project.git。如果之前配置过HTTP的密码缓存credential helper可能需要清除或更新。在Linux上可以检查~/.git-credentials文件在Windows上去凭据管理器里修改。重定向测试访问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-age63072000; 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。可能的原因和排查链路如下后端服务未运行或崩溃检查对于Omnibus安装运行sudo gitlab-ctl status查看unicorn,puma,gitlab-workhorse等服务状态是否为 “run”。如果有服务显示 “down”去对应的日志文件/var/log/gitlab/unicorn/current等查看错误原因。常见诱因配置错误如gitlab.rb语法错误、端口冲突、内存不足导致进程被OOM Killer杀掉。解决根据日志修复配置或尝试sudo gitlab-ctl restart重启所有服务。Nginx配置中的上游地址错误检查核对Nginx配置中proxy_pass指令指向的地址和端口。对于Omnibus GitLabWorkhorse默认监听unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket这个Unix Socket。对于独立Nginx代理你指向的可能是http://localhost:8080确保这个端口的服务确实在运行用netstat -tlnp | grep :8080查看。解决修正proxy_pass地址。Omnibus安装通常不需要手动改这个除非你自定义过。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证书相关错误浏览器提示“不安全”或“证书无效”自签名证书这是预期行为。你需要将自签名证书的根证书导入到操作系统或浏览器的受信任根证书颁发机构存储中。证书域名不匹配证书的Common Name (CN) 或 Subject Alternative Names (SAN) 不包含你实际访问的域名。确保申请证书时填写的域名完全一致。证书链不完整有些CA如Let‘s Encrypt颁发的证书需要中间证书。你的ssl_certificate文件应该是你的服务器证书和中间证书的合并文件通常按服务器证书、中间证书的顺序拼接。你可以用cat your_domain.crt intermediate.crt bundle.crt命令生成然后在Nginx中指向bundle.crt。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克隆的仓库地址失效了。更新远程仓库URLgit remote set-url origin https://gitlab.yourcompany.com/group/project.git认证问题HTTP可能缓存了密码通过credential helper但切换到HTTPS后可能需要重新认证。清除旧的凭据git credential reject然后按提示输入URL。或者直接编辑~/.git-credentials文件如果有更新里面的URL为HTTPS格式。对于使用个人访问令牌Personal Access Token的情况确保令牌具有足够的权限read_repository,write_repository并且在克隆时使用https://oauth2:YOUR_TOKENgitlab.yourcompany.com/...格式。Webhook和集成服务失效这是最容易遗漏的一点。所有配置了GitLab Webhook的外部服务如Jenkins、钉钉/飞书机器人、自定义CI系统都需要手动将其中的回调URL从http://更新为https://。否则你会看到Webhook测试失败提示“Failed to connect”或“SSL error”。6. 进阶配置与安全加固基础HTTPS配置完成后可以考虑一些进阶设置来提升安全性和性能。6.1 启用HTTP/2HTTP/2可以显著提升页面加载速度特别是对于需要加载大量静态资源如JS、CSS的GitLab页面。在Nginx配置中将listen 443 ssl;改为listen 443 ssl http2;即可。注意HTTP/2要求使用ALPN扩展这需要较新版本的OpenSSL和Nginx支持现代系统通常都满足。6.2 配置OCSP StaplingOCSP装订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 valid300s; 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版本收集反馈平稳过渡后再全面切换。