1. Nginx UI 项目概述与核心设计理念1.1 项目定位与诞生背景Nginx 的安装和基础配置并不难真正让人头疼的是后面那些繁琐的维护操作改一个反向代理要去翻 conf 文件加一个静态站点要计算 location 正则申请 SSL 证书要在服务器上敲一堆命令行搞完之后还要记得nginx -t检查语法再 reload。一旦服务器上跑的站点多了配置文件就是一团乱麻每改一处都心惊胆战生怕手一抖把整个服务搞挂。我自己管理着几台线上服务器高峰期跑了十几个站点和 API 服务对这个痛点深有体会。直到我遇到 xJacky 开源的这个 Nginx UI 项目它把 Nginx 从命令行工具真正变成了可视化服务。Nginx UI 是一个基于 Web 的 Nginx 图形化管理平台后端用 Go 编写前端用 Vue 构建整体打包后只需要运行一个二进制文件服务器上不需要额外安装 MySQL、Redis 这些依赖部署成本极低。它最核心的价值在于把/etc/nginx/conf.d/下那些零散的配置文件变成了浏览器里一张张清晰明了的表单和按钮点一点鼠标就能完成站点的创建、启停、修改、证书配置。这个项目适合三类人第一类是刚入门 Nginx、对命令行不太熟悉的新手可以通过图形界面直观理解 Nginx 的核心概念第二类是负责多台服务器的运维工程师用它统一管理配置、快速排查问题第三类是自己折腾 VPS 的个人开发者部署一次之后能省下大量重复劳动。我第一次用它的感受是原来通过图形界面配置 Nginx 也可以这么顺手而且它在保留 Web 界面便捷性的同时并没有架空底层配置本身——所有操作最终还是会落到实际的 conf 文件上你随时可以回到命令行去看、去改本质上它就像一个配置生成器 状态监视器 证书管理器三合一的工具。1.2 核心功能架构一览从功能模块来看Nginx UI 做的事情可以分成五个维度配置管理支持图形化创建和编辑 Nginx 站点配置提供可视化表单同时保留原始配置文件的直接编辑能力两套模式可以随时切换。状态监控内置服务器基础指标监控面板可以查看 CPU、内存、网络流量、Nginx 连接数和请求数等实时数据不用再单独装 netdata 之类的工具。证书管理集成 Lets Encrypt 免费证书的申请与自动续期功能也支持上传自定义证书到期前会自动提醒甚至自动续签。系统管理多用户体系、用户权限控制、操作日志审计、自定义 Nginx 二进制路径等。在线终端浏览器内嵌终端工具可以直接在页面上执行命令行操作不需要额外开 SSH。这五个模块合在一起几乎覆盖了一个 Nginx 运维场景下 80% 的高频操作。下面从我的实际使用经验出发逐个拆解这些功能的特点和隐藏细节。2. 六大核心特点深度拆解2.1 图形化配置把 conf 变成可视化表单Nginx UI 的主打功能就是简化配置。打开站点的编辑页面你会看到它不是把 conf 原样丢给你而是把配置项拆成了结构化的表单域名、监听端口、根目录、索引文件、反向代理地址、缓存策略、SSL 证书下拉选择框、强制 HTTPS 跳转开关……这种设计最直接的好处是你再也不需要背 Nginx 的配置语法了。以前新建一个 Vue 项目的静态站点我得写这样的配置server { listen 80; server_name example.com; root /var/www/example; index index.html; location / { try_files $uri $uri/ /index.html; } }这个配置本身不复杂但如果要加 HTTPS、加 Gzip、加静态资源缓存配置就会越堆越长一旦写错一个分号或括号nginx -t就会报错新手常常被各种语法错误折磨到怀疑人生。在 Nginx UI 里新建站点时只需要填几个表单字段它会自动帮你生成标准的 server 块。更重要的是它对编辑结果有实时校验机制——每次保存前都会自动执行nginx -t来检查语法有错误会直接提示在界面上而不是等 reload 之后才发现线上服务挂了。我用它创建过几个 WordPress 站点和一个 Node.js API 的反向代理整个过程真的就像填表一样流畅。它生成的配置层次分明注释也清楚事后回到命令行里看文件完全能看懂它做了什么不会出现那种工具生成的天书配置文件的问题。不过要注意一点图形化表单覆盖的是常规场景像自定义if语句块、复杂的 rewrite 规则、stream 模块配置这些表单里不一定有对应的字段。这种情况下直接切到高级模式手工编辑反而更快。所以我的建议是——用它管理常规配置用它辅助排查问题但在遇到特殊需求时不要死磕表单该上编辑器就上编辑器。2.2 在线编辑与实时校验双模式加成Nginx UI 并没有因为做了图形界面就抛弃传统的文件编辑方式。在站点编辑页面里有两个标签页一个是表单/图形化模式一个是配置文件模式。配置文件模式内置了一套带语法高亮的文本编辑器代码补全和错误标记都能用。你可以在里面直接写原生 Nginx 配置保存的时候它会做两件事先检查语法再重载配置。如果语法有问题它会明确告诉你错误出现在哪一行、大概是哪类错误而不是像命令行那样只丢给你一行含糊的emerg日志。这个设计我觉得是这个项目最聪明的地方它承认图形化表单有边界总有高手需要直接手写 conf所以它保留了完整的原生编辑能力同时把校验-重载-回滚这套流程自动化了。我自己的使用习惯是这样的小站点、常规反向代理我用表单生成涉及 rewrite 规则、upstream 权重调整、复杂 location 嵌套的时候我直接切到编辑器写。有了实时校验在背后撑腰手写配置时的心理压力小了很多反正保存之前它会告诉我错没错。2.3 状态监控与流量统计Nginx 自带的stub_status模块可以输出连接数等基础指标但输出格式比较简陋需要你在终端里定期 curl 来看没有历史趋势更不可能做成图表。而 Nginx UI 内置的监控面板把这个问题解决了。它的监控页面展示的信息包括服务器基本状态CPU 使用率、内存占用、磁盘空间、系统负载、运行时间Nginx 运行状态活跃连接数、接受连接总数、处理请求总数、Reading/Writing/Waiting 连接数实时图表按时间维度绘制 CPU 和内存趋势曲线面板的数据刷新是有延迟的大概 3~5 秒一次对于日常运维足够用了。想看实时吞吐的话可以在页面上直接点刷新按钮强制拉取最新数据。我特别推荐在排查问题的场景里用它比如怀疑某个站点访问变慢是不是 Nginx 连接数打满了打开监控面板看一眼活跃连接数和 Reading 状态的趋势再对照站点日志去定位比之前到处敲ss、top、curl status组合命令要直观得多。需要提醒的是Nginx UI 的监控数据默认只存在内存里进程重启后历史数据就没了。如果你需要长时间的监控报表建议搭配 Prometheus Grafana 这类专用监控栈Nginx UI 的目标是让你看得见问题而不是记录一切历史。2.4 SSL 证书管理自动化告别 Lets Encrypt 手动续期证书管理是 Nginx 场景里最麻烦的环节之一尤其是 Lets Encrypt 证书 90 天有效期意味着一年要手动续期四回。我见过太多人因为忘记续期早上上班发现所有 https 站点全部证书过期那种事故是纯粹的运维灾难。Nginx UI 在证书管理模块里做了两件事一是流程自动化二是集中管理。自动化部分它内置了 Lets Encrypt 协议的客户端逻辑你只需要在站点配置里选择启用 HTTPS填上邮箱和一些基础参数它会自动完成证书申请、私钥生成、Nginx 配置更新这一整套动作。到期前还能设置自动续期快到期的证书它会提前处理续签你只需要确保域名正确解析到服务器上、80/443 端口能正常访问验证就行。集中管理部分所有证书在一个页面上列出状态一目了然签发时间、到期时间、关联的站点、续期记录。纸质证书文件分散在磁盘各个目录的问题从此解决。我在真实服务器上用它申请过两个域名的证书整个流程跑通只需要几分钟。它注册 ACME 账号、签发证书、写入配置的衔接做得比较稳没有出现那种证书申请成功但 Nginx 没生效的脱节问题。不过有一点经验要分享如果你的服务器在国内、解析用的是 CDN第一次申请证书时大概率会因为验证请求超时而失败这种情况先把 CDN 的回源模式改成直接回源或者临时关闭 CDN等证书签下来之后再恢复。另外付费证书、企业内部证书这类不便走 ACME 流程的场景它支持直接上传证书文件和私钥操作也很干脆。2.5 多用户体系与细粒度权限控制Nginx UI 不是单用户工具它内置了一套用户权限系统。管理员可以创建多个用户并为每个用户设置不同的权限级别。角色分成管理员和普通用户。管理员拥有全部权限可以管理用户、修改系统设置、查看日志普通用户默认只能看到自己被授权的站点和功能。这种设计对于团队协作场景很有价值——开发团队里每个人负责不同的项目给每个人开一个账号只赋予他自己站点的管理权限其他人碰不到你的配置文件。实际操作中如果你只是在自己一台 VPS 上自用创建管理员账号就够了不用管这些。但如果你打算把它部署在公司的跳板机上供多人使用我建议提前规划好用户权限矩阵避免所有人都是管理员谁都能动 Nginx 全局配置那还不如不搞这套系统直接给 root 权限拉倒。另外要说明一点Nginx UI 的用户体系和 Linux 系统用户是两套东西。Nginx UI 的登录账号只用来登录 Web 界面最终执行 Nginx 命令的还是后端进程的系统身份。部署时建议让 Nginx UI 进程以 root 之外的专门用户运行同时配置好 sudo 提权规则这块内容我在第 4 部分详细演示。2.6 在线终端与暗色主题等体验细节除开上面这些硬功能Nginx UI 还有几个值得说的体验细节。在线终端是一个 Web 版的终端模拟器底层走 WebSocket 通道打开之后就是服务器上的 shell。遇到临时要改个文件权限、查看一下进程状态这种小操作就不用再另开一个 SSH 窗口了。它支持常见的终端操作Vim 之类的全屏交互程序也能正常用我实测过在在线终端里操作 fzf 也没问题。安全性上它跟 Nginx UI 的登录会话绑定你要是退出登录终端连接也会断开。UI 层面支持浅色/深色主题切换深色模式对长期盯监控面板的人很友好。界面默认就是中文对国内用户很友好不用自己折腾汉化。还有一个小细节站点列表上可以直接看到每个站点的启用状态、SSL 状态、关联的 upstream 地址整个仪表盘的信息密度比较高扫一眼就知道整套服务器上有哪些站点、谁在跑、谁挂了。3. 部署实操从编译到跑起来3.1 环境准备与前置条件在开始部署之前先确认服务器满足这几个条件Linux 发行版不限Debian/Ubuntu/CentOS/OpenEuler 都可以。macOS 也能编译运行但生产环境建议还是 Linux。目标机器上已经安装好了 Nginx 本体。Nginx UI 本身不携带 Nginx 程序它只是管理 Nginx 的一个前端面板。没有 Nginx 的话后面所有配置操作都是空中楼阁。服务器能解析到你的管理域名或者你打算直接用 IP端口访问。建议用域名 HTTPS 的方式访问 Nginx UI 管理后台否则账号密码在网络上裸奔风险太大。如果要申请 Lets Encrypt 证书需要保证 80 和 443 端口都能被外网正常访问。我建议的服务器配置不低于 1 核 1G部署完 Nginx 本体和 Nginx UI 之后内存占用大概在 200~300MB 左右非常轻量。如果你还要在同一台机器上跑数据库和业务应用那根据实际情况调整配置即可。3.2 编译安装与前端构建Nginx UI 提供了两种安装方式直接下载 Release 二进制包或者从源码编译。对于大多数人来说直接下载 Release 包是最省事的。它的 GitHub Release 页面会为不同架构提供预编译好的二进制包比如 amd64、arm64 都有。下载下来的是一个压缩包解压之后里面有 nginx-ui 可执行文件和 app.ini 配置文件模版之后直接按第 3.3 节的方法初始化运行即可。如果你对时效性有要求、想体验最新代码或者需要改一些交互逻辑再考虑源码编译。编译环境需要 Go 1.21 以上和 Node.js 16 以上的版本。以 Debian 系系统为例先装基础工具链apt update apt install -y git build-essential然后把项目克隆到本地并进入目录git clone https://github.com/xJacky/nginx-ui.git cd nginx-ui前端和后端是分开构建的。先处理前端资源它默认基于 Vite 打包我这里用 pnpm你也可以用 npm效果一样# 安装前端依赖 npm install -g pnpm pnpm install # 构建前端静态资源默认输出到 dist 目录 pnpm build构建完之后前端静态资源会生成在项目根目录下的dist文件夹里。接下来处理后端后端是一个 Go 项目构建的时候需要把前端产物嵌入到二进制包里这样最后只需要分发一个文件就能跑整个服务。这个嵌入逻辑走的是 Go 的 embed 机制构建脚本里已经处理好了。# 生成嵌入前端的静态文件包 go generate ./... # 编译后端主程序 go build -o nginx-ui main.go编译完成后项目目录下会多出一个 nginx-ui 二进制文件。把dist目录、app.ini、nginx-ui文件放到同一个目录下这样一个绿色版部署包就做好了。传到服务器上任意目录这台机器就算有了管理面板的程序体。这里有一个容易踩的坑如果你只执行go build而没有执行go generate或者前端pnpm build之后直接编译那打出来的二进制里可能没有前端页面。运行之后访问 Web 界面会白屏只有接口数据没有页面元素。我的经验是严格按上面顺序操作前三步缺一不可构建完成后检查一下二进制包的大小——如果正常嵌入了前端资源包体至少在 50MB 以上如果只有十几 MB那基本可以断定前端资源没打进去。3.3 初始化配置与 systemd 托管拿到二进制文件后在放置 nginx-ui 文件的目录下执行./nginx-ui第一次启动时它会自动生成一个默认的app.ini配置文件并且会提示你设置管理员账号。之后在浏览器里访问http://你的服务器IP:9000用刚才设置的管理员账号登录。配置文件app.ini里最核心的几个参数如下[Server] # 面板监听端口默认 9000可以改成内网专用端口 HttpPort 9000 [Database] # 默认使用 SQLite 单文件数据库路径相对于程序目录 Path ./nginx-ui.db [Nginx] # 这里是指向系统 Nginx 可执行文件的绝对路径 NginxBinPath /usr/sbin/nginx # Nginx 配置目录路径 NginxConfigDir /etc/nginx建议把面板监听端口改成一个不太显眼的端口比如 9118然后通过 Nginx 反向代理到子路径再用 you-get 之类的方式管理访问。我实际部署时的做法是Nginx 80 端口做一个专门的反向代理到 127.0.0.1:9118再配一层 HTTPS这样管理入口变得比较干净而且不会和其他站点抢端口。把服务托管给 systemd 实现开机自启这里给一份我常用的 unit 文件[Unit] DescriptionNginx UI Afternetwork.target nginx.service [Service] Typesimple WorkingDirectory/opt/nginx-ui ExecStart/opt/nginx-ui/nginx-ui Restarton-failure RestartSec5s [Install] WantedBymulti-user.target保存到/etc/systemd/system/nginx-ui.service然后执行systemctl daemon-reload systemctl enable --now nginx-ui systemctl status nginx-ui看到active (running)就说明部署成功了。注意 WorkingDirectory 一定要指向你放置 nginx-ui 和 app.ini 的目录否则程序可能找不到数据库文件又会生成一个新的实例两个实例同时跑就会出现端口冲突、数据文件错乱的问题。4. 进阶玩法与实际站点配置4.1 使用 Nginx UI 配置反向代理与静态站点部署好 Nginx UI 之后最常用的操作就是创建站点。我以反向代理为例完整走一遍流程。打开左侧菜单站点管理点击新建站点填写以下关键信息域名填写你要对外提供服务的域名例如api.example.com监听端口默认 80同时勾选 443前提是证书已配置好类型选择反向代理目标地址填写后端服务的实际地址例如http://127.0.0.1:8080保存之后Nginx UI 会生成一段类似下面的配置server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:8080; 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; proxy_read_timeout 60s; } }默认配置下常用头部基本都会帮你带上。但如果你后端服务比较挑例如拿到了真实客户端 IP 才能做限流那记得在高级配置里再补一层 real IP 模块相关的配置这里不展开。静态站点的场景也类似。新建站点时类型选静态站点指定root目录和index文件再勾选启用 HTTPS和自动申请证书基本就是两三分钟的事。对于用 Vue/React 打包出来的单页应用记得在高级配置里手动补一段location / { try_files $uri $uri/ /index.html; }这种场景在 Nginx UI 的默认模板里不会自动生成需要你在配置文件的编辑器模式下自行加上。第一次创建单页应用站点的时候我因为没有加这段规则刷新页面后全部 404排查了半天才反应过来。4.2 站点启停、日志查看与备份恢复Nginx UI 的站点列表里每个站点都有一个启用/停用开关。实际操作上停用站点不是粗暴地删掉配置文件而是在 conf.d 对应的文件名上做调整并 reload例如把example.conf重命名成example.conf.bak。这个逻辑很安全想恢复服务只需要再点一次启用作弊即可不会再出现误删配置导致整站宕机的低级事故。日志查看方面Nginx UI 没有做复杂的日志检索它把错误日志和访问日志文件路径展示在站点详情页里点击就能跳到在线终端配合 tail 命令实时跟踪。如果你需要类似 GoAccess 那样可视化的日志分析报表它不会帮你生成需要自己另搭方案。再说备份恢复。因为核心数据就两个一个是nginx-ui.dbSQLite 数据库负责保存站点配置元数据另一个是/etc/nginx/下实际的 conf 文件。所以备份策略非常简单# 备份数据库 cp /opt/nginx-ui/nginx-ui.db /backup/nginx-ui-$(date %F).db # 备份 nginx 配置目录 tar czvf /backup/nginx-conf-$(date %F).tar.gz /etc/nginx/恢复时更简单把 db 文件放回原目录、把 conf 文件解压回/etc/nginx/启动 Nginx UI 服务即可。它不会像某些商业化面板那样悄悄改掉你的 conf 文件格式所有配置都是标准的 Nginx 语法这意味着即使某天你不再使用 Nginx UI历史配置也完全可迁移、可维护不存在被绑定在一套私有配置格式上的问题。这一点我觉得是开源运维工具该有的操守——工具是帮你生成标准配置而不是创造一套只有它能读懂的黑话格式。5. 常见问题排查与避坑指南5.1 部署与配置常见问题速查问题现象可能原因处理办法访问管理界面白屏前端资源未嵌入二进制按 3.2 节顺序重新构建检查二进制体积是否大于 50MB新建站点后网站 404缺少 try_files 规则静态站点场景补 try_files 指令单页应用补 index.html 回退证书申请失败域名解析到 CDN 或未开放 80/443 端口临时关闭 CDN 回源或检查安全组入站规则保存配置后 Nginx 未生效PHP 文件权限问题、reload 权限不足查看 /var/log/nginx/error.log确认运行用户对 conf 目录有写权限两个面板实例同时运行WorkingDirectory 配置错误systemd 里指定正确的目录避免生成第二份 db 文件在线终端连接断开服务端 WebSocket 超时检查代理层超时配置设置 proxy_read_timeout 180s5.2 实操心得与避坑经验第一个坑是安全问题。Nginx UI 默认没有任何访问 IP 限制一旦开了公网端口任何人都能打开你的登录页。虽然它有登录密码保护但暴力破解的风险总归存在。我的处理方式是把监听地址从 0.0.0.0 改成 127.0.0.1然后借助 Nginx 本体的反向代理去暴露面板再配合 basic auth 做一层额外校验。改监听地址只需要把app.ini里的HttpHost从默认值 0.0.0.0 改成 127.0.0.1 就行实际这样配置之后面板只能从本机访问从外网访问需要走 Nginx 代理。第二个坑是权限问题。Nginx UI 进程默认用自己的运行用户去执行nginx -t和 reload。如果 Nginx 主进程的配置目录权限比较苛刻比如目录属主是 root 而且没给其他用户写权限那 Nginx UI 执行 reload 就会失败。解决方法是把 Nginx UI 的运行用户加入 Nginx 同组或者给NginxConfigDir设置 755 权限再不行就通过 sudoers 单独授权 nginx-ui 用户执行 reload 命令。这块不要图省事直接让 Nginx UI 跑在 root 下面板这类带 Web 入口的程序一旦被攻破root shell 落到别人手里就不是小事了。第三个坑是配置文件的路径锚定。Nginx UI 在生成站点配置时会把include目录告诉 Nginx默认是/etc/nginx/conf.d/。如果你系统和默认路径不一致比如某些定制发行版把配置放在/usr/local/etc/nginx/记得先在app.ini里把路径指对否则你新建的站点会写到 Nginx 根本不读取的目录站点建好了但就是不出效果。第四个经验是关于流量报表的认知。Nginx UI 的状态监控更多是给当下看的不是给趋势分析用的。真正需要月级、季度级流量报表的场景我建议从/etc/nginx/conf.d/里把 access_log 单独指到独立文件再用 Filebeat 或 Promtail 采集到日志搜索平台。这个思路能帮你把 Nginx UI 的轻量监控和重量级日志体系分开各司其职。5.3 与现有运维体系无缝共存最后聊一下 Nginx UI 怎么跟现有运维体系共存的。很多人在引入可视化面板时最担心的就是它会不会把原来的配置文件打乱、搞出外人看不懂的东西我实测下来Nginx UI 的并发协议设计得比较克制。它生成的文件格式非常标准而且你原有手写的 conf 文件它不会主动去动面板只会管理它自己创建的站点。如果你在命令行里手动修改了一个站点的 conf 文件回到面板刷新后它会把新内容读取回来同步显示不会强制覆盖。但反过来如果你在面板里编辑保存了同一个文件那命令行里的旧改动自然就被覆盖掉了。这个以最后一次保存为准的逻辑也提醒了团队协作时要注意同一个时段不要同时用面板和命令行去改同一个配置文件容易互相覆盖。我现在的工作流是常规操作走 Nginx UI特殊需求走命令行两边始终保持同步。既不用为了跑一个站点去背几十条 Nginx 指令也没有被图形界面限制住手脚。对我自己来说这个工具把日常运维里最琐碎的那部分工作稳稳地接住了。最后再补充一个小技巧Nginx UI 的管理界面支持直接绑定自己的域名并自动申请证书这样你访问面板本身也是 HTTPS 的登录凭证不会在网络上明文传输。我自己的管理域名是nginx.example.com在面板设置里填好域名之后它就直接完成了证书签发后续浏览器打开自动就是绿色小锁省心不少。在最后我把这个项目值得一试的理由总结成一句大白话如果你每天都在跟 Nginx 配置文件打交道又希望少背点命令、多留点精力干正事那开源的 Nginx UI 是现阶段很值得部署的一套方案。它可能不是银弹但绝对能让你从命令行炼丹里解脱出来大半。搞一台测试服务器按照上面的步骤部署一遍相信你会很快感受到它的好处。
Nginx UI 可视化配置与运维实战：从图形化管理到证书自动化
1. Nginx UI 项目概述与核心设计理念1.1 项目定位与诞生背景Nginx 的安装和基础配置并不难真正让人头疼的是后面那些繁琐的维护操作改一个反向代理要去翻 conf 文件加一个静态站点要计算 location 正则申请 SSL 证书要在服务器上敲一堆命令行搞完之后还要记得nginx -t检查语法再 reload。一旦服务器上跑的站点多了配置文件就是一团乱麻每改一处都心惊胆战生怕手一抖把整个服务搞挂。我自己管理着几台线上服务器高峰期跑了十几个站点和 API 服务对这个痛点深有体会。直到我遇到 xJacky 开源的这个 Nginx UI 项目它把 Nginx 从命令行工具真正变成了可视化服务。Nginx UI 是一个基于 Web 的 Nginx 图形化管理平台后端用 Go 编写前端用 Vue 构建整体打包后只需要运行一个二进制文件服务器上不需要额外安装 MySQL、Redis 这些依赖部署成本极低。它最核心的价值在于把/etc/nginx/conf.d/下那些零散的配置文件变成了浏览器里一张张清晰明了的表单和按钮点一点鼠标就能完成站点的创建、启停、修改、证书配置。这个项目适合三类人第一类是刚入门 Nginx、对命令行不太熟悉的新手可以通过图形界面直观理解 Nginx 的核心概念第二类是负责多台服务器的运维工程师用它统一管理配置、快速排查问题第三类是自己折腾 VPS 的个人开发者部署一次之后能省下大量重复劳动。我第一次用它的感受是原来通过图形界面配置 Nginx 也可以这么顺手而且它在保留 Web 界面便捷性的同时并没有架空底层配置本身——所有操作最终还是会落到实际的 conf 文件上你随时可以回到命令行去看、去改本质上它就像一个配置生成器 状态监视器 证书管理器三合一的工具。1.2 核心功能架构一览从功能模块来看Nginx UI 做的事情可以分成五个维度配置管理支持图形化创建和编辑 Nginx 站点配置提供可视化表单同时保留原始配置文件的直接编辑能力两套模式可以随时切换。状态监控内置服务器基础指标监控面板可以查看 CPU、内存、网络流量、Nginx 连接数和请求数等实时数据不用再单独装 netdata 之类的工具。证书管理集成 Lets Encrypt 免费证书的申请与自动续期功能也支持上传自定义证书到期前会自动提醒甚至自动续签。系统管理多用户体系、用户权限控制、操作日志审计、自定义 Nginx 二进制路径等。在线终端浏览器内嵌终端工具可以直接在页面上执行命令行操作不需要额外开 SSH。这五个模块合在一起几乎覆盖了一个 Nginx 运维场景下 80% 的高频操作。下面从我的实际使用经验出发逐个拆解这些功能的特点和隐藏细节。2. 六大核心特点深度拆解2.1 图形化配置把 conf 变成可视化表单Nginx UI 的主打功能就是简化配置。打开站点的编辑页面你会看到它不是把 conf 原样丢给你而是把配置项拆成了结构化的表单域名、监听端口、根目录、索引文件、反向代理地址、缓存策略、SSL 证书下拉选择框、强制 HTTPS 跳转开关……这种设计最直接的好处是你再也不需要背 Nginx 的配置语法了。以前新建一个 Vue 项目的静态站点我得写这样的配置server { listen 80; server_name example.com; root /var/www/example; index index.html; location / { try_files $uri $uri/ /index.html; } }这个配置本身不复杂但如果要加 HTTPS、加 Gzip、加静态资源缓存配置就会越堆越长一旦写错一个分号或括号nginx -t就会报错新手常常被各种语法错误折磨到怀疑人生。在 Nginx UI 里新建站点时只需要填几个表单字段它会自动帮你生成标准的 server 块。更重要的是它对编辑结果有实时校验机制——每次保存前都会自动执行nginx -t来检查语法有错误会直接提示在界面上而不是等 reload 之后才发现线上服务挂了。我用它创建过几个 WordPress 站点和一个 Node.js API 的反向代理整个过程真的就像填表一样流畅。它生成的配置层次分明注释也清楚事后回到命令行里看文件完全能看懂它做了什么不会出现那种工具生成的天书配置文件的问题。不过要注意一点图形化表单覆盖的是常规场景像自定义if语句块、复杂的 rewrite 规则、stream 模块配置这些表单里不一定有对应的字段。这种情况下直接切到高级模式手工编辑反而更快。所以我的建议是——用它管理常规配置用它辅助排查问题但在遇到特殊需求时不要死磕表单该上编辑器就上编辑器。2.2 在线编辑与实时校验双模式加成Nginx UI 并没有因为做了图形界面就抛弃传统的文件编辑方式。在站点编辑页面里有两个标签页一个是表单/图形化模式一个是配置文件模式。配置文件模式内置了一套带语法高亮的文本编辑器代码补全和错误标记都能用。你可以在里面直接写原生 Nginx 配置保存的时候它会做两件事先检查语法再重载配置。如果语法有问题它会明确告诉你错误出现在哪一行、大概是哪类错误而不是像命令行那样只丢给你一行含糊的emerg日志。这个设计我觉得是这个项目最聪明的地方它承认图形化表单有边界总有高手需要直接手写 conf所以它保留了完整的原生编辑能力同时把校验-重载-回滚这套流程自动化了。我自己的使用习惯是这样的小站点、常规反向代理我用表单生成涉及 rewrite 规则、upstream 权重调整、复杂 location 嵌套的时候我直接切到编辑器写。有了实时校验在背后撑腰手写配置时的心理压力小了很多反正保存之前它会告诉我错没错。2.3 状态监控与流量统计Nginx 自带的stub_status模块可以输出连接数等基础指标但输出格式比较简陋需要你在终端里定期 curl 来看没有历史趋势更不可能做成图表。而 Nginx UI 内置的监控面板把这个问题解决了。它的监控页面展示的信息包括服务器基本状态CPU 使用率、内存占用、磁盘空间、系统负载、运行时间Nginx 运行状态活跃连接数、接受连接总数、处理请求总数、Reading/Writing/Waiting 连接数实时图表按时间维度绘制 CPU 和内存趋势曲线面板的数据刷新是有延迟的大概 3~5 秒一次对于日常运维足够用了。想看实时吞吐的话可以在页面上直接点刷新按钮强制拉取最新数据。我特别推荐在排查问题的场景里用它比如怀疑某个站点访问变慢是不是 Nginx 连接数打满了打开监控面板看一眼活跃连接数和 Reading 状态的趋势再对照站点日志去定位比之前到处敲ss、top、curl status组合命令要直观得多。需要提醒的是Nginx UI 的监控数据默认只存在内存里进程重启后历史数据就没了。如果你需要长时间的监控报表建议搭配 Prometheus Grafana 这类专用监控栈Nginx UI 的目标是让你看得见问题而不是记录一切历史。2.4 SSL 证书管理自动化告别 Lets Encrypt 手动续期证书管理是 Nginx 场景里最麻烦的环节之一尤其是 Lets Encrypt 证书 90 天有效期意味着一年要手动续期四回。我见过太多人因为忘记续期早上上班发现所有 https 站点全部证书过期那种事故是纯粹的运维灾难。Nginx UI 在证书管理模块里做了两件事一是流程自动化二是集中管理。自动化部分它内置了 Lets Encrypt 协议的客户端逻辑你只需要在站点配置里选择启用 HTTPS填上邮箱和一些基础参数它会自动完成证书申请、私钥生成、Nginx 配置更新这一整套动作。到期前还能设置自动续期快到期的证书它会提前处理续签你只需要确保域名正确解析到服务器上、80/443 端口能正常访问验证就行。集中管理部分所有证书在一个页面上列出状态一目了然签发时间、到期时间、关联的站点、续期记录。纸质证书文件分散在磁盘各个目录的问题从此解决。我在真实服务器上用它申请过两个域名的证书整个流程跑通只需要几分钟。它注册 ACME 账号、签发证书、写入配置的衔接做得比较稳没有出现那种证书申请成功但 Nginx 没生效的脱节问题。不过有一点经验要分享如果你的服务器在国内、解析用的是 CDN第一次申请证书时大概率会因为验证请求超时而失败这种情况先把 CDN 的回源模式改成直接回源或者临时关闭 CDN等证书签下来之后再恢复。另外付费证书、企业内部证书这类不便走 ACME 流程的场景它支持直接上传证书文件和私钥操作也很干脆。2.5 多用户体系与细粒度权限控制Nginx UI 不是单用户工具它内置了一套用户权限系统。管理员可以创建多个用户并为每个用户设置不同的权限级别。角色分成管理员和普通用户。管理员拥有全部权限可以管理用户、修改系统设置、查看日志普通用户默认只能看到自己被授权的站点和功能。这种设计对于团队协作场景很有价值——开发团队里每个人负责不同的项目给每个人开一个账号只赋予他自己站点的管理权限其他人碰不到你的配置文件。实际操作中如果你只是在自己一台 VPS 上自用创建管理员账号就够了不用管这些。但如果你打算把它部署在公司的跳板机上供多人使用我建议提前规划好用户权限矩阵避免所有人都是管理员谁都能动 Nginx 全局配置那还不如不搞这套系统直接给 root 权限拉倒。另外要说明一点Nginx UI 的用户体系和 Linux 系统用户是两套东西。Nginx UI 的登录账号只用来登录 Web 界面最终执行 Nginx 命令的还是后端进程的系统身份。部署时建议让 Nginx UI 进程以 root 之外的专门用户运行同时配置好 sudo 提权规则这块内容我在第 4 部分详细演示。2.6 在线终端与暗色主题等体验细节除开上面这些硬功能Nginx UI 还有几个值得说的体验细节。在线终端是一个 Web 版的终端模拟器底层走 WebSocket 通道打开之后就是服务器上的 shell。遇到临时要改个文件权限、查看一下进程状态这种小操作就不用再另开一个 SSH 窗口了。它支持常见的终端操作Vim 之类的全屏交互程序也能正常用我实测过在在线终端里操作 fzf 也没问题。安全性上它跟 Nginx UI 的登录会话绑定你要是退出登录终端连接也会断开。UI 层面支持浅色/深色主题切换深色模式对长期盯监控面板的人很友好。界面默认就是中文对国内用户很友好不用自己折腾汉化。还有一个小细节站点列表上可以直接看到每个站点的启用状态、SSL 状态、关联的 upstream 地址整个仪表盘的信息密度比较高扫一眼就知道整套服务器上有哪些站点、谁在跑、谁挂了。3. 部署实操从编译到跑起来3.1 环境准备与前置条件在开始部署之前先确认服务器满足这几个条件Linux 发行版不限Debian/Ubuntu/CentOS/OpenEuler 都可以。macOS 也能编译运行但生产环境建议还是 Linux。目标机器上已经安装好了 Nginx 本体。Nginx UI 本身不携带 Nginx 程序它只是管理 Nginx 的一个前端面板。没有 Nginx 的话后面所有配置操作都是空中楼阁。服务器能解析到你的管理域名或者你打算直接用 IP端口访问。建议用域名 HTTPS 的方式访问 Nginx UI 管理后台否则账号密码在网络上裸奔风险太大。如果要申请 Lets Encrypt 证书需要保证 80 和 443 端口都能被外网正常访问。我建议的服务器配置不低于 1 核 1G部署完 Nginx 本体和 Nginx UI 之后内存占用大概在 200~300MB 左右非常轻量。如果你还要在同一台机器上跑数据库和业务应用那根据实际情况调整配置即可。3.2 编译安装与前端构建Nginx UI 提供了两种安装方式直接下载 Release 二进制包或者从源码编译。对于大多数人来说直接下载 Release 包是最省事的。它的 GitHub Release 页面会为不同架构提供预编译好的二进制包比如 amd64、arm64 都有。下载下来的是一个压缩包解压之后里面有 nginx-ui 可执行文件和 app.ini 配置文件模版之后直接按第 3.3 节的方法初始化运行即可。如果你对时效性有要求、想体验最新代码或者需要改一些交互逻辑再考虑源码编译。编译环境需要 Go 1.21 以上和 Node.js 16 以上的版本。以 Debian 系系统为例先装基础工具链apt update apt install -y git build-essential然后把项目克隆到本地并进入目录git clone https://github.com/xJacky/nginx-ui.git cd nginx-ui前端和后端是分开构建的。先处理前端资源它默认基于 Vite 打包我这里用 pnpm你也可以用 npm效果一样# 安装前端依赖 npm install -g pnpm pnpm install # 构建前端静态资源默认输出到 dist 目录 pnpm build构建完之后前端静态资源会生成在项目根目录下的dist文件夹里。接下来处理后端后端是一个 Go 项目构建的时候需要把前端产物嵌入到二进制包里这样最后只需要分发一个文件就能跑整个服务。这个嵌入逻辑走的是 Go 的 embed 机制构建脚本里已经处理好了。# 生成嵌入前端的静态文件包 go generate ./... # 编译后端主程序 go build -o nginx-ui main.go编译完成后项目目录下会多出一个 nginx-ui 二进制文件。把dist目录、app.ini、nginx-ui文件放到同一个目录下这样一个绿色版部署包就做好了。传到服务器上任意目录这台机器就算有了管理面板的程序体。这里有一个容易踩的坑如果你只执行go build而没有执行go generate或者前端pnpm build之后直接编译那打出来的二进制里可能没有前端页面。运行之后访问 Web 界面会白屏只有接口数据没有页面元素。我的经验是严格按上面顺序操作前三步缺一不可构建完成后检查一下二进制包的大小——如果正常嵌入了前端资源包体至少在 50MB 以上如果只有十几 MB那基本可以断定前端资源没打进去。3.3 初始化配置与 systemd 托管拿到二进制文件后在放置 nginx-ui 文件的目录下执行./nginx-ui第一次启动时它会自动生成一个默认的app.ini配置文件并且会提示你设置管理员账号。之后在浏览器里访问http://你的服务器IP:9000用刚才设置的管理员账号登录。配置文件app.ini里最核心的几个参数如下[Server] # 面板监听端口默认 9000可以改成内网专用端口 HttpPort 9000 [Database] # 默认使用 SQLite 单文件数据库路径相对于程序目录 Path ./nginx-ui.db [Nginx] # 这里是指向系统 Nginx 可执行文件的绝对路径 NginxBinPath /usr/sbin/nginx # Nginx 配置目录路径 NginxConfigDir /etc/nginx建议把面板监听端口改成一个不太显眼的端口比如 9118然后通过 Nginx 反向代理到子路径再用 you-get 之类的方式管理访问。我实际部署时的做法是Nginx 80 端口做一个专门的反向代理到 127.0.0.1:9118再配一层 HTTPS这样管理入口变得比较干净而且不会和其他站点抢端口。把服务托管给 systemd 实现开机自启这里给一份我常用的 unit 文件[Unit] DescriptionNginx UI Afternetwork.target nginx.service [Service] Typesimple WorkingDirectory/opt/nginx-ui ExecStart/opt/nginx-ui/nginx-ui Restarton-failure RestartSec5s [Install] WantedBymulti-user.target保存到/etc/systemd/system/nginx-ui.service然后执行systemctl daemon-reload systemctl enable --now nginx-ui systemctl status nginx-ui看到active (running)就说明部署成功了。注意 WorkingDirectory 一定要指向你放置 nginx-ui 和 app.ini 的目录否则程序可能找不到数据库文件又会生成一个新的实例两个实例同时跑就会出现端口冲突、数据文件错乱的问题。4. 进阶玩法与实际站点配置4.1 使用 Nginx UI 配置反向代理与静态站点部署好 Nginx UI 之后最常用的操作就是创建站点。我以反向代理为例完整走一遍流程。打开左侧菜单站点管理点击新建站点填写以下关键信息域名填写你要对外提供服务的域名例如api.example.com监听端口默认 80同时勾选 443前提是证书已配置好类型选择反向代理目标地址填写后端服务的实际地址例如http://127.0.0.1:8080保存之后Nginx UI 会生成一段类似下面的配置server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:8080; 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; proxy_read_timeout 60s; } }默认配置下常用头部基本都会帮你带上。但如果你后端服务比较挑例如拿到了真实客户端 IP 才能做限流那记得在高级配置里再补一层 real IP 模块相关的配置这里不展开。静态站点的场景也类似。新建站点时类型选静态站点指定root目录和index文件再勾选启用 HTTPS和自动申请证书基本就是两三分钟的事。对于用 Vue/React 打包出来的单页应用记得在高级配置里手动补一段location / { try_files $uri $uri/ /index.html; }这种场景在 Nginx UI 的默认模板里不会自动生成需要你在配置文件的编辑器模式下自行加上。第一次创建单页应用站点的时候我因为没有加这段规则刷新页面后全部 404排查了半天才反应过来。4.2 站点启停、日志查看与备份恢复Nginx UI 的站点列表里每个站点都有一个启用/停用开关。实际操作上停用站点不是粗暴地删掉配置文件而是在 conf.d 对应的文件名上做调整并 reload例如把example.conf重命名成example.conf.bak。这个逻辑很安全想恢复服务只需要再点一次启用作弊即可不会再出现误删配置导致整站宕机的低级事故。日志查看方面Nginx UI 没有做复杂的日志检索它把错误日志和访问日志文件路径展示在站点详情页里点击就能跳到在线终端配合 tail 命令实时跟踪。如果你需要类似 GoAccess 那样可视化的日志分析报表它不会帮你生成需要自己另搭方案。再说备份恢复。因为核心数据就两个一个是nginx-ui.dbSQLite 数据库负责保存站点配置元数据另一个是/etc/nginx/下实际的 conf 文件。所以备份策略非常简单# 备份数据库 cp /opt/nginx-ui/nginx-ui.db /backup/nginx-ui-$(date %F).db # 备份 nginx 配置目录 tar czvf /backup/nginx-conf-$(date %F).tar.gz /etc/nginx/恢复时更简单把 db 文件放回原目录、把 conf 文件解压回/etc/nginx/启动 Nginx UI 服务即可。它不会像某些商业化面板那样悄悄改掉你的 conf 文件格式所有配置都是标准的 Nginx 语法这意味着即使某天你不再使用 Nginx UI历史配置也完全可迁移、可维护不存在被绑定在一套私有配置格式上的问题。这一点我觉得是开源运维工具该有的操守——工具是帮你生成标准配置而不是创造一套只有它能读懂的黑话格式。5. 常见问题排查与避坑指南5.1 部署与配置常见问题速查问题现象可能原因处理办法访问管理界面白屏前端资源未嵌入二进制按 3.2 节顺序重新构建检查二进制体积是否大于 50MB新建站点后网站 404缺少 try_files 规则静态站点场景补 try_files 指令单页应用补 index.html 回退证书申请失败域名解析到 CDN 或未开放 80/443 端口临时关闭 CDN 回源或检查安全组入站规则保存配置后 Nginx 未生效PHP 文件权限问题、reload 权限不足查看 /var/log/nginx/error.log确认运行用户对 conf 目录有写权限两个面板实例同时运行WorkingDirectory 配置错误systemd 里指定正确的目录避免生成第二份 db 文件在线终端连接断开服务端 WebSocket 超时检查代理层超时配置设置 proxy_read_timeout 180s5.2 实操心得与避坑经验第一个坑是安全问题。Nginx UI 默认没有任何访问 IP 限制一旦开了公网端口任何人都能打开你的登录页。虽然它有登录密码保护但暴力破解的风险总归存在。我的处理方式是把监听地址从 0.0.0.0 改成 127.0.0.1然后借助 Nginx 本体的反向代理去暴露面板再配合 basic auth 做一层额外校验。改监听地址只需要把app.ini里的HttpHost从默认值 0.0.0.0 改成 127.0.0.1 就行实际这样配置之后面板只能从本机访问从外网访问需要走 Nginx 代理。第二个坑是权限问题。Nginx UI 进程默认用自己的运行用户去执行nginx -t和 reload。如果 Nginx 主进程的配置目录权限比较苛刻比如目录属主是 root 而且没给其他用户写权限那 Nginx UI 执行 reload 就会失败。解决方法是把 Nginx UI 的运行用户加入 Nginx 同组或者给NginxConfigDir设置 755 权限再不行就通过 sudoers 单独授权 nginx-ui 用户执行 reload 命令。这块不要图省事直接让 Nginx UI 跑在 root 下面板这类带 Web 入口的程序一旦被攻破root shell 落到别人手里就不是小事了。第三个坑是配置文件的路径锚定。Nginx UI 在生成站点配置时会把include目录告诉 Nginx默认是/etc/nginx/conf.d/。如果你系统和默认路径不一致比如某些定制发行版把配置放在/usr/local/etc/nginx/记得先在app.ini里把路径指对否则你新建的站点会写到 Nginx 根本不读取的目录站点建好了但就是不出效果。第四个经验是关于流量报表的认知。Nginx UI 的状态监控更多是给当下看的不是给趋势分析用的。真正需要月级、季度级流量报表的场景我建议从/etc/nginx/conf.d/里把 access_log 单独指到独立文件再用 Filebeat 或 Promtail 采集到日志搜索平台。这个思路能帮你把 Nginx UI 的轻量监控和重量级日志体系分开各司其职。5.3 与现有运维体系无缝共存最后聊一下 Nginx UI 怎么跟现有运维体系共存的。很多人在引入可视化面板时最担心的就是它会不会把原来的配置文件打乱、搞出外人看不懂的东西我实测下来Nginx UI 的并发协议设计得比较克制。它生成的文件格式非常标准而且你原有手写的 conf 文件它不会主动去动面板只会管理它自己创建的站点。如果你在命令行里手动修改了一个站点的 conf 文件回到面板刷新后它会把新内容读取回来同步显示不会强制覆盖。但反过来如果你在面板里编辑保存了同一个文件那命令行里的旧改动自然就被覆盖掉了。这个以最后一次保存为准的逻辑也提醒了团队协作时要注意同一个时段不要同时用面板和命令行去改同一个配置文件容易互相覆盖。我现在的工作流是常规操作走 Nginx UI特殊需求走命令行两边始终保持同步。既不用为了跑一个站点去背几十条 Nginx 指令也没有被图形界面限制住手脚。对我自己来说这个工具把日常运维里最琐碎的那部分工作稳稳地接住了。最后再补充一个小技巧Nginx UI 的管理界面支持直接绑定自己的域名并自动申请证书这样你访问面板本身也是 HTTPS 的登录凭证不会在网络上明文传输。我自己的管理域名是nginx.example.com在面板设置里填好域名之后它就直接完成了证书签发后续浏览器打开自动就是绿色小锁省心不少。在最后我把这个项目值得一试的理由总结成一句大白话如果你每天都在跟 Nginx 配置文件打交道又希望少背点命令、多留点精力干正事那开源的 Nginx UI 是现阶段很值得部署的一套方案。它可能不是银弹但绝对能让你从命令行炼丹里解脱出来大半。搞一台测试服务器按照上面的步骤部署一遍相信你会很快感受到它的好处。
