中文

应用程序

安装 Nginx Proxy Manager

在 Debian 或 Ubuntu 上使用 Docker 安装 Nginx Proxy Manager,让其管理界面不暴露在互联网上,以 HTTPS 发布服务,限制访问,并完成更新与备份。

阅读约 10 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

Nginx Proxy Manager(NPM)是基于 Nginx 的反向代理,通过网页界面进行管理。它在 80 和 443 端口接收访客请求,申请 Let’s Encrypt 证书,并将请求转发给您的服务,您无需自己编写任何 Nginx 配置。

完成本指南后,NPM 将在 Docker 中运行,其管理界面只能通过 SSH 隧道访问。一个测试服务将通过 https://app.您的域名.com 响应,您也将掌握如何限制访问、更新 NPM 以及备份其数据。

使用的版本是 2.17.0,即撰写时(2026 年 11 月)的最新稳定版本。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

  • 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器,架构为 amd64 或 arm64
  • 使用具有 sudo 权限且属于 docker 组的用户进行 SSH 访问
  • 已按照指南安装 Docker Engine 和 Docker Compose安装 Docker Engine 和 Docker Compose
  • 一个由您管理 DNS 区域的域名
  • 没有其他软件占用 80 和 443 端口,例如 Nginx、Apache、Caddy 或 Traefik

使用的端口

端口 方向 作用 是否需要开放
80/tcp 入站 Let’s Encrypt 验证以及重定向到 HTTPS 是
443/tcp 入站 以 HTTPS 发布的站点 是
81/tcp 本地 管理界面,位于 127.0.0.1 否

步骤 1:将域名指向服务器

为 app.您的域名.com 创建一条指向 您的服务器IP 的 A 记录。如果您的域名由 HostMyServers 管理,请参阅指南创建 A 记录。

然后在服务器上检查结果:

终端
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.您的域名.com
dig +short AAAA app.您的域名.com

第一条命令应返回您服务器的地址。如果第二条命令返回了 IPv6 地址,它也必须对应这台服务器。否则,请删除该 AAAA 记录。

步骤 2:准备文件夹和网络

创建项目文件夹,然后创建 NPM 与待发布服务共用的 Docker 网络:

终端
sudo install -d -o "$USER" -g "$USER" /opt/npm
docker network create proxy

步骤 3:编写 Compose 文件

终端
nano /opt/npm/compose.yaml
YAML
services:
  npm:
    image: jc21/nginx-proxy-manager:2.17.0
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:81:81"
    environment:
      TZ: "Europe/Paris"
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - proxy

networks:
  proxy:
    external: true
元素 作用
127.0.0.1:81:81 使界面只能从服务器本机访问
./data SQLite 数据库、应用密钥、主机配置和日志
./letsencrypt 证书和私钥
proxy NPM 用来连接您各个服务的网络

步骤 4:启动 NPM

终端
cd /opt/npm
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f npm

首次启动会初始化数据库并生成密钥,可能需要几分钟。请按 Ctrl+C 退出日志,然后检查端口:

终端
sudo ss -ltnp | grep -E ':(80|81|443) '

81 端口应只出现在 127.0.0.1 上。

步骤 5:检查防火墙

Docker 使用自己的规则发布 80 和 443 端口,这些规则先于 UFW 的规则生效。因此,即使没有执行 ufw allow,这两个端口也可以被访问,UFW 无法对其进行限制。这正是必须在 compose.yaml 而不是 UFW 中限制 81 端口的原因。指南配置 UFW 防火墙详细介绍了这一机制。

如果您使用实例自带的防火墙,请同时在客户中心允许 80 和 443 端口。

步骤 6:创建管理员账户

在您的电脑上打开 SSH 隧道,并保持该终端处于打开状态:

终端
ssh -N -L 8181:127.0.0.1:81 您的用户名@您的服务器IP

然后在浏览器中打开 http://127.0.0.1:8181。流量会经由加密的隧道传输。

