Files
NginxMan/README.md
T

8.7 KiB
Raw Blame History

NginxMan

NginxMan 是一款面向 Windows 的可视化 Nginx 反向代理管理工具。程序将 Nginx 运行环境打包在单个 EXE 中,通过图形界面管理入口页、域名、监听端口和上游服务。

软件目标

NginxMan 主要用于:

  • 让不熟悉 Nginx 配置语法的用户也能建立反向代理。
  • 将本机或内网中的多个服务通过不同域名和端口对外提供访问。
  • 集中管理代理映射,避免手工编辑 nginx.conf 带来的格式错误。
  • 根据用户配置自动生成统一的网站入口页。
  • 将程序、Nginx、配置、日志和入口页集中放在一个可迁移目录中。

程序首次运行时不会预置任何代理映射,也不会预设入口页域名。所有域名、端口、名称和简介均由用户填写。

核心功能

  • 内置 Nginx:首次运行时自动释放完整的 Windows Nginx 运行文件。
  • 入口页设置:用户可以设置或关闭入口页域名,并为入口页指定独立的监听端口。
  • 映射管理:支持新增、修改和删除域名反向代理映射。
  • 可配置端口:入口页和每条代理映射均可使用 1–65535 范围内的端口。
  • 配置生成:根据界面数据自动生成 data/nginx.conf。
  • 进程控制:可以启动、重新加载和停止 Nginx,并显示当前运行状态。
  • 入口页生成:根据所有代理映射自动生成 data/www/index.html。
  • 网页模板:入口页样式保存在 data/www/index.template.html,入口卡片由程序动态填充。
  • 配置持久化:设置保存在 data/nginxman.json,重启程序后继续使用。
  • 自定义 Nginx:既可以使用内置 Nginx,也可以在界面中选择其他 nginx.exe。

配置组成

入口页设置

入口页是可选的服务导航页面,配置包含:

字段 作用 通用示例
入口页域名 用于访问统一入口页;留空表示关闭入口站点 portal.example.com
入口页端口 入口页对外监听的端口 8088

入口页域名和端口不会写死在源码中,也不需要通过重新编译程序来修改。

代理映射

每条代理映射包含:

字段 作用 通用示例
网站名称 显示在入口页卡片上的名称 Example Application
域名 用户访问目标服务时使用的域名 app.example.com
上游接口 Nginx 实际转发到的服务地址 http://127.0.0.1:5000
监听端口 该域名对外监听的端口 8080
网站简介 显示在入口页卡片上的说明 示例业务应用

监听端口并非固定为 80。界面中的 80 只是初始测试值,可以根据部署环境修改为其他可用端口。

快速开始

1. 启动程序

运行发布目录中的:

bin\NginxMan.exe

首次运行时,程序会在 EXE 所在目录创建 data 文件夹,并准备 Nginx、配置、日志和入口页文件。代理映射列表初始为空。

2. 设置入口页(可选)

在程序顶部填写:

  1. 入口页域名,例如 portal.example.com。
  2. 入口页端口,例如 8088。
  3. 点击“保存入口设置”。

若不需要统一入口页,将入口页域名留空并保存即可。此时程序不会在 Nginx 配置中生成入口站点,但代理映射仍可正常使用。

3. 新增代理映射

在“编辑映射”区域依次填写:

  1. 域名,例如 app.example.com。
  2. 上游接口,例如 http://127.0.0.1:5000。
  3. 监听端口,例如 8080。
  4. 网站名称,例如 Example Application。
  5. 网站简介,例如 示例业务应用。
  6. 点击“新增”。

新增成功后,程序会立即:

  • 保存 data/nginxman.json。
  • 重新生成 data/nginx.conf。
  • 将新入口写入 data/www/index.html。

按上述示例配置后,代理访问地址为:

http://app.example.com:8080/

4. 启动或重新加载代理

  • Nginx 尚未运行时,点击“启动代理”。
  • Nginx 已运行且配置发生变化时,点击“重新加载”。
  • 需要关闭代理时,点击“停止代理”。

5. 配置 DNS 和防火墙

入口页域名及每个代理域名都需要解析到运行 NginxMan 的服务器 IP。非标准 HTTP 端口还需要在服务器防火墙或云安全组中开放。

例如:

portal.example.com  ->  服务器 IP
app.example.com     ->  服务器 IP

