Nginx Proxy Manager 配置速查：不用再手写 Nginx 配置文件了

结论先行：自部署独立开发者的反向代理首选 Nginx Proxy Manager（NPM）。一条 Docker 命令启动，Web 界面点选代替手写复杂配置，自动申请并定时续期 Let’s Encrypt 证书。哪怕是 1GB 内存的廉价 VPS 也能平稳运行，几分钟即可交付多域名 HTTPS。除非你需要编译第三方 Nginx 模块或精细调优数万并发的大流量负载均衡，否则把运维精力交给 NPM 图形化面板是效率最高的方案。

每次上线新项目都要手写 Nginx server 块？每次都要手动敲 Certbot 申请证书并担心续期失败？这篇文章带你用 Nginx Proxy Manager 搞定反向代理和 HTTPS，全程可视化操作，告别冗长易错的手写配置文件。

0、写在前面

做独立开发或海外 SaaS，服务部署是家常便饭。

每次新增一个二级域名或微服务，传统流程极其冗长：

登录 VPS 手写一份 Nginx 反向代理配置；
运行 certbot 申请 SSL 证书并配置重定向；
检查 cron 定时任务是否配置了自动续期；
运行 nginx -t 语法检测，最后手动 systemctl reload nginx。

一旦手抖少了一个分号，或者证书路径填错，已上线的服务甚至可能直接挂掉。

Nginx Proxy Manager（简称 NPM）彻底改变了这个局面：

免写配置文件：Web 界面点选表单，底层自动生成并重载合规的 Nginx 配置；
全自动 SSL：一键签发 Let’s Encrypt 免费证书，后台自动轮询续期，永不过期；
统一路由面板：所有微服务、子域名、WebSocket、静态代理集中管理；
极速部署：官方 Docker 镜像开箱即用，两分钟跑起整套反向代理中心。

这份速查手册为你梳理从部署、反代配置、证书签发到安全加固的完整操作路线。

1、期望目标

阅读并实践本篇指南后，你将达成以下目标：

[ ] 在服务器上通过 Docker Compose 正确运行 Nginx Proxy Manager；
[ ] 掌握宿主机防火墙加固策略，保护 81 管理后台不受公网扫描；
[ ] 5 分钟内完成任意容器或宿主机服务的 HTTP/HTTPS 反向代理映射；
[ ] 零手动配置获取 Let’s Encrypt SSL 证书，并开启强制 HTTPS、HTTP/2 与 HSTS；
[ ] 掌握 Basic Auth 访问密码保护、IP 白名单以及自定义 Nginx 指令扩展；
[ ] 建立数据目录与证书目录的增量备份恢复流程。

2、技术选型与架构设计

传统 Nginx vs Nginx Proxy Manager

为什么独立开发者更倾向于 NPM？对比两者的运维成本：

维护维度	传统手工 Nginx	Nginx Proxy Manager (NPM)
配置方式	手写 `/etc/nginx/conf.d/*.conf`，易出现语法报错	Web 交互表单输入，表单验证后自动生成配置
SSL 证书	手动执行 `certbot certonly`，手工指定证书路径	点击勾选即可自动向 Let’s Encrypt 申请
证书续期	依赖外部 systemd timer 或 cron 脚本，掉线风险高	内置 acme 续期守护进程，过期前 30 天自动刷新
多域名维护	配置文件分散，查找域名对应 upstream 效率低	表单搜索过滤，状态与转发目标一目了然
配置生效	手动执行 `nginx -t && nginx -s reload`	点击保存后容器内自动执行语法验证与 reload
WebSocket	需手动配置 `Upgrade` 与 `Connection` 请求头	勾选 `Websockets Support` 单选框即开
访问控制	手动生成 `.htpasswd` 文件与配置 `allow/deny`	后台 Access Lists 可视化勾选与用户密码管理

架构模式与流量拓扑

NPM 本质是一个运行在 Docker 容器内的标准 OpenResty / Nginx 实例，配有一套 Node.js 编写的管理服务与 SQLite/MySQL 数据库。

流量到达 VPS 后的具体链路如下图所示：

80 / 443 端口：暴露于公网，承接常规 HTTP 访问以及 Let’s Encrypt 的 HTTP-01 验证；
81 端口：NPM 管理 Web UI，严禁向全公网开放，建议通过 UFW 或 Cloudflare Access 进行访问白名单限制；
后端服务：既支持同台机器上的 Docker 容器（容器名互通），也支持宿主机端口甚至远程第三方 IP。

3、从零部署与实操配置

3.1 前置检查与 Docker 环境快速就绪

在启动 NPM 之前，确保宿主机环境未被其他 Web 服务占用，且安装了 Docker 运行时：

