如何在 Nginx 中配置 Basic Auth 密码认证保护特定目录访问

在 Nginx 中配置 Basic Auth 密码认证保护特定目录，需要在 location 块中添加 auth_basic 和 auth_basic_user_file 指令，并配合 htpasswd 工具生成密码文件。

该方案适合保护后台入口或敏感文件，但必须配合 HTTPS 使用，否则密码会以 Base64 编码明文传输，存在被嗅探风险。

先说结论：配置 Nginx Basic Auth 的核心是生成密码文件并在 location 块中启用 auth_basic 模块，无需重启服务即可生效。

适合：保护管理后台、临时封闭特定目录或限制 API 访问。
先准备：安装 apache2-utils 或 httpd-tools 工具包，确保证书文件权限安全。
验收：使用 curl 命令或未登录浏览器访问，确认弹出认证框且错误密码被拒绝。

命令速用版

以下命令用于生成密码文件并展示基础配置结构，直接复制需修改路径和域名。

# 1. 生成密码文件（首次创建用 -c，追加用户去掉 -c）
htpasswd -c /etc/nginx/.passwd username

# 2. Nginx 配置片段
location /protected/ {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.passwd;
}

# 3. 检查并重载配置
nginx -t
nginx -s reload

为什么会这样

Nginx 的 auth_basic 模块通过 HTTP 协议标准的 Authorization 头进行身份验证，浏览器会自动处理弹窗逻辑。

当用户访问受保护目录时，Nginx 返回 401 状态码，浏览器弹出输入框。用户输入凭证后，Nginx 将密码加密哈希与密码文件中的记录比对。该机制依赖客户端配合，不适合需要自定义登录界面或复杂权限管理的场景，但配置成本极低。

分步处理

按顺序执行以下步骤，每步完成后检查对应状态，确保配置无误。

步骤 1：安装密码工具

Linux 发行版默认可能未安装 htpasswd 命令，需手动安装工具包。

Debian/Ubuntu 系统执行：apt-get install apache2-utils

CentOS/RHEL 系统执行：yum install httpd-tools

步骤 2：生成密码文件

使用 htpasswd 命令创建存储用户名和加密密码的文件，文件路径建议放在 Nginx 配置目录内。

执行 htpasswd -c /etc/nginx/.passwd admin 输入两次密码。

注意：-c 参数仅在首次创建文件时使用，追加新用户时去掉 -c，否则会清空原有用户。

执行 chmod 640 /etc/nginx/.passwd 限制文件权限，确保仅 Nginx 进程用户可读。

步骤 3：修改 Nginx 配置

打开 Nginx 配置文件，通常在 /etc/nginx/nginx.conf 或 /etc/nginx/conf.d/ 下的站点配置文件中。

在需要保护的 location 块内添加 auth_basic 和 auth_basic_user_file 指令。

示例配置：

server {
    listen 80;
    server_name example.com;

    location /admin/ {
        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.passwd;
        # 其他配置...
    }
}

步骤 4：检查并重载

执行 nginx -t 确认配置语法无误，出现 successful 提示后再执行 nginx -s reload 应用更改。

若 nginx -t 报错，检查密码文件路径是否正确，或是否存在拼写错误。

怎么验证是否生效

通过浏览器和命令行工具双重验证，确保认证机制正常工作且无权限泄露。

浏览器验证：在无痕模式下访问 http://example.com/admin/，页面应立即弹出用户名密码输入框。输入错误密码应显示 401 Authorization Required 页面。

命令行验证：使用 curl 命令模拟请求。

未带凭证访问：curl -I http://example.com/admin/ 应返回 HTTP/1.1 401 Unauthorized。

带正确凭证访问：curl -u admin:password http://example.com/admin/ 应返回 HTTP/1.1 200 OK。

带错误凭证访问：curl -u admin:wrongpass http://example.com/admin/ 应返回 HTTP/1.1 401 Unauthorized。

常见坑

配置过程中容易忽略权限设置和传输加密，导致安全隐患或服务不可用。

密码文件权限过大：若 /etc/nginx/.passwd 文件对所有用户可读，存在密码哈希泄露风险。务必执行 chmod 640 并将属组设为 nginx 或 www-data。

未启用 HTTPS：Basic Auth 的密码仅经过 Base64 编码，未加密传输。在 HTTP 环境下，抓包即可还原密码。生产环境必须配置 SSL 证书，强制 HTTPS 访问。

配置层级冲突：若在 server 块开启了 auth_basic，但在某个 location 块想取消认证，需显式设置 auth_basic off;，否则子目录会继承父级配置。

常见问题

如何添加多个用户？

再次运行 htpasswd 命令但不加 -c 参数即可追加用户。

执行 htpasswd /etc/nginx/.passwd user2 输入新密码，原有用户保留，新用户生效。

如何取消某个目录的认证？

在该 location 块中显式关闭 auth_basic 继承。

添加 auth_basic off; 指令，Nginx 会停止对该 location 及其子目录的认证要求。

忘记密码文件路径怎么办？

在 Nginx 配置文件中搜索 auth_basic_user_file 指令查找路径。

执行 grep -r "auth_basic_user_file" /etc/nginx/ 可快速定位配置文件和文件路径。

参考来源

Nginx Official Documentation, Module ngx_http_auth_basic_module, http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html