配置模板
Nginx UI Template 提供了一种开箱即用的配置模板机制。在 NgxConfigEditor 中,我们设计了一个可视化界面,使用户能够方便地插入模板中的配置到当前的配置文件中。 在本篇指南中,我们将绍这种配置模板的文件格式和语法规则。 配置模板文件存储在 template/block
目录中,我们欢迎并期待您通过提交 PR 的形式分享您编写的配置模板。
TIP
请注意,每次修改或添加新的配置文件后,需要重新编译后端以生效。
文件格式
Nginx UI Template 文件由两部分组成:文件头部以及具体的 Nginx 配置。
以下是一个关于防盗链的配置模板,我们将以这个模板为基础为您介绍 Nginx UI Template 的文件格式及相关语法。
# Nginx UI Template Start
name = "Hotlink Protection"
author = "@0xJacky"
description = { en = "Hotlink Protection Config Template", zh_CN = "防盗链配置模板"}
[variables.NoneReferer]
type = "boolean"
name = { en = "Allow Referer is None", zh_CN = "允许空 Referer"}
value = false
[variables.AllowReferers]
type = "string"
name = { en = "Allow Referers", zh_CN = "允许的 Referers"}
value = ""
# Nginx UI Template End
location ~ .*\.(jpg|png|js|css)$ {
valid_referers {{- if .NoneReferer}} none {{- end}} blocked server_names {{if .AllowReferers}}{{.AllowReferers}}{{- end}};
if ($invalid_referer) {
return 403;
}
}
文件头部
文件头部应该包含在 # Nginx UI Template Start
和 # Nginx UI Template End
之间,遵循 toml 语法。
文件头部包含以下字段:
字段 | 描述 | 类型 | 必要 |
---|---|---|---|
name | 配置的名称 | string | 是 |
author | 作者 | string | 是 |
description | 描述,使用 toml 格式的字典来实现多语言描述 | toml 字典 | 是 |
variables.变量名称.type | 变量类型,目前支持 boolean 和 string | string (boolean/string) | 否 |
variables.变量名称.name | 变量显示的名称,是一个 toml 格式的字典,用于支持多语言 | toml 字典 | 否 |
variables.变量名称.value | 变量的默认值 | boolean/string (根据 type 定义) | 否 |
示例如下:
# Nginx UI Template Start
name = "Hotlink Protection"
author = "@0xJacky"
description = { en = "Hotlink Protection Config Template", zh_CN = "防盗链配置模板"}
[variables.NoneReferer]
type = "boolean"
name = { en = "Allow Referer is None", zh_CN = "允许空 Referer"}
value = false
[variables.AllowReferers]
type = "string"
name = { en = "Allow Referers", zh_CN = "允许的 Referers"}
value = ""
# Nginx UI Template End
其中,名称、作者及描述将会以摘要的形式在配置列表中显示。
当您点击「查看」按钮,界面会显示一个对话框,如下图所示。
界面中的输入框和开关对应着变量的类型 boolean
和 string
。
Nginx 配置
Nginx 配置应该在文件头部之后提供,这部分将使用 Go 的 text/template
库进行解析。这个库提供了强大的模板生成能力,包括条件判断、循环以及复杂的文本处理等。 具体语法可以参考 Go 文档。
在头部中定义的变量可以在这部分中使用,如 .NoneReferer
和 .AllowReferers
。请注意,需要预先在头部定义变量,才能在这部分中使用。
示例如下:
location ~ .*\.(jpg|png|js|css)$ {
valid_referers {{- if .NoneReferer}} none {{- end}} blocked server_names {{if .AllowReferers}}{{.AllowReferers}}{{- end}};
if ($invalid_referer) {
return 403;
}
}
当用户在前端的输入框中输入变量的值后,系统将会自动生成新的配置内容,效果如下:
除了模板头部定义的变量,我们还提供了宏定义的变量,如下表所示:
变量名 | 描述 |
---|---|
HTTPPORT | Nginx UI 监听的端口 |
HTTP01PORT | 用于 HTTP01 Challenge 的端口 |
上述变量可以直接在配置部分使用,无需在头部定义。