Files
NginxMan/README.md
T

297 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. 启动程序
运行发布目录中的:
```text
bin\NginxMan.exe
```
首次运行时,程序会在 EXE 所在目录创建 `data` 文件夹,并准备 Nginx、配置、日志和入口页文件。代理映射列表初始为空。
### 2. 设置入口页(可选)
在程序顶部填写:
1. 入口页域名,例如 `portal.example.com`。
2. 入口页端口,例如 `8088`。
3. 点击“保存入口设置”。
若不需要统一入口页,将入口页域名留空并保存即可。此时程序不会在 Nginx 配置中生成入口站点,但代理映射仍可正常使用。
如果 Nginx 已经运行,保存入口设置后程序会自动重新加载 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`。
按上述示例配置后,代理访问地址为:
```text
http://app.example.com:8080/
```
### 4. 启动或重新加载代理
- Nginx 尚未运行时,点击“启动代理”。
- Nginx 已运行且配置发生变化时,点击“重新加载”。
- 需要关闭代理时,点击“停止代理”。
### 5. 配置 DNS 和防火墙
入口页域名及每个代理域名都需要解析到运行 NginxMan 的服务器 IP。非标准 HTTP 端口还需要在服务器防火墙或云安全组中开放。
例如:
```text
portal.example.com -> 服务器 IP
app.example.com -> 服务器 IP
```
## 端口说明
- 可配置范围为 `1–65535`。
- 80 只是方便测试普通 HTTP 的初始值,不是固定端口。
- 访问非 80 端口时,需要在 URL 中显式写出端口号。
- 入口页和代理映射可以使用不同端口。
- 同一服务器上不能让两个不同程序同时占用相同的 IP 和端口组合。
- 入口页不能与某条代理映射使用完全相同的域名和监听端口。
## 界面按钮说明
| 按钮 | 作用 |
| --- | --- |
| 保存入口设置 | 保存入口页域名与监听端口;Nginx 运行时自动重新加载;域名留空表示关闭入口站点 |
| 新增 | 使用当前表单内容创建一条新映射 |
| 保存修改 | 保存列表中当前选中映射的修改 |
| 删除 | 删除当前选中的映射 |
| 清空 | 清除表单内容并进入新增状态 |
| 生成配置 | 手动重新生成 Nginx 配置 |
| 启动代理 | 生成配置并启动 Nginx |
| 重新加载 | 让正在运行的 Nginx 读取最新配置 |
| 停止代理 | 停止 Nginx |
| 手动备份 | 将当前配置与入口页模板打包到 `data/backups`,并只保留最新 10 份 |
| 导入备份 | 导入 ZIP 备份包或旧版 JSON 配置;导入前会自动备份当前数据 |
| 刷新状态 | 重新检查 Nginx 进程状态 |
| 打开配置文件 | 打开 `nginxman.json` |
| 打开文件夹 | 打开配置文件所在目录 |
| 浏览 | 选择外部 `nginx.exe` |
## 数据目录
发布后的主要目录结构:
```text
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 会自动创建以时间开头的备份:
```text
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` 的结构示例:
```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,使程序重新读取文件。
## 自定义入口页模板
入口页模板位于:
```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
- 检查所配置的监听端口是否已被 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 自动完成。