nginx-ui 部署与使用指南

 

项目简介

 

nginx-ui 是一个现代化的 NGINX Web 管理面板，使用 Golang + Vue3 开发。
它提供直观的 Web 可视化界面，用于：

  • 管理 NGINX 配置

  • 配置反向代理

  • 管理 SSL 证书

  • 查看访问日志

  • 监控 NGINX 状态
    相比传统 Java 类管理面板：

  • 更轻量

  • 内存占用低

  • 启动速度快

- 更适合小内存 VPS NAS 云服务器

功能特点

Web 可视化管理

  • WebUI 在线编辑 NGINX 配置

  • 支持虚拟主机管理

  • 支持多域名代理配置

- 支持配置热加载

SSL 证书管理

  • 内置 Let’s Encrypt 集成

  • 支持自动申请 HTTPS 证书

  • 支持自动续签

- 支持手动上传证书与私钥

多用户与权限管理

  • 内置 RBAC 权限控制

  • 支持多用户管理

- 支持权限隔离

可观察性

  • 实时查看 NGINX 状态

  • 查看访问日志

  • 查看错误日志

- 支持 Prometheus 指标采集

API 支持

  • 提供 REST API

  • 方便自动化运维

- 支持二次开发集成

系统需求

 

项目要求
操作系统Linux / macOS
推荐环境Linux 服务器
NGINX已安装并正常运行
内存占用30–80 MB

|推荐权限 |root 或具备 NGINX 管理权限 |

部署方式

推荐：

  1. Docker 部署（最简单）

2. 二进制部署（生产更灵活）

1. Docker 部署（推荐）

启动容器

docker run -d \
  --name nginx-ui \
  -p 8080:8080 \
  -v /etc/nginx:/etc/nginx \
  -v /etc/letsencrypt:/etc/letsencrypt \
  --restart=always \
  0xjacky/nginx-ui:latest

参数说明

参数说明
-p 8080:8080映射 Web 管理端口
-v /etc/nginx:/etc/nginx挂载 NGINX 配置目录
-v /etc/letsencrypt:/etc/letsencrypt挂载 SSL 证书目录

|--restart=always |容器异常退出自动重启 |

访问 WebUI

浏览器访问：

http://服务器IP:8080

2. 二进制文件部署（推荐生产环境）

2.1 下载程序

官方下载地址：

  • GitHub Release：
    github.com/0xJacky/n...
    本文示例版本：

    v2.3.11

2.2 创建目录

mkdir -p /wzxy/nginxui
cd /wzxy/nginxui

2.3 上传安装包

示例文件：

nginx-ui-linux-64.tar.gz
nginx-ui-linux-64.tar.gz.digest

2.4 校验 SHA256（可选）

sha256sum -c nginx-ui-linux-64.tar.gz.digest

如果输出：

OK

说明：

  • 文件完整

- 未被篡改

2.5 解压程序

tar -xzf nginx-ui-linux-64.tar.gz

2.6 启动 nginx-ui

./nginx-ui

首次启动后会自动生成：

  • SQLite 数据库

  • 配置文件

- 默认目录结构

3. app.ini 配置说明

官方示例配置：
github.com/0xJacky/n...
默认生成后一般无需修改。

示例配置

[app]
PageSize  = 20
JwtSecret = FUXjeiVNwdtNqh

[server]
Host        = 0.0.0.0
Port        = 9000
RunMode     = release
EnableHTTPS = false
EnableH2    = false
EnableH3    = false

[auth]
IPWhiteList         =
BanThresholdMinutes = 10
MaxAttempts         = 10

[nginx]
AccessLogPath   = /var/log/nginx/access.log
ErrorLogPath    = /var/log/nginx/error.log
LogDirWhiteList = /var/log/nginx
ConfigDir       = /etc/nginx
PIDPath         = /run/nginx.pid
ReloadCmd       = /usr/sbin/nginx -s reload
RestartCmd      = /usr/sbin/nginx -s reload

[node]
Name             = Local
Secret           =
SkipInstallation = false

4. HTTPS 证书目录

