Nginx Proxy Manager 中文版安装部署

world_alive
2025年7月7日2025年7月8日
Docker, Nginx

Nginx Proxy Manager 中文版安装部署

Nginx Proxy Manager 中文版安装部署教程

一、项目简介

Nginx Proxy Manager (NPM) 是一个基于Nginx的开源反向代理管理工具，提供了友好的Web界面，让用户可以轻松管理Nginx代理配置，而无需深入了解Nginx的复杂配置语法。本文档介绍的是由GitHub用户xiaoxinpro基于原版翻译的中文版本，为中文用户提供了更友好的使用体验。

1.1 主要功能特点

通过Web界面管理Nginx反向代理配置
自动申请和管理SSL证书（Let’s Encrypt集成）
支持HTTP重定向到HTTPS
支持自定义SSL证书
支持访问控制（基本身份验证）
支持流代理（TCP/UDP）
完整的中文用户界面

1.2 项目地址

中文版项目：https://github.com/xiaoxinpro/nginx-proxy-manager-zh
原版项目：https://nginxproxymanager.com/

1.3 系统架构与工作原理

Nginx Proxy Manager(NPM)的系统架构主要由以下几部分组成：

┌─────────────────────────────────┐
│    客户端浏览器/应用程序        │
└───────────────┬─────────────────┘
                │
                ▼
┌─────────────────────────────────┐
│      Nginx Proxy Manager        │
│                                 │
│  ┌─────────────┐ ┌───────────┐  │
│  │ Nginx服务器  │ │ 管理API    │  │
│  └──────┬──────┘ └─────┬─────┘  │
│         │              │        │
│  ┌──────▼──────┐ ┌─────▼─────┐  │
│  │ 配置生成器    │ │ Web界面   │  │
│  └──────┬──────┘ └───────────┘  │
│         │                       │
│  ┌──────▼──────────────────┐    │
│  │ Let's Encrypt客户端      │    │
│  └─────────────────────────┘    │
└─────────────────┬───────────────┘
                  │
                  ▼
┌─────────────────────────────────┐
│       后端服务/应用程序            │
└─────────────────────────────────┘

工作原理：

配置管理：
- 用户通过Web界面进行配置操作
- 管理API接收请求并处理配置变更
- 配置生成器将用户配置转换为Nginx配置文件
请求处理流程：
- 客户端请求发送到NPM服务器(80/443端口)
- Nginx根据配置规则匹配请求域名
- 请求被路由到对应的后端服务
- 响应返回给客户端
SSL证书管理：
- 用户通过界面申请SSL证书
- Let’s Encrypt客户端自动完成验证和申请
- 证书自动应用到对应的代理配置
- 证书自动更新(90天有效期)

1.4 适用场景

Nginx Proxy Manager特别适合以下应用场景：

多站点托管：在单一服务器上托管多个网站或Web应用
内部服务暴露：安全地将内部服务暴露到公网
HTTP转HTTPS：为所有服务提供统一的SSL加密访问
开发环境代理：整合不同端口和服务到域名
家庭/小型企业服务器：简化服务访问管理

二、系统要求

2.1 硬件要求

CPU: 1核心以上
内存: 512MB以上
存储空间: 1GB以上

2.2 软件要求

Docker 19.03.0+
Docker Compose 1.24.0+
具有公网IP的服务器（用于SSL证书申请）
开放端口: 80, 81, 443

三、Docker环境部署

在开始安装Nginx Proxy Manager之前，我们需要先在服务器上安装Docker和Docker Compose。

3.1 CentOS系统安装Docker

# 1. 安装必要的依赖
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 2. 添加Docker仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 3. 安装Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 4. 启动Docker并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 5. 验证Docker安装
sudo docker --version

3.2 Ubuntu系统安装Docker

# 1. 更新apt包索引
sudo apt-get update

# 2. 安装必要的依赖
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 3. 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 4. 添加Docker仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 更新apt包索引并安装Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 6. 启动Docker并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 7. 验证Docker安装
sudo docker --version

3.3 安装Docker Compose

