Nginx Proxy Manager 完整教程：安装、配置及 SSL 证书 – wiki基地

作者： /

Nginx Proxy Manager 完整教程：安装、配置及 SSL 证书管理

在现代网络应用部署中，反向代理扮演着至关重要的角色。它不仅能提高安全性、实现负载均衡，还能简化 SSL/TLS 证书的管理。Nginx 作为业界领先的高性能 Web 服务器和反向代理服务器，功能强大但配置相对复杂，尤其是对于新手或者需要管理大量站点的用户而言。

Nginx Proxy Manager (NPM) 应运而生，它是一个基于 Docker 的开源项目，提供了一个美观、易用的 Web 用户界面，极大地简化了 Nginx 反向代理的配置和 SSL 证书（特别是 Let’s Encrypt 证书）的管理。无论您是家庭实验室爱好者、小型企业运维人员还是开发者，Nginx Proxy Manager 都能让您轻松地将内部服务安全地暴露到公网。

本教程将详细介绍 Nginx Proxy Manager 的完整使用流程，涵盖从安装部署、基础配置、添加代理主机，到自动化申请和续签 Let’s Encrypt SSL 证书等各个方面，旨在帮助您全面掌握这个强大的工具。

本文主要内容：

  1. Nginx Proxy Manager 简介与优势
  2. 准备工作 (Prerequisites)
  3. 使用 Docker Compose 安装 Nginx Proxy Manager
  4. 初始配置与登录
  5. 核心功能：配置代理主机 (Proxy Hosts)
  6. SSL 证书管理：申请与自动续签 Let’s Encrypt 证书
  7. 进阶功能探索 (重定向、访问控制、自定义 Nginx 配置等)
  8. 维护与更新
  9. 常见问题与故障排查
  10. 总结与最佳实践

1. Nginx Proxy Manager 简介与优势

Nginx Proxy Manager (NPM) 本质上是一个 Nginx 的图形化管理工具。它将复杂的 Nginx 配置文件抽象为易于理解的 Web 表单，用户无需直接编写 Nginx 语法即可完成常见的反向代理设置。

主要优势：

  • 易于使用： 提供直观的 Web UI，配置过程简单明了，学习曲线平缓。
  • 简化 SSL 管理： 内置 Let’s Encrypt 支持，可以轻松申请、部署和自动续签免费 SSL 证书，实现 HTTPS 加密。
  • 基于 Docker： 部署简单快捷，环境隔离性好，便于迁移和管理。
  • 功能全面： 支持反向代理、重定向、访问控制列表 (ACL)、基本的用户认证、Websocket 支持、自定义 Nginx 配置等。
  • 开源免费： 由社区驱动，持续更新，无需支付任何费用。
  • 可视化管理： 集中管理所有代理规则和证书，状态一目了然。

对于那些希望利用 Nginx 的强大功能但又不想深入研究其复杂配置语法的用户来说，NPM 是一个理想的选择。

2. 准备工作 (Prerequisites)

在开始安装 Nginx Proxy Manager 之前，请确保您已满足以下条件：

  1. 一台服务器： 可以是物理服务器、虚拟机或云服务器。推荐使用 Linux 发行版，如 Ubuntu 或 Debian。服务器需要能够访问互联网。
  2. 安装 Docker 和 Docker Compose： NPM 官方推荐使用 Docker 进行部署。请确保您的服务器上已正确安装 Docker Engine 和 Docker Compose。
  3. 域名： 您需要拥有一个或多个域名，并能够配置这些域名的 DNS 解析。您需要将希望通过 NPM 代理的域名（或子域名）指向运行 NPM 服务器的公网 IP 地址。
  4. 防火墙/路由器端口转发： 确保服务器的防火墙或您的网络路由器已放行 TCP 端口 80 (HTTP) 和 443 (HTTPS)。这是 Let’s Encrypt 进行域名验证以及 Web 服务正常访问所必需的。NPM 的管理界面默认使用端口 81，如果需要从公网访问管理界面（不推荐，建议仅内网访问），也需要放行此端口。
  5. 基本的命令行知识： 需要使用命令行执行 Docker 相关操作。

