🚀 使用 Docker Compose 部署 Nginx Proxy Manager（NPM）

🚀 使用 Docker Compose 部署 Nginx Proxy Manager

Nginx Proxy Manager（简称 NPM）是一个基于 Nginx 的反向代理管理工具，它通过友好的 Web 界面，让用户无需手动编辑复杂的 Nginx 配置文件，就能轻松配置反向代理、申请和管理 SSL 证书，并设置访问控制等功能。它特别适合个人或小型团队使用 Docker 部署的多个 Web 服务，旨在简化反向代理和 SSL 证书管理。

📝 项目简介

Nginx Proxy Manager 的核心是一个开源的、基于 Web 界面的反向代理管理工具。它的出现，极大地降低了使用 Nginx 做反向代理和 HTTPS 服务的门槛。

核心特点概览：

特性	说明
直观的 Web 界面	通过网页可视化地管理代理和证书，无需手动编辑 Nginx 配置文件。
自动化 SSL 证书	集成 Let's Encrypt，可以轻松为站点获取和续订免费的 SSL 证书。
灵活的代理功能	支持反向代理、端口映射、域名重定向、WebSocket 支持等。
访问控制	可以通过设置用户名和密码或 IP 白名单来保护特定的路径或站点。
基于 Docker	采用容器化部署，简单方便，迁移容易。

它的典型应用场景包括： * 托管多个站点：当你在一台服务器上使用 Docker 运行了多个 Web 服务（如个人博客、Nextcloud、GitLab 等），并希望通过不同的域名访问它们时。 * 统一 SSL 管理：希望为所有服务轻松配置和支持 HTTPS，并自动续期证书。 * 简化运维：不希望深入学习和编写 Nginx 配置文件的个人开发者或小团队。

🔧 部署前准备

在开始部署之前，请确保您的环境满足以下基本要求：

一台服务器：可以是云服务器（VPS）、本地虚拟机，甚至是一台树莓派。操作系统推荐 Linux（如 Ubuntu、CentOS 等）。
安装 Docker 引擎：确保您的系统上已经安装了 Docker。您可以参考官方 Docker 安装文档。
安装 Docker Compose：这是通过 YAML 文件定义和运行多容器 Docker 应用程序的工具。请参考官方 Docker Compose 安装文档。
一个域名（可选但推荐）：如果您计划申请 SSL 证书，需要一个已经注册的域名，并能够配置 DNS 解析，将您的域名指向服务器 IP 地址。

环境检查：在部署之前，可以通过以下命令快速检查 Docker 环境是否就绪：

docker --version
docker compose version

⚙️ 配置 Docker Compose

创建部署目录：首先，在服务器上创建一个专用的目录来存放 NPM 的所有相关文件，这有助于后续管理和维护。

    mkdir -p /home/compose/nginx-proxy-manager
    cd /home/compose/nginx-proxy-manager

创建 docker-compose.yml 文件：在此目录下，创建 docker-compose.yml 文件。您可以直接使用提供的配置内容。

#version: '3'
services:
  app:
    # 官方最新镜像（稳定版，自动更新核心功能）
    image: 'jc21/nginx-proxy-manager:latest' #jlesage/nginx-proxy-manager
    container_name: npm  # 容器名称，便于管理（如停止/查看日志）
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障服务稳定）
    ports:
      # 端口映射说明：左侧=主机端口，右侧=容器端口（右侧不可修改！）
      - '80:80'   # HTTP 端口：用于证书验证、HTTP 请求转发  # 保持默认即可，不建议修改左侧的80
      - '81:81'   # 管理界面端口：Web 登录入口（左侧可改，如 8081:81，需同步开放新端口）
      - '443:443' # HTTPS 端口：加密访问代理服务（左侧不可修改，浏览器默认 HTTPS 端口）
    volumes:
      # 数据持久化：确保容器删除后配置、证书不丢失
      - ./data:/data               # 本地 ./data → 容器 /data（配置、日志）
      - ./letsencrypt:/etc/letsencrypt  # 本地 ./letsencrypt → 容器 /etc/letsencrypt（SSL 证书）
    # 可选配置：新手建议默认关闭，需特殊网络场景（如访问局域网其他子网）再取消注释
    #network_mode: "host"  # 使用主机网络（可能导致端口冲突，谨慎开启）  # 使用本地网络, 方便连接各子网的客户端
    #privileged: true      # 开启特权模式（用于特殊权限需求，如修改网络配置）


#首次登录用户名和密码为，需要修改用户名和密码，根据提示修改即可
#Email:    admin@example.com
#Password: changeme

**关键配置说明**：
*   `image`: 指定使用的 Docker 镜像，这里使用官方最新的 `jc21/nginx-proxy-manager:latest`。
*   `ports`: 端口映射，将容器内的端口绑定到宿主机的端口。
    *   `80:80`: **HTTP 流量端口**，用于接收普通的 HTTP 请求。
    *   `81:81`: **NPM 管理界面端口**，稍后我们通过此端口访问 Web 管理后台。
    *   `443:443`: **HTTPS 流量端口**，用于接收加密的 HTTPS 请求。

