当前Nginx Docker镜像是否未集成ngx_http_auth_basic_module？401错误如何解决

关于镜像模块集成的说明 #

官方Nginx Docker镜像分不同变体：

• 基于Debian/Ubuntu的nginx:latest、nginx:stable等版本，默认编译包含ngx_http_auth_basic_module；
• 主打轻量的nginx:alpine镜像为了精简体积，默认未编译该模块，这就是你执行检查命令后输出为空的原因。

解决方法 #

方法1：切换到官方非Alpine镜像

直接改用nginx:latest或nginx:stable镜像重新部署，这些版本默认集成所需模块。验证模块是否存在的命令：

docker run --rm nginx:latest nginx -V 2>&1 | grep http_auth_basic_module

正常输出会显示--with-http_auth_basic_module，说明模块已集成。

方法2：自定义编译Alpine版Nginx（若必须保留Alpine特性）

如果需要维持Alpine镜像的轻量优势，需自行编译Nginx并加入目标模块，步骤如下：

1. 创建Dockerfile：

FROM alpine:latest

RUN apk add --no-cache gcc musl-dev make openssl-dev pcre-dev zlib-dev wget \
    && wget http://nginx.org/download/nginx-1.25.3.tar.gz \
    && tar -xzf nginx-1.25.3.tar.gz \
    && cd nginx-1.25.3 \
    && ./configure --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib/nginx/modules --conf-path=/etc/nginx/nginx.conf --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --pid-path=/var/run/nginx.pid --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --user=nginx --group=nginx --with-compat --with-file-aio --with-threads --with-http_addition_module --with-http_auth_basic_module --with-http_dav_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_realip_module --with-http_secure_link_module --with-http_slice_module --with-http_ssl_module --with-http_stub_status_module --with-http_sub_module --with-http_v2_module --with-mail --with-mail_ssl_module --with-stream --with-stream_realip_module --with-stream_ssl_module --with-stream_ssl_preread_module \
    && make && make install \
    && apk del gcc musl-dev make openssl-dev pcre-dev zlib-dev wget \
    && rm -rf /nginx-1.25.3* /var/cache/apk/*

RUN addgroup -S nginx && adduser -S nginx -G nginx

EXPOSE 80 443

CMD ["nginx", "-g", "daemon off;"]

2. 构建自定义镜像：

docker build -t nginx-alpine-with-auth .

3. 使用该自定义镜像部署服务即可。

额外配置检查

即使模块正常，以下问题也会导致401错误：

• 确认.htpasswd文件已正确挂载到容器内，且Nginx进程拥有读取权限；
• auth_basic_user_file指令指定的是容器内的绝对路径，而非宿主机路径；
• 用户名密码需通过htpasswd命令生成（例如htpasswd -c /path/to/.htpasswd your_username），避免手动编辑导致格式错误。

内容的提问来源于stack exchange，提问作者keshuan_jeme