nginx身份验证逻辑解耦的关键是用auth_request模块将认证作为可插拔网关能力，通过独立/_auth内部location转发子请求至专用鉴权服务，依据2xx/401/403状态码放行或拦截，并透传用户信息；basic auth收敛至snippets层，jwt校验封装为lua模块，配置严格分层：upstream须在http顶层定义，snippets仅含location级指令，conf.d限server块，所有include用绝对路径或/etc/nginx/起始相对路径。
实现 Nginx 身份验证逻辑的解耦，关键不是把认证代码塞进业务 location 里，而是让认证成为可插拔、可复用、可独立治理的网关能力。它应与业务路由、协议转换、日志记录等职责彻底分离，既不污染后端代码，也不随业务变更而频繁修改配置。
用 auth_request 做统一认证入口
auth_request 模块是解耦认证最自然的方式——它把“要不要放行”这件事，交给一个专用认证服务判断，Nginx 只负责转发、拦截和响应。
- 定义独立 upstream，指向你的鉴权服务（如 /auth/jwt-check 或 /auth/oidc-validate）
- 在 conf.d/ 的业务 server 中，用 location = /_auth 声明内部认证端点，并设置 internal；禁止外部直接访问
- 在需要保护的 location 块顶部写 auth_request /_auth;，Nginx 自动发起子请求并根据返回状态码（2xx 放行，401/403 拒绝）决策
- 配合 auth_request_set，可把子请求返回的用户 ID、角色等透传给后端：auth_request_set $auth_user $upstream_http_x_user_id;
基础认证（auth_basic）要收敛到 snippets 层
如果仍需 Basic Auth 作临时管控或运维入口，也不能在每个 location 里重复写 auth_basic_user_file。
- 把密码文件统一放在 /etc/nginx/secrets/basic-auth/ 下，按环境或用途命名（如 admin-dev.passwd、api-staging.passwd）
- 在 snippets/ 目录下建 basic-auth.conf，内容只含两行：
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/secrets/basic-auth/$auth_realm.passwd; - 在 server 或 location 中 include snippets/basic-auth.conf，并通过 set $auth_realm "admin-dev"; 动态指定 realm 和对应文件
JWT 验证走 Lua 扩展，不侵入核心配置
JWT 校验含密钥解析、签名校验、有效期检查等逻辑，硬编码在配置里既不安全也不易维护。推荐用 lua-resty-jwt 或 nginx-jwt 封装为独立模块。
- 将 jwt.lua 和依赖库（如 resty.jwt、resty.sha256）放在 /etc/nginx/lua/lib/ 下
- 在 http 块中声明路径：lua_package_path "/etc/nginx/lua/lib/?.lua;;";
- 在 protected location 中只保留一行 access_by_lua_file /etc/nginx/lua/lib/jwt-guard.lua;，所有校验逻辑、错误响应、claim 提取都封装在该文件内
- 密钥、算法、issuer 等参数通过 nginx 变量注入（如 set $jwt_secret "xxx";），避免写死在 Lua 文件中
配置作用域必须严格分层
解耦失败常源于指令错放位置——比如把 upstream 写进 conf.d/*.conf，或在 location 里 include 含 map 的文件。
- upstream 必须在 http {} 顶层定义，单独存于 /etc/nginx/upstreams/ 目录，由 nginx.conf 显式 include
- snippets/ 下的文件只能含 if、add_header、auth_request 等允许出现在 location 内的指令
- conf.d/ 下每个文件只允许一个 server 块，且不得包含任何 upstream、map、limit_req_zone 等全局指令
- 所有 include 使用绝对路径或从 /etc/nginx/ 开始的相对路径（如 include snippets/auth-common.conf;），杜绝 ./ 或 ../
