NginxUI部署技巧与使用经验

从 0 到 1 的 NginxUI 实战：部署、使用技巧与踩坑经验

作者：hace
日期：2025-08-01

一、为什么需要 NginxUI？

传统 Nginx 配置是“文本 + reload”的范式：

• 改配置 → nginx -t → systemctl reload nginx → 祈祷不 502。
• 多环境、多证书、多 upstream 时，人肉极易出错。

NginxUI（https://github.com/0xJacky/nginx-ui）把 Nginx 的管理界面化：

• 在线编辑、语法高亮、实时语法检查；
• 一键申请 / 续期 Let’s Encrypt 证书；
• 可视化 upstream、location、rewrite；
• 多节点集中管理（配合 Nginx-UI-Agent）。

一句话：让 Nginx 像用宝塔一样简单，但比宝塔更纯粹、更轻量。

二、快速部署（Docker 版，三分钟搞定）

1. 单机尝鲜

# 1. 创建数据目录

mkdir -p /opt/nginx-ui/{data,ssl}

# 2. 拉起容器

docker run -d --name nginx-ui --restart=always \

-p 80:80 \

-p 443:443 \

-p 9000:9000 \

-v /opt/nginx-ui/data:/etc/nginx-ui \

-v /opt/nginx-ui/ssl:/etc/ssl/private \

uozi/nginx-ui:latest

• 9000 端口是后台管理界面，80/443 用于反向代理。
• 第一次访问 http://<IP>:9000，按向导设置管理员账号即可。

2. 生产级 docker-compose

version: "3.8"
services:
nginx-ui:
image: uozi/nginx-ui:latest
container_name: nginx-ui
restart: always
environment:
TZ: Asia/Shanghai
# 关闭演示模式
DEMO: "false"
ports:

- "80:80"

- "443:443"

- "9000:9000"

volumes:

- ./data:/etc/nginx-ui

- ./ssl:/etc/ssl/private

# 外挂真实 nginx.conf，方便容器内外共用

- ./nginx.conf:/etc/nginx/nginx.conf:ro

logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "3"

三、核心功能实战

1. 反向代理：一行代码都不用写

• “站点管理 → 添加站点”
  • 域名：app.example.com
  • 模式：反向代理
  • 上游：http://172.17.0.3:8080
  • 点击“生成配置 & 重载”，立刻生效。

小技巧：勾选“自动申请 HTTPS”，NginxUI 会自动跑 certbot，证书到期前 30 天续期。

2. 多环境配置模板

日常有“测试 / 预发 / 生产”三套 upstream，手工复制粘贴太累。

方案：用变量 + 模板

1. 在“环境变量”里新建：

• 
  upstream_api_test = 172.17.0.10:8080
  upstream_api_prod = 10.0.0.21:8080,10.0.0.22:8080

1. 在站点配置里写：

• 
  upstream backend {
  {{ .upstream_api_prod }}
  }

1. 切换环境时，只需改变量值 → 一键重载，十几台机器零出错。

3. 灰度发布（基于权重）

NginxUI 把 upstream 权重做成了滑杆：

• 旧版本权重 90，新版本权重 10；
• 观察日志没问题，再把滑杆拖到 50/50 → 0/100，全程 UI 操作，2 分钟完成灰度。

四、高阶玩法：集中管理 N 台 Nginx

场景：公司有 10 台边缘节点，想统一改配置、统一查看证书。

1. 安装 Nginx-UI-Agent（边缘节点）

# 以 CentOS 为例

curl -fsSL https://get.nginx-ui.com/agent.sh | bash -s -- \

--server https://nginx-ui.company.com:9000 \

--token <从 UI 复制的 Agent Token> \

--name edge-node-01

Agent 只做两件事：

• 定时把 /etc/nginx/nginx.conf 上报中央；
• 接收中央下发的重载指令 nginx -s reload。

2. 在 NginxUI 里批量操作

• “节点管理”能看到所有 Agent 心跳；
• 修改一个站点的 upstream → 选择“应用到节点” → 勾选 10 台机器 → 一键下发；
• 证书续期也只需点一次“全部更新”。

五、踩坑与经验汇总

坑点	现象	解决方案
容器内外 nginx 版本不一致	reload 时提示 directive "xxx" is not supported	把宿主机 /usr/sbin/nginx 挂进容器 -v /usr/sbin/nginx:/usr/sbin/nginx:ro
80/443 被宿主机 nginx 占用	容器启动报 bind failed	先停宿主机 nginx，或改用 host 网络 network_mode: host
Let’s Encrypt 申请失败	报 Timeout during connect	检查 80 端口是否已放行；域名 A 记录是否指向本机
多人同时编辑	配置被覆盖	在“设置 → 高级”里开启 Git 版本库，每次保存自动 commit，可回退
升级镜像后数据丢失	站点全消失	一定 把 /etc/nginx-ui 持久化到宿主机卷

六、一键备份脚本（每天凌晨 3 点）

#!/bin/bash

set -e
BACKUP_DIR="/backup/nginx-ui/$(date +%F)"
mkdir -p "$BACKUP_DIR"
docker exec nginx-ui tar czf - /etc/nginx-ui | gzip > "$BACKUP_DIR/nginx-ui.tar.gz"

# 把备份推到 S3 / OSS

aws s3 cp "$BACKUP_DIR" s3://my-backup/nginx-ui/ --recursive

七、总结

• 如果只有一台 Nginx，Docker 单机版 3 分钟就能起飞；
• 如果有多台边缘节点，用 Agent 模式，彻底告别 ssh 批量脚本；
• 记得把数据卷、备份、Git 版本库三件事做好，线上可睡安稳觉。

NginxUI 不是万能的，但它把 80% 的日常操作变成了“点点鼠标”，剩下的 20% 极端场景再回退到 CLI，既优雅又可控。