Nginx Proxy Manager 详细入门教程：安装与配置 – wiki基地

---

Nginx Proxy Manager 详细入门教程：安装与配置

在当今的网络环境中，运行多个Web服务、容器或应用程序变得越来越普遍。如何优雅地管理这些服务，让它们都能通过你的域名安全地访问，并轻松地获取和续订SSL证书？手动配置Nginx或Apache的反向代理虽然强大，但对于新手来说门槛较高，特别是证书的申请和续期更是令人头疼。

这时，Nginx Proxy Manager (NPM) 应运而生。它是一个基于Web界面的反向代理管理工具，极大地简化了使用Nginx进行反向代理、SSL证书管理（特别是Let’s Encrypt）等操作。无需编写一行Nginx配置文件，通过简单的图形界面点击即可完成复杂的设置。

本教程将详细介绍如何从零开始安装Nginx Proxy Manager，并指导你完成基本的反向代理配置和SSL证书的申请，让你轻松迈出管理Web服务的第一步。

引言：为什么选择 Nginx Proxy Manager？

在深入安装之前，让我们先了解一下为什么选择NPM：

1. 用户友好的Web界面： 这是NPM最大的亮点。所有的配置都在一个直观的Web界面中完成，无需记忆复杂的命令或配置文件语法。
2. 简化的反向代理设置： 为你的内网服务（如运行在不同端口的Web应用）配置域名访问变得异常简单。只需填写域名、目标IP和端口，NPM会自动为你生成并管理Nginx配置。
3. 自动化SSL证书管理： NPM内置了对Let’s Encrypt的支持。你可以轻松地为你的域名申请免费的SSL证书，并且NPM会自动处理证书的续期，让你告别证书过期的烦恼。
4. 集中管理： 所有的反向代理、重定向、流代理配置都集中在一个地方管理，清晰明了。
5. 基于Docker： NPM通常以Docker容器的形式运行，这使得它的安装和升级变得非常方便，也减少了与宿主机系统的依赖冲突。
6. 强大的底层： 虽然操作简单，但NPM底层依然是功能强大的Nginx，因此你可以享受到Nginx带来的高性能和稳定性。

如果你厌倦了手动配置Nginx、处理证书续期，或者你是一个刚接触反向代理的新手，那么Nginx Proxy Manager绝对值得一试。

准备工作：你需要什么？

在开始安装NPM之前，请确保你具备以下条件：

1. 一台服务器或VPS： 这可以是云服务器（如阿里云、腾讯云、AWS、Linode、Vultr等），也可以是家里的物理机或树莓派。确保服务器拥有公网IP地址。
2. 一个域名： 用于外部访问你的服务。例如 yourdomain.com 或 sub.yourdomain.com。你需要有域名的管理权限，以便设置DNS记录。
3. 安装Docker和Docker Compose： NPM最推荐和最便捷的安装方式是使用Docker。如果你的服务器上还没有安装，请参考官方文档进行安装：
   • Docker 安装指南：https://docs.docker.com/engine/install/
   • Docker Compose 安装指南：https://docs.docker.com/compose/install/
   • 注意： 新版本的Docker Compose已经集成到Docker CLI中，使用 docker compose 命令（注意compose中间有空格）即可，无需单独安装 docker-compose 二进制文件。本文将以 docker compose 命令为例。
4. 基础的Linux命令行知识： 你需要能够通过SSH连接到你的服务器，并执行一些基本的Linux命令（如创建文件、运行命令等）。
5. 开放防火墙端口： 确保你的服务器防火墙（包括操作系统防火墙如 ufw 或 firewalld，以及云服务提供商的安全组）开放了以下端口：
   • 80 (HTTP): 用于Let’s Encrypt证书验证和HTTP访问。
   • 443 (HTTPS): 用于HTTPS安全访问。
   • 81: NPM Web UI的管理端口（默认）。这个端口不对外开放也可以，只要你能从内网或通过SSH隧道访问即可。

安装 Nginx Proxy Manager

我们将主要介绍使用Docker Compose进行安装，这是官方推荐且最方便的方式。

步骤 1：创建 Docker Compose 文件

