跳转至

583_Nginx Proxy Manager

一句话概述：Nginx Proxy Manager（NPM）是 Nginx 的可视化管理面板，通过 Web 界面配置反向代理、SSL 证书和访问控制，不需要手写 Nginx 配置文件。

核心知识点表

概念白话解释
反向代理把用户访问的域名转发到内部服务的指定端口
Proxy Host代理主机，一条"域名→内部服务"的转发规则
SSL 证书HTTPS 加密证书，NPM 自动通过 Let's Encrypt 申请
Redirection重定向，把一个域名跳转到另一个地址
Stream四层代理，转发 TCP/UDP 流量（如数据库、游戏服务器）
Access List访问控制列表，限制谁能访问某个代理

安装配置

Docker Compose 安装

# docker-compose.yml
services:
  npm:
    image: jc21/nginx-proxy-manager:latest  # 官方镜像
    container_name: npm                      # 容器名
    restart: unless-stopped                  # 自动重启
    ports:
      - "80:80"                              # HTTP
      - "443:443"                            # HTTPS
      - "81:81"                              # 管理面板
    volumes:
      - ./data:/data                         # 配置数据
      - ./letsencrypt:/etc/letsencrypt       # SSL 证书

mkdir -p data letsencrypt            # 创建目录
docker compose up -d                 # 启动

首次登录

# 浏览器打开：http://你的IP:81

# 默认管理员账号：
# 邮箱：admin@example.com
# 密码：changeme

# 首次登录后立即修改邮箱和密码！

基本使用

添加代理主机（最常用功能）

# 在管理面板操作：
# 1. Dashboard → Proxy Hosts → Add Proxy Host

# "Details" 标签页：
# - Domain Names：输入域名（如 app.example.com）
# - Scheme：选择 http 或 https
# - Forward Hostname / IP：内部服务地址
#   → 如果是 Docker 容器，用容器名（如 myapp）
#   → 如果是其他服务器，用 IP 地址（如 192.168.1.100）
# - Forward Port：内部服务端口（如 3000）
# - Block Common Exploits：开启（阻止常见攻击）
# - Websockets Support：如需 WebSocket 则开启

# "SSL" 标签页：
# - SSL Certificate：选择 "Request a new SSL Certificate"
# - Force SSL：开启（强制 HTTPS）
# - HTTP/2 Support：开启
# - 同意 Let's Encrypt 条款
# - Save

# 就这么简单！域名现在可以通过 HTTPS 访问了

添加重定向

# Proxy Hosts → Add Proxy Host → 或使用 Redirection Hosts
# 
# 场景：把 old.example.com 跳转到 new.example.com
# 
# Redirection Hosts → Add Redirection Host
# - Domain Names：old.example.com
# - Scheme：选择 auto
# - Forward Domain：new.example.com
# - Preserve Path：开启（保留 URL 路径）
# - HTTP Code：301（永久重定向）

配置 Stream（TCP/UDP代理）

# Streams → Add Stream
# 
# 场景：转发 MySQL 连接
# - Incoming Port：3307（外部访问端口）
# - Forward Host：mysql-server（内部服务）
# - Forward Port：3306（MySQL 默认端口）
# - TCP Forwarding：开启
# 
# 现在可以用 mysql -h your-ip -P 3307 连接

访问控制

# Access Lists → Add Access List
# 
# 1. 创建访问列表：
# - Name：给个名字（如 "内部访问"）
# - Satisfy Any：有一个条件满足即可
# 
# 2. Authorization：添加用户名/密码（HTTP 基本认证）
#    - Username: admin
#    - Password: your-password
# 
# 3. Access：添加 IP 白名单
#    - Allow: 192.168.1.0/24（允许局域网）
#    - Deny: all（拒绝其他）
# 
# 4. 在 Proxy Host 中选择这个 Access List

高级用法

自定义 Nginx 配置

# 在 Proxy Host 编辑页 → "Advanced" 标签页
# 可以添加自定义 Nginx 配置，例如：

