安装 Nginx Proxy Manager
在 Debian 或 Ubuntu 上使用 Docker 安装 Nginx Proxy Manager,让其管理界面不暴露在互联网上,以 HTTPS 发布服务,限制访问,并完成更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
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.yamlservices:
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 注册:请填写一个有效的邮箱。
此处的菜单名称以英文给出,这是界面的默认语言。您可以在界面中更改语言。
接着加强安装的安全性:
- 打开右上角的账户菜单,然后选择 Two-Factor Auth。启用双重身份验证,并妥善保管备用代码。
- 在 Settings 中打开 Default Site,选择 No Response (444)。与您的任何域名都不匹配的请求将不再收到欢迎页面。
步骤 7:发布服务
创建一个连接到 proxy 网络的测试服务。它不会在服务器上发布任何端口:
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yamlservices:
whoami:
image: traefik/whoami:v1.12.0
restart: unless-stopped
networks:
- proxy
networks:
proxy:
external: truecd /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 选项卡中:
- 在 SSL Certificate 中选择 Request a new Certificate。
- 启用 Force SSL 和 HTTP/2 Support。
- 保持 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 -datesHTTP 请求应返回指向 HTTPS 的重定向,HTTPS 请求应返回 200 状态码。证书的颁发者应为 Let’s Encrypt。
在您的电脑上,管理端口不应有响应:
curl -m 5 http://您的服务器IP:81限制对服务的访问
在 Access Lists 中点击 Add Access List:
- 在 Details 中为列表命名。保持 Satisfy Any 处于禁用状态,以要求满足所有条件,同时保持 Pass Auth to Upstream 处于禁用状态。
- 在 Authorizations 中添加用户名和密码。
- 在 Rules 中添加一条 Allow 规则,填入
您的IP。只要存在规则,NPM 就会在末尾添加一条deny all。
保存后,在 Proxy Host 的 Access List 字段中选择该列表。
通过域名访问界面
SSH 隧道仍然是最安全的方式。如果您更希望使用域名,请将界面置于 NPM 之后,并且将其限定为只能从您的 IP 地址访问:
- 为
npm.您的域名.com创建一条 A 记录,不要创建 AAAA 记录。通过 IPv6 发起的连接可能带着 Docker 网关的地址到达,从而被拒绝。 - 创建一个访问列表,其中只包含 Allow 规则
您的IP,不设用户:NPM 的界面本身就使用Authorization请求头。 - 创建 Proxy Host
npm.您的域名.com,使用http指向127.0.0.1,端口81,并应用该访问列表。 - 在 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 重新启动:
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)。