3. 使用 Docker Compose 安装 Nginx Proxy Manager

使用 Docker Compose 是安装和管理 NPM 的最推荐方式，它允许您通过一个 YAML 文件来定义和运行多容器 Docker 应用程序。

步骤：

  1. 创建安装目录：
    选择一个合适的位置存放 NPM 的配置文件和数据。例如，在用户主目录下创建一个 npm 文件夹。

    bash
    mkdir ~/npm
    cd ~/npm

  2. 创建 docker-compose.yml 文件：
    在该目录下创建一个名为 docker-compose.yml 的文件，并填入以下内容：

    “`yaml
    version: ‘3.8’
    services:
    app:
    image: ‘jc21/nginx-proxy-manager:latest’ # 使用官方镜像
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
    # Public HTTP Port:
    – ’80:8080′ # 将宿主机的 80 端口映射到容器的 8080 端口
    # Public HTTPS Port:
    – ‘443:4443′ # 将宿主机的 443 端口映射到容器的 4443 端口
    # Admin Web Port:
    – ’81:8181’ # 将宿主机的 81 端口映射到容器的 8181 端口 (管理界面)
    environment:
    # 如果在 MySQL/MariaDB 中使用非标准端口，请取消注释并修改下一行
    # DB_MYSQL_PORT: 3306
    # 如果希望使用自定义的 MySQL/MariaDB 数据库，请取消注释以下行
    # DB_MYSQL_HOST: “db”
    # DB_MYSQL_USER: “npm”
    # DB_MYSQL_PASSWORD: “npm_password” # 请务必修改为强密码
    # DB_MYSQL_NAME: “npm”
    # 指定 TZ 环境变量以确保 Let’s Encrypt 的计划任务在正确的时间运行
    TZ: ‘Asia/Shanghai’ # 根据需要修改时区
    volumes:
    – ./data:/data # 挂载数据卷，存储配置和证书
    – ./letsencrypt:/etc/letsencrypt # 挂载 Let’s Encrypt 证书卷
    depends_on:
    # 如果使用自定义数据库，请取消注释下一行
    # – db # 确保数据库容器先启动

    # 如果希望使用自定义的 MySQL/MariaDB 数据库，请取消注释以下数据库服务定义
    # db:
    # image: ‘jc21/mariadb-aria:latest’
    # container_name: npm-mariadb
    # restart: unless-stopped
    # environment:
    # MYSQL_ROOT_PASSWORD: ‘npm_root_password’ # 请务必修改为强密码
    # MYSQL_DATABASE: ‘npm’
    # MYSQL_USER: ‘npm’
    # MYSQL_PASSWORD: ‘npm_password’ # 请务必修改为强密码
    # volumes:
    # – ./data/mysql:/var/lib/mysql

    注意：默认配置使用 SQLite 数据库，存储在 ./data 卷中。

    如果需要处理大量配置或追求更高性能，可以切换到 MySQL/MariaDB。

    “`

    配置说明：
    * image: 'jc21/nginx-proxy-manager:latest': 指定使用的 NPM Docker 镜像。latest 标签通常指向最新的稳定版本。
    * restart: unless-stopped: 确保容器在 Docker 服务启动或意外退出时自动重启。
    * ports: 将宿主机的端口映射到容器内部的端口。
    * 80:8080: 公网 HTTP 流量入口。
    * 443:4443: 公网 HTTPS 流量入口。
    * 81:8181: NPM 管理界面的访问端口。
    * environment: 设置环境变量。
    * TZ: 设置容器的时区，对于 Let’s Encrypt 证书的自动续签非常重要。请根据您服务器所在位置修改。
    * DB_MYSQL_*: （默认注释掉）如果选择使用外部 MySQL/MariaDB 数据库，需要取消注释并配置数据库连接信息。
    * volumes: 将宿主机的目录挂载到容器内部，用于持久化存储数据。
    * ./data:/data: 存储 NPM 的配置信息（包括 SQLite 数据库，如果使用默认设置）。
    * ./letsencrypt:/etc/letsencrypt: 存储 Let’s Encrypt 签发的 SSL 证书。
    * depends_on: （默认注释掉）如果使用自定义数据库容器，确保数据库容器在 NPM 应用容器之前启动。

  3. 启动 Nginx Proxy Manager 容器：
    在包含 docker-compose.yml 文件的目录 (~/npm) 中，运行以下命令：

    bash
    docker-compose up -d

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

    Docker 会自动下载所需的镜像并启动容器。您可以使用 docker-compose ps 命令查看容器状态，或使用 docker-compose logs -f app 查看 nginx-proxy-manager 容器的实时日志。

  4. 验证安装：
    等待片刻让容器完全启动。然后，在浏览器中访问 http://<你的服务器IP>:81。如果看到 Nginx Proxy Manager 的登录页面，说明安装成功。

