4、反向代理层（Nginx/Traefik）鉴权：配置JWT验证、Basic Auth、IP白名单，以及常见配置错误导致鉴权失败

反向代理是后端鉴权拦截链路的第一道关卡。Nginx 与 Traefik 作为 Docker 环境下最常用的反向代理，承担着提前验证请求身份、过滤非法流量的职责。本章聚焦三种核心鉴权机制——JWT 验证、Basic Auth、IP 白名单，并剖析因配置疏忽导致的典型鉴权失败场景。

4.1 三种鉴权机制对比与适用场景

4.2 Nginx 鉴权配置详解

4.2.1 JWT 验证（通过 lua-resty-jwt 或 njs 模块）

Nginx 原生不支持 JWT 解析，需借助 OpenResty（lua-resty-jwt）或 njs 模块实现。以下为基于 OpenResty 的典型配置：

# nginx.conf — JWT 验证示例
server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/ {
        access_by_lua_block {
            local jwt = require("resty.jwt")
            local jwt_token = ngx.var.http_authorization

            if not jwt_token then
                ngx.status = 401
                ngx.say('{"error":"Missing Authorization header"}')
                ngx.exit(401)
            end

            -- 去除 "Bearer " 前缀
            local _, _, token = string.find(jwt_token, "Bearer%s+(.+)")
            if not token then
                ngx.status = 401
                ngx.say('{"error":"Invalid Authorization format"}')
                ngx.exit(401)
            end

            local secret = "your-256-bit-secret"
            local jwt_obj = jwt:verify(secret, token)

            if not jwt_obj.verified then
                ngx.status = 401
                ngx.say('{"error":"JWT verification failed: ' .. jwt_obj.reason .. '"}')
                ngx.exit(401)
            end

            -- 将解析后的 payload 传递给后端
            ngx.var.jwt_payload = jwt_obj.payload
        }

        proxy_pass http://backend_app:3000;
        proxy_set_header X-JWT-Payload $jwt_payload;
    }
}

4.2.2 Basic Auth 配置

# 生成密码文件（使用 htpasswd）
# htpasswd -c /etc/nginx/.htpasswd admin

# nginx.conf
location /admin/ {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://admin_panel:8080;
}

4.2.3 IP 白名单配置

location /internal/ {
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    deny all;

    proxy_pass http://internal_service:4000;
}

4.3 Traefik 鉴权配置详解

Traefik 原生支持中间件（Middleware）链式鉴权，通过 Docker Compose 标签或动态配置文件声明。

4.3.1 JWT 验证（使用 ForwardAuth 中间件）

Traefik 本身不解析 JWT，需通过 ForwardAuth 将请求转发至专门的认证服务：

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--providers.docker=true"
      - "--entrypoints.websecure.address=:443"
    labels:
      - "traefik.http.middlewares.jwt-auth.forwardauth.address=http://auth-service:8080/verify"
      - "traefik.http.middlewares.jwt-auth.forwardauth.authResponseHeaders=X-JWT-Payload"

  whoami:
    image: traefik/whoami
    labels:
      - "traefik.http.routers.whoami.rule=Host(`api.example.com`) && PathPrefix(`/api`)"
      - "traefik.http.routers.whoami.middlewares=jwt-auth"
      - "traefik.http.routers.whoami.tls=true"

4.3.2 Basic Auth 配置（Traefik 原生中间件）

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.0
    labels:
      # 定义 Basic Auth 中间件（用户名:admin, 密码:secret）
      - "traefik.http.middlewares.admin-auth.basicauth.users=admin:$$2y$$10$$..."
      # 或者从文件读取
      # - "traefik.http.middlewares.admin-auth.basicauth.usersfile=/etc/traefik/.htpasswd"

  admin-ui:
    image: admin-panel:latest
    labels:
      - "traefik.http.routers.admin.middlewares=admin-auth"

4.3.3 IP 白名单配置

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.0
    labels:
      - "traefik.http.middlewares.internal-ipwhitelist.ipwhitelist.sourcerange=10.0.0.0/8, 172.16.0.0/12"

  metrics:
    image: prom/prometheus
    labels:
      - "traefik.http.routers.metrics.middlewares=internal-ipwhitelist"

4.4 反向代理层鉴权流程总览

下图展示了请求到达反向代理后，三种鉴权机制的判断顺序与决策路径：

4.5 常见配置错误速查表

4.6 故障排查步骤

1. 确认鉴权配置是否生效：使用 curl -v 发送请求，观察响应头中是否包含预期的鉴权提示（如 WWW-Authenticate、401 Unauthorized）。
2. 检查代理日志：Nginx 查看 error.log 和 access.log；Traefik 使用 docker logs traefik 或访问其 Dashboard。
3. 验证中间件链顺序：在 Traefik 中，中间件执行顺序由 middlewares 标签中的逗号分隔顺序决定。确保 IP 白名单在 JWT 验证之前执行，以尽早拦截无效来源。
4. 测试后端直连：临时绕过反向代理，直接访问后端容器端口，确认后端服务本身是否正常工作。
5. 检查网络拓扑：在 Docker 环境下，使用 docker network inspect 确认容器 IP 分配，确保 IP 白名单中的 CIDR 范围与实际网络匹配。

4.7 安全加固建议

• 组合使用鉴权方式：对外 API 使用 JWT + IP 白名单双层验证；内部管理端点使用 Basic Auth + IP 白名单。
• 定期轮换密钥：JWT 签名密钥、Basic Auth 密码应定期更新，并存储在 Docker Secrets 或外部密钥管理服务中。
• 限制失败尝试：在反向代理层配置速率限制（Nginx limit_req / Traefik RateLimit 中间件），防止暴力破解。
• 启用 HTTPS：所有鉴权机制必须运行在 TLS 之下，避免凭证在传输过程中被截获。
• 日志脱敏：在代理日志中避免记录完整的 JWT Token 或 Basic Auth 密码，仅记录验证结果与时间戳。