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

樊会灿

于 2025-06-05 09:01:15 发布

阅读量298

点赞数 5

本文链接：https://blog.youkuaiyun.com/gitblog_01005/article/details/148440109

版权

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

nginx-ui 项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui

什么是 Nginx UI 配置模板

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

模板文件结构解析

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

文件头部分：位于 # Nginx UI Template Start 和 # Nginx UI Template End 之间，采用 TOML 语法
自定义部分：位于 # Nginx UI Custom Start 和 # Nginx UI Custom End 之间（可选）
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 模板引擎，支持以下高级特性：

条件判断：通过 {{ if .参数名 }}...{{ end }} 实现条件配置
变量插值：使用 {{ .参数名 }} 插入用户配置的值
循环结构：支持 range 等循环结构（适用于复杂配置）
宏变量：系统预定义的变量如 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 }}/;
}