GitLab 运维实战：彻底解决反向代理后只记录内网 IP 的问题（获取并关联用户真实源 IP 完整指南）

在企业级 GitLab 部署架构中，为了实现 HTTPS 卸载、多服务域名复用或接入 WAF/CDN，我们通常不会将 GitLab 直接暴露在公网，而是将其部署在内网环境中，前置一层或多层反向代理（如 Nginx、HAProxy、阿里云 SLB 或 AWS ALB）。

然而，这种架构往往会带来一个经典的运维痛点：GitLab 后台记录的所有用户访问和登录 IP，全部变成了反向代理服务器的内网 IP。

本文将从问题现象出发，深入剖析 HTTP 代理链路中真实 IP 丢失的底层逻辑，并提供从前置反代到 GitLab 服务端（涵盖宿主机安装与 Docker 部署）的完整配置方案与排错指南。

一、 问题现象与安全隐患

在完成 GitLab（如 18.x 版本）的反代上线后，管理员进入 GitLab 管理后台查看用户详情时，经常会看到类似下图的异常状态：

• 当前登录IP：显示为内网地址 172.31.0.245。
• 最后登录IP：同样显示为内网地址 172.31.0.245。
• 登录时间审计：尽管“当前登录于”和“最后登录于”准确记录了时间戳（例如 Oct 25, 2026 10:13am），但 IP 归属完全失去了追踪意义。

如果放任不管，这不仅是一个“显示不美观”的问题，更会带来两大严重隐患：

1. 安全审计失效：当发生账号异地异常登录、代码恶意拖库或暴力破解时，安全团队在审计日志（Audit Events）中只能看到反向代理的内网 IP（如 172.31.0.245），无法定位攻击者的真实公网源 IP。
2. 防爆破机制“误杀”全员：GitLab 内置了 Rack::Attack 安全组件，用于针对高频请求或密码爆破的 IP 进行自动封禁。如果所有用户的请求在 GitLab 看来都来自同一个反向代理 IP，一旦某个员工输错几次密码触发限流，GitLab 会直接将反向代理的 IP 封禁，导致整个公司的所有人都无法访问 GitLab。

二、 核心原理解析：为什么真实 IP 会“被替换”？

要彻底解决该问题，首先需要理解网络请求在反向代理架构中的流转过程：

[客户端真实 IP: 203.0.113.88] 
       │ (1. 建立 TCP 连接)
       ▼
[前置反向代理 Nginx: 172.31.0.245] 
       │ (2. 重新发起内网 TCP 连接，附加 HTTP 头部)
       ▼
[GitLab 内置 Nginx -> GitLab Workhorse -> GitLab Rails]

1. TCP 层面的天然覆盖：HTTP 协议基于 TCP 连接。当客户端访问前置反向代理时，反向代理会终结该 TCP 连接，并以自己的内网身份（如 172.31.0.245）向后端的 GitLab 发起一条全新的 TCP 连接。默认情况下，Web 服务器直接读取 TCP Socket 的对端地址（$remote_addr）作为客户端 IP，因此自然只能拿到 172.31.0.245。
2. HTTP 请求头的接力传递：为了保留最初的客户端 IP，业界标准做法是由反向代理在转发 HTTP 请求时，将真实客户端 IP 写入扩展请求头中（即 X-Real-IP 和 X-Forwarded-For）。
3. GitLab 的安全防御机制（可信代理）：即便前置代理传递了 X-Forwarded-For，GitLab 默认也会忽略它。因为 HTTP 请求头是极易伪造的——任何攻击者都可以直接在本地用 curl -H "X-Forwarded-For: 1.2.3.4" 伪造源 IP。为了防止 IP 欺骗，GitLab 内置的 Nginx 和底层的 Ruby on Rails 框架要求管理员必须显式声明“我信任哪些代理服务器发来的请求头”。只有来自可信代理 IP 的请求，GitLab 才会去解析其中的真实源 IP。

三、 完整配置方案：三步打通真实 IP 链路

解决该问题需要前置反向代理与GitLab 服务端双向配合。

第一步：确保前置反向代理正确传递 IP 请求头

以前置 Nginx 为例，打开反代 GitLab 的虚拟主机配置文件，在 location / 块中添加标准的代理透传头：

server {
    listen 80;
    listen 443 ssl http2;
    server_name gitlab.example.com;

    # SSL 证书配置省略...

    location / {
        proxy_pass http://172.31.0.100:80; # 替换为你的 GitLab 实际内网地址与端口
        
        # 保持原始请求的 Host 头部
        proxy_set_header Host $http_host;
        
        # 记录直接与当前前置反代建立连接的客户端 IP
        proxy_set_header X-Real-IP $remote_addr;
        
        # 追加每一层代理的 IP 链路（核心请求头）
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 传递原始协议类型（http 或 https），防止 GitLab 重定向死循环
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Ssl on;
    }
}

参数细节解析：

• $remote_addr：当前直接连接前置 Nginx 的客户端真实 IP（假设没有套 CDN）。
• $proxy_add_x_forwarded_for：如果请求此前已经经过了 CDN，它会保留原有的 X-Forwarded-For 值，并在末尾追加当前 $remote_addr，形成如 真实用户IP, CDN节点IP 的链条。

配置完成后，检查语法并重载前置 Nginx：

nginx -t && nginx -s reload

第二步：在 GitLab 中配置可信代理与 real_ip 模块