首先，在你的服务器上创建一个用于存放NPM配置文件的目录。例如，在 /opt 目录下创建 npm 目录：

bash
sudo mkdir -p /opt/npm
cd /opt/npm

接下来，在这个目录下创建一个名为 docker-compose.yml 的文件：

bash
sudo nano docker-compose.yml

将以下内容复制到 docker-compose.yml 文件中：

“`yaml
version: ‘3.8’

services:
app:
image: ‘jc21/nginx-proxy-manager:latest’
restart: unless-stopped
ports:
# These ports are in use by Host network or other containers:
# 80:80 # Public HTTP Port
# 443:443 # Public HTTPS Port
# 81:81 # Admin Web Port
# To avoid conflicts, map ports to different host ports if necessary:
– ’80:80′ # 将主机的 80 端口映射到容器的 80 端口
– ‘443:443′ # 将主机的 443 端口映射到容器的 443 端口
– ’81:81’ # 将主机的 81 端口映射到容器的 81 端口 (Web UI 端口)
volumes:
# This assumes your data dir is on a volume named ‘npm_data’
– ./data:/data # 将当前目录下的 data 目录映射到容器的 /data 目录，用于持久化数据
– ./letsencrypt:/etc/letsencrypt # 可选，映射证书目录，方便查看或备份
# depends_on:
# – db # Uncomment if you use a database other than the default SQLite

# Uncomment the sections below if you want to use a database other than SQLite
# db:
# image: ‘jc21/mariadb-aria:latest’
# restart: unless-stopped
# environment:
# MYSQL_ROOT_PASSWORD: ‘changeme’ # <—- CHANGE THIS PASSWORD
# MYSQL_DATABASE: ‘npm’
# MYSQL_USER: ‘npm’
# MYSQL_PASSWORD: ‘changeme’ # <—- CHANGE THIS PASSWORD
# volumes:
# – ./mysql:/var/lib/mysql # This assumes your data dir is on a volume named ‘mysql_data’
# # Note: if you are using a volume, you may need to grant it permissions with chown
# # sudo chown -R 1000:1000 ./mysql

“`

文件内容解释：

• version: '3.8': 指定 Docker Compose 文件版本。
• services:: 定义服务列表。
• app:: 定义一个名为 app 的服务，这是NPM容器。
• image: 'jc21/nginx-proxy-manager:latest': 使用 jc21/nginx-proxy-manager 镜像的最新版本。
• restart: unless-stopped: 设置容器的重启策略。除非手动停止，否则容器崩溃或宿主机重启后会自动重启。
• ports:: 端口映射。
  • - '80:80': 将宿主机的 80 端口映射到容器的 80 端口。重要： 确保宿主机的 80 端口没有被其他服务（如 Apache, Nginx）占用。
  • - '443:443': 将宿主机的 443 端口映射到容器的 443 端口。重要： 确保宿主机的 443 端口没有被其他服务占用。
  • - '81:81': 将宿主机的 81 端口映射到容器的 81 端口。这是NPM Web UI的默认端口。你可以根据需要修改宿主机的端口（例如 - '8181:81'），但容器端口 81 不能改。
• volumes:: 数据卷映射，用于持久化NPM的配置、数据库和证书。
  • - ./data:/data: 将宿主机当前目录下的 data 子目录映射到容器内部的 /data 目录。NPM使用 /data 目录存放SQLite数据库文件（如果你没有配置外部数据库）和配置信息。这个映射非常重要，否则容器删除后你的配置会丢失。
  • - ./letsencrypt:/etc/letsencrypt: （可选但推荐） 将宿主机当前目录下的 letsencrypt 子目录映射到容器内部的 /etc/letsencrypt 目录。Let’s Encrypt 证书会存放在这里，方便你查看、备份或在其他地方使用。
• db: 服务部分被注释掉了。默认情况下，NPM使用SQLite数据库存储配置，数据保存在 /data 目录下。对于大多数入门用户来说，SQLite足够了。如果你需要更高的性能或更大的规模，可以解除注释并配置外部的MySQL或MariaDB数据库。入门阶段不建议修改这部分。

编辑完成后，保存并关闭文件（在 nano 中按 Ctrl + X，然后按 Y，最后按 回车）。

