在 VPS 上用 htpasswd 为目录设置密码保护

基本认证是把测试站点、管理目录或私有工具藏到登录框之后的最快方法。本教程在您的 VPS Linux Infrawire 上同时介绍 Apache 和 Nginx，密码文件由 htpasswd 生成。

📋 前提条件

一台可通过 SSH 以 root 登录的 Linux VPS（Ubuntu 24.04 / Debian 12 或 AlmaLinux 9 / Rocky 9）。IP 和 root 密码在客户中心。
已有 Apache 或 Nginx 正在托管站点。
example.com 的有效 HTTPS 证书。基本认证以 Base64 编码发送密码，这并不是加密：切勿在纯 HTTP 下使用。

📦 安装 htpasswd 工具

即使使用 Nginx，htpasswd 命令也来自一个小软件包：

Bash
1# Debian / Ubuntu
2sudo apt install -y apache2-utils
3
4# AlmaLinux / Rocky
5sudo dnf install -y httpd-tools

🔐 创建密码文件

把文件放在任何网站根目录之外，避免被人下载：

Bash
1sudo mkdir -p /etc/htpasswd
2sudo htpasswd -c -B /etc/htpasswd/example.com USER

-B 使用 bcrypt。-c 用于创建文件：只在添加第一个用户时使用，因为对已有文件使用会覆盖全部内容（破坏性操作）。添加其他用户时不要加 -c：

Bash
1sudo htpasswd -B /etc/htpasswd/example.com USER2

Web 服务器必须能读取该文件：

Bash
1# Debian / Ubuntu（Apache 和 Nginx 都以 www-data 运行）
2sudo chown root:www-data /etc/htpasswd/example.com
3# AlmaLinux / Rocky：Apache 用 apache 组，Nginx 用 nginx 组
4sudo chmod 640 /etc/htpasswd/example.com

删除用户：sudo htpasswd -D /etc/htpasswd/example.com USER2。

🪶 方案 A：Apache 与 .htaccess

在需要保护的目录中放置 .htaccess 文件，例如 /var/www/example.com/private/.htaccess：

Apache
AuthType Basic
AuthName "受限区域"
AuthUserFile /etc/htpasswd/example.com
Require valid-user

除非虚拟主机允许，否则 .htaccess 会被忽略。在 <Directory> 块中设置（Debian/Ubuntu 位于 /etc/apache2/sites-available/，AlmaLinux/Rocky 位于 /etc/httpd/conf.d/）：

Apache
<Directory /var/www/example.com>
    AllowOverride AuthConfig
</Directory>

然后测试并重载：

Bash
1sudo apachectl configtest
2sudo systemctl reload apache2   # Debian / Ubuntu
3sudo systemctl reload httpd     # AlmaLinux / Rocky

如果不想使用 .htaccess，可以把这四行认证指令直接写进 <Directory> 或 <Location> 块：更快也更安全。

🚀 方案 B：Nginx 与 auth_basic

Nginx 不读取 .htaccess。把指令加到 server 块中：

Nginx
1server {
2    listen 443 ssl;
3    server_name example.com;
4    # 此处放 ssl_certificate 相关行
5
6    location /private/ {
7        auth_basic           "受限区域";
8        auth_basic_user_file /etc/htpasswd/example.com;
9    }
10}

要保护整个站点，请把这两行放在 server 块中。若要在受保护的站点里让某个路径保持公开（例如 webhook），在它自己的 location 中加入 auth_basic off;。然后：

Bash
1sudo nginx -t && sudo systemctl reload nginx

✅ 测试

不带凭据应返回 401，带凭据应返回 200：

Bash
1curl -I https://example.com/private/
2curl -I -u USER https://example.com/private/

第一次预期响应：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="受限区域"

只写 -u USER 时 curl 会提示输入密码，这样密码不会留在 shell 历史记录里。

🛠️ 故障排查

Apache 不弹出登录框。 AllowOverride 仍是 None，或 .htaccess 放错了目录。重新检查 <Directory> 块并重载。

密码正确却一直 401。 Web 服务器无法读取该文件（检查 chown 和 chmod），或 AuthUserFile / auth_basic_user_file 中的路径有误。错误日志会说明原因：/var/log/apache2/error.log、/var/log/httpd/error_log 或 /var/log/nginx/error.log。

添加 .htaccess 后出现 500 错误。 某条指令无效或缺少所需模块。运行 sudo apachectl configtest 并阅读提示信息。

通过 HTTP 弹出密码框。 请先把 HTTP 重定向到 HTTPS，避免凭据以明文传输。

🎉 您的私有目录现在需要登录，密码以哈希形式存放在无法被访问的位置，并且只通过 HTTPS 提供。