目录
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
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 添加代理主机
-
登录管理界面后，点击顶部菜单中的"代理主机"
-
点击"添加代理主机"按钮
-
填写表单：
- 域名：您要代理的域名（例如：example.com）
- 转发目标：目标服务器地址和端口（例如：http://192.168.1.100:8080）
- 选择SSL配置：可以启用自动SSL证书
-
点击"保存"按钮完成配置
5.4 SSL证书配置
- 在添加代理主机时，切换到"SSL"选项卡
- 选择"请求新的SSL证书"
- 勾选"使用赛迪测试" - 适用于测试环境
- 勾选"我同意Let’s Encrypt服务条款"
- 点击"保存"按钮
六、高级配置
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 你的域名 - 检查80端口可访问性:
curl -I http://你的域名 - 查看详细错误日志:
docker-compose logs | grep -i "lets\|error\|certificate"
解决方案:
-
DNS问题: 确保域名正确解析到服务器IP，等待DNS生效(可能需要48小时)
-
防火墙问题: 确保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
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