4. 初始配置与登录

首次访问 NPM 管理界面 (http://<你的服务器IP>:81) 时，需要使用默认凭据登录：

首次登录后，请务必立即修改默认的管理员信息和密码！

  1. 修改管理员信息：
    • 登录后，点击右上角的用户名 ([email protected])，选择 “Edit Profile”。
    • 修改 “Full Name” 和 “Nickname”。
    • 点击 “Save”。
  2. 修改管理员密码：
    • 再次点击右上角的用户名，选择 “Change Password”。
    • 输入当前密码 (changeme)。
    • 输入两次您的新密码（请使用强密码）。
    • 点击 “Save”。
  3. 修改管理员邮箱：
    • 点击左侧菜单栏的 “Users”。
    • 点击 [email protected] 用户右侧的三个点按钮，选择 “Edit”。
    • 修改 “Email” 为您自己的有效邮箱地址。
    • 点击 “Save”。

完成这些步骤后，您的 NPM 实例就基本安全了。

5. 核心功能：配置代理主机 (Proxy Hosts)

这是 NPM 最核心的功能：将公网访问的域名（或子域名）代理到您内网运行的各种服务（如网站、API、应用程序等）。

假设场景： 您有一个内部服务（例如一个简单的 Web 应用）运行在 192.168.1.100 这台机器的 8080 端口上，您希望通过公网域名 myapp.yourdomain.com 来访问它。

配置步骤：

  1. 导航到 Proxy Hosts：
    在 NPM Web UI 的左侧菜单中，点击 “Hosts” -> “Proxy Hosts”。

  2. 添加代理主机：
    点击页面右上角的 “Add Proxy Host” 按钮。

  3. 填写详细信息 (Details Tab)：

    • Domain Names: 输入您希望用于访问该服务的公网域名。可以输入多个，每行一个。例如：myapp.yourdomain.com。如果您希望 www.myapp.yourdomain.com 也指向同一个服务，可以也添加上。
    • Scheme: 选择您的内部服务使用的协议。通常是 http 或 https。如果您的内部服务没有配置 HTTPS，选择 http。
    • Forward Hostname / IP: 输入您的内部服务的 IP 地址或主机名。例如：192.168.1.100。如果目标服务也在 Docker 网络中，可以使用 Docker 容器名。
    • Forward Port: 输入您的内部服务监听的端口。例如：8080。
    • Block Common Exploits: 建议勾选。这会启用一些基本的安全防护规则，阻止常见的 Web 攻击尝试。
    • Websockets Support: 如果您的后端应用需要 Websocket 支持（例如实时聊天、协作工具等），请勾选此项。NPM 会自动添加必要的 Nginx 配置指令。
    • Cache Assets: (可选) 启用此项可以缓存静态资源 (JS, CSS, images等)，提高加载速度，减轻后端服务压力。
    • Allow Cross-Origin Resource Sharing (CORS): (可选) 如果您的前端应用和后端 API 部署在不同的域或端口下，并且需要跨域请求，可以启用此项。

  4. 配置 SSL (SSL Tab) – 稍后详述：
    此选项卡用于配置 HTTPS。我们将在下一节详细介绍。

  5. 高级配置 (Advanced Tab) – 可选：
    这里允许您直接添加自定义的 Nginx 配置。这适用于需要标准 UI 无法满足的特殊 Nginx 指令的高级用户。

  6. 保存配置：
    检查所有信息无误后，点击 “Save” 按钮。

现在，NPM 会自动生成对应的 Nginx 配置并重新加载 Nginx 服务。稍等片刻，您应该就可以通过浏览器访问 http://myapp.yourdomain.com (如果您还没配置 SSL) 来访问您部署在 192.168.1.100:8080 的内部服务了。NPM 在中间充当了反向代理的角色。

6. SSL 证书管理：申请与自动续签 Let’s Encrypt 证书

为您的服务启用 HTTPS 是现代 Web 的标准实践，它能加密客户端和服务器之间的通信，保护数据安全，增加用户信任，并有助于 SEO 排名。Nginx Proxy Manager 让使用 Let’s Encrypt 提供的免费 SSL 证书变得异常简单。

前提条件：

  • 您的域名已正确解析到运行 NPM 服务器的公网 IP。
  • 服务器的 TCP 端口 80 和 443 已对外开放，并且没有被其他程序占用（或者已正确映射到 NPM 容器的 8080 和 4443 端口）。Let’s Encrypt 需要通过 80 端口（HTTP-01 challenge）或 443 端口（TLS-ALPN-01 challenge）来验证您对域名的所有权。

为代理主机配置 SSL 证书：

  1. 编辑代理主机：
    在 “Proxy Hosts” 列表中，找到您想要启用 SSL 的主机（例如 myapp.yourdomain.com），点击右侧的三个点按钮，选择 “Edit”。

  2. 切换到 SSL 选项卡：
    在弹出的编辑窗口中，点击 “SSL” 选项卡。

  3. 选择 SSL 证书类型：
    在 “SSL Certificate” 下拉菜单中，选择 “Request a new SSL Certificate”。

  4. 配置 SSL 选项：

    • Force SSL: 强烈建议勾选！此选项会自动将所有 HTTP 请求重定向到 HTTPS，确保所有连接都是加密的。
    • HTTP/2 Support: 建议勾选。HTTP/2 协议能提高网页加载速度和效率。
    • HSTS Enabled: (可选，但推荐) 勾选此项会添加 Strict-Transport-Security 响应头。这告诉浏览器在未来一段时间内（由 Max Age 定义）只能通过 HTTPS 访问该域名，有助于防止协议降级攻击。首次启用建议使用较短的 Max Age (如几分钟) 进行测试，确认无误后再增加时长。注意：一旦启用 HSTS，如果后续 HTTPS 配置出现问题，浏览器可能会拒绝连接，直到 HSTS 过期或手动清除浏览器 HSTS 缓存。
    • Use a DNS Challenge: (可选) 如果您的服务器无法直接从公网通过端口 80/443 访问（例如，位于严格限制入站连接的网络），您可以选择使用 DNS Challenge 进行域名验证。这需要您提供 DNS 提供商的 API凭据，NPM 会通过 API 添加 TXT 记录来完成验证。选择此项后，需要选择您的 DNS Provider 并填写 API Credentials。
    • Let’s Encrypt Terms of Service: 勾选复选框，表示您同意 Let’s Encrypt 的服务条款。

  5. 保存并申请证书：
    填写您的 真实邮箱地址 (Let’s Encrypt 会将证书到期提醒等重要通知发送到此邮箱)。然后点击 “Save”。

NPM 现在会自动与 Let’s Encrypt 服务器通信，为 “Details” 选项卡中列出的所有域名申请 SSL 证书。这个过程可能需要几十秒到几分钟。

  • 成功： 如果一切顺利，页面会刷新，SSL 下拉菜单会显示刚刚申请到的证书（通常以域名命名，并带有过期日期）。您的服务现在可以通过 https://myapp.yourdomain.com 访问了。
  • 失败： 如果申请失败，通常会弹出错误信息。最常见的原因是：
    • DNS 解析问题： 域名没有正确指向服务器 IP，或者 DNS 记录尚未在全球范围内生效（需要等待 TTL 过期）。
    • 端口不通： 服务器的 80 或 443 端口被防火墙阻止，或者没有正确映射到 NPM 容器。
    • Let’s Encrypt 速率限制： 短时间内申请次数过多。
      请仔细检查上述前提条件，解决问题后重试。可以查看 NPM 容器日志 (docker-compose logs -f app) 获取更详细的错误信息。

自动续签：
NPM 会自动处理 Let’s Encrypt 证书的续签。它内置了一个定时任务，会定期检查证书的有效期，并在到期前自动尝试续签。只要您的服务器和 DNS 配置保持正确，通常无需手动干预。

7. 进阶功能探索

除了核心的代理和 SSL 功能，NPM 还提供了一些有用的进阶特性：

  • Redirection Hosts (重定向主机):
    用于将一个域名或路径永久（301）或临时（302）重定向到另一个 URL。例如：

    • 将 http://yourdomain.com 重定向到 https://yourdomain.com (虽然 Force SSL 更常用)。
    • 将 www.yourdomain.com 重定向到 yourdomain.com (或反之)。
    • 将旧的 URL 路径重定向到新的路径。
      配置方式与 Proxy Host 类似，但需要指定目标 URL 和重定向类型。

  • 404 Hosts (默认主机):
    可以设置一个默认的代理主机。当有请求访问服务器 IP 或未在 NPM 中配置的域名时，请求将被转发到这个默认主机。可以用来显示一个自定义的 “未找到” 页面或公司主页。

  • Streams (TCP/UDP 代理):
    NPM 不仅能代理 HTTP/HTTPS 流量，还能代理原始的 TCP 或 UDP 流量。这对于代理非 Web 服务（如 Minecraft 服务器、SSH、数据库端口等）非常有用。在 “Hosts” -> “Streams” 中配置，需要指定公网监听端口、内部服务 IP 和端口以及协议类型 (TCP/UDP)。

  • Access Lists (访问控制列表):
    提供基本的访问控制功能：

    • Authentication: 可以为某个代理主机启用 HTTP Basic Auth，要求用户输入用户名和密码才能访问。可以在 “Access Lists” 中创建用户名/密码对，然后在 Proxy Host 的 “Access List” 选项卡中选择应用。
    • IP Access Control: 可以限制允许或拒绝访问的 IP 地址或 CIDR 网段。同样在 “Access Lists” 中创建规则，然后在 Proxy Host 中应用。

  • Custom Nginx Configuration (自定义 Nginx 配置):
    对于需要精细控制 Nginx 行为的高级用户，可以在 Proxy Host 的 “Advanced” 选项卡中直接编写 Nginx 配置指令。这些指令会被插入到该 server 块的特定位置。这允许您实现 UI 未提供的复杂逻辑，如自定义 Header、复杂的 location 规则等。请谨慎使用，错误的配置可能导致 Nginx 无法启动或服务异常。

  • Settings (设置):
    可以在 “Settings” -> “Default Site” 和 “Error Pages” 中自定义默认的 “Congratulations” 页面和错误页面 (如 404 Not Found, 502 Bad Gateway 等)。

8. 维护与更新

  • 更新 Nginx Proxy Manager:
    由于 NPM 是基于 Docker 的，更新非常简单。在包含 docker-compose.yml 的目录 (~/npm) 中执行以下命令：

    “`bash

    1. 拉取最新的镜像

    docker-compose pull app

    2. 停止并移除旧容器，然后使用新镜像重新创建并启动容器

    docker-compose up -d –force-recreate –remove-orphans

    3. (可选) 清理旧的、未使用的 Docker 镜像，释放磁盘空间

    docker image prune
    “`
    建议在更新前备份数据。

  • 备份数据:
    NPM 的所有配置和证书都存储在您挂载的 data 和 letsencrypt 卷中（在我们的示例中是 ~/npm/data 和 ~/npm/letsencrypt 目录）。定期备份这两个目录至关重要！您可以使用 tar 命令或备份工具来完成。

    “`bash

    示例：创建一个压缩备份文件

    tar czvf npm_backup_$(date +%Y%m%d).tar.gz ~/npm/data ~/npm/letsencrypt
    “`

  • 查看日志:
    如果遇到问题，查看 NPM 容器的日志是排查的第一步：

    “`bash

    查看实时日志

    docker-compose logs -f app

    查看所有历史日志

    docker-compose logs app
    “`

9. 常见问题与故障排查

  • 访问代理域名时出现 502 Bad Gateway 错误:

    • 检查您的后端服务是否正在运行且可访问（从 NPM 服务器尝试 curl http://<Forward Hostname / IP>:<Forward Port>）。
    • 确认在 NPM 中配置的 “Forward Hostname / IP” 和 “Forward Port” 是否正确。
    • 检查 NPM 容器与后端服务之间的网络连接是否通畅（防火墙、Docker 网络设置等）。
    • 查看 NPM 日志 (docker-compose logs app) 获取更详细的 Nginx 错误信息。

  • SSL 证书申请失败:

    • DNS 未生效: 使用 dig yourdomain.com 或在线 DNS 检测工具确认域名已指向正确的公网 IP。DNS 更改可能需要一些时间才能全球生效。
    • 端口 80/443 不通: 确认服务器防火墙（如 ufw, firewalld）和路由器端口转发规则已正确设置，允许外部访问这两个端口。使用在线端口扫描工具测试。
    • 端口被占用: 确保宿主机上的 80/443 端口没有被其他服务（如 Apache、另一个 Nginx 实例）占用。如果必须使用其他端口，请确保 Docker 端口映射正确。
    • Let’s Encrypt 速率限制: 如果短时间内多次尝试失败，可能会触发速率限制。请等待一段时间后再试。
    • 检查 NPM 日志: 日志通常会包含 Let’s Encrypt 返回的具体错误信息。

  • 无法访问 NPM 管理界面 (端口 81):

    • 确认 nginx-proxy-manager 容器正在运行 (docker-compose ps)。
    • 确认服务器防火墙允许访问端口 81 (如果从外部访问)。
    • 确认 Docker 端口映射 - '81:8181' 配置正确。

  • 忘记 NPM 管理员密码:
    如果使用的是默认的 SQLite 数据库，目前没有简单的官方重置方法。最可靠的方式是停止 NPM 容器，删除 data 卷下的数据库文件 (database.sqlite)，然后重新启动容器，这将重置 NPM 到初始状态（需要重新配置所有内容）。这也是强调备份重要性的原因。如果使用的是 MySQL/MariaDB，可以通过数据库工具直接修改用户表中的密码哈希（需要了解具体操作）。

10. 总结与最佳实践

Nginx Proxy Manager 是一个极其强大且易于使用的工具，它显著降低了配置 Nginx 反向代理和管理 SSL 证书的门槛。通过其直观的 Web 界面，用户可以快速、安全地将内部服务发布到互联网。

关键最佳实践：

  • 始终使用强密码 保护您的 NPM 管理界面。
  • 立即更改默认管理员凭据。
  • 尽可能为所有服务启用 HTTPS (Force SSL)。
  • 保持 Nginx Proxy Manager 和 Docker 为最新版本 以获取安全补丁和新功能。
  • 定期备份 data 和 letsencrypt 卷。
  • 仔细检查防火墙和端口转发规则，确保 80 和 443 端口对公网可访问（对于 Let’s Encrypt 验证至关重要）。
  • 理解 DNS 的工作方式，确保域名正确解析。
  • 利用访问控制列表 (Access Lists) 增加需要额外保护的服务的安全性。
  • 监控 NPM 容器日志 以便及时发现和解决问题。

通过遵循本教程的步骤和建议，您应该能够成功部署和有效利用 Nginx Proxy Manager，为您的 Web 服务提供安全、可靠的访问入口。希望这篇详细的教程对您有所帮助！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部