# 增大上传文件限制
client_max_body_size 100m;

# 添加自定义头
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# 缓存设置
proxy_cache_valid 200 1d;

# 自定义错误页面
error_page 502 /custom_502.html;

Docker 网络配置（重要！）

# 关键：NPM 和被代理的服务必须在同一 Docker 网络中！

# docker-compose.yml
services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    ports:
      - "80:80"
      - "443:443"
      - "81:81"
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - proxy                          # 加入 proxy 网络

  myapp:
    image: myapp:latest
    # 注意：不需要暴露端口到主机！
    # NPM 通过 Docker 内部网络直接访问
    networks:
      - proxy                          # 同一网络

networks:
  proxy:
    name: proxy                        # 命名网络
    driver: bridge

# 如果应用在另一个 docker-compose 文件中：
# 在那个文件中也加入 proxy 网络：

networks:
  proxy:
    external: true                     # 使用已存在的外部网络

# 然后在 Proxy Host 中用容器名作为 Forward Hostname

使用自定义 SSL 证书

# SSL Certificates → Add SSL Certificate → Custom
# 上传你自己的证书文件：
# - Certificate Key：私钥文件（.key）
# - Certificate：证书文件（.crt/.pem）
# - Intermediate Certificate：中间证书（可选）

使用 DNS Challenge（通配符证书）

# SSL Certificates → Add SSL Certificate → Let's Encrypt
# 
# 对于通配符证书（*.example.com）：
# - Domain Names：*.example.com
# - Use a DNS Challenge：开启
# - DNS Provider：选择你的 DNS 服务商（Cloudflare/阿里云等）
# - 填入 API Token
# 
# 这样一个证书覆盖所有子域名

常见报错

报错信息原因解决方案
502 Bad Gateway后端服务不可达检查容器名/IP和端口，确认在同一网络
SSL certificate errorLet's Encrypt 验证失败确保 80 端口可从外网访问，DNS 已解析
Connection refused目标端口未监听检查目标服务是否运行
Too many redirects代理配置和应用都做了 HTTPS 重定向应用侧关闭 HTTPS 重定向
413 Entity Too Large上传文件超过 Nginx 限制Advanced 中加 client_max_body_size 100m;
管理面板无法访问81 端口被防火墙阻止开放防火墙 81 端口

速查表

# === 安装 ===
# 镜像：jc21/nginx-proxy-manager:latest
# 端口：80(HTTP) + 443(HTTPS) + 81(管理面板)
# 默认账号：admin@example.com / changeme

# === 功能入口 ===
# Proxy Hosts      → 反向代理配置（最常用）
# Redirection Hosts → URL 重定向
# Streams           → TCP/UDP 代理
# 404 Hosts         → 自定义 404 页面
# SSL Certificates  → SSL 证书管理
# Access Lists      → 访问控制
# Users             → 用户管理

# === Forward Hostname 填写规则 ===
# Docker 同网络容器 → 用容器名（如 myapp）
# 主机上的服务     → 用 host.docker.internal（macOS/Win）
#                    或用宿主机 IP（Linux）
# 其他服务器       → 用 IP 地址

# === 常用 Advanced 配置 ===
client_max_body_size 100m;             # 上传限制
proxy_read_timeout 300s;               # 读取超时
proxy_connect_timeout 60s;             # 连接超时

同类对比

特性NPMTraefikCaddyNginx 手动
配置方式GUI 点击Docker LabelCaddyfile手写配置文件
学习曲线极低中等低高
自动发现不支持Docker 原生不支持不支持
SSL 管理GUI 一键自动自动需 certbot
适合场景家庭/小团队Docker/K8s简单部署高度定制
性能好优秀良好极佳
高级功能基础丰富中等最灵活

选型建议：新手或不想写配置文件选 NPM（纯 GUI 操作）；Docker 环境选 Traefik（自动发现）；追求简洁选 Caddy；需要极致性能和灵活性选原生 Nginx。