auth_basic_user_file 是 Nginx 实现 HTTP 基本认证的核心配置项，指向存储用户名和加密密码的文件；Nginx 原生仅支持 crypt 和 apr1（MD5）格式，不支持 bcrypt 或 SHA-512，除非启用第三方模块。
使用 auth_basic_user_file 是 Nginx 中实现 HTTP 基本认证（Basic Auth）的核心配置项，它指向一个存储用户名和加密密码的文件。这个文件不是明文存储密码，而是使用 crypt()（如 Apache 的 htpasswd 工具默认方式）或更安全的 bcrypt、SHA、MD5 等格式——但 Nginx 本身只原生支持 crypt 和 apr1（即 MD5-based Apache 格式），不直接支持 bcrypt 或 SHA-512，除非编译时启用了第三方模块（如 nginx-http-auth-pam-module 或使用 OpenResty）。
生成合法的用户凭据文件
Nginx 不自带密码生成工具，需借助外部命令（最常用的是 htpasswd）。确保已安装 apache2-utils（Ubuntu/Debian）或 httpd-tools（CentOS/RHEL）：
- 创建新文件并添加首个用户（
-c表示新建，会覆盖已有文件）：htpasswd -c /etc/nginx/.htpasswd alice - 追加用户（不带
-c）：htpasswd /etc/nginx/.htpasswd bob - 指定哈希算法（推荐更强的
-B使用 bcrypt，但注意：Nginx 原生不识别 bcrypt 格式；若用-B，需搭配支持 bcrypt 的第三方模块，否则会导致认证失败）：
安全且兼容的写法是：htpasswd -m /etc/nginx/.htpasswd charlie（-m表示 MD5-based apr1，Nginx 支持）
在 Nginx 配置中启用 basic auth
在 server 或 location 块中设置认证相关指令：
-
auth_basic "Restricted Area";—— 设置认证域名称（浏览器弹窗中显示） -
auth_basic_user_file /etc/nginx/.htpasswd;—— 指向凭据文件的绝对路径 - 确保该文件对 Nginx worker 进程（通常是
www-data或nginx用户）可读：sudo chown root:www-data /etc/nginx/.htpasswdsudo chmod 640 /etc/nginx/.htpasswd
示例片段：
location /admin/ {
auth_basic "Admin Access";
auth_basic_user_file /etc/nginx/.htpasswd;
}
验证格式与排查常见错误
凭据文件每行格式为：username:hash，例如：alice:$apr1$ZaKvQJ7F$X9zLqVwYbRjT7gUkWnEoP.
- 检查 hash 前缀：
$apr1$表示 MD5-based（Nginx 支持），$2y$表示 bcrypt（Nginx 原生不支持） - 确认路径拼写正确，且 Nginx 能访问该路径（SELinux 或 AppArmor 可能拦截）
- 重启或重载 Nginx 后测试：
sudo nginx -t && sudo systemctl reload nginx - 若提示 “No user/password provided” 或 401 但不弹窗，可能是浏览器缓存了错误凭据，或前端代理（如 Cloudflare）屏蔽了认证头
安全注意事项
HTTP Basic Auth 明文传输凭证（仅 Base64 编码，非加密），必须配合 HTTPS 使用，否则密码易被截获。
- 禁止在 HTTP 站点启用 basic auth
- 避免将
.htpasswd放在网站根目录下（防止被直接下载） - 定期轮换密码，尤其当员工离职或设备失窃时
- 如需更高安全性，考虑结合 OAuth2、JWT 或反向代理后端鉴权（如 Keycloak）
