# wos-nginx

**Repository Path**: dushu/wos-nginx

## Basic Information

- **Project Name**: wos-nginx
- **Description**: nginx在线管理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 恩杰克斯 · Nginx 管理工具

轻量 nginx 可视化管理面板：**接管现有配置**，不另起炉灶。Node + Express 后端 + Vue3 前端（wos-ui 皮肤）+ 本地 JSON 存储（**零数据库**）。单机部署，面板内存约 50MB。

## 界面截图

| 任务台 | 证书管理 |
|---|---|
| ![任务台](docs/screenshots/01-dashboard.png) | ![证书管理](docs/screenshots/02-certificates.png) |

| 端口与防火墙 | 日志备份 | 系统设置 |
|---|---|---|
| ![端口与防火墙](docs/screenshots/03-firewall.png) | ![日志备份](docs/screenshots/04-log-backup.jpg) | ![系统设置](docs/screenshots/05-settings.png) |

## 核心设计：接管模式

这套工具不"拥有"你的配置，只**接管** `conf.d` 里已有的配置文件：

| 操作 | 行为 |
|------|------|
| 列表 | 实时扫描配置目录下的 `.conf` / `.conf.disabled`，解析展示（域名/端口/类型/证书） |
| 编辑 | 在**原文**上做最小化修改；`nginx -t` 校验通过才落盘，**失败自动回滚** |
| 证书关联 | 只替换原文里 `ssl_certificate` / `ssl_certificate_key` 两行路径，其余一律不动 |
| 停用 | 改后缀 `.disabled`（conf.d 只 include `*.conf`，可逆） |
| 删除 | 先备份到 `data/conf-snapshots/` 再从配置目录移除 |
| 新建 | 写一个标准 conf 进配置目录 |

站点信息不落库、每次现读。只有「面板关联过的证书」记在 `db.siteCerts`（用于恢复原路径）。

## 功能

- **域名管理**：扫描接管、快捷修改（server_name/root/proxy_pass/access_log 行级替换）、配置原文编辑、启停、删除（可恢复）、reload 生效
- **建站模板**（创建域名向导）：选模板 → 填参数 → 实时预览 → 原文微调 → 创建生效
  - **静态主站**（HTTP/HTTPS）：root + index，可选 SPA 路由回退
  - **反向代理**（HTTP/HTTPS）：proxy_pass 到本地端口，自动带 X-Real-IP/X-Forwarded-\* 头
  - **HTTPS 变体**：关联证书库证书，80 跳 443（可关），http2 可选
  - **空白配置**：手工粘贴完整 conf
  - 预览与正式创建共用同一渲染函数，所见即所得；手改过的原文优先落盘
- **SSL 证书管理**：zip 压缩包上传（自动解压/识别/去重/配对校验）、整包替换、单文件替换、PEM 文本上传；证书详情（CN/SAN/颁发者/到期天数，临期变色预警）
- **端口与防火墙**：ss 现读（带进程和 PID，跨平台）、firewalld/ufw/iptables 自动探测
- **日志备份**：独立页查看日志尾巴、单站/全量打包、下载、保留份数
- **系统状态**：内存/硬盘/负载/nginx 状态登录后现读，不建表

## 快速开始

### 环境要求

- **Node.js ≥ 18**（开发机实测 Node 20 运行）
- 一台装了 **nginx** 的 Linux 服务器（面板管理的对象；macOS 亦可本地跑）
- 面板需要对 nginx 配置目录、日志目录有读写权限，并能执行 `nginx -t` / `nginx -s reload`

### 部署运行（四步，不会错）

```bash
# 1. 获取代码
git clone https://gitee.com/dushu/wos-nginx.git
cd wos-nginx

# 2. 安装依赖（两处：项目根 + web）
npm install
cd web && npm install && cd ..

# 3. 构建前端（必须做！server 直接托管 web/dist，不构建打不开页面）
cd web && npm run build && cd ..

# 4. 启动
npm start
```

启动后访问 **http://服务器IP:8088**，默认账号 `admin` / `admin123`——**登录后立刻到「系统设置」改密码**。

### 端口说明（只有一个对外端口）

| 场景 | 端口 | 说明 |
|------|------|------|
| 生产运行 | **8088** | `npm start` 一个进程全包：API + 前端页面都由它提供 |
| 本地开发 | 前端 **5174** + 后端 8088 | `npm start` 起后端；`cd web && npm run dev` 起前端（自带 `/api` 代理和热更新） |

改端口三种方式（任一）：`PORT=9000 npm start` / 改 `data/db.json` 的 `settings.panelPort` / 「系统设置」页里改。

### 常用配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `settings.confDir` | `/etc/nginx/conf.d` | nginx 配置目录（宝塔/源码编译的在设置页改） |
| `settings.logDir` | `/var/log/nginx` | 日志目录 |
| `settings.nginxBin` | `nginx` | nginx 命令路径 |
| `settings.backupKeep` | `10` | 日志备份保留份数 |

环境变量：`PORT`（面板端口）、`NM_ADMIN_PASSWORD`（首次启动时预设管理员密码，免默认密码）。

### pm2 常驻（可选）

```bash
pm2 start server/index.js --name wos-nginx
pm2 save        # 保存进程列表
pm2 startup     # 注册开机自启（只需做一次）
```

两行都做，服务器重启后面板才会自动回来。

## 目录结构

```
wos-nginx/
├── package.json          # 运行时依赖：express + adm-zip
├── server/
│   ├── index.js          # 入口：API + 前端托管
│   ├── jsonStore.js      # 本地 JSON 存储（原子写、退出同步落盘）
│   ├── auth.js           # scrypt 认证
│   ├── lib/
│   │   ├── confParser.js # nginx conf 解析器（花括号配对，多 server 块）
│   │   ├── nginx.js      # nginx -t / reload / 读写 conf（失败回滚）
│   │   ├── cert.js       # openssl 证书解析（兼容 OpenSSL 1.0.2）
│   │   └── firewall.js   # 防火墙探测
│   └── routes/           # sites / certs / system / network / logs / settings
├── web/                  # Vue3 + wos-ui（hash 路由）
├── docs/screenshots/     # README 截图
└── data/                 # 运行时生成：db.json + certs/ + backups/ + conf-snapshots/（不入库）
```

## 环境适配

- **nginx 路径**：默认 `/etc/nginx/conf.d`，源码编译/宝塔装在「系统设置」里改
- **OpenSSL 版本**：TLSv1.3 支持自动探测（CentOS 7 的 1.0.2 不支持，自动降级 TLSv1.2）
- **端口解析**：ss → netstat → lsof 逐级兜底（Linux/macOS 通用）

## 已知注意点

- CentOS 7 nginx 默认 `PrivateTmp=yes`，站点 root 不要用 `/tmp` 下目录
- `nginx -t` 会校验证书文件存在性：配置指向的证书文件缺失时，任何写入都会被拦截并回滚（保护机制）
- `nginx -s reload` 只发信号不等 worker 就绪，创建/修改后立刻访问可能落到旧 worker（稍等 1-2 秒或刷新即可）

## 安全须知

- 面板拥有 nginx 配置的完全读写权限，**不要暴露到公网**；建议只绑内网 IP，或套一层 VPN/反代 + 访问控制
- 首次登录后立即修改默认密码
- `data/` 含证书与配置快照，注意备份和权限

## License

MIT