Files
NginxMan/README.md
T
2026-08-27 09:05:06 +08:00

203 lines
6.9 KiB
Markdown

# NginxMan
NginxMan 是一款面向 Windows 的可视化 Nginx 反向代理管理工具。程序将 Nginx 运行环境打包在单个 EXE 中,用图形界面管理域名、监听端口和上游服务,并自动维护统一的网站入口页。
## 软件目标
NginxMan 主要解决以下问题:
- 让不熟悉 Nginx 配置语法的用户也能建立反向代理。
- 将多个本机或内网服务统一通过域名访问,例如将 `team.m3frame.com` 转发到 `http://127.0.0.1:803`。
- 集中管理域名映射,避免手工编辑 `nginx.conf` 带来的格式错误。
- 自动生成 `www.m3frame.com` 网站入口页,新增服务时无需再次修改网页源码或重新编译 EXE。
- 将程序、Nginx、配置、日志和入口页集中放在一个可迁移目录中。
## 核心功能
- **内置 Nginx**:首次运行时自动释放完整的 Windows Nginx 运行文件。
- **映射管理**:支持新增、修改和删除域名反向代理映射。
- **配置生成**:根据界面数据自动生成 `data/nginx.conf`。
- **进程控制**:可以启动、重新加载和停止 Nginx,并显示当前运行状态。
- **入口页生成**:根据所有映射自动生成 `data/www/index.html`。
- **网页模板**:入口页样式保存在 `data/www/index.template.html`,入口卡片由程序动态填充。
- **配置持久化**:映射保存在 `data/nginxman.json`,重启程序后继续使用。
- **旧配置兼容**:旧版本中缺少网站名称和简介的记录会在启动时自动补齐。
- **自定义 Nginx**:既可以使用内置 Nginx,也可以在界面中选择其他 `nginx.exe`。
## 映射字段
每个网站入口包含以下信息:
| 字段 | 作用 | 示例 |
| --- | --- | --- |
| 网站名称 | 显示在入口页卡片上的名称 | `Team Workspace` |
| 域名 | 用户访问服务时使用的域名 | `team.m3frame.com` |
| 上游接口 | Nginx 实际转发到的服务地址 | `http://127.0.0.1:803` |
| 监听端口 | Nginx 对外监听的端口,通常为 80 | `80` |
| 网站简介 | 显示在入口页卡片上的说明 | `团队协作与项目管理平台` |
## 快速开始
### 1. 启动程序
运行发布目录中的:
```text
bin\NginxMan.exe
```
首次运行时,程序会在 EXE 所在目录创建 `data` 文件夹,并准备 Nginx、配置、日志和入口页文件。
### 2. 新增网站入口
在界面下方的“编辑映射”区域依次填写:
1. 域名,例如 `docs.m3frame.com`。
2. 上游接口,例如 `http://127.0.0.1:8080`。
3. 监听端口,普通 HTTP 服务通常填写 `80`。
4. 网站名称,例如 `Documentation`。
5. 网站简介,例如 `团队文档与知识库`。
6. 点击“新增”。
新增成功后,程序会立即完成以下操作:
- 保存 `data/nginxman.json`。
- 重新生成 `data/nginx.conf`。
- 将新入口写入 `data/www/index.html`。
入口页内容是静态文件,保存后即可更新;如果 Nginx 已经运行,还需要点击“重新加载”,使新增的反向代理域名生效。
### 3. 启动或重新加载代理
- Nginx 尚未运行时,点击“启动代理”。
- Nginx 已经运行且映射发生变化时,点击“重新加载”。
- 需要关闭代理时,点击“停止代理”。
### 4. 配置 DNS
每个域名都必须解析到运行 NginxMan 的服务器 IP。例如:
```text
docs.m3frame.com -> 服务器 IP
```
DNS 生效后,可通过 `http://docs.m3frame.com/` 访问对应的上游服务。
## 界面按钮说明
| 按钮 | 作用 |
| --- | --- |
| 新增 | 使用当前表单内容创建一条新映射 |
| 保存修改 | 保存列表中当前选中映射的修改 |
| 删除 | 删除当前选中的映射 |
| 清空 | 清除表单内容并进入新增状态 |
| 生成配置 | 手动重新生成 Nginx 配置 |
| 启动代理 | 生成配置并启动 Nginx |
| 重新加载 | 让正在运行的 Nginx 读取最新配置 |
| 停止代理 | 停止 Nginx |
| 刷新状态 | 重新检查 Nginx 进程状态 |
| 打开配置文件 | 打开 `nginxman.json` |
| 打开文件夹 | 打开配置文件所在目录 |
| 浏览 | 选择外部 `nginx.exe` |
## 数据目录
发布后的主要目录结构如下:
```text
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` 中的每条映射包含网站信息和代理信息:
```json
{
"domain": "docs.m3frame.com",
"upstream": "http://127.0.0.1:8080",
"listenPort": 80,
"websiteName": "Documentation",
"description": "团队文档与知识库"
}
```
建议通过界面维护配置。若手工修改 JSON,需要重新启动 NginxMan,使程序重新读取文件。
## 自定义入口页模板
入口页模板位于:
```text
data\www\index.template.html
```
可以直接修改页面标题、颜色、布局和其他静态内容。程序生成入口页时,会将所有网站卡片插入以下占位符:
```text
{{NGINXMAN_SERVICE_CARDS}}
```
请勿删除或修改该占位符,否则程序无法生成入口页。网站名称和简介在写入 HTML 前会自动转义,避免特殊字符破坏页面结构。
## 从源码构建
开发环境需要:
- Windows 10 或 Windows 11。
- 支持 .NET 8 的 .NET SDK。
- .NET Windows Desktop/WinForms 构建组件。
在项目目录运行:
```powershell
.\build.ps1
```
构建结果位于:
```text
bin\NginxMan.exe
```
发布结果为自包含的 Windows x64 单文件程序,目标计算机通常不需要另外安装 .NET Runtime。
## 常见问题
### 无法启动 Nginx
- 检查 80 端口是否已被 IIS、Apache、其他 Nginx 或其他程序占用。
- 检查 Windows 防火墙是否允许目标端口访问。
- 查看 `data/logs/error.log` 获取具体错误。
- 如使用外部 Nginx,确认界面中的 `nginx.exe` 路径正确。
### 域名无法访问
- 确认域名 DNS 已解析到当前服务器。
- 确认上游服务正在运行,并能在服务器本机访问。
- 确认 Nginx 状态显示为“运行中”。
- 修改映射后,如果 Nginx 已运行,请点击“重新加载”。
### 入口页没有显示最新内容
- 确认 `data/www/index.html` 的修改时间已经更新。
- 强制刷新浏览器缓存。
- 确认 `index.template.html` 中仍保留 `{{NGINXMAN_SERVICE_CARDS}}`。
## 使用限制
- 当前自动生成的是 HTTP 反向代理配置。
- 如需 HTTPS,需要自行补充证书、443 监听及相关 Nginx 配置。
- 域名解析、证书申请和服务器防火墙配置不由 NginxMan 自动完成。