Nginx UI 项目配置模板使用指南

什么是 Nginx UI 配置模板

Nginx UI 配置模板是 Nginx UI 项目提供的一项实用功能，它允许用户通过预定义的模板快速生成 Nginx 配置片段。这些模板不仅包含了常见的 Nginx 配置场景，还提供了可视化的参数配置界面，大大简化了 Nginx 配置的复杂度。

模板文件结构解析

一个完整的 Nginx UI 配置模板文件由三部分组成：

1. 文件头部分：位于 # Nginx UI Template Start 和 # Nginx UI Template End 之间，采用 TOML 语法
2. 自定义部分：位于 # Nginx UI Custom Start 和 # Nginx UI Custom End 之间（可选）
3. Nginx 配置主体：模板的主要配置内容

文件头详解

文件头部分定义了模板的元信息和可配置参数。以下是各字段的详细说明：

name = "模板名称"  # 必填，模板的显示名称
author = "作者信息"  # 必填，模板作者
description = { en = "英文描述", zh_CN = "中文描述" }  # 必填，多语言描述

[variables.参数名]  # 定义可配置参数
type = "参数类型"  # 支持 boolean/string/select
name = { en = "英文名称", zh_CN = "中文名称" }  # 参数显示名称
value = "默认值"  # 可选，参数默认值
mask = { 选项1 = { en = "英文显示", zh_CN = "中文显示" }, ... }  # 仅select类型需要

参数类型与UI控件对应关系

参数类型	对应UI控件	适用场景示例
boolean	开关按钮	是否启用WebSocket支持
string	文本输入框	设置客户端最大请求体大小
select	下拉选择框	选择HTTP/HTTPS协议

模板配置主体编写技巧

配置主体部分使用 Go 的 text/template 模板引擎，支持以下高级特性：

1. 条件判断：通过 {{ if .参数名 }}...{{ end }} 实现条件配置
2. 变量插值：使用 {{ .参数名 }} 插入用户配置的值
3. 循环结构：支持 range 等循环结构（适用于复杂配置）
4. 宏变量：系统预定义的变量如 HTTPPORT、HTTP01PORT 等

实用示例：反向代理配置

location / {
    {{ if .enableWebSocket }}
    # WebSocket 相关配置
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    {{ end }}

    # 客户端请求体大小限制
    client_max_body_size {{ .clientMaxBodySize }};

    # 基础代理配置
    proxy_redirect off;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 代理目标地址
    proxy_pass {{ .scheme }}://{{ .host }}:{{ .port }}/;
}

最佳实践建议

1. 参数命名规范：使用驼峰命名法，如 enableWebSocket 而非 enable_websocket
2. 默认值设置：为常用参数设置合理的默认值，提升用户体验
3. 多语言支持：确保所有显示文本都提供中英文版本
4. 复杂配置拆分：将复杂配置拆分为多个简单模板，提高复用性
5. 注释说明：在模板中添加必要的配置说明，帮助用户理解

模板开发注意事项

1. 修改或新增模板后需要重新编译后端才能生效
2. 变量使用前必须在文件头中定义
3. 注意模板语法的正确性，避免出现语法错误
4. 考虑不同Nginx版本的兼容性问题
5. 测试各种参数组合下的配置生成结果

通过合理使用 Nginx UI 配置模板功能，可以显著提升 Nginx 配置效率，降低配置错误风险，特别适合需要频繁调整 Nginx 配置的场景。