使用 ngx_http_auth_basic_module 结合外部密码文件是为 Nginx 内部接口添加基础访问控制最轻量稳妥的方式，无需后端逻辑、不引入额外服务、兼容所有 HTTP 客户端。
使用 ngx_http_auth_basic_module 结合外部密码文件，是为 Nginx 托管的内部接口添加基础访问控制最轻量、最稳妥的方式之一。它不依赖后端逻辑，不引入额外服务，且兼容所有 HTTP 客户端（包括 curl、Postman、前端 fetch 等）。
确认模块已启用并配置 auth_basic 指令
Nginx 默认编译通常已包含该模块（可通过 nginx -V 2>&1 | grep -o with-http-auth-basic-module 验证）。只需在 location 块中启用认证：
- 在需保护的接口 location 中添加：
auth_basic "Restricted Area"; - 指定密码文件路径：
auth_basic_user_file /etc/nginx/.htpasswd; - 注意：路径必须是 Nginx worker 进程有读取权限的绝对路径；相对路径以 Nginx 配置目录为基准，易出错，不推荐。
生成符合格式的外部密码文件（.htpasswd）
该文件每行一个用户，格式为 username:encrypted_password，密码必须用 Apache 兼容的 crypt(3)、MD5、SHA-1 或 bcrypt 加密（Nginx 1.19+ 支持 bcrypt，推荐）。
- 使用
htpasswd工具（来自apache2-utils或httpd-tools）生成：htpasswd -c -B /etc/nginx/.htpasswd admin（-B表示 bcrypt，-c表示新建） - 若无
htpasswd，可用 Python 快速生成 bcrypt 密码：python3 -c "from passlib.hash import bcrypt; print(bcrypt.using(rounds=12).hash('mypass'))"，再手动拼成admin:$2b$12$...写入文件 - 切勿明文存储密码；避免使用弱哈希如 crypt 或 MD5（仅用于兼容旧环境）
限制作用域：精准保护内部接口，避免误拦静态资源或健康检查
不要在 server 级别全局开启，而应按需绑定到具体路径，尤其注意排除监控探针和前端资源：
- 只保护 API 接口路径：
location ^~ /api/v1/internal/ { auth_basic ...; auth_basic_user_file ...; } - 放行健康检查（如 Kubernetes livenessProbe）：
location = /healthz { auth_basic off; } - 若前端与 API 同域，确保
/static/、/assets/等路径未被继承认证规则（利用 location 匹配优先级，显式关闭）
增强实用性的小技巧
生产环境中可进一步提升可维护性与安全性：
- 将密码文件挂载为只读 ConfigMap（K8s）或通过 Ansible/Vault 管理，禁止直接编辑
- 配合
auth_request模块实现动态校验（如对接内部鉴权服务），但此时已超出“轻量级”范畴，需权衡复杂度 - 记录认证失败日志便于审计：
error_log /var/log/nginx/auth_error.log warn;（warn 级别会记录 401 请求） - 浏览器下输入错误凭据会弹窗重试，curl 则需显式传参：
curl -u admin:mypass https://example.com/api/v1/internal/status
这种方式不改变业务代码，零运行时开销，部署即生效，适合 DevOps 快速加固管理后台、调试接口、内部 Webhook 等低敏感但需防误触的场景。