NPM 会显示用于创建账户的 Welcome! 界面。请填写 Full Name、Email address 和 Password(至少 8 个字符,但请选择一个较长且唯一的密码),然后确认。该邮箱地址同时用于在 Let’s Encrypt 注册:请填写一个有效的邮箱。

此处的菜单名称以英文给出,这是界面的默认语言。您可以在界面中更改语言。

接着加强安装的安全性:

  1. 打开右上角的账户菜单,然后选择 Two-Factor Auth。启用双重身份验证,并妥善保管备用代码。
  2. 在 Settings 中打开 Default Site,选择 No Response (444)。与您的任何域名都不匹配的请求将不再收到欢迎页面。

步骤 7:发布服务

创建一个连接到 proxy 网络的测试服务。它不会在服务器上发布任何端口:

终端
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yaml
YAML
services:
  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    external: true
终端
cd /opt/whoami
docker compose up -d

在 NPM 中打开 Hosts,然后打开 Proxy Hosts,并点击 Add Proxy Host。在 Details 选项卡中:

字段 值
Domain Names app.您的域名.com
Scheme http
Forward Hostname / IP whoami
Forward Port 80
Access List Publicly Accessible
Block Common Exploits 已启用

名称 whoami 是 Compose 服务的名称,80 是它在容器内部的端口。如果您的应用需要,请启用 Websockets Support。只应将可信的服务连接到 proxy 网络:它们可以在该网络内部访问 NPM 的 81 端口。

在 SSL 选项卡中:

  1. 在 SSL Certificate 中选择 Request a new Certificate。
  2. 启用 Force SSL 和 HTTP/2 Support。
  3. 保持 Use DNS Challenge 处于禁用状态:验证通过 80 端口进行。

点击 Save。只有在确定该域名会一直使用 HTTPS 之后,才启用 HSTS Enabled:浏览器会记住这一选择。

NPM 每小时检查一次证书,并续期有效期不足 30 天的证书。

验证结果

在服务器或您的电脑上执行:

终端
curl -I http://app.您的域名.com
curl -I https://app.您的域名.com
echo | openssl s_client -connect app.您的域名.com:443 -servername app.您的域名.com 2>/dev/null | openssl x509 -noout -issuer -dates

HTTP 请求应返回指向 HTTPS 的重定向,HTTPS 请求应返回 200 状态码。证书的颁发者应为 Let’s Encrypt。

在您的电脑上,管理端口不应有响应:

终端
curl -m 5 http://您的服务器IP:81

限制对服务的访问

在 Access Lists 中点击 Add Access List:

  1. 在 Details 中为列表命名。保持 Satisfy Any 处于禁用状态,以要求满足所有条件,同时保持 Pass Auth to Upstream 处于禁用状态。
  2. 在 Authorizations 中添加用户名和密码。
  3. 在 Rules 中添加一条 Allow 规则,填入 您的IP。只要存在规则,NPM 就会在末尾添加一条 deny all。

保存后,在 Proxy Host 的 Access List 字段中选择该列表。

通过域名访问界面

SSH 隧道仍然是最安全的方式。如果您更希望使用域名,请将界面置于 NPM 之后,并且将其限定为只能从您的 IP 地址访问:

  1. 为 npm.您的域名.com 创建一条 A 记录,不要创建 AAAA 记录。通过 IPv6 发起的连接可能带着 Docker 网关的地址到达,从而被拒绝。
  2. 创建一个访问列表,其中只包含 Allow 规则 您的IP,不设用户:NPM 的界面本身就使用 Authorization 请求头。
  3. 创建 Proxy Host npm.您的域名.com,使用 http 指向 127.0.0.1,端口 81,并应用该访问列表。
  4. 在 SSL 中申请证书并启用 Force SSL。

