记一次GitLab域名修改全流程实录

摘要

在企业IT架构中，GitLab作为核心代码管理平台，其域名的稳定性直接影响开发效率。本文以实际案例为基础，系统阐述GitLab域名修改的完整流程，涵盖DNS解析调整、Nginx配置更新、证书管理优化及服务验证等关键环节。通过分步骤解析和配置示例，帮助运维人员规避常见风险，确保服务平滑过渡。

一、域名修改背景与必要性

1.1 典型触发场景

企业品牌升级：原域名与公司新品牌不符，需同步更新
合规性要求：域名所有权变更需迁移至新注册商
网络架构优化：从公网域名迁移至内网专用域名
安全加固：替换存在漏洞的旧域名

1.2 潜在风险评估

服务中断：配置错误可能导致502错误
证书失效：未更新SSL证书将触发浏览器警告
持续集成中断：Jenkins/GitLab CI等工具配置需同步更新
数据同步问题：远程仓库地址变更需全员通知

二、修改前关键准备工作

2.1 基础环境检查

# 验证当前运行状态
sudo gitlab-ctl status
# 检查Nginx配置
sudo gitlab-ctl nginx-status
# 备份配置文件
sudo cp -r /etc/gitlab /etc/gitlab.bak.$(date +%Y%m%d)

2.2 资源准备清单

资源类型	具体要求	验证方式
新域名	已完成DNS解析（A记录/CNAME）	`dig new.domain.com`
SSL证书	包含主域名及通配符子域名	`openssl x509 -in cert.pem -noout -text`
运维权限	具备root或gitlab-www用户权限	`sudo -l`
备份方案	完整数据备份+配置快照	`gitlab-rake gitlabcreate`

三、核心修改流程详解

3.1 配置文件调整

路径：/etc/gitlab/gitlab.rb

# 修改外部URL配置
external_url 'https://new.domain.com'
# Nginx监听配置（如需自定义端口）
nginx['listen_port'] = 443
nginx['listen_https'] = true
# 证书路径配置
nginx['ssl_certificate'] = "/etc/gitlab/ssl/new.domain.com.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/new.domain.com.key"

关键参数说明：

external_url：必须包含协议头（http/https）
证书路径：需确保gitlab-www用户有读取权限
端口配置：与防火墙规则保持一致

3.2 证书部署优化

推荐方案：

使用Let’s Encrypt自动证书（需安装certbot）

sudo certbot certonly --nginx -d new.domain.com
sudo chmod 644 /etc/letsencrypt/live/new.domain.com/*

手动部署证书时，建议创建专用目录：

sudo mkdir -p /etc/gitlab/ssl
sudo chown -R gitlab-www:gitlab-www /etc/gitlab/ssl

3.3 服务重启与验证

分阶段重启策略：

配置重载（不中断服务）：
```
sudo gitlab-ctl reconfigure
```
完整重启（修改核心参数后）：
```
sudo gitlab-ctl restart
```

验证检查表：

Web访问：curl -v https://new.domain.com
API连通性：curl -k https://new.domain.com/api/v4/version
邮件服务：测试注册/密码重置邮件发送
Git操作：执行git clone测试

四、常见问题处理方案

4.1 502 Bad Gateway错误

排查流程：

检查Nginx错误日志：
```
sudo gitlab-ctl tail nginx
```
常见原因：
- 证书路径错误
- 端口冲突
- 内存不足（建议≥4GB）

4.2 SSL证书不匹配

解决方案：

确认证书链完整性：

openssl s_client -connect new.domain.com:443 -showcerts

检查中间证书是否缺失，必要时合并证书文件：
```
cat domain.crt intermediate.crt > fullchain.crt
```

4.3 持续集成中断

修复步骤：

更新GitLab Runner配置：

# /etc/gitlab-runner/config.toml
[runners.docker]
extra_hosts = ["new.domain.com:192.168.1.10"]

修改CI/CD变量中的域名引用

五、修改后优化建议

5.1 监控体系构建

# Prometheus监控配置示例
- job_name: 'gitlab'
  static_configs:
    - targets: ['new.domain.com:9168']  # GitLab Exporter

5.2 自动化回滚方案

#!/bin/bash
# 回滚脚本示例
if ! curl -sSf https://new.domain.com > /dev/null; then
  echo "验证失败，执行回滚..."
  cp -r /etc/gitlab.bak.* /etc/gitlab
  gitlab-ctl reconfigure
  gitlab-ctl restart
fi

5.3 变更管理规范

建立域名变更SOP文档
实施变更窗口制度（建议非业务高峰期）
配置变更审批流程

六、总结与延伸思考

本次域名修改实践表明，通过系统化的准备和分阶段实施，可将服务中断时间控制在5分钟以内。关键成功要素包括：

完善的备份机制
渐进式验证策略
跨团队协同（开发/运维/安全）

未来可探索的改进方向：

实现域名变更的IaC（基础设施即代码）管理
集成自动化测试用例
建立多活域名架构

通过本次实践，团队不仅掌握了GitLab域名修改的核心技术，更建立了完善的变更管理流程，为后续类似操作提供了标准化模板。建议每季度进行一次变更演练，持续提升运维响应能力。