端口说明

  • 可配置范围为 1–65535。
  • 80 只是方便测试普通 HTTP 的初始值,不是固定端口。
  • 访问非 80 端口时,需要在 URL 中显式写出端口号。
  • 入口页和代理映射可以使用不同端口。
  • 同一服务器上不能让两个不同程序同时占用相同的 IP 和端口组合。
  • 入口页不能与某条代理映射使用完全相同的域名和监听端口。

界面按钮说明

按钮 作用
保存入口设置 保存入口页域名与监听端口;域名留空表示关闭入口站点
新增 使用当前表单内容创建一条新映射
保存修改 保存列表中当前选中映射的修改
删除 删除当前选中的映射
清空 清除表单内容并进入新增状态
生成配置 手动重新生成 Nginx 配置
启动代理 生成配置并启动 Nginx
重新加载 让正在运行的 Nginx 读取最新配置
停止代理 停止 Nginx
刷新状态 重新检查 Nginx 进程状态
打开配置文件 打开 nginxman.json
打开文件夹 打开配置文件所在目录
浏览 选择外部 nginx.exe

数据目录

发布后的主要目录结构:

bin\
├─ NginxMan.exe
└─ data\
   ├─ nginxman.json              # 入口页、端口及代理映射配置
   ├─ nginx.conf                 # 自动生成的 Nginx 配置
   ├─ nginx\                     # 内置 Nginx 运行文件
   ├─ logs\                      # 访问日志和错误日志
   └─ www\
      ├─ index.template.html     # 可编辑的入口页模板
      └─ index.html              # 自动生成的入口页

升级或替换 NginxMan.exe 时,请保留 bin/data 目录,以免丢失用户配置、模板和日志。

配置文件示例

data/nginxman.json 的结构示例:

{
  "nginxExePath": "data\\nginx\\nginx.exe",
  "nginxConfPath": "data\\nginx.conf",
  "accessLogPath": "data\\logs\\access.log",
  "errorLogPath": "data\\logs\\error.log",
  "portalDomain": "portal.example.com",
  "portalListenPort": 8088,
  "routes": [
    {
      "domain": "app.example.com",
      "upstream": "http://127.0.0.1:5000",
      "listenPort": 8080,
      "websiteName": "Example Application",
      "description": "示例业务应用"
    }
  ]
}

建议通过界面维护配置。若手工修改 JSON,需要重新启动 NginxMan,使程序重新读取文件。

自定义入口页模板

入口页模板位于:

data\www\index.template.html

可以直接修改页面标题、颜色、布局和其他静态内容。程序生成入口页时,会将所有网站卡片插入以下占位符:

{{NGINXMAN_SERVICE_CARDS}}

请勿删除或修改该占位符,否则程序无法生成入口页。网站名称和简介在写入 HTML 前会自动转义,避免特殊字符破坏页面结构。

从源码构建

开发环境需要:

  • Windows 10 或 Windows 11。
  • 支持 .NET 8 的 .NET SDK。
  • .NET Windows Desktop/WinForms 构建组件。

在项目目录运行:

.\build.ps1

构建结果位于:

bin\NginxMan.exe

发布结果为自包含的 Windows x64 单文件程序,目标计算机通常不需要另外安装 .NET Runtime。

常见问题

无法启动 Nginx

  • 检查所配置的监听端口是否已被 IIS、Apache、其他 Nginx 或其他程序占用。
  • 检查 Windows 防火墙或云安全组是否允许目标端口访问。
  • 查看 data/logs/error.log 获取具体错误。
  • 如使用外部 Nginx,确认界面中的 nginx.exe 路径正确。

域名无法访问

  • 确认域名 DNS 已解析到当前服务器。
  • 确认访问 URL 中的端口与监听端口一致。
  • 确认上游服务正在运行,并能在服务器本机访问。
  • 确认 Nginx 状态显示为“运行中”。
  • 修改配置后,如果 Nginx 已运行,请点击“重新加载”。

入口页没有显示最新内容

  • 确认 data/www/index.html 的修改时间已经更新。
  • 强制刷新浏览器缓存。
  • 确认 index.template.html 中仍保留 {{NGINXMAN_SERVICE_CARDS}}。

使用限制

  • 当前自动生成的是 HTTP 反向代理配置。
  • 如需 HTTPS,需要自行补充证书、TLS 监听及相关 Nginx 配置。
  • 域名解析、证书申请和服务器防火墙配置不由 NginxMan 自动完成。