# nginx-ui

**Repository Path**: gebing80/nginx-ui

## Basic Information

- **Project Name**: nginx-ui
- **Description**: Nginx UI
Web 管理平台
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nginx UI

一个现代化的 Nginx Web 管理平台，提供可视化的站点管理、上游管理、配置编辑、日志查看和服务控制功能，支持本机与远程 SSH 集群统一管理。

## 功能

| 模块 | 功能 |
|------|------|
| **概览** | 服务状态、PID、站点/上游数量、CPU/内存/网络/磁盘监控；概览卡片可跳转对应页面 |
| **站点** | 创建、编辑、删除、启用/禁用虚拟主机；点击列表行预览配置；历史版本（预览、回退、删除） |
| **上游** | 创建、编辑、删除 upstream 配置；点击列表行预览配置；历史版本（预览、回退、删除） |
| **日志** | 访问/错误日志列表、内容预览、实时追踪 |
| **配置** | 编辑 nginx.conf、测试/保存/重载、SSL 证书管理 |
| **管理** | 测试配置、重载、启动/停止 Nginx |
| **集群** | 通过 SSH 直连管理多台远程 Nginx 节点 |

### 交互说明

- 侧边栏可收起，收拢后图标悬停显示提示
- 操作提示在页面顶部居中悬浮显示，5 秒后自动消失
- 删除、停止、重载等重要操作需二次确认
- 站点/上游列表点击非操作列，弹窗预览当前配置文件内容

## 配置历史版本

创建或更新站点/上游时，会自动保存历史版本（每个资源最多 50 条），存储在 Nginx UI 后端本地：

```
{STATE_FILE 父目录}/
├── site_versions/{节点}/{站点ID}/
└── upstream_versions/{节点}/{上游名}/
```

- 历史版本保存在 UI 服务器，不会写入远程节点磁盘
- 删除站点/上游时，会同步清除对应历史
- 重命名上游时，历史目录会自动迁移

## 集群管理（SSH 直连）

1. 侧边栏进入 **集群** 页面，添加远程节点（主机、SSH 账号、密码或私钥、Nginx 路径）
2. 左侧 **当前节点** 下拉框切换「本机」或远程节点
3. 概览 / 站点 / 上游 / 日志 / 配置 / 管理 会针对所选节点操作

**要求：**

- nginx-ui 所在机器需能 SSH 连通各节点
- 远程主机需安装 `python3` 与 `psutil`（概览页系统监控）
- SSH 用户需有读写 Nginx 配置、执行 `nginx -t` / `reload` 的权限
- 节点凭证保存在 `{STATE_FILE 父目录}/nodes.json`，请限制文件权限

**性能优化：** 远程节点使用合并 Dashboard API、读缓存（远程 3s / 本机 1s）、批量 SSH 查询，减少重复连接。

## 快速开始

### 开发模式

```bash
chmod +x dev.sh start.sh
./dev.sh
```

- 前端：http://localhost:5173
- 后端 API：http://localhost:8089

### 生产模式

```bash
./start.sh
```

访问 http://localhost:8089，或通过 Nginx 反代访问 http://localhost

## 服务器部署（生产环境）

### 1. 安装 Nginx

**Ubuntu / Debian：**
```bash
sudo apt update && sudo apt install -y nginx python3 python3-venv nodejs npm
sudo mkdir -p /etc/nginx/sites-available /etc/nginx/sites-enabled /etc/nginx/certs
```

确认 `nginx.conf` 的 `http {}` 块中包含：
```nginx
include /etc/nginx/sites-enabled/*.conf;
```

**CentOS / RHEL / Alibaba Cloud Linux：**
```bash
sudo yum install -y nginx python3 nodejs npm
```

使用 `conf.d` 目录，环境变量设置为：
```bash
NGINX_LAYOUT=conf.d
SITES_AVAILABLE=/etc/nginx/conf.d
SITES_ENABLED=/etc/nginx/conf.d
```

### 2. 一键安装 Nginx UI