请保留 127.0.0.1:81:81 这一发布方式:出错时,您可以借此通过 SSH 隧道重新进入。如果您的 IP 地址经常变化,建议改用 WireGuard 或 Tailscale 组成私有网络。

更新

请先阅读版本说明。例如,2.17.0 版本更新了 Certbot,可能会导致某些 DNS 插件失效。然后备份 NPM,修改 compose.yaml 中的镜像标签,再执行:

终端
cd /opt/npm
docker compose pull
docker compose up -d
docker compose logs --tail 50 npm

接着检查能否登录界面,以及您的服务能否正常访问。

备份与恢复

所有内容都位于 /opt/npm 中:文件 compose.yaml、data 和 letsencrypt。请在制作归档期间停止 NPM,以获得一致的 SQLite 数据库:

终端
cd /opt/npm
docker compose stop
sudo tar -czf /root/npm-$(date +%F).tar.gz -C /opt npm
sudo chmod 600 /root/npm-$(date +%F).tar.gz
docker compose start

该归档包含私钥:请将其复制到服务器之外的加密位置。如果您配置了 DNS 验证,它还可能包含您的 API 凭据。

要恢复归档,请将 YYYY-MM-DD 替换为归档的日期,如果该服务器上尚不存在 proxy 网络,请先创建它:

终端
cd /opt/npm 2>/dev/null && docker compose down
sudo tar -xzf /root/npm-YYYY-MM-DD.tar.gz -C /opt
docker network create proxy
cd /opt/npm
docker compose up -d

故障排除

在 /opt/npm 中执行 docker compose logs --tail 100 npm 即可显示常规日志。每个 Proxy Host 的日志位于 /opt/npm/data/logs/,文件名形如 proxy-host-1_access.log 和 proxy-host-1_error.log。请使用 sudo 读取它们。

port is already allocated 或 address already in use

另一个服务占用了 80 或 443 端口:

终端
sudo ss -ltnp | grep -E ':(80|443) '

如果不再需要该服务,请将其停止,例如使用 sudo systemctl disable --now nginx。

Address family not supported by protocol

服务器没有 IPv6。请在 environment 中添加以下变量,然后使用 docker compose up -d 重新启动:

YAML
DISABLE_IPV6: "true"

channel 2: open failed: connect failed: Connection refused

SSH 隧道工作正常,但 81 端口上没有任何程序在监听。NPM 仍在启动,或者已经停止:请检查 docker compose ps 及其日志。

502 Bad Gateway

NPM 无法连接到该服务。请检查容器是否已启动、是否已连接到 proxy 网络,以及 Proxy Host 中的名称和端口是否准确:

终端
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'

在 Forward Hostname / IP 中,127.0.0.1 指的是 NPM 容器本身,而不是服务器。服务也必须在其容器内监听 0.0.0.0。

证书未能签发

自 2.17 版本起,界面会显示 Certbot 给出的原因:

  • NXDOMAIN:该域名在 DNS 中尚不存在。
  • Timeout during connect 或 Connection refused:无法从互联网访问 80 端口。请检查 A 和 AAAA 记录,然后检查实例的防火墙。如果一切正常,请通过客户中心联系支持团队。
  • CAA record:某条 CAA 记录禁止了 Let’s Encrypt。
  • too many certificates 或 too many failed authorizations:已达到 Let’s Encrypt 的某项限制。请等到消息中指明的日期。

受保护的服务出现 403 Forbidden

您的地址不在访问列表中。请将其与 Proxy Host 访问日志中记录的地址进行比较,然后修正规则。

添加密码后应用的登录陷入循环

这是前文所述的 Authorization 请求头冲突。请从访问列表中移除用户,只保留 IP 地址规则。

重定向循环

应用在不识别 X-Forwarded-Proto 请求头的情况下强制使用 HTTPS。请在应用中启用“trust proxy”选项或其等效选项。如果域名经过 Cloudflare 代理,请将 SSL/TLS 模式设为 Full (strict)。

参考资料