internal 指令是 Nginx 的路径身份标记机制，仅允许 rewrite last、try_files、error_page 或 X-Accel-Redirect 等内部跳转访问，客户端直连一律返回 404；它不参与权限判断，必须配合外部鉴权 location 使用，不可单独配置或用于根上下文。
internal 指令是 Nginx 提供的一种轻量但精准的访问控制机制，它不靠 IP 白名单、Token 验证或 Header 判断，而是从请求发起方式本身做区分：只允许 Nginx 自身内部跳转到达，拒绝一切客户端直连。这正是保护内网接口（如认证中转、后端聚合、临时文件服务）最干净、最不易绕过的手段之一。
它不是权限控制，而是“路径身份”标记
internal 不检查请求头、Cookie、来源 IP 或证书，哪怕你带着合法 JWT、伪造 Host、甚至走 HTTPS 直接 curl，只要这个请求是浏览器或外部工具主动发来的，Nginx 就会直接返回 404 Not Found（注意：不是 403）。它的判断依据只有一个——该请求是否由 Nginx 内部指令触发：
- rewrite ... last（内部重定向，非 redirect）
- try_files 后匹配到该 location
- error_page 指向该 location
- post_action、X-Accel-Redirect 响应头触发（需配合启用）
正确配置的关键写法
必须把 internal 放在明确的具名 location 块中，且不能与 proxy_pass 等指令混用于无匹配的根上下文。典型安全写法如下：
location /auth-check {
internal;
proxy_pass http://auth-service/validate;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
同时，需要另一个对外暴露的 location 来“合法引入”它，例如：
location /api/login {
rewrite ^/api/login$ /auth-check break;
# 或用 try_files /auth-check =404;
}
这样，用户访问 /api/login 会被内部重写到 /auth-check，顺利转发；而直接请求 /auth-check 则立刻 404。
常见踩坑点
- 用了
rewrite ... redirect（301/302）——这是外部跳转，无法抵达 internal location - 把 internal 写在 server 块顶层或 if 块里——语法错误或无效
- 期望 internal 配合 auth_basic 或 allow/deny 使用——它完全独立，加了也没用
- location 匹配过于宽泛，比如
location /internal会误伤/internal-api/v1和/internal-log——建议用精确匹配location = /internal-api或带尾斜杠的前缀location ^~ /internal-api/
它适合什么场景，不适合什么
适合：
• 接口仅作内部服务调用中转（如统一鉴权、日志上报、健康检查代理）
• 静态资源临时生成路径（如 /temp-download/xxx），防止被爬取或暴力猜解
• 与 error_page 联动处理异常响应（如自定义 503 页面后端渲染）
不适合：
• 需要按用户角色或 Token 动态放行的接口——应交由应用层或 API 网关处理
• 需要记录访问者真实 IP 或做审计日志的场景——internal 不影响日志，但本身不提供额外字段
• 想屏蔽某类设备或地区——这不是它的设计目标
