Files
NginxMan/README.md
T

11 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,重启程序后继续使用。
  • 手动备份:可将当前配置和可编辑入口页模板保存为一个 ZIP 备份包。
  • 关闭时备份:正常关闭程序时,自动在 data/backups 中保存一份备份。
  • 手动导入:支持导入 NginxMan ZIP 备份包,也兼容直接导入旧的 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
手动备份 将当前配置与入口页模板打包到 data/backups,并只保留最新 10 份
导入备份 导入 ZIP 备份包或旧版 JSON 配置;导入前会自动备份当前数据
刷新状态 重新检查 Nginx 进程状态
打开配置文件 打开 nginxman.json
打开文件夹 打开配置文件所在目录
浏览 选择外部 nginx.exe

数据目录

发布后的主要目录结构:

bin\
├─ NginxMan.exe
└─ data\
   ├─ nginxman.json              # 入口页、端口及代理映射配置
   ├─ nginx.conf                 # 自动生成的 Nginx 配置
   ├─ nginx\                     # 内置 Nginx 运行文件
   ├─ logs\                      # 访问日志和错误日志
   ├─ backups\                   # 手动、关闭时和导入前安全备份(最多 10 份)
   └─ www\
      ├─ index.template.html     # 可编辑的入口页模板
      └─ index.html              # 自动生成的入口页

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

备份与恢复

手动备份

点击“手动备份”,程序会在 data/backups 中创建以时间开头的文件,例如 20260827-103015-123-manual.zip。生成的 ZIP 备份包包含:

  • nginxman.json:入口页设置、Nginx 路径和全部代理映射。
  • www/index.template.html:当前可编辑的网站入口页模板。

运行日志、自动生成的 nginx.conf、index.html 和 Nginx 程序文件不会写入备份;这些内容可以由程序重新生成,或不属于用户配置。

关闭时自动备份

通过窗口关闭按钮、快捷键或正常退出程序时,NginxMan 会自动创建以时间开头的备份:

data\backups\年年年年月月日日-时时分分秒秒-毫秒-auto-close.zip

文件名使用固定宽度时间格式,按名称排序即可直观看到备份先后。data/backups 中的手动备份、关闭备份和导入前备份合计最多保留最新 10 个,超过数量后自动删除最旧文件。自动备份失败时,正常交互关闭会提示是否仍然退出。系统关机过程中不会阻止 Windows 关闭。

手动导入

点击“导入备份”,可以选择:

  • NginxMan 生成的 .zip 备份包;
  • 旧版本或手工保存的 nginxman.json。

程序会先读取并校验全部配置。校验通过后,会在 data/backups 中创建 年年年年月月日日-时时分分秒秒-毫秒-before-import.zip,然后才替换当前配置、恢复备份包中的网页模板,并重新生成入口页和 Nginx 配置。损坏的 ZIP、无效 JSON、重复域名、错误端口或缺少入口占位符的网页模板不会覆盖现有数据。

如果导入时 Nginx 正在运行,导入完成后请点击“重新加载”,使新的代理配置生效。

配置文件示例

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 自动完成。