# 1. 检查 80 和 443 端口占用情况
sudo ss -tulpn | grep -E ':(80|443|81)\b'

# 若此前系统已安装 Apache 或 Nginx 并占用了 80/443，请先停止并禁用
sudo systemctl stop nginx apache2 2>/dev/null || true
sudo systemctl disable nginx apache2 2>/dev/null || true

若 VPS 是刚开通的全新主机，推荐使用 ittinker-scripts 工具库中的 docker-quick-deploy 脚本完成环境初始化：

1 2	# 一键安装 Docker 与 Docker Compose 生产环境 curl -fsSL https://raw.githubusercontent.com/ittinker-org/ittinker-scripts/main/docker-quick-deploy/deploy.sh \| bash

3.2 编写 Docker Compose 并启动 NPM

建议为反向代理设立单独的项目根目录，以便持久化数据和证书：

1 2	mkdir -p ~/nginx-proxy-manager cd ~/nginx-proxy-manager

创建 docker-compose.yml 配置文件：

services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - '80:80'     # 外部 HTTP 流量与 ACME 验证
      - '443:443'   # 外部 HTTPS 流量
      - '81:81'     # 管理控制台端口（必须配合防火墙规则保护）
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - npm-net

networks:
  npm-net:
    name: npm-net
    driver: bridge

执行命令拉取镜像并在后台启动容器：

docker compose up -d

# 查看容器启动日志，确保 SQLite 数据库初始化顺利完成
docker compose logs -f app

当看到日志打印出 Waiting for Services to start... 与 HTTP server listening on port 80 时，说明底层 Nginx 与控制台已正常运行。

3.3 首次登录与强制安全加固

打开本地电脑浏览器，访问控制台：

1	http://<你的服务器公网IP>:81

系统预设的初始管理员凭据如下：

Email: [email protected]
Password: changeme

🔴 安全警告：changeme 是全网已知的默认凭据。部署完毕后必须立刻登入修改邮箱与强密码。

NPM 首次登录界面

完成密码变更后，立即在 VPS 宿主机通过 UFW 对 81 端口进行白名单保护，防止暴力破解：

# 允许业务端口（80/443 对外开放）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 仅允许你自己的办公 IP 访问 81 管理端口（替换 203.0.113.88 为你的实际公网出口 IP）
sudo ufw allow from 203.0.113.88 to any port 81 proto tcp
sudo ufw enable

如果你使用了 Cloudflare 托管站点，可以搭配 cloudflare-ufw 脚本一键将 80/443 锁定仅接收 Cloudflare 节点流量：

1 2	# 仅对 Cloudflare 节点 IP 开放 80/443 curl -fsSL https://raw.githubusercontent.com/ittinker-org/ittinker-scripts/main/cloudflare-ufw/sync-cloudflare-ufw.sh \| bash

3.4 快速添加第一个反向代理（Proxy Host）

假设你有一个运行在本地的后端服务：

目标访问域名：api.example.com
后端服务：部署在同机 Docker 容器中的 Node.js 接口，监听 3000 端口，且已接入 npm-net 网络；或者运行在宿主机的 3000 端口。

步骤一：录入代理基本信息

在 NPM 面板顶部导航栏点击 Dashboard → Proxy Hosts → 点击右上角 Add Proxy Host：

NPM 添加 Proxy Host 界面

配置参数表：

表单字段	填写建议	详细说明
Domain Names	`api.example.com`	输入完整域名，按回车键生成 Tag。支持多域名同时映射。
Scheme	`http`	后端服务接收协议。内部服务通常直接用 `http`。
Forward Hostname / IP	`api-container` 或 `172.17.0.1`	若后端是加入 `npm-net` 的容器，填其容器名；若在宿主机，Linux 系统填 `172.17.0.1`（宿主机 Docker 网关）。
Forward Port	`3000`	后端应用程序的实际监听端口。
Cache Assets	建议开启	开启静态资源缓存，减轻应用负载。
Block Common Exploits	建议开启	自动拦截 SQL 注入、非法路径遍历等常见探测。
Websockets Support	按需开启	如果使用 Socket.io、WS 连接，必须打开此项。

点击 Save，基础的反向代理配置即可生效。

3.5 Let’s Encrypt SSL 自动化申请

前提条件校验

Let’s Encrypt 的 HTTP-01 验证要求其海外验证节点能够通过公网访问你域名的 80 端口。在配置前请运行以下命令进行本地验证：

# 验证 DNS A 记录是否已正确解析到该 VPS IP
dig +short api.example.com

# 检查当前 80 端口连通性
curl -I -m 5 "http://api.example.com/.well-known/acme-challenge/test"

