GET /api/v4/version 返回 401：认证凭据缺失或失效

Question

常见问题：调用 `GET /api/v4/version` 时返回 `401 Unauthorized`，提示“认证凭据缺失或失效”，通常并非接口本身需要鉴权（该端点本应为公开、无需认证的健康/版本探测接口），而是因网关层（如 Nginx、API Gateway 或 GitLab CE/EE 的反向代理配置）错误地将 `/api/v4/` 下所有路径统一纳入了认证拦截规则；或客户端误在请求头中携带了已过期/格式错误的 `Authorization: Bearer `，触发后端鉴权中间件提前拒绝；亦可能是 GitLab 实例启用了 `require_authentication_for_api` 配置（非默认），强制所有 API 请求认证。排查需优先检查请求是否含冗余 Token、对比 `curl -v https://host/api/v4/version`（无头）与带 Auth 头的响应差异，并核查网关路由策略与 GitLab 配置项 `gitlab_rails['gitlab_default_projects_features_version_check']` 是否被非预期修改。

Answer 1

```html

一、现象层：表征异常与基础验证

调用 GET /api/v4/version 返回 401 Unauthorized，但该端点在 GitLab 官方文档中明确标注为 public, unauthenticated（见 GitLab API v4 Version Endpoint）。首要验证应排除客户端干扰：执行无头请求 curl -v https://gitlab.example.com/api/v4/version。若响应为 200 OK，则问题必源于请求头污染或网关策略；若仍为 401，则需深入基础设施层。

二、客户端层：隐式凭据污染与工具链陷阱

• CI/CD 工具（如 GitLab CI 的 CI_JOB_TOKEN）、Postman 环境变量、curl 别名或 SDK 默认配置可能自动注入 Authorization: Bearer xxx；
• 过期 Token 或格式错误（如缺失 Bearer 前缀、含不可见 Unicode 字符）将触发 Rails 的 warden.authenticate! 中间件提前拒绝，不进入控制器逻辑；
• 验证命令：curl -v -H "Authorization: Bearer invalid" https://host/api/v4/version 与 curl -v -H "Authorization:" https://host/api/v4/version 对比响应头 WWW-Authenticate 和 X-Request-ID。

三、网关层：反向代理的“过度鉴权”配置

Nginx 或 Kong 等网关常因安全加固误配，对 /api/v4/ 全路径启用 JWT/OAuth2 验证。典型错误配置示例：

location ~ ^/api/v4/ {
    auth_request /auth;
    proxy_pass http://gitlab-workhorse;
}

此规则未排除白名单路径（如 /api/v4/version, /api/v4/help），导致健康检查被拦截。修复方案需添加精确匹配优先级：

location = /api/v4/version { proxy_pass http://gitlab-workhorse; }
location ~ ^/api/v4/ { ... # 带 auth_request 的通用规则 }

四、GitLab 应用层：非默认配置项的隐蔽影响

配置项	默认值	风险说明	检查命令
gitlab_rails['require_authentication_for_api']	false	设为 true 将强制所有 API 请求认证（含 /version）	sudo gitlab-ctl show-config | grep require_authentication_for_api
gitlab_rails['gitlab_default_projects_features_version_check']	true	虽不直接影响鉴权，但若被误设为 false 可能关联权限模块异常	sudo gitlab-rake gitlab:env:info

五、深度诊断：请求生命周期追踪流程图

flowchart TD
    A[Client Request] --> B{Has Authorization Header?}
    B -->|Yes| C[Gateway Auth Check]
    B -->|No| D[Route to GitLab Workhorse]
    C -->|Fail| E[401 from Nginx/Kong]
    C -->|Pass| D
    D --> F[GitLab Rails Router]
    F --> G{Is path /api/v4/version?}
    G -->|Yes| H[Skip before_action :authenticate_user!]
    G -->|No| I[Apply auth middleware]
    H --> J[200 OK with version info]

六、解决方案矩阵：按责任域归类

• 客户端侧：禁用 SDK 自动鉴权（如 Python python-gitlab 设置 private_token=None）；
• 网关侧：Nginx 中使用 location = /api/v4/version 显式放行，或在 Kong 中配置 pre-function 跳过鉴权；
• GitLab 侧：确认 /etc/gitlab/gitlab.rb 中 gitlab_rails['require_authentication_for_api'] = false，重载配置 sudo gitlab-ctl reconfigure；
• 监控侧：在 Prometheus + Grafana 中新增告警规则：当 gitlab_api_requests_total{path="/api/v4/version", status="401"} > 0 持续5分钟即触发。

七、高阶规避：构建弹性健康检查机制

生产环境不应依赖单一端点。推荐组合探测策略：

1. HTTP HEAD /api/v4/version（轻量，验证路由可达性）；
2. GET /help（GitLab 公开静态页，无后端逻辑依赖）；
3. TCP 连通性测试 gitlab-workhorse:8181（绕过 Nginx）；
4. 结合 gitlab-ctl status 输出解析服务进程状态。

自动化脚本示例（Bash）：

#!/bin/bash
set -o pipefail
curl -sfI https://$HOST/api/v4/version | grep "200 OK" && echo "✅ Version OK" || echo "❌ Version failed"

```