0xJacky/nginx-ui · 上手攻略

• 仓库：0xJacky/nginx-ui
• 链接：https://github.com/0xJacky/nginx-ui
• 分类：engineering / web-server-management
• 作者：spark
• 更新：2026-10-10

§0 速览

本棒 net-new = 1 件（nginx-ui 单仓独立攻略，无沿用件）。 来源：GitHub README（fetch 200 OK）+ Docker Hub uozi/nginx-ui + nginxui.com 官方文档 + 第三方实测报告（hysenlabs / DEV.to / pkg.go.dev）。Star 11,581，最近提交 2026-10-10，许可证 AGPL-3.0（⚠️ 见下文法律注意）。

一、是什么

nginx-ui 是 0xJacky、Hintay、Akino 共同开发的 Nginx Web 管理面板，单二进制发布（Go 后端 + Vue 前端），自称为"又一个 Nginx WebUI"——名字谦卑，但功能相当完整。它把原本只能通过 vim /etc/nginx/nginx.conf + nginx -s reload 完成的配置、站点、证书、日志、终端操作，集中到一个 Web 界面里，并自带 MCP（Model Context Protocol）接口允许 AI Agent 介入。

二、解决什么问题

运维 Nginx 时最痛的几件事：

1. 多节点重复操作——手工 scp + reload，nginx-ui 提供"集群镜像操作"，一批服务器一次推送。
2. 配置变更可追溯——每次保存自动备份版本，支持 diff 和回滚。
3. 证书易过期——内置 Let's Encrypt 一键签发 + 自动续期，HTTP-01 端口 9180。
4. 写反代配置容易写错 WebSocket——自带 NgxConfigEditor 块编辑器与 Ace 代码编辑器，含 LLM 代码补全。
5. 线上排障要 SSH——Web Terminal + 在线日志查看器。
6. AI 辅助配置——内置 ChatGPT/DeepSeek-R1 助手，可显示思维链；MCP 通道给 Claude/Cursor 这类 Agent 直接操控。

三、快速安装

方案 A：Linux 一键脚本（systemd）

适合把宿主 Nginx 也交给它管理的场景。脚本会自动安装 nginx-ui systemd 单元，默认端口 9000、HTTP-01 校验端口 9180。

bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ install

控制命令：

systemctl start  nginx-ui
systemctl stop   nginx-ui
systemctl restart nginx-ui
systemctl status nginx-ui

卸载（保留配置和数据库）：

bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ remove

方案 B：Docker（推荐给容器化部署）

镜像基于官方 nginx:latest，可以直接"替换宿主 Nginx"——只要把容器 80/443 端口发布出去即可。首次启动要保证 -v 挂载的 /etc/nginx 是空目录。

docker run -dit \
  --name=nginx-ui \
  --restart=always \
  -e TZ=Asia/Shanghai \
  -v /mnt/user/appdata/nginx:/etc/nginx \
  -v /mnt/user/appdata/nginx-ui:/etc/nginx-ui \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:80 -p 8443:443 \
  uozi/nginx-ui:latest

启动后浏览器打开 http://<host>:8080/install 走首次初始化向导。如果改了端口映射，访问映射到容器 80 端口的那个宿主机端口。

docker-compose.yml 版本：

services:
  nginx-ui:
    stdin_open: true
    tty: true
    container_name: nginx-ui
    restart: always
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - '/mnt/user/appdata/nginx:/etc/nginx'
      - '/mnt/user/appdata/nginx-ui:/etc/nginx-ui'
      - '/var/www:/var/www'
      - '/var/run/docker.sock:/var/run/docker.sock'
    ports:
      - 8080:80
      - 8443:443
    image: 'uozi/nginx-ui:latest'

方案 C：可执行二进制 + nohup

适合不想装服务、临时调试：

./nginx-ui -config app.ini          # 前台
nohup ./nginx-ui -config app.ini &  # 后台
kill -9 $(ps -aux | grep nginx-ui | grep -v grep | awk '{print $2}')

支持平台覆盖 macOS 11+、Windows 10+、Linux（含 arm64/armv5-7/mips32-64/riscv64/loongarch64）、FreeBSD/OpenBSD/Dragonfly BSD、OpenWrt。

方案 D：从源码构建

需要 Make、Golang 1.23+、Node.js 21+（README 注明）。先后端构建、前端 bun install && bun run build，再回到根目录：

go generate
go build -tags=jsoniter -ldflags "$LD_FLAGS -X 'github.com/0xJacky/Nginx-UI/settings.buildTime=$(date +%s)'" -o nginx-ui -v main.go

四、核心用法

1. Debian 风格站点目录约定