# 1. 下载Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.15.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 2. 添加可执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 3. 创建软链接
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

# 4. 验证安装
docker-compose --version

四、安装Nginx Proxy Manager中文版

4.1 创建项目目录

# 创建并进入项目目录
mkdir -p ~/npm
cd ~/npm

4.2 创建docker-compose.yml文件

# 创建配置文件
vi docker-compose.yml

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

version: '3'
services:
  app:
    image: 'chishin/nginx-proxy-manager-zh:latest'
    restart: always
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

#####官网原版 https://nginxproxymanager.com/guide/

 
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

4.3 更新容器

 
###1. 停止运行中的容器组
cd npm && docker compose down
###2. 备份数据（重要）
cp -r ~/npm ~/npm.back
###需要注意的是，npm.back 文件名不一定要根据此文档命名，这里仅仅是个示例。

4.4 更新服务

 
###拉取最新镜像
docker compose pull
###重新启动容器
docker compose up -d

五、初始配置和使用

5.1 访问管理界面

通过浏览器访问 http://服务器IP:81 打开Nginx Proxy Manager的管理界面。登录页面如下(中文版)：

┌────────────────────────────────────────────┐
│                                            │
│             Nginx Proxy Manager            │
│                                            │
│  ┌────────────────────────────────────┐    │
│  │             登录                    │    │
│  │                                    │    │
│  │  电子邮箱:                         │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │ [email protected]          │    │    │
│  │  └────────────────────────────┘    │    │
│  │                                    │    │
│  │  密码:                             │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │ ********                   │    │    │
│  │  └────────────────────────────┘    │    │
│  │                                    │    │
│  │         ┌──────────────┐           │    │
│  │         │     登录     │           │    │
│  │         └──────────────┘           │    │
│  └────────────────────────────────────┘    │
│                                            │
└────────────────────────────────────────────┘

5.2 首次登录

首次登录使用以下默认管理员账号：

Email:    [email protected]
Password: changeme

登录后，系统会立即要求您修改管理员信息和密码。请务必设置一个安全性高的密码以保护您的服务器安全。

5.3 添加代理主机

登录管理界面后，点击顶部菜单中的”代理主机”
点击”添加代理主机”按钮
填写表单：
- 域名：您要代理的域名（例如：example.com）
- 转发目标：目标服务器地址和端口（例如：http://192.168.1.100:8080）
- 选择SSL配置：可以启用自动SSL证书
点击”保存”按钮完成配置

5.4 SSL证书配置

在添加代理主机时，切换到”SSL”选项卡
选择”请求新的SSL证书”
勾选”使用赛迪测试” – 适用于测试环境
勾选”我同意Let’s Encrypt服务条款”
点击”保存”按钮

 
###    中文默认填写的信息是  token 未测试成功 改为原版使用的 api key 测试可用
# Cloudflare API credentials used by Certbot
dns_cloudflare_email = [email protected]
dns_cloudflare_api_key = api key

六、高级配置

6.1 添加访问控制

在代理主机详情页，点击”编辑”
切换到”高级”选项卡
启用”基本身份验证”
添加用户名和密码
点击”保存”按钮

6.2 配置自定义SSL证书

在管理界面，点击”SSL证书”
点击”添加SSL证书”
选择”自定义”
上传您的证书和私钥文件
点击”保存”按钮

6.3 配置TCP/UDP流代理

在管理界面，点击”流”
点击”添加流”
配置：
- 连接类型：TCP或UDP
- 转发主机名: 目标主机名或IP
- 转发端口: 目标端口
- 入站端口: 接收连接的端口
点击”保存”按钮

七、日常维护

7.1 查看日志

# 查看容器日志
docker-compose logs -f

7.2 备份配置

Nginx Proxy Manager的所有配置都保存在 ~/npm/data 目录中，您可以定期备份此目录：

# 备份数据目录
tar -czvf npm-backup-$(date +%Y%m%d).tar.gz ~/npm/data ~/npm/letsencrypt

7.3 升级操作

当需要升级Nginx Proxy Manager时，可以按照以下步骤操作：

