记一次GitLab域名修改：从准备到验证的全流程实践

在企业IT架构中，GitLab作为核心的代码托管与协作平台，其域名的稳定性直接影响开发效率与安全性。近期，笔者所在团队因业务调整需将GitLab域名从gitlab.old-domain.com迁移至code.new-domain.com，过程中涉及配置修改、证书更新、服务重启等多环节。本文将系统梳理此次域名修改的全流程，结合实践中的关键细节与注意事项，为开发者提供可复用的技术参考。

一、修改前的核心准备工作

1.1 风险评估与备份策略

域名修改可能引发服务中断、数据丢失或权限异常，需提前制定风险预案：

• 全量备份：使用gitlab-rake gitlabcreate命令生成完整备份，存储至独立存储卷；
• 服务依赖分析：梳理Jenkins、SonarQube等依赖GitLab API的服务，确认其域名配置是否需同步更新；
• 回滚方案：保留旧域名的DNS解析记录，确保修改失败时可快速切换。

1.2 证书与DNS配置

• SSL证书申请：根据新域名生成CSR（证书签名请求），提交至CA机构获取通配符证书（如*.new-domain.com）；
• DNS解析：在DNS管理平台添加A记录，指向GitLab服务器的IP地址，设置TTL为300秒以加速生效；
• 内部DNS缓存清除：通过systemctl restart nscd（Linux）或重启本地DNS服务清除缓存。

二、GitLab配置文件修改

2.1 核心配置文件调整

GitLab的域名配置主要涉及以下文件：

• /etc/gitlab/gitlab.rb：修改external_url参数，例如：

  external_url 'https://code.new-domain.com'

• Nginx配置：若使用自定义Nginx，需在/etc/nginx/sites-available/gitlab中更新server_name：

  server {
      server_name code.new-domain.com;
      listen 443 ssl;
      # 其他配置...
  }

2.2 邮件与通知配置

若GitLab通过邮件发送通知，需同步更新SMTP配置中的域名：

# /etc/gitlab/gitlab.rb
gitlab_rails['smtp_domain'] = 'new-domain.com'

2.3 配置重载与验证

修改后执行以下命令使配置生效：

gitlab-ctl reconfigure
gitlab-ctl restart

通过gitlab-ctl status确认所有服务（如Unicorn、Sidekiq）均处于running状态。

三、证书部署与HTTPS配置

3.1 证书文件放置

将证书文件（.crt）与私钥（.key）放置于指定目录：

# 默认路径（Omnibus安装）
sudo cp new-domain.crt /etc/gitlab/ssl/code.new-domain.com.crt
sudo cp new-domain.key /etc/gitlab/ssl/code.new-domain.com.key

确保文件权限为600，所有者为root:root。

3.2 HTTPS强制跳转配置

在gitlab.rb中启用HTTPS强制跳转：

nginx['redirect_http_to_https'] = true
nginx['ssl_certificate'] = "/etc/gitlab/ssl/code.new-domain.com.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/code.new-domain.com.key"

四、数据同步与权限修复

4.1 仓库URL批量更新

若项目依赖旧域名，需通过sed命令批量替换仓库URL：

# 示例：替换本地仓库的remote URL
sed -i 's/git@gitlab.old-domain.com:/git@code.new-domain.com:/g' ~/.git/config

对于已克隆的仓库，需手动执行：

git remote set-url origin https://code.new-domain.com/username/repo.git

4.2 权限与钩子修复

• Webhook配置：登录GitLab Web界面，检查所有项目的Webhook URL是否已更新；
• CI/CD变量：在项目设置中更新GITLAB_HOST等环境变量；
• SSH密钥关联：确认用户SSH密钥仍可正常推送代码。

五、验证与监控

5.1 功能验证清单

• 访问测试：通过浏览器访问https://code.new-domain.com，确认无SSL错误；
• API调用测试：使用curl -v https://code.new-domain.com/api/v4/projects验证API可用性；
• 邮件通知测试：触发一次合并请求，检查通知邮件是否包含新域名。

5.2 监控与日志分析

• Prometheus监控：检查GitLab Exporter指标，确认请求成功率、响应时间等指标正常；
• 日志排查：通过gitlab-ctl tail nginx实时查看Nginx访问日志，排查404或502错误。

六、常见问题与解决方案

6.1 证书链不完整

现象：浏览器提示“证书不受信任”。
解决：合并证书与中间证书为单个文件，例如：

cat new-domain.crt intermediate.crt > fullchain.crt
sudo mv fullchain.crt /etc/gitlab/ssl/code.new-domain.com.crt

6.2 502 Bad Gateway错误

可能原因：Unicorn或Sidekiq进程未启动。
解决：执行gitlab-ctl restart，并通过gitlab-ctl tail查看具体错误日志。

6.3 旧域名缓存问题

现象：部分用户仍访问旧域名。
解决：在DNS层面设置CNAME记录，将旧域名指向新域名，并配置HTTP 301重定向。

七、总结与最佳实践

此次域名修改历时4小时，涉及配置修改、证书部署、数据同步等12个关键步骤。核心经验包括：

1. 分阶段验证：每完成一个配置模块（如DNS、证书），立即进行功能测试；
2. 自动化脚本：编写sed与curl脚本批量更新仓库URL，减少人工错误；
3. 沟通机制：提前通知所有开发者修改本地配置，并提供详细文档。

对于未来类似操作，建议结合Ansible或GitLab提供的domain-migration工具实现自动化，进一步降低风险。通过此次实践，团队不仅完成了域名迁移，更建立了标准化的GitLab运维流程，为后续规模化部署奠定了基础。