注意：80 和 443 端口是 Web 服务的标准端口，不建议修改左侧的宿主机端口，否则用户访问时可能需要指定端口号。管理端口 81 的左侧可以根据实际情况修改，如果服务器上 81 端口已被占用，可改为其他未被占用的端口，例如 8080:81。

*   `volumes`: 数据卷挂载，用于**持久化数据**，防止容器删除后配置和证书丢失。
    *   `./data:/data`: 将容器内的 `/data` 目录（存放 NPM 自身配置和 SQLite 数据库）映射到当前目录下的 `data` 文件夹。
    *   `./letsencrypt:/etc/letsencrypt`: 将容器内的 `/etc/letsencrypt` 目录（存放 SSL 证书）映射到当前目录下的 `letsencrypt` 文件夹。

🚀 启动与验证

启动服务：在 docker-compose.yml 文件所在目录下，执行以下命令来启动 NPM 服务： bash docker compose up -d 参数 -d 表示在后台运行容器。
验证服务状态：
- 执行 docker ps 命令。如果看到名为 npm 的容器状态为 Up，说明容器已成功启动。
- 您还可以查看启动日志以排查潜在问题：docker compose logs。
访问管理界面并初始化：
- 打开浏览器，输入 http://你的服务器IP:81 访问 NPM 的管理界面。
- 首次登录使用默认凭证：
  - 邮箱：admin@example.com
  - 密码：changeme
- 登录后，系统会强制要求修改默认的邮箱和密码，请务必按照提示设置一个强密码并妥善保管。

🔌 基础配置与使用

成功登录后，您就可以开始使用 NPM 来管理您的反向代理和 SSL 证书了。

添加反向代理（Proxy Host） 这是 NPM 最核心的功能，目的是让通过域名访问您的内部服务。
- 在管理界面，点击 "Proxy Hosts" 选项卡，然后点击 "Add Proxy Host"。
- 会弹出配置对话框，主要填写以下信息：
  - Domain Names: 输入您想要用来访问服务的域名，例如 app.yourdomain.com。（前提是您已将该域名的 DNS 解析指向了您的服务器 IP）。
  - Forward Hostname / IP: 填写您要代理的服务所在的主机名或 IP 地址。
    - 如果目标服务与 NPM 在同一台服务器上的 另一个 Docker 容器 中，可以填写该容器的 服务名称 或 容器 IP（通常需要自定义 Docker 网络）。
    - 如果目标服务在 宿主机 上（非 Docker 部署），可以填写宿主机的 内网 IP（如 192.168.x.x）或 Docker 的桥接网络网关 172.17.0.1。
    - 如果目标服务在 另一台服务器 上，填写那台服务器的 IP 地址。
  - Forward Port: 填写目标服务监听的端口号。
- 点击 "Save" 保存。现在，您应该已经可以通过域名 http://app.yourdomain.com 访问到您的后端服务了。
一键申请 SSL 证书 让您的网站支持 HTTPS，提升安全性和专业性。
- 在刚才添加的代理主机条目上，点击 "Edit"。
- 切换到 "SSL" 选项卡。
- 选择 "Request a new SSL Certificate"。
- 勾选 "Force SSL" 以强制将所有 HTTP 请求重定向到 HTTPS。
- 勾选 "I agree to the Let's Encrypt Terms of Service" 并填写一个有效的邮箱地址。
- 点击 "Save"。NPM 将自动与 Let's Encrypt 通信，为您申请并部署免费的 SSL 证书。成功后，您的网站就可以通过 https://app.yourdomain.com 安全访问了。

🛠️ 维护与管理

1.服务更新： NPM 项目更新较为频繁。要更新到最新版本，只需在 docker-compose.yml 文件所在目录执行：

    docker compose down    # 停止当前容器
    docker compose pull    # 拉取最新镜像
    docker compose up -d   # 重新启动容器

注意：在升级前，建议先备份 data 和 letsencrypt 目录。对于生产环境，建议先在测试环境中验证新版本的兼容性。

2.数据备份：定期备份部署目录下的 data 和 letsencrypt 文件夹至关重要。这包含了您的所有代理配置和 SSL 证书。

    # 在部署目录的上一级目录执行
    tar -czf npm-backup-$(date +%Y%m%d).tar.gz nginx-proxy-manager/

3.问题排查： * 查看日志：NPM 的 Web 界面有内置的日志查看功能（"System" -> "Logs"）。此外，也可以通过命令行 docker compose logs app 查看容器日志。 * 检查 Nginx 配置：如果遇到配置不生效的问题，可以尝试在 Web 界面的 "System" -> "Repair" 中点击 "Check Configuration" 和 "Reload Nginx"。