编辑 GitLab 的核心配置文件 /etc/gitlab/gitlab.rb（若采用 Docker 容器化部署，通常对应宿主机挂载目录中的 config/gitlab.rb）。

根据你的 GitLab 架构模式，选择以下对应的配置方案：

场景 A：使用 GitLab 内置 NGINX（95% 以上的默认部署场景）

Omnibus GitLab 和官方 Docker 镜像默认自带了一个内置的 Nginx 服务。我们需要同时开启内置 Nginx 的 ngx_http_realip_module 模块，并配置 GitLab Rails 的可信代理列表：

# =================================================================
# 1. 配置内置 NGINX 的 Real-IP 模块
# =================================================================

# 将前置反向代理的 IP 或内网 CIDR 网段加入可信列表
# 可以填单个 IP（如 '172.31.0.245'），也可以直接填整个内网子网段
nginx['real_ip_trusted_addresses'] = ['172.31.0.245', '172.31.0.0/16']

# 指定从哪个 HTTP 头部提取真实 IP（通常为 X-Forwarded-For 或 X-Real-IP）
nginx['real_ip_header'] = 'X-Forwarded-For'

# 开启递归剔除模式（强烈建议设为 'on'）
nginx['real_ip_recursive'] = 'on'

# =================================================================
# 2. 配置 GitLab Rails 应用层的可信代理
# =================================================================

# 确保 Rails 框架在生成审计日志、记录用户登录 IP 时信任该代理网段
gitlab_rails['trusted_proxies'] = ['172.31.0.245', '172.31.0.0/16']

为什么要把 real_ip_recursive 设为 'on'？
假设请求链路为：用户 (203.0.113.88) -> 云负载均衡 (172.31.0.10) -> 前置 Nginx (172.31.0.245) -> GitLab。
此时 X-Forwarded-For 的内容为：203.0.113.88, 172.31.0.10。

• 如果 real_ip_recursive 为 'off'，GitLab 内置 Nginx 只会信任直接连接它的 172.31.0.245，然后直接取请求头里的最后一个 IP（即 172.31.0.10）当作客户端 IP，结果依然是内网 IP。
• 如果 real_ip_recursive 为 'on'，GitLab 内置 Nginx 会从右往左依次检查请求头中的 IP：发现 172.31.0.245 和 172.31.0.10 都属于 172.31.0.0/16 可信网段，便会将它们全部剥离，最终精准提取出最左侧的 203.0.113.88 作为真实客户端 IP。

场景 B：禁用了内置 NGINX（外部 Web 服务器直连模式）

如果你在 gitlab.rb 中显式配置了 nginx['enable'] = false，使用外部 Nginx 或 Apache 直接通过 Socket/端口连接 GitLab Workhorse，那么上述 nginx['...'] 开头的配置将不会生效。此时必须确保外部 Web 服务器已处理好头信息，并在 gitlab.rb 中配置 Rails 层的信任列表：

gitlab_rails['trusted_proxies'] = ['172.31.0.245', '172.31.0.0/16']

第三步：重载配置与多维度验证

完成 /etc/gitlab/gitlab.rb 的修改后，需要重新编译并加载 GitLab 配置：

1. 执行重载命令：

2. 宿主机软件包安装（Ubuntu/CentOS/RockyLinux）：

   sudo gitlab-ctl reconfigure
   

• Docker 容器部署：

  docker exec -it <你的GitLab容器名> gitlab-ctl reconfigure
  

• 补充操作：在部分 GitLab 版本中，修改 gitlab_rails['trusted_proxies'] 后，Puma 进程可能不会立即热更新该配置。如果发现页面没变，建议手动重启一下应用层进程：

  sudo gitlab-ctl restart puma
  

2. 验证真实 IP 是否生效：

3. 方法一：实时查看访问日志（最快、最直观）
   在终端执行日志追踪命令，同时在浏览器刷新一下 GitLab 页面：

   sudo gitlab-ctl tail nginx/gitlab_access.log
   

观察输出日志的第一列（或 JSON 格式中的 remote_addr 字段），如果已经从 172.31.0.245 变成了你电脑所在的真实公网/办公网 IP，说明内置 Nginx 层面已解析成功。

• 方法二：验证 GitLab Rails 后台用户面板
  注意，GitLab 用户详情页中的“当前登录IP”和“最后登录IP”字段仅在用户触发登录动作（创建新 Session）时才会更新入库，单纯刷新页面不会改变已有数值。
  请点击右上角头像退出登录，然后重新输入账号密码登录一次。再次进入管理后台（Admin Area -> Users -> 点击对应用户），即可看到“当前登录IP”已成功更新为真实的源站/客户端 IP。

四、 进阶避坑指南：复杂网络架构下的疑难杂症

在实际生产环境中，网络拓扑往往比单层 Nginx 更加复杂。如果按照上述步骤配置后仍然显示代理 IP，请对照以下常见场景进行排查：

打通反向代理与 GitLab 之间的真实 IP 传递，本质上是建立一条“逐级追加请求头 + 逐级配置可信剥离”的信任链。只要理清流量经过的每一个网络节点，确保前置节点忠实记录 $remote_addr、后端节点将所有中间代理网段纳入 real_ip_trusted_addresses 与 trusted_proxies，就能让 GitLab 的安全审计与防爆破机制真正发挥作用，为企业的代码资产安全保驾护航。

版权属于：soarli

本文链接：https://blog.soarli.top/archives/1212.html

转载时须注明出处及本声明。