步骤 2：启动容器

在 docker-compose.yml 文件所在的目录下，执行以下命令启动NPM容器：

bash
sudo docker compose up -d

• docker compose up: 根据 docker-compose.yml 文件创建并启动服务。
• -d: 在后台运行容器（detached mode）。

Docker Compose 会自动拉取NPM镜像（如果本地没有），然后创建并启动容器。

步骤 3：验证安装

执行以下命令检查容器是否正在运行：

bash
sudo docker ps

你应该能看到一个名为 npm-app-1 或类似的容器，状态是 Up。

检查宿主机的端口是否在监听：

bash
sudo netstat -tulnp | grep -E ':(80|443|81)'

你应该能看到 Docker 相关的进程正在监听 80, 443, 和 81 端口。

初次登录与基本设置

安装完成后，你现在可以通过Web浏览器访问NPM的管理界面了。

1. 打开浏览器： 访问 http://你的服务器IP地址:81。
2. 登录界面： 你会看到Nginx Proxy Manager的登录界面。
3. 默认凭据：
   • Username: [email protected]
   • Password: changeme
4. 首次登录： 使用默认凭据登录后，系统会强制你修改用户名、邮箱和密码。这是非常重要的安全步骤，请务必修改！
   • 填写新的用户名和邮箱（例如你的真实邮箱或常用邮箱）。
   • 输入当前密码 (changeme)。
   • 设置并确认你的新密码。
   • 点击 Save。

完成密码修改后，你将进入Nginx Proxy Manager的主界面（Dashboard）。

核心功能：配置反向代理 (Proxy Hosts)

现在，最激动人心的时刻到了！我们将配置你的第一个反向代理。假设你在服务器的 localhost:3000 上运行了一个Web应用程序（例如一个Node.js应用，或者一个Docker容器）。你想通过 app.yourdomain.com 这个域名来访问它。

1. 确保域名解析： 在你的域名注册商或DNS服务商那里，添加一条 A记录 或 CNAME记录，将 app.yourdomain.com 指向你的服务器的公网IP地址。请等待DNS记录生效（可能需要几分钟到几小时不等）。你可以使用 ping app.yourdomain.com 或在线DNS查询工具来检查解析是否生效。
2. 进入 Proxy Hosts： 在NPM主界面，点击左侧导航栏的 Hosts，然后选择 Proxy Hosts。
3. 添加 Proxy Host： 点击右上角的 Add Proxy Host 按钮。

配置 Details 标签页

这是配置反向代理的核心部分。

• Domain Names:
  • 填写你想要用来访问这个服务的域名，例如 app.yourdomain.com。
  • 如果你有多个域名指向同一个后端服务，可以在这里添加多行。
  • 重要： 确保你填写的域名已经正确解析到你的NPM服务器的公网IP。
• Scheme:
  • 选择你的后端服务使用的协议。通常是 http。如果你的后端服务已经配置了SSL，可以选择 https。对于初学者，后端通常是HTTP服务，由NPM负责SSL。
• Forward Hostname / IP:
  • 填写你的后端服务运行在哪个IP地址或主机名上。
  • 如果你的后端服务运行在同一台服务器上，通常填写 localhost 或 127.0.0.1。
  • 如果你的后端服务运行在局域网内另一台服务器上，填写那台服务器的局域网IP地址（例如 192.168.1.100）。
  • 如果你的后端服务是另一个Docker容器，并且它们在同一个 Docker 网络中，你可以填写容器名或其在Docker网络中的IP。使用容器名更方便，前提是它们在同一个network下，推荐使用Docker Compose并将所有相关服务放在同一个compose文件中。
• Forward Port:
  • 填写你的后端服务正在监听的端口号。例如 3000。
• Cache Assets:
  • 开启后，NPM会缓存后端服务返回的静态资源（如CSS, JS, 图片）。这可以减轻后端服务的负载并提升访问速度。对于大多数静态网站或Web应用，推荐开启。
• Block Common Exploits:
  • 开启后，NPM会尝试拦截一些常见的Web攻击请求。增加安全性，推荐开启。
