GitLab 按访问IP动态切换项目下载/克隆地址原理与配置说明
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. 动态地址替换流程
GitLab 后端根据固定的
external\_url统一生成页面内容（默认生成公网域名地址）；页面、接口数据返回给内置 Nginx；
Nginx 通过 IP 规则判断客户端网络环境，通过
sub\_filter动态替换页面源码中的域名/IP；将替换后的内容返回给浏览器，实现不同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'; }代码逐行释义
IP网段判断：默认标记客户端为外网（
$internal=0），匹配 10.0.0.0/8、172.16-31.0.0/12、192.168.0.0/16 标准内网段时，标记为内网用户（$internal=1）。全局替换开启：
sub\_filter\_once off允许批量替换页面中所有匹配内容，不限制单次替换；sub\_filter\_types覆盖网页HTML和接口JSON数据，保证页面、API返回地址统一生效。内网地址替换：内网用户访问时，将页面内所有公网HTTPS地址、SSH域名地址，强制替换为内网IP地址。
外网地址兜底：外网用户访问时，反向兜底替换，杜绝内网IP地址泄露，保证外网统一展示公网域名。
四、直接修改 gitlab-http.conf 的优缺点
优点
即时生效，无需复杂配置，调试便捷；
精准替换页面所有下载、克隆、Release资源地址；
原生依赖 GitLab 内置Nginx，无需额外部署反向代理。
致命缺点
- 配置不持久化：执行
gitlab\-ctl reconfigure、GitLab版本升级、服务重置时，gitlab\-http\.conf会被系统自动覆盖，自定义规则全部丢失。
五、生产环境持久化方案（推荐）
为避免配置丢失，需将规则写入gitlab\.rb，实现永久生效，升级不重置。
1. 编辑全局配置文件
vi /etc/gitlab/gitlab.rb2. 写入持久化配置（可直接复制使用）
# 固定系统默认公网地址（必须配置） 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'] = true3. 生效命令
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证书。
七、总结
gitlab\-http\.conf是内置Nginx实时配置文件，直接修改可即时生效，适合临时调试；核心原理为GitLab生成固定地址 + Nginx按IP动态替换页面内容，无代码侵入、稳定性高；
生产环境必须使用
gitlab\.rb持久化配置，避免升级、重配导致规则丢失。
（注：文档部分内容可能由 AI 生成）