💡 DNS 灰云提示：如果域名托管在 Cloudflare，初次申请 Let’s Encrypt 证书时，建议暂时将 DNS 记录设为 DNS Only（灰色云朵），避免 CDN 缓存干扰验证；签发成功后再切回 Proxy 模式。

一键签发证书

重新打开刚才创建的 Proxy Host 编辑弹窗；
切换至 SSL 标签页；
在 SSL Certificate 下拉菜单中选择 Request a new SSL Certificate；
勾选 Force SSL（强制 HTTP 自动 301 重定向到 HTTPS）；
勾选 HTTP/2 Support（开启现代 HTTP/2 多路复用加速）；
勾选 HSTS Enabled 与 HSTS Subdomains；
填写一个接收续期通知的真实邮箱，并勾选 I Agree to the Let’s Encrypt Terms of Service；
点击 Save。

系统将在 10~20 秒内向 Let’s Encrypt 完成握手、验证并存入证书。

NPM SSL 证书配置界面

验证 HTTPS 连通性

在终端使用 curl 验证证书链与跳转状态：

# 验证 HTTP 自动跳转 HTTPS
curl -I "http://api.example.com"
# 应返回: HTTP/1.1 301 Moved Permanently 且 Location 为 https://...

# 验证 HTTPS 证书指纹与协议版本
curl -Iv "https://api.example.com" 2>&1 | grep -E '(ALPN|CN=|issuer)'

NPM 会由后台定时脚本在证书剩余 30 天以内全自动发起静默更新，你无需单独添加定时任务。

3.6 生产环境高级功能配置

方案一：为敏感路径添加 HTTP Basic Auth 密码保护

如果你的后台管理系统（如 /admin）还没有接入 OAuth，或者希望在外层加一层防护：

点击导航栏 Access Lists → Add Access List；
输入名单名称（例如 Admin Protection）；
切换至 Authorization 标签，添加允许的用户名与密码；
若需搭配 IP 限制，在 Access 标签填入允许放行的 IP 段（如 192.168.1.0/24）；
保存后，回到 Proxy Hosts 编辑该域名，在 Access List 下拉框中直接选中应用。

方案二：嵌入自定义 Nginx 指令（Custom Nginx Configuration）

当面板默认选项无法满足复杂业务需求时，无需进入容器手写文件。直接进入 Proxy Host 编辑界面的 Advanced 标签页输入特定指令：

# 1. 放宽大文件上传限制（默认仅 1MB）
client_max_body_size 50M;

# 2. 跨域 CORS 响应头注入
add_header 'Access-Control-Allow-Origin' '$http_origin' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
if ($request_method = 'OPTIONS') {
    return 204;
}

# 3. 超时时间调大（应对 AI 生成等流式长响应场景）
proxy_read_timeout 300s;
proxy_send_timeout 300s;

3.7 自动化备份与跨服务器迁移

NPM 的所有状态均保存在 data（含数据库与生成配置）与 letsencrypt（包含公私钥与账户凭证）目录下。

一键归档备份脚本

在项目目录下执行打包命令：

1 2	cd ~/nginx-proxy-manager tar -czvf npm-backup-$(date +%Y%m%d).tar.gz data letsencrypt docker-compose.yml

灾难恢复或跨云迁移步骤

在新服务器上还原配置只需三步：

将 npm-backup-*.tar.gz 传输到目标服务器；

解压归档文件：

1 2	mkdir -p ~/nginx-proxy-manager && cd ~/nginx-proxy-manager tar -xzvf npm-backup-20260702.tar.gz

执行 docker compose up -d 重新构建容器。DNS 解析更新到新 VPS 后，所有域名配置与 HTTPS 证书立即完整恢复。

4、生产落地检查清单

部署上线前，建议对照此表格逐项核实：

校验模块	检查命令 / 操作方法	合格标准
容器健康	`docker ps -f name=nginx-proxy-manager`	状态显示 `Up`，无异常频繁重启
端口监听	`sudo ss -tulpn \| grep -E ':(80\|443\|81)'`	80/443/81 均由 docker-proxy 监听
后台安全	外网 IP 直接请求 `http://<IP>:81`	外部无法直接建立 TCP 握手（连接超时/拒绝）
默认密码	面板左上角用户设置	邮箱已由 `[email protected]` 更改为个人邮箱
域名证书	`curl -Iv https://<域名> 2>&1 \| grep 'expire date'`	证书颁发者为 Let’s Encrypt，有效期处于 90 天内
跳转合规	`curl -s -o /dev/null -w "%{http_code}" http://<域名>`	返回状态码为 `301` 或 `308`
文件持久化	`ls -la ~/nginx-proxy-manager/data`	存在 `database.sqlite` 或 `nginx/` 目录结构

