ngx_http_auth_basic_module 在 content phase 触发认证，仅当 location 启用 auth_basic 时解析 Authorization 头并比对密码文件；支持 apr1/crypt/SSHA 格式，失败返回 401 并设 WWW-Authenticate 头。
ngx_http_auth_basic_module 的身份验证逻辑并不复杂，但理解它在 Nginx 请求处理流程中的触发时机和关键判断点，对排查认证失效、绕过或 401 响应异常等问题非常关键。
认证何时被触发
该模块只在 HTTP 请求进入 content phase（内容处理阶段）且匹配到启用 auth_basic 的 location 时才介入。它不会处理 CONNECT 请求（正向代理隧道）、静态文件未命中时的 try_files 回退路径，也不会在 rewrite 或 proxy_pass 转发前主动校验——除非这些指令仍在同一 location 内执行且未跳转出当前上下文。
典型触发路径是：
收到 GET/POST 等标准方法 → 匹配 location → 进入 content handler → 检查是否配置了 auth_basic → 若开启，则读取 Authorization 请求头 → 解析 Base64 编码的 "user:pass" → 打开并逐行比对 auth_basic_user_file 中的记录。
密码文件解析与匹配规则
模块本身不负责密码加密运算，只做字符串比对。它支持三种主流格式：
-
apr1（MD5 变体）：最常用，由 htpasswd -m 或 openssl passwd -apr1 生成，形如
user:$apr1$salt$hash - crypt()：兼容 Unix 传统，但强度较弱，适合老旧环境
- SSHA：带 salt 的 SHA-1，安全性优于纯 SHA，常见于 OpenLDAP 场景
模块会跳过以 # 开头的注释行，也支持用户名后带冒号分隔的注释字段（如 admin:$apr1$...:dev-admin），但仅比对冒号前的用户名和第一个冒号后的密码哈希部分。
认证失败的响应机制
一旦校验失败（用户名不存在、密码不匹配、文件不可读、格式错误），模块直接返回 401 状态，并设置响应头：WWW-Authenticate: Basic realm="xxx"
这个动作发生在 content phase 中，因此：
- 不会触发 log phase 的 access_log 记录（除非你额外配置了 error_log 记录 auth 失败）
- 不会执行后续的 proxy_pass 或 fastcgi_pass —— 请求在此终止
- 浏览器收到 401 后自动弹窗，用户再次提交时 Authorization 头才会携带凭证
配置继承与作用域控制
auth_basic 和 auth_basic_user_file 都支持多级配置继承（http → server → location）。但要注意：
- 子块中设为
auth_basic off可显式关闭上级继承的认证 - auth_basic_user_file 不支持相对路径拼接，推荐使用绝对路径，避免因 root 或 alias 变更导致文件打开失败
- 同一个 location 下若存在多个 auth_basic_user_file 指令，只有最后一个生效
模块内部通过 ngx_http_auth_basic_loc_conf_t 结构体保存配置，每个 location 独立一份，确保不同路径可配置不同 realm 和不同密码文件。