# 进入项目目录
cd ~/npm

# 停止容器
docker-compose down

# 拉取最新镜像
docker-compose pull

# 启动容器
docker-compose up -d

八、故障排除

8.1 无法访问管理界面

检查服务器防火墙是否开放81端口
检查服务是否正常运行：docker-compose ps
检查容器日志：docker-compose logs

8.2 SSL证书申请失败

确保域名已正确解析到服务器IP
确保80和443端口可以从公网访问
检查Let’s Encrypt限制（短时间内申请过多证书会受限）

8.3 代理转发失败

检查目标服务是否正常运行
检查网络连接是否通畅
检查代理配置是否正确

8.4 详细故障排查指南

问题1: NPM容器无法启动

症状: docker-compose up -d后容器立即退出 排查步骤:

查看详细日志: docker-compose logs
检查端口占用情况: netstat -tulpn | grep -E '80|81|443'
检查挂载目录权限: ls -la ~/npm/

解决方案:

如果端口被占用: 停止占用端口的服务或修改NPM端口映射
如果是权限问题: sudo chown -R $(whoami):$(whoami) ~/npm/
如果数据库损坏: 备份并重新初始化数据库

# 备份数据
cp -r ~/npm/data ~/npm/data_backup

# 重新初始化(注意会丢失所有配置)
rm -rf ~/npm/data
docker-compose down
docker-compose up -d

问题2: SSL证书申请失败

症状: 在界面操作中SSL证书申请失败，出现”Challenge Failed”错误 排查步骤:

检查域名DNS解析: dig +short 你的域名
ERROR: Cannot install certbot-dns-cloudflare
检查80端口可访问性: curl -I http://你的域名
查看详细错误日志: docker-compose logs | grep -i "lets\|error\|certificate"

解决方案:

DNS问题: 确保域名正确解析到服务器IP，等待DNS生效(可能需要48小时)
进入容器：apt install python3-certbot-dns-cloudflare（仅限使用CF验证的）

防火墙问题: 确保80和443端口对外开放

# iptables开放端口
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
service iptables save

# 或使用firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload

申请频率限制: Let’s Encrypt有频率限制，等待一段时间后重试

问题3: 反向代理504超时错误

症状: 访问代理网站时出现504 Gateway Timeout错误 排查步骤:

检查目标服务状态: curl -I http://目标IP:端口
检查NPM与目标服务器网络连接
查看nginx错误日志: docker exec -it npm-app cat /var/log/nginx/error.log

解决方案:

增加超时设置: 在代理主机的高级选项中增加超时设置

添加自定义Nginx配置:

proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
send_timeout 300s;

检查目标服务器性能，可能需要优化后端服务

问题4: WebSocket连接失败

症状: 网站WebSocket功能无法正常工作 排查步骤:

在浏览器开发者工具中查看WebSocket连接错误
检查代理配置中是否启用了WebSocket支持

解决方案:

在代理主机设置中启用WebSocket支持

添加自定义配置支持WebSocket:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;

问题5: 管理界面密码遗忘

症状: 无法登录NPM管理界面 解决方案: 通过重置数据库中的管理员密码:

# 进入容器
docker-compose exec app /bin/sh

# 安装SQLite工具
apk add --no-cache sqlite

# 连接到数据库并重置密码
sqlite3 /data/database.sqlite

在SQLite提示符下执行:

-- 查看用户列表
SELECT id, name, email FROM users;

-- 重置ID为1的用户密码为"changeme"
UPDATE users SET 
password = '$2a$08$EbEwC10JJT92XD7n7rCQMuHLE8JHWqmYqQECYZbs.n9M6R7bJVlUO'
WHERE id = 1;

-- 退出
.exit

九、最佳实践

9.1 安全加固

更改默认管理端口（81）
使用强密码保护管理员账号
定期更新容器镜像
限制管理界面的访问IP

以下是更详细的安全加固建议：

9.1.1 修改默认管理端口

默认管理端口(81)可能成为攻击目标，可通过修改docker-compose.yml文件来更改：

