mirror of
https://github.com/0xJacky/nginx-ui.git
synced 2025-05-12 19:05:55 +02:00
117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
# Config Template
|
|
|
|
Nginx UI Template provides out-of-the-box configuration templates for users. In `NgxConfigEditor`, we offer a UI where users can quickly insert configurations from the template into the current configuration file.
|
|
In this document, we will describe the file format and syntax of it.
|
|
|
|
The configuration templates are stored in `template/block`, and we welcome you to share your own configuration templates by open a [PR](https://github.com/0xJacky/nginx-ui/pulls).
|
|
|
|
::: tip
|
|
Please note, you need to recompile the backend after modifying or adding new configuration files.
|
|
:::
|
|
|
|
## File Format
|
|
|
|
Nginx UI Template file consists of two parts: the file header and the actual Nginx configuration.
|
|
|
|
Below is a configuration template for hotlink protection, which we will use as a basis to introduce the file format and related syntax of Nginx UI Template.
|
|
|
|
```nginx configuration
|
|
# 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;
|
|
}
|
|
}
|
|
```
|
|
|
|
## File Header
|
|
|
|
The file header should be placed between `# Nginx UI Template Start` and `# Nginx UI Template End`, and should follow the toml syntax.
|
|
|
|
The file header includes the following fields:
|
|
|
|
| Field | Description | Type | Required |
|
|
|:------------------------------:|:---------------------------------------------------------------------:|:---------------------------------------------:|:--------:|
|
|
| `name` | Name of the configuration | string | Yes |
|
|
| `author` | Author | string | Yes |
|
|
| `description` | Desciption, uses a toml dictionary for multi-language support | toml dictionary | Yes |
|
|
| `variables.VariableName.type` | Variable type, currently supports `boolean` and `string` | string | No |
|
|
| `variables.VariableName.name` | Variable display name, is a toml dictionary to support multi-language | toml dictionary | No |
|
|
| `variables.VariableName.value` | Default value of the variable | boolean/string (according to type definition) | No |
|
|
|
|
Example:
|
|
|
|
```toml
|
|
# 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
|
|
```
|
|
|
|
The name, author, and description will be displayed in the configuration list as a summary.
|
|
|
|
|
|
|
|
When you click the "View" button, a dialog will appear, as shown below.
|
|
|
|
<img src="/assets/nginx-ui-template/en/config-ui.png" width="350px" title="Config Modal" />
|
|
|
|
The input boxes and switches in the interface correspond to the variable types `boolean` and `string`.
|
|
|
|
## Nginx Configuration
|
|
The Nginx configuration should be provided after the file header. This part will be parsed using the Go `text/template` library. This library provides powerful template generation capabilities, including conditional judgment, looping, and complex text processing, etc.
|
|
For more information, please check [Go Documentation](https://pkg.go.dev/text/template).
|
|
|
|
The variables defined in the header can be used in this part, such as `.NoneReferer` and `.AllowReferers`.
|
|
Please note that you need to define the variables in the header in advance before using them in this part.
|
|
|
|
Here is an example:
|
|
|
|
```nginx configuration
|
|
location ~ .*\.(jpg|png|js|css)$ {
|
|
valid_referers {{- if .NoneReferer}} none {{- end}} blocked server_names {{if .AllowReferers}}{{.AllowReferers}}{{- end}};
|
|
if ($invalid_referer) {
|
|
return 403;
|
|
}
|
|
}
|
|
```
|
|
|
|
When users input variable values in the app input boxes, the system will automatically generate new configuration content, as shown below:
|
|
|
|
<img src="/assets/nginx-ui-template/en/config-ui-after-input.png" width="350px" title="Config Modal" />
|
|
|
|
In addition to the variables defined in the template header, we also provide macro-defined variables, as shown in the table below:
|
|
|
|
| Variable Name | Description |
|
|
|:-------------:|:-------------------------:|
|
|
| HTTPPORT | Nginx UI listening port |
|
|
| HTTP01PORT | Port for HTTP01 Challenge |
|
|
|
|
The variables above can be used directly in the configuration part without definition in the header.
|