证书与私钥建议统一放置：

/etc/nginx/

例如：

/etc/nginx/cert.pem
/etc/nginx/cert.key

5. 使用 Supervisor 托管（推荐）

生产环境建议通过 Supervisor 管理 nginx-ui。
优点：

  • 自动拉起

  • 崩溃自动重启

  • 日志统一管理

- 开机自启

5.1 创建 Supervisor 配置

创建文件：

/etc/supervisord.d/nginxui.ini

或者：

/etc/supervisor/conf.d/nginxui.conf

配置内容

[program:nginxui]

; =========================
; 1. 启动命令
; =========================
command=/wzxy/nginxui/nginx-ui

; =========================
; 2. 运行环境
; =========================

; 工作目录
directory=/wzxy/nginxui

; 使用 root 身份运行
user=root

; 环境变量
environment=SPRING_PROFILES_ACTIVE="prod"

; =========================
; 3. 启动与重启策略
; =========================

; Supervisor 启动时自动拉起
autostart=true

; 异常退出自动重启
autorestart=true

; 持续运行 30 秒才视为启动成功
startsecs=30

; 启动失败最大重试次数
startretries=3

; =========================
; 4. 日志配置
; =========================

; stderr 合并到 stdout
redirect_stderr=true

; 日志文件路径
stdout_logfile=/wzxy/nginxui/log/nginxui.log

; 单文件最大大小
stdout_logfile_maxbytes=10MB

; 保留历史日志数量
stdout_logfile_backups=10

; =========================
; 5. 可选配置
; =========================

; priority=999

5.2 创建日志目录

mkdir -p /wzxy/nginxui/log

5.3 重新加载 Supervisor

supervisorctl reread

supervisorctl update

5.4 启动 nginx-ui

supervisorctl start nginxui

查看状态：

supervisorctl status

5.5 查看日志

tail -f /wzxy/nginxui/log/nginxui.log

6. 放行防火墙端口

 

如果开启了防火墙：

firewall-cmd --permanent --add-port=9000/tcp

firewall-cmd --reload

7. 推荐生产部署架构

推荐：

Browser
    ↓
Nginx :80 / :443
    ↓
nginx-ui :9000

即：

  • 外部用户访问 NGINX

  • nginx-ui 不直接暴露公网

- 使用 NGINX 做反向代理

8. NGINX 反向代理 nginx-ui

示例：

server {
    listen 80;

    server_name nginxui.example.com;

    location / {
        proxy_pass http://127.0.0.1:9000;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

9. 常用命令

Supervisor

命令说明
supervisorctl status查看状态
supervisorctl start nginxui启动
supervisorctl stop nginxui停止
supervisorctl restart nginxui重启
supervisorctl tail nginxui查看日志

nginx-ui

命令说明 
./nginx-ui前台启动 
./nginx-ui -h查看帮助 
`ps -efgrep nginx-ui`查看进程

10. 注意事项

10.1 root 权限问题

nginx-ui 需要：

  • 修改 NGINX 配置

  • 重载 NGINX

  • 管理证书
    因此通常需要：

    root 权限

    否则可能无法：

  • reload nginx

  • 写入配置文件

  • 读取日志

10.2 配置修改后建议测试

执行：

nginx -t

确认配置正常后再 reload。

10.3 不建议直接暴露公网

推荐：

公网
  ↓
Nginx HTTPS
  ↓
nginx-ui

不要：

公网 → 9000

避免管理后台被扫描攻击。

10.4 建议开启 HTTPS

管理后台建议：

  • HTTPS

  • 强密码

  • IP 白名单

- Fail2Ban

结束

至此，你已经完成：

  • nginx-ui 安装

  • Supervisor 托管

  • WebUI 管理

  • SSL 管理

  • NGINX 配置管理

  • Prometheus 支持
    适用于：

  • VPS

  • NAS

  • 云服务器

  • 小型生产环境

  • Spring Boot 反向代理管理场景

作者：zws  创建时间：2026-05-24 17:17
最后编辑：zws  更新时间：2026-05-24 17:36
上一篇：
下一篇：