• Websockets Support:
  • 如果你的Web应用程序使用了WebSocket（例如聊天应用、在线终端、某些实时监控页面等），必须开启此选项，否则WebSocket连接会失败。如果你的应用不使用WebSocket，保持关闭即可。

填写示例：

• Domain Names: app.yourdomain.com
• Scheme: http
• Forward Hostname / IP: localhost (或 127.0.0.1 或容器名)
• Forward Port: 3000
• Cache Assets: On
• Block Common Exploits: On
• Websockets Support: Off (根据你的应用决定)

配置 SSL 标签页

这是NPM最强大的功能之一：自动化Let’s Encrypt证书。

• SSL Certificate:
  • 选择 <None>: 不使用SSL，只做HTTP代理。
  • 选择 Request a new SSL Certificate: 使用Let’s Encrypt申请免费证书。强烈推荐！
  • 选择 Use an existing SSL Certificate: 如果你已经有其他渠道获得的证书，可以选择上传或引用。
• 如果你选择 “Request a new SSL Certificate”:
  • Force SSL: 开启此选项。这将强制所有HTTP请求自动重定向到HTTPS，确保访问的安全性。
  • HTTP/2 Support: 开启此选项。HTTP/2是新一代的HTTP协议，能提升加载速度。推荐开启。
  • HSTS Enabled: 开启此选项。HTTP Strict Transport Security (HSTS) 是一种安全策略，指示浏览器只通过HTTPS与网站进行通信，即使地址栏输入的是HTTP。可以增强安全性，但请确保你的网站能完全通过HTTPS访问，否则可能导致问题。对于新站点，推荐开启（可以选择有效期 4 months 或更长）。
  • Include Subdomains (Optional): 如果你的域名是 yourdomain.com 并且你在配置 app.yourdomain.com，勾选此项会尝试为 *.yourdomain.com 申请通配符证书。通常你只需要为当前指定的域名申请证书即可，不勾选也行。如果你的域名是 yourdomain.com 主域名，并且你有多个子域名需要SSL，建议为 yourdomain.com 和 *.yourdomain.com 申请通配符证书（需要在DNS提供商处配置一条TXT记录进行验证）。对于单个子域名如 app.yourdomain.com，无需勾选此项。
  • tls-sni-01 is deprecated…: Let’s Encrypt 旧的验证方式已弃用。通常NPM会自动使用 http-01 或 dns-01 验证。http-01 是默认且最常见的方式，它要求你的服务器能通过 80 端口访问。确保你的 80 端口已开放并正确映射到NPM容器。
  • Email Address for Let’s Encrypt: 填写你的邮箱地址，用于接收Let’s Encrypt的通知（如证书即将过期）。
  • I Agree to the Let’s Encrypt Terms of Service: 必勾选，表示同意Let’s Encrypt的服务条款。
  • Propagate Certificates? (Optional): 用于集群环境，通常不需要勾选。

填写示例 (Request a new SSL Certificate):

• SSL Certificate: Request a new SSL Certificate
• Force SSL: On
• HTTP/2 Support: On
• HSTS Enabled: On
• Include Subdomains: Off (除非你需要通配符证书)
• Email Address: [email protected]
• I Agree…: 勾选

配置 Advanced 标签页 (可选，入门可跳过)

这个标签页允许你添加自定义的Nginx配置片段。只有当你需要NPM界面没有提供的特定Nginx功能时才需要使用，例如：

• 设置特定的请求头或响应头。
• 更复杂的缓存规则。
• 使用 proxy_set_header 添加额外的请求头。
• 配置Client Body Size限制。

例如，要增加上传文件大小限制，你可以在这里添加：

nginx
client_max_body_size 100M;

对于初学者，通常不需要在这里添加任何东西。

配置 Access List 标签页 (可选)

这个标签页用于配置访问控制，例如 basic HTTP 认证。

• 选择 Public (No Auth): 任何人都可以访问（默认）。
• 选择 Restricted: 应用一个访问列表。
  • 点击 Manage Access Lists 可以创建新的访问列表。你可以设置基于IP地址的限制，或者创建需要输入用户名和密码才能访问的 basic auth 保护。

创建 Basic Auth 示例：

