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客户端      │    │
│  └─────────────────────────┘    │
└─────────────────┬───────────────┘│▼
┌─────────────────────────────────┐
│       后端服务/应用程序            │
└─────────────────────────────────┘

工作原理：

1. 配置管理：

   • 用户通过Web界面进行配置操作
   • 管理API接收请求并处理配置变更
   • 配置生成器将用户配置转换为Nginx配置文件

2. 请求处理流程：

   • 客户端请求发送到NPM服务器(80/443端口)
   • Nginx根据配置规则匹配请求域名
   • 请求被路由到对应的后端服务
   • 响应返回给客户端

3. SSL证书管理：

   • 用户通过界面申请SSL证书
   • Let’s Encrypt客户端自动完成验证和申请
   • 证书自动应用到对应的代理配置
   • 证书自动更新(90天有效期)

1.4 适用场景

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

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

二、系统要求

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: alwaysports:- '80:80'- '81:81'- '443:443'volumes:- ./data:/data- ./letsencrypt:/etc/letsencrypt

4.3 启动服务

# 在后台启动服务
docker-compose up -d

五、初始配置和使用

5.1 访问管理界面

通过浏览器访问 http://服务器IP:81 打开Nginx Proxy Manager的管理界面。

登录页面如下(中文版)：

┌────────────────────────────────────────────┐
│                                            │
│             Nginx Proxy Manager            │
│                                            │
│  ┌────────────────────────────────────┐    │
│  │             登录                    │    │
│  │                                    │    │
│  │  电子邮箱:                         │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │ admin@example.com          │    │    │
│  │  └────────────────────────────┘    │    │
│  │                                    │    │
│  │  密码:                             │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │ ********                   │    │    │
│  │  └────────────────────────────┘    │    │
│  │                                    │    │
│  │         ┌──────────────┐           │    │
│  │         │     登录     │           │    │
│  │         └──────────────┘           │    │
│  └────────────────────────────────────┘    │
│                                            │
└────────────────────────────────────────────┘

5.2 首次登录

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

Email:    admin@example.com
Password: changeme

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

5.3 添加代理主机

1. 登录管理界面后，点击顶部菜单中的"代理主机"

2. 点击"添加代理主机"按钮

3. 填写表单：

   • 域名：您要代理的域名（例如：example.com）
   • 转发目标：目标服务器地址和端口（例如：http://192.168.1.100:8080）
   • 选择SSL配置：可以启用自动SSL证书

4. 点击"保存"按钮完成配置

5.4 SSL证书配置

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

六、高级配置

6.1 添加访问控制

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

6.2 配置自定义SSL证书

1. 在管理界面，点击"SSL证书"
2. 点击"添加SSL证书"
3. 选择"自定义"
4. 上传您的证书和私钥文件
5. 点击"保存"按钮

6.3 配置TCP/UDP流代理

1. 在管理界面，点击"流"

2. 点击"添加流"

3. 配置：

   • 连接类型：TCP或UDP
   • 转发主机名: 目标主机名或IP
   • 转发端口: 目标端口
   • 入站端口: 接收连接的端口

4. 点击"保存"按钮

七、日常维护

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后容器立即退出

排查步骤:

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

解决方案:

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

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

问题2: SSL证书申请失败

症状: 在界面操作中SSL证书申请失败，出现"Challenge Failed"错误

排查步骤:

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

解决方案:

1. DNS问题: 确保域名正确解析到服务器IP，等待DNS生效(可能需要48小时)

2. 防火墙问题: 确保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
   

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

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

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

排查步骤:

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

解决方案:

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

2. 添加自定义Nginx配置:

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

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

问题4: WebSocket连接失败

症状: 网站WebSocket功能无法正常工作

排查步骤:

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

解决方案:

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

2. 添加自定义配置支持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: alwaysports:- '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自身管理界面的反向代理，添加以下安全措施：

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

配置示例：

域名: 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: alwaysports:- '80:80'- '81:81'- '443:443'volumes:- ./data:/data- ./letsencrypt:/etc/letsencrypt# 安全加固配置security_opt:- no-new-privileges:truecap_drop:- ALLcap_add:- NET_BIND_SERVICE# 资源限制mem_limit: 512mcpus: 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安全地发布到互联网。

配置步骤：

1. 确保您的域名(如example.com)已正确解析到NPM服务器IP

2. 在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 内部服务访问集成

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

配置步骤：

1. 使用子域名区分不同服务

2. 为每个服务配置代理:

   • 监控系统: monitor.internal.com → http://监控服务器:8080
   • 文档系统: docs.internal.com → http://文档服务器:3000
   • 开发工具: dev.internal.com → http://开发服务器:9000

3. 为每个子域名配置基本认证，限制访问

配置示例:

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

10.3 API网关应用

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

配置步骤：

1. 使用路径区分不同API服务

2. 配置路径转发:

   • 用户服务: api.example.com/users → http://用户服务:8001
   • 订单服务: api.example.com/orders → http://订单服务:8002
   • 产品服务: api.example.com/products → http://产品服务:8003

3. 添加适当的请求头和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提供流媒体服务，如视频直播或音频流。

配置步骤：

1. 添加代理主机用于HTTP直播服务
2. 启用WebSocket支持
3. 配置较长的超时时间
4. 为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