🐛 常见问题排查

无法通过 http://服务器IP:81 访问管理界面
- 检查防火墙：确保您的服务器安全组（云服务商控制台）和系统防火墙（如 ufw）已放行 81 端口。例如，使用 UFW 防火墙可以执行：sudo ufw allow 81。
- 检查端口占用：确认服务器上 81 端口没有被其他进程占用。可以使用 netstat -tulpn | grep 81 命令检查。
- 确认映射端口：检查 docker-compose.yml 文件中的端口映射配置，确保宿主机的端口（冒号左侧）是正确的。
SSL 证书申请失败
- 域名解析：确保您申请证书的域名已经正确解析到了 NPM 所在服务器的公网 IP。
- 端口开放：确保服务器的 80 和 443 端口对公网是开放的，因为 Let's Encrypt 需要通过这两个端口来验证域名所有权。如果使用了 CloudFlare 等 CDN，在申请证书时建议暂时关闭代理（即让流量直接到达你的服务器，俗称"把小黄云关掉"）。
反向代理后显示 502 Bad Gateway
- 检查目标服务：确认您要代理的后端服务本身是否运行正常，并且可以通过其 IP 和端口直接访问。
- 检查 Forward 设置：在代理主机配置中，仔细检查 "Forward Hostname / IP" 和 "Forward Port" 是否填写正确。如果 NPM 和目标服务在同一台宿主机但不同容器，确保它们在同一 Docker 网络中，或使用正确的宿主机内部 IP。
关于访问控制 Satisfy Any 失效问题
- 在一些旧版本（如 2.12.1）中，存在一个已知问题：当同时设置 IP 白名单和 HTTP 基础认证并启用 "Satisfy Any"（满足任一条件即可）时，该选项可能不生效。
- 解决方案：建议将 NPM 升级到最新版本，此问题在 2.12.2 及更高版本中已被修复。

通过本篇教程，您应该已经成功地使用 Docker Compose 部署并初步配置了 Nginx Proxy Manager。这款工具能极大简化您的 Web 服务管理流程，特别是对于 SSL 证书的自动化管理，非常省心。如果在使用过程中遇到更复杂的问题，可以参考其官方文档或在相关的技术社区寻求帮助。

🐛 常见问题排查2

1. 管理界面无法访问（ERR_CONNECTION_REFUSED）

原因 1：81 端口未开放或被占用。解决：
1. 检查端口占用：sudo lsof -i :81，若有占用，执行 sudo kill -9 进程ID 停止占用服务；
2. 重新开放 81 端口：sudo ufw allow 81/tcp，重启 NPM 容器。
3. 原因 2：容器未正常启动（State 为 Exited）。解决：查看日志 docker compose logs npm，修复权限或端口冲突问题后重启。

2. HTTPS 证书申请失败（提示 “Could not validate domain”）

原因 1：域名未解析到服务器 IP 或解析未生效（DNS 缓存）。解决：
1. 通过 ping test.example.com 验证域名是否指向正确 IP；
2. 若解析错误，在域名服务商控制台修改 A 记录（指向服务器公网 IP）；
3. 若解析正确，等待 10-30 分钟（DNS 缓存生效）后重新申请。
4. 原因 2：80 端口被防火墙 / 安全组阻止（Let's Encrypt 需通过 80 端口验证域名所有权）。解决：开放 80 端口（sudo ufw allow 80/tcp），云服务器需在安全组添加 “允许 80 端口入站” 规则。

3. 反向代理提示 “502 Bad Gateway”（网关错误）

原因 1：目标 Web 服务未启动或地址错误（如 IP / 端口填写错误）。解决：
1. 验证目标服务是否正常：curl http://127.0.0.1:8080（替换为你的服务 IP / 端口），若无法访问，启动服务；
2. 检查反向代理 “转发主机名”“转发端口” 是否正确，修改后保存。
3. 原因 2：容器网络无法访问目标服务（如目标服务在其他 Docker 容器，未在同一网络）。解决：将 NPM 与目标服务加入同一 Docker 网络（参考 Docker 网络配置），或开启 NPM 的 network_mode: "host"（谨慎开启，避免端口冲突）。

4. 80/443 端口被本地 Nginx/Apache 占用

原因：服务器已安装 Nginx/Apache，默认占用 80/443 端口，与 NPM 冲突。
解决： 1.停止本地 Nginx/Apache 服务：

        # 停止 Nginx
        sudo systemctl stop nginx && sudo systemctl disable nginx
        # 停止 Apache
        sudo systemctl stop apache2 && sudo systemctl disable apache2

2.重启 NPM 容器：docker compose up -d。

通过以上步骤，新手可快速搭建 NPM 并实现 “域名反向代理 + HTTPS 加密”，无需手动编写 Nginx 配置。NPM 功能灵活，后续可探索 “端口转发”“IP 黑白名单” 等高级功能，具体可参考 NPM 官方文档。