nginx 的 auth_basic 模块通过 auth_basic 和 auth_basic_user_file 指令实现轻量 http 基础认证，需配合 htpasswd 生成加密密码文件、限定 location 范围、强制 https 传输并确保文件权限安全。
Nginx 的 auth_basic 模块提供了一种轻量、标准的 HTTP 基础认证（Basic Authentication）方式，无需额外依赖，适合对特定 location 或整个站点做简单访问控制。
启用 auth_basic 并指定认证域
在 server 或 location 块中添加 auth_basic 指令，它会触发浏览器弹出登录框，并设置响应头 WWW-Authenticate 中的 realm 字符串：
location /admin/ {
auth_basic "Restricted Area";
auth_basic_user_file /etc/nginx/.htpasswd;
}
其中 "Restricted Area" 是显示给用户的提示文字（非密码提示），不同 realm 会被浏览器视为独立认证上下文。
生成兼容的用户密码文件
Nginx 不自带密码生成工具，需用 htpasswd（Apache 工具）或 OpenSSL 手动创建符合格式的文件。每行格式为：username:password_hash，密码必须是 crypt、apr1（MD5）、SHA 或 bcrypt 格式（推荐 bcrypt）：
- 安装
apache2-utils（Ubuntu/Debian）或httpd-tools（CentOS/RHEL）后运行：htpasswd -B -c /etc/nginx/.htpasswd alice（-B启用 bcrypt，-c创建新文件） - 若无 htpasswd，可用 OpenSSL 生成 crypt 格式（安全性较低，仅作临时测试）：
printf "alice:$(openssl passwd -crypt mypass)\n" >> /etc/nginx/.htpasswd
确保该文件由 Nginx worker 进程可读（如 chown www-data:www-data /etc/nginx/.htpasswd），且路径不在 web 可访问范围内。
配合其他指令提升安全性
基础认证本身明文传输（实际靠 HTTPS 保护凭证），因此必须与 SSL/TLS 结合使用。同时建议限制认证范围，避免误配导致全站锁死：
- 只在需要保护的 location 中启用，不要放在顶层 server 块里影响静态资源
- 搭配
satisfy any;和 IP 白名单实现“认证或白名单”逻辑（需同时加载ngx_http_access_module） - 禁用缓存敏感接口：添加
add_header Cache-Control "no-store, no-cache, must-revalidate";防止浏览器缓存认证后的内容
调试常见问题
若认证不生效或反复弹窗，检查以下几点：
- 确认
auth_basic_user_file路径正确、文件存在、权限可读 - 查看 Nginx 错误日志（
error_log）是否有open() "/path/.htpasswd" failed类报错 - 浏览器可能缓存了错误凭据：尝试隐身窗口，或清除当前域的 HTTP 认证状态（Chrome 地址栏输入
chrome://settings/clearBrowserData→ 勾选“密码和表单数据”） - 确认未被 upstream 或 proxy_pass 覆盖：若反向代理后端服务，需确保认证在 proxy 前生效，或后端也支持并透传认证头
