记一次GitLab域名修改：从规划到落地的全流程实践

在企业级DevOps体系中，GitLab作为核心代码管理平台，其域名的稳定性直接影响开发流程的连续性。近期因公司安全合规要求，需将运行三年的GitLab实例从gitlab.old-domain.com迁移至code.new-domain.com，本文将系统记录此次域名修改的全过程，涵盖技术细节、风险控制及经验总结。

一、修改前的关键检查

1.1 依赖系统梳理

通过netstat -tulnp | grep gitlab确认80/443端口仅由GitLab服务占用，避免端口冲突。使用lsof -i :443进一步验证Nginx配置中是否存在其他虚拟主机监听同一端口。特别检查Jenkins、SonarQube等工具的Webhook配置，确保其URL字段包含旧域名。

1.2 数据备份策略

执行gitlab-rake gitlabcreate生成完整备份，验证备份文件包含repositories/、db/、uploads/等关键目录。将备份文件通过rsync -avz传输至异地存储，同时使用sha256sum校验文件完整性。

1.3 证书准备验证

使用Let’s Encrypt生成新域名证书：

certbot certonly --manual -d code.new-domain.com \
--preferred-challenges dns \
--server https://acme-v02.api.letsencrypt.org/directory

验证证书链完整性：

openssl x509 -in /etc/letsencrypt/live/code.new-domain.com/fullchain.pem \
-noout -text | grep "Subject Alternative Name"

二、核心配置修改

2.1 Nginx配置更新

修改/etc/gitlab/gitlab.rb中的external_url参数：

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

同步更新Nginx虚拟主机配置：

server {
    listen 443 ssl;
    server_name code.new-domain.com;
    ssl_certificate /etc/letsencrypt/live/code.new-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/code.new-domain.com/privkey.pem;
    # ...其他配置...
}

2.2 数据库内容替换

执行SQL更新项目URL（需GitLab 12.0+版本）：

UPDATE projects SET http_url_to_repo = REPLACE(http_url_to_repo, 
'gitlab.old-domain.com', 'code.new-domain.com'),
ssh_url_to_repo = REPLACE(ssh_url_to_repo, 
'gitlab.old-domain.com', 'code.new-domain.com');

对于用户会话表，需清理可能存在的旧域名Cookie：

DELETE FROM sessions WHERE data LIKE '%gitlab.old-domain.com%';

2.3 辅助服务调整

修改GitLab Runner注册信息：

gitlab-runner unregister --url https://code.new-domain.com/ --token [REGISTRATION_TOKEN]
gitlab-runner register --non-interactive \
--url "https://code.new-domain.com/" \
--registration-token [NEW_TOKEN] \
--executor "shell" \
--description "new-domain-runner"

三、服务重启与验证

3.1 渐进式重启

执行gitlab-ctl reconfigure后，采用分阶段重启策略：

gitlab-ctl restart nginx   # 优先重启Web服务
sleep 30                  # 等待Nginx稳定
gitlab-ctl restart sidekiq # 重启后台任务
gitlab-ctl restart unicorn # 最后重启应用服务

3.2 多维度验证

功能测试：创建测试项目，验证Git克隆（HTTPS/SSH）、Webhook触发、CI/CD流水线执行
性能监控：通过gitlab-rails runner "puts ActiveRecord::Base.connection.tables.size"检查数据库连接
日志分析：检查/var/log/gitlab/gitlab-rails/production.log中是否存在404错误

四、迁移后处理

4.1 旧域名重定向

在原域名服务器配置301重定向：

server {
    listen 80;
    server_name gitlab.old-domain.com;
    return 301 https://code.new-domain.com$request_uri;
}

4.2 通知机制建立

内部邮件通知：包含新域名、证书有效期、DNS更新时间

自动化提醒：设置Cron任务检查证书有效期

0 0 1 * * /usr/bin/certbot renew --quiet && /usr/bin/systemctl reload nginx

五、经验总结与避坑指南

5.1 常见问题处理

502错误：检查Sidekiq队列积压（gitlab-rails runner "puts Sidekiq::Queue.all.map(&:size)"）
SSH连接失败：更新~/.ssh/known_hosts中旧域名记录
CI/CD卡顿：清理Runner缓存目录/var/lib/gitlab-runner/builds/

5.2 最佳实践建议

灰度发布：先修改测试环境域名，验证无误后再操作生产环境
变更窗口：选择业务低峰期（如周末凌晨）执行
回滚方案：提前准备旧配置的备份包，确保10分钟内可恢复

此次域名修改历时3小时27分，涉及12个核心配置项、4个关联系统，最终实现零数据丢失、零业务中断的目标。通过系统化的准备和验证，不仅完成了域名迁移，更建立了可复用的GitLab变更管理流程，为后续类似操作提供了标准化模板。

gitlab域名变更全流程解析：从配置到验证的完整实践