可信代理认证

可信代理认证（Trusted Proxy Authentication）允许 Gateway 信任来自反向代理（Reverse Proxy）的认证头信息，将身份验证委托给上游代理。

使用场景

当 Gateway 部署在反向代理（如 Nginx、Caddy、Cloudflare）之后时：

┌──────────┐     HTTPS      ┌──────────┐     HTTP      ┌──────────┐
│  Client   │ ──────────▶  │  Nginx    │ ──────────▶  │  Gateway  │
│           │              │ (认证)    │              │ (信任代理) │
└──────────┘              └──────────┘              └──────────┘

反向代理负责 TLS 终止和用户认证，Gateway 信任代理传递的身份信息。

配置

启用可信代理

{
  "security": {
    "trustedProxy": {
      "enabled": true,
      "trustedIPs": [
        "127.0.0.1",       // 本地代理
        "10.0.0.0/8",      // 内网 IP 段
        "172.16.0.0/12"    // Docker 网络
      ],
      "headers": {
        "clientIP": "X-Real-IP",
        "forwardedFor": "X-Forwarded-For",
        "protocol": "X-Forwarded-Proto",
        "user": "X-Authenticated-User"
      }
    }
  }
}

安全警告

仅在 Gateway 位于受信任的反向代理之后时启用此功能。如果 Gateway 直接暴露到网络，攻击者可以伪造这些头信息。

CLI 配置

# 启用可信代理
openclaw config set security.trustedProxy.enabled true

# 添加可信 IP
openclaw config set security.trustedProxy.trustedIPs '["127.0.0.1"]'

X-Forwarded-For 处理

标准头格式

X-Forwarded-For: client_ip, proxy1_ip, proxy2_ip
X-Real-IP: client_ip
X-Forwarded-Proto: https

Gateway 处理逻辑

1. 检查请求来源 IP 是否在 trustedIPs 列表中
   └─ 否 → 忽略代理头，使用实际连接 IP
   └─ 是 → 继续处理

2. 解析 X-Forwarded-For 头
   └─ 提取最左侧（原始客户端）IP

3. 验证 X-Real-IP 头
   └─ 与 X-Forwarded-For 交叉验证

4. 记录客户端真实 IP
   └─ 用于日志、速率限制等

IP 链验证

Gateway 从右到左遍历 X-Forwarded-For 链，跳过所有在 trustedIPs 中的 IP，第一个非可信 IP 即为客户端真实 IP。

Header-Based 认证委托

反向代理可以在完成用户认证后，通过自定义头将身份信息传递给 Gateway。

Nginx + OAuth2 Proxy 示例

server {
    listen 443 ssl;
    server_name gateway.example.com;

    # OAuth2 Proxy 认证
    location /oauth2/ {
        proxy_pass http://127.0.0.1:4180;
    }

    location / {
        auth_request /oauth2/auth;
        auth_request_set $user $upstream_http_x_auth_request_user;
        auth_request_set $email $upstream_http_x_auth_request_email;

        # 传递认证信息给 Gateway
        proxy_set_header X-Authenticated-User $user;
        proxy_set_header X-Authenticated-Email $email;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Gateway 配置

{
  "security": {
    "trustedProxy": {
      "enabled": true,
      "trustedIPs": ["127.0.0.1"],
      "headers": {
        "user": "X-Authenticated-User",
        "email": "X-Authenticated-Email"
      },
      // 启用代理认证后，跳过 Gateway 自身的 Token 认证
      "skipGatewayAuth": true
    }
  }
}

skipGatewayAuth

设置 skipGatewayAuth: true 后，Gateway 将完全依赖反向代理进行认证，不再检查 Token。确保代理配置正确，否则任何人都可以绕过认证。

Caddy 集成

Caddy 配合 basicauth 或外部认证：

gateway.example.com {
    basicauth /* {
        admin $2a$14$hash_of_password
    }

    reverse_proxy 127.0.0.1:18789 {
        header_up X-Authenticated-User {http.auth.user.id}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

Cloudflare 集成

使用 Cloudflare Access 进行零信任认证：

{
  "security": {
    "trustedProxy": {
      "enabled": true,
      "trustedIPs": [
        "173.245.48.0/20",
        "103.21.244.0/22",
        "103.22.200.0/22"
        // ... Cloudflare IP ranges
      ],
      "headers": {
        "clientIP": "CF-Connecting-IP",
        "user": "Cf-Access-Authenticated-User-Email"
      }
    }
  }
}

诊断

# 检查可信代理配置
openclaw doctor --check trusted-proxy

# 查看当前识别的客户端 IP
openclaw logs --filter "client-ip"

输出示例：

[INFO] Trusted proxy request from 127.0.0.1
  Client IP: 203.0.113.45 (via X-Forwarded-For)
  User: admin@example.com (via X-Authenticated-User)
  Proto: https (via X-Forwarded-Proto)

安全检查清单

• [x] trustedIPs 仅包含可信的反向代理 IP
• [x] Gateway 端口不对外直接暴露
• [x] 防火墙阻止直接访问 Gateway 端口
• [x] 反向代理配置了有效的认证机制
• [x] 定期审查代理配置和访问日志

相关文档

• 远程访问 — 反向代理配置
• 认证 — Gateway 认证机制
• 安全概览 — 完整安全架构