1. 点击 Manage Access Lists。
2. 点击 Add Access List。
3. 填写一个名称 (如 MyBasicAuth)。
4. 在 Satisfy 选择 Any 或 All (通常是Any)。
5. 在 Authentication 部分，点击 Add。
6. 输入用户名和密码。点击 Save。
7. 保存访问列表。
8. 回到 Proxy Host 配置的 Access List 标签页。
9. 选择 Restricted。
10. 选择刚刚创建的访问列表 (MyBasicAuth)。

保存 Proxy Host

完成所有配置后，点击右下角的 Save 按钮。

NPM会立即保存你的配置，并尝试执行以下操作：

1. 生成并加载新的Nginx配置文件。
2. 如果你请求了新的SSL证书，NPM会向Let’s Encrypt服务器发送请求，进行域名验证，并自动获取证书。

如果一切顺利，你应该能在 Proxy Hosts 列表中看到你刚刚添加的条目，并且如果申请了SSL，几秒钟或几十秒后，SSL列会显示绿色的锁图标，表示证书已成功获取。

现在，你可以通过 https://app.yourdomain.com 来访问你的后端服务 localhost:3000 了！

其他类型的 Hosts

除了最常用的 Proxy Hosts，NPM还支持其他类型的 Hosts：

1. Redirection Hosts (重定向): 用于将一个域名或路径重定向到另一个URL。
   • 例如，将 olddomain.com 重定向到 newdomain.com。
   • 例如，将 http://yourdomain.com 重定向到 https://yourdomain.com (虽然Proxy Host的 Force SSL 已经做到了这一点，但有时你可能需要更复杂的重定向规则)。
   • 你可以选择重定向类型：Permanent (301) 或 Temporary (302)。
2. Stream Hosts (流传输): 用于代理非HTTP/HTTPS流量，例如TCP或UDP服务。
   • 例如，代理SSH (端口22)、RDP (端口3389) 或其他自定义TCP/UDP服务。
   • 你需要指定协议 (TCP/UDP)、监听端口，并将流量转发到后端的IP和端口。注意：Stream Hosts 的监听端口是 Nginx 直接监听的，不经过 80/443。

配置这些Hosts的步骤与Proxy Hosts类似，只需点击对应的选项卡，然后点击 Add 按钮并填写相应信息即可。对于入门用户，主要精力会集中在 Proxy Hosts 上。

用户管理

在NPM中，你可以创建多个用户，并分配不同的角色：

• Admin: 拥有所有权限，可以进行所有配置和管理操作。
• User: 只能查看和管理由他们自己创建的 Hosts，不能创建、删除或编辑其他用户的 Hosts，也不能访问设置或用户管理页面。

如果你需要允许多个用户使用NPM管理他们自己的服务，这个功能非常有用。

在左侧导航栏点击 Users，即可添加、编辑或删除用户。记住，务必妥善保管 Admin 用户的密码。

SSL 证书管理

NPM的SSL证书管理功能非常强大且自动化。

• 在左侧导航栏点击 SSL Certificates，你可以看到所有通过NPM获取或导入的证书列表。
• 你可以查看证书的详细信息，包括有效期、关联的域名等。
• NPM会定期自动检查Let’s Encrypt证书的有效期，并在证书即将过期时尝试自动续期。只要你的域名解析正确，并且 80/443 端口可以正常访问，自动续期通常都能成功。
• 你也可以在这里手动添加证书，或者上传自己的 .pem 格式证书文件。

故障排除 (Troubleshooting)

在使用NPM过程中，你可能会遇到一些问题。以下是一些常见的故障及排查方法：

1. 无法访问 NPM Web UI (服务器IP:81)

• 检查防火墙： 确保你的服务器防火墙（如 ufw, firewalld）和云服务提供商的安全组已经开放了 81 端口。
  • sudo ufw status 或 sudo firewall-cmd --list-all
  • 如果未开放，使用相应命令开放端口：sudo ufw allow 81/tcp 或 sudo firewall-cmd --zone=public --add-port=81/tcp --permanent，然后重启防火墙。
• 检查端口占用： 确认宿主机的 81 端口没有被其他程序占用。
  • sudo netstat -tulnp | grep 81
  • 如果被占用，找出占用进程并停止，或者修改NPM的端口映射（修改 docker-compose.yml 中的 '81:81' 为 '新的端口:81'，然后重新启动容器）。
