Yii框架中安全读取X-Forwarded-For等代理头需在config/web.php的request组件中配置ipHeaders和trustedHosts，明确指定可信代理段；读取Authorization头须手动校验Bearer前缀；RESTful接口应在beforeAction中统一校验必需Header并脱敏记录。
Yii 框架里读取请求头，不能只靠 $headers->get('X-Forwarded-For') 就完事——尤其在 RESTful 接口场景下，Header 常携带认证令牌、版本标识、设备指纹等关键信息，漏读、误读或没校验来源可信度，直接导致鉴权失败或 IP 伪造漏洞。
怎么安全读取 X-Forwarded-For 等代理头
RESTful 接口常部署在 Nginx + PHP-FPM 或云 SLB 后，$request->userIP 默认返回的是上一跳代理 IP（比如 10.0.0.2），不是用户真实出口 IP。必须显式配置才生效：
-
'ipHeaders' => ['X-Forwarded-For', 'X-Real-IP']要写进config/web.php的'components' => ['request' => [...]]里，不能只在控制器里改 -
'trustedHosts' => ['10.0.0.0/8', '192.168.0.0/16']必须填你实际的内网代理段；公网 IP 绝对不能加进去，否则攻击者伪造X-Forwarded-For: 1.2.3.4就能绕过 - 云厂商（如腾讯云 SLB）可能用
Tencent-Cloud-Real-IP，得查清文档并加进ipHeaders数组 - 配置后仍拿不到真实 IP？检查 Nginx 是否转发了对应 Header：
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
怎么读取 Authorization 或自定义 Token 头
REST API 鉴权基本靠 Authorization 头，但 Yii 不会自动解析 Bearer 格式，得手动拆：
- 用
$headers->get('Authorization')拿到原始值，比如"Bearer abc123" - 别直接
explode(' ', ...)就取第二段——要先判断前缀是否为"Bearer "（注意末尾空格），避免被Basic xxx或其他 scheme 混淆 - 自定义头如
X-Api-Version，用$headers->get('X-Api-Version')即可，但要注意：Header 名大小写不敏感，Yii 内部已处理，不用手写strtolower() - 如果头不存在，
get()返回null，不是空字符串；想设默认值得自己判断，比如$version = $headers->get('X-Api-Version') ?: 'v1'
为什么 getallheaders() 在 Nginx 下总是返回空
因为 getallheaders() 是 Apache 专属函数，Nginx + PHP-FPM 环境下它不可用，Yii 会 fallback 到 $_SERVER 解析——但这个 fallback 有陷阱：
-
$_SERVER里的 Header 键名是HTTP_X_FORWARDED_FOR这种格式，Yii 会自动转成X-Forwarded-For，但前提是键名以HTTP_开头且后续部分不含非法字符 - Nginx 如果用了
underscores_in_headers on;，且前端传了带下划线的头（如X_API_TOKEN），PHP 可能收不到——Nginx 默认丢弃下划线 Header，得关掉该配置或改用中划线 - 调试时可用
var_dump(array_keys($_SERVER));查看哪些 Header 实际进了$_SERVER，确认是否被 Web 服务器过滤
RESTful 场景下如何统一校验必需 Header
比如要求所有 /api/v2/* 接口必须带 X-Client-ID 和 Authorization，不满足就 400 返回，别等到业务逻辑里再判：
- 在 Controller 的
beforeAction()里集中处理，避免每个 action 重复写 - 用
$headers->has('X-Client-ID')判断存在性，比get()再判 null 更轻量 - 对敏感头如
Authorization，建议记录日志时脱敏，比如只记"Bearer abc***"，防止密钥泄露 - 注意：CLI 请求（如单元测试）没有 Header，
$headers->get()全返回null，测试时得 mockHeaderCollection或用createRequest()->setHeaders(...)
Header 不是“取出来就行”，关键在谁发的、有没有被中间件篡改、要不要参与鉴权链路——尤其是 X-Forwarded-For 这类代理头，没配 trustedHosts 就调 getUserIP()，等于把防火墙钥匙交给了攻击者。