```bash
cd /path/to/nginx-ui
sudo bash deploy/install.sh
```

### 3. 配置环境变量

编辑 `/opt/nginx-ui/.env`（安装脚本会自动从模板创建）：

```bash
sudo vim /opt/nginx-ui/.env
```

**Ubuntu/Debian 示例：**
```bash
NGINX_BIN=/usr/sbin/nginx
NGINX_CONF=/etc/nginx/nginx.conf
SITES_AVAILABLE=/etc/nginx/sites-available
SITES_ENABLED=/etc/nginx/sites-enabled
CERTS_DIR=/etc/nginx/certs
STATE_FILE=/var/lib/nginx-ui/state.json
HOST=0.0.0.0
PORT=8089
ADMIN_USERNAME=admin
ADMIN_PASSWORD=你的强密码
JWT_SECRET=随机长字符串
```

**CentOS/RHEL 示例：**
```bash
NGINX_LAYOUT=conf.d
SITES_AVAILABLE=/etc/nginx/conf.d
SITES_ENABLED=/etc/nginx/conf.d
CERTS_DIR=/etc/nginx/certs
STATE_FILE=/var/lib/nginx-ui/state.json
ADMIN_USERNAME=admin
ADMIN_PASSWORD=你的强密码
JWT_SECRET=随机长字符串
```

### 4. 启动服务

```bash
sudo systemctl start nginx-ui
sudo systemctl status nginx-ui
```

或使用项目内重启脚本：

```bash
sudo bash /opt/nginx-ui/restart.sh
```

访问：`http://<服务器IP>`（Nginx 80 端口反代）或 `http://<服务器IP>:8089`

### 5. 权限说明

Nginx UI 需要读写 `/etc/nginx` 下的配置，并执行 `nginx -t` / `nginx -s reload`，因此 **systemd 服务默认以 root 运行**。

生产环境建议：
- 用防火墙限制 8089 端口仅内网可访问（80 端口对外提供反代访问）
- 前面加 Nginx 反向代理并配置 HTTPS + 基础认证
- 不要将管理端口暴露到公网

### 6. Docker 部署

```bash
docker compose up -d
```

`docker-compose.yml` 默认映射 `8089` 端口，并挂载 `/etc/nginx`。

安装脚本会自动写入 Nginx 反代配置（`nginx-ui.conf`），将 80 端口默认站点转发到 `127.0.0.1:8089`。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `NGINX_BIN` | `nginx` | Nginx 可执行文件路径 |
| `NGINX_CONF` | `/etc/nginx/nginx.conf` | 主配置文件路径 |
| `SITES_AVAILABLE` | `/etc/nginx/sites-available` | 站点配置目录 |
| `SITES_ENABLED` | `/etc/nginx/sites-enabled` | 已启用站点目录 |
| `CERTS_DIR` | `/etc/nginx/certs` | SSL 证书目录 |
| `ACCESS_LOG` | `/var/log/nginx/access.log` | 默认访问日志路径 |
| `ERROR_LOG` | `/var/log/nginx/error.log` | 默认错误日志路径 |
| `STATE_FILE` | `.local/state.json` | 状态文件路径；历史版本、节点信息存于其父目录 |
| `NGINX_LAYOUT` | `auto` | `debian` 或 `conf.d`（CentOS 系列） |
| `PORT` | `8089` | Nginx UI 服务端口 |
| `JWT_EXPIRE_HOURS` | `24` | Token 有效期（小时） |
| `ADMIN_USERNAME` | `admin` | 管理员用户名 |
| `ADMIN_PASSWORD` | `admin123` | 管理员密码（生产环境务必修改） |
| `JWT_SECRET` | - | JWT 签名密钥（生产环境务必修改） |

## 管理员登录

平台已启用 JWT 鉴权，未登录无法访问管理页面和 API。

- 登录页：`/login`
- 默认账号：`admin` / `admin123`
- 生产环境请在 `/opt/nginx-ui/.env` 中修改 `ADMIN_USERNAME`、`ADMIN_PASSWORD`、`JWT_SECRET`

