HTTP Basic Auth是最经典的Web访问认证方式之一，浏览器访问受保护资源时会弹出用户名密码输入框，验证通过才能继续访问。Nginx原生支持这套机制，只需要两个指令加上一个密码文件就能生效，非常适合给管理后台、测试环境、内部文档这类不希望公开的页面加一层保护。下面从密码文件制作、核心配置写法、常见报错排查和进阶用法几个方面完整讲一遍。
一、生成密码文件的几种方式
Basic Auth的核心是一个密码文件，里面按“用户名:加密密码”的格式逐行存放账号信息。生成这个文件最常用的工具是Apache自带的htpasswd，Nginx官方也推荐这种方式。如果机器上没装Apache，可以通过安装包管理器单独获取工具，例如CentOS下执行yum install httpd-tools，Debian或Ubuntu下执行apt install apache2-utils。
创建第一个账号的命令如下：
htpasswd -c /etc/nginx/.htpasswd admin # 会提示连续输入两次密码，-c表示新建文件
注意-c参数会覆盖同名文件，追加第二个账号时千万不要再带它，否则之前的账号会被清空：
htpasswd /etc/nginx/.htpasswd dev1 # 追加用户，不带-c
如果不想安装额外工具，也可以用OpenSSL生成密码串后手动拼文件，或者用Python的crypt库来生成。密码文件权限也很重要，建议设置为chmod 640并把属主改成nginx运行用户，避免被普通用户读取。
二、Nginx核心配置写法
开启认证只需要两个指令：auth_basic定义提示信息并启用认证，auth_basic_user_file指定密码文件路径。最简单的全局写法：
server {
listen 80;
server_name admin.example.ipipp.com;
auth_basic "Restricted Area";
auth_basic_user_file /etc/nginx/.htpasswd;
location / {
root /data/admin;
index index.html;
}
}放在server块里，整个站点都会要求认证；如果只想保护某个路径，把指令下放到对应的location中即可，其余路径不受影响：
server {
listen 80;
server_name www.example.ipipp.com;
location / {
root /data/www;
index index.html;
}
# 仅管理后台需要认证
location /admin/ {
auth_basic "Admin Login";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
}
}需要注意嵌套location的继承规则：子location会继承父级的auth_basic配置，除非在子块中显式写auth_basic off;关闭。配置完成后用nginx -t检查语法，再执行nginx -s reload平滑加载，浏览器访问就能看到弹出的认证框了。
如果想用curl测试，可以这样带凭据访问：
curl -u admin:密码 http://www.example.ipipp.com/admin/ # 或不交互查看响应头 curl -I -u admin:密码 http://www.example.ipipp.com/admin/
三、401报错与常见坑排查
配置后访问返回401或反复弹框，最常见的原因有四个。第一是密码文件路径错误，Nginx worker进程没有权限读取，此时error.log里通常能看到open() failed的记录，检查文件属主和SELinux上下文。第二是密码加密格式不被支持，Nginx默认支持CRYPT方式的加密串，若密码是用SHA或者不常见的算法生成，某些版本会验证失败，建议统一用htpasswd默认的apr1（MD5变种）格式。
第三是Windows换行符问题。如果密码文件是在Windows下编辑后上传的，每行末尾会带\r字符，Nginx解析时会把\r当成密码的一部分导致验证失败，用dos2unix转换一下即可。第四是反向代理场景下，后端服务自己也做了一层认证，两层验证叠加导致逻辑混乱，这时要明确分工，通常只保留Nginx这一层，后端通过proxy_set_header Authorization "";清掉透传的认证头。
另外提醒一点，Basic Auth的凭据是Base64编码后放在Authorization请求头里传输的，Base64只是编码不是加密，抓包就能还原出明文密码。因此生产环境务必配合HTTPS使用，否则密码等于裸奔。证书可以用Let's Encrypt免费签发，配置ssl证书后整套方案才算安全。
四、进阶玩法：白名单与认证组合
实际业务中经常有这样的需求：办公室IP直接放行，外部访问才要求密码。这可以通过satisfy指令配合allow/deny实现：
location /admin/ {
# 默认拒绝所有，再放行内网段
satisfy any;
allow 192.168.1.0/24;
allow 10.0.0.0/8;
deny all;
auth_basic "Admin Login";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
}satisfy any表示IP白名单和密码认证满足任意一个即可访问；改成satisfy all则要求两个条件同时满足，安全性更高但使用更麻烦，按需选择。
还可以给不同目录配置不同的密码文件，实现多套账号体系。比如/admin/用管理员账号组，/reports/用只读账号组，两个location分别指向不同的auth_basic_user_file即可。这套方案不依赖任何后端代码，对静态站点、内网工具页来说几乎零成本，是Nginx里性价比最高的访问控制手段之一。
Nginx配置HTTP Basic Auth访问认证修改时间：2026-09-13 15:02:40