GitLab 按访问IP动态切换项目下载/克隆地址原理与配置说明

一、核心功能概述

GitLab 官方无原生支持「根据客户端访问IP展示不同项目下载、克隆地址」的功能。可通过GitLab内置Nginx内容替换规则实现动态适配：

• 内网IP访问：自动展示内网IP地址（HTTP克隆、SSH克隆、ZIP/Release下载地址）

• 外网IP访问：默认展示公网域名地址

二、核心生效原理（为什么修改 gitlab-http.conf 有效）

1. 架构底层逻辑

GitLab 默认自带完整的内置 Nginx 服务，所有前端页面、项目克隆地址、资源下载请求，必须经过该 Nginx 转发渲染。

/var/opt/gitlab/nginx/conf/gitlab\-http\.conf 是 GitLab 内置 Nginx 的实时生效主配置文件，直接修改该文件的规则，会被 Nginx 即时加载、执行，因此配置可以立刻生效。

2. 动态地址替换流程

1. GitLab 后端根据固定的 external\_url 统一生成页面内容（默认生成公网域名地址）；

2. 页面、接口数据返回给内置 Nginx；

3. Nginx 通过 IP 规则判断客户端网络环境，通过 sub\_filter 动态替换页面源码中的域名/IP；

4. 将替换后的内容返回给浏览器，实现不同IP看到不同下载/克隆地址。

三、完整配置脚本逐行解析

以下为临时生效的 Nginx 规则（直接写入 gitlab-http.conf），适配标准内网网段，实现内外网地址自动切换。

# 定义内网IP
set $internal 0;
if ($remote_addr ~ ^(192\.168\.|10\.|172\.(1[6-9]|2[0-9]|3[0-1])) ) {
    set $internal 1;
}

# 响应头允许替换
sub_filter_once off;
sub_filter_types text/html application/json;

# 内网IP：替换为内网地址
if ($internal = 1) {
    sub_filter 'https://git.xxx.com' 'http://192.168.1.100';
    sub_filter 'git@git.xxx.com' 'git@192.168.1.100';
}
# 外网IP：默认公网地址（不替换，保持原有）
else {
    sub_filter 'http://192.168.1.100' 'https://git.xxx.com';
}

代码逐行释义

1. IP网段判断：默认标记客户端为外网（$internal=0），匹配 10.0.0.0/8、172.16-31.0.0/12、192.168.0.0/16 标准内网段时，标记为内网用户（$internal=1）。

2. 全局替换开启：sub\_filter\_once off 允许批量替换页面中所有匹配内容，不限制单次替换；sub\_filter\_types 覆盖网页HTML和接口JSON数据，保证页面、API返回地址统一生效。

3. 内网地址替换：内网用户访问时，将页面内所有公网HTTPS地址、SSH域名地址，强制替换为内网IP地址。

4. 外网地址兜底：外网用户访问时，反向兜底替换，杜绝内网IP地址泄露，保证外网统一展示公网域名。

四、直接修改 gitlab-http.conf 的优缺点

优点

• 即时生效，无需复杂配置，调试便捷；

• 精准替换页面所有下载、克隆、Release资源地址；

• 原生依赖 GitLab 内置Nginx，无需额外部署反向代理。

致命缺点

• 配置不持久化：执行 gitlab\-ctl reconfigure、GitLab版本升级、服务重置时，gitlab\-http\.conf 会被系统自动覆盖，自定义规则全部丢失。

五、生产环境持久化方案（推荐）

为避免配置丢失，需将规则写入 gitlab\.rb，实现永久生效，升级不重置。

1. 编辑全局配置文件

vi /etc/gitlab/gitlab.rb

2. 写入持久化配置（可直接复制使用）

# 固定系统默认公网地址（必须配置）
external_url 'https://git.xxx.com'

# 内外网IP动态切换地址持久化配置
nginx['custom_nginx_config'] = <<-'EOF'
# 定义内网标记
set $git_net "public";
# 匹配标准内网网段
if ($remote_addr ~ "^(10\.|172\.(1[6-9]|2[0-9]|3[0-1])\.|192\.168\.)") {
    set $git_net "internal";
}

# 开启全局内容替换
sub_filter_once off;
sub_filter_types text/html application/json text/plain;

# 内网访问：切换内网地址
if ($git_net = "internal") {
    sub_filter 'https://git.xxx.com' 'http://192.168.1.100';
    sub_filter 'git@git.xxx.com' 'git@192.168.1.100';
    sub_filter 'https://git.xxx.com/-/' 'http://192.168.1.100/-/';
}

# 外网访问：兜底公网地址
if ($git_net = "public") {
    sub_filter 'http://192.168.1.100' 'https://git.xxx.com';
    sub_filter 'git@192.168.1.100' 'git@git.xxx.com';
}
EOF

# 开启替换模块
nginx['enable_sub_filter_module'] = true

3. 生效命令

gitlab-ctl reconfigure
gitlab-ctl restart nginx

六、适配范围与配套说明

1. 支持的地址类型

• HTTPS 项目克隆地址

• SSH 项目克隆地址

• 项目ZIP源码下载地址

• Release 版本二进制资源下载地址

2. 配套注意事项

• SSH克隆：内网DNS可将公网域名解析为内网IP，或直接使用替换后的内网IP SSH地址；

• CI/CD Runner：内网Runner自动获取内网克隆地址，外网Runner获取公网地址，无需单独配置；

• HTTPS适配：若内网需要HTTPS访问，可将替换地址改为 https://192\.168\.1\.100，并配置内网SSL证书。

七、总结

1. gitlab\-http\.conf 是内置Nginx实时配置文件，直接修改可即时生效，适合临时调试；

2. 核心原理为 GitLab生成固定地址 + Nginx按IP动态替换页面内容，无代码侵入、稳定性高；

3. 生产环境必须使用 gitlab\.rb 持久化配置，避免升级、重配导致规则丢失。

（注：文档部分内容可能由 AI 生成）