macOS Homebrew 安装的 Nginx 会自动检测 `/opt/homebrew/etc/nginx/` 路径。

## 本地开发（macOS Homebrew）

```bash
# 1. 安装 nginx
brew install nginx

# 2. 初始化站点目录，并写入 sites-enabled include
bash scripts/setup-local-nginx.sh

# 3. 生成本地 .env（若还没有）
cp .env.example .env

# 4. 启动 Nginx UI
./dev.sh

# 5. 另开终端启动 nginx
nginx
```

Intel Mac 默认路径为 `/usr/local/etc/nginx/`，Apple Silicon 为 `/opt/homebrew/etc/nginx/`，会自动检测。

### 前端构建失败（rollup 报错）

Linux 服务器上若出现 `@rollup/rollup-linux-x64-gnu` 缺失，通常是 `node_modules` 平台不匹配。执行：

```bash
cd /opt/nginx-ui
sudo git pull
sudo bash deploy/build-frontend.sh /opt/nginx-ui/frontend
sudo systemctl restart nginx-ui
```

或手动修复：

```bash
cd /opt/nginx-ui/frontend
rm -rf node_modules package-lock.json
npm install --include=optional
npm run build
```

## 技术栈

- **后端**：Python FastAPI + Uvicorn
- **前端**：React + TypeScript + Tailwind CSS + Vite

## API 端点

```
POST   /api/auth/login                          管理员登录
GET    /api/auth/me                             当前用户
POST   /api/auth/logout                         退出登录

GET    /api/dashboard                           概览 + 系统监控（合并）
GET    /api/overview                            概览信息
GET    /api/system/metrics                      系统监控

GET    /api/nodes                               节点列表
POST   /api/nodes                               添加节点
PUT    /api/nodes/:id                           更新节点
DELETE /api/nodes/:id                           删除节点
POST   /api/nodes/:id/test                      测试 SSH 连接

GET    /api/sites                               站点列表
GET    /api/sites/:id                           站点详情
POST   /api/sites                               创建站点
PUT    /api/sites/:id                           更新站点
DELETE /api/sites/:id                           删除站点
PATCH  /api/sites/:id/toggle                    启用/禁用
GET    /api/sites/:id/versions                  站点历史版本
GET    /api/sites/:id/versions/:vid             版本详情
POST   /api/sites/:id/versions/:vid/restore     回退版本
DELETE /api/sites/:id/versions/:vid             删除版本

GET    /api/upstreams                             上游列表
GET    /api/upstreams/:name                       上游详情
POST   /api/upstreams                             创建上游
PUT    /api/upstreams/:name                       更新上游
DELETE /api/upstreams/:name                       删除上游
GET    /api/upstreams/:name/versions              上游历史版本
GET    /api/upstreams/:name/versions/:vid         版本详情
POST   /api/upstreams/:name/versions/:vid/restore 回退版本
DELETE /api/upstreams/:name/versions/:vid         删除版本

GET    /api/logs                                日志文件列表
GET    /api/logs/read                           读取日志
GET    /api/logs/tail                           实时追踪

GET    /api/config/page                         配置页数据
GET    /api/config/nginx                        读取 nginx.conf
PUT    /api/config/nginx                        保存 nginx.conf
POST   /api/config/test                         测试配置
POST   /api/config/reload                       重载

GET    /api/certificates                        证书列表
POST   /api/certificates                        上传证书
DELETE /api/certificates/:name                  删除证书

POST   /api/nginx/test                          测试配置
POST   /api/nginx/reload                        重载
POST   /api/nginx/start                         启动
POST   /api/nginx/stop                          停止
```

所有 API 均支持 `?node_id=` 参数，用于指定远程集群节点（省略则为本机）。

## 注意事项

- 生产环境部署时建议配置反向代理和身份认证
- 修改 Nginx 配置需要相应的文件系统权限
- 保存配置前会自动创建 `.bak` 备份文件
- 站点/上游历史版本仅存于 UI 后端，请一并备份 `{STATE_FILE 父目录}` 目录