version: '3'
services:
  app:
    image: 'chishin/nginx-proxy-manager-zh:latest'
    restart: always
    ports:
      - '80:80'
      - '8888:81'  # 将管理界面端口从81修改为8888
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

修改后重启容器：docker-compose down && docker-compose up -d

9.1.2 使用反向代理保护管理界面

可以设置NPM自身管理界面的反向代理，添加以下安全措施：

为管理界面设置专用域名
启用SSL加密
配置IP访问限制
启用双重认证

配置示例：

域名: npm-admin.example.com
方案: http
转发主机名/IP: 127.0.0.1
转发端口: 81
访问限制: 允许xxx.xxx.xxx.xxx/32
基本认证: 启用
SSL: Let's Encrypt
强制SSL: 启用

9.1.3 Docker容器安全加固

限制Docker容器的权限和资源使用：

version: '3'
services:
  app:
    image: 'chishin/nginx-proxy-manager-zh:latest'
    restart: always
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    # 安全加固配置
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    # 资源限制
    mem_limit: 512m
    cpus: 1

9.1.4 定期安全更新

创建一个更新脚本scheduled-update.sh并设置定期执行：

#!/bin/bash
# 更新NPM容器
cd /path/to/npm
docker-compose pull
docker-compose down
docker-compose up -d

# 备份配置
tar -czvf /path/to/backups/npm-backup-$(date +%Y%m%d).tar.gz ./data ./letsencrypt

# 清理旧备份(保留最近30天)
find /path/to/backups/ -name "npm-backup-*.tar.gz" -mtime +30 -delete

将此脚本添加到crontab定期执行：

0 2 * * 0 /path/to/scheduled-update.sh >> /var/log/npm-update.log 2>&1

9.2 性能优化

为频繁访问的站点启用缓存
适当调整Nginx工作进程数
监控系统资源使用情况

9.2.1 高级缓存配置

NPM默认缓存配置较为基础，可添加自定义Nginx配置提升性能：

# 设置缓存路径
proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m;
proxy_temp_path /data/nginx/temp;

# 缓存配置
proxy_cache my_cache;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;

9.2.2 调整工作进程数

为Nginx服务器优化工作进程数量，创建自定义配置文件：

# 设置工作进程数为自动(根据CPU核心数)
worker_processes auto;

# 调整每个工作进程的连接数
events {
    worker_connections 1024;
    multi_accept on;
    use epoll;
}

# 调整超时设置
http {
    keepalive_timeout 65;
    keepalive_requests 100;
    client_body_timeout 10;
    client_header_timeout 10;
    send_timeout 10;
}

9.2.3 启用Gzip压缩

启用Gzip压缩可以显著减少传输数据大小：

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;

十、参考资料

中文版项目地址：https://github.com/xiaoxinpro/nginx-proxy-manager-zh
原版项目文档：https://nginxproxymanager.com/
Docker官方文档：https://docs.docker.com/
Docker Compose文档：https://docs.docker.com/compose/
Let’s Encrypt文档：https://letsencrypt.org/docs/

十、应用场景示例

10.1 WordPress网站反向代理

场景：将运行在内部服务器上的WordPress站点通过HTTPS安全地发布到互联网。 配置步骤：

确保您的域名(如example.com)已正确解析到NPM服务器IP
在NPM中添加新的代理主机:
- 域名: example.com 和 www.example.com
- 转发目标: http://内部服务器IP:80
- SSL: 申请Let’s Encrypt证书
- 高级选项: 启用WebSocket支持、启用缓存

配置示例:

域名: example.com, www.example.com
方案: http
转发主机名/IP: 192.168.1.10
转发端口: 80
缓存资源: 开启
WebSockets支持: 开启
SSL: Let's Encrypt
强制SSL: 开启
HTTP/2 支持: 开启

10.2 内部服务访问集成

场景：公司内部有多个服务(监控系统、文档系统、开发工具等)需要通过统一的域名访问。 配置步骤：