nginx-ui 遵循 Debian 的 sites-available / sites-enabled 软链约定，启用站点时自动在 sites-enabled 建软链。非 Debian/Ubuntu 系统需要改 nginx.conf，加入：

http {
    # ...
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

否则站点不会被加载。⚠️ 这是最常见的"装上但站点不生效"原因。

2. Nginx 反代 nginx-ui 自身的配置（关键片段）

Web Terminal 和实时日志用了 WebSocket，必须带 Upgrade/Connection 头映射：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name <your_server_name>;
    rewrite ^(.*)$ https://$host$1 permanent;
}

server {
    listen 443 ssl http2;
    server_name <your_server_name>;

    ssl_certificate     /path/to/ssl_cert;
    ssl_certificate_key /path/to/ssl_cert_key;

    location / {
        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_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_pass http://127.0.0.1:9000/;
    }
}

从老版本升级的 Docker 用户需要额外看 Docker WebSocket fix 修 conf.d/nginx-ui.conf。

3. MCP 接口（AI Agent 自动化）

nginx-ui 暴露 MCP 端点，允许 Claude / Cursor / 自研 Agent 通过标准化协议读写配置、重载服务。直接对接 MCP 客户端即可，无需手写 API 包装。

4. AI 助手

面板内集成 ChatGPT / DeepSeek-R1，支持 CoT 思维链展示——可以看它怎么推理你的 nginx 配置为何不优。

五、典型适用场景

• 小型 VPS / 个人服务器：单台机器想可视化管 Nginx，不想记 nginx -t + nginx -s reload 那一套。
• 中小团队多节点运维：用集群镜像功能批量推送配置。
• 证书自动续期场景：避免手动 acme.sh cron。
• AI 辅助运维：MCP 让 Agent 直接调 nginx-ui，省一层适配。
• Demo / 教学环境：官方提供 https://demo.nginxui.com（admin / admin）。

六、坑与注意

1. AGPL-3.0 传染性 ⚠️：如果你修改并对外提供服务（SaaS / 网络服务），AGPL 要求你向用户公开修改后的源码。内部使用或仅自用问题不大，对外提供服务请评估法律风险（hysenlabs 2026-10 报告特别提示）。
2. 默认分支是 dev ⚠️：生产环境不要直接跑 dev 分支，要用 latest release 标签版（2026-08 报告时为 v2.5.10，更晚版本以 release 页为准——具体版本号未在抓取页面 verbatim 显示，⚠️ 待复核）。
3. Debian 风格配置：CentOS / Arch 默认 nginx.conf 不含 sites-enabled，装完必须按上面改 include，否则站点保存后不生效。
4. 首次启动端口冲突：脚本默认 9000/9180，如果被占用要改 /usr/local/etc/nginx-ui/app.ini 后 systemctl restart nginx-ui。
5. Docker 挂载 /etc/nginx 必须空目录：否则容器启动后会因写权限或冲突配置失败。
6. WebSocket 反代配错：只 proxy_pass 不带 Upgrade 头，Web Terminal 和实时日志会断流。
7. 从老镜像升级：需修 conf.d/nginx-ui.conf，参考官方 WebSocket fix 指南。
8. Docker socket 挂载 ⚠️：-v /var/run/docker.sock:/var/run/docker.sock 会给容器 root 级控制宿主 docker 的能力，安全风险高，公网部署请评估替代方案（如 docker-in-docker / socket-proxy）。

七、与同类对比

工具	语言	部署形态	集群	AI 集成	许可证
nginx-ui	Go + Vue	单二进制 / Docker / systemd	✅ 镜像多节点	✅ ChatGPT + DeepSeek-R1 CoT + MCP	AGPL-3.0
Nginx Proxy Manager	Node.js + Vue	Docker 为主	❌	❌	MIT
Ajenti	Python	包安装	❌	❌	MIT
Cockpit Nginx module	各种	系统组件	取决于 Cockpit	❌	LGPL

nginx-ui 的差异化在集群管理 + AI 集成 + MCP，单机简单场景 Nginx Proxy Manager 更轻量，但需要 AI 运维或多节点批量操作时 nginx-ui 优势明显。

八、一句话推荐

适合多节点运维 + 想要 AI 辅助 / MCP 集成的团队首选；AGPL 是唯一需要事先评估的门槛，单机玩玩 NPM 更省心。

---

诚实标注：①uozi/nginx-ui:latest 镜像具体 tag / Dockerfile 时间未在 README 直接给出 verbatim，⚠️ 部署前到 Docker Hub 复核最新稳定 tag；②仓库 README 标注的 Go 1.23+ / Node 21+ 为构建期依赖，运行期只需二进制；③Demo 站凭据 admin/admin 为公开测试账号，公网部署必须立刻改密码。