5、高频故障与异常排查

Q1：管理界面 81 端口在浏览器无法打开？

排查步骤：

检查云服务商安全组：AWS EC2 Security Group、阿里云/腾讯云安全组是否漏放了 81 端口入站规则。
检查宿主机 UFW：
1
sudo ufw status verbose
若配置了仅允许特定 IP，确认你当前本地宽带的公网 IP 是否发生过变动。

检查容器内部服务状态：

1	docker logs nginx-proxy-manager 2>&1 \| tail -n 30

Q2：申请 Let’s Encrypt 证书报错 Internal Error？

这是最常见的问题，通常由以下几种原因造成：

原因一：DNS 解析未完成公网收敛。刚修改 A 记录后各级 DNS 存在缓存，Let’s Encrypt 节点查询不到最新 IP。用 dig @8.8.8.8 <域名> 验证，等待数分钟再试。
原因二：80 端口被封堵。很多云服务商（尤其部分轻量服务器）默认封禁入站 80 端口，或者 VPS 上其他进程抢占了 80。
原因三：命中 Let’s Encrypt 频率限制（Rate Limits）。同一个主域名下每小时最多允许验证失败 5 次。若连续报错，切忌疯狂点击重新申请，需查看日志定位根因：
1
cat ~/nginx-proxy-manager/data/logs/fallback_error.log

Q3：反代后页面显示 502 Bad Gateway？

502 错误意味着 NPM 容器能够接收访客请求，但在向 upstream 后端转发时连接被拒。

容器与 NPM 不在同一网络：
若后端也是 Docker 容器，必须将后端容器与 NPM 加入同名 bridge 网络（如 npm-net），且在 Forward Hostname 填写容器名称。
1
2
3
4
5
# 后端容器的 docker-compose.yml 示例片段
networks:
default:
name: npm-net
external: true
误将 Forward Hostname 填为 127.0.0.1：
在容器内部，127.0.0.1 指向的是 NPM 容器自身，并非宿主机。Linux 环境下访问宿主机端口需填写宿主机 docker0 网桥 IP（通常为 172.17.0.1）。

Q4：如何查看 NPM 实时生成的真实 Nginx 配置文件？

如果你希望深入核实某个域名的底层配置指令：

# 查看各个 Proxy Host 生成的独立配置文件
ls -l ~/nginx-proxy-manager/data/nginx/proxy_host/

# 打印特定站点的完整指令块
cat ~/nginx-proxy-manager/data/nginx/proxy_host/1.conf

6、技术边界：何时回到纯手工 Nginx？

虽然 NPM 极大提升了微服务反代效率，但它并非全能工具。在以下场景中，建议切回直接手写 Nginx：

需要编译集成第三方模块：例如 ModSecurity、Lua 模块、Brotli 压缩模块等；
极高并发与超精细调优：当单机并发连接数突破数万，需在 events 块与内核参数中调优 epoll、worker_rlimit_nofile、so_reuseport 等底层指令；
复杂的动态 URL 重写（Rewrite）体系：遗留系统迁移涉及成百上千条复杂的正则 Rewrite 规则，图形界面维护成本反而高于代码仓库集中管理；
GitOps 集中式配置驱动：团队要求所有网关配置全部走 Git 提交、Code Review 并由 CI/CD 自动分发时，文本格式的 nginx.conf 更有利于版本追踪。

7、核心数据与行业参考

Nginx Proxy Manager（jc21/nginx-proxy-manager）是广泛采用的开源自托管网关工具：底层基于 OpenResty/Nginx，所有配置通过前端交互编译后热加载，不破坏底层 Nginx 的稳定性。Nginx Proxy Manager GitHub
Nginx 占据全球 Web 服务器核心市场份额：根据 W3Techs 统计，全球超 32% 的活跃站点采用 Nginx 支撑反向代理与静态资源托管。W3Techs Web Server Report
Let’s Encrypt 证书申请频率边界：单个注册域名（Registered Domain）每周证书签发上限为 50 张；同一域名完全相同的证书每周限制 5 张；单账户每小时验证失败上限为 5 次。Let’s Encrypt Documentation

8、推荐工具与延伸阅读

Cloudflare 基础配置速查：在域名层配合 NPM 进行 DNS 解析与流量调度。
UFW 防火墙速配指南：严密把控服务器开放端口，避免把管理后台直接裸露在公网。
ittinker-scripts 开源工具箱：包含 VPS 初始化、防火墙自动化及 Docker 快速部署的生产脚本。