使用子域名区分不同服务
为每个服务配置代理:
- 监控系统: monitor.internal.com → http://监控服务器:8080
- 文档系统: docs.internal.com → http://文档服务器:3000
- 开发工具: dev.internal.com → http://开发服务器:9000
为每个子域名配置基本认证，限制访问

配置示例:

域名: monitor.internal.com
方案: http
转发主机名/IP: 192.168.1.20
转发端口: 8080
基本认证: 开启
  用户名: monitor-admin
  密码: 安全密码
SSL: 自定义证书(内部CA签发)

10.3 API网关应用

场景：为多个微服务API提供统一的访问入口，并添加安全层。 配置步骤：

使用路径区分不同API服务
配置路径转发:
- 用户服务: api.example.com/users → http://用户服务:8001
- 订单服务: api.example.com/orders → http://订单服务:8002
- 产品服务: api.example.com/products → http://产品服务:8003
添加适当的请求头和CORS配置

配置注意：NPM默认不支持路径级别的代理转发，需要通过自定义Nginx配置实现：

# 用户服务配置
location /users {
    proxy_pass http://用户服务IP:8001;
    proxy_set_header Host $host;
    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;
}

# 订单服务配置
location /orders {
    proxy_pass http://订单服务IP:8002;
    proxy_set_header Host $host;
    # ... 其他头信息 ...
}

10.4 媒体流服务代理

场景：通过HTTPS提供流媒体服务，如视频直播或音频流。 配置步骤：

添加代理主机用于HTTP直播服务
启用WebSocket支持
配置较长的超时时间
为TCP流添加流代理配置

配置示例:

# HTTP流配置
域名: stream.example.com
方案: http
转发主机名/IP: 192.168.1.30
转发端口: 1935
WebSockets支持: 开启
缓存资源: 关闭
客户端超时: 300
SSL: Let's Encrypt

# RTMP流配置(通过流代理)
流类型: TCP
转发主机名: 192.168.1.30
转发端口: 1935
入站端口: 1935

参考URL: https://blog.csdn.net/weixin_45693551/article/details/147654511 https://nginxproxymanager.com/guide/ https://www.bilibili.com/opus/1053089688529666066

2025 年 7 月
一	二	三	四	五	六	日
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	31

Nginx Proxy Manager 中文版安装部署

Nginx Proxy Manager 中文版安装部署

目录

Nginx Proxy Manager 中文版安装部署教程

一、项目简介

1.1 主要功能特点

1.2 项目地址

1.3 系统架构与工作原理

1.4 适用场景

二、系统要求

2.1 硬件要求

2.2 软件要求

三、Docker环境部署

3.1 CentOS系统安装Docker

3.2 Ubuntu系统安装Docker

3.3 安装Docker Compose

四、安装Nginx Proxy Manager中文版

4.1 创建项目目录

4.2 创建docker-compose.yml文件

4.3 更新容器

4.4 更新服务

五、初始配置和使用

5.1 访问管理界面

5.2 首次登录

5.3 添加代理主机

5.4 SSL证书配置

六、高级配置

6.1 添加访问控制

6.2 配置自定义SSL证书

6.3 配置TCP/UDP流代理

七、日常维护

7.1 查看日志

7.2 备份配置

7.3 升级操作

八、故障排除

8.1 无法访问管理界面

8.2 SSL证书申请失败

8.3 代理转发失败

8.4 详细故障排查指南

问题1: NPM容器无法启动

问题2: SSL证书申请失败

问题3: 反向代理504超时错误

问题4: WebSocket连接失败

问题5: 管理界面密码遗忘

九、最佳实践

9.1 安全加固

9.1.1 修改默认管理端口

9.1.2 使用反向代理保护管理界面

9.1.3 Docker容器安全加固

9.1.4 定期安全更新

9.2 性能优化

9.2.1 高级缓存配置

9.2.2 调整工作进程数

9.2.3 启用Gzip压缩

十、参考资料

十、应用场景示例

10.1 WordPress网站反向代理

10.2 内部服务访问集成

10.3 API网关应用

10.4 媒体流服务代理

上一篇

下一篇

world_alive