• 检查 Docker 容器状态： 确保NPM容器正在运行。
  • sudo docker ps
  • 如果状态不是 Up，查看容器日志：sudo docker logs <容器ID或名称> 来查找错误原因。
• 检查端口映射： 确认 docker-compose.yml 或 docker run 命令中的端口映射是否正确，确保宿主机的 81 端口正确映射到了容器的 81 端口。

2. 无法通过域名访问代理的服务 (域名:80 或 域名:443)

• 检查 DNS 解析： 确保你的域名已正确解析到你的服务器的公网IP地址。使用 ping yourdomain.com 或 nslookup yourdomain.com 命令检查。DNS更改可能需要一些时间才能全球生效。
• 检查防火墙： 确保你的服务器防火墙和安全组已经开放了 80 和 443 端口。
  • sudo ufw allow 80/tcp
  • sudo ufw allow 443/tcp
  • 或 sudo firewall-cmd --zone=public --add-port=80/tcp --permanent
  • sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
• 检查 Docker 端口映射： 确保 docker-compose.yml 或 docker run 命令中的 '80:80' 和 '443:443' 映射正确。
• 检查 NPM 容器日志： 查看NPM容器的日志，看是否有关于该域名的错误信息。
  • sudo docker logs <容器ID或名称>
• 检查 Proxy Host 配置：
  • 确保在NPM界面中，你为该域名配置了正确的 Forward Hostname / IP 和 Forward Port。
  • 确保 Scheme (http 或 https) 选择正确。
• 检查后端服务： 确保你的后端服务正在你配置的 Forward Hostname / IP 和 Forward Port 上正常运行并且可以从NPM容器内访问。你可以在NPM容器所在的服务器上，使用 curl 或 wget 命令测试是否能访问后端服务（例如 curl http://localhost:3000 或 curl http://192.168.1.100:5000）。
• 检查 SSL 证书状态： 如果你使用HTTPS访问失败，检查NPM界面中该 Proxy Host 的 SSL 状态。
  • 如果证书申请失败（红色叉号），通常是因为Let’s Encrypt无法验证你的域名。最常见的原因是：
    • 域名DNS解析不对。
    • 服务器的 80 端口未开放或未正确映射到NPM容器。Let’s Encrypt 主要通过 80 端口进行 http-01 验证。
    • NPM配置中的域名填写错误。
  • 查看NPM容器日志，通常会有详细的证书申请失败原因。
• 缓存问题： 有时浏览器会缓存旧的重定向或SSL信息。尝试清除浏览器缓存，或使用浏览器的隐私模式/无痕模式访问。

3. 后端服务无法通过 WebSockets 工作

• 确保在 Proxy Host 的 Details 标签页中，Websockets Support 选项已开启并保存。

4. 配置修改后不生效

• 保存配置后，NPM会自动重新加载Nginx配置。通常立即生效。如果发现未生效，尝试在NPM界面的 Dashboard 页面点击 Reload Nginx 按钮。如果问题依然存在，查看容器日志。

总结与展望

Nginx Proxy Manager极大地简化了反向代理和SSL证书的管理，特别是对于Docker用户和不熟悉Nginx配置文件的用户而言。通过本教程，你应该已经掌握了NPM的安装、初次设置以及最核心的反向代理配置方法。

使用NPM，你可以轻松地：

• 为你的各种内网服务（网站、API、容器应用等）设置域名访问。
• 一键申请和自动化续期免费的Let’s Encrypt SSL证书，保障网站安全。
• 集中管理你的所有域名和代理规则。

NPM还有许多其他功能等待你去探索，例如：

• 自定义Nginx配置片段，实现更高级的功能。
• 设置基本的访问认证。
• 配置错误页面。
• 利用Docker网络更优雅地代理其他容器。

随着你对NPM越来越熟悉，你会发现它能帮助你更高效地管理你的Web服务基础设施。记住，遇到问题时，首先查看NPM界面的提示和Docker容器的日志，它们通常会给出最直接的错误原因。

祝你在使用 Nginx Proxy Manager 的旅程中一切顺利！

---