记一次GitLab域名修改：从规划到落地的完整实践指南

一、背景与需求分析

在企业IT架构中，GitLab作为核心代码管理平台，其域名的稳定性直接影响开发效率与协作安全。本次域名修改源于两方面需求：其一，原域名（如git.old-domain.com）因品牌升级需替换为新域名（如code.new-domain.com）；其二，原域名SSL证书即将过期，需同步更新证书以避免服务中断。

关键风险点：

1. 服务中断：域名变更可能导致客户端无法访问，影响持续集成流程。
2. 数据一致性：仓库URL、Webhook配置、CI/CD脚本中的硬编码域名需同步更新。
3. 认证失效：若使用OAuth或LDAP集成，域名变更可能破坏认证链。

二、前期准备：三阶段验证模型

1. 环境隔离与备份

• 数据库备份：执行gitlab-rake gitlabcreate生成完整备份，存储至独立存储卷。
• 配置文件备份：保存/etc/gitlab/gitlab.rb及Nginx配置文件（/var/opt/gitlab/nginx/conf/）。
• 容器快照（若使用Docker）：docker commit gitlab-container gitlab-backup-$(date +%Y%m%d)。

2. 依赖系统梳理

通过脚本自动化扫描依赖关系：

# 查找所有包含旧域名的配置文件
grep -r "old-domain.com" /etc/gitlab/ /opt/gitlab/embedded/service/gitlab-rails/config/
# 输出示例：
# /etc/gitlab/gitlab.rb:external_url 'https://git.old-domain.com'
# /opt/gitlab/embedded/service/gitlab-rails/config/gitlab.yml:  host: git.old-domain.com

3. 测试环境验证

在独立测试环境执行以下操作：

1. 修改gitlab.rb中的external_url为新域名。
2. 更新Nginx配置中的server_name与SSL证书路径。
3. 通过gitlab-ctl reconfigure应用配置。
4. 验证基础功能：仓库克隆、Web界面访问、API调用。

三、核心变更步骤

1. 域名解析配置

• DNS记录调整：
  • 添加CNAME记录：code.new-domain.com CNAME gitlab-server.example.com
  • 设置TTL为300秒（变更期间），稳定后恢复至86400秒。
• 本地Hosts文件测试（开发机）：

  192.168.1.100 code.new-domain.com

2. GitLab配置更新

编辑/etc/gitlab/gitlab.rb，修改以下参数：

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

执行配置重载：

gitlab-ctl reconfigure
gitlab-ctl restart

3. 数据迁移与URL替换

• 仓库远程URL批量更新：

  # 查找所有本地仓库并更新remote URL
  find ~/projects -name ".git" -type d -exec sh -c '
    cd "$(dirname "{}")" && \
    old_url="$(git remote get-url origin)" && \
    new_url="$(echo "$old_url" | sed "s/old-domain.com/new-domain.com/g")" && \
    git remote set-url origin "$new_url"
  ' \;

• CI/CD变量更新：在GitLab UI中修改所有包含旧域名的环境变量（如DOCKER_REGISTRY_URL）。

4. 认证系统适配

• OAuth集成：若使用GitHub/GitLab等作为认证源，需在/etc/gitlab/gitlab.rb中更新oauth配置块。
• LDAP配置：检查ldap['host']是否指向新域名对应的服务器。

四、验证与回滚方案

1. 多维度验证

• 功能测试：
  • 创建新仓库并推送代码。
  • 触发CI/CD流水线验证Webhook。
  • 通过SSH克隆仓库：git clone git@code.new-domain.com:group/project.git。
• 性能监控：

  # 检查Nginx访问日志
  tail -f /var/log/gitlab/nginx/gitlab_access.log
  # 监控GitLab进程状态
  gitlab-ctl status

2. 回滚策略

若验证失败，执行以下步骤：

1. 恢复DNS记录至旧域名。
2. 回滚gitlab.rb配置并重载服务。
3. 通知开发团队切换回旧域名进行临时操作。

五、经验总结与最佳实践

1. 灰度发布：先对部分用户开放新域名访问，逐步扩大范围。
2. 自动化脚本：将域名替换操作封装为Ansible/Chef剧本，减少人为错误。
3. 文档更新：同步修改内部Wiki中的GitLab访问指南、CI/CD文档。
4. 监控告警：在Prometheus中添加针对新域名的HTTP状态码监控（如404、502）。

工具推荐：

• git-remote-update：批量更新远程仓库URL的开源工具。
• gitlab-monitor：官方提供的监控仪表盘，可快速检查服务健康状态。

通过本次域名修改，我们验证了GitLab在域名变更场景下的稳定性，并形成了标准化操作流程（SOP），为后续类似变更提供了可复用的方法论。对于企业用户而言，建议将此类操作纳入变更管